[0.12] Define the .agents contract and kickstart crew

[adrian-lorenzo]

Goal

Make .agents/ the only source of agent configuration and teach kickstart to install the standard crew.

File format

Each agent is a Markdown file with frontmatter. The body is the prompt. The schema supports:

• name and an optional description
• engine, initially claude_code or codex
• an explicit model
• optional reasoning_effort
• enabled
• one or more manual, MCP, UI, GitHub, or schedule triggers

The schema must reject permissions, sandbox, tool allowlists, and related access controls. Facility has one access policy for every agent.

Unknown fields should fail with a message that includes the file and field. Invalid agents must not be partially registered or executed.

Kickstart output

Kickstart writes these files:

• .agents/architect.md
• .agents/builder.md
• .agents/pr-reviewer.md
• .agents/address-review.md
• .agents/ci-doctor.md
• .agents/security-audit.md

Every generated file contains an explicit engine and model. Kickstart lets the user review and change those values before it opens its setup pull request. Existing files are reported as conflicts and are never silently overwritten.

The old codex-architect and codex-builder names are not built-in variants. A repository can define them as ordinary files if it wants those names.

One code path

Put parsing, validation, normalization, and hashing in a shared library. Kickstart, API routes, MCP tools, the scheduler, and the UI must import it. A database projection may cache the commit and parsed result, but it cannot be edited as a second source of truth.

Each dispatched turn stores the agent name, source commit, manifest hash, engine, model, and engine options used for that turn.

Acceptance criteria

• One shared parser handles every agent file and trigger type.
• Engine and model are required; reasoning effort is the only initial execution option.
• Permission, sandbox, and tool restriction fields are rejected.
• Kickstart renders all six standard agents; a smoke test dispatches each file and the fake engine receives its distinct non-empty prompt and configured trigger payload.
• Kickstart handles existing files without overwriting them.
• A repository can add a custom seventh agent without server code changes.
• Backend, MCP, scheduler, kickstart, and UI use the shared parser.
• A database cache cannot override repository content.
• A turn records the exact manifest revision and effective model.
• Unit tests cover valid Claude and Codex files, each trigger type, unknown fields, malformed frontmatter, duplicate names, and conflicting paths.
• Contract tests load the same commit through kickstart, API, MCP, scheduler, and UI and get the same normalized hash.

Contributor note

Keep the first schema small. Add a field only when one of the standard crew needs it.