Refactor architecture decision processes across templates

- Updated `pb-build` templates to enforce architecture decision adherence, ensuring that all tasks and subagents follow the approved design patterns and principles.
- Enhanced `pb-init` templates to capture architecture decision snapshots, including established patterns and dependency injection boundaries.
- Revised `pb-plan` templates to require explicit architecture decisions before implementation, emphasizing the importance of SRP, DIP, and other architectural principles.
- Improved documentation in `design_template.md` and `tasks_template.md` to clarify architecture decision requirements and project identity alignment.
- Added tests to verify that templates enforce architecture decision rules and capture necessary context for implementers.
- Bumped version to 0.8.0 to reflect these changes.

Author: Akagi201

README.md

@@ -34,6 +34,7 @@ pb-spec follows a **harness-first** philosophy: reliability comes from process d
 - **Behavior Before Code:** `/pb-plan` turns user-visible requirements into Gherkin `.feature` scenarios before implementation begins.
 - **Verification by Design:** Planning requires explicit verification commands so completion is measurable.
 - **Observability as Context:** Service-facing tasks must capture runtime evidence (log tails and/or health probes), not only test output.
+- **Architecture Before Implementation:** `/pb-init` snapshots established architecture decisions, `/pb-plan` records explicit `Architecture Decisions`, and `/pb-build` executes against that contract instead of inventing a new one.
 - **Double-Loop Execution:** `/pb-build` enforces a BDD outer loop plus a TDD inner loop with per-task status tracking.
 - **Escalation Over Thrashing:** Three consecutive failures suspend the current task and route a standardized DCR packet to `/pb-refine`.
 - **Safe Failure Recovery:** Failed attempts use scoped recovery guidance to avoid polluting unrelated workspace state.
@@ -131,6 +132,8 @@ Merge behavior is non-destructive:
 
 This design avoids relying on any fixed `AGENTS.md` section layout and protects user-maintained constraints across re-runs.
 
+The managed snapshot now also includes an **Architecture Decision Snapshot** so later agents inherit repo-level conventions instead of re-deciding them every run. Typical entries include established patterns, dependency-injection boundaries, error-handling conventions, and workflow/state-modeling rules.
+
 ### 2. `/pb-plan <requirement>` — Design & Task Planning
 
 Takes a natural-language requirement and produces a complete feature spec:
@@ -153,6 +156,8 @@ It also performs two additional planning audits before implementation starts:
 - Template identity alignment: if the repo still contains generic crate/package/module names from a scaffold, `pb-plan` must front-load renaming those identifiers to project-matching names.
 - Risk-based advanced testing: property testing is planned by default for broad input-domain logic, while fuzzing and benchmarks are added only when the feature profile justifies them. Tool selection follows repo language conventions: `Hypothesis` / `fast-check` / `proptest`, `Atheris` / `jazzer.js` / `cargo-fuzz`, and `pytest-benchmark` / `Vitest Bench` / `criterion`.
 
+It also adds an explicit **Architecture Decisions** section to `design.md`. For work that introduces a new boundary or is likely to exceed 200 lines, planning must evaluate **SRP**, **DIP**, and the classic patterns **Factory**, **Strategy**, **Observer**, **Adapter**, and **Decorator**. The chosen pattern must be justified against alternatives and checked against the code-simplification lens so the design stays simpler, not just more abstract.
+
 ### 3. `/pb-refine <feature-name>` — Design Iteration (Optional)
 
 Reads user feedback or Design Change Requests (from failed builds, including standardized 3-failure build-block packets) and intelligently updates `design.md` and `tasks.md`. It maintains a revision history and cascades design changes to the task list without overwriting completed work. `AGENTS.md` remains read-only in this phase.
@@ -161,6 +166,8 @@ Reads user feedback or Design Change Requests (from failed builds, including sta
 
 Reads `specs/<YYYY-MM-DD-NO-feature-name>/tasks.md` and implements each task sequentially. Every `BDD+TDD` task is executed by a fresh subagent following an outside-in double loop: run the Gherkin scenario first so the BDD outer loop is red, drive the implementation with TDD (Red → Green → Refactor) in the inner loop, then re-run the scenario until it passes. Runtime verification (log/health evidence when applicable) still applies. Supports **Design Change Requests** if the planned design proves infeasible during implementation, and auto-escalates to DCR after three consecutive task failures. Only the `<feature-name>` part is needed when invoking — the agent resolves the full directory automatically. `AGENTS.md` is read-only unless the user explicitly requests an `AGENTS.md` change.
 
+`/pb-build` is now explicitly architecture-bound: it reads the repo's **Architecture Decision Snapshot**, follows the feature's **Architecture Decisions**, re-checks **SRP** and **DIP** during execution, and keeps external dependencies behind interfaces or abstract classes when the design requires that seam. It should not improvise a different Factory, Strategy, Observer, Adapter, or Decorator choice mid-build.
+
 ## Skills Overview
 
 | Skill | Trigger | Output | Description |
@@ -179,6 +186,7 @@ pb-spec's prompt design is inspired by Anthropic's research on [Effective Harnes
 | Principle | How pb-spec Implements It |
 |---|---|
 | **State Grounding** | Subagents must verify workspace state (`ls`, `find`, `read_file`) before writing any code — preventing path hallucination |
+| **Architecture Continuity** | `pb-init` records an Architecture Decision Snapshot, `pb-plan` makes Architecture Decisions explicit, and `pb-build` verifies implementation still conforms to that contract |
 | **Error Quoting** | Subagents must quote specific error messages before attempting fixes — preventing blind debugging |
 | **Context Hygiene** | Orchestrator passes only minimal, relevant context to each subagent — preventing context window pollution |
 | **Recovery Loop** | Failed tasks use pre-task snapshots + file-scoped recovery (`git restore` + task-local cleanup), and avoid workspace-wide restore in dirty trees |

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "pb-spec"
-version = "0.7.1"
+version = "0.8.0"
 description = "Plan-Build Spec (pb-spec): A CLI tool for managing AI coding assistant skills"
 readme = "README.md"
 license = "Apache-2.0"

src/pb_spec/templates/prompts/pb-build.prompt.md

@@ -9,6 +9,7 @@ Run this when the user invokes `/pb-build <feature-name>`.
 - Complete unfinished tasks in `tasks.md` sequentially until done or explicitly blocked.
 - Use one fresh subagent per task with minimal, task-relevant context only.
 - Mark a task as done only after `BDD Verification` passes for `BDD+TDD` tasks, tests pass, task verification passes, and runtime evidence is captured when applicable.
+- Treat `design.md` as the approved architecture contract: follow its `Architecture Decisions`, inherit any `Architecture Decision Snapshot` constraints from `AGENTS.md`, and do not improvise a new pattern mid-build.
 - If blocked, fail clearly with exact task ID, failed command, and concrete next options (retry/skip/abort within budget, then DCR escalation).
 
 ---
@@ -63,15 +64,18 @@ For each unfinished task, in order:
 1. **Extract** the full task block (Context, Scenario Coverage, Loop Type, Steps, BDD Verification, Verification).
 2. **Gather context** — read `design.md` and `AGENTS.md` (if it exists). Treat `AGENTS.md` as read-only policy context.
    - Read any referenced `.feature` files under `specs/<spec-dir>/features/`.
+   - Extract the relevant `Architecture Decisions` from `design.md` and any `Architecture Decision Snapshot` constraints from `AGENTS.md` that apply to this task.
    - Record a pre-task workspace snapshot (`git status --porcelain` + tracked/untracked file lists) for safe rollback.
 3. **Spawn a fresh subagent** with the Implementer Prompt (below), filled in with the task content and project context.
    **Context Hygiene:** Do NOT pass the entire chat history. Pass ONLY:
    - The specific Task Description from `tasks.md`.
    - The `AGENTS.md` (project constraints and hard rules; do not assume any fixed template layout).
    - The `design.md` (Feature Spec).
    - The relevant `.feature` file content and scenario name when `Loop Type` is `BDD+TDD`.
+   - The task-relevant `Architecture Decisions` and `Architecture Decision Snapshot` excerpts, including any SRP, DIP, Factory, Strategy, Observer, Adapter, or Decorator choice and any requirement to route external dependencies through interfaces or abstract classes.
    - **Summary of previous tasks** — a one-line-per-task summary (e.g., "Task 1.1 created `models.py` with `User` class."). Do NOT pass raw logs or full outputs.
 4. **Subagent executes** the BDD + TDD + runtime verification cycle (see Implementer Prompt section).
+   - The subagent must restate the architecture contract before coding and verify it still conforms after implementation.
 5. **Mark completed** — update `- [ ]` to `- [x]` and Status to `🟢 DONE` in `tasks.md`.
    - **Use precise editing:** Use `sed`, string-replacement, or line-targeted edits to update the specific Task ID heading and its checkboxes. Do NOT rewrite the entire `tasks.md` file — this risks truncation and content loss in large files.
    - **Completion gate:** Mark done only when `BDD Verification` is satisfied for `BDD+TDD` tasks, task Verification is satisfied, tests are green, and runtime checks (when applicable) are evidence-backed.
@@ -177,10 +181,10 @@ Summary must be factual and command-backed: do not claim "passed" or "completed"
 ## Subagent Rules
 
 1. **One subagent per task.** Never combine tasks.
-2. **Fresh context per subagent.** Only: task description, non-obvious constraints (AGENTS.md) + design (design.md), summary of completed tasks, files on disk.
+2. **Fresh context per subagent.** Only: task description, non-obvious constraints (AGENTS.md) + design (design.md), relevant `Architecture Decisions`, summary of completed tasks, files on disk.
 3. **Sequential execution.** Strict `tasks.md` order. No parallelism.
 4. **Independence.** Cross-task state lives in files, not memory.
-5. **Grounding first.** Every subagent verifies workspace state before writing code.
+5. **Grounding first.** Every subagent verifies workspace state before writing code and restates the architecture contract it must preserve.
 6. **Verifiable closure.** A task closes only after explicit verification evidence.
 
 ---
@@ -252,6 +256,7 @@ Update `tasks.md` in-place after each task using **precise edits** (target the s
 9. **Context hygiene.** Pass minimal, relevant context. Summarize — don't dump.
 10. **Evidence over assertion.** Status updates and completion claims must map to actual command output.
 11. **Escalate deterministically.** After three consecutive failures, stop thrashing and route to `pb-refine` with a structured DCR.
+12. **Architecture decisions are binding.** `pb-build` executes the approved design; it does not invent a different architecture during implementation.
 
 ---
 
@@ -273,7 +278,7 @@ You are implementing **Task {{TASK_NUMBER}}: {{TASK_NAME}}**.
 
 {{PROJECT_CONTEXT}}
 
-> From `AGENTS.md` (project constraints and rules) and `design.md` (feature design decisions).
+> From `AGENTS.md` (project constraints and rules), the repo's `Architecture Decision Snapshot`, and `design.md` (feature `Architecture Decisions`).
 
 ### Your Job
 
@@ -285,6 +290,7 @@ Before coding, define a compact task contract from the provided task block:
 - What must not change
 - How success is verified
 - Which `Scenario Coverage` entries and scenario name apply to this task
+- Which `Architecture Decisions` are binding for this task, including any SRP, DIP, Factory, Strategy, Observer, Adapter, or Decorator choice
 
 **1. Grounding & State Verification (Mandatory)**
 
@@ -294,6 +300,8 @@ Before writing any code, verify the current workspace state:
 - **Read Context:** Read target files to understand surrounding code and current state.
 - **Check Dependencies:** Verify modules you plan to import actually exist.
 - **Read `design.md`** for overall design context.
+- **Read the `Architecture Decisions` section** and restate the specific architecture contract for this task before coding.
+- **Read the `Architecture Decision Snapshot`** from `AGENTS.md` when present and preserve any repo-level constraints it establishes.
 - Identify existing patterns to follow.
 - Confirm task boundaries to avoid scope bleed.
 
@@ -309,6 +317,7 @@ Before writing any code, verify the current workspace state:
 | **BDD OUTER GREEN** | Re-run the BDD scenario until it passes for `BDD+TDD` tasks. | BDD scenario passes |
 | **Runtime Verification (if applicable)** | Run runtime checks from task Verification, capture logs + probe output (or explicit `N/A` reason). | Runtime evidence captured |
 | **REFACTOR** | Clean up if needed | ALL tests still pass |
+| **ARCHITECTURE CHECK** | Confirm the implementation still follows the selected `Architecture Decisions`, preserves SRP and DIP, and keeps external dependencies behind interfaces or abstract classes when required. | Architecture contract preserved |
 | **SCOPE CHECK** | Confirm implemented changes match task contract and nothing extra. | Task scope respected |
 
 **3. Self-Review Checklist**
@@ -319,6 +328,7 @@ Before writing any code, verify the current workspace state:
 - [ ] Test coverage — tests meaningfully verify requirements
 - [ ] No regressions — all pre-existing tests pass
 - [ ] BDD coverage — for `BDD+TDD` tasks, the referenced scenario failed first and then passed
+- [ ] Architecture conformance — the change still matches the selected `Architecture Decisions` and does not introduce a conflicting pattern
 - [ ] YAGNI — no over-engineering
 - [ ] Verification mapping — task's stated Verification is explicitly satisfied
 
@@ -358,6 +368,8 @@ Fix any "no" answers before submitting.
 - Only implement the current task.
 - Follow YAGNI — no speculative features.
 - Use existing patterns — match project style.
+- Follow approved architecture decisions — respect the task's `Architecture Decisions` and the repo's `Architecture Decision Snapshot`; do not improvise a different pattern mid-build.
+- do not improvise a new pattern mid-build. If the planned architecture no longer fits, raise a Design Change Request instead of silently switching patterns.
 - Do not modify `design.md` or `tasks.md`.
 - Do not modify, delete, or reformat `AGENTS.md` unless the user explicitly requests an `AGENTS.md` change.
 - Do not modify unrelated code.

src/pb_spec/templates/prompts/pb-init.prompt.md

@@ -62,7 +62,22 @@ Locate and list:
 - **CI**: `.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`
 - **Docs**: `README.md`, `docs/`, `CHANGELOG.md`
 
-## Step 4: Detect Active Specs
+## Step 4: Capture Architecture Decision Snapshot
+
+Search the project for explicit architecture decisions that later agents must inherit instead of reinventing:
+
+1. Read `AGENTS.md`, `CLAUDE.md`, `README.md`, `docs/`, active `specs/`, and nearby source modules for stated or strongly evidenced conventions.
+2. Record only decisions grounded in explicit evidence. **Only record decisions grounded in explicit evidence** — do not speculate from vague naming alone.
+3. Capture the current project position for:
+   - **Established Patterns** — e.g. Strategy, Adapter, typestate, repository, command objects
+   - **Dependency Injection Boundaries** — how external services, SDKs, clients, or storage are abstracted and injected
+   - **Error Handling Conventions** — shared error types, exception policies, result objects, recovery boundaries
+   - **State and Workflow Modeling** — how state transitions, orchestration, and long-running flows are represented
+   - **External Dependency Access** — whether network, filesystem, DB, or platform calls must go through interfaces, protocols, base classes, or wrapper services
+   - **Known Exceptions / TODOs** — temporary deviations or pending cleanups already documented in the repo
+4. If the repo does not expose explicit architecture decisions yet, write `No explicit architecture decisions detected.` instead of inventing guidance.
+
+## Step 5: Detect Active Specs
 
 Check if a `specs/` directory exists. If so, list each subdirectory as an active feature spec. For each spec, perform **dynamic status detection**:
 
@@ -80,7 +95,7 @@ Output format per spec:
 - `specs/<YYYY-MM-DD-NO-feature-name>/` — <status emoji> <status text> | Design: <design status> | Last modified: YYYY-MM-DD
 ```
 
-## Step 5: Write AGENTS.md (Managed Block, Non-Destructive)
+## Step 6: Write AGENTS.md (Managed Block, Non-Destructive)
 
 Write or update `AGENTS.md` at the project root using a **marker-based managed block**. Do NOT parse or rewrite user sections based on heading names.
 
@@ -128,6 +143,15 @@ This strategy is format-agnostic and prevents accidental loss of user-maintained
 - Config: {{config_path}}
 - Tests: {{tests_path}}
 
+### Architecture Decision Snapshot
+
+- Established Patterns: {{established_patterns}}
+- Dependency Injection Boundaries: {{dependency_injection_boundaries}}
+- Error Handling Conventions: {{error_handling_conventions}}
+- State and Workflow Modeling: {{state_and_workflow_modeling}}
+- External Dependency Access: {{external_dependency_access}}
+- Known Exceptions / TODOs: {{architecture_exceptions}}
+
 ### Suggested Conventions (Optional Defaults)
 
 - Commit style: conventional commits