get-shit-done-codex (Codex CLI)

A meta-prompting, context engineering and spec-driven development system for OpenAI Codex CLI.

Fork of get-shit-done by TÂCHES, adapted for Codex CLI by undeemed.

What This Does

get-shit-done-codex (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

npx @undeemed/get-shit-done-codex

You'll be prompted to install globally (~/.codex/) or locally (./).

For non-interactive installs:

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

# 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:

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:

npx @undeemed/get-shit-done-codex@latest

More Documentation

For deeper guides, detailed workflows, and comprehensive documentation, see the original get-shit-done README.

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. This fork adapts it for Codex CLI.

License

MIT