@karthikrajkumar.kannan/get-things-done 1.0.0

package/workflows/backward/verify-document.md

@@ -0,0 +1,79 @@
+<purpose>
+Run accuracy verification and completeness audit on a generated document.
+Spawns both verification agents and produces a combined report.
+</purpose>
+
+<available_agent_types>
+- gtd-accuracy-verifier — Cross-references claims against codebase
+- gtd-completeness-auditor — Checks template and component coverage
+</available_agent_types>
+
+<process>
+
+<step name="initialize">
+```bash
+INIT=$(node "$GTD_TOOLS_PATH/gtd-tools.cjs" init verify-document "$DOC_TYPE" "$ARGUMENTS")
+```
+Parse: project_root, docs_root, config, state, args.
+Extract: doc_type from args, --strict flag.
+
+Locate the document to verify:
+1. Check drafts/<TYPE>-DRAFT.md (verify draft before finalization)
+2. Check documents/<TYPE>.md (verify finalized document)
+3. Error if neither exists
+</step>
+
+<step name="spawn_verifiers">
+**Spawn accuracy verifier:**
+```
+Verify the document at: {doc_path}
+Project root: {project_root}
+Codebase map: {docs_root}/CODEBASE-MAP.md
+Write report to: {docs_root}/verification/{DOC_FILENAME}-VERIFICATION.md
+```
+
+**Spawn completeness auditor:**
+```
+Audit completeness of: {doc_path}
+Codebase map: {docs_root}/CODEBASE-MAP.md
+Analysis directory: {docs_root}/analysis/
+Template type: {doc_type}
+Write report to: {docs_root}/verification/{DOC_FILENAME}-COMPLETENESS.md
+```
+
+Run both agents (sequentially or in parallel per config).
+</step>
+
+<step name="aggregate_results">
+Read both reports. Produce combined summary:
+
+```
+📋 Verification Results: {Doc Type}
+
+  Accuracy:
+    ✓ Verified: {N} claims
+    ✗ Inaccurate: {N} claims
+    ? Unverifiable: {N} claims
+    Confidence: {score}%
+
+  Completeness:
+    Sections: {complete}/{total}
+    Components: {documented}/{total}
+    Overall: {score}%
+
+  {#if inaccurate > 0}
+  ⚠ Corrections needed:
+    {list of inaccuracies with corrections}
+  {/if}
+
+  {#if gaps > 0}
+  📝 Documentation gaps:
+    {list of missing components/sections}
+  {/if}
+```
+
+If --strict and (accuracy < 90% or completeness < 100%):
+  Display: "STRICT MODE: Verification failed. Fix issues before finalizing."
+</step>
+
+</process>

package/workflows/forward/add-phase.md

@@ -0,0 +1,29 @@
+<purpose>
+Add a new phase to the existing roadmap without disrupting current progress.
+</purpose>
+
+<process>
+
+<step name="initialize">
+```bash
+INIT=$(node "$GTD_TOOLS_PATH/gtd-tools.cjs" init add-phase "$ARGUMENTS")
+```
+Parse: docs_root, roadmap, args (phase description).
+</step>
+
+<step name="determine_position">
+Read ROADMAP.md → determine next phase number.
+Ask user: insert at position N or append to end?
+</step>
+
+<step name="create_phase">
+Create phase directory: .planning/phases/{padded}-{slug}/
+Update ROADMAP.md with new phase entry (status: pending).
+Link requirements if provided.
+</step>
+
+<step name="report">
+Display: "Phase {N} added: {name}. Run /gtd-discuss-phase {N} to begin."
+</step>
+
+</process>

package/workflows/forward/autonomous.md

@@ -0,0 +1,62 @@
+<purpose>
+Run phases N through M unattended. Loops through each phase from current to target, executing the full pipeline (discuss, plan, execute, verify) with auto-approved gates. Stops on any abort gate.
+</purpose>
+
+<process>
+
+<step name="initialize">
+```bash
+INIT=$(node "$GTD_TOOLS_PATH/gtd-tools.cjs" init autonomous "$ARGUMENTS")
+```
+Parse: docs_root, state, roadmap, config.
+Parse flags: --from N (default: current phase), --to M (required).
+Validate: phase range exists in ROADMAP.md.
+</step>
+
+<step name="configure_auto_mode">
+Set auto-approve for all human gates within the loop.
+Record original state so it can be restored on abort.
+Track progress: phases_completed, phases_remaining, errors.
+</step>
+
+<step name="loop_phases">
+For each phase from {start} to {target}:
+
+  1. **Discuss** (auto): run discuss-phase with --auto flag, skip interactive prompts
+  2. **Plan**: run plan-phase for the current phase
+  3. **Execute**: run execute-phase for the current phase
+  4. **Verify**: run verify-work for the current phase
+
+  After each sub-step:
+  - Check result status — if abort gate triggered, stop immediately
+  - Update progress tracker
+  - Log: "Phase {N}/{M}: {sub_step} complete"
+
+  ```bash
+  node "$GTD_TOOLS_PATH/gtd-tools.cjs" state update forward.current_phase "$PHASE"
+  ```
+</step>
+
+<step name="report">
+Display:
+```
+Autonomous run complete
+
+  Phases completed: {count}/{total}
+  Total commits: {commit_count}
+  Duration: {elapsed}
+  Status: {success|aborted at Phase N step}
+
+  Next: /gtd-ship (create PR)
+        /gtd-deploy-local (test locally)
+```
+</step>
+
+</process>
+
+<error_handling>
+- Abort gate triggered → stop loop, preserve state, report which phase/step failed
+- Executor crash → retry phase once, then abort with report
+- Verification failure → attempt debug loop (3 tries), then abort if unresolved
+- Ctrl+C / interrupt → save progress, report partial completion
+</error_handling>

package/workflows/forward/code-review.md

@@ -0,0 +1,78 @@
+<purpose>
+Code quality review. Spawns a gtd-code-reviewer agent on the current phase's changes. Produces REVIEW.md with findings categorized as critical, major, minor, or suggestion.
+</purpose>
+
+<available_agent_types>
+- gtd-code-reviewer — Reviews code for quality, correctness, and style
+</available_agent_types>
+
+<process>
+
+<step name="initialize">
+```bash
+INIT=$(node "$GTD_TOOLS_PATH/gtd-tools.cjs" init code-review "$ARGUMENTS")
+```
+Parse: phase_number (optional, defaults to current phase), docs_root, config, state.
+Determine diff scope: phase branch vs main, or staged changes.
+</step>
+
+<step name="collect_changes">
+Gather the changeset for review:
+```bash
+DIFF=$(git diff main...HEAD --stat)
+FILES=$(git diff main...HEAD --name-only)
+```
+
+If no phase specified, review all uncommitted + committed changes since last milestone.
+Read project conventions from PROJECT.md if available.
+</step>
+
+<step name="spawn_reviewer">
+Spawn gtd-code-reviewer agent:
+```
+Review these changes for code quality:
+
+Changed files:
+{file_list}
+
+Project context:
+  PROJECT.md: {path}
+  REQUIREMENTS.md: {path}
+
+Review criteria:
+- Correctness: bugs, logic errors, edge cases
+- Security: vulnerabilities, input validation
+- Performance: inefficiencies, N+1 queries
+- Maintainability: readability, naming, complexity
+- Style: consistency with project conventions
+
+Categorize each finding as: critical / major / minor / suggestion
+Write: {phase_dir}/REVIEW.md
+```
+</step>
+
+<step name="display">
+Display summary:
+```
+Code Review — Phase {N}
+
+  Files reviewed: {count}
+  Critical: {count}
+  Major:    {count}
+  Minor:    {count}
+  Suggestions: {count}
+
+  Full report: {phase_dir}/REVIEW.md
+
+  Next: /gtd-debug (fix critical issues)
+        /gtd-next (continue if clean)
+```
+</step>
+
+</process>
+
+<error_handling>
+- No changes to review → inform user: "No changes found. Nothing to review."
+- Phase not found → review current working tree changes instead
+- Reviewer timeout → produce partial review from completed files
+</error_handling>

package/workflows/forward/complete-milestone.md

@@ -0,0 +1,45 @@
+<purpose>
+Close the current milestone — verify all phases complete, generate summary, archive.
+</purpose>
+
+<process>
+
+<step name="initialize">
+```bash
+INIT=$(node "$GTD_TOOLS_PATH/gtd-tools.cjs" init complete-milestone "$ARGUMENTS")
+```
+Parse: state, roadmap.
+</step>
+
+<step name="verify_all_complete">
+Check ROADMAP.md: are all phases marked complete?
+If not: display which phases remain, ask to proceed anyway or complete them first.
+</step>
+
+<step name="generate_summary">
+Create .planning/milestones/{milestone-name}-SUMMARY.md:
+- Phases completed, tasks executed, tests passed
+- Requirements coverage
+- Timeline and cost metrics
+</step>
+
+<step name="archive">
+Archive current milestone state.
+Update STATE.md: reset forward.current_phase.
+Optionally trigger backward pipeline: /gtd-create-all (generate fresh docs for the completed milestone).
+</step>
+
+<step name="report">
+Display:
+```
+✓ Milestone {name} complete!
+
+  Phases: {count}
+  Requirements: {covered}/{total}
+
+  Next: /gtd-new-milestone (start next milestone)
+        /gtd-create-all (generate documentation)
+```
+</step>
+
+</process>

package/workflows/forward/debug.md

@@ -0,0 +1,78 @@
+<purpose>
+Diagnose and fix issues. Spawns a gtd-debugger agent with error context. Accepts error output, stack trace, or "last command failed" as input. Agent reads code, identifies root cause, applies fix, and verifies.
+</purpose>
+
+<available_agent_types>
+- gtd-debugger — Diagnoses failures, reads code, applies fixes
+</available_agent_types>
+
+<process>
+
+<step name="initialize">
+```bash
+INIT=$(node "$GTD_TOOLS_PATH/gtd-tools.cjs" init debug "$ARGUMENTS")
+```
+Parse: docs_root, config, state, error_context from arguments.
+Accept input as: raw error text, --file path/to/error.log, or --last (re-read last command output).
+</step>
+
+<step name="gather_context">
+Collect debugging context:
+- Error message or stack trace from input
+- Current phase and recent changes (git log --oneline -10)
+- Relevant source files mentioned in the error
+- Test output if available
+
+If --last flag: retrieve the most recent command output from shell history or logs.
+</step>
+
+<step name="spawn_debugger">
+Spawn gtd-debugger agent:
+```
+Diagnose and fix this issue:
+
+Error context:
+{error_output}
+
+Recent changes:
+{git_log}
+
+Relevant files:
+{file_list}
+
+Project docs:
+  PROJECT.md: {path}
+  REQUIREMENTS.md: {path}
+
+Steps:
+1. Identify root cause
+2. Apply minimal fix
+3. Verify fix resolves the error
+4. Commit with message: "fix: {short description}"
+```
+</step>
+
+<step name="report">
+Display:
+```
+Debug complete
+
+  Root cause: {description}
+  Fix applied: {files_changed}
+  Commit: {short_sha}
+  Verification: {pass|fail}
+
+  Next: /gtd-next (continue pipeline)
+        /gtd-debug (if issue persists)
+```
+
+If fix failed after 3 attempts: report unresolved, suggest manual intervention.
+</step>
+
+</process>
+
+<error_handling>
+- No error context provided → prompt user: "Paste the error or use --last"
+- Debugger cannot identify cause → report findings, suggest files to inspect manually
+- Fix introduces new failures → revert fix, report both original and new errors
+</error_handling>

package/workflows/forward/deploy-local.md

@@ -0,0 +1,51 @@
+<purpose>
+Deploy the project locally — detect method, build, start, health check.
+</purpose>
+
+<available_agent_types>
+- gtd-deployer — Local deployment orchestration
+</available_agent_types>
+
+<process>
+
+<step name="initialize">
+```bash
+INIT=$(node "$GTD_TOOLS_PATH/gtd-tools.cjs" init deploy-local "$ARGUMENTS")
+DEPLOY=$(node "$GTD_TOOLS_PATH/gtd-tools.cjs" deploy detect)
+```
+Parse: method, port, config.deploy settings.
+</step>
+
+<step name="pre_deploy">
+Check port availability:
+```bash
+PORT_CHECK=$(node "$GTD_TOOLS_PATH/gtd-tools.cjs" deploy check-port "$PORT")
+```
+If port in use: warn user, offer to use different port or kill existing process.
+</step>
+
+<step name="spawn_deployer">
+Spawn gtd-deployer agent with project context and deployment info.
+Agent handles: dependency install → build → start → health check.
+Produces: DEPLOY-REPORT.md
+</step>
+
+<step name="update_state">
+```bash
+node "$GTD_TOOLS_PATH/gtd-tools.cjs" state update forward.status deployed
+```
+
+Display:
+```
+✓ Deployed locally
+
+  Method: {method}
+  URL: http://localhost:{port}
+  Health: {healthy|unhealthy}
+
+  Next: /gtd-test-phase {N} (run tests)
+        /gtd-verify-work {N} (full verification)
+```
+</step>
+
+</process>

package/workflows/forward/discuss-phase.md

@@ -0,0 +1,89 @@
+<purpose>
+Capture user's implementation preferences and decisions for a specific phase before research and planning. Eliminates gray areas that cause the AI to guess during execution.
+</purpose>
+
+<required_reading>
+@references/questioning.md
+</required_reading>
+
+<process>
+
+<step name="initialize">
+```bash
+INIT=$(node "$GTD_TOOLS_PATH/gtd-tools.cjs" init discuss-phase "$ARGUMENTS")
+```
+Parse: phase_number, docs_root, config, state, roadmap, phase_context.
+
+Load ROADMAP.md → get phase description and requirements.
+Check if {phase}-CONTEXT.md already exists → load prior decisions to avoid re-asking.
+</step>
+
+<step name="scout_codebase">
+If code already exists (brownfield or previous phases completed):
+  Read relevant source files to understand current state.
+  Identify gray areas based on what's already implemented vs what's needed.
+</step>
+
+<step name="identify_gray_areas">
+Analyze phase scope and identify decision points:
+
+| Category | Example Decisions |
+|----------|-------------------|
+| Visual/UI | Layout, density, interactions, empty states |
+| API/CLI | Response format, pagination, error handling |
+| Data | Schema design, relationships, indexing |
+| Organization | File structure, naming conventions |
+| Integration | Third-party services, auth flow |
+| Performance | Caching strategy, pagination limits |
+
+Filter out decisions already made in prior CONTEXT.md files.
+</step>
+
+<step name="ask_questions">
+If NOT --auto mode:
+  Present gray areas grouped by category.
+  For each, offer options with recommendations.
+  Use --batch flag for grouped Q&A.
+
+If --auto mode:
+  Auto-select recommended defaults for all gray areas.
+</step>
+
+<step name="write_context">
+Write decisions to .planning/phases/{phase}/{phase}-CONTEXT.md:
+
+```markdown
+---
+phase: {number}
+timestamp: {ISO 8601}
+mode: {guided|auto}
+---
+
+# Phase {N} Context: {Phase Name}
+
+## Decisions
+| # | Area | Decision | Rationale |
+|---|------|----------|-----------|
+| 1 | ... | ... | ... |
+
+## Preferences
+...
+
+## Open Questions (deferred)
+...
+```
+</step>
+
+<step name="report">
+Display:
+```
+✓ Phase {N} discussion complete
+
+  Decisions captured: {count}
+  Open questions deferred: {count}
+  
+  Next: /gtd-plan-phase {N} (research + create execution plan)
+```
+</step>
+
+</process>

package/workflows/forward/execute-phase.md

@@ -0,0 +1,138 @@
+<purpose>
+Execute all plans in a phase using wave-based parallel execution. Orchestrator stays lean — delegates plan execution to executor subagents. Each executor gets a fresh context window.
+</purpose>
+
+<required_reading>
+@references/agent-contracts.md
+@references/context-budget.md
+@references/gate-prompts.md
+</required_reading>
+
+<available_agent_types>
+- gtd-executor — Executes plan tasks, writes code, commits
+- gtd-verifier — Verifies phase completion against requirements
+- gtd-debugger — Diagnoses and fixes failures
+</available_agent_types>
+
+<process>
+
+<step name="initialize">
+```bash
+INIT=$(node "$GTD_TOOLS_PATH/gtd-tools.cjs" init execute-phase "$ARGUMENTS")
+```
+Parse: phase_number, docs_root, config, state, roadmap, plans, git.
+Also parse optional flags: --wave N (execute specific wave only), --sequential (force sequential).
+
+Verify:
+- Phase exists in ROADMAP.md
+- Plans exist in phases/{phase}/ directory
+- State is "planned" (ready for execution)
+</step>
+
+<step name="discover_plans">
+```bash
+PLANS=$(node "$GTD_TOOLS_PATH/gtd-tools.cjs" phase plans "$PHASE_NUMBER")
+```
+Parse plan list. If no plans → Error: "No plans found. Run /gtd-plan-phase first."
+
+Analyze dependencies between plans (from plan frontmatter or naming).
+Group into execution waves using `groupIntoWaves()`.
+
+Display:
+```
+Phase {N}: {name}
+  Plans: {count}
+  Waves: {wave_count}
+  Wave 1: {plan_names} (parallel)
+  Wave 2: {plan_names} (depends on wave 1)
+  ...
+```
+</step>
+
+<step name="execute_waves">
+For each wave (or single wave if --wave flag):
+
+  **If parallelization enabled AND runtime supports Task spawning:**
+    Spawn one gtd-executor agent per plan in the wave (concurrent).
+    Each executor runs in a worktree (if config.execution.use_worktrees is true).
+
+  **Otherwise (sequential):**
+    Execute plans one at a time in order.
+
+  Each executor receives:
+  ```
+  Execute the plan at: {plan_path}
+  
+  Project context:
+    PROJECT.md: {docs_root}/PROJECT.md
+    REQUIREMENTS.md: {docs_root}/REQUIREMENTS.md
+    CONTEXT.md: {phase_dir}/{phase}-CONTEXT.md
+    RESEARCH.md: {phase_dir}/{phase}-RESEARCH.md
+  
+  Git commit after each task.
+  Write completion to: {phase_dir}/{plan}-SUMMARY.md
+  ```
+
+  Wait for all executors in this wave to complete.
+  Verify each produced a SUMMARY.md.
+</step>
+
+<step name="integration_checkpoint">
+After each wave completes:
+  1. Check all SUMMARY.md files — any failures?
+  2. Run integration test suite (if available)
+  3. If failures: spawn gtd-debugger to investigate
+  4. If debug succeeds: continue to next wave
+  5. If debug fails after 3 attempts: pause and present to user
+</step>
+
+<step name="post_execution_verification">
+After all waves complete:
+  Spawn gtd-verifier agent:
+  ```
+  Verify Phase {N} execution.
+  
+  SUMMARY files: {list of all SUMMARY.md paths}
+  REQUIREMENTS.md: {path}
+  ROADMAP.md: {path}
+  
+  Check: requirements coverage, test results, regression.
+  Write: {phase_dir}/VERIFICATION.md
+  ```
+</step>
+
+<step name="update_state">
+```bash
+node "$GTD_TOOLS_PATH/gtd-tools.cjs" state update forward.status executing
+node "$GTD_TOOLS_PATH/gtd-tools.cjs" state update forward.current_phase "$PHASE_NUMBER"
+```
+
+After verification:
+```bash
+node "$GTD_TOOLS_PATH/gtd-tools.cjs" state update forward.status verified
+```
+
+Display:
+```
+✓ Phase {N} execution complete
+
+  Plans executed: {count}
+  Tasks completed: {total}
+  Commits: {commit_count}
+  Verification: {pass_count}/{total_reqs} requirements verified
+
+  Next: /gtd-deploy-local (test locally)
+        /gtd-ship (create PR)
+        /gtd-next (auto-advance)
+```
+</step>
+
+</process>
+
+<error_handling>
+- Executor timeout → check filesystem for partial SUMMARY.md, treat completed tasks as done
+- Executor crash → retry plan once, then mark as failed
+- Test failure during execution → executor's internal debug loop (3 attempts)
+- Integration test failure → spawn debugger agent
+- All plans failed → abort, preserve state, report to user
+</error_handling>