codebase-ai 0.1.4 → 0.2.0

package/commands/build.md

@@ -70,102 +70,223 @@ gh label list --limit 1 --json name --jq '.[0].name' 2>/dev/null | grep -q "sim"
 
 ## Phase 0 — Orientation
 
-Load project board config, define `add_to_project()` helper, parse flags, auto-triage unlabeled issues — all exactly as in `/vb-build`.
+Parse flags from `$ARGUMENTS`. Surface the build queue:
 
-For the implementation plan, use `codebase next` to surface the highest-priority item first:
 ```bash
 npx codebase next 2>/dev/null || true
 ```
 
----
+Auto-triage unlabeled open issues:
+```bash
+UNLABELED=$(gh issue list --state open --json number,labels --jq '[.[] | select(.labels | length == 0)] | .[].number')
+for N in $UNLABELED; do
+  gh issue edit $N --add-label "arch"
+done
+```
 
-## Phases 1–4 — Implementation Loop
+Read `CLAUDE.md` if present — follow its conventions exactly.
 
-Follow the complete `/vb-build` workflow:
+Print orientation banner:
+```
+BUILD LOOP — ROUND [R] of [max-rounds]
+════════════════════════════════════════════════════
+  Project:     [name from brief]
+  Stack:       [frameworks from brief]
+  Test runner: [commands.test]
+  Open arch:   [N] issues
+  Open bugs:   [N] issues
+  Mode:        [full | --once | --issue N | --dry-run]
+════════════════════════════════════════════════════
+```
+
+If `--dry-run`: print the issue queue and exit.
+
+---
 
-- **Phase 0.5** — Mode selection, approval banner
-- **Phase 1** — Plan (read issues, wait for approval, dry-run exit)
-- **Phase 2** — Implement (read → implement → verify via Playwright → commit → close)
-- **Phase 3** — Carry-forward resolution
-- **Phase 4** — Summary
+## Phase 1 — Plan
 
-### codebase integration points
+Fetch the build queue — issues labeled `arch` or `vibekit`, state `open`, sorted by priority:
 
-**Before implementing each issue**, get fresh context:
 ```bash
-npx codebase brief 2>/dev/null > /tmp/cb-brief.json || true
+QUEUE=$(gh issue list --label "arch" --label "vibekit" --state open --json number,title,labels --jq 'sort_by(.number) | .[]')
 ```
 
-Read `CLAUDE.md` if present — follow its conventions exactly.
+If `--issue N` was passed, filter to that single issue.
+
+For each issue in the queue:
+1. Read the full issue body: `gh issue view [N] --json body --jq '.body'`
+2. Identify affected files from the issue body or `mapped_files` from `codebase next`
+3. Add to the implementation plan
+
+If queue is empty: print "No arch/vibekit issues found. Nothing to build." and exit.
 
-**Branch + commit convention:**
+---
+
+## Phase 2 — Implement (per issue)
 
-For small fixes (< 50 lines): commit directly to `develop`.
-For arch issues (significant changes): use a feature branch → PR.
+For each issue in the plan, execute this sequence:
+
+### 2a. Sync and branch
 
 ```bash
-# Pre-work: always sync first
 git fetch origin
-git status  # abort if dirty uncommitted changes exist
+git status --short  # abort if dirty
 git checkout develop && git pull origin develop
+```
 
-# For arch issues — create a feature branch
+For significant changes (arch issues): create a feature branch.
+For small fixes (< 50 lines): commit directly to develop.
+
+```bash
 SLUG=$(echo "[issue title]" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd 'a-z0-9-' | cut -c1-40)
 git checkout -b feat/${SLUG}
+```
+
+### 2b. Read and understand
+
+1. Re-read the issue body for acceptance criteria
+2. Read all affected files identified in Phase 1
+3. Read `CLAUDE.md` conventions — follow them exactly
+4. Check `patterns.architecture` from brief — match existing patterns
+
+### 2c. Implement
+
+Write the code. Follow these rules:
+- One issue per implementation — never batch
+- Match existing code style (indentation, naming, patterns)
+- Add tests if the project has a test framework (`quality.test_framework` from brief)
+- No over-engineering — solve exactly what the issue asks
+
+### 2d. Verify
 
-# ... implement the fix ...
+Run the test suite:
+```bash
+TEST_CMD=$(node -e "try{const b=require('/tmp/cb-brief.json');console.log(b.commands?.test||'')}catch{}" 2>/dev/null)
+[ -z "$TEST_CMD" ] && TEST_CMD="npm test"
+$TEST_CMD
+```
+
+If tests fail: fix the implementation, re-run. Do not proceed with failing tests.
+
+If the project has a running dev server and agent-browser is available, verify via browser:
+```bash
+agent-browser open http://localhost:[port]
+agent-browser snapshot -i
+# Navigate to the affected page, verify the change works
+agent-browser screenshot
+```
 
-# Stash if you need to switch context mid-work
-# git stash && git checkout develop && git stash pop
+### 2e. Commit and close
 
-# Atomic commit — one commit per issue, never batch unrelated changes
-git add [specific files changed]
+For feature branches:
+```bash
+git add [specific files only]
 git commit -m "feat(#[N]): [short description]
 
-[1-2 sentence description of what was built]
+[1-2 sentence description]
 Closes #[N]"
 git push origin feat/${SLUG}
 
-# Raise PR — do not merge directly
-gh pr create \
-  --base develop \
-  --head feat/${SLUG} \
+gh pr create --base develop --head feat/${SLUG} \
   --title "feat(#[N]): [short description]" \
   --body "## What
 [description]
 
 ## Test evidence
-[test output or Playwright result]
+[test output or screenshot]
 
 Closes #[N]"
 
-# After PR is merged, clean up
+# Wait for PR, then clean up
 git checkout develop && git pull origin develop
 git branch -d feat/${SLUG} 2>/dev/null || true
 ```
 
-For direct `develop` commits (small fixes only):
+For direct develop commits:
 ```bash
-git checkout develop && git pull origin develop
-git add [specific files changed]
+git add [specific files only]
 git commit -m "fix(#[N]): [short description]
 
 Closes #[N]"
 git push origin develop
 ```
 
-**After closing each issue**, update the manifest so `codebase next` stays current:
+Close the issue:
+```bash
+gh issue close [N] --comment "Implemented in $(git rev-parse --short HEAD)."
+npx codebase issue close [N] --reason "Implemented in $(git rev-parse --short HEAD)" 2>/dev/null || true
+```
+
+Refresh manifest:
 ```bash
 npx codebase scan-only --incremental --quiet --sync
 ```
 
-**When closing an issue via gh**:
+### 2f. Repeat
+
+Return to Phase 2a for the next issue in the queue.
+
+---
+
+## Phase 3 — Simulate (full loop mode only)
+
+Skip if `--once` or `--issue N` was passed.
+
+On even rounds: invoke `/simulate --journey-only` (quick verification).
+On odd rounds: invoke `/simulate` (full UX audit + journeys).
+
+If `/simulate` creates new bug issues, they enter the queue for the next round.
+
+---
+
+## Phase 4 — Poll and Loop
+
+Skip if `--once` or `--issue N` was passed.
+
+```bash
+npx codebase scan-only --quiet --sync
+```
+
+Check for new issues:
 ```bash
-gh issue close [N] --comment "Implemented in $(git rev-parse --short HEAD). Verified via Playwright."
-# Also update codebase issue tracking
-npx codebase issue close [N] --reason "Implemented in $(git rev-parse --short HEAD)" 2>/dev/null || true
+NEW=$(gh issue list --label "arch" --label "vibekit" --state open --json number --jq 'length')
+```
+
+Check launch readiness:
+```bash
+BUGS=$(gh issue list --label "bug" --state open --json number --jq 'length')
+```
+
+If `$NEW == 0` and `$BUGS == 0`: print "All issues resolved. Ready for /launch." and exit.
+If round >= `--max-rounds`: print "Max rounds reached. Stopping." and exit.
+Otherwise: increment round counter, return to Phase 1.
+
+---
+
+## Phase 5 — Summary
+
+```
+/build COMPLETE — [R] rounds
+════════════════════════════════════════════════════
+  Issues implemented: [N]
+  Issues remaining:   [N]
+  Tests:              [pass/fail]
+  Simulate cycles:    [N]
+
+  [If all clear: "Ready for /launch"]
+  [If issues remain: "Run /build again or /launch --dry-run to check gates"]
+════════════════════════════════════════════════════
 ```
 
-**simulate step** (in full loop mode): invoke `/simulate` with `--journey-only` on even rounds, full on odd rounds.
+---
+
+## Ground Rules
 
-All other behavior (Playwright verification, project board updates, auto-launch gate, polling) follows the `/vb-build` specification exactly.
+1. **One issue, one commit** — never batch unrelated changes
+2. **Tests must pass** — do not close an issue with failing tests
+3. **Follow CLAUDE.md** — project conventions are law
+4. **Feature branches for arch** — small fixes can go to develop directly
+5. **Atomic commits** — `git add [specific files]`, never `git add .`
+6. **No force push** — use `git revert` to undo
+7. **Refresh manifest after every close** — keeps `codebase next` current
+8. **Read the issue body** — acceptance criteria are in the body, not just the title

package/commands/review.md

@@ -2,7 +2,7 @@
 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
+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(python:*), Bash(python3:*), Bash(pnpm:*), Bash(uv:*), Bash(pip:*), Read, Write, Edit, Glob, Grep
 ---
 
 # /review
@@ -68,6 +68,7 @@ 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, defensive programming, minimal code)
+- **Phase 2b** — Dead Code Declutter (stack-aware — runs `/py-declutter` for Python, `/nextjs-declutter` for Next.js)
 - **Phase 3** — Dependency Health (outdated, vulnerable, alternatives)
 - **Phase 4** — UI/Accessibility (contrast, ARIA, keyboard, responsive)
 - **Phase 5** — Consolidate & prioritize
@@ -151,6 +152,49 @@ All other behavior (security agent prompts, CVE research, accessibility checks,
 
 ---
 
+## Phase 2b — Dead Code Declutter (Stack-Aware)
+
+After the quality review, detect the project stack from the brief and run the appropriate declutter skill if installed. This is automatic — no flags needed.
+
+### Detection logic
+
+```bash
+# Read stack from brief (already loaded in Phase 0)
+LANGUAGES=$(node -e "try{const b=require('/tmp/cb-brief.json');console.log((b.stack?.languages||[]).join(','))}catch{}" 2>/dev/null)
+FRAMEWORKS=$(node -e "try{const b=require('/tmp/cb-brief.json');console.log((b.stack?.frameworks||[]).join(','))}catch{}" 2>/dev/null)
+```
+
+### Dispatch rules
+
+| Condition | Action |
+|-----------|--------|
+| `LANGUAGES` contains `python` | Run `/py-declutter` |
+| `FRAMEWORKS` contains `next` or `nextjs` | Run `/nextjs-declutter` |
+| Both match | Run both sequentially (Python first, then Next.js) |
+| Neither matches | Skip Phase 2b — log: "No declutter skill matches this stack" |
+
+### Execution
+
+When a matching skill is detected:
+1. Call `list_skills` via MCP (or `codebase skills` via bash) to confirm the skill is installed
+2. Read the skill's SKILL.md to understand its workflow (the skill file is at `~/.claude/skills/<name>.skill`)
+3. Follow the workflow defined in SKILL.md using the tools available in the /review context (Agent, Bash, Read, Write, Edit, Glob, Grep)
+4. For Python skills: run the analysis scripts via `Bash(python:*)`
+5. For Node.js skills: run the analysis scripts via `Bash(node:*)`
+6. Findings with confidence <80% are reported as GitHub Issues (labeled `review,quality,dead-code`)
+7. Findings with confidence >=80% are auto-removed if `--fix` is active, otherwise reported as issues
+8. After the skill completes, include its KPI summary (files removed, lines eliminated, functions cleaned) in the Phase 8 summary
+
+### If skill is not installed
+
+If the matching skill file is not found in `~/.claude/skills/`, log:
+```
+  Skill [name] not installed — run: codebase setup
+```
+Then continue to Phase 3. Do not fail the review.
+
+---
+
 ## Phase 2 — Quality Review (Extended Rules)
 
 The quality agent must check the following **in addition** to the base `/vb-review` quality rules.

package/commands/simulate.md

@@ -108,70 +108,253 @@ PREFLIGHT — CYCLE [N]
 
 ---
 
-## Phases 1–7 — Full Simulation Loop
+## Phase 1 — Customer Journeys
 
-Follow the complete `/vb-simulate` workflow:
+Skip if `--cx-only` was passed.
 
-- **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
+### 1a. Generate customer profiles
 
-### codebase integration points
+For each of `--count N` customers (default 3), generate a realistic persona:
+- **Name, role, company** — from roles in `docs/PRODUCT.md`
+- **Country** — from `$ARGUMENTS` or random if not specified
+- **Goals** — 3-5 tasks this persona would do in the app (derived from PRODUCT.md role tasks)
+- **Tech comfort** — varies (some savvy, some not)
 
-**After every inline fix commit**, refresh the manifest so `codebase next` stays current:
-```bash
-npx codebase scan-only --incremental --quiet --sync
-```
+### 1b. Run each journey sequentially
+
+For each customer, run a browser session via agent-browser:
 
-**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
+# Sync before starting
+git fetch origin && git checkout develop && git pull origin develop
+
+# Start browser session
+agent-browser open http://localhost:[port]
+agent-browser snapshot -i  # accessibility tree → @e1, @e2 refs
 ```
-This keeps the codebase manifest's issue list in sync.
 
-**Pre-work sync (run once at the start of each cycle):**
+**Login** using the detected mechanism from Phase 0:
 ```bash
-git fetch origin
-git status  # if dirty, stash first: git stash
-git checkout develop && git pull origin develop
+agent-browser auth login [role]  # if saved
+# OR navigate to login page and fill credentials from PRODUCT.md
 ```
 
-**Commit convention — one atomic commit per fix, never batch:**
+**Execute each goal** as a sequence of browser actions:
+1. Navigate to the relevant page
+2. `agent-browser snapshot -i` to read the accessibility tree
+3. Interact: `click @eN`, `fill @eN "value"`, navigate
+4. After each action, `snapshot -i` again to verify state changed
+5. `agent-browser screenshot` to capture evidence
+
+**Triage findings** during the journey:
+
+| Severity | Criteria | Action |
+|----------|----------|--------|
+| `critical` | App crash, data loss, security hole, blank page | Create issue immediately |
+| `high` | Feature broken, workflow blocked, wrong data shown | Create issue immediately |
+| `medium` | UI glitch, slow load, confusing UX, missing feedback | Create issue, fix inline if < 30 min |
+| `low` | Cosmetic, minor copy, alignment | Create issue, fix inline if < 10 min |
+
+**Inline fix flow** (for fixable bugs):
+1. Read the source file causing the bug
+2. Fix it
+3. Verify the fix via browser (`snapshot -i` → confirm change)
+4. Commit atomically:
 ```bash
-git add [specific files only — never git add .]
+git add [specific files only]
 git commit -m "fix([severity]): [short description]
 
 Simulation cycle [N] — [role] at [company]
 Page: [route]
 Closes #[issue-N if exists]"
 git push origin develop
+npx codebase scan-only --incremental --quiet --sync
 ```
 
-**If working files are dirty before checkout:**
+**Create GitHub issues** for everything found:
 ```bash
-git stash
-git checkout develop && git pull origin develop
-git stash pop
+gh issue create --title "[Sim] [severity]: [description]" \
+  --label "bug,[severity],sim" \
+  --body "## Bug Report
+**Cycle:** [N]
+**Customer:** [name] ([role] at [company])
+**Page:** [route]
+**Steps to reproduce:**
+1. [step]
+2. [step]
+
+**Expected:** [what should happen]
+**Actual:** [what happened]
+**Screenshot:** [attached or described]
+**Fixed inline:** [yes/no — if yes, commit SHA]"
 ```
 
-**After each full cycle** run a fresh scan:
+### 1c. Session log
+
+After each customer journey, write an HTML session log to `.vibekit/sessions/cycle-[N]-[role].html` with all screenshots, accessibility trees, and actions taken.
+
+---
+
+## Phase 2 — UX Audit
+
+Skip if `--journey-only` was passed.
+
+### 2a. Page inventory
+
+Crawl the app to build a page list:
 ```bash
-npx codebase scan-only --quiet --sync
+agent-browser open http://localhost:[port]
+agent-browser snapshot -i
 ```
+Navigate each link in the accessibility tree. Build a list of all unique routes.
 
-Use agent-browser for all browser automation. One sequential browser session per journey — no parallel tabs. Example session:
+### 2b. Audit each page across 9 dimensions
+
+For each page, evaluate:
+
+| # | Dimension | What to check |
+|---|-----------|---------------|
+| 1 | **Visual hierarchy** | Clear heading structure, logical reading order, emphasis on primary actions |
+| 2 | **Navigation** | Breadcrumbs, back buttons, consistent nav, no dead ends |
+| 3 | **Forms & input** | Labels, validation messages, error recovery, tab order |
+| 4 | **Feedback** | Loading states, success/error messages, progress indicators |
+| 5 | **Accessibility** | Contrast ratios, ARIA labels, keyboard navigation, screen reader text |
+| 6 | **Responsive** | Layout at different viewport widths (if testable) |
+| 7 | **Content** | Spelling, grammar, placeholder text, missing copy |
+| 8 | **Performance** | Perceived speed, unnecessary spinners, layout shift |
+| 9 | **Consistency** | Same patterns used across pages, no style drift |
+
+Score each dimension 1-10. Repeat for `--iterations N` passes (default 3), improving scores each pass by fixing what you can inline.
+
+### 2c. Fix and commit
+
+Same inline fix flow as Phase 1. One commit per fix, push to develop.
+
+---
+
+## Phase 3 — Performance Audit
+
+Quick performance check on the top 5 most-visited pages:
+1. Navigate to each page
+2. Note perceived load time (fast/medium/slow)
+3. Check for layout shifts (`snapshot -i` before and after full load)
+4. Check for unnecessary network requests if visible in page behavior
+
+Create issues for any `medium` or `slow` pages with label `performance,sim`.
+
+---
+
+## Phase 4 — Dedup
+
+Before creating the cycle summary, deduplicate findings:
 ```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
+EXISTING=$(gh issue list --label "sim" --state open --json title --jq '.[].title')
 ```
+Skip creating any issue whose title matches an existing open issue (fuzzy — same key words).
 
-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.
+## Phase 5 — GitHub Output
+
+### 5a. Create cycle parent issue
+
+```bash
+gh issue create \
+  --title "[Sim] Cycle [N] — [date]" \
+  --label "cycle,sim" \
+  --body "## Simulation Cycle [N]
+
+**Date:** [ISO date]
+**Customers:** [count]
+**Bugs found:** [N] (critical: [N], high: [N], medium: [N], low: [N])
+**Fixed inline:** [N]
+**Issues created:** [list of #numbers]
+
+### UX Audit Scores
+| Dimension | Score |
+|-----------|-------|
+| Visual hierarchy | [N]/10 |
+| Navigation | [N]/10 |
+| Forms & input | [N]/10 |
+| Feedback | [N]/10 |
+| Accessibility | [N]/10 |
+| Responsive | [N]/10 |
+| Content | [N]/10 |
+| Performance | [N]/10 |
+| Consistency | [N]/10 |
+| **Average** | **[N]/10** |
+
+### Highlights
+[Notable positive findings — things working well]
+
+### Session Logs
+[Links to .vibekit/sessions/ HTML files]"
+```
+
+### 5b. Update Highlights Index
+
+Find the Highlights Index issue and append new highlights:
+```bash
+HIGHLIGHTS_N=$(gh issue list --label "highlight" --state all --limit 1 --json number --jq '.[0].number // empty')
+if [ -n "$HIGHLIGHTS_N" ]; then
+  gh issue comment $HIGHLIGHTS_N --body "## Cycle [N] Highlights
+[list of positive findings]"
+fi
+```
+
+---
+
+## Phase 6 — Refresh
+
+```bash
+npx codebase scan-only --quiet --sync
+```
+
+---
+
+## Phase 7 — Loop
+
+Print cycle summary:
+```
+CYCLE [N] COMPLETE
+════════════════════════════════════════════════════
+  Bugs found:      [N]
+  Fixed inline:    [N]
+  Issues created:  [N]
+  UX average:      [N]/10
+  Carry bugs:      [N]
+════════════════════════════════════════════════════
+```
+
+If running in continuous mode (no `--journey-only` or `--cx-only`): increment cycle number, return to Phase 0 preflight.
+
+Otherwise: exit.
+
+---
+
+## Ground Rules
+
+1. **One fix, one commit** — never batch unrelated changes
+2. **`git add [specific files]`** — never `git add .`
+3. **Always push to develop** — no feature branches for inline fixes
+4. **Create issues for everything** — even things you fix, so there's a record
+5. **No force push** — use `git revert` to undo
+6. **Read PRODUCT.md** — personas and roles come from there, never hardcoded
+7. **Sequential browser sessions** — one tab at a time, no parallel navigation
+8. **Screenshot evidence** — every bug needs visual proof
+9. **Dedup before creating** — don't file duplicate issues
+10. **Refresh manifest after every fix** — keeps `codebase next` current
+
+## Browser Automation Reference (agent-browser)
+
+```bash
+agent-browser open <url>           # navigate to URL
+agent-browser snapshot -i          # accessibility tree → @e1, @e2 element refs
+agent-browser click @e1            # click element
+agent-browser fill @e2 "text"      # type into input
+agent-browser screenshot           # capture current page
+agent-browser auth save <profile>  # save auth state
+agent-browser auth login <profile> # restore auth state
+agent-browser state save <name>    # save page state
+agent-browser state load <name>    # restore page state
+```