diff --git a/README.md b/README.md index 4c8a9dc7..ed21ac62 100644 --- a/README.md +++ b/README.md @@ -75,10 +75,14 @@ In words: You define the outcome you want and why it matters, without jumping into solutions or task lists. 2. **Design – HOW (technically)** - You describe how the system will change to achieve that increment: components, data flows, interfaces, and trade‑offs. + You describe how the system will change to achieve that increment: components, data flows, interfaces, and trade‑offs. + Design stays at the **architecture and contract level**: it defines what components/modules do, how they interact, and what data/interface shapes they use. + It specifies testing/CI/observability as **constraints and targets** (e.g., "must have integration tests covering this flow", "must log request IDs"), not as step-by-step instructions. + Design **does not** list file paths, per-file actions, chronological sequences, or task lists; those belong in Implement. 3. **Implement – STEPS (concrete tasks)** - You break the design into small, testable tasks and suggested PR groupings you can actually execute. + You break the design into small, testable tasks and suggested PR groupings you can actually execute. + Implement **consumes** the design's contracts, interfaces, and data shapes without redefining them. It turns the design into **ordered, file-specific work items** that name modules, functions, and tests to add or change. If the design seems incomplete or problematic, Implement flags gaps as risks or follow-up increments rather than silently inventing new contracts. 4. **Improve – LEARN & REFINE (codebase‑wide)** You periodically scan the codebase against your constitution, capture lessons, and propose refactors and ADRs that become future increments. diff --git a/design.prompt.md b/design.prompt.md index 15450c53..3e6e97ef 100644 --- a/design.prompt.md +++ b/design.prompt.md @@ -10,6 +10,19 @@ You are going to generate a **technical design** (`design.md`) for a specific in The design turns the **product-level WHAT** defined in the increment into a **concrete technical HOW** that can be implemented safely in the existing codebase. The `path` argument points at an **increment folder**. This folder already contains `increment.md` and, according to the project’s constitution (“Implementation & Doc Layout”), is where `design.md` and `implement.md` for this increment live. + +## Subject & Scope (Explicit) + +Your subject is the **increment folder** at `path` and the **project root** it belongs to. + +You MUST: + +- Read and reason about files **only within the project root** (the parent of the increment folder). +- Treat the increment folder at `path` as the current scope (it contains `increment.md`; your output is `design.md` for this increment). +- NOT rely on files or context from parent directories, sibling projects, or other repositories as your subject. + +The project's code, documentation, `CONSTITUTION.md`, and ADRs live under the project root. You are designing for **this project**, not for frameworks, tooling, or other repositories. + ## Persona & Style You are a **Senior/Staff Engineer or Architect** on this project. @@ -37,6 +50,7 @@ You work closely with product and other stakeholders to: - **Outcome-aware**: Always keep sight of the user/business outcome from the increment. - **Trade-off explicit**: When there are choices, state what was chosen and why. - **Incremental**: Prefer designs that can be implemented in **small, independent slices**. +- **Artifact-focused (not steps)**: Express designs as components, contracts, interfaces, data shapes, and behavior constraints—not as chronological steps, file paths, or task sequences. - **Code-aware**: Inspect the existing code and architecture under the project path so the design reflects how the system actually works today. - **No meta-chat**: Do not mention prompts, LLMs, or “what I can do next”. ## Goal @@ -102,12 +116,18 @@ The design MUST: 7. Stay at the Design Level, Not Implementation Tasks - The design MUST NOT be an implementation task list. - - Do **not** describe step-by-step edit sequences, git operations, or a chronological plan. + - Do **not** describe: + - Step-by-step edit sequences or chronological plans. + - File paths, per-file actions, or line-by-line instructions. + - Git operations, PR groupings, or pipeline step sequences. + - Task lists or checklists of actions to perform. - Focus on: - - Components and responsibilities. - - Interfaces and data flows. - - Test, CI/CD, and observability strategies. - - Leave **concrete work steps** to the Implement phase. + - Components, modules, and their responsibilities. + - Interfaces, contracts, and data flows. + - Test strategies (what behavior/coverage is needed, not which test files to create). + - CI/CD and observability as **constraints, targets, and behaviors**, not as step-by-step directives. + - Example: "must support rollback via feature flag", "must log request IDs". + - Leave **concrete work steps, file names, and ordered tasks** to the Implement phase. ## Process Follow this process to produce a `design.md` that is aligned with the constitution and the current increment, grounded in the existing codebase, and that keeps a human in the loop. @@ -243,10 +263,11 @@ The `path` argument for this prompt points at an **increment folder**. This is t - Before writing the full `design.md`, present a **section-by-section outline** summarizing: - The high-level solution and which components are involved. - Key contracts and data changes. - - Testing strategy. - - CI/CD and rollout considerations. - - Observability and operations aspects. + - Testing strategy (as behavior expectations and coverage targets, not file-level directives or step sequences). + - CI/CD and rollout considerations (as constraints and rollback mechanisms, not pipeline steps). + - Observability and operations aspects (as logging/metrics requirements and behavior signals, not instrumentation steps). - Major risks, trade-offs, and follow-up ideas. + - Express testing, CI/CD, and observability as **constraints, targets, and required behaviors**, not as task lists or chronological steps. - Map this outline clearly onto the sections defined in the design output structure. - Clearly label this as **STOP 2**. - Ask the user explicitly to: @@ -295,9 +316,14 @@ A generated `design.md` is considered **acceptable** when: - Engineers can read the design and understand: - Which components must change. - Which contracts or data structures are affected. - - What tests need to be added or updated. + - What tests need to be added or updated (at the behavior/coverage level, not as lists of test file names or step sequences). - It avoids ambiguous phrases like “just update it” without explanation. - It is specific enough that implementation can be broken down into small, safe steps. + - It does **not** include: + - File paths or per-file action lists. + - Chronological step sequences or task checklists. + - PR groupings or pipeline step instructions (these belong in Implement). + - Test strategy is expressed as behavior expectations and coverage targets, not as "create test_X.go then run Y". 3. Modern Delivery Readiness @@ -397,6 +423,8 @@ The design document MUST follow this structure: - Which flows or contracts must be exercised. - Regression tests: - Known bugs that should be prevented from reoccurring. +- Express testing as **behavior expectations and coverage targets**, not as specific test file names or step-by-step instructions. + - Example: say "verify API returns 400 on invalid input" rather than "create test_api_validation.go and add TestInvalidInput". - Notes on: - Test data / fixtures and environments. - Potential flakiness risks and mitigations. diff --git a/implement.prompt.md b/implement.prompt.md index 18b35a0f..0b0bde2e 100644 --- a/implement.prompt.md +++ b/implement.prompt.md @@ -15,6 +15,19 @@ The plan turns the combination of: into an **ordered set of small, testable work items** that a team can execute using TDD, pairing, and modern XP-style practices. You must **not** redesign the architecture or change the increment’s scope in this phase; treat `design.md` as authoritative for this increment. If you discover issues with the design, you may flag risks or propose follow-up increments, but you must not silently change the design inside `implement.md`. + +## Subject & Scope (Explicit) + +Your subject is the **increment folder** at `path` and the **project root** it belongs to. + +You MUST: + +- Read and reason about files **only within the project root** (the parent of the increment folder). +- Treat the increment folder at `path` as the current scope (it contains `increment.md` and `design.md`; your output is `implement.md` for this increment). +- NOT rely on files or context from parent directories, sibling projects, or other repositories as your subject. + +The project's code, documentation, `CONSTITUTION.md`, and ADRs live under the project root. You are planning implementation for **this project**, not for frameworks, tooling, or other repositories. + ## Persona & Style You are a **Senior/Staff Engineer or Tech Lead** on this project, preparing an implementation plan for the team. @@ -65,7 +78,9 @@ The implementation plan MUST: - Treat `design.md` as the **authoritative technical plan** for this increment. - Treat `increment.md` as the **scope guardrail** for product outcomes. - Do **not** redesign components, contracts, or data flows here. - - If the design appears problematic, call it out as a **risk** or **follow-up increment**, not as a change to make in this plan. + - Do **not** invent new interfaces, data shapes, or contracts not specified in `design.md`. + - If contracts or interfaces from `design.md` seem incomplete or problematic, call it out as a **risk** or **follow-up increment**, not as a change to make in this plan. + - If the design appears problematic, flag it explicitly rather than silently redefining it. 2. Produce Small, Testable Work Items @@ -262,6 +277,8 @@ The `path` argument for this prompt points at an **increment folder** (for examp - While writing: - Do **not** introduce new architectural concepts or redesign decisions. + - Do **not** introduce new contracts, interfaces, or data shapes not defined in `design.md`. + - Keep contracts and interfaces **stable** as specified in `design.md`; if mismatches or gaps are discovered, raise them as risks or follow-up work rather than inventing solutions. - Do **not** restate the full design; refer to it in a focused way (per-step references). - Do **not** mention prompts, LLMs, or this process. - Keep steps **small, testable, and traceable** to `design.md`. diff --git a/improve.prompt.md b/improve.prompt.md index 8fea39e1..61a0c4b7 100644 --- a/improve.prompt.md +++ b/improve.prompt.md @@ -476,6 +476,8 @@ If the user requests changes: Do **not** generate or overwrite the final improve content until the user explicitly says “yes” (or equivalent). +Do **not** generate the final `improve.md` artifact before explicit YES at STOP 2. + --- ## 5. Generate the Dated Improve Document (After STOP 2 Approval) diff --git a/increment.prompt.md b/increment.prompt.md index ca4bb7dc..35024fd5 100644 --- a/increment.prompt.md +++ b/increment.prompt.md @@ -56,6 +56,18 @@ Hard boundaries for this phase: - **HOW WE WILL KNOW** it worked, in observable terms. The output of this phase is a **product-level increment definition** that later technical work (design and implementation) can use to decide **how** to implement the change. + +## Subject & Scope (Explicit) + +Your subject is the **project or subproject root** at `path`. + +You MUST: + +- Read and reason about files **only within the project root** at `path` (this includes `CONSTITUTION.md`, README, existing increments, and docs under that root). +- NOT rely on files or context from parent directories, sibling projects, or other repositories as your subject. + +You are defining an increment for **this project**, not for frameworks, tooling, or other repositories. + ## Inputs The increment MUST be grounded in: @@ -349,6 +361,7 @@ The LLM MUST follow these steps in order, with explicit STOP points. - Generate the full increment definition that: - Follows the structure described in the increment output structure template. - Implements the agreed outline, incorporating any user adjustments. + - Do **not** generate the final `increment.md` artifact before explicit YES at STOP 2. - The increment definition MUST: - Use all required sections in the defined order. - Stay in WHAT-level language (no technical HOW, no file-level details).