codexkit 1.0.0

package/.codex/prompts/ui-inspire.md

@@ -0,0 +1,151 @@
+---
+description: Find UI inspiration grounded in the current codebase, then shortlist external references with rationale
+argument-hint: "<component|page|flow|system> <topic> [keywords] [--quick] [--codebase-only]"
+agent: vision
+---
+
+# UI Inspire: $ARGUMENTS
+
+Search for design inspiration the way a strong product designer would: start from the current codebase, then gather external references that actually fit.
+
+> Use this before `/prompts:design` when you want direction, references, and visual options instead of jumping straight into code.
+
+## Load Skills
+
+- `$ui-inspiration-scout` — codebase-grounded inspiration workflow
+- `$frontend-design` — visual quality and anti-slop guardrails
+- `$visual-analysis` — analyze screenshots or rendered UI if available
+
+## Optional Local Enhancer
+
+If the local skill `$ui-ux-pro-max` is installed, use it after codebase grounding to expand palette, typography, and style options. Treat it as an enhancer, not the source of truth.
+
+## Parse Arguments
+
+| Argument | Default | Description |
+| -------- | ------- | ----------- |
+| `component` | — | Search inspiration for a component |
+| `page` | — | Search inspiration for a page layout |
+| `flow` | — | Search inspiration for a multi-step user flow |
+| `system` | — | Search inspiration for a design system or broad UI language |
+| `[topic]` | required | Target surface, such as `pricing`, `settings`, `dashboard`, `navbar` |
+| `[keywords]` | none | Optional style, industry, or product hints |
+| `--quick` | false | Return only shortlist + recommendation, skip deeper synthesis |
+| `--codebase-only` | false | Skip external search and produce inspiration directions from local patterns only |
+
+## Phase 1: Ground In The Existing UI
+
+Inspect the current codebase before searching externally.
+
+Read whichever of these exist:
+
+```bash
+find . -name "tailwind.config.*" -o -name "components.json" -o -name "globals.css" 2>/dev/null
+```
+
+Then inspect likely UI surfaces:
+
+```bash
+rg -n --glob 'src/**/*.{ts,tsx,js,jsx,css,scss}' --glob 'app/**/*.{ts,tsx,js,jsx,css,scss}' --glob 'components/**/*.{ts,tsx,js,jsx,css,scss}' "(className=|class=|bg-|text-|border-|shadow-|rounded-|grid|flex|motion\\.|transition-|font-)" .
+```
+
+Extract a short signature:
+
+1. product/interface type
+2. visual tone and density
+3. recurring layout patterns
+4. component primitives already in use
+5. keep / change / avoid constraints
+
+If screenshots or mockups already exist in the repo, analyze them too before searching outward.
+
+## Phase 2: Check Memory And Prior Decisions
+
+Read relevant prior design context from:
+
+- `.codex/context/decision-log.md`
+- `.codex/context/worklog.md`
+- `.codex/memory/project/project.md`
+- `.codex/memory/project/gotchas.md`
+
+If the repo already committed to a design direction, treat that as a constraint unless the user explicitly asks to revisit it.
+
+## Phase 3: Build The Search Brief
+
+Convert the local UI signature plus `$ARGUMENTS` into a search brief:
+
+- target surface
+- product/domain
+- style direction
+- interaction tone
+- implementation constraints
+- source priorities
+
+State the brief explicitly before searching.
+
+## Phase 4: Search External References
+
+Unless `--codebase-only` is set, search external inspiration sources with deliberate queries.
+
+Preferred tool order:
+
+1. Exa or web/image search for current references
+2. Ref search when a source page or implementation example should be read directly
+3. Context7 when the inspiration touches a specific UI library/framework and you need authoritative docs
+
+Good source targets include:
+
+- Dribbble
+- Mobbin
+- Awwwards
+- Land-book / Landingfolio style galleries
+- official product marketing pages
+- official component library examples
+
+Rules:
+
+- Cite only verified URLs
+- Prefer 3-5 strong references over a large dump
+- Explain why each reference matches this repo
+- Extract patterns, not clones
+
+If `--codebase-only` is set, skip web search and synthesize 2-3 directions from the local UI signature instead.
+
+## Phase 5: Synthesize Directions
+
+Output:
+
+1. **Codebase UI signature** — current visual language and constraints
+2. **Search brief** — how you searched and what you optimized for
+3. **Inspiration shortlist** — 3-5 references with source + URL + rationale
+4. **Directions** — 2-3 directions ranging from safest evolution to bolder option
+5. **Recommendation** — best-fit direction for this repo
+
+For each shortlisted reference include:
+
+- source
+- URL
+- match rationale
+- what to borrow
+- what to avoid
+
+For `--quick`, keep the shortlist tight and give a concise recommendation.
+
+## Phase 6: Hand Off Cleanly
+
+End with:
+
+- a recommended direction
+- implementation guardrails
+- the best next command
+
+If the next step is ideation-to-implementation, recommend `/prompts:design`.
+If the next step is critique of existing work, recommend `/prompts:ui-review`.
+
+## Related Commands
+
+| Need | Command |
+| ---- | ------- |
+| Turn inspiration into a concrete design | `/prompts:design` |
+| Review an existing UI | `/prompts:ui-review` |
+| Start implementation | `/prompts:start` |

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

@@ -0,0 +1,86 @@
+---
+description: Review UI/UX design for quality, aesthetics, and best practices
+argument-hint: "<image-or-component-path> [--responsive] [--dark-mode]"
+agent: vision
+---
+
+# UI Review: $ARGUMENTS
+
+## Load Skills
+
+- $frontend-design
+- `$visual-analysis` — visual analysis and comparison
+- $accessibility-audit
+
+## Input
+
+Parse `$ARGUMENTS`:
+
+- **Path** (required): image, screenshot, or component file
+- **`--responsive`**: include responsive breakpoint review
+- **`--dark-mode`**: include dark mode review
+
+## Phase 1: Analyze Input (visual-analysis approach)
+
+Perform structured visual analysis:
+
+- Content inventory (elements, text, icons)
+- Visual properties (colors, typography, spacing, layout)
+- Detected design patterns and potential anti-patterns
+
+## Phase 2: Score Categories
+
+Rate each 1-10 with brief justification:
+
+| Category               | What to Evaluate                                               |
+| ---------------------- | -------------------------------------------------------------- |
+| **Typography**         | Hierarchy, readability, weight contrast, intentional choices   |
+| **Color**              | Palette cohesion, contrast, semantic usage, no visual slop     |
+| **Layout & Spacing**   | Visual hierarchy, consistency, alignment, white space          |
+| **Interactive States** | Hover, focus, active, disabled, loading coverage               |
+| **Accessibility**      | WCAG AA compliance (use accessibility checklist)               |
+| **Visual Polish**      | Consistency, attention to detail, motion, shadows, icons       |
+
+## Phase 3: Conditional Reviews
+
+**If `--responsive`**: Check at 375px, 768px, 1280px, 1536px+ for touch targets, overflow, and text sizing.
+
+**If `--dark-mode`**: Check contrast on dark surfaces, semantic color adaptation, shadow behavior, and focus visibility.
+
+## Phase 4: Report Findings by Severity
+
+- **Critical (Must Fix)**: accessibility failures, broken interactions
+- **Warning (Should Fix)**: inconsistent spacing, missing states, weak contrast
+- **Info (Nice to Have)**: polish opportunities
+
+For each finding include: location, impact, recommended fix.
+
+Output:
+
+1. Category scores + rationale
+2. Overall assessment (1-2 sentences)
+3. Severity-grouped findings with actionable fixes
+4. Code-level fix suggestions when reviewing component code
+
+## Phase 5: Record Findings
+
+Record significant findings in `.codex/context/decision-log.md`:
+
+```markdown
+## [YYYY-MM-DD] UI Review: <component or screen>
+
+- Severity: Critical | Warning | Info
+- Finding: <short issue summary>
+- Location: <file or screen region>
+- Impact: <user or product impact>
+- Recommended fix: <specific change>
+```
+
+## Related Commands
+
+| Need                 | Command              |
+| -------------------- | -------------------- |
+| Gather inspiration   | `/prompts:ui-inspire` |
+| Design new UI        | `/prompts:design`    |
+| Start implementation | `/prompts:start`     |
+| Ship implementation  | `/prompts:ship`      |

package/.codex/prompts/verify.md

@@ -0,0 +1,181 @@
+---
+description: Verify implementation completeness, correctness, and coherence
+argument-hint: "<bead-id> [--quick] [--full] [--fix] [--no-cache]"
+agent: review
+---
+
+# Verify: $ARGUMENTS
+
+Check implementation against PRD before shipping.
+
+## Load Skills
+
+- `$beads` — bead lifecycle and br CLI
+- `$verification-before-completion` — evidence-based completion protocol
+
+## Parse Arguments
+
+| Argument     | Default  | Description                                    |
+| ------------ | -------- | ---------------------------------------------- |
+| `<bead-id>`  | required | The task to verify                             |
+| `--quick`    | false    | Gates only, skip coherence check               |
+| `--full`     | false    | Force full verification mode (non-incremental) |
+| `--fix`      | false    | Auto-fix lint/format issues                    |
+| `--no-cache` | false    | Bypass verification cache, force fresh run     |
+
+## Determine Input Type
+
+| Input Type | Detection                   | Action                              |
+| ---------- | --------------------------- | ----------------------------------- |
+| Bead ID    | Matches `br-xxx` or numeric | Check implementation vs PRD in bead |
+| Path       | File/directory path         | Verify that specific path           |
+| `all`      | Keyword                     | Verify all in-progress work         |
+
+## Before You Verify
+
+- **Be certain**: only flag issues you can verify.
+- **Do not invent problems** outside PRD scope.
+- **Run all required gates** (typecheck/lint/test/build as applicable).
+- **Prefer project scripts** when available.
+
+## 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: Verification Cache
+
+Before running gates, check whether a fresh pass already exists.
+
+```bash
+.codex/scripts/verify_bead.sh $ARGUMENTS --full
+```
+
+Use `--no-cache` when the latest PASS stamp should be ignored.
+
+| Condition                                   | Action                              |
+| ------------------------------------------- | ----------------------------------- |
+| `--no-cache` or `--full`                    | Skip cache, run fresh               |
+| `<current-stamp> == LAST_STAMP`             | Report cached PASS, skip to Phase 2 |
+| `<current-stamp> != LAST_STAMP` or no cache | Run gates normally                  |
+
+## Phase 2: Gather Context
+
+```bash
+br show $ARGUMENTS
+ls .beads/artifacts/$ARGUMENTS/
+```
+
+Read PRD and supporting artifacts (`plan.md`, research/design notes if present).
+
+Guards:
+
+- [ ] status is `in_progress`
+- [ ] `prd.md` exists
+- [ ] PRD fully reviewed
+
+## Phase 3: Completeness Check
+
+Extract requirements/tasks from PRD and map each to implementation evidence.
+
+- Mark each item: complete, partial, missing
+- Include file:line evidence
+- Compute score (X/Y requirements met)
+
+## Phase 4: Correctness Gates
+
+### Mode selection
+
+| Mode        | When                                     | Behavior                |
+| ----------- | ---------------------------------------- | ----------------------- |
+| Incremental | Default, <20 changed files               | Lint/test changed scope |
+| Full        | `--full`, >20 changed files, or shipping | Lint/test full scope    |
+
+### Project detection
+
+| Indicator        | Typecheck                     | Lint                | Test            | Build            |
+| ---------------- | ----------------------------- | ------------------- | --------------- | ---------------- |
+| `package.json`   | `npm run typecheck`           | `npm run lint`      | `npm test`      | `npm run build`  |
+| `Cargo.toml`     | `cargo check`                 | `cargo clippy`      | `cargo test`    | `cargo build`    |
+| `pyproject.toml` | `mypy .` / `pyright`          | `ruff check .`      | `pytest`        | —                |
+| `go.mod`         | `go vet ./...`                | `golangci-lint run` | `go test ./...` | `go build ./...` |
+| `Makefile`       | Use available project targets | Use targets         | Use targets     | Use targets      |
+
+### Execution order
+
+1. **Parallel:** typecheck + lint
+2. **Sequential:** test, then build
+
+Report format:
+
+```text
+| Gate      | Status | Mode        | Time |
+|-----------|--------|-------------|------|
+| Typecheck | PASS   | full        | ...  |
+| Lint      | PASS   | incremental | ...  |
+| Test      | PASS   | incremental | ...  |
+| Build     | SKIP   | —           | —    |
+```
+
+If `--fix` is set, run project autofix (e.g., `npm run lint:fix`, `ruff check --fix`).
+
+The helper records a fresh PASS stamp in `.beads/verify.log` after all gates and `Verify:` commands succeed.
+
+## Phase 5: Coherence Check (skip with --quick)
+
+Cross-check for contradictions:
+
+- PRD vs implementation
+- Plan vs implementation (if plan exists)
+- Recommendations vs final approach (if research exists)
+
+Also check for leftover artifacts:
+
+- Debug statements
+- Untracked TODO/FIXME
+- Commented-out dead code
+- Hardcoded values that should be configurable
+
+## Phase 6: Report and Record
+
+```bash
+br comments add $ARGUMENTS "Verification: [PASS|PARTIAL|FAIL] - [summary]"
+```
+
+Output:
+
+1. **Result**: READY TO SHIP / NEEDS WORK / BLOCKED
+2. **Completeness**: score + missing items
+3. **Correctness**: gate outcomes
+4. **Coherence**: contradictions (if checked)
+5. **Blocking issues**
+6. **Next step**: `/prompts:ship $ARGUMENTS` or explicit fixes
+
+Completion checklist:
+
+- [ ] Requirement coverage scored
+- [ ] Gates executed with fresh evidence
+- [ ] Coherence checked or intentionally skipped with reason
+- [ ] Follow-up action is explicit
+
+Record significant findings in `.codex/context/decision-log.md`:
+
+```markdown
+## [YYYY-MM-DD] Verification Finding: <short title>
+
+- Result: PASS | PARTIAL | FAIL
+- Scope: <bead-id>
+- Evidence: <file:line or command output>
+- Required action: <fixes or follow-up>
+```
+
+## Related Commands
+
+| Need              | Command                    |
+| ----------------- | -------------------------- |
+| Ship after verify | `/prompts:ship <id>`       |
+| Review code       | `/prompts:review-codebase` |
+| Check status      | `/prompts:status`          |

package/.codex/scripts/append_worklog.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+set -euo pipefail
+# Script: append_worklog
+# Appends a timestamped entry to .codex/context/worklog.md.
+# Usage: ./append_worklog.sh "Completed task X"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+WORKLOG="$SCRIPT_DIR/context/worklog.md"
+
+MESSAGE="${1:-"(no message)"}"
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+# Ensure context directory and worklog exist
+mkdir -p "$SCRIPT_DIR/context"
+if [[ ! -f "$WORKLOG" ]]; then
+  echo "# Worklog" > "$WORKLOG"
+  echo "" >> "$WORKLOG"
+fi
+
+echo "- **[$TIMESTAMP]** $MESSAGE" >> "$WORKLOG"

package/.codex/scripts/apply_worklog_archive.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+set -euo pipefail
+
+# Script: apply_worklog_archive
+# Applies reviewed worklog archive drafts to the canonical worklog and archive directory.
+
+if [[ $# -lt 2 ]]; then
+  echo "Usage: $0 <archive-draft-path> <retained-draft-path> [archive-destination-path]" >&2
+  exit 1
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+ARCHIVE_DRAFT="$1"
+RETAINED_DRAFT="$2"
+ARCHIVE_DIR="$SCRIPT_DIR/context/archive"
+TIMESTAMP="$(date +%Y%m%d-%H%M%S)"
+ARCHIVE_DEST="${3:-$ARCHIVE_DIR/worklog-$TIMESTAMP.md}"
+WORKLOG="$SCRIPT_DIR/context/worklog.md"
+
+if [[ ! -f "$ARCHIVE_DRAFT" ]]; then
+  echo "archive draft not found: $ARCHIVE_DRAFT" >&2
+  exit 1
+fi
+
+if [[ ! -f "$RETAINED_DRAFT" ]]; then
+  echo "retained draft not found: $RETAINED_DRAFT" >&2
+  exit 1
+fi
+
+if ! grep -q "^# Worklog Archive Draft" "$ARCHIVE_DRAFT"; then
+  echo "archive draft does not look valid: missing expected heading" >&2
+  exit 1
+fi
+
+if ! grep -q "^# Worklog" "$RETAINED_DRAFT"; then
+  echo "retained draft does not look valid: missing expected heading" >&2
+  exit 1
+fi
+
+mkdir -p "$ARCHIVE_DIR"
+cp "$ARCHIVE_DRAFT" "$ARCHIVE_DEST"
+cp "$RETAINED_DRAFT" "$WORKLOG"
+
+echo "Applied retained worklog draft to: $WORKLOG"
+echo "Saved archive draft to: $ARCHIVE_DEST"
+echo
+echo "Next step:"
+echo "- Review git diff before committing."

package/.codex/scripts/audit_memory_hygiene.sh

@@ -0,0 +1,102 @@
+#!/bin/bash
+set -euo pipefail
+
+# Script: audit_memory_hygiene
+# Audits context/memory health without mutating repository files.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+WORKLOG="$SCRIPT_DIR/context/worklog.md"
+DECISION_LOG="$SCRIPT_DIR/context/decision-log.md"
+SESSION_CONTEXT="$SCRIPT_DIR/context/session-context.md"
+STATE_FILE="$SCRIPT_DIR/memory/project/state.md"
+LEGACY_SESSION_CONTEXT="$SCRIPT_DIR/memory/session-context.md"
+
+check_budget() {
+  local file="$1"
+  local label="$2"
+  local max_lines="$3"
+
+  if [[ ! -f "$file" ]]; then
+    printf "MISSING  %-28s %s\n" "$label" "$file"
+    return
+  fi
+
+  local lines
+  lines=$(wc -l < "$file" | tr -d ' ')
+  if [[ "$lines" -le "$max_lines" ]]; then
+    printf "OK       %-28s %s/%s lines\n" "$label" "$lines" "$max_lines"
+  else
+    printf "WARN     %-28s %s/%s lines\n" "$label" "$lines" "$max_lines"
+  fi
+}
+
+extract_section_bullets() {
+  local file="$1"
+  local heading="$2"
+  awk -v heading="$heading" '
+    $0 == heading { in_section=1; next }
+    /^## / && in_section { exit }
+    in_section && /^- / { print }
+  ' "$file" 2>/dev/null || true
+}
+
+first_non_placeholder_line() {
+  awk '
+    /^- / {
+      if ($0 !~ /None recorded\./) {
+        print
+        exit
+      }
+    }
+  ' "$1" 2>/dev/null || true
+}
+
+echo "=== Memory Hygiene Audit ==="
+echo
+echo "Line budgets:"
+check_budget "$WORKLOG" "worklog.md" 200
+check_budget "$DECISION_LOG" "decision-log.md" 200
+check_budget "$SESSION_CONTEXT" "context/session-context.md" 80
+check_budget "$STATE_FILE" "memory/project/state.md" 120
+
+echo
+echo "Boundary checks:"
+
+if [[ -f "$LEGACY_SESSION_CONTEXT" ]] && grep -q "Legacy compatibility file only." "$LEGACY_SESSION_CONTEXT" 2>/dev/null; then
+  echo "OK       legacy memory/session-context.md is compatibility-only"
+elif [[ -f "$LEGACY_SESSION_CONTEXT" ]]; then
+  echo "WARN     legacy memory/session-context.md is not marked compatibility-only"
+else
+  echo "OK       no legacy memory/session-context.md present"
+fi
+
+session_next=$(first_non_placeholder_line "$SESSION_CONTEXT")
+state_next=$(extract_section_bullets "$STATE_FILE" "## Next Actions" | head -n 1)
+
+if [[ -n "$session_next" && -n "$state_next" && "$session_next" == "$state_next" ]]; then
+  echo "WARN     first next action is duplicated in session-context.md and state.md"
+else
+  echo "OK       no exact duplicate first next action across session-context.md and state.md"
+fi
+
+if grep -q "^## Activity Log" "$STATE_FILE" 2>/dev/null; then
+  echo "WARN     state.md still contains an Activity Log section"
+else
+  echo "OK       state.md does not contain an Activity Log section"
+fi
+
+worklog_entries=$(grep -c '^-' "$WORKLOG" 2>/dev/null || true)
+decision_count=$(grep -c '^### DLOG-' "$DECISION_LOG" 2>/dev/null || true)
+
+echo
+echo "Counts:"
+printf "INFO     %-28s %s\n" "worklog entries" "$worklog_entries"
+printf "INFO     %-28s %s\n" "decision-log entries" "$decision_count"
+
+echo
+echo "Recommended next actions:"
+echo "- Run .codex/scripts/prepare_worklog_archive.sh <archive-path> if worklog needs pruning."
+echo "- After reviewing both drafts, run .codex/scripts/apply_worklog_archive.sh <archive-draft> <retained-draft> to update worklog.md and save an archive copy."
+echo "- Trim duplicate next-action bullets so session-context.md stays the precise restart cue."
+echo "- Keep only still-relevant durable decisions in decision-log.md."