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.

## Lifecycle

`docs/specs/` and `docs/plans/` hold **only the active cycle's
artefacts** — they are working space, not an archive. A spec or plan is
valid for the cycle that produces it; its code shapes drift the moment
the code moves, so a stale one left lying around reads as a live API
reference and misleads the next agent that opens it.

The two directories stay **git-tracked** — never git-ignored. A
spec/plan is committed while its cycle is live, and at **cycle close** —
after `audit` is drift-clean — the orchestrator **retires** it: `git rm`
the spec and plan in the cycle-close commit. The deletion rides in that
commit, so at `HEAD` the directories hold only what is still in flight,
while the full text stays recoverable from git history
(`git show <rev>:<path>`).

A spec/plan is therefore **transient in the repo**: present for its own
cycle, gone from `HEAD` afterwards. The durable record of a past cycle
is the design ledger (where the rationale is lifted during audit) + the
git history of the spec, plan, and code — never a live file under
`docs/specs` / `docs/plans`.

## 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; `brainstorm` / `specify` / `planner` scan the
target directory for the next free number before writing.

The number is a within-cycle handle, not a stable archival ID.
Because the directories hold only active artefacts (see § Lifecycle),
an emptied directory restarts at `0001` and a number freed by a
retired file may be reused — that recycling is fine, since the durable
record is git history, not the filename.

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. There is no
per-project behavioural toggle: spec auto-sign is always on under
`/boss`.

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

### 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:

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