codexkit 1.0.0

package/.codex/prompts/init-context.md

@@ -0,0 +1,185 @@
+---
+description: Initialize GSD-style project planning context with integrated skill usage
+argument-hint: "[--skip-questions] [--brownfield]"
+agent: build
+---
+
+# Init-Context: $ARGUMENTS
+
+Initialize planning context for richer multi-session execution.
+
+`tech-stack.md` is baseline context. This command refreshes durable planning memory in
+`.codex/memory/project/` using the templates in `.codex/memory/_templates/`, then
+updates `.codex/context/` pointers and current priorities as needed.
+
+## Load Skills
+
+- `$repo-orientation` — discovery and structure mapping
+- `$brainstorming` — collaborative idea refinement
+- `$verification-before-completion` — evidence-based verification
+
+## Parse Arguments
+
+- `--skip-questions`: infer values where possible
+- `--brownfield`: run existing-codebase analysis first
+- `--focus=<area>`: optional domain focus (api, ui, db, etc.)
+
+## Phase 1: Discovery
+
+### 1.1 Check Existing Context
+
+```bash
+ls .codex/context/ 2>/dev/null
+ls .codex/memory/project/ 2>/dev/null
+head -20 .codex/memory/project/project.md 2>/dev/null
+```
+
+If planning files exist, offer:
+
+> **Choose one:**
+> 1. **Refresh (Recommended for stale docs)** — recreate planning files
+> 2. **Update** — keep existing files, update state-focused sections
+> 3. **Skip** — keep as-is and exit
+
+### 1.2 Brownfield Analysis (`--brownfield`)
+
+Analyze current codebase and capture findings into `.codex/memory/project/` and
+`.codex/context/`:
+
+- Tech analysis: languages, frameworks, dependencies, tooling
+- Architecture analysis: structure, patterns, entry points, data flow
+- Integration points and risks
+
+## Phase 2: Requirements Gathering
+
+### 2.1 Interactive Brainstorming (default)
+
+If not `--skip-questions`, ask concise questions:
+
+1. Vision: one-sentence project purpose
+2. Success criteria: 3-7 measurable outcomes
+3. Target users: primary and secondary
+4. Phases: major milestones
+5. Current phase: where project stands now
+
+### 2.2 Quick Mode (`--skip-questions`)
+
+Use defaults/placeholders for unknowns and infer from README + repo signals.
+
+## Phase 3: Document Creation
+
+Create/update planning files using templates from `.codex/memory/_templates/`:
+
+### 3.1 `.codex/memory/project/project.md`
+- Vision
+- Success criteria
+- Target users
+- Principles
+- Current phase
+
+### 3.2 `.codex/memory/project/roadmap.md`
+- Phase table:
+
+```markdown
+| Phase     | Goal   | Status   | Beads |
+| --------- | ------ | -------- | ----- |
+| [Phase 1] | [Goal] | [Status] | [#]   |
+```
+
+### 3.3 `.codex/memory/project/state.md`
+- Active bead
+- Current status/phase/date
+- Recent work, decisions, blockers, questions
+- Next actions
+
+### 3.4 Context linkage
+- Mirror only concise session-facing summaries into `.codex/context/current-priorities.md`
+- Keep durable project detail in `.codex/memory/project/*.md`
+
+### 3.5 Brownfield integration (if used)
+- Merge analysis findings into `project.md`, `roadmap.md`, and `state.md`
+
+## Phase 4: Verification and Secret Scan
+
+### 4.1 Verify Files
+
+```bash
+ls -la .codex/context/
+ls -la .codex/memory/project/
+wc -l .codex/memory/project/*.md
+```
+
+Check:
+
+- [ ] `.codex/memory/project/project.md` exists and >20 lines
+- [ ] `.codex/memory/project/roadmap.md` exists and >20 lines
+- [ ] `.codex/memory/project/state.md` exists and >20 lines
+- [ ] Files are readable and non-empty
+
+### 4.2 Secret Scan
+
+```bash
+grep -E '(sk-[a-zA-Z0-9]{20,}|sk_live_[a-zA-Z0-9]+|AKIA[A-Z0-9]{16}|ghp_[a-zA-Z0-9]{36}|-----BEGIN.*PRIVATE KEY)' .codex/context/*.md .codex/memory/project/*.md 2>/dev/null && echo "SECRETS_FOUND" || echo "OK"
+```
+
+If secrets are found: alert user and pause.
+
+## Phase 5: Beads Integration (Optional)
+
+Optional tracking flow:
+
+```bash
+br create "Initialize project context" --type=task
+br update <bead-id> --status closed --reason "Context files created"
+```
+
+## Phase 6: Custom Context (Optional)
+
+Inform user about extending `.codex/context/` with additional docs (domain knowledge, architecture decisions, team agreements).
+
+## Output
+
+Creates/updates planning memory in `.codex/memory/project/`:
+
+| File         | Purpose                                  | Lines (typical) |
+| ------------ | ---------------------------------------- | --------------- |
+| `project.md` | Vision, success criteria, principles     | 50-100          |
+| `roadmap.md` | Phases, milestones, bead planning        | 80-150          |
+| `state.md`   | Current position, blockers, next actions | 60-100          |
+
+Also updates:
+
+- `.codex/context/current-priorities.md`
+- `.codex/context/session-context.md`
+
+## Success Criteria
+
+- [ ] All planning documents created/updated from structure above
+- [ ] Documents are complete and readable
+- [ ] No secrets leaked in generated content
+- [ ] User informed of next steps
+
+## Next Steps
+
+1. New projects: `/prompts:plan`
+2. Brownfield: start with `/prompts:create`, then let `/prompts:ship` plan inline as needed
+3. Existing beads: `/prompts:resume`
+4. Use `/prompts:plan` only if a durable `plan.md` artifact is explicitly needed
+5. Add custom context files as needed
+
+---
+
+## Skill Integration Summary
+
+| Skill                 | When Used                         | Purpose                              |
+| --------------------- | --------------------------------- | ------------------------------------ |
+| `repo-orientation`    | Phase 1                           | Analyze codebase and current context |
+| `verification`        | Phase 4                           | Verify file integrity and readiness  |
+| `brainstorming`       | Phase 2 (interactive questions)   | Refine vision and requirements       |
+| `beads`               | Phase 5 (optional)                | Track initialization as a task       |
+
+## Related Commands
+
+- `prompts:init` — Initialize project structure
+- `prompts:init-user` — Create user profile
+- `prompts:start` — Begin working on a task

package/.codex/prompts/init-user.md

@@ -0,0 +1,93 @@
+---
+description: Set up user profile and preferences
+argument-hint: "[--skip-questions]"
+agent: build
+---
+
+# Init-User: $ARGUMENTS
+
+Create personalized user profile. Optional but recommended for better AI responses.
+
+> **Prerequisite:** Run `/prompts:init` first for core setup
+> **Related:** `/prompts:init-context` for project planning setup
+
+## Load Skills
+
+- `$memory-system`
+
+## Options
+
+| Argument           | Default | Description                         |
+| ------------------ | ------- | ----------------------------------- |
+| `--skip-questions` | false   | Infer from git config, skip prompts |
+
+## Phase 1: Gather Preferences
+
+Unless `--skip-questions`, ask in one message:
+
+1. **Identity**: "Which git contributor are you?" (show top 5 from `git shortlog -sn --all`)
+2. **Communication**: "Terse or detailed responses?"
+3. **Workflow**: "Auto-commit or ask-first?"
+4. **Rules**: "Any rules I should always follow?"
+5. **Technical**: "Preferred languages/frameworks?"
+
+If skipped, infer from `git config user.name` and `git config user.email`.
+
+## Phase 2: Create user.md
+
+Write `.codex/context/user.md` with captured answers:
+
+```markdown
+---
+purpose: User identity, preferences, communication style
+updated: [today]
+---
+
+# User Profile
+
+## Identity
+
+- Name: [from answers]
+- Git email: [user.email]
+
+## Communication Preferences
+
+- Style: [Terse/Detailed]
+- Tone: [Professional/Casual]
+
+## Workflow Preferences
+
+- Git commits: [Auto/Ask-first]
+- Beads updates: [Auto/Ask-first]
+
+## Technical Preferences
+
+- Languages/frameworks: [Preferred languages/frameworks]
+
+## Rules to Always Follow
+
+- [Rule 1]
+- [Rule 2]
+- [Rule 3]
+```
+
+## Phase 3: Configuration Note
+
+User preferences are stored in `.codex/context/user.md`.
+
+If the user has specific rules, suggest adding them to `AGENTS.md` or to the Codex CLI `config.toml`.
+
+## Phase 4: Report
+
+Output:
+
+1. `user.md` created at `.codex/context/user.md`
+2. Preferences captured
+3. Where persistent rules should live (`AGENTS.md` or `config.toml`)
+4. Next step: `/prompts:init-context` for broader project context setup
+
+## Related Commands
+
+- `/prompts:init` — Full project initialization
+- `/prompts:init-context` — Initialize context documents
+- `/prompts:status` — View current project state

package/.codex/prompts/init.md

@@ -0,0 +1,103 @@
+---
+description: Initialize core project setup (AGENTS.md + tech-stack detection only)
+argument-hint: "[--deep]"
+agent: build
+---
+
+# Init: $ARGUMENTS
+
+Core project setup. Creates `AGENTS.md` and detects tech stack. Run once per project.
+
+> Next steps: `/prompts:init-user` for personalization, `/prompts:init-context` for planning context.
+
+## Load Skills
+
+- `$repo-orientation` — codebase discovery and structure mapping
+
+## Options
+
+| Argument | Default | Description                               |
+| -------- | ------- | ----------------------------------------- |
+| `--deep` | false   | Comprehensive research (~100+ tool calls) |
+
+## Phase 1: Detect Project
+
+Detect and validate:
+
+- Package manager and dependencies (with versions)
+- Build, test, lint, dev commands — verify each actually works
+- CI/CD configuration
+- Existing AI rules (`.cursor/rules/`, `.cursorrules`, `.github/copilot-instructions.md`)
+- Top-level directory structure
+
+With `--deep`: also inspect git history, source patterns, subsystem candidates.
+
+## Phase 2: Preview Detection
+
+After detection, present summary and confirm:
+
+> **Choose one:**
+> 1. **Yes, create it (Recommended)** — write files now
+> 2. **Show me what you'll write first** — preview without writing, then confirm again
+> 3. **Cancel** — stop with no changes
+
+## Phase 3: Create AGENTS.md
+
+Create or improve `AGENTS.md` (target <60 lines, max 150):
+
+- Tech stack with versions
+- File structure
+- Commands (validated)
+- Code example from actual codebase (5-10 lines)
+- Testing conventions
+- Boundaries: always / ask-first / never
+- Gotchas
+
+Principles: examples over explanation; pointers over copies; merge existing custom rules.
+
+## Phase 4: Create Tech Stack + Context Docs
+
+Write/update `.codex/context/` docs with detected values:
+
+- `index.md` — context map
+- `architecture.md` — boundaries, modules, data flow
+- `conventions.md` — coding/testing/tooling conventions
+- `current-priorities.md` — active priorities or initialized default
+- `decision-log.md` — initialization decision entry
+- `worklog.md` — initialization activity entry
+
+## Phase 5: Subsystems (`--deep` only)
+
+Identify candidates for nested `AGENTS.md`:
+
+- `packages/*/` (monorepos)
+- Distinct `frontend/` and `backend/` regions
+- Subsystems with clearly different patterns
+
+Ask user before creating nested files.
+
+## Phase 6: Verify and Report
+
+Verify:
+
+- [ ] `AGENTS.md` exists and is <60 lines (or justified)
+- [ ] Commands were validated
+- [ ] Boundaries include explicit Never rules
+- [ ] Code example is from real code
+- [ ] `.codex/context/` docs created/updated
+
+Output:
+
+1. Files created/updated with line counts
+2. Tech stack detected
+3. Commands validated (yes/no)
+4. Suggested next steps:
+   - `/prompts:init-user`
+   - `/prompts:init-context`
+   - `/prompts:review-codebase`
+
+## Related Commands
+
+- `prompts:init-context` — Set up planning context
+- `prompts:init-user` — Create user profile
+- `prompts:start` — Begin working on a task

package/.codex/prompts/lfg.md

@@ -0,0 +1,140 @@
+---
+description: Full autonomous chain - execute, review, and compound in one command
+argument-hint: "<bead-id>"
+agent: ship
+---
+
+# LFG: $ARGUMENTS
+
+## Let's Go
+
+Full compound engineering cycle. One command, planning included inline when needed.
+
+> **When to use:** You have a bead in `in_progress` state with a PRD and want end-to-end execution.
+>
+> **Checkpoints happen** only at decision points. Everything automatable should be automated.
+
+## Load Skills
+
+- `$safe-implementation`
+- `$verification`
+- `$code-review`
+
+## Parse Arguments
+
+| Argument    | Default  | Description         |
+| ----------- | -------- | ------------------- |
+| `<bead-id>` | required | The bead to execute |
+
+## Phase 0: Preflight
+
+```bash
+br show $ARGUMENTS
+ls .beads/artifacts/$ARGUMENTS/
+```
+
+Verify:
+
+- Bead exists and is `in_progress`
+- `prd.md` exists
+- If `plan.md` exists, reuse it only if still current
+
+> **Choose one:**
+> 1. **Use existing plan (Recommended)** — continue with current `plan.md`
+> 2. **Recreate plan** — overwrite with a fresh planning pass
+
+Report:
+
+```markdown
+## LFG: $ARGUMENTS — <title>
+
+Cycle: Inline plan → Ship → Review → Compound
+Review mode: Deep self-review (5 passes)
+Plan mode: [inline / reuse existing artifact]
+```
+
+## Step 1: PLAN INLINE
+
+Do any necessary planning inside this session before execution begins.
+
+- Reuse `plan.md` if a current one already exists
+- Otherwise derive execution order directly from `prd.md`
+- Persist a fresh `plan.md` only when the work truly benefits from a durable plan artifact
+
+## Step 2: WORK
+
+Run `/prompts:ship $ARGUMENTS` with wave-by-wave execution.
+
+- Follow `$executing-plans` behavior: execute by dependency waves
+- Run incremental verification between waves
+- Run full verification at end
+- Respect checkpoint tasks: `checkpoint:human-verify`, `checkpoint:decision`
+
+## Step 3: REVIEW
+
+Perform deep self-review equivalent to a 5-agent pass:
+
+1. Security/correctness
+2. Performance/architecture
+3. Type-safety/tests
+4. Conventions/patterns
+5. Simplicity/completeness
+
+Auto-fix rules:
+
+- Critical issues → fix inline, re-verify
+- Important issues → fix inline
+- Minor issues → log in bead comments or final notes
+
+If a Critical issue requires architectural change, stop and request a decision.
+
+## Step 4: COMPOUND
+
+Extract learnings from the full cycle and write to `.codex/context/`:
+
+- Durable decisions → `.codex/context/decision-log.md`
+- Session progress → `.codex/context/worklog.md`
+- Reusable conventions → `.codex/context/conventions.md`
+
+## Step 5: Report & Next
+
+```markdown
+## LFG Complete: $ARGUMENTS
+
+### Cycle Summary
+
+| Step     | Status | Notes                        |
+|----------|--------|------------------------------|
+| Plan     | ✓      | [N] waves, [M] tasks         |
+| Work     | ✓      | [N] commits, [M] files       |
+| Review   | ✓      | 5-pass self-review, [M] fixes|
+| Compound | ✓      | [N] context updates          |
+
+### Learnings Captured
+- [decision or convention titles]
+
+### Verification
+- typecheck: pass/fail
+- lint: pass/fail
+- tests: pass/fail ([N] passing)
+
+### Next Steps
+- Review changes: `git diff origin/main`
+- Create PR: `/prompts:pr`
+- Continue next bead: `/prompts:lfg <next-bead-id>`
+```
+
+## Swarm Mode (sLFG)
+
+For large plans with 6+ independent tasks, run Work in swarm mode.
+
+Use when plan has 2+ independent waves with no shared file mutations.
+
+## Related Commands
+
+| Need | Command |
+| --- | --- |
+| Ship only | `/prompts:ship <id>` |
+| Review only | `/prompts:review-codebase` |
+| Compound only | `/prompts:compound <id>` |
+| Create PR after | `/prompts:pr` |

package/.codex/prompts/plan.md

@@ -0,0 +1,140 @@
+---
+description: Compatibility shim for explicit plan requests; prefer native Codex planning inline during create/start/ship
+argument-hint: "<bead-id>"
+agent: plan
+---
+
+# Plan: $ARGUMENTS
+
+Compatibility shim for users who explicitly ask for a stored plan artifact.
+
+> **Preferred workflow:** `/prompts:create` → `/prompts:start <id>` → `/prompts:ship <id>` → `/prompts:verify <id>`
+>
+> Use this only when you explicitly need a durable `.beads/artifacts/<id>/plan.md`.
+
+## Load Skills
+
+- `$beads`
+- `$writing-plans`
+
+## Parse Arguments
+
+| Argument         | Default  | Description                       |
+| ---------------- | -------- | --------------------------------- |
+| `<bead-id>` | required | The bead to plan |
+
+## Before You Plan
+
+- Prefer native Codex planning inside `/prompts:ship` for most work
+- Use this prompt only when a durable, reviewable `plan.md` adds real value
+- Keep plans concise and execution-oriented
+- Do not create child beads automatically from this shim
+
+## Phase 0: Bootstrap Beads
+
+```bash
+.codex/scripts/ensure_beads.sh
+```
+
+## Phase 1: Gather Current State
+
+```bash
+br show $ARGUMENTS
+ls .beads/artifacts/$ARGUMENTS/
+```
+
+Verify:
+- Bead is `in_progress`
+- `prd.md` exists
+- If `plan.md` exists, overwrite only if the user explicitly wants a fresh durable plan
+
+## Phase 2: Plan Inline with Native Codex Reasoning
+
+Do the planning in-session using Codex's normal reasoning and codebase inspection.
+
+Focus on:
+
+- outcome-shaped goal
+- affected files
+- verification commands
+- dependency order
+- optional checkpoints
+
+## Phase 3: Persist a Concise Execution Plan
+
+Write `.beads/artifacts/<bead-id>/plan.md` with this required header:
+
+```markdown
+# [Feature] Implementation Plan
+
+> REQUIRED SUB-SKILL: Use `$executing-plans` for task-by-task implementation.
+
+**Goal:** [Outcome-shaped goal]
+
+**Why a Stored Plan Exists:** [Reason durable plan is useful here]
+
+---
+
+## Discovery
+
+[Summarize the key findings Codex used to shape execution.]
+
+### Observable Truths
+
+1. [Truth 1]
+2. [Truth 2]
+3. [Truth 3]
+
+### Required Artifacts
+
+| Artifact | Provides | Path |
+| -------- | -------- | ---- |
+| ...      | ...      | ...  |
+
+### Key Links
+
+| From | To  | Via | Risk |
+| ---- | --- | --- | ---- |
+| ...  | ..  | ... | ...  |
+
+## Execution Order
+
+[Tasks + waves]
+
+## Tasks
+
+[Concrete, file-specific, verification-backed steps]
+```
+
+Keep the plan lean. If the same result can be achieved directly in `/prompts:ship`, say so.
+
+## Phase 4: Report
+
+Output:
+
+1. Why a stored plan was warranted
+2. Affected file list
+3. Execution order summary
+4. Plan path
+5. Next step: `/prompts:ship $ARGUMENTS`
+
+## Related Commands
+
+| Need | Command |
+| --- | --- |
+| Create task first | `/prompts:create` |
+| Start bead | `/prompts:start <id>` |
+| Execute work | `/prompts:ship <id>` |
+
+```bash
+br comments add $ARGUMENTS "Created plan.md: Level [N] discovery, [X] waves, [Y] tasks, [Z] TDD steps"
+```
+
+## Related Commands
+
+| Need           | Command             |
+| -------------- | ------------------- |
+| Create spec    | `/prompts:create`   |
+| Start working  | `/prompts:start`    |
+| Execute plan   | `/prompts:ship`     |
+| Research first | `/prompts:research` |