@undeemed/get-shit-done-codex 1.6.12 → 1.20.3

package/get-shit-done/templates/user-setup.md

@@ -1,8 +1,8 @@
 # User Setup Template
 
-Template for `.planning/phases/XX-name/{phase}-USER-SETUP.md` - human-required configuration that Claude cannot automate.
+Template for `.planning/phases/XX-name/{phase}-USER-SETUP.md` - human-required configuration that Codex cannot automate.
 
-**Purpose:** Document setup tasks that literally require human action - account creation, dashboard configuration, secret retrieval. Claude automates everything possible; this file captures only what remains.
+**Purpose:** Document setup tasks that literally require human action - account creation, dashboard configuration, secret retrieval. Codex automates everything possible; this file captures only what remains.
 
 ---
 
@@ -15,7 +15,7 @@ Template for `.planning/phases/XX-name/{phase}-USER-SETUP.md` - human-required c
 **Phase:** {phase-name}
 **Status:** Incomplete
 
-Complete these items for the integration to function. Claude automated everything possible; these items require human access to external dashboards/accounts.
+Complete these items for the integration to function. Codex automated everything possible; these items require human access to external dashboards/accounts.
 
 ## Environment Variables
 
@@ -97,9 +97,9 @@ user_setup:
 
 ## The Automation-First Rule
 
-**USER-SETUP.md contains ONLY what Claude literally cannot do.**
+**USER-SETUP.md contains ONLY what Codex literally cannot do.**
 
-| Claude CAN Do (not in USER-SETUP) | Claude CANNOT Do (→ USER-SETUP) |
+| Codex CAN Do (not in USER-SETUP) | Codex CANNOT Do (→ USER-SETUP) |
 |-----------------------------------|--------------------------------|
 | `npm install stripe` | Create Stripe account |
 | Write webhook handler code | Get API keys from dashboard |
@@ -108,9 +108,9 @@ user_setup:
 | Configure package.json | Access external service dashboards |
 | Write any code | Retrieve secrets from third-party systems |
 
-**The test:** "Does this require a human in a browser, accessing an account Claude doesn't have credentials for?"
+**The test:** "Does this require a human in a browser, accessing an account Codex doesn't have credentials for?"
 - Yes → USER-SETUP.md
-- No → Claude does it automatically
+- No → Codex does it automatically
 
 ---
 
@@ -304,20 +304,8 @@ curl -X POST http://localhost:3000/api/test-email \
 
 ## Guidelines
 
-**Include in USER-SETUP.md:**
-- Environment variable names and where to find values
-- Account creation URLs (if new service)
-- Dashboard configuration steps
-- Verification commands to confirm setup works
-- Local development alternatives (e.g., `stripe listen`)
-
-**Do NOT include:**
-- Actual secret values (never)
-- Steps Claude can automate (package installs, code changes, file creation)
-- Generic instructions ("set up your environment")
+**Never include:** Actual secret values. Steps Codex can automate (package installs, code changes).
 
 **Naming:** `{phase}-USER-SETUP.md` matches the phase number pattern.
-
 **Status tracking:** User marks checkboxes and updates status line when complete.
-
 **Searchability:** `grep -r "USER-SETUP" .planning/` finds all phases with user requirements.

package/get-shit-done/templates/verification-report.md

@@ -1,6 +1,6 @@
 # Verification Report Template
 
-Template for `.planning/phases/XX-name/{phase}-VERIFICATION.md` — phase goal verification results.
+Template for `.planning/phases/XX-name/{phase_num}-VERIFICATION.md` — phase goal verification results.
 
 ---
 
@@ -154,7 +154,7 @@ None — all verifiable items checked programmatically.
 
 ---
 *Verified: {timestamp}*
-*Verifier: Claude (subagent)*
+*Verifier: Codex (subagent)*
 ```
 
 ---
@@ -318,5 +318,5 @@ None needed until automated gaps are fixed.
 
 ---
 *Verified: 2025-01-15T14:30:00Z*
-*Verifier: Claude (subagent)*
+*Verifier: Codex (subagent)*
 ```

package/get-shit-done/workflows/add-phase.md

@@ -0,0 +1,111 @@
+<purpose>
+Add a new integer phase to the end of the current milestone in the roadmap. Automatically calculates next phase number, creates phase directory, and updates roadmap structure.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="parse_arguments">
+Parse the command arguments:
+- All arguments become the phase description
+- Example: `/gsd:add-phase Add authentication` → description = "Add authentication"
+- Example: `/gsd:add-phase Fix critical performance issues` → description = "Fix critical performance issues"
+
+If no arguments provided:
+
+```
+ERROR: Phase description required
+Usage: /gsd:add-phase <description>
+Example: /gsd:add-phase Add authentication system
+```
+
+Exit.
+</step>
+
+<step name="init_context">
+Load phase operation context:
+
+```bash
+INIT=$(node ~/.codex/get-shit-done/bin/gsd-tools.cjs init phase-op "0")
+```
+
+Check `roadmap_exists` from init JSON. If false:
+```
+ERROR: No roadmap found (.planning/ROADMAP.md)
+Run /gsd:new-project to initialize.
+```
+Exit.
+</step>
+
+<step name="add_phase">
+**Delegate the phase addition to gsd-tools:**
+
+```bash
+RESULT=$(node ~/.codex/get-shit-done/bin/gsd-tools.cjs phase add "${description}")
+```
+
+The CLI handles:
+- Finding the highest existing integer phase number
+- Calculating next phase number (max + 1)
+- Generating slug from description
+- Creating the phase directory (`.planning/phases/{NN}-{slug}/`)
+- Inserting the phase entry into ROADMAP.md with Goal, Depends on, and Plans sections
+
+Extract from result: `phase_number`, `padded`, `name`, `slug`, `directory`.
+</step>
+
+<step name="update_project_state">
+Update STATE.md to reflect the new phase:
+
+1. Read `.planning/STATE.md`
+2. Under "## Accumulated Context" → "### Roadmap Evolution" add entry:
+   ```
+   - Phase {N} added: {description}
+   ```
+
+If "Roadmap Evolution" section doesn't exist, create it.
+</step>
+
+<step name="completion">
+Present completion summary:
+
+```
+Phase {N} added to current milestone:
+- Description: {description}
+- Directory: .planning/phases/{phase-num}-{slug}/
+- Status: Not planned yet
+
+Roadmap updated: .planning/ROADMAP.md
+
+---
+
+## ▶ Next Up
+
+**Phase {N}: {description}**
+
+`/gsd:plan-phase {N}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/gsd:add-phase <description>` — add another phase
+- Review roadmap
+
+---
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] `gsd-tools phase add` executed successfully
+- [ ] Phase directory created
+- [ ] Roadmap updated with new phase entry
+- [ ] STATE.md updated with roadmap evolution note
+- [ ] User informed of next steps
+</success_criteria>

package/get-shit-done/workflows/add-todo.md

@@ -0,0 +1,157 @@
+<purpose>
+Capture an idea, task, or issue that surfaces during a GSD session as a structured todo for later work. Enables "thought → capture → continue" flow without losing context.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="init_context">
+Load todo context:
+
+```bash
+INIT=$(node ~/.codex/get-shit-done/bin/gsd-tools.cjs init todos)
+```
+
+Extract from init JSON: `commit_docs`, `date`, `timestamp`, `todo_count`, `todos`, `pending_dir`, `todos_dir_exists`.
+
+Ensure directories exist:
+```bash
+mkdir -p .planning/todos/pending .planning/todos/done
+```
+
+Note existing areas from the todos array for consistency in infer_area step.
+</step>
+
+<step name="extract_content">
+**With arguments:** Use as the title/focus.
+- `/gsd:add-todo Add auth token refresh` → title = "Add auth token refresh"
+
+**Without arguments:** Analyze recent conversation to extract:
+- The specific problem, idea, or task discussed
+- Relevant file paths mentioned
+- Technical details (error messages, line numbers, constraints)
+
+Formulate:
+- `title`: 3-10 word descriptive title (action verb preferred)
+- `problem`: What's wrong or why this is needed
+- `solution`: Approach hints or "TBD" if just an idea
+- `files`: Relevant paths with line numbers from conversation
+</step>
+
+<step name="infer_area">
+Infer area from file paths:
+
+| Path pattern | Area |
+|--------------|------|
+| `src/api/*`, `api/*` | `api` |
+| `src/components/*`, `src/ui/*` | `ui` |
+| `src/auth/*`, `auth/*` | `auth` |
+| `src/db/*`, `database/*` | `database` |
+| `tests/*`, `__tests__/*` | `testing` |
+| `docs/*` | `docs` |
+| `.planning/*` | `planning` |
+| `scripts/*`, `bin/*` | `tooling` |
+| No files or unclear | `general` |
+
+Use existing area from step 2 if similar match exists.
+</step>
+
+<step name="check_duplicates">
+```bash
+# Search for key words from title in existing todos
+grep -l -i "[key words from title]" .planning/todos/pending/*.md 2>/dev/null
+```
+
+If potential duplicate found:
+1. Read the existing todo
+2. Compare scope
+
+If overlapping, use AskUserQuestion:
+- header: "Duplicate?"
+- question: "Similar todo exists: [title]. What would you like to do?"
+- options:
+  - "Skip" — keep existing todo
+  - "Replace" — update existing with new context
+  - "Add anyway" — create as separate todo
+</step>
+
+<step name="create_file">
+Use values from init context: `timestamp` and `date` are already available.
+
+Generate slug for the title:
+```bash
+slug=$(node ~/.codex/get-shit-done/bin/gsd-tools.cjs generate-slug "$title" --raw)
+```
+
+Write to `.planning/todos/pending/${date}-${slug}.md`:
+
+```markdown
+---
+created: [timestamp]
+title: [title]
+area: [area]
+files:
+  - [file:lines]
+---
+
+## Problem
+
+[problem description - enough context for future Codex to understand weeks later]
+
+## Solution
+
+[approach hints or "TBD"]
+```
+</step>
+
+<step name="update_state">
+If `.planning/STATE.md` exists:
+
+1. Use `todo_count` from init context (or re-run `init todos` if count changed)
+2. Update "### Pending Todos" under "## Accumulated Context"
+</step>
+
+<step name="git_commit">
+Commit the todo and any updated state:
+
+```bash
+node ~/.codex/get-shit-done/bin/gsd-tools.cjs commit "docs: capture todo - [title]" --files .planning/todos/pending/[filename] .planning/STATE.md
+```
+
+Tool respects `commit_docs` config and gitignore automatically.
+
+Confirm: "Committed: docs: capture todo - [title]"
+</step>
+
+<step name="confirm">
+```
+Todo saved: .planning/todos/pending/[filename]
+
+  [title]
+  Area: [area]
+  Files: [count] referenced
+
+---
+
+Would you like to:
+
+1. Continue with current work
+2. Add another todo
+3. View all todos (/gsd:check-todos)
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Directory structure exists
+- [ ] Todo file created with valid frontmatter
+- [ ] Problem section has enough context for future Codex
+- [ ] No duplicates (checked and resolved)
+- [ ] Area consistent with existing todos
+- [ ] STATE.md updated if exists
+- [ ] Todo and state committed to git
+</success_criteria>

package/get-shit-done/workflows/audit-milestone.md

@@ -0,0 +1,242 @@
+<purpose>
+Verify milestone achieved its definition of done by aggregating phase verifications, checking cross-phase integration, and assessing requirements coverage. Reads existing VERIFICATION.md files (phases already verified during execute-phase), aggregates tech debt and deferred gaps, then spawns integration checker for cross-phase wiring.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+## 0. Initialize Milestone Context
+
+```bash
+INIT=$(node ~/.codex/get-shit-done/bin/gsd-tools.cjs init milestone-op)
+```
+
+Extract from init JSON: `milestone_version`, `milestone_name`, `phase_count`, `completed_phases`, `commit_docs`.
+
+Resolve integration checker model:
+```bash
+CHECKER_MODEL=$(node ~/.codex/get-shit-done/bin/gsd-tools.cjs resolve-model gsd-integration-checker --raw)
+```
+
+## 1. Determine Milestone Scope
+
+```bash
+# Get phases in milestone (sorted numerically, handles decimals)
+node ~/.codex/get-shit-done/bin/gsd-tools.cjs phases list
+```
+
+- Parse version from arguments or detect current from ROADMAP.md
+- Identify all phase directories in scope
+- Extract milestone definition of done from ROADMAP.md
+- Extract requirements mapped to this milestone from REQUIREMENTS.md
+
+## 2. Read All Phase Verifications
+
+For each phase directory, read the VERIFICATION.md:
+
+```bash
+# For each phase, use find-phase to resolve the directory (handles archived phases)
+PHASE_INFO=$(node ~/.codex/get-shit-done/bin/gsd-tools.cjs find-phase 01 --raw)
+# Extract directory from JSON, then read VERIFICATION.md from that directory
+# Repeat for each phase number from ROADMAP.md
+```
+
+From each VERIFICATION.md, extract:
+- **Status:** passed | gaps_found
+- **Critical gaps:** (if any — these are blockers)
+- **Non-critical gaps:** tech debt, deferred items, warnings
+- **Anti-patterns found:** TODOs, stubs, placeholders
+- **Requirements coverage:** which requirements satisfied/blocked
+
+If a phase is missing VERIFICATION.md, flag it as "unverified phase" — this is a blocker.
+
+## 3. Spawn Integration Checker
+
+With phase context collected:
+
+```
+Task(
+  prompt="Check cross-phase integration and E2E flows.
+
+Phases: {phase_dirs}
+Phase exports: {from SUMMARYs}
+API routes: {routes created}
+
+Verify cross-phase wiring and E2E user flows.",
+  subagent_type="gsd-integration-checker",
+  model="{integration_checker_model}"
+)
+```
+
+## 4. Collect Results
+
+Combine:
+- Phase-level gaps and tech debt (from step 2)
+- Integration checker's report (wiring gaps, broken flows)
+
+## 5. Check Requirements Coverage
+
+For each requirement in REQUIREMENTS.md mapped to this milestone:
+- Find owning phase
+- Check phase verification status
+- Determine: satisfied | partial | unsatisfied
+
+## 6. Aggregate into v{version}-MILESTONE-AUDIT.md
+
+Create `.planning/v{version}-v{version}-MILESTONE-AUDIT.md` with:
+
+```yaml
+---
+milestone: {version}
+audited: {timestamp}
+status: passed | gaps_found | tech_debt
+scores:
+  requirements: N/M
+  phases: N/M
+  integration: N/M
+  flows: N/M
+gaps:  # Critical blockers
+  requirements: [...]
+  integration: [...]
+  flows: [...]
+tech_debt:  # Non-critical, deferred
+  - phase: 01-auth
+    items:
+      - "TODO: add rate limiting"
+      - "Warning: no password strength validation"
+  - phase: 03-dashboard
+    items:
+      - "Deferred: mobile responsive layout"
+---
+```
+
+Plus full markdown report with tables for requirements, phases, integration, tech debt.
+
+**Status values:**
+- `passed` — all requirements met, no critical gaps, minimal tech debt
+- `gaps_found` — critical blockers exist
+- `tech_debt` — no blockers but accumulated deferred items need review
+
+## 7. Present Results
+
+Route by status (see `<offer_next>`).
+
+</process>
+
+<offer_next>
+Output this markdown directly (not as a code block). Route based on status:
+
+---
+
+**If passed:**
+
+## ✓ Milestone {version} — Audit Passed
+
+**Score:** {N}/{M} requirements satisfied
+**Report:** .planning/v{version}-MILESTONE-AUDIT.md
+
+All requirements covered. Cross-phase integration verified. E2E flows complete.
+
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Complete milestone** — archive and tag
+
+/gsd:complete-milestone {version}
+
+<sub>/clear first → fresh context window</sub>
+
+───────────────────────────────────────────────────────────────
+
+---
+
+**If gaps_found:**
+
+## ⚠ Milestone {version} — Gaps Found
+
+**Score:** {N}/{M} requirements satisfied
+**Report:** .planning/v{version}-MILESTONE-AUDIT.md
+
+### Unsatisfied Requirements
+
+{For each unsatisfied requirement:}
+- **{REQ-ID}: {description}** (Phase {X})
+  - {reason}
+
+### Cross-Phase Issues
+
+{For each integration gap:}
+- **{from} → {to}:** {issue}
+
+### Broken Flows
+
+{For each flow gap:}
+- **{flow name}:** breaks at {step}
+
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Plan gap closure** — create phases to complete milestone
+
+/gsd:plan-milestone-gaps
+
+<sub>/clear first → fresh context window</sub>
+
+───────────────────────────────────────────────────────────────
+
+**Also available:**
+- cat .planning/v{version}-MILESTONE-AUDIT.md — see full report
+- /gsd:complete-milestone {version} — proceed anyway (accept tech debt)
+
+───────────────────────────────────────────────────────────────
+
+---
+
+**If tech_debt (no blockers but accumulated debt):**
+
+## ⚡ Milestone {version} — Tech Debt Review
+
+**Score:** {N}/{M} requirements satisfied
+**Report:** .planning/v{version}-MILESTONE-AUDIT.md
+
+All requirements met. No critical blockers. Accumulated tech debt needs review.
+
+### Tech Debt by Phase
+
+{For each phase with debt:}
+**Phase {X}: {name}**
+- {item 1}
+- {item 2}
+
+### Total: {N} items across {M} phases
+
+───────────────────────────────────────────────────────────────
+
+## ▶ Options
+
+**A. Complete milestone** — accept debt, track in backlog
+
+/gsd:complete-milestone {version}
+
+**B. Plan cleanup phase** — address debt before completing
+
+/gsd:plan-milestone-gaps
+
+<sub>/clear first → fresh context window</sub>
+
+───────────────────────────────────────────────────────────────
+</offer_next>
+
+<success_criteria>
+- [ ] Milestone scope identified
+- [ ] All phase VERIFICATION.md files read
+- [ ] Tech debt and deferred gaps aggregated
+- [ ] Integration checker spawned for cross-phase wiring
+- [ ] v{version}-MILESTONE-AUDIT.md created
+- [ ] Results presented with actionable next steps
+</success_criteria>