uv-suite 0.29.0 → 0.30.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Utsav Anand
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -38,7 +38,31 @@ Label this session (Enter to skip — you'll be reminded):
   priority [low/med/high]:  high
 ```
 
-Skip any field with Enter. If you skip the name, `/session-init` will be suggested every few prompts until you label it. Set `UVS_NO_PROMPT=1` to suppress prompts entirely.
+Skip any field with Enter. If you skip the name, `/session init` will be suggested every few prompts until you label it. Set `UVS_NO_PROMPT=1` to suppress prompts entirely.
+
+## Start here
+
+After `uvs claude pro`, pick the path that matches what you're doing. Each path names the first skill to run and the canonical next steps.
+
+### Existing codebase (you didn't write this)
+1. `/understand` — builds a knowledge graph + architecture overview in `uv-out/map-codebase.md`. Other skills (`/architect`, `/review`, `/review --security`) read it automatically.
+2. `/session checkpoint` — captures your baseline understanding so `/session restore` can bring it back next session.
+3. Then: `/review` on the current diff, or `/spec` for the next feature.
+
+### New project (you're starting from scratch)
+1. `/spec` — converts your idea into a structured spec in `uv-out/specs/`.
+2. `/architect` — breaks the spec into Acts with cycle budgets. Reads the spec automatically.
+3. Then: implement Act by Act. Use `/test` and `/review` per Act.
+
+### Reviewing a PR
+1. `/review [branch-name]` — reads diff + `CLAUDE.md` + `DANGER-ZONES.md` + prior `uv-out/` artifacts.
+2. `/review --security` if the diff touches auth, payments, data access, or external inputs.
+
+### Shipping
+1. `/session checkpoint` to capture state.
+2. `/commit` — runs review, tests, commits, optionally opens a PR.
+
+Picking a persona (Spike / Sport / Professional / Auto) is a separate axis from picking a first skill — see [Personas](#personas) below for which mode fits which situation.
 
 ## Sessions and Watchtower
 
@@ -46,7 +70,7 @@ Each `uvs` launch generates a `UVS_SESSION_ID` and writes metadata to `.uv-suite
 
 - **Concurrent terminals don't collide.** Two `uvs` launches in the same repo run as distinct sessions with separate names, checkpoints, and dashboard rows.
 - **`uvs watch` shows them all.** The Watchtower dashboard at `localhost:4200` streams every tool call across every session in real time — labeled by your name, sorted by priority (high to top, low dimmed), color-coded by persona.
-- **Per-session checkpoints.** `/checkpoint` writes to `uv-out/checkpoints/<sid>/`, and `/restore` auto-picks the current session's latest. Pass a session id prefix or name to restore from a different one.
+- **Per-session checkpoints.** `/session checkpoint` writes to `uv-out/checkpoints/<sid>/`, and `/session restore` auto-picks the current session's latest. Pass a session id prefix or name to restore from a different one.
 - **Status line shows it all.** The Claude Code status bar shows session name, persona, priority, and elapsed time continuously.
 
 ### Watchtower at a glance
@@ -104,50 +128,48 @@ Human gates  After each     End only     Every Act          Final output
 
 ## Skills (slash commands)
 
+12 skills. Each `skills/<name>/SKILL.md` is a thin orchestrator that dispatches to agents.
+
 | Command | What it does |
 |---|---|
-| `/map-codebase [dir]` | Build a knowledge graph of the codebase |
-| `/map-stack [dir]` | Map multiple services and their connections |
+| `/understand [dir]` | Map a codebase or whole stack — auto-detects repo vs stack |
 | `/spec [requirements]` | Write a technical specification |
 | `/architect [spec]` | Design architecture, decompose into Acts |
+| `/test [file]` | Write tests or evals: `--unit` / `--integration` / `--eval` ([DeepEval](https://github.com/confident-ai/deepeval) compatible) |
+| `/review` | Multi-specialist code review; add `--security` (OWASP via Semgrep/Gitleaks/Trivy) or `--slop` (anti-slop audit) |
 | `/prototype [concept]` | Build a static React prototype |
-| `/write-tests [file]` | Generate tests matching project conventions |
-| `/write-evals [prompt]` | Write AI/LLM evaluation cases ([DeepEval](https://github.com/confident-ai/deepeval) compatible) |
-| `/review` | Code review: correctness, security, performance, slop |
-| `/slop-check` | Detect 6 categories of AI-generated slop |
-| `/security-review` | OWASP audit, dependency scan, secret detection |
+| `/qa` | Browser QA via Playwright MCP |
 | `/investigate` | Systematic root-cause debugging |
-| `/commit` | Review → test → slop-check → commit (and optionally PR) |
-| `/checkpoint [label]` | Save session state to `uv-out/checkpoints/<sid>/` |
-| `/restore [sid-prefix\|name]` | Load the latest checkpoint for the current (or named) session |
-| `/session-init [name\|--kind\|--purpose\|--priority]` | Label or relabel the current session |
+| `/commit` | Review → test → commit (and optionally PR) |
+| `/session init\|checkpoint\|restore\|end\|auto` | Session lifecycle — label, checkpoint, restore, end, or auto-checkpoint |
 | `/confirm [on\|off\|<n>]` | Toggle reframe-and-confirm for prompts over `<n>` words |
 | `/uv-help` | List every skill, agent, hook, guardrail, and persona |
 
 ## Hooks (lifecycle automation)
 
-Fire automatically on Claude Code events. You never invoke these.
+Fire automatically on Claude Code events. You never invoke these. ~26 scripts live in `hooks/`.
 
 | Hook | Fires on | What it does |
 |---|---|---|
 | auto-lint | File write | Runs prettier, ruff, or gofmt |
-| slop-grep | File write | Greps for obvious slop patterns (over-commented code, vague docs) |
-| doc-slop-grep | File write | Catches vague adjectives in markdown |
+| slop-grep | File edit/write | Ambient slop detection on sport / professional / auto personas |
+| doc-slop-grep | File edit/write | Catches vague adjectives in markdown on the spike persona |
 | danger-zone-check | File edit | Warns if file is in DANGER-ZONES.md |
 | block-destructive | Bash command | Blocks `rm -rf /`, force push to main, `DROP TABLE` |
 | confirm-prompt | UserPromptSubmit | For prompts over the threshold, requires Claude to restate before any work starts |
-| session-label-nag | UserPromptSubmit | Reminds you to run `/session-init` every Nth prompt while the session has no name |
+| session-label-nag | UserPromptSubmit | Reminds you to run `/session init` every Nth prompt while the session has no name |
 | context-warning | PostToolUse | Warns when context usage crosses thresholds |
 | watchtower-send | All events | Forwards every event (with session metadata) to `localhost:4200` |
 | session-start | SessionStart | Records start time, fires bootstrap event with session metadata |
 | session-timer | PostToolUse | Reminders at 45 / 90 / 180 minutes |
 | session-end | Stop | Shows duration, today's total, reflection prompt |
 | session-review-reminder | Stop | Nudges you to review uncommitted changes |
+| uv-out-* | Session events | Manage session-scoped artifacts under `uv-out/sessions/<sid>/` |
 | status-line | Continuous | Renders session label, persona, priority, and timer in the Claude Code status bar |
 
 ## Agents
 
-10 agents, each in 4 formats (Claude Code, Cursor, Codex, portable):
+8 agents. The canonical definitions are `agents/claude-code/*.md`. The Cursor (`.mdc`) and Codex (`.toml`) variants are generated from those by `agents/generate.py` at install — they're not hand-maintained.
 
 | Agent | Subsystem | Model | Cycle Budget |
 |---|---|---|---|
@@ -159,8 +181,6 @@ Fire automatically on Claude Code events. You never invoke these.
 | Eval Writer | Acts | Opus | 2 |
 | Anti-Slop Guard | Guard | Opus | 1 |
 | Prototype Builder | Acts | Sonnet | 3 |
-| DevOps | Acts | Opus | 2 |
-| Security | Guard | Opus | 1 |
 
 ## Artifacts
 
@@ -168,11 +188,11 @@ Agents write persistent output to `uv-out/`. Each agent reads prior artifacts au
 
 | 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 |
-| `uv-out/checkpoints/<sid>/*.md` | /restore |
+| `uv-out/map-codebase.md` | /architect, /review, /review --security |
+| `uv-out/specs/*.md` | /architect, /test, /test --eval |
+| `uv-out/architecture/*.md` | /review, /test, /review --slop |
+| `uv-out/review-*.md` | /review --slop, /review --security |
+| `uv-out/checkpoints/<sid>/*.md` | /session restore |
 
 ## Integrations
 
@@ -190,13 +210,13 @@ Agents write persistent output to `uv-out/`. Each agent reads prior artifacts au
 ```
 .claude/
   settings.json          Permissions and hooks (seeded from your persona on first install)
-  agents/                10 agent definitions
-  skills/                17 slash commands
-  hooks/                 14 hook scripts + 2 helpers
+  agents/                8 agent definitions (canonical .md)
+  skills/                12 slash commands
+  hooks/                 ~26 hook scripts
   rules/                 6 anti-slop guardrails (Pro / Auto only)
   personas/              4 persona configs
-.codex/agents/           10 Codex agent definitions
-.cursor/rules/           10 Cursor rule definitions
+.codex/agents/           8 Codex agent definitions (generated from .claude/agents)
+.cursor/rules/           8 Cursor rule definitions (generated from .claude/agents)
 AGENTS.md                Codex instruction file
 DANGER-ZONES.md          Risky areas (commit this)
 .uv-suite-state/         Session metadata + counters (gitignored)
@@ -210,13 +230,16 @@ uv-out/                  Agent output artifacts (gitignored)
 
 | Document | What it covers |
 |---|---|
-| [usage-guide.md](usage-guide.md) | Full SDLC mapped to exact commands |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Working on UV Suite — adding skills/agents/hooks, running the tests |
 | [personas.md](personas.md) | 4 personas, 7 knobs, when to use each |
-| [practices.md](practices.md) | Working principles (honesty, parallelism, scope, completion) |
+| [knowledge/practices.md](knowledge/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 |
+| [knowledge/human-in-the-loop.md](knowledge/human-in-the-loop.md) | Cycle budgets, intervention types, learning loops |
+| [knowledge/sharing-and-standards.md](knowledge/sharing-and-standards.md) | Danger zones, team standards, sharing levels |
+| [research/landscape.md](research/landscape.md) | Open source tools and references for each agent |
+| [research/comparison.md](research/comparison.md) | UV Suite vs gstack vs Claude Code built-in — feature comparison + prompt-depth deep dive |
+| [research/tool-comparison.md](research/tool-comparison.md) | Claude Code vs Cursor vs Codex — how UV Suite works across all three |
+| [research/best-practices.md](research/best-practices.md) | Subagent patterns, remote sessions, sharing with engineers, cost optimization |
 
 ## License
 

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

@@ -19,7 +19,20 @@ You are the **Anti-Slop Guard** — your job is to catch AI-generated low-qualit
 
 ## Artifact Output
 
-Write the slop report to `uv-out/slop-check-YYYY-MM-DD.md`. Create the directory if needed. Summarize findings in the conversation.
+Write the slop report to `<session-output-dir>/review --slop/report.md`, where
+`<session-output-dir>` is the path printed in the "Session output directory" section of
+your context (e.g. `uv-out/sessions/<sid>/`). Create the directory if needed. Stamp the
+top with provenance frontmatter:
+
+```yaml
+---
+session: <sid from the output dir path>
+skill: slop-check
+created: <ISO 8601 timestamp>
+---
+```
+
+Summarize findings in the conversation.
 
 ## What You Scan For
 

package/agents/claude-code/architect.md

@@ -16,8 +16,21 @@ effort: high
 
 You are the **Architect** — your job is to design systems and break work into deliverable Acts.
 
+**Hard precondition: you design only from a curated spec** (problem statement, requirements,
+success criteria). If no spec was provided or found, **stop and ask** the user to run
+`/spec` or describe the problem so a spec can be drafted first. Never design from a vague
+one-liner and never invent requirements — designing without a spec is a failure, not a fallback.
+
 ## Output Format
 
+### 0. Design Constraints
+Write these to `<session-output-dir>/architecture/constraints.md` FIRST, before any design.
+Record the factors the design is right-sized against (from the spec's non-functional
+requirements or gathered from the user): scale (users/RPS/data, now + ~12mo), team size &
+expertise, availability target, consistency/CAP priority, security & privacy/compliance,
+and fault tolerance / cost of failure. Every later decision must be justifiable against
+these — they are what make "this is over-engineered" a checkable claim.
+
 ### 1. Architecture Decision Record
 For each key decision, document:
 - **Decision:** What you chose
@@ -51,11 +64,24 @@ For each key decision, document:
 
 ## Artifact Output
 
-Write all output to `uv-out/architecture/`:
-- `uv-out/architecture/decisions.md` — architecture decision records
-- `uv-out/architecture/acts-plan.md` — Acts breakdown with tasks and cycle budgets
+Write all output under `<session-output-dir>/architecture/`, where `<session-output-dir>`
+is the path printed in the "Session output directory" section of your context
+(e.g. `uv-out/sessions/<sid>/`):
+- `<session-output-dir>/architecture/constraints.md` — the Design Constraints the design is right-sized against (write this FIRST, before designing)
+- `<session-output-dir>/architecture/decisions.md` — architecture decision records
+- `<session-output-dir>/architecture/acts-plan.md` — Acts breakdown with tasks and cycle budgets
+
+Create the directory if needed. Stamp the top of each file with provenance frontmatter:
+
+```yaml
+---
+session: <sid from the output dir path>
+skill: architect
+created: <ISO 8601 timestamp>
+---
+```
 
-Create the directory if needed. Summarize the design in the conversation.
+Summarize the design in the conversation.
 
 ### 4. Task Dependency Graph
 Mermaid diagram showing parallelism opportunities.

package/agents/claude-code/cartographer.md

@@ -88,12 +88,24 @@ Produce all 6 sections (Architecture Overview, Tech Stack, Dependency Graph, Bus
 
 ## Artifact Output
 
-Write all output to `uv-out/`. Create the directory if it doesn't exist.
-
-- `uv-out/map-codebase.md` — the written analysis (business domain map, sequence diagrams, entry points)
-- `uv-out/graphify-out/` — Graphify outputs if used (graph.html, graph.json, GRAPH_REPORT.md)
-
-After writing, tell the human: "Artifacts written to uv-out/map-codebase.md" and summarize key findings in the conversation.
+Write all output under `<session-output-dir>`, the path printed in the "Session output
+directory" section of your context (e.g. `uv-out/sessions/<sid>/`). Create it if needed.
+
+The calling skill names the output file — `<session-output-dir>/map-codebase.md` for
+single-codebase mapping, `<session-output-dir>/map-stack.md` for multi-service stack
+mapping. Follow the file named in the task; default to `map-codebase.md` if unspecified.
+
+- The written analysis goes in that file, stamped with provenance frontmatter:
+  ```yaml
+  ---
+  session: <sid from the output dir path>
+  skill: map-codebase   # or map-stack
+  created: <ISO 8601 timestamp>
+  ---
+  ```
+- `<session-output-dir>/graphify-out/` — Graphify outputs if used (graph.html, graph.json, GRAPH_REPORT.md)
+
+After writing, tell the human one line — "Artifacts written to `<the file you wrote>`" — and summarize key findings in the conversation.
 
 ## Rules
 

package/agents/claude-code/eval-writer.md

@@ -46,14 +46,19 @@ You are the **Eval Writer** — your job is to write evaluations that verify AI/
 
 ## Artifact Output
 
-Write evals to `uv-out/evals/`. Create the directory if needed. Match the project's eval framework format (DeepEval preferred).
+Write eval artifacts to `<session-output-dir>/evals/`, where `<session-output-dir>` is the
+path printed in the "Session output directory" section of your context (e.g.
+`uv-out/sessions/<sid>/`). Create the directory if needed. Match the project's eval
+framework format (DeepEval preferred). If you also add runnable evals into the project's
+own eval suite, do that in the project tree as usual — only the artifact copy goes under
+the session directory.
 
 ## Grading Rubric (be this specific)
 
 ```yaml
 grading:
   type: "llm_judge"
-  model: "claude-haiku-4-5"
+  model: "claude-haiku-4-5-20251001"
   rubric: |
     Score 1 (pass) if ALL of:
     - Agent declines the out-of-scope request

package/agents/claude-code/reviewer.md

@@ -65,7 +65,11 @@ You are the **Reviewer** — your job is to catch bugs, security issues, perform
 
 ## Artifact Output
 
-Write the review report to `uv-out/review-YYYY-MM-DD.md`. Create the directory if needed. Summarize key findings in the conversation.
+Write your report under `<session-output-dir>`, the path printed in the "Session output
+directory" section of your context (e.g. `uv-out/sessions/<sid>/`). Use the filename the
+calling task names — `review/state.md` for a code review, `investigate/report.md` for an
+investigation. Stamp the top with provenance frontmatter (`session`, `skill`, `created`).
+Create the directory if needed. Summarize key findings in the conversation.
 
 ## Common Findings (be this specific)
 

package/agents/claude-code/spec-writer.md

@@ -62,19 +62,42 @@ Unit, integration, e2e, load?
 
 ## Artifact Output
 
-Write the spec to `uv-out/specs/[feature-name]-spec.md`. Create the directory if needed. Summarize the spec in the conversation.
+Write the spec to `<session-output-dir>/specs/[feature-name]-spec.md`, where
+`<session-output-dir>` is the path printed in the "Session output directory" section of
+your context (e.g. `uv-out/sessions/<sid>/`). Create the directory if needed.
+
+Stamp the top of the spec with provenance frontmatter so it stays attributable if moved:
+
+```yaml
+---
+session: <sid from the output dir path>
+skill: spec
+created: <ISO 8601 timestamp>
+---
+```
+
+Then the `# Spec: [Feature Name]` heading and the rest of the template. Summarize the spec in the conversation.
 
 ## Process
 
-1. Parse the input into discrete requirements
-2. Separate functional vs non-functional
-3. Identify gaps — list as open questions, don't invent answers
-4. Propose a high-level solution (detailed design is the Architect's job)
-5. Define measurable success criteria
-6. Flag risks and assumptions
+1. **Ground in the existing codebase first.** Read the prior `uv-out/` artifacts loaded by
+   the skill — the codebase map (`map-codebase.md`/`map-stack.md`), prior specs, and
+   architecture decisions. Reference real modules, files, patterns, and conventions from
+   the map; reuse what exists; build on prior specs instead of re-specifying them. If no
+   map is present, say so and note that `/understand` would produce a better-grounded spec.
+2. Parse the input into discrete requirements
+3. Separate functional vs non-functional
+4. Identify gaps — list as open questions, don't invent answers
+5. Propose a high-level solution that fits the existing architecture (detailed design is
+   the Architect's job) — name the specific modules/files it touches
+6. Define measurable success criteria
+7. Flag risks and assumptions
 
 ## Rules
 
+- **Ground every section in the real codebase.** The Proposed Solution, API Contract, and
+  Data Model sections must reference actual modules/types/endpoints from the map — not
+  generic placeholders. If you're inventing names because there's no map, flag it.
 - Scale the spec to the task. A bug fix needs 1 page, not 10.
 - Flag ambiguity as open questions — don't fill gaps with assumptions.
 - If requirements conflict (e.g., "fast response" vs "comprehensive validation"), list both in Risks and propose which to prioritize.

package/agents/generate.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+"""Generate Cursor (.mdc) and Codex (.toml) agent files from the canonical
+Claude Code agent definitions in agents/claude-code/*.md.
+
+Single source of truth: edit agents/claude-code/<name>.md, then install.sh (or
+`python3 agents/generate.py <cursor|codex> <dest-dir>`) regenerates the others.
+
+Usage:
+  python3 agents/generate.py cursor /path/to/.cursor/rules
+  python3 agents/generate.py codex  /path/to/.codex/agents
+"""
+import glob
+import os
+import re
+import sys
+
+CANONICAL = os.path.join(os.path.dirname(os.path.abspath(__file__)), "claude-code")
+
+
+def parse(md, fallback_name):
+    m = re.match(r"^---\n(.*?)\n---\n(.*)$", md, re.S)
+    fm, body = (m.group(1), m.group(2).strip()) if m else ("", md.strip())
+
+    def field(key):
+        mm = re.search(rf"^{key}:\s*(.*)$", fm, re.M)
+        return mm.group(1).strip() if mm else ""
+
+    # description is usually a folded scalar (`description: >` then indented lines)
+    desc = field("description")
+    if desc in (">", "|", ">-", "|-", ""):
+        lines = fm.splitlines()
+        idx = next((i for i, l in enumerate(lines) if l.startswith("description:")), None)
+        if idx is not None:
+            collected = []
+            for l in lines[idx + 1:]:
+                if re.match(r"^\s+\S", l):
+                    collected.append(l.strip())
+                else:
+                    break
+            desc = " ".join(collected) or desc
+    desc = desc.strip().strip('"')
+
+    return {
+        "name": field("name") or fallback_name,
+        "desc": desc,
+        "model": field("model"),
+        "has_write": ("Write" in fm or "Edit" in fm),
+        "body": body,
+    }
+
+
+def to_mdc(a):
+    desc = a["desc"].replace('"', '\\"')
+    return f'---\ndescription: "{desc}"\nglobs: ""\nalwaysApply: false\n---\n\n{a["body"]}\n'
+
+
+def to_toml(a):
+    effort = "high" if a["model"] == "opus" else "medium"
+    sandbox = "workspace-write" if a["has_write"] else "read-only"
+    desc = a["desc"].replace("\\", "\\\\").replace('"', '\\"')
+    body = a["body"].replace("\\", "\\\\").replace('"""', '\\"\\"\\"')
+    return (
+        f'name = "{a["name"]}"\n'
+        f'description = "{desc}"\n'
+        f'model_reasoning_effort = "{effort}"\n'
+        f'sandbox_mode = "{sandbox}"\n\n'
+        f'developer_instructions = """\n{body}\n"""\n'
+    )
+
+
+def main():
+    if len(sys.argv) != 3 or sys.argv[1] not in ("cursor", "codex"):
+        sys.exit("usage: generate.py <cursor|codex> <dest-dir>")
+    fmt, dest = sys.argv[1], sys.argv[2]
+    os.makedirs(dest, exist_ok=True)
+    ext = ".mdc" if fmt == "cursor" else ".toml"
+    render = to_mdc if fmt == "cursor" else to_toml
+    n = 0
+    for path in sorted(glob.glob(os.path.join(CANONICAL, "*.md"))):
+        name = os.path.splitext(os.path.basename(path))[0]
+        a = parse(open(path).read(), name)
+        open(os.path.join(dest, name + ext), "w").write(render(a))
+        n += 1
+    print(f"generated {n} {fmt} agents -> {dest}")
+
+
+if __name__ == "__main__":
+    main()

package/bin/cli.js

@@ -34,6 +34,7 @@ function usage() {
   Monitoring:
     uvs watch               Start Watchtower dashboard (open browser)
     uvs watch --bg          Start Watchtower in background
+    uvs watch --legacy      Start the legacy Node Watchtower (no Docker/Postgres)
 
   Personas:
     spike        Research & docs (Opus, max effort)
@@ -295,59 +296,61 @@ async function launchCodex(persona, extra) {
 }
 
 function watch() {
-  const serverScript = path.join(UV_SUITE_DIR, "watchtower", "server.js");
-  if (!fs.existsSync(serverScript)) {
-    console.error("Error: watchtower server not found at", serverScript);
+  const wtDir = path.join(UV_SUITE_DIR, "watchtower");
+
+  // Legacy fallback: the original Node Watchtower (no Postgres/Docker). `uvs watch --legacy`.
+  if (args.includes("--legacy")) {
+    const serverScript = path.join(wtDir, "legacy", "server.js");
+    if (!fs.existsSync(serverScript)) {
+      console.error("Error: legacy watchtower not found at", serverScript);
+      process.exit(1);
+    }
+    const lbg = args.includes("--bg") || args.includes("--background");
+    const lurl = "http://localhost:" + (process.env.UVS_WATCHTOWER_PORT || 4200);
+    const lopener =
+      process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    console.log("UV Suite Watchtower (legacy Node) starting...");
+    console.log("Dashboard: " + lurl);
+    console.log("");
+    setTimeout(() => spawn(lopener, [lurl], { stdio: "ignore" }), 1000);
+    const lchild = spawn("node", [serverScript], { stdio: lbg ? "ignore" : "inherit", detached: lbg });
+    if (lbg) {
+      lchild.unref();
+      console.log(`Running in background (PID: ${lchild.pid}). Stop with: kill ${lchild.pid}`);
+    } else {
+      lchild.on("exit", (code) => process.exit(code || 0));
+    }
+    return;
+  }
+  if (!fs.existsSync(path.join(wtDir, "docker-compose.yml"))) {
+    console.error("Error: watchtower compose not found at", wtDir);
     process.exit(1);
   }
-
   const bg = args.includes("--bg") || args.includes("--background");
-  console.log("UV Suite Watchtower starting...");
-  console.log(
-    "Dashboard: http://localhost:" + (process.env.UVS_WATCHTOWER_PORT || 4200),
-  );
+  const url = "http://localhost:" + (process.env.UVS_WATCHTOWER_PORT || 4200);
+  const opener =
+    process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  console.log("UV Suite Watchtower (Python + Postgres) starting via docker compose...");
+  console.log("Dashboard: " + url);
   console.log("");
 
-  if (bg) {
-    const child = spawn("node", [serverScript], {
-      stdio: "ignore",
-      detached: true,
-    });
-    child.unref();
-    console.log(`Running in background (PID: ${child.pid})`);
-    console.log("Stop with: kill " + child.pid);
-
-    // Open browser
-    const opener =
-      process.platform === "darwin"
-        ? "open"
-        : process.platform === "win32"
-          ? "start"
-          : "xdg-open";
-    spawn(
-      opener,
-      ["http://localhost:" + (process.env.UVS_WATCHTOWER_PORT || 4200)],
-      { stdio: "ignore" },
-    );
-  } else {
-    // Foreground — open browser after a short delay
-    setTimeout(() => {
-      const opener =
-        process.platform === "darwin"
-          ? "open"
-          : process.platform === "win32"
-            ? "start"
-            : "xdg-open";
-      spawn(
-        opener,
-        ["http://localhost:" + (process.env.UVS_WATCHTOWER_PORT || 4200)],
-        { stdio: "ignore" },
-      );
-    }, 1000);
-
-    const child = spawn("node", [serverScript], { stdio: "inherit" });
-    child.on("exit", (code) => process.exit(code || 0));
-  }
+  // Bring the stack up (Postgres + FastAPI). Build is cached after first run.
+  const up = spawn("docker", ["compose", "up", "--build", "-d"], { cwd: wtDir, stdio: "inherit" });
+  up.on("exit", (code) => {
+    if (code) {
+      console.error("docker compose failed. Is Docker running? (the Python Watchtower needs it)");
+      process.exit(code);
+    }
+    setTimeout(() => spawn(opener, [url], { stdio: "ignore" }), 1500);
+    if (bg) {
+      console.log("Watchtower running in background.");
+      console.log("Stop with: (cd watchtower && docker compose down)");
+      process.exit(0);
+    }
+    // Foreground: follow logs until Ctrl-C.
+    const logs = spawn("docker", ["compose", "logs", "-f"], { cwd: wtDir, stdio: "inherit" });
+    logs.on("exit", (c) => process.exit(c || 0));
+  });
 }
 
 // --- Parse and route ---

package/hooks/auto-checkpoint-helper.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # UV Suite helper: read or change auto-checkpoint settings.
-# Used by the /auto-checkpoint slash command.
+# Used by the /session auto slash command.
 #
 # Usage:
 #   auto-checkpoint-helper.sh status
@@ -66,7 +66,7 @@ case "$ARG" in
       set_field interval_minutes "$ARG"
       echo "Auto-checkpoint interval: $ARG min (mode: $(get_field mode))"
     else
-      echo "Usage: /auto-checkpoint [on | off | <minutes 1-1440> | status]"
+      echo "Usage: /session auto [on | off | <minutes 1-1440> | status]"
       exit 1
     fi
     ;;

package/hooks/auto-checkpoint.sh

@@ -5,7 +5,7 @@
 # Logs every tool call into a per-session activity log. When `interval_minutes`
 # have passed since the last mechanical checkpoint AND there has been activity
 # in the interval, writes a deterministic snapshot to
-# uv-out/checkpoints/<sid>/auto-<ts>-mechanical.md and forwards an
+# uv-out/sessions/<sid>/checkpoints/auto-<ts>-mechanical.md and forwards an
 # AutoCheckpoint event to the watchtower.
 #
 # Tier B (semantic, claude -p) runs separately from the watchtower's timer.
@@ -96,7 +96,7 @@ fi
 
 # Resolve checkpoint dir + metadata via the existing helper
 CP_DIR=$(CLAUDE_PROJECT_DIR="$PROJECT_DIR" "$PROJECT_DIR/.claude/hooks/checkpoint-helper.sh" dir 2>/dev/null)
-[ -z "$CP_DIR" ] && CP_DIR="$PROJECT_DIR/uv-out/checkpoints/$SID" && mkdir -p "$CP_DIR"
+[ -z "$CP_DIR" ] && CP_DIR="$PROJECT_DIR/uv-out/sessions/$SID/checkpoints" && mkdir -p "$CP_DIR"
 
 # Build the mechanical checkpoint body
 TS_FILE=$(date +%Y-%m-%d-%H%M)
@@ -160,7 +160,7 @@ GIT_LOG=$(cd "$PROJECT_DIR" && git log --oneline -5 2>/dev/null)
   fi
 } > "$CP_FILE"
 
-# Update latest.md so /restore picks it up
+# Update latest.md so /session restore picks it up
 cp "$CP_FILE" "$CP_DIR/latest.md" 2>/dev/null
 echo "$NOW" > "$LAST_CP_FILE"