AGENTS.md

1# AGENTS
2 
3## Start of Session
4- Read SOUL.md to align identity.
5- Run `prompt-manager team member-context scenario-qa quality-auditor` for team context.
6 
7## Workflow
81. **Select scenario** — Run `swarm-manager scenarios review-queue --limit 1`. If zero returned, log "No scenarios for deep audit" and stop.
92. **Check recency** — Query knowledge log for recent `[deep-audit]` entries. Skip if this scenario was audited in the last 7 days.
103. **Select steer skill** — Choose the next skill from the rotation that has NOT been recently applied to this scenario.
114. **Read the skill** — Run `prompt-manager skill read <skill-id>` and internalize the methodology.
125. **Investigate** — Read the scenario's architecture docs, code structure, and test suite. Apply the skill's methodology to identify structural quality issues.
136. **Create backlog item** — If non-trivial findings exist:
14   - `swarm-manager backlog create --kind execute --name qa-deep-<scenario>-<skill-short>-YYYYMMDD`
15   - Include findings as evidence in the description
16   - Set `suggested_skills` to `["<skill-id>"]`
17   - Set tags: `["deep-audit", "<scenario-name>"]`
18   - Set acceptance_allow: `["scenarios/<scenario>/**"]`
19   - Set priority: 6
20   - Write a draft plan.md in the backlog item folder
217. **Log** — Record `[YYYY-MM-DD] Deep audit: <scenario> via <skill-id> — <one-line-summary>` to knowledge log.
22 
23## Steer Skill Rotation
24 
25### Always applicable (Tier 1)
261. `screaming-architecture-audit` — Does the physical structure express the scenario's purpose?
272. `boundary-of-responsibility-enforcement` — Is each module doing only its own job?
283. `seam-discovery-and-enforcement` — Are side effects isolated? Can behavior vary without invasive changes?
294. `invariant-discovery-and-enforcement` — Are system constraints explicit and enforced?
305. `cognitive-load-reduction` — Can a new developer understand this code quickly?
316. `decision-boundary-extraction` — Are important decisions explicit and easy to locate?
327. `code-cleanup` — Is there dead code, unused imports, or backwards-compatibility cruft?
33 
34### Conditional (Tier 2 — check applicability first)
35- `react-coherence` — Only for scenarios with a React UI
36- `security` — OWASP baseline audit
37- `e2e-testing` — End-to-end test strategy assessment
38- `documentation-health` — Documentation quality and bidirectional traceability
39 
40## Coordination
41- Works alongside the programmatic QA runner: the runner handles GCT-driven reviews, quality-auditor handles structural analysis (judgment-based).
42- All findings feed into the same swarm-manager backlog pipeline.
43