<!-- Generated from workflows/plan-execute.md by tools/generate_integrations.py. Edit the source file, not this one. This is an execution WORKFLOW packaged as an Agent Skill so it is discoverable and directly invocable ("/plan-execute") in every compatible tool. -->

Workflow: Plan-then-Execute

When to Use

Criteria	Match
Intention	complex_feature, refactor, moderate_change
Complexity	multi-file, moderate risk, needs up-front analysis
Power Mode	Balanced or Deep
Clarity	requirements are clear but implementation is non-trivial

Required Skills

• codebase-understanding (GitNexus): for pre-analysis
• file-operations
• code-execution
• code-quality-testing
• communication-tone
• build-discipline
• project-scaffolding (if new files needed)
• safety-profiles (default or strict)

Flow

Phase 0: Thinking Stage (Pre-Action)

• Is the user's intent clear? Re-evaluate on EVERY new message
• Have I read the relevant code areas? NEVER change what I haven't read
• Do I understand the existing patterns and conventions?
• What's the blast radius of my planned changes? (GitNexus impact analysis)
• Verify: am I in PLAN mode or EXECUTE mode? Never mix the two

Phase 1: Intent Gate

Determine: Am I in plan mode or execute mode?

• Plan mode: research, gather context, propose approach; NO file changes
• Execute mode: implement following the approved plan; NO scope changes

State your mode at the start: "I'm in PLAN mode. Let me research before making changes."

Phase 2: Research & Context (Plan Mode)

1. READ gitnexus://repo/{name}/context → Codebase overview
2. query({search_query: "<relevant concept>"}) → Find related code
3. impact({target: "<planned change area>", direction: "upstream"})
   → Understand blast radius before designing solution
4. Read key source files for implementation details
5. Check existing patterns and conventions in the codebase

Phase 3: Propose Plan (Plan Mode)

• Multi-Axis Solution Mapping: Map at least 2 distinct implementation approaches (evaluating trade-off axes: complexity vs performance vs maintainability vs blast radius) before selecting the optimal path. Present to user:
• What needs to change (files, interfaces, data flow)
• How it will change (selected optimal approach & trade-off rationale)
• Risk assessment (based on GitNexus impact analysis)
• Order of changes (dependencies between changes)
• What won't change (scope boundaries)

Phase 4: Execute (Execute Mode)

• After user approves the plan
• Follow the planned order precisely
• Implement one logical unit at a time
• After each unit: verify it works before moving on

Phase 5: Real Test Verification & Shipping Sync

• Run tests for affected execution flows
• Real Test Contract: Wait on real completion signals, not fixed sleeps. Test against non-cached truth endpoints or vary cache keys. Isolate tests from persisted service state.
• Shipping Verification: Run full test verification suite (pnpm test / npm run verify) prior to committing.
• Documentation Synchronization: If code changes alter API contracts, configuration, or developer workflows, update corresponding documentation files in the same change set.
• detect_changes() to confirm scope matches plan
• Linter on new/changed files

Phase 5b: Sanity Check

• Does the implementation match the approved plan? Any deviations?
• Have all planned files been created/modified? No orphaned code?
• detect_changes(): is scope limited to what was planned?
• Does the existing functionality still work? (regression check)
• Are there linter errors or test failures?

Phase 6: Report

• What was implemented (matching the plan)
• Any deviations from the plan (and why)
• Verification results

Token Budget

• Typical: 15K-60K tokens
• Max recommended: 100K tokens
• Warning threshold: >100K → switch to Spec-Driven or session summarization

GitNexus Integration: Heavy in Plan Phase

• query: understanding related code
• impact: pre-implementation blast radius
• context: interface understanding
• detect_changes: post-implementation verification

Hallucination Watchpoints

• Switching to execute mode without user approval
• Adding scope/features not in the approved plan
• Skipping research phase for "obvious" changes
• Not checking blast radius before implementation
• Inconsistent: plan says one thing, code does another

Example

User: "Add rate limiting to the API"

PLAN MODE:
1. query({search_query: "api middleware request handling"})
   → Found: apiMiddleware, requestHandler, authMiddleware
2. impact({target: "apiMiddleware", direction: "upstream"})
   → d=1: router definitions, request handler
3. Plan:
   - New file: src/middleware/rateLimiter.ts
   - Integration: add to apiMiddleware chain
   - Uses express-rate-limit package
   - Risk: LOW (middleware pattern already exists)

USER: "Looks good, proceed"

EXECUTE MODE:
1. pnpm install express-rate-limit
2. Create src/middleware/rateLimiter.ts
3. Wire into apiMiddleware
4. verify → linter clean, tests pass