Verify Workflow

---
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

```text
/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.

1. Create feature branch: git checkout -b feat/{feature-name} (skip if already on one)

2. Dev server verified: curl -s -o /dev/null -w "%{http_code}" http://localhost:3000 → expect 200. If not reachable, ask human to start it.

3. Admin login verified: Navigate to /auth/admin-signin, fill credentials from MEMORY.md, confirm login succeeds. If it fails, STOP.

4. 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)

1. Plan committed: git commit --no-verify -m "docs: add plan for {feature}"

2. 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.

3. Status updated (via Edit tool on .claude/verification-status.json): 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."
   }
   

4. 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.

5. When coding begins, update status to "implementing" (Edit tool)

6. When all code is written + precheck passes, update status to "pending" (Edit tool)

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 TodoWrite.

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.json to "pending" (Edit tool) before proceeding to verification.

Step 2: Verify (sub-agent delegation)

Mandatory and automatic. After precheck passes, immediately read the ACs doc and spawn the verification sub-agent. Do NOT pause, do NOT ask the user "should I run verification?" — just proceed.

How to build the sub-agent prompt:

1. Read the ACs doc (docs/features/{feature}/ACs.md or docs/plans/{feature}-ACs.md) to extract the full AC list
2. Check for --skip-ui flag or CI/backend-only note in the plan → omit PAGES_TO_SCREENSHOT and set DEV_SERVER to "N/A"
3. Spawn immediately:

**⚠️ CRITICAL — first line