--- name: blueprint description: Conversational interview skill that bridges the "I want to build X" to "here are tickets" gap. It classifies the idea against an archetype, designs a complete architecture using the knowledge base, produces a self-contained blueprint markdown, and emits a structured requirements.json directly for import into the ticket database. Use this skill when a user describes an idea for a new project and needs an opinionated architecture and a path to tickets. --- # Blueprint Skill **Version**: 1.0.0 **Category**: Design **Type**: Conversational (no script, prompt-driven) **Session Duration**: 10-25 minutes ## Purpose Artifex's existing flow assumes tickets already exist — `afx-ticket-manager` needs a `requirements.json`, and `afx-ticket-implementation` needs a ticket to work on. Neither bridges the starting point: **"I have an idea and I don't know what to build yet."** `afx-blueprint` fills that gap. It interviews the user, classifies the idea against one of the six archetypes, designs a complete stack-structure-data-model-API-build-order architecture using the knowledge base, and produces two artifacts side by side: 1. A self-contained blueprint markdown — the human design document. Can be handed to a fresh Claude Code instance with zero prior context and built from scratch. 2. A `requirements.json` — the machine handoff. Generated directly by this skill (no intermediate converter step) and ready to import via `afx-ticket-manager import`. This is **not** the same as `afx-project-init`, which bootstraps documentation *inside an existing project directory*. `afx-blueprint` produces a full greenfield design *before the project exists*. ## Workflow The skill runs in five phases. **Phases 1-3 are mandatory** — the architecture must be confirmed before the blueprint is generated. Phases 4 and 5 always run together: the markdown blueprint and the `requirements.json` are produced in the same turn. ### Phase 1: DISCOVERY (≤3 questions, classify into archetype) Start with one open-ended Vision question: > "What are you building? Give me a sentence or two — what it is, who it's for, and what problem it solves." Listen for signal keywords and map to an archetype: | Keywords in the user's description | Archetype | | --------------------------------------------------------------------- | --------------------- | | "SaaS", "subscription", "multi-tenant", "dashboard", "billing" | `saas-webapp` | | "API", "backend for", "service for", "microservice", "webhook" | `api-backend` | | "landing page", "waitlist", "marketing site", "brochure", "pre-launch"| `marketing-site` | | "iOS app", "Android app", "mobile app", "React Native", "Expo" | `mobile-app` | | "admin dashboard", "internal tool", "ops console", "back-office" | `internal-tool` | | "blog", "docs site", "knowledge base", "CMS", "content" | `content-platform` | If the first answer is ambiguous, ask **at most two** clarifying questions: 1. "Who is this for?" (audience — devs, end users, internal team, the public) 2. "Is this a prototype you want to explore, or something you plan to ship to users?" (stage) **Announce the classification explicitly** before proceeding: > "Got it. I'm classifying this as a **saas-webapp**. I'm going to load the default stack and ask a handful of targeted questions to fill in what the archetype can't tell me. If that's wrong, say so now." **Then read the archetype file:** ``` docs/knowledge/archetypes/.md ``` Resolve the path to an absolute location (the knowledge base lives in the Artifex SDK install). Extract the default stack, directory structure, key decisions, and gotchas. If the user describes a hybrid (e.g., "a SaaS with a marketing landing page"), pick the **primary** archetype (where the business logic lives) and note the secondary — it'll show up as an additional top-level directory in the structure, not a second stack. If the idea is genuinely unclassifiable, say so and fall back to a full open interview. Never force a bad classification. ### Phase 2: DEEP DIVE (3-5 targeted questions from the archetype) Ask only the questions the archetype can't answer on its own. Never more than 5 questions total in this phase. One or two questions per message — keep it conversational. Adapt to the archetype: **saas-webapp:** 1. Core data model — "What are the main entities? Users, plus what else? (e.g., Workspaces, Projects, Documents)" 2. Auth & teams — "Single-tenant or multi-tenant? Teams/workspaces with roles, or flat users?" 3. Payments — "Subscriptions (Stripe Billing), one-time (Stripe Checkout), usage-based, or none yet?" 4. Real-time — "Anything live — presence, collaborative editing, notifications? Or can everything be request/response?" 5. Third-party integrations — "What external APIs or services do you need to talk to?" **api-backend:** 1. Main resources — "What are the core resources this API exposes?" 2. Auth strategy — "OAuth2/JWT, API keys, mTLS, or no auth (internal only)?" 3. Persistence — "PostgreSQL + jOOQ is the default. Does that work, or do you need something else (Mongo, Dynamo, event store)?" 4. Rate limiting — "Public API that needs per-consumer quotas, or internal only?" 5. Consumers — "Who's calling this? Browser, mobile, other services, partners?" **marketing-site:** 1. Page count and structure — "Single landing, or multi-page (Pricing, About, Features, Blog)?" 2. Content source — "File-based (MDX in-repo) or headless CMS (Sanity, Contentful, Prismic)?" 3. Lead capture — "Waitlist email, demo request form, Calendly embed, nothing?" 4. Analytics — "Plausible, Posthog, GA4, or none?" **mobile-app:** 1. Platform — "iOS-only, Android-only, or cross-platform (Expo/React Native)?" 2. Backend — "New backend, existing API, or BaaS (Supabase, Firebase)?" 3. Offline support — "Fully offline-capable, offline-friendly with sync, or always-online?" 4. Push notifications — "Yes/no, and which provider (APNs, FCM, OneSignal)?" **internal-tool:** 1. User count and SSO — "How many users? Google/Microsoft SSO, or is email+password enough?" 2. Data complexity — "Simple CRUD, or rich filtering/sorting/bulk operations on large tables?" 3. Audit logging — "Who changed what, when? Required, nice-to-have, or not needed?" 4. Integrations — "Which internal systems does it need to talk to?" **content-platform:** 1. Content types — "Just articles, or multiple types (posts, guides, tutorials, case studies)?" 2. Search — "Full-text search required? Client-side (Pagefind), server-side (Meilisearch), or third-party (Algolia)?" 3. i18n — "Single language, or multiple locales?" 4. CMS — "File-based (MDX in-repo) or headless CMS?" **As questions are answered, read relevant building-block files** so the architecture proposal cites real patterns: - Always read: `docs/knowledge/stack-compatibility.md` (before Phase 3) - For any archetype with a backend: `docs/knowledge/building-blocks/auth-patterns.md`, `database-patterns.md`, `api-design-patterns.md`, `testing-patterns.md`, `observability-patterns.md` - For anything deployed: `docs/knowledge/building-blocks/deployment-patterns.md`, `iac-patterns.md`, `ci-cd-patterns.md` - For frontend-bearing archetypes: `docs/knowledge/building-blocks/styling-systems.md`, `state-management.md` Don't dump building-block content at the user. Use it silently to inform the architecture proposal in Phase 3. ### Phase 3: ARCHITECTURE (present, validate, confirm) Present the proposed architecture as a single cohesive proposal. Structure: 1. **Stack** — a table with columns `Layer | Technology | Rationale`. One recommendation per layer. No menus. If the archetype default applies, use it and explain briefly. If you're deviating, explain why. 2. **Directory structure** — a code block showing the top-level layout with inline comments on each directory. 3. **Data model** — a short bulleted list of entities and relationships. No DDL yet. 4. **API shape** — 5-10 representative routes in a table (method, path, description, auth). 5. **Build order (high level)** — 5-8 numbered milestones (e.g., "Scaffold backend", "Add auth", "Add first resource", "Wire frontend", "Deploy to staging"). The full detailed build order goes into the blueprint file itself. 6. **Key decisions** — 3-5 bullets on opinionated calls ("jOOQ, not JPA", "contract-first OpenAPI", "multi-tenant via tenant_id column", etc.) **Validate the stack against `docs/knowledge/stack-compatibility.md`** before presenting. If any combination is on the known-bad list, flag it explicitly in the proposal and recommend the proven alternative. For example, if the user insisted on JPA and the compatibility matrix flags JPA + jOOQ + Kotlin as a known-bad combo, say so and recommend jOOQ alone. **Be opinionated.** Frame as "Here's what I'd build" not "Here are your options." Recommend ONE default per layer and explain the tradeoff in one sentence. **Prefer JVM stacks** per the knowledge base defaults: - Backend: Spring Boot 4 + Kotlin 2.3 + Java 25, Gradle Kotlin DSL, jOOQ (never JPA/Hibernate for new services), Flyway migrations, Spring Security OAuth2 RS256 JWT, Testcontainers. - Never recommend Python for general backend work. Python is only for narrow data-engineering paths the user explicitly signals. - Frontend (only when genuinely needed): Next.js 15 + Tailwind v4 + shadcn/ui + pnpm. After presenting, ask explicitly: > "Does this look right? Reply **OK** to generate the blueprint, or tell me what to adjust (e.g., 'swap Postgres for MySQL', 'drop the frontend', 'use Dagger instead of Spring')." **Do not generate the blueprint file until the user approves.** This is non-negotiable. ### Phase 4: GENERATE (write the blueprint file) Once the architecture is confirmed: 1. Read `templates/blueprint.md.template` (resolve to the absolute path in the Artifex SDK install). 2. Compose the complete blueprint by filling every `{PLACEHOLDER}` in the template. Every section must be filled — if a section genuinely doesn't apply (e.g., "Frontend Architecture" for a pure API backend), write "Not applicable — this is a headless API." Do not delete sections. 3. Numbered build order is the most critical section. It must contain **10-20 ordered steps from zero to deployed**, each with a clear deliverable. A fresh Claude Code instance must be able to follow these steps in order and end up with a working project. 4. Include a complete CLAUDE.md for the target project inside the blueprint (the template has a slot for it) — this gets dropped into the target project's root when scaffolding starts. 5. Ensure `.artifex/tmp/` exists in the current working directory. If not, create it with `mkdir -p .artifex/tmp`. 6. Write the blueprint to `.artifex/tmp/-blueprint.md` (slugified project name). **Never write to the repository root.** 7. Proceed immediately to Phase 5 — the requirements.json is generated as part of the same run, not as an optional follow-up. ### Phase 5: GENERATE requirements.json (always run, alongside the markdown) Immediately after writing the blueprint markdown in Phase 4, generate `requirements.json` directly. **Do not invoke any converter skill** — this skill owns JSON generation end-to-end. **Mapping rules:** each top-level blueprint section (Tech Stack, Data Model, API Design, Auth, Infrastructure, CI/CD, Frontend, Build Order, Observability) becomes an **epic**. Cross-cutting concerns (Auth, Infrastructure, Observability) always get their own epic — never folded into Build Order. Each numbered build-order step (or discrete deliverable inside a section) becomes a **story** inside the most relevant epic. IDs follow the project's existing scheme if established, otherwise numeric strings: epics `"1"`, `"2"`; stories `"1.1"`, `"1.2"`, `"2.1"`. **Schema fields — every field MUST be populated at generation time. Nothing deferred:** - **`id`** — numeric string (`"1"`, `"1.1"`) unless the project carries an existing scheme. - **`title`** — short imperative phrase. - **`description`** — design rationale pulled from blueprint prose, Key Decisions, Gotchas, and section intros. Capture WHY the story exists. **Never empty** unless there is genuinely zero context to record. - **`complexity`** — concrete value: `Low`, `Medium`, `High`, or `Very High`. Judge each story individually. **Do NOT auto-default to Medium.** A scaffold is `Low`; Stripe billing with webhooks is `High`; a multi-tenant migration is `Very High`. - **`implementation_order`** — explicit integer in **global topological order across all epics**. First story to implement is `1`, next is `2`, regardless of epic. Array order matches the integer. - **`acceptance_criteria`** — array of Gherkin strings, **one scenario per entry**, each matching `Given ... When ... Then ...`. 3-7 per story, grounded in file existence, command output, test results, or user-observable behavior. No bullets, no plain assertions. - **`technical_notes`** — array of one-line strings, one per entry. Concrete, non-obvious constraints from Key Decisions and Gotchas (`"Use jOOQ, not JPA"`), not generic instructions. Walk the build order end to end before emitting the JSON. If story `2.1` (Auth) must precede story `1.3` (Build Order) in the dependency chain, it gets the lower `implementation_order`. Each epic's `user_stories` array stays sorted by that integer. Write the file to `.artifex/tmp/requirements-.json` (slugified name, matching the blueprint filename). Both files coexist — markdown for humans, JSON for the import pipeline. **Example** (2 epics, 3 stories): ```json { "epics": [ { "id": "1", "title": "Backend Foundation", "description": "Stand up the Spring Boot service with Postgres, jOOQ, and Flyway. Every feature story depends on this skeleton and green CI before any feature work begins.", "user_stories": [ { "id": "1.1", "title": "Scaffold Spring Boot project", "description": "Greenfield project needs a runnable Kotlin + Spring Boot 4 skeleton with Gradle Kotlin DSL. The scaffold is the foundation every later story builds on — boring, reproducible, CI-verified.", "complexity": "Low", "implementation_order": 1, "acceptance_criteria": [ "Given an empty project directory, When the scaffold step runs, Then build.gradle.kts, settings.gradle.kts, and src/main/kotlin/com/acme/Application.kt exist", "Given the scaffolded project, When ./gradlew build runs, Then it exits 0 with no warnings", "Given the running app, When GET /actuator/health is called, Then the response is 200 with status UP" ], "technical_notes": ["Spring Boot 4 + Kotlin 2.3 + Java 25, Gradle Kotlin DSL only — no Groovy"] }, { "id": "1.2", "title": "Wire Postgres + jOOQ + Flyway", "description": "Persistence is jOOQ-first, schema-managed by Flyway. JPA is off the table per the anti-ORM stance, so the jOOQ codegen must be wired into Gradle before any domain code lands.", "complexity": "Medium", "implementation_order": 2, "acceptance_criteria": [ "Given a Postgres Testcontainer, When Flyway migrate runs, Then the migration history table shows V1__init applied", "Given the Flyway-managed schema, When jOOQ codegen runs, Then generated classes appear under build/generated/jooq", "Given a DSLContext bean, When an integration test queries SELECT 1, Then it returns 1" ], "technical_notes": [ "jOOQ codegen runs from the Flyway-migrated Testcontainer, not a static schema dump", "No JPA, Hibernate, or Spring Data JPA on the classpath" ] } ] }, { "id": "2", "title": "Auth", "description": "OAuth2 resource server with RS256 JWTs. Cross-cutting concern that must land before any feature endpoint, otherwise routes get retrofitted later and introduce inconsistent guards.", "user_stories": [ { "id": "2.1", "title": "OAuth2 resource server with RS256 JWT", "description": "All API routes are guarded by Spring Security as an OAuth2 resource server validating RS256 JWTs against the IdP's JWKS endpoint. Landed early to avoid retrofitting guards onto existing routes.", "complexity": "High", "implementation_order": 3, "acceptance_criteria": [ "Given a request with no Authorization header, When it hits any non-public route, Then the response is 401", "Given a valid RS256 JWT, When the request hits a guarded route, Then the response is 200 and SecurityContext.principal carries the sub claim", "Given an expired JWT, When the request hits a guarded route, Then the response is 401 with WWW-Authenticate: Bearer error=invalid_token" ], "technical_notes": ["RS256 only — HS256 is forbidden; JWKS URI via spring.security.oauth2.resourceserver.jwt.jwk-set-uri"] } ] } ] } ``` The example shows: populated descriptions (never empty), three distinct complexity values (`Low`, `Medium`, `High` — not a row of Mediums), Gherkin acceptance criteria, one-line technical notes, and global `implementation_order` running `1, 2, 3` across both epics. After writing both files, report the output and offer the import: > "Generated `.artifex/tmp/acme-blueprint.md` and `.artifex/tmp/requirements-acme.json` (2 epics, 3 stories). Want me to run `afx-ticket-manager import .artifex/tmp/requirements-acme.json` now?" If yes, invoke the `afx-ticket-manager` skill and import. Report counts (epics, stories, total tickets) when done. ## Fast-track mode If the user says "just build it", "skip questions", "fast-track", or invokes the command with `fast-track` as an argument, collapse Phase 1 + Phase 2 to **three essential questions total**: 1. "What are you building?" (one sentence — drives archetype classification) 2. "Who is this for?" (audience) 3. "Any tech preferences I should respect, or should I use the defaults?" Use archetype defaults for everything else. **Do not skip Phase 3** — always present the architecture for confirmation, but make it short (just the stack table and build-order milestones). **Do not skip Phase 4** — always generate the blueprint. Fast-track is about fewer questions, not a lower-quality output. ## Import mode If the user invokes `/afx-blueprint import `, or says "I already have a blueprint at , just make tickets": 1. Read the blueprint markdown at ``. No interview, no validation, no regeneration of the markdown. 2. Walk the markdown headers yourself and map sections to epics / stories using the Phase 5 mapping rules. This skill does the parsing — **do not invoke `afx-requirements-converter`**. "Parsing" here means Claude reads the markdown structure and uses its own judgment to build the JSON, following the same rules as Phase 5 generation (populated descriptions, concrete complexity, Gherkin acceptance criteria, one-line technical notes, global topological `implementation_order`). 3. Write `.artifex/tmp/requirements-.json` directly, where `` is derived from the input filename (e.g., `acme-blueprint.md` → `requirements-acme.json`). 4. Offer the `afx-ticket-manager import` handoff just like Phase 5. 5. If the blueprint is missing a Build Order section, warn the user and offer to re-run the skill in interactive mode instead. ## Consuming the knowledge base The knowledge base lives under the Artifex SDK install at `docs/knowledge/`. Resolve to the absolute path at runtime — the user may invoke from any directory. **When to read what:** | Phase | Files to read | Why | |-------|---------------|-----| | Phase 1 (after classification) | `docs/knowledge/archetypes/.md` | Load default stack, structure, key decisions, gotchas | | Phase 2 (as questions are answered) | `docs/knowledge/building-blocks/auth-patterns.md` | For any archetype with authentication | | Phase 2 | `docs/knowledge/building-blocks/database-patterns.md` | For any archetype with persistence | | Phase 2 | `docs/knowledge/building-blocks/api-design-patterns.md` | For `api-backend` and `saas-webapp` | | Phase 2 | `docs/knowledge/building-blocks/testing-patterns.md` | All archetypes except `marketing-site` | | Phase 2 | `docs/knowledge/building-blocks/observability-patterns.md` | All non-trivial deployments | | Phase 2 | `docs/knowledge/building-blocks/deployment-patterns.md` | All archetypes | | Phase 2 | `docs/knowledge/building-blocks/iac-patterns.md` | Anything with cloud infra | | Phase 2 | `docs/knowledge/building-blocks/ci-cd-patterns.md` | Anything with a pipeline | | Phase 2 | `docs/knowledge/building-blocks/styling-systems.md` | Frontend-bearing archetypes | | Phase 2 | `docs/knowledge/building-blocks/state-management.md` | Frontend-bearing archetypes | | Phase 3 (always) | `docs/knowledge/stack-compatibility.md` | Validate the proposed stack against known-bad combinations | | Phase 4 (always) | `templates/blueprint.md.template` | The output template | Read these files **silently** — use Read, then use what you learned to inform the conversation. Don't dump their contents on the user. Building-block files are authoritative for patterns. If a user asks "should I use Flyway or Liquibase?" and the database-patterns file says "Flyway is the default", recommend Flyway. Don't re-derive decisions the knowledge base has already made. The `stack-compatibility.md` matrix is authoritative for compatibility. Before Phase 3, cross-check every entry in your proposed stack table against this file. If you find a hit, surface it: > "Heads up — you asked for Spring Boot WebFlux + jOOQ. The compatibility matrix flags this as known-bad (jOOQ is blocking, WebFlux is reactive). I'd recommend Spring MVC + jOOQ, which is the proven combo. Want me to swap it?" ## Non-negotiable rules 1. **NEVER generate the blueprint before completing Phases 1-3.** The discovery conversation is mandatory unless in import mode. 2. **Max 3 questions per message.** Keep it conversational. One or two is usually better than three. 3. **ALWAYS present the architecture for confirmation before generating.** Even in fast-track. 4. **The blueprint must be self-contained.** A Claude Code instance with zero prior context must be able to build from it. 5. **ALWAYS include a numbered build order** in the blueprint, 10-20 steps, zero to deployed. This is the most critical section. 6. **Save every blueprint to `.artifex/tmp/-blueprint.md`.** Never the repository root. Create `.artifex/tmp/` if it doesn't exist. 7. **The `requirements.json` is the machine handoff.** It is generated directly by this skill (at `.artifex/tmp/requirements-.json`), never via `afx-requirements-converter`. Every schema field (`id`, `title`, `description`, `complexity`, `implementation_order`, `acceptance_criteria`, `technical_notes`) must be populated at generation time — nothing is deferred. 8. **Stories in the JSON array are in global topological order across all epics** — not just per-epic order. `implementation_order` is a single monotonically increasing integer spanning every story in the output. 9. **Descriptions are never empty** unless a story truly has no context to record. Complexity is never auto-defaulted to `Medium` — judge each story individually and emit `Low`, `Medium`, `High`, or `Very High` based on the blueprint's assessment. 10. **Detect the user's language** from their first message. If they wrote in Spanish, respond in Spanish. Match them. 11. **Be opinionated.** Recommend what you'd build, explain why in one sentence, don't enumerate options. 12. **Validate the stack** against `stack-compatibility.md` before generating. Warn on known-bad combinations. 13. **Prefer JVM stacks** (Spring Boot 4 + Kotlin + jOOQ) for backend and full-stack work. Never recommend Python for general backend. Never recommend JPA/Hibernate for new services. Next.js 15 only when a frontend is genuinely needed. ## Session start When invoked, begin with a brief welcome that sets expectations, then go straight to Phase 1: > "I'll help you design a complete architecture for what you want to build. This should take 10-25 minutes. At the end you'll get a self-contained blueprint markdown, a matching `requirements.json`, and optionally a set of tickets imported into your ticket database. > > **What are you building?** Give me a sentence or two — what it is, who it's for, and what problem it solves." If the user invoked with a project description as an argument (e.g., `/afx-blueprint A SaaS for freelance designers to track invoices`), treat that as the answer to the Vision question and proceed directly to classification + any follow-up clarifying questions. If the user invoked with `fast-track`, announce the mode: > "Fast-track mode — I'll ask three quick questions and use sensible defaults for everything else. Let's go. **What are you building?**" If the user invoked with `import `, skip the interview entirely and follow the Import mode section above. ## When NOT to use this skill - When the project already exists and the user just needs documentation — use `afx-project-init` instead. - When the user already has tickets in the database and wants to start implementing — use `afx-next-ticket` and `afx-ticket-implementation`. - When the user is asking for a quick architectural opinion without wanting a full blueprint file — just answer conversationally.