# ChatStack — Full Reference

> Canonical agent-facing reference for ChatStack. Dense, no marketing copy. Source of truth for agents that do not follow the marketing HTML. For interactive schemas see `/openapi.json`. For plugin metadata see `/.well-known/ai-plugin.json`. For capability discovery see `/api/agent`.

## Identity

- Name: ChatStack
- Canonical origin: `https://www.chatstack.app`
- Operator: App Developer Studio
- Product category: AI PRD generator + software cost estimator
- Target users: founders, product managers, and engineers using AI coding tools (Cursor, Claude Code, Windsurf, MCP-aware IDEs)

## Product summary

ChatStack converts an unstructured project brief into four structured JSON artifacts plus a story-point cost estimate. The human path is a chat interview at `/`. The agent path is a single authenticated POST to `/api/agent/submit`. All outputs are machine-readable and designed to be ingested as context by AI coding tools.

## The 4-agent workflow

1. User Story Agent — elicits persona-driven user stories in the canonical "As a <user_type>, I want <goal> so that <benefit>" format; emits `stories_json_approved`.
2. Functional and NFR Agent — derives functional requirements (`FR-<n>`), non-functional requirements (`NFR-<n>`), and assumptions (`ASS-<n>`); emits `requirements_json_approved`.
3. Technical Specs Agent — produces architectural decisions per area (Authentication, Database, Frontend, API, Infrastructure, etc.); emits `techspec_json_approved`.
4. Cost Estimate Agent — assigns story points per story, converts to hours and cost, applies the AI efficiency discount; emits `estimate_json`.

## Cost model

- `cost_before_discount = story_points * rate_per_point`
- `cost_after_discount  = cost_before_discount * (1 - ai_efficiency_discount)`
- Default `ai_efficiency_discount = 0.65` reflecting empirically measured rework reduction when AI coding tools receive high-fidelity structured PRD context.
- `rate_per_point` and `currency` are declared in `estimate_json.meta`.
- Totals are aggregated across `rows[]` in `estimate_json.totals`.

## Artifact contract

Required for a successful submission:

- `artifacts.stories_json_approved` — `{ stories: UserStory[], global_nfr?: string[] }`
- `artifacts.requirements_json_approved` — `{ requirements: Requirement[] }`
- `interview_summary` — plain-text brief, 20+ characters, ideally 2 to 5 sentences.

Strongly recommended:

- `artifacts.techspec_json_approved` — `{ specifications: TechSpec[] }`
- `artifacts.estimate_json` — `{ meta, rows[], totals, assumptions?, risks? }`

Contact fields (used to match or create a portal account when provided): `first_name`, `last_name`, `email`, `country`, `message`.

Full JSON schemas are at `https://www.chatstack.app/openapi.json`. Agents must not JSON-stringify nested objects; they must submit JSON objects directly.

## ID conventions

- User stories: `US-<n>` (e.g. `US-1`). Sequential, stable across submissions.
- Functional requirements: `FR-<n>`.
- Non-functional requirements: `NFR-<n>`.
- Assumptions: `ASS-<n>`.
- Technical specifications: `TS-<n>`.
- Estimate rows: `id` matches a user story ID for traceability.

## Agent API

- Discovery: `GET https://www.chatstack.app/api/agent` → JSON with capabilities, auth model, rate limits, schema URL.
- Submit: `POST https://www.chatstack.app/api/agent/submit`.
- Auth: `Authorization: Bearer <AGENT_API_KEY>`. Keys are issued on request via `/speak-to-a-human`.
- Content-Type: `application/json` required. Non-JSON returns HTTP 415.
- Max payload: 10 MB. Larger returns HTTP 413.
- Rate limit: 5 submissions per hour per IP (HTTP 429 when exceeded). Enterprise keys can have higher limits.
- Success: HTTP 200 with `{ ok: true, id, project_id?, version_id?, warnings? }`.
- Validation failure: HTTP 400 with `{ error, details }`.

This endpoint is intentionally agent-first. It is server-to-server only (no browser CORS). The browser-facing chat interview at `/` remains the recommended human path.

## Integrations

- Cursor `.cursorrules`: ChatStack provides opinionated rules for observability, security, and testing, derived from the PRD.
- Claude Code: same JSON PRD drives prompt context.
- Model Context Protocol (MCP): the JSON PRD is designed to be served over MCP in IDE tooling so that requirements stay out of the chat window.

## Output formats

- JSON (primary, canonical)
- Markdown (human-readable render of JSON, per page under `/<slug>.md`)
- CSV (estimate tables, on request)
- `.cursorrules` snippet (derived)

## Privacy and data use

Submissions are used solely to generate the requesting project's PRD and portal record. User data is not used to train third-party LLMs. Bring-your-own-NDA is supported; see `/non-disclosure-and-tcs`.

## Crawler and agent policy

- `robots.txt` allows all well-behaved crawlers and LLM training agents on HTML and Markdown.
- `Disallow: /api/` except `/api/agent` (public discovery GET).
- `POST /api/agent/submit` requires an API key and is not meant for crawling.

## Canonical URLs

- Home: `https://www.chatstack.app/`
- Machine-readable: `/llms.txt`, `/llms-full.txt`, `/openapi.json`, `/.well-known/ai-plugin.json`, `/ai-dataset.json`, `/sitemap.xml`
- API: `/api/agent` (GET), `/api/agent/submit` (POST, auth)
- Marketing Markdown: `/<slug>.md` for every page listed in `/sitemap.xml`

## Glossary

- PRD — Product Requirements Document.
- Story point — agile unit of relative effort; here translated to hours via `rate_per_point`.
- AI efficiency discount — fractional reduction applied to pre-discount cost to reflect productivity gains from structured context.
- Vibe coding — AI-assisted coding where human intent is conveyed conversationally; requires strong context discipline.
- Context drift — loss of project context across long AI-assisted sessions; mitigated by structured PRDs and MCP.