From ff92d6c913b6a99aacc4bb890a9c366affcf9d30 Mon Sep 17 00:00:00 2001 From: Richardson Gunde Date: Tue, 2 Jun 2026 20:07:45 +0530 Subject: [PATCH] =?UTF-8?q?docs(mintlify):=20overhaul=20for=20v1.7.1=20?= =?UTF-8?q?=E2=80=94=20beginner-first,=20accurate,=20every=20feature=20(#5?= =?UTF-8?q?6)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New pages: - getting-started/install-your-framework — step-by-step per framework (Pi, Claude Code, Codex, Gemini CLI, Operator, universal) with honest integration-depth table - reference/business-hub — the :3008 dashboard, Studio 3D, artifact browser, scope switcher, multi-project aggregation (+ honest token/cost limitation) - reference/webhooks — all 5 channels (slack/teams/discord/telegram/whatsapp), both config options, notify --test - reference/approvals — policy.json, manager allow-list, RSTACK_APPROVAL_TOKEN Fixes (stale → real): - removed commands that don't exist (list prompts, info) - cli.mdx rewritten around real commands (init/hub/notify/list/add/validate) + the dashboard binaries - quickstart + installation now lead with 'npm install rstack-agents' + init - port 3005 → 3008 (architecture, observability, pi-tools) - '14 pipeline agents' → 15 (intro, sdlc-pipeline/overview) - configuration.mdx: identity/hub/approval/notification env vars added - governance: policy.json + token + manager roles - docs.json: new Business Hub group, install-your-framework, observability in nav - removed broken hero (asset never existed) — mint broken-links clean Closes #56 Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/mintlify/architecture.mdx | 4 +- docs/mintlify/concepts/plugins-and-skills.mdx | 15 +- docs/mintlify/docs.json | 10 + .../getting-started/governance-model.mdx | 10 +- .../install-your-framework.mdx | 178 ++++++++++++++++++ .../mintlify/getting-started/installation.mdx | 30 ++- docs/mintlify/introduction.mdx | 18 +- docs/mintlify/quickstart.mdx | 140 ++++++-------- docs/mintlify/reference/approvals.mdx | 78 ++++++++ docs/mintlify/reference/business-hub.mdx | 88 +++++++++ docs/mintlify/reference/cli.mdx | 143 +++++++------- docs/mintlify/reference/configuration.mdx | 33 ++++ docs/mintlify/reference/observability.mdx | 2 +- docs/mintlify/reference/pi-tools.mdx | 2 +- docs/mintlify/reference/webhooks.mdx | 74 ++++++++ docs/mintlify/sdlc-pipeline/overview.mdx | 4 +- 16 files changed, 643 insertions(+), 186 deletions(-) create mode 100644 docs/mintlify/getting-started/install-your-framework.mdx create mode 100644 docs/mintlify/reference/approvals.mdx create mode 100644 docs/mintlify/reference/business-hub.mdx create mode 100644 docs/mintlify/reference/webhooks.mdx 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 | |---|---|---|