[EPIC] Production-ready, end-to-end onboarding on every harness (Pi-parity distribution)

[richard-devbot]

Why this epic exists

Epic #376 proved RStack's enforcement is real on every harness (guard + validator sandbox + budgets). This epic is about the other half — distribution & end-to-end onboarding. Right now only Pi is genuinely install-and-go; the docs promise a Claude Code plugin (/plugin install …, /sdlc-* commands) that does not exist in the repo, and Tau/Operator/Hermes are "adapter written, wired manually, barely live-run." A user who installs rstack-agents and follows the README cannot reproduce the Pi experience anywhere else. This epic makes every supported harness reach Pi-parity onboarding: install → one wiring step → drive the governed loop.

The command surface (what a harness must expose)

The product is 18 sdlc_* tools (the LLM-facing surface — identical names/schemas on every harness, served from one registry via bin/rstack-bridge.ts --list):

Tool	What it does
sdlc_orchestrate	Load orchestrator/builder/validator instructions into the task (call first)
sdlc_start	Begin a governed run under .rstack/runs/<id>/
sdlc_clarify	Capture product-owner answers before planning
sdlc_plan	Build the stage/task graph
sdlc_spec	Read/update a stage artifact (vision, requirements, architecture, …)
sdlc_dor_check	Definition-of-Ready gate → dor-report.json/readiness.json
sdlc_build_next	Claim + prepare the next builder task (enforces attempt budgets)
sdlc_validate	Read-only validation report (enforces telemetry budgets)
sdlc_approve	Record a human approval/rejection at a gate
sdlc_decisions / sdlc_decide	List/add / resolve/waive Decision Queue items
sdlc_delegate	Spawn agents as isolated workers (validators default read-only)
sdlc_status	Run status, task progress, next recommended action
sdlc_agents	List package/project agents/skills by domain (routing)
sdlc_memory	Search/append episodic project learnings
sdlc_rollback	Restore a stage to its last verified checkpoint
sdlc_trace	Trace tool calls/results for a task
sdlc_dashboard	Generate a static run dashboard

Plus the rstack-agents CLI (host-agnostic operations): init, doctor, adopt, guard, gate, pipeline status|run|loop, rollback, checkpoint-status, config validate, approvals audit, decisions, dor, review independence, attest/verify-attestations, drift, memory inspect, env scan, inventory, list, add, notify, context/observe/notify-hook/statusline, hub. (Full detail: docs/SETUP.md.)

How the backend is designed (harness-independent)

Everything that decides lives in src/core/harness/ (~32 pure modules) and is reused by every adapter — zero host logic:

• State & run model: runs.js, run-state.js, pipeline-state.js, stages.js, migrations.js (schema-versioned, atomic via safe-write.js).
• Contracts: contracts.js (builder/validator completeness), required-checks.js, validator-registry.js.
• Governance/enforcement: guardrails.js (attempt/telemetry budgets), destructive-actions.js (the classifier), validator-sandbox.js, stage-approvals.js, approval-audit.js (trust boundary), checkpoints.js, retry-policy.js.
• Loop & goals: goal-check.js, goal-loop.js, context-pressure.js.
• Evidence & audit: evidence.js, attestations.js, review-independence.js, drift.js, telemetry.js, readiness.js, decisions.js.
• Two front doors: bin/rstack-bridge.ts (framework-neutral tool bridge) and rstack-agents guard (framework-neutral enforcement gate). Both are how non-Pi hosts reach the core.

The Pi reference pattern (what "end-to-end, just like Pi" means)

Pi is the gold standard. src/integrations/pi/rstack-sdlc.ts does three things, and every harness must reproduce all three:

1. Register the 18 tools — registerTool(...) × 18 (the LLM-facing surface).
2. Wire the lifecycle hooks — pi.on(...): tool_call (the enforcement gate), before_agent_start (inject the orchestrator packet on RStack prompts), session_start (launch the Business Hub), tool_result (observability), session_shutdown, resources_discover (expose the agent/skill catalog).
3. Auto-load — pi.extensions in package.json, so npm install is the only step.

Result: on Pi, install → sdlc_start { goal } → the whole governed loop, enforced, observable, no manual wiring. That is the bar for every other harness.

Current state (honest)

Harness	Tools registered	Enforcement hook	Context/observe	One-command onboarding	Live-run end-to-end
Pi	✅	✅	✅	✅ auto-load	✅
Claude Code	via bridge only	✅ (guard hook init writes)	✅	❌ no plugin / marketplace / /sdlc-* commands	hooks only
Tau	✅ (bridge)	✅ (tool_call)	⚠️ partial	⚠️ manual settings merge	once (doctor)
Operator	✅ (bridge)	❌ no blocking hook	❌	⚠️ manual settings merge	once
Hermes	✅ (bridge)	✅ (pre_tool_call)	⚠️	⚠️ manual symlink	❌ never run against real Hermes

Children

• [P0][claude-code] Ship the real Claude Code plugin + marketplace (/plugin install sdlc-rstack, /sdlc-* commands) #388 [P0] Claude Code plugin + marketplace — build .claude-plugin/marketplace.json + an sdlc-rstack plugin (/sdlc-* commands driving the loop + agents + the hooks init writes). The flagship gap.
• [P1][tau] Bring Tau to Pi-parity onboarding (install-and-go + command ergonomics + a real run) #389 [P1] Tau → Pi-parity onboarding — install-and-go + command ergonomics + a real live run.
• [P1][hermes] Live-verify the Hermes plugin against real Hermes + smoother install #390 [P1] Hermes → live verification + smoother install — the adapter is code-complete but has never run against real Hermes.
• [P2][operator] Confirm operator_use hook API; wire what's possible; make the tier honest #391 [P2] Operator — honest tier + wire available hooks — confirm the operator_use hook API; wire observe/context if any; nail the manual-guard recipe + truthful docs.
• [P1][testing] End-to-end live-test matrix per harness (only Pi is exercised today) #392 [P1] End-to-end live-test matrix — only Pi is exercised; add a per-harness smoke run so "production-ready" is a fact, not a claim.

Suggested order: #388 first (its marketplace manifest unblocks installability for the whole plugins/ library), then #392 live-test matrix as the harness stabilizes, with #389/#390/#391 in parallel.

Prereq order: the marketplace manifest (in the Claude Code issue) unblocks installability for all the repo's plugins, not just SDLC.

[richard-devbot]

All framework repos (one place)

Harness / ref	Git
Pi (reference, end-to-end)	https://github.com/earendil-works/pi.git
Tau	https://github.com/Jeomon/Tau.git
Hermes	https://github.com/NousResearch/hermes-agent.git
Claude Agent SDK (Python)	https://github.com/anthropics/claude-agent-sdk-python.git
Operator (operator_use)	repo TBD — see #391
RStack	https://github.com/richard-devbot/SDLC-rstack.git

Prior art / competitor references (research, not integration targets):

• ai-sdlc (closest competitor): https://github.com/ai-sdlc-framework/ai-sdlc.git
• Archon (workflow-orchestrates coding agents): https://github.com/coleam00/Archon.git
• AI-SDLC-SOPs (governance-philosophy + MCP mesh): https://github.com/AISDLC/AI-SDLC-SOPs.git

The through-line gap

Every harness must reproduce Pi's three moves — register the 18 tools · wire the lifecycle hooks (enforcement + context + observe) · auto-load — and then be run once for real. Today only Pi does all four. Children #388–#392 close this per host.

Research prompt (run BEFORE any harness build)

Before adapting a harness to RStack, produce a one-page "integration fit" note:
1. Clone the harness repo (above). Identify its (a) tool-registration API, (b) pre-tool hook and whether it can BLOCK, (c) session/result hooks for observe/context, (d) command/slash surface, (e) auto-load/plugin-discovery mechanism.
2. Map each to Pi's reference (registerTool / pi.on("tool_call") / before_agent_start / tool_result / pi.extensions). Mark each cell: native | via-bridge | via-guard | not-possible.
3. State the achievable tier honestly (full Pi-parity vs bridge+manual). If a capability is host-impossible, say so — do not design a false gate.
OUTPUT: the fit note + the shortest real onboarding path, checked into the harness's child issue, BEFORE writing adapter/plugin code.

[richard-devbot]

Operator (operator_use) repo TBD — see #391 https://github.com/CursorTouch/Operator-Use.git