@undeemed/get-shit-done-codex 1.20.3 → 1.20.8

package/get-shit-done/workflows/progress.md

@@ -9,23 +9,13 @@ Read all files referenced by the invoking prompt's execution_context before star
 <process>
 
 <step name="init_context">
-**Load progress context (with file contents to avoid redundant reads):**
+**Load progress context (paths only):**
 
 ```bash
-INIT_RAW=$(node ~/.codex/get-shit-done/bin/gsd-tools.cjs init progress --include state,roadmap,project,config)
-# Large payloads are written to a tmpfile — output starts with @file:/path
-if [[ "$INIT_RAW" == @file:* ]]; then
-  INIT_FILE="${INIT_RAW#@file:}"
-  INIT=$(cat "$INIT_FILE")
-  rm -f "$INIT_FILE"
-else
-  INIT="$INIT_RAW"
-fi
+INIT=$(node ~/.codex/get-shit-done/bin/gsd-tools.cjs init progress)
 ```
 
-Extract from init JSON: `project_exists`, `roadmap_exists`, `state_exists`, `phases`, `current_phase`, `next_phase`, `milestone_version`, `completed_count`, `phase_count`, `paused_at`.
-
-**File contents (from --include):** `state_content`, `roadmap_content`, `project_content`, `config_content`. These are null if files don't exist.
+Extract from init JSON: `project_exists`, `roadmap_exists`, `state_exists`, `phases`, `current_phase`, `next_phase`, `milestone_version`, `completed_count`, `phase_count`, `paused_at`, `state_path`, `roadmap_path`, `project_path`, `config_path`.
 
 If `project_exists` is false (no `.planning/` directory):
 
@@ -47,15 +37,13 @@ If missing both ROADMAP.md and PROJECT.md: suggest `/gsd:new-project`.
 </step>
 
 <step name="load">
-**Use project context from INIT:**
+**Use structured extraction from gsd-tools:**
 
-All file contents are already loaded via `--include` in init_context step:
-- `state_content` — living memory (position, decisions, issues)
-- `roadmap_content` — phase structure and objectives
-- `project_content` — current state (What This Is, Core Value, Requirements)
-- `config_content` — settings (model_profile, workflow toggles)
+Instead of reading full files, use targeted tools to get only the data needed for the report:
+- `ROADMAP=$(node ~/.codex/get-shit-done/bin/gsd-tools.cjs roadmap analyze)`
+- `STATE=$(node ~/.codex/get-shit-done/bin/gsd-tools.cjs state-snapshot)`
 
-No additional file reads needed.
+This minimizes orchestrator context usage.
 </step>
 
 <step name="analyze_roadmap">
@@ -89,9 +77,8 @@ Use this instead of manually reading/parsing ROADMAP.md.
 <step name="position">
 **Parse current position from init context and roadmap analysis:**
 
-- Use `current_phase` and `next_phase` from roadmap analyze
-- Use phase-level `has_context` and `has_research` flags from analyze
-- Note `paused_at` if work was paused (from init context)
+- Use `current_phase` and `next_phase` from `$ROADMAP`
+- Note `paused_at` if work was paused (from `$STATE`)
 - Count pending todos: use `init todos` or `list-todos`
 - Check for active debug sessions: `ls .planning/debug/*.md 2>/dev/null | grep -v resolved | wc -l`
   </step>
@@ -122,11 +109,12 @@ Plan [M] of [phase-total]: [status]
 CONTEXT: [✓ if has_context | - if not]
 
 ## Key Decisions Made
-- [decision 1 from STATE.md]
-- [decision 2]
+- [extract from $STATE.decisions[]]
+- [e.g. jq -r '.decisions[].decision' from state-snapshot]
 
 ## Blockers/Concerns
-- [any blockers or concerns from STATE.md]
+- [extract from $STATE.blockers[]]
+- [e.g. jq -r '.blockers[].text' from state-snapshot]
 
 ## Pending Todos
 - [count] pending — /gsd:check-todos to review

package/get-shit-done/workflows/quick.md

@@ -96,8 +96,12 @@ Task(
 **Directory:** ${QUICK_DIR}
 **Description:** ${DESCRIPTION}
 
-**Project State:**
-@.planning/STATE.md
+<files_to_read>
+- .planning/STATE.md (Project State)
+- ./CODEX.md (if exists — follow project-specific guidelines)
+</files_to_read>
+
+**Project skills:** Check .agents/skills/ directory (if exists) — read SKILL.md files, plans should account for project skill rules
 
 </planning_context>
 
@@ -143,10 +147,6 @@ Display banner:
 ◆ Spawning plan checker...
 ```
 
-```bash
-PLAN_CONTENT=$(cat "${QUICK_DIR}/${next_num}-PLAN.md" 2>/dev/null)
-```
-
 Checker prompt:
 
 ```markdown
@@ -154,7 +154,9 @@ Checker prompt:
 **Mode:** quick-full
 **Task Description:** ${DESCRIPTION}
 
-**Plan to verify:** ${PLAN_CONTENT}
+<files_to_read>
+- ${QUICK_DIR}/${next_num}-PLAN.md (Plan to verify)
+</files_to_read>
 
 **Scope:** This is a quick task, not a full phase. Skip checks that require a ROADMAP phase goal.
 </verification_context>
@@ -197,17 +199,16 @@ Track `iteration_count` (starts at 1 after initial plan + check).
 
 Display: `Sending back to planner for revision... (iteration ${N}/2)`
 
-```bash
-PLAN_CONTENT=$(cat "${QUICK_DIR}/${next_num}-PLAN.md" 2>/dev/null)
-```
-
 Revision prompt:
 
 ```markdown
 <revision_context>
 **Mode:** quick-full (revision)
 
-**Existing plan:** ${PLAN_CONTENT}
+<files_to_read>
+- ${QUICK_DIR}/${next_num}-PLAN.md (Existing plan)
+</files_to_read>
+
 **Checker issues:** ${structured_issues_from_checker}
 
 </revision_context>
@@ -247,8 +248,12 @@ Task(
   prompt="
 Execute quick task ${next_num}.
 
-Plan: @${QUICK_DIR}/${next_num}-PLAN.md
-Project state: @.planning/STATE.md
+<files_to_read>
+- ${QUICK_DIR}/${next_num}-PLAN.md (Plan)
+- .planning/STATE.md (Project state)
+- ./CODEX.md (Project instructions, if exists)
+- .agents/skills/ (Project skills, if exists — list skills, read SKILL.md for each, follow relevant rules during implementation)
+</files_to_read>
 
 <constraints>
 - Execute all tasks in the plan
@@ -294,7 +299,11 @@ Task(
   prompt="Verify quick task goal achievement.
 Task directory: ${QUICK_DIR}
 Task goal: ${DESCRIPTION}
-Plan: @${QUICK_DIR}/${next_num}-PLAN.md
+
+<files_to_read>
+- ${QUICK_DIR}/${next_num}-PLAN.md (Plan)
+</files_to_read>
+
 Check must_haves against actual codebase. Create VERIFICATION.md at ${QUICK_DIR}/${next_num}-VERIFICATION.md.",
   subagent_type="gsd-verifier",
   model="{verifier_model}",

package/get-shit-done/workflows/research-phase.md

@@ -34,12 +34,8 @@ If exists: Offer update/view/skip options.
 ## Step 3: Gather Phase Context
 
 ```bash
-# Phase section from roadmap (already loaded in PHASE_INFO)
-echo "$PHASE_INFO" | jq -r '.section'
-cat .planning/REQUIREMENTS.md 2>/dev/null
-cat .planning/phases/${PHASE}-*/*-CONTEXT.md 2>/dev/null
-# Decisions from state-snapshot (structured JSON)
-node ~/.codex/get-shit-done/bin/gsd-tools.cjs state-snapshot | jq '.decisions'
+INIT=$(node ~/.codex/get-shit-done/bin/gsd-tools.cjs init phase-op "${PHASE}")
+# Extract: phase_dir, padded_phase, phase_number, state_path, requirements_path, context_path
 ```
 
 ## Step 4: Spawn Researcher
@@ -50,12 +46,15 @@ Task(
 Research implementation approach for Phase {phase}: {name}
 </objective>
 
-<context>
+<files_to_read>
+- {context_path} (USER DECISIONS from /gsd:discuss-phase)
+- {requirements_path} (Project requirements)
+- {state_path} (Project decisions and history)
+</files_to_read>
+
+<additional_context>
 Phase description: {description}
-Requirements: {requirements}
-Prior decisions: {decisions}
-Phase context: {context_md}
-</context>
+</additional_context>
 
 <output>
 Write to: .planning/phases/${PHASE}-{slug}/${PHASE}-RESEARCH.md

package/get-shit-done/workflows/settings.md

@@ -28,6 +28,7 @@ Parse current values (default to `true` if not present):
 - `workflow.research` — spawn researcher during plan-phase
 - `workflow.plan_check` — spawn plan checker during plan-phase
 - `workflow.verifier` — spawn verifier during execute-phase
+- `workflow.nyquist_validation` — validation architecture research during plan-phase
 - `model_profile` — which model each agent uses (default: `balanced`)
 - `git.branching_strategy` — branching approach (default: `"none"`)
 </step>
@@ -83,6 +84,15 @@ AskUserQuestion([
       { label: "Yes", description: "Chain stages via Task() subagents (same isolation)" }
     ]
   },
+  {
+    question: "Enable Nyquist Validation? (researches test coverage during planning)",
+    header: "Nyquist",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "Research automated test coverage during plan-phase. Adds validation requirements to plans. Blocks approval if tasks lack automated verify." },
+      { label: "No", description: "Skip validation research. Good for rapid prototyping or no-test phases." }
+    ]
+  },
   {
     question: "Git branching strategy?",
     header: "Branching",
@@ -108,7 +118,8 @@ Merge new settings into existing config.json:
     "research": true/false,
     "plan_check": true/false,
     "verifier": true/false,
-    "auto_advance": true/false
+    "auto_advance": true/false,
+    "nyquist_validation": true/false
   },
   "git": {
     "branching_strategy": "none" | "phase" | "milestone"
@@ -155,7 +166,8 @@ Write `~/.gsd/defaults.json` with:
     "research": <current>,
     "plan_check": <current>,
     "verifier": <current>,
-    "auto_advance": <current>
+    "auto_advance": <current>,
+    "nyquist_validation": <current>
   }
 }
 ```
@@ -176,6 +188,7 @@ Display:
 | Plan Checker         | {On/Off} |
 | Execution Verifier   | {On/Off} |
 | Auto-Advance         | {On/Off} |
+| Nyquist Validation   | {On/Off} |
 | Git Branching        | {None/Per Phase/Per Milestone} |
 | Saved as Defaults    | {Yes/No} |
 
@@ -193,7 +206,7 @@ Quick commands:
 
 <success_criteria>
 - [ ] Current config read
-- [ ] User presented with 6 settings (profile + 4 workflow toggles + git branching)
+- [ ] User presented with 7 settings (profile + 5 workflow toggles + git branching)
 - [ ] Config updated with model_profile, workflow, and git sections
 - [ ] User offered to save as global defaults (~/.gsd/defaults.json)
 - [ ] Changes confirmed to user

package/get-shit-done/workflows/transition.md

@@ -451,6 +451,11 @@ Exit skill and invoke SlashCommand("/gsd:discuss-phase [X+1] --auto")
 
 **Route B: Milestone complete (all phases done)**
 
+**Clear auto-advance** — milestone boundary is the natural stopping point:
+```bash
+node ~/.codex/get-shit-done/bin/gsd-tools.cjs config-set workflow.auto_advance false
+```
+
 <if mode="yolo">
 
 ```

package/get-shit-done/workflows/verify-work.md

@@ -365,14 +365,11 @@ Task(
 **Phase:** {phase_number}
 **Mode:** gap_closure
 
-**UAT with diagnoses:**
-@.planning/phases/{phase_dir}/{phase_num}-UAT.md
-
-**Project State:**
-@.planning/STATE.md
-
-**Roadmap:**
-@.planning/ROADMAP.md
+<files_to_read>
+- {phase_dir}/{phase_num}-UAT.md (UAT with diagnoses)
+- .planning/STATE.md (Project State)
+- .planning/ROADMAP.md (Roadmap)
+</files_to_read>
 
 </planning_context>
 
@@ -416,8 +413,9 @@ Task(
 **Phase:** {phase_number}
 **Phase Goal:** Close diagnosed gaps from UAT
 
-**Plans to verify:**
-@.planning/phases/{phase_dir}/*-PLAN.md
+<files_to_read>
+- {phase_dir}/*-PLAN.md (Plans to verify)
+</files_to_read>
 
 </verification_context>
 
@@ -455,8 +453,9 @@ Task(
 **Phase:** {phase_number}
 **Mode:** revision
 
-**Existing plans:**
-@.planning/phases/{phase_dir}/*-PLAN.md
+<files_to_read>
+- {phase_dir}/*-PLAN.md (Existing plans)
+</files_to_read>
 
 **Checker issues:**
 {structured_issues_from_checker}

package/hooks/dist/gsd-context-monitor.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+// Context Monitor - PostToolUse hook
+// Reads context metrics from the statusline bridge file and injects
+// warnings when context usage is high. This makes the AGENT aware of
+// context limits (the statusline only shows the user).
+//
+// How it works:
+// 1. The statusline hook writes metrics to /tmp/codex-ctx-{session_id}.json
+// 2. This hook reads those metrics after each tool use
+// 3. When remaining context drops below thresholds, it injects a warning
+//    as additionalContext, which the agent sees in its conversation
+//
+// Thresholds:
+//   WARNING  (remaining <= 35%): Agent should wrap up current task
+//   CRITICAL (remaining <= 25%): Agent should stop immediately and save state
+//
+// Debounce: 5 tool uses between warnings to avoid spam
+// Severity escalation bypasses debounce (WARNING -> CRITICAL fires immediately)
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const WARNING_THRESHOLD = 35;  // remaining_percentage <= 35%
+const CRITICAL_THRESHOLD = 25; // remaining_percentage <= 25%
+const STALE_SECONDS = 60;      // ignore metrics older than 60s
+const DEBOUNCE_CALLS = 5;      // min tool uses between warnings
+
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const sessionId = data.session_id;
+
+    if (!sessionId) {
+      process.exit(0);
+    }
+
+    const tmpDir = os.tmpdir();
+    const metricsPath = path.join(tmpDir, `codex-ctx-${sessionId}.json`);
+
+    // If no metrics file, this is a subagent or fresh session -- exit silently
+    if (!fs.existsSync(metricsPath)) {
+      process.exit(0);
+    }
+
+    const metrics = JSON.parse(fs.readFileSync(metricsPath, 'utf8'));
+    const now = Math.floor(Date.now() / 1000);
+
+    // Ignore stale metrics
+    if (metrics.timestamp && (now - metrics.timestamp) > STALE_SECONDS) {
+      process.exit(0);
+    }
+
+    const remaining = metrics.remaining_percentage;
+    const usedPct = metrics.used_pct;
+
+    // No warning needed
+    if (remaining > WARNING_THRESHOLD) {
+      process.exit(0);
+    }
+
+    // Debounce: check if we warned recently
+    const warnPath = path.join(tmpDir, `codex-ctx-${sessionId}-warned.json`);
+    let warnData = { callsSinceWarn: 0, lastLevel: null };
+    let firstWarn = true;
+
+    if (fs.existsSync(warnPath)) {
+      try {
+        warnData = JSON.parse(fs.readFileSync(warnPath, 'utf8'));
+        firstWarn = false;
+      } catch (e) {
+        // Corrupted file, reset
+      }
+    }
+
+    warnData.callsSinceWarn = (warnData.callsSinceWarn || 0) + 1;
+
+    const isCritical = remaining <= CRITICAL_THRESHOLD;
+    const currentLevel = isCritical ? 'critical' : 'warning';
+
+    // Emit immediately on first warning, then debounce subsequent ones
+    // Severity escalation (WARNING -> CRITICAL) bypasses debounce
+    const severityEscalated = currentLevel === 'critical' && warnData.lastLevel === 'warning';
+    if (!firstWarn && warnData.callsSinceWarn < DEBOUNCE_CALLS && !severityEscalated) {
+      // Update counter and exit without warning
+      fs.writeFileSync(warnPath, JSON.stringify(warnData));
+      process.exit(0);
+    }
+
+    // Reset debounce counter
+    warnData.callsSinceWarn = 0;
+    warnData.lastLevel = currentLevel;
+    fs.writeFileSync(warnPath, JSON.stringify(warnData));
+
+    // Build warning message
+    let message;
+    if (isCritical) {
+      message = `CONTEXT MONITOR CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+        'STOP new work immediately. Save state NOW and inform the user that context is nearly exhausted. ' +
+        'If using GSD, run /gsd:pause-work to save execution state.';
+    } else {
+      message = `CONTEXT MONITOR WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+        'Begin wrapping up current task. Do not start new complex work. ' +
+        'If using GSD, consider /gsd:pause-work to save state.';
+    }
+
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: "PostToolUse",
+        additionalContext: message
+      }
+    };
+
+    process.stdout.write(JSON.stringify(output));
+  } catch (e) {
+    // Silent fail -- never block tool execution
+    process.exit(0);
+  }
+});

package/hooks/dist/gsd-statusline.js

@@ -27,6 +27,23 @@ process.stdin.on('end', () => {
       // Scale: 80% real usage = 100% displayed
       const used = Math.min(100, Math.round((rawUsed / 80) * 100));
 
+      // Write context metrics to bridge file for the context-monitor PostToolUse hook.
+      // The monitor reads this file to inject agent-facing warnings when context is low.
+      if (session) {
+        try {
+          const bridgePath = path.join(os.tmpdir(), `codex-ctx-${session}.json`);
+          const bridgeData = JSON.stringify({
+            session_id: session,
+            remaining_percentage: remaining,
+            used_pct: used,
+            timestamp: Math.floor(Date.now() / 1000)
+          });
+          fs.writeFileSync(bridgePath, bridgeData);
+        } catch (e) {
+          // Silent fail -- bridge is best-effort, don't break statusline
+        }
+      }
+
       // Build progress bar (10 segments)
       const filled = Math.floor(used / 10);
       const bar = '█'.repeat(filled) + '░'.repeat(10 - filled);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@undeemed/get-shit-done-codex",
-  "version": "1.20.3",
+  "version": "1.20.8",
   "description": "A meta-prompting, context engineering and spec-driven development system for OpenAI Codex (CLI and Desktop). Fork of get-shit-done by TÂCHES, adapted for Codex by undeemed.",
   "bin": {
     "get-shit-done-codex": "bin/install.js"
@@ -18,13 +18,29 @@
     "AGENTS.md"
   ],
   "keywords": [
+    "get-shit-done",
+    "gsd",
     "openai",
     "codex",
     "codex-cli",
+    "codex-desktop",
+    "codex-app",
+    "openai-codex",
     "ai",
+    "ai-coding",
+    "ai-agents",
     "meta-prompting",
     "context-engineering",
+    "context-rot",
     "spec-driven-development",
+    "prompt-engineering",
+    "multi-agent",
+    "subagent",
+    "ai-workflow",
+    "developer-tools",
+    "dev-tools",
+    "productivity",
+    "code-generation",
     "agents"
   ],
   "author": "undeemed <jerry.x0930@gmail.com>",
@@ -50,6 +66,6 @@
   "scripts": {
     "build:hooks": "node scripts/build-hooks.js",
     "prepublishOnly": "npm run build:hooks",
-    "test": "node --test get-shit-done/bin/gsd-tools.test.cjs"
+    "test": "node --test tests/*.test.cjs"
   }
 }

package/scripts/build-hooks.js

@@ -12,6 +12,7 @@ const DIST_DIR = path.join(HOOKS_DIR, 'dist');
 // Hooks to copy (pure Node.js, no bundling needed)
 const HOOKS_TO_COPY = [
   'gsd-check-update.js',
+  'gsd-context-monitor.js',
   'gsd-statusline.js'
 ];