codebase-ai 0.1.0

package/README.md

@@ -0,0 +1,309 @@
+# CodeBase
+
+<p align="center">
+  <img src="https://img.shields.io/npm/v/codebase-ai" alt="npm version" />
+  <img src="https://img.shields.io/npm/dm/codebase-ai" alt="npm downloads" />
+  <img src="https://img.shields.io/github/license/ZySec-AI/codebase" alt="license" />
+  <a href="https://github.com/ZySec-AI/codebase/stargazers"><img src="https://img.shields.io/github/stars/ZySec-AI/codebase?style=social" alt="GitHub stars"></a>
+</p>
+
+<p align="center">
+  <b>One command. Your AI understands your project, finds bugs, fixes them, and ships.</b>
+</p>
+
+---
+
+## The idea in plain English
+
+Imagine hiring an engineer who reads your entire project in seconds and works through your bug list on demand. That's what `codebase` does — it gives AI the context and the tools to work *on* your project, not just *for* you.
+
+**Without codebase:** Every time you open Claude Code, it starts from zero. You re-explain your project, paste in files, describe what's broken. You're the coordinator. Claude is the cursor.
+
+**With codebase:** Claude reads a single compact file that captures everything about your project — your stack, your commands, your open issues. It knows where things are. It knows what needs doing. It can act.
+
+**Two things happen:**
+
+**1 — Claude gets permanent memory of your project**
+One command scans your project and writes a small snapshot file (`.codebase.json`). Claude reads this automatically on every session via `CLAUDE.md`. You never re-explain your project again.
+
+**2 — AI gets the ability to act**
+Seven slash commands give AI a complete workflow: simulate real users in a browser, work through your bug backlog, run tests, commit fixes, and ship releases. Not prompts — real, repeatable actions.
+
+---
+
+## The three commands that matter
+
+Once set up, your entire development loop is:
+
+```
+/simulate  →  /build  →  /launch
+```
+
+That's it. Here's what each one actually does:
+
+---
+
+### `/simulate` — AI becomes your user
+
+Claude opens your app in a real browser (agent-browser) and acts like a real customer. It tries to sign up, log in, complete purchases, hit edge cases. When something breaks or feels wrong, it:
+
+1. Fixes the bug directly in your code
+2. Commits the fix with a proper message
+3. Opens a GitHub Issue if the bug is too complex to fix inline
+4. Records UX problems (confusing copy, broken flows, accessibility issues) as issues
+
+After `/simulate`, your repo has real user-found bugs tracked and many already fixed.
+
+---
+
+### `/build` — AI works through your issue backlog
+
+Claude reads your open GitHub Issues (prioritized by label), picks the most important one, and implements the fix. It:
+
+1. Reads `codebase brief` to understand your project
+2. Picks the top issue labeled `vibekit`, `critical`, `high`, or `bug`
+3. Writes the fix
+4. Runs your test suite
+5. Commits if tests pass — or opens a new issue if it gets stuck
+6. Closes the original issue with a summary of what was done
+7. Moves to the next issue
+8. Repeats until the backlog is clear or you stop it
+
+This runs in a loop. You can run `/build` once or keep it running until the backlog is clear.
+
+---
+
+### `/launch` — AI ships your release
+
+Before merging to `main`, Claude checks four quality gates:
+
+| Gate | What it checks |
+|------|---------------|
+| **Bugs** | No open critical or high severity issues |
+| **Tests** | Your full test suite passes |
+| **UX score** | World-class score ≥ 7.0 (from `/simulate` cycles) |
+| **Branch** | No uncommitted changes, branch is clean |
+
+If all gates pass, it:
+- Auto-increments your version
+- Tags the release
+- Merges `develop → main` with a proper merge commit
+- Creates a GitHub Release with auto-generated release notes
+- Rotates the milestone
+
+One command. Zero manual steps.
+
+---
+
+## Quick start
+
+### Level 1 — Give Claude memory of your project
+
+Only requires Node.js 18+.
+
+```bash
+cd your-project
+npx codebase-ai
+```
+
+This scans your project and wires everything automatically:
+- Writes `.codebase.json` — a compact snapshot of your stack, commands, and structure
+- Injects smart instructions into `CLAUDE.md`
+- Configures the MCP server so Claude can query project context natively
+- Installs git hooks so the manifest stays fresh on every commit
+- Updates `.gitignore`
+
+That's it. Every Claude session now starts with instant project context — no re-explaining, no file pasting.
+
+---
+
+### Level 2 — Autonomous dev loop
+
+> **Requires:** Claude Code (`npm install -g @anthropic-ai/claude-code`) and GitHub CLI (`gh auth login`)
+
+Open Claude Code in your project and run `/setup` — this creates `docs/PRODUCT.md` and sets up your first GitHub milestone.
+
+Then run the loop:
+```bash
+/simulate    # find and fix bugs as a real user would
+/build       # clear the issue backlog
+/launch      # ship the release
+```
+
+---
+
+## Why does Claude actually understand my project?
+
+Without codebase, Claude starts every session knowing nothing:
+
+```
+Session start → reads package.json → reads src/ → reads tests/ → reads configs...
+30 seconds + ~10,000 tokens later: "ok so you're using Next.js..."
+```
+
+With codebase, every session starts instantly:
+
+```
+Session start → reads .codebase.json (~500 tokens)
+"I can see: Next.js 14, Prisma, Vitest, dev server on port 3000,
+ 3 open critical bugs, last commit 2 hours ago, milestone v1.2 is 60% done"
+```
+
+**~95% fewer tokens. Instant context. Every session.**
+
+The autonomous commands (`/simulate`, `/build`, `/launch`) all read the same manifest. That's why they work without human guidance. They know your stack, your commands, your open issues, your product brief. They're not guessing.
+
+---
+
+## All seven slash commands
+
+These live in `.claude/commands/` in your project. Commit this folder to share them with your team.
+
+| Command | Plain English |
+|---------|--------------|
+| `/setup` | First-time setup. Creates GitHub labels, your first milestone, and `docs/PRODUCT.md`. Run once per project. |
+| `/simulate` | Opens your app in a real browser. Acts like multiple types of users. Finds bugs, UX problems, and accessibility issues. Fixes what it can, tracks the rest as GitHub Issues. |
+| `/build` | Reads your open GitHub Issues. Picks the most important one. Implements the fix. Tests it. Commits it. Closes the issue. Moves to the next. Repeats. |
+| `/launch` | Checks quality gates (bugs, tests, UX score). If everything passes: bumps version, tags release, merges to main, publishes GitHub Release. |
+| `/review` | Deep code audit. Checks for security vulnerabilities, code quality problems, outdated/vulnerable dependencies, and accessibility issues. Everything goes to GitHub Issues. |
+
+---
+
+## How the git workflow works
+
+codebase enforces a simple convention that makes autonomous commits safe:
+
+- **All work happens on `develop`** — the AI commits here
+- **`main` is protected** — direct commits are blocked by a git hook
+- **Releases merge `develop → main`** — only via `codebase release`, with a proper merge commit
+- **One commit per verified fix** — the AI never batches unrelated changes
+
+This means you can safely let the AI commit to `develop`. Nothing reaches `main` until you run `/launch` and the quality gates pass.
+
+---
+
+## What gets captured in `.codebase.json`
+
+| Category | Examples |
+|----------|---------|
+| **Stack** | TypeScript, Next.js, Prisma, PostgreSQL, Vitest |
+| **Commands** | `npm run dev`, `npm test`, `npm run build` |
+| **Structure** | Where `src/` is, entry points, build output |
+| **Dependencies** | What's installed, what's outdated, what's notable |
+| **Config** | Which env vars exist, feature flags, CI setup |
+| **Git** | Recent commits, active branches, uncommitted changes |
+| **Quality** | Test framework, linter, formatter, pre-commit hooks |
+| **GitHub** | Open issues by priority, PRs, milestones, releases |
+| **Patterns** | Architecture style, API patterns, state management |
+
+30+ languages and 100+ frameworks detected automatically.
+
+---
+
+## MCP Server
+
+For AI tools that support Model Context Protocol:
+
+```bash
+codebase mcp    # start stdio MCP server
+```
+
+Add to your Claude Code MCP config (`.mcp.json` in project root):
+
+```json
+{
+  "mcpServers": {
+    "codebase": {
+      "command": "npx",
+      "args": ["codebase", "mcp"]
+    }
+  }
+}
+```
+
+Tools available: `project_brief`, `get_codebase`, `query_codebase`, `get_next_task`, `get_blockers`, `create_issue`, `close_issue`, `rescan_project`, `list_commands`.
+
+---
+
+
+## Diagnostics
+
+```bash
+codebase doctor    # shows exactly what's broken and why
+codebase fix       # auto-repairs everything doctor flags
+```
+
+`doctor` checks: manifest freshness, AI tool injection, MCP config, git hooks, commit-msg hook, `.claude/commands/`, and `.gitignore`.
+
+---
+
+## All CLI commands
+
+```bash
+# Setup
+npx codebase           # full setup — run once per project
+codebase setup         # re-run wiring (updates commands, hooks, tools)
+
+# AI interface (what AI tools call)
+codebase brief         # full project briefing
+codebase next          # highest-priority open issue
+codebase status        # kanban board + milestones
+codebase query <path>  # any field, e.g. stack.languages or commands.test
+
+# Issues
+codebase issue create "title"                    # create GitHub issue
+codebase issue close <n> --reason "why"          # close with reason
+codebase issue comment <n> --message "text"      # add comment (audit trail)
+
+# Maintenance
+codebase scan          # refresh .codebase.json
+codebase release       # quality gates → tag → develop→main → GitHub release
+codebase doctor        # health check
+codebase fix           # auto-repair
+
+# Integrations
+codebase mcp           # start MCP server
+```
+
+---
+
+## FAQ
+
+**Do I need Claude Code for this to work?**
+Yes. `codebase` is built for Claude Code. The MCP server, slash commands, and autonomous loop all require Claude Code.
+
+**What does "autonomous" actually mean — will it break my code?**
+All AI commits go to `develop`. Nothing reaches `main` until you run `/launch` and quality gates pass. You're always in control of what ships. The AI runs tests before committing and opens issues rather than guessing when it's stuck.
+
+**Does it send my code to anyone?**
+No. Everything runs locally. The only external calls are to GitHub (via `gh` CLI) and to Anthropic's API (only when you run Claude commands).
+
+**Will the git hooks slow down my commits?**
+No. The scan runs in ~200ms on most projects.
+
+**What if I don't use GitHub?**
+The manifest and AI tool wiring work without GitHub. You lose issues, PRs, releases, and labels — but the core context injection still works.
+
+**My project isn't JavaScript — does it work?**
+Yes. Detectors cover Python, Go, Rust, Ruby, Java, PHP, Swift, C#, and more. The slash commands use `codebase brief` to detect your stack and adapt automatically.
+
+**Can my whole team use this?**
+Yes. Commit `.codebase.json` and `.claude/commands/`. Every team member with Claude Code gets the same context and the same slash commands.
+
+---
+
+## Install
+
+```bash
+npm install -g codebase-ai    # global (recommended)
+npx codebase-ai               # try without installing
+pnpm add -g codebase-ai
+```
+
+Zero runtime dependencies. Node.js 18+ only.
+
+---
+
+## License
+
+MIT

package/commands/build.md

@@ -0,0 +1,171 @@
+---
+description: Autonomous development loop — builds arch issues, simulates, watches for new issues, repeats until production-ready. Uses codebase context.
+argument-hint: [--dry-run] [--issue N] [--once] [--interval N] [--max-rounds N]
+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 tag:*), Bash(git rev-parse:*), Bash(git branch:*), Bash(git merge:*), Bash(pnpm:*), Bash(npx:*), Bash(npm:*), Bash(node:*), Bash(uv:*), Read, Write, Edit, Glob, Grep
+---
+
+# /build
+
+Autonomous development loop. Builds all open `[Arch]` and `vibekit`-labeled issues, runs the test suite, runs a `/simulate` cycle, polls for new issues, repeats until launch gates pass.
+
+Branch: always `develop`. For full arch issues, use a `feat/<slug>` branch → PR → merge to develop.
+
+## Arguments
+
+```
+$ARGUMENTS
+```
+
+- *(no flags)* — full autonomous loop: build → test → simulate → poll → repeat
+- `--dry-run` — show plan only, no implementation
+- `--issue N` — implement only issue #N, then exit
+- `--once` — build all open arch issues once, then exit (no simulate cycle)
+- `--interval N` — polling interval in minutes (default: 5)
+- `--max-rounds N` — safety limit (default: 20)
+
+---
+
+## 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 `/tmp/cb-brief.json`. Extract:
+- `commands.test` — use this as the test command (fallback to package.json detection)
+- `commands.dev` — dev server start command
+- `stack.frameworks`, `stack.languages` — implementation context
+- `patterns.architecture` — follow existing patterns
+- `quality.test_framework` — confirms test runner
+
+Read `docs/PRODUCT.md` before evaluating any issue. If missing → print "Run /setup first." and exit.
+
+Load dev login path:
+```bash
+DEV_LOGIN_PATH=""
+[ -f ".vibekit/repo.env" ] && DEV_LOGIN_PATH=$(grep "DEV_LOGIN_PATH" .vibekit/repo.env 2>/dev/null | cut -d= -f2)
+```
+
+### Detect test runner
+
+Prefer `commands.test` from codebase brief. Fall back to package.json/pyproject.toml detection.
+
+### Label check
+
+```bash
+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;
+}
+```
+
+---
+
+## Phase 0 — Orientation
+
+Load project board config, define `add_to_project()` helper, parse flags, auto-triage unlabeled issues — all exactly as in `/vb-build`.
+
+For the implementation plan, use `codebase next` to surface the highest-priority item first:
+```bash
+npx codebase next 2>/dev/null || true
+```
+
+---
+
+## Phases 1–4 — Implementation Loop
+
+Follow the complete `/vb-build` workflow:
+
+- **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
+
+### codebase integration points
+
+**Before implementing each issue**, get fresh context:
+```bash
+npx codebase brief 2>/dev/null > /tmp/cb-brief.json || true
+```
+
+Read `CLAUDE.md` if present — follow its conventions exactly.
+
+**Branch + commit convention:**
+
+For small fixes (< 50 lines): commit directly to `develop`.
+For arch issues (significant changes): use a feature branch → PR.
+
+```bash
+# Pre-work: always sync first
+git fetch origin
+git status  # abort if dirty uncommitted changes exist
+git checkout develop && git pull origin develop
+
+# For arch issues — create a feature branch
+SLUG=$(echo "[issue title]" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd 'a-z0-9-' | cut -c1-40)
+git checkout -b feat/${SLUG}
+
+# ... implement the fix ...
+
+# Stash if you need to switch context mid-work
+# git stash && git checkout develop && git stash pop
+
+# Atomic commit — one commit per issue, never batch unrelated changes
+git add [specific files changed]
+git commit -m "feat(#[N]): [short description]
+
+[1-2 sentence description of what was built]
+Closes #[N]"
+git push origin feat/${SLUG}
+
+# Raise PR — do not merge directly
+gh pr create \
+  --base develop \
+  --head feat/${SLUG} \
+  --title "feat(#[N]): [short description]" \
+  --body "## What
+[description]
+
+## Test evidence
+[test output or Playwright result]
+
+Closes #[N]"
+
+# After PR is merged, 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):
+```bash
+git checkout develop && git pull origin develop
+git add [specific files changed]
+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:
+```bash
+npx codebase scan-only --incremental --quiet --sync
+```
+
+**When closing an issue via gh**:
+```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
+```
+
+**simulate step** (in full loop mode): invoke `/simulate` with `--journey-only` on even rounds, full on odd rounds.
+
+All other behavior (Playwright verification, project board updates, auto-launch gate, polling) follows the `/vb-build` specification exactly.

package/commands/launch.md

@@ -0,0 +1,220 @@
+---
+description: Gates on open bugs, runs test suite + world-class score check, generates release notes, creates GitHub release, merges develop to main.
+argument-hint: [--version X.Y.Z] [--dry-run]
+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 log:*), Bash(git status:*), Bash(git diff:*), Bash(git tag:*), Bash(git rev-parse:*), Bash(git branch:*), Bash(git merge:*), Bash(npx:*), Bash(npm:*), Bash(node:*), Read, Write, Edit, Glob, Grep
+---
+
+# /launch
+
+Release manager. Gate on open bugs, generate all release artifacts, create a GitHub release, merge to main.
+
+Branch flow: `develop` → `main`.
+
+## Arguments
+
+```
+$ARGUMENTS
+```
+
+- `--version X.Y.Z` — override version tag (default: auto-increment from latest tag)
+- `--dry-run` — run all gates and generate artifacts, do NOT create release or merge
+
+---
+
+## 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: `project.name`, `project.description`, `commands.test`, `quality.test_framework`.
+
+Read `docs/PRODUCT.md` before generating any artifact. Fetch highlights data from the Highlights Index GitHub Issue.
+
+---
+
+## Phase 0 — Gate Check
+
+All gates must pass. Any blocking failure exits.
+
+### Gate 1a — No open critical or high bugs
+
+```bash
+gh issue list --label "bug,critical" --state open --limit 10 --json number,title
+gh issue list --label "bug,high"     --state open --limit 10 --json number,title
+```
+
+If any exist → print list, exit with "BLOCKED".
+
+### Gate 1b — Test suite passes
+
+Use `commands.test` from codebase brief. Fall back to package.json/pyproject.toml detection.
+
+```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"
+```
+
+Run test suite. If failures → print last 10 lines, exit "BLOCKED".
+
+If no test files exist: warn (not blocking) — "No tests found. Run /review --test to generate them."
+
+### Gate 1c — World-class score ≥ 7.0
+
+Read the most recent `[Sim]` cycle issue body. Parse world-class scores.
+
+If average < 7.0 → exit "BLOCKED". If no data → warn only.
+
+### Gate 2 — Carry bugs (warning, not blocking)
+
+List open carry bugs — they appear in release notes as known issues.
+
+### Gate 3 — Branch clean and current
+
+```bash
+git fetch origin
+git status --short
+git log HEAD..origin/develop --oneline
+```
+
+If uncommitted changes → exit "BLOCKED: commit or stash all changes first."
+If behind remote → exit "BLOCKED: git pull origin develop".
+
+Print gate summary:
+```
+LAUNCH GATES
+════════════════════════════════════════════════════════
+Gate 1a — Critical/high bugs:   PASS (0 open)
+Gate 1b — Test suite:           [PASS | FAIL | WARNING: no tests]
+Gate 1c — World-class score:    [PASS (N/10) | FAIL (N/10 < 7.0) | WARNING]
+Gate 2  — Carry bugs:           [PASS | WARNING: N open]
+Gate 3  — Branch clean:         PASS
+All blocking gates passed. Proceeding.
+════════════════════════════════════════════════════════
+```
+
+---
+
+## Phase 1 — Version
+
+```bash
+LATEST=$(git tag --sort=-version:refname | head -1)
+```
+
+- `--version X.Y.Z` passed → use it
+- No tags → `v0.1.0`
+- Tags exist → increment patch
+
+---
+
+## Phase 2 — Release Notes
+
+Generate `docs/RELEASE-NOTES.md`:
+- **What's New** — closed `[Arch]` issues since last tag
+- **Bug Fixes** — closed `bug,sim` issues
+- **Improvements** — UX/content improvements
+- **Known Issues** — open carry bugs + open arch issues (honest, never omit)
+
+---
+
+## Phase 3 — Create GitHub Release
+
+```bash
+# Always sync before tagging
+git fetch origin
+git checkout develop && git pull origin develop
+git tag -a [version] -m "Release [version]"
+git push origin [version]
+
+gh release create [version] \
+  --title "v[version]" \
+  --notes-file docs/RELEASE-NOTES.md \
+  --target develop
+```
+
+If `--dry-run`: print what would be created, skip.
+
+---
+
+## Phase 4 — Merge to Main
+
+```bash
+git checkout main && git pull origin main
+git merge develop --no-ff -m "Release [version]"
+git push origin main
+git checkout develop
+```
+
+If `--dry-run`: print what would happen, skip.
+
+---
+
+## Phase 5 — Milestone rotation
+
+Load `.vibekit/milestone.env`. Close current milestone. Create next (increment minor: v0.1 → v0.2).
+
+---
+
+## Phase 6 — Refresh codebase manifest
+
+```bash
+npx codebase scan-only --quiet --sync
+```
+
+This updates `.codebase.json` with the new release tag so `codebase brief` reflects the released version.
+
+---
+
+## Phase 7 — Summary
+
+```
+/launch COMPLETE
+════════════════════════════════════════════════════════
+Version:        [version]
+Release date:   [date]
+GitHub release: [URL]
+
+Artifacts:
+  docs/RELEASE-NOTES.md
+
+develop → main:  merged
+Tag [version]:   pushed
+Milestone:       [v0.1 closed → v0.2 created]
+.codebase.json:  refreshed
+
+[If --dry-run: DRY RUN — no release, no merge]
+════════════════════════════════════════════════════════
+```
+
+---
+
+## Ground Rules
+
+1. **Gates 1a/1b/1c failures always block** — no exceptions
+2. **Grounded release notes** — every item traceable to a closed GitHub Issue
+3. **main is production** — merging to main is the last step, only via /launch
+4. **Dry-run is safe** — never touches git history or creates releases
+5. **Honest known issues** — never omit carry bugs or open arch from release notes
+6. **No force push ever** — use `git revert` to undo commits
+7. **No direct push to main** — only the merge step in Phase 4 touches main
+
+## Branch Convention (reference)
+
+```
+main          protected — only /launch merges here
+develop       integration branch — 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 prod fixes    (→ PR to develop, then /launch fast-track)
+docs/<slug>   documentation only   (→ PR to develop)
+test/<slug>   test additions       (→ PR to develop)
+```