Skip to content

Commit 8310d2b

Browse files
kanfilkanfil
committed
refactor: move architecture and product records to drafts, add team-ai-directives PR workflow
Major changes to output file locations: - architect.implement: - AD.md → {TD}/AD.md (TD root) via PR when configured - Accepted ADRs → {TD}/context_modules/adr.md - Cleanup phase: copies accepted ADRs to .specify/memory/ when not configured - product.implement: - PRD.md → {TD}/PRD.md (TD root) via PR when configured - Accepted PDRs → {TD}/context_modules/pdr.md - Cleanup phase: copies accepted PDRs to .specify/memory/ when not configured - levelup.implement: - Accepted CDRs → {TD}/context_modules/cdr.md - Cleanup phase: copies accepted CDRs to .specify/memory/ when not configured - All extensions: - Only 'Accepted' records are pushed to team-ai-directives - .specify/drafts/ cleaned up when no remaining non-accepted records - Cross-reference leftovers fixed Bumps version to 0.0.138
1 parent aeaf3d2 commit 8310d2b

46 files changed

Lines changed: 456 additions & 195 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎CHANGELOG.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,24 @@ All notable changes to the Specify CLI and templates are documented here.
77
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
88
and this project adheres to to [Semantic Versioning](https://semver.org/spec/v2.0.0/).
99

10+
## [0.0.138] - 2026-03-14
11+
12+
### Fixed
13+
14+
- **Cross-reference fixes**: Corrected remaining references to output file locations
15+
- Fixed `context_modules/AD.md` → `{TD}/AD.md` (TD root)
16+
- Fixed `context_modules/PRD.md` → `{TD}/PRD.md` (TD root)
17+
18+
## [0.0.137] - 2026-03-14
19+
20+
### Changed
21+
22+
- **Refined output file locations for extensions**:
23+
- architect.implement: AD.md → `{TD}/AD.md` (TD root), accepted ADRs → `{TD}/context_modules/adr.md`
24+
- product.implement: PRD.md → `{TD}/PRD.md` (TD root), accepted PDRs → `{TD}/context_modules/pdr.md`
25+
- levelup.implement: accepted CDRs → `{TD}/context_modules/cdr.md`
26+
- When NOT configured: All extensions copy accepted records to `.specify/memory/` and clean up `.specify/drafts/`
27+
1028
## [0.0.136] - 2026-03-13
1129

1230
### Fixed

‎docs/architecture.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -84,8 +84,8 @@ Greenfield: /architect.specify --> /architect.clarify --> /architect.implement
8484

8585
| File | Location | Purpose |
8686
|------|----------|---------|
87-
| System ADRs | `.specify/memory/adr.md` | Architecture Decision Records |
88-
| System AD | `AD.md` (project root) | Full Architecture Description |
87+
| System ADRs | `.specify/drafts/adr.md` | Architecture Decision Records |
88+
| System AD | `AD.md` (root) or `{TEAM_DIRECTIVES}/AD.md` via PR | Full Architecture Description |
8989
| Feature ADRs | `specs/{feature}/adr.md` | Feature-level decisions |
9090
| Feature AD | `specs/{feature}/AD.md` | Feature-level architecture |
9191
| Constitution | `.specify/memory/constitution.md` | Governance principles |
@@ -203,7 +203,7 @@ Architecture commands work alongside specification commands via extension hooks:
203203
|------|--------|---------|
204204
| **before_plan** | Before plan generation | Create feature ADRs using architect.specify/clarify/implement |
205205
| **after_plan** | After plan generation | Validate plan alignment using architect.validate --for-plan (READ-ONLY) |
206-
| **Activation** | adr.md exists | Hooks only fire if `.specify/memory/adr.md` present |
206+
| **Activation** | adr.md exists | Hooks only fire if `.specify/drafts/adr.md` present |
207207

208208
**Feature Architecture Generation**:
209209

@@ -218,7 +218,7 @@ Optional configuration in `.specify/extensions/architect/architect-config.yml`:
218218
```yaml
219219
adr:
220220
heuristic: "surprising" # surprising | all | minimal
221-
location: ".specify/memory/adr.md"
221+
location: ".specify/drafts/adr.md"
222222

223223
views:
224224
default: "core" # core | all | concurrency,operational

‎extensions/architect/README.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -55,19 +55,21 @@ Greenfield: /architect.specify --> /architect.clarify --> /architect.implement
5555

5656
| File | Location | Purpose |
5757
|------|----------|---------|
58-
| System ADRs | `.specify/memory/adr.md` | Architecture Decision Records |
59-
| System AD | `AD.md` (root) | Full Architecture Description |
58+
| System ADRs | `.specify/drafts/adr.md` | Architecture Decision Records |
59+
| System AD | `AD.md` (root) or `{TEAM_DIRECTIVES}/AD.md` via PR | Full Architecture Description |
6060
| Feature ADRs | `specs/{feature}/adr.md` | Feature-level decisions |
6161
| Feature AD | `specs/{feature}/AD.md` | Feature-level architecture |
6262

6363
## Two-Level Architecture System
6464

6565
| Level | Location | ADR File | Architecture Description | Hook Timing |
6666
|-------|----------|----------|--------------------------|--------------|
67-
| **System** | Main branch | `memory/adr.md` | `AD.md` (root) | N/A |
67+
| **System** | Main branch | `.specify/drafts/adr.md` | `AD.md` (root) or `{TEAM_DIRECTIVES}/AD.md` via PR | N/A |
6868
| **Feature** | Feature branch | `specs/{feature}/adr.md` | `specs/{feature}/AD.md` | before_plan hook |
6969
| **Validation** | Plan level | READ-ONLY via architect.validate | Validates plan alignment | after_plan hook |
7070

71+
**When team-ai-directives is configured**, the architect.implement command will create a PR to `{TEAM_DIRECTIVES}/AD.md` instead of writing to project root.
72+
7173
**Feature-level ADRs and AD.md** are created automatically via extension hooks during `/spec.plan` execution (if system architecture exists).
7274

7375
## Installation
@@ -130,7 +132,7 @@ Optional configuration in `.specify/extensions/architect/architect-config.yml`:
130132
```yaml
131133
adr:
132134
heuristic: "surprising" # surprising | all | minimal
133-
location: ".specify/memory/adr.md"
135+
location: ".specify/drafts/adr.md"
134136

135137
views:
136138
default: "core" # core | all | concurrency,operational
@@ -242,7 +244,7 @@ Architecture works with specification commands via extension hooks:
242244
/spec.specify --> /spec.plan --> /spec.tasks --> /spec.implement
243245
```
244246

245-
**Hooks only execute when `.specify/memory/adr.md` exists (architecture detection)**
247+
**Hooks only execute when `.specify/drafts/adr.md` exists (architecture detection)**
246248

247249
| Hook | When it Runs | Command | Purpose |
248250
|------|--------------|---------|---------|

‎extensions/architect/commands/analyze.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -79,8 +79,10 @@ You are acting as an **Architecture Analyst** validating architecture documentat
7979
- Parse JSON for file paths and existence status
8080

8181
2. **Load System-Level Artifacts**:
82-
- Read `AD.md` (project root) if exists
83-
- Read `.specify/memory/adr.md` if exists
82+
- Check if team-ai-directives is configured
83+
- Read `{TEAM_DIRECTIVES}/AD.md` if TD configured and exists
84+
- Read `AD.md` (project root) if exists (fallback)
85+
- Read `.specify/drafts/adr.md` if exists
8486
- Read `.specify/memory/constitution.md` if exists
8587

8688
3. **Load Feature-Level Artifacts** (if analyzing features):
@@ -91,8 +93,8 @@ You are acting as an **Architecture Analyst** validating architecture documentat
9193

9294
| Artifact | Path | Status |
9395
|----------|------|--------|
94-
| System AD | `AD.md` | Found/Missing |
95-
| System ADRs | `.specify/memory/adr.md` | Found/Missing |
96+
| System AD | `{TEAM_DIRECTIVES}/AD.md` or `AD.md` | Found/Missing |
97+
| System ADRs | `.specify/drafts/adr.md` | Found/Missing |
9698
| Constitution | `.specify/memory/constitution.md` | Found/Missing |
9799
| Feature ADs | `specs/*/AD.md` | Count: N |
98100
| Feature ADRs | `specs/*/adr.md` | Count: N |
@@ -106,7 +108,7 @@ You are acting as an **Architecture Analyst** validating architecture documentat
106108
| User Input | Scope | Artifacts Analyzed |
107109
|------------|-------|-------------------|
108110
| (empty) | Full | All system + all feature artifacts |
109-
| `"system"` | System only | AD.md, .specify/memory/adr.md |
111+
| `"system"` | System only | AD.md, .specify/drafts/adr.md |
110112
| `"feature {name}"` | Single feature | specs/{name}/AD.md, specs/{name}/adr.md |
111113
| `"adrs"` | ADR quality | All adr.md files (system + feature) |
112114
| `"views"` | AD completeness | All AD.md files (system + feature) |

‎extensions/architect/commands/clarify.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ Each ADR should have:
5151

5252
## Outline
5353

54-
1. **Load Current State**: Parse `.specify/memory/adr.md` and `.specify/memory/constitution.md`
54+
1. **Load Current State**: Parse `.specify/drafts/adr.md` and `.specify/memory/constitution.md`
5555
2. **Analyze ADRs**: Check each ADR against quality checklist
5656
3. **Identify Gaps**: List areas needing clarification
5757
4. **Interactive Refinement**: Ask targeted questions to fill gaps
@@ -69,7 +69,7 @@ Each ADR should have:
6969
- Handle errors gracefully if files don't exist
7070

7171
2. **Load ADR File**:
72-
- Read `.specify/memory/adr.md`
72+
- Read `.specify/drafts/adr.md`
7373
- Parse ADR index and individual ADR sections
7474
- Count total ADRs and identify status distribution
7575

@@ -306,7 +306,7 @@ Reply with: "A [amendment text]" or "B/C/D [reasoning]"
306306
- Update status if applicable
307307

308308
4. **Write File**:
309-
- Atomic write to `.specify/memory/adr.md`
309+
- Atomic write to `.specify/drafts/adr.md`
310310
- Preserve any ADRs that weren't modified
311311

312312
## Key Rules
@@ -368,7 +368,7 @@ After clarification ends (all gaps addressed or user signals "done"):
368368
- References added: [N]
369369

370370
**Recommended Next Steps**:
371-
1. Review updated ADRs in `.specify/memory/adr.md`
371+
1. Review updated ADRs in `.specify/drafts/adr.md`
372372
2. Run `/architect.implement` to generate AD.md
373373
3. Or run `/spec.specify` to start feature development
374374
```

‎extensions/architect/commands/implement.md‎

Lines changed: 66 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -50,17 +50,18 @@ You are acting as a **Technical Writer** synthesizing ADRs into comprehensive ar
5050

5151
| Document | Purpose | Location |
5252
|----------|---------|----------|
53-
| `.specify/memory/adr.md` | Architectural decisions with rationale | Input |
54-
| `AD.md` (root) | Full Architecture Description | Output |
53+
| `.specify/drafts/adr.md` | Architectural decisions with rationale | Input |
54+
| `AD.md` (root) | Full Architecture Description | Output (when TD not configured) |
55+
| `{TEAM_DIRECTIVES}/AD.md` | Full Architecture Description | Output via PR (when TD configured) |
5556
| `.specify/memory/constitution.md` | Governance principles | Constraint |
5657

5758
## Outline
5859

59-
1. **Load ADRs**: Parse all ADRs from `.specify/memory/adr.md`
60+
1. **Load ADRs**: Parse all ADRs from `.specify/drafts/adr.md`
6061
2. **Determine Views**: Parse `--views` flag to determine which views to generate
6162
3. **Generate Views**: Create requested viewpoints (core 5 by default, optionally +2)
6263
4. **Apply Perspectives**: Add Security and Performance perspectives
63-
5. **Output**: Write complete `AD.md` to project root
64+
5. **Output**: Write `AD.md` to team-ai-directives via PR (if configured) or project root
6465

6566
## Execution Steps
6667

@@ -73,7 +74,7 @@ You are acting as a **Technical Writer** synthesizing ADRs into comprehensive ar
7374
- Creates `AD.md` from template if it doesn't exist
7475

7576
2. **Load ADRs**:
76-
- Read `.specify/memory/adr.md`
77+
- Read `.specify/drafts/adr.md`
7778
- Parse each ADR: ID, title, context, decision, consequences
7879
- Build decision index
7980

@@ -371,7 +372,7 @@ graph TB
371372
- Document architectural principles
372373

373374
2. **ADR Summary**:
374-
- Create summary table linking to `.specify/memory/adr.md`
375+
- Create summary table linking to `.specify/drafts/adr.md`
375376
- List key decisions with impact levels
376377

377378
3. **Tech Stack Summary**:
@@ -387,21 +388,73 @@ graph TB
387388
- Ensure both perspectives are present
388389
- Validate diagram syntax
389390

390-
2. **Write AD.md**:
391+
2. **Determine Output Location**:
392+
- Check if team-ai-directives is configured (via `SPECIFY_TEAM_DIRECTIVES` env var or `.specify/team-ai-directives`)
393+
- If configured: Output AD.md to `{TEAM_DIRECTIVES}/AD.md` via PR workflow
394+
- If NOT configured: Output to `{REPO_ROOT}/AD.md` (project root)
395+
396+
3. **Write AD.md**:
391397
- Use `templates/AD-template.md` as base
392398
- Replace placeholders with generated content
393-
- Write to project root as `AD.md`
394-
395-
3. **Update References**:
396-
- Ensure `.specify/memory/adr.md` link is correct
399+
- Write to determined output location
400+
401+
4. **Write Accepted ADRs to context_modules/** (when TD configured):
402+
- Filter ADRs with status "Accepted" from `.specify/drafts/adr.md`
403+
- Write to `{TEAM_DIRECTIVES}/context_modules/adr.md`
404+
405+
5. **If team-ai-directives configured - Execute PR Workflow**:
406+
407+
a. **Check Working Tree**:
408+
```bash
409+
cd "{TEAM_DIRECTIVES}"
410+
git status --porcelain
411+
```
412+
413+
b. **Create Branch**:
414+
```bash
415+
BRANCH_NAME="context/{project-name}"
416+
git checkout -b "$BRANCH_NAME" main
417+
```
418+
419+
c. **Write files**:
420+
```bash
421+
cp AD.md "$TEAM_DIRECTIVES/AD.md"
422+
cp .specify/drafts/adr.md "$TEAM_DIRECTIVES/context_modules/adr.md"
423+
```
424+
425+
d. **Commit and Push**:
426+
```bash
427+
git add AD.md context_modules/adr.md
428+
git commit -m "Add architecture from {project-name}"
429+
git push -u origin "$BRANCH_NAME"
430+
```
431+
432+
e. **Create PR via MCP**:
433+
```
434+
Tool: create_pull_request (GitHub) or create_merge_request (GitLab)
435+
Parameters:
436+
- title: "Add Architecture from {project-name}"
437+
- body: "Architecture Description and ADRs from {project-name}"
438+
- source_branch: "{BRANCH_NAME}"
439+
- target_branch: "main"
440+
```
441+
442+
6. **Cleanup Phase** (when NOT configured):
443+
- Filter ADRs with status "Accepted" from `.specify/drafts/adr.md`
444+
- Copy accepted ADRs to `.specify/memory/adr.md`
445+
- Check if `.specify/drafts/adr.md` has any remaining non-accepted ADRs
446+
- If no remaining records → remove `.specify/drafts/` directory
447+
448+
7. **Update References**:
449+
- Ensure `.specify/drafts/adr.md` link is correct
397450
- Update version and timestamp
398451

399-
4. **Generate Report**:
452+
8. **Generate Report**:
400453

401454
```markdown
402455
## Architecture Description Generated
403456

404-
**Output**: AD.md (project root)
457+
**Output**: [AD.md (project root)|{TEAM_DIRECTIVES}/AD.md via PR]
405458
**Views Mode**: [core|all|custom]
406459

407460
**Views Generated** (based on --views flag):

‎extensions/architect/commands/init.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ Reverse-engineer architecture from an **existing codebase** (brownfield) to crea
2929

3030
**Output**:
3131

32-
1. **ADRs** documenting inferred architectural decisions in `.specify/memory/adr.md`
32+
1. **ADRs** documenting inferred architectural decisions in `.specify/drafts/adr.md`
3333
2. **Auto-handoff** to `/architect.clarify` to validate discovered decisions
3434

3535
**Key Difference from `/architect.specify`**:
@@ -72,7 +72,7 @@ You are acting as an **Architecture Archaeologist** uncovering implicit architec
7272
4. **Pattern Detection**: Identify architectural patterns in use
7373
5. **ADR Generation**: Create ADRs for discovered decisions (marked "Discovered"), organized by sub-system
7474
6. **Gap Analysis**: Identify areas where decisions are unclear
75-
7. **Output**: Write ADRs to `.specify/memory/adr.md` (NO AD.md creation)
75+
7. **Output**: Write ADRs to `.specify/drafts/adr.md` (NO AD.md creation)
7676
8. **Auto-Handoff**: Trigger `/architect.clarify` to validate brownfield findings
7777

7878
## Execution Steps
@@ -467,7 +467,7 @@ After scanning, report:
467467
**Objective**: Write discovered ADRs to file (NO AD.md creation)
468468

469469
1. **Write ADRs**:
470-
- Create or update `.specify/memory/adr.md` with discovered ADRs
470+
- Create or update `.specify/drafts/adr.md` with discovered ADRs
471471
- Mark ADRs as "Discovered (Inferred)" status ← USE THIS STATUS
472472
- Use "Common Alternatives" section with neutral trade-offs (no "Rejected because")
473473
- Note confidence level for each
@@ -568,7 +568,7 @@ The clarify phase will refine ADRs based on your input, then you can run `/archi
568568

569569
After clarification completes:
570570

571-
1. **Review Validated ADRs**: Check `.specify/memory/adr.md` for accuracy
571+
1. **Review Validated ADRs**: Check `.specify/drafts/adr.md` for accuracy
572572
2. **Run `/architect.implement`**: Generate full AD.md from validated ADRs
573573
3. **Update As Needed**: Refine documentation as you learn more
574574

@@ -579,7 +579,7 @@ After clarification completes:
579579
↓
580580
[Scan codebase] → Detect technologies, patterns
581581
↓
582-
[Generate ADRs] → Write to .specify/memory/adr.md (marked "Discovered")
582+
[Generate ADRs] → Write to .specify/drafts/adr.md (marked "Discovered")
583583
↓
584584
[Auto-trigger /architect.clarify]
585585
↓

‎extensions/architect/commands/specify.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -64,10 +64,10 @@ You are acting as a **Solutions Architect** facilitating an architectural discov
6464

6565
| Level | Location | ADR File | Architecture Description |
6666
|-------|----------|----------|--------------------------|
67-
| **System** | Main branch | `.specify/memory/adr.md` | `AD.md` (root) |
67+
| **System** | Main branch | `.specify/drafts/adr.md` | `AD.md` (root) |
6868
| **Feature** | Feature branch | `specs/{feature}/adr.md` | `specs/{feature}/AD.md` |
6969

70-
This command operates at the **System level**, creating ADRs in `.specify/memory/adr.md`.
70+
This command operates at the **System level**, creating ADRs in `.specify/drafts/adr.md`.
7171

7272
## Outline
7373

@@ -78,7 +78,7 @@ Given the PRD input, execute this workflow:
7878
3. **Load Governance**: Check `.specify/memory/constitution.md` for architectural constraints
7979
4. **Exploration Phase**: Interactive discussion to surface trade-offs and options (per sub-system)
8080
5. **Decision Phase**: Document decisions as ADRs with full rationale (organized by sub-system)
81-
6. **Output**: Write ADRs to `.specify/memory/adr.md` with sub-system organization
81+
6. **Output**: Write ADRs to `.specify/drafts/adr.md` with sub-system organization
8282

8383
**NOTE:** This is an interactive command. You will engage the user in conversation before finalizing ADRs.
8484

@@ -406,12 +406,12 @@ Proposed
406406
**Objective**: Write finalized ADRs to file
407407

408408
1. **Run Setup Script**:
409-
- Execute `{SCRIPT}` to ensure `.specify/memory/adr.md` exists
409+
- Execute `{SCRIPT}` to ensure `.specify/drafts/adr.md` exists
410410
- Script creates from template if file doesn't exist
411411
- Pass `--no-decompose` if decomposition was disabled
412412

413413
2. **Write ADRs**:
414-
- Append new ADRs to `.specify/memory/adr.md`
414+
- Append new ADRs to `.specify/drafts/adr.md`
415415
- Update ADR index table at top of file (include Sub-System column)
416416
- Preserve any existing ADRs (don't overwrite)
417417
- **If decomposed**: Add section headers for each sub-system

0 commit comments

Comments
 (0)