@undeemed/get-shit-done-codex 1.20.10 → 1.21.0

package/.codex/config.toml

@@ -0,0 +1,77 @@
+:schema https://developers.openai.com/codex/config-schema.json
+
+# Project-scoped Codex config for get-shit-done-codex.
+# Loaded only when this project is trusted.
+# Docs:
+# - https://developers.openai.com/codex/config-basic
+# - https://developers.openai.com/codex/config-reference
+# - https://developers.openai.com/codex/multi-agent
+
+web_search = "live"
+
+[features]
+multi_agent = true
+collaboration_modes = true
+shell_tool = true
+shell_snapshot = true
+unified_exec = true
+apply_patch_freeform = true
+personality = true
+request_rule = true
+
+[agents]
+max_threads = 12
+max_depth = 3
+
+[agents."general-purpose"]
+description = "General fallback role for GSD orchestration and ad-hoc subtasks."
+
+[agents."gsd-codebase-mapper"]
+description = "Map stack, architecture, conventions, testing, and concerns into .planning/codebase docs."
+developer_instructions = "Read and follow agents/gsd-codebase-mapper.md for your complete role definition."
+
+[agents."gsd-debugger"]
+description = "Investigate regressions with hypothesis testing, isolate root cause, and propose or apply fixes."
+developer_instructions = "Read and follow agents/gsd-debugger.md for your complete role definition."
+
+[agents."gsd-executor"]
+description = "Execute PLAN.md tasks with atomic commits, verification, and summary updates."
+developer_instructions = "Read and follow agents/gsd-executor.md for your complete role definition."
+
+[agents."gsd-integration-checker"]
+description = "Verify cross-phase wiring and end-to-end behavior across delivered milestones."
+developer_instructions = "Read and follow agents/gsd-integration-checker.md for your complete role definition."
+
+[agents."gsd-phase-researcher"]
+description = "Research phase implementation patterns and write RESEARCH.md artifacts for planners."
+developer_instructions = "Read and follow agents/gsd-phase-researcher.md for your complete role definition."
+
+[agents."gsd-plan-checker"]
+description = "Stress-test plan quality and requirement coverage before execution."
+developer_instructions = "Read and follow agents/gsd-plan-checker.md for your complete role definition."
+
+[agents."gsd-planner"]
+description = "Draft atomic PLAN.md files with objective, context, tasks, and success criteria."
+developer_instructions = "Read and follow agents/gsd-planner.md for your complete role definition."
+
+[agents."gsd-project-researcher"]
+description = "Research ecosystem and produce project-level research docs for roadmap creation."
+developer_instructions = "Read and follow agents/gsd-project-researcher.md for your complete role definition."
+
+[agents."gsd-research-synthesizer"]
+description = "Synthesize parallel research artifacts into actionable roadmap inputs."
+developer_instructions = "Read and follow agents/gsd-research-synthesizer.md for your complete role definition."
+
+[agents."gsd-roadmapper"]
+description = "Turn requirements into phased ROADMAP.md structure with clear success criteria."
+developer_instructions = "Read and follow agents/gsd-roadmapper.md for your complete role definition."
+
+[agents."gsd-verifier"]
+description = "Perform goal-backward verification that outcomes are actually delivered in code."
+developer_instructions = "Read and follow agents/gsd-verifier.md for your complete role definition."
+
+[mcp_servers.context7]
+url = "https://mcp.context7.com/mcp"
+
+[mcp_servers.context7.env_http_headers]
+CONTEXT7_API_KEY = "CONTEXT7_API_KEY"

package/README.md

@@ -21,7 +21,7 @@ get-shit-done-codex (GSD) solves context rot — the quality degradation that ha
 
 ## What Changed In This Fork
 
-- **AGENTS-first for Codex:** `AGENTS.md` is the primary behavior contract  . [Agent.md > Skills.md](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals)
+- **AGENTS-first for Codex:** `AGENTS.md` is the primary behavior contract . [Agent.md > Skills.md](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals)
 - **Two command surfaces:** choose native skills (`$gsd-*`) or prompt aliases (`/prompts:gsd-*`).
 - **Installer integrity checks:** `--verify` audits installation health, `--repair` restores missing artifacts.
 - **Mode-aware installs:** installer adapts `AGENTS.md` and command guidance to your chosen mode.
@@ -58,14 +58,29 @@ npx @undeemed/get-shit-done-codex --verify --repair --global     # Auto-repair
 
 ### Codex Modes
 
-| Mode      | Installs                     | Use Commands Like           |
-| --------- | ---------------------------- | --------------------------- |
-| `skills` (default) | `skills/gsd-*/SKILL.md`      | `$gsd-help`, `$gsd-plan-phase 1` |
-| `prompts` | `prompts/gsd-*.md`           | `/prompts:gsd-help`         |
+| Mode               | Installs                | Use Commands Like                |
+| ------------------ | ----------------------- | -------------------------------- |
+| `skills` (default) | `skills/gsd-*/SKILL.md` | `$gsd-help`, `$gsd-plan-phase 1` |
+| `prompts`          | `prompts/gsd-*.md`      | `/prompts:gsd-help`              |
 
 After installation, run `codex` (CLI) or `codex app` (Desktop), then run `$gsd-help` (or `/prompts:gsd-help` in prompts mode).
 Single-surface policy: mixed `skills/` + `prompts/` installs are treated as drift and fail `--verify`.
 
+### What Gets Installed
+
+The installer distributes everything GSD needs:
+
+- **`AGENTS.md`** — behavior contract and command reference for Codex
+- **`.codex/config.toml`** — multi-agent mode, feature flags, agent role registry, MCP servers
+- **`agents/gsd-*.md`** — rich agent definitions (700+ lines each) for sub-agent orchestration
+- **`skills/gsd-*/SKILL.md`** or **`prompts/gsd-*.md`** — command surfaces
+- **`get-shit-done/`** — workflow files, templates, and references
+
+On first run, Codex will prompt you to **trust the project** so the config takes effect (one-time, one-click).
+
+> [!NOTE]
+> `.codex/config.toml` is non-destructive — the installer skips it if you already have one, so your customizations are preserved on updates.
+
 ### Installed File Structure
 
 `$` skills mode (`--codex-mode skills`, default):
@@ -73,8 +88,9 @@ Single-surface policy: mixed `skills/` + `prompts/` installs are treated as drif
 ```text
 ~/.codex/
 ├── AGENTS.md
-├── skills/
-│   └── gsd-*/SKILL.md
+├── .codex/config.toml
+├── agents/gsd-*.md
+├── skills/gsd-*/SKILL.md
 └── get-shit-done/
 ```
 
@@ -83,8 +99,9 @@ Single-surface policy: mixed `skills/` + `prompts/` installs are treated as drif
 ```text
 ~/.codex/
 ├── AGENTS.md
-├── prompts/
-│   └── gsd-*.md
+├── .codex/config.toml
+├── agents/gsd-*.md
+├── prompts/gsd-*.md
 └── get-shit-done/
 ```
 
@@ -92,7 +109,7 @@ For local installs, replace `~/.codex/` with `./`.
 
 ### Verify And Repair
 
-- `--verify`: checks `AGENTS.md`, command surfaces, workflow assets, and version metadata.
+- `--verify`: checks `AGENTS.md`, `config.toml`, agent definitions, command surfaces, workflow assets, and version metadata.
 - `--verify --repair`: reinstalls missing/broken artifacts and verifies again.
 - Migration is **detect-then-confirm**, not automatic:
   - Interactive install asks before removing legacy surface files
@@ -251,6 +268,12 @@ Git bisect finds exact failing task. Each task independently revertable.
 - Check `~/.codex/skills/gsd-*/SKILL.md` (global) or `./skills/gsd-*/SKILL.md` (local)
 - If using prompt aliases, check `~/.codex/prompts/gsd-*.md` (global) or `./prompts/gsd-*.md` (local)
 
+**Multi-agent / sub-agents not working?**
+
+- Check `.codex/config.toml` exists in your install directory
+- Ensure the project is **trusted** in Codex (it prompts on first run)
+- Run `--verify` to check all artifacts are present
+
 **Update to latest:**
 
 ```bash

package/bin/install.js

@@ -305,6 +305,52 @@ function removeSkillAliases(skillsDir) {
   return removed;
 }
 
+function installConfig(src, codexDir, pathPrefix) {
+  const configSrc = path.join(src, '.codex', 'config.toml');
+  if (!fs.existsSync(configSrc)) return false;
+  const codexConfigDir = path.join(codexDir, '.codex');
+  const configDest = path.join(codexConfigDir, 'config.toml');
+  if (fs.existsSync(configDest)) return false;
+  fs.mkdirSync(codexConfigDir, { recursive: true });
+  let content = applyPathPrefixReplacements(fs.readFileSync(configSrc, 'utf8'), pathPrefix);
+  if (pathPrefix === '~/.codex/') {
+    content = content.replace(/agents\/gsd-/g, '~/.codex/agents/gsd-');
+  }
+  fs.writeFileSync(configDest, content, 'utf8');
+  return true;
+}
+
+function installAgentDefs(src, codexDir, pathPrefix, mode) {
+  const agentsSrc = path.join(src, 'agents');
+  if (!fs.existsSync(agentsSrc)) return 0;
+  const agentsDest = path.join(codexDir, 'agents');
+  fs.mkdirSync(agentsDest, { recursive: true });
+  const entries = fs.readdirSync(agentsSrc).filter((e) => /^gsd-.*\.md$/i.test(e));
+  for (const entry of entries) {
+    let content = fs.readFileSync(path.join(agentsSrc, entry), 'utf8');
+    content = applyReplacements(content, pathPrefix);
+    if (mode === 'skills') {
+      content = convertPromptRefsToSkillRefs(content);
+    } else if (mode === 'prompts') {
+      content = convertSkillRefsToPromptRefs(content);
+    }
+    fs.writeFileSync(path.join(agentsDest, entry), content, 'utf8');
+  }
+  return entries.length;
+}
+
+function countSourceAgentDefs(src) {
+  const agentsSrc = path.join(src, 'agents');
+  if (!fs.existsSync(agentsSrc)) return 0;
+  return fs.readdirSync(agentsSrc).filter((e) => /^gsd-.*\.md$/i.test(e)).length;
+}
+
+function countInstalledAgentDefs(codexDir) {
+  const agentsDest = path.join(codexDir, 'agents');
+  if (!fs.existsSync(agentsDest)) return 0;
+  return fs.readdirSync(agentsDest).filter((e) => /^gsd-.*\.md$/i.test(e)).length;
+}
+
 function detectMigrationPlan(codexDir, mode) {
   const promptsDir = path.join(codexDir, 'prompts');
   const skillsDir = path.join(codexDir, 'skills');
@@ -450,8 +496,15 @@ function verifyInstall(isGlobal, expectedMode, strictMode = false) {
   const checks = [];
   const addCheck = (ok, label, detail) => checks.push({ ok, label, detail });
 
+  const expectedAgentCount = countSourceAgentDefs(src);
+
   addCheck(fs.existsSync(codexDir), 'Config directory exists', codexDir);
   addCheck(fs.existsSync(path.join(codexDir, 'AGENTS.md')), 'AGENTS.md installed', path.join(codexDir, 'AGENTS.md'));
+  addCheck(fs.existsSync(path.join(codexDir, '.codex', 'config.toml')), 'config.toml installed', path.join(codexDir, '.codex', 'config.toml'));
+  if (expectedAgentCount > 0) {
+    const installedAgents = countInstalledAgentDefs(codexDir);
+    addCheck(installedAgents === expectedAgentCount, 'Agent definitions complete', `${installedAgents}/${expectedAgentCount}`);
+  }
   addCheck(fs.existsSync(workflowRoot), 'get-shit-done assets installed', workflowRoot);
   addCheck(fs.existsSync(path.join(workflowRoot, 'workflows')), 'Workflow directory installed', path.join(workflowRoot, 'workflows'));
   addCheck(fs.existsSync(path.join(workflowRoot, 'templates')), 'Template directory installed', path.join(workflowRoot, 'templates'));
@@ -496,7 +549,7 @@ function verifyInstall(isGlobal, expectedMode, strictMode = false) {
   return { ok, detectedMode, checkedMode: modeToCheck };
 }
 
-function installCore(isGlobal, mode, migrationPlan, applyMigration) {
+function installCore(isGlobal, mode, migrationPlan, applyMigration, done = () => {}) {
   const src = path.join(__dirname, '..');
   const { codexDir, locationLabel, pathPrefix } = getInstallContext(isGlobal);
   const installPromptsEnabled = mode === 'prompts';
@@ -508,43 +561,61 @@ function installCore(isGlobal, mode, migrationPlan, applyMigration) {
     applyMigrationPlan(migrationPlan);
   }
 
-  const agentsSrc = path.join(src, 'AGENTS.md');
+  const agentsSrc = path.join(src, 'get-shit-done', 'AGENTS.md');
   const agentsDest = path.join(codexDir, 'AGENTS.md');
-  let agentsContent = applyReplacements(fs.readFileSync(agentsSrc, 'utf8'), pathPrefix);
-  agentsContent = adaptAgentsForCodexMode(agentsContent, mode);
-  fs.writeFileSync(agentsDest, agentsContent, 'utf8');
-  console.log(`  ${green}✓${reset} Installed AGENTS.md`);
+  const agentsExisted = fs.existsSync(agentsDest);
 
-  const gsdSrc = path.join(src, 'commands', 'gsd');
-  const entries = fs.readdirSync(gsdSrc);
-  const markdownEntries = entries.filter((entry) => entry.endsWith('.md'));
+  const writeAgents = () => {
+    let agentsContent = applyReplacements(fs.readFileSync(agentsSrc, 'utf8'), pathPrefix);
+    agentsContent = adaptAgentsForCodexMode(agentsContent, mode);
+    fs.writeFileSync(agentsDest, agentsContent, 'utf8');
+  };
 
-  if (installPromptsEnabled) {
-    const promptsDir = path.join(codexDir, 'prompts');
-    installPrompts(gsdSrc, promptsDir, markdownEntries, pathPrefix);
-    console.log(`  ${green}✓${reset} Installed prompts/gsd-*.md (${markdownEntries.length} commands)`);
-  }
+  const continueAfterAgents = () => {
+    const configInstalled = installConfig(src, codexDir, pathPrefix);
+    if (configInstalled) {
+      console.log(`  ${green}✓${reset} Installed .codex/config.toml`);
+    } else {
+      console.log(`  ${dim}-${reset} Skipped .codex/config.toml (already exists or source missing)`);
+    }
 
-  if (installSkillsEnabled) {
-    const skillsDir = path.join(codexDir, 'skills');
-    installCodexSkills(gsdSrc, skillsDir, markdownEntries, pathPrefix);
-    console.log(`  ${green}✓${reset} Installed skills/gsd-*/SKILL.md (${markdownEntries.length} skills)`);
-  }
+    const agentCount = installAgentDefs(src, codexDir, pathPrefix, mode);
+    if (agentCount > 0) {
+      console.log(`  ${green}✓${reset} Installed agents/gsd-*.md (${agentCount} agent definitions)`);
+    }
 
-  const skillSrc = path.join(src, 'get-shit-done');
-  const skillDest = path.join(codexDir, 'get-shit-done');
-  copyWithPathReplacement(skillSrc, skillDest, pathPrefix);
-  writeVersionFile(skillDest, isGlobal);
-  console.log(`  ${green}✓${reset} Installed get-shit-done/ workflow files`);
-  console.log(`  ${green}✓${reset} Wrote get-shit-done/VERSION (${pkg.version})`);
+    const gsdSrc = path.join(src, 'commands', 'gsd');
+    const entries = fs.readdirSync(gsdSrc);
+    const markdownEntries = entries.filter((entry) => entry.endsWith('.md'));
 
-  console.log(`
+    if (installPromptsEnabled) {
+      const promptsDir = path.join(codexDir, 'prompts');
+      installPrompts(gsdSrc, promptsDir, markdownEntries, pathPrefix);
+      console.log(`  ${green}✓${reset} Installed prompts/gsd-*.md (${markdownEntries.length} commands)`);
+    }
+
+    if (installSkillsEnabled) {
+      const skillsDir = path.join(codexDir, 'skills');
+      installCodexSkills(gsdSrc, skillsDir, markdownEntries, pathPrefix);
+      console.log(`  ${green}✓${reset} Installed skills/gsd-*/SKILL.md (${markdownEntries.length} skills)`);
+    }
+
+    const skillSrc = path.join(src, 'get-shit-done');
+    const skillDest = path.join(codexDir, 'get-shit-done');
+    copyWithPathReplacement(skillSrc, skillDest, pathPrefix);
+    writeVersionFile(skillDest, isGlobal);
+    console.log(`  ${green}✓${reset} Installed get-shit-done/ workflow files`);
+    console.log(`  ${green}✓${reset} Wrote get-shit-done/VERSION (${pkg.version})`);
+
+    console.log(`
   ${green}Done!${reset}
 
   ${yellow}For Codex (CLI + Desktop):${reset}
   - AGENTS.md: ${cyan}${codexDir}/AGENTS.md${reset}
   ${installPromptsEnabled ? `- Prompt commands: ${cyan}${codexDir}/prompts/${reset}` : ''}
   ${installSkillsEnabled ? `- Native skills: ${cyan}${codexDir}/skills/gsd-*/SKILL.md${reset}` : ''}
+  - Config: ${cyan}${codexDir}/.codex/config.toml${reset}
+  - Agent defs: ${cyan}${codexDir}/agents/gsd-*.md${reset}
 
   ${yellow}Getting Started:${reset}
   1. Run ${cyan}codex${reset} (CLI) or ${cyan}codex app${reset} (Desktop)
@@ -554,7 +625,38 @@ function installCore(isGlobal, mode, migrationPlan, applyMigration) {
   ${yellow}Staying Updated:${reset}
   - In Codex: ${cyan}${installSkillsEnabled ? '$gsd-update' : '/prompts:gsd-update'}${reset}
   - In terminal: ${cyan}npx ${NPM_PACKAGE_LATEST}${reset}
+
+  ${dim}Note: Codex will prompt you to trust this project on first run
+  so that the config, agents, and MCP servers take effect.${reset}
 `);
+    done();
+  };
+
+  if (isGlobal && agentsExisted && isInteractiveTerminal) {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+    rl.question(`  ${yellow}⚠${reset} AGENTS.md already exists at ${dim}${agentsDest}${reset}. Overwrite? ${dim}[Y/n]${reset}: `, (answer) => {
+      rl.close();
+      const normalized = answer.trim().toLowerCase();
+      if (normalized === '' || normalized === 'y' || normalized === 'yes') {
+        writeAgents();
+        console.log(`  ${green}✓${reset} Overwrote AGENTS.md`);
+      } else {
+        console.log(`  ${yellow}⚠${reset} Kept existing AGENTS.md`);
+      }
+      continueAfterAgents();
+    });
+  } else {
+    writeAgents();
+    if (agentsExisted) {
+      console.log(`  ${yellow}⚠${reset} Overwrote existing AGENTS.md ${dim}(non-interactive)${reset}`);
+    } else {
+      console.log(`  ${green}✓${reset} Installed AGENTS.md`);
+    }
+    continueAfterAgents();
+  }
 }
 
 function install(isGlobal, mode = codexMode, done = () => {}) {
@@ -562,8 +664,7 @@ function install(isGlobal, mode = codexMode, done = () => {}) {
   const migrationPlan = detectMigrationPlan(codexDir, mode);
 
   if (!migrationPlan.hasChanges) {
-    installCore(isGlobal, mode, migrationPlan, false);
-    done();
+    installCore(isGlobal, mode, migrationPlan, false, done);
     return;
   }
 
@@ -572,23 +673,20 @@ function install(isGlobal, mode = codexMode, done = () => {}) {
 
   if (hasMigrate) {
     console.log(`  ${green}✓${reset} Migration approved by --migrate`);
-    installCore(isGlobal, mode, migrationPlan, true);
-    done();
+    installCore(isGlobal, mode, migrationPlan, true, done);
     return;
   }
 
   if (hasSkipMigrate) {
     console.log(`  ${yellow}Skipping migration due to --skip-migrate.${reset}`);
-    installCore(isGlobal, mode, migrationPlan, false);
-    done();
+    installCore(isGlobal, mode, migrationPlan, false, done);
     return;
   }
 
   if (!isInteractiveTerminal) {
     console.log(`  ${yellow}Skipping migration in non-interactive mode.${reset}`);
     console.log(`  ${dim}Re-run with --migrate to apply cleanup or --skip-migrate to keep legacy files explicitly.${reset}`);
-    installCore(isGlobal, mode, migrationPlan, false);
-    done();
+    installCore(isGlobal, mode, migrationPlan, false, done);
     return;
   }
 
@@ -604,8 +702,7 @@ function install(isGlobal, mode = codexMode, done = () => {}) {
     if (!applyMigration) {
       console.log(`  ${yellow}Keeping legacy files.${reset}`);
     }
-    installCore(isGlobal, mode, migrationPlan, applyMigration);
-    done();
+    installCore(isGlobal, mode, migrationPlan, applyMigration, done);
   });
 }
 

package/{AGENTS.md → get-shit-done/AGENTS.md}

@@ -1,6 +1,6 @@
 # get-shit-done-codex (GSD) - Agent Instructions
 
-A meta-prompting, context engineering and spec-driven development system for Codex CLI.
+A meta-prompting, context engineering and spec-driven development system for Codex CLI and Desktop.
 
 ## Overview
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@undeemed/get-shit-done-codex",
-  "version": "1.20.10",
+  "version": "1.21.0",
   "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"
@@ -16,7 +16,7 @@
     "agents",
     "hooks/dist",
     "scripts",
-    "AGENTS.md"
+    ".codex"
   ],
   "keywords": [
     "get-shit-done",