@undeemed/get-shit-done-codex 1.23.2 → 1.24.2

package/bin/install.js

@@ -19,6 +19,23 @@ const UPSTREAM_PACKAGE = 'get-shit-done-cc';
 const UPSTREAM_REPO = 'https://github.com/glittercowboy/get-shit-done';
 const FORK_REPO = 'https://github.com/undeemed/get-shit-done-codex';
 
+// ─── Codex Config Constants ───────────────────────────────────────────────────
+const GSD_CODEX_MARKER = '# GSD Agent Configuration \u2014 managed by get-shit-done installer';
+
+const CODEX_AGENT_SANDBOX = {
+  'gsd-executor': 'workspace-write',
+  'gsd-planner': 'workspace-write',
+  'gsd-phase-researcher': 'workspace-write',
+  'gsd-project-researcher': 'workspace-write',
+  'gsd-research-synthesizer': 'workspace-write',
+  'gsd-verifier': 'workspace-write',
+  'gsd-codebase-mapper': 'workspace-write',
+  'gsd-roadmapper': 'workspace-write',
+  'gsd-debugger': 'workspace-write',
+  'gsd-plan-checker': 'read-only',
+  'gsd-integration-checker': 'read-only',
+};
+
 const banner = `
 ${green}   ██████╗ ███████╗██████╗
    ██╔════╝ ██╔════╝██╔══██╗
@@ -169,12 +186,45 @@ function toSingleLine(value) {
 }
 
 function getCodexSkillAdapterHeader(skillName) {
+  const invocation = `$${skillName}`;
   return `<codex_skill_adapter>
-Codex native skill mode:
-- AGENTS-first: treat AGENTS.md as the persistent source of truth for behavior and constraints.
-- Invoke this workflow with \`$${skillName}\`.
-- Treat user text after \`$${skillName}\` as \`{{GSD_ARGS}}\` (empty when omitted).
-- Any legacy \`Task(...)\` notation in referenced docs means "spawn a specialized subagent" in Codex.
+## A. Skill Invocation
+- This skill is invoked by mentioning \`${invocation}\`.
+- Treat all user text after \`${invocation}\` as \`{{GSD_ARGS}}\`.
+- If no arguments are present, treat \`{{GSD_ARGS}}\` as empty.
+
+## B. AskUserQuestion → request_user_input Mapping
+GSD workflows use \`AskUserQuestion\` (GSD workflow syntax). Translate to Codex \`request_user_input\`:
+
+Parameter mapping:
+- \`header\` → \`header\`
+- \`question\` → \`question\`
+- Options formatted as \`"Label" — description\` → \`{label: "Label", description: "description"}\`
+- Generate \`id\` from header: lowercase, replace spaces with underscores
+
+Batched calls:
+- \`AskUserQuestion([q1, q2])\` → single \`request_user_input\` with multiple entries in \`questions[]\`
+
+Multi-select workaround:
+- Codex has no \`multiSelect\`. Use sequential single-selects, or present a numbered freeform list asking the user to enter comma-separated numbers.
+
+Execute mode fallback:
+- When \`request_user_input\` is rejected (Execute mode), present a plain-text numbered list and pick a reasonable default.
+
+## C. Task() → spawn_agent Mapping
+GSD workflows use \`Task(...)\` (GSD workflow syntax). Translate to Codex collaboration tools:
+
+Direct mapping:
+- \`Task(subagent_type="X", prompt="Y")\` → \`spawn_agent(agent_type="X", message="Y")\`
+- \`Task(model="...")\` → omit (Codex uses per-role config, not inline model selection)
+- \`fork_context: false\` by default — GSD agents load their own context via \`<files_to_read>\` blocks
+
+Parallel fan-out:
+- Spawn multiple agents → collect agent IDs → \`wait(ids)\` for all to complete
+
+Result parsing:
+- Look for structured markers in agent output: \`CHECKPOINT\`, \`PLAN COMPLETE\`, \`SUMMARY\`, etc.
+- \`close_agent(id)\` after collecting results from each agent
 </codex_skill_adapter>`;
 }
 
@@ -638,6 +688,216 @@ if (locationFlagCount > 1) {
   process.exit(1);
 }
 
+// ─── Upstream Codex Config Functions ──────────────────────────────────────────
+// These are ported from upstream's install.js for multi-agent config.toml
+// generation, merge, strip, and per-agent .toml config files.
+
+/**
+ * Convert an agent markdown file to Codex agent format.
+ * Applies base markdown conversions, then adds a <codex_agent_role> header
+ * and cleans up frontmatter (removes tools/color fields).
+ */
+function convertAgentToCodexFormat(content) {
+  let converted = convertPromptRefsToSkillRefs(content);
+  converted = convertCommandRefsToSkillMentions(converted);
+  converted = converted.replace(/\$ARGUMENTS\b/g, '{{GSD_ARGS}}');
+
+  const { frontmatter, body } = extractFrontmatterAndBody(converted);
+  if (!frontmatter) return converted;
+
+  const name = extractFrontmatterField(frontmatter, 'name') || 'unknown';
+  const description = extractFrontmatterField(frontmatter, 'description') || '';
+  const tools = extractFrontmatterField(frontmatter, 'tools') || '';
+
+  const roleHeader = `<codex_agent_role>
+role: ${name}
+tools: ${tools}
+purpose: ${toSingleLine(description)}
+</codex_agent_role>`;
+
+  const cleanFrontmatter = `---\nname: ${yamlQuote(name)}\ndescription: ${yamlQuote(toSingleLine(description))}\n---`;
+
+  return `${cleanFrontmatter}\n\n${roleHeader}\n${body}`;
+}
+
+function convertCommandToCodexSkill(content, skillName) {
+  let converted = convertPromptRefsToSkillRefs(content);
+  converted = convertCommandRefsToSkillMentions(converted);
+  converted = converted.replace(/\$ARGUMENTS\b/g, '{{GSD_ARGS}}');
+  const { frontmatter, body } = extractFrontmatterAndBody(converted);
+  let description = `Run GSD workflow ${skillName}.`;
+  if (frontmatter) {
+    const maybeDescription = extractFrontmatterField(frontmatter, 'description');
+    if (maybeDescription) {
+      description = maybeDescription;
+    }
+  }
+  description = toSingleLine(description);
+  const shortDescription = description.length > 180 ? `${description.slice(0, 177)}...` : description;
+  const adapter = getCodexSkillAdapterHeader(skillName);
+
+  return `---\nname: ${yamlQuote(skillName)}\ndescription: ${yamlQuote(description)}\nmetadata:\n  short-description: ${yamlQuote(shortDescription)}\n---\n\n${adapter}\n\n${body.trimStart()}`;
+}
+
+/**
+ * Generate a per-agent .toml config file for Codex.
+ * Sets sandbox_mode and developer_instructions from the agent markdown body.
+ */
+function generateCodexAgentToml(agentName, agentContent) {
+  const sandboxMode = CODEX_AGENT_SANDBOX[agentName] || 'read-only';
+  const { body } = extractFrontmatterAndBody(agentContent);
+  const instructions = body.trim();
+
+  const lines = [
+    `sandbox_mode = "${sandboxMode}"`,
+    `developer_instructions = """`,
+    instructions,
+    `"""`,
+  ];
+  return lines.join('\n') + '\n';
+}
+
+/**
+ * Generate the GSD config block for Codex config.toml.
+ * @param {Array<{name: string, description: string}>} agents
+ */
+function generateCodexConfigBlock(agents) {
+  const lines = [
+    GSD_CODEX_MARKER,
+    '[features]',
+    'multi_agent = true',
+    'default_mode_request_user_input = true',
+    '',
+    '[agents]',
+    'max_threads = 4',
+    'max_depth = 2',
+    '',
+  ];
+
+  for (const { name, description } of agents) {
+    lines.push(`[agents.${name}]`);
+    lines.push(`description = ${JSON.stringify(description)}`);
+    lines.push(`config_file = "agents/${name}.toml"`);
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Strip GSD sections from Codex config.toml content.
+ * Returns cleaned content, or null if file would be empty.
+ */
+function stripGsdFromCodexConfig(content) {
+  const markerIndex = content.indexOf(GSD_CODEX_MARKER);
+
+  if (markerIndex !== -1) {
+    let before = content.substring(0, markerIndex).trimEnd();
+    before = before.replace(/^multi_agent\s*=\s*true\s*\n?/m, '');
+    before = before.replace(/^default_mode_request_user_input\s*=\s*true\s*\n?/m, '');
+    before = before.replace(/^\[features\]\s*\n(?=\[|$)/m, '');
+    before = before.replace(/\n{3,}/g, '\n\n').trim();
+    if (!before) return null;
+    return before + '\n';
+  }
+
+  let cleaned = content;
+  cleaned = cleaned.replace(/^multi_agent\s*=\s*true\s*\n?/m, '');
+  cleaned = cleaned.replace(/^default_mode_request_user_input\s*=\s*true\s*\n?/m, '');
+  cleaned = cleaned.replace(/^\[agents\.gsd-[^\]]+\]\n(?:(?!\[)[^\n]*\n?)*/gm, '');
+  cleaned = cleaned.replace(/^\[features\]\s*\n(?=\[|$)/m, '');
+  cleaned = cleaned.replace(/^\[agents\]\s*\n(?=\[|$)/m, '');
+  cleaned = cleaned.replace(/\n{3,}/g, '\n\n').trim();
+
+  if (!cleaned) return null;
+  return cleaned + '\n';
+}
+
+/**
+ * Merge GSD config block into an existing or new config.toml.
+ */
+function mergeCodexConfig(configPath, gsdBlock) {
+  if (!fs.existsSync(configPath)) {
+    fs.writeFileSync(configPath, gsdBlock + '\n');
+    return;
+  }
+
+  const existing = fs.readFileSync(configPath, 'utf8');
+  const markerIndex = existing.indexOf(GSD_CODEX_MARKER);
+
+  if (markerIndex !== -1) {
+    const before = existing.substring(0, markerIndex).trimEnd();
+    const newContent = before ? before + '\n\n' + gsdBlock + '\n' : gsdBlock + '\n';
+    fs.writeFileSync(configPath, newContent);
+    return;
+  }
+
+  let content = existing;
+  const featuresRegex = /^\[features\]\s*$/m;
+  const hasFeatures = featuresRegex.test(content);
+
+  if (hasFeatures) {
+    if (!content.includes('multi_agent')) {
+      content = content.replace(featuresRegex, '[features]\nmulti_agent = true');
+    }
+    if (!content.includes('default_mode_request_user_input')) {
+      content = content.replace(/^\[features\].*$/m, '$&\ndefault_mode_request_user_input = true');
+    }
+    const agentsBlock = gsdBlock.substring(gsdBlock.indexOf('[agents]'));
+    content = content.trimEnd() + '\n\n' + GSD_CODEX_MARKER + '\n' + agentsBlock + '\n';
+  } else {
+    content = content.trimEnd() + '\n\n' + gsdBlock + '\n';
+  }
+
+  fs.writeFileSync(configPath, content);
+}
+
+/**
+ * Generate config.toml and per-agent .toml files for Codex.
+ */
+function installCodexConfig(targetDir, agentsSrc) {
+  const configPath = path.join(targetDir, 'config.toml');
+  const agentsTomlDir = path.join(targetDir, 'agents');
+  fs.mkdirSync(agentsTomlDir, { recursive: true });
+
+  const agentEntries = fs.readdirSync(agentsSrc).filter(f => f.startsWith('gsd-') && f.endsWith('.md'));
+  const agents = [];
+
+  for (const file of agentEntries) {
+    const content = fs.readFileSync(path.join(agentsSrc, file), 'utf8');
+    const { frontmatter } = extractFrontmatterAndBody(content);
+    const name = extractFrontmatterField(frontmatter, 'name') || file.replace('.md', '');
+    const description = extractFrontmatterField(frontmatter, 'description') || '';
+
+    agents.push({ name, description: toSingleLine(description) });
+
+    const tomlContent = generateCodexAgentToml(name, content);
+    fs.writeFileSync(path.join(agentsTomlDir, `${name}.toml`), tomlContent);
+  }
+
+  const gsdBlock = generateCodexConfigBlock(agents);
+  mergeCodexConfig(configPath, gsdBlock);
+
+  return agents.length;
+}
+
+// ─── Test-only exports ───────────────────────────────────────────────────────
+// When loaded as a module for testing, skip main CLI logic and export functions
+if (process.env.GSD_TEST_MODE) {
+  module.exports = {
+    getCodexSkillAdapterHeader,
+    convertAgentToCodexFormat,
+    generateCodexAgentToml,
+    generateCodexConfigBlock,
+    stripGsdFromCodexConfig,
+    mergeCodexConfig,
+    installCodexConfig,
+    convertCommandToCodexSkill,
+    GSD_CODEX_MARKER,
+    CODEX_AGENT_SANDBOX,
+  };
+} else {
+
 if (pathIdx !== -1 && !customPath) {
   console.error(`  ${yellow}--path requires a directory argument${reset}`);
   process.exit(1);
@@ -684,3 +944,5 @@ if (hasVerify) {
     });
   }
 }
+
+} // end of else block for GSD_TEST_MODE

package/commands/gsd/add-phase.md

@@ -19,15 +19,11 @@ Routes to the add-phase workflow which handles:
 </objective>
 
 <execution_context>
+@.planning/ROADMAP.md
+@.planning/STATE.md
 @~/.codex/get-shit-done/workflows/add-phase.md
 </execution_context>
 
-<context>
-Arguments: $ARGUMENTS (phase description)
-
-Roadmap and state are resolved in-workflow via `init phase-op` and targeted tool calls.
-</context>
-
 <process>
 **Follow the add-phase workflow** from `@~/.codex/get-shit-done/workflows/add-phase.md`.
 

package/commands/gsd/add-todo.md

@@ -23,15 +23,10 @@ Routes to the add-todo workflow which handles:
 </objective>
 
 <execution_context>
+@.planning/STATE.md
 @~/.codex/get-shit-done/workflows/add-todo.md
 </execution_context>
 
-<context>
-Arguments: $ARGUMENTS (optional todo description)
-
-State is resolved in-workflow via `init todos` and targeted reads.
-</context>
-
 <process>
 **Follow the add-todo workflow** from `@~/.codex/get-shit-done/workflows/add-todo.md`.
 

package/commands/gsd/check-todos.md

@@ -21,15 +21,11 @@ Routes to the check-todos workflow which handles:
 </objective>
 
 <execution_context>
+@.planning/STATE.md
+@.planning/ROADMAP.md
 @~/.codex/get-shit-done/workflows/check-todos.md
 </execution_context>
 
-<context>
-Arguments: $ARGUMENTS (optional area filter)
-
-Todo state and roadmap correlation are loaded in-workflow using `init todos` and targeted reads.
-</context>
-
 <process>
 **Follow the check-todos workflow** from `@~/.codex/get-shit-done/workflows/check-todos.md`.
 

package/commands/gsd/debug.md

@@ -110,9 +110,6 @@ Task(
 **If `## CHECKPOINT REACHED`:**
 - Present checkpoint details to user
 - Get user response
-- If checkpoint type is `human-verify`:
-  - If user confirms fixed: continue so agent can finalize/resolve/archive
-  - If user reports issues: continue so agent returns to investigation/fixing
 - Spawn continuation agent (see step 5)
 
 **If `## INVESTIGATION INCONCLUSIVE`:**
@@ -132,9 +129,7 @@ Continue debugging {slug}. Evidence is in the debug file.
 </objective>
 
 <prior_state>
-<files_to_read>
-- .planning/debug/{slug}.md (Debug session state)
-</files_to_read>
+Debug file: @.planning/debug/{slug}.md
 </prior_state>
 
 <checkpoint_response>

package/commands/gsd/discuss-phase.md

@@ -10,16 +10,20 @@ allowed-tools:
   - Grep
   - AskUserQuestion
   - Task
+  - mcp__context7__resolve-library-id
+  - mcp__context7__query-docs
 ---
 
 <objective>
 Extract implementation decisions that downstream agents need — researcher and planner will use CONTEXT.md to know what to investigate and what choices are locked.
 
 **How it works:**
-1. Analyze the phase to identify gray areas (UI, UX, behavior, etc.)
-2. Present gray areas — user selects which to discuss
-3. Deep-dive each selected area until satisfied
-4. Create CONTEXT.md with decisions that guide research and planning
+1. Load prior context (PROJECT.md, REQUIREMENTS.md, STATE.md, prior CONTEXT.md files)
+2. Scout codebase for reusable assets and patterns
+3. Analyze phase — skip gray areas already decided in prior phases
+4. Present remaining gray areas — user selects which to discuss
+5. Deep-dive each selected area until satisfied
+6. Create CONTEXT.md with decisions that guide research and planning
 
 **Output:** `{phase_num}-CONTEXT.md` — decisions clear enough that downstream agents can act without asking the user again
 </objective>
@@ -38,11 +42,13 @@ Context files are resolved in-workflow using `init phase-op` and roadmap/state t
 <process>
 1. Validate phase number (error if missing or not in roadmap)
 2. Check if CONTEXT.md exists (offer update/view/skip if yes)
-3. **Analyze phase** — Identify domain and generate phase-specific gray areas
-4. **Present gray areas** — Multi-select: which to discuss? (NO skip option)
-5. **Deep-dive each area** — 4 questions per area, then offer more/next
-6. **Write CONTEXT.md** — Sections match areas discussed
-7. Offer next steps (research or plan)
+3. **Load prior context** — Read PROJECT.md, REQUIREMENTS.md, STATE.md, and all prior CONTEXT.md files
+4. **Scout codebase** — Find reusable assets, patterns, and integration points
+5. **Analyze phase** — Check prior decisions, skip already-decided areas, generate remaining gray areas
+6. **Present gray areas** — Multi-select: which to discuss? Annotate with prior decisions + code context
+7. **Deep-dive each area** — 4 questions per area, code-informed options, Context7 for library choices
+8. **Write CONTEXT.md** — Sections match areas discussed + code_context section
+9. Offer next steps (research or plan)
 
 **CRITICAL: Scope guardrail**
 - Phase boundary from ROADMAP.md is FIXED
@@ -74,6 +80,7 @@ Generate 3-4 **phase-specific** gray areas, not generic categories.
 </process>
 
 <success_criteria>
+- Prior context loaded and applied (no re-asking decided questions)
 - Gray areas identified through intelligent analysis
 - User chose which areas to discuss
 - Each selected area explored until satisfied

package/commands/gsd/execute-phase.md

@@ -32,7 +32,8 @@ Phase: $ARGUMENTS
 **Flags:**
 - `--gaps-only` — Execute only gap closure plans (plans with `gap_closure: true` in frontmatter). Use after verify-work creates fix plans.
 
-Context files are resolved inside the workflow via `gsd-tools init execute-phase` and per-subagent `<files_to_read>` blocks.
+@.planning/ROADMAP.md
+@.planning/STATE.md
 </context>
 
 <process>

package/commands/gsd/new-milestone.md

@@ -35,7 +35,14 @@ Brownfield equivalent of new-project. Project exists, PROJECT.md has history. Ga
 <context>
 Milestone name: $ARGUMENTS (optional - will prompt if not provided)
 
-Project and milestone context files are resolved inside the workflow (`init new-milestone`) and delegated via `<files_to_read>` blocks where subagents are used.
+**Load project context:**
+@.planning/PROJECT.md
+@.planning/STATE.md
+@.planning/MILESTONES.md
+@.planning/config.json
+
+**Load milestone context (if exists, from /gsd:discuss-milestone):**
+@.planning/MILESTONE-CONTEXT.md
 </context>
 
 <process>

package/commands/gsd/pause-work.md

@@ -19,13 +19,10 @@ Routes to the pause-work workflow which handles:
 </objective>
 
 <execution_context>
+@.planning/STATE.md
 @~/.codex/get-shit-done/workflows/pause-work.md
 </execution_context>
 
-<context>
-State and phase progress are gathered in-workflow with targeted reads.
-</context>
-
 <process>
 **Follow the pause-work workflow** from `@~/.codex/get-shit-done/workflows/pause-work.md`.
 

package/commands/gsd/plan-phase.md

@@ -1,7 +1,7 @@
 ---
 name: gsd:plan-phase
 description: Create detailed phase plan (PLAN.md) with verification loop
-argument-hint: "[phase] [--auto] [--research] [--skip-research] [--gaps] [--skip-verify] [--prd <file>]"
+argument-hint: "[phase] [--auto] [--research] [--skip-research] [--gaps] [--skip-verify]"
 agent: gsd-planner
 allowed-tools:
   - Read
@@ -34,7 +34,6 @@ Phase number: $ARGUMENTS (optional — auto-detects next unplanned phase if omit
 - `--skip-research` — Skip research, go straight to planning
 - `--gaps` — Gap closure mode (reads VERIFICATION.md, skips research)
 - `--skip-verify` — Skip verification loop
-- `--prd <file>` — Use a PRD/acceptance criteria file instead of discuss-phase. Parses requirements into CONTEXT.md automatically. Skips discuss-phase entirely.
 
 Normalize phase input in step 2 before any directory lookups.
 </context>

package/commands/gsd/research-phase.md

@@ -37,7 +37,7 @@ Normalize phase input in step 1 before any directory lookups.
 INIT=$(node ~/.codex/get-shit-done/bin/gsd-tools.cjs init phase-op "$ARGUMENTS")
 ```
 
-Extract from init JSON: `phase_dir`, `phase_number`, `phase_name`, `phase_found`, `commit_docs`, `has_research`, `state_path`, `requirements_path`, `context_path`, `research_path`.
+Extract from init JSON: `phase_dir`, `phase_number`, `phase_name`, `phase_found`, `commit_docs`, `has_research`.
 
 Resolve researcher model:
 ```bash
@@ -64,12 +64,15 @@ ls .planning/phases/${PHASE}-*/RESEARCH.md 2>/dev/null
 
 ## 3. Gather Phase Context
 
-Use paths from INIT (do not inline file contents in orchestrator context):
-- `requirements_path`
-- `context_path`
-- `state_path`
+```bash
+# Phase section 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
+grep -A30 "### Decisions Made" .planning/STATE.md 2>/dev/null
+```
 
-Present summary with phase description and what files the researcher will load.
+Present summary with phase description, requirements, prior decisions.
 
 ## 4. Spawn gsd-phase-researcher Agent
 
@@ -98,15 +101,12 @@ Research implementation approach for Phase {phase_number}: {phase_name}
 Mode: ecosystem
 </objective>
 
-<files_to_read>
-- {requirements_path} (Requirements)
-- {context_path} (Phase context from discuss-phase, if exists)
-- {state_path} (Prior project decisions and blockers)
-</files_to_read>
-
-<additional_context>
+<context>
 **Phase description:** {phase_description}
-</additional_context>
+**Requirements:** {requirements_list}
+**Prior decisions:** {decisions_if_any}
+**Phase context:** {context_md_content}
+</context>
 
 <downstream_consumer>
 Your RESEARCH.md will be loaded by `$gsd-plan-phase` which uses specific sections:
@@ -158,9 +158,7 @@ Continue research for Phase {phase_number}: {phase_name}
 </objective>
 
 <prior_state>
-<files_to_read>
-- .planning/phases/${PHASE}-{slug}/${PHASE}-RESEARCH.md (Existing research)
-</files_to_read>
+Research file: @.planning/phases/${PHASE}-{slug}/${PHASE}-RESEARCH.md
 </prior_state>
 
 <checkpoint_response>

package/commands/gsd/verify-work.md

@@ -29,7 +29,8 @@ Phase: $ARGUMENTS (optional)
 - If provided: Test specific phase (e.g., "4")
 - If not provided: Check for active sessions or prompt for phase
 
-Context files are resolved inside the workflow (`init verify-work`) and delegated via `<files_to_read>` blocks.
+@.planning/STATE.md
+@.planning/ROADMAP.md
 </context>
 
 <process>