RStack SDLC

A governed AI-SDLC operating layer for AI coding harnesses.
Since 2026 · MIT · richard-devbot/SDLC-rstack

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 runtime enforcement on Pi and Operator (live tool-call gating), and on Claude Code via the rstack-agents guard PreToolUse hook (installed by init). 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).

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

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.

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 15 `sdlc_*` tools, lifecycle hooks, tool gating, auto-launch dashboard
Claude Code	Usage guide, optional SessionStart hook, slash commands via plugin
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, 72 plugins), but you configure only what your project needs.

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

Current package limitation

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 on session start	Merge `.claude/rstack-hooks.json` into `.claude/settings.json`
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`
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):

Edit .rstack/rstack.config.json — add enabled_domains, enabled_plugins, dashboard_pages
npx rstack-agents add plugin <name> — copy needed plugin packs locally
Adjust .rstack/budget.json — raise thresholds as team size and scope grow
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 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.
Runtime enforcement tiers: live tool-call gating runs on Pi and Operator; Claude Code and other harnesses get contracts, state, and validate-time checks until the rstack-agents guard hook ships (#227).
MCP/A2A: .rstack is adapter-friendly, but a native MCP/A2A server is still a future slice.

Roadmap (contributions welcome)

Feature	Ref
Parallel execution enforcement — wire benchmarked data-independent stage groups into the pipeline runner	#208
Pack installer — physically copy only selected packs into `.rstack/`	future
RStack Spec v1alpha1 — JSON schemas + conformance examples	#71
Stage-blanket approvals — `required_stage_approvals` + `approvals.every_stage` per-stage human gates	#228
Exposure CLI verbs — `pipeline rollback`, checkpoint status, config validate, approvals audit, memory inspect	#229

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

Documentation

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

Full docs in docs/mintlify:

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          # 756 pass, 0 fail
npm run lint      # pass
npm run validate  # All 196 agents passed validation
npm pack --dry-run  # package includes templates/bootstrap/

Name		Name	Last commit message	Last commit date
Latest commit History 465 Commits
.github		.github
agents		agents
assets		assets
bin		bin
docs		docs
extensions		extensions
plugins		plugins
prompts		prompts
research		research
rfcs		rfcs
scripts		scripts
skills		skills
src		src
templates/bootstrap		templates/bootstrap
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
eslint.config.js		eslint.config.js
operator.json		operator.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

RStack SDLC

Meet the studio

Table of contents

Quick start

Govern an existing codebase

Choose your framework

Configure your team

1. Pick a profile

2. Narrow domains and plugins

3. Add plugins locally

4. Browse the catalog

5. Project-local overrides

Agent identity and standby automation

Hooks (optional, on standby)

Upgrade path

Start your first governed run

What init creates

Builder and validator sandbox model

Business Hub — live observability on :3008

CLI reference

Known limitations and roadmap

Shipped in 1.9 / 2.0

Current limitations

Roadmap (contributions welcome)

Documentation

Bootstrap templates

Mintlify docs

Harness and integrations

Development

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages