Skills/docs/profile-schema.md

# Profile schema

Location: `<project-root>/.claude/dev-cycle-profile.yml`

Encoding: YAML. Each top-level key is a section. Keys are
lowercase snake_case. Lists are YAML sequences.

## `paths`

| Key                 | Type   | Default                | Description |
|---------------------|--------|------------------------|-------------|
| `spec_dir`          | string | `docs/specs`           | Where the brainstorm skill writes specs. |
| `plan_dir`          | string | `docs/plans`           | Where the planner skill writes plans. |
| `design_ledger`     | string | `design/INDEX.md`      | Canonical specification index (optional — projects without a design ledger can omit). |
| `design_contracts`  | string | `design/contracts`     | Directory of prose-authoritative contracts (optional). |
| `design_models`     | string | `design/models`        | Directory of onboarding whitepapers (optional). |
| `code_roots`        | list   | `[src]`                | Code directories the architect / quality reviewer walk. |
| `bench_dir`         | string | `bench`                | Where regression harnesses live (optional). |
| `public_interface`  | list   | `[README.md, docs]`    | Directories and files the `fieldtester` may read — the project's outward-facing surface (READMEs, design ledger, examples, public API docs). Everything else (especially `code_roots` and `bench_dir`) is forbidden to the fieldtester. |
| `fieldtest_examples`| string | `examples/fieldtest`   | Where the `fieldtester` agent writes its fixtures. |

Omitted optional keys signal that the feature is unused in this
project; skills that depend on them either short-circuit or
skip the corresponding step.

### Aspirational-source marker (recommendation)

Files under `design_models` (or an equivalent `RFCs` /
`proposals` directory) commonly carry aspirational code —
constructs written before the surface that would parse them
exists. To let a later brainstorm tell aspirational content from
validated contract, projects are encouraged (not required) to
give each such file a frontmatter marker:

```yaml
---
status: aspirational
validated-against: <commit-sha | "no validation">
---
```

`status: aspirational` says "the code here is a target, not a
verified fact"; `validated-against` records the last commit at
which someone actually ran the code through the live tool (or
`"no validation"`). A design ledger (`design_ledger`) is likewise
encouraged to distinguish "model" rows from "contract" rows so a
reading agent can mechanically tell which carry verified
behaviour.

When a file lacks the marker the signal is simply absent — the
brainstorm degrades to treating its content as unmarked, never
hard-failing. The marker is consumed by the brainstorm skill (see
its Step 1 and Step 4): content lifted from an aspirational source
is flagged and must clear the Step-7 parse-every-block gate before
it ships in a spec.

## `naming`

| Key                | Type   | Default                          | Description |
|--------------------|--------|----------------------------------|-------------|
| `counter_dirs`     | list   | `[]`                             | Directories that use the counter-prefix policy. |
| `policy`           | enum   | `flat`                           | One of `stable_per_directory_4digit`, `date_prefix`, `flat`. |
| `slug_separator`   | string | `-`                              | Separator inside the slug. |

`stable_per_directory_4digit` means each listed directory has a
per-directory counter, 4-digit zero-padded, assigned in
creation order, stable for the life of the file. New files
take the next-higher number; deleted files retire their number.

`date_prefix` uses `YYYY-MM-DD-slug.md`.

`flat` uses `slug.md`.

## `commands`

| Key            | Type   | Default        | Description |
|----------------|--------|----------------|-------------|
| `build`        | string | (required)     | Build command — exit 0 means success. |
| `test`         | string | (required)     | Test command — exit 0 means success. |
| `lint`         | string | (optional)     | Lint command — exit 0 means success. |
| `doc_build`    | string | (optional)     | Documentation-build command used by the `docwriter` skill. Should print warnings on stderr so the agent can enumerate them (e.g. `cargo doc --no-deps 2>&1`). Omit if the project has no API docs. |
| `regression`   | list   | `[]`           | Regression scripts run by the audit skill. Each entry is a shell command; non-zero exit is a regress. |
| `architect_sweeps` | list | `[]`         | Project-specific architect sweep commands run by the `architect` agent in addition to its universal checks. Each entry is a shell command; non-zero exit means at least one sweep matched and the matches are drift-suspicions to verify. Optional. |

## `spec_validation`

Optional. A registry mapping each markdown fence label to the tool
that validates a spec code block of that kind. The brainstorm
parse-gate and the grounding-check code-block pass run these
parsers so that spec code blocks are treated as hypotheses to
verify, not as authoritative truth.

```yaml
spec_validation:
  parsers:
    ail:
      ext: ".ail"
      cmd: "ail parse {file}"
    ail-json:
      ext: ".ail.json"
      cmd: "ail check {file}"
    ll:
      ext: ".ll"
      cmd: "llvm-as {file} -o /dev/null"
```

The key of each `parsers` entry is the fence info-string of a spec
code block (the token immediately after the opening ` ``` `). Only
blocks whose label has an entry are validated; a block whose label
is absent from the map is skipped and the skip is documented ("no
parser for fence label X") — never a silent pass.

| Key   | Type   | Description |
|-------|--------|-------------|
| `ext` | string | Extension (including the leading dot) the harness gives the temp file it writes the block into, so tools that key off extension — `.ail` vs `.ail.json` — see the right one. |
| `cmd` | string | Validation command. MUST contain the `{file}` placeholder, which is substituted with the temp file's path. Exit 0 means a clean parse; any non-zero exit is a parse failure the consuming skill turns into a BLOCK. |

A malformed entry — `cmd` missing the `{file}` placeholder, or
either `ext` or `cmd` absent — is a profile error the consuming
skill surfaces, not a silent skip; the gate fails closed.

Omitting the whole `spec_validation` section disables the
block-validation gates: the consuming skills short-circuit, exactly
as with other omitted optional features.

## `vocabulary`

| Key            | Type   | Default        | Description |
|----------------|--------|----------------|-------------|
| `cycle`        | string | `cycle`        | What a top-level work unit is called. Examples: `milestone`, `release`, `epic`. |
| `subcycle`     | string | `iteration`    | What a sub-unit is called. Examples: `iteration`, `sprint`, `story`. |
| `ledger_entry` | string | `contract`     | What a single design-ledger entry is called. Examples: `contract`, `RFC`, `ADR`. |

Skills use these names in their generated artefacts and prose.
Picking accurate vocabulary keeps prose readable; the underlying
mechanics are identical regardless of name.

## `standing_reading`

| Key            | Type   | Default        | Description |
|----------------|--------|----------------|-------------|
| `always`       | list   | `[CLAUDE.md]`  | Files every agent reads at start of every dispatch. |
| `by_role`      | map    | `{}`           | Map from role name to list of additional files. |

Role names match agent slugs: `architect`, `bencher`, `debugger`,
`implementer`, `tester`, `fieldtester`, `docwriter`,
`grounding-check`, `plan-recon`, `spec-reviewer`, `quality-reviewer`.

Entries may be shell commands as well as file paths — they are
read as opaque strings the agent should fetch / execute, e.g.
`"git log -10 --format=full"`.

## `git`

| Key                          | Type | Default | Description |
|------------------------------|------|---------|-------------|
| `main_sacrosanct`            | bool | `true`  | If true, no actor may reset or revert main. |
| `only_orchestrator_commits`  | bool | `true`  | If true, no agent commits; the orchestrator commits. |
| `issue_tracker.kind`         | enum | `none`  | One of `gitea`, `github`, `linear`, `none`. |
| `issue_tracker.close_marker` | string | `"closes #N"` | Marker the orchestrator includes in commit bodies to auto-close issues. |
| `issue_tracker.url`          | string | (empty) | Human-browsable URL of the issue list — surfaced in notifications and cross-references. |
| `issue_tracker.list_cmd`     | string | (empty) | Shell command that lists open issues. Used by the `boss` skill to read the forward queue. Examples: `tea issues ls --repo X/Y --state open`, `gh issue list --repo X/Y --state open`. |
| `protected_branches`         | list | `[main]` | Branches that are sacrosanct in the same sense as main. |

## `notifications`

| Key       | Type   | Default | Description |
|-----------|--------|---------|-------------|
| `command` | string | (empty) | Shell command the `boss` skill invokes on done-state and bounce-back. Receives the message text as a single argument. Example: `"~/.claude/notify.sh"`. If empty, the orchestrator falls back to printing the notification in chat. |

## `pipeline`

Per-phase configuration. Each phase has its own sub-map.

```yaml
pipeline:
  brainstorm:
    gates: [planner]              # planner cannot start until this has run
  planner:
    gates: [implement]
  implement: {}                   # standard
  audit:
    mandatory_at: cycle_close     # auto-fires at end of each cycle
  fieldtest:
    boss_only: true               # only orchestrator dispatches
    when: surface_touch           # condition tag (orchestrator judgement)
  docwriter:
    boss_only: true
    when: api_stable_across_n_cycles
  debug:
    trigger: bug                  # observable misbehaviour
    red_first: true               # RED test before any fix
  boss:
    user_invoked: true            # autonomous-orchestrator mode, /boss
```

Phases not listed are disabled for the project. A project that
does not want a `fieldtest` phase simply omits the key.

## Example: minimal profile

```yaml
paths:
  spec_dir: docs/specs
  plan_dir: docs/plans
  code_roots: [src]

commands:
  build: cargo build
  test: cargo test

vocabulary:
  cycle: milestone
  subcycle: iteration

standing_reading:
  always:
    - CLAUDE.md
    - "git log -10 --format=full"

git:
  issue_tracker:
    kind: github
    close_marker: "closes #N"

pipeline:
  brainstorm: { gates: [planner] }
  planner:    { gates: [implement] }
  implement:  {}
  audit:      { mandatory_at: cycle_close }
  debug:      { trigger: bug, red_first: true }
```

This minimal profile enables five phases, no fieldtest, no
docwriter, no design-ledger. Good starting point for a small
project.