codexkit 1.0.0

package/.codex/prompts/ship.md

@@ -0,0 +1,334 @@
+---
+description: Ship a bead - implement PRD tasks, verify, review, close
+argument-hint: "<bead-id>"
+agent: build
+---
+
+# Ship: $ARGUMENTS
+
+Execute PRD tasks, verify each gate passes, run review, then request close approval.
+
+> **Workflow:** `/prompts:create` → `/prompts:start <id>` → **`/prompts:ship <id>`**
+>
+> Task must be `in_progress` with `prd.md` present.
+
+## Load Skills
+
+- `$beads` — bead lifecycle and br CLI
+- `$verification-before-completion` — evidence-based completion
+- `$executing-plans` — wave-based plan execution (if plan.md exists)
+- `$requesting-code-review` — multi-agent review dispatch
+
+## Determine Input Type
+
+| Input Type | Detection                   | Action                       |
+| ---------- | --------------------------- | ---------------------------- |
+| Bead ID    | Matches `br-xxx` or numeric | Ship that bead               |
+| Path       | File/directory path         | Not supported for ship       |
+| `all`      | Keyword                     | Ship all `in_progress` beads |
+
+## Before You Ship
+
+- **Be certain**: Only ship when all tasks and gates pass.
+- **Do not skip gates**: typecheck, lint, test, build are required.
+- **Run review** before completion.
+- **Verify goals, not only tasks** (goal-backward checks).
+- **Keep commit history clear**: per-task commits.
+- **Ask before close**: never close task state without user confirmation.
+- **Use native Codex planning/research inline** when extra decomposition or investigation is needed.
+
+## Available Tools
+
+| Tool  | Use When                                  |
+| ----- | ----------------------------------------- |
+| `br`  | Task metadata, comments, close/sync       |
+| `git` | Branch, commits, diffs, verification prep |
+| `grep`| Stub checks and key-link checks           |
+
+## Phase 0: Bootstrap Beads
+
+```bash
+.codex/scripts/ensure_beads.sh
+```
+
+If bootstrap fails because `br` is missing, stop and show the install error clearly.
+
+## Phase 1: Guards
+
+```bash
+br show $ARGUMENTS
+ls .beads/artifacts/$ARGUMENTS/
+```
+
+Verify:
+
+- Status is `in_progress`
+- `.beads/artifacts/$ARGUMENTS/prd.md` exists
+
+Read current memory context before execution:
+
+- `.codex/memory/project/state.md` for durable blockers and current state
+- `.codex/context/session-context.md` for the latest exact stop point
+- `.codex/context/worklog.md` for recent session trail if needed
+
+If either fails, stop and route user to `/prompts:start $ARGUMENTS` or `/prompts:create`.
+
+## Phase 2: Route to Execution
+
+| Artifact exists | Action                                                   |
+| --------------- | -------------------------------------------------------- |
+| `plan.md`       | Follow existing wave/dependency execution from plan      |
+| `prd.json`      | Execute PRD task loop directly                           |
+| Only `prd.md`   | Convert to `prd.json` first using `$prd-task`, then loop |
+
+If no `plan.md` exists and extra decomposition is needed, do the planning inline in this session rather than routing the user to a separate planning prompt.
+
+## Phase 3: Wave-Based Execution
+
+If `plan.md` defines waves:
+
+1. Execute wave-by-wave.
+2. Single-task wave: execute directly.
+3. Multi-task wave: execute tasks in parallel only when file-disjoint.
+4. After each wave: run verification gates and review checkpoint.
+
+Wave review checkpoint:
+
+- confirm completed tasks actually produced the expected files or behavior
+- confirm no later-wave task started early
+- confirm changed files remain within the wave's declared scope
+
+### Phase 3A: PRD Task Loop
+
+For each task:
+
+1. Read task description and verification steps.
+2. Read listed files before editing.
+3. Implement minimal in-scope changes.
+4. Apply deviation rules (auto-fix Rules 1-3, stop on Rule 4).
+5. Handle `checkpoint:*` if present.
+6. Run task verification commands.
+7. If verification fails, fix and retry (max 2 attempts).
+8. Commit per task.
+9. Mark task pass status in `prd.json`.
+10. Append progress to `.beads/artifacts/$ARGUMENTS/progress.txt`.
+
+### Checkpoint Protocol
+
+| Type                      | Action                                                     |
+| ------------------------- | ---------------------------------------------------------- |
+| `checkpoint:human-verify` | Automate checks first, then pause for user verification    |
+| `checkpoint:decision`     | Present options, wait for explicit selection               |
+| `checkpoint:human-action` | Request specific action and provide verification command   |
+
+**Checkpoint format:**
+
+```markdown
+## CHECKPOINT REACHED
+
+**Type:** [human-verify | decision | human-action]
+**Progress:** X/Y tasks complete
+
+### Completed
+
+| Task | Commit | Status |
+| ---- | ------ | ------ |
+| [N]  | [hash] | [✓/✗]  |
+
+### Current Task
+
+**Task:** [name]
+**Blocked by:** [specific blocker]
+
+### Awaiting
+
+[What user needs to do/provide]
+```
+
+### TDD Execution Flow
+
+**RED**
+1. Add failing test
+2. Run test (must fail)
+3. Commit: `test: add failing test for [feature]`
+
+**GREEN**
+1. Implement minimal fix
+2. Run test (must pass)
+3. Commit: `feat: implement [feature]`
+
+**REFACTOR** (optional)
+1. Clean up without behavior change
+2. Run tests (must remain green)
+3. Commit: `refactor: clean up [feature]`
+
+### Task Commit Protocol
+
+1. `git status --short`
+2. Stage task files individually (never `git add .`)
+3. Commit with type prefix:
+
+```bash
+git commit -m "feat(bead-$ARGUMENTS): <task description>
+
+- <key change 1>
+- <key change 2>"
+```
+
+Commit types:
+
+| Type       | Use For                                 |
+| ---------- | --------------------------------------- |
+| `feat`     | New user-visible behavior               |
+| `fix`      | Bug fix                                 |
+| `test`     | Test-only changes                       |
+| `refactor` | Internal cleanup, no behavior change    |
+| `chore`    | Tooling/config/dependency updates       |
+
+### Stop Conditions
+
+- Same task verification fails twice
+- Dependency task incomplete
+- Changes required outside task scope
+- Rule 4 architectural decision required
+
+## Phase 4: Verification
+
+Run full verification using project-appropriate gates:
+
+- Typecheck
+- Lint
+- Test
+- Build
+
+Also run all `Verify:` commands listed in PRD artifacts.
+
+Preferred direct helper:
+
+```bash
+.codex/scripts/verify_bead.sh $ARGUMENTS --full
+```
+
+Completion checklist before closing:
+
+- [ ] All wave checkpoints passed
+- [ ] All declared `Verify:` commands were executed
+- [ ] Review findings were triaged
+- [ ] Goal-backward Exists/Substantive/Wired checks passed
+- [ ] Durable memory artifacts were updated in the correct home if the work changed state, blockers, or learnings
+- [ ] User approval obtained before bead close
+
+## Phase 6: Review
+
+Load and run `$requesting-code-review`. Dispatch **5 parallel review agents**, each covering one lens:
+
+1. Security + correctness
+2. Performance + architecture fit
+3. Type safety + test quality
+4. Conventions + consistency
+5. Simplicity + completeness
+
+```bash
+base_sha=$(git rev-parse origin/main 2>/dev/null || git rev-parse HEAD~1)
+head_sha=$(git rev-parse HEAD)
+```
+
+Provide each agent with:
+
+- `{WHAT_WAS_IMPLEMENTED}`: bead title + change summary
+- `{PLAN_OR_REQUIREMENTS}`: `.beads/artifacts/$ARGUMENTS/prd.md`
+- `{BASE_SHA}` / `{HEAD_SHA}`: from above
+
+Wait for all 5 to return. Synthesize findings:
+
+- **Critical**: fix inline, re-run Phase 4 verification
+- **Important**: fix inline when low-risk
+- **Minor**: capture as follow-up in bead comments
+
+If critical issues require architectural decisions, stop and present options.
+
+## Phase 6B: Goal-Backward Verification
+
+Three-level verification:
+
+| Level              | Check                  | Command/Action                                                    |
+| ------------------ | ---------------------- | ----------------------------------------------------------------- |
+| **1: Exists**      | File is present        | `ls path/to/file.ts`                                              |
+| **2: Substantive** | Not a stub/placeholder | `grep -v "TODO\|FIXME\|return null\|placeholder" path/to/file.ts` |
+| **3: Wired**       | Connected and used     | `grep -r "import.*ComponentName" src/`                            |
+
+Key-link checks:
+
+- Component → API: `grep -E "fetch.*api/|axios" Component.tsx`
+- API → Data layer: `grep -E "prisma\.|db\." route.ts`
+- Form → Handler: `grep "onSubmit" Component.tsx`
+- State → Render: `grep "{stateVar}" Component.tsx`
+
+Stub red flags:
+
+```javascript
+return <div>Component</div>
+return <div>{/* TODO */}</div>
+return null
+onClick={() => {}}
+fetch('/api/...')
+return Response.json({ ok: true })
+```
+
+If Level 2/3 fails, fix and re-verify.
+
+## Phase 7: Close
+
+> **Choose one:**
+> 1. **Close bead (Recommended)** — All tasks complete, all gates pass, review clear.
+> 2. **Keep open** — Additional changes required.
+
+Before closing, route any lasting learnings or state changes:
+
+- `session-context.md` only if the bead remains open and needs a precise restart point
+- `worklog.md` for a concise session milestone
+- `memory/project/state.md` for durable current state / blockers
+- `decision-log.md` only for true architecture or workflow decisions with rationale
+- `/prompts:compound` if the work produced reusable learnings worth preserving
+
+If user confirms close:
+
+```bash
+.codex/scripts/close_bead.sh $ARGUMENTS --reason "Shipped: PRD tasks complete, verification and review passed"
+```
+
+## Output
+
+Report with six sections:
+
+1. **Execution Summary**
+   - Tasks completed/total
+   - Waves executed
+   - Deviations applied
+   - Checkpoints encountered
+   - Commits made
+2. **PRD Task Results**
+   - Per-task pass/fail/checkpoint
+   - Files modified
+   - Commit hashes
+3. **Verification Gate Results**
+   - Typecheck/Lint/Test/Build status
+4. **Goal-Backward Verification**
+   - Exists/Substantive/Wired counts
+   - Key-link check outcomes
+   - Stub detections
+5. **Review Summary**
+   - Critical/Important/Minor counts
+   - Overall assessment
+6. **Next Steps**
+   - `/prompts:pr` for PR
+   - Follow-up tasks for deferred items
+
+## Related Commands
+
+| Need        | Command              |
+| ----------- | -------------------- |
+| Create spec | `/prompts:create`    |
+| Claim task  | `/prompts:start <id>` |
+| Verify only | `/prompts:verify <id>` |
+| Create PR   | `/prompts:pr`        |

package/.codex/prompts/start.md

@@ -0,0 +1,141 @@
+---
+description: Start working on a bead - claim it and prepare workspace
+argument-hint: "<bead-id> [--worktree]"
+agent: build
+---
+
+# Start: $ARGUMENTS
+
+Claim a task and prepare workspace. Bridge between `/prompts:create` and `/prompts:ship`.
+
+## Load Skills
+
+- `$beads` — bead lifecycle management
+- `$prd-task` — PRD to executable task conversion
+
+## Parse Arguments
+
+| Argument     | Default  | Description                   |
+| ------------ | -------- | ----------------------------- |
+| `<bead-id>`  | required | Task to start                 |
+| `--worktree` | false    | Prepare isolated git worktree |
+
+## Determine Input Type
+
+| Input Type | Detection                   | Action                  |
+| ---------- | --------------------------- | ----------------------- |
+| Bead ID    | Matches `br-xxx` or numeric | Start that bead         |
+| Path       | File/directory path         | Not supported for start |
+
+## Before You Start
+
+- **Be certain**: Only start tasks with a valid PRD.
+- **Check workspace**: Handle uncommitted changes before claiming.
+- **One task at a time**: Warn when other tasks are active.
+- **Validate spec**: Confirm `prd.md` exists and is substantive.
+- **Pick workspace strategy** before implementation starts.
+
+## Phase 0: Bootstrap Beads
+
+```bash
+.codex/scripts/ensure_beads.sh
+```
+
+If bootstrap fails because `br` is missing, stop and show the install error clearly.
+
+## Phase 1: Pre-flight
+
+```bash
+git status --porcelain
+git branch --show-current
+br list --status=in_progress
+```
+
+Read current context before claiming:
+
+- `.codex/memory/project/state.md` for active blockers and durable current state
+- `.codex/context/current-priorities.md` for what matters now
+- `.codex/context/session-context.md` if resuming interrupted work on the same bead
+
+- If uncommitted changes exist, pause and request direction.
+- If other tasks are active, warn before continuing.
+- If `state.md` or `session-context.md` shows the bead is already mid-flight elsewhere, surface that before claiming.
+
+## Phase 2: Validate Specification
+
+```bash
+br show $ARGUMENTS
+ls .beads/artifacts/$ARGUMENTS/
+```
+
+Verify `prd.md` exists and has real content (not placeholders).
+
+If missing/incomplete, route to `/prompts:create`.
+
+## Phase 3: Claim
+
+```bash
+.codex/scripts/start_bead.sh $ARGUMENTS
+```
+
+This helper validates `prd.md`, claims the bead, and prepares the default feature branch.
+
+## Phase 4: Prepare Workspace
+
+> **Choose one:**
+>
+> 1. **Create feature branch (Recommended)** — Isolated branch for this task.
+> 2. **Use current branch** — Continue where you are.
+> 3. **Create worktree** — Isolated filesystem + branch workspace.
+
+If feature branch is selected, map task type to prefix:
+
+| Bead Type | Branch Prefix |
+| --------- | ------------- |
+| feature   | `feat`        |
+| bug       | `fix`         |
+| task      | `task`        |
+| epic      | `epic`        |
+
+```bash
+prefix=$(case "$bead_type" in
+  feature) echo "feat" ;;
+  bug) echo "fix" ;;
+  task) echo "task" ;;
+  epic) echo "epic" ;;
+  *) echo "task" ;;
+esac)
+title_slug=$(echo "$title" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
+git checkout -b "$prefix/$ARGUMENTS-$title_slug"
+```
+
+If worktree is selected, use `$using-git-worktrees` workflow.
+
+## Phase 5: Convert PRD to Tasks
+
+If `prd.json` does not exist yet, convert PRD markdown to executable tasks via `$prd-task`.
+
+If `prd.json` exists, report progress (completed/total).
+
+## Phase 6: Report and Route
+
+Output:
+
+1. Task type and status
+2. Active branch/workspace
+3. Artifact status (`prd.md`, `prd.json`)
+4. Relevant prior context found (`state.md`, `current-priorities.md`, `session-context.md`)
+5. Recommended next step
+
+| State              | Recommended Command           |
+| ------------------ | ----------------------------- |
+| Has `prd.json`     | `/prompts:ship $ARGUMENTS`    |
+| Epic with subtasks | `/prompts:start <subtask-id>` |
+| Complex task       | Use Codex native planning inline during `/prompts:ship` |
+
+## Related Commands
+
+| Need                | Command              |
+| ------------------- | -------------------- |
+| Create spec first   | `/prompts:create`    |
+| Implement and ship  | `/prompts:ship <id>` |

package/.codex/prompts/status.md

@@ -0,0 +1,102 @@
+---
+description: Show project status - tasks, git state, recent sessions
+argument-hint: "[--git] [--sessions]"
+agent: build
+---
+
+# Status: $ARGUMENTS
+
+Quick project status dashboard. Read-only command.
+
+## Load Skills
+
+- $beads
+
+## Determine Input Type
+
+| Input Type   | Detection     | Action              |
+| ------------ | ------------- | ------------------- |
+| No arguments | Default       | Show full dashboard |
+| `--git`      | Flag provided | Git-focused view    |
+| `--sessions` | Flag provided | Session-focused view |
+
+## Before You Status
+
+- **Read-only only**: do not modify task or git state.
+- **Use real output**: no invented values.
+- **Single recommendation**: suggest one next action.
+
+## Available Tools
+
+| Tool                   | Use When                     |
+| ---------------------- | ---------------------------- |
+| `br`                   | Task stats and active/ready lists |
+| `git`                  | Branch, changes, recent commits |
+| `.codex/context/session-context.md` | Latest exact stop point |
+| `.codex/context/worklog.md` | Recent session activity |
+| `.codex/memory/project/state.md` | Durable current state and blockers |
+
+## Phase 1: Gather State (Parallel)
+
+Run these checks together:
+
+```bash
+br stats
+br list --status in_progress
+br ready
+```
+
+```bash
+git status --porcelain
+git branch --show-current
+git log --oneline -5
+```
+
+Then read:
+
+- `.codex/context/session-context.md` for the latest exact stop point
+- `.codex/context/worklog.md` for recent session activity
+- `.codex/memory/project/state.md` for durable blockers and current state
+
+## Phase 2: Format Report
+
+Use this structure:
+
+```text
+Status
+━━━━━━
+
+TASKS
+  In Progress: [from br list --status in_progress]
+  Ready:       [from br ready]
+  Stats:       [from br stats]
+
+GIT
+  Branch:  [from git branch]
+  Changes: [from git status or "clean"]
+  Recent:  [from git log]
+
+RECENT SESSIONS
+  Stop Point: [from .codex/context/session-context.md]
+  Recent:     [from .codex/context/worklog.md]
+  State:      [from .codex/memory/project/state.md]
+```
+
+## Phase 3: Suggest Next Action
+
+| State                        | Suggestion                    |
+| ---------------------------- | ----------------------------- |
+| Has in-progress tasks        | `/prompts:ship <id>`          |
+| Has ready tasks, none active | `/prompts:start <id>`         |
+| Uncommitted changes          | Review and commit             |
+| Nothing active or ready      | `/prompts:create "<task>"`    |
+
+Return one recommendation only.
+
+## Related Commands
+
+| Need                 | Command              |
+| -------------------- | -------------------- |
+| Start work           | `/prompts:start <id>` |
+| Verify readiness     | `/prompts:verify <id>` |
+| Continue delivery    | `/prompts:ship <id>` |