bobp 0.1.0__py3-none-any.whl

bobp/__init__.py

@@ -0,0 +1,3 @@
+"""bobp: CLI front-end for the Bob Protocol multi-persona AI development framework."""
+
+__version__ = "0.1.0"

bobp/cli.py

@@ -0,0 +1,80 @@
+"""bobp command-line dispatcher.
+
+TLDR:
+    Single `bobp <subcommand> [args...]` entry point that front-ends the
+    scripts in bobp.tools. Each subcommand maps to a tool module; the
+    module is imported lazily (only when its subcommand is invoked) so
+    that subcommands with extra dependencies (prep-tldr, session-trace,
+    trace-annotate all import the separate `via` package) don't block
+    unrelated subcommands like `bobp chat` from running without it
+    installed. Argument parsing itself is delegated entirely to each
+    module's own main(), which parses sys.argv directly, so this
+    dispatcher just rewrites sys.argv[0] to the subcommand name before
+    calling in.
+
+    Bob-protocol project management (install/update/pull/clean/diff) is
+    implemented natively in bobp.tools._bob_manage; the templates Makefile's
+    install_bob/update_bob/pull_bob/clean_bob/diff_bob targets are now thin
+    wrappers that just call these subcommands.
+"""
+
+import importlib
+import sys
+
+SUBCOMMANDS = {
+    "chat": "bobp.tools.chat",
+    "chat-diagram": "bobp.tools.chat_diagram",
+    "chat-merge": "bobp.tools.chat_merge",
+    "chat-report": "bobp.tools.chat_report",
+    "make": "bobp.tools.make",
+    "persona-eval": "bobp.tools.persona_eval",
+    "prep-tldr": "bobp.tools.prep_tldr",
+    "session-trace": "bobp.tools.session_trace",
+    "setup-agent-links": "bobp.tools.setup_agent_links",
+    "teardown-agent-links": "bobp.tools.teardown_agent_links",
+    "tldr": "bobp.tools.tldr",
+    "trace-annotate": "bobp.tools.trace_annotate",
+    "install": "bobp.tools.bob_install",
+    "update": "bobp.tools.bob_update",
+    "pull": "bobp.tools.bob_pull",
+    "clean": "bobp.tools.bob_clean",
+    "diff": "bobp.tools.bob_diff",
+}
+
+
+def print_help() -> None:
+    print("usage: bobp <subcommand> [args...]")
+    print()
+    print("subcommands:")
+    for name in sorted(SUBCOMMANDS):
+        print(f"  {name}")
+    print()
+    print("Run `bobp <subcommand> --help` for subcommand-specific options.")
+
+
+def main(argv: "list[str] | None" = None) -> int:
+    argv = sys.argv[1:] if argv is None else list(argv)
+
+    if not argv:
+        print_help()
+        return 1
+
+    if argv[0] in ("-h", "--help"):
+        print_help()
+        return 0
+
+    name, rest = argv[0], argv[1:]
+    module_path = SUBCOMMANDS.get(name)
+    if module_path is None:
+        print(f"bobp: unknown subcommand '{name}'", file=sys.stderr)
+        print_help()
+        return 1
+
+    module = importlib.import_module(module_path)
+    sys.argv = [name, *rest]
+    module.main()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

bobp/templates/README.md

@@ -0,0 +1,227 @@
+TL;DR: BobProtocol is a reusable Claude Code Skills framework. Invoke personas with `*chat`, Bloop commands (`*fix`, `*impl`, `*plan sprint`), or direct skill triggers. State persists per-persona in `agents/[persona]/`.
+
+# BobProtocol: Multi-Persona AI Development Framework
+
+A reusable multi-harness agent-skills framework that orchestrates a team of specialized AI personas. One LLM dynamically switches between 9 expert roles based on task context, with persistent state and structured handoffs across sessions.
+
+## How It Works
+
+Each persona is an agent instruction file with standard YAML frontmatter for `name` and `description`:
+- A Markdown command interface documenting `*prefix command` invocations
+- Optional `Triggers` and `Requires` sections in the body for invocation aliases and prerequisite skills
+- State files in `agents/[persona]/` — the only memory that survives context clears and session restarts
+
+All coordination flows through `agents/CHAT.md` — a shared team log that every persona reads on entry.
+
+## The Team
+
+| Persona | Role | Prefix | Responsibility |
+|---------|------|--------|----------------|
+| **Neo** | Senior SWE | `*swe` | Implementation, debugging, coding |
+| **Morpheus** | Tech Lead | `*lead` | Architecture, design decisions, code review |
+| **Trin** | QA Guardian | `*qa` | Testing, quality gates, coverage |
+| **Oracle** | Knowledge Officer | `*ora` | Documentation, knowledge queries, decisions |
+| **Mouse** | Scrum Master | `*sm` | Sprint tracking, coordination, velocity |
+| **Cypher** | Product Manager | `*pm` | Requirements, user stories, PRDs |
+| **Bob** | Prompt Engineer | `*prompt` | Agent creation, system improvement |
+| **Smith** | HCI Expert | `*user` | Usability testing, HCI evaluation, sprint gates |
+| **Tank** | DevOps Engineer | `*devops` | IaC, CI/CD, deployment automation, environment management, systems reliability |
+
+## Skills & Workflow Loops
+
+Bob Protocol organizes autonomous workflows into hierarchical loops and supporting capabilities:
+
+### Planning Loops (Strategic Scoping & Specification)
+| Skill / Trigger | Focus / Deliverable | Literature |
+|-----------------|---------------------|------------|
+| `epic` / `*plan epic` | Problem framing, appetite budget, domain model (`DOMAIN.md`) | *Shape Up* (Singer) / *Inspired* (Cagan) |
+| `story` / `*plan story` | Vertical user story slicing, INVEST criteria, ADRs (`ARCH.md`), test strategy | *User Story Mapping* (Patton) / *Agile Estimating* (Cohn) |
+| `sprint` / `*plan sprint` | Sprint planning, SDLC verification, task board (`task.md`) with Work Loops | *The Scrum Guide* (Schwaber & Sutherland) |
+
+### Work Loops (Tactical Execution Chains)
+| Skill / Trigger | Execution Chain | Invariant / Literature |
+|-----------------|-----------------|------------------------|
+| `impl` / `*impl` | Neo TDD → Trin verify → Morpheus review | **Test-First**: failing test required before production code (*TDD* — Beck) |
+| `fix` / `*fix` | Neo diagnose → User confirm → Neo fix → Trin test → Morpheus review | **Reproduce First**: diagnose & confirm before edits (*Debugging* — Agans) |
+| `refactor` / `*refactor` | Morpheus plan → Trin baseline → Neo restructure → Trin parity → Morpheus | **Two Hats**: zero behavioral change, green before/after (*Refactoring* — Fowler) |
+| `spike` / `*spike` | Oracle survey → Neo prototype → Morpheus decision/ADR | **Disposable**: timeboxed, zero prod commits (*XP Installed* / *Shape Up*) |
+| `uat` / `*uat` | Trin acceptance matrix → Smith UX audit → Cypher sign-off | **Real-World Experience**: end-to-end evaluation (*Agile Testing* — Crispin) |
+| `deploy` / `*deploy` | Tank Makefile deploy → Trin live smoke test | **Pipeline as Code**: automated release via SDLC Makefile (*Continuous Delivery*) |
+| `bloop` / `*bloop` | Multi-persona work-loop conductor and catalog | Autonomous orchestration, state preservation, anti-loop guards |
+
+### Supporting Protocol & Tool Skills
+- **Session Lifecycle**: `init` (session startup & discovery), `prep-clear` (checkpointing state before `/clear`), `judge` / `*judge` (persona, skill, and tool evaluation)
+- **Protocol & Operations**: `bob-protocol` (routing & state protocol), `bob-tools` (`bobp` CLI operations), `build-env` (`docs/SDLC.md` management), `chat` (team logging), `linter` (code analysis), `make` (captured target runner), `make-discover` (target self-discovery), `personas` (specialist switching), `render` (cloud deployment), `test-runner` (bounded tests), `via` (symbol lookup)
+
+## Invoking Agents
+
+### Autonomous Workflow Loops (Recommended)
+```bash
+# Strategic Planning Loops
+*plan epic <name>        # Cypher framing → Smith gate → Morpheus domain → (Spikes)
+*plan story <slice>      # Cypher story → Smith gate 1 → Morpheus arch → Trin test → Smith gate 2
+*plan sprint             # Cypher → Smith gate → Morpheus → Smith gate → Mouse task board
+
+# Tactical Work Loops
+*impl <task>             # Neo TDD (red-green-refactor) → Trin verify → Morpheus review
+*fix <bug>               # Neo repro/diagnose → confirm → surgical fix → Trin regression sweep
+*refactor <target>       # Morpheus plan → Trin baseline → Neo restructure → Trin parity
+*spike <topic>           # Oracle survey → Neo prototype → Morpheus decision / ADR
+*uat <scope>             # Trin scenario matrix → Smith UX evaluation → Cypher sign-off
+*deploy <env>            # Tank Makefile deploy → Trin live smoke test
+```
+
+### `*chat` — auto-select a persona for a single task
+```
+*chat fix the authentication bug in auth.py
+*chat what's the current sprint status?
+```
+
+### `*chat @Persona` — direct single-persona invocation
+Directly invoke a persona using Gemini's `@` syntax or the internal `@Persona` trigger.
+
+```
+*chat @neo *fix authentication bug in auth.py
+@neo *fix authentication bug in auth.py
+*chat @trin *test all
+*chat @oracle *ora ask What's our pattern for error handling?
+*chat @smith *user review the sprint stories
+```
+
+> **Note on Harness Prefixes**: Different AI harnesses use different prefixes for direct invocation (e.g., `@persona` or `/persona` in Gemini CLI, `/persona` in Claude, `$persona` in Codex). If you are invoked directly via such a command, you MUST log the invocation to `agents/CHAT.md` immediately upon entry if it has not already been logged.
+
+
+### Direct skill triggers — bypass chat routing
+```
+*swe impl Add input validation to the API
+*qa test all
+*ora ask Where is the database schema defined?
+```
+
+## Project Structure
+
+```
+agents/
+├── CHAT.md                  # Shared team communication log
+├── CHAT.diagram.md          # Auto-generated Mermaid view of CHAT.md (derived, don't edit)
+├── PROJECT.md               # Project capabilities (created by setup when missing)
+├── PROJECT.md.template      # Reference template for capability declarations
+├── [persona]/               # Per-persona state and working memory (e.g. neo/, trin/)
+│   ├── SKILL.md             # Persona definition + command interface
+│   └── state.md             # Context, current task, and resume plan (state)
+├── skills/                  # 24 shared skills discovered by harnesses
+│   ├── epic/                # Strategic epic planning (*plan epic)
+│   ├── story/               # User story slicing & ADRs (*plan story)
+│   ├── sprint/              # Sprint planning & cadence container (*plan sprint)
+│   ├── impl/                # Feature TDD work-loop (*impl)
+│   ├── fix/                 # Defect diagnosis & surgical fix work-loop (*fix)
+│   ├── refactor/            # Behavior-preserving refactoring work-loop (*refactor)
+│   ├── spike/               # Disposable research spike work-loop (*spike)
+│   ├── uat/                 # End-to-end acceptance & UX audit work-loop (*uat)
+│   ├── deploy/              # Automated delivery & live smoke work-loop (*deploy)
+│   ├── bloop/               # Work-loop conductor & catalog (*bloop)
+│   ├── init/                # Session initialization & resume (*init, *resume)
+│   ├── prep-clear/          # Context checkpointing before /clear (*prep-clear)
+│   ├── judge/               # Agent & prompt optimization loop (*judge)
+│   └── ...                  # Supporting tool skills (make, chat, via, build-env, etc.)
+└── templates/               # Document and state file templates (ARTIFACTS.md, rubrics)
+.claude/skills/              # Discovery links to persona and shared-skill folders
+```
+
+`bobp` never installs, generates, or modifies a `Makefile` — that stays entirely
+yours. See "Running Your Own Make Targets" below.
+
+## Installing into a Project
+
+`bobp` is installed separately from the framework files. This project version
+is not yet published to PyPI; from a BobProtocol source checkout, install the
+CLI as a uv-managed user tool:
+
+```bash
+cd /path/to/bob_protocol
+uv tool install --editable .
+```
+
+Installing, updating, pulling, diffing, and cleaning a Bob Protocol install
+are `bobp` subcommands, not `make` targets:
+
+```bash
+# First install
+bobp install /path/to/your/project
+
+# Later, once installed
+bobp update /path/to/your/project    # refresh skills/templates, preserving state
+bobp pull /path/to/another/project   # pull framework updates from a peer project
+bobp diff /path/to/your/project      # compare the template against an install
+bobp clean                           # reset state files and remove symlinks (run inside the project)
+```
+
+## Project Setup (after install)
+
+1. Run skill link setup:
+```bash
+bobp setup-agent-links
+```
+
+2. Review project capabilities in `agents/PROJECT.md`. Setup creates this file when it is missing and enables `via` only when its integration setup succeeds:
+```markdown
+## Capabilities
+via: enabled   # present only when via integration setup succeeds
+```
+
+Link setup creates project discovery links and may also write to the user's
+Codex skills directory and Codex MCP configuration. When the `via` CLI is
+installed, setup configures the project's `.mcp.json` and index too. Review its
+output; restart Codex after creating or changing Codex links.
+
+## Team Coordination Commands
+
+These are `bobp` subcommands, not `make` targets — bob never touches your `Makefile`:
+
+```bash
+bobp tldr                             # show TL;DR from all project files
+bobp chat "..." --persona X --cmd Y   # post a message to CHAT.md
+bobp chat-diagram                     # regenerate CHAT.diagram.md on demand
+```
+
+## Running Your Own Make Targets
+
+If your project has its own `Makefile` (test, lint, build — whatever you already
+use), run it through `bobp make` instead of bare `make` to get output captured to
+`build/build.out` and a pass/fail status posted to CHAT.md:
+
+```bash
+bobp make test         # silent — exit code + 10-line tail on finish
+bobp make -vvv test    # full output live
+```
+
+See the `make` skill for the full contract.
+
+## Optional: via Integration
+
+[`via`](https://github.com/drewpifer/via) is a Python codebase symbol index. When enabled in `agents/PROJECT.md`, personas use `via` for code navigation instead of reading files directly — saving significant context.
+
+Running `bobp setup-agent-links` installs the generic via MCP config with `via install mcp`, ensures the project has a `.via/index.db`, and, when Codex is installed, registers the same server with Codex using `codex mcp add via --env HOME=<project-root> -- <via> mcp serve --no-web <project-root>`.
+
+Each persona knows how to use `via` in the way that best fits their role (e.g. Trin uses `--stale` for coverage gap detection, Morpheus uses `-oD` for architecture diagrams).
+
+## State Management and Cold Start Recovery
+
+State files in `agents/[persona]/state.md` are your working memory — the only state that survives context clears and session restarts.
+
+Every persona follows the strict State Management Protocol:
+- **ENTRY**: Read `agents/CHAT.md` (last 10–20 messages) → load `agents/[persona]/state.md`
+- **WORK**: Update working memory with progress, blockers, and findings
+- **EXIT (Mandatory Hard Gate)**:
+  1. Follow `agents/skills/prep-clear/SKILL.md` before `/clear` or persona switch — flush Context, Current Task progress %, and Next Steps cold-start resume plan to `state.md`.
+  2. Post handoff message: `bobp chat "<summary> @NextPersona *command" --persona <Name> --cmd handoff --to <next>`.
+  3. Never switch personas or clear context without completing both steps.
+
+If resuming after a context clear with no memory:
+1. Run `*init` or read the bottom of `agents/CHAT.md` to find the last handoff
+2. Load that persona's `state.md`
+3. Resume immediately from its `## Next Steps` section
+
+See **[docs/WALKTHROUGH.md](docs/WALKTHROUGH.md)** for a complete step-by-step tutorial building a restaurant reservation app, and **[docs/PERSONA_EVALUATION.md](docs/PERSONA_EVALUATION.md)** for setting up, running, and reviewing persona eval suites.
+See **[STARTUP.md](STARTUP.md)** for LLM startup instructions.
+See **[SHORTHAND_GUIDE.md](SHORTHAND_GUIDE.md)** for the full trigger/command reference.

bobp/templates/SHORTHAND_GUIDE.md

@@ -0,0 +1,232 @@
+TL;DR: Use `*fix`, `*impl`, `*plan sprint` for full workflow chains. Use `*chat @Persona *command` for direct single-persona control. All triggers listed below.
+
+# Shorthand Guide — Skill Triggers
+
+## Session Lifecycle (Init, Checkpoint & Resume)
+
+Formalized in `agents/skills/init/SKILL.md` & `agents/skills/prep-clear/SKILL.md`.
+
+| Command / Trigger | Action | Primary Handler |
+|-------------------|--------|-----------------|
+| `/init`, `*init`, `/bob-protocol init` | Read chat/state, check discovery links, post initialization, and display quick reference | Bob (`*prompt`) |
+| `*resume` | Cold-start recovery from last CHAT.md handoff | Last active persona |
+| `*prep-clear`, `/prep-clear`, `*checkpoint` | Reconcile state, write resume plan, prepare for `/clear` | Active persona |
+| `*startup`, `*chat init` | Startup protocol alias | Bob (`*prompt`) |
+
+---
+
+## Bloop Commands (Bob Loops — Hierarchical SDLC Cycles)
+
+Multi-persona automated workflow loops decomposed into two hierarchical tiers: **Planning Loops** (strategic scoping and specification) and **Work Loops** (tactical execution and verification). Grounded in canonical software engineering literature (Beck, Agans, Fowler, Singer, Patton, Schwaber & Sutherland, Humble & Farley).
+
+### Planning Loops (Strategic Scoping & Specification)
+
+| Command / Loop | Skill | Sequence | Primary Deliverables / Gates | Literature |
+|----------------|-------|----------|------------------------------|------------|
+| `*plan epic <name>` | `skills/epic` | Cypher → Smith → Morpheus → (Spikes) | Problem framing, appetite, `DOMAIN.md`, de-risking spikes | *Shape Up* (Singer) / *Inspired* (Cagan) |
+| `*plan story <slice>` | `skills/story` | Cypher → [Smith Gate 1] → Morpheus → Trin → [Smith Gate 2] | Vertical slice, INVEST criteria, `ARCH.md` ADRs, `TEST_STRATEGY.md` | *User Story Mapping* (Patton) / *Agile Estimating* (Cohn) |
+| `*plan sprint [tier1\|tier2]` | `skills/sprint` | Cypher → Smith → Morpheus → Smith → Mouse → Morpheus | Sprint goal, scoped stories, prioritized `task.md` with Work Loops | *The Scrum Guide* (Schwaber & Sutherland) |
+
+### Work Loops (Tactical Execution & Verification)
+
+| Command / Loop | Skill | Sequence | Core Invariant | Literature |
+|----------------|-------|----------|----------------|------------|
+| `*impl <task>` | `skills/impl` | Neo → Trin → Morpheus | Test-first (no code without failing test); acceptance verified | *TDD: By Example* (Beck) |
+| `*fix <defect>` | `skills/fix` | Neo → Trin → Morpheus | Reproduce & diagnose first; confirm diagnosis before editing; zero regressions | *Debugging* (Agans) |
+| `*refactor <target>` | `skills/refactor` | Neo → Trin → Morpheus | Two-Hats rule; zero behavioral change; green baseline before and after | *Refactoring* (Fowler) |
+| `*spike <unknown>` | `skills/spike` | Neo / Morpheus → Oracle | Disposable exploration; zero production code; outputs finding/decision | *XP Installed* (Jeffries) / *Shape Up* |
+| `*uat <phase>` | `skills/uat` | Trin → Smith → (Neo if defect) | End-to-end acceptance + UX heuristic evaluation; defect halts to `*fix` | *Agile Testing* (Crispin & Gregory) |
+| `*deploy <target>` | `skills/deploy` | Tank → Trin smoke | Automated release via Makefile; live smoke test before pass | *Continuous Delivery* (Humble & Farley) |
+| `*judge <persona-or-skill>` | `skills/judge` | Trin → Smith → Neo or Bob → Trin | Evaluate a fixed scenario with evidence, then verify a focused fix in a fresh run | Eval-driven development |
+| `*qa <scope>` | `skills/trin` | Trin → Morpheus | Test suite execution & codebase health verification | *Working Effectively with Legacy Code* |
+| `*review <target>` | `skills/morpheus` | Morpheus → Trin | Architectural alignment, maintainability, and quality review | *Clean Architecture* (Martin) |
+
+---
+
+## Direct Skill Triggers
+
+Invoke a persona directly — bypasses `*chat` routing.
+
+### Neo — Software Engineer
+| Trigger | Action |
+|---------|--------|
+| `*swe impl <task>` | Implement a feature (TDD) |
+| `*swe fix <issue>` | Diagnose and fix a bug |
+| `*swe test <scope>` | Write and run tests |
+| `*swe refactor <target>` | Refactor without changing behaviour |
+
+### Morpheus — Tech Lead
+| Trigger | Action |
+|---------|--------|
+| `*lead arch <topic>` | Architecture review or decision |
+| `*lead plan <story>` | Create technical implementation plan |
+| `*lead decide <choice>` | Make and record an architectural decision |
+| `*lead guide <area>` | Provide technical guidance |
+| `*lead refactor <target>` | Plan a refactoring strategy |
+| `*lead review <target>` | Review code for architecture alignment |
+
+### Trin — QA Guardian
+| Trigger | Action |
+|---------|--------|
+| `*qa test <scope>` | Run tests (`all`, `unit`, `integration`, or specific) |
+| `*qa uat <phase>` | UAT — verify acceptance criteria for a phase |
+| `*qa verify <feature>` | Verify a feature meets acceptance criteria |
+| `*qa review <change>` | Code review for quality and correctness |
+| `*qa report` | Summarise codebase health |
+| `*qa repro <issue>` | Create a minimal reproduction of a bug |
+
+### Oracle — Knowledge Officer
+| Trigger | Action |
+|---------|--------|
+| `*ora ask <question>` | Query the knowledge base |
+| `*ora record <type> <content>` | Log a decision, lesson, or finding |
+| `*ora distill <file>` | Break down a large document with TL;DR + ToC |
+| `*ora tldr [glob]` | Write/update TL;DR blocks in project files |
+| `*ora groom` | Audit and organise the knowledge base |
+| `*ora archive` | Archive old CHAT.md messages (>50-100 messages) |
+| `*ora report <moniker>` | Archive the sprint chat and reset the current log through `bobp chat-report` |
+
+### Cypher — Product Manager
+| Trigger | Action |
+|---------|--------|
+| `*pm plan sprint` | Define sprint stories and acceptance criteria |
+| `*pm story <request>` | Write user stories from a feature request |
+| `*pm doc <topic>` | Create or update a PRD or product document |
+| `*pm assess <scope>` | Assess feature readiness or completion status |
+| `*pm prioritize` | Prioritize the backlog |
+| `*pm update` | Post product status update |
+| `*pm launch <sprint>` | Close sprint — announce, backlog retro feedback, update changelog |
+
+### Mouse — Scrum Master
+| Trigger | Action |
+|---------|--------|
+| `*sm plan sprint` | Break sprint into short phases (1-3 tasks each) |
+| `*sm status` | Report current sprint progress |
+| `*sm tasks` | List all active tasks |
+| `*sm next` | Identify the next task to work on |
+| `*sm blocked` | Report and triage a blocker |
+| `*sm done <task>` | Mark a task complete |
+| `*sm assign <task> <persona>` | Assign a task to a persona |
+| `*sm velocity` | Report team velocity metrics |
+
+### Smith — HCI Expert & UX Advocate
+| Trigger | Action |
+|---------|--------|
+| `*user review <stories>` | Review user stories against HCI principles |
+| `*user test <feature>` | Usability-test a feature by running the software |
+| `*user consult <question>` | Quick, non-blocking UX opinion |
+| `*user feedback <question>` | Deeper investigation of open UX/domain questions |
+| `*user research <topic>` | Research comparable tools — ends with `@Oracle *ora record` |
+| `*user story <id> <criteria>` | Co-author user-perspective acceptance criteria |
+| `*user bug CMD:... \| EXPECTED:... \| ACTUAL:... \| UX ISSUE:...` | File a usability defect |
+| `*user approve` | Approve a sprint review gate |
+| `*user reject REASON:... \| FIX:...` | Block a sprint gate — both fields required |
+| `*user blocked <reason>` | Signal gate cannot complete — escalates to Mouse |
+
+### Bob — Prompt Engineer
+| Trigger | Action |
+|---------|--------|
+| `*prompt <description>` | Create a new agent SKILL.md |
+| `*reprompt <instructions>` | Update existing agent prompts |
+| `*learn <lesson>` | Broadcast lesson to all agents |
+| `*help` | Show full system reference |
+| `*bob review <target>` | Review agent interactions and prompt effectiveness |
+
+### Tank — DevOps Engineer
+| Trigger | Action |
+|---------|--------|
+| `*devops deploy` | Orchestrate deployment |
+| `*devops infra` | Declarative IaC management |
+| `*devops ci` | Maintain CI/CD pipelines |
+| `*devops env` | Environment hygiene & secrets |
+| `*devops bootstrap <lang>` | Setup build environment & manifest |
+| `*devops sdlc [check]` | Create or audit docs/SDLC.md |
+
+---
+
+## `*chat` Routing Syntax
+
+```
+*chat <message>                      # auto-select persona
+*chat @<Persona> *<command> <args>   # direct invocation
+@<Persona> <message>                 # Gemini-style direct invocation
+```
+
+### Note on Direct Invocations
+Different AI harnesses use different prefixes for direct persona invocation (e.g., `@persona` or `/persona` in Gemini CLI, `/persona` in Claude, `$persona` in Codex). 
+
+**Rule**: If you are invoked directly via such a command, you MUST log the invocation to `agents/CHAT.md` immediately upon entry if it has not already been logged. This ensures the shared team context is complete.
+```
+*chat fix the bug in parser.py
+*chat @neo *swe fix bug in parser.py line 42
+*chat @trin *qa test all
+*chat @oracle *ora ask What's our DB pattern?
+*chat @morpheus *lead decide REST vs GraphQL
+*chat @cypher *pm story users need CSV export
+*chat @mouse *sm status
+*chat @bob *reprompt Neo needs to know about the new cache layer
+*chat @smith *user review sprint stories
+*chat @smith *user test the export command
+```
+
+---
+
+## Sprint Cycle Quick Reference
+
+```
+*plan sprint (or *plan epic / *plan story)
+  → Cypher *pm plan sprint
+  → [Smith *user approve]         ← gate
+  → Morpheus *lead arch sprint
+  → [Smith *user approve]         ← gate
+  → Mouse *sm plan sprint (task board with typed Work Loops)
+  → Morpheus *lead review sprint plan
+
+Per task / phase (execute typed Work Loops):
+  → *impl <task>          (Neo TDD → Trin verify → Morpheus review)
+  → *fix <defect>         (Neo diagnose/fix → Trin test → Morpheus review)
+  → *refactor <target>    (Neo restructure → Trin parity → Morpheus review)
+  → *spike <unknown>      (Neo/Morpheus prototype → Oracle record)
+  → *uat <phase>          (Trin acceptance → Smith UX evaluation)
+  → *deploy <target>      (Tank automated deploy → Trin smoke)
+
+Sprint close:
+  → Oracle *ora groom
+  → Smith *user test + *user feedback
+  → All *sprint retro             ← feeds backlog
+  → Cypher *pm launch <sprint>
+```
+
+---
+
+## Coordination Commands
+
+These are `bobp` subcommands, not `make` targets — bob never installs or owns
+a `Makefile`:
+
+```bash
+bobp tldr                              # TL;DR from all project files
+bobp chat "..." --persona X --cmd Y    # post to CHAT.md
+bobp chat-diagram                      # regenerate CHAT.diagram.md
+```
+
+## Running Your Own Make Targets
+
+If your project has its own `Makefile`, run it through `bobp make` for output
+captured to `build/build.out` and a status post to CHAT.md:
+
+```bash
+bobp make test                       # captured, silent on pass
+bobp make -vvv test                  # full output live
+```
+
+Installing/updating/pulling/diffing/cleaning a Bob Protocol install is done
+with the `bobp` CLI, not make:
+
+```bash
+bobp diff <path>          # diff framework files with a project
+bobp update <path>        # push framework updates to a project
+bobp pull <path>          # pull framework updates from a project
+bobp install <path>       # fresh install into a project
+bobp clean                # reset state files and symlinks (run inside the project)
+```

bobp/templates/STARTUP.md

@@ -0,0 +1,85 @@
+TL;DR: On startup, read CHAT.md for context, load your persona's state.md, then wait for user direction. If resuming mid-task, check its Next Steps section and continue from there.
+
+# BobProtocol: LLM Startup Instructions
+
+See instructions here -> `agents/skills/init/SKILL.md` & `agents/skills/prep-clear/SKILL.md`
+
+## On Startup (Fresh Session)
+
+1. Read `agents/CHAT.md` — last 10-20 messages for current team context
+2. Load the active persona's `agents/[persona]/state.md`
+3. If `agents/PROJECT.md` exists, read it for project capabilities (e.g. `via: enabled`)
+4. Check that agent discovery links are present; run `bobp setup-agent-links` only when links are missing, stale, or after repository updates
+5. Post the persona's initialization message to `agents/CHAT.md`
+6. Display the quick reference below
+7. Wait for user input — do not auto-execute tasks
+
+## Cold Start Recovery (After Context Clear or Session Restart)
+
+If you were mid-task when context was lost:
+
+1. Read the bottom of `agents/CHAT.md` — find the last handoff message
+2. Identify which persona was active and what command was pending
+3. Load that persona's state file:
+   - `agents/[persona]/state.md`
+4. Post a resume message:
+   ```bash
+   bobp chat "Resuming <task> from last session." --persona <Name> --cmd resume
+   ```
+5. Continue from the `## Next Steps` section of `state.md` — do not restart from scratch
+
+If `CHAT.md` has no clear handoff, ask the user: *"I'm resuming — what should I pick up?"*
+
+---
+
+## Quick Reference
+
+### Planning Loops (Strategic Scoping & Specification)
+```
+*plan epic <name>    → Cypher shape → Smith gate → Morpheus domain → (Spikes)
+*plan story <slice>  → Cypher story → Smith gate 1 → Morpheus arch → Trin test → Smith gate 2
+*plan sprint         → Cypher → Smith gate → Morpheus → Smith gate → Mouse task board
+```
+
+### Work Loops (Tactical Execution Chains)
+```
+*impl <task>         → Neo TDD (red-green-refactor) → Trin verify → Morpheus review
+*fix <bug>           → Neo repro/diagnose → confirm → surgical fix → Trin regression → Morpheus review
+*refactor <target>   → Morpheus plan → Trin baseline → Neo restructure → Trin parity → Morpheus review
+*spike <topic>       → Oracle prior art → Neo prototype → Morpheus decision/ADR
+*uat <scope>         → Trin scenario matrix → Smith UX evaluation → Cypher business sign-off
+*deploy <env>        → Tank Makefile deploy → Trin live smoke test
+```
+
+### `*chat` Routing
+```
+*chat <message>                      # auto-select persona
+*chat @<Persona> *<command> <args>   # direct invocation
+@<Persona> <message>                 # Gemini-style direct invocation
+```
+
+**Note on Direct Invocations**: If you are invoked directly via a harness-specific command (e.g., `@persona` or `/persona` in Gemini CLI, `/persona` in Claude, `$persona` in Codex), you MUST log the invocation to `agents/CHAT.md` immediately upon entry if it has not already been logged.
+
+### Direct Skill Triggers
+```
+*swe impl / *swe fix / *swe test     # Neo
+*qa test / *qa verify / *qa review   # Trin
+*lead arch / *lead decide            # Morpheus
+*ora ask / *ora record / *ora groom  # Oracle
+*sm status / *sm plan / *sm blocked  # Mouse
+*pm story / *pm doc / *pm assess     # Cypher
+*user review / *user test / *user approve  # Smith
+*prompt / *reprompt / *learn         # Bob
+*devops deploy / *devops infra / *devops sdlc  # Tank
+*judge <persona-or-skill>            # Evaluate and improve a persona, skill, or tool
+```
+
+### Make Targets (Single Front Door via bobp make)
+```bash
+bobp make help                       # list all project targets
+bobp make test                       # run tests (captured to build/build.out)
+bobp make -vvv test                  # run tests (full output live)
+bobp chat "..." --persona ... --cmd ... --to ...  # post to CHAT.md
+```
+
+See **[SHORTHAND_GUIDE.md](SHORTHAND_GUIDE.md)** for the full command reference.