RStack SDLC

A governed AI-SDLC operating layer for any coding framework.

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.

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

Quick start

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.

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

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, 156+ 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-hub-hook.json` into `.claude/settings.json`
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
`rstack-agents init --fresh`	Archive prior `.rstack/` state and start clean
`rstack-agents hub`	Start/open the dashboard
`rstack-agents list agents\|skills\|plugins`	Browse packaged catalog
`rstack-agents add plugin <name>`	Copy a packaged plugin into `.rstack/plugins/`
`rstack-agents notify --test`	Test Slack/Teams/Discord/Telegram/WhatsApp notifications
`rstack-agents validate`	Validate packaged and local agent definitions
`rstack-business --port 3008 --project .`	Run the dashboard directly

Known limitations and roadmap

Actual token/cost capture: host frameworks execute model calls, so real usage 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.
Validator enforcement: validator tool policy is encoded in RStack packets, but strict enforcement depends on the host sandbox.
Open-source adaptation: learn from OSS agent frameworks, but preserve licenses and validate contracts before importing anything.
MCP/A2A: .rstack is adapter-friendly, but a native MCP/A2A server is still a future slice.

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 -- --runInBand   # 111+ pass
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 175 Commits
.github		.github
agents		agents
bin		bin
docs		docs
extensions		extensions
plugins		plugins
prompts		prompts
research		research
rfcs		rfcs
scripts		scripts
skills		skills
specs		specs
src		src
templates/bootstrap		templates/bootstrap
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

RStack SDLC

Table of contents

Quick start

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

Documentation

Bootstrap templates

Mintlify docs

Harness and integrations

Development

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

RStack SDLC

Table of contents

Quick start

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

Documentation

Bootstrap templates

Mintlify docs

Harness and integrations

Development

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages