codexkit 1.0.2 → 1.0.4

package/.codex/memory/_templates/state.md

@@ -2,10 +2,20 @@
 
 ## Status
 
+- Record the current milestone and operating state here.
+
 ## Recent Completed Work
 
+- Summarize recently completed work here.
+
 ## Active Decisions
 
+- Capture decisions currently steering implementation here.
+
 ## Blockers
 
+- Record active blockers here. Remove when resolved.
+
 ## Next Actions
+
+- Record the next durable actions here. Keep to 3-5 items.

package/.codex/memory/_templates/tech-stack.md

@@ -2,8 +2,17 @@
 
 ## Languages
 
+- Add primary implementation languages here.
+
 ## Runtime
 
+- Add runtime and framework notes here.
+
 ## Tooling
 
+- Add build tools, formatters, and other tooling here.
+
 ## Verification Commands
+
+- Add the main verification commands for this project here.
+- Example: `npm run typecheck`, `npm run lint`, `npm test`

package/.codex/memory/_templates/user.md

@@ -2,6 +2,12 @@
 
 ## Preferences
 
+- Add collaboration preferences for this project's user here.
+
 ## Workflow
 
+- Add workflow preferences or operating preferences here.
+
 ## Communication Notes
+
+- Record communication style or response format preferences here.

package/.codex/prompts/create.md

@@ -76,16 +76,41 @@ If `--type` is provided, use it directly. Otherwise classify and confirm:
 - **bug**: broken behavior
 - **task**: tactical change with clear scope
 
-## Phase 3: Choose Research Depth
+## Phase 3: Detect Research Scope
+
+Scan `$ARGUMENTS` for signals of external dependencies:
+
+| Category      | Signal Words                                            |
+| ------------- | ------------------------------------------------------- |
+| Payment       | stripe, paypal, paddle, lemonsqueezy, payment, billing  |
+| Auth          | auth0, clerk, supabase auth, firebase auth, oauth, SAML |
+| Email         | resend, sendgrid, postmark, ses, transactional email    |
+| Cloud         | aws, gcp, azure, vercel, cloudflare, fly.io             |
+| Database SaaS | supabase, planetscale, neon, turso, firebase            |
+| Analytics     | posthog, amplitude, mixpanel, plausible                 |
+| AI/ML         | openai, anthropic, gemini, huggingface, replicate       |
+| Storage       | s3, r2, cloudinary, uploadthing                         |
+| Task Tracking | beads_rust, linear, jira                                |
+
+**Classification:**
+
+- **internal-only**: No signals detected → all research depths available
+- **external-required**: Signal detected → Minimal and Skip are **blocked**; minimum Standard depth
+
+If external dependency is detected, tell the user: "External dependency detected ([category]). Research depth must be Standard or Deep."
+
+## Phase 4: 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
+> 3. **Minimal** — 1 investigation: quick file scan (~30 sec) ⚠️ _Blocked if external deps detected_
+> 4. **Skip** — use current project knowledge only ⚠️ _Blocked if external deps detected_
 
-## Phase 4: Gather Context (Delegation by Depth)
+**Auto-escalation rule:** If Phase 3 classified as `external-required`, options 3 and 4 are unavailable. Default to Standard.
+
+## Phase 5: Gather Context (Delegation by Depth)
 
 Based on selected depth:
 
@@ -108,9 +133,20 @@ Based on selected depth:
 
 - No delegation; use existing `AGENTS.md` + `.codex/context/`
 
+**External dependency research (when Phase 3 = external-required):**
+
+For any depth (Deep or Standard), `@scout` **must** search for:
+
+- Official documentation / API reference for the detected service
+- Current pricing and rate limits
+- Integration examples in the project's language/framework
+- Known gotchas or breaking changes
+
+Include source URLs in all research findings. Save findings to `.beads/artifacts/<bead-id>/research.md`.
+
 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
+## Phase 6: Search Prior Related Work
 
 Before creating a new PRD, search durable project context for relevant prior bead work:
 
@@ -134,7 +170,7 @@ When you are ready to write the PRD, you may build that section directly with:
 .codex/scripts/build_prior_related_work.sh "$ARGUMENTS" --limit 3
 ```
 
-## Phase 6: Create Bead
+## Phase 7: Create Bead
 
 Extract title/description from `$ARGUMENTS`:
 
@@ -157,7 +193,7 @@ 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
+├── research.md        # if Phase 5 used scout/explore findings
 ├── design.md          # if design tradeoffs matter
 └── notes.md           # optional clarifications gathered during create
 ```
@@ -165,24 +201,24 @@ Create and reserve these files up front so later prompts have predictable inputs
 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
+## Phase 8: 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      |
+| 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 5)             | 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 5                              | If any exist      |
 
 ### Task Format
 
@@ -202,7 +238,7 @@ For feature/epic work, add a short `Execution Strategy` section covering:
 - whether child beads are recommended
 - what must be manually verified by a human
 
-## Phase 8: Validate PRD
+## Phase 9: Validate PRD
 
 Before finalizing, verify:
 
@@ -214,10 +250,11 @@ Before finalizing, verify:
 - [ ] Tasks use `[category]` headings
 - [ ] Every task includes verification
 - [ ] No implementation code in PRD
+- [ ] If external deps detected in Phase 3: `research.md` exists in artifacts with source URLs
 
 If any check fails, fix it without asking.
 
-## Phase 9: Report
+## Phase 10: Report
 
 Output:
 
@@ -232,7 +269,7 @@ 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>`  |
+| Need           | Command               |
+| -------------- | --------------------- |
+| Start working  | `/prompts:start <id>` |
+| Implement next | `/prompts:ship <id>`  |

package/.codex/prompts/init.md

@@ -53,6 +53,30 @@ Create or improve `AGENTS.md` (target <60 lines, max 150):
 - Boundaries: always / ask-first / never
 - Gotchas
 
+### File Operation Guard (include in generated AGENTS.md)
+
+Document the runtime-enforced Read-before-Write/Edit rule:
+
+```markdown
+## File Operations
+
+Codex enforces a **Read-before-Write** guard at runtime for existing files:
+
+- **Existing files**: Must be Read before any Write or Edit. The runtime
+  rejects the operation with:
+  > `File has not been read in this session. Read the file before editing.`
+- **New files**: Can be written freely — the guard only fires for files
+  that already exist on disk.
+
+**Preferred tool selection:**
+
+| Intent                                 | Tool  |
+| -------------------------------------- | ----- |
+| Modify part of an existing file        | Edit  |
+| Full replacement of an existing file   | Write (after Read) |
+| Create a file that does not exist yet  | Write |
+```
+
 Principles: examples over explanation; pointers over copies; merge existing custom rules.
 
 ## Phase 4: Create Tech Stack + Context Docs

package/.codex/prompts/resume.md

@@ -8,6 +8,12 @@ agent: build
 
 Pick up where a previous session left off. Recover context, verify state, continue.
 
+> **Two resume paths:**
+> - **Thread-based**: `codex resume` restores a previous Codex session transcript (best for short interruptions within the same thread).
+> - **File-based**: This prompt recovers context from repo-visible files (best for cross-session continuity, different machines, or when thread history is unavailable).
+>
+> Use `codex resume` when you want the exact conversation back. Use this prompt when you need structured context recovery from durable project files.
+
 ## Load Skills
 
 - `$beads`

package/.codex/prompts/search.md

@@ -0,0 +1,78 @@
+---
+description: Search project memory and context for prior decisions, patterns, and knowledge
+argument-hint: "<query> [--limit <n>] [--decisions-only]"
+agent: explore
+---
+
+# Search: $ARGUMENTS
+
+Search durable project memory and context docs for relevant prior knowledge.
+
+## Load Skills
+
+- `$memory-system` — memory file structure and update protocol
+
+## Phase 1: Parse Query
+
+| Argument          | Default | Description                              |
+| ----------------- | ------- | ---------------------------------------- |
+| `<query>`         | required | Search terms (natural language or keywords) |
+| `--limit <n>`     | 5       | Max results to return                    |
+| `--decisions-only`| false   | Restrict to decision-log entries only    |
+
+## Phase 2: Run Search
+
+Execute the local memory search:
+
+```bash
+bash .codex/scripts/memory_search.sh $ARGUMENTS
+```
+
+If the derived index does not exist, it will be built automatically on first run.
+
+## Phase 3: Present Results
+
+For each result:
+
+1. Show the source file path and heading
+2. Show the relevance score and match reasons
+3. Show the snippet (first 180 characters)
+
+If results reference decision-log entries, highlight them separately under "Related Decisions".
+
+## Phase 4: Offer Next Steps
+
+Based on results, suggest:
+
+- Read the full source file for more context
+- Update stale entries if information has changed
+- Create new memory entries if the query topic has no coverage
+
+## Output
+
+```text
+Search: <query>
+━━━━━━━━━━━━━━━━━━━
+
+Results: <n> matches
+
+1. [score=<n>] <path>
+   Heading: <heading>
+   Snippet: <text>
+
+...
+
+Related Decisions:
+  1. <decision heading> — <snippet>
+
+Suggestions:
+  - <next step>
+```
+
+## Related Commands
+
+| Need              | Command                    |
+| ----------------- | -------------------------- |
+| Full audit        | `bash .codex/scripts/audit_memory_hygiene.sh` |
+| Resume session    | `/prompts:resume`          |
+| Project status    | `/prompts:status`          |

package/.codex/prompts/ship.md

@@ -39,11 +39,11 @@ Execute PRD tasks, verify each gate passes, run review, then request close appro
 
 ## Available Tools
 
-| Tool  | Use When                                  |
-| ----- | ----------------------------------------- |
-| `br`  | Task metadata, comments, close/sync       |
-| `git` | Branch, commits, diffs, verification prep |
-| `grep`| Stub checks and key-link checks           |
+| 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
 
@@ -115,11 +115,11 @@ For each task:
 
 ### 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   |
+| 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:**
 
@@ -148,16 +148,19 @@ For each task:
 ### 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]`
@@ -177,13 +180,13 @@ git commit -m "feat(bead-$ARGUMENTS): <task description>
 
 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       |
+| 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
 
@@ -218,7 +221,7 @@ Completion checklist before closing:
 - [ ] 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
+## Phase 5: Review
 
 Load and run `$requesting-code-review`. Dispatch **5 parallel review agents**, each covering one lens:
 
@@ -247,7 +250,7 @@ Wait for all 5 to return. Synthesize findings:
 
 If critical issues require architectural decisions, stop and present options.
 
-## Phase 6B: Goal-Backward Verification
+## Phase 5B: Goal-Backward Verification
 
 Three-level verification:
 
@@ -277,9 +280,10 @@ return Response.json({ ok: true })
 
 If Level 2/3 fails, fix and re-verify.
 
-## Phase 7: Close
+## Phase 6: Close
 
 > **Choose one:**
+>
 > 1. **Close bead (Recommended)** — All tasks complete, all gates pass, review clear.
 > 2. **Keep open** — Additional changes required.
 
@@ -297,6 +301,13 @@ If user confirms close:
 .codex/scripts/close_bead.sh $ARGUMENTS --reason "Shipped: PRD tasks complete, verification and review passed"
 ```
 
+After close, commit bead state:
+
+```bash
+git add .beads/
+git commit -m "chore(bead-$ARGUMENTS): close - shipped with all gates passing"
+```
+
 ## Output
 
 Report with six sections:
@@ -326,9 +337,9 @@ Report with six sections:
 
 ## Related Commands
 
-| Need        | Command              |
-| ----------- | -------------------- |
-| Create spec | `/prompts:create`    |
-| Claim task  | `/prompts:start <id>` |
+| Need        | Command                |
+| ----------- | ---------------------- |
+| Create spec | `/prompts:create`      |
+| Claim task  | `/prompts:start <id>`  |
 | Verify only | `/prompts:verify <id>` |
-| Create PR   | `/prompts:pr`        |
+| Create PR   | `/prompts:pr`          |

package/.codex/prompts/start.md

@@ -75,10 +75,10 @@ If missing/incomplete, route to `/prompts:create`.
 ## Phase 3: Claim
 
 ```bash
-.codex/scripts/start_bead.sh $ARGUMENTS
+.codex/scripts/start_bead.sh $ARGUMENTS --use-current-branch
 ```
 
-This helper validates `prd.md`, claims the bead, and prepares the default feature branch.
+This helper validates `prd.md` and claims the bead; workspace setup is handled in Phase 4.
 
 ## Phase 4: Prepare Workspace
 

package/.codex/prompts/ui-slop-check.md

@@ -0,0 +1,119 @@
+---
+description: Automated audit for AI aesthetic fingerprints with actionable fixes
+argument-hint: "<component-or-file-path> [--fix]"
+agent: vision
+---
+
+# UI Slop Check: $ARGUMENTS
+
+Scan frontend code for the 12 AI aesthetic fingerprint anti-patterns. Returns a pass/fail verdict with specific findings and actionable corrections.
+
+> Inspired by [pbakaus/impeccable](https://github.com/pbakaus/impeccable) design language kit.
+
+## Load Skills
+
+- `$frontend-design` — design principles and AI slop taxonomy
+- `$visual-analysis` — visual analysis and comparison
+
+## Options
+
+| Argument | Default | Description |
+| -------- | ------- | ------------------------------------------- |
+| `--fix` | false | Auto-apply corrections for detected issues |
+
+## Phase 1: Scan Target
+
+Parse `$ARGUMENTS` for the target path (component file, directory, or screenshot).
+
+Read all relevant files. For each file, scan against the 12 AI fingerprint anti-patterns from the `frontend-design` skill:
+
+| # | Anti-Pattern | What to Look For |
+|---|-------------|------------------|
+| 1 | **Inter/Roboto font** | `font-family` declarations using Inter, Roboto, Arial, Open Sans, system defaults as primary choice |
+| 2 | **Purple-to-blue gradients** | `linear-gradient` with purple/blue/cyan hues; neon accents on dark backgrounds |
+| 3 | **Cards-on-cards** | Nested card components; `Card` inside `Card`; excessive `.rounded` + `.shadow` nesting |
+| 4 | **Glassmorphism abuse** | `backdrop-filter: blur`, glass-effect classes used decoratively across multiple components |
+| 5 | **Bounce/elastic easing** | `cubic-bezier` with values >1 (overshoot); `bounce`, `elastic`, `spring` in animation names |
+| 6 | **Pure black/white** | `#000`, `#fff`, `rgb(0,0,0)`, `rgb(255,255,255)` without tinting |
+| 7 | **Hero metric template** | Big number + small label + supporting stats + gradient accent layout pattern |
+| 8 | **Identical card grids** | Same-sized cards with icon + heading + text repeated 3+ times identically |
+| 9 | **Gradient text impact** | `background-clip: text` + gradient on headings or metrics |
+| 10 | **Gray text on color** | Gray (`#6b7280`, `gray-500`, etc.) text on non-white/non-gray backgrounds |
+| 11 | **Decorative sparklines** | Chart/sparkline components with no real data binding or meaningful data |
+| 12 | **Dark mode default** | Only dark theme defined; dark mode with glowing accents and no light mode |
+
+## Phase 2: Generate Report
+
+### Verdict
+
+Start with a clear **PASS** or **FAIL** verdict.
+
+A single critical anti-pattern = FAIL. Explain why immediately.
+
+### Findings Table
+
+For each detected anti-pattern:
+
+```markdown
+| # | Anti-Pattern | Status | Location | Severity |
+|---|-------------|--------|----------|----------|
+| 1 | Inter font  | FOUND  | globals.css:3 | Medium |
+| 2 | Purple gradient | CLEAR | - | - |
+...
+```
+
+### Detailed Findings
+
+For each FOUND item:
+
+1. **Location**: File path and line number
+2. **Evidence**: The specific code or pattern detected
+3. **Impact**: Why this makes the UI look AI-generated
+4. **Fix**: Specific replacement code or approach
+
+### Summary
+
+- Total anti-patterns found: X/12
+- Severity breakdown: Critical / Medium / Low
+- Estimated fix effort: Quick (<30min) / Moderate (1-2hr) / Significant (>2hr)
+
+## Phase 3: Auto-Fix (if `--fix`)
+
+If `--fix` is passed, apply corrections for each detected anti-pattern:
+
+1. Replace generic fonts with distinctive alternatives
+2. Replace purple/blue gradients with project-appropriate OKLCH palette
+3. Flatten nested card structures
+4. Remove decorative glassmorphism; keep functional uses
+5. Replace bounce/elastic easing with exponential curves
+6. Tint pure black/white with subtle brand hue
+7. Redesign hero metric layouts
+8. Vary card grid sizes and layouts
+9. Replace gradient text with weight/size/color contrast
+10. Replace gray-on-color with shade-of-background text color
+11. Remove decorative sparklines or bind to real data
+12. Add light mode support if only dark mode exists
+
+After fixing, re-run the scan to confirm improvements.
+
+## Phase 4: Record
+
+If significant findings, append to `.codex/context/worklog.md`:
+
+```markdown
+## [YYYY-MM-DD] UI Slop Check: <target>
+
+- Verdict: PASS/FAIL
+- Anti-patterns found: X/12
+- Fixed: Y (if --fix)
+- Remaining: Z
+```
+
+## Related Commands
+
+| Need | Command |
+| ---- | ------- |
+| Full UI/UX review | `/prompts:ui-review` |
+| Design new UI | `/prompts:design` |
+| Gather inspiration | `/prompts:ui-inspire` |
+| Ship implementation | `/prompts:ship` |