docs: formalize architecture pattern in architect role and SDD process
- Update architect.md to codify the ADR/OQ/README pattern: - decisions/ directory with numbered ADRs (not inline) - open-questions.md with OQ-IDs (not scattered per-doc) - README.md as index with doc table and ADR table - Spec docs reference ADRs and OQs by number - Document lifecycle states (draft/reviewed/stable/deprecated) - Anti-patterns updated for the new pattern - Update sdd_process.md: - Phase 1 (Architecture) now specifies the full doc structure - Document Structure section updated with ADR/OQ format templates - Architect role deliverables updated - Architecture Reviewer checks updated for structural issues - Spec document Design Decisions section format specified
This commit is contained in:
@@ -46,13 +46,24 @@ approaches
|
||||
|
||||
**Process**:
|
||||
|
||||
1. Architect creates modular architecture docs in `docs/architecture/` (Draft
|
||||
status)
|
||||
2. Architecture Review validates for ambiguities, risks
|
||||
3. Iterate until zero critical issues
|
||||
4. Transition to Stable status
|
||||
1. Architect creates the architecture documentation structure:
|
||||
- `docs/architecture/README.md` — index with doc table, ADR table, lifecycle
|
||||
- `docs/architecture/overview.md` — package purpose, exports, dependencies
|
||||
- `docs/architecture/<component>.md` — one focused doc per component/area
|
||||
- `docs/architecture/decisions/` — numbered ADR files (ADR-001, ADR-002, ...)
|
||||
- `docs/architecture/open-questions.md` — centralized tracker with OQ-IDs
|
||||
2. All docs start in `Draft` status. Spec docs reference ADRs by number (not
|
||||
inline rationale) and OQs by number (not inline questions).
|
||||
3. Architecture Review validates for ambiguities, risks, and structural issues
|
||||
(inline decisions not extracted, missing ADRs, no README index)
|
||||
4. Iterate until zero critical issues
|
||||
5. Transition to `Reviewed` status when all open questions for a doc are resolved
|
||||
|
||||
**Output**: Stable architecture documents ready for decomposition
|
||||
**Output**: Reviewed architecture documents ready for decomposition
|
||||
|
||||
**Key pattern**: Decisions go in `decisions/` ADRs, not inline in specs.
|
||||
Open questions go in `open-questions.md`, not scattered per-doc. Specs describe
|
||||
WHAT, ADRs explain WHY, open questions track what's unresolved.
|
||||
|
||||
### Phase 2: Decomposition
|
||||
|
||||
@@ -120,14 +131,19 @@ approaches
|
||||
**Key Behaviors**:
|
||||
|
||||
- Focus on WHAT and WHY, never HOW
|
||||
- Document decisions with ADR format
|
||||
- Extract decisions into numbered ADRs in `decisions/` directory
|
||||
- Centralize open questions in `open-questions.md` with OQ-IDs
|
||||
- Maintain `README.md` as the architecture index
|
||||
- Keep spec documents focused (~500 lines) — reference ADRs and OQs, don't inline them
|
||||
- Redirect exploration work to Research Specialist
|
||||
- Iterate based on review feedback
|
||||
|
||||
**Deliverables**:
|
||||
|
||||
- Modular architecture docs in `docs/architecture/`
|
||||
- Component-specific documents
|
||||
- `docs/architecture/README.md` — index with doc table, ADR table, lifecycle
|
||||
- `docs/architecture/<component>.md` — focused spec documents
|
||||
- `docs/architecture/decisions/` — numbered ADR files
|
||||
- `docs/architecture/open-questions.md` — centralized OQ tracker
|
||||
|
||||
---
|
||||
|
||||
@@ -230,7 +246,7 @@ limited set (current, notify, status). No mode toggle required.
|
||||
|
||||
#### 5. Architecture Reviewer
|
||||
|
||||
**Responsibility**: Validate architecture for ambiguities and risks.
|
||||
**Responsibility**: Validate architecture for ambiguities, risks, and structural issues.
|
||||
|
||||
**Mode**: Subagent (invoked by Architect)
|
||||
|
||||
@@ -240,10 +256,16 @@ limited set (current, notify, status). No mode toggle required.
|
||||
|
||||
**Key Behaviors**:
|
||||
|
||||
- Check for undefined terms
|
||||
- Check for inline decision rationale that should be in ADRs
|
||||
- Check for inline open questions that should be in `open-questions.md`
|
||||
- Check for missing ADR references for visible design choices
|
||||
- Identify undefined terms or concepts
|
||||
- Identify missing trade-off documentation
|
||||
- Validate quality attribute coverage
|
||||
- Flag ambiguities that could cause implementation issues
|
||||
- Check document size (recommend split if >700 lines)
|
||||
- Verify README has complete doc table and ADR table
|
||||
- Verify cross-references between docs, ADRs, and OQs are correct
|
||||
|
||||
---
|
||||
|
||||
@@ -542,10 +564,15 @@ capabilities as server-side operations accessible from any environment.
|
||||
|
||||
docs/
|
||||
├── architecture/
|
||||
│ └── storage/ # Decomposed: README.md, table-reference.md, per-domain schema files
|
||||
│ └── (ADRs in decisions/)
|
||||
│ ├── README.md # Index: doc table, ADR table, lifecycle definitions
|
||||
│ ├── overview.md # Package purpose, exports, dependencies
|
||||
│ ├── <component>.md # One focused doc per component/area
|
||||
│ ├── open-questions.md # Centralized OQ tracker with IDs, priorities, status
|
||||
│ └── decisions/ # Numbered ADRs
|
||||
│ ├── 001-<slug>.md
|
||||
│ ├── 002-<slug>.md
|
||||
│ └── ...
|
||||
├── sdd_process.md # This document
|
||||
└── decisions/ # ADRs
|
||||
|
||||
tasks/
|
||||
├── architecture/
|
||||
@@ -562,6 +589,75 @@ tasks/
|
||||
└── storage-abstraction/
|
||||
```
|
||||
|
||||
### ADR Format
|
||||
|
||||
ADRs follow this template:
|
||||
|
||||
```markdown
|
||||
# ADR-NNN: Descriptive Title
|
||||
|
||||
## Status
|
||||
Accepted | Proposed | Deprecated | Superseded
|
||||
|
||||
## Context
|
||||
(Why this decision is needed)
|
||||
|
||||
## Decision
|
||||
(What was decided)
|
||||
|
||||
## Consequences
|
||||
(Positive and negative outcomes)
|
||||
|
||||
## References
|
||||
(Links to related specs and ADRs)
|
||||
```
|
||||
|
||||
Numbering starts at 001 within each project. ADRs are stable — once Accepted,
|
||||
they don't revert. If superseded, mark the old one and create a new one.
|
||||
|
||||
### Open Questions Format
|
||||
|
||||
`open-questions.md` organizes questions by theme:
|
||||
|
||||
```markdown
|
||||
## Theme 1: <Theme Name>
|
||||
|
||||
### OQ-NN: <Question>
|
||||
|
||||
- **Origin**: [spec-doc.md]
|
||||
- **Status**: open | resolved
|
||||
- **Priority**: high | medium | low
|
||||
- **Resolution**: (when resolved)
|
||||
- **Cross-references**: OQ-NN, ADR-NNN
|
||||
```
|
||||
|
||||
### Spec Document Format
|
||||
|
||||
Spec documents reference ADRs and OQs by number, not by inlining rationale or
|
||||
questions. The Design Decisions section is a reference table:
|
||||
|
||||
```markdown
|
||||
## Design Decisions
|
||||
|
||||
All design decisions are documented as ADRs in [decisions/](decisions/).
|
||||
|
||||
| ADR | Decision | Summary |
|
||||
|-----|----------|---------|
|
||||
| [001](decisions/001-slug.md) | Decision title | One-line summary |
|
||||
```
|
||||
|
||||
The Open Questions section is also a reference:
|
||||
|
||||
```markdown
|
||||
## Open Questions
|
||||
|
||||
Open questions are tracked in [open-questions.md](open-questions.md). Key
|
||||
questions affecting this document:
|
||||
|
||||
- **OQ-01**: Question summary (status)
|
||||
- **OQ-03**: Question summary (status)
|
||||
```
|
||||
|
||||
## Agent Role Specs
|
||||
|
||||
Agent definitions are in `.opencode/agents/`:
|
||||
|
||||
Reference in New Issue
Block a user