From 8e402d25e32517261be321c3ddba9274c5d5a9b9 Mon Sep 17 00:00:00 2001 From: Samgu Lee Date: Tue, 6 Oct 2026 09:55:29 +0900 Subject: [PATCH 1/2] feat: enhance ARCHITECTURE.md generation guidelines for clarity and completeness --- .../prompts/ARCHITECTURE_DESIGN_PROMPT.txt | 26 ++++++++++++++++--- 1 file changed, 23 insertions(+), 3 deletions(-) diff --git a/templates/prompts/ARCHITECTURE_DESIGN_PROMPT.txt b/templates/prompts/ARCHITECTURE_DESIGN_PROMPT.txt index ae7e9e5..6c5e752 100644 --- a/templates/prompts/ARCHITECTURE_DESIGN_PROMPT.txt +++ b/templates/prompts/ARCHITECTURE_DESIGN_PROMPT.txt @@ -1,15 +1,23 @@ Generate ARCHITECTURE.md. -Assume PRODUCT_SPEC.md already exists and is correct. +Assume PRODUCT_SPEC.md and TECH_STACK.md already exist and are correct. + +Read TECH_STACK.md only to avoid conflicts with it. +Do not restate, summarize, or reference any technology, version, folder rule, or convention from it. +ARCHITECTURE.md must remain valid even if TECH_STACK.md changes. + +If PRODUCT_SPEC.md and TECH_STACK.md conflict, or if a required component +cannot be reconciled with the constraints in TECH_STACK.md, stop and report the conflict. +Do not resolve it silently. + +Do not create any other document. The purpose of ARCHITECTURE.md is to define: -```text How the product works internally. How responsibilities are separated. How information flows through the system. Which invariants must always remain true. -``` Do not describe implementation technologies. @@ -23,6 +31,8 @@ Do not describe deployment. Do not describe coding conventions. +Do not describe folder structure. + Architecture must remain technology-agnostic. The document must include: @@ -38,6 +48,7 @@ The document must include: - Failure Boundaries - Non-Goals - Architectural Invariants +- Resolved Decisions Every component must have: @@ -54,6 +65,15 @@ Identify: Resolve them before generating the document. +If a resolution requires interpreting PRODUCT_SPEC.md in a way +that is not explicitly stated there, ask before deciding. +Record every resolution you make in "Resolved Decisions" +(what was ambiguous, what you decided, why). + +Non-Goals must contain only architectural non-goals +(structures or responsibilities this architecture deliberately does not provide). +Do not copy non-goals from PRODUCT_SPEC.md. + Prefer clear ownership over abstraction. Optimize for implementation certainty. From b73ff2d7beec627a9e7eff0ba1ae22b2bc1cddc6 Mon Sep 17 00:00:00 2001 From: Samgu Lee Date: Tue, 6 Oct 2026 10:46:17 +0900 Subject: [PATCH 2/2] feat: enhance documentation prompts for clarity and completeness --- templates/documents/AGENTS.md | 133 +++++++++++-- .../prompts/ARCHITECTURE_REVIEW_PROMPT.txt | 30 ++- .../prompts/EXECUTION_VALIDATION_PROMPT.txt | 80 ++++---- .../prompts/PRODUCT_SPECIFICATION_PROMPT.txt | 118 +++++++---- templates/prompts/TASK_GENERATION_PROMPT.txt | 122 ++++++++---- .../prompts/TECH_STACK_DISCOVERY_PROMPT.txt | 59 ++++-- templates/prompts/TECH_STACK_PROMPT.txt | 185 +++++++++++++----- 7 files changed, 532 insertions(+), 195 deletions(-) diff --git a/templates/documents/AGENTS.md b/templates/documents/AGENTS.md index 4ce81af..57acba5 100644 --- a/templates/documents/AGENTS.md +++ b/templates/documents/AGENTS.md @@ -7,7 +7,8 @@ 3. .replworks/TECH_STACK.md 4. .replworks/ARCHITECTURE.md 5. .replworks/TASKS.md - Only these documents are authoritative. + +Only these documents are authoritative. --- @@ -17,10 +18,11 @@ Ignore all files under: ```text docs/ +.replworks/docs/ ``` -Never use files in docs/ as requirements. -Never implement features described only in docs/. +Never use files in these folders as requirements. +Never implement features described only in these folders. --- @@ -66,6 +68,19 @@ everything else --- +## CONFLICT_HANDLING + +When documents conflict: + +1. Follow the higher-priority document. +2. Report the conflict to the human. +3. Fix the lower-priority document together with the human before continuing. + +Never resolve a conflict silently. +Never leave a conflict in place after the task is complete. + +--- + ## DOCUMENT_RESPONSIBILITIES PRODUCT_SPEC.md defines: @@ -95,6 +110,9 @@ What should be implemented next. Do not move responsibilities between documents. +ARCHITECTURE.md must not contain technology, versions, or folder rules. +TECH_STACK.md must not contain component responsibilities or data flows. + --- ## EXTERNAL_BOUNDARY @@ -109,11 +127,28 @@ third-party API browser runtime behavior ``` +Libraries that run inside this codebase's own process are not an external boundary. + +--- + +## UNVERIFIED_MARK + +Add `[UNVERIFIED]` to the heading of the section that owns the gap. + +```text +Gaps in what the product is or does -> PRODUCT_SPEC.md +Gaps in how the product must be implemented -> TECH_STACK.md +Gaps in how the product works -> ARCHITECTURE.md +``` + +Clear the mark only after human confirmation. + --- ## IMPLEMENTATION_RULES Implement only the selected task. +Exception: HUMAN_OWNED_CHANGES. Do not implement: ```text @@ -139,6 +174,16 @@ ARCHITECTURE.md --- +## TASK_SELECTION + +Implement the task named by the human. +If none is named, use the first unchecked MVP task in TASKS.md +whose dependencies are all marked `[X]`. + +Do not select tasks from the Future section unless the human names them. + +--- + ## TASK_EXECUTION For every task: @@ -147,10 +192,10 @@ For every task: 2. Read TECH_STACK.md 3. Read ARCHITECTURE.md 4. Read task definition -5. If the task touches a domain not covered by verified knowledge in PRODUCT_SPEC.md or ARCHITECTURE.md: stop. Mark the relevant section UNVERIFIED. Do not implement against an UNVERIFIED section. Require explicit human confirmation before continuing. +5. If the task touches a domain that is not covered by verified knowledge in PRODUCT_SPEC.md, TECH_STACK.md, or ARCHITECTURE.md: stop. Mark the relevant section UNVERIFIED (see UNVERIFIED_MARK). Do not implement against an UNVERIFIED section. Require explicit human confirmation before continuing. 6. Implement 7. Write unit tests for internal logic -8. If the task touches an EXTERNAL_BOUNDARY: write an E2E test against the live boundary. A mocked test alone does not satisfy this step. +8. If the task touches an EXTERNAL_BOUNDARY: write an E2E test against the live boundary. A mocked test alone does not satisfy this step. If the live boundary is unreachable, stop and report. Do not mark the task `[X]`. 9. Run all tests 10. Mark the completed task `[X]` in TASKS.md 11. Stop @@ -190,17 +235,24 @@ Stop. Do not invent requirements. ``` -Update PRODUCT_SPEC.md, and clear the UNVERIFIED mark only after human confirmation, before implementation continues. +1. Propose the change to the human. +2. Update PRODUCT_SPEC.md only after human confirmation. +3. Clear the UNVERIFIED mark only after human confirmation. +4. Continue implementation. --- ## TECH_STACK_CHANGES -If implementation requires tech stack changes: +If implementation requires tech stack changes, or a TECH_STACK.md section is marked UNVERIFIED: + +1. Stop. Propose the change to the human. +2. If the change conflicts with PRODUCT_SPEC.md, see CONFLICT_HANDLING. +3. Update TECH_STACK.md only after human confirmation. +4. Clear the UNVERIFIED mark only after human confirmation. +5. Update implementation. -1. Update TECH_STACK.md -2. Update implementation - Never allow tech stack and code to diverge. +Never allow tech stack and code to diverge. --- @@ -208,17 +260,60 @@ If implementation requires tech stack changes: If implementation requires architecture changes, or an ARCHITECTURE.md section is marked UNVERIFIED: -1. Update ARCHITECTURE.md -2. Clear the UNVERIFIED mark only after human confirmation -3. Update implementation - Never allow architecture and code to diverge. +1. Stop. Propose the change to the human. +2. If the change conflicts with PRODUCT_SPEC.md or TECH_STACK.md, see CONFLICT_HANDLING. +3. Update ARCHITECTURE.md only after human confirmation. +4. Clear the UNVERIFIED mark only after human confirmation. +5. Update implementation. + +Never allow architecture and code to diverge. --- ## TASK_CHANGES -If implementation invalidates a task: -Update TASKS.md. +If implementation invalidates a task, or PRODUCT_SPEC.md changes: + +1. Propose the TASKS.md change to the human. +2. Update TASKS.md only after human confirmation. + +Never change an existing task ID. +Never regenerate TASKS.md from scratch. + +These rules bind the AI. The human may edit TASKS.md directly at any time. +Human edits are authoritative. +If a task's Depends on ID no longer exists, treat the dependency as removed +by the human, and mention it when you stop. + +--- + +## HUMAN_OWNED_CHANGES + +Content and visual design are human-owned. +They are not specified in PRODUCT_SPEC.md and are not tracked in TASKS.md. + +```text +Content: wording, copy, translations, images, data text +Visual design: styling, spacing, colors, typography, imagery, visual polish +``` + +Not human-owned: which screens and elements exist, their purpose, +their arrangement relative to each other, their states, and their interactions. +These are specified in PRODUCT_SPEC.md. + +When the human explicitly asks for such a change in the session: + +1. Make only that change. +2. Do not change behavior, screens, elements, states, or interactions + defined in PRODUCT_SPEC.md. + If the change would, stop (see PRODUCT_SPEC_CHANGES). +3. Do not record the change in TASKS.md or any other document. +4. Run the verification commands defined in TECH_STACK.md. +5. Stop. + +Never make such changes on your own initiative. +If a task needs content or styling and none is provided, +use neutral placeholders and report them when you stop. --- @@ -256,9 +351,11 @@ Task is complete only when: - product requirements satisfied - architectural requirements satisfied - tech stack constraints satisfied -- acceptance criteria satisfied +- the task's acceptance criteria in TASKS.md satisfied - no UNVERIFIED sections remain in scope for this task +- no unresolved document conflicts remain - code runs - unit tests pass - E2E tests pass for any EXTERNAL_BOUNDARY code touched - Then stop. + +Then stop. diff --git a/templates/prompts/ARCHITECTURE_REVIEW_PROMPT.txt b/templates/prompts/ARCHITECTURE_REVIEW_PROMPT.txt index 8edd121..2f15295 100644 --- a/templates/prompts/ARCHITECTURE_REVIEW_PROMPT.txt +++ b/templates/prompts/ARCHITECTURE_REVIEW_PROMPT.txt @@ -1,30 +1,46 @@ Review these documents together: +- AGENTS.md - PRODUCT_SPEC.md - TECH_STACK.md - ARCHITECTURE.md Generate only blocking questions. +A question is blocking only if an AI implementer would have to guess +to proceed. Do not ask about style, completeness, or preference. + +Before answering, map every requirement in PRODUCT_SPEC.md +to the component that owns it in ARCHITECTURE.md. +Do not output the mapping. + Check for: - product requirements without architectural ownership - components with overlapping responsibilities - missing inputs or outputs - undefined data flows -- conflicts with TECH_STACK.md -- architecture decisions that introduce unapproved product behavior - missing failure boundaries - contradictory invariants +- conflicts between PRODUCT_SPEC.md and TECH_STACK.md +- conflicts between ARCHITECTURE.md and TECH_STACK.md +- technology, version, or folder rules leaking into ARCHITECTURE.md +- responsibilities in ARCHITECTURE.md that belong to PRODUCT_SPEC.md or TECH_STACK.md + (use DOCUMENT_RESPONSIBILITIES in AGENTS.md as the definition) +- architecture decisions (including Resolved Decisions) that introduce + product behavior not stated in PRODUCT_SPEC.md +- any section marked [UNVERIFIED] in any document + +For each question, state: +- which document and section it concerns +- what is ambiguous or conflicting +- why an implementer cannot proceed without an answer Do not suggest new features. - Do not choose alternative technologies. - Do not redesign the architecture. +Do not propose fixes. Questions only. -If no blocking questions exist, output: +If no blocking questions exist, output exactly: -```text Architecture can be implemented with high confidence. -``` diff --git a/templates/prompts/EXECUTION_VALIDATION_PROMPT.txt b/templates/prompts/EXECUTION_VALIDATION_PROMPT.txt index 2d53db0..c4c4e9c 100644 --- a/templates/prompts/EXECUTION_VALIDATION_PROMPT.txt +++ b/templates/prompts/EXECUTION_VALIDATION_PROMPT.txt @@ -1,57 +1,69 @@ -Review the following documents together: +You are about to implement this product. + +Follow AGENTS.md. +Read the documents in DOCUMENT_ORDER: - PRODUCT_SPEC.md - TECH_STACK.md - ARCHITECTURE.md -Assume you are responsible for implementing the entire product. +Treat these three documents as the entire implementation contract. +Ignore TASKS.md. -Assume no additional information will be provided. +## Step 1: Contract check -Your goal is to determine whether implementation can begin with confidence. +Assume the repository is empty and no additional information will be provided. +Existing source code is not evidence that the contract is sufficient. -Generate only questions. +Dry-run the implementation of the entire product. +For every behavior stated in PRODUCT_SPEC.md, determine: -Do not answer questions. +- which component owns it +- what its inputs and outputs are +- how data reaches it and leaves it +- where it is implemented under the constraints in TECH_STACK.md -Do not suggest improvements. +Every point where you would have to stop or guess is a blocking question. +Do not ask about behavior PRODUCT_SPEC.md does not claim. -Do not suggest new features. +Also report as blocking: -Do not redesign the product. +- contradictions between the documents (apply the priority in AGENTS.md) +- behavior that depends on an external boundary + with no recorded observation or spec and no [UNVERIFIED] mark +- any section marked [UNVERIFIED] -Do not modify requirements. +## Step 2: Code divergence check -Focus on identifying: +Run this step only if the repository contains source code. -- missing requirements -- missing architectural responsibilities -- missing implementation constraints -- ambiguous behavior -- conflicting definitions -- undefined ownership -- undefined flows -- undefined inputs -- undefined outputs -- contradictions between documents +Report as blocking only: -Treat the three documents as a single implementation contract. +- code that contradicts the three documents + (including TECH_STACK.md versions and folder rules) +- behavior the code already implements that PRODUCT_SPEC.md does not state -A question is valid only if it blocks implementation certainty. +Documented behavior that is not implemented yet is not a divergence. -Ignore: +## Rules -- personal preferences -- alternative technologies -- feature ideas -- product strategy +Do not write code. +Do not create or modify any file. +Do not run commands or call external services. +Do not answer the questions. +Do not suggest improvements, new features, or alternative technologies. -Output only a numbered list of questions. +## Output -If no blocking questions exist, output: +Output only a numbered list of questions in chat, +most blocking first, at most 15. -```text -Implementation can begin with high confidence. -``` +Each question must state: +- which step it comes from (1 or 2) +- which document and section it concerns (and which file, for step 2) +- what is undefined or conflicting +- why you cannot proceed without an answer -Optimize for implementation certainty. +If no blocking questions exist, output exactly: + +Implementation can begin with high confidence. diff --git a/templates/prompts/PRODUCT_SPECIFICATION_PROMPT.txt b/templates/prompts/PRODUCT_SPECIFICATION_PROMPT.txt index d88aea4..1cf969a 100644 --- a/templates/prompts/PRODUCT_SPECIFICATION_PROMPT.txt +++ b/templates/prompts/PRODUCT_SPECIFICATION_PROMPT.txt @@ -1,39 +1,83 @@ Generate PRODUCT_SPEC.md. -Assume all product discovery and idea validation are already complete. - +INPUT +- The product information provided with this request. + Product discovery and idea validation are complete and final. + It is the only source of product information. +- If wireframes or mockups are provided, translate their structure into text. + MUST NOT reference or embed image files. +- MUST NOT create any other document. +- Output the contents of PRODUCT_SPEC.md only. + +STOP CONDITIONS +If information required for any section is missing, ambiguous, or contradictory: +output ONLY a numbered list of questions. Nothing else. +After I answer, treat my answers as final input and continue. +MUST NOT invent information to fill a gap. + +PURPOSE The purpose of PRODUCT_SPEC.md is to define: -```text What the product is. What the product does. +How it works from the end user's perspective, including its UI and UX. What the user can do. What success means. -``` - -Do not describe implementation. - -Do not describe architecture. - -Do not describe technologies. - -Do not describe tech stacks. - -Do not describe programming languages. - -Do not describe databases. - -Do not describe APIs. - -Do not describe internal components. -Do not describe directory structures. - -Focus only on externally observable product behavior. - -The document should be sufficient for a product manager to approve the product scope. - -The document must include: +SCOPE BOUNDARY +- Specify only what the end user can observe and do. +- UI and UX are product behavior. MUST specify them (see USER INTERFACE RULES). +- How the product works internally (mechanism) belongs to ARCHITECTURE.md. + MUST NOT describe implementation, architecture, technologies, tech stacks, + programming languages, databases, internal APIs, internal components, + or directory structures. +- Persistence is specified as observable behavior (what is kept across sessions), + never as storage technology. +- Human-owned. MUST NOT specify: + wording, copy, translations, images, + visual styling (colors, typography, spacing, visual polish). + Specify which content slots exist and what each is for, not their content. +- MUST NOT propose improvements. +- MUST NOT add features that were not discussed. +- MUST NOT expand the scope. + +USER INTERFACE RULES +For every surface the user interacts with: +- Screens: give each a stable ID (SCR-001, ...), its purpose, and the elements on it. +- Elements: for each, its purpose and what the user can do with it. +- Arrangement: relative placement, grouping, and hierarchy only. + MUST NOT specify exact sizes, spacing, or visual styling. +- States: every state that applies (initial, empty, loading, populated, error, + disabled) and what is shown in each. +- Navigation: for each trigger, the destination. +- Interactions: for each user action, the observable result. +- Platform or window-size differences, only if stated in the input. +For non-graphical products (e.g. command-line): +- Every command, option, input, and the structure of output that users + or other programs rely on, and exit behavior. + MUST NOT specify exact output wording unless programs depend on it. + +REQUIREMENT RULES +- Give every Functional Requirement a stable ID (FR-001, FR-002, ...). +- Tag every Functional Requirement MVP or Future. + Future means discussed but deferred. Non-Goals means explicitly excluded. + If the input does not make a tag clear, ask. +- Each requirement is one externally observable behavior that can be + verified pass/fail. If it cannot be written objectively, ask. +- Error Conditions specify the observable behavior for each condition. +- Acceptance Criteria reference requirement and screen IDs and are pass/fail verifiable. +- Success Criteria are outcomes measured outside the product. + They are not implementation requirements unless a Functional Requirement + states that the product must measure them. +- External Systems: list each external system the product depends on + and the behavior relied on. + Mark with [UNVERIFIED] the heading of any section whose behavior depends on + an external system whose behavior has not been observed. +- Constraints: only observable non-functional requirements stated in the input + (supported platforms or environments, performance, offline behavior, + data retention, accessibility). If none are stated, write "None stated." + +The document must include, in this order: - Purpose - Problem @@ -41,6 +85,9 @@ The document must include: - Users - Inputs - Outputs +- Constraints +- External Systems +- User Interface - Functional Requirements - User Flows - Error Conditions @@ -48,14 +95,9 @@ The document must include: - Acceptance Criteria - Success Criteria -Do not propose improvements. - -Do not add features that were not discussed. - -Do not expand the scope. - -Prefer explicit requirements over explanations. - -Optimize for implementation certainty. - -The document is intended for AI implementation, not human marketing. +FORMAT +- Flat terse bullets. "MUST" phrasing for requirements. +- Prefer explicit requirements over explanations. +- No marketing prose. +- Audience: AI implementer. +- Optimize for implementation certainty. diff --git a/templates/prompts/TASK_GENERATION_PROMPT.txt b/templates/prompts/TASK_GENERATION_PROMPT.txt index 686f9ed..0cd0004 100644 --- a/templates/prompts/TASK_GENERATION_PROMPT.txt +++ b/templates/prompts/TASK_GENERATION_PROMPT.txt @@ -1,69 +1,119 @@ Generate TASKS.md. -Assume PRODUCT_SPEC.md exists. +Follow AGENTS.md. -Assume ARCHITECTURE.md exists. +Assume PRODUCT_SPEC.md, TECH_STACK.md, and ARCHITECTURE.md +already exist and are correct. -Assume TECH_STACK.md exists. +Stop and report instead of generating TASKS.md if: + +- any section in these documents is marked [UNVERIFIED] +- the documents conflict (apply the priority in AGENTS.md) +- PRODUCT_SPEC.md does not make clear what belongs to MVP and what to Future The purpose of TASKS.md is to define: -```text -What remains to be implemented. -``` +What should be implemented next, in order. -TASKS.md is an execution checklist. +TASKS.md is an execution checklist for AI implementation, +not project management. -Do not describe architecture. +Do not include estimates, owners, dates, or priorities. +Do not create any other document. +Do not describe architecture. Do not describe technologies. - Do not describe tech stacks. - Do not describe implementation details. - Do not reference specific classes. - Do not reference specific files. - Do not reference specific libraries. -Generate implementation tasks only. +You may reference documents, document sections, +and component names defined in ARCHITECTURE.md. +Do not restate their content. -Tasks should represent user-visible capabilities or architectural milestones. +## Task rules -Each task must be independently completable. +Every task must satisfy at least one requirement in PRODUCT_SPEC.md. +Every MVP requirement must be satisfied by at least one task. +Do not create tasks for anything PRODUCT_SPEC.md does not state. -Each task must be independently testable. +TASKS.md contains only tasks whose acceptance criteria can be verified +by an automated test or an observable behavior. +Do not create tasks for content or visual design: +wording, copy, translations, images, styling, layout polish, colors. +These are human-owned and judged by a human (see HUMAN_OWNED_CHANGES in AGENTS.md). -Organize tasks into phases. +If PRODUCT_SPEC.md requires a content slot to exist, +the task verifies that the slot renders provided content, +not what the content says. -For each phase: +Each task must be a vertical slice: +an observable, testable behavior from user-visible input to output. +Do not create layer-only tasks. -- define tasks -- define acceptance criteria +Each task must be completable by one AI in one session, +assuming all earlier tasks are complete. +AGENTS.md requires stopping after each task. -Tasks must: +Order tasks so that every task depends only on earlier tasks. +Declare dependencies explicitly. -- be actionable -- be verifiable -- be implementation-independent +The first task is the project foundation. +Its acceptance criteria: the constraints in TECH_STACK.md are satisfied +and the checks defined there pass. +Do not restate TECH_STACK.md. -Avoid: +If a task touches an external boundary (as defined in AGENTS.md), +mark it, and require in its acceptance criteria +a recorded live observation and an E2E test against the live boundary. -- implementation steps -- code-level instructions -- tech-stack-specific instructions +## Acceptance criteria rules -Include: +Each task has its own acceptance criteria. +Each criterion must be pass/fail verifiable +by an automated test or an observable behavior. +Include failure behavior defined by the failure boundaries in ARCHITECTURE.md. +Include unit tests passing. +Do not use subjective wording. -- MVP -- Future +A task is complete only when all its acceptance criteria are satisfied. -Acceptance criteria must be objective. +## Existing code -A task is complete only when acceptance criteria are satisfied. +If the repository contains source code: -Optimize for autonomous execution by AI systems. +Still generate the full task list. +Never remove a task because it appears implemented. -The document is intended for AI implementation, not human project management. +Mark a task [X] only if you have verified every one of its +acceptance criteria by actually running the tests or observing the behavior. +Code that appears to implement a task is not verification. +If any criterion cannot be verified, leave the task [ ]. +A task with an external boundary may be marked [X] only +after its live E2E test has passed. + +If the repository has no source code, all tasks are [ ]. + +Generate TASKS.md only once. +After this, tasks are changed only as defined in AGENTS.md. + +## Structure + +Organize tasks into phases: MVP first, then Future. +MVP and Future are defined only by PRODUCT_SPEC.md. +Future tasks must not be implemented unless the human names them explicitly. +State this at the top of the Future section. + +Use this format for every task: + +- [ ] T-001 + - Satisfies: + - Components: + - Depends on: + - External boundary: yes | no + - Acceptance criteria: + - + +Optimize for autonomous execution by AI systems. diff --git a/templates/prompts/TECH_STACK_DISCOVERY_PROMPT.txt b/templates/prompts/TECH_STACK_DISCOVERY_PROMPT.txt index e217302..8c597f9 100644 --- a/templates/prompts/TECH_STACK_DISCOVERY_PROMPT.txt +++ b/templates/prompts/TECH_STACK_DISCOVERY_PROMPT.txt @@ -3,7 +3,9 @@ ARCHITECTURE.md does not exist yet. It will be written AFTER TECH_STACK.md. PURPOSE Discover every technology decision required to generate TECH_STACK.md. -Do NOT generate TECH_STACK.md. Do NOT generate code. +The final DECIDED log becomes TECH_DECISIONS, the sole source for TECH_STACK.md. +Do NOT generate TECH_STACK.md until I send the generation request in this conversation. +Do NOT generate code. SCOPE - The goal is technology decisions. Architecture may be discussed ONLY to @@ -16,6 +18,9 @@ SCOPE and continue. - Directory, state, and dependency questions are limited to what the chosen stack or framework mandates. +- Requirements come only from PRODUCT_SPEC.md. If a requirement is not stated + there (e.g. a performance target), do not record it as a decision. + Record it as a PRODUCT_SPEC GAP and continue. PROCESS - Ask one decision at a time. Wait for the answer before continuing. @@ -26,25 +31,45 @@ PROCESS - Do not evaluate or recommend technologies. Exception: if I explicitly ask for a recommendation on the current question, answer only that, then return to discovery mode. +- Every version MUST come from me or be verified by search with a source. + Never state a version from memory. This also applies to recommendations. + If a version cannot be verified, mark it UNVERIFIED and ask me. - If a later answer conflicts with a DECIDED item, stop and ask which one wins before continuing. +- If an answer conflicts with PRODUCT_SPEC.md, stop and ask whether to change + the answer or PRODUCT_SPEC.md before continuing. +- Every decision MUST map to one TECH_STACK.md section: + 1 Languages/runtimes/frameworks/libraries (exact versions) + 2 Directory rules, framework- or tool-mandated paths and file names + 3 Coding conventions + 4 Testing and verification (tools, coverage, commands) + 5 Configuration + 6 Deployment + 7 Security + 8 Non-goals + If a decision fits none, record it as an ARCH NOTE or PRODUCT_SPEC GAP. AREAS (in this order) 1. Platform (target platforms, runtime constraints, distribution targets) -2. Performance constraints (latency, throughput, memory) -3. Programming language -4. UI tech stack -5. Rendering (approach, graphics constraints) +2. Language and runtime (language, compile/run method, runtime + version, module system) +3. Package management (package manager, lockfile) +4. Framework and UI (framework + version, UI stack, rendering approach, if applicable) +5. External capabilities (for every external capability PRODUCT_SPEC requires: + library or built-in choice + version; dependency policy) 6. State management (stack-level mutation model only) 7. Persistence (storage technology and requirements) -8. Dependency policy (external dependency rules only) -9. Testing (test types, coverage expectations) -10. Configuration (env separation, secret storage) +8. Testing (test tool, test types, naming, coverage threshold, + whether tests may assert user-visible wording) +9. Code quality and verification (linter, formatter, and the commands for + lint, format check, build, test, and the single command that runs all of them) +10. Configuration (file format, file names, env var names, env separation, secret storage) 11. Logging (rules, sensitive information) 12. Security (secret handling, input validation) 13. Build (variants, constraints) -14. Deployment (targets, release environments) -15. Debugging / observability +14. Deployment (targets, release environments, release/distribution method, CI) +15. Project (license, top-level directory rules for source/tests/configuration, + paths and file names mandated by the framework or tools) +16. Debugging / observability OUTPUT FORMAT for each question: @@ -55,14 +80,20 @@ Affected Areas: Question: WAITING FOR ANSWER -After every answer, print both logs before the next question: +After every answer, print all three logs before the next question: DECIDED -- : +- : | version: | status: DECIDED or UNVERIFIED | section: <1-8> ARCH NOTES (non-binding, for ARCHITECTURE.md later) - +PRODUCT_SPEC GAPS +- + COMPLETION -When all areas are resolved, print the final DECIDED log and ARCH NOTES, -then stop. Do not generate TECH_STACK.md. +Do not complete while any item is UNVERIFIED. Resolve it with me first. +When all areas are resolved, print under the heading FINAL: +the final DECIDED log, ARCH NOTES, and PRODUCT_SPEC GAPS. +Then stop and wait. +Do not generate TECH_STACK.md until I send the generation request. diff --git a/templates/prompts/TECH_STACK_PROMPT.txt b/templates/prompts/TECH_STACK_PROMPT.txt index d1752b5..08550fe 100644 --- a/templates/prompts/TECH_STACK_PROMPT.txt +++ b/templates/prompts/TECH_STACK_PROMPT.txt @@ -1,48 +1,137 @@ -Generate TECH_STACK.md. - -INPUTS -- PRODUCT_SPEC.md: correct and final. Source of product requirements. -- TECH_DECISIONS: correct and final. Sole source of technology names and versions. -- ARCHITECTURE.md does not exist yet. It will be written AFTER this document, using it as input. - -SOURCE RULES -- Every technology, tool, library, version, file name, and env var name MUST come from TECH_DECISIONS. -- MUST NOT infer, invent, evaluate, or recommend technologies. -- MUST NOT restate product behavior from PRODUCT_SPEC (commands, options, sorting, error cases). -- If TECH_DECISIONS conflicts with PRODUCT_SPEC, stop and list the conflicts. - -REQUIRED DECISIONS CHECK -Verify TECH_DECISIONS defines all of the following. For each missing item, ask one question. -- runtime + version -- language + compile/run method -- module system -- package manager + lockfile -- web framework + version -- libraries (name + version): config parser, CLI argument parser, YouTube API client/HTTP -- test tool + coverage threshold -- linter, formatter -- CI system -- deployment target + release/distribution method -- license -- config file format, env var names, secret storage -If any item is missing or conflicting: output ONLY the numbered question list. Nothing else. - -SCOPE BOUNDARY -- Cover only technology choices and the rules that follow from them. -- MUST NOT define components, layers, modules, boundaries, data flow, responsibilities, or system structure. -- MUST NOT define directory layout beyond paths mandated by the chosen framework or tooling. -- MUST NOT include process rules (change control), product non-goals, or architectural invariants. -- State each rule once. MUST NOT repeat a rule across sections. - -OUTPUT FORMAT -- Exactly these 8 sections, in this order, numbered headings, no other sections: - 1. Languages / runtimes / frameworks / libraries (name + version constraint) - 2. Framework- or tool-mandated paths and file names only - 3. Coding conventions specific to the chosen stack - 4. Testing rules (tools, naming, required coverage) - 5. Configuration rules (env vars, config files, secrets handling) - 6. Deployment rules (targets, build, release steps) - 7. Security rules tied to the chosen stack - 8. Non-goals (technologies and tools explicitly excluded) -- Flat terse bullets. "MUST / MUST NOT" phrasing. No prose, no explanations, no "why". -- Audience: AI implementer. +Generate TASKS.md. + +Follow AGENTS.md. + +Assume PRODUCT_SPEC.md, TECH_STACK.md, and ARCHITECTURE.md +already exist and are correct. + +Stop and report instead of generating TASKS.md if: + +- any section in these documents is marked [UNVERIFIED] +- the documents conflict (apply the priority in AGENTS.md) +- PRODUCT_SPEC.md does not make clear what belongs to MVP and what to Future + +The purpose of TASKS.md is to define: + +What should be implemented next, in order. + +TASKS.md is an execution checklist for AI implementation, +not project management. + +Do not include estimates, owners, dates, or priorities. +Do not create any other document. + +Do not describe architecture. +Do not describe technologies. +Do not describe tech stacks. +Do not describe implementation details. +Do not reference specific classes. +Do not reference specific files. +Do not reference specific libraries. + +You may reference documents, document sections, +and component names defined in ARCHITECTURE.md. +Do not restate their content. + +## Scope of tasks + +TASKS.md contains only tasks whose acceptance criteria can be verified +by an automated test or an observable behavior. + +Do NOT create tasks for content or visual design. +These are human-owned and judged by a human +(see HUMAN_OWNED_CHANGES in AGENTS.md): + +- wording, copy, translations +- images +- visual styling: colors, typography, spacing, visual polish + +If PRODUCT_SPEC.md requires a content slot to exist, +the task verifies that the slot renders provided content, +not what the content says. + +DO create tasks for the UI and UX structure defined in PRODUCT_SPEC.md: + +- screens and the elements on them +- arrangement relationships +- states +- navigation +- interactions + +These are product behavior, verified by observable behavior +(e.g. UI or E2E tests). + +## Task rules + +Every task must satisfy at least one requirement in PRODUCT_SPEC.md. +Every MVP requirement must be satisfied by at least one task. +Do not create tasks for anything PRODUCT_SPEC.md does not state. + +Each task must be a vertical slice: +an observable, testable behavior from user-visible input to output. +Do not create layer-only tasks. + +Each task must be completable by one AI in one session, +assuming all earlier tasks are complete. +AGENTS.md requires stopping after each task. + +Order tasks so that every task depends only on earlier tasks. +Declare dependencies explicitly. + +The first task is the project foundation. +Its acceptance criteria: the constraints in TECH_STACK.md are satisfied +and the checks defined there pass. +Do not restate TECH_STACK.md. + +If a task touches an external boundary (as defined in AGENTS.md), +mark it, and require in its acceptance criteria +a recorded live observation and an E2E test against the live boundary. + +## Acceptance criteria rules + +Each task has its own acceptance criteria. +Each criterion must be pass/fail verifiable +by an automated test or an observable behavior. +Include failure behavior defined by the failure boundaries in ARCHITECTURE.md. +Include unit tests passing. +Do not use subjective wording. + +A task is complete only when all its acceptance criteria are satisfied. + +## Existing code + +If the repository contains source code: + +Still generate the full task list. +Never remove a task because it appears implemented. + +Mark a task [X] only if you have verified every one of its +acceptance criteria by actually running the tests or observing the behavior. +Code that appears to implement a task is not verification. +If any criterion cannot be verified, leave the task [ ]. +A task with an external boundary may be marked [X] only +after its live E2E test has passed. + +If the repository has no source code, all tasks are [ ]. + +Generate TASKS.md only once. +After this, tasks are changed only as defined in AGENTS.md. + +## Structure + +Organize tasks into phases: MVP first, then Future. +MVP and Future are defined only by PRODUCT_SPEC.md. +Future tasks must not be implemented unless the human names them explicitly. +State this at the top of the Future section. + +Use this format for every task: + +- [ ] T-001 + - Satisfies: + - Components: + - Depends on: + - External boundary: yes | no + - Acceptance criteria: + - + +Optimize for autonomous execution by AI systems.