Quality governance for agent-assisted software development.
Scaffold a complete quality system — findings, audits, QA sessions, merge gates — designed for AI agents to read and execute.
Based on Founder-Led Engineering Ops.
npx create-qa-opsThat's it. Run it from your project root and it scaffolds everything.
your-project/
├── docs/quality/
│ ├── README.md # Index
│ ├── AGENTS.md # Agent reads this to auto-configure everything
│ ├── review-sop.md # Operating procedure (roles, sequence, merge gate)
│ ├── findings/
│ │ ├── open.md # Live backlog of findings
│ │ └── closed.md # Historical log
│ ├── templates/
│ │ ├── finding-template.md # Structure for every finding
│ │ ├── qa-session-prompt.md # Prompt template for QA sessions
│ │ ├── audit-prompt.md # Prompt template for pre-merge audits
│ │ ├── reverify-prompt.md # Prompt template for fix re-verification
│ │ └── qa-checklist-skeleton.md # Skeleton QA checklist to adapt
│ └── report/ # One file per audit or QA session
└── .kiro/steering/
├── quality-core.md # Base rules (always active)
└── finding-governance.md # Finding lifecycle governance
Existing files are never overwritten.
| Role | Does | Modifies code? |
|---|---|---|
| Orchestrator (human) | Coordinates, triages, decides merge readiness | No |
| Implementer (agent) | Executes tasks, fixes findings | Yes |
| Auditor (agent) | Technical audit, detects findings | No |
| QA (agent) | Browser/product flow validation | No |
| Final auditor (different model) | Last review before merge | No |
NEW → TRIAGED → ACCEPTED → FIXED_PENDING_VERIFICATION → VERIFIED_CLOSED
→ REJECTED (with rationale)
→ DEFERRED (with rationale)
A fix is not closed until a different role verifies it.
| Level | Blocks merge? | Examples |
|---|---|---|
| P0 | Yes | Security breach, data loss, broken core flow |
| P1 | Yes | Major functional bug, serious spec mismatch |
| P2 | No | Moderate defect, edge case, non-blocking regression |
| P3 | No | Cosmetic, polish, minor code quality |
A branch is not merge-ready unless:
- 0 open P0 findings
- 0 open P1 findings
- All accepted findings are verified closed or formally deferred
- Critical QA flows passed
- Findings logs updated
Use at least two model families. The implementation model has blind spots — a different model family for the final audit systematically catches what the first one misses. This is not redundancy; it's a deliberate quality mechanism.
- Run
npx create-qa-opsin your project - Auto-configure with AI: tell your agent to read
docs/quality/AGENTS.md— it contains step-by-step instructions for the agent to configure everything automatically (replaces placeholders, generates a QA checklist from your actual routes, verifies steering files) - Or configure manually: read
docs/quality/review-sop.mdand replace{{PLACEHOLDERS}}in the prompt templates - Start logging findings in
docs/quality/findings/open.md - Use the steering files (
.kiro/steering/) if you're on Kiro — otherwise include their content in your agent's system prompt
The templates are ready to copy-paste into a new agent session:
qa-session-prompt.md— Full QA session with Playwright MCP + DB verificationaudit-prompt.md— Pre-merge technical audit (security, data, architecture, API)reverify-prompt.md— Re-verify specific findings after fixes
Each template has {{PLACEHOLDERS}} for your app URL, DB tool, branch name, etc.
This system exists because generating code is not the same as building software. AI agents accelerate execution, but quality requires specification, structured review, evidence-based findings, and human governance.
The goal is not maximum output — it's verifiable throughput with control.
This quality system assumes you have specs before you audit. That means:
- Requirements (functional + non-functional)
- Design document (architecture, decisions, constraints)
- Implementation plan (phases, tasks, acceptance criteria)
Without specs, findings lack traceability and audits become opinion. The quality system governs the gap between "what was specified" and "what was built".
If you use Kiro, the steering files are automatically injected into agent context:
quality-core.md— Always active. Base rules for all agents.finding-governance.md— Auto-included when auditing, reviewing, or triaging.
If you use another IDE, include the content of these files in your project rules or system prompt.
MIT — 0xnavarro