Skip to content

Commit 607ef8e

Browse files
NeilJo-GYNeilJo-GY
committed
feat!: Organize templates by specification system source
BREAKING CHANGE: Templates directory structure now organized by source Before (0.3.0): - templates/{template-name} - templates/commands/{command-name} After (0.4.0): - templates/{source}/templates/{template-name} - templates/{source}/commands/{command-name} Benefits: - Clear provenance of commands/templates - Namespace isolation prevents naming conflicts - Embodies specification composability principle - Matches documented design (spec-template.md.j2) Migration: See CHANGELOG.md for migration guide Fixes: #architecture-consistency Changes: - generator.py: Preserve source in output paths - specify.md.j2: Update documentation (3 locations) - architecture.md: Update examples - Add detailed analysis: ANALYSIS-templates-structure-diff.md
1 parent b797f83 commit 607ef8e

File tree

9 files changed

+546
-13
lines changed

9 files changed

+546
-13
lines changed

‎ANALYSIS-templates-structure-diff.md‎

Lines changed: 245 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,245 @@
1+
# Templates 目录结构差异分析
2+
3+
## ❌ 问题：文档与实现不一致
4+
5+
### 📄 文档建议的结构 (`spec-template.md.j2` Line 415-429)
6+
7+
**按 specification system source 组织**:
8+
9+
```
10+
templates/
11+
├── [library-spec-1]/ # 例如: generic/
12+
│ ├── commands/ # Slash Commands from this specification system
13+
│ │ └── [command-name].md
14+
│ └── templates/ # Entity/workflow templates from this system
15+
│ └── [template-name].yaml
16+
├── [library-spec-2]/ # 例如: spec-kit/
17+
│ ├── commands/
18+
│ └── templates/
19+
└── [custom]/ # 例如: mcp/ (from protocol)
20+
├── commands/
21+
└── templates/
22+
```
23+
24+
**设计理念**:
25+
- ✅ 按来源分组（library vs custom）
26+
- ✅ 清晰的命名空间隔离
27+
- ✅ 体现规范组合性（Specification Composability）
28+
- ✅ 易于理解来源和用途
29+
30+
**文档示例 (MCP-Speckit)**:
31+
```
32+
templates/
33+
├── generic/ # From library/generic
34+
│ ├── commands/
35+
│ │ ├── init.md
36+
│ │ └── validate.md
37+
│ └── templates/
38+
│ └── basic-spec.yaml
39+
├── spec-kit/ # From library/sdd/spec-kit
40+
│ ├── commands/
41+
│ │ ├── plan.md
42+
│ │ └── implement.md
43+
│ └── templates/
44+
│ └── toolkit-spec.yaml
45+
└── mcp/ # Custom (from protocol/001-mcp-protocol)
46+
├── commands/
47+
│ ├── show-protocol.md
48+
│ ├── get-template.md
49+
│ └── validate-server.md
50+
└── templates/
51+
├── basic-server.yaml
52+
├── advanced-server.yaml
53+
└── tool-definition.yaml
54+
```
55+
56+
---
57+
58+
### 💻 实际实现的结构 (`generator.py` Line 257-269)
59+
60+
**扁平化组织**:
61+
62+
```python
63+
# Line 260: 模板文件直接在 templates/ 根目录
64+
output_template = f"templates/{template_name}"
65+
66+
# Line 266: 命令文件在 templates/commands/ 统一目录
67+
output_command = f"templates/commands/{command_name}"
68+
```
69+
70+
**实际生成的结构**:
71+
```
72+
templates/
73+
├── specify-template.md # 直接在根目录，没有 source 分组
74+
├── plan-template.md # 直接在根目录
75+
├── validate-template.md # 直接在根目录
76+
└── commands/ # 所有命令混在一起
77+
├── specify.md # 来自 generic/greenfield
78+
├── plan.md # 来自 spec-kit
79+
├── proposal.md # 来自 openspec
80+
└── validate.md # 来自 generic/greenfield
81+
```
82+
83+
**问题**:
84+
- ❌ 无法区分来源（generic vs spec-kit vs custom）
85+
- ❌ 命名冲突风险（不同 source 可能有同名命令）
86+
- ❌ 与文档承诺的结构不符
87+
- ❌ 不符合"按 specification system source 组织"的设计原则
88+
89+
---
90+
91+
## 📊 具体差异对比
92+
93+
| 方面 | 文档建议 | 实际实现 | 影响 |
94+
|------|---------|---------|------|
95+
| **组织原则** | 按 source 分组 | 扁平化 | ❌ 不符合设计理念 |
96+
| **目录结构** | `templates/{source}/commands/` | `templates/commands/` | ❌ 无法区分来源 |
97+
| **模板位置** | `templates/{source}/templates/` | `templates/` | ❌ 混在根目录 |
98+
| **命名冲突** | 隔离（不同 source 可同名） | 可能冲突 | ❌ 风险增加 |
99+
| **可组合性** | 体现规范组合 | 无法体现 | ❌ 设计理念丢失 |
100+
| **用户理解** | 清晰来源和职责 | 混乱不清 | ❌ 学习曲线增加 |
101+
102+
---
103+
104+
## 🔍 根本原因
105+
106+
### generator.py 中的简化逻辑
107+
108+
```python
109+
# Line 248-269: 循环处理 slash_commands
110+
for sc in meta_spec.slash_commands:
111+
source = f"library/{sc.source}"
112+
113+
# 从 source 读取
114+
source_template = f"{source}/templates/{template_name}.j2"
115+
source_command = f"{source}/commands/{command_name}.j2"
116+
117+
# 但输出时丢弃了 source 信息！
118+
output_template = f"templates/{template_name}" # ❌ 扁平化
119+
output_command = f"templates/commands/{command_name}" # ❌ 扁平化
120+
```
121+
122+
**问题**: 输出路径没有保留 `source` 信息。
123+
124+
---
125+
126+
## ✅ 建议的修复方案
127+
128+
### 方案 1: 保留 source 层次结构（推荐）
129+
130+
**修改 generator.py**:
131+
132+
```python
133+
for sc in meta_spec.slash_commands:
134+
source = f"library/{sc.source}"
135+
136+
# 保留 source 信息
137+
output_template = f"templates/{sc.source}/templates/{template_name}"
138+
output_command = f"templates/{sc.source}/commands/{command_name}"
139+
```
140+
141+
**修复后的结构**:
142+
```
143+
templates/
144+
├── generic/
145+
│ ├── commands/
146+
│ │ ├── specify.md
147+
│ │ └── validate.md
148+
│ └── templates/
149+
│ ├── specify-template.md
150+
│ └── validate-template.md
151+
├── spec-kit/
152+
│ ├── commands/
153+
│ │ ├── plan.md
154+
│ │ └── implement.md
155+
│ └── templates/
156+
│ ├── plan-template.md
157+
│ └── implement-template.md
158+
└── custom/ # 如果有 protocol-derived commands
159+
├── commands/
160+
│ └── show-protocol.md
161+
└── templates/
162+
└── server-template.yaml
163+
```
164+
165+
**优点**:
166+
- ✅ 符合文档设计
167+
- ✅ 清晰的命名空间
168+
- ✅ 体现规范组合性
169+
- ✅ 避免命名冲突
170+
171+
**风险**:
172+
- ⚠️ 破坏性变更（需要更新版本）
173+
- ⚠️ 已有 speckit 的迁移
174+
175+
---
176+
177+
### 方案 2: 更新文档以匹配实现
178+
179+
**修改 spec-template.md.j2**:
180+
181+
将推荐结构改为：
182+
```
183+
templates/
184+
├── {command1}-template.md # 模板文件
185+
├── {command2}-template.md
186+
└── commands/ # 所有 Slash Commands
187+
├── {command1}.md
188+
└── {command2}.md
189+
```
190+
191+
**优点**:
192+
- ✅ 简单快速
193+
- ✅ 不破坏现有代码
194+
195+
**缺点**:
196+
- ❌ 放弃设计理念
197+
- ❌ 无法体现规范组合性
198+
- ❌ 可能有命名冲突
199+
200+
---
201+
202+
## 🎯 推荐决策
203+
204+
### 建议：采用方案 1（保留 source 层次结构）
205+
206+
**理由**:
207+
1. **设计一致性**: 文档描述的"按 specification system source 组织"是核心设计理念
208+
2. **可扩展性**: 支持多个 library 的组合使用
209+
3. **清晰性**: 用户可以清楚地看到每个命令来自哪个 specification system
210+
4. **避免冲突**: 不同 source 可以有同名命令而不冲突
211+
212+
**实施步骤**:
213+
1. ✅ 修改 `generator.py` (Line 260, 266)
214+
2. ✅ 更新测试用例
215+
3. ✅ 添加版本升级指南
216+
4. ✅ 更新 CHANGELOG (MAJOR version bump: 0.3.0 → 1.0.0)
217+
218+
---
219+
220+
## 📝 相关文件
221+
222+
- `src/metaspec/generator.py` (Line 257-269) - 实现代码
223+
- `src/metaspec/templates/meta/templates/spec-template.md.j2` (Line 409-455) - 文档规范
224+
- `src/metaspec/templates/meta/sdd/commands/specify.md.j2` (Line 1468-1494) - 开发指南
225+
226+
---
227+
228+
## ⏰ 发现时间
229+
230+
2025-11-08 (Version 0.3.0 发布后)
231+
232+
---
233+
234+
## 🚨 影响评估
235+
236+
**当前状态**:
237+
- ✅ 功能正常工作（能生成 speckit）
238+
- ❌ 结构与文档不符
239+
- ❌ 可能导致用户困惑
240+
- ❌ 无法体现核心设计理念
241+
242+
**修复优先级**: **P0 (Critical)**
243+
244+
**原因**: 这是核心架构设计问题，影响框架的可理解性和可扩展性。
245+

‎CHANGELOG.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,132 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
99

1010
---
1111

12+
## [0.4.0] - 2025-11-08
13+
14+
### ✨ Features
15+
16+
**Added templates/README.md for user guidance**
17+
18+
Generated speckits now include a comprehensive README in the `templates/` directory that explains:
19+
- ✅ New directory structure organized by source
20+
- ✅ Available templates and slash commands
21+
- ✅ How to use templates (AI agents, CLI, manual)
22+
- ✅ How to add custom templates
23+
- ✅ Why organize by source (provenance, namespace isolation, composability)
24+
25+
**Example content**:
26+
```markdown
27+
# Templates Directory
28+
> Organized by Specification System Source
29+
30+
templates/
31+
├── generic/ # From MetaSpec library/generic
32+
│ ├── commands/ # Slash Commands
33+
│ └── templates/ # Template files
34+
└── spec-kit/ # From MetaSpec library/sdd/spec-kit
35+
├── commands/
36+
└── templates/
37+
```
38+
39+
**Benefits**:
40+
- ✅ Reduces user confusion about new structure
41+
- ✅ Self-documenting directory
42+
- ✅ Onboarding guide for new users
43+
- ✅ Reference for adding custom templates
44+
45+
**Files Changed**:
46+
- `src/metaspec/templates/base/templates/README.md.j2` - New template file
47+
- `src/metaspec/generator.py` (Line 220) - Add to base templates list
48+
- `src/metaspec/templates/meta/templates/spec-template.md.j2` - Updated structure examples and checklist
49+
50+
---
51+
52+
### 💥 BREAKING CHANGES
53+
54+
**Templates directory structure now organized by specification system source**
55+
56+
**Issue**: Generator implementation did not match documented design
57+
- ❌ Documentation promised: `templates/{source}/commands/` (organized by source)
58+
- ❌ Implementation generated: `templates/commands/` (flat structure)
59+
- ❌ Result: Naming conflicts, unclear provenance, violated "specification composability" principle
60+
61+
**Fix**: Restructured templates directory to preserve source hierarchy
62+
63+
**Before** (0.3.0):
64+
```
65+
my-speckit/
66+
└── templates/
67+
├── specify-template.md # ❌ Flat, no source info
68+
├── plan-template.md
69+
└── commands/ # ❌ All commands mixed
70+
├── specify.md # From generic?
71+
└── plan.md # From spec-kit?
72+
```
73+
74+
**After** (0.4.0):
75+
```
76+
my-speckit/
77+
└── templates/
78+
├── generic/ # ✅ Clear source
79+
│ ├── commands/
80+
│ │ └── specify.md
81+
│ └── templates/
82+
│ └── specify-template.md
83+
└── spec-kit/ # ✅ Clear source
84+
├── commands/
85+
│ └── plan.md
86+
└── templates/
87+
└── plan-template.md
88+
```
89+
90+
**Benefits**:
91+
- ✅ **Clear provenance**: Users know which specification system each command comes from
92+
- ✅ **Namespace isolation**: Different sources can have same-named commands without conflict
93+
- ✅ **Specification composability**: Embodies MetaSpec's core design principle
94+
- ✅ **Matches documentation**: Implementation now aligns with spec-template.md.j2
95+
96+
**Migration Guide**:
97+
98+
For existing speckits generated with 0.x.x:
99+
100+
1. **Restructure templates directory**:
101+
```bash
102+
cd my-speckit/templates
103+
104+
# Create source directories
105+
mkdir -p generic/commands generic/templates
106+
mkdir -p spec-kit/commands spec-kit/templates
107+
108+
# Move files based on their source
109+
# (Check your meta-spec.yaml to identify which commands came from which source)
110+
mv specify-template.md generic/templates/
111+
mv commands/specify.md generic/commands/
112+
113+
mv plan-template.md spec-kit/templates/
114+
mv commands/plan.md spec-kit/commands/
115+
116+
# Remove old flat directories
117+
rmdir commands/
118+
```
119+
120+
2. **Update any hardcoded paths in scripts** (if applicable)
121+
122+
**Impact**:
123+
- ⚠️ **Existing speckits**: Need manual restructuring (see migration guide above)
124+
- ⚠️ **New speckits**: Automatically use new structure via `metaspec init`
125+
- ⚠️ **Breaking change in 0.x**: MINOR version bump (0.3.0 → 0.4.0)
126+
127+
**Files Changed**:
128+
- `src/metaspec/generator.py` (Line 261, 268) - Preserve source in output paths
129+
- `src/metaspec/templates/meta/sdd/commands/specify.md.j2` (3 locations) - Updated documentation
130+
- `docs/architecture.md` (Line 266-268) - Updated examples
131+
132+
**References**:
133+
- Detailed analysis: `ANALYSIS-templates-structure-diff.md`
134+
- Original specification: `spec-template.md.j2` Line 409-455
135+
136+
---
137+
12138
## [0.3.0] - 2025-11-07
13139

14140
### ✨ Features

‎docs/architecture.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -263,9 +263,9 @@ When speckit developer designs workflow:
263263
template: "templates/endpoint-design-template.md.j2"
264264
265265
4. Implement custom template
266-
→ Create endpoint-design-template.md in templates/ (development reference)
267-
→ Create .j2 file in src/*/templates/templates/ (for packaging)
268-
→ Create command instruction in src/*/templates/commands/ (for packaging)
266+
→ Create endpoint-design-template.md in templates/{source}/templates/ (development reference)
267+
→ Create .j2 file in src/*/templates/{source}/templates/ (for packaging)
268+
→ Create command instruction in src/*/templates/{source}/commands/ (for packaging)
269269
```
270270

271271
---

‎pyproject.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[project]
22
name = "meta-spec"
3-
version = "0.3.0"
3+
version = "0.4.0"
44
description = "Meta-specification framework for generating Spec-Driven X (SD-X) toolkits for AI agents"
55
readme = "README.md"
66
requires-python = ">=3.11"

0 commit comments

Comments
 (0)