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).

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.

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.

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

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.