tdd-verify-from-spec

TDD Verify from Spec

The main agent orchestrates verification of each acceptance item in spec.md by dispatching one ac-verifier subagent per item. Each subagent uses a shared playwright persistent profile so the login session is on disk and accessible to all subagents. Failures dispatch fixer subagents. After all items are verified, this skill hands off to design-to-code:visual-qa-from-design.

Plugin-wide discipline (shared HARD-GATE)

• Internal references MUST use design-to-code:<skill-name>. References to superpowers:* are forbidden.
• Artifact directory is docs/design-to-code/<YYYY-MM-DD>-<topic>/. Filenames are fixed: spec.md, plan.md, progress.md, verify.log.md, visual-qa.md.
• Convert this skill's checklist into TodoWrite tasks and execute in order; no skipping.
• spec.md is immutable to the assistant; only the user may edit it. plan.md is written only by design-to-code:writing-plans. progress.md is appended only by design-to-code:subagent-driven-development. verify.log.md is written only by this skill. visual-qa.md is written only by design-to-code:visual-qa-from-design. No skill writes into another skill's artifact.
• Do not write artifact files on main / release. A feature branch or worktree must exist first.

Hard gates

• Code fixes MUST go through a fixer subagent; the main agent does not edit code.
• spec.md is immutable here. The assistant MUST NOT weaken or mutate acceptance items to make verification pass.
• Every acceptance item is recorded as pass/fail in verify.log.md.
• Every failure MUST be classified as either Category A (code-in-repo issue that a fixer could plausibly resolve) or Category B (out-of-repo issue: test case itself ambiguous or wrong, backend data anomaly, environment/dependency issue, or underlying spec.md defect). The classification determines the failure threshold (see below).
• Internal references only design-to-code:*.

Shared playwright profile

All ac-verifier subagents use ~/.playwright-profiles/design-to-code as the persistent profile directory. This means the login session written during the pre-flight step is automatically available to every subagent — no re-login needed.

Session Bootstrap

When invoked in a fresh session where the spec.md path was not passed from a previous skill:

1. Run find docs/design-to-code -name "spec.md" | sort to discover existing specs.
2. One or more results → list them to the user (show the date-topic directory name for each) and ask which feature to continue with. Wait for the answer before proceeding. Then load spec.md and progress.md from the chosen directory.
3. No results → report that no spec.md was found under docs/design-to-code/; ask the user to run design-to-code:brainstorming-from-design first.

Process

1. Pre-flight — ensure the dev server is running (if not, ask the user how to start or start it per project conventions). Ensure @playwright/cli is installed (npm install -g @playwright/cli@latest on miss).

2. Collect dynamic URL parameters — scan all acceptance items in spec.md for URLs or navigation paths that contain dynamic segments (e.g. /teams/:teamId, /projects/:id/issues/:issueId). For each dynamic segment:

   • Try to infer a concrete value from the codebase (seed files, fixtures, .env.example, README, or a quick DB/API query if the project supports it).
   • If a concrete value cannot be confidently inferred, ask the user directly before dispatching any subagent. Example: "AC-3 需要访问一个具体的团队页面。请问你希望用哪个团队测试？请提供团队 ID（或名称）。" Collect all unknowns in a single message — do not ask one at a time if multiple ACs share the same unknown.
   • Record the resolved values (e.g. teamId = 42) for substitution into every AC that needs them.

3. Establish browser session — run once on the main agent:

   playwright open <dev-url> --headed --persistent ~/.playwright-profiles/design-to-code
   

   Prompt the user to log in if not already authenticated. Once the authenticated page is visible, confirm with the user before dispatching subagents. This writes the session to disk so all subsequent ac-verifier subagents share it.

4. Per-item verification loop — for each acceptance item in spec.md, in order:

   • Resolve any dynamic params collected in step 2.
   • Copy ./ac-verifier-prompt.md, fill all {{...}} variables, and dispatch as a subagent.
   • When the subagent returns:
     • PASS: record ✅ in verify.log.md and proceed to next item.
     • FAIL:
       1. Record ❌ with the subagent's assertion result and DOM evidence.
       2. Classify the failure as Category A or Category B (see next section).
       3. For Category A: dispatch a fixer subagent (see ./fixer-prompt.md). When the fixer returns, dispatch a fresh ac-verifier for the SAME acceptance item.
       4. For Category B: do NOT dispatch a fixer. Record the category and reasoning in verify.log.md.

5. Completion — after all items pass (or are recorded as Category B), invoke design-to-code:visual-qa-from-design to run pixel-level visual fidelity verification against the original design source. Pass the spec.md path so the visual-qa skill can locate the design reference.

Failure classification and thresholds

• Category A — code-in-repo: defect looks fixable by editing files in the current repo (component, slice, API call, styling, routing, etc.). Threshold: 5 consecutive rounds on the same acceptance item pauses the loop and reports to the user.
• Category B — out-of-repo: test case itself ambiguous or wrong, backend data anomaly, environment/dependency issue, spec.md defect. Threshold: 2 consecutive rounds on the same acceptance item pauses the loop and reports to the user. Do NOT dispatch a fixer for Category B failures.
• When uncertain about classification, treat as Category B (fail-fast) rather than burning rounds on Category A.
• An item may change category across rounds; use the threshold matching the current round's category.

Prompt files

• ./ac-verifier-prompt.md — template for the ac-verifier subagent. Fill {{AC_ITEM}}, {{DEV_URL}}, {{PLAYWRIGHT_PROFILE_PATH}} (use ~/.playwright-profiles/design-to-code), {{RESOLVED_PARAMS}}, and {{SCREENSHOT_PATH}} before dispatching.
• ./fixer-prompt.md — sent to fixer subagents (Category A failures only).

Integration

Required workflow skills:

• design-to-code:subagent-driven-development — runs before this skill; produces the implementation.
• design-to-code:visual-qa-from-design — runs after this skill; checks pixel-level visual fidelity against the original design.

Artifacts

• verify.log.md (committed to git by the user's project). Per-item entry:

  ## Acceptance N: <item>
  - Attempts: <count>
  - Result: ✅ / ❌
  - Category (only on ❌): A (code-in-repo) / B (out-of-repo)
  - Category reasoning (only on ❌): <one-line justification>
  - Evidence: <screenshot path or DOM excerpt>
  - Fixes applied: <files changed by fixer, if any>