@undeemed/get-shit-done-codex 1.6.5

package/AGENTS.md

@@ -0,0 +1,183 @@
+# Get Shit Done (GSD) - Agent Instructions
+
+A meta-prompting, context engineering and spec-driven development system for Codex CLI.
+
+## Overview
+
+This system helps you build software projects by:
+
+1. **Deep context gathering** - Understanding what you want to build through structured questioning
+2. **Roadmap creation** - Breaking work into phases and plans
+3. **Autonomous execution** - Running atomic tasks with fresh context each time
+4. **State tracking** - Maintaining project state across sessions
+
+## Core Principles
+
+### Solo Developer Model
+
+- You are planning for ONE person (the user) and ONE implementer (the AI)
+- No teams, stakeholders, ceremonies, or coordination overhead
+- User is the visionary/product owner
+- AI is the builder
+- Estimate effort in AI execution time, not human dev time
+
+### Plans Are Prompts
+
+- PLAN.md IS the prompt that executes work
+- Contains: Objective, Context, Tasks, Success Criteria
+- When planning a phase, you are writing the prompt that will execute it
+
+### Scope Control
+
+**Quality degradation curve:**
+
+- 0-30% context: Peak quality
+- 30-50% context: Good quality
+- 50-70% context: Degrading quality
+- 70%+ context: Poor quality
+
+**Solution:** Aggressive atomicity - 2-3 tasks per plan maximum
+
+### Deviation Rules
+
+During execution:
+
+1. **Auto-fix bugs** - Fix immediately, document
+2. **Auto-add critical** - Security/correctness gaps, add immediately
+3. **Auto-fix blockers** - Can't proceed, fix immediately
+4. **Ask about architectural** - Major changes, stop and ask
+5. **Log enhancements** - Nice-to-haves, log to ISSUES.md, continue
+
+### Atomic Git Commits
+
+Each task gets its own commit immediately after completion:
+
+- Format: `{type}({phase}-{plan}): {task-description}`
+- Types: feat, fix, test, refactor, perf, chore, docs
+- One final metadata commit per plan
+
+## Directory Structure
+
+```
+.planning/
+├── PROJECT.md          # Project vision and requirements
+├── ROADMAP.md          # Phases from start to finish
+├── STATE.md            # Living memory across sessions
+├── ISSUES.md           # Deferred enhancements
+├── config.json         # Workflow mode and settings
+├── codebase/           # (brownfield) Codebase analysis
+│   ├── STACK.md
+│   ├── ARCHITECTURE.md
+│   ├── STRUCTURE.md
+│   ├── CONVENTIONS.md
+│   ├── TESTING.md
+│   ├── INTEGRATIONS.md
+│   └── CONCERNS.md
+└── phases/
+    └── XX-name/
+        ├── XX-NN-PLAN.md
+        └── XX-NN-SUMMARY.md
+```
+
+## Commands
+
+The following commands are available. Invoke them with `/gsd:command-name`:
+
+| Command                           | Description                                 |
+| --------------------------------- | ------------------------------------------- |
+| `/gsd:new-project`                | Initialize project through deep questioning |
+| `/gsd:create-roadmap`             | Create roadmap and state tracking           |
+| `/gsd:map-codebase`               | Map existing codebase (brownfield projects) |
+| `/gsd:plan-phase [N]`             | Generate task plans for phase N             |
+| `/gsd:execute-plan [path]`        | Execute a PLAN.md file                      |
+| `/gsd:progress`                   | Show current position and what's next       |
+| `/gsd:verify-work [N]`            | User acceptance testing                     |
+| `/gsd:plan-fix [plan]`            | Plan fixes for UAT issues                   |
+| `/gsd:complete-milestone`         | Archive milestone, prep next version        |
+| `/gsd:discuss-milestone`          | Gather context for next milestone           |
+| `/gsd:new-milestone [name]`       | Create new milestone with phases            |
+| `/gsd:add-phase`                  | Append phase to roadmap                     |
+| `/gsd:insert-phase [N]`           | Insert urgent work                          |
+| `/gsd:remove-phase [N]`           | Remove future phase                         |
+| `/gsd:discuss-phase [N]`          | Gather context before planning              |
+| `/gsd:research-phase [N]`         | Deep ecosystem research                     |
+| `/gsd:list-phase-assumptions [N]` | Review assumptions before planning          |
+| `/gsd:pause-work`                 | Create handoff when stopping mid-phase      |
+| `/gsd:resume-work`                | Restore from last session                   |
+| `/gsd:consider-issues`            | Review deferred issues                      |
+| `/gsd:help`                       | Show all commands                           |
+
+## Workflow
+
+### New Projects (Greenfield)
+
+```bash
+/gsd:new-project       # Deep questioning → PROJECT.md
+/gsd:create-roadmap    # Create ROADMAP.md and STATE.md
+/gsd:plan-phase 1      # Create atomic task plans
+/gsd:execute-plan      # Subagent executes autonomously
+```
+
+### Existing Projects (Brownfield)
+
+```bash
+/gsd:map-codebase      # Analyze existing code → codebase/
+/gsd:new-project       # Questioning with codebase context
+/gsd:create-roadmap    # Continue as normal
+```
+
+## File References
+
+When executing commands, reference these files for detailed instructions:
+
+- **Workflows:** `get-shit-done/workflows/*.md`
+- **Templates:** `get-shit-done/templates/*.md`
+- **References:** `get-shit-done/references/*.md`
+- **Commands:** `commands/gsd/*.md`
+
+## Anti-Patterns
+
+NEVER include:
+
+- Team structures, RACI matrices
+- Stakeholder management
+- Sprint ceremonies
+- Human dev time estimates
+- Change management processes
+- Documentation for documentation's sake
+
+If it sounds like corporate PM theater, delete it.
+
+## Context Engineering
+
+Always load relevant context files:
+
+- `.planning/PROJECT.md` - Project vision
+- `.planning/STATE.md` - Current position and decisions
+- `.planning/ROADMAP.md` - Phase structure
+- `.planning/config.json` - Mode settings
+
+For brownfield projects, also load:
+
+- `.planning/codebase/ARCHITECTURE.md`
+- `.planning/codebase/CONVENTIONS.md`
+- `.planning/codebase/STACK.md`
+
+## Test-Driven Development
+
+Use TDD when beneficial:
+
+- Business logic with defined inputs/outputs
+- API endpoints and handlers
+- Data transformations and parsing
+- Validation rules
+- State machines and workflows
+
+Skip TDD for:
+
+- UI layout and styling
+- Exploratory prototyping
+- One-off scripts and migrations
+- Configuration changes
+
+See `get-shit-done/references/tdd.md` for detailed TDD workflow.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Lex Christopherson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,179 @@
+# Get Shit Done (Codex CLI)
+
+A meta-prompting, context engineering and spec-driven development system for [OpenAI Codex CLI](https://github.com/openai/codex).
+
+Fork of [get-shit-done](https://github.com/taches/get-shit-done) by TÂCHES, adapted for Codex CLI by [undeemed](https://github.com/undeemed).
+
+[![npm version](https://img.shields.io/npm/v/%40undeemed%2Fget-shit-done-codex?style=flat-square)](https://www.npmjs.com/package/@undeemed/get-shit-done-codex)
+[![License](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)
+
+## What This Does
+
+GSD solves context rot — the quality degradation that happens as AI fills its context window. It structures your project through specs and plans so Codex CLI has what it needs to build reliably.
+
+**The problem:** AI assistants lose quality as conversations grow. Context gets polluted, requirements get forgotten, work becomes inconsistent.
+
+**The solution:** Hierarchical planning with fresh context windows. Each task runs in isolation with exactly the context it needs—no degradation from accumulated garbage.
+
+## Installation
+
+```bash
+npx @undeemed/get-shit-done-codex
+```
+
+You'll be prompted to install globally (`~/.codex/`) or locally (`./`).
+
+For non-interactive installs:
+
+```bash
+npx @undeemed/get-shit-done-codex --global   # Install to ~/.codex/
+npx @undeemed/get-shit-done-codex --local    # Install to current directory
+```
+
+After installation, run `codex` to start Codex CLI, then use `/prompts:gsd-help` to see all commands.
+
+## Quick Start
+
+```bash
+# 1. Initialize project (questions → research → requirements → roadmap)
+/prompts:gsd-new-project
+
+# 2. Plan the first phase
+/prompts:gsd-plan-phase 1
+
+# 3. Execute the phase
+/prompts:gsd-execute-phase 1
+
+# 4. Verify it works
+/prompts:gsd-verify-work 1
+```
+
+## How It Works
+
+### 1. Initialize Project
+
+```
+/prompts:gsd-new-project
+```
+
+One command takes you from idea to ready-for-planning:
+- Deep questioning to understand what you're building
+- Optional domain research (spawns 4 parallel researcher agents)
+- Requirements definition with v1/v2/out-of-scope scoping
+- Roadmap creation with phase breakdown
+
+**Creates:** `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, `.planning/research/`
+
+### 2. Plan Phase
+
+```
+/prompts:gsd-plan-phase 1
+```
+
+The system researches how to implement the phase, creates 2-3 atomic task plans, and verifies them against requirements.
+
+**Creates:** `{phase}-RESEARCH.md`, `{phase}-{N}-PLAN.md`
+
+### 3. Execute Phase
+
+```
+/prompts:gsd-execute-phase 1
+```
+
+Runs all plans in parallel waves. Each plan executes in a fresh 200k context window. Every task gets its own atomic commit.
+
+**Creates:** `{phase}-{N}-SUMMARY.md`, `{phase}-VERIFICATION.md`
+
+### 4. Verify Work
+
+```
+/prompts:gsd-verify-work 1
+```
+
+Manual user acceptance testing. The system walks you through testable deliverables and creates fix plans if issues are found.
+
+## Commands
+
+| Command                             | Description                                                       |
+|-------------------------------------|-------------------------------------------------------------------|
+| `/prompts:gsd-new-project`          | Initialize project: questions → research → requirements → roadmap |
+| `/prompts:gsd-plan-phase [N]`       | Research + plan + verify for a phase                              |
+| `/prompts:gsd-execute-phase <N>`    | Execute all plans in parallel waves                               |
+| `/prompts:gsd-verify-work [N]`      | Manual user acceptance testing                                    |
+| `/prompts:gsd-complete-milestone`   | Archive milestone, tag release                                    |
+| `/prompts:gsd-new-milestone [name]` | Start next version                                                |
+| `/prompts:gsd-progress`             | Show current status and what's next                               |
+| `/prompts:gsd-help`                 | Show all commands                                                 |
+
+See `/prompts:gsd-help` for the complete command reference.
+
+## Why It Works
+
+### Context Engineering
+
+GSD maintains structured context files that stay within quality limits:
+
+- `PROJECT.md` — Project vision, always loaded
+- `REQUIREMENTS.md` — Scoped v1/v2 requirements with phase traceability
+- `ROADMAP.md` — Where you're going, what's done
+- `STATE.md` — Decisions, blockers, position — memory across sessions
+- `PLAN.md` — Atomic task with XML structure, verification steps
+- `SUMMARY.md` — What happened, committed to history
+
+### Multi-Agent Orchestration
+
+Every stage uses a thin orchestrator that spawns specialized agents:
+
+- **Research** — 4 parallel researchers investigate stack, features, architecture, pitfalls
+- **Planning** — Planner creates plans, checker verifies, loops until pass
+- **Execution** — Executors implement in parallel, each with fresh 200k context
+- **Verification** — Verifier checks codebase against goals, debuggers diagnose failures
+
+The orchestrator stays at 30-40% context. The work happens in fresh subagent contexts.
+
+### Atomic Git Commits
+
+Each task gets its own commit immediately after completion:
+
+```bash
+feat(01-01): implement user authentication
+feat(01-01): add password hashing
+docs(01-01): complete auth-setup plan
+```
+
+Git bisect finds exact failing task. Each task independently revertable.
+
+## Troubleshooting
+
+**Commands not found?**
+- Restart Codex CLI to reload prompts
+- Check `~/.codex/prompts/gsd-*.md` (global) or `./prompts/gsd-*.md` (local)
+
+**Update to latest:**
+```bash
+npx get-shit-done-codex@latest
+```
+
+## More Documentation
+
+For deeper guides, detailed workflows, and comprehensive documentation, see the [original get-shit-done README](https://github.com/taches/get-shit-done/blob/main/README.md).
+
+The original repository contains:
+- Detailed workflow explanations
+- Advanced usage patterns
+- Complete command reference
+- Best practices and examples
+- Architecture and design principles
+
+**Note:** The original README is written for Claude Code. When following it, remember that this fork uses:
+- `/prompts:gsd-*` command format (instead of `/gsd:*`)
+- Codex CLI (instead of Claude Code)
+- `~/.codex/` directory (instead of `~/.claude/`)
+
+## Credits
+
+Original project by [TÂCHES](https://github.com/taches). This fork adapts it for Codex CLI.
+
+## License
+
+MIT

package/bin/install.js

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+
+// Colors
+const cyan = '\x1b[36m';
+const green = '\x1b[32m';
+const yellow = '\x1b[33m';
+const dim = '\x1b[2m';
+const reset = '\x1b[0m';
+
+// Get version from package.json
+const pkg = require('../package.json');
+
+const banner = `
+${cyan}   ██████╗ ███████╗██████╗  ██████╗
+   ██╔════╝ ██╔════╝██╔══██╗██╔════╝
+   ██║  ███╗███████╗██║  ██║██║
+   ██║   ██║╚════██║██║  ██║██║
+   ╚██████╔╝███████║██████╔╝╚██████╗
+    ╚═════╝ ╚══════╝╚═════╝  ╚═════╝${reset}
+
+   Get Shit Done ${dim}v${pkg.version}${reset}
+   A meta-prompting, context engineering and spec-driven
+   development system for OpenAI Codex CLI by TÂCHES.
+`;
+
+// Parse args
+const args = process.argv.slice(2);
+const hasGlobal = args.includes('--global') || args.includes('-g');
+const hasLocal = args.includes('--local') || args.includes('-l');
+const hasHelp = args.includes('--help') || args.includes('-h');
+
+console.log(banner);
+
+// Show help if requested
+if (hasHelp) {
+  console.log(`  ${yellow}Usage:${reset} npx get-shit-done-codex [options]
+
+  ${yellow}Options:${reset}
+    ${cyan}-g, --global${reset}              Install globally (to ~/.codex/)
+    ${cyan}-l, --local${reset}               Install locally (to current directory)
+    ${cyan}-h, --help${reset}                Show this help message
+
+  ${yellow}Examples:${reset}
+    ${dim}# Install globally to ~/.codex directory${reset}
+    npx get-shit-done-codex --global
+
+    ${dim}# Install to current project only${reset}
+    npx get-shit-done-codex --local
+
+  ${yellow}Notes:${reset}
+    For codex-cli, this installer:
+    - Creates/updates AGENTS.md in the target directory
+    - Copies the get-shit-done skill and commands
+    - Global install goes to ~/.codex/ (inherited by all projects)
+    - Local install puts files in current directory
+`);
+  process.exit(0);
+}
+
+/**
+ * Apply content replacements for Codex CLI compatibility
+ */
+function applyReplacements(content, pathPrefix) {
+  // Path replacements
+  content = content.replace(/~\/\.claude\//g, pathPrefix);
+  content = content.replace(/\.claude\//g, pathPrefix.replace('~/', ''));
+  
+  // Claude → Codex naming
+  content = content.replace(/Claude Code/g, 'Codex CLI');
+  content = content.replace(/Claude/g, 'Codex');
+  
+  // Command format: /gsd:name → /prompts:gsd-name (Codex CLI custom prompts format)
+  content = content.replace(/\/gsd:/g, '/prompts:gsd-');
+  
+  return content;
+}
+
+/**
+ * Recursively copy directory, replacing paths in .md files
+ */
+function copyWithPathReplacement(srcDir, destDir, pathPrefix) {
+  fs.mkdirSync(destDir, { recursive: true });
+
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+
+    if (entry.isDirectory()) {
+      copyWithPathReplacement(srcPath, destPath, pathPrefix);
+    } else if (entry.name.endsWith('.md')) {
+      let content = fs.readFileSync(srcPath, 'utf8');
+      content = applyReplacements(content, pathPrefix);
+      fs.writeFileSync(destPath, content);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * Install to the specified directory
+ */
+function install(isGlobal) {
+  const src = path.join(__dirname, '..');
+  const codexDir = isGlobal
+    ? path.join(os.homedir(), '.codex')
+    : process.cwd();
+
+  const locationLabel = isGlobal
+    ? '~/.codex'
+    : '.';
+
+  // Path prefix for file references
+  const pathPrefix = isGlobal
+    ? '~/.codex/'
+    : './';
+
+  console.log(`  Installing to ${cyan}${locationLabel}${reset}\n`);
+
+  // Create target directory if needed
+  fs.mkdirSync(codexDir, { recursive: true });
+
+  // Copy AGENTS.md
+  const agentsSrc = path.join(src, 'AGENTS.md');
+  const agentsDest = path.join(codexDir, 'AGENTS.md');
+  let agentsContent = fs.readFileSync(agentsSrc, 'utf8');
+  agentsContent = applyReplacements(agentsContent, pathPrefix);
+  fs.writeFileSync(agentsDest, agentsContent);
+  console.log(`  ${green}✓${reset} Installed AGENTS.md`);
+
+  // Create prompts directory (Codex CLI uses prompts/ for custom slash commands)
+  const promptsDir = path.join(codexDir, 'prompts');
+  fs.mkdirSync(promptsDir, { recursive: true });
+
+  // Copy commands/gsd as prompts (flatten the structure for Codex CLI)
+  // Codex CLI expects prompts/command-name.md format
+  const gsdSrc = path.join(src, 'commands', 'gsd');
+  const entries = fs.readdirSync(gsdSrc);
+  for (const entry of entries) {
+    if (entry.endsWith('.md')) {
+      const srcPath = path.join(gsdSrc, entry);
+      // Convert to gsd-command format (e.g., help.md -> gsd-help.md)
+      const destName = 'gsd-' + entry;
+      const destPath = path.join(promptsDir, destName);
+      let content = fs.readFileSync(srcPath, 'utf8');
+      content = applyReplacements(content, pathPrefix);
+      fs.writeFileSync(destPath, content);
+    }
+  }
+  console.log(`  ${green}✓${reset} Installed prompts/gsd-*.md (${entries.filter(e => e.endsWith('.md')).length} commands)`);
+
+  // Copy get-shit-done skill with path replacement
+  const skillSrc = path.join(src, 'get-shit-done');
+  const skillDest = path.join(codexDir, 'get-shit-done');
+  copyWithPathReplacement(skillSrc, skillDest, pathPrefix);
+  console.log(`  ${green}✓${reset} Installed get-shit-done`);
+
+  console.log(`
+  ${green}Done!${reset} 
+  
+  ${yellow}For Codex CLI:${reset}
+  - AGENTS.md is at ${cyan}${codexDir}/AGENTS.md${reset}
+  - Slash commands are in ${cyan}${codexDir}/prompts/${reset}
+  
+  ${yellow}Getting Started:${reset}
+  1. Run ${cyan}codex${reset} to start the Codex CLI
+  2. Type ${cyan}/${reset} to see available commands
+  3. Start with ${cyan}/prompts:gsd-new-project${reset} to initialize a project
+
+  ${dim}Commands use /prompts:gsd-name format (e.g., /prompts:gsd-help)${reset}
+`);
+}
+
+/**
+ * Prompt for install location
+ */
+function promptLocation() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  console.log(`  ${yellow}Where would you like to install?${reset}
+
+  ${cyan}1${reset}) Global ${dim}(~/.codex)${reset} - available in all projects
+  ${cyan}2${reset}) Local  ${dim}(.)${reset} - this project only
+`);
+
+  rl.question(`  Choice ${dim}[1]${reset}: `, (answer) => {
+    rl.close();
+    const choice = answer.trim() || '1';
+    const isGlobal = choice !== '2';
+    install(isGlobal);
+  });
+}
+
+// Main
+if (hasGlobal && hasLocal) {
+  console.error(`  ${yellow}Cannot specify both --global and --local${reset}`);
+  process.exit(1);
+} else if (hasGlobal) {
+  install(true);
+} else if (hasLocal) {
+  install(false);
+} else {
+  promptLocation();
+}