codexkit 1.0.0

package/.codex/prompts/pr.md

@@ -0,0 +1,150 @@
+---
+description: Create and submit pull request with bead traceability
+argument-hint: "[bead-id] [--draft]"
+agent: build
+---
+
+# Pull Request
+
+## Load Skills
+
+- `$beads`
+- `$verification-before-completion`
+- `$requesting-code-review`
+
+## Parse Arguments
+
+| Argument    | Default  | Description        |
+| ----------- | -------- | ------------------ |
+| `<bead-id>` | optional | Link PR to bead    |
+| `--draft`   | false    | Create as draft PR |
+
+## Phase 1: Pre-PR Verification
+
+```bash
+git status --porcelain
+```
+
+If uncommitted changes exist, ask whether to commit first.
+
+Project detection + preferred gates:
+
+| Project Type    | Detect Via                    | Build            | Test            | Lint                          | Typecheck                             |
+| --------------- | ----------------------------- | ---------------- | --------------- | ----------------------------- | ------------------------------------- |
+| Node/TypeScript | `package.json`                | `npm run build`  | `npm test`      | `npm run lint`                | `npm run typecheck` or `tsc --noEmit` |
+| Rust            | `Cargo.toml`                  | `cargo build`    | `cargo test`    | `cargo clippy -- -D warnings` | (included in build)                   |
+| Python          | `pyproject.toml` / `setup.py` | —                | `pytest`        | `ruff check .`                | `mypy .`                              |
+| Go              | `go.mod`                      | `go build ./...` | `go test ./...` | `golangci-lint run`           | (included in build)                   |
+
+Prefer project scripts in `package.json`, `Makefile`, or `justfile` if present.
+
+Checklist before any push:
+
+- [ ] Working tree is intentional
+- [ ] Verification gates were run fresh
+- [ ] PR summary can be tied back to bead or plan artifacts
+- [ ] Deferred issues are documented
+
+## Phase 2: Gather Context
+
+```bash
+git branch --show-current
+git log main...HEAD --oneline
+git diff main...HEAD --stat
+```
+
+If bead ID provided:
+
+```bash
+br show $ARGUMENTS
+ls .beads/artifacts/$ARGUMENTS/
+```
+
+Read PRD for goal and success criteria.
+
+## Phase 2B: Pre-PR Review
+
+Run 5 review checks (parallel in intent, consolidated in one pass):
+
+1. Security/correctness
+2. Performance/architecture
+3. Type-safety/tests
+4. Conventions/patterns
+5. Simplicity/completeness
+
+```bash
+BASE_SHA=$(git rev-parse origin/main 2>/dev/null || git merge-base HEAD origin/main)
+HEAD_SHA=$(git rev-parse HEAD)
+```
+
+Gate rule:
+
+- Critical issues must be resolved before push
+- Important issues: fix or document in PR body
+
+If code changes during review, re-run Phase 1 gates.
+
+## Phase 3: Push and Confirm
+
+> **Choose one:**
+> 1. **Push & create PR (Recommended)** — push branch and open ready PR
+> 2. **Push & draft PR** — push branch and open draft PR
+> 3. **Show diff first** — inspect final diff before any push
+
+If confirmed:
+
+```bash
+git push -u origin $(git branch --show-current)
+```
+
+## Phase 4: Create PR
+
+```bash
+gh pr create --title "<title>" --body "$(cat <<'EOF2'
+## Summary
+
+[1-2 sentences: what this PR does and why]
+
+## Changes
+
+- `file.ts`: [what changed]
+- `other.ts`: [what changed]
+
+## Testing
+
+- All tests pass
+- Lint and typecheck pass
+- Manual verification: [how to test]
+
+## Checklist
+
+- [x] Tests added/updated
+- [x] All gates pass
+- [ ] Docs updated (if applicable)
+EOF2
+)"
+```
+
+If `--draft`, add `--draft`.
+
+If bead ID provided, include artifact links:
+
+- `.beads/artifacts/$ARGUMENTS/prd.md`
+- `.beads/artifacts/$ARGUMENTS/plan.md` (if exists)
+
+## Output
+
+Report:
+
+1. PR URL
+2. Status (Ready for Review / Draft)
+3. Branch → main
+4. Gate results
+
+## Related Commands
+
+| Need         | Command              |
+| ------------ | -------------------- |
+| Ship first   | `/prompts:ship`      |
+| Verify first | `/prompts:verify`    |
+| Review code  | `/prompts:review-codebase` |

package/.codex/prompts/research.md

@@ -0,0 +1,137 @@
+---
+description: Compatibility shim for explicit research requests; prefer native Codex investigation inline during create or ship
+argument-hint: "<topic-or-bead-id> [--quick|--thorough]"
+agent: scout
+---
+
+# Research: $ARGUMENTS
+
+Compatibility shim for users who explicitly want a persisted research note.
+
+> **Preferred workflow:** do research inline during `/prompts:create` or `/prompts:ship`, and only persist `research.md` when it materially helps execution.
+
+## Load Skills
+
+- `$beads`
+- `$deep-research` (for `--thorough`)
+
+## Parse Arguments
+
+| Argument         | Default  | Description                         |
+| ---------------- | -------- | ----------------------------------- |
+| Topic or bead ID | required | What to research                    |
+| `--quick`        | false    | ~10 tool calls, single question     |
+| `--thorough`     | false    | ~100+ calls, comprehensive analysis |
+
+Default depth: ~30 tool calls for moderate exploration.
+
+## Determine Input Type
+
+| Input Type | Detection                   | Action                            |
+| ---------- | --------------------------- | --------------------------------- |
+| Bead ID    | Matches `br-xxx` or numeric | Research within bead context      |
+| Topic      | String                      | Standalone research               |
+
+## Before You Research
+
+- **Be certain**: Research only what is needed for implementation
+- **Don't over-research**: Stop when there is enough confidence to proceed
+- **Use source priority**: Codebase → Docs → Source → GitHub → Web
+- **Verify confidence**: Medium+ confidence before stopping
+- **Document findings**: Write bead research artifacts or direct report
+
+## Phase 0: Bootstrap Beads (bead mode only)
+
+If the argument is a bead ID:
+
+```bash
+.codex/scripts/ensure_beads.sh
+```
+
+## Available Tools
+
+| Tool         | Use When                        |
+| ------------ | ------------------------------- |
+| `explore`    | Codebase patterns, structure    |
+| `scout`      | External docs, best practices   |
+| `context7`   | Official API references         |
+| `grepsearch` | Real-world code examples        |
+| web search   | Last resort for missing details |
+
+## Phase 1: Load Context
+
+If argument is a bead ID:
+
+```bash
+br show $ARGUMENTS
+```
+
+Read PRD and extract unanswered questions.
+
+Check context files for previous related research:
+
+- `.codex/context/worklog.md`
+- `.codex/context/decision-log.md`
+- `.codex/context/conventions.md`
+
+## Phase 2: Research
+
+### Source Priority
+
+1. Codebase patterns (`explore`)
+2. Official docs (`context7`)
+3. Source code inspection when docs are insufficient
+4. Real-world examples (`grepsearch`)
+5. Web search only if needed
+
+### Delegation
+
+| What              | Agent                        | When                                   |
+| ----------------- | ---------------------------- | -------------------------------------- |
+| Codebase analysis | `explore`                    | Internal patterns, file structure      |
+| External docs     | `scout`                      | Library APIs, best practices           |
+| Multiple domains  | Parallel `explore` + `scout` | 3+ independent questions               |
+
+### Confidence Levels
+
+- **High**: Multiple authoritative sources agree + validated in codebase
+- **Medium**: One credible source, plausible but unverified locally
+- **Low**: Conflicting/uncorroborated information
+
+## Phase 3: Stop Conditions
+
+Stop when one condition is true:
+
+- All key questions answered with medium+ confidence
+- Tool-call budget exhausted for selected depth
+- Last 5 tool calls produced no new insight
+- Blocked and user decision is required
+
+## Phase 4: Document Findings
+
+If bead-based, write `.beads/artifacts/$ARGUMENTS/research.md` including:
+
+- Questions + status (answered/partial/unanswered) + confidence
+- Key findings with source references
+- Recommendation based on evidence
+- Open items requiring decisions
+
+If topic-based, return the same structure in the final report.
+
+## Output
+
+Report:
+
+1. Depth mode and tool-call count
+2. Question matrix with confidence
+3. Key insights
+4. Open items
+5. Suggested next command
+
+## Related Commands
+
+| Need | Command |
+| --- | --- |
+| Create spec | `/prompts:create` |
+| Start working | `/prompts:start` |
+| Execute work | `/prompts:ship` |

package/.codex/prompts/resume.md

@@ -0,0 +1,105 @@
+---
+description: Resume work on a bead from previous session
+argument-hint: "<bead-id>"
+agent: build
+---
+
+# Resume: $ARGUMENTS
+
+Pick up where a previous session left off. Recover context, verify state, continue.
+
+## Load Skills
+
+- `$beads`
+
+## Phase 1: Verify Task
+
+1. Check bead state:
+```bash
+br show $ARGUMENTS
+```
+If not found, run `br list --status=all` to check closed or mistyped IDs.
+
+2. Search for previous session context:
+- Read `.codex/context/session-context.md` first for the compact stop point
+- Read `.codex/context/worklog.md` for the latest session trail
+- Read `.codex/memory/project/state.md` for the latest durable state snapshot
+- Read `.codex/memory/research/beads/$ARGUMENTS.md` first if a synced bead summary exists
+- Check `.beads/artifacts/$ARGUMENTS/` for PRD, plan, and progress notes
+- Read task-local handoff artifacts only if they add information beyond `session-context.md`
+
+## Phase 2: Git State
+
+```bash
+git branch --show-current
+git status --porcelain
+```
+
+If not on expected feature branch, switch first. If dirty, ask user how to proceed.
+
+## Phase 3: Find Handoff
+
+Check session context and handoff artifacts:
+```bash
+ls .beads/artifacts/$ARGUMENTS/handoffs/ 2>/dev/null
+```
+
+Then review:
+- `.codex/memory/research/beads/$ARGUMENTS.md` for normalized bead context if present
+- `.codex/context/session-context.md` for the latest compact stop point
+- Latest handoff file under `.beads/artifacts/$ARGUMENTS/handoffs/`
+- `.codex/context/worklog.md` for previous session notes tied to this bead
+- `.codex/memory/project/state.md` for blockers and next actions
+
+Extract in this order:
+1. exact stop point
+2. first next action
+3. blockers
+4. completed work worth knowing
+
+## Phase 4: Load Artifacts
+
+Prefer the synced bead summary first, then read available artifacts:
+- `.codex/memory/research/beads/$ARGUMENTS.md` (if exists)
+- `.beads/artifacts/$ARGUMENTS/prd.md`
+- `.beads/artifacts/$ARGUMENTS/plan.md` (if exists)
+- `.beads/artifacts/$ARGUMENTS/progress.txt` (if exists)
+- `.beads/artifacts/$ARGUMENTS/research.md` (if exists)
+
+Do not treat `worklog.md` as the canonical stop point if `session-context.md` is more precise.
+Do not treat external handoff artifacts as more authoritative than repo-visible state unless they clearly contain newer information.
+
+## Phase 5: Check Staleness
+
+If latest handoff is older than 3 days:
+
+```bash
+git log --oneline -10
+```
+
+Validate whether mainline changes invalidate assumptions. Re-plan if needed.
+
+Also check whether the saved stop point is stale because:
+- the branch changed materially
+- blockers were already resolved
+- the synced bead summary is newer than the handoff note
+
+## Phase 6: Continue & Report
+
+```bash
+br update $ARGUMENTS --status in_progress
+```
+
+Report:
+
+1. Current branch and HEAD commit
+2. Handoff age
+3. Canonical stop point source used (`session-context`, synced bead summary, or artifact handoff)
+4. Progress snapshot (completed/remaining)
+5. Recommended next command (`/prompts:ship $ARGUMENTS` or `/prompts:create` for a different task)
+
+## Related Commands
+
+- `/prompts:handoff` — Save progress for next session
+- `/prompts:status` — View project state
+- `/prompts:start` — Claim and start a new task

package/.codex/prompts/review-codebase.md

@@ -0,0 +1,147 @@
+---
+description: Review code for quality, security, and compliance
+argument-hint: "[path|bead-id|pr-number|'all'] [--quick|--thorough]"
+agent: review
+---
+
+# Review: $ARGUMENTS
+
+## Load Skills
+
+- $beads
+- $requesting-code-review
+
+## Determine Input Type
+
+| Input Type            | Detection                    | Action                     |
+| --------------------- | ---------------------------- | -------------------------- |
+| No arguments          | Default                      | Review uncommitted changes |
+| Commit hash (40-char) | SHA pattern                  | `git show <hash>`          |
+| Branch name           | String, not matching above   | `git diff main...HEAD`     |
+| PR URL/number         | Contains `github.com` or `#` | `gh pr diff`               |
+| File/directory path   | Existing path                | Review that path only      |
+| Bead ID               | Matches `br-xxx` or numeric  | Review changes vs PRD      |
+
+## Before You Review
+
+- **Be certain**: Only flag issues you can verify with tools.
+- **Do not invent problems**: If an edge case is not in scope, do not flag it.
+- **Do not flag style-only nits** unless they violate project conventions.
+- **Review changed code**: Avoid flagging unrelated legacy code.
+- **Investigate first**: If unsure, do additional checks before reporting.
+
+## Available Tools
+
+| Tool              | Use When                                |
+| ----------------- | --------------------------------------- |
+| `br`              | Task context and bead metadata          |
+| `git`             | Diff and history inspection             |
+| `grep`            | Pattern scans (debug logs, TODO, etc.) |
+| `.codex/context/` | Conventions, architecture, worklog      |
+| `gh`              | PR-based review scope                   |
+
+## Phase 1: Gather Context
+
+```bash
+git status --short
+git diff --cached
+git diff
+```
+
+For each changed file:
+
+- Read full file content (not diff-only).
+- Check intent against task spec.
+
+If bead provided:
+
+```bash
+br show $ARGUMENTS
+ls .beads/artifacts/$ARGUMENTS/
+```
+
+Then read `.beads/artifacts/$ARGUMENTS/prd.md`.
+
+Also read supporting context as needed:
+
+- `.codex/context/conventions.md`
+- `.codex/context/architecture.md`
+- `.codex/context/current-priorities.md`
+
+## Phase 2: Determine Scope + Automated Checks
+
+| Input                    | Scope                 | How to Get Code           |
+| ------------------------ | --------------------- | ------------------------- |
+| File/directory path      | That path only        | `read` or `glob` + `read` |
+| Bead ID (e.g., `br-123`) | Implementation vs PRD | `br show` then `git diff` |
+| PR number (e.g., `#45`)  | PR changes            | `gh pr diff 45`           |
+| `all` or empty           | Recent changes        | `git diff main...HEAD`    |
+
+Detect project type and run appropriate checks:
+
+| Project Type    | Detect Via                    | Build            | Test            | Lint                | Typecheck                             |
+| --------------- | ----------------------------- | ---------------- | --------------- | ------------------- | ------------------------------------- |
+| Node/TypeScript | `package.json`                | `npm run build`  | `npm test`      | `npm run lint`      | `npm run typecheck` or `tsc --noEmit` |
+| Rust            | `Cargo.toml`                  | `cargo build`    | `cargo test`    | `cargo clippy`      | Included in build                     |
+| Python          | `pyproject.toml` / `setup.py` | —                | `pytest`        | `ruff check .`      | `mypy .`                              |
+| Go              | `go.mod`                      | `go build ./...` | `go test ./...` | `golangci-lint run` | Included in build                     |
+
+Prefer project scripts (`package.json`, `Makefile`, or `justfile`) when available.
+
+Language-specific scan:
+
+- Debug statements: `console.log`, `print()`, `println!`, `fmt.Println`
+- Loose typing: `any`, `type: ignore`
+- Markers: `TODO`, `FIXME`, `HACK`
+- Hardcoded secrets patterns
+
+## Phase 3: Manual Review
+
+| Category            | Focus                                                                   |
+| ------------------- | ----------------------------------------------------------------------- |
+| **Security**        | Auth checks, input validation, secret handling, injection prevention    |
+| **Performance**     | N+1 queries, unbounded loops, missing pagination, heavy hot-path work   |
+| **Maintainability** | Complexity, duplication, dead code, naming clarity                      |
+| **Error Handling**  | Async handling, contextual errors, sanitized user-facing failures        |
+| **Testing**         | Coverage for changed behavior, edge cases, deterministic checks          |
+| **Type Safety**     | Unjustified loose types, null safety, explicit return contracts          |
+
+Depth levels:
+
+- `--quick`: automated checks + critical findings only
+- default: full automated + manual review
+- `--thorough`: deep review of all categories
+
+## Phase 4: Report
+
+Group findings by severity:
+
+- **Critical** (must fix before merge)
+- **Important** (should fix)
+- **Minor** (nice to have)
+
+Include:
+
+1. Summary metrics (files reviewed, issues by severity)
+2. Strengths (what is done well)
+3. Verdict (Ready / With fixes / Blocked)
+4. Brief rationale
+
+Record significant findings in `.codex/context/decision-log.md`:
+
+```markdown
+## [YYYY-MM-DD] Review Finding: <short title>
+
+- Scope: <bead-id/path/pr>
+- Severity: Critical | Important | Minor
+- Evidence: <file:line>
+- Recommendation: <fix or follow-up>
+```
+
+## Related Commands
+
+| Need                | Command                 |
+| ------------------- | ----------------------- |
+| Ship after review   | `/prompts:ship <id>`    |
+| Verify completeness | `/prompts:verify <id>`  |
+| Check current state | `/prompts:status --git` |