codebase-ai 0.1.0

package/commands/review.md

@@ -0,0 +1,150 @@
+---
+description: Code review (security, quality, deps health, UI/accessibility) + test generation. Outputs GitHub Issues. Uses codebase context.
+argument-hint: [--security] [--quality] [--deps] [--ui] [--test] [--pr N] [--fix]
+model: sonnet
+allowed-tools: Agent, Bash(gh:*), Bash(git add:*), Bash(git commit:*), Bash(git push:*), Bash(git checkout:*), Bash(git pull:*), Bash(git fetch:*), Bash(git stash:*), Bash(git log:*), Bash(git status:*), Bash(git diff:*), Bash(git rev-parse:*), Bash(git branch:*), Bash(npx:*), Bash(npm:*), Bash(node:*), Bash(pnpm:*), Bash(uv:*), Bash(pip:*), Read, Write, Edit, Glob, Grep
+---
+
+# /review
+
+Security, quality, dependency health, accessibility review + test generation. Every finding becomes a GitHub Issue. Powered by `codebase` project intelligence.
+
+Branch: `develop` for read-only review. For `--fix`: use a `fix/<slug>` branch → PR → merge to develop.
+
+## Arguments
+
+```
+$ARGUMENTS
+```
+
+- `--security` — OWASP top 10, dependency CVEs, secrets in code, auth/authz
+- `--quality` — convention adherence (CLAUDE.md), dead code, lint, complexity, duplication
+- `--deps` — outdated/vulnerable packages, suggest updates
+- `--ui` — accessibility (contrast, ARIA, keyboard nav), responsive issues
+- `--test` — generate and run persistent test suites for untested code
+- `--test --unit` / `--integration` / `--e2e` / `--coverage` / `--for "feature"` — test scope
+- `--pr N` — scope review to changes in PR #N
+- `--fix` — auto-fix fixable quality, deps, UI issues, commit to develop
+- *(no flags)* — runs all: security + quality + deps + ui
+
+---
+
+## Prerequisites
+
+```bash
+gh auth status || { echo "ERROR: gh auth login first."; exit 1; }
+git remote get-url origin || { echo "ERROR: No git remote."; exit 1; }
+```
+
+### Load codebase project intelligence
+
+```bash
+npx codebase brief 2>/dev/null > /tmp/cb-brief.json || true
+```
+
+Read the brief. Extract and use throughout:
+- `stack.languages`, `stack.frameworks` — language-specific review rules
+- `dependencies.notable`, `dependencies.direct_count` — dependency surface
+- `quality.linter`, `quality.formatter`, `quality.test_framework` — tooling
+- `quality.pre_commit_hooks` — hook coverage
+- `patterns.architecture`, `patterns.api_style` — architecture context
+- `config.env_vars` — identify secrets/sensitive config exposure
+
+Read `CLAUDE.md` if present — conventions drive the quality dimension.
+Read `docs/PRODUCT.md` if present — product context informs security review (roles, auth model, data sensitivity).
+
+### Ensure `review` label exists
+
+```bash
+gh label create "review" --color "6f42c1" --description "From a /review audit" 2>/dev/null || true
+```
+
+---
+
+## Review Workflow
+
+Follow the complete `/vb-review` workflow across all phases:
+
+- **Phase 0** — Scope (`--pr N` or full codebase)
+- **Phase 1** — Security Review (OWASP top 10, CVEs, secrets, auth/authz)
+- **Phase 2** — Quality Review (CLAUDE.md conventions, dead code, lint, complexity)
+- **Phase 3** — Dependency Health (outdated, vulnerable, alternatives)
+- **Phase 4** — UI/Accessibility (contrast, ARIA, keyboard, responsive)
+- **Phase 5** — Consolidate & prioritize
+- **Phase 6** — Create GitHub Issues (one per finding, labeled `review,[severity],[dimension]`)
+- **Phase 7** — Auto-fix (if `--fix`) + commit
+- **Phase 8** — Summary
+
+### codebase integration points
+
+**Use brief data to skip re-scanning what codebase already knows:**
+
+```bash
+# Instead of re-detecting test framework:
+TEST_FRAMEWORK=$(node -e "try{const b=require('/tmp/cb-brief.json');console.log(b.quality?.test_framework||'')}catch{}" 2>/dev/null)
+
+# Instead of re-detecting linter:
+LINTER=$(node -e "try{const b=require('/tmp/cb-brief.json');console.log(b.quality?.linter||'')}catch{}" 2>/dev/null)
+
+# Get dependency count for scope estimate:
+DEPS=$(node -e "try{const b=require('/tmp/cb-brief.json');console.log(b.dependencies?.direct_count||0)}catch{}" 2>/dev/null)
+```
+
+**Issue creation** — after creating a GitHub Issue, also track in codebase:
+```bash
+npx codebase issue create "[title]" --message "[body summary]" 2>/dev/null || true
+npx codebase scan-only --incremental --quiet --sync
+```
+
+**Pre-work sync:**
+```bash
+git fetch origin
+git status  # abort if dirty
+git checkout develop && git pull origin develop
+```
+
+**Commit convention (if `--fix`):**
+
+For each finding, use an isolated branch:
+```bash
+SLUG=$(echo "[finding title]" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd 'a-z0-9-' | cut -c1-40)
+git checkout -b fix/${SLUG}
+
+git add [specific files only]
+git commit -m "fix([dim]): [short description]
+
+/review --fix | Severity: [sev] | Dimension: [dim]
+Closes #[N]"
+git push origin fix/${SLUG}
+
+gh pr create \
+  --base develop \
+  --head fix/${SLUG} \
+  --title "fix(#[N]): [short description]" \
+  --body "## Finding
+[description]
+
+## Fix
+[what was changed]
+
+Severity: [sev] | Closes #[N]"
+```
+
+After PR merge: `git checkout develop && git pull origin develop && git branch -d fix/${SLUG}`
+
+Print scope banner:
+```
+REVIEW SCOPE
+════════════════════════════════════════════════════════
+Project:       [name from brief]
+Stack:         [frameworks from brief]
+Source files:  [N]
+Dependencies:  [direct_count from brief]
+Test framework:[quality.test_framework]
+Linter:        [quality.linter]
+Dimensions:    [security | quality | ui | all]
+Auto-fix:      [yes | no]
+════════════════════════════════════════════════════════
+```
+
+All other behavior (security agent prompts, quality rules, CVE research, accessibility checks, test generation) follows the `/vb-review` specification exactly.

package/commands/setup.md

@@ -0,0 +1,220 @@
+---
+description: Bootstrap a project for the /simulate → /build → /launch loop. Run once per project.
+argument-hint: [--auto] [--refresh]
+model: sonnet
+allowed-tools: Bash(gh:*), Bash(git add:*), Bash(git commit:*), Bash(git push:*), Bash(git checkout:*), Bash(git pull:*), Bash(git fetch:*), Bash(git status:*), Bash(git rev-parse:*), Bash(git branch:*), Bash(git remote:*), Bash(node:*), Bash(npx:*), Bash(npm:*), Bash(brew:*), Bash(curl:*), Bash(chmod:*), Read, Write, Edit, Glob, Grep
+---
+
+# /setup
+
+Bootstrap this project for the codebase + vibekit development loop. Run once when starting on a new project.
+
+## Arguments
+
+```
+$ARGUMENTS
+```
+
+- `--auto` — generate PRODUCT.md entirely from codebase scan, zero questions. Marks uncertain sections with `[INFERRED]`.
+- `--refresh` — re-scan codebase, diff against existing PRODUCT.md, propose updates for stale sections.
+
+---
+
+## Step 1 — Prerequisites
+
+```bash
+node --version     2>/dev/null || echo "MISSING: install Node.js 18+"
+claude --version   2>/dev/null || echo "MISSING: npm install -g @anthropic-ai/claude-code"
+gh --version       2>/dev/null || echo "MISSING: brew install gh"
+gh auth status     2>/dev/null || echo "NOT AUTHENTICATED: gh auth login"
+git remote get-url origin 2>/dev/null || echo "NO REMOTE: git remote add origin <url>"
+agent-browser --version 2>/dev/null || {
+  echo "Installing agent-browser..."
+  npm install -g agent-browser && agent-browser install
+}
+```
+
+Print status table:
+```
+PREREQUISITE CHECK
+══════════════════════════════════════
+Node.js:       [OK vX.X.X | MISSING]
+Claude Code:   [OK vX.X.X | MISSING]
+gh CLI:        [OK vX.X.X | MISSING]
+gh auth:       [OK | NOT AUTHENTICATED]
+git remote:    [OK | MISSING]
+agent-browser: [OK | installed now]
+══════════════════════════════════════
+```
+
+Stop if any prerequisite is missing. Do not proceed until all are resolved.
+
+---
+
+## Step 2 — codebase init
+
+Run the full codebase setup to generate `.codebase.json`, wire AI tools, and install git hooks:
+
+```bash
+npx codebase setup --sync 2>/dev/null || npx codebase init --sync
+```
+
+This installs:
+- `.codebase.json` manifest
+- `CLAUDE.md` injection
+- `post-commit` hook (auto-updates manifest)
+- `commit-msg` hook (blocks direct commits to main/master)
+- `.claude/hooks/git-guard.sh` (PreToolUse — blocks unsafe git ops in Claude)
+- `.claude/hooks/git-post.sh` (PostToolUse — PR reminder after branch push)
+- `.claude/settings.json` (wires Claude Code hooks)
+- `.gitignore` entries
+
+Print: `codebase manifest: generated`
+
+---
+
+## Step 3 — GitHub labels
+
+```bash
+for label in \
+  "bug:d73a4a:Something isn't working" \
+  "arch:0075ca:Architectural change needed" \
+  "sim:e4e669:Found by simulation" \
+  "carry:ff6b35:Bug surviving 2+ cycles" \
+  "cycle:c5def5:Simulation cycle summary" \
+  "critical:b60205:Critical severity" \
+  "high:d93f0b:High severity" \
+  "medium:e99695:Medium severity" \
+  "low:fef2c0:Low severity" \
+  "highlight:0e8a16:Positive product signal" \
+  "vibekit:7057ff:Queued for autonomous build" \
+  "performance:ff8c00:Performance issue" \
+  "review:6f42c1:From a code review"; do
+  NAME=$(echo "$label" | cut -d: -f1)
+  COLOR=$(echo "$label" | cut -d: -f2)
+  DESC=$(echo "$label" | cut -d: -f3-)
+  gh label list --json name --jq '.[].name' 2>/dev/null | grep -q "^${NAME}$" || \
+    gh label create "$NAME" --color "$COLOR" --description "$DESC" 2>/dev/null || true
+done
+echo "Labels ready"
+```
+
+---
+
+## Step 4 — Milestone + .vibekit dir
+
+```bash
+mkdir -p .vibekit
+[ -f ".vibekit/milestone.env" ] && source .vibekit/milestone.env || true
+
+if [ -z "${MILESTONE_NUMBER:-}" ]; then
+  REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner' 2>/dev/null)
+  MS_NUM=$(gh api "repos/${REPO}/milestones" -X POST \
+    -f title="v0.1" -f state="open" \
+    -f description="First release — managed by codebase" \
+    --jq '.number' 2>/dev/null || echo "")
+  if [ -n "$MS_NUM" ]; then
+    echo "MILESTONE_NUMBER=${MS_NUM}" > .vibekit/milestone.env
+    echo "MILESTONE_TITLE=v0.1" >> .vibekit/milestone.env
+    echo "Milestone v0.1 created (#${MS_NUM})"
+  fi
+fi
+```
+
+Add `.vibekit/` entries to `.gitignore` (lock/log files only):
+```bash
+grep -q "build.lock" .gitignore 2>/dev/null || printf "\n.vibekit/build.lock\n" >> .gitignore
+```
+
+---
+
+## Step 5 — Highlights Index issue
+
+```bash
+EXISTING=$(gh issue list --search "Highlights Index" --state all --limit 1 --json number --jq '.[0].number // empty' 2>/dev/null)
+if [ -z "$EXISTING" ]; then
+  gh issue create \
+    --title "Highlights Index" \
+    --label "highlight" \
+    --body "# Product Highlights Index
+
+Tracks positive signals from /simulate cycles. Updated automatically — do not edit manually.
+
+## Index
+<!-- /simulate appends here -->"
+  echo "Highlights Index issue created"
+else
+  echo "Highlights Index already exists (#$EXISTING)"
+fi
+```
+
+---
+
+## Step 6 — PRODUCT.md
+
+Use `codebase brief` as the primary source of project intelligence:
+
+```bash
+npx codebase brief 2>/dev/null > /tmp/cb-brief.json || true
+```
+
+Read the brief. If `docs/PRODUCT.md` exists and `--refresh` not passed: show diff of stale sections, ask user to confirm updates.
+
+Otherwise generate `docs/PRODUCT.md` from:
+- `project.name`, `project.description` → Summary
+- `stack.languages`, `stack.frameworks`, `commands.*` → Tech Stack (auto-filled)
+- `patterns.architecture`, `patterns.api_style` → Context
+- Route/page file scan → infer User Roles
+- `repo.url` → links
+
+Mark genuinely unknown sections with `[INFERRED: ...]`.
+
+**Never hardcode example industries, roles, or countries** — infer from codebase or ask the user.
+
+Commit:
+```bash
+git checkout develop 2>/dev/null || git checkout -b develop
+git add docs/PRODUCT.md .vibekit/ .gitignore 2>/dev/null || true
+git diff --cached --quiet || git commit -m "chore: bootstrap codebase + vibekit setup
+
+Initialized by /setup"
+```
+
+---
+
+## Step 7 — Summary
+
+```
+/setup COMPLETE
+══════════════════════════════════════════════════
+.codebase.json:      generated
+GitHub labels:       13 ready
+Milestone:           v0.1 (#N)
+Highlights Index:    #N
+docs/PRODUCT.md:     [generated | updated]
+Branch:              develop
+Claude hooks:        git-guard + git-post active
+
+Branch convention:
+  main          protected — only /launch merges here
+  develop       integration — all work lands here
+  feat/<slug>   new features  → PR to develop
+  fix/<slug>    bug fixes     → PR to develop
+  chore/<slug>  maintenance   → PR to develop
+  hotfix/<slug> urgent fixes  → PR to develop
+  docs/<slug>   docs only     → PR to develop
+  test/<slug>   tests only    → PR to develop
+
+Commit format:
+  feat(#N): short description
+  fix(#N):  short description
+  chore:    short description
+  docs:     short description
+
+Next steps:
+  1. Review docs/PRODUCT.md — fill in [INFERRED] sections
+  2. /simulate    — AI customer journeys find & fix bugs
+  3. /build       — implement architectural issues
+  4. /launch      — gate check, release, merge to main
+══════════════════════════════════════════════════
+```

package/commands/simulate.md

@@ -0,0 +1,177 @@
+---
+description: Customer journeys (agent-browser) + UX audit (9 dimensions, 3 iterations). Fixes all bugs inline. Outputs GitHub Issues. Uses codebase context.
+argument-hint: [country] [industry] [--count N] [--iterations N] [--cx-only] [--journey-only]
+model: sonnet
+allowed-tools: Agent, Bash(gh:*), Bash(pnpm:*), Bash(npx:*), Bash(npm:*), Bash(git add:*), Bash(git commit:*), Bash(git push:*), Bash(git checkout:*), Bash(git pull:*), Bash(git fetch:*), Bash(git stash:*), Bash(git log:*), Bash(git status:*), Bash(git diff:*), Bash(git rev-parse:*), Bash(git branch:*), Bash(node:*), Bash(curl:*), Bash(uv:*), Read, Write, Edit, Glob, Grep
+---
+
+# /simulate
+
+Simulate real customers via agent-browser, perform a deep UX audit, fix everything fixable inline, and track all output in GitHub Issues. Powered by `codebase` project intelligence.
+
+Runs indefinitely (Ctrl+C to stop). Branch: always `develop`. All inline fixes go directly to `develop` as atomic commits (one commit per fix).
+
+---
+
+## Arguments
+
+```
+$ARGUMENTS
+```
+
+- First positional word(s) → `country` (optional)
+- Any industry keyword → `industry` (optional)
+- `--count N` — customers per cycle (default: 3)
+- `--iterations N` — UX audit iterations (default: 3)
+- `--cx-only` — UX audit only, skip journeys
+- `--journey-only` — journeys only, skip UX audit
+
+---
+
+## Phase 0 — Preflight
+
+```bash
+gh auth status || { echo "ERROR: gh auth login first."; exit 1; }
+git remote get-url origin || { echo "ERROR: No git remote."; exit 1; }
+gh label list --limit 1 --json name --jq '.[0].name' 2>/dev/null | grep -q "sim" || {
+  echo "Labels not found — run /setup first."; exit 1;
+}
+```
+
+### Load codebase project intelligence
+
+```bash
+npx codebase brief 2>/dev/null > /tmp/cb-brief.json || true
+```
+
+Read `/tmp/cb-brief.json`. Extract and hold in context:
+- `project.name`, `project.description`
+- `commands.dev`, `commands.test`, `commands.build`
+- `stack.frameworks`, `stack.languages`, `stack.package_manager`
+- `patterns.architecture`, `patterns.api_style`
+- `git.default_branch` — verify it's `develop`
+
+Load vibekit config:
+```bash
+[ -f ".vibekit/project.env" ] && source .vibekit/project.env || true
+[ -f ".vibekit/milestone.env" ] && source .vibekit/milestone.env || true
+```
+
+### Read PRODUCT.md (required)
+
+Read `docs/PRODUCT.md`. If missing → print "Run /setup first." and exit.
+
+Extract: **ICP**, **Roles**, **Role tasks**, **Competitive context**, **Dev credentials**.
+
+**Never hardcode a country or industry list. Always read from PRODUCT.md.**
+
+### Detect cycle number
+
+```bash
+LAST=$(gh issue list --label "cycle" --state all --limit 1 --json title --jq '.[0].title // ""')
+# Parse N from "[Sim] Cycle N", default 0, set CYCLE_N=$((N+1))
+```
+
+Pull carry-forward bugs and open bugs.
+
+### Detect dev server
+
+Try ports 3000, 3001, 5173, 8000, 8080, 4000, 4200, 8888 with a quick curl.
+
+If none respond, use `commands.dev` from codebase brief:
+```bash
+DEV_CMD=$(node -e "try{const b=require('/tmp/cb-brief.json');console.log(b.commands?.dev||'')}catch{}" 2>/dev/null)
+```
+
+Node projects: use detected package manager from brief. Python: `uv run dev` or `uv run uvicorn main:app`.
+
+### Detect login mechanism
+
+1. Check `.vibekit/repo.env` for `DEV_LOGIN_PATH`
+2. Scan route files for `dev-login`, `dev_login`, `bypass`, `quick-login`
+3. Standard form — seed creds from `docs/PRODUCT.md`
+4. OAuth — note and warn
+
+Print preflight summary:
+```
+PREFLIGHT — CYCLE [N]
+══════════════════════════════════════════════════
+  Project:        [name from codebase brief]
+  Stack:          [frameworks from brief]
+  Carry bugs:     [N]
+  Open bugs:      [N]
+  Server:         http://localhost:[port]
+  Login:          [method]
+  Customers:      [N]
+══════════════════════════════════════════════════
+```
+
+---
+
+## Phases 1–7 — Full Simulation Loop
+
+Follow the complete `/vb-simulate` workflow:
+
+- **Phase 1** — Customer Journeys (agent-browser, profile generation, triage, inline fixes)
+- **Phase 2** — UX Audit (9 dimensions, 3 iterations, page inventory, IA audit, fixes)
+- **Phase 3** — Performance Audit (Core Web Vitals via CDP)
+- **Phase 4** — Dedup
+- **Phase 5** — GitHub Output ([Sim] Cycle N parent issue, Highlights Index update)
+- **Phase 6** — GTM Sync (DEMO-SEQUENCE.md)
+- **Phase 7** — Status → Loop
+
+### codebase integration points
+
+**After every inline fix commit**, refresh the manifest so `codebase next` stays current:
+```bash
+npx codebase scan-only --incremental --quiet --sync
+```
+
+**Issue creation** uses the standard `gh issue create` flow. After creating any issue, also run:
+```bash
+npx codebase issue create "[title]" --message "[body summary]" 2>/dev/null || true
+```
+This keeps the codebase manifest's issue list in sync.
+
+**Pre-work sync (run once at the start of each cycle):**
+```bash
+git fetch origin
+git status  # if dirty, stash first: git stash
+git checkout develop && git pull origin develop
+```
+
+**Commit convention — one atomic commit per fix, never batch:**
+```bash
+git add [specific files only — never git add .]
+git commit -m "fix([severity]): [short description]
+
+Simulation cycle [N] — [role] at [company]
+Page: [route]
+Closes #[issue-N if exists]"
+git push origin develop
+```
+
+**If working files are dirty before checkout:**
+```bash
+git stash
+git checkout develop && git pull origin develop
+git stash pop
+```
+
+**After each full cycle** run a fresh scan:
+```bash
+npx codebase scan-only --quiet --sync
+```
+
+Use agent-browser for all browser automation. One sequential browser session per journey — no parallel tabs. Example session:
+```bash
+agent-browser open http://localhost:[port]
+agent-browser snapshot -i              # get @e1, @e2 refs from accessibility tree
+agent-browser click @e1
+agent-browser fill @e2 "value"
+agent-browser screenshot               # capture evidence
+```
+
+Auth persistence: `agent-browser auth save <role>` after login, `agent-browser auth login <role>` to restore. State: `agent-browser state save/load <name>` between pages.
+
+All other behavior follows the `/vb-simulate` specification exactly.