Skip to content

Commit 737dd84

Browse files
committed
docs: lock critical design decision for AD Mode tech stack integration
DESIGN DECISION: Single source of truth for tech stack - /architect map populates architecture.md Section C directly - Removes separate tech-stack.md file (redundancy eliminated) - Enables Constitution validation against official architecture doc - Improves Phases 2 & 3 integration paths PHASE 1 UPDATES: - Added Task 1F: Modify setup-architecture.sh action_map() Parse and populate architecture.md Section C with detected tech - Total Phase 1: 12-17 hours (was 10-13, +2-4 for proper integration) - Includes PowerShell equivalent updates RATIONALE: - User-identified design flaw (redundant tech-stack.md) - Fixes Constitution validation mechanism - Simplifies architecture documentation (no placeholders) - Single integration point for all tech validation in Phases 2-3 Addresses user insight: 'architecture.md Section C already exists for tech stack, why generate separate tech-stack.md?'
1 parent 5ececac commit 737dd84

File tree

1 file changed

+35
-1
lines changed

1 file changed

+35
-1
lines changed

roadmap.md

Lines changed: 35 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -141,7 +141,7 @@
141141
-**Setup Scripts (Bash)**: `scripts/bash/setup-architecture.sh` (449 lines) with tech detection, directory mapping, API scanning - production-ready.
142142
-**Setup Scripts (PS1)**: `scripts/powershell/setup-architecture.ps1` - PowerShell equivalent complete.
143143
-**Mode Documentation**: `templates/commands/mode.md:128-138` - AD mode workflow fully documented with use cases and artifacts.
144-
-**Codebase Mapper (/map)**: `/architect map` action fully implemented with language, framework, database, and infrastructure detection for brownfield projects.
144+
-**Codebase Mapper (/map)**: `/architect map` action fully implemented with language, framework, database, and infrastructure detection for brownfield projects. **[DESIGN DECISION LOCKED - Option A]**: Detects technologies and **populates `architecture.md` Section C** (Tech Stack Summary) directly. Single source of truth: `architecture.md` Section C (no separate `tech-stack.md` file). Enables Constitution validation against architecture.
145145
- ⚠️ **Plan Script Updates**: `scripts/bash/setup-plan.sh:46` hardcoded to `plan-template.md` - **MISSING MODE DETECTION** (critical blocker).
146146
- ⚠️ **plan-template-ad.md**: **DOES NOT EXIST** - template file missing (blocks schema generation guidance).
147147
-**Mode Detection Utility**: No `get_current_mode()` function in `scripts/bash/common.sh` - needed by setup-plan.sh.
@@ -163,6 +163,14 @@
163163
4. Add `Get-CurrentMode` to `scripts/powershell/common.ps1` (2-3 hours)
164164
5. Update `scripts/powershell/setup-plan.ps1` with mode detection (1-2 hours)
165165
6. Update `src/specify_cli/__init__.py` help text to mention AD mode (1 hour)
166+
7. **[NEW] Modify `scripts/bash/setup-architecture.sh` action_map()** to populate `architecture.md` Section C (2-3 hours)
167+
- Parse architecture.md and locate Section C: Tech Stack Summary
168+
- Replace [PLACEHOLDER] values with detected technologies
169+
- Update architecture.md directly (single source of truth)
170+
- **REMOVE tech-stack.md generation** (no separate inventory file)
171+
- Add PowerShell equivalent in `scripts/powershell/setup-architecture.ps1`
172+
173+
**Total Phase 1: ~12-17 hours (~3 days)** (was 10-13 hours; design improvement adds proper integration)
166174

167175
**Phase 2 Decisions (Before Implementation)**:
168176
- Which schema formats? (Recommendation: OpenAPI 3.1 + JSON Schema)
@@ -174,6 +182,32 @@
174182
- Detection strategy? (Recommendation: Language-specific pattern matching)
175183
- Integration? (Recommendation: Both auto in /analyze + on-demand command)
176184

185+
**🎯 CRITICAL DESIGN DECISION - SINGLE SOURCE OF TRUTH FOR TECH STACK** *(User-Identified & Locked)*:
186+
187+
**Issue Identified**: architecture.md already has Section C (Tech Stack Summary), but `/architect map` was creating separate `memory/tech-stack.md` → redundancy and broken Constitution validation.
188+
189+
**Decision LOCKED - Option A** ✅:
190+
- `/architect map` detects tech from codebase (existing ✅)
191+
- **POPULATES `architecture.md` Section C directly** (NEW)
192+
- **NO separate `tech-stack.md` file** (removed from design)
193+
- **Single source of truth**: `architecture.md` Section C
194+
- **Constitution can validate** against official architecture doc
195+
196+
**Rationale**:
197+
- ✅ One authoritative system design document (architecture.md)
198+
- ✅ Constitution validation path clear (references architecture.md Section C)
199+
- ✅ Complete architecture docs (no [PLACEHOLDER] format)
200+
- ✅ Phases 2 & 3 can reference unified tech context
201+
- ✅ Easier maintenance (no file sync needed)
202+
203+
**Implementation Impact**:
204+
- Phase 1 Task 7 (NEW): Modify setup-architecture.sh action_map() to populate architecture.md Section C
205+
- Phase 1F adds 2-3 hours → total Phase 1 now 12-17 hours
206+
- Both Bash and PowerShell scripts updated
207+
208+
**Phase 2 Benefit**: Schema generation references architecture.md Section C for tech context
209+
**Phase 3 Benefit**: /analyze validates code against architecture.md Section C AND constitution
210+
177211
---
178212

179213
#### **Strategic Tooling Improvements** *(60% Complete)* - **MEDIUM PRIORITY**

0 commit comments

Comments
 (0)