Triangulated Spec Review Loop

Use this reference when running multi-agent review rounds for a spec, ADR, or architecture proposal.

Prompt Contract

Ask each reviewer to read the same target file and return JSON:

{
  "reviewer": "claude|qodercli|agent|codex",
  "verdict": "pass|fail",
  "p1_p2_clear": true,
  "summary": "...",
  "findings": [
    {
      "severity": "P1|P2|P3",
      "dimension": "complexity|convenience|evolution",
      "issue": "...",
      "evidence": "...",
      "recommendation": "..."
    }
  ]
}

agent is Cursor's CLI.

Default dimensions:

• complexity: whether the design is understandable and not over-factored.
• convenience: whether contributors and agents can find the correct edit target.
• evolution: whether the design can grow without migration traps.

Severity Rubric

• P1: blocks adoption because the spec is unsafe, contradictory, or likely to cause wrong edits.
• P2: should be fixed before acceptance because the spec is ambiguous, inconvenient, or likely to drift.
• P3: useful polish that does not block acceptance.

Only P1 and P2 findings drive mandatory iteration.

Reviewer Command Matrix

Prefer cross-platform argv execution from the bundled script. When running manually, use equivalent commands:

claude -p --permission-mode dontAsk --max-budget-usd 0.50 --tools Read,Glob,Grep,LS

qodercli --cwd <repo> --setting-sources user,project,local --permission-mode dont_ask --max-output-tokens 3000 -p "$PROMPT"

agent -p --mode ask --trust --workspace <repo> "$PROMPT"

If codex is part of the requested surface, use the locally supported noninteractive command and keep the same prompt and output schema.

Iteration Pattern

1. Run all reviewers against the same spec.
2. Parse findings into P1/P2/P3.
3. Cluster duplicate issues by target concept, not by wording.
4. Patch the smallest owning section for P1/P2.
5. Run local validation.
6. Re-run reviewers with the same prompt.

Stop when all required reviewers return p1_p2_clear: true.

Common Finding Patterns

• Layer collision: two directories own the same behavior.
• Target-only trap: a future directory is written as if it exists today.
• Naming collision: two paths share a term but have different ownership.
• Generated-vs-source ambiguity: package output is not marked generated.
• Promotion gap: example, community, or draft assets can become runtime policy without an explicit gate.
• Adapter leakage: host-specific rules leak into shared detector or report logic.