execute

name	execute
description	Execute an implementation plan step by step. Use after planning is complete.
disable-model-invocation	true
allowed-tools	Read, Write, Edit, Bash, Glob, Grep
argument-hint	["path-to-plan"]

Execute: Implement from Plan

Plan to Execute

Read plan file: $ARGUMENTS

If no argument provided, list available plans: !ls -la .agents/plans/ 2>/dev/null || echo "No plans found"

Execution Instructions

1. Read and Understand

• Read the ENTIRE plan carefully
• Understand all tasks and their dependencies
• Note the validation commands to run
• Review the testing strategy
• Check the patterns to follow

2. Create Feature Branch (MANDATORY)

BEFORE any code changes, create a feature branch from latest main.

# Derive branch name from plan file
# Example: .agents/plans/2026-02-11-crash-safe-session-tracking.md
#        → feature/crash-safe-session-tracking
PLAN_FILE="$ARGUMENTS"
BRANCH_NAME=$(basename "$PLAN_FILE" .md | sed 's/^[0-9]\{4\}-[0-9]\{2\}-[0-9]\{2\}-//')
BRANCH_NAME="feature/$BRANCH_NAME"

# Ensure we branch from latest main
git checkout main
git pull origin main

# Create and switch to feature branch
git checkout -b "$BRANCH_NAME"

Show confirmation:

┌──────────────────────────────────────────────────────────────────────┐
│  FEATURE BRANCH CREATED                                              │
│  ──────────────────────                                              │
│                                                                      │
│  Branch:  feature/crash-safe-session-tracking                        │
│  Base:    main (up to date)                                          │
│  Plan:    .agents/plans/2026-02-11-crash-safe-session-tracking.md    │
│                                                                      │
│  All commits will land on this branch.                               │
│  Use /pr when implementation is complete.                            │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘

Branch naming rules:

• Strip date prefix from plan filename (YYYY-MM-DD-)
• Prefix with feature/ (or fix/ if plan is a bugfix)
• Lowercase, kebab-case
• If no plan file given, ask user for branch name

Safety checks:

• If already on a feature branch: Ask user if they want to continue on it or create a new one
• If there are uncommitted changes: STOP and ask user to commit or stash first

3. Pre-Flight Checks

Before starting implementation:

# Ensure clean working state
git status

# Ensure dependencies are installed
cd frontend && pnpm install

# Ensure dev server works
pnpm run dev
# (Stop with Ctrl+C after confirming it works)

3. Execute Tasks with TDD

For EACH task in "Step by Step Tasks":

a. Navigate to the task

• Identify the file and action required
• Read existing related files if modifying

b. Apply TDD (Test-Driven Development)

For functions, utilities, schemas, API routes:

1. RED - Write Test First

   # Create test file: lib/__tests__/[name].test.ts
   # Write tests that define expected behavior
   # Run: pnpm run test
   # Tests MUST fail (function doesn't exist yet)
   

2. GREEN - Write Minimal Code

   # Implement the function
   # Run: pnpm run test
   # Tests MUST pass
   

3. REFACTOR - Improve Code

   # Improve code quality
   # Run: pnpm run test
   # Tests MUST still pass
   

Skip TDD for:

• UI styling (use /visual-verify)
• Trivial getters/setters
• Framework boilerplate

c. Implement the task

• Follow the detailed specifications exactly
• Maintain consistency with existing code patterns
• Include proper TypeScript types
• Add structured logging where appropriate
• Follow shadcn/ui patterns for UI components

d. Verify as you go

• After each file change, run pnpm run test
• Ensure TypeScript has no errors
• Ensure imports are correct

3.5 Progress Tracking (Optional - Claude Code v2.1.16+)

Use Claude Code's Task system for visual progress tracking in the terminal.

When to Use Task Tracking

Scenario	Use Tasks?
3+ tasks in plan	Yes
Complex multi-file changes	Yes
Quick single-file fix	No
User requests tracking	Yes

How to Track Progress

Before starting implementation:

TaskCreate({
  subject: "Task 1: Create types",
  description: "Create TypeScript interfaces for the feature",
  activeForm: "Creating types"
})

When starting a task:

TaskUpdate({ taskId: "1", status: "in_progress" })

When completing a task:

TaskUpdate({ taskId: "1", status: "completed" })

Benefits

• Visual progress bar in terminal
• Clear status of each task
• Can be resumed if session interrupted
• Provides structured progress report

Task Dependencies (Advanced)

For sequential tasks where one must complete before another:

TaskUpdate({ taskId: "2", addBlockedBy: ["1"] })

Task 2 will automatically unblock when Task 1 completes.

4. Implement Testing Strategy

After completing implementation tasks:

• Create all test files specified in the plan
• Implement all test cases mentioned
• Follow the testing approach outlined
• Ensure tests cover edge cases

5. Run Validation Commands

Execute ALL validation commands from the plan in order:

# Level 1: Syntax & Style
cd frontend && pnpm run lint
cd frontend && pnpm run type-check

# Level 2: Unit Tests
pnpm run test

# Level 3: Build
cd frontend && pnpm run build

If any command fails:

• Fix the issue
• Re-run the command
• Continue only when it passes

5.5 Architecture Guard (MANDATORY)

Run quality gate subagents on all changed files:

1. architecture-guard on all modified/created files
2. design-system-guard if any UI files were changed (components/, app/)
3. ssr-safety-checker if any React components were changed
4. mastra-validator if any mastra/ files were changed

Gate Results:
- CRITICAL → STOP. Fix before proceeding.
- HIGH     → STOP. Fix before proceeding.
- WARNING  → List warnings. User decides.
- INFO     → Document and continue.

See .claude/reference/quality-gates.md for full gate architecture.

5.6 Unit Test Gate (MANDATORY)

Check that new code has tests:

1. For every new function/utility: verify a corresponding test exists
2. Run pnpm run test - must be green
3. If tests are missing for new code: STOP and write tests before continuing

5.7 Change Size Classification (MANDATORY)

Classify the scope of changes to determine if Visual Verification is needed:

git diff --stat main..HEAD

Level	Criteria	Visual Verification?
S	1-2 files, config/docs only	No
M	3-10 files, single component	No
L	10+ files, new feature with UI	YES

Any change that touches UI files (components/, app/) AND is L-level triggers Visual Verification.

5.8 Smoke Test (MANDATORY for M and L)

Always runs proactively for M and L changes. No user confirmation needed.

Verify the basics work before anything else:

# 1. Is the dev server running? If not, start it.
pnpm run dev

# 2. Does the main page respond?
curl -s -o /dev/null -w "%{http_code}" http://localhost:[PORT]/

# 3. Are API endpoints reachable? (if API routes were changed)
curl -s -o /dev/null -w "%{http_code}" http://localhost:[PORT]/api/health

Show a brief status:

┌──────────────────────────────────────────────────────────────────┐
│  SMOKE TEST                                                       │
│  ──────────                                                       │
│  Dev server: Running on :3000                                    │
│  Main page:  200 OK                                              │
│  API health: 200 OK                                              │
└──────────────────────────────────────────────────────────────────┘

If anything returns an error: try refreshing/restarting. If still broken, fix the code.

5.9 Visual Verification Gate (L-Level with UI — ASK FIRST)

Skip this step if change level is S or M, or if no UI files were changed.

ASK THE USER before starting browser verification:

This was a large feature (L-level, [X] files changed).
Shall I verify the UI in the browser with screenshots?

If user confirms, show status and proceed:

┌──────────────────────────────────────────────────────────────────┐
│  VISUAL VERIFICATION                                              │
│  ────────────────────                                             │
│                                                                   │
│  Change Level: L (Large) — [X] files changed                    │
│  Affected Pages: [list of routes]                                │
│                                                                   │
│  I'm now verifying the implementation in the browser.             │
│  Opening pages, taking screenshots, checking layout.              │
│  If something doesn't work, I'll fix it before moving on.        │
│                                                                   │
└──────────────────────────────────────────────────────────────────┘

Steps:

1. Ensure dev server is running (should be from smoke test)
2. For each affected page:

   agent-browser open http://localhost:[PORT]/[path]
   agent-browser snapshot -i
   agent-browser screenshot ./screenshots/[page]-desktop.png
   

3. Check each page:
   • Page loads without blank screen or errors
   • Layout matches expected structure
   • Key interactive elements are present
4. Mobile check (for responsive pages):

   agent-browser viewport 375 812
   agent-browser screenshot ./screenshots/[page]-mobile.png
   

5. If issues found: fix the code, re-verify, loop until clean
6. Only proceed when all pages work correctly

If user declines, skip browser verification but note it in the output report.

See .claude/reference/quality-gates.md → "Visual Verification Gate" for full rules.

6. Manual Testing

Follow the manual testing checklist from the plan:

1. Start the dev server: cd frontend && pnpm run dev
2. Open http://localhost:3000
3. Test the feature as described
4. Test on mobile viewport (Chrome DevTools)
5. Test edge cases

7. Final Verification

Before completing:

• All tasks from plan completed
• All tests created and passing
• All validation commands pass
• Code follows project conventions
• Mobile responsive verified
• Visual verification passed (if L-level with UI)
• Documentation added/updated as needed

Output Report

Provide summary:

Completed Tasks

• List of all tasks completed
• Files created (with paths)
• Files modified (with paths)

Tests Added

• Test files created
• Test cases implemented
• Test results (pass/fail)

Validation Results

# Output from each validation command

Screenshots/Evidence

• Describe what was manually tested
• Note any visual changes

Issues Encountered

• Any deviations from the plan
• Problems solved during implementation
• Suggestions for plan improvements

Ready for Commit

• Confirm all changes are complete
• Confirm all validations pass
• Ready for /commit command

Update PROJECT-STATUS.md

After completing execution, update PROJECT-STATUS.md:

Update Progress

## Active Plan

**Plan:** `.agents/plans/[plan-name].md`
**Feature:** [Feature description]
**Phase:** Implementation Complete
**Progress:** [X/Y] tasks completed

### Completed Tasks
- [x] Task 1 - [Description]
- [x] Task 2 - [Description]
...

Add to Recent Activity

| [Today] | execute | Completed: [feature-name] |

If All Tasks Complete

Update status to indicate ready for validation and commit:

**Phase:** Implementation Complete
**Next Steps:**
1. Run `/validate` to verify all checks pass
2. Run `/commit` to create commit

Notes

• If you encounter issues not addressed in the plan, document them
• If you need to deviate from the plan, explain why
• If tests fail, fix implementation until they pass
• Don't skip validation steps
• Ask for clarification if something is unclear