Conventions

What every agent assumes about house style. These are not opinions to debate per project — they're how Foundry artifacts stay consistent and traceable.

Artifact locations

Every artifact lands in one of three roots, configured during install:

Root	Default	Holds
{planning_artifacts}	{output_folder}/planning-artifacts	Briefs, PRDs, UX designs, architecture, epics & stories, validation reports, course corrections
{implementation_artifacts}	{output_folder}/implementation-artifacts	Sprint plans, stories, code reviews, retrospectives, Solo Dev specs
{project_knowledge}	docs	Long-lived reference material — research output, brownfield documentation, project context

{output_folder} defaults to .foundry-output. Override any of these during install or in .foundry/foundry/config.yaml after.

Don't write to .foundry/ itself by hand. That directory is installer-managed and gets regenerated on update.

Citations

Every non-obvious claim in a Foundry-generated artifact carries a citation so readers can trace it. Two schemes:

Scheme	Used for	Example
alloy://<path>	Anything sourced from the @engineering11/alloy corpus	alloy://sources/sdks-nodejs/sdks/auth/backend-using.md
sdks-nodejs-skill://<file>	The four reserved upstream-skill files (backend patterns, standards, gen-microservice, gen-sdk)	sdks-nodejs-skill://STANDARDS.md

Citation rules per agent:

• Architect cites every non-obvious decision in the architecture doc.
• Dev cites in commit messages and Dev Agent Record when following a non-obvious SDK convention.
• UX cites the source of every component decision (alloy path, shadcn URL, or node_modules/@engineering11/<pkg>/src/... when reading source directly).
• Analyst partitions Technical Research output into "From alloy" and "From the web" sections, each with its own citation list.

When you see an agent skipping citations or inventing claims unsourced, that's a regression worth flagging.

Persona voice

Each agent's YAML has three fields that govern voice:

Field	What it describes
identity	The artifacts the agent produces — concrete, not theatrical. "Produces sprint plans and implementation-ready story files."
communication_style	How the agent talks — direct, terse, checklist-driven, citation-disciplined. Not "passionate" or "enthusiastic".
principles	The actionable rules the agent always follows. Each principle should change behaviour, not just signal an attitude.

Three things you'll never see in a Foundry agent:

• Theatrical similes ("like a master craftsman", "elite", "world-class").
• Vague qualifiers ("modern", "clean", "simply", "just").
• Restatement preambles ("Great question! As you mentioned, …").

If you see them, they're a regression — flag or fix.

Command codes

Commands are addressed by 2–3 letter codes (CB, CP, CA, DS, CR, SF, DF, NB, etc.). The codes are:

• Stable across installs. A given workflow has the same code in every project.
• Fuzzy-matched. Typing dev-story or "implement the next story" routes to DS for Dev.
• Catalogued. See .foundry/foundry/module-help.csv for the full list with phase, agent, output location, and description.

Don't invent new codes ad-hoc. If a workflow needs a new code, that's a Foundry change (see Contributing).

Agents always spell codes out. Every identifier Foundry uses in conversation — command codes, acceptance criteria (AC4), functional requirements (FR3), spec capabilities (CAP-2), story keys (2-3), decision ids — is paired with its human-readable name the first time it appears in a message: "AC4 (offline retry)", "[DF] Dev Flow", "CAP-2 (input validation)". You should never have to go look up what an agent just said. If an agent gives you a bare code, that's a bug worth reporting.

File naming

• Stories: stories/<epic>/<story-id>-<slug>.md — e.g. stories/epic-2/story-2.3-tenant-switch.md. Epic and story IDs are decimal-dotted; slugs are kebab-case.
• Code reviews: code-review-<story-slug>.md next to the implementation artifacts root, not inside stories/.
• Retrospectives: retrospective-epic-<n>.md.
• Course corrections: correction-<YYYY-MM-DD>.md — datestamped because there may be several.
• Research: research-<topic>.md — e.g. research-multi-tenant-firestore.md.
• Briefs / PRDs / architecture / UX: singular files at the artifact root — brief.md, prd.md, architecture.md, ux-design.md.

When to refine

The [BH] Help skill and e11-refine rewrite output against the project's vocabulary and persona conventions. Run e11-refine when:

• Output drifts from the agent's principles (e.g. PRD restates user inputs without challenging them).
• A teammate flags non-obvious language or theatrical voice.
• An artifact will outlive the session and you want it standardised.

It's faster than rewriting by hand and keeps the artifact aligned to house style.

Standards vs sidecars

The Tech Writer is the only agent with a persistent sidecar memory at .foundry/_memory/tech-writer-sidecar/documentation-standards.md. Repo-specific documentation conventions accumulate there via [US] Update Standards. Other agents don't have sidecars — their YAML and source workflows are the source of truth.

If you find yourself repeating a correction to one of those other agents across sessions, the right fix is a change to the source agent YAML or workflow, not a sidecar that doesn't exist.

Source

Tasks and skills: e11-refine/SKILL.md, e11-help/SKILL.md · agent YAML directory: src/foundry/agents/ · command catalog: src/foundry/module-help.csv.