Skills/docs/conventions.md

Conventions

The skills plugin used to read a per-project dev-cycle-profile.yml. It no longer does. There was never a parser — the profile was prose the skill bodies told the model to read, and almost every slot was either dead, constant across all projects, or derivable. So the plugin now splits cleanly in two:

• Fixed conventions (this file) — the things that were constant across every project. They are not configurable; the skill and agent bodies name them directly.
• Per-project facts — the handful of things that genuinely vary per project (where the code lives, how to build and test it, the tracker slug, …). These live as prose in each project's own CLAUDE.md under a ## Skills plugin: project facts heading. See ../templates/CLAUDE.md.fragment for the template, and the section list at the bottom of this file.

File layout

Artefact	Location
Specs (from specify)	docs/specs/
Plans (from planner)	docs/plans/

These directories are fixed. A project that keeps specs and plans elsewhere is the rare exception and states the override in its CLAUDE.md project facts.

Naming

Counter-prefixed, per directory: NNNN-slug.md, 4-digit zero-padded. The counter is per directory, assigned in creation order, and stable for the life of the file. New files take the next-higher number; deleted files retire their number (numbers are not recycled). brainstorm / specify / planner scan the target directory for the next free number before writing.

The slug separator is -.

Vocabulary

The pipeline's nouns are fixed:

Term	Meaning
cycle	One round in the pipeline graph (brainstorm → specify → planner → implement → audit → [fieldtest]). NOT the top-level container.
iteration	A sub-unit of a cycle.
milestone	Tracker container spanning many cycles; closes only when complete AND functional (see pipeline.md § Milestone-close gate).
contract	A single design-ledger entry.

When a project declares a glossary (in its CLAUDE.md project facts), that glossary is the source of truth for domain nomenclature and overrides these names where they collide (see glossary-convention.md).

Standing reading

Every agent reads, at the start of every dispatch:

• the project's CLAUDE.md
• git log -10 --format=full

A project may add more — globally or per role — in its CLAUDE.md project facts (standing reading). If the project declares a glossary, that file is implicitly standing reading for every role too.

Git discipline

• Only the orchestrator commits. No skill agent runs git commit. Agents write into the working tree as unstaged changes; the orchestrator inspects, decides commit shape, and commits.
• main HEAD is sacrosanct. Nobody runs git reset / git revert on main (or any other protected branch). main moves forward only via orchestrator commits; a wrong agent diff is discarded with git checkout -- <paths> / git stash, never by rewinding main.

These also appear in the universal-discipline fragment (../templates/CLAUDE.md.fragment) that each project's CLAUDE.md imports.

Issue tracker

The tracker is Gitea and the commit close-marker is closes #N (refs #N for non-closing work). The per-project repo slug and the list/show commands live in the project's CLAUDE.md project facts (see below) — the boss skill reads the forward queue from there, and the spec-skeptic scope-fork juror reads single issues with their comment threads from there.

Pipeline

The phase set, the gates, and the conditional dispatch are fixed and documented once in pipeline.md. There is no per-project pipeline configuration. In particular: brainstorm, specify, planner, implement, audit, debug, tdd, fieldtest, and docwriter are always available. tdd is a standard entry path for test-specifiable work — not an opt-in. audit is mandatory at cycle close. fieldtest / docwriter are orchestrator-dispatched. The single behavioural toggle is spec auto-sign under /boss, declared (when a project wants it) in that project's CLAUDE.md project facts.

Per-project facts (in each project's CLAUDE.md)

Under ## Skills plugin: project facts, where applicable:

Fact	Used by	Notes
code roots	architect, quality-reviewer, fieldtester	Directories reviewers walk. Required.
build / test command	implement, audit	Required. Exit 0 = success.
lint command	(quality)	Optional.
doc-build command	docwriter	Optional; prints warnings on stderr.
regression scripts	audit (bencher)	Optional list; non-zero exit = regress.
architect sweeps	audit (architect)	Optional list; non-zero exit = drift suspicion.
design ledger	architect, most agents	Optional path (e.g. design/INDEX.md).
glossary	every role	Optional path; implicitly standing reading.
design contracts / models	docwriter, specify	Optional dirs. Aspirational-source frontmatter marker recommended (see below).
bench dir	fieldtest, bencher	Optional path.
public interface	fieldtester	Optional list — the only surface the fieldtester may read; everything else (code roots, bench) is forbidden to it.
fieldtest examples	fieldtester	Optional path where fixtures are written.
by-role standing reading	named agent	Optional; extra files/commands a specific role reads.
issue tracker	boss, spec-skeptic	Repo slug + list command + show command (the latter MUST render an issue WITH its comments).
spec auto-sign	boss, specify	Optional; enabled lets /boss sign a spec in the user's place through the auto-sign gate (default: human signature).

Aspirational-source marker (recommendation)

Files under a project's design-models / RFCs / proposals directory commonly carry aspirational code — constructs written before the surface that parses them exists. To let a later specify tell aspirational content from validated contract, give each such file a frontmatter marker:

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

When the marker is absent the signal is simply absent — specify degrades to treating the content as unmarked, never hard-failing. Content lifted from an aspirational source is flagged as a target, not verified fact, before it ships in a spec.