uv-suite 0.7.0 → 0.9.0

package/README.md

@@ -4,29 +4,82 @@ Portable framework for AI-assisted software development. Works with Claude Code,
 
 ## Install
 
+```bash
+npm install -g uv-suite
+uv install
+```
+
+Or with npx:
+
 ```bash
 npx uv-suite install
 ```
 
-Or clone and run directly:
+This installs 10 agents, 10 skills, 8 hooks, 6 guardrails, and 4 personas into your project.
+
+## Quick Start
 
 ```bash
-git clone https://github.com/utsavanand/uv-suite.git
-cd uv-suite
-./install.sh
+uv install                    # Install UV Suite into current project
+uv claude pro                 # Start Claude Code, Professional persona
+uv codex auto                 # Start Codex, Auto persona
+uv pro                        # Shorthand for uv claude pro
+```
+
+## Modes
+
+Four personas for different contexts. Pick one when you start a session.
+
+```
+             Spike          Sport        Professional       Auto
+             ─────          ─────        ────────────       ────
+Purpose      Research       Build new    Ship to prod       Let it run
+             & document     things
+
+Model        Opus           Sonnet       Inherit            Inherit
+Effort       max            high         high               max
+
+Writes       New files      Anything     Anything           Anything
+             only                        (reviewed)         (autonomous)
+Edits        Blocked        Allowed      Allowed            Allowed
+
+Hooks        1              1            8                  3
+             doc-slop       lint         all                lint, block,
+                                                            timer
+
+Guardrails   Doc slop       None         All 6              All 6
+
+Human gates  After each     End only     Every Act          Final output
+             map                         boundary           only
 ```
 
-This installs 10 agents, 9 skills, 5 hooks, 6 guardrails, and 4 personas into your project's `.claude/` directory.
+### When to use what
+
+| Situation | Mode | Why |
+|-----------|------|-----|
+| Joining a new codebase | **Spike** | Understand before changing. Writes docs, not code. |
+| Architecture review | **Spike** | Map the system, write ADRs, document findings. |
+| Prototyping a demo | **Sport** | Move fast, iterate freely, quality comes later. |
+| Hackathon or new project | **Sport** | Get the foundation down without review gates. |
+| Fixing a bug in production code | **Professional** | Every change matters. Full review rigor. |
+| Adding a feature to an existing service | **Professional** | Team depends on this code. Slop-checked. |
+| Well-scoped task with a clear spec | **Auto** | Let the agent build, test, review end-to-end. |
+| Batch of small tasks | **Auto** | Agent handles repetitive work autonomously. |
+
+**Common progressions:**
+- Spike → Sport → Professional (understand, explore, harden)
+- Spike → Auto (research thoroughly, then let the agent execute)
+- Sport → Professional (prototype fast, switch to rigor when it matters)
 
 ## What You Get
 
 | Category | Count | What |
 |----------|-------|------|
 | Agents | 10 | Subagent definitions for Claude Code, Cursor, and Codex |
-| Skills | 9 | Slash commands with dynamic context injection |
-| Hooks | 5 | Auto-lint, slop check, danger zones, destructive blocks, review reminder |
+| Skills | 10 | Slash commands with dynamic context injection |
+| Hooks | 8 | Auto-lint, slop check, danger zones, session tracking, destructive blocks |
 | Guardrails | 6 | Anti-slop rules (comments, overengineering, tests, docs, architecture, errors) |
-| Personas | 4 | Spike, Sport, Professional, Auto — different rigor for different contexts |
+| Personas | 4 | Spike, Sport, Professional, Auto |
 
 ## Three Subsystems
 
@@ -43,11 +96,12 @@ Remember          Present           Protect
 
 **UV Guard** catches AI slop in real time, reviews code for security (OWASP, [Semgrep](https://github.com/semgrep/semgrep)), and enforces danger zones.
 
-## Skills (Slash Commands)
+## Skills
 
 | Command | What it does |
 |---------|-------------|
 | `/map-codebase [dir]` | Build a knowledge graph of the codebase |
+| `/map-stack [dir]` | Map multiple services and their connections |
 | `/spec [requirements]` | Write a technical specification |
 | `/architect [spec]` | Design architecture, decompose into Acts |
 | `/review` | Code review: correctness, security, performance, slop |
@@ -57,87 +111,51 @@ Remember          Present           Protect
 | `/prototype [concept]` | Build a static React prototype |
 | `/security-review` | OWASP audit, dependency scan, secret detection |
 
-## Personas
-
-Different contexts need different rigor. Pick a persona when you start a session.
-
-```bash
-./uv.sh spike        # Research & docs (Opus, max effort, doc-slop checked)
-./uv.sh sport        # New projects (Sonnet, high effort, lint only)
-./uv.sh pro          # Production code (all hooks, all guardrails)
-./uv.sh auto         # Fully autonomous (max effort, everything approved)
-```
-
-Or launch Claude directly:
-
-```bash
-claude --settings .claude/personas/professional.json
-```
-
-| Persona | For | Effort | Hooks | Guardrails |
-|---------|-----|--------|-------|------------|
-| **Spike** | Research, documentation | max | 1 (doc slop) | Doc slop |
-| **Sport** | New projects, prototyping | high | 1 (lint) | None |
-| **Professional** | Production code (default) | high | All 5 | All 6 |
-| **Auto** | Fully autonomous execution | max | 2 (lint + block) | All 6 |
+## Hooks
 
-## Hooks (Automatic)
-
-These fire without invocation. You never type these.
+Fire automatically. You never invoke these.
 
 | Hook | Fires on | What it does |
 |------|----------|-------------|
-| auto-lint | Every file write | Runs prettier, ruff, or gofmt |
-| Slop check | Every file write | Haiku scans for obvious slop patterns |
-| Danger zone | Every file edit | Warns if file is in DANGER-ZONES.md |
-| Destructive block | Every bash command | Blocks rm -rf, force push, DROP TABLE |
-| Review reminder | Session ending | Reminds to /review if uncommitted changes |
+| auto-lint | File write | Runs prettier, ruff, or gofmt |
+| Slop check | File write | Haiku scans for obvious slop patterns |
+| Danger zone | File edit | Warns if file is in DANGER-ZONES.md |
+| Destructive block | Bash command | Blocks rm -rf, force push, DROP TABLE |
+| Session start | Session start | Records start time for duration tracking |
+| Session timer | Every 20th tool call | Checkpoint reminders at 45/90/180 min |
+| Session end | Session stop | Shows duration, today's total, reflection prompt |
+| Status line | Continuous | Shows session time in Claude Code's status bar |
 
 ## Agents
 
-10 agents, each available in 4 formats:
-
-| Agent | Subsystem | Model | Read-only | Cycle Budget |
-|-------|-----------|-------|-----------|-------------|
-| Cartographer | UV Index | Opus | Yes | 1 |
-| Spec Writer | UV Acts | Opus | No | 1 |
-| Architect | UV Acts | Opus | No | 1 |
-| Reviewer | UV Guard | Opus | Yes | 1 |
-| Test Writer | UV Acts | Sonnet | No | 3 |
-| Eval Writer | UV Acts | Opus | No | 2 |
-| Anti-Slop Guard | UV Guard | Opus | Yes | 1 |
-| Prototype Builder | UV Acts | Sonnet | No | 3 |
-| DevOps | UV Acts | Sonnet | No | 2 |
-| Security | UV Guard | Opus | Yes | 1 |
+10 agents, each in 4 formats (Claude Code, Cursor, Codex, Portable):
 
-Each agent has definitions for:
-- **Claude Code** — `.claude/agents/*.md`
-- **Cursor** — `.cursor/rules/*.mdc`
-- **Codex** — `.codex/agents/*.toml`
-- **Portable** — tool-agnostic Markdown
+| Agent | Subsystem | Model | Cycle Budget |
+|-------|-----------|-------|-------------|
+| Cartographer | UV Index | Opus | 1 |
+| Spec Writer | UV Acts | Opus | 1 |
+| Architect | UV Acts | Opus | 2 |
+| Reviewer | UV Guard | Opus | 1 |
+| Test Writer | UV Acts | Sonnet | 3 |
+| Eval Writer | UV Acts | Opus | 2 |
+| Anti-Slop Guard | UV Guard | Opus | 1 |
+| Prototype Builder | UV Acts | Sonnet | 3 |
+| DevOps | UV Acts | Opus | 2 |
+| Security | UV Guard | Opus | 1 |
 
-## Human-in-the-Loop
+## Artifacts
 
-Agents get cycle budgets — maximum attempts before mandatory escalation to the human. Four intervention types:
+Agents write persistent output to `uv-out/`. Each agent reads prior artifacts automatically.
 
-- **Teach** — domain knowledge the agent lacks
-- **Debug** — when the agent is stuck after retries
-- **Taste** — subjective and aesthetic decisions
-- **Clarify** — ambiguous or conflicting requirements
-
-Every intervention gets persisted so the agent doesn't need re-teaching.
-
-## Collaboration
-
-- **DANGER-ZONES.md** — mark risky areas, agents check before modifying
-- **Inline annotations** — `@danger`, `@agent-skip`, `@agent-ask` in code
-- **Sharing levels** — personal, project, team, community
-- **Team-evolved standards** — best practices that improve through use
+| Agent output | Read by |
+|-------------|---------|
+| `uv-out/map-codebase.md` | /architect, /review, /security-review |
+| `uv-out/specs/*.md` | /architect, /write-tests, /write-evals |
+| `uv-out/architecture/*.md` | /review, /write-tests, /slop-check |
+| `uv-out/review-*.md` | /slop-check, /security-review |
 
 ## Integrations
 
-UV Suite works with the open source ecosystem:
-
 | Tool | Used by | Purpose |
 |------|---------|---------|
 | [Graphify](https://github.com/safishamsi/graphify) | Cartographer | Knowledge graph from codebase via Tree-sitter |
@@ -145,7 +163,7 @@ UV Suite works with the open source ecosystem:
 | [Gitleaks](https://github.com/gitleaks/gitleaks) | Security Agent | Secret detection in git repos |
 | [Trivy](https://github.com/aquasecurity/trivy) | Security Agent | Dependency vulnerability scanning |
 | [DeepEval](https://github.com/confident-ai/deepeval) | Eval Writer | Pytest-compatible LLM evaluation |
-| [Ruff](https://github.com/astral-sh/ruff) | auto-lint hook | Python linting and formatting |
+| [Playwright](https://playwright.dev/docs/getting-started-mcp) | Prototype Builder, Test Writer | Browser automation and e2e testing |
 
 ## Project Structure After Install
 
@@ -153,27 +171,28 @@ UV Suite works with the open source ecosystem:
 .claude/
   settings.json        Permissions, hooks (from persona)
   agents/              10 agent definitions
-  skills/              9 slash commands
-  hooks/               4 hook scripts
+  skills/              10 slash commands
+  hooks/               7 hook scripts
   rules/               6 anti-slop guardrails
   personas/            4 persona configs
+.codex/agents/         10 Codex agent definitions
+.cursor/rules/         10 Cursor rule definitions
+AGENTS.md              Codex instruction file
 DANGER-ZONES.md        Risky areas (commit this)
-uv.sh                  Session launcher
+uv-out/                Agent output artifacts (gitignored)
 ```
 
 ## Documentation
 
 | Document | What it covers |
 |----------|---------------|
-| [usage-guide.md](usage-guide.md) | Full SDLC mapped to exact commands and invocations |
+| [usage-guide.md](usage-guide.md) | Full SDLC mapped to exact commands |
 | [personas.md](personas.md) | 4 personas, 7 knobs, when to use each |
+| [practices.md](practices.md) | Working principles (honesty, parallelism, scope, completion) |
 | [acts-methodology.md](acts-methodology.md) | Acts delivery framework with worked examples |
 | [methodology/human-in-the-loop.md](methodology/human-in-the-loop.md) | Cycle budgets, intervention types, learning loops |
 | [collaboration/sharing-and-standards.md](collaboration/sharing-and-standards.md) | Danger zones, team standards, sharing levels |
 | [landscape.md](landscape.md) | Open source tools and references for each agent |
-| [agents.md](agents.md) | Full specifications for all 10 agents |
-| [anti-slop.md](anti-slop.md) | 6 categories of AI slop with detection rules |
-| [tool-comparison.md](tool-comparison.md) | Claude Code vs Cursor vs Codex comparison |
 
 ## License
 

package/agents/claude-code/anti-slop-guard.md

@@ -79,9 +79,9 @@ Comments that restate the code. If deleting the comment loses no information, it
 
 ## Rules
 
-- Be specific. Point to exact lines and explain why it's slop.
+- Be specific: exact lines, why it's slop, how to fix.
 - High = actively harmful. Medium = wasteful. Low = stylistic.
-- If the code is clean, say "No slop detected." Don't hunt for problems that aren't there.
+- If the code is clean, say "No slop detected."
 
 ## Cycle Budget
 

package/agents/claude-code/architect.md

@@ -65,9 +65,9 @@ Mermaid diagram showing parallelism opportunities.
 - Every design decision needs a "why" — not just what you chose, but why.
 - Acts must deliver complete vertical slices, not horizontal layers.
 - Tasks within an Act should be parallelizable where possible.
-- Keep the architecture as simple as the requirements allow.
-- When in doubt, choose the boring technology.
+- Prefer established technologies unless a requirement justifies otherwise.
 - 3-7 tasks per Act. If more, break into separate Acts.
+- Maximize parallelism — identify independent tasks that agents can run simultaneously.
 - Annotate each task with a cycle budget.
 - Identify where human taste/judgment is needed before the agent proceeds.
 

package/agents/claude-code/devops.md

@@ -43,7 +43,7 @@ You are the **DevOps Agent** — your job is to set up reliable CI/CD pipelines,
   - **Deploy:** exact commands to ship
   - **Rollback:** exact commands to revert
   - **Debug:** where to look when things break (logs, metrics, dashboards)
-- Don't over-engineer. A simple GitHub Actions workflow is fine.
+- Run independent pipeline steps in parallel where possible (lint + test simultaneously)
 
 ## Cycle Budget
 

package/agents/claude-code/reviewer.md

@@ -80,12 +80,11 @@ Line 30 fetches all orders, then line 33 loops and queries User for each one. Fi
 
 ## Rules
 
-- Be specific. "This might have a bug" is useless. Point to the exact line, show the code, explain the issue, show the fix.
-- Don't nitpick style unless it hurts readability.
-- Focus on what matters: correctness > security > performance > style.
-- Severity = exploitability x impact. A timing attack is lower priority than a data leak.
-- If the code is good, say so. Don't manufacture issues.
-- Check the tests: do they test behavior or just exercise code paths?
+- Be specific: line number, code snippet, fix.
+- Focus: correctness > security > performance > style.
+- Severity = exploitability x impact.
+- If the code is clean, say so.
+- Run review checks in parallel where possible (correctness, security, performance simultaneously).
 
 ## Cycle Budget
 

package/guardrails/test-slop.md

@@ -10,7 +10,7 @@ Tests that pass but don't actually verify behavior. They inflate coverage metric
 ## Detection Rules
 
 - `expect(x).toBeTruthy()` or `expect(x).toBeDefined()` — almost always slop
-- Tests where the mock is the only thing being tested (you're testing your setup, not your code)
+- Tests where the mock is the only thing being tested
 - Snapshot tests on simple/trivial components
 - Tests with no assertions
 - Tests that test framework behavior ("does React render a component?")

package/hooks/session-timer.sh

@@ -33,13 +33,13 @@ MESSAGE=""
 WARN_LEVEL=0
 
 if [ "$MINUTES" -ge 180 ] && [ "$LAST_WARN" -lt 3 ]; then
-  MESSAGE="SESSION HEALTH (3+ hours): You've been in this session for ${MINUTES} minutes. This is a long stretch. Strongly consider: (1) commit what you have, (2) close this session, (3) take a real break away from the screen. Long uninterrupted agent sessions lead to goal drift, lower judgment quality, and burnout. /compact if you must continue, but a break is better."
+  MESSAGE="CHECKPOINT (${MINUTES} min): Long session. Commit what you have, then consider a fresh session. /compact if continuing."
   WARN_LEVEL=3
 elif [ "$MINUTES" -ge 90 ] && [ "$LAST_WARN" -lt 2 ]; then
-  MESSAGE="SESSION HEALTH (90+ min): You've been in this session for ${MINUTES} minutes. Consider taking a 10-minute break — stretch, water, walk. Come back with fresh eyes. Also a good time to commit progress."
+  MESSAGE="CHECKPOINT (${MINUTES} min): Good time to commit progress and take a break."
   WARN_LEVEL=2
 elif [ "$MINUTES" -ge 45 ] && [ "$LAST_WARN" -lt 1 ]; then
-  MESSAGE="SESSION HEALTH (45 min): You've been in this session for ${MINUTES} minutes. Good time for a quick break and to commit any progress."
+  MESSAGE="CHECKPOINT (${MINUTES} min): Consider committing progress."
   WARN_LEVEL=1
 fi
 

package/install.sh

@@ -102,7 +102,7 @@ cp "$UV_SUITE_DIR/agents/cursor/"*.mdc "$PROJECT_ROOT/.cursor/rules/"
 echo "  ✓ .cursor/rules/*.mdc installed"
 
 # --- Install skills (slash commands) ---
-echo "Installing 9 skills..."
+echo "Installing 10 skills..."
 for skill_dir in "$UV_SUITE_DIR/skills/"*/; do
   skill_name=$(basename "$skill_dir")
   mkdir -p "$TARGET_DIR/skills/$skill_name"
@@ -110,6 +110,7 @@ for skill_dir in "$UV_SUITE_DIR/skills/"*/; do
 done
 echo "  ✓ /map-codebase, /spec, /architect, /review, /write-tests"
 echo "  ✓ /write-evals, /slop-check, /prototype, /security-review"
+echo "  ✓ /map-stack"
 
 # --- Install hooks ---
 echo "Installing hook scripts..."
@@ -221,9 +222,25 @@ Agent output is written to uv-out/. Agents read prior artifacts automatically:
 
 ${HOOKS_TEXT}
 
-### Personas
+### Working practices
 
-Start sessions with: ./uv.sh spike | sport | pro | auto
+**Honesty:** If you can't find a doc, file, or function, say "I did not find X. What should I do?" Don't fabricate. If 2-3 attempts fail, escalate with what you tried.
+
+**Parallelism:** Move fast. Spin up parallel agents for independent tasks. Run independent tool calls in the same message. Parallelize wherever possible — this is the primary speed lever.
+
+**Scope:** Stay focused. If you notice something worth fixing outside scope, mention it at the end, don't silently change it.
+
+**Completion:** "Done" means verified. Run the tests. Prefer "I ran it and it works" over "should work."
+
+**Failures:** When you fail, say so. Escalate: what you tried, why each failed, what you need.
+
+**User context:** If something looks wrong, ask why before fixing. Users have constraints you may not see.
+
+**Session:** Long conversation? Suggest /compact or a new session. Past 90 min, suggest a break.
+
+### Launching sessions
+
+uv claude pro | uv codex pro | uv pro (shorthand)
 EOF
 
   echo "  ✓ UV Suite section added to CLAUDE.md"
@@ -328,102 +345,6 @@ else
   echo "    Register manually after installing Claude Code: claude mcp add playwright -- npx @playwright/mcp@latest"
 fi
 
-# --- Write UV Suite context to CLAUDE.md ---
-if [ "$INSTALL_MODE" = "project" ]; then
-  PROJECT_ROOT="$(dirname "$TARGET_DIR")"
-  CLAUDE_MD="$PROJECT_ROOT/CLAUDE.md"
-
-  # Check if UV Suite section already exists
-  if [ -f "$CLAUDE_MD" ] && grep -q "## UV Suite" "$CLAUDE_MD" 2>/dev/null; then
-    echo "Updating UV Suite section in CLAUDE.md..."
-    # Remove old UV Suite section and rewrite
-    sed -i.bak '/^## UV Suite$/,/^## [^U]/{ /^## [^U]/!d; }' "$CLAUDE_MD" 2>/dev/null || true
-    rm -f "$CLAUDE_MD.bak" 2>/dev/null
-  else
-    echo "Adding UV Suite section to CLAUDE.md..."
-  fi
-
-  cat >> "$CLAUDE_MD" << CLAUDEMD
-
-## UV Suite
-
-This project uses [UV Suite](https://github.com/utsavanand/uv-suite) for AI-assisted development.
-
-**Active persona:** $PERSONA_LABEL
-**Version:** $(cat "$UV_SUITE_DIR/package.json" 2>/dev/null | grep '"version"' | head -1 | sed 's/.*: "//;s/".*//')
-
-### Available skills (slash commands)
-
-| Command | Agent | What it does |
-|---------|-------|-------------|
-| /map-codebase [dir] | Cartographer | Build knowledge graph of codebase |
-| /map-stack [dir] | Cartographer | Map multiple services and their connections |
-| /spec [requirements] | Spec Writer | Write technical specification |
-| /architect [spec] | Architect | Design architecture, decompose into Acts |
-| /review | Reviewer | Code review (correctness, security, perf, slop) |
-| /write-tests [file] | Test Writer | Generate tests matching project conventions |
-| /write-evals [prompt] | Eval Writer | Write AI/LLM evaluation cases |
-| /slop-check | Anti-Slop Guard | Detect 6 categories of AI-generated slop |
-| /prototype [concept] | Prototype Builder | Build static React prototype |
-| /security-review | Security Agent | OWASP audit, dependency scan, secret detection |
-
-### Artifacts
-
-All agent output is written to \`uv-out/\`. Each agent reads relevant prior artifacts from this directory automatically.
-
-| Artifact | Written by | Read by |
-|----------|-----------|---------|
-| uv-out/map-codebase.md | /map-codebase | /architect, /review, /security-review |
-| uv-out/specs/*.md | /spec | /architect, /write-tests, /write-evals |
-| uv-out/architecture/*.md | /architect | /review, /write-tests, /slop-check |
-| uv-out/review-*.md | /review | /slop-check, /security-review |
-| uv-out/security-review-*.md | /security-review | — |
-| uv-out/slop-check-*.md | /slop-check | — |
-
-### Active hooks
-
-Hooks fire automatically on every relevant action. You do not invoke these.
-
-$(if [ "$PERSONA" = "professional" ]; then
-cat << 'HOOKS'
-- **auto-lint** (on file write) — runs prettier/ruff/gofmt
-- **slop check** (on file write) — Haiku scans for obvious slop
-- **danger zone** (on file edit) — warns if file is in DANGER-ZONES.md
-- **destructive block** (on bash) — blocks rm -rf, force push
-- **review reminder** (on session end) — reminds to /review if uncommitted changes
-HOOKS
-elif [ "$PERSONA" = "auto" ]; then
-cat << 'HOOKS'
-- **auto-lint** (on file write) — runs prettier/ruff/gofmt
-- **destructive block** (on bash) — blocks rm -rf, force push
-HOOKS
-elif [ "$PERSONA" = "sport" ]; then
-cat << 'HOOKS'
-- **auto-lint** (on file write) — runs prettier/ruff/gofmt
-HOOKS
-elif [ "$PERSONA" = "spike" ]; then
-cat << 'HOOKS'
-- **doc slop check** (on file write) — Haiku checks documentation quality
-HOOKS
-fi)
-
-### Context management
-
-If the conversation is getting long, proactively suggest running /compact or starting a new session. Use /cost to check token usage. The user's status line shows context window usage.
-
-### Launching sessions
-
-\`\`\`
-uv claude pro     # Claude Code, Professional persona
-uv claude auto    # Claude Code, Auto persona
-uv codex pro      # OpenAI Codex, Professional persona
-uv codex sport    # OpenAI Codex, Sport persona
-\`\`\`
-CLAUDEMD
-
-  echo "  ✓ UV Suite section added to CLAUDE.md"
-fi
-
 # --- Install launcher script ---
 echo "Installing session launcher..."
 cp "$UV_SUITE_DIR/uv.sh" "$TARGET_DIR/../uv.sh" 2>/dev/null || true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uv-suite",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Portable framework for AI-assisted software development. 10 agents, 9 skills, 5 hooks, 4 personas. Works with Claude Code, Cursor, and Codex.",
   "author": "Utsav Anand",
   "license": "MIT",