@@ -125,6 +125,7 @@ Each step has a designated agent and a specific deliverable. No step is skipped.
125125│ docs/features/discovery.md (project-level) │
126126│ ALL backlog .feature files (discovery + entities sections) │
127127│ in-progress .feature file (full: Rules + Examples + @id) │
128+ │ ALL existing .py files in <package>/ ← know what exists first │
128129│ │
129130│ DOMAIN ANALYSIS │
130131│ From Entities table + Rules (Business) in .feature file: │
@@ -143,30 +144,28 @@ Each step has a designated agent and a specific deliverable. No step is skipped.
143144│ Any structure missing a named design pattern? │
144145│ → If pattern smell detected: load skill design-patterns │
145146│ │
146- │ Write Architecture section in in-progress .feature file │
147- │ ### Module Structure │
148- │ <package>/domain/<noun>.py │
149- │ class <Noun>: ← named class + responsibilities │
150- │ field: Type │
151- │ def <verb>(<Noun>) -> <Type>: ... ← typed signatures │
152- │ class <DepName>(Protocol): ... ← external dep contract │
153- │ <package>/domain/service.py ← cross-entity operations │
154- │ <package>/adapters/<dep>.py ← Protocol impl │
155- │ ### Key Decisions │
156- │ ADR-NNN: <title> │
157- │ Decision: <what> │
158- │ Reason: <why in one sentence> │
147+ │ WRITE STUBS INTO PACKAGE (signatures only — bodies must be `...`) │
148+ │ If file exists → add class/method; do not remove existing code │
149+ │ If file does not exist → create with signatures only │
150+ │ File placement (common patterns, not required names): │
151+ │ <package>/domain/<noun>.py ← entities, value objects │
152+ │ <package>/domain/service.py ← cross-entity operations │
153+ │ Do not pre-create ports/ or adapters/ without a concrete dep │
154+ │ Stub rules: │
155+ │ Bodies: `...` only — no logic, no conditionals │
156+ │ No docstrings — add after GREEN when signatures are stable │
157+ │ No inline comments, no TODO, no speculative code │
158+ │ │
159+ │ WRITE ADR FILES (significant decisions only) │
160+ │ docs/architecture/adr-NNN-<title>.md │
161+ │ Decision: <what> Reason: <why> │
159162│ Alternatives considered: <what was rejected and why> │
160- │ ### Build Changes (new runtime deps — requires PO approval) │
161- │ │
162- │ NOTE: signatures are informative — tests/implementation may │
163- │ refine them; record significant changes as ADR updates │
164163│ │
165164│ ARCHITECTURE SMELL CHECK — hard gate (fix before commit) │
166- │ [ ] No planned class with >2 responsibilities (SOLID-S) │
167- │ [ ] No planned class with >2 instance variables (OC-8) │
168- │ [ ] All external deps assigned a Protocol/Adapter (SOLID-D + │
169- │ Hexagonal Architecture) │
165+ │ [ ] No class with >2 responsibilities (SOLID-S) │
166+ │ [ ] No class with >2 instance variables (OC-8) │
167+ │ [ ] All external deps assigned a Protocol (SOLID-D + Hexagonal) │
168+ │ N/A if no external dependencies identified in scope │
170169│ [ ] No noun with different meaning across planned modules │
171170│ (DDD Bounded Context) │
172171│ [ ] No missing Creational pattern: repeated construction │
@@ -178,7 +177,7 @@ Each step has a designated agent and a specific deliverable. No step is skipped.
178177│ [ ] Each ADR consistent with each @id AC — no contradictions │
179178│ [ ] Technically infeasible story → escalate to PO │
180179│ │
181- │ commit: feat(<name>): add architecture │
180+ │ commit: feat(<name>): add architecture stubs │
182181│ │
183182└─────────────────────────────────────────────────────────────────────┘
184183 ↓
@@ -187,7 +186,8 @@ Each step has a designated agent and a specific deliverable. No step is skipped.
187186├─────────────────────────────────────────────────────────────────────┤
188187│ │
189188│ PREREQUISITES (stop if any fail — escalate to PO) │
190- │ [ ] Architecture section present in in-progress .feature file │
189+ │ [ ] Architecture stubs present in <package>/ (Step 2 committed) │
190+ │ [ ] Read all docs/architecture/adr-NNN-*.md files │
191191│ [ ] All tests written in tests/features/<feature>/ │
192192│ │
193193│ Build TODO.md test list │
@@ -203,7 +203,9 @@ Each step has a designated agent and a specific deliverable. No step is skipped.
203203│ │ INNER LOOP │ │
204204│ │ ┌───────────────────────────────────────────────────────┐ │ │
205205│ │ │ RED │ │ │
206+ │ │ │ Read stubs in <package>/ — base test on them │ │ │
206207│ │ │ Write test body (Given/When/Then → Arrange/Act/Assert) │ │
208+ │ │ │ Update stub signatures as needed — edit .py directly │ │ │
207209│ │ │ uv run task test-fast │ │ │
208210│ │ │ EXIT: this @id FAILS │ │ │
209211│ │ │ (if it passes: test is wrong — fix it first) │ │ │
@@ -216,10 +218,8 @@ Each step has a designated agent and a specific deliverable. No step is skipped.
216218│ │ │ (fix implementation only; do not advance @id) │ │ │
217219│ │ ├───────────────────────────────────────────────────────┤ │ │
218220│ │ │ REFACTOR │ │ │
219- │ │ │ Apply: DRY → SOLID → OC → patterns │ │ │
220- │ │ │ Load design-patterns skill if smell detected │ │ │
221- │ │ │ Add type hints and docstrings │ │ │
222- │ │ │ uv run task test-fast after each change │ │ │
221+ │ │ │ Load skill refactor — follow its protocol │ │ │
222+ │ │ │ uv run task test-fast after each individual change │ │ │
223223│ │ │ EXIT: test-fast passes; no smells remain │ │ │
224224│ │ └───────────────────────────────────────────────────────┘ │ │
225225│ │ │ │
@@ -368,25 +368,19 @@ Feature: <title>
368368
369369 Session 1 — Individual Entity Elicitation:
370370 | ID | Question | Answer | Status | ← OPEN / ANSWERED
371+ Template §1: PENDING | CONFIRMED
371372 Synthesis: <PO synthesis — confirmed by stakeholder>
373+ Pre-mortem: <gaps identified; new questions added above>
372374
373375 Session 2 — Behavior Groups / Big Picture:
374376 | ID | Question | Answer | Status |
375- Behavior Groups: <named behavior groups derived from answers>
377+ Template §2: PENDING | CONFIRMED
378+ Behavior Groups:
379+ - <behavior group name>: <one-sentence summary>
376380
377381 Session 3 — Feature Synthesis:
378- Synthesis: <full synthesis across behavior groups>
379- Approved: YES / NO
380-
381- Architecture: ← added at Step 2 by software-engineer
382-
383- ### Module Structure
384- - <package>/domain/entity.py — ...
385-
386- ### Key Decisions
387- ADR-001: <title>
388- Decision: <what>
389- Reason: <why>
382+ Template §3: PENDING | CONFIRMED — stakeholder approved YYYY-MM-DD
383+ Synthesis: <full synthesis across all behavior groups>
390384
391385 Rule: <story title>
392386 As a <role>
@@ -402,7 +396,40 @@ Feature: <title>
402396
403397Two discovery sources:
404398- ` docs/features/discovery.md ` — project-level 3-session discovery (once per project; additive for new features)
405- - Feature file description — per-feature 3-session discovery, entities, clusters, architecture
399+ - Feature file description — per-feature 3-session discovery, entities, business rules, and acceptance criteria
400+
401+ ---
402+
403+ ## Architecture Artifacts
404+
405+ Architectural decisions made during Step 2 are recorded as ADR files:
406+
407+ ```
408+ docs/architecture/
409+ adr-template.md ← blank template — copy to create a new ADR
410+ adr-001-<title>.md ← one file per significant decision
411+ adr-002-<title>.md
412+ ...
413+ ```
414+
415+ ** ADR format** (copy ` adr-template.md ` and fill in):
416+
417+ ``` markdown
418+ # ADR-NNN: <title >
419+
420+ ** Status:** PROPOSED | ACCEPTED | SUPERSEDED by ADR-NNN
421+
422+ ** Decision:** <what was decided — one sentence>
423+
424+ ** Reason:** <why — one sentence>
425+
426+ ** Alternatives considered:**
427+ - <option >: <why rejected >
428+ ```
429+
430+ Write an ADR only for non-obvious decisions with real trade-offs — module boundaries, external dependency strategy, Protocol vs. concrete class, data model choices. Routine YAGNI choices do not need an ADR.
431+
432+ Domain entity and service stubs (signatures, no bodies) live directly in the package under ` <package>/domain/ ` , ` <package>/ports/ ` , and ` <package>/adapters/ ` — written at Step 2, filled in during Step 3.
406433
407434---
408435
0 commit comments