@smartmemory/compose 0.3.7 → 0.4.0

package/.claude/skills/compose/SKILL.md

@@ -537,7 +537,7 @@ When `/compose` is invoked, always scan first:
 | `refactor` | Phase 7 — when review finds large files |
 | `update-docs` | Phase 9 |
 
-**Note on dependencies:** these skills are referenced by name and must be installed on the user's machine. See `## Dependencies` below for the install contract — `compose setup` only ships compose-owned skills today; external deps are documented but not auto-installed.
+**Note on dependencies:** these skills are referenced by name and must be installed on the user's machine. See `## Dependencies` below for the install contract — `compose setup` ships compose-owned skills and auto-installs the plugins behind missing REQUIRED external deps (COMP-DEPS-AUTOINSTALL); optional deps remain documented hints.
 
 ## Memory
 
@@ -559,11 +559,20 @@ After completing a feature OR bug-fix lifecycle, update project memory:
 | `stratum` | `compose/skills/stratum/` (if present) | Execution substrate |
 | `compose-explorer`, `compose-architect` | agents under `compose/.claude/agents/` | Required by Phases 1, 3, 4 |
 
-### External dependencies (NOT auto-installed)
+### External dependencies
 
 Authoritative list lives in `compose/.compose-deps.json`. Run `compose doctor` to see what's installed locally and `compose doctor --json` for machine-readable output. The manifest is the single source of truth for external dep IDs and per-dep `fallback` behavior — this SKILL.md never duplicates per-dep fallback strings.
 
-The manifest declares 12 external skills/commands across `superpowers:*`, `interface-design:*`, `codex:review`, `refactor`, and `update-docs`. Each entry carries `id`, `required_for`, `install`, `fallback` (or null), and `optional`.
+The manifest declares 12 external skills/commands across `superpowers:*`, `interface-design:*`, `codex:review`, `refactor`, and `update-docs`. Each entry carries `id`, `required_for`, `install`, `fallback` (or null), and `optional`, plus two optional fields used by auto-install: `plugin` (the `<plugin>@<marketplace>` spec passed to `claude plugin install`) and `marketplace_source` (the `owner/repo` registered first when that marketplace is not configured yet).
+
+**Auto-install (COMP-DEPS-AUTOINSTALL).** `compose setup` / `init` / `update` install the plugins behind missing **required** deps before printing the dep report, so the report describes the state you end up in rather than the state you started from. Rules:
+
+- Only deps with a `plugin` spec are installable. Deps whose `install` is prose (`refactor`, `update-docs`) stay hints.
+- **Optional deps are never auto-installed** — the ones we ship live in third-party marketplaces that each need a separate `marketplace add`, a larger consent step than pulling from a marketplace the user already has.
+- Specs are deduped: six `superpowers:*` deps produce one install.
+- On a machine with no marketplaces registered the first install fails; compose registers the declared `marketplace_source` and retries once.
+- Opt out with `--no-install-deps` or `COMPOSE_NO_PLUGIN_INSTALL=1`. Failures print the real stderr and never change the exit code.
+- `compose doctor` stays read-only; it reports, it never installs.
 
 The manifest also has an optional `external_binaries` array for CLI tools (not skills). Today it declares `rtk` ([Rust Token Killer](https://github.com/rtk-ai/rtk), COMP-RTK-INTEROP) — a lossy output compressor compose routes its one LLM-bound `git diff` (the Codex review diff) through when present, degrading byte-identically when absent. `compose doctor` reports binaries alongside skills and surfaces each binary's `recommend` (for rtk: `rtk init -g`, which installs RTK's Claude Code hook so the agent's *own* Bash output is compressed too — the larger token win). Binary entries carry `id`, `detect`, `install`, `recommend` (or null), and `optional`; all are optional and never block the lifecycle.
 

package/.compose-deps.json

@@ -3,100 +3,126 @@
   "external_skills": [
     {
       "id": "superpowers:systematic-debugging",
-      "required_for": ["bug-fix Phase F3", "any unexpected failure"],
+      "required_for": [
+        "bug-fix Phase F3",
+        "any unexpected failure"
+      ],
       "install": "claude plugin install superpowers",
+      "plugin": "superpowers@claude-plugins-official",
+      "marketplace_source": "anthropics/claude-plugins-official",
       "fallback": "general-purpose Agent with debugging prompt",
       "optional": false
     },
     {
       "id": "superpowers:test-driven-development",
-      "required_for": ["bug-fix Phase F2", "build Phase 7 step 1"],
+      "required_for": [
+        "bug-fix Phase F2",
+        "build Phase 7 step 1"
+      ],
       "install": "claude plugin install superpowers",
+      "plugin": "superpowers@claude-plugins-official",
+      "marketplace_source": "anthropics/claude-plugins-official",
       "fallback": "inline TDD instructions in SKILL.md",
       "optional": false
     },
     {
       "id": "superpowers:verification-before-completion",
-      "required_for": ["all phase exits"],
+      "required_for": [
+        "all phase exits"
+      ],
       "install": "claude plugin install superpowers",
+      "plugin": "superpowers@claude-plugins-official",
+      "marketplace_source": "anthropics/claude-plugins-official",
       "fallback": "inline verification checklist in SKILL.md",
       "optional": false
     },
     {
       "id": "superpowers:requesting-code-review",
-      "required_for": ["Phase 7 review fallback"],
+      "required_for": [
+        "Phase 7 review fallback"
+      ],
       "install": "claude plugin install superpowers",
+      "plugin": "superpowers@claude-plugins-official",
+      "marketplace_source": "anthropics/claude-plugins-official",
       "fallback": "general-purpose Agent reviewer with canonical ReviewResult prompt",
       "optional": true
     },
     {
       "id": "superpowers:executing-plans",
-      "required_for": ["Phase 7 sequential execution"],
+      "required_for": [
+        "Phase 7 sequential execution"
+      ],
       "install": "claude plugin install superpowers",
+      "plugin": "superpowers@claude-plugins-official",
+      "marketplace_source": "anthropics/claude-plugins-official",
       "fallback": "inline plan-execution instructions",
       "optional": false
     },
     {
       "id": "superpowers:dispatching-parallel-agents",
-      "required_for": ["Phase 7 parallel execution"],
+      "required_for": [
+        "Phase 7 parallel execution"
+      ],
       "install": "claude plugin install superpowers",
+      "plugin": "superpowers@claude-plugins-official",
+      "marketplace_source": "anthropics/claude-plugins-official",
       "fallback": "sequential execution",
       "optional": true
     },
     {
       "id": "interface-design:init",
-      "required_for": ["Phase 7 — new UI components"],
+      "required_for": [
+        "Phase 7 \u2014 new UI components"
+      ],
       "install": "claude plugin install interface-design",
       "fallback": null,
       "optional": true
     },
     {
       "id": "interface-design:critique",
-      "required_for": ["Phase 7 — UI critique pass"],
+      "required_for": [
+        "Phase 7 \u2014 UI critique pass"
+      ],
       "install": "claude plugin install interface-design",
       "fallback": null,
       "optional": true
     },
     {
       "id": "interface-design:audit",
-      "required_for": ["Phase 7 — UI design-system audit"],
+      "required_for": [
+        "Phase 7 \u2014 UI design-system audit"
+      ],
       "install": "claude plugin install interface-design",
       "fallback": null,
       "optional": true
     },
     {
       "id": "codex:review",
-      "required_for": ["Phase 7 review gate (human-driven)"],
+      "required_for": [
+        "Phase 7 review gate (human-driven)"
+      ],
       "install": "claude plugin install openai-codex",
       "fallback": "mcp__stratum__stratum_agent_run type=codex",
       "optional": true
     },
     {
       "id": "refactor",
-      "required_for": ["Phase 7 large-file split"],
+      "required_for": [
+        "Phase 7 large-file split"
+      ],
       "install": "user-installed skill at ~/.claude/skills/refactor/",
       "fallback": null,
       "optional": true
     },
     {
       "id": "update-docs",
-      "required_for": ["Phase 9 docs sync"],
+      "required_for": [
+        "Phase 9 docs sync"
+      ],
       "install": "user-installed skill at ~/.claude/skills/update-docs/",
       "fallback": "manual TODO surfaced in implementation report",
       "optional": true
     }
   ],
-  "external_binaries": [
-    {
-      "id": "rtk",
-      "detect": "rtk --version",
-      "required_for": [
-        "LLM-bound git-diff compression (build review)",
-        "agent Bash output compression via `rtk init -g` hook"
-      ],
-      "install": "brew install rtk  (or: cargo install --git https://github.com/rtk-ai/rtk)",
-      "recommend": "rtk init -g",
-      "optional": true
-    }
-  ]
+  "external_binaries": []
 }

package/README.md

@@ -1,14 +1,47 @@
 # Compose
 
-Compose is a CLI that drives a product idea from intent to shipped code. It runs YAML-defined multi-step pipelines on top of [Stratum](https://github.com/smartmemory/stratum), dispatching each step to an AI agent (Claude or Codex), checking postconditions, and pausing at human gates between phases. Output: a feature folder with design, blueprint, plan, code, tests, review trail, and an updated `ROADMAP.md` — auditable end-to-end.
+### Structured AI dev pipeline: goal to shipped code, with gates that hold
+
+#### *Your agent writes the code. Compose makes it prove it.*
+
+> Describe what you want. Compose decomposes it, forces the design decisions before any code is written, hands each step to the right agent, and refuses to advance until that step proves it is done. What comes back is a feature folder with the design, the blueprint, the plan, the code, the tests, and the full review trail. Auditable end to end.
 
 ![Compose Cockpit Shell](Screenshot.png)
 
-## Pitch
+## The problem
+
+An agent finishes, reports done, and the suite is green. Weeks later you find the feature. It exists, it has tests, and nothing calls it. The tests exercise a path that real data never enters.
+
+Nobody lied. The agent did what it was asked, the tests assert what they assert, and no step in between ever had to prove the thing was wired to anything. That gap does not show up in a diff review. It shows up in production, or it never shows up at all, which is worse.
+
+Compose sits above Claude Code and Codex rather than in place of them. It decides what the next step is, hands it to whichever agent should do it, and will not advance until the step proves it finished.
+
+## Who it's for
+
+- **Solo builders and small teams** shipping more code each week than they can personally review, who need something other than trust to decide when a feature is really done
+- **Tech leads reviewing agent output** who keep finding work that passes its own tests and is wired to nothing
+- **Anyone running more than one agent** (Claude for implementation, Codex for review) who wants the same standard applied no matter which model did the work
+- **Developers who lose the thread at a session boundary** and want the plan, the decisions, and the open questions to outlive the context window instead of living in chat scrollback
+- **Maintainers whose roadmap has drifted from reality** and want status derived from what actually shipped rather than from what someone remembered to update
+- **Teams who have to explain a decision months later**, what was chosen, what was rejected and why, and cannot reconstruct any of it from a diff
 
-- **Gates everywhere** — every phase transition (design, plan, ship) is approve/revise/kill. Human or Codex review at any point.
-- **Stratum-backed** — pipelines are declarative `.stratum.yaml` specs with typed contracts, `ensure` postconditions, and retry/`on_fail` routing. Specs are editable.
-- **Multi-agent** — Claude (via the Anthropic Agent SDK) and Codex (via the OpenAI CLI) plug in through a uniform connector interface; reviews can run on a different model than implementation.
+## Why Compose
+
+| | Prompting the agent directly | A plan.md or TODO list | **Compose** |
+| --- | --- | --- | --- |
+| **Definition of done** | Whatever the agent says | A checkbox someone ticks | Postconditions checked before the step can pass |
+| **Design decisions** | In the chat, then gone | Sometimes written down | Recorded artifacts, gated before any code |
+| **Survives a session boundary** | No, only scrollback | The text, not the reasoning | Feature folder: design, blueprint, plan, review trail |
+| **Review** | Whenever you remember | Manual | Enforced at every gate, and runnable on a different model than the one that wrote the code |
+| **Catches wired-to-nothing code** | No | No | Implementation review keyed to wiring, not only to tests |
+| **Roadmap status** | Manual | Manual, and it drifts | Generated from what actually shipped |
+| **Recovery mid-build** | Start over | Re-read and guess | Resume from recorded state |
+
+## How it holds the line
+
+- **Gates everywhere.** Every phase transition (design, plan, ship) is approve, revise, or kill. Human or Codex review at any point.
+- **Stratum-backed.** Pipelines are declarative `.stratum.yaml` specs with typed contracts, `ensure` postconditions, and retry/`on_fail` routing. Specs are editable.
+- **Multi-agent.** Claude (via the Anthropic Agent SDK) and Codex (via the OpenAI CLI) plug in through a uniform connector interface. Reviews can run on a different model than implementation.
 
 ## 30-second example
 
@@ -43,7 +76,7 @@ compose plan "a tool that summarizes my team's standups"
 
 ## Quick install
 
-Prerequisites: Node.js 18+ and a [Stratum](https://github.com/smartmemory/stratum) checkout as a sibling directory (the TS engine runs from source; `compose init` detects its MCP entrypoint automatically — the python `stratum-mcp` PyPI package is retired). Codex steps additionally need the OpenAI `codex` CLI. Full prereqs in [docs/install.md](docs/install.md).
+Prerequisites: Node.js 18+. [Stratum](https://github.com/smartmemory/stratum) needs no separate install — `@smartmemory/stratum` is a dependency, and `compose init` registers the installed copy's MCP entrypoint automatically (a sibling `stratum/` checkout is a development convenience, not a requirement; the python `stratum-mcp` PyPI package is retired). Codex steps additionally need the OpenAI `codex` CLI. Full prereqs in [docs/install.md](docs/install.md).
 
 The package is published to npm as `@smartmemory/compose`. Pick one install style:
 
@@ -51,7 +84,7 @@ The package is published to npm as `@smartmemory/compose`. Pick one install styl
 
 ```bash
 npm install -g @smartmemory/compose
-compose setup                # install bundled skills + register the Stratum MCP server (alias: compose sync)
+compose setup                # install bundled skills, auto-install missing required plugins, register the Stratum MCP server (alias: compose sync)
 ```
 
 **Option B — git clone (for development):**
@@ -85,6 +118,11 @@ One command — auto-detects whether compose was installed via npm or git clone:
 compose update
 ```
 
+Versions across the three published packages move together: `@smartmemory/compose-mcp` carries
+compose's exact version, and `@smartmemory/compose` shares a minor with `@smartmemory/stratum`
+(patches move independently). So compose 0.4.x pairs with stratum 0.4.x. See
+[.claude/rules/versioning.md](.claude/rules/versioning.md).
+
 For npm installs, this runs `npm install -g @smartmemory/compose@latest`. For git clones, it runs `git pull --ff-only && npm install`. Either way it then refreshes the global skill and (if invoked from inside a Compose project) re-runs `compose init` to refresh `.mcp.json` and pipeline templates. Use `compose update --force` to bypass the dirty-tree check on git clones.
 
 Check what you're running:
@@ -144,6 +182,17 @@ compose tracker sync     # reconcile op-log against remote provider
 
 See [docs/configuration.md](docs/configuration.md) for the full `tracker` config reference.
 
+## Backfilling a completion (guarded workspaces)
+
+Sometimes a feature is finished before its lifecycle was ever walked: it shipped before Compose existed, or the guard was switched off at the time. Compose can record that completion with evidence instead of an override token. Call the MCP tool `backfill_completion` (or `POST /api/vision/items/:id/lifecycle/backfill`) with the completing commit, a test attestation, a reason, and dated phase occurrences. The gate verifies the evidence, merges the occurrences into the phase history by their real dates, and moves the guard to `complete_backfilled`. Readers and the UI show which entries were backfilled.
+
+Features that were never registered with the guard need nothing else. Features registered before this release carry an older policy, and the guard will only accept the new one under a signed upgrade descriptor. The signature is the one thing an agent must never be able to produce on its own, so it is the one thing a human confirms:
+
+- **Once per Mac:** run `compose guard enrol` from a terminal. It installs a root-owned signing key and signer under `/Library/Compose/guard/`, a `sudo` rule that always re-authenticates (Touch ID via `pam_tid`), enrols the public key in stratum's trust root, and verifies the round trip. Two Touch ID prompts, then `done`.
+- **Every later signature is one Touch ID prompt.** When a backfill needs a descriptor that is not yet signed, the gate generates it, asks, verifies, and continues. Nothing else is manual. `compose guard sign` does the same explicitly and `compose guard status` shows custody, enrolment, descriptor freshness and whether the signed generations are committed.
+
+Signed descriptors live in `.compose/guard-upgrades/<sha256>/` (immutable) with `current` pointing at the live generation; commit them like any other workspace canon. A backfill refuses with `signature_not_approved` when the prompt is cancelled or cannot be shown (SSH session, `tmux` without `pam_reattach`), and with `upgrade_descriptor_unavailable` on a machine that has not run `enrol`. Admins who want the "one approval, one signature" property to hold against their own other `sudo` use can add `Defaults timestamp_timeout=0` to sudoers. Without macOS custody (Linux, CI), `compose guard descriptors` still writes the unsigned candidate and prints the `ssh-keygen -Y sign` command for an operator key.
+
 ## Remote access (mobile PWA from anywhere)
 
 The mobile cockpit at `/m` can be reached from outside localhost — bring your own tunnel, compose handles auth and pairing:
@@ -189,6 +238,29 @@ compose smartmemory sync --dry-run       # preview counts without ingesting
 compose smartmemory sync --feature CODE  # scope the sync to one feature
 ```
 
+### Maya colleague panel (opt-in, requires the SmartMemory service stack)
+
+With the SmartMemory fluid provider configured, a `maya` block summons Maya (the SmartMemory
+assistant) as a colleague inside the cockpit: a slide-over panel where you discuss ideas while
+Compose computes the memory findings (challenge, conviction, contradictions) and hands them to
+her as per-turn context. Her replies about a focused idea append to its discussion trail as
+`author: maya`.
+
+```json
+{
+  "maya": {
+    "baseUrl": "http://localhost:9005",
+    "auth": { "mode": "provision" }
+  }
+}
+```
+
+`auth.mode` is `provision` (a dedicated colleague identity minted lazily against the local
+smart-memory-service test surface) or `static` (paste a token in the panel; it is verified
+against the service before being stored). The colleague never runs degraded: without the
+SmartMemory provider the panel explains what to connect instead of falling back to plain chat,
+and capabilities the provider does not declare render as visibly unavailable.
+
 ## Documentation
 
 Topic-scoped reference: