Strengthen Design/Implement boundary and add explicit Subject & Scope to all prompts

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.

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.

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`.

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)

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).