name: verify-workflow description: Full verification workflow automation - precheck, tests, UI verification before human review

Verify Workflow Skill

Orchestrates the full autonomous feature development loop — from implementation through verification — with sub-agent delegation and human-in-the-loop review gates.

IMPORTANT: Verification is NOT optional for AC-driven features. Once implementation is complete and status is pending, you MUST run the verification loop. Do not ask the user "should I verify?" — just proceed with verification.

See docs/AGENTIC-WORKFLOW.md for the complete architecture document.

Purpose

Drive a complete implement -> verify -> iterate -> review loop using sub-agents for verification, keeping the main thread's context clean for implementation work.

Usage

/verify-workflow                           # Full loop: implement -> verify -> review-ready
/verify-workflow --verify-only             # Skip implementation, verify + test only
/verify-workflow --skip-ui                 # Skip UI verification (code-only changes)
/verify-workflow --acs "AC1" "AC2"         # Verify specific ACs only

Triggering: This workflow is invoked explicitly by the user or the main thread when ready. It does NOT run automatically on every code change.

The Loop

┌──────────────────────────────────────────────────────────┐
│  1. IMPLEMENT (main thread)                              │
│     - Write code per approved plan                       │
│     - Track progress with task list                      │
│     - Run precheck after implementation                  │
│                                                          │
│  2. VERIFY (sub-agent)                                   │
│     - Spawn general-purpose sub-agent with /ac-verify    │
│     - Sub-agent: screenshots + code review + tests       │
│     - Sub-agent returns: structured pass/fail report     │
│                                                          │
│  3. ITERATE (main thread, if issues found)               │
│     - Read sub-agent report                              │
│     - Fix code based on findings                         │
│     - Re-spawn sub-agent for re-verification             │
│     - Repeat until all ACs pass                          │
│                                                          │
│  4. READY FOR REVIEW (main thread)                       │
│     - Update verification-status.json                    │
│     - Present consolidated report to human               │
│     - Human approves -> commit, PR, release              │
│     - Human rejects -> back to step 3                    │
└──────────────────────────────────────────────────────────┘

Step-by-Step

Step 0a: Workflow Initiation (before plan mode)

MANDATORY before entering plan mode. Run these checks first. If any fail, fix before planning.

Create feature branch: git checkout -b feat/{feature-name} (skip if already on one)
Dev server verified: curl -s -o /dev/null -w "%{http_code}" http://localhost:3000 → expect 200. If not reachable, ask human to start it.
Admin login verified: Navigate to /auth/admin-signin, fill credentials from MEMORY.md, confirm login succeeds. If it fails, STOP.

Status registered: Create entry in verification-status.json with "planning" status and acs_total: 0:

// .claude/verification-status.json → branches["{branch}"]
{
  "status": "planning",
  "acs_passed": 0,
  "acs_total": 0,
  "tasks": [],
  "notes": "Workflow initiated. Entering plan mode."
}

Only after all 4 checks pass does planning begin.

Step 0b: Post-Plan-Approval (after human approves plan)

Plan committed: git commit --no-verify -m "docs: add plan for {feature}"
ACs doc created: Extract ACs from plan into docs/plans/{feature}-ACs.md using the template at docs/templates/acs-template.md. All What/How/Pass columns filled, Agent/QC/Reviewer columns empty.

Status updated: Update entry from "planning" → "planned" with acs_total set to actual AC count:

// .claude/verification-status.json → branches["{branch}"]
{
  "status": "planned",
  "acs_passed": 0,
  "acs_total": {count from plan},
  "tasks": [],
  "notes": "Plan approved and committed."
}

Verify status clean: Confirm the current branch is in "planned" state. If it's in "pending" or "partial", a previous iteration was interrupted — resume from there instead of restarting.
When coding begins, update status to "implementing"
When all code is written + precheck passes, update status to "pending"

This activates the enforcement hooks: SessionStart will inject workflow context, Stop will block premature completion, and the commit gate will allow intermediate commits.

Step 1: Implement

Execute the approved plan. Track progress with TaskCreate/TaskUpdate.

Follow the commit schedule defined in the plan — commit logical chunks as you go (status must be "planned" or "implementing" for intermediate commits).

After implementation, run precheck:

npm run precheck

Fix any TS/ESLint errors, then update verification-status to "pending" before proceeding to verification.

Step 2: Verify (sub-agent delegation)

Spawn a verification sub-agent using the /ac-verify skill template. The sub-agent fills the Agent column in the ACs tracking doc (docs/plans/{feature}-ACs.md):

Task(subagent_type="general-purpose", prompt="""
Run the AC verification protocol from .claude/skills/ac-verify/SKILL.md.

BRANCH: {current branch name}
DEV_SERVER: http://localhost:3000
ACS_DOC: docs/plans/{feature}-ACs.md

ACS:
{paste the AC list from the approved plan}

PAGES_TO_SCREENSHOT:
{list pages and interaction steps}

CONTEXT:
{relevant file paths and behavioral notes}
""")

Parallelism option: For large features, spawn UI verification and test suite as separate sub-agents:

# Parallel sub-agents
Task("UI ACs", subagent_type="general-purpose", prompt="Verify UI ACs: ...")
Task("Test suite", subagent_type="general-purpose", prompt="Run npm run test:ci and report results...")

Sub-agent monitoring: Run sub-agents in the background (run_in_background: true). Check back after 5 minutes using the Read tool on the output file. If the sub-agent is stuck (repeating the same action, retrying a failing step, or making no progress), stop it with TaskStop and either:

Re-spawn with corrected instructions (e.g., fix a selector, adjust navigation steps)
Take over the task in the main thread if the sub-agent lacks the context to recover

Step 3: Iterate (if needed)

Read the sub-agent's report (the Agent column in the ACs doc). For each failed AC:

Identify root cause from the report's evidence (screenshot, file:line)
Fix the code in the main thread
Fill in the QC column with your assessment (confirms or overrides Agent result, with fix notes)
Re-spawn a new sub-agent to re-verify ALL ACs (not just failed ones)
Repeat until all pass

Key: Always re-verify all ACs after fixes to catch regressions.

This loop is fully autonomous — the human does not need to be present during implement/verify/iterate cycles. The human is only needed at plan approval (Phase 1) and final review (Step 4).

Step 4: Ready for Review

When all ACs pass:

Update verification status:

// .claude/verification-status.json
{
  "branches": {
    "{branch}": {
      "status": "verified",
      "acs_passed": 9,
      "acs_total": 9,
      "tasks": [],
      "notes": "All ACs verified via sub-agent. {n} iterations."
    }
  }
}

Ensure ACs doc is complete: All three columns should be filled — Agent (by sub-agent), QC (by main thread). The Reviewer column is left empty for the human.

Present handoff to human:

## Ready for Review

- Branch: {branch}
- Files changed: {n}
- ACs: {passed}/{total} passed
- Tests: {passed}/{total} passed
- Iterations: {n}

ACs tracking doc: docs/plans/{feature}-ACs.md
Please review and fill in the Reviewer column.

Approve to commit and release, or provide feedback to iterate.

On approval: Commit -> PR -> merge -> /release
On rejection: Fix -> re-verify (back to Step 2)

AC Categories

Plans must include ACs in these categories:

Category	Prefix	Verified By	Example
UI	AC-UI-{n}	Screenshots at 3 breakpoints	"Button visible at mobile width"
Functional	AC-FN-{n}	Code review with file:line evidence	"Endpoint returns 403 for non-owner"
Regression	AC-REG-{n}	Test suite + screenshot spot-check	"Existing columns unchanged"

Human Checkpoints

The implement → verify → iterate loop is fully autonomous. The human only needs to be present at two gates:

Gate	When	Why
Plan approval	Before implementation	Human approves ACs as verification contract, then can step away
Dev server	Server not running (pre-flight)	Human starts server, then can step away
Review gate	All ACs pass, Agent + QC columns filled	Human fills Reviewer column in ACs doc, approves or rejects

The human does NOT need to be present during autonomous iteration cycles (implement → verify → fix → re-verify).

Templates

Template	Path	Purpose
Plan template	`docs/templates/plan-template.md`	Structure for feature plans with ACs and commit schedule
ACs template	`docs/templates/acs-template.md`	Structured What/How/Pass + Agent/QC/Reviewer tracking doc for verification handoff

Integration with Other Skills

Skill	Role in Loop
`/ac-verify`	Sub-agent prompt template (Step 2) — sub-agent fills Agent column
`/ui-verify`	Screenshot capture and comparison (used by sub-agent)
`/release`	Version bump + tag + PR (Step 4, after approval)

Gotchas

Next.js Cache

After modifying client components, dev server may serve stale builds:

Stop dev server
rm -rf .next
Restart dev server
Wait for compilation before spawning verification sub-agent

Screenshot Script Port

Default is localhost:3000. If dev server runs on different port, pass it in the sub-agent prompt as DEV_SERVER: http://localhost:{port}.

Sub-Agent Context

Each sub-agent starts fresh — it does not have the main thread's conversation history. Include all relevant context (file paths, component names, behavioral notes) in the sub-agent prompt.

Quick Reference

# Full loop (plan -> implement -> verify -> review)
/verify-workflow

# Verify only (skip implementation)
/verify-workflow --verify-only

# Code-only (no UI screenshots)
/verify-workflow --skip-ui

# Specific ACs
/verify-workflow --acs "AC-UI-1" "AC-FN-2"

Name	verify-workflow
Description	Full verification workflow automation - precheck, tests, UI verification before human review