Agent workflow hierarchy
- Status: in progress, opened 2026-08-22.
- Issues:
#950: the design,#951: the workflow drift gate. - Launch plan: none. This is tooling, not product. It maps to no row and does not get a fake one.
What is this?
Agent guidance lives in six layers, and nothing says which layer a new piece of guidance belongs in.
- Each layer grew on its own and each one works. What is missing is the contract between them, so the choice gets made by whoever happens to be writing at the time.
- The consequence, measured on 2026-08-21: every failure captured that day landed in a skill, because the routing test on offer had no other destination that fit "steps someone should follow".
This project writes that contract down.
- It also fixes the two things the survey found broken, and names the loop that already exists for testing and refining an agent asset.
What are the layers, as of 2026-08-22?
| Layer | Count | Source | Reaches | Drift gate |
|---|---|---|---|---|
| Hooks | 8 | .claude/hooks/ | Claude only | none |
| Rules | 13 | .agents/rules/ | Claude, Copilot, Cursor, Gemini | Agents Sync |
| Workflows | 3 | .agents/workflows/ | Claude only | none, see #951 |
| Skills | 33 | .agents/skills/ | Claude, Copilot, Gemini, plus 20 slash commands | Skill Sync, both directions |
| Context | per-user | ~/.agents/context/<repo>/ | Claude, via a SessionStart hook | none, syncs by hand |
| Output style | 1 | generated from the voice rule | Claude, via a settings key | Agents Sync |
What is the current state?
The six project files exist and each owns one job.
- design.md holds the layer contract, the routing test, and the refinement loop.
- backlog.md holds what is raised but not sequenced, so an idea gets a home without costing a GitHub issue.
- logging.md is the worklog: one timestamped line per thing that happened.
- implementation.md holds the execution detail: mechanisms, defect analysis, run statistics.
- testing.md is the manual test plan: 21 scenarios, including a falsifying pair that can reopen the diagnosis, and four on the agenda format whose predictions were written before the run.
- voice-checkability.md covers the one layer that had no drift gate at all: what an agent actually says to a person.
- fixtures/ holds a small, deliberately awkward agenda for calibrating the workflows without touching the real board.
This is the first folder built to the project layout, and it was made by hand.
- The layout comes from the project creation workflow spec.
- Hand-made because the four doc-type scaffolding skills that spec depends on do not exist yet. Operator ruling, 2026-08-22.
What else is related?
#928: per-project doc folders, the container this lands in.#853and#852, proposed skills that the routing test would place.#835: splitting the communication rule, a rules-layer question.#923, a proposed workflow.#834: context home sync across machines, the gap that left one laptop 102 commits behind.