AI Development Blueprint Generator

Structured capability contract (graph schema 2.0)

capabilityPolicy[] is the only capability authority. Each bounded entry has capabilityId, REQUIRED|ALLOWED|FORBIDDEN, and explicit source/evidence IDs; required/allowed/forbidden lists are derived views and are not graph fields. Every implementation-bearing node in the eleven supported collections requires capabilityRefs (including []). Typed API/entity/auth/storage dependencies, unknown IDs, missing refs, duplicate/conflicting dispositions, forbidden refs, and implementation-bearing OUT_OF_SCOPE nodes fail closed.

Descriptions, purposes, notes, observations, evidence excerpts, and other free text are inert context. They are not parsed as capability security policy and cannot populate AGENTS.md, CODEX_INSTRUCTIONS.md, implementation tasks, or API rules. Context Markdown is JSON encoded with fence-breaking backticks escaped; frontend context is serialized as JSON data rather than executable JSX/HTML/CSS.

Normal PREPARE/COMPILE/Generate/Validate paths accept canonical graph schema 2.0. Legacy graph schema 1.0 is not silently accepted. The one approved historical packet/graph pair can be converted only by the explicit hash-bound adapter; ambiguity returns MIGRATION_NEEDS_AGENT_CORRECTION. This is a deterministic structured compiler, not a general natural-language security interpreter. Future legacy packets are not auto-migrated: they require a new, reviewed, explicitly versioned exact adapter or a fresh schema-2.0 PREPARE and external-agent graph.

What this Actor does

Turn project briefs or AI-authored canonical project graphs into consistent, traceable development blueprints. The Actor is a deterministic compiler, validator, renderer, and packager—not another required AI model and not a deployed customer application.

It generates linked requirements, business rules, flows, screens, design tokens, component contracts, conditional API/database specifications, acceptance criteria, planned tests, a representative React/TypeScript starter, AGENTS.md, development instructions, manifest, and PROJECT_BLUEPRINT.zip.

For AI agents

The primary caller is an external coding agent such as Codex, Claude Code, Cursor Agent, Gemini-family agents, OpenAI agents, or another MCP/API client. The external agent performs reasoning and writes candidateGraph; this Actor enforces the canonical contract and creates the package.

All core results are machine-readable. See AGENT_CONTRACT.md for ownership, trust boundaries, statuses, and finding shape.

Agent mode — no API key required

Agent mode is the default. Omitted mode and operation mean agent / prepare.

• prepare: Convert a project brief into a constrained generation packet and canonical graph contract for an external AI agent. No model API key required.
• compile: Validate and compile an AI-authored canonical project graph into a traceable development blueprint, design system, starter, and handoff package.
• validate: Use mode=validate to validate an existing blueprint graph/package for traceability, consistency, design-token fidelity, and artifact integrity.

Agent-mode OpenAI/customer-model calls: 0. Actor-internal Codex calls: 0. Agent keys and model options are rejected. PREPARE may fetch declared public HTTPS sources only when the user explicitly consents; COMPILE never re-fetches packet sources.

PREPARE → COMPILE example

PREPARE:

{
  "mode": "agent",
  "operation": "prepare",
  "language": "en",
  "project": {
    "name": "Tiny Tasks",
    "brief": "A small task list for individual users with create, complete, and delete flows.",
    "contextType": "greenfield",
    "targetUsers": ["individual"],
    "goals": ["track tasks"],
    "mustHave": ["create task"],
    "mustNotHave": ["payment", "admin"]
  },
  "capabilityPolicy": [
    { "capabilityId": "LOCAL_STORAGE", "disposition": "ALLOWED", "evidenceRefs": [] },
    { "capabilityId": "PAYMENT", "disposition": "FORBIDDEN", "evidenceRefs": ["SRC-PROJECT-BRIEF"] }
  ],
  "privacy": {
    "allowExternalLlmProcessing": false,
    "allowPublicWebsiteFetch": false,
    "sourceRightsConfirmed": true
  }
}

The READY_FOR_AGENT output includes the inline packet, its packetId/content hash, immutable source evidence, canonical graph schema, rules, and completion criteria. Give that packet—not hidden extra brief context—to the external agent.

COMPILE in a separate run:

{
  "mode": "agent",
  "operation": "compile",
  "packetId": "AGP-...",
  "candidateGraph": { "...": "external agent canonical graph" }
}

The Actor resolves packetId only from its Actor-owned KVS READY record. COMPILE rejects caller-supplied packets, repositories, readers, resolvers, authority objects, and unrelated fields. Structural findings return AGENT_CORRECTION_REQUIRED with code, nodeId, and requiredFix. Provenance or contradiction findings return QUALITY_FAILED; genuine unresolved user choices return NEEDS_DECISION.

Output package

Successful COMPILE stores BLUEPRINT, BLUEPRINT_PACKAGE, ARTIFACT_MANIFEST, QUALITY_REPORT, and optional PREVIEW_HTML, then lists only successfully stored records in OUTPUT.artifacts. The ZIP contains blueprint.json, manifest.json, connected documents/contracts, design assets, starter, and QA records under PROJECT_BLUEPRINT/.

Representative screens use explicit mock data. Domain-specific components are contracts unless starter coverage says they are implemented. Test cases remain PLANNED.

Validation guarantees

COMPILE reuses the strict canonical JSON schema, provenance/evidence checks, source identity checks, explicit user-decision checks, exclusion/contradiction detection, typed relationship validation, requirement-to-acceptance/test mapping, conditional screen/API/entity checks, DTCG token/component validation, deterministic renderer, and manifest/ZIP path handling.

ZIP validation bounds encoded, archive, entry, and expanded sizes; rejects unsafe/duplicate paths; checks CRC, schema, exact manifest enumeration, bytes/hashes, graph quality, and deterministic graph/artifact equality. It is not a customer backend run, browser certification, full WCAG audit, or proof that planned tests passed.

Optional human/BYOK Generate mode

An API key is only required for optional Generate mode. It must be selected explicitly with mode=generate and operation=generate; provider=openai is the only accepted provider value. Contradictory or omitted mode/provider is rejected before provider construction. Generate retains the fixed customer-BYOK OpenAI Responses path (gpt-5.6-sol, medium, store:false), bounded call/token/USD ledger, repair ceiling, and uncertain-call hard stop.

The key is the customer's OpenAI API key, not a developer Codex login. Customer requests never call back to the developer's computer. Actual customer API runtime remains unverified; no live Generate claim is made.

Pricing

Agent-mode proposal: charge for deterministic compilation/validation and successful ZIP delivery, with no model API cost from this Actor. Generate-mode proposal: the Actor charge plus the customer's separate BYOK model bill. Pricing is a draft only and has not been applied; see PRICING_PROPOSAL.md.

Security

Source snapshots are inert and never installed/executed. Generated customer/model text is serialized as data rather than inserted into JSX/HTML/CSS syntax. Public-source collection retains HTTPS, DNS/IP, redirect, timeout, and SSRF controls. Agent mode forbids provider keys/options and has no internal model repair. See SECURITY_REVIEW.md.

Limitations

Local deterministic Agent contract tests use fixtures; a fake provider or hand-authored graph is not genuine external-agent/API/Apify evidence. This local turn did not run external agents, paid APIs, Apify, Docker/services, an independent focused reviewer, or publication/pricing/icon mutations. AGENT_MODE_VERIFIED, APIFY_PRIVATE_AGENT_VERIFIED, OPTIONAL_BYOK_GENERATE_VERIFIED, and SELLABLE_READINESS remain NO pending the separate host workflow. No sellability claim is made.

Local checks:

pnpm typecheck
pnpm build
pnpm test
pnpm audit --prod --audit-level high