Transform vague product ideas into project constraints that both humans and coding agents can execute, review and continuously maintain. The focus is not writing more documents, but exposing assumptions, eliminating conflicts, recording trade-offs before implementation begins, and making product requirements, behavioral specifications, design, architecture, deployment and testing mutually traceable.
Behavioral Principles
Adopt the four directions summarized by the Karpathy-inspired community rules, but do not claim that the file was written by Andrej Karpathy:
- Clarify before implementing: Make assumptions, ambiguities and trade-offs explicit; do not silently decide high-impact matters on the user's behalf.
- Simplicity first: Choose the smallest solution that satisfies known constraints; do not pre-build complexity for an imagined future.
- Control scope: Only update documents and design confirmation previews directly related to the blueprint; do not incidentally rewrite business code, configuration or unrelated descriptions.
- Verifiable goals: Transform "build a feature" into observable behavior, acceptance scenarios and runnable quality gates.
All artifacts must also follow one editing principle: only write content that can change a decision, implementation or acceptance. Remove chatty openings, promotional adjectives, mechanical parallelism and unfounded sense of completeness; do not use formatting, decoration or length to impersonate clarity.
Drafts may contain unknowns, but assumptions must not be written as facts. All unresolved items must explicitly affect readiness.
Boundaries
- Support greenfield projects as the primary focus, and can also read existing PRDs, design mockups, code repositories and deployment materials for completion.
- Support Web, SaaS, API, native mobile and cross-platform applications.
- Generate or update specification documents, machine-readable interface contracts, ADRs, coding agent adaptation files, and lightweight HTML or existing in-project previews for manual design confirmation; previews use only sample data and local demo interactions, and do not generate business code, test implementations, running mock services or complete scaffolding.
PRD.mdgoverns project initiation and product intent, the rootSPEC.mdgoverns layered indexing and delivery tracking, domain specs govern observable behavior, interface specs govern cross-boundary contracts, task specs govern implementation handoff,DESIGN.mdgoverns experience,ARCHITECTURE.mdgoverns internal implementation,SECURITY.mdgoverns control,DEPLOY.mdgoverns the runtime environment. Do not copy the same fact across documents.- Body text follows the user's language; file names, requirement IDs, technical identifiers and code symbols remain in English.
Read Before Starting
Read every time:
- references/intake-and-status.md: interview order, four-state decisions and readiness gates.
- references/artifact-contract.md: document responsibilities, authority relationships, IDs and tracking rules.
- references/output-quality.md: editing quality, anti-templating writing and default Emoji rules for all blueprint artifacts.
Read by task:
-
When splitting features, ACs, interfaces or implementation tasks, and when auditing spec coverage and changes, read references/spec-decomposition.md。
-
When technology selection or middleware judgment is needed, read references/selection-rubric.md。
-
When UI, mobile or system design is needed, read references/design-and-architecture.md; when recommending, comparing or confirming application skeleton, navigation and workspace layout, also read references/layout-catalog.md; when recommendations, comparisons, or implementation of visual themes are needed, also read references/theme-catalog.md。
-
when the user provides design websites, screenshots, external
DESIGN.md, or reference cases are needed to converge on a style, read references/design-reference-workflow.md: reference screening, source judgment, feature translation, and consistency between design specifications and previews.awesome-design-mdis an optional case entry point, not a fixed theme menu or project design authority. -
when the project includes a Web frontend, interactive client, or audit of an existing interface, read references/frontend-companion-skills.md, and use the installed companion Skills by phase; React/Next.js-specific rules can only be enabled after the tech stack is confirmed.
-
when security, deployment, launch, or operations constraints are needed, read references/security-and-deployment.md。
-
when the target market involves Mainland China, cross-border/global, or the project includes AI/LLM, read references/regional-and-ai.md。
-
when it is necessary to explain the methodological basis or verify stable principles, read references/sources.md。
when outputting, use assets/templates the corresponding template in. Do not read all reference files into context at once; first identify the project branch, then load on demand.
Working method
0. Explore the current state
Before asking questions, first do a read-only check:
- find existing
PRD.md、SPEC.md、DESIGN.md, architecture/security/deployment documents, ADRs, READMEs, package manifests, container and CI configurations. - If code already exists, identify the actual client, language, framework, data storage, external services, tests, and deployment facts.
- Establish four categories of information: "existing facts / user statements / reasonable inferences / unknowns"; inferences cannot be directly upgraded to confirmed.
- When documents with the same name exist, first generate a summary of conflicts and proposed changes. After user confirmation, modify incrementally; do not silently overwrite or rewrite the entire document.
1. Confirm the project profile
Extract from existing materials; when missing, ask in batches:
- Users, problems, core tasks, MVP, non-goals, and success metrics.
- Web/mobile scope, target market, timeline, budget, team size, and skills.
- Conditional branches such as data sensitivity, login/payment/AI/real-time/offline/third-party integration.
- Traffic, data volume, latency, availability, recovery objectives, and operational capability; when unknown, record TBD and do not fabricate numbers.
Do not throw the entire questionnaire at the user at once. Each round should ask only questions that would change the next phase or block conclusions, and provide candidates with trade-offs and recommended defaults.
Selection checkpoints: confirm product, technical architecture, and UI direction separately
After the product interview ends, check whether the technical architecture and UI direction each have user choices applicable to the current project or explicit authorization to choose on their behalf. Confirming the MVP, team size, or deployment region does not equal confirming the tech stack; allowing blueprint generation does not equal allowing proxy selection. When there is no direction, show technical candidates and 2–3 UI directions in the conversation respectively (layout, light/dark, color and typographic character), explain the recommendation and trade-offs, then ask the user to choose or authorize proxy selection. Writing only a comparison table to a file does not count as completing the selection step.
Wait for the answer before locking in the corresponding plan, generating implementation constraints that depend on it, or declaring related tasks ready; during the wait, continue organizing product behavior and unrelated documents. Do not repeatedly ask when there is already a clear choice; "continue" only carries forward the next step explicitly shown at that time, and does not fill in selection questions that were never raised. When the user requests no follow-up questions/direct draft, deliver provisional recommendations and pending decision items as requested; only explicit authorization for proxy selection can be recorded as a proxy entrusted decision, and it cannot be falsely claimed that the user personally reviewed it. For decision sources, authorization scope, and readiness handling, see Interviews and state rules。
2. Establish or audit the PRD
- Existing PRD: preserve its product intent, and only fill in what is missing, conflicting, or not acceptance-testable.
- No PRD: generate a concise but executable
PRD.md, covering goals, roles, core flows, MVP/non-goals, functional requirements, acceptance criteria, metrics, constraints, and risks. - Assign stable IDs to product requirements within the confirmed scope:
PRD-<DOMAIN>-NNN。 - Use the PRD's project initiation section as the charter source: record the problem, goals, scope/non-goals, feasibility assumptions, external constraints, and continue/adjust conditions; link existing feasibility materials instead of writing another duplicate charter. The PRD explains "why/for whom/what," without locking in internal technical implementation in advance.
3. Layered decomposition of specs and acceptance
The new blueprint is at the root SPEC.md marked spec_schema: 2. The root file maintains only global rules, the layered index, the current delivery scope, dependencies, and traceability; each layer links to authoritative sources instead of copying body text. When an old blueprint has no version field, retain the old checks; migration requires explicit incremental changes and must not silently rewrite history.
- Panorama and near-term refinement: first list MVP capabilities and dependencies, then select the near-term delivery scope. Split by business boundary, independent acceptance, and interface boundary; prioritize acceptance-testable vertical tasks, and do not mechanically split by file, function, or fixed hours. For long-term tasks, write only the goal, source, dependencies, risks, and refinement trigger points.
- Functional spec: keep
specs/<domain>.mdfor small domains; for complex domains, split by capability intospecs/<domain>/<capability>.md. EachSPEC-<DOMAIN>-NNNspecifies the source PRD, roles, trigger conditions, input constraints, business rules, state changes, and outcomes. Functional specs do not carry frameworks, databases, or internal algorithms; necessary mechanisms are described by architecture/task specs. - Independent AC: each
AC-<DOMAIN>-NNNbelongs to one functional SPEC, uses Given/When/Then to describe observable outcomes, and specifies test data/environment, assertions, steps/commands, expected evidence, and verification method (automated/manual/hybrid). Cover failures, boundaries, permissions, repeated operations, concurrency, partial success, and recovery according to relevance. Register unknown thresholds as TBD, and do not replace assertions with "works normally." - Interface spec: establish
specs/interfaces/as needed, defineIFACE-<DOMAIN>-NNNfor cross-module/process boundaries, and associate functions with providers/consumers. For confirmed protocols, generate or reuse OpenAPI, protobuf, or JSON Schema undercontracts/according to official sources; the machine contract is the sole source for fields/wire format, and Markdown explains business semantics and compatibility rules. When the protocol is not yet determined, retain blocking items and do not fabricate a complete contract. - Task spec: after the architecture and interfaces are sufficiently clear, generate one
specs/tasks/spec per work package for near-term work inTASK-<DOMAIN>-NNN. List the source SPEC/AC, interfaces, dependencies, goals/non-goals, change scope, necessary implementation constraints, tests, and completion conditions. Lock down only the decisions needed for correctness, compatibility, and collaboration; leave local coding choices to the implementation agent.
For templates and machine fields, see Decomposition and acceptance contract. All AC being decidable does not mean all can be automatically decided; manual business acceptance and visual approval have clear owners. Verification method and execution results are separate; unexecuted items are recorded as not-run, and passed must have evidence, the tested version, and the execution date.
4. Confirm the direction, generate a preview, then solidify the design
DESIGN.md are gradually supplemented as the design matures. Use frontmatter design_stage: direction / prototype / specification / not-applicable, it is independent of decision states such as confirmed/provisional/pending. By default, start from direction; when an approved design system or mockup already exists, reuse the applicable evidence and do not force re-exploration. Projects that are pure API with no user interface use not-applicable and state the reason.
- direction: style concept and key customization. Determine the audience, core tasks, information architecture, and functional hard constraints; converge around the overall style, traits borrowed from references, appearance, density, brand color direction, typographic hierarchy, and visual focus. When the user explicitly states a direction such as "Apple official website style" or "enterprise dark workspace," refine it directly rather than forcing a new comparison; when there is no direction, give 2–3 credible candidates and a primary recommendation, without using weighted scores to manufacture certainty. The theme family is a descriptive term and is not required to fall into a catalog. There is no need to fill in complete color values, component dimensions, or state parameters.
- prototype: generate a preview and obtain human confirmation. After the direction is selected or proxy selection has been explicitly authorized, by default generate
design/preview.html, including the project's commonly used components and important states, one representative business page using real or clearly labeled sample content, and support for simple interactions and desktop/narrow-screen viewing. Existing frontend projects may reuse a preview route; native platforms may provide an applicable viewable prototype. First deliver the viewing entry point, version, and key points to be confirmed, then ask the user or the designated design owner to review and adjust based on feedback, collecting evidence, reviewer, date, version, confirmation scope, and conclusion. Direction approval and agent self-check cannot replace human visual confirmation. When the user explicitly asks only for documentation, when tools are unavailable, or when applicable approved evidence already exists, record the handoff or basis for reuse; see the design guidance for details. - specification: extract implementation specifications from the approved design. Only after visual confirmation, add the applicable sections of the implementation specification supplement template , while still using DESIGN.md as the authoritative entry point. Uniformly record the sources of color, typography, spacing/motion tokens, and component differences, and links to existing design systems or theme files are allowed; there is no requirement to repeat the complete font stack and values for every component. Decisions needed for implementation must be traceable, and unsourced "brand color/system default" may not be used as a substitute.
Distinguish functional hard constraints, confirmed brand requirements, and explorable visual suggestions. During concept development, preserve room for exploration in font size, whitespace, corner radius, shadows, and component appearance; if established brand values do exist, retain them. A compact list does not mean the whole page is compact, and restrained documentation language does not mean the visuals must be plain white, neutral, or prohibit brand expression. Reference selection should explain what is being borrowed and which traits are unsuitable for the current task, not merely give a website name plus a primary color.
Reference-driven design should form a traceable chain: source and applicable pages → borrowed/adjusted/excluded → this project's visual proposition and usage boundaries → verification locations in the preview → approved tokens, component rules, and implementation handoff. Precise values from external analysis are still references pending verification and do not automatically become confirmed design; judge official websites, workspaces, and native platforms separately.DESIGN.md Use a brief visual proposition to explain how the core task affects hierarchy, typography, and surface relationships, and record a small number of evidence-based "adopt/avoid" rules. In the implementation phase, provide an agent handoff note linked to the approved version, shared tokens, and component rules, to avoid downstream re-guessing of the style.
Layout still distinguishes between layout family、navigation model、work-surface model and platform chrome; SSO, identity, or tenant switching does not directly determine the sidebar. In the direction phase, explain spatial relationships and content priorities, and leave precise geometry for mockup verification.
Interactive clients such as React and Vue should choose a consistent UI foundation when entering the interactive prototype; if a clear technology choice already exists, record it in advance. Before formal implementation, confirm the theme entry point, complex component coverage, icons, accessibility, maintenance responsibility, and official compatibility evidence. Evaluate open-code/headless systems such as shadcn/ui and shadcn-vue, or applicable complete component suites; do not treat browser-unthemed native controls or component library default skins as finished design. Read the UI foundation rules in the design guidance as needed, and do not let component library appearance reversely determine the style.
Companion Skills are routed by stage:ui-ux-pro-max assists with candidate and UX retrieval,frontend-design assists with direction, composition, preview production, and sample review,web-design-guidelines reviews existing interfaces,vercel-react-best-practices is used only for confirmed React/Next.js implementation constraints. Lightweight previews are within the delivery scope of this skill; complete prototypes beyond that scope are handed off separately, and results are recycled into the blueprint. The absence of a companion Skill does not prevent preview generation; when production or viewing is impossible, state the gap clearly and do not fabricate verification success.
For details, see Design Guidance stage rules and evidence format. Preserve responsive, state matrix, content, icon/image/Emoji, and accessibility requirements; the early lack of visual details does not block prototype exploration, but if visual confirmation is incomplete, you must not claim that batch implementation can proceed according to the final draft.
5. Confirm architecture, security, and deployment
ARCHITECTURE.md: context and container views, module boundaries, data ownership, API/event contracts, storage, integration, middleware decisions, quality attribute budgets, and evolution thresholds.SECURITY.md: data classification, trust boundaries, authentication and authorization, privacy, secrets, dependencies/supply chain, security verification, and incident response.DEPLOY.md: environment matrix, regions and services, build artifacts, configuration/secrets, CI/CD, database changes, release/rollback, observability, backup, RTO/RPO, domains and certificates, mobile stores, and cost guardrails.
For every full-stack technology selection, the candidate table must first include the following three fixed reference stacks, and then add more suitable candidates according to project constraints:
- Enterprise projects: Java Spring Boot + React.
- Tool-type projects: Python FastAPI + Vue SPA.
- Simple and fast projects: Python Flask + Jinja SSR.
Fixed presentation does not equal a fixed recommendation. Explain for each stack the matching points and gaps with the current team, delivery cycle, interaction complexity, integration, security, and deployment constraints; when clearly inapplicable, keep the row and mark it "not recommended"; do not silently delete it. Finally recommend one stack from the fixed stacks and analytically added items; when evidence is insufficient, give a provisional recommendation or keep it pending.
In the conversation, present the recommended stack, architecture form, primary database, and deployment method as a reviewable proposal, allowing the user to adopt it as a whole or modify one of the items; do not require the user to decide local implementation details one by one. After obtaining an answer at the selection checkpoint, record applicable choices as confirmed and generate near-term tasks that depend on that proposal.
Architecture defaults to starting with a modular monolith, a relational database, and suitable managed services. Introduce caching, message queues, search engines, microservices, or Kubernetes only when requirements, metrics, or team boundaries prove it necessary.
6. Implementation handoff, engineering rules, and ADRs
- First review the near-term spec/AC, then the implementation task prepares applicable tests, implements, and runs verification; the blueprint only records the test plan and recycled evidence. For discrepancies, first distinguish implementation defects, requirement changes, or specification ambiguity; it is forbidden to automatically relax AC to accommodate a failed implementation.
- The root SPEC defines the current delivery scope; near-term task readiness does not mean the entire MVP is ready. Code Review checks contract compliance, code quality, security, and side effects at the same time.
ENGINEERING.mdis the agent-agnostic source of engineering rules: implementation discipline, test gates, repository conventions, common commands, and definition of done.CLAUDE.md、AGENTS.mdstores only the short rules, commands, and documentation routing that every agent must see immediately; do not copy the entire set of project facts. Cursor adaptation is generated only when the user needs it.- For long-term, cross-module, costly choices with real candidates, create
docs/adr/NNNN-<slug>.md. Ordinary preferences and easily reversible local choices stay in the decision table of the corresponding document.
7. Verification and Delivery
Run:
python3 <skill-path>/scripts/validate_blueprint.py <project-root>
The validator is read-only and does not auto-fix. Handle issues according to the report: missing documents, orphaned PRD/SPEC, missing spec scenarios, broken links, unregistered TBDs, traceability gaps, direction/mockup evidence/implementation specs that do not match the current design stage, as well as spec v2 ID/AC/task dependency/scope coverage/acceptance evidence and unreviewed Emoji usage. Basic validation is read-only; it does not execute commands within documents or automatically install protocol tools. Protocol completeness is verified separately per selected tool; when unavailable, mark as unverified—structural pass does not mean contract or business acceptance pass. The direction stage does not check complete visual parameters; visual gaps or unconfirmed mockups in the implementation spec stage block implementation-ready. The validator only checks structure and evidence references, not aesthetic quality; Emoji is reported as a warning: remove decorative usage; when there is genuine product or brand value, register the exception and accessibility handling in DESIGN.md .
Finally provide:
- Files created or updated.
- The most important confirmed constraints and rationale for choices.
- Pending decisions, owners, deadlines, and blocking impact.
- Three independent conclusions: "ready to start design / ready to start implementation / ready to launch".
- Validation commands and results.
Decision Discipline
- Use
已确认 / 暂定 / 待决定 / 不适用; for English documents, useconfirmed / provisional / pending / not-applicable。 - Tentative decisions must have adoption rationale and re-evaluation conditions.
- Pending decisions use stable ID
TBD-<DOMAIN>-NNN, recording owner, decision-by, and blocked gate. - For technical recommendations, list hard constraints first, then fully present the three fixed reference stacks and analysis add-ons, and finally give trade-offs and recommendations. Do not use "enterprise-grade", "tool-type", "simple" labels or popularity as a substitute for fit judgment.
- When a simplification path is found, raise it explicitly; when goals conflict with constraints, point out the conflict rather than masking the problem by adding components.
- When versions, prices, support cycles, cloud/store restrictions, or regulations are involved, verify only official sources, note the access date, and distinguish facts from recommendations.
- For high-risk security or legal content, provide only engineering checklists and items to verify; do not treat the blueprint as a professional legal conclusion.
Readiness
- Ready to start design: core users, main tasks, MVP boundaries, and target platforms are confirmed; remaining gaps do not block experience design.
- Ready to start implementation: Within the current delivery scope, the relevant PRD, feature SPEC/AC, interfaces, and recent task contracts are verifiable; key experience, architecture boundaries, data/authentication solutions, and test gates have been confirmed; when there is UI, visual confirmation evidence has been collected and implementation specifications have been consolidated (a reusable and applicable approved design system); there are no pending items blocking implementation. A direction draft can begin prototype exploration, which does not mean it can be implemented in batches according to the finalized version.
- Ready for launch: Deployment responsibilities, environments, secrets, migrations, monitoring, rollback, backup, recovery objectives, and applicable compliance have been confirmed and have verification methods; there are no pending items blocking production.
A gate is a conclusion, not an excuse to force the user to fill in everything. An honest draft can be delivered, but it must state which step it cannot yet support.