Act II · How a change flows
AI Factory · Agents & skills
A crew, not a chatbot
One change, four lanes
Follow a single Issue from the Owner's backlog to a closed Issue. Each lane can only do what its role allows.
- 1Issues & prioritiesdecides what mattersOwner
- 2Pick & briefissue · use case · ACForeman
- 3Plan, then red testsOpenSpec change, tests firstWorker
- 4Code & open PR[#N] type(scope) · Closes #NWorker
- 5Light + heavy CIevery required checkCI
- 6Fix from red logsmerge main in, never rebaseWorker
- 7All checks greenexit code, not opinionCI
- 8Gate 4 reviewheavy CI · archive · boardForeman
- 9Merge Worker PRForeman merge ruleForeman
- 10Merge protected PRsConstitution · exception · harnessOwner
- 11CD · Pages · Releaseon mainCI
- 12Smoke & closeevidence, Issue closedForeman
Roles and authority
| Role | Who | May | May never |
|---|---|---|---|
| Owner | The human code owner (CODEOWNERS) | Approve specs; grant exceptions; merge Constitution, sdlc-exception and harness PRs; merge any PR | — |
| Foreman | Supervising AI agent | Run and validate gates, write review notes, merge Worker PRs when all required checks are green and check-heavy-ci.sh exits 0 (#1624) | Implement the change it reviews; merge policy or its own harness |
| Worker | Implementing AI agent | Implement phase by phase; answer review notes | Merge, push to main, grant itself an exception |
The specialist crew
Orchestrates the loop: pick, Gate 1, dispatch, PR, CI, review, merge
Writes the specification that Gate 1 checks
Package, port/adapter and migration decisions
Test design and red proof; Bruno and Playwright
Compose, CI and observability
Milestones, priority and lanes; no product code
Cost-matched delegation
Mechanical
Renames, applying a known pattern, running a fixed script → the cheapest capable model.
Standard
Writing and fixing tests, routine bug fixes, consistency checks → the mid tier.
Critical
Architecture, ambiguous judgment, security consequences → the top tier.
Skills by SDLC stage
| Stage | Skills | Primary output |
|---|---|---|
| Strategy & discovery | delivery-maturity-roadmapanalystproduct-owner | roadmap hypothesis, Issue, Use Case, acceptance criteria |
| Traceability | devsecops-traceabilityopenspec-triage | IDs, traceability ledger, impact map |
| Specification | openspec-propose | proposal, delta specs, scenarios |
| Architecture | architecture-decision-designhexagonal-archdesign-doc-mermaid | design, ADR, Mermaid/C4 views |
| Security design | secure-threat-modeling | threat model, risk register, SR-* requirements |
| Test design | qa-automation-strategytesting | test plan, cases, fixtures |
| Implementation | openspec-apply-changeprogrammingjavafrontend-design | failing tests, implementation, updated ledger |
| Contract & integration | api-contract-testingapi-rest | OpenAPI, Bruno and contract evidence |
| Delivery | ci-cd-quality-gatesdevopsmaven-buildsteward | gate log, reports, immutable artifact |
| Production | operations-observability-readiness | SLOs, telemetry, runbook, smoke evidence |
| Completion | openspec-archive-change | complete ledger, permanent docs, archived change |
Selection rule: use the narrowest project skill for implementation details and a generic lifecycle skill for cross-cutting decisions. Skills are guidance, not a second policy layer, and cannot override the Constitution, an approved spec or a human. Each generic skill ships an evaluation manifest (evals/evals.json).
Two runtimes, one process
Cursor Cloud fleet
A Foreman with specialist sub-agents on cloud VMs drives pick → Gate 1 → TDD → preflight → PR → CI → review → merge. Coordination goes through GitHub (Issue state, board Status, labels, PR Closes/Refs), never a private queue.
Local-AI harness
A small local model with a 32K window cannot hold the whole process, and it tends to report success it has not earned. foreman.sh splits the Constitution into phases, gives each a fresh context and a short brief, checks every result with real commands, and retries with the gate output attached.
| Harness phase | Who | Deterministic gate |
|---|---|---|
| triage | worker | triage.env schema + every criterion has a proof |
| setup | harness | branch from fresh origin/main, OpenSpec change, in-progress label |
| spec | worker | openspec validate --strict + validate-sdlc-plan.sh → Gate 1 |
| tests | worker | tests committed, TEST_CMD must FAIL → Gate 2 |
| implement | worker | TEST_CMD green + full suite green + Closes #n |
| docs | worker | CHANGELOG for feat/fix, plan still valid |
| quality | harness → worker | preflight.sh |
| pipeline | harness → worker | run_pipeline.sh (stack + E2E + Bruno) → Gate 3 |
| pr | worker | PR title, body references issue, branch pushed |
| ci | harness → worker | check runs on the last non-[skip ci] commit settle green |
| review | foreman | diff review → Gate 4; findings go back via fix |
| merge | harness | CI + CD green, /actuator/health UP, issue closed → Gate 5 |
Entry points by tool
| Tool | Reads |
|---|---|
| Claude Code | |
| OpenCode | |
| Cursor Cloud fleet | |
| Any agent via the CLI | |
| Local model (Codex / OpenCode on oMLX) |
.claude/skills/ and .claude/agents/ are the only catalogs; no per-tool copy may exist. The always-loaded context (CLAUDE.md, slim AGENTS.md, the Constitution card, the workflow rule) stays under 8,000 tokens.