diff --git a/docs/mintlify/architecture.mdx b/docs/mintlify/architecture.mdx index 43971cd..1b376eb 100644 --- a/docs/mintlify/architecture.mdx +++ b/docs/mintlify/architecture.mdx @@ -30,7 +30,7 @@ The system has nine distinct layers: | **Harness Core** | Enforces contracts, validates evidence, manages run state and notifications (7 modules) | | **Pipeline Engine** | Routes work through 15 canonical SDLC stages, each producing a typed artifact | | **Governance + Security + Memory** | Approval gates, guardrails, secret scanning, injection detection, episodic memory | -| **Observability** | Live dashboard server (port 3005), run reporter, 19 tracked event types | +| **Observability** | Live dashboard server (port 3008), run reporter, 19 tracked event types | | **Notifications & Handoff** | Slack/Discord/Teams webhooks; structured agent-to-agent context relay via `handoff.md` | | **Asset Registry & Run State** | 196 agents ยท 156 skills ยท 72 plugins; resumable run state with checkpoint/rollback | @@ -563,7 +563,7 @@ RStack ships a built-in enterprise observability stack. Three components work to ### `sdlc_dashboard` โ€” Live HTML dashboard -Generates `dashboard.html` under the run directory and starts a local HTTP server (default port `3005`): +Generates `dashboard.html` under the run directory and starts a local HTTP server (default port `3008`): ```text sdlc_dashboard() diff --git a/docs/mintlify/concepts/plugins-and-skills.mdx b/docs/mintlify/concepts/plugins-and-skills.mdx index c537702..8d3b3e3 100644 --- a/docs/mintlify/concepts/plugins-and-skills.mdx +++ b/docs/mintlify/concepts/plugins-and-skills.mdx @@ -133,14 +133,13 @@ Prompts are command-style workflow templates. They give the agent a scripted app **Count:** 36 prompts included -```bash -rstack-agents list prompts -# Example: -# api-design.md -# database-migration.md -# release-checklist.md -# security-review.md -# ... +```text +prompts/ + api-design.md + database-migration.md + release-checklist.md + security-review.md + ... ``` Prompts are exposed as slash commands in Pi: diff --git a/docs/mintlify/docs.json b/docs/mintlify/docs.json index ae66ac5..61367d2 100644 --- a/docs/mintlify/docs.json +++ b/docs/mintlify/docs.json @@ -23,11 +23,20 @@ { "group": "Getting Started", "pages": [ + "getting-started/install-your-framework", "getting-started/installation", "getting-started/your-first-run", "getting-started/governance-model" ] }, + { + "group": "Business Hub", + "pages": [ + "reference/business-hub", + "reference/approvals", + "reference/webhooks" + ] + }, { "group": "Core Concepts", "pages": [ @@ -73,6 +82,7 @@ "pages": [ "reference/cli", "reference/pi-tools", + "reference/observability", "reference/configuration", "reference/protected-actions" ] diff --git a/docs/mintlify/getting-started/governance-model.mdx b/docs/mintlify/getting-started/governance-model.mdx index 8529449..c2435b1 100644 --- a/docs/mintlify/getting-started/governance-model.mdx +++ b/docs/mintlify/getting-started/governance-model.mdx @@ -39,7 +39,15 @@ sdlc_approve(artifact="release-readiness.json", status="APPROVED") sdlc_approve(artifact="destructive-action", status="APPROVED") ``` -Approvals are written to `.rstack/runs//approvals.json` and referenced in traceability. +Approvals are written to `.rstack/runs//approvals.json` and referenced in traceability. The recorded approver is the resolved identity (git config or `RSTACK_USER`), not a placeholder. + +### Enforce policy & manager roles + +For team use you can require specific approvals in **every** mode (including +express) and restrict who may approve, via `.rstack/policy.json` plus the +`RSTACK_APPROVAL_TOKEN` / `RSTACK_MANAGER_USERS` settings. The moment a gate +blocks, every configured notification channel is paged. See +[Approvals & Policy](/reference/approvals) for the full model. ## Protected actions diff --git a/docs/mintlify/getting-started/install-your-framework.mdx b/docs/mintlify/getting-started/install-your-framework.mdx new file mode 100644 index 0000000..7c597e3 --- /dev/null +++ b/docs/mintlify/getting-started/install-your-framework.mdx @@ -0,0 +1,178 @@ +--- +title: "Install your framework" +description: "Set up your AI coding framework first, then add RStack to it." +--- + +RStack is a plugin, not a standalone app โ€” it runs inside an AI coding +framework. This page gets you from nothing to a framework with RStack installed, +whichever tool you use. Every path ends the same way: + +```bash +cd your-project +npm install rstack-agents +npx rstack-agents init # auto-detects your framework +``` + + + **Prerequisite for all frameworks:** Node.js 18 or newer (`node --version`). + RStack and its dashboard run on Node. + + +## How well does each framework integrate? + +| Framework | Integration | What you get | +|---|---|---| +| **Pi** | ๐ŸŸข Native adapter | All 15 `sdlc_*` tools, lifecycle hooks, gating, auto-launch dashboard | +| **Claude Code** | ๐ŸŸข First-class | `init` writes a usage guide + a SessionStart hook; plugin commands | +| **Operator** | ๐ŸŸข First-class | Python adapter bridges to the same harness; auto-launch dashboard | +| **Codex CLI** | ๐ŸŸก Asset-based | RStack agents/skills as context via `AGENTS.md`; no native tool gating | +| **Gemini CLI** | ๐ŸŸก Asset-based | RStack agents/skills as context via `GEMINI.md`; no native tool gating | +| **Any other harness** | ๐ŸŸก Universal | The `.rstack/` state contract + a Node bridge any tool can call | + +๐ŸŸข = full governed harness. ๐ŸŸก = RStack guides the agent via shared context; +the dashboard, state, and CLI still work, but tool-level gating depends on the host. + +--- + +## Pi + +Pi is RStack's native home โ€” the deepest integration. + + + + Follow the Pi install guide for your platform, then confirm: + ```bash + pi --version + ``` + + + ```bash + cd your-project + npm install rstack-agents + npx rstack-agents init --framework pi + ``` + Pi auto-loads the RStack extension from the package โ€” no manual wiring. + + + ```text + sdlc_start(goal="...") + ``` + + + +Details: [Pi adapter](/adapters/pi). + +--- + +## Claude Code + + + + Install the Claude Code CLI or IDE extension, then confirm with `claude --version`. + + + ```bash + cd your-project + npm install rstack-agents + npx rstack-agents init --framework claude-code + ``` + This writes `.claude/rstack-sdlc.md` (a usage guide) and a **SessionStart + hook** so the Business Hub opens every session. If you already have a + `.claude/settings.json`, RStack leaves a mergeable snippet instead of + overwriting it. + + + ```text + /plugin install sdlc-automation + ``` + Then drive the pipeline with `/sdlc-start`, `/sdlc-status`, `/sdlc-resume`. + + + +Details: [Claude Code adapter](/adapters/claude-code). + +--- + +## Operator + + + + Operator is a Python harness. RStack's Operator adapter shells out to a + Node bridge, so you need `node` and `npx` on `PATH`. + + + ```bash + cd your-project + npm install rstack-agents + npx rstack-agents init --framework operator + ``` + `init` writes `rstack-operator.example.json`. + + + Merge the `extensions.list` entry from `rstack-operator.example.json` into + your Operator `settings.json`. The Business Hub auto-launches when the + extension loads. + + + +Details: [Operator adapter](/adapters/universal). + +--- + +## Codex CLI + +Codex integrates through shared context files (no native tool binding yet). + + + + Install per its docs and confirm it runs in your project. + + + ```bash + cd your-project + npm install rstack-agents + npx rstack-agents init --framework custom + ``` + Then point Codex at the RStack agents via `AGENTS.md`. See the + [Codex adapter](/adapters/codex) for the exact `AGENTS.md` block. + + + The Business Hub (`npx rstack-agents hub`) and `.rstack/` state work the + same as any framework. + + + +--- + +## Gemini CLI + +Same asset-based pattern as Codex, via `GEMINI.md`. + + + + Install per its docs. + + + ```bash + cd your-project + npm install rstack-agents + npx rstack-agents init --framework custom + ``` + Add the RStack instructions to `GEMINI.md` โ€” see the + [Gemini adapter](/adapters/gemini). + + + +--- + +## Any other framework + +If your harness can read a project directory, it can use RStack. Install with +`--framework custom`, then either feed it the RStack agent context or have it +call the Node bridge per tool. Full contract: +[Universal / custom adapter](/adapters/universal). + + + Whatever framework you chose, your next stop is the same: + [Your first run](/getting-started/your-first-run). + diff --git a/docs/mintlify/getting-started/installation.mdx b/docs/mintlify/getting-started/installation.mdx index 373b554..ca9e7a1 100644 --- a/docs/mintlify/getting-started/installation.mdx +++ b/docs/mintlify/getting-started/installation.mdx @@ -3,13 +3,33 @@ title: "Installation" description: "All supported installation methods for RStack SDLC." --- -RStack can be installed in any AI coding environment. Choose the method that matches your runtime. +RStack can be installed in any AI coding environment. ## Requirements - Node.js >= 18.0.0 - npm >= 9.0.0 +## Recommended: one command for any framework + +```bash +cd your-project +npm install rstack-agents +npx rstack-agents init # auto-detects pi | claude-code | operator | custom +``` + +`init` sets up `.rstack/`, registers the project with the Business Hub, writes +the framework-specific glue, and prints next steps โ€” idempotent and +non-destructive. New to your AI framework itself? See +[Install your framework](/getting-started/install-your-framework) for the +per-tool setup, then run the command above. + + + The sections below are the **manual / asset-based** paths. You only need them + for frameworks without a native adapter (Codex, Gemini, universal) or if you + prefer wiring assets yourself. + + ## Pi โ€” Native adapter (full-featured) The native Pi adapter gives RStack lifecycle hooks, tool gating, session events, and the full governed harness. @@ -130,8 +150,8 @@ rstack-agents validate Expected output: ``` -196 agents found -156 skills found -72 plugins found -โœ“ Validation passed +$ rstack-agents validate +[rstack] All 196 agents passed validation. ``` + +The catalog ships **196 agents, 156 skills, 72 plugins, 36 prompts**. diff --git a/docs/mintlify/introduction.mdx b/docs/mintlify/introduction.mdx index 40a94e2..8bfcb93 100644 --- a/docs/mintlify/introduction.mdx +++ b/docs/mintlify/introduction.mdx @@ -3,12 +3,6 @@ title: "RStack SDLC" description: "A framework-independent, governed AI software-delivery harness for coding agents." --- -RStack SDLC - ## What is RStack? **RStack SDLC** is a portable AI-SDLC framework developed by Richardson Gunde. It gives AI coding agents a repeatable, governed software delivery lifecycle instead of ad-hoc prompting. @@ -24,13 +18,13 @@ description: "A framework-independent, governed AI software-delivery harness for Understand the Orchestrator โ†’ Builder โ†’ Validator model. - Explore all 14 pipeline agents from environment to cost estimation. + Explore all 15 pipeline agents from environment to cost estimation. - - Install RStack in Pi, Claude Code, Codex, Gemini, and more. + + Set up Pi, Claude Code, Codex, Gemini CLI, or Operator โ€” then add RStack. - - Live dashboard, CLI trace, and multi-channel webhook notifications. + + Live multi-project dashboard, Studio 3D, approvals, and webhooks on :3008. @@ -47,7 +41,7 @@ RStack enforces this lifecycle so AI agents behave like a productive software te | Layer | Contents | |---|---| | `agents/core/` | Orchestrator, builder, and validator team contracts | -| `agents/sdlc/` | 14 full-lifecycle pipeline agents | +| `agents/sdlc/` | 15 full-lifecycle pipeline agents (stages 00โ€“14) | | `agents/specialists/` | Backend, frontend, devops, QA, security, data, docs specialists | | `skills/` | 156 reusable workflow instructions | | `prompts/` | 36 prompt templates and command-style workflows | diff --git a/docs/mintlify/quickstart.mdx b/docs/mintlify/quickstart.mdx index d6b7798..c19991c 100644 --- a/docs/mintlify/quickstart.mdx +++ b/docs/mintlify/quickstart.mdx @@ -1,117 +1,93 @@ --- title: "Quickstart" -description: "Get RStack SDLC running in under 5 minutes." +description: "From zero to a governed AI run in under 5 minutes." --- -## Install in Pi (recommended) - -Pi is the native runtime for RStack and gives you the full governed harness with lifecycle hooks. +RStack plugs into the AI coding framework you already use. The fastest path is +the same for everyone: - + ```bash - pi install npm:rstack-agents + cd your-project + npm install rstack-agents ``` - Or from a local checkout: + + ```bash - pi install /path/to/SDLC-rstack + npx rstack-agents init ``` - - - ```text - Use RStack to build a production-ready todo app with auth, tests, docs, and release readiness. + `init` auto-detects your framework (Pi, Claude Code, Operator, or custom), + creates the `.rstack/` state directory, registers the project with the + Business Hub, writes any framework-specific glue, and prints your next + steps. Running it twice is safe โ€” it never overwrites your files. + + Force a specific framework with `--framework`: + ```bash + npx rstack-agents init --framework pi # pi | claude-code | operator | custom ``` - - RStack guides you through each phase: + ```text - sdlc_orchestrate(goal="Build a production-ready todo app...") - sdlc_start(goal="Build a production-ready todo app...") + sdlc_start(goal="Build a checkout flow with Stripe, tests, and release readiness") sdlc_clarify() sdlc_plan() ``` - + ```text sdlc_approve(artifact="plan.md", status="APPROVED") sdlc_approve(artifact="requirements.json", status="APPROVED") sdlc_approve(artifact="architecture.md", status="APPROVED") - ``` - - - ```text sdlc_build_next() sdlc_validate() - sdlc_status() ``` - - -## Try without installing - -Run RStack once without a permanent install: - -```bash -pi -e /path/to/SDLC-rstack/extensions/rstack-sdlc.ts -``` - -## Install in Claude Code - - - - ```bash - export RSTACK_HOME=/path/to/SDLC-rstack - ``` - - + + The dashboard opens automatically when your session starts. Bring it up + any time from any framework: ```bash - mkdir -p .claude/agents/rstack .claude/commands/rstack .rstack/vendor/rstack - cp -R "$RSTACK_HOME/agents" .rstack/vendor/rstack/ - cp -R "$RSTACK_HOME/skills" .rstack/vendor/rstack/ - cp -R "$RSTACK_HOME/plugins" .rstack/vendor/rstack/ - cp -R "$RSTACK_HOME/prompts" .rstack/vendor/rstack/ - cp -R "$RSTACK_HOME/agents"/* .claude/agents/rstack/ - ``` - - - ```markdown - # RStack SDLC - Use RStack SDLC from `.rstack/vendor/rstack`. - Start with `.rstack/vendor/rstack/agents/core/orchestrator.md`. - Write all run state under `.rstack/runs//`. - Require specs, approvals, traceability, builder.json, and validation.json. - Never claim DONE without evidence. + npx rstack-agents hub ``` + Open [http://localhost:3008](http://localhost:3008) โ€” runs, the Studio + live agent view, approvals, and traceability. - - See the [Adapters](/adapters/pi) section for installation guides for Codex CLI, Gemini CLI, Qwen Code, and universal asset-only mode. - + + New to your AI framework too? Start with + [Install your framework](/getting-started/install-your-framework) โ€” it covers + installing Pi, Claude Code, Codex CLI, Gemini CLI, and Operator first, then + adding RStack. + -## What happens after install - -RStack creates a `.rstack/` directory in your project with: +## What `init` created ```text -.rstack/ - memory/ - learnings.jsonl # Accumulated cross-run learnings - registry/ - registry.json # Full asset manifest - agents.json - skills.json - plugins.json - routing.json # Pipeline routing map - runs/ - / - manifest.json - plan.md - tasks.json - approvals.json - traceability.json - specs/ # Generated spec artifacts - tasks/ # Per-task builder + validator contracts +your-project/ +โ”œโ”€โ”€ .rstack/ +โ”‚ โ”œโ”€โ”€ runs/ # every governed run lands here +โ”‚ โ”œโ”€โ”€ registry/ # agent / skill / plugin catalog +โ”‚ โ””โ”€โ”€ policy.json # (optional) approval policy you control +โ””โ”€โ”€ .claude/rstack-sdlc.md # (claude-code only) usage guide + session hook ``` -Every run is inspectable, resumable, and auditable. +Every run is inspectable, resumable, and auditable. See +[Your first run](/getting-started/your-first-run) for the full walkthrough. + +## Pick your path + + + + Pi, Claude Code, Codex, Gemini CLI, Operator โ€” step by step. + + + Clarify โ†’ plan โ†’ approve โ†’ build โ†’ validate, explained. + + + The live dashboard, Studio 3D, and team views. + + + Slack, Teams, Discord, Telegram, WhatsApp. + + diff --git a/docs/mintlify/reference/approvals.mdx b/docs/mintlify/reference/approvals.mdx new file mode 100644 index 0000000..4fa1471 --- /dev/null +++ b/docs/mintlify/reference/approvals.mdx @@ -0,0 +1,78 @@ +--- +title: "Approvals & Policy" +description: "Human-in-the-loop gates, manager allow-lists, and the approval token." +--- + +No change ships without sign-off. RStack gates planning, requirements, and +architecture by default, and lets you enforce stricter, role-based policy. + +## How approvals work + +When a task reaches a gate, the run blocks and records an `approval_gate_blocked` +event. A human resolves it: + +```text +sdlc_approve(artifact="architecture.md", status="APPROVED") +``` + +The approver is recorded as the resolved identity (git config or `RSTACK_USER`) +โ€” not a generic placeholder. Resolving from the Business Hub is also possible +(see [the token](#dashboard-approval-token) below). + +## Enforce policy โ€” `.rstack/policy.json` + +Make selected stages require approval **in every mode**, including express runs: + +```json +{ + "required_approvals": { + "008-release-readiness": ["release-readiness.json"] + }, + "enforce_in_express": true, + "managers": ["maya@acme.com", "lena@acme.com"] +} +``` + +- **`required_approvals`** โ€” task id โ†’ artifacts that must be approved before + that task can run. Enforced in interactive **and** express mode. +- **`enforce_in_express`** โ€” also apply the default interactive gates to + express runs. +- **`managers`** โ€” only these people may resolve approvals (see below). + +## Manager allow-list + +When a manager list is configured (via `policy.json` `managers[]` or the +`RSTACK_MANAGER_USERS` env var, comma-separated), only those identities can +resolve a gate. Anyone else is rejected. With no list configured, any +identified user may approve. + +```bash +export RSTACK_MANAGER_USERS="maya@acme.com,lena@acme.com" +``` + +## Dashboard approval token + +Approving from the browser requires a signed token so a manager's identity +can't be spoofed from an unauthenticated request: + +```bash +export RSTACK_APPROVAL_TOKEN="a-long-random-secret" +``` + +- With the token set, the dashboard sends it as a header; approvals also + require a same-origin request and `Content-Type: application/json`. +- **Without the token set, browser approvals are disabled** (the secure + default) โ€” approve via `sdlc_approve` instead. +- Every dashboard approval records audit-proof actor evidence, not just a name. + + + The CLI path (`sdlc_approve`) always enforces the manager allow-list. The + token specifically protects the **dashboard** endpoint from spoofed requests. + + +## Everyone gets paged when a gate blocks + +A blocked gate fires a notification to every configured channel +([webhooks](/reference/webhooks)) and pops a browser notification in the hub โ€” +so the manager doesn't have to be watching the dashboard to know work is +waiting. diff --git a/docs/mintlify/reference/business-hub.mdx b/docs/mintlify/reference/business-hub.mdx new file mode 100644 index 0000000..adefea8 --- /dev/null +++ b/docs/mintlify/reference/business-hub.mdx @@ -0,0 +1,88 @@ +--- +title: "Business Hub" +description: "The live multi-project observability dashboard on :3008." +--- + +The **Business Hub** is RStack's company dashboard. It aggregates every run +across every project on the machine and shows them live โ€” no database, no +telemetry leaves your machine; everything is derived from the `.rstack/` files. + +## Launch it + +The hub opens automatically when a session starts (Pi, the Claude Code +SessionStart hook, and Operator all launch it). Bring it up manually from any +framework: + +```bash +npx rstack-agents hub # health-check :3008, start if down, open browser +``` + +Or run the server directly: + +```bash +rstack-business --port 3008 --project . +``` + + + Default port is **3008** (override with `RSTACK_BUSINESS_PORT`). Disable + auto-launch with `RSTACK_NO_BUSINESS_HUB=1`. The legacy `rstack-observer` + command is a compatibility alias that opens the same hub. + + +## Pages + + + + A live agent workspace โ€” every stage as a workstation, status as a glowing + state. The 3D scene (`/studio3d`) lets you click any agent to see what it + worked on, what it shipped, and why it's waiting. + + + Wall-clock Gantt per run, average stage durations, and run-over-run trends. + + + Who is live now, a people directory (runs / approvals / guidance per + person), and a manager rollup per project. + + + Every session. Open a run to read its actual deliverables and evidence. + + + Approve or reject gates from the browser; popups when new gates block. + + + The 15-stage map with live states and requirement โ†’ stage โ†’ task โ†’ evidence + chains. + + + +## Read what the agents produced + +Open any run and the drawer lists its **deliverables** โ€” `requirements.json`, +`architecture.md`, the QA report, security review, release readiness, the plan โ€” +grouped by stage. Click one to read it in the dashboard. The **Evidence** +section lists the validation records beside them. + +The artifact API is strictly sandboxed: the run is located via the known +project roots, the resolved path must stay inside the run directory, only +text artifacts are served, and there's a 512 KB cap. + +## Switch scope & share links + +A project โ†’ run switcher in the top bar scopes every page to the run you care +about and remembers your choice. Links are shareable: `#run=` deep-links +straight to a run (handy in Slack). + +## Multi-project aggregation + +The hub reads a global registry (`~/.rstack/known-projects.json`) that every +`rstack-agents init` and `hub` call updates, so one dashboard shows runs from +all your projects. Many people can point the same hub (or the same Slack bot) +at it. + + + **Honest limitation:** LLM token usage and real cost are not captured โ€” the + host framework executes the model calls, so the harness never sees usage. + Cost shows `$0` unless a builder reports it in its contract. Host-side usage + instrumentation is on the roadmap. + diff --git a/docs/mintlify/reference/cli.mdx b/docs/mintlify/reference/cli.mdx index 0a253bf..e02ec43 100644 --- a/docs/mintlify/reference/cli.mdx +++ b/docs/mintlify/reference/cli.mdx @@ -1,33 +1,73 @@ --- title: "CLI Reference" -description: "rstack-agents command-line interface โ€” framework-neutral inspection and management." +description: "rstack-agents and the dashboard binaries โ€” framework-neutral." --- ## Overview -The `rstack-agents` CLI is framework-neutral and works in any environment. Use it to inspect assets, validate the registry, and manage plugins โ€” without needing Pi or any other runtime. - -## Installation - -The CLI is included in the npm package: +The `rstack-agents` CLI is framework-neutral and works in any environment. Use +it to set up a project, launch the dashboard, test notifications, inspect +assets, and validate the registry โ€” without needing Pi or any other runtime. ```bash -npm install -g rstack-agents -# or use it from a local checkout: +npm install rstack-agents # in your project +# or run any command via npx without installing: +npx rstack-agents +# from a local checkout: node bin/rstack-agents.js ``` ## Commands +### `init` + +Set up RStack in the current project. Idempotent โ€” never overwrites your files. + +```bash +rstack-agents init # auto-detect the framework +rstack-agents init --framework pi # pi | claude-code | operator | custom +rstack-agents init --project ./apps/web # target a different directory +``` + +Creates `.rstack/`, registers the project with the Business Hub, writes +framework-specific glue, and prints next steps. + +--- + +### `hub` + +Ensure the Business Hub is running on :3008 and open it โ€” the universal +session-start entry point for any framework. + +```bash +rstack-agents hub +rstack-agents hub --no-browser # start/register without opening a tab +rstack-agents hub --project ./apps/web +``` + +--- + +### `notify` + +Inspect configured notification channels, or test them. + +```bash +rstack-agents notify # list configured channels +rstack-agents notify --test # send a test message to every channel +``` + +See [Notifications & Webhooks](/reference/webhooks). + +--- + ### `list` -List available assets by type. +List packaged assets by type. ```bash rstack-agents list agents rstack-agents list skills rstack-agents list plugins -rstack-agents list prompts ``` **Example output:** @@ -41,97 +81,56 @@ $ rstack-agents list agents builder โ†’ Implementation agent with write permissions validator โ†’ Read-only review agent - sdlc/ + sdlc/ (15 stages, 00โ€“14) 00-environment โ†’ Detect tools, produce environment_report.json 01-transcript โ†’ Parse raw input into transcript.json 02-requirements โ†’ Extract requirements with acceptance criteria - 03-documentation โ†’ Generate BRD, FRD, SOW documents - 04-planning โ†’ Sprint plan, milestones, team composition - 05-jira โ†’ Create Jira tickets from requirements - 06-architecture โ†’ System design, API contracts, DB schema - 07-code โ†’ Generate production code scaffolding - 08-testing โ†’ Test plans, unit tests, security tests - 09-deployment โ†’ Dockerfile, CI/CD, deploy scripts - 10-summary โ†’ Executive summary, handoff docs - 11-feedback-loop โ†’ Retrospective, traceability audit - 12-security-threat-model โ†’ STRIDE threat model - 13-compliance-checker โ†’ GDPR/HIPAA/SOC2/PCI-DSS gap analysis + โ€ฆ 14-cost-estimation โ†’ Cloud cost forecast ``` --- -### `validate` - -Validate the full asset registry โ€” checks frontmatter, duplicate names, broken references, and package integrity. - -```bash -rstack-agents validate -``` - -**Example output:** -``` -$ rstack-agents validate - -Validating agents... 196/196 โœ“ -Validating skills... 156/156 โœ“ -Validating plugins... 72/72 โœ“ -Validating prompts... 36/36 โœ“ - -Checking for duplicate names... โœ“ -Checking agent references... โœ“ -Checking plugin manifests... โœ“ - -โœ“ Validation passed โ€” 460 assets, 0 errors -``` - ---- - ### `add plugin` -Add a domain plugin pack to your project. +Copy a packaged domain plugin into your project. ```bash rstack-agents add plugin backend-development -rstack-agents add plugin frontend-design rstack-agents add plugin cloud-infrastructure ``` --- -### `info` +### `validate` -Show detailed information about a specific agent, skill, or plugin. +Validate the packaged agent definitions โ€” frontmatter, duplicate names, broken +references, manifest integrity. ```bash -rstack-agents info agent orchestrator -rstack-agents info skill security-owasp -rstack-agents info plugin backend-development +rstack-agents validate ``` ---- - -## Local development equivalent - -If you have a local checkout and don't want to install globally: +**Example output:** +``` +$ rstack-agents validate +[rstack] All 196 agents passed validation. +``` -```bash -# List agents -node bin/rstack-agents.js list agents +The catalog ships **196 agents, 156 skills, 72 plugins, 36 prompts**. -# Validate registry -node bin/rstack-agents.js validate +## The dashboard binaries -# Add a plugin -node bin/rstack-agents.js add plugin backend-development -``` +| Binary | Purpose | +|---|---| +| `rstack-business` | Run the Business Hub server directly: `rstack-business --port 3008 --project .` | +| `rstack-observer` | Compatibility alias that opens the same Business Hub | +| `rstack-operator-bridge` | Node bridge the Operator (Python) adapter shells out to per tool call | ## npm scripts -The package also exposes these scripts: - ```bash -npm test # Run test suite -npm run validate # Run rstack-agents validate +npm test # run the test suite +npm run validate # rstack-agents validate npm run lint # ESLint src/, bin/, tests/ ``` diff --git a/docs/mintlify/reference/configuration.mdx b/docs/mintlify/reference/configuration.mdx index 0769753..027eaa8 100644 --- a/docs/mintlify/reference/configuration.mdx +++ b/docs/mintlify/reference/configuration.mdx @@ -13,6 +13,39 @@ description: "Environment variables, project overrides, and registry configurati | `RSTACK_LOG_LEVEL` | `info` | Log verbosity: `debug`, `info`, `warn`, `error` | | `RSTACK_MODEL_OPUS` | `claude-opus-4-5` | Model to use for Opus-tier agents (architecture, code, security) | | `RSTACK_MODEL_SONNET` | `claude-sonnet-4-5` | Model to use for Sonnet-tier agents | +| `RSTACK_DEFAULT_MODEL` | โ€” | Model for delegated builder agents | +| `RSTACK_ESCALATED_MODEL` | โ€” | Model used when a task reaches attempt โ‰ฅ 2 | + +### Identity & people + +| Variable | Default | Description | +|---|---|---| +| `RSTACK_USER` | git `user.name` | Who started the run / resolved an approval | +| `RSTACK_USER_EMAIL` | git `user.email` | Email recorded alongside the identity | + +### Business Hub + +| Variable | Default | Description | +|---|---|---| +| `RSTACK_BUSINESS_PORT` | `3008` | Dashboard port | +| `RSTACK_NO_BUSINESS_HUB` | โ€” | Set to `1` to disable dashboard auto-launch | +| `RSTACK_NO_BROWSER` | โ€” | Set to `1` to never open a browser tab | + +### Approvals (see [Approvals & Policy](/reference/approvals)) + +| Variable | Default | Description | +|---|---|---| +| `RSTACK_APPROVAL_TOKEN` | โ€” | Required to approve from the dashboard (prevents spoofing) | +| `RSTACK_MANAGER_USERS` | โ€” | Comma-separated manager allow-list (also settable in `policy.json`) | + +### Notifications (see [Webhooks](/reference/webhooks)) + +| Variable | Description | +|---|---| +| `RSTACK_SLACK_WEBHOOK` | Slack incoming webhook (Teams/Discord URLs auto-routed) | +| `RSTACK_TEAMS_WEBHOOK` / `RSTACK_DISCORD_WEBHOOK` | Teams / Discord webhooks | +| `RSTACK_TELEGRAM_BOT_TOKEN` + `RSTACK_TELEGRAM_CHAT_ID` | Telegram bot | +| `RSTACK_WHATSAPP_TOKEN` + `RSTACK_WHATSAPP_PHONE_ID` + `RSTACK_WHATSAPP_TO` | WhatsApp Cloud API | --- diff --git a/docs/mintlify/reference/observability.mdx b/docs/mintlify/reference/observability.mdx index def9922..02d6753 100644 --- a/docs/mintlify/reference/observability.mdx +++ b/docs/mintlify/reference/observability.mdx @@ -24,7 +24,7 @@ RStack ships a built-in observability stack that gives you real-time visibility ## `sdlc_dashboard` -Generates `dashboard.html` inside the run directory and starts a local HTTP server (default port `3005`) that auto-refreshes every 2 seconds. +Generates `dashboard.html` inside the run directory and starts a local HTTP server (default port `3008`) that auto-refreshes every 2 seconds. ```text sdlc_dashboard() diff --git a/docs/mintlify/reference/pi-tools.mdx b/docs/mintlify/reference/pi-tools.mdx index c983ef9..9063c23 100644 --- a/docs/mintlify/reference/pi-tools.mdx +++ b/docs/mintlify/reference/pi-tools.mdx @@ -253,7 +253,7 @@ The dashboard auto-refreshes every 2 seconds and shows: - **Traceability Explorer** โ€” link to `traceability.json` - **Harness Guardrail Limits** โ€” enforced policy values -Writes `dashboard.html` to `.rstack/runs//dashboard.html` and serves it at `http://localhost:3005` (port configurable). +Writes `dashboard.html` to `.rstack/runs//dashboard.html` and serves it at `http://localhost:3008` (port configurable). --- diff --git a/docs/mintlify/reference/webhooks.mdx b/docs/mintlify/reference/webhooks.mdx new file mode 100644 index 0000000..ca853b9 --- /dev/null +++ b/docs/mintlify/reference/webhooks.mdx @@ -0,0 +1,74 @@ +--- +title: "Notifications & Webhooks" +description: "Send SDLC events to Slack, Teams, Discord, Telegram, and WhatsApp." +--- + +RStack notifies your team where they already are. One event fans out to every +channel you configure; a webhook failure never fails a run. + +## What gets notified + +- Run started (`sdlc_start`) +- Task validated โ€” pass/fail with summary and attempt count +- A rich task execution report โ€” tool calls, guardrail hits, memory actions, checks +- Human approval recorded (`sdlc_approve`) +- **A gate blocking** โ€” the moment work is blocked on an approval, every + channel is paged + +## Configure โ€” environment variables + +| Channel | Variables | +|---|---| +| **Slack** | `RSTACK_SLACK_WEBHOOK` (Teams/Discord URLs are auto-routed too) | +| **Teams** | `RSTACK_TEAMS_WEBHOOK` | +| **Discord** | `RSTACK_DISCORD_WEBHOOK` | +| **Telegram** | `RSTACK_TELEGRAM_BOT_TOKEN` + `RSTACK_TELEGRAM_CHAT_ID` | +| **WhatsApp** | `RSTACK_WHATSAPP_TOKEN` + `RSTACK_WHATSAPP_PHONE_ID` + `RSTACK_WHATSAPP_TO` | + +## Configure โ€” `.rstack/notifications.json` + +```json +{ + "channels": { + "slack": { "webhook": "https://hooks.slack.com/services/..." }, + "teams": { "webhook": "https://yourorg.webhook.office.com/..." }, + "discord": { "webhook": "https://discord.com/api/webhooks/..." }, + "telegram": { "bot_token": "123456:ABC...", "chat_id": "-1001234567890" }, + "whatsapp": { "token": "EAAB...", "phone_number_id": "1055...", "to": "15551234567" } + } +} +``` + +Environment variables win over the file for the same channel. + +## Verify in seconds + +```bash +npx rstack-agents notify # show which channels are configured +npx rstack-agents notify --test # send a test message to every channel +``` + +Per-channel results are printed; exit code is non-zero if any channel fails. + +## Channel notes + +- **Slack** โ€” incoming webhook; native Block Kit payloads. +- **Teams** โ€” incoming webhook (connector); converted to MessageCard. +- **Discord** โ€” webhook; converted to embeds. +- **Telegram** โ€” create a bot with @BotFather, add it to your chat/group, use + the bot token + chat id. Rendered as plain text. +- **WhatsApp** โ€” Meta WhatsApp Business Cloud API: a Meta app with the WhatsApp + product, a system-user token, the sender phone-number id, and the recipient + number in international format (no `+`). + +## For adapter authors + +```js +import { notifyAll, hasConfiguredChannels, formatSlackStageMessage } from 'rstack-agents'; + +if (hasConfiguredChannels({ projectRoot })) { + await notifyAll(formatSlackStageMessage(runId, stageId, 'PASS', { message }), { projectRoot }); +} +``` + +`notifyAll` never throws โ€” it returns `[{ channel, ok, detail }]`. diff --git a/docs/mintlify/sdlc-pipeline/overview.mdx b/docs/mintlify/sdlc-pipeline/overview.mdx index acb836d..0034cce 100644 --- a/docs/mintlify/sdlc-pipeline/overview.mdx +++ b/docs/mintlify/sdlc-pipeline/overview.mdx @@ -1,11 +1,11 @@ --- title: "Pipeline Overview" -description: "The 14-agent SDLC pipeline from environment discovery to cost estimation." +description: "The 15-agent SDLC pipeline from environment discovery to cost estimation." --- ## The complete pipeline -RStack ships 14 SDLC pipeline agents that cover the full software delivery lifecycle: +RStack ships 15 SDLC pipeline agents (stages 00โ€“14) that cover the full software delivery lifecycle: | # | Agent file | Stage | |---|---|---|