diff --git a/templates/prompts/PRODUCT_SPECIFICATION_PROMPT.txt b/templates/prompts/PRODUCT_SPECIFICATION_PROMPT.txt index 0ec79d6..a72cb90 100644 --- a/templates/prompts/PRODUCT_SPECIFICATION_PROMPT.txt +++ b/templates/prompts/PRODUCT_SPECIFICATION_PROMPT.txt @@ -96,8 +96,41 @@ The document must include, in this order: - Acceptance Criteria FORMAT -- Flat terse bullets. "MUST" phrasing for requirements. -- Prefer explicit requirements over explanations. -- No marketing prose. -- Audience: AI implementer. -- Optimize for implementation certainty. +LANGUAGE +- Write the entire document in English, regardless of the input language. + Translate all input content into English. +- Exception: proper nouns and identifiers stay as given. +- Content slots are specified by purpose only (see SCOPE BOUNDARY), + so this rule never requires writing product copy. + +READER +- The only reader is a coding AI agent. There is no human reader. +- Optimize for unambiguous, direct implementation and test derivation. +- Every line MUST be an actionable, verifiable statement or a defined fact. + +STYLE +- MUST NOT include background, rationale, motivation, narrative, + introductions, summaries, transitions, or commentary. +- One behavior or fact per bullet. MUST NOT combine multiple behaviors + in one bullet. +- Use only "MUST" and "MUST NOT" for requirements. + MUST NOT use "should", "may", "can", "ideally", "preferably". +- MUST NOT use vague terms: "etc.", "and so on", "appropriate", "as needed", + "fast", "user-friendly", "properly", "similar". + Enumerate every item explicitly. If it cannot be enumerated, ask. +- Use one term per concept. Define it once in the section where it + first appears and reuse it exactly. MUST NOT use synonyms. +- Reference other items by ID only (FR-xxx, SCR-xxx, EL-xxx, ERR-xxx). + MUST NOT refer to them by description. + +STRUCTURE +- Flat bullets. Maximum nesting depth: 2. +- Per screen, use this fixed schema in this order: + ID / Purpose / Elements (EL-xxx: purpose, user actions) / + States / Navigation (trigger -> destination) / + Interactions (action -> observable result) +- Use "trigger -> result" lines for navigation and interactions. +- Give IDs to every element (EL-), error condition (ERR-), + and acceptance criterion (AC-). +- No emphasis styling, no emoji, no ASCII art, no images. +- Output the document only. diff --git a/templates/prompts/TASK_GENERATION_PROMPT.txt b/templates/prompts/TASK_GENERATION_PROMPT.txt index 0cd0004..657a1eb 100644 --- a/templates/prompts/TASK_GENERATION_PROMPT.txt +++ b/templates/prompts/TASK_GENERATION_PROMPT.txt @@ -5,15 +5,18 @@ 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: +Stop and report instead of generating TASKS.md only 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 documents conflict and the conflict cannot be resolved by the priority rules in AGENTS.md +- PRODUCT_SPEC.md contains unresolved product-scope ambiguity or contradiction +- a required behavior is undefined in PRODUCT_SPEC.md and cannot be derived + without inventing product behavior + +Do NOT stop merely because any document contains [UNVERIFIED]. The purpose of TASKS.md is to define: -What should be implemented next, in order. +What should be implemented next, in dependency order. TASKS.md is an execution checklist for AI implementation, not project management. @@ -33,50 +36,122 @@ You may reference documents, document sections, and component names defined in ARCHITECTURE.md. Do not restate their content. -## Task rules +## Scope rules + +PRODUCT_SPEC.md defines the complete current build scope. + +Do not require PRODUCT_SPEC.md to distinguish MVP from Future. +Do not invent an MVP/Future classification. + +Every buildable requirement stated in PRODUCT_SPEC.md is in the current scope. +Features excluded by PRODUCT_SPEC.md MUST NOT appear as tasks. -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. +## Task rules + +Every task must satisfy at least one requirement in PRODUCT_SPEC.md, +except an external-boundary verification task explicitly created +to resolve [UNVERIFIED] behavior required by a PRODUCT_SPEC.md requirement. + +Every requirement in PRODUCT_SPEC.md that requires implementation +must be satisfied by at least one task. + 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). +These are human-owned and judged by a human +(see HUMAN_OWNED_CHANGES in AGENTS.md). If PRODUCT_SPEC.md requires a content slot to exist, the task verifies that the slot renders provided content, not what the content says. -Each task must be a vertical slice: +Each implementation task must be a vertical slice: an observable, testable behavior from user-visible input to output. -Do not create layer-only tasks. + +Do not create layer-only implementation tasks. + +External-boundary verification tasks are an exception to the +user-visible vertical-slice rule. +Their purpose is to establish observed behavior at an external boundary +before dependent implementation work is performed. 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. +## Task ordering + +Order tasks by dependency. The first task is the project foundation. -Its acceptance criteria: the constraints in TECH_STACK.md are satisfied + +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. +If a PRODUCT_SPEC.md requirement depends on an external system +whose behavior is marked [UNVERIFIED], create one or more +prerequisite verification tasks before creating implementation tasks +that depend on that behavior. + +Do not infer, assume, or invent the unverified behavior. + +An external-boundary verification task MUST: + +- identify the external boundary by reference to the relevant document section +- record the observed live behavior needed by dependent tasks +- include an executable test or probe against the live boundary +- define the observed result in pass/fail terms + +After the required behavior has been verified, +dependent implementation tasks may rely on that recorded observation. + +Do not create speculative implementation tasks for behavior +that has not been verified. + +## External boundaries + +If a task touches an external boundary as defined in AGENTS.md, +mark it. + +For an external-boundary implementation task, +its acceptance criteria MUST include: + +- the required live behavior is observed at the boundary +- an E2E test exercises the product through the live boundary +- the observed success behavior passes +- the failure behavior defined by ARCHITECTURE.md passes + +For an external-boundary verification task, +its acceptance criteria MUST include +a recorded live observation and an executable probe or E2E check +against the live boundary. + +Do not replace live-boundary verification with mocked behavior. + +Mocks may be used in addition to live verification, +but a mock does not satisfy the external-boundary verification requirement. ## 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. + +Acceptance criteria MUST: + +- reference the behavior required by the task +- include applicable failure behavior defined in ARCHITECTURE.md +- include unit tests passing where unit tests apply +- avoid subjective wording A task is complete only when all its acceptance criteria are satisfied. @@ -88,32 +163,59 @@ 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. +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 [ ]. +An external-boundary implementation task may be marked [X] only +after its required live E2E test has passed. + +An external-boundary verification task may be marked [X] only +after its required live observation and executable probe or E2E check +have passed. + +If the repository has no source code, all implementation tasks are [ ]. + +## Execution model + +TASKS.md is generated from the current contents of: + +- PRODUCT_SPEC.md +- TECH_STACK.md +- ARCHITECTURE.md +- AGENTS.md + +Do not use Git history to infer product requirements, +scope, acceptance criteria, or external behavior. + +Do not infer missing requirements from existing code. + +Do not infer missing external behavior from documentation alone +when the relevant section is marked [UNVERIFIED]. 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. +Organize tasks in dependency order. + +Do not create MVP/Future phases unless PRODUCT_SPEC.md itself explicitly +defines such phases. Use this format for every task: - [ ] T-001 - Satisfies: - - Components: - - Depends on: - External boundary: yes | no - Acceptance criteria: - +For an external-boundary verification task, +use the same format and identify the referenced PRODUCT_SPEC.md section +whose required behavior is being verified. + Optimize for autonomous execution by AI systems.