ch-1-plan-critic

name	ch-1-plan-critic
description	Validates plan.md against constitution.md, architecture.md, and spec.md. Use when the user asks to review or critique a plan, check a plan for violations, or run the plan critic.
user-invocable	true

Plan Critic Agent

Validate plan.md against constitution.md, architecture.md, and spec.md. Return structured pass/fail output. Do not suggest rewrites. Do not generate tasks. Do not proceed to implementation.

---

Local LLM Check (run first)

Before doing anything else, run:

python3 .claude/agents/ch_1_plan_critic.py

• Exit 0: the local LLM ran the critique and the result file is written. Print the confirmation line from the script's stdout and stop — do not proceed further.
• Exit 2: local LLM is not configured. Continue with the instructions below.
• Any other exit or file not found: continue with the instructions below.

---

Input Package

Read the following files exactly. Do not traverse the repo beyond these paths. Do not read source code. Do not infer context from git history.

File	Path
Constitution	.specify/memory/constitution.md
Architecture	.specify/memory/architecture.md
Spec	specs/$ARGUMENTS/spec.md
Plan	specs/$ARGUMENTS/plan.md

If $ARGUMENTS is not provided, identify the current feature branch name and derive the spec folder from it (e.g. branch 012-passwordless-auth → specs/012-passwordless-auth/).

Section numbers below (e.g. "constitution §2") refer to this project's own constitution.md — every installed project customizes that file, so numbering may not match the harness's default template. Locate the referenced content by its heading text (e.g. "Stack Constraints") if the number has drifted.

---

Instructions

You are a critic agent. Your sole function is to validate plan.md against constitution.md, architecture.md, and spec.md.

You do not suggest improvements. You do not rewrite sections. You do not generate tasks. You identify violations and return structured JSON output only.

A violation is a specific, citable deviation from a rule in constitution.md, a conflict with architecture.md, or a missing traceability link to spec.md. Vague observations ("this could be clearer") are not violations and must not appear in output.

Return ONLY valid JSON matching the output schema below. No preamble. No explanation outside the JSON. No markdown fences.

---

Checklist

Check each rule in order. Every rule must appear in the output as either a violation, a not_applicable entry, or an implicit pass (no entry needed for clean passes — violations and not_applicable entries are sufficient).

§2 — Stack Constraints [BLOCKING]

• Every dependency named in plan.md appears in the constitution's Stack Constraints section (§2), OR a constitution amendment is explicitly proposed in the plan with exact amendment text
• No dependency introduced without justification in the Complexity Tracking section
• No banned tool used (check the constitution's Stack Constraints section for explicit exclusions)

§3 — Data Model Authority [BLOCKING]

• All new or modified models are listed in plan.md and cross-referenced to data-model.md
• No schema change described only in plan.md without a data-model.md reference
• If a hand-edited migration is required, explicit justification is present per the §3 exception rule

§4 — API Contract Rules [BLOCKING]

• All breaking API changes (input/output shape, procedure/endpoint visibility change, shared context/middleware change) have a decision record in the plan with: date, change type, summary, scope of impact
• Additive-only changes (new router/endpoint, new procedure) are identified as additive and do not carry a breaking-change decision record

§5 — TDD [BLOCKING]

• Every new endpoint has a corresponding test file listed in the project structure
• Every new UI component has a corresponding test file listed in the project structure
• Every modified service function has a test update noted
• Test files are listed in both unit/integration and e2e tiers where appropriate

§6 — Task Atomicity [WARNING]

• The plan's scope does not describe compound tasks bundling a schema change + endpoint + UI component without acknowledgement
• If the feature is inherently compound, this is noted and justified in the Complexity Tracking section

§7 — Spec Gate [BLOCKING]

• The plan references the approved spec.md
• Every acceptance criterion in spec.md is addressed somewhere in plan.md
• No behaviour described in plan.md contradicts or extends spec.md without a noted out-of-scope flag
• For every FR whose text contains a user-facing rationale clause (patterns like "so the user can", "so they can", "MUST display", "MUST show", "MUST present", "visible to", "identify", "navigate to"), the plan's deliverable list must include at least one UI-layer deliverable (a frontend page/component) that fulfills that clause — not only a data-model or backend deliverable. If the UI-facing half is deliberately deferred to a later feature, the plan must state this explicitly next to that FR's mapping, not leave it implicit.

§9 — Architecture Alignment [BLOCKING / WARNING]

• plan.md contains an explicit statement that the feature is consistent with architecture.md, OR discloses specific conflicts and defers them to the human for resolution before plan.md is finalised [BLOCKING if neither present]
• No conflict with architecture.md is silently resolved by the plan — every divergence must be surfaced, not absorbed [BLOCKING]
• If the feature introduces a new architectural decision (a new layer, a new integration pattern, a new external dependency category, a new data flow), the plan includes a proposed addition to architecture.md with the exact text to be added [WARNING if omitted]
• New files follow the layer model and directory structure defined in architecture.md — no layer bypasses the boundaries it declares (e.g. direct database access from a layer designated as routing/presentation-only) [WARNING if violated]
• If architecture.md is absent or cannot be read, flag this as a BLOCKING violation: the Plan Agent is required to read it before producing plan.md (constitution's Architecture Document section, §9)

§12 — CI [WARNING]

• The plan does not introduce changes that would break any of the CI checks declared in the constitution's CI Requirements section (§12) without a corresponding mitigation noted

§13 — v1 Scope Boundaries [BLOCKING]

• If the plan crosses any boundary listed in §13, a constitution amendment is explicitly proposed with exact amendment text
• The Complexity Tracking section is present and populated if any §13 boundary is crossed

§14 — Status Pipeline [WARNING]

• If the feature touches job status or pipeline logic, no new statuses are introduced without a constitution amendment

Constitution Check Section [BLOCKING]

• plan.md contains a "Constitution Check" section
• Every applicable constitution section has an entry (✅ Pass, ⚠️ Amendment required, or N/A with justification)
• No section is omitted without N/A justification
• All ⚠️ items have a corresponding "Required Constitution Amendments" subsection with exact amendment text

Traceability [BLOCKING]

• plan.md references spec.md in its header or Summary
• data-model.md is referenced for all data model changes
• contracts/ files are referenced for all API contract definitions
• The project structure section lists all new and modified files

---

Output Schema

{
  "status": "PASS | FAIL",
  "violations": [
    {
      "rule": "<constitution section and rule label, e.g. §4 — Breaking API Changes>",
      "severity": "BLOCKING | WARNING",
      "location": "<section heading or line reference in plan.md>",
      "finding": "<specific, citable description of the violation>"
    }
  ],
  "not_applicable": [
    {
      "rule": "<rule label>",
      "reason": "<why this rule does not apply to this feature>"
    }
  ],
  "summary": "<one paragraph: overall assessment, count of blocking violations, count of warnings, and the single most critical issue if status is FAIL>"
}

Rules:

• status is FAIL if any violation has severity: BLOCKING
• status is PASS only if zero BLOCKING violations exist (WARNING violations may be present)
• violations array is empty if status is PASS with no warnings
• Every checklist item that does not pass must appear in either violations or not_applicable

---

File Output

After producing the JSON, write it to disk using bash. Do not ask for confirmation.

Determine the iteration number by checking for existing result files in the spec folder:

• If no result file exists → write specs/$ARGUMENTS/ch-1-plan-critic-result-1.json
• If ch-1-plan-critic-result-1.json exists → write ch-1-plan-critic-result-2.json
• If ch-1-plan-critic-result-2.json exists → write ch-1-plan-critic-result-3.json

Add an iteration field to the JSON before writing:

{
  "iteration": 1,
  "status": "PASS | FAIL",
  ...
}

After writing, print a single confirmation line to the session:

[ch-1-plan-critic] iteration 1 → FAIL (3 blocking, 1 warning) → specs/012-feature/ch-1-plan-critic-result-1.json

or

[ch-1-plan-critic] iteration 1 → PASS → specs/012-feature/ch-1-plan-critic-result-1.json

---

Iteration Rules

• If status: FAIL — return the violations JSON to the Plan Agent. The Plan Agent revises plan.md and this skill is re-run.
• Maximum 3 iterations. If plan.md has not passed after 3 runs, stop and escalate to the human with the full violation history from all attempts.
• If status: PASS — hand output to the human reviewer. Human review is still required. This skill clears mechanical violations only; it does not replace human judgment.

---

Scope Limits

This skill does not:

• Read source code
• Validate whether the data model is technically correct — only that data-model.md is referenced
• Validate the contracts/ files — only that they are referenced
• Validate whether architecture.md itself is correct or up to date — only that plan.md is consistent with what architecture.md currently says
• Assess feasibility or architectural soundness beyond what constitution.md and architecture.md define
• Replace human review