@smartmemory/compose 0.2.49-beta → 0.2.51-beta

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

@@ -16,6 +16,14 @@ Both modes share Phase 6 (plan), Phase 7 (TDD execute + E2E + review loop + cove
 
 Before any phase begins, read project state via the `compose` MCP server (get_vision_items, get_phase_summary, get_blocked_items). Every feature OR bug maps to a vision item — check it exists, create it if not.
 
+## Platform Adaptation
+
+This SKILL.md uses **Claude Code** tool names (Skill, Agent/Task, EnterPlanMode, TodoWrite). On other harnesses, resolve each action to that harness's equivalent:
+
+- **Nous Hermes Agent** → `references/hermes-tools.md` (skills, `delegate_task` for subagents, MCP servers, AGENTS.md; Phase-6 plan mode degrades to a flat gate).
+
+The headless `compose build`/`compose fix` CLI is harness-agnostic — it runs from any shell and delegates agent execution to Stratum (Claude/Codex) regardless of the launching harness. The mapping files only matter for running the *interactive* lifecycle under a non-Claude-Code harness.
+
 ## Mode Selection
 
 `/compose` with no verb defaults to `build` for back-compat. Explicit verbs:
@@ -23,10 +31,25 @@ Before any phase begins, read project state via the `compose` MCP server (get_vi
 | Verb | Use | Folder |
 |---|---|---|
 | `/compose build <feature-ref>` | New feature, 3+ files, 2+ phases, needs design | `docs/features/<feature-code>/` |
+| `/compose build --quick <feature-ref>` | **Small-but-real** additive work — one flag + a test + changelog entry; well-scoped, single component | `docs/features/<feature-code>/` |
 | `/compose fix <bug-ref>` | Non-trivial bug, test failure, regression, hotfix | `docs/bugs/<bug-code>/` |
 
 **Skip Compose entirely for:** typos, one-line obvious fixes, cosmetic changes — just fix those directly.
 
+### Build Quick path: `/compose build --quick` (COMP-BUILD-QUICK)
+
+`--quick` collapses the build lifecycle to **design → implement → ship** with a *single design gate*. The phases `prd`, `architecture`, `blueprint`, `blueprint-verification`, `plan`, and `report` are **omitted** (not just self-skipping). Use it for small additive work that would otherwise pay full-lifecycle ceremony: a new flag plus its test, a small helper with a golden test, a one-component addition.
+
+This is the symmetric counterpart to fix mode's Quick path. Note the implementation asymmetry: fix's Quick path is a **triage decision** the agent makes at Phase F1, whereas build's `--quick` is a **CLI flag** that selects the trimmed `build-quick` pipeline (headless CLI: `compose build --quick <code>` → `template: 'build-quick'`, the same `--template` mechanism fix uses with `bug-fix`).
+
+**What `--quick` keeps (NOT OpenSpec's no-gates model):**
+- The design gate and ship gate.
+- All Phase-7 enforcement: TDD per task, verification-before-completion, the parallel + Codex review loop, the coverage sweep, and the generated-test review. Only phase *count* shrinks — enforcement is the differentiator and stays.
+
+**Escalation guardrail.** If, during design or decomposition, the work proves multi-file, cross-cutting, or in need of architecture/PRD-level design, **stop and recommend the user re-run with full `/compose build` (no `--quick`)** rather than silently under-scoping. Note the recommendation in the design doc.
+
+`--quick` is single-feature only — it is mutually exclusive with `--template` (it already selects one) and with batch builds (`--all`, prefix, or multiple codes).
+
 ## Partial Execution: `--through <phase>`
 
 By default, `/compose` runs the full lifecycle. Use `--through` to stop after a specific phase's gate is approved:
@@ -580,7 +603,7 @@ After completing a feature OR bug-fix lifecycle, update project memory:
 
 ## Dependencies
 
-`compose setup` (see `bin/compose.js` `syncSkills()`) installs compose-owned skills from `PACKAGE_ROOT/.claude/skills/` and `PACKAGE_ROOT/skills/` to `~/.claude/skills/` and tracks them in `~/.claude/skills/.compose-skills.json`.
+`compose setup` (see `bin/compose.js` `syncSkills()`) installs compose-owned skills from `PACKAGE_ROOT/.claude/skills/` and `PACKAGE_ROOT/skills/` to `~/.claude/skills/` and tracks them in `~/.claude/skills/.compose-skills.json`. It also installs the vendored agent definitions from `PACKAGE_ROOT/.claude/agents/` (`compose-explorer`, `compose-architect`) to `~/.claude/agents/` (COMP-AGENT-VENDOR-1).
 
 ### Vendored (ship with compose)
 

package/.claude/skills/compose/references/hermes-tools.md

@@ -0,0 +1,80 @@
+# Compose on Hermes Agent — Tool Mapping
+
+SKILL.md is written against **Claude Code** tool names. This file maps each
+primitive the compose lifecycle uses to its **Nous Hermes Agent** equivalent, so
+the lifecycle can run under Hermes. Scope: the *interactive* `/compose` lifecycle
+(the headless `compose` CLI is already harness-agnostic — it runs from any shell
+and delegates agent execution to Stratum).
+
+Hermes shares the three primitives the lifecycle depends on — **skills**, an
+**MCP client**, and **parallel subagent delegation** — so this is a name/packaging
+adaptation, not an architecture port. The one genuine gap is plan mode (Phase 6);
+see below.
+
+## Action mapping
+
+| Action compose requests (Claude Code) | Hermes equivalent |
+|---|---|
+| Invoke a skill (`/compose`, `superpowers:*`) — **Skill** tool | Skills load natively from `~/.hermes/skills/`. Install with `hermes skills install <git-url\|file\|registry-id>` (SKILL.md frontmatter convention). |
+| Dispatch a subagent (`compose-explorer`, `compose-architect`, `general-purpose`) — **Agent/Task** tool | `delegate_task` (runtime tool) — spawns an isolated child agent with its own conversation, terminal, and toolset; only the final summary returns. |
+| Dispatch 2-3 subagents **in parallel** (Phase 1 explorers, Phase 3 architects) | `delegate_task` with a **`tasks` array** — runs in parallel via a thread pool, `max_concurrent_children` (default **3**, matches compose's fan-out). Orchestrator→leaf nesting needs `delegation.max_spawn_depth: 2`. |
+| **Plan mode** (Phase 6) — `EnterPlanMode` / `ExitPlanMode` | **No direct equivalent.** Degrade to a flat gate: write `plan.md`, present it in chat, human approves before Phase 7. Compose already supports this fallback ("If Stratum unavailable, continue with flat prompt chain"). |
+| Task tracking ("create a todo", "mark complete") — **TodoWrite** | `hermes kanban` (statuses todo/triage/scheduled/blocked/running/done; `hermes kanban create "<title>"`). Optional/advisory — skip if not wired. |
+| Read a file — **Read** | Native file read, `@file` context injection, or shell (`cat`/`head`). |
+| Create / edit a file — **Write / Edit** | Native file tools, or a filesystem MCP server (`hermes mcp add fs --command ...`). |
+| Run a shell command — **Bash** | Hermes shell / per-subagent terminal session. |
+| Search contents / find files — **Grep / Glob** | Shell (`rg`, `grep`, `find`). |
+| compose tracker (`mcp__compose__*`) | `hermes mcp add compose --command "<compose-mcp-launch>"`, then call natively. |
+| Stratum (`mcp__stratum__stratum_*`, incl. `stratum_agent_run type=codex`) | `hermes mcp add stratum --command "<stratum-mcp-launch>"`, then call natively. **Codex review works unchanged** — it's an MCP call, harness-agnostic. |
+| Bind flow → vision item — `POST /api/stratum/bind` (HTTP) | Shell `curl` (harness-agnostic). |
+| Project instructions — **CLAUDE.md** | **AGENTS.md** (Hermes auto-injects `AGENTS.md`/`SOUL.md`/`USER.md`/`MEMORY.md` unless `--ignore-rules`). |
+
+## Setup (one-time, per workspace)
+
+```bash
+# 1. Install the compose skill into Hermes
+hermes skills install <compose-skill-git-url>        # → ~/.hermes/skills/compose/
+
+# 2. Register the MCP servers the lifecycle reads/writes through
+hermes mcp add compose  --command "<compose-mcp-launch-command>"
+hermes mcp add stratum  --command "<stratum-mcp-launch-command>"
+hermes mcp test compose && hermes mcp test stratum   # verify discovery
+
+# 3. Mirror compose's project guidance for auto-injection
+#    (compose's CLAUDE.md content → AGENTS.md at the project root)
+```
+
+## What does NOT port 1:1 (the real work)
+
+1. **`compose-explorer` / `compose-architect` are Claude agent files** (installed to
+   `~/.claude/agents/` by `compose setup` → `syncSkills()`). Hermes has no agent-file
+   format; re-express each as a **`delegate_task` prompt template** carrying the same
+   mandate (explorer = read-only codebase mapping; architect = competing-mandate
+   proposals). The prompts in SKILL.md Phases 1/3/4 are the source of truth — port
+   those strings, not the `.md` agent files.
+
+2. **`compose setup` targets Claude paths** (`~/.claude/skills/`, `~/.claude/agents/`,
+   `.compose-skills.json`). A Hermes path would install to `~/.hermes/skills/` via
+   `hermes skills install`. This is a `bin/compose.js syncSkills()` branch, not a
+   lifecycle change.
+
+3. **Plan mode (Phase 6)** has no Hermes analog — use the flat-gate degrade above.
+   This is the only lifecycle *behavior* that changes shape; everything else is a
+   rename.
+
+4. **Tier→model mapping is Claude-centric** (`server/model-tiers.js` maps
+   `critical/standard/fast` → Opus/Sonnet/Haiku). Under Hermes-as-driver this only
+   matters if you also make Hermes the *executing agent* — which is a **Stratum**
+   change (add a `hermes` provider to Stratum's agent runner), out of scope for this
+   harness-driver adaptation. See SKILL.md "Stratum Integration".
+
+## Quick decision guide
+
+- **Just want to launch builds from Hermes?** Don't port anything — run the headless
+  `compose build`/`compose fix` CLI from the Hermes shell. It executes via Claude/Codex
+  under Stratum regardless of the launching harness.
+- **Want the interactive lifecycle inside Hermes?** Use this mapping: install the skill,
+  register the two MCP servers, port the two agent prompts to `delegate_task`, accept the
+  flat-gate Phase-6 degrade.
+- **Want Hermes to be the building agent?** That's the Stratum provider-addition path,
+  not this file.

package/README.md

@@ -55,7 +55,7 @@ Then in your project:
 
 ```bash
 cd /path/to/your/project
-compose init                 # writes .compose/, registers MCP, scaffolds ROADMAP and pipeline specs
+compose init                 # writes .compose/, registers MCP, scaffolds ROADMAP, pipeline specs, contracts/vocabulary.yaml
 compose new "what you want to build"
 ```