RStack SDLC

---

The most governance-complete AI-SDLC layer available for autonomous coding agents. Not a prompt template, not a set of suggested conventions — every gate, guardrail, and contract in this README is backed by runtime enforcement in code, live-verified against five real coding harnesses, and observable end-to-end from a real dashboard, not a demo.

RStack sits on top of Pi, Claude Code, Operator, Codex-style CLIs, Gemini-style CLIs, or a custom harness and gives agent teams a repeatable lifecycle with approvals, builder/validator contracts, evidence, memory, budget envelopes, and a live Business Hub.

Enforcement tiers: full, live tool-call gating on Pi, Tau, Claude Code, Hermes, and Operator — each verified against the real, installed framework (Tau by shadowing its built-in tools, Hermes via its real pre_tool_call hook, Operator via the shipped bootstrap.py wrapper, since operator-use has no plugin-loading mechanism of its own). Every other harness gets the governed contracts, state, and Business Hub, plus a guided recipe to wire the guard into its own hook system (wire-your-own-harness).

What makes this different from a prompt-only "AI SDLC" framework:

• Enforced, not requested. Destructive-action gates, attempt budgets, and the validator sandbox are checked in code on every tool call — an agent cannot talk its way past a guardrail.
• Built for unattended operation. A durable worker scheduler (pipeline watch) drives a run for hours without a human at the keyboard, with a persisted heartbeat, graceful signal handling, and a duplicate-instance guard — not a toy loop that dies the moment the terminal closes.
• Real execution, not self-reported success. Builder-claimed test results are re-run in a locked-down transient sandbox; the gate trusts the container's exit code, never the agent's own word.
• A truth layer, not a status page. Quality & Risk scores, traceability chains, and drift detection are computed from the actual .rstack evidence on disk — an "Unknown" is a real unknown, never a fabricated green.
• Cross-harness by construction. The same governed run state, approvals, and Business Hub work identically whether the agent behind the keyboard is Pi, Claude Code, Tau, Hermes, or Operator.

clarify → plan → spec → approve → build → validate → release-readiness → learn

New here? Start with the one-page Setup & Usage guide → docs/SETUP.md — install, per-harness wiring (Pi · Claude Code · Tau · Operator · Hermes · custom), running a governed pipeline, approvals, the dashboard, and the full CLI reference, all in one place.

Meet the studio

Your AI software team in one place — builders, validators, the skills rack, and live delivery status. Open the interactive 3D workspace → — drag to look around, scroll to zoom, click any room to explore, or take the guided tour where each specialist introduces itself.

Business Hub in action

Real screenshots from a live rstack-agents hub session against seeded .rstack state — every number, band color, and status pill below is computed from real evidence on disk, not mocked for the README.

Delivery outcome and the proof rail — the honest verdict a run earns, with the exact evidence path behind it:

Quality & Risk — an aggregated risk score and complexity index computed from real builder-reported risks, guardrail blocks, and container-verified execution, never a self-report:

SDLC stage health — all 15 canonical stages, real pass/fail/risk counts per stage, at a glance:

Table of contents

• Business Hub in action
• Quick start
• Govern an existing codebase
• Choose your framework
• Configure your team
• Agent identity and standby automation
• Upgrade path
• Start your first governed run
• What init creates
• Builder and validator sandbox model
• Business Hub
• CLI reference
• Known limitations and roadmap
• Documentation
• Development

---

Quick start

New here? RStack in 5 Minutes — install to a validated, human-approved pipeline task from a bare terminal, no framework required.

cd your-project
npm install rstack-agents
npx rstack-agents init --profile business-flex

init auto-detects pi | claude-code | operator | custom, creates .rstack/, scaffolds bootstrap files (SOUL.md, HEARTBEAT.md, and framework-specific CLAUDE.md or AGENTS.md), registers the project with the Business Hub, writes framework glue, and never overwrites existing files.

Verify your setup: run npx rstack-agents doctor — it checks your environment, config, and framework wiring, and runs a live guard self-test to prove enforcement is working. Every problem prints its fix. Per-framework "test in 5 minutes" recipes: docs/integrations/testing-matrix.md.

If .rstack/ already exists, init adopts it and preserves all prior runs. To start clean instead (nothing is deleted):

npx rstack-agents init --fresh   # archives prior state to .rstack/archive/<timestamp>/

Pick a profile size:

npx rstack-agents init --profile lean-mvp
npx rstack-agents init --profile enterprise-webapp

Profile	Best for	Result
business-flex	Most business/product teams	Product, backend, frontend, QA, security, devops, docs, budget policy, Business Flex dashboard
lean-mvp	Fast prototypes	Smaller full-stack team and lower budget defaults
enterprise-webapp	Heavier governance	Enterprise web app team with security/compliance/devops emphasis

---

Govern an existing codebase

Brownfield is first-class. adopt scans your repo read-only and harvests real artifacts (README, tests, CI config, deploy manifests) into a resumable pipeline run — stages with evidence are marked DONE, gaps are left open, and nothing is invented. Work then resumes from reality, not from scratch.

npx rstack-agents adopt --dry-run   # print the stage-population plan, write nothing
npx rstack-agents adopt             # harvest evidence into an adoption run
npx rstack-agents pipeline run      # advance from the gaps, stopping at human gates

Full guide: docs/brownfield-adoption.md. To keep iterating toward a goal after adoption, see the loop recipes in docs/loop-recipes.md.

---

Choose your framework

RStack is a plugin layer — install your AI coding framework first, then run init.

Framework	Integration	Bootstrap files	Harness entry
Pi	Native adapter	SOUL.md, HEARTBEAT.md	sdlc_start(goal="...")
Claude Code	First-class	CLAUDE.md, SOUL.md, HEARTBEAT.md	/sdlc-start or orchestrator
Operator	Python bridge	SOUL.md, HEARTBEAT.md	Operator extension + Node bridge
Codex / custom	Asset + bridge	AGENTS.md, SOUL.md, HEARTBEAT.md	Node bridge or prompt-driven

Framework	What you get
Pi	All 18 sdlc_* tools, lifecycle hooks, tool gating, auto-launch dashboard
Claude Code	Guard/observe/context hooks + the sdlc-rstack plugin (/plugin install sdlc-rstack) for the full /sdlc-* command surface
Operator	Python adapter shells out to the same Node harness
Codex / Gemini / custom	.rstack/ state contract, agents/skills as context, CLI bridge

Per-framework setup: docs/mintlify/getting-started/install-your-framework.mdx

Custom harness bridge:

RSTACK_PROJECT_ROOT="$(pwd)" \
  npx tsx node_modules/rstack-agents/bin/rstack-operator-bridge.ts sdlc_start '{"goal":"..."}'

Full contract: docs/integrations/custom.md

---

Configure your team

RStack ships a large catalog (196 agents, 68 skills, 73 plugins), but you configure only what your project needs. Plugins are organized by domain under plugins/<domain>/<name>/ (e.g. plugins/backend/backend-development/) — sdlc-rstack itself stays at plugins/sdlc-rstack/ since it's the core product plugin, not a domain accelerator. Vendored plugins keep their original author/license; see THIRD-PARTY-NOTICES.md.

1. Pick a profile

Profiles write .rstack/rstack.config.json and .rstack/budget.json:

npx rstack-agents init --profile business-flex   # default for most teams
npx rstack-agents init --profile lean-mvp        # prototypes
npx rstack-agents init --profile enterprise-webapp # compliance-heavy delivery

2. Narrow domains and plugins

Edit .rstack/rstack.config.json any time:

{
  "profile": "business-flex",
  "enabled_domains": ["product", "backend", "qa", "security", "docs"],
  "enabled_plugins": [
    "business-analytics",
    "backend-development",
    "unit-testing",
    "security-scanning",
    "documentation-generation"
  ],
  "dashboard_pages": ["command", "business-flex", "workflow", "agent-work", "live-feed", "approvals"]
}

When sdlc_plan runs, each task gets active profile, routing explanation, and budget envelope.

3. Add plugins locally

Copy one plugin pack into your project:

npx rstack-agents add plugin unit-testing
npx rstack-agents add plugin security-scanning

Plugins land in .rstack/plugins/<name>/.

4. Browse the catalog

npx rstack-agents list agents
npx rstack-agents list skills
npx rstack-agents list plugins

5. Project-local overrides

Drop custom assets in .rstack/ — they take precedence over package defaults:

.rstack/agents/     custom agent definitions
.rstack/skills/     custom skills
.rstack/plugins/    custom or copied plugin packs
.rstack/prompts/    custom prompts

Then validate: npx rstack-agents validate

Profiles guide routing, budget, dashboard visibility, and project-local configuration. The npm package still ships the full catalog so offline/project-local routing works. The next product step is a pack installer that physically copies only selected packs into .rstack/ for stricter enterprise footprints.

---

Agent identity and standby automation

File	Purpose
SOUL.md	Governance identity — orchestrator/builder/validator roles, evidence rules, profile awareness
HEARTBEAT.md	Optional periodic checks — pending approvals, budget burn, stalled tasks, validation retries
CLAUDE.md	Claude Code bootstrap — asset paths, slash commands, optional hooks
AGENTS.md	Codex/universal bootstrap — same rules plus skill routing and Node bridge

init scaffolds these from templates/bootstrap/ when missing. Canonical templates live in the package at node_modules/rstack-agents/templates/bootstrap/.

Hooks (optional, on standby)

RStack does not require hooks. Enable only what you want:

Hook	What it does	How to enable
Claude SessionStart	Auto-launch Business Hub + inject RStack context	Merge .claude/rstack-hooks.json into .claude/settings.json
Claude UserPromptSubmit	Inject RStack context packet (rstack-agents context) — run + stage + blockers + orchestrator pointer	Written by init --framework claude-code
Claude PreToolUse	Enforcement guard — destructive gate + validator sandbox at tool-call time	Written by init --framework claude-code; snippet in docs/integrations/claude-code.md
Claude PostToolUse / PostToolUseFailure / SubagentStart / SubagentStop / PreCompact / Stop / SessionEnd	Observability writer (rstack-agents observe) — tool results, delegated subagents, failures, compaction, session end into the run ledger	Written by init --framework claude-code
Claude Notification	Route host notifications to your channels (rstack-agents notify-hook)	Written by init --framework claude-code
Claude statusLine	Live RStack status bar (rstack-agents statusline) — run + stage, approvals, open decisions	Written by init --framework claude-code (top-level statusLine key)
Pi lifecycle	Tool gating, stage events, contract enforcement	Automatic when using Pi extension
HEARTBEAT.md	Periodic approval/budget/stall checks	Wire into your harness cron or idle trigger

Disable hub auto-launch:

export RSTACK_NO_BUSINESS_HUB=1   # skip hub spawn
export RSTACK_NO_BROWSER=1        # hub may start but no browser tab
export RSTACK_BUSINESS_PORT=3008  # change port

---

Upgrade path

Start small and expand as requirements grow:

lean-mvp  →  business-flex  →  enterprise-webapp

Stage	When	Action
lean-mvp	Prototypes, internal tools	init --profile lean-mvp — lower budgets, fewer domains
business-flex	Client/product delivery	Add domains/plugins in rstack.config.json, raise budget in budget.json
enterprise-webapp	Compliance-heavy web apps	init --profile enterprise-webapp or enable security/compliance plugins

Upgrade steps (no reinstall required):

1. Edit .rstack/rstack.config.json — add enabled_domains, enabled_plugins, dashboard_pages
2. npx rstack-agents add plugin <name> — copy needed plugin packs locally
3. Adjust .rstack/budget.json — raise thresholds as team size and scope grow
4. npx rstack-agents validate — refresh registry after changes

---

Start your first governed run

From the host AI framework session:

sdlc_start(goal="Upgrade this app, add required tests, improve docs, and run a security review")
sdlc_clarify()
sdlc_plan()

Approve gates, then build and validate:

sdlc_approve(artifact="plan.md", status="APPROVED")
sdlc_approve(artifact="requirements.json", status="APPROVED")
sdlc_approve(artifact="architecture.md", status="APPROVED")
sdlc_build_next()
sdlc_validate()

---

What init creates

your-project/
├── CLAUDE.md or AGENTS.md   # framework bootstrap (if missing)
├── SOUL.md                  # governance identity (if missing)
├── HEARTBEAT.md             # standby automation guide (if missing)
├── .rstack/
│   ├── rstack.config.json   # active profile, enabled domains/plugins, dashboard pages
│   ├── budget.json          # run/daily/monthly budget, warnings, approval thresholds
│   ├── runs/                # every governed run lands here
│   ├── registry/            # agents, skills, plugins, routing metadata
│   └── policy.json          # optional approval policy you control
└── framework glue           # e.g. .claude/rstack-sdlc.md or Operator template

Every run records its manifest, plan, tasks, approvals, evidence, events, stage artifacts, builder contracts, validator contracts, and metrics under .rstack/runs/<run-id>/.

---

Builder and validator sandbox model

RStack uses scoped task packets instead of giving every worker the whole project and whole catalog.

Role	Tools	Must write	Rule
Orchestrator	planning/status tools	plan.md, tasks.json, specs	Routes work; does not directly implement
Builder	read, bash, edit, write, grep, find, ls	builder.json	Changes only task-scoped files; runs checks before claiming done
Validator	read, grep, find, ls	validation.json	Read-only review; no mutation

Builder contract:

{
  "task_id": "003-architecture",
  "agent": "builder",
  "status": "PASS|FAIL|BLOCKED|DONE_WITH_CONCERNS",
  "summary": "",
  "files_modified": [],
  "tests_run": [],
  "risks": [],
  "next_steps": []
}

Contract v2 can also capture backend visibility:

{
  "execution": { "tools_used": [], "events": [], "artifacts_written": [] },
  "cost": { "currency": "USD", "estimated_usd": 1.5, "actual_usd": 1.2 },
  "context": { "profile": "business-flex", "workflow": "production-business-sdlc" },
  "routing": { "selected_by": "profile-domain-stage-affinity", "explanation": [] }
}

Validator contract:

{
  "task_id": "003-architecture",
  "validator": "rstack-validator",
  "status": "PASS|FAIL",
  "checks": [],
  "issues": [],
  "retry_recommendation": "none|retry_builder|ask_user|block"
}

---

Business Hub — live observability on :3008

npx rstack-agents hub

The dashboard derives everything from real .rstack files — no fake demo state and no telemetry leaving your machine.

Page	What you get
Command Center	Portfolio status, attention signals, stage health, live activity
Business Flex	Active profiles, enabled domains, budget guardrails, routing proof
Studio / Studio 3D	Agent workspace with live stage status and clickable agent panels
Projects & Runs	Every run and its actual deliverables
Run Analytics	Stage timing, Gantt, trend rows
Agent Work	Builder/validator contracts and evidence
Approvals / Alerts	Human gates, guardrails, spend/stall signals
Traceability	Requirement → stage → task → evidence chains

---

CLI reference

Command	Purpose
rstack-agents init --profile business-flex	Set up profile, budget, bootstrap files, framework glue, and Business Hub registry (--fresh archives prior .rstack/ state and starts clean)
rstack-agents doctor [--framework <x>]	Verify setup and prove enforcement is live (env, config, framework wiring, guard self-test, hub health); prints a fix per FAIL, --json for CI
rstack-agents list agents|skills|plugins	Browse the packaged catalog
rstack-agents add plugin <name>	Copy a packaged plugin into .rstack/plugins/
rstack-agents validate	Validate packaged agent definitions — frontmatter, duplicate names, hook paths
rstack-agents hub	Ensure the Business Hub is running on :3008 and open it
rstack-agents guard	Enforcement hook: classify one pending tool call, exit 0 allow / exit 2 block (destructive gate + validator sandbox)
rstack-agents observe	Observability hook: append a normalized event (tool result, subagent, compaction, session) to the run ledger — never blocks, exit 0
rstack-agents context	Context hook: emit the RStack packet (run + stage + blockers + orchestrator pointer) for UserPromptSubmit/SessionStart — never blocks, exit 0
rstack-agents notify-hook	Notification hook: route a host notification to configured channels — never blocks, exit 0
rstack-agents statusline	Claude Code statusLine command: print ONE live status-bar line (run + stage, ✔approved/⧗pending approvals, ◇open decisions) — display-only, exit 0
rstack-agents notify --test	Test Slack/Teams/Discord/Telegram/WhatsApp notifications
rstack-agents inventory	Generate a backend control-plane registry report
rstack-agents adopt	Adopt an existing codebase — harvest evidence into a resumable pipeline run (--dry-run plans without writing)
rstack-agents decisions	List, add, resolve, or waive run-level Decision Queue items
rstack-agents dor	Run the Definition-of-Ready gate for a run and target stage
rstack-agents pipeline status	Show pipeline status for the latest or selected run, with one recommended next action
rstack-agents pipeline run	Advance the run from current state: skip DONE work, re-enter retryable tasks, stop at human gates
rstack-agents pipeline loop	Bounded goal loop: advance, evaluate the goal, rerun recommended stages until PASS, a human gate, or a spent bound
rstack-business --port 3008 --project .	Run the dashboard server directly
rstack-observer	Deprecated alias — opens the same Business Hub

Pipeline command flags and exit codes: docs/mintlify/reference/pipeline.mdx.

---

Known limitations and roadmap

Shipped in 1.9 / 2.0

The loop-engineering program that earlier READMEs listed as planned has shipped: the harness ↔ loop-runner bridge, resume-aware pipeline state and pipeline run, deterministic retry plus the stage-specific validator registry, the bounded goal loop (pipeline loop), and persisted per-stage cost/token observability. The authoritative reference for all of it — run state, contracts, guardrails, checkpoints, metrics — is docs/HARNESS.md.

Current limitations

• Actual token/cost capture: per-stage cost and token totals persist from builder contracts at validate time; provider-level usage still needs host-side reporting or provider adapters.
• Physical pack pruning: profiles narrow routing today; a future pack installer should reduce project-local agent/plugin footprint.
• MCP/A2A: .rstack is adapter-friendly, but a native MCP server is still a future slice — held deliberately pending a decision on scope (#374).

Roadmap (contributions welcome)

Feature	Ref
Pack installer — physically copy only selected packs into .rstack/	future
End-to-end live-test matrix per harness — systematic live verification beyond Pi's automated CI coverage	#392
Native MCP server — expose the 18 sdlc_* tools to Cursor, Codex, and other MCP clients	#374

Contributions are welcome. Read CONTRIBUTING.md for branching rules, CI requirements, IP policy, and CodeRabbit guidelines before opening a PR.

---

Documentation

Start here: docs/SETUP.md — the single-page setup & usage guide covering every harness (install → wiring → running a governed pipeline → approvals → dashboard → CLI reference → env vars → troubleshooting).

Bootstrap templates

Canonical copies in templates/bootstrap/:

• SOUL.md — governance identity
• HEARTBEAT.md — standby automation
• CLAUDE.md — Claude Code bootstrap
• AGENTS.md — Codex/universal bootstrap
• GEMINI.md — Gemini CLI pointer

Mintlify docs

Live site: sdlc-rstack.mintlify.site — the full docs, browsable and searchable. Source lives in docs/mintlify:

• Quickstart
• Install your framework
• Business Flex Profiles
• Builder & Validator Sandbox
• Configuration reference
• Business Hub overview
• AI SDLC Trends & Loopholes

Ask the codebase

DeepWiki — an AI-generated, conversational wiki over this repo. Useful for tracing how a specific mechanism works across files without reading the whole harness yourself.

Harness and integrations

• Harness contract — stages, contracts, evidence, guardrails
• Custom integration — Node bridge and state contract

Research material: research/. Architecture decisions: rfcs/.

---

Development

git clone https://github.com/richard-devbot/SDLC-rstack.git
cd SDLC-rstack
npm install
npm test
npm run lint
npm run validate

Latest verified branch state:

npm test          # 2010 pass, 0 fail
npm run lint      # pass, 0 warnings
npm run validate  # All 196 agents passed validation
npm pack --dry-run  # package includes templates/bootstrap/

License

MIT © Richardson Gunde