@undeemed/get-shit-done-codex

v1.24.3

Published

20 days ago

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.

get-shit-done-codex (Codex CLI/Desktop)

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

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

[!CAUTION] Codex is now supported upstream. This fork remains focused on Codex-specific UX, compatibility, and experimental features for personal use.

npm Downloads

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 each task runs in a fresh context with exactly what it needs. No accumulated garbage, no forgotten requirements.

graph TB
  subgraph codex["GSD-Codex"]
    direction TB
    A["AGENTS.md<br/><i>behavior contract</i>"] --> O["Thin Orchestrator<br/><i>30-40% context</i>"]
    C[".codex/config.toml<br/><i>agent roles + flags</i>"] --> O
    O -->|"spawn"| S1["gsd-planner<br/><i>fresh 200k context</i>"]
    O -->|"spawn"| S2["gsd-executor<br/><i>fresh 200k context</i>"]
    O -->|"spawn"| S3["gsd-verifier<br/><i>fresh 200k context</i>"]
    S1 -.->|"agents/gsd-planner.md<br/>loaded at spawn"| D1["700+ line<br/>role definition"]
    S2 -.->|"agents/gsd-executor.md"| D2["700+ line<br/>role definition"]
    S3 -.->|"agents/gsd-verifier.md"| D3["700+ line<br/>role definition"]
  end

  style codex fill:#1a1a2e,stroke:#00d4ff,color:#e0e0e0
  style A fill:#0d2137,stroke:#00d4ff,color:#e0e0e0
  style C fill:#0d2137,stroke:#00d4ff,color:#e0e0e0
  style O fill:#162447,stroke:#00d4ff,color:#e0e0e0
  style S1 fill:#1f4068,stroke:#1b998b,color:#e0e0e0
  style S2 fill:#1f4068,stroke:#1b998b,color:#e0e0e0
  style S3 fill:#1f4068,stroke:#1b998b,color:#e0e0e0
  style D1 fill:#0d2137,stroke:#444,color:#999
  style D2 fill:#0d2137,stroke:#444,color:#999
  style D3 fill:#0d2137,stroke:#444,color:#999

What Changed In This Fork

AGENTS-first for Codex: AGENTS.md is the primary behavior contract. Agent.md Info
Default Model is flagship: Codex 5.3 is used for all profile modes, but at different thinking levels. Model Profiles
Native skills: all commands use $gsd-* skill notation — no prompt aliases needed.
Full config distribution: installer ships .codex/config.toml (multi-agent, feature flags, MCP servers) and 11 rich agents/*.md sub-agent definitions — everything needed for multi-agent orchestration out of the box.
Sub-agent linking: each agent role in config.toml uses developer_instructions to load its full role definition from agents/gsd-*.md at runtime — no manual wiring needed.
Overwrite protection: config.toml is never overwritten on reinstall. AGENTS.md prompts for confirmation on global installs.
Installer integrity checks: --verify audits AGENTS.md, config.toml, agent definitions, command surfaces, and version metadata. --repair restores missing artifacts.
One-click trust: Codex prompts to trust the project on first run so the config takes effect.

Installation

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

You can install globally (~/.codex/) or locally (./).

npx @undeemed/get-shit-done-codex --global   # Install to ~/.codex/
npx @undeemed/get-shit-done-codex --local    # Install to current directory
npx @undeemed/get-shit-done-codex --path .   # Install to a specific directory
npx @undeemed/get-shit-done-codex --global --migrate             # Clean up legacy prompts/
npx @undeemed/get-shit-done-codex --verify --global              # Check install integrity
npx @undeemed/get-shit-done-codex --verify --repair --global     # Auto-repair

After installation, run codex (CLI) or codex app (Desktop), then run $gsd-help.

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 — native Codex skill commands
get-shit-done/ — workflow files, templates, and references

On first run, Codex may 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. You can manually update it later referencing the .codex/.toml in this repo.

Installed File Structure

~/.codex/
├── AGENTS.md
├── .codex/config.toml
├── agents/gsd-*.md
├── skills/gsd-*/SKILL.md
└── get-shit-done/

For local installs, replace ~/.codex/ with ./.

Verify And Repair

--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
- Non-interactive install skips cleanup unless --migrate is passed
- --skip-migrate keeps legacy files explicitly

AGENTS-First Reliability

This fork is intentionally AGENTS.md-first for Codex reliability:

AGENTS.md is the source of truth for behavior and workflow constraints
$gsd-* skills are lightweight command wrappers around the same workflow docs

Staying Updated

# Check for updates from inside Codex
$gsd-update

# Update from terminal
npx @undeemed/get-shit-done-codex@latest --global

The installer writes a get-shit-done/VERSION file so $gsd-update can detect installed vs latest and show changelog before updating.

npm Trusted Publisher (OIDC)

This repo includes a GitHub Actions publish workflow at:

.github/workflows/publish.yml

When setting up npm Trusted Publisher for this package, use:

Publisher: GitHub Actions
Organization or user: undeemed
Repository: get-shit-done-codex
Workflow filename: publish.yml
Environment name: leave blank (unless you later bind this workflow to a specific GitHub Environment)

Quick Start

# 1. Initialize project (questions → research → requirements → roadmap)
$gsd-new-project

# 2. Plan the first phase
$gsd-plan-phase 1

# 3. Execute the phase
$gsd-execute-phase 1

# 4. Verify it works
$gsd-verify-work 1

How It Works

1. Initialize Project

$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

$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

$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

$gsd-verify-work 1

Manual user acceptance testing. The system walks you through testable deliverables and creates fix plans if issues are found.

Commands

Core Workflow

| Command | Description | | -------------------------- | ----------------------------------------------------------------- | | $gsd-new-project | Initialize project: questions → research → requirements → roadmap | | $gsd-create-roadmap | Create roadmap and state tracking | | $gsd-map-codebase | Map existing codebase (brownfield projects) | | $gsd-plan-phase [N] | Research + plan + verify for a phase | | $gsd-execute-phase <N> | Execute all plans in parallel waves | | $gsd-execute-plan [path] | Execute a single PLAN.md file | | $gsd-verify-work [N] | Manual user acceptance testing | | $gsd-progress | Show current position and what's next | | $gsd-quick | Quick-start shortcut for small tasks |

Phase Management

| Command | Description | | --------------------------------- | ----------------------------------- | | $gsd-add-phase | Append phase to roadmap | | $gsd-insert-phase [N] | Insert urgent work at position N | | $gsd-remove-phase [N] | Remove a future phase | | $gsd-discuss-phase [N] | Gather context before planning | | $gsd-research-phase [N] | Deep ecosystem research for a phase | | $gsd-list-phase-assumptions [N] | Review assumptions before planning |

Milestones

| Command | Description | | --------------------------- | ------------------------------------ | | $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-audit-milestone | Audit milestone completeness | | $gsd-plan-milestone-gaps | Plan for gaps in current milestone |

Session & Debugging

| Command | Description | | ---------------------- | -------------------------------------- | | $gsd-pause-work | Create handoff when stopping mid-phase | | $gsd-resume-work | Restore from last session | | $gsd-consider-issues | Review deferred issues | | $gsd-plan-fix [plan] | Plan fixes for UAT issues | | $gsd-debug | Diagnose and debug issues | | $gsd-cleanup | Clean up planning artifacts |

Configuration & Utilities

| Command | Description | | ---------------------- | ------------------------------------------------------ | | $gsd-set-profile <P> | Switch model profile (quality, balanced, budget) | | $gsd-settings | View or edit project config | | $gsd-health | Project health check | | $gsd-add-tests | Add tests for a phase | | $gsd-add-todo | Add a todo item | | $gsd-check-todos | Review open todos | | $gsd-reapply-patches | Reapply saved patches | | $gsd-update | Check for and install updates | | $gsd-help | Show all commands |

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.

Sub-Agent Roles

GSD ships 11 specialized agent definitions in agents/gsd-*.md, each wired into config.toml via developer_instructions:

| Agent | Role | | -------------------------- | ---------------------------------------------------------- | | gsd-planner | Draft atomic PLAN.md files with tasks and success criteria | | gsd-executor | Execute plans with atomic commits and verification | | gsd-verifier | Goal-backward verification that outcomes are delivered | | gsd-debugger | Hypothesis testing, root cause isolation, fix proposals | | gsd-phase-researcher | Research implementation patterns for planners | | gsd-project-researcher | Ecosystem research for roadmap creation | | gsd-research-synthesizer | Synthesize parallel research into actionable inputs | | gsd-plan-checker | Stress-test plan quality and requirement coverage | | gsd-codebase-mapper | Map stack, architecture, and conventions | | gsd-roadmapper | Turn requirements into phased roadmaps | | gsd-integration-checker | Verify cross-phase wiring and e2e behavior |

Each agent gets its full role definition (700+ lines) loaded at spawn time — no context wasted on the orchestrator.

Model Profiles

All agents use gpt-5.3-codex with role-based thinking levels:

| Profile | Planner/Debugger | Executor/Verifier | Researchers/Mapper | | ---------- | ---------------- | ----------------- | ------------------ | | quality | 🔴 xhigh | 🟢 high | 🟢 high/🟡 medium | | balanced | 🔴 xhigh | 🟢 high | 🟡 medium | | budget | 🟢 high | 🟡 medium | 🟡 medium |

Switch profiles: $gsd-set-profile budget

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 to reload installed command surfaces
Check ~/.codex/skills/gsd-*/SKILL.md (global) or ./skills/gsd-*/SKILL.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:

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

Can users be notified when an update is available?

Yes. The installer prints an update notice if a newer npm version exists.
In-Codex update checks are available via $gsd-update.
For release notifications outside the CLI, enable GitHub release watching on this repo.

gsd-tools scripting tips

Use --cwd <path> (or --cwd=<path>) to target a specific project directory from automation scripts.
Use state json for machine-readable state; use state-snapshot for structured markdown-field extraction.
Use requirements mark-complete REQ-01 REQ-02 to update both requirement checkboxes and traceability rows.
If commit appears to skip unexpectedly, check .planning/config.json for commit_docs: false and also check user defaults in ~/.gsd/defaults.json.

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

Credits

Original project by TÂCHES. This fork adapts it for Codex CLI.

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

get-shit-done-codex (Codex CLI/Desktop)

What This Does

What Changed In This Fork

Installation

Recommended

What Gets Installed

Installed File Structure

Verify And Repair

AGENTS-First Reliability

Staying Updated

npm Trusted Publisher (OIDC)

Quick Start

How It Works

1. Initialize Project

2. Plan Phase

3. Execute Phase

4. Verify Work

Commands

Why It Works

Context Engineering

Multi-Agent Orchestration

Sub-Agent Roles

Model Profiles

Atomic Git Commits

Troubleshooting

More Documentation

Keywords

Credits

License