codexkit 1.0.0

package/.codex/prompts/compound.md

@@ -0,0 +1,154 @@
+---
+description: Extract and persist learnings from completed work
+argument-hint: "[bead-id]"
+agent: build
+---
+
+# Compound: $ARGUMENTS
+
+Capture what was learned. This is the flywheel step — each cycle makes the next cycle faster.
+
+> **Workflow:** `/prompts:create` → `/prompts:start` → `/prompts:ship` → `/prompts:review-codebase` → **`/prompts:compound`** → `/prompts:pr`
+>
+> Run after completed tasks, reviews, or merges.
+
+## Load Skills
+
+- `$beads` — bead lifecycle
+- `$memory-system` — knowledge persistence
+
+## What This Does
+
+Extracts learnings from completed work and stores them in the correct durable home so future planning starts with institutional knowledge instead of duplicated notes.
+
+## Phase 1: Gather Evidence
+
+```bash
+# Get what changed
+git diff origin/main..HEAD --stat
+git log origin/main..HEAD --oneline
+
+# Get review comments if any
+br comments list $ARGUMENTS 2>/dev/null || echo "No bead"
+
+# Get bead context if provided
+br show $ARGUMENTS 2>/dev/null || echo "No bead specified"
+```
+
+Collect from all available sources:
+
+- Git diff (files changed, patterns used)
+- Bead comments (review findings, decisions)
+- Current session context (discoveries, friction points)
+- Errors that were solved
+
+## Phase 2: Classify Learnings
+
+For each finding, assign a type:
+
+| Type        | When to Use                                                | Example                                         |
+| ----------- | ---------------------------------------------------------- | ----------------------------------------------- |
+| `pattern`   | Reusable approach confirmed to work                        | "Use X pattern for Y component type"           |
+| `bugfix`    | Non-obvious bug and root cause                             | "Tool X fails on Y; use Z"                     |
+| `decision`  | Design/architecture choice with rationale                  | "Selected approach A over B because..."        |
+| `gotcha`    | Footgun or constraint                                      | "Do not edit generated output directly"        |
+| `discovery` | Non-obvious fact about codebase or dependencies            | "Build pipeline copies template files at build" |
+| `warning`   | Something likely to break if ignored                       | "Run lint:fix before commit"                   |
+
+Quality bar: record only learnings that save 15+ minutes later.
+
+## Phase 3: Store Learnings
+
+Write durable memory to the most specific destination that fits:
+
+- `.codex/context/session-context.md` only for the current stop point or immediate next-session restart cue
+- `.codex/context/worklog.md` for short session milestone summaries
+- `.codex/memory/project/state.md` for durable current state, active blockers, and what remains true after this session ends
+- `.codex/memory/project/gotchas.md` for warnings, footguns, and recurring constraints
+- `.codex/memory/project/tech-stack.md` for tooling facts and verification commands
+- `.codex/memory/project/project.md` for stable project-level discoveries
+- `.codex/context/decision-log.md` only for true architecture or workflow decisions with rationale
+
+Canonical rule: one learning should have one primary home. Do not write the same fact into multiple durable files unless each copy serves a different purpose.
+
+For decision-log entries, append an entry in `.codex/context/decision-log.md`:
+
+```markdown
+## [Date] — [Type]: [Concise, searchable title]
+
+**What happened:** [what happened, why it matters, how to apply it]
+**Key facts:** [comma-separated facts]
+**Files:** [relevant/file.ts if applicable]
+**Confidence:** high / medium / low
+```
+
+Minimum viable: title + narrative.
+
+If the learning is not a durable decision, prefer `memory/project/*.md`, `worklog.md`, or `session-context.md` instead of the decision log.
+
+Quick routing guide:
+
+| If the learning is... | Store it in... |
+| --------------------- | -------------- |
+| "here is where we stopped" | `.codex/context/session-context.md` |
+| "here is what happened this session" | `.codex/context/worklog.md` |
+| "here is the current durable state/blocker" | `.codex/memory/project/state.md` |
+| "here is a reusable constraint/gotcha" | `.codex/memory/project/gotchas.md` |
+| "here is a stable tooling fact" | `.codex/memory/project/tech-stack.md` |
+| "we chose A over B because..." | `.codex/context/decision-log.md` |
+
+## Phase 4: Check Permanent Rule Candidates
+
+Ask: should this become a permanent rule?
+
+- If **yes**: suggest updating `AGENTS.md` or `.codex/context/conventions.md`
+- If **maybe**: keep only decision-log entry
+
+Rule: changes to `AGENTS.md` require user confirmation.
+
+## Phase 5: Search Related Past Learnings
+
+Read `.codex/context/decision-log.md`, `.codex/context/worklog.md`, and the relevant `memory/project/*.md` file for related or conflicting prior entries.
+
+If a new learning supersedes an old one, include in new entry:
+
+```markdown
+**Supersedes:** [date/title of older entry]
+```
+
+## Phase 6: Output Summary
+
+```markdown
+## Compound Summary
+
+**Work reviewed:** [brief description]
+**Learnings captured:** [N] entries
+
+| # | Type      | Title                        | Concepts               |
+|---|-----------|------------------------------|------------------------|
+| 1 | pattern   | ...                          | auth, token            |
+| 2 | gotcha    | ...                          | build, generated       |
+| 3 | bugfix    | ...                          | typecheck, strict-mode |
+
+**Rule updates suggested:** [yes/no - describe if yes]
+**Primary destinations updated:** [session-context / worklog / state / gotchas / tech-stack / decision-log / research]
+**Next recommended:** /prompts:pr  (or /prompts:create for next task)
+```
+
+## When Nothing to Compound
+
+If work was trivial with no non-obvious learning:
+
+> "Nothing worth compounding. Work was straightforward — no non-obvious patterns, bugs, or decisions encountered."
+
+Do not force entries.
+Do not create ceremonial decision-log entries.
+
+## Related Commands
+
+| Need                   | Command                    |
+| ---------------------- | -------------------------- |
+| Full chain             | `/prompts:lfg`             |
+| Review before compound | `/prompts:review-codebase` |
+| Ship the work          | `/prompts:ship`            |
+| Create PR              | `/prompts:pr`              |

package/.codex/prompts/create.md

@@ -0,0 +1,238 @@
+---
+description: Define a new task with requirements and acceptance criteria
+argument-hint: "<description> [--type epic|feature|task|bug]"
+agent: build
+---
+
+# Create: $ARGUMENTS
+
+Create a bead and its specification (PRD) from a description.
+
+> **Workflow:** `/prompts:create` → `/prompts:start <id>` → `/prompts:ship <id>` → `/prompts:verify <id>`
+>
+> ⛔ This command creates the specification only. Do not write implementation code.
+
+## Load Skills
+
+- `$beads` — bead lifecycle management
+- `$prd` — PRD template guidance
+
+## Parse Arguments
+
+| Argument        | Default       | Description                        |
+| --------------- | ------------- | ---------------------------------- |
+| `<description>` | required      | What to build/fix (quoted string)  |
+| `--type`        | auto-detected | Override: epic, feature, task, bug |
+
+## Determine Input Type
+
+| Input Type  | Detection            | Action                        |
+| ----------- | -------------------- | ----------------------------- |
+| Quoted text | `"description here"` | Create PRD from description   |
+| Short form  | Simple string        | Ask for more detail if needed |
+| `--type`    | Flag provided        | Use provided type             |
+
+## Before You Create
+
+- Be certain: only create beads with clear scope
+- Do not over-spec: if vague, ask clarifying questions first
+- Check duplicates first (Phase 1)
+- No implementation here
+- Verify PRD completeness before saving
+- Search prior bead summaries before writing a new PRD
+
+## Available Helpers
+
+| Helper     | Use When                                     |
+| ---------- | -------------------------------------------- |
+| `@explore` | Finding patterns in codebase, affected files |
+| `@scout`   | External research, best practices            |
+| `br`       | Creating and managing beads                  |
+
+## Phase 0: Bootstrap Beads
+
+Before any `br` command, ensure the project is bead-ready:
+
+```bash
+.codex/scripts/ensure_beads.sh
+```
+
+If bootstrap fails because `br` is missing, stop and show the install error clearly.
+
+## Phase 1: Duplicate Check
+
+```bash
+br list --status=open --status=in_progress
+```
+
+If a matching bead exists, stop and direct user to `/prompts:start <id>`.
+
+## Phase 2: Classify Type
+
+If `--type` is provided, use it directly. Otherwise classify and confirm:
+
+- **epic**: multi-session, cross-domain
+- **feature**: scoped new capability
+- **bug**: broken behavior
+- **task**: tactical change with clear scope
+
+## Phase 3: Choose Research Depth
+
+> **Choose one:**
+>
+> 1. **Deep (Recommended)** — 3-5 investigations: patterns, tests, dependencies, and best practices (~2 min)
+> 2. **Standard** — 2 investigations: patterns + tests (~1 min)
+> 3. **Minimal** — 1 investigation: quick file scan (~30 sec)
+> 4. **Skip** — use current project knowledge only
+
+## Phase 4: Gather Context (Delegation by Depth)
+
+Based on selected depth:
+
+**Deep**
+
+- 3x `@explore`: patterns, tests, dependencies
+- 1x `@scout`: external best practices (feature/epic)
+- 1x `@review`: risk review (epic)
+
+**Standard**
+
+- 2x `@explore`: patterns, tests
+- 1x `@scout`: feature/epic only
+
+**Minimal**
+
+- 1x `@explore`: core pattern scan
+
+**Skip**
+
+- No delegation; use existing `AGENTS.md` + `.codex/context/`
+
+While context is gathered, ask clarifying questions for missing scope/outcomes. For bugs, require repro steps and expected vs actual behavior.
+
+## Phase 5: Search Prior Related Work
+
+Before creating a new PRD, search durable project context for relevant prior bead work:
+
+```bash
+.codex/scripts/search_bead_context.sh "$ARGUMENTS" --limit 3
+```
+
+If strong matches exist:
+
+- Read the top 1-3 relevant bead summaries returned under `Related Bead Summaries`
+- Reuse only durable decisions, constraints, failed approaches, and acceptance criteria
+- Open raw `.beads/artifacts/<id>/...` only if a summary clearly points to deeper context
+- Use matching entries under `Related Durable Context` for worklog, state, or decision carry-forward
+
+The PRD must include a short `Prior Related Work` section when prior bead context is reused.
+If nothing relevant is found, state that explicitly instead of skipping the search silently.
+
+When you are ready to write the PRD, you may build that section directly with:
+
+```bash
+.codex/scripts/build_prior_related_work.sh "$ARGUMENTS" --limit 3
+```
+
+## Phase 6: Create Bead
+
+Extract title/description from `$ARGUMENTS`:
+
+```bash
+title=$(echo "$ARGUMENTS" | head -n1)
+description=$(echo "$ARGUMENTS")
+
+if [ "$title" = "$description" ]; then
+  description="$title"
+fi
+
+bead_id=$(br create --title "$title" --description "$description" --type "$bead_type" --json | jq -r '.id')
+mkdir -p ".beads/artifacts/$bead_id"
+```
+
+### Required Artifact Layout
+
+Create and reserve these files up front so later prompts have predictable inputs:
+
+```text
+.beads/artifacts/<bead-id>/
+├── prd.md
+├── research.md        # if Phase 4 used scout/explore findings
+├── design.md          # if design tradeoffs matter
+└── notes.md           # optional clarifications gathered during create
+```
+
+If the task is epic-sized, define candidate child-bead boundaries in the PRD even if the
+child beads are not created yet.
+
+## Phase 7: Write PRD
+
+Use the `$prd` skill template to write `.beads/artifacts/<bead-id>/prd.md`. Fill every section from gathered context — no placeholders allowed.
+
+### Required Sections
+
+| Section           | Source                                                     | Required          |
+| ----------------- | ---------------------------------------------------------- | ----------------- |
+| Problem Statement | User description + clarifying questions                    | Always            |
+| Scope (In/Out)    | User input + codebase exploration                          | Always            |
+| Proposed Solution | Codebase patterns + user intent                            | Always            |
+| Success Criteria  | User verification + test commands (must include `Verify:`) | Always            |
+| Technical Context | Exploration findings                                       | Always            |
+| Affected Files    | Exploration findings (real paths from Phase 4)             | Always            |
+| Prior Related Work | Synced bead summaries and decision/worklog search         | If relevant       |
+| Tasks             | Derived from scope + solution                              | Always            |
+| Risks             | Codebase exploration                                       | Feature/epic only |
+| Open Questions    | Unresolved items from Phase 4                              | If any exist      |
+
+### Task Format
+
+Each task must include:
+
+- Title with `[category]` tag
+- One-sentence **end state** (not implementation steps)
+- Metadata block: `depends_on`, `parallel`, `conflicts_with`, `files`
+- At least one verification command
+
+### Beads Integration Depth
+
+For feature/epic work, add a short `Execution Strategy` section covering:
+
+- whether the PRD is sufficient to ship directly
+- whether native Codex planning/research should happen inline during execution
+- whether child beads are recommended
+- what must be manually verified by a human
+
+## Phase 8: Validate PRD
+
+Before finalizing, verify:
+
+- [ ] No placeholder text remains (e.g. `[... ]`, `TODO`, `TBD`)
+- [ ] Success criteria include `Verify:` commands
+- [ ] Technical context references real `src/` or project paths
+- [ ] Affected files list real paths
+- [ ] `Prior Related Work` is present when prior bead summaries were reused
+- [ ] Tasks use `[category]` headings
+- [ ] Every task includes verification
+- [ ] No implementation code in PRD
+
+If any check fails, fix it without asking.
+
+## Phase 9: Report
+
+Output:
+
+1. Bead ID and type
+2. PRD location: `.beads/artifacts/<bead-id>/prd.md`
+3. Summary: task count, success criteria count, affected files count
+4. Next steps: `/prompts:start <bead-id>`
+
+```bash
+br comments add $bead_id "Created prd.md with [N] tasks, [M] success criteria"
+```
+
+## Related Commands
+
+| Need            | Command               |
+| --------------- | --------------------- |
+| Start working   | `/prompts:start <id>` |
+| Implement next  | `/prompts:ship <id>`  |

package/.codex/prompts/design.md

@@ -0,0 +1,90 @@
+---
+description: UI/UX visual design with code output
+argument-hint: "<component|page|system> [topic] [--quick]"
+agent: vision
+---
+
+# Design: $ARGUMENTS
+
+Design a component, page, or system with a clear aesthetic direction.
+
+> Design track is optional and can be used before or during implementation.
+
+## Load Skills
+
+- `$frontend-design` — design system guidance, anti-patterns, references
+- `$ui-inspiration-scout` — external inspiration search grounded in repo UI patterns
+
+## Parse Arguments
+
+| Argument    | Default  | Description                                 |
+| ----------- | -------- | ------------------------------------------- |
+| `component` | —        | Design a specific component                 |
+| `page`      | —        | Design a page layout                        |
+| `system`    | —        | Create or extend a design system            |
+| `[topic]`   | required | What to design (e.g. `button`, `dashboard`) |
+| `--quick`   | false    | High-level direction only, skip code        |
+
+## Phase 1: Detect Existing Design System
+
+```bash
+find . -name "tailwind.config.*" -o -name "globals.css" -o -name "components.json" 2>/dev/null
+```
+
+Read existing design foundations and build on them.
+
+## Phase 2: Memory Check
+
+Read prior design decisions from:
+
+- `.codex/context/decision-log.md`
+- `.codex/context/worklog.md`
+
+Reuse existing aesthetic decisions unless user asks to change direction.
+
+## Phase 3: Design
+
+Before output, state:
+
+1. **Aesthetic direction** — chosen style and why
+2. **Key characteristics** — three specific elements to apply
+
+Then produce deliverables:
+
+| Task Type   | Output                                |
+| ----------- | ------------------------------------- |
+| `component` | Spec (variants, sizes, states) + code |
+| `page`      | Layout structure + section breakdown  |
+| `system`    | Tokens (CSS variables) + guidelines   |
+
+For `--quick`: provide direction and key decisions only.
+
+## Phase 4: Record Decision
+
+Append to `.codex/context/decision-log.md`:
+
+```markdown
+## [Date] — decision: Design: [topic]
+
+**Choice:** [direction]
+**Rationale:** [why]
+**Key tokens:** [colors, fonts, spacing]
+**Confidence:** high
+```
+
+## Examples
+
+```bash
+/prompts:design component button
+/prompts:design page landing --quick
+/prompts:design system
+```
+
+## Related Commands
+
+| Need               | Command              |
+| ------------------ | -------------------- |
+| Gather inspiration | `/prompts:ui-inspire` |
+| Review existing UI | `/prompts:ui-review` |
+| Start building     | `/prompts:start`     |
+| Ship it            | `/prompts:ship`      |

package/.codex/prompts/handoff.md

@@ -0,0 +1,184 @@
+---
+description: Save progress and context for next session
+argument-hint: "<bead-id> [instructions]"
+agent: build
+---
+
+# Handoff: $ARGUMENTS
+
+Save state so the next session can continue cleanly.
+
+> Run when pausing work. Resume with `/prompts:resume $ARGUMENTS`.
+
+## Load Skills
+
+- `$beads` — bead lifecycle and sync
+- `$docs-handoff` — handoff and resume protocol
+
+## Parse Arguments
+
+| Argument         | Default  | Description                        |
+| ---------------- | -------- | ---------------------------------- |
+| `<bead-id>`      | required | Bead to hand off                   |
+| `[instructions]` | none     | Extra context for next session     |
+
+## Phase 1: Gather State
+
+```bash
+br show $ARGUMENTS
+git status --porcelain
+git branch --show-current
+git rev-parse --short HEAD
+ls .beads/artifacts/$ARGUMENTS/ 2>/dev/null
+```
+
+## Phase 2: Handle Uncommitted Changes
+
+If uncommitted changes exist:
+
+> **Choose one:**
+> 1. **Commit as WIP (Recommended)** — create a WIP commit scoped to changed files
+> 2. **Leave uncommitted** — skip commit and only write handoff
+
+If user chooses WIP commit:
+
+```bash
+git add <specific changed files>
+git commit -m "WIP: $ARGUMENTS - [brief stop point]"
+```
+
+## Phase 3: Write Handoff
+
+Update the handoff in three layers with clear boundaries:
+- `.codex/context/worklog.md` -> milestone summary only
+- `.codex/context/session-context.md` -> compact stop point for next session
+- `.codex/memory/project/state.md` -> durable current state and blockers
+
+```markdown
+## Handoff: $ARGUMENTS
+
+**Date:** [timestamp]
+**Branch:** [branch]
+**Commit:** [short hash]
+
+### Done
+- [completed work]
+
+### In Progress
+- [current step] — stopped because [reason]
+
+### Remaining
+- [next steps]
+
+### Files Touched
+- `path/to/file.ts` — [what changed]
+
+### Decisions Made This Session
+- [decision]: [why]
+
+### Blockers
+[None or blocker details]
+
+### Resume Instructions
+1. [first action]
+2. [second action]
+
+Resume with: `/prompts:resume $ARGUMENTS`
+```
+
+Suggested `session-context.md` update:
+
+```markdown
+## Resume: $ARGUMENTS
+
+- Branch: [branch]
+- Commit: [short hash]
+- Stop point: [the exact step that was in progress]
+- First next action: [single best next action]
+- Blockers: [none or short blocker list]
+- Artifacts to read first:
+  - `.codex/memory/research/beads/$ARGUMENTS.md` if present
+  - `.beads/artifacts/$ARGUMENTS/prd.md`
+  - `.beads/artifacts/$ARGUMENTS/progress.txt` if present
+```
+
+Suggested `state.md` update:
+
+```markdown
+## Status
+- Active bead: $ARGUMENTS
+- Session paused at: [timestamp]
+
+## Blockers
+- [current blockers]
+
+## Next Actions
+- [next step]
+```
+
+## Phase 4: Record Durable Learnings
+
+Only write to `.codex/context/decision-log.md` if a real durable architecture or workflow decision was made.
+If the session produced only a gotcha, pattern, or temporary note, prefer:
+- `.codex/context/worklog.md` for milestone trail
+- `.codex/memory/project/*.md` for durable non-decision facts
+- `.codex/memory/research/beads/$ARGUMENTS.md` via sync for task-local synthesis
+
+For true decisions, append to `.codex/context/decision-log.md`:
+
+```markdown
+## [Date] — decision: [searchable title]
+
+**Context:** [why the decision was needed]
+**Decision:** [what was chosen]
+**Consequences:** [tradeoffs and implications]
+**Bead:** $ARGUMENTS
+**Concepts:** [keywords]
+```
+
+Do not use the decision log for:
+- raw handoff state
+- speculative ideas
+- unresolved options
+- duplicate worklog summaries
+
+## Phase 5: Sync Bead Context
+
+Before syncing Beads state, compact task-local artifacts into durable repo context:
+
+```bash
+.codex/scripts/sync_bead_context.sh $ARGUMENTS
+```
+
+This should create or refresh:
+
+- `.codex/memory/research/beads/$ARGUMENTS.md`
+- a concise worklog entry if the synced summary changed
+
+Use the synced summary as the reusable layer for future `/prompts:create` and `/prompts:resume` flows.
+
+## Phase 6: Sync
+
+```bash
+br sync --flush-only
+```
+
+## Output
+
+```text
+Handoff: $ARGUMENTS
+━━━━━━━━━━━━━━━━━━━
+
+Branch: [branch]
+Commit: [hash]
+Saved:  `.codex/context/worklog.md`, `.codex/context/session-context.md`, `.codex/memory/project/state.md`
+
+Next session: /prompts:resume $ARGUMENTS
+```
+
+## Related Commands
+
+- `/prompts:resume` — resume previous work
+- `/prompts:status` — inspect current state
+- `/prompts:compound` — capture learnings
+- `codexkit bead-sync <id>` — manually backfill or refresh a bead summary