@karthikrajkumar.kannan/get-things-done 1.0.0

package/workflows/sync/audit.md

@@ -0,0 +1,110 @@
+<purpose>
+Run a full alignment audit across specifications, code, and documentation. Produces a comprehensive coverage matrix and gap analysis showing what is implemented, documented, and tested — and what is missing.
+</purpose>
+
+<available_agent_types>
+- gtd-alignment-auditor — Full alignment audit with coverage matrix
+</available_agent_types>
+
+<process>
+
+<step name="initialize" priority="first">
+Load context:
+
+```bash
+INIT=$(node "$GTD_TOOLS_PATH/gtd-tools.cjs" init audit "$ARGUMENTS")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Parse JSON for: `project_root`, `docs_root`, `config`, `state`, `git`, `args`.
+
+Parse `--compliance` flag: `soc2` | `iso27001` | none (default: none).
+Parse `--force` flag to re-run even if recent audit exists.
+</step>
+
+<step name="check_existing_audit">
+If `.planning/AUDIT-REPORT.md` exists AND is less than 24 hours old AND `--force` is not set:
+  Display:
+  ```
+  Recent audit report found (generated: {timestamp}).
+  Use --force to re-run.
+  ```
+  Present the existing report summary and EXIT.
+</step>
+
+<step name="spawn_alignment_auditor">
+Spawn `gtd-alignment-auditor` agent with prompt:
+
+```
+Run a full alignment audit on the project at: {project_root}
+
+Compliance checks: {args.compliance or "none"}
+
+Docs root: {docs_root}
+Git context:
+  commit: {git.commit}
+  branch: {git.branch}
+
+Follow the process defined in your agent definition.
+Write the audit report to: {docs_root}/AUDIT-REPORT.md
+```
+
+Wait for agent completion. Verify AUDIT-REPORT.md exists.
+</step>
+
+<step name="update_state">
+Read the generated AUDIT-REPORT.md frontmatter to get coverage metrics.
+
+```bash
+node "$GTD_TOOLS_PATH/gtd-tools.cjs" state update sync.last_audit "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+node "$GTD_TOOLS_PATH/gtd-tools.cjs" state update sync.spec_coverage "{spec_coverage}"
+node "$GTD_TOOLS_PATH/gtd-tools.cjs" state update sync.doc_coverage "{doc_coverage}"
+node "$GTD_TOOLS_PATH/gtd-tools.cjs" state update sync.test_coverage "{test_coverage}"
+```
+</step>
+
+<step name="display_report">
+Present the coverage matrix and gap summary:
+
+```
+Alignment Audit Complete
+
+  Coverage:
+    Spec coverage:  {spec}%  {status_emoji}
+    Doc coverage:   {doc}%   {status_emoji}
+    Test coverage:  {test}%  {status_emoji}
+    Full coverage:  {full}%  {status_emoji}
+    Orphan code:    {orphan}%
+
+  Gaps found:
+    Undocumented code:    {count}
+    Unimplemented specs:  {count}
+    Untested features:    {count}
+    Orphan documentation: {count}
+
+  Full report: {docs_root}/AUDIT-REPORT.md
+```
+
+If compliance checks were run:
+```
+  Compliance ({type}):
+    Pass:   {pass_count}
+    Fail:   {fail_count}
+    Partial: {partial_count}
+```
+
+Suggest next steps based on gaps:
+- If spec coverage < 80%: "Run /gtd-reconcile --strategy spec-wins to plan implementation"
+- If doc coverage < 80%: "Run /gtd-create-all to regenerate documentation"
+- If test coverage < 60%: "Consider adding tests for untested features"
+</step>
+
+</process>
+
+<error_handling>
+- If alignment auditor agent fails: report error, suggest checking if codebase has been scanned
+- If AUDIT-REPORT.md is not produced: report failure, check agent output for errors
+- If no specs exist: run audit with code-and-docs only, note missing specs in report
+- If no docs exist: run audit with code-and-specs only, note missing docs in report
+- If compliance flag is unrecognized: warn and proceed without compliance checks
+</error_handling>

package/workflows/sync/detect-drift.md

@@ -0,0 +1,122 @@
+<purpose>
+Detect drift between specifications, documentation, and actual code. This is the entry point of the sync pipeline — it identifies where things have gone out of alignment so that reconciliation can bring them back.
+</purpose>
+
+<available_agent_types>
+- gtd-drift-detector — Compares specs and docs against actual code to detect drift
+</available_agent_types>
+
+<process>
+
+<step name="initialize" priority="first">
+Load context:
+
+```bash
+INIT=$(node "$GTD_TOOLS_PATH/gtd-tools.cjs" init detect-drift "$ARGUMENTS")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Parse JSON for: `project_root`, `docs_root`, `config`, `state`, `git`, `args`.
+
+Check for `--since` flag (commit hash to compare from) and `--scope` flag (specs|docs|both, default: both).
+</step>
+
+<step name="check_if_needed">
+Check if drift detection is needed:
+
+```bash
+DRIFT_CHECK=$(node "$GTD_TOOLS_PATH/drift-engine.cjs" check "$ARGUMENTS")
+if [[ "$DRIFT_CHECK" == @file:* ]]; then DRIFT_CHECK=$(cat "${DRIFT_CHECK#@file:}"); fi
+```
+
+Parse result for `needs_check` boolean and `reason`.
+
+If `needs_check` is false AND `--force` is not set:
+  Display:
+  ```
+  No drift detection needed: {reason}
+  Use --force to run anyway.
+  ```
+  EXIT — no work needed.
+</step>
+
+<step name="build_drift_context">
+Build context for the drift detector:
+
+```bash
+DRIFT_CTX=$(node "$GTD_TOOLS_PATH/drift-engine.cjs" context "$ARGUMENTS")
+if [[ "$DRIFT_CTX" == @file:* ]]; then DRIFT_CTX=$(cat "${DRIFT_CTX#@file:}"); fi
+```
+
+Parse result for: `specs_available`, `docs_available`, `last_sync_commit`, `files_changed_since`.
+
+If no specs and no docs are available:
+  Display:
+  ```
+  No specifications or documents found to compare against code.
+  Run /gtd-scan and /gtd-create-* first, or create REQUIREMENTS.md.
+  ```
+  EXIT.
+</step>
+
+<step name="spawn_drift_detector">
+Spawn `gtd-drift-detector` agent with prompt:
+
+```
+Detect drift in the project at: {project_root}
+
+Scope: {args.scope or "both"}
+Since commit: {args.since or "all"}
+
+Available specs: {specs_available}
+Available docs: {docs_available}
+Last sync commit: {last_sync_commit}
+Files changed since last sync: {files_changed_since}
+
+Docs root: {docs_root}
+
+Follow the process defined in your agent definition.
+Write the drift report to: {docs_root}/DRIFT-REPORT.md
+```
+
+Wait for agent completion. Verify DRIFT-REPORT.md exists.
+</step>
+
+<step name="update_state">
+Read the generated DRIFT-REPORT.md frontmatter to get counts.
+
+If total_items > 0 (any drift found):
+```bash
+node "$GTD_TOOLS_PATH/gtd-tools.cjs" state update sync.status drifted
+node "$GTD_TOOLS_PATH/gtd-tools.cjs" state update sync.last_drift_check "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+node "$GTD_TOOLS_PATH/gtd-tools.cjs" state update sync.drift_items "{total_items}"
+```
+
+If total_items == 0 (no drift):
+```bash
+node "$GTD_TOOLS_PATH/gtd-tools.cjs" state update sync.status synced
+node "$GTD_TOOLS_PATH/gtd-tools.cjs" state update sync.last_drift_check "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+node "$GTD_TOOLS_PATH/gtd-tools.cjs" state update sync.drift_items "0"
+```
+</step>
+
+<step name="report">
+Display summary:
+
+```
+Found {total_items} drift items: {critical} critical, {major} major, {minor} minor, {info} info
+
+Status: {DRIFTED or SYNCED}
+
+Run /gtd-reconcile to plan fixes, or /gtd-audit for full coverage analysis.
+```
+</step>
+
+</process>
+
+<error_handling>
+- If drift detector agent fails: report error, suggest checking if specs/docs exist
+- If DRIFT-REPORT.md is not produced: report failure, check agent output for errors
+- If specs are missing but docs exist: run with docs-only scope
+- If docs are missing but specs exist: run with specs-only scope
+</error_handling>

package/workflows/sync/reconcile.md

@@ -0,0 +1,113 @@
+<purpose>
+Plan how to reconcile drift between specifications, documentation, and code. Takes the drift report as input and produces an actionable reconciliation plan with per-item actions and effort estimates.
+</purpose>
+
+<available_agent_types>
+- gtd-reconciliation-planner — Plans how to reconcile drift between specs and code
+</available_agent_types>
+
+<process>
+
+<step name="initialize" priority="first">
+Load context:
+
+```bash
+INIT=$(node "$GTD_TOOLS_PATH/gtd-tools.cjs" init reconcile "$ARGUMENTS")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Parse JSON for: `project_root`, `docs_root`, `config`, `state`, `args`.
+
+Parse `--strategy` flag: `code-wins` | `spec-wins` | `interactive` (default: `interactive`).
+</step>
+
+<step name="check_drift_report">
+Check if a drift report exists:
+
+```bash
+test -f "$DOCS_ROOT/DRIFT-REPORT.md" && echo "EXISTS" || echo "MISSING"
+```
+
+If MISSING:
+  Display:
+  ```
+  No drift report found. Run /gtd-drift first to detect drift.
+  ```
+  EXIT — cannot reconcile without drift data.
+
+If EXISTS, read the frontmatter to confirm there are drift items:
+- If `total_items` is 0:
+  Display:
+  ```
+  Drift report shows 0 items — everything is in sync.
+  No reconciliation needed.
+  ```
+  EXIT.
+</step>
+
+<step name="spawn_reconciliation_planner">
+Spawn `gtd-reconciliation-planner` agent with prompt:
+
+```
+Plan reconciliation for the project at: {project_root}
+
+Strategy: {args.strategy or "interactive"}
+
+Drift report: {docs_root}/DRIFT-REPORT.md
+Specs root: {project_root}
+Docs root: {docs_root}
+
+Follow the process defined in your agent definition.
+Write the reconciliation plan to: {docs_root}/RECONCILIATION-PLAN.md
+```
+
+Wait for agent completion. Verify RECONCILIATION-PLAN.md exists.
+</step>
+
+<step name="present_plan">
+Read the generated RECONCILIATION-PLAN.md and present a summary to the user:
+
+```
+Reconciliation Plan ({strategy} strategy)
+
+  Total actions: {total_actions}
+  Needs user decision: {needs_decision}
+  Auto-resolvable: {auto}
+
+  Effort breakdown:
+    Trivial: {trivial}
+    Small: {small}
+    Medium: {medium}
+    Large: {large}
+
+  Estimated total effort: {hours} hours
+```
+
+If strategy is `interactive`, list the items that need a decision:
+```
+Items requiring your decision:
+  1. [CRITICAL] {description} — recommend: {direction}
+  2. [MAJOR] {description} — recommend: {direction}
+  ...
+
+Review the full plan at: {docs_root}/RECONCILIATION-PLAN.md
+Run /gtd-sync to execute the plan.
+```
+</step>
+
+<step name="update_state">
+```bash
+node "$GTD_TOOLS_PATH/gtd-tools.cjs" state update sync.status reconciling
+node "$GTD_TOOLS_PATH/gtd-tools.cjs" state update sync.reconciliation_strategy "{strategy}"
+node "$GTD_TOOLS_PATH/gtd-tools.cjs" state update sync.last_reconciliation "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+```
+</step>
+
+</process>
+
+<error_handling>
+- If reconciliation planner agent fails: report error, suggest checking drift report format
+- If RECONCILIATION-PLAN.md is not produced: report failure, check agent output
+- If drift report is malformed: report error, suggest re-running /gtd-drift
+- If strategy flag is invalid: default to interactive with a warning
+</error_handling>

package/workflows/sync/sync.md

@@ -0,0 +1,150 @@
+<purpose>
+The auto-sync workflow: detect drift, reconcile, and apply changes to bring specs, docs, and code back into alignment. This is the all-in-one command for keeping a project synchronized.
+</purpose>
+
+<available_agent_types>
+- gtd-drift-detector — Compares specs and docs against actual code to detect drift
+- gtd-reconciliation-planner — Plans how to reconcile drift between specs and code
+</available_agent_types>
+
+<process>
+
+<step name="initialize" priority="first">
+Load context:
+
+```bash
+INIT=$(node "$GTD_TOOLS_PATH/gtd-tools.cjs" init sync "$ARGUMENTS")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Parse JSON for: `project_root`, `docs_root`, `config`, `state`, `git`, `args`.
+
+Parse flags:
+- `--auto` — Fully automatic mode: use code-wins strategy, auto-approve all actions
+- `--direction` — `forward` (specs to code) | `backward` (code to specs) | `both` (default: both)
+- `--force` — Force re-detection even if recent drift report exists
+</step>
+
+<step name="detect_drift">
+Run drift detection (equivalent to /gtd-drift):
+
+Check if a recent DRIFT-REPORT.md exists AND `--force` is not set:
+- If exists and less than 1 hour old: reuse it
+- Otherwise: run drift detection
+
+```bash
+DRIFT_CTX=$(node "$GTD_TOOLS_PATH/drift-engine.cjs" context "$ARGUMENTS")
+if [[ "$DRIFT_CTX" == @file:* ]]; then DRIFT_CTX=$(cat "${DRIFT_CTX#@file:}"); fi
+```
+
+Spawn `gtd-drift-detector` agent with the project context.
+Wait for DRIFT-REPORT.md.
+
+If no drift found:
+  Display:
+  ```
+  Everything is in sync. No changes needed.
+  ```
+  Update state to "synced" and EXIT.
+</step>
+
+<step name="determine_strategy">
+Determine reconciliation strategy based on flags:
+
+- If `--auto` is set: strategy = `code-wins`
+- If `--direction forward`: strategy = `spec-wins` (specs drive code changes)
+- If `--direction backward`: strategy = `code-wins` (code drives spec/doc updates)
+- If `--direction both`: strategy = `interactive` (unless `--auto`, then `code-wins`)
+- Default (no flags): strategy = `interactive`
+</step>
+
+<step name="reconcile">
+Spawn `gtd-reconciliation-planner` agent with the determined strategy.
+
+Wait for RECONCILIATION-PLAN.md.
+
+If strategy is `interactive` (and `--auto` is NOT set):
+  Present the plan to the user and wait for approval:
+  ```
+  Reconciliation plan ready with {total_actions} actions.
+  Review: {docs_root}/RECONCILIATION-PLAN.md
+
+  Approve and apply? (yes/no)
+  ```
+  If user declines: EXIT with state "reconciling".
+</step>
+
+<step name="apply_changes">
+Apply the reconciliation plan:
+
+### For code-wins actions (update specs/docs):
+- Read each affected document
+- Apply the planned changes (update sections, fix paths, correct versions)
+- Write updated documents back
+
+### For spec-wins actions (update code):
+- Create task items in `.planning/SYNC-TASKS.md` for code changes
+- Each task includes: description, affected files, acceptance criteria
+- Display tasks for developer action
+
+### For document regeneration:
+- If a document is too stale (> 50% claims incorrect), trigger full regeneration
+- Use the backward pipeline: /gtd-create-{type} --force
+
+```bash
+node "$GTD_TOOLS_PATH/gtd-tools.cjs" state update sync.status applying
+```
+</step>
+
+<step name="verify_sync">
+After applying changes, run a quick verification:
+
+- Re-check critical drift items to confirm they're resolved
+- Count remaining drift items
+
+If all resolved:
+```bash
+node "$GTD_TOOLS_PATH/gtd-tools.cjs" state update sync.status synced
+node "$GTD_TOOLS_PATH/gtd-tools.cjs" state update sync.last_sync "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+node "$GTD_TOOLS_PATH/gtd-tools.cjs" state update sync.last_sync_commit "$(git rev-parse --short HEAD)"
+```
+
+If some remain:
+```bash
+node "$GTD_TOOLS_PATH/gtd-tools.cjs" state update sync.status partially_synced
+```
+</step>
+
+<step name="report">
+Display final summary:
+
+```
+Sync complete.
+
+  Actions applied: {applied} / {total}
+  Docs updated: {docs_updated}
+  Tasks created: {tasks_created}
+  Remaining drift: {remaining}
+
+  Status: {SYNCED / PARTIALLY_SYNCED}
+```
+
+If tasks were created for code changes:
+```
+  Code tasks pending developer action:
+    1. {task description} — {affected files}
+    2. ...
+
+  See: {docs_root}/SYNC-TASKS.md
+```
+</step>
+
+</process>
+
+<error_handling>
+- If drift detection fails: report error, suggest running /gtd-drift independently
+- If reconciliation fails: report error, suggest running /gtd-reconcile independently
+- If a document update fails: skip that item, continue with others, report at end
+- If --auto mode encounters a CRITICAL spec-wins item: pause and warn user (safety override)
+- If git is dirty (uncommitted changes): warn user before applying changes
+</error_handling>