peaks-cli 1.2.4 → 1.2.6

package/skills/peaks-solo/references/swarm-dispatch-contract.md

@@ -0,0 +1,186 @@
+# Swarm dispatch contract
+
+> Reference for `peaks-solo` Swarm phase and the role sub-agents (`peaks-ui` / `peaks-rd` planning / `peaks-qa` test-cases). Defines the **mechanism** of fan-out: how Solo launches sub-agents, what the sub-agent prompt must contain, what the sub-agent must return, and how Solo reduces the result.
+
+## 1. Why this exists
+
+The previous "Swarm" used `Skill(skill="peaks-rd")` calls. That is **single-stack and blocking** — there is no concurrency. Three sequential `Skill` calls run in order on the same main loop, not in parallel. The "parallel Agent calls" wording in the old SKILL.md was a v1.x illusion.
+
+This contract moves the Swarm to the `Task` tool with `subagent_type="general-purpose"`, which is the only Claude Code mechanism that gives real concurrent fan-out. Solo launches all sub-agents in a single message; the platform schedules them concurrently.
+
+## 2. When to swarm (decision)
+
+Solo runs the swarm only after `peaks request show <rid> --role prd` is in state `confirmed-by-user` or `handed-off`. Before that, there is nothing for the sub-agents to derive from.
+
+Solo computes the **swarm plan** from three signals (see "Swarm gate" in the main SKILL.md):
+
+1. `--type` from `peaks request init` (already on the PRD artefact).
+2. `frontendOnly` from `.peaks/<session-id>/rd/project-scan.md` `## Project mode`.
+3. Frontend keyword scan over the PRD body.
+
+The plan is written to `.peaks/<session-id>/sc/swarm-plan.json` before any Task call, so SC and TXT can audit what was launched. Solo updates `.peaks/.active-skill.json` to `gate=swarm-fan-out` at this point.
+
+| `--type` | Frontend signal | Plan |
+|---|---|---|
+| `feature` / `refactor` / `bugfix` | keyword hit OR `frontendOnly=true` | `[ui, rd-planning, qa-test-cases]` |
+| `feature` / `refactor` / `bugfix` | no keyword hit AND `frontendOnly=false` | `[rd-planning, qa-test-cases]` |
+| `config` / `docs` / `chore` | (any) | `[]` (swarm skipped, recorded in plan) |
+
+In `assisted` and `strict` modes, Solo replaces signal (3) with a three-option `AskUserQuestion` (see "Mode-driven fan-out shape" in the main SKILL.md) and uses the user's choice as the plan.
+
+## 3. Sub-agent invocation template
+
+Solo emits one Task call per sub-agent in the plan, all in the same message:
+
+```js
+Task({
+  subagent_type: "general-purpose",
+  description: "<role> for rid=<rid>",
+  prompt: <see role-specific sections below>
+})
+```
+
+### 3.1 Common prompt header (all sub-agents)
+
+```
+You are a sub-agent invoked by peaks-solo. You are NOT the main Claude session.
+Your job: execute ONE role from the peaks skill family and write its artefact(s).
+Return a compact JSON envelope — do not write prose.
+
+## Hard prohibitions
+- Do NOT call Skill(skill="..."). You are the role.
+- Do NOT call `peaks skill presence:set` — the main loop owns .peaks/.active-skill.json.
+  If you need to record state, write to .peaks/<session-id>/system/sub-agent-<role>.json.
+- Do NOT commit, push, install hooks, or apply settings.json mutations.
+- Do NOT ask the user interactive questions. If you need clarification, return
+  {"status":"blocked","blockedReason":"<text>"} and let the main loop handle it.
+
+## Runtime arguments (provided by Solo)
+- project: <repo>            (git repo root, NOT a sub-package)
+- session-id: <sid>          (from .peaks/.active-skill.json or .peaks/.session.json)
+- request-id: <rid>          (PRD id)
+- type: <type>               (feature | bugfix | refactor | config | docs | chore)
+- mode: <mode>               (full-auto | swarm | assisted | strict)
+- project-scan-path: <path>  (read this for component library / CSS / build tool)
+- existing-system-path: <path>  (legacy projects only)
+- frontendOnly: <bool>       (from project-scan)
+- frontendKeywordHit: <bool> (Solo's PRD scan result)
+```
+
+### 3.2 peaks-ui sub-agent prompt
+
+Append after the common header:
+
+```
+## Role: UI design direction
+You are running peaks-ui. Produce design direction, not code. RD will implement.
+
+Steps:
+1. peaks request init --role ui --id <rid> --project <repo> --apply --type <type> --json
+2. peaks request show <rid> --role prd --project <repo> --json
+3. Read <project-scan-path> for component library / CSS framework.
+4. Run the prototype fidelity gate: Figma file? PRD visuals? Headed browser?
+5. Write TWO artefacts:
+   - .peaks/<sid>/ui/design-draft.md
+   - .peaks/<sid>/ui/requests/<rid>.md
+6. Return:
+   {
+     "role": "ui",
+     "rid": "<rid>",
+     "status": "ok" | "blocked" | "skipped",
+     "artefacts": [".peaks/<sid>/ui/design-draft.md", ".peaks/<sid>/ui/requests/<rid>.md"],
+     "warnings": [],
+     "blockedReason": null
+   }
+
+If you determine the request is non-visual (no UI surface, no design impact),
+return {"status":"skipped","reason":"non-frontend-request"} so Solo can record
+the misfire in sc/swarm-plan.json.
+```
+
+### 3.3 peaks-rd (planning) sub-agent prompt
+
+```
+## Role: RD planning
+You are running peaks-rd's planning step. Produce the planning artefact, not code.
+Code is written in a later sub-agent or inline run.
+
+Steps:
+1. peaks request init --role rd --id <rid> --project <repo> --apply --type <type> --json
+2. peaks request show <rid> --role prd --project <repo> --json
+3. peaks request show <rid> --role ui  --project <repo> --json  (if ui in plan)
+4. Read <project-scan-path>. If absent and Solo did not pre-create it, create it
+   by running `peaks scan archetype --project <repo> --json` and copying the JSON
+   into rd/project-scan.md.
+5. Read <existing-system-path> if archetype is legacy-*.
+6. Write the type-appropriate planning artefact:
+   - feature | refactor  → .peaks/<sid>/rd/tech-doc.md
+   - bugfix              → .peaks/<sid>/rd/bug-analysis.md
+   - config | docs | chore → no planning artefact required. Return skipped.
+7. Return:
+   {
+     "role": "rd-planning",
+     "rid": "<rid>",
+     "status": "ok" | "blocked" | "skipped",
+     "artefacts": [".peaks/<sid>/rd/tech-doc.md"],   // or [] when skipped
+     "warnings": [],
+     "blockedReason": null
+   }
+```
+
+### 3.4 peaks-qa (test-cases) sub-agent prompt
+
+```
+## Role: QA test-case generation (planning, not execution)
+You are running peaks-qa's planning step. Produce test cases, do NOT execute them.
+The execution step runs after RD implementation in a separate sub-agent.
+
+Steps:
+1. peaks request init --role qa --id <rid> --project <repo> --apply --type <type> --json
+2. peaks request show <rid> --role prd --project <repo> --json
+3. peaks request show <rid> --role rd  --project <repo> --json
+4. Read <project-scan-path>.
+5. Write .peaks/<sid>/qa/test-cases/<rid>.md with test cases linked to PRD
+   acceptance items (use **Acceptance:** A1, A2 style).
+6. Return:
+   {
+     "role": "qa-test-cases",
+     "rid": "<rid>",
+     "status": "ok" | "blocked" | "skipped",
+     "artefacts": [".peaks/<sid>/qa/test-cases/<rid>.md"],
+     "warnings": [],
+     "blockedReason": null
+   }
+
+If --type is docs|chore, return {"status":"skipped","reason":"type=<type>"} —
+no acceptance surface to plan tests for.
+```
+
+## 4. Reducer (Solo side)
+
+After all sub-agent Tasks return, Solo:
+
+1. Restores presence ONCE (not per-agent):
+   ```
+   peaks skill presence:set peaks-solo --project <repo> --mode <mode> --gate swarm-converged
+   ```
+2. Runs `ls` checks against `sc/swarm-plan.json` — every promised artefact must exist (Gate B hard). If any are missing, apply the degradation rules in "Degradation when swarm roles fail or are absent" (main SKILL.md).
+3. Updates `sc/swarm-plan.json` with the final status of each sub-agent (ok / blocked / skipped / error).
+4. Advances to step 4 (RD implementation) with all the artefacts in hand.
+
+## 5. Presence restoration (single-shot)
+
+Sub-agents are explicitly forbidden from calling `peaks skill presence:set`. That means `.peaks/.active-skill.json` does not move during the fan-out. Solo sets it to `gate=swarm-fan-out` before fan-out and to `gate=swarm-converged` once after all Tasks return. The status header (the `Peaks-Cli Skill: peaks-solo | Peaks-Cli Gate: <gate>` line) therefore reads consistently across the fan-out window.
+
+If a sub-agent is misbehaving and writes to `.peaks/.active-skill.json` anyway, the next Solo presence-set (after fan-out) overwrites it — the bug self-heals on the next gate advance, but the swarm-phase display may be off. The hard prohibition is there to prevent this; Solo should still treat the file as a single-writer resource.
+
+## 6. Why not a `peaks-swarm` skill?
+
+A skill cannot itself trigger sub-agents — the Skill tool runs in the main loop. The orchestrator (peaks-solo) has to be in the main loop and has to use the Task tool directly. Putting swarm logic into a separate skill would either re-introduce the "single-stack blocking" anti-pattern or require a custom slash command that bypasses the Skill tool. The current design keeps swarm control in peaks-solo where it belongs.
+
+## 7. Tests / dogfood
+
+- `peaks scan archetype --project <repo> --json` must keep emitting `frontendOnly` and `frontendOnlyReason`. Both fields are read here and by the existing pre-RD scan contract.
+- `peaks request show <rid> --role prd --json` must surface the `--type` chosen at `peaks request init`. Sub-agents pass it through unchanged.
+- `peaks skill presence:set` must remain single-writer-friendly (the sub-agents do not call it).
+- Smoke test: a full-auto peaks-solo run on a `legacy-frontend` project with a UI-affecting PRD should produce `sc/swarm-plan.json` containing all three sub-agents and three corresponding artefacts in `ui/`, `rd/`, `qa/`.

package/skills/peaks-txt/SKILL.md

@@ -207,12 +207,28 @@ peaks capabilities --json
 
 # 6. Memory extraction — --apply is REQUIRED to write .peaks/memory
 #    (without --apply the command only previews; the directory will NOT be created)
+#    You MUST scan the handoff capsule for embedded memory blocks FIRST. If none
+#    are present, the step is a no-op (the command succeeds with extractedCount=0
+#    and writes nothing). If blocks are present, --apply writes them and the
+#    index is regenerated.
+grep -c "peaks-memory:start" .peaks/<id>/txt/handoff.md || true   # skill-side scan; do NOT add a new CLI
 peaks memory extract --project <repo> --artifact .peaks/<id>/txt/handoff.md --apply --json
 peaks skill presence:clear --project <repo>                      # handoff capsule complete, remove presence indicator
 ```
 
 `peaks memory extract --apply` writes to `.peaks/memory` (without `--apply` it only previews). The handoff capsule `.peaks/<id>/txt/handoff.md` is the primary artifact for extraction — embed `<!-- peaks-memory:start -->` blocks in it for stable project facts before running extract.
 
+### Memory block embedding rule (BLOCKING — read before writing the handoff)
+
+Every handoff capsule you emit **MUST** include the scan for stable facts. The minimum acceptable is:
+
+- Run `grep -c 'peaks-memory:start' .peaks/<id>/txt/handoff.md` after writing the capsule body.
+- If the count is 0 AND this session surfaced a stable project fact (an architectural decision, a stack constraint, a naming convention, a refactor approved by the user, an API pattern, a hard rule from RD/QA review), you MUST go back and embed at least one `<!-- peaks-memory:start -->` block before declaring TXT complete. Skipping the block is a workflow violation.
+- If the count is 0 AND no stable fact was surfaced (pure analysis, no code touched, all transient), it is acceptable to skip embedding — but you MUST still run `peaks memory extract --apply` so the artefact state stays consistent (the command will be a no-op write, that's fine).
+- If the count is ≥ 1, the `--apply` extract will write one markdown per block to `.peaks/memory/` and regenerate `index.json`. The user sees the durable persistence; that is the entire point of this step.
+
+This rule is the skill-side half of the **Skill is primary, CLI is auxiliary** contract: the LLM is responsible for embedding blocks (skill prompt, no CLI can decide what is stable), and the CLI is responsible for atomic persistence (`peaks memory extract --apply`, single shot, structured JSON envelope).
+
 ### Transition verification gates (MANDATORY — run the command, see the output)
 
 You cannot declare TXT complete from memory. Each gate below is a `ls` command you **MUST run** and whose output you **MUST see** before proceeding.

package/skills/peaks-ui/SKILL.md

@@ -7,9 +7,68 @@ description: UI and experience skill for Peaks. Use when a workflow touches UI/U
 
 Peaks-Cli UI handles experience, interaction, visual direction, and UI-specific refactor artifacts.
 
-## Skill presence (MANDATORY first action)
+## Hard contracts for browser inspection (BLOCKING — read before any browser_take_screenshot / login flow)
 
-Before any analysis or tool call, immediately run:
+UI's headed-browser work (visual inspection, regression seed capture, Figma / live-page cross-check) follows the same two contracts as `peaks-qa` and `peaks-rd`. The contracts are defined in full in `peaks-qa` ("Hard contracts for browser validation"); UI inherits them.
+
+### Contract 1 — Inspection screenshots must land under .peaks/<sid>/qa/screenshots/
+
+Every `mcp__playwright__browser_take_screenshot` call **MUST** pass `filename` inside `.peaks/<session-id>/qa/screenshots/`, named after the inspection target (e.g. `home-after-cta.png`, `empty-state-v2.png`). Do not let Playwright fall back to the project root. After every batch, run:
+
+```bash
+ls .peaks/<sid>/qa/screenshots/*.png 2>&1
+find . -maxdepth 1 -name '*.png' 2>&1
+```
+
+`find` must be empty; any project-root `.png` is a leak and must be moved into the screenshots directory before completing this skill.
+
+### Contract 2 — Login / CAPTCHA / SSO / MFA wall is a hard block, not a skip
+
+UI's headed-browser inspection hits the same auth walls. The flow is identical to QA: `AskUserQuestion` with three options (logged in / skip / cancel); no silent downgrade to static screenshots, no inferring login from DOM state. The full hard-block contract is defined in `peaks-qa`; UI inherits it.
+
+## Sub-agent dispatch (when launched by peaks-solo swarm)
+
+When this skill is launched as a sub-agent via `Task(subagent_type="general-purpose", ...)` from `peaks-solo`, the following sections of THIS skill are **suspended** for the sub-agent run:
+
+- **Skill presence (MANDATORY first action)** — do NOT call `peaks skill presence:set peaks-ui`. The sub-agent must not overwrite `.peaks/.active-skill.json`; the main Solo loop owns that file. If you need to mark your own state, write a marker file at `.peaks/<session-id>/system/sub-agent-ui.json` and only that.
+- **Workspace initialization** — Solo has already run `peaks workspace init` before fan-out. Do not re-run it.
+- **Mode selection** — Solo has already chosen the mode.
+- **Statusline install** — already done by Solo at session startup.
+
+What the sub-agent **MUST** still do:
+
+0. **Do NOT call `peaks request init`** — Solo has already initialised the request artefact slot in the main loop before fan-out. The sub-agent reads it via `peaks request show <rid> --role ui --project <repo> --json` if it needs to.
+2. `peaks request show <rid> --role prd --project <repo> --json` to read the PRD scope.
+3. Read project-scan (`rd/project-scan.md`) for component library, CSS framework, design-system context.
+4. Run the prototype fidelity check (Figma / PRD visuals / headed browser).
+5. Write the two artefacts: `.peaks/<session-id>/ui/design-draft.md` and `.peaks/<session-id>/ui/requests/<rid>.md`.
+6. Return only a compact JSON envelope:
+
+```json
+{
+  "role": "ui",
+  "rid": "<rid>",
+  "status": "ok" | "blocked" | "skipped",
+  "artefacts": [".peaks/<sid>/ui/design-draft.md", ".peaks/<sid>/ui/requests/<rid>.md"],
+  "warnings": [],
+  "blockedReason": null
+}
+```
+
+**Hard prohibitions** (sub-agent context):
+
+- Do NOT call `Skill(skill="...")`.
+- Do NOT call `peaks skill presence:set` — Solo owns the active-skill file.
+- Do NOT modify application code. UI is design-direction only; the actual frontend code is written in the RD implementation phase.
+- Do NOT install MCP servers. If `peaks mcp list` shows playwright-mcp missing and the headed browser is required, return `{"status":"blocked","blockedReason":"playwright-mcp-unavailable"}` and let Solo escalate to the user.
+- Do NOT commit, push, install hooks, or apply settings.json mutations.
+- Do NOT ask the user interactive questions. If you need clarification, return `{"status":"blocked","blockedReason":"<text>"}`.
+
+If the request does not affect user-visible behavior (no frontend keyword hit, `frontendOnly=false`), the swarm plan should not include UI at all — Solo will not launch this sub-agent. But if it does launch you and you determine the work is non-visual, return `{"status":"skipped","reason":"non-frontend-request"}` so Solo can record the misfire.
+
+## Skill presence (MANDATORY first action — main-loop context only)
+
+When this skill is running in the main Claude session (not as a sub-agent), before any analysis or tool call, immediately run:
 
 ```bash
 peaks skill presence:set peaks-ui --project <repo> --mode <mode> --gate startup