Process-as-Code for Agentic QA

This repository is a sanitized, tool-light reference for governing an AI coding agent across a software-testing workflow.

The central rule is simple:

An agent may prepare evidence, propose coverage, and implement tests. It may not define its own acceptance criteria or approve the gate it is trying to pass.

The repository is intentionally generic. Names, URLs, credentials, ticket identifiers, production metrics, and product-specific implementation details have been removed. The examples describe a fictional SDK ecosystem with a dApp, a reference wallet, an external relay, and a browser-based E2E suite.

What this demonstrates

• Process context in version control. Rules, invariants, handoff contracts, coverage decisions, and CI boundaries are reviewed like code.
• A small context router. The agent loads the minimum mandatory sources for the current task instead of treating chat history as a knowledge base.
• Human-reviewed phase transitions. PREP, EXEC, and AUTO have explicit exit criteria and different owners.
• A deterministic automation boundary. CI verifies reproducible client behavior; real signatures and production side effects remain separately controlled evidence.
• Team-scale change control. Owners review changes to rules and invariants, and every process change records the failure mode or decision that motivated it.

This is an operating-model skeleton, not a drop-in test framework. Adapt ownership, tools, risk categories, and authorization controls to your system.

Repository map

.
├── CLAUDE.md                         # Claude Code entry point and context router
├── README.md
├── commands/
│   └── bug.md                        # /bug contract: evidence, routing, approval
├── contracts/
│   ├── ci-boundary.md                # what CI proves, mocks, and excludes
│   ├── dev-to-qa.md                  # human intent that code cannot provide
│   └── qa-to-dev.md                  # evidence-backed questions before execution
├── examples/
│   ├── coverage-matrix.md            # illustrative coverage decision
│   └── deterministic-e2e.yml         # non-executing example CI workflow
├── governance/
│   └── change-control.md              # ownership and review policy for a team
├── process/
│   └── coverage-matrix.md             # matrix authoring rules
├── rules/
│   └── agent-rules.md                 # reusable failure-prevention rules
└── specs/
    └── invariants.md                  # conditions that precede test design

Workflow

Phase	Agent responsibility	Human decision	Durable output
PREP	Reconcile specification, design, handoff, code, and diff; draft questions and coverage	Approve scope, expected behavior, unresolved owners, and the test plan	Approved plan and coverage matrix
EXEC	Prepare the environment, collect evidence, and draft findings	Run critical scenarios, classify findings, and assign verdicts	Verified findings and final coverage decision
AUTO	Implement deterministic tests and CI integration	Approve assertions, mock boundaries, credentials, and merge	Tests in the product repository and a CI gate

Phase gates describe decision quality. They are not an authorization boundary. Service permissions, protected branches, separate read/write credentials, and audit logs must enforce authorization independently.

Try the reference process

1. Read CLAUDE.md.
2. Replace the illustrative invariants in specs/invariants.md with your system's real constraints.
3. Require contracts/dev-to-qa.md for a feature handoff.
4. Build a matrix using process/coverage-matrix.md.
5. Review the deterministic boundary in contracts/ci-boundary.md before creating automation.
6. Route bug drafts through commands/bug.md; keep the final write behind human approval.

What is deliberately absent

• MCP configuration, OAuth metadata, tokens, and internal service URLs
• real project, repository, team, wallet, and customer names
• production bugs, transaction data, screenshots, and proprietary specifications
• claims that this exact skeleton has been validated at a particular team size

The architecture is designed to scale through explicit ownership and review. A team still needs to measure review latency, rule churn, false-positive rate, and automation maintenance in its own environment.