diff --git a/.gitignore b/.gitignore index 48ec5ae..7a438c2 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,8 @@ dist/ .dev.vars *.log .mcp.json +# cc-taskrunner worktree protection +C:* +node_modules/ +.pnpm-store/ +__pycache__/ diff --git a/docs-manifest.json b/docs-manifest.json index e13661c..ab5ec58 100644 --- a/docs-manifest.json +++ b/docs-manifest.json @@ -14,7 +14,7 @@ "order": 1, "color": "#2ea043", "tag": "01" - }, + } } }, "edgestack": { diff --git a/src/content/docs/api-reference.md b/src/content/docs/api-reference.md index f416685..b078078 100644 --- a/src/content/docs/api-reference.md +++ b/src/content/docs/api-reference.md @@ -9,269 +9,363 @@ tag: "07" # API Reference -Complete reference for the Stackbilder platform API. +Complete reference for the StackBilt Stackbilder Architect API. -**Base URL:** `https://stackbilder.com` +**Base URL:** `https://stackbilt.dev` -All API routes are Astro server endpoints that call backend services (TarotScript, img-forge) via Cloudflare service bindings. No separate API domain — frontend and API share one worker. +Flows created on one environment do not exist on another (separate Durable Objects). ## Authentication -All `/api/*` endpoints require an authenticated session. Authentication is handled via the `better-auth.session_token` cookie, set during OAuth sign-in through edge-auth (`auth.stackbilt.dev`). +Authentication is endpoint-specific. Most protected endpoints accept one of: -### Session Flow +| Method | Header | Format | +|--------|--------|--------| +| MCP Token | `Authorization` | `Bearer ` | +| Access Key | `X-Access-Key` | `ska_...` | +| Compass JWT | `Authorization` | `Bearer ` (RS256) | -1. User clicks "Sign in with GitHub" (or Google) on `stackbilder.com/login` -2. Redirects to `auth.stackbilt.dev/auth/sign-in/github` -3. OAuth callback sets `better-auth.session_token` cookie -4. All subsequent API requests include the cookie automatically +`GET /mcp/info` is public (capability discovery / health check). -### Session Validation +Public/special-auth exceptions include: -The platform validates sessions via an RPC binding to edge-auth (`EdgeAuthEntrypoint.validateSession`). This runs in the same Cloudflare colo with near-zero latency. +- `POST /api/webhooks/stripe` (Stripe signature-verified webhook) +- `POST /api/trial/start` (public trial bootstrap) +- `GET /api/trial/status` and `POST /api/trial/upgrade-intent` (trial token required, not access key) +- `POST /api/self-serve/access-key` (public self-serve key issuance) +- `POST /api/feedback/submit` and `POST /api/contact` -**Session claims returned:** +### Token Exchange +Exchange an access key for a Compass JWT that works at both StackBilt and Compass: + +```bash +POST /api/auth/token +X-Access-Key: ska_... +Content-Type: application/json + +{ "expires_in": 3600 } +``` + +Response: ```json -{ - "userId": "string", - "email": "string", - "orgId": "string | null", - "expiresAt": 1234567890 -} +{ "access_token": "eyJ...", "token_type": "Bearer", "expires_in": 3600 } ``` -## Flows API +## Flow API -### Create a Flow +### Create & Run Full Flow ``` -POST /api/flows +POST /api/flow/full ``` -Classifies the intention via TarotScript, then runs a `scaffold-cast` spread to generate the project skeleton and governance output. - -**Request body:** +Kickoff is asynchronous — returns `flowId` immediately. Poll `GET /api/flow/:id` for progress, or use the `getFlowSummary` MCP tool for a lightweight summary. +**Request:** ```json { - "intention": "A REST API for managing subscriptions with Stripe", - "project_type": "api" + "input": "Description of your system to architect", + "config": { + "sprint": { + "teamSize": "SMALL_TEAM", + "sprintDuration": "TWO_WEEKS" + }, + "governance": { + "mode": "ADVISORY", + "projectId": "your-project-id", + "transport": "auto", + "qualityThreshold": 80 + } + } } ``` -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `intention` | string | Yes | Plain-language description of what to build | -| `project_type` | string | No | `saas`, `api`, `dashboard`, `cli`, `library`, `marketplace` (default: `api`) | - -**Response (`201 Created`):** - +**Response:** ```json { - "id": "sha256-hash", - "classification": { - "pattern": "stripe", - "confidence": "high" - }, - "traits": { - "route_shape": "REST CRUD + webhooks", - "verification": "Stripe signature verification", - "bindings": "D1, KV", - "framework": "Hono" - }, - "tier2_recommended": false, - "output": "...", - "facts": { ... } + "flowId": "uuid", + "status": "RUNNING", + "createdAt": "" } ``` -### List Flows +### Get Flow Status (Full) ``` -GET /api/flows +GET /api/flow/:id ``` -Returns scaffold-cast readings from the TarotScript grimoire for the authenticated user. +Returns the complete flow state (100KB+) including all mode outputs, structured artifacts, and contradiction reports. **For lightweight polling, use the `getFlowSummary` MCP tool instead.** -**Response:** +### Get Flow Summary (MCP Only) + +**MCP-only operation.** This summary is not available as a direct REST call. Use the `getFlowSummary` MCP tool instead. The REST equivalent for full flow state is `GET /api/flow/:id`. + +The `getFlowSummary` tool returns a compact (<2KB) progress snapshot. Recommended for polling from AI agents. ```json { - "flows": [ - { - "id": "sha256-hash", - "intention": "A REST API for...", - "project_type": "api", - "status": "completed", - "created_at": "2026-03-29T12:00:00Z" - } - ] + "flowId": "abc-123", + "status": "IN_PROGRESS", + "currentMode": "ARCHITECT", + "elapsed": "2m34s", + "modes": { + "PRODUCT": { "status": "COMPLETED", "duration": "28s", "qualityPass": true }, + "UX": { "status": "COMPLETED", "duration": "31s", "qualityPass": true }, + "ARCHITECT": { "status": "RUNNING", "duration": null, "qualityPass": false } + }, + "contradictions": { "critical": 0, "high": 0, "coverageGaps": 0, "missingItems": 2 }, + "artifactCounts": { "requirements": 18, "risks": 5, "components": 0, "adrs": 0 }, + "usage": { "totalInputTokens": 12450, "totalOutputTokens": 8320 } } ``` -### Get Flow Detail +### Get Artifact (MCP Only) + +**MCP-only operation.** The `/artifacts/:MODE/structured` path does not exist as a REST route. Use the `getArtifact` MCP tool to retrieve a typed JSON artifact for a single mode. + +The actual REST artifact routes are: ``` -GET /api/flows/:id +GET /api/flow/:id/artifacts/:MODE ``` -Returns the full flow including governance artifacts, scaffold output, and classification facts. +Returns artifact metadata for a mode. Modes: `PRODUCT`, `UX`, `RISK`, `ARCHITECT`, `TDD`, `SPRINT`. -**Response:** +``` +GET /api/flow/:id/artifacts/:MODE/content +``` + +Returns chunked artifact content for a mode. + +The `getArtifact` MCP tool combines these into a single typed response (2-5KB): ```json { - "id": "sha256-hash", - "intention": "A REST API for...", - "project_type": "api", - "status": "completed", - "created_at": "2026-03-29T12:00:00Z", - "seed": 12345, - "artifacts": { ... }, - "governance": { - "threats": "## STRIDE Analysis\nT-001: ...", - "adrs": "## Decision\nUse cookie-based sessions...", - "test_plan": "## Integration Tests\ntest_auth_flow: ..." - }, - "scaffold": { - "files": { "src/index.ts": "...", "wrangler.toml": "..." }, - "download_url": "" - }, - "output": "..." + "schemaVersion": "2.0.0", + "mode": "PRODUCT", + "requirements": [ + { "id": "REQ-001", "text": "User authentication via JWT", "priority": "MUST", "category": "functional" } + ], + "entities": ["User", "Payment"], + "slas": [{ "id": "SLA-001", "metric": "uptime", "target": "99.9%", "window": "monthly" }], + "constraints": [{ "id": "CON-001", "type": "security", "text": "All data encrypted at rest" }], + "confidence": { "overall": 85, "missing": ["pricing model"] } } ``` -## Images API +Each mode produces sequential, referenceable IDs: `REQ-001`, `SLA-001`, `RISK-001`, `COMP-001`, `TS-001`, `ADR-001`. Downstream modes cross-reference these IDs. -### Generate an Image +### Get Flow Package ``` -POST /api/images/generate +GET /api/flow/:id/package ``` -Creates an image generation job via img-forge. The request is delegated through a service binding with the user's ID for tenant-scoped access. +Returns the complete structured project package (100-300KB). Supports `Accept: application/json` or `Accept: text/markdown`. -**Request body:** +### Get Flow Quality -```json -{ - "prompt": "A cyberpunk cityscape at sunset", - "quality_tier": "premium", - "negative_prompt": "blurry, low quality" -} +``` +GET /api/flow/:id/quality ``` -| Field | Type | Required | Default | Description | -|-------|------|----------|---------|-------------| -| `prompt` | string | Yes | — | Text description, 1-2000 characters | -| `quality_tier` | string | No | `standard` | `draft`, `standard`, `premium`, `ultra`, `ultra_plus` | -| `negative_prompt` | string | No | — | Things to exclude (effective on `draft` tier only) | +Returns concise quality checks: `grounding_pass`, `state_safety_pass`, `artifact_completeness_pass`, `overall_pass`. -**Response (`201 Created`):** +### Run Single Mode -```json -{ - "id": "uuid", - "job_id": "uuid", - "state": "queued", - "original_prompt": "A cyberpunk cityscape at sunset", - "final_prompt": "A cyberpunk cityscape at sunset, masterpiece, best quality...", - "asset_url": null, - "created_at": "2026-03-29T12:00:00Z" -} ``` +POST /api/flow/:MODE +``` + +Runs one mode against a flow context. If `flowId` is omitted, creates a new flow. Modes: `PRODUCT`, `UX`, `RISK`, `ARCHITECT`, `TDD`, `SPRINT`. + +### Flow Lifecycle -### List Images +| Endpoint | Method | Description | +|----------|--------|-------------| +| `/api/flow/:id/advance` | POST | Advance to next pending mode | +| `/api/flow/:id/resume` | POST | Resume from last failed step | +| `/api/flow/:id/recover` | POST | Rerun failed mode + recompute downstream | +| `/api/flow/:id/cancel` | POST | Cancel a running flow | +| `/api/flow/:id/logs` | GET | Execution timeline with timestamps | +| `/api/flow/:id/codegen` | GET | `project.json` draft for codegen engine | + +## Scaffold Engine ``` -GET /api/images +GET /api/flow/:id/scaffold ``` -Returns image jobs for the authenticated user. - -**Query parameters:** +Generates a deployable Cloudflare Workers project from a completed flow. -| Param | Type | Default | Description | -|-------|------|---------|-------------| -| `limit` | number | 20 | Max 100 | -| `offset` | number | 0 | Pagination offset | -| `state` | string | — | Filter: `queued`, `processing`, `completed`, `failed` | +**Prerequisites:** ARCHITECT mode must be completed. -**Response:** +**Content negotiation:** +- `Accept: application/json` — file manifest with `scaffoldHints` + `nextSteps` +- `Accept: application/zip` — downloadable ZIP archive +**JSON Response:** ```json { - "images": [ - { - "id": "uuid", - "prompt": "A cyberpunk cityscape...", - "quality_tier": "premium", - "status": "completed", - "image_url": "/v2/assets/sha256hash", - "created_at": "2026-03-29T12:00:00Z" - } + "flowId": "uuid", + "files": [ + { "path": "wrangler.toml", "content": "..." }, + { "path": "package.json", "content": "..." }, + { "path": "routes/api-gateway.ts", "content": "..." }, + { "path": "worker/event-queue.ts", "content": "..." } + ], + "scaffoldHints": { + "templateType": "workers-crud-api", + "primaryFramework": "Hono", + "hasQueueHandlers": true, + "hasScheduledJobs": false, + "hasDurableObjects": false, + "confidence": 85 + }, + "nextSteps": [ + "mkdir my-project && write each file", + "cd my-project && npm install", + "npx wrangler d1 create my-db", + "npx wrangler dev", + "npx wrangler deploy" ] } ``` -### Get Image Status +**Template Types:** -``` -GET /api/images/:id -``` +| Type | Description | +|------|-------------| +| `workers-crud-api` | Standard REST API with Hono routes | +| `workers-queue-consumer` | Queue-driven batch processing | +| `workers-durable-object` | Stateful Durable Object service | +| `workers-websocket` | WebSocket real-time service | +| `workers-cron` | Scheduled/cron-driven worker | +| `pages-static` | Static frontend (no Worker routes) | -Check the status of a specific image generation job. +**Category-aware file generation:** +- `compute`/`data`/`integration` → `routes/*.ts` (CRUD stubs) +- `async` → `worker/*-queue.ts` (queue consumer handlers) +- `security` → `worker/middleware/*.ts` (auth middleware) +- `frontend` → skipped -**Response:** +**Rate limiting:** 3 scaffolds per flow per 24 hours. Returns `429` if exceeded. -```json -{ - "id": "uuid", - "prompt": "...", - "quality_tier": "premium", - "status": "completed", - "image_url": "/v2/assets/sha256hash", - "error": null, - "created_at": "2026-03-29T12:00:00Z" -} -``` +**Generated files:** `wrangler.toml`, `package.json`, `tsconfig.json`, `worker/index.ts`, `schema.sql` (if D1), `routes/*.ts`, `worker/*-queue.ts`, `worker/middleware/*.ts`, `README.md`, `.gitignore`, `scripts/deploy.sh`, `.charter/config.json`, `governance.md` -**Job states:** `queued` → `processing` → `completed` | `failed` +## Structured Artifact Contract (v2) -Jobs stuck in `processing` for more than 60 seconds are automatically marked `failed`. +Each mode emits a machine-readable JSON block using the `:::ARTIFACT_JSON_START:::` delimiter. These are extracted, validated, and stored in `FlowState.structuredArtifacts`. -## Quality Tiers (img-forge) +**Contradiction checker** runs incrementally after each mode (8 cross-mode checks): +- Every `MUST` requirement → component or `reqCoverage` in ARCHITECT +- Every PRODUCT SLA → `slaValidation` entry in TDD +- Every `CRITICAL`/`HIGH` risk → test scenario in TDD +- ARCHITECT must not use `blockedPatterns` from RISK +- Named events must appear across ARCHITECT and TDD +- SPRINT surfaces requirements with no ADR as `undecidedReqs` -| Tier | Provider | Model | Neg. Prompt | Default Size | -|------|----------|-------|-------------|--------------| -| `draft` | Cloudflare AI | SDXL Lightning | Yes | 1024x1024 | -| `standard` | Cloudflare AI | FLUX.2 Klein 4B | No | 1024x768 | -| `premium` | Cloudflare AI | FLUX.2 Dev | No | 1024x768 | -| `ultra` | Gemini | Gemini 2.5 Flash | No | 1024x1024 | -| `ultra_plus` | Gemini | Gemini 3.1 Flash | No | 1024x1024 | +## Auth & GitHub Endpoints -## Error Responses +| Endpoint | Method | Description | +|----------|--------|-------------| +| `/api/auth/me` | GET | Current authenticated identity | +| `/api/auth/token` | POST | Exchange `ska_` key for Compass JWT | +| `/api/auth/better/*` | ALL | Proxies to the dedicated auth-worker service (Better Auth). Supports session management, API key authentication, and OAuth Provider plugin. Replaces the previous GitHub OAuth flow. Specific sub-routes are handled by the auth-worker and include session introspection and token management. | +| `/api/self-serve/access-key` | POST | Public self-serve `ska_` key issuance (rate limited, email-based) | +| `/api/github/repos` | GET/POST | List or create GitHub repos | +| `/api/github/publish` | POST | Publish a project to GitHub | +| `/api/github/publish-generated` | POST | Server-side codegen + full repo publish | -All errors return JSON: +## Admin Endpoints -```json -{ - "error": "Description of what went wrong" -} -``` +| Endpoint | Method | Description | +|----------|--------|-------------| +| `/api/admin/access-keys` | POST | Issue new access key | +| `/api/admin/access-keys` | GET | List keys (filter by userId, status) | +| `/api/admin/access-keys/:id` | GET | Inspect one key | +| `/api/admin/access-keys/:id/link-compass` | POST | Provision/link Compass seat credentials for an existing access key | +| `/api/admin/access-keys/:id/revoke` | POST | Revoke a key | +| `/api/admin/access-keys/:id/rotate` | POST | Rotate an access key. Generates a new key and revokes the old one. Returns the new key value. | +| `/api/admin/usage/:keyId` | GET | Per-key usage dashboard. Optional `?days=N` query param to filter by time window. Returns usage metrics. | +| `/api/admin/trial/leads` | GET | List trial lead records with associated events. Query params: `limit` (number), `eventsPerLead` (number). | +| `/api/keys/groq/self` | GET/POST/DELETE | Per-user GROQ key management | +| `/api/codegen/locks/release` | POST | Release a codegen lock manually. Used to resolve stuck locks. | +| `/api/codegen/locks/sweep` | POST | Sweep expired codegen locks across all active flows. | +| `/api/codegen/audit/rollup` | POST | Trigger a codegen audit rollup. Aggregates lock and collision metrics. | + +## Trial Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `POST` | `/api/trial/start` | Start a trial session. Accepts `email` in the request body. Creates a 72-hour trial with 2 flow runs. Returns a `trialToken`, usage counters, and expiry. | +| `GET` | `/api/trial/status` | Check current trial status. Returns remaining runs, expiry timestamp, and whether the trial is active. | +| `POST` | `/api/trial/upgrade-intent` | Log upgrade intent for the current trial token. Accepts optional `trigger` and `note`. | + +`POST /api/trial/start` returns a `trialToken` plus usage counters (`runsAllowed`, `runsUsed`, `runsRemaining`) and `expiresAt`. + +Trial sessions are stored in LEADS KV. Each trial allows 2 flow runs within a 72-hour window. + +## Feedback + +| Method | Path | Description | +|--------|------|-------------| +| `POST` | `/api/feedback/submit` | Submit feedback (bug report, feature request, or flow quality feedback). Rate limited to 5 submissions per day per IP. Stores in LEADS KV and sends admin notification via Resend. | + +**Request body fields:** + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `message` | string | yes | Feedback content | +| `type` | enum | yes | `bug` \| `feature` \| `general` \| `flow-quality` | +| `rating` | number | no | Score from 1–5 | +| `flowId` | string | no | Associated flow ID | +| `mode` | string | no | Associated flow mode | + +## Contact + +| Method | Path | Description | +|--------|------|-------------| +| `POST` | `/api/contact` | Landing page contact form submission. Accepts `email`, `team`, and `source` fields. Sends notification via Resend. | + +## Billing (Stripe) -| Status | Meaning | -|--------|---------| -| `400` | Invalid request (missing/invalid parameters) | -| `401` | No valid session (redirect to /login) | -| `404` | Resource not found | -| `502` | Backend service error (TarotScript or img-forge unavailable) | +| Endpoint | Method | Description | +|----------|--------|-------------| +| `/api/billing/checkout` | POST | Create Stripe Checkout session | +| `/api/billing/portal` | GET | Stripe billing portal | +| `/api/webhooks/stripe` | POST | Webhook receiver (signature verified) | -## Architecture Notes +## MCP Server + +The MCP server exposes 22 tools for AI agent integration (flow execution/inspection plus related platform operations like feedback and artifact amendment). See the [MCP Integration](/mcp) page for full tool documentation. + +| Endpoint | Method | Purpose | +|----------|--------|---------| +| `/mcp` | POST | Streamable HTTP transport | +| `/mcp` | GET | SSE connection | +| `/mcp/sse` | GET | Legacy SSE transport | +| `/mcp/info` | GET | Server capabilities (no auth) | + +## Error Responses -- API routes are Astro server endpoints (`src/pages/api/*.ts`) -- TarotScript is called via `TAROTSCRIPT` service binding (Fetcher) -- img-forge is called via `IMG_FORGE` service binding (Fetcher) with `X-Service-Binding` secret for delegated auth -- Session validation uses `AUTH_SERVICE` RPC binding to edge-auth (`EdgeAuthEntrypoint`) -- All three bindings run in the same Cloudflare colo — zero HTTP hops +| HTTP Status | Meaning | +|-------------|---------| +| `400` | Invalid request or missing flow state | +| `401` | Missing authentication | +| `403` | Invalid token | +| `404` | Flow or endpoint not found | +| `429` | Rate limit exceeded | +| `500` | Server error | + +JSON-RPC errors (MCP): + +| Code | Meaning | +|------|---------| +| `-32700` | Parse error | +| `-32600` | Invalid request | +| `-32601` | Method not found | +| `-32602` | Invalid params | +| `-32000` | Tool execution failed | diff --git a/src/content/docs/compass-governance-api.md b/src/content/docs/compass-governance-api.md new file mode 100644 index 0000000..cd70b6d --- /dev/null +++ b/src/content/docs/compass-governance-api.md @@ -0,0 +1,108 @@ +--- +title: "Compass Governance" +description: "Compass internal governance service — RPC methods, service binding integration, and governance modes." +section: "platform" +order: 8 +color: "#22d3ee" +tag: "08" +--- + +# Compass Governance + +Compass is an internal governance service accessed via Cloudflare Service Binding from the Stackbilder flow pipeline. It is **not a public API** — there are no HTTP endpoints, no MCP server, and no admin surface. + +## Architecture + +Compass is a lightweight RPC service (`compass` worker) bound to EdgeStack via `CSA_SERVICE` service binding. It provides governance guidance, quality assessment, and decision persistence for the 6-mode flow pipeline. + +``` +EdgeStack (FlowDO) + │ + ├── fetchGuidance(mode, tier) → constraints + quality thresholds + │ + ├── mode execution (LLM) + │ + ├── assessQuality(artifact) → score + pass/fail + │ + └── persistDecisions(decisions) → ledger write (SPRINT mode only) +``` + +## RPC Methods + +All calls go through `POST /rpc` with JSON-RPC payload. Requires `scope` object with `projectId`, `flowId`, `mode`, `tier`, `effectiveGovernanceMode`. + +### compass.fetchGuidance + +Returns governance context and quality thresholds for a flow mode. Called before each mode execution. + +```json +{ + "method": "compass.fetchGuidance", + "params": { + "scope": { + "projectId": "...", + "flowId": "...", + "mode": "ARCHITECT", + "tier": "pro", + "effectiveGovernanceMode": "ADVISORY" + } + } +} +``` + +### compass.assessQuality + +Scores a generated artifact against quality thresholds. Called after artifact generation. + +```json +{ + "method": "compass.assessQuality", + "params": { + "scope": { "..." }, + "artifact": "...", + "mode": "ARCHITECT" + } +} +``` + +### compass.persistDecisions + +Stores ADRs and architectural decisions in the governance ledger. Called at end of SPRINT mode only. + +```json +{ + "method": "compass.persistDecisions", + "params": { + "scope": { "..." }, + "decisions": [{ "..." }] + } +} +``` + +## Governance Modes by Plan + +| Plan | Max Mode | Behavior | +|------|----------|----------| +| Free | `PASSIVE` | Log only — never blocks | +| Pro | `ADVISORY` | Warn on issues, flow continues | +| Enterprise | `ENFORCED` | Block on FAIL, require remediation | + +## Integration + +EdgeStack creates a `CompassExchangeClient` per flow (cached, 5-min TTL). The client calls Compass via service binding with a 10-second timeout. + +```toml +# edgestack-v2/wrangler.toml +[[services]] +binding = "CSA_SERVICE" +service = "compass" +``` + +## Future Direction + +Compass governance logic is being consolidated into the Stackbilder Engine (`stackbilt-engine`), which already handles blessed pattern enforcement, compatibility scoring, and tier gating deterministically. See [edgestack#32](https://github.com/Stackbilt-dev/edgestack_v2/issues/32) for the migration plan. + +## Related Docs + +- [Ecosystem](/ecosystem) +- [Platform](/platform) (Stackbilder flow pipeline) diff --git a/src/content/docs/ecosystem.md b/src/content/docs/ecosystem.md index 68a115b..2ad62fb 100644 --- a/src/content/docs/ecosystem.md +++ b/src/content/docs/ecosystem.md @@ -9,52 +9,49 @@ tag: "01" # Ecosystem -Stackbilt is a developer platform built on three commercial services and one open-source CLI. Together they span the full lifecycle from describing an idea to shipping a governed, production-ready codebase. +StackBilt is three complementary tools that enforce governance across the full development lifecycle. ## The Three Pieces -| Tool | Role | -|------|------| -| **Charter** (`@stackbilt/cli`) | Open-source (Apache-2.0). Local + CI governance runtime, ADF context compiler, CLI gateway. | -| **Stackbilder** | Commercial. Two-phase scaffold engine: deterministic skeleton via TarotScript (~20ms, zero LLM), optional LLM polish via Cerebras. Governance output (threat analysis, ADRs, test plans) ships with every scaffold. | -| **img-forge** | Commercial. Multi-provider AI image generation across 5 quality tiers (SDXL through Gemini 3.1). | +| Tool | License | Role | +|------|---------|------| +| **Charter** (`@stackbilt/cli`) | Apache-2.0 (open source) | Local + CI governance runtime with ADF context compiler | +| **Stackbilder** | Commercial | Architecture generation, scaffold engine, structured artifacts | +| **Compass** | Commercial | Governance policy brain, institutional memory, ADR ledger | -Charter is the open-source CLI. Stackbilder and img-forge are commercial services, both included in the unified flat pricing at [stackbilder.com/pricing](https://stackbilder.com/pricing). +Charter is the open-source foundation. Stackbilder and Compass are commercial services. ## Service Map -| Service | Domain | Purpose | -|---------|--------|---------| -| **Stackbilder Platform** | `stackbilder.com` | Product frontend, Astro server API routes, service binding gateway | -| **TarotScript** | `tarotscript-worker` (service binding) | Deterministic scaffold engine — intent classification, scaffold-cast spreads, grimoire persistence | -| **img-forge** | `img-forge-gateway` (service binding) | AI image generation API, async job queue, R2 image storage | -| **Auth** | `auth.stackbilt.dev` | Centralized auth — OAuth (GitHub/Google), session management, API keys, quota, billing | -| **AEGIS** | `aegis.stackbilt.dev` | Persistent AI agent framework — see [aegis-oss](https://github.com/Stackbilt-dev/aegis-oss) | -| **Docs** | `docs.stackbilder.com` | Documentation (this site) | -| **Blog** | `blog.stackbilder.com` | Blog and changelog | +| Service | URL | Purpose | +|---------|-----|---------| +| **StackBilt** | `stackbilt.dev` | Architecture generation, MCP server, scaffold engine | +| **Compass** | via Stackbilder service binding | Governance enforcement, blessed patterns, ADR ledger | +| **Auth Worker** | `auth-tenant-v2` | Authentication service (Better Auth + D1, OAuth, SSO) | +| **img-forge** | `imgforge.stackbilt.dev` | AI image generation for documentation | ## How They Fit Together ``` -IDEA (plain language description) +IDEA │ ▼ -Phase 1: TarotScript classify(intention) - │ → deterministic pattern matching, ~20ms +Compass: governance("Can we build X?") + │ + ├── REJECTED ──► Stop + │ + ▼ APPROVED +Stackbilder: runFullFlowAsync(idea) + → PRODUCT → UX → RISK → ARCHITECT → TDD → SPRINT │ ▼ -Phase 1: TarotScript scaffold-cast(intention + pattern) - │ → project structure, config files, .ai/ governance suite - │ → threat-model.md, ADRs, test-plan.md - │ → zero LLM, zero inference cost +Compass: red_team(architecture) → security review │ - ▼ (optional, Pro tier) -Phase 2: Cerebras LLM polish - │ → idiomatic code generation WITHIN Phase 1 constraints - │ → governance guardrails prevent drift + ▼ +Stackbilder: getFlowScaffold(flowId) → deployable project │ ▼ -Charter: validate + drift → commit compliance +Charter: validate + drift → commit and stack compliance │ ▼ SHIPPED (governed) @@ -63,9 +60,9 @@ SHIPPED (governed) ## Charter: Local Enforcement + ADF Context Compiler -Charter runs in your terminal and CI pipeline. It validates commit trailers, scores drift against your blessed stack, and blocks merges on violations. Zero SaaS dependency — all checks are deterministic and local. +Charter runs in your terminal and CI pipeline. It validates commit trailers, scores drift against your blessed stack, and blocks merges on violations. Zero SaaS dependency - all checks are deterministic and local. -Charter also ships **ADF (Attention-Directed Format)** — a modular, AST-backed context system that replaces monolithic `.cursorrules` and `claude.md` files with compiled, trigger-routed `.ai/` modules. ADF treats LLM context as a compiled language: emoji-decorated semantic keys, typed patch operations, manifest-driven progressive disclosure, and metric ceilings with CI evidence gating. +Charter also ships **ADF (Attention-Directed Format)** - a modular, AST-backed context system that replaces monolithic `.cursorrules` and `claude.md` files with compiled, trigger-routed `.ai/` modules. ADF treats LLM context as a compiled language: emoji-decorated semantic keys, typed patch operations, manifest-driven progressive disclosure, and metric ceilings with CI evidence gating. ```bash npm install --save-dev @stackbilt/cli @@ -75,114 +72,99 @@ npx charter adf init # scaffold .ai/ context directory **Governance commands:** `validate`, `drift`, `audit`, `classify`, `hook install`. **ADF commands:** `adf init`, `adf fmt`, `adf patch`, `adf bundle`, `adf sync`, `adf evidence`. -**Engine commands:** `login`, `architect`, `scaffold` — generate and write tech stacks via the Stackbilder Engine. -For quantitative analysis of ADF's impact on autonomous system architecture, see the [Context-as-Code white paper](https://github.com/Stackbilt-dev/charter/blob/main/papers/context-as-code-v1.1.md). +For quantitative analysis of ADF's impact on autonomous system architecture, see the [Context-as-Code white paper](https://github.com/stackbilt-dev/charter-kit/blob/main/papers/context-as-code-v1.1.md). -## Stackbilder: Two-Phase Scaffold - -### Phase 1 — Deterministic Skeleton (Free tier) - -TarotScript classifies your intention against a vocabulary deck, then runs a `scaffold-cast` spread that deterministically produces: - -- Project structure and config files -- `.ai/threat-model.md` — STRIDE-based security threat analysis -- `.ai/adr-*.md` — Architectural decision records -- `.ai/test-plan.md` — Integration and unit test specifications -- Architectural constraints (machine-readable guardrails) - -~20ms. Zero inference cost. Same input = same output. +## Stackbilder: Architecture + Scaffold -### Phase 2 — LLM Polish (Pro tier) +The 6-mode pipeline (PRODUCT → UX → RISK → ARCHITECT → TDD → SPRINT) produces structured artifacts with cross-referenced IDs. After completion, the scaffold engine generates a deployable Cloudflare Workers project. -Takes the Phase 1 skeleton and generates idiomatic, production-grade code using Cerebras fast inference. The key differentiator: the LLM works *within* the governance constraints from Phase 1 — guided generation, not blind generation. +Available via: +- **Browser UI** at [stackbilt.dev](https://stackbilt.dev) (interactive) +- **MCP server** at `stackbilt.dev/mcp` (agent-driven, 22 tools) +- **REST API** at `stackbilt.dev/api/flow/*` (direct HTTP) -### Access +### Lightweight Agent Pattern -- **Browser UI** at [stackbilder.com](https://stackbilder.com) -- **API** at `stackbilder.com/api/flows` (authenticated Astro server routes) -- **MCP** via the Stackbilt MCP gateway (see [MCP Integration](/mcp)) +The recommended agent workflow downloads ~40KB total (down from 300KB+): -## img-forge: AI Image Generation - -Multi-provider image generation across 5 quality tiers, included in your Stackbilder plan with no per-image costs. - -| Tier | Provider | Model | -|------|----------|-------| -| Draft | Cloudflare AI | SDXL Lightning | -| Standard | Cloudflare AI | FLUX.2 Klein 4B | -| Premium | Cloudflare AI | FLUX.2 Dev | -| Ultra | Gemini | Gemini 2.5 Flash | -| Ultra+ | Gemini | Gemini 3.1 Flash | +``` +runFullFlowAsync → getFlowSummary polls → getArtifact per mode → getFlowScaffold +``` -See [img-forge API](/img-forge) for the full REST and MCP reference. +## Compass: Policy Brain -## Authentication +For current Compass routes, auth endpoints, and MCP integration surfaces, see [Compass Governance API](/compass-governance-api). -All services use edge-auth (`auth.stackbilt.dev`) for centralized authentication: +Compass is an AI governance agent with institutional memory — a ledger of ADRs, blessed patterns, and constitutional rules. It validates architecture decisions, runs red-team reviews, and drafts formal policy documents. -- **OAuth** — GitHub and Google sign-in via Better Auth -- **Session cookies** — `better-auth.session_token`, validated via RPC service binding -- **API keys** — `ea_*`, `sb_live_*`, `sb_test_*` prefixes for programmatic access +### Governance Modes by Plan -The platform frontend (`stackbilder.com`) validates sessions via an RPC binding to edge-auth — near-zero latency, no HTTP hop. +| Plan | Max Mode | Behavior | +|------|----------|----------| +| Free | `PASSIVE` | Log only — never blocks | +| Pro | `ADVISORY` | Warn on issues, flow continues | +| Enterprise | `ENFORCED` | Block on FAIL, require remediation | -## Pricing +When governance mode is capped by plan tier, a soft upsell prompt appears in the `governanceState` response. -Flat tiers. No credits, no tokens, no per-action charges. +### Blessed Patterns -| Plan | Scaffolds/mo | Images/mo | Price | -|------|-------------|-----------|-------| -| Free | 3 | 5 | $0 | -| Pro | 50 | 100 | $29/mo | -| Team | 50/seat | Pooled | $19/seat/mo | +Compass maintains a ledger of approved technology patterns. These are injected into Stackbilder's ARCHITECT prompt automatically when governance is enabled. Example: -Every plan includes full governance output. See [stackbilder.com/pricing](https://stackbilder.com/pricing). +- Compute: Cloudflare Workers (not AWS Lambda) +- Database: Cloudflare D1 (not PostgreSQL) +- Cache: Cloudflare KV (not Redis) +- Queue: Cloudflare Queues (not SQS) -## Open Source Libraries +### CSA Transport Modes -Beyond Charter and the commercial services, Stackbilt maintains a set of edge-native open source libraries. They are standalone, composable, and deliberately scoped — each solves one problem Cloudflare Workers developers hit repeatedly. +Communication between Stackbilder and Compass supports multiple transports: -| Library | Repo | Purpose | -|---|---|---| -| **Charter CLI** | [Stackbilt-dev/charter](https://github.com/Stackbilt-dev/charter) | Governance runtime, ADF context compiler, CLI gateway (Apache-2.0) | -| **Stackbilt MCP Gateway** | [Stackbilt-dev/stackbilt-mcp-gateway](https://github.com/Stackbilt-dev/stackbilt-mcp-gateway) | OAuth-authenticated MCP gateway routing to Stackbilt platform services | -| **AEGIS (OSS framework)** | [Stackbilt-dev/aegis-oss](https://github.com/Stackbilt-dev/aegis-oss) | Persistent AI agent framework for Workers — multi-tier memory, goals, dreaming cycles, MCP native | -| **llm-providers** | [Stackbilt-dev/llm-providers](https://github.com/Stackbilt-dev/llm-providers) | Multi-LLM failover with circuit breakers, cost tracking, intelligent retry | -| **worker-observability** | [Stackbilt-dev/worker-observability](https://github.com/Stackbilt-dev/worker-observability) | Edge-native observability — health checks, structured logging, metrics, tracing, SLI/SLO monitoring | -| **audit-chain** | [Stackbilt-dev/audit-chain](https://github.com/Stackbilt-dev/audit-chain) | Tamper-evident audit trail via SHA-256 hash chaining with R2 immutability and D1 indexing | -| **feature-flags** | [Stackbilt-dev/feature-flags](https://github.com/Stackbilt-dev/feature-flags) | KV-backed feature flags — per-tenant, canary rollouts, A/B conditions, Hono middleware | -| **contracts** | [Stackbilt-dev/contracts](https://github.com/Stackbilt-dev/contracts) | Stackbilt Contract Ontology Layer — ODD-driven code generation from TypeScript+Zod contracts | -| **cc-taskrunner** | [Stackbilt-dev/cc-taskrunner](https://github.com/Stackbilt-dev/cc-taskrunner) | Autonomous task queue for Claude Code with safety hooks, branch isolation, PR creation | -| **Social Sentinel** | [Stackbilt-dev/social-sentinel](https://github.com/Stackbilt-dev/social-sentinel) | Privacy-first social sentiment monitoring — PII redaction, Workers AI sentiment analysis | -| **Mindspring** | [Stackbilt-dev/mindspring](https://github.com/Stackbilt-dev/mindspring) | Semantic search for AI conversation exports — upload, embed, search, RAG chat | -| **n8n-transpiler** | [Stackbilt-dev/n8n-transpiler](https://github.com/Stackbilt-dev/n8n-transpiler) | n8n automation JSON → deployable Workers transpiler | -| **equity-scenario-sim** | [Stackbilt-dev/equity-scenario-sim](https://github.com/Stackbilt-dev/equity-scenario-sim) | Cap table simulator for partnership negotiations | -| **ai-playbook** | [Stackbilt-dev/ai-playbook](https://github.com/Stackbilt-dev/ai-playbook) | AI interaction frameworks, philosophical archetypes, context engineering patterns | +| Transport | Description | +|-----------|-------------| +| `external_http` | Public HTTPS MCP endpoint (default) | +| `service_binding` | Internal Worker binding (when configured) | +| `auto` | Canary split between HTTP and binding | -All libraries live under the [`Stackbilt-dev`](https://github.com/Stackbilt-dev) GitHub organization. Contributions welcome — see each repo's `CONTRIBUTING.md` and `SECURITY.md`. +Canary rollout percentage is configurable per-flow or via environment default. -## OSS Core ↔ Commercial Extension Pattern +## Governance-First Development -Some capabilities in the Stackbilt ecosystem ship as a public OSS core with a commercial productization built on top. The OSS core is the canonical, publicly-named reference implementation — that's what gets documented, discussed, contributed to, and written about. Commercial extensions are implementation details: they are not publicly named, not separately documented, and not referenced in public artifacts. +Every significant decision flows through governance before implementation: -A concrete example: [`aegis-oss`](https://github.com/Stackbilt-dev/aegis-oss) is the full persistent AI agent framework for Cloudflare Workers — multi-tier memory, autonomous goals, dreaming cycles, MCP native. It is the canonical AEGIS and is fully open source under its repository license. The commercial Stackbilt platform builds additional integrations and productization on top of that core. When referring to "AEGIS" in any public context — blog posts, GitHub issues, conference talks, external documentation, social media — the reference is to `aegis-oss`. Commercial extensions exist but are not separately named, advertised, or linked publicly. +1. **Pre-approval** — Compass validates the idea against policy +2. **Architecture** — Stackbilder generates a governed blueprint with blessed patterns +3. **Review** — Compass red-teams the architecture output +4. **Record** — ADRs are persisted to the governance ledger (when `autoPersist: true`) +5. **Scaffold** — Stackbilder generates deployable project files +6. **Commit** — Charter enforces `Governed-By:` trailer compliance at the repo level +7. **Evidence** — Charter validates ADF metric ceilings (`adf evidence --auto-measure --ci`) +8. **CI** — Charter blocks merges on drift violations or metric ceiling breaches -This convention serves two purposes: +## Authentication Across Services -1. **OSS clarity.** Contributors, users, and researchers engage with one canonical repo per capability. There is no ambiguity about "which version are we talking about." -2. **Moat protection.** Commercial productization is kept out of public discussion, which prevents feature leaks and competitive mapping of the commercial surface. +### Unified Auth (Recommended) -Internal contributors — including autonomous agents filing issues or drafting documentation — must follow the same convention. Public artifacts reference the OSS core only. See [Outbound Disclosure](/security/#outbound-disclosure--filing-against-stackbilt-dev-public-repositories) for the full authoring rules. +One access key works at both Stackbilder and Compass: -## Multi-Stack Roadmap +```bash +# Exchange ska_ key for a JWT +curl -X POST https://stackbilt.dev/api/auth/token \ + -H "X-Access-Key: ska_..." \ + -d '{"expires_in": 3600}' +# Use the returned JWT at either service +``` -Cloudflare Workers is the currently supported stack. Coming soon: +### Service-to-Service -- Vercel / Next.js -- AWS Lambda + API Gateway -- Supabase Edge Functions -- Deno Deploy +For automated pipelines, each service has its own token: -Stack expansion is tracked in the TarotScript deck system. The architecture is stack-agnostic — each target gets its own runtime deck + threat overlay + file templates. +```json +{ + "edgestack": { "url": "https://stackbilt.dev/mcp", "token": "EDGESTACK_MCP_TOKEN" }, + "compass": { "url": "https://stackbilt.dev/mcp", "transport": "service_binding", "token": "CSA_MCP_TOKEN" }, + "imgforge": { "url": "https://imgforge.stackbilt.dev/mcp", "token": "IMGFORGE_MCP_TOKEN" } +} +``` diff --git a/src/content/docs/getting-started.md b/src/content/docs/getting-started.md index 73956c6..bc880ad 100644 --- a/src/content/docs/getting-started.md +++ b/src/content/docs/getting-started.md @@ -7,374 +7,105 @@ color: "#2ea043" tag: "02" --- -# Charter Kit +# Getting Started -[![npm version](https://img.shields.io/npm/v/@stackbilt/cli?label=charter&color=5F7FFF&style=for-the-badge)](https://www.npmjs.com/package/@stackbilt/cli) +Charter is a local-first governance toolkit with a built-in AI context compiler. It validates commit governance, detects stack drift, scores risk, and ships **ADF (Attention-Directed Format)** — a modular, AST-backed context system that replaces monolithic `.cursorrules` and `claude.md` files. Everything runs locally and in CI, with no SaaS dependency. +## Install - -## The Problem - -You write a CLAUDE.md. You add a `.cursorrules`. You paste instructions into GEMINI.md. Your AI agent loads all of it into the context window -- 10,000 tokens of flat, unstructured rules competing with the actual work. - -Half get ignored. You don't know which half. - -## The Solution - -Charter is an open-source CLI that replaces monolithic agent config files with **ADF (Attention-Directed Format)** -- a modular context system where agents load only the rules they need for the current task. - -Instead of one big file, you get a manifest. The manifest declares modules, trigger keywords that load them on demand, token budgets, and weighted sections that tell the agent what's load-bearing vs. advisory. +Recommended: local dev dependency per repo. ```bash npm install --save-dev @stackbilt/cli -npx charter bootstrap --yes # detect stack, scaffold .ai/, migrate existing rules ``` -## Five-Minute Adoption - -Already have agent config files? Charter migrates them: +pnpm workspace root: ```bash -# See what would happen (dry run) -charter adf migrate --dry-run - -# Migrate: classifies rules by strength, routes to ADF modules, replaces originals with thin pointers -charter adf migrate -``` - -Your `CLAUDE.md` / `.cursorrules` / `GEMINI.md` content gets classified (imperative vs. advisory vs. neutral), routed to the right module (frontend rules to `frontend.adf`, backend rules to `backend.adf`), and your originals become one-line pointers to `.ai/`. No content lost, no rewrite needed. - -## How ADF Works - -Charter manages context through the `.ai/` directory: - -```text -.ai/ - manifest.adf # Module registry: default-load vs on-demand with trigger keywords - core.adf # Always-loaded: role, constraints, output format, metric ceilings - state.adf # Session state: current task, decisions, blockers - frontend.adf # On-demand: loaded when task mentions "react", "css", etc. - backend.adf # On-demand: loaded when task mentions "endpoint", "REST", etc. +pnpm add -Dw @stackbilt/cli ``` -When you run `charter adf bundle --task "Fix the React login component"`, Charter: -1. Reads the manifest -2. Loads `core.adf` and `state.adf` (always loaded) -3. Sees "React" matches a trigger keyword -- loads `frontend.adf` -4. Skips `backend.adf` (no matching triggers) -5. Merges the loaded modules into a single context payload with token budget tracking +Global (optional, puts `charter` on your PATH): -The agent gets exactly the rules it needs. Nothing more. - -### Format Example - -```text -ADF: 0.1 - -TASK: - Build the user dashboard - -CONTEXT: - - React 18 with TypeScript - - TailwindCSS for styling - - REST API at /api/v2 - -CONSTRAINTS [load-bearing]: - - No external state libraries - - Must support SSR - -METRICS [load-bearing]: - entry_loc: 142 / 500 [lines] - handler_loc: 88 / 300 [lines] - -STATE: - CURRENT: Implementing layout grid - NEXT: Add data fetching - BLOCKED: Waiting on API schema +```bash +npm install -g @stackbilt/cli ``` -Sections use emoji decorations for attention signaling, support four content types (text, list, key-value map, and metric with value/ceiling/unit), and follow a canonical ordering the formatter enforces. `[load-bearing]` vs `[advisory]` weight annotations distinguish measurable constraints from preferences. Metric entries (`key: value / ceiling [unit]`) define hard ceilings that the `evidence` command validates automatically. - -## Self-Governance: Charter Enforces Its Own Rules +> **WSL2 users:** If your project lives on the Windows filesystem (`/mnt/c/...`), see [WSL2 + Windows Filesystem](./wsl2-install.md) for path considerations, pnpm workarounds, and line-ending setup. -This isn't theoretical. Charter uses ADF to govern its own codebase. The `.ai/` directory in this repository contains the same modules and metric ceilings that any adopting repo would use. +## Bootstrap a Repo -Every commit runs through a pre-commit hook that executes `charter adf evidence --auto-measure`. If a source file exceeds its declared LOC ceiling, the commit is rejected. We can't ship code that violates our own governance rules -- even by accident, even at 2am. +```bash +# Preview what charter detects — no files written +npx charter setup --detect-only --format json -Here is the actual output from Charter's own evidence check (v0.8.0): +# Write governance baseline + optional CI workflow +npx charter setup --ci github --yes -```text - ADF Evidence Report - =================== - Modules loaded: core.adf, state.adf - Token estimate: ~494 - Token budget: 4000 (12%) - - Auto-measured: - adf_commands_loc: 618 lines (packages/cli/src/commands/adf.ts) - adf_bundle_loc: 175 lines (packages/cli/src/commands/adf-bundle.ts) - adf_sync_loc: 213 lines (packages/cli/src/commands/adf-sync.ts) - adf_evidence_loc: 272 lines (packages/cli/src/commands/adf-evidence.ts) - adf_migrate_loc: 474 lines (packages/cli/src/commands/adf-migrate.ts) - bundler_loc: 125 lines (packages/adf/src/bundler.ts) - parser_loc: 214 lines (packages/adf/src/parser.ts) - cli_entry_loc: 191 lines (packages/cli/src/index.ts) - - Section weights: - Load-bearing: 3 - Advisory: 1 - Unweighted: 0 - - Constraints: - [ok] adf_commands_loc: 618 / 650 [lines] -- PASS - [ok] adf_bundle_loc: 175 / 200 [lines] -- PASS - [ok] adf_sync_loc: 213 / 250 [lines] -- PASS - [ok] adf_evidence_loc: 272 / 380 [lines] -- PASS - [ok] adf_migrate_loc: 474 / 500 [lines] -- PASS - [ok] bundler_loc: 125 / 500 [lines] -- PASS - [ok] parser_loc: 214 / 300 [lines] -- PASS - [ok] cli_entry_loc: 191 / 200 [lines] -- PASS - - Sync: all sources in sync - - Verdict: PASS +# Mixed repos (frontend + backend): choose preset explicitly +npx charter setup --detect-only +npx charter setup --preset fullstack --ci github --yes ``` -What this shows: +`setup` writes: +- `.charter/config.json` — governance baseline config +- `.charter/patterns/*.json` — blessed-stack pattern definitions +- `.charter/policies/*.md` — human-readable policy summary +- `.github/workflows/charter-governance.yml` — CI workflow (if `--ci github`) -- **Metric ceilings enforce LOC limits on source files.** Each metric in a `.adf` module declares a ceiling. `--auto-measure` counts lines live from the sources referenced in the manifest. -- **Self-correcting architecture.** When `bundler_loc` hit 413/500, Charter's own evidence gate flagged the pressure. The file was split into three focused modules (`manifest.ts`, `merger.ts`, `bundler.ts`) -- now 125/500. The system caught the problem and the system verified the fix. -- **CI gating.** Generated governance workflows run `doctor --adf-only --ci` and `adf evidence --auto-measure --ci` on every PR, blocking merges on ceiling breaches. -- **Available to any repo.** This is the same system you get by running `charter adf init` in your own project. +## Set Up ADF Context -## Quick Reference +ADF turns your LLM context into a compiled, modular system. Scaffold the `.ai/` directory: ```bash -# Scaffold .ai/ with starter modules -charter adf init - -# Reformat to canonical form -charter adf fmt .ai/core.adf --write - -# Apply a typed patch -charter adf patch .ai/state.adf --ops '[{"op":"ADD_BULLET","section":"STATE","value":"Reviewing PR #42"}]' - -# Bundle context for a task (trigger-based module loading) -charter adf bundle --task "Fix the React login component" - -# Migrate existing agent configs into ADF -charter adf migrate --dry-run +# Scaffold .ai/ with manifest, core, and state modules +npx charter adf init -# Verify .adf files haven't drifted from locked hashes -charter adf sync --check - -# Validate metric constraints -charter adf evidence --auto-measure - -# Recalibrate metric ceilings -charter adf metrics recalibrate --headroom 15 --reason "Scope expansion" --dry-run - -# Expose ADF context as an MCP server (for Claude Code / any MCP client) -charter serve +# Verify everything parses and syncs +npx charter doctor --format json ``` -## Why Charter +This creates (for default presets): -- **Modular AI context** -- trigger-routed `.ai/` modules replace monolithic config files -- **Five-minute migration** -- classify and route existing CLAUDE.md / .cursorrules / GEMINI.md rules automatically -- **MCP server** -- `charter serve` exposes your ADF context as an MCP server; Claude Code can query constraints, architectural decisions, and recent changes without reading raw files -- **Evidence-based governance** -- metric ceilings with auto-measurement, structured pass/fail reports, CI gating -- **Self-regulating** -- pre-commit hooks enforce constraints before code lands -- **Commit governance** -- validate `Governed-By` and `Resolves-Request` trailers, score commit risk -- **Drift detection** -- scan for stack drift against blessed patterns -- **Stable JSON output** -- every command supports `--format json` with `nextActions` hints for agent workflows - -## Install - -```bash -npm install --save-dev @stackbilt/cli +```text +.ai/ + manifest.adf # Module registry: default-load vs on-demand with triggers + core.adf # Always-loaded: role, constraints, metric ceilings + state.adf # Session state: current task, decisions, blockers + frontend.adf # Frontend module scaffold (on-demand, triggers: React, CSS, UI) + backend.adf # Backend module scaffold (on-demand, triggers: API, Node, DB) ``` -For pnpm workspaces: `pnpm add -Dw @stackbilt/cli`. For global install: `npm install -g @stackbilt/cli`. +For documentation-heavy repos, use `--preset docs` to get `decisions.adf` and `planning.adf` instead of frontend/backend modules. -## Getting Started +Edit `.ai/core.adf` to define your project constraints and LOC ceilings. The `METRICS [load-bearing]` section enforces hard limits that CI can gate on. -### Human Workflow +## Verify the Setup ```bash -charter # Repo risk/value snapshot -charter bootstrap --ci github # One-command onboarding -charter doctor # Validate environment/config -charter validate # Check commit governance -charter drift # Scan for stack drift -charter audit # Governance summary -charter adf init # Scaffold .ai/ context directory +npx charter doctor --format json +npx charter ``` -### Claude Code Integration (MCP) - -`charter serve` exposes your `.ai/` modules as an MCP server. Add it to `.claude/settings.json`: - -```json -{ - "mcpServers": { - "charter": { - "command": "charter", - "args": ["serve"] - } - } -} -``` +`charter` with no arguments prints a live governance snapshot: risk score, governed commit ratio, drift status. -Claude Code can then call `getProjectContext`, `getArchitecturalDecisions`, `getProjectState`, and `getRecentChanges` directly — no manual `adf bundle` needed in the conversation. +`doctor` validates environment health including ADF readiness: manifest existence, module parse status, and sync lock integrity. -### Agent Workflow +## Run an Evidence Check -Prefer JSON mode and exit-code handling: +If you have ADF set up with metric ceilings, run the evidence pipeline: ```bash -charter --format json -charter setup --ci github --yes --format json -charter doctor --format json -charter validate --format json --ci -charter drift --format json --ci -charter audit --format json -charter adf bundle --task "describe the task" --format json -charter adf evidence --auto-measure --format json --ci -charter adf sync --check --format json -``` +# Validate all metric ceilings and produce a structured report +npx charter adf evidence --auto-measure -Agent contract: -- Inputs: git repo + optional existing `.charter/` -- Stable machine output: `--format json` with `nextActions` hints where applicable -- Exit codes: `0` success, `1` policy violation, `2` runtime/usage error -- CI behavior: with `--ci`, treat `1` as gating failure and surface actionable remediation -- Evidence: `adf evidence --ci` exits 1 on metric ceiling breaches; warnings (at boundary) don't fail - -
-Trailer Adoption Ramp - -Teams often score lower early due to missing governance trailers. Use this ramp: -- Stage 1: run `charter validate --ci --format json` in PR CI and fail on policy violations. -- Stage 2: add a commit template in the repo that includes `Governed-By` and `Resolves-Request`. -- Stage 3: track audit trend; trailer coverage should rise naturally as PR gating normalizes behavior. - -
- -## Cross-Platform Support - -Charter works across WSL, PowerShell, CMD, macOS, and Linux. All git operations use a unified invocation layer with cross-platform PATH resolution. Line endings are normalized via `.gitattributes`. - -## Command Reference - -- `charter`: show repo risk/value snapshot and recommended next action -- `charter bootstrap [--ci github] [--preset ] [--yes] [--skip-install] [--skip-doctor]`: one-command onboarding (detect + setup + ADF + migrate + install + doctor) -- `charter setup [--ci github] [--preset ] [--detect-only] [--no-dependency-sync]`: detect stack and scaffold `.charter/` baseline -- `charter init [--preset ]`: scaffold `.charter/` templates only -- `charter doctor [--adf-only]`: validate environment/config state (`--adf-only` runs strict ADF wiring checks) -- `charter validate [--ci] [--range ]`: validate commit governance and citations -- `charter drift [--path ] [--ci]`: run drift scan -- `charter audit [--ci] [--range ]`: produce governance audit summary -- `charter classify `: classify change scope heuristically -- `charter hook install --commit-msg [--force]`: install commit-msg trailer normalization hook -- `charter hook install --pre-commit [--force]`: install pre-commit ADF routing + evidence gate -- `charter adf init [--ai-dir ] [--force]`: scaffold `.ai/` context directory -- `charter adf fmt [--check] [--write]`: parse and reformat ADF files to canonical form -- `charter adf fmt --explain`: show canonical formatter section ordering -- `charter adf patch --ops | --ops-file `: apply typed delta operations -- `charter adf create [--triggers "a,b,c"] [--load default|on-demand]`: create and register a module -- `charter adf bundle --task "" [--ai-dir ]`: resolve manifest and output merged context -- `charter adf sync --check [--ai-dir ]`: verify .adf files match locked hashes -- `charter adf sync --write [--ai-dir ]`: update `.adf.lock` with current hashes -- `charter adf evidence [--task ""] [--ai-dir ] [--auto-measure] [--context '{"k":v}'] [--context-file ]`: validate metric constraints and produce evidence report -- `charter adf metrics recalibrate [--headroom ] [--reason ""|--auto-rationale] [--dry-run]`: recalibrate metric baselines/ceilings -- `charter adf migrate [--dry-run] [--source ] [--no-backup] [--merge-strategy append|dedupe|replace]`: migrate existing agent config files into ADF modules -- `charter serve [--name ] [--ai-dir ]`: start an MCP server (stdio) exposing ADF context as tools and resources for Claude Code and other MCP clients -- `charter telemetry report [--period <30m|24h|7d>]`: summarize local CLI telemetry -- `charter why`: explain adoption rationale and expected payoff - -Global options: `--config `, `--format text|json`, `--ci`, `--yes`. - -## Exit Code Contract - -- `0`: success/pass -- `1`: policy violation in CI mode -- `2`: runtime/config/usage error - -## CI Integration - -- Reusable template: `.github/workflows/governance.yml` -- Generated in target repos by `charter setup --ci github`: `.github/workflows/charter-governance.yml` -- The governance workflow runs `validate`, `drift`, ADF wiring integrity (`doctor --adf-only --ci`), ADF ceiling evidence (`adf evidence --auto-measure --ci`), and `audit` on every PR. - -## Workspace Layout - -```text -packages/ - types/ Shared contracts - core/ Schemas, sanitization, errors - adf/ ADF parser, formatter, patcher, bundler, evidence pipeline - git/ Trailer parsing and risk scoring - classify/ Heuristic classification - validate/ Governance validation - drift/ Pattern drift scanning - cli/ `charter` command - ci/ GitHub Actions integration helpers +# CI mode: exits 1 if any ceiling is breached +npx charter adf evidence --auto-measure --ci --format json ``` -## Development - -- `pnpm run clean` -- `pnpm run typecheck` -- `pnpm run build` -- `pnpm run test` - -## SemVer and Stability Policy - -Charter uses [Semantic Versioning](https://semver.org/) for this repository and for published `@stackbilt/*` packages. - -Until `1.0.0`, Charter may still evolve quickly, but breaking changes should remain exceptional, deliberate, and clearly documented. The goal of `1.0.0` is simple: a connected coding agent or developer can rely on Charter's machine-facing contracts without source archaeology. - -The following surfaces are semver-governed: - -- **Package APIs** -- exported functions, classes, and types from published `@stackbilt/*` packages -- **CLI behavior** -- command names, flags, exit codes, and machine-readable `--format json` output -- **ADF behavior** -- parse, format, patch, bundle, sync, and evidence semantics -- **Generated artifacts** -- thin pointer files, `.ai/manifest.adf`, `.adf.lock`, and related scaffolded outputs -- **Governance schemas** -- evidence, audit, drift, doctor, and scorecard JSON envelopes - -Versioning rules: - -- **PATCH** -- bug fixes, docs, internal refactors, and non-breaking UX improvements -- **MINOR** -- additive commands, flags, fields, modules, templates, and advisory checks that do not break existing consumers -- **MAJOR** -- incompatible changes to CLI contracts, JSON schemas, ADF semantics, generated artifact conventions, or other machine-facing behavior that agents may rely on - -For agent-facing workflows, schema stability is treated as a core product promise, not a nice-to-have. - -## Research & White Papers - -The [`papers/`](./papers/) directory contains Charter's research narrative: - -| Entry Point | Purpose | -|---|---| -| [Papers Index](./papers/README.md) | Research papers, UX feedback, and release planning docs | -| [UX Feedback Index](./papers/ux-feedback/README.md) | Journey-bucketed ADX findings | -| [Release Plans Index](./papers/releases/README.md) | Versioned plans mapping feedback to implementation | -| [`@stackbilt/adf` API](./packages/adf/README.md) | Full ADF package API documentation | - -## Release Docs - -- `PUBLISHING.md`: first release/publish workflow -- `CHANGELOG.md`: user-visible change history -- `CONTRIBUTING.md`: contribution conventions -- `SECURITY.md`: vulnerability reporting - -## License - -Apache-2.0. See [LICENSE](./LICENSE). +## What's Next -

- - Buy me a coffee - -

+- [CLI Reference](/cli-reference) — full command surface +- [CI Integration](/ci-integration) — GitHub Actions workflow with evidence gating +- [WSL2 + Windows Filesystem](/wsl2-install) — installation and path guidance for WSL2 +- [Ecosystem](/ecosystem) — how Charter fits into the Stackbilt platform diff --git a/src/content/docs/img-forge.md b/src/content/docs/img-forge.md index 6c1b157..9fd8b36 100644 --- a/src/content/docs/img-forge.md +++ b/src/content/docs/img-forge.md @@ -9,13 +9,10 @@ tag: "09" # img-forge API -img-forge is Stackbilder's AI image generation service. Submit a text prompt, get back a generated image. Supports 5 quality tiers (SDXL through Gemini 3.1), async job queuing, and content-addressed image storage on R2. +img-forge is StackBilt's AI image generation service. Submit a text prompt, get back a generated image. Supports multiple quality tiers (Stable Diffusion XL through Gemini), async job queuing, and content-addressed image storage on R2. -img-forge is included in all Stackbilder plans with no per-image costs. Usage counts against your monthly image quota. - -**Platform UI:** [stackbilder.com/images](https://stackbilder.com/images) -**API:** `stackbilder.com/api/images/*` (authenticated, via service binding to img-forge-gateway) -**Direct gateway:** `imgforge.stackbilt.dev` (for API key / MCP access) +**Gateway:** `https://imgforge.stackbilt.dev` +**MCP Server:** `https://img-forge-mcp.blue-pine-edf6.workers.dev/mcp` ## Authentication @@ -70,6 +67,7 @@ Submit a generation request. Returns immediately with a job ID (async) or waits | `prompt` | string | Yes | — | Text description, 1–2000 characters | | `negative_prompt` | string | No | — | Things to exclude (effective on `draft` tier only) | | `quality_tier` | string | No | `standard` | `draft`, `standard`, `premium`, `ultra`, `ultra_plus` | +| `seed` | integer | No | — | Seed for reproducible generation (0–2147483647). Cloudflare tiers only. | | `sync` | boolean | No | `false` | Wait for completion before responding | | `idempotency_key` | string | No | — | Deduplication key (24h TTL) | @@ -96,6 +94,7 @@ curl -X POST https://imgforge.stackbilt.dev/v2/generate \ "enhancement_logic": "...", "asset_url": null, "error": null, + "seed_used": null, "created_at": "2026-03-04T12:00:00.000Z", "completed_at": null } @@ -122,6 +121,7 @@ Check the state of a generation job. Jobs are scoped to the authenticated tenant "enhancement_logic": "...", "asset_url": "/v2/assets/sha256hash", "error": null, + "seed_used": null, "created_at": "2026-03-04T12:00:00.000Z", "completed_at": "2026-03-04T12:00:08.000Z" } @@ -151,13 +151,13 @@ Returns `{ "status": "ok", "version": "0.2.0" }`. ## Quality Tiers -| Tier | Provider | Model | Negative Prompt | Default Size | -|------|----------|-------|-----------------|--------------| -| `draft` | Cloudflare AI | Stable Diffusion XL Lightning | Yes | 1024×1024 | -| `standard` | Cloudflare AI | FLUX.2 Klein 4B | No | 1024×768 | -| `premium` | Cloudflare AI | FLUX.2 Dev | No | 1024×768 | -| `ultra` | Gemini | Gemini 2.5 Flash Image | No | 1024×1024 | -| `ultra_plus` | Gemini | Gemini 3.1 Flash Image Preview | No | 1024×1024 | +| Tier | Provider | Model | Negative Prompt | Seed | Default Size | +|------|----------|-------|-----------------|------|--------------| +| `draft` | Cloudflare AI | Stable Diffusion XL Lightning | Yes | Yes | 1024×1024 | +| `standard` | Cloudflare AI | FLUX.2 Klein 4B | No | Yes | 1024×768 | +| `premium` | Cloudflare AI | FLUX.2 Dev | No | Yes | 1024×768 | +| `ultra` | Gemini | Gemini 2.5 Flash Image | No | No | 1024×1024 | +| `ultra_plus` | Gemini | Gemini 3.1 Flash Image Preview | No | No | 1024×1024 | ## MCP Tools @@ -188,6 +188,7 @@ Generate an image from a text prompt. Requires `generate` scope. | `prompt` | string | Yes | — | Text description, 1–2000 characters | | `quality_tier` | enum | No | `standard` | `draft`, `standard`, `premium`, `ultra`, `ultra_plus` | | `negative_prompt` | string | No | — | Exclusions (effective on `draft` tier only) | +| `seed` | integer | No | — | Seed for reproducible generation (0–2147483647). Cloudflare tiers only. | The MCP tool always uses sync mode — it returns the completed image URL directly. @@ -203,19 +204,15 @@ Check the status of a generation job. Requires `read` scope. |-----------|------|----------|-------------| | `job_id` | string (UUID) | Yes | The job ID to check | -## Usage Limits - -Image generation is included in Stackbilder plans. Limits are enforced via invisible quotas — no credits or per-image charges. - -| Plan | Monthly Images | Quality Tiers | -|------|---------------|---------------| -| Free | 5 | Draft through Premium | -| Pro | 100 | All 5 tiers | -| Team | Pooled | All 5 tiers | +## Rate Limits -Anonymous access (no auth) is rate-limited to 100 images/month per IP. +| Auth Method | Quota | Period | Enforcement | +|-------------|-------|--------|-------------| +| Anonymous | 100 images | Calendar month | Per IP, via KV | +| API key (free tier) | 100 images | Calendar month | Per tenant, via D1 entitlements | +| OAuth / MCP (free tier) | 100 images | Calendar month | Per tenant, via D1 entitlements | -When quota is exceeded, the API returns `429`. A soft warning appears at 80% usage. +When quota is exceeded, the API returns `429` with error code `QUOTA_EXCEEDED` (authenticated) or `RATE_LIMITED` (anonymous). ## Tenant Management diff --git a/src/content/docs/mcp.md b/src/content/docs/mcp.md index 7ebc162..fb4fbb7 100644 --- a/src/content/docs/mcp.md +++ b/src/content/docs/mcp.md @@ -9,9 +9,9 @@ tag: "05" # MCP Integration -Stackbilder exposes scaffold creation, image generation, and flow management as MCP-compliant tools. Connect MCP-compatible agents (Claude Code, Claude Desktop, custom agents) to generate governed codebases and images programmatically. +StackBilt exposes its 6-mode architecture workflow as an MCP-compliant remote server. Connect MCP-compatible agents (Claude Code, Claude Desktop, custom agents) to run architecture flows programmatically. -**Production endpoint:** `https://stackbilder.com/mcp` *(MCP gateway — routes to TarotScript, img-forge, and Stackbilder backends)* +**Production endpoint:** `https://stackbilt.dev/mcp` **Protocol versions:** `2024-11-05` (SSE transport) · `2025-03-26` (Streamable HTTP transport) @@ -27,9 +27,17 @@ MCP endpoints require authentication (except `GET /mcp/info`). Three methods, ch ### Unified Auth (Recommended) -Sign in via OAuth at `stackbilder.com/login` (GitHub or Google). The session cookie authenticates all MCP requests automatically. +Exchange an access key for a JWT that works at both StackBilt and Compass: -For programmatic access, use API keys (`ea_*`, `sb_live_*`) issued through edge-auth. +```bash +curl -X POST https://stackbilt.dev/api/auth/token \ + -H "X-Access-Key: ska_..." \ + -H "Content-Type: application/json" \ + -d '{"expires_in": 3600}' +# Returns: { "access_token": "eyJ...", "token_type": "Bearer", "expires_in": 3600 } +``` + +One key, both services. ## Transport Options @@ -57,7 +65,7 @@ For Streamable HTTP, sessions use the `Mcp-Session-Id` header: { "mcpServers": { "stackbilt": { - "url": "https://stackbilder.com/mcp", + "url": "https://stackbilt.dev/mcp", "transport": { "type": "streamable-http" }, "headers": { "Authorization": "Bearer " @@ -74,7 +82,7 @@ For Streamable HTTP, sessions use the `Mcp-Session-Id` header: "mcpServers": { "stackbilt": { "type": "sse", - "url": "https://stackbilder.com/mcp", + "url": "https://stackbilt.dev/mcp", "headers": { "Authorization": "Bearer " } @@ -90,7 +98,7 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js"; import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js"; const transport = new SSEClientTransport( - new URL("https://stackbilder.com/mcp"), + new URL("https://stackbilt.dev/mcp"), { requestInit: { headers: { "Authorization": "Bearer " } @@ -107,7 +115,7 @@ const result = await client.callTool("runFullFlowAsync", { }); ``` -## Native Tools (22) +## All 22 Tools ### Flow Execution @@ -151,12 +159,6 @@ const result = await client.callTool("runFullFlowAsync", { | `getGovernanceStatus` | Governance validation results, blessed patterns, persisted ADR IDs. | | `submitFeedback` | Submit bug reports, feature requests, and flow quality feedback. Params: `message` (string, required), `type` (enum: bug/feature/general/flow-quality), `rating` (number 1-5, optional), `flowId` (string, optional), `mode` (string, optional). | -## Governance - -Governance output (threat analysis, ADRs, test plans) is generated automatically as part of the scaffold process — not via separate governance tools. The `.ai/` directory ships with every scaffold created through `scaffold_create` or the flow tools. - -For Team plans, shared governance policies can be configured via the settings page at `stackbilder.com/settings`. - ## Recommended Agent Workflow The lightweight tools enable a minimal-overhead pattern: @@ -208,6 +210,77 @@ for (let i = 0; i < 6; i++) { } ``` +## Governance Integration + +Pass a `governance` config to validate architecture against blessed patterns: + +```typescript +governance: { + mode: 'ENFORCED', // PASSIVE | ADVISORY | ENFORCED + projectId: 'my-proj', // scope to project patterns + autoPersist: true, // record ADRs in governance ledger + persistTags: ['api', 'v2'], + qualityThreshold: 80, // 0-100 + transport: 'auto', // external_http | service_binding | auto + transportCanaryPercent: 5 // canary rollout percentage +} +``` + +| Mode | Behavior | +|------|----------| +| `PASSIVE` | Log only — never blocks | +| `ADVISORY` | Warn on issues, flow continues | +| `ENFORCED` | Block on FAIL, require remediation | + +Plan-tier caps: free plans are capped at PASSIVE, pro at ADVISORY, enterprise gets full ENFORCED. + +### Advanced Governance Sub-configs + +Three optional sub-configs extend the base governance object: + +**`domainLock`** — Locks domain entities after PRODUCT mode completes, preventing drift in downstream modes. + +```typescript +governance: { + // ...base config... + domainLock: { + enabled: true, // Enable/disable domain locking + strictness: 'strict', // 'strict' | 'advisory' | 'off' + noNewEntities: true, // Prevent creation of new domain entities + allowVendors: ['stripe', 'sendgrid'], // Vendor allowlist + forbidVendors: ['twilio'], // Vendor blocklist + requireTerms: ['Order', 'Customer'], // Domain terms that must appear + forbidTerms: ['User', 'Account'], // Domain terms that must not appear + } +} +``` + +**`qualityByMode`** — Per-mode quality thresholds. Overrides the top-level `qualityThreshold` for specific execution modes, letting you enforce tighter standards on critical modes. + +```typescript +governance: { + // ...base config... + qualityByMode: { + ARCHITECT: 90, + TDD: 85, + CODE: 80, + } +} +``` + +**`qualityWeighting`** — Hybrid local/CSA weighting for quality evaluation. Controls the balance between local static analysis and Compass governance scoring when computing the final quality score. + +```typescript +governance: { + // ...base config... + qualityWeighting: { + local: 0.4, // Weight given to local analysis (0.0–1.0) + csa: 0.6, // Weight given to Compass governance scoring (0.0–1.0) + } +} +``` + +All three sub-configs are independent and can be combined freely within a single governance object. ## Error Handling diff --git a/src/content/docs/platform.md b/src/content/docs/platform.md index bbe2d53..1639e28 100644 --- a/src/content/docs/platform.md +++ b/src/content/docs/platform.md @@ -7,94 +7,125 @@ color: "#f472b6" tag: "04" --- -# Stackbilder Platform +# StackBilt Platform -Stackbilder generates governed, production-ready codebases from plain-language descriptions. The architecture uses a two-phase approach: a deterministic skeleton with governance output (Phase 1), and optional LLM-powered code polish (Phase 2). +> **Architect v2 — Active Build.** The platform is in its v2 build cycle. Docs reflect the current stable surface; new capabilities are landing continuously. -## Two-Phase Architecture +StackBilt is a governance-enforced architecture planning tool that produces sprint-ready ADRs, deployable scaffolds, and structured artifacts — not vague suggestions. -### Phase 1: Deterministic Skeleton (TarotScript) +## The 6-Mode Pipeline -Your intention is processed in two deterministic steps: +Architecture generation runs through six sequential modes. Each mode builds on the previous, with cross-references via sequential IDs. -1. **Classify** — TarotScript maps your description against a vocabulary deck, producing a pattern classification (e.g., "stripe", "github", "mcp", "rest") with confidence scoring. +| Phase | Mode | Output | IDs | +|-------|------|--------|-----| +| Definition | **PRODUCT** | Product Requirements Document | REQ-001, SLA-001, CON-001 | +| Definition | **UX** | User journey maps and experience flows | UJ-001 | +| Definition | **RISK** | Risk assessment and value model | RISK-001 | +| Architecture | **ARCHITECT** | Technical blueprint: services, schemas, boundaries | COMP-001, DS-001 | +| Execution | **TDD** | Test strategy per component | TS-001 | +| Execution | **SPRINT** | Sprint-ready ADRs with dependency graph | ADR-001 | -2. **Scaffold-Cast** — A deterministic spread generates the full project skeleton: file structure, config files, and the `.ai/` governance suite. +## Structured Artifacts (v2) -**Performance:** ~20ms. Zero inference cost. Same input = same output. +Every mode emits a typed JSON artifact alongside prose. These artifacts use sequential, referenceable IDs that chain across modes: -**Output includes:** -- Project structure and configuration -- `.ai/threat-model.md` — STRIDE-based security threat analysis specific to your architecture -- `.ai/adr-*.md` — Architectural decision records with context, alternatives, and consequences -- `.ai/test-plan.md` — Integration and unit test specifications with coverage targets -- Architectural constraints — machine-readable guardrails for Phase 2 +- PRODUCT defines `REQ-001`, `SLA-001`, `CON-001` +- ARCHITECT references `reqRefs: ["REQ-001"]`, `riskRefs: ["RISK-001"]` +- TDD validates `slaRefs: ["SLA-001"]` +- SPRINT produces ADRs that trace back to components and requirements -### Phase 2: LLM Polish (Pro tier) +Each artifact includes a `confidence` field with an overall score (0-100) and a `missing[]` array surfacing what the AI was not told. -Takes the Phase 1 skeleton and generates idiomatic, production-grade code using Cerebras fast inference. The differentiator: the LLM works *within* the governance constraints from Phase 1. +## Cross-Mode Contradiction Checker -Phase 2 is optional and only available on Pro and Team plans. +After each mode completes, an incremental checker runs 8 validation rules: -## Governance Output +- Every `MUST` requirement has a component covering it +- Every SLA has a validation entry in TDD +- Every `CRITICAL`/`HIGH` risk has a test scenario +- ARCHITECT doesn't use technologies RISK marked as blocked +- Named events appear consistently across modes +- SPRINT surfaces requirements with no ADR -Every scaffold ships with governance — it's not a separate product or add-on. The `.ai/` directory is generated deterministically in Phase 1. +Results are available via the API as a `contradictionReport`. -| File | Content | -|------|---------| -| `threat-model.md` | STRIDE analysis: spoofing, tampering, repudiation, information disclosure, denial of service, elevation of privilege — specific to your architecture | -| `adr-*.md` | Architectural decision records: the "why" behind non-obvious choices, with alternatives considered | -| `test-plan.md` | Test specifications: integration scenarios, unit test targets, coverage goals, framework recommendations | -| `constraints.json` | Machine-readable guardrails that Phase 2 LLM must respect | +## Scaffold Engine -## Plan Tiers +Completed flows can generate a deployable Cloudflare Workers project (9-15 files). The scaffold engine uses category-aware routing: -Flat pricing. No credits, no tokens, no per-action charges. +| Component Category | Generated File | +|-------------------|----------------| +| compute / data / integration | `routes/*.ts` (CRUD stubs) | +| async | `worker/*-queue.ts` (queue handlers) | +| security | `worker/middleware/*.ts` (auth middleware) | +| frontend | skipped | -| | Free | Pro | Team | -|---|---|---|---| -| **Price** | $0 | $29/mo | $19/seat/mo | -| **Scaffolds/mo** | 3 | 50 | 50/seat | -| **Images/mo** | 5 | 100 | Pooled | -| **Phase 1** | Yes | Yes | Yes | -| **Phase 2 (LLM polish)** | No | Yes | Yes | -| **Quality tiers (img-forge)** | Draft-Premium | All 5 | All 5 | -| **Stacks** | Cloudflare Workers | All supported | All supported | -| **Governance output** | Yes | Yes | Yes | +Template types: `workers-crud-api`, `workers-queue-consumer`, `workers-durable-object`, `workers-websocket`, `workers-cron`, `pages-static`. -Usage is enforced via invisible quotas through edge-auth. Users see "X scaffolds remaining" at 80% usage, with a hard wall and upgrade CTA at 100%. +Scaffolds include `scaffoldHints` (template classification + confidence score) and `nextSteps` (deployment commands). -## Supported Stacks +## Governance Integration -Cloudflare Workers is the currently available stack. Multi-stack expansion is on the roadmap: +When running a governed flow, architecture decisions are validated against blessed patterns via Compass. Violations are flagged depending on governance mode. -| Stack | Status | -|-------|--------| -| Cloudflare Workers (D1, KV, R2, DO) | Available | -| Vercel / Next.js (App Router, Edge Runtime) | Roadmap | -| AWS Lambda (API Gateway, DynamoDB) | Roadmap | -| Supabase Edge Functions (Postgres) | Roadmap | -| Deno Deploy (Fresh, KV) | Roadmap | +| Mode | Behavior | Plan Tier | +|------|----------|-----------| +| `PASSIVE` | Log only — never blocks | Free | +| `ADVISORY` | Warn on issues, flow continues | Pro | +| `ENFORCED` | Block on FAIL, require remediation | Enterprise | -## API +Blessed patterns from Compass are injected into the ARCHITECT mode prompt automatically. Governance results (validations, persisted ADR IDs, warnings) are available via `getGovernanceStatus`. -Stackbilder exposes server-side API routes at `stackbilder.com/api/*`. These call TarotScript and img-forge via Cloudflare service bindings (zero HTTP hop, same-colo execution). +### Advanced Governance Configurations -| Endpoint | Method | Purpose | -|----------|--------|---------| -| `/api/flows` | GET | List user's scaffold flows | -| `/api/flows` | POST | Classify + scaffold-cast a new flow | -| `/api/flows/:id` | GET | Get flow detail (artifacts, governance, scaffold) | -| `/api/images/generate` | POST | Create an image generation job | -| `/api/images` | GET | List user's image jobs | -| `/api/images/:id` | GET | Get image job status | +For Compass route taxonomy and auth/MCP endpoints, see [Compass Governance API](/compass-governance-api). -All API routes require authentication via `better-auth.session_token` cookie. Session validation runs through an RPC binding to edge-auth. +Enterprise plans unlock additional governance options: -See [API Reference](/api-reference) for full request/response documentation. +- **Domain Locking** (`domainLock`) — Locks domain entities after PRODUCT mode to prevent drift. Supports strictness levels, entity creation controls, and vendor allow/block lists. +- **Per-Mode Quality Thresholds** (`qualityByMode`) — Set different minimum quality scores per execution mode. +- **Quality Weighting** (`qualityWeighting`) — Hybrid local/CSA weighting for quality evaluation. + +## Plan Tiers & Quotas + +Every access key is associated with a plan tier that determines rate limits and feature access. + +| Quota | Free | Pro | Enterprise | +|-------|------|-----|------------| +| AI calls per day | 50 | 500 | Unlimited | +| Flow runs per day | 10 | 100 | Unlimited | +| Scaffolds per day | 1 | 10 | Unlimited | + +## AI Model Routing + +The platform applies a model policy per request. By default, provider/model selection is tier-aware (with per-request overrides and fallback chains available internally). + +| Plan | Default Provider | Model | +|------|-----------------|-------| +| Free | Gemini | `gemini-2.5-flash-lite` | +| Pro | Gemini | `gemini-2.5-pro` | +| Enterprise | Anthropic | `claude-sonnet-4-6` | + +Premium-tier model access is enforced by plan. Users can also configure a personal Groq API key for supported flows/endpoints. + +## Output Artifacts + +Each completed flow produces: + +- **PRD** — structured product requirements with `REQ-001` IDs +- **Experience Maps** — user journeys and touchpoints +- **Risk Model** — value assessment, compliance flags, blocked patterns +- **Architecture Blueprint** — services, data contracts, component tree with cross-refs +- **TDD Strategy** — test surface per component with SLA validation +- **Sprint ADRs** — executable sprint plan with Architecture Decision Records +- **Scaffold** — deployable Workers project (on demand) +- **Contradiction Report** — cross-mode consistency validation ## Access -- **Browser** at [stackbilder.com](https://stackbilder.com) -- **API** at `stackbilder.com/api/*` (authenticated server routes) -- **MCP** via the Stackbilt MCP gateway (see [MCP Integration](/mcp)) +Access StackBilt via: + +- **Browser UI** at [stackbilt.dev](https://stackbilt.dev) — interactive flow builder +- **MCP Server** — programmatic agent-driven workflows (see [MCP Integration](/mcp)) +- **REST API** — direct HTTP integration (see [API Reference](/api-reference))