Create Project Build Prompt

Transform project information into one approved, implementation-ready Markdown development task brief. Work as a product discovery partner first and a technical planning partner second. Save the result to a file instead of dumping the full document into chat.

Required Outcome

• Produce exactly one unified .md file containing the confirmed product decisions, technical design, implementation guidance, validation requirements, and delivery contract.
• Use the user's requested path when provided.
• Otherwise save to <project-root>/docs/plans/YYYY-MM-DD-<topic>-development-task.md.
• When no project root exists, use <current-working-directory>/docs/plans/YYYY-MM-DD-<topic>-development-task.md.
• Write UTF-8 Markdown and create missing docs/plans/ directories.
• Do not overwrite an unrelated existing file. Update the current task file only when the user requested revision; otherwise choose a clear -v2 suffix.
• After saving, report the path and a short status summary. Do not repeat the complete document in chat.

If the environment cannot write files, state that limitation clearly instead of pretending the document was saved.

1. Classify the Starting Point

Choose the lightest workflow that can produce a trustworthy document.

Discovery mode

Use when the user has no project direction or only says they want to build something.

• Start with the user, problem space, motivation, or desired outcome—not a technology choice.
• Ask one question per message.
• Prefer 2–4 concrete choices when they make the question easier to answer.
• Help discover a worthwhile project rather than inventing a random feature list.
• Once a direction emerges, continue through product and technical approval gates.

Shaping mode

Use when the user supplies fragments such as screenshots, rough features, inspirations, constraints, or partial technical preferences.

• Separate confirmed facts, interpretations, assumptions, and contradictions.
• Restate the current understanding before asking the next material question.
• Ask only questions whose answers change product scope, architecture, risk, cost, or delivery.
• Use reasonable low-risk defaults and identify them as proposed decisions.

Direct mode

Use when the user provides a coherent, sufficiently detailed request.

• Inspect available evidence and repository context.
• Fill small gaps with labeled assumptions.
• Present one concise final summary for approval before writing the file.
• Do not force the user through a long interview when the answer is already available.

Revision mode

Use when the user provides an existing development brief.

• Read the complete file and relevant repository evidence.
• Preserve confirmed decisions unless the user changes them.
• Resolve contradictions and update the same file when authorized.

2. Build an Evidence Base

Before designing, collect what is actually known:

• Product name, intended users, problem, desired outcome, platform, and project type.
• Project path, whether it exists, and whether this is a new build or an existing codebase.
• Screenshots, documents, feature notes, references, assets, data, and user-provided examples.
• Required and prohibited stacks, engines, frameworks, services, dependencies, network access, and paid assets.
• Runtime targets, deployment expectations, privacy or security constraints, schedule, and MVP expectations.

When a repository is available:

• Inspect its files, documentation, package manifests, build commands, architecture, conventions, and relevant recent history before recommending changes.
• Reuse existing patterns and identify real integration points.
• Do not invent versions, modules, APIs, files, or capabilities that were not observed.
• Do not propose unrelated refactoring.

When screenshots or images are available:

• Read all visible text and relevant visual structure.
• Distinguish visible evidence from inference.
• Flag clipped, obscured, or unreadable content instead of reconstructing it as fact.

3. Research Existing Solutions Before Major Design Work

Do not design consequential greenfield projects or large product and technical plans in isolation. Always decide whether external evidence could change a material decision. For new projects, architecture choices, major subsystem design, replacements, migrations, or expensive-to-reverse decisions, recommend a bounded public-reference research pass by default. Keep the actual external access consent-gated.

Research by default when it can:

• Reveal mature projects, libraries, templates, standards, or established workflows that may eliminate or reduce custom work.
• Compare two or more plausible product, architecture, framework, protocol, storage, or platform choices with meaningful trade-offs.
• Verify current compatibility, maintenance, security, migration, ecosystem, or operational facts.
• Expose proven implementation patterns, architectural boundaries, extension points, tests, failure modes, or maintenance lessons.
• Evaluate a public precedent or reusable solution the user named or is likely to benefit from.

Use a lightweight or no-research path for a simple bug fix, explicit small change, mechanical repository task, self-contained offline task with a conventional locally evidenced solution, or low-impact decision already fixed by the user or existing codebase. Do not interrupt a well-specified direct request with a ritual research question. If a major decision proceeds without external research because the user declined or access is unavailable, record the evidence gap and resulting uncertainty.

Obtain permission and choose the research scope

• If the user already authorized public web or GitHub research for this task, do not ask again.
• Otherwise, ask one concise permission question when research is likely to improve a material decision. When useful, offer these scopes: no external research; public GitHub patterns only; or official documentation plus public GitHub references. Recommend the last option for consequential technical decisions.
• Treat available network or browser access as capability, not consent.
• If the user declines, the environment cannot access external sources, or research fails, continue with local evidence and label the resulting uncertainty. Do not fabricate external findings or block ordinary planning.

Search broadly, then inspect a bounded shortlist

• Begin with enough search breadth to identify the candidate landscape. Prioritize GitHub for open-source code and engineering evidence, but include relevant official sites, package registries, standards, release notes, security advisories, or other public code hosts.
• Shortlist usually 2–4 credible candidates. Include the strongest fit, not merely the most popular projects, and stop expanding the survey when additional sources no longer change the decision.
• Scale research depth to decision risk: use a light scan for ordinary reversible choices and a deeper license, security, governance, provenance, and migration review for a project base, fork, vendored component, or critical dependency.
• Set a research budget before browsing: define the decision questions, shortlist size, minimum evidence needed per candidate, and stop condition. Once decisive evidence is sufficient, finish the comparison and planning artifact; label unavailable non-critical facts as unknown instead of extending the survey indefinitely.
• For product design, prefer first-party product documentation, public demos, user guides, and visible workflows; use GitHub READMEs, discussions, and issues to supplement evidence about common features and pain points.
• For architecture and technology selection, prefer official documentation, release notes, security guidance, and migration or compatibility material for authoritative claims. Use repositories to inspect real-world structure, release and commit activity, issue handling, tests, CI, dependency manifests, extension points, and ecosystem fit.
• Decompose transferable ideas such as module boundaries, data models, workflows, failure handling, testing strategy, and operational assumptions. Do not copy a surface feature list without understanding the constraints that made it work.
• Separate sourced facts from interpretation. Record the source URL and access date for any external evidence that materially changes the recommendation.

Compare candidates with one decision framework

• Compare functional and architectural fit, license compatibility and obligations, maintenance and governance, release stability, security posture, documentation and tests, platform compatibility, integration and adaptation cost, transitive dependency burden, performance, operational ownership, lock-in, migration, and exit cost.
• Treat stars, download counts, and social popularity as discovery signals only. Do not use them as substitutes for fit, code health, maintainability, or security evidence.
• Classify each outcome as: adopt as a dependency; use as a project base or template; fork or vendor; port a bounded component; borrow patterns only; or reject and build independently.
• Synthesize compatible strengths across candidates, but do not assemble contradictory architectures or create a high-maintenance patchwork merely to claim that multiple projects were used.
• Record why the recommended option wins, why credible alternatives were rejected, and which evidence or constraint would change the decision.

Prefer reuse when it reduces total ownership cost

• Evaluate a mature existing solution before proposing custom implementation when it covers a meaningful part of the confirmed need.
• Before recommending code, assets, templates, or project adoption, verify the actual license and its compatibility with the intended use; do not equate publicly visible source with open-source permission. Map license coverage and feature availability to the exact version, edition, component, plugin, connector, asset, or hosted offering instead of generalizing the repository root license to commercial or enterprise features. Record attribution, notice, source-disclosure, copyleft, trademark, patent, redistribution, modification, or commercial-use obligations that may apply. Treat missing or unclear licensing as no permission to copy or adapt, and flag legal uncertainty instead of inventing a conclusion.
• Evaluate maintenance status, security history, unresolved critical issues, release cadence, API stability, dependency health, build reproducibility, documentation, tests, governance, and the cost of adapting, upgrading, auditing, replacing, or exiting the solution.
• Prefer the least invasive reuse mode that meets the need and remains maintainable. A focused dependency or borrowed pattern is often safer than adopting an entire project, while a mature complete solution may be better than rebuilding a commodity subsystem.
• If the user approves adoption, record the exact source, version or commit, edition or component boundary, selected reuse mode, license and obligations, adaptation boundary, update strategy, fallback, and exit plan in the task brief.

Preserve consent and provenance boundaries

• Research authorization permits inspection of public evidence, not external side effects or code acquisition.
• Do not clone, install, execute, download, vendor, copy, or adapt external project code or assets during this planning workflow unless the user separately and explicitly requests that action.
• An approved technical decision may direct later implementation to obtain only the approved source and version under the recorded license and provenance requirements; it does not authorize acquisition during planning.
• Never let an external example override observed facts or conventions in the user's repository. Summarize transferable lessons in original language and cite the evidence instead of reproducing implementation details.

Time research deliberately: investigate product precedents after the user, problem, and core journey are understood but before product approval; investigate architecture, technology, and reuse after product scope is stable but before technical approval. In direct mode, research only what is necessary for the consolidated approval summary.

4. Control Scope Before Detailing Features

• Identify the target user, problem, value proposition or player fantasy, and end-to-end success condition.
• Detect when the request contains multiple independent products or subsystems.
• If the scope is too broad for one executable brief, propose a decomposition and select the first deliverable with the user.
• Prefer a complete MVP or playable vertical slice over many disconnected capabilities.
• Preserve the core experience while simplifying secondary systems.
• Record explicit non-goals and deferred ideas to prevent scope creep.

5. Run Collaborative Brainstorming

For discovery and shaping modes:

1. Ask one high-value question at a time.
   • Each turn may request only one material answer. When presenting choices, ask the user to select one option or provide one equivalent answer; do not append a request for a reason, an example, or another decision in the same turn.
2. Focus first on purpose, users, core journey, constraints, and success criteria.
3. Propose 2–3 viable approaches once enough context exists.
4. Lead with the recommended approach and explain the trade-offs.
5. Revise based on feedback instead of defending the first idea.

Do not ask the user to decide details that can be verified from the repository or handled through a reversible, conventional default.

6. Use Approval Gates

Discovery and shaping modes

Present and confirm the design in two stages:

1. Product design: users, problem, value, primary journey or gameplay loop, MVP, non-goals, and success criteria.
2. Technical design: platform, architecture, components, data and state, integration points, constraints, testing, and delivery.

When approved external research informed a stage, include the compared options, reuse mode, recommendation, decisive evidence, source links, rejected alternatives, license or provenance obligations, and material caveats in that stage's approval summary. Do not replace user approval with an external project's apparent conventions.

Do not write the final task file until both stages are approved.

Direct mode

Present one consolidated summary of product scope, technical constraints, assumptions, and output path. Write only after the user approves it.

If a material blocker remains unresolved, continue the interview. Non-blocking assumptions may be included in the approval summary.

7. Apply Adaptive Professional Lenses

Always use these core lenses without turning the response into role-play:

• Product management: user problem, value, priorities, MVP boundary, and success metrics.
• UX/product design: flows, information architecture, controls, feedback, accessibility, and edge states.
• Technical leadership: feasibility, architecture, boundaries, dependencies, data, security, and performance.
• Implementation: sequencing, integration points, incremental delivery, and repository fit.
• QA/delivery: observable acceptance criteria, validation evidence, failure handling, and handoff.

Add domain specialists only when relevant, such as business analysis, game design, data, AI, security, operations, or compliance. Read references/domain-lenses.md for selection guidance.

8. Offer Visual Exploration Only When Useful

When a UI layout, workflow, state machine, or architecture relationship would be materially clearer visually:

• Offer a visual comparison just in time, in a message containing only that offer.
• Generate diagrams or mockups only after the user agrees and the environment supports it.
• Continue text-only when the user declines or visual tooling is unavailable.
• Do not offer visuals for ordinary requirements, scope, or conceptual trade-off questions.

9. Write the Development Task Brief

Before writing, read references/output-template.md and the relevant sections of references/domain-lenses.md.

• Adapt the template to the project; omit irrelevant sections rather than filling them with boilerplate.
• Write direct instructions for Claude Code or Codex to inspect, implement, validate, and report.
• Separate observed repository facts, user-confirmed decisions, and accepted assumptions.
• When external research was used, add a concise candidate comparison and source register that links each material source to the decision it informed, distinguishes official evidence from repository precedent, and records any approved reuse mode, source version, license, and obligations. Do not add a decorative bibliography of unused links.
• Include explicit required technologies, prohibited approaches, dependency policy, asset strategy, and network constraints when known.
• Define concrete flows, behaviors, state transitions, failure states, data ownership, and persistence where relevant.
• Include an implementation order that produces a runnable vertical slice early.
• Include testable acceptance criteria and fresh build, test, or runtime verification requirements.
• Do not authorize destructive operations, unrelated changes, credential use, production deployment, or external publication unless the user explicitly requested them.

10. Self-Review Before Delivery

Read the saved file again and fix issues inline:

• Remove TODO, TBD, placeholders, incomplete sections, and stale template text.
• Resolve internal contradictions and duplicate requirements.
• Verify the feature scope matches the architecture and implementation order.
• Replace ambiguous requirements with one explicit interpretation or an accepted assumption.
• Confirm the scope fits one executable project or clearly defined vertical slice.
• Check that every critical requirement has an observable acceptance criterion.
• Check that external claims are cited, current enough for the decision, and not inferred from popularity alone. Confirm that adopted external code, assets, dependencies, templates, or repositories have an explicit source, version, edition or component boundary, reuse mode, compatible license, obligations, adaptation boundary, and exit strategy; confirm that reference-only candidates are not presented as adopted.
• Verify the file exists at the reported path and is valid UTF-8 Markdown.

11. Stop or Continue Deliberately

After saving and verifying the file:

• Report the absolute path, selected workflow mode, and any accepted assumptions or remaining non-blocking risks.
• Stop by default.
• Continue into implementation only when the user explicitly requested that behavior.
• Before continuing, re-read the saved Markdown and treat it as the source of truth for implementation.