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.

## `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. |

## `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.