codebase-ai 0.3.3 → 0.3.5

package/README.md

@@ -1,4 +1,6 @@
-# CodeBase
+<p align="center">
+  <img src="assets/logo.svg" alt="codebase" width="800"/>
+</p>
 
 <p align="center">
   <img src="https://img.shields.io/npm/v/codebase-ai" alt="npm version" />
@@ -9,176 +11,101 @@
   <a href="https://securityscorecards.dev/viewer/?uri=github.com/ZySec-AI/codebase"><img src="https://api.securityscorecards.dev/projects/github.com/ZySec-AI/codebase/badge" alt="OpenSSF Scorecard" /></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.
+> **~95% fewer tokens.** Claude reads one 500-token snapshot instead of exploring thousands of files. Instant context, every session.
 
 ---
 
-## The loop
-
-Once set up, your entire development loop is:
+## Install
 
-```
-/simulate  →  /build  →  /launch
+```bash
+npm install -g codebase-ai
 ```
 
-Or if you want zero intervention — one command that runs the entire loop automatically:
+Then in your project:
 
+```bash
+npx codebase-ai
 ```
-/vibeloop
-```
-
-Here's what each step 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
+That's it. Every Claude session now starts with instant project context.
 
-After `/simulate`, your repo has real user-found bugs tracked and many already fixed.
+> Requires Node.js 20+. For the autonomous loop, also install [Claude Code](https://www.npmjs.com/package/@anthropic-ai/claude-code) and run `gh auth login`.
 
 ---
 
-### `/build` — AI works through your issue backlog
+## What it does
 
-Claude reads your open GitHub Issues (prioritized by label), picks the most important one, and implements the fix. It:
+`codebase` is a vibecoding loop built around three ideas:
 
-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
+- **Codebase = brain.** One scan writes a compact snapshot (`.codebase.json`) — your stack, commands, open issues, recent decisions. AI reads this instead of exploring files. ~95% fewer tokens, instant context.
+- **GitHub = memory.** Issues, PRs, and labels are the persistent state. The loop can restart anytime and pick up where it left off.
+- **Claude = execution.** Slash commands give AI a complete workflow: simulate real users, fix bugs, run tests, commit, ship.
 
-This runs in a loop. You can run `/build` once or keep it running until the backlog is clear.
+Multiple developers can jump into the same loop. Commit `.codebase.json` and `.claude/commands/` — everyone gets the same context and commands.
 
 ---
 
-### `/launch` — AI ships your release
+## The loop
 
-Before merging to `main`, Claude checks four quality gates:
+<p align="center">
+  <img src="assets/loop.svg" alt="codebase loop animation" width="800"/>
+</p>
 
-| 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 |
+Or run the entire loop hands-free with one command:
 
-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
+```
+/vibeloop
+```
 
-One command. Zero manual steps.
+| Command | What it does |
+|---------|-------------|
+| `/simulate` | Opens your app in a real browser. Acts like real users. Fixes bugs inline, tracks complex ones as GitHub Issues. |
+| `/build` | Reads open issues, picks the highest priority, implements the fix, tests it, commits, closes the issue. Repeats. |
+| `/launch` | Checks quality gates (open bugs, test suite, UX score). If all pass: bumps version, tags release, merges to main, publishes GitHub Release. |
+| `/vibeloop` | **Runs everything.** Continuous `/simulate → /build → /launch` loop. Zero intervention. |
+
+First time? Run `/setup` in Claude Code to create `docs/PRODUCT.md` and your first milestone.
 
 ---
 
 ## Quick start
 
-### Level 1 — Give Claude memory of your project
-
-Only requires Node.js 20+.
+**Level 1 — Give Claude memory of your project** (Node.js only)
 
 ```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`
+Scans your project and wires everything: `.codebase.json`, `CLAUDE.md`, MCP server, git hooks, `.gitignore`.
 
-That's it. Every Claude session now starts with instant project context — no re-explaining, no file pasting.
+**Level 2 — Autonomous dev loop**
 
----
-
-### 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
+npm install -g @anthropic-ai/claude-code
+gh auth login
 ```
 
----
-
-## Why does Claude actually understand my project?
-
-Without codebase, Claude starts every session knowing nothing:
+Open Claude Code in your project, then:
 
 ```
-Session start → reads package.json → reads src/ → reads tests/ → reads configs...
-30 seconds + ~10,000 tokens later: "ok so you're using Next.js..."
+/setup      ← run once
+/simulate   ← find & fix bugs
+/build      ← clear the backlog
+/launch     ← ship
 ```
 
-With codebase, every session starts instantly:
+Or just:
 
 ```
-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"
+/vibeloop   ← does all of the above, continuously
 ```
 
-**~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 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. |
-| `/vibeloop` | **The single command that does everything.** Runs `/simulate → /build → /launch` in a fully autonomous loop until your project is shipped. Zero human intervention required. |
-
-### `/vibeloop` — the one command to rule them all
-
-If you only remember one command, make it this one:
+## `/vibeloop` — zero intervention mode
 
 ```
 /vibeloop                    # full autonomous run: simulate → build → launch
@@ -189,51 +116,41 @@ If you only remember one command, make it this one:
 /vibeloop --version 1.2.0    # pin the release version tag
 ```
 
-`/vibeloop` runs the full loop repeatedly — simulate real users, fix what breaks, clear the issue backlog, ship the release — without you touching the keyboard. You invoke it once and come back to a shipped, tested, tagged release.
+Invoke once. Come back to a shipped, tested, tagged release.
 
 ---
 
-## 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
+## All CLI commands
 
-This means you can safely let the AI commit to `develop`. Nothing reaches `main` until you run `/launch` and the quality gates pass.
+```bash
+# First run
+npx codebase-ai            # scan + wire AI tools + hooks
 
----
+# Re-wire after adding a new AI tool
+codebase setup
 
-## What gets captured in `.codebase.json`
+# AI interface
+codebase brief             # full project briefing
+codebase next              # highest-priority open issue
+codebase status            # kanban board + milestones
+codebase query <path>      # e.g. stack.languages or commands.test
 
-| 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 |
+# Issues
+codebase issue create "title"
+codebase issue close <n> --reason "why"
+codebase issue comment <n> --message "text"
 
-30+ languages and 100+ frameworks detected automatically.
+# Maintenance
+codebase scan              # refresh .codebase.json
+codebase doctor            # health check
+codebase fix               # auto-repair
+codebase mcp               # start MCP server
+```
 
 ---
 
 ## 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": {
@@ -245,96 +162,40 @@ Add to your Claude Code MCP config (`.mcp.json` in project root):
 }
 ```
 
-Tools available: `project_brief`, `get_codebase`, `query_codebase`, `get_next_task`, `get_blockers`, `create_issue`, `close_issue`, `rescan_project`, `list_commands`.
+Add to `.mcp.json` in your project root. Tools: `project_brief`, `get_codebase`, `query_codebase`, `get_next_task`, `get_blockers`, `create_issue`, `close_issue`, `rescan_project`, `list_commands`.
 
 ---
 
+## Team usage
 
-## 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
-# Use `npx codebase` / `codebase init` the first time: scans your project AND wires AI tools + hooks.
-# Use `codebase setup` to re-wire AI tools and hooks only — it does NOT re-scan. Run it when you
-# add a new AI tool or need to reinstall hooks on an existing project.
-npx codebase           # full setup — scan + wire AI tools + hooks (run once per project)
-codebase setup         # re-wire AI tools and hooks only (no scan)
-
-# 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
-```
+Commit `.codebase.json` and `.claude/commands/`. Every teammate with Claude Code gets the same context and slash commands. The loop is resumable — restart anytime, GitHub tracks state.
 
 ---
 
 ## 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.
+No. Everything runs locally. External calls go only to GitHub (via `gh` CLI) and Anthropic's API (only when you run Claude commands).
 
 **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.
+Manifest and AI tool wiring work without GitHub. You lose issues, PRs, releases, and labels — 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.
-
----
+Yes. 30+ languages, 100+ frameworks detected automatically.
 
-## Install
+**Will the git hooks slow down my commits?**
+No. Scan runs in ~200ms.
 
-```bash
-npm install -g codebase-ai    # global (recommended)
-npx codebase-ai               # try without installing
-pnpm add -g codebase-ai
-```
+**What does "autonomous" mean — will it break my code?**
+All AI commits go to `develop`. Nothing reaches `main` until `/launch` passes quality gates.
 
-Zero runtime dependencies. Node.js 20+ only.
+→ [Full how-it-works docs](docs/HOW-IT-WORKS.md)
 
 ---
 
 ## Contributing
 
-We welcome contributions! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for
-guidelines on how to get started, our commit conventions, and the PR process.
+We welcome contributions! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to get started, our commit conventions, and the PR process.
 
 Found a security issue? See [SECURITY.md](SECURITY.md) — do not open a public issue.
 
@@ -344,8 +205,7 @@ See [CHANGELOG.md](CHANGELOG.md) for a full version history.
 
 ## Code of Conduct
 
-This project follows a [Code of Conduct](CODE_OF_CONDUCT.md).
-By participating, you agree to uphold it.
+This project follows a [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you agree to uphold it.
 
 ## License