diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 9ad2087436..2ae4044da9 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -2,7 +2,7 @@ name: Create Release on: push: - branches: [ main ] + branches: [ main, develop ] paths: - 'memory/**' - 'scripts/**' diff --git a/README.md b/README.md index 76149512f6..7f4349435a 100644 --- a/README.md +++ b/README.md @@ -9,9 +9,9 @@

- Release - GitHub stars - License + Release + GitHub stars + License Documentation

@@ -51,7 +51,7 @@ Choose your preferred installation method: Install once and use everywhere: ```bash -uv tool install specify-cli --from git+https://github.com/github/spec-kit.git +uv tool install specify-cli --from git+https://github.com/zixun-github/spec-kit.git ``` Then use the tool directly: @@ -72,7 +72,7 @@ specify check To upgrade Specify, see the [Upgrade Guide](./docs/upgrade.md) for detailed instructions. Quick upgrade: ```bash -uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git +uv tool install specify-cli --force --from git+https://github.com/zixun-github/spec-kit.git ``` #### Option 2: One-time Usage @@ -80,7 +80,7 @@ uv tool install specify-cli --force --from git+https://github.com/github/spec-ki Run directly without installing: ```bash -uvx --from git+https://github.com/github/spec-kit.git specify init +uvx --from git+https://github.com/zixun-github/spec-kit.git specify init ``` **Benefits of persistent installation:** @@ -643,7 +643,7 @@ rm gcm-linux_amd64.2.6.1.deb ## 💬 Support -For support, please open a [GitHub issue](https://github.com/github/spec-kit/issues/new). We welcome bug reports, feature requests, and questions about using Spec-Driven Development. +For support, please open a [GitHub issue](https://github.com/zixun-github/spec-kit/issues/new). We welcome bug reports, feature requests, and questions about using Spec-Driven Development. ## 🙏 Acknowledgements diff --git a/scripts/bash/common.sh b/scripts/bash/common.sh index 2c3165e41d..7bd2128593 100644 --- a/scripts/bash/common.sh +++ b/scripts/bash/common.sh @@ -142,6 +142,7 @@ CURRENT_BRANCH='$current_branch' HAS_GIT='$has_git_repo' FEATURE_DIR='$feature_dir' FEATURE_SPEC='$feature_dir/spec.md' +IMPL_DESIGN='$feature_dir/design.md' IMPL_PLAN='$feature_dir/plan.md' TASKS='$feature_dir/tasks.md' RESEARCH='$feature_dir/research.md' diff --git a/scripts/bash/setup-plan.sh b/scripts/bash/setup-plan.sh index d01c6d6cb5..ff0c05773d 100644 --- a/scripts/bash/setup-plan.sh +++ b/scripts/bash/setup-plan.sh @@ -36,6 +36,17 @@ check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1 # Ensure the feature directory exists mkdir -p "$FEATURE_DIR" +# Copy design template if it exists +TEMPLATE="$REPO_ROOT/.specify/templates/design-template.md" +if [[ -f "$TEMPLATE" ]]; then + cp "$TEMPLATE" "$IMPL_DESIGN" + echo "Copied design template to $IMPL_DESIGN" +else + echo "Warning: Design template not found at $TEMPLATE" + # Create a basic plan file if template doesn't exist + touch "$IMPL_DESIGN" +fi + # Copy plan template if it exists TEMPLATE="$REPO_ROOT/.specify/templates/plan-template.md" if [[ -f "$TEMPLATE" ]]; then diff --git a/scripts/powershell/common.ps1 b/scripts/powershell/common.ps1 index b0be273545..13d35ede19 100644 --- a/scripts/powershell/common.ps1 +++ b/scripts/powershell/common.ps1 @@ -104,6 +104,7 @@ function Get-FeaturePathsEnv { HAS_GIT = $hasGit FEATURE_DIR = $featureDir FEATURE_SPEC = Join-Path $featureDir 'spec.md' + IMPL_DESIGN = Join-Path $featureDir 'design.md' IMPL_PLAN = Join-Path $featureDir 'plan.md' TASKS = Join-Path $featureDir 'tasks.md' RESEARCH = Join-Path $featureDir 'research.md' diff --git a/scripts/powershell/setup-plan.ps1 b/scripts/powershell/setup-plan.ps1 index d0ed582fa9..2111952d34 100644 --- a/scripts/powershell/setup-plan.ps1 +++ b/scripts/powershell/setup-plan.ps1 @@ -31,6 +31,17 @@ if (-not (Test-FeatureBranch -Branch $paths.CURRENT_BRANCH -HasGit $paths.HAS_GI # Ensure the feature directory exists New-Item -ItemType Directory -Path $paths.FEATURE_DIR -Force | Out-Null +# Copy design template if it exists, otherwise note it or create empty file +$template = Join-Path $paths.REPO_ROOT '.specify/templates/design-template.md' +if (Test-Path $template) { + Copy-Item $template $paths.IMPL_DESIGN -Force + Write-Output "Copied design template to $($paths.IMPL_DESIGN)" +} else { + Write-Warning "Design template not found at $template" + # Create a basic design file if template doesn't exist + New-Item -ItemType File -Path $paths.IMPL_DESIGN -Force | Out-Null +} + # Copy plan template if it exists, otherwise note it or create empty file $template = Join-Path $paths.REPO_ROOT '.specify/templates/plan-template.md' if (Test-Path $template) { @@ -42,10 +53,12 @@ if (Test-Path $template) { New-Item -ItemType File -Path $paths.IMPL_PLAN -Force | Out-Null } + # Output results if ($Json) { $result = [PSCustomObject]@{ FEATURE_SPEC = $paths.FEATURE_SPEC + IMPL_DESIGN = $paths.IMPL_DESIGN IMPL_PLAN = $paths.IMPL_PLAN SPECS_DIR = $paths.FEATURE_DIR BRANCH = $paths.CURRENT_BRANCH @@ -54,6 +67,7 @@ if ($Json) { $result | ConvertTo-Json -Compress } else { Write-Output "FEATURE_SPEC: $($paths.FEATURE_SPEC)" + Write-Output "IMPL_DESIGN: $($paths.IMPL_DESIGN)" Write-Output "IMPL_PLAN: $($paths.IMPL_PLAN)" Write-Output "SPECS_DIR: $($paths.FEATURE_DIR)" Write-Output "BRANCH: $($paths.CURRENT_BRANCH)" diff --git a/src/specify_cli/__init__.py b/src/specify_cli/__init__.py index 1dedb31949..4844ca2de0 100644 --- a/src/specify_cli/__init__.py +++ b/src/specify_cli/__init__.py @@ -635,7 +635,7 @@ def deep_merge(base: dict, update: dict) -> dict: return merged def download_template_from_github(ai_assistant: str, download_dir: Path, *, script_type: str = "sh", verbose: bool = True, show_progress: bool = True, client: httpx.Client = None, debug: bool = False, github_token: str = None) -> Tuple[Path, dict]: - repo_owner = "github" + repo_owner = "zixun-github" repo_name = "spec-kit" if client is None: client = httpx.Client(verify=ssl_context) diff --git a/templates/commands/plan.md b/templates/commands/plan.md index 147da0afa0..b2352d5327 100644 --- a/templates/commands/plan.md +++ b/templates/commands/plan.md @@ -28,18 +28,19 @@ You **MUST** consider the user input before proceeding (if not empty). 1. **Setup**: Run `{SCRIPT}` from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). -2. **Load context**: Read FEATURE_SPEC and `/memory/constitution.md`. Load IMPL_PLAN template (already copied). +2. **Load context**: Read FEATURE_SPEC, `/memory/constitution.md` and `/memory/architecture.md`(only if it exists). Load IMPL_PLAN template (already copied). 3. **Execute plan workflow**: Follow the structure in IMPL_PLAN template to: - Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION") - Fill Constitution Check section from constitution - Evaluate gates (ERROR if violations unjustified) - Phase 0: Generate research.md (resolve all NEEDS CLARIFICATION) - - Phase 1: Generate data-model.md, contracts/, quickstart.md - - Phase 1: Update agent context by running the agent script + - Phase 1: Generate design.md, domain-model.md (if needed) + - Phase 2: Generate contracts/, quickstart.md + - Phase 2: Update agent context by running the agent script - Re-evaluate Constitution Check post-design -4. **Stop and report**: Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generated artifacts. +4. **Stop and report**: Command ends after Phase 3 planning. Report branch, IMPL_PLAN path, and generated artifacts. ## Phases @@ -66,7 +67,7 @@ You **MUST** consider the user input before proceeding (if not empty). **Output**: research.md with all NEEDS CLARIFICATION resolved -### Phase 1: Design & Contracts +### Phase 1: Design **Prerequisites:** `research.md` complete @@ -75,11 +76,47 @@ You **MUST** consider the user input before proceeding (if not empty). - Validation rules from requirements - State transitions if applicable -2. **Generate API contracts** from functional requirements: +2. **Consider IMPL_DESIGN guidance**: + - Reference Section 2: Requirements Overview (background, objectives, scope, value) + - Reference Section 3: Requirements Analysis (feature list, use case diagram, key processes) + - Reference Section 4.1: System Context Diagram (system boundaries, external entities) + - Reference Section 4.2: Impact Analysis (business processes, upstream/downstream systems, performance impact) + - Reference Section 4.3: Key Design Decisions (using ADR format) + +3. **Generate `design.md`**: + - Follow the structure of `design-template.md` + - Core content (required): + - Requirements Analysis (Section 3): feature list, use case diagram, key processes + - System Context Diagram (Section 4.1) + - Key Design Decisions (Section 4.3): record important decisions in ADR format, including decision background, candidate solutions, selection rationale, and consequences + - Optional extended content: + - Non-functional Requirements (Section 3.4) + - Impact Analysis (Section 4.2) + - Domain Model Diagram (Section 4.4): UML class diagram, distinguish entities, value objects, and aggregate roots, relationship types and cardinality annotations + - Specialized Design (Section 4.5) - e.g., state diagrams, sequence diagrams + +**Output**: design.md, data-model.md + +**Key rules**: +- Use absolute paths +- ERROR on gate failures or unresolved clarifications +- Strictly follow IMPL_DESIGN structure and format +- Prioritize core content, extend optional content as needed +- Domain model must clearly annotate entities + +### Phase 2: Contracts + +**Prerequisites:** `design.md` and `data-model.md` (if needed) complete + +1. **Generate API contracts** from functional requirements: - For each user action → endpoint - Use standard REST/GraphQL patterns - Output OpenAPI/GraphQL schema to `/contracts/` +2. **Generate quickstart.md**: + - Provide quick reference for developers + - Include key endpoints, data models, and usage examples + 3. **Agent context update**: - Run `{AGENT_SCRIPT}` - These scripts detect which AI agent is in use @@ -87,7 +124,7 @@ You **MUST** consider the user input before proceeding (if not empty). - Add only new technology from current plan - Preserve manual additions between markers -**Output**: data-model.md, /contracts/*, quickstart.md, agent-specific file +**Output**: /contracts/*, quickstart.md, agent-specific file ## Key rules diff --git a/templates/design-template.md b/templates/design-template.md new file mode 100644 index 0000000000..a34853ce0b --- /dev/null +++ b/templates/design-template.md @@ -0,0 +1,457 @@ +# 需求设计文档：[需求名称] + +**分支**：`[###-需求名称]` | **日期**：[日期] | **规格**：[链接] +**输入**：来自 `/specs/[###-需求名称]/spec.md` 的功能规格 + +**注意**：此模板由 `/speckit.design` 命令填写。用于已完成整体架构设计的项目中某一具体需求的概要设计。 + +--- + +## 1. 版本及变更信息 + + + +| 版本 | 日期 | 变更人 | 变更类型 | 变更内容 | 影响范围 | +|------|------|--------|----------|----------|----------| +| v1.0.0 | [日期] | [变更人] | [类型] | [内容摘要] | [范围] | + +--- + +## 2. 需求概述 + + + +### 需求背景 + +- **业务驱动**：[市场变化、用户痛点、竞品压力等] +- **技术驱动**：[性能瓶颈、技术债务、架构升级等] +- **战略驱动**：[公司战略、产品规划等] + +### 需求目标 + +- **业务目标**：[可量化的业务指标，如转化率提升、成本降低] +- **技术目标**：[性能提升、可维护性改善、稳定性增强] +- **用户目标**：[解决的用户问题或体验提升] + +### 需求范围 + +- **包含内容**：[明确包含的模块、功能、系统] +- **不包含内容**：[边界说明，避免范围蔓延] +- **集成边界**：[与现有系统的集成点和交互边界] + +### 业务价值 + +- **用户价值**：[解决什么问题、带来什么便利] +- **业务价值**：[预期的商业收益、数据指标提升] +- **技术价值**：[技术债务清理、架构优化、可维护性提升] + +--- + +## 3. 需求分析 + +### 3.1. 功能清单 + + + +| 功能编号 | 功能名称 | 功能描述 | 优先级 | 依赖关系 | 验收标准 | +|----------|----------|----------|--------|----------|----------| +| F001 | [功能名称] | [输入、处理、输出描述] | P0/P1/P2 | [依赖项] | [如何判断完成] | +| F002 | [功能名称] | [输入、处理、输出描述] | P0/P1/P2 | [依赖项] | [如何判断完成] | + +**边界说明**： + +- 本期实现：[明确范围] +- 后续迭代：[标注后续功能] +- 不在范围：[明确不包含内容] + +### 3.2. 用例图 + + + +**参与者识别**： + +- 主要参与者：[直接使用系统的用户，如普通用户、管理员] +- 次要参与者：[外部系统或服务，如支付系统、第三方API] + +**用例列表**： + +- [用例1]：[描述] +- [用例2]：[描述] + +**用例图**： + +```text +[插入用例图] +``` + +### 3.3. 关键流程（可选） + + + +#### 正常业务流程 + +1. [步骤1]：[输入 → 处理 → 输出] +2. [步骤2]：[输入 → 处理 → 输出] +3. [步骤3]：[输入 → 处理 → 输出] + +**流程图**： + +```text +[插入流程图] +``` + +#### 异常流程处理 + +| 异常场景 | 触发条件 | 处理策略 | 恢复机制 | +|----------|----------|----------|----------| +| [异常1] | [条件] | [重试/回退/补偿/人工介入] | [如何恢复] | +| [异常2] | [条件] | [重试/回退/补偿/人工介入] | [如何恢复] | + +**流程约束**： + +- 时间约束：[超时处理、执行时限] +- 并发约束：[并发控制、幂等性保证] +- 事务约束：[事务边界、一致性要求] +- 权限约束：[权限检查点] + +### 3.4. 非功能性需求（可选） + + + +#### 性能需求 + +- **响应时间**：[如 P95 < 200ms] +- **吞吐量**：[如 QPS、TPS] +- **并发用户数**：[支持的并发数量] +- **数据容量**：[处理的数据量级] + +#### 可用性需求 + +- **系统可用性**：[如 99.9% SLA] +- **故障恢复时间**：[RTO] +- **数据恢复点**：[RPO] +- **降级策略**：[关键功能的降级方案] + +#### 安全性需求 + +- **身份认证**：[认证方式和强度] +- **权限控制**：[访问控制策略] +- **数据加密**：[加密存储和传输要求] +- **安全审计**：[操作日志和审计追踪] +- **安全合规**：[需满足的标准，如等保、GDPR] + +#### 可扩展性需求 + +- **水平扩展**：[横向扩展能力] +- **垂直扩展**：[纵向扩展空间] +- **模块化设计**：[解耦和可插拔性] +- **配置灵活性**：[配置调整范围] + +#### 可维护性需求 + +- **代码质量**：[规范、测试覆盖率要求] +- **日志规范**：[日志级别、内容、格式] +- **监控告警**：[关键指标和告警阈值] +- **运维支持**：[部署、配置管理、故障排查] + +#### 兼容性需求 + +- **浏览器兼容**：[支持的浏览器类型和版本] +- **设备兼容**：[PC、移动端、平板] +- **操作系统兼容**：[支持的操作系统和版本] +- **API兼容**：[接口版本兼容策略] + +--- + +## 4. 方案设计 + +### 4.1. 系统上下文图 + + + +**系统边界**： + +- 系统职责：[本系统的职责范围] +- 内部功能：[在系统内部实现的功能] +- 外部依赖：[由外部系统提供的功能] + +**外部实体**： + +- 用户和角色：[使用系统的用户群体] +- 外部系统：[与本系统交互的其他系统] +- 第三方服务：[依赖的第三方 API 或服务] +- 基础设施：[数据库、缓存、消息队列等] + +**系统上下文图**： + +```text +[插入系统上下文图] +``` + +### 4.2. 影响分析 + + + +#### 业务流程影响 + +- 流程改变：[对现有业务流程的改变] +- 业务规则：[是否影响已有的业务规则或策略] +- 数据影响：[数据迁移、数据清洗需求] + +#### 上下游系统影响 + +- 上游系统：[是否需要上游配合改造] +- 下游系统：[下游消费方是否需要同步升级] +- 兼容性：[是否需要保持接口向后兼容] +- 联调计划：[系统间的联调和集成测试计划] + +#### 对系统影响 + +- 影响模块：[现有模块和组件清单] +- 数据库变更：[表结构新增、修改、删除] +- 接口变更：[新增接口、参数变更、废弃接口] +- 配置变更：[配置项新增或修改] +- 依赖变更：[新增或升级依赖库] + +#### 性能影响分析 + +- 系统性能：[对响应时间、吞吐量的影响] +- 数据库性能：[对查询效率、存储空间的影响] +- 网络带宽：[对网络带宽的影响] +- 优化需求：[是否需要性能优化或容量规划] + +#### 风险识别 + +- 技术风险：[技术难点、不确定性] +- 业务风险：[业务中断、数据错误] +- 时间风险：[工期延误、资源不足] +- 依赖风险：[第三方服务、团队协作] + +#### 兼容性考虑 + +- 功能兼容：[与现有功能的兼容性] +- 版本兼容：[新老版本的兼容策略] +- 数据兼容：[数据格式的兼容性] +- API管理：[API 版本管理策略] + +### 4.3. 关键设计决策 + + + +#### 【决策1】[决策标题] + +- **状态**：[提议/已接受/已弃用/已替代] +- **背景**：[问题描述和决策动机] +- **候选方案**： + - 方案A：[描述 + 优缺点] + - 方案B：[描述 + 优缺点] + - 方案C：[描述 + 优缺点] +- **决策**：[选择的方案] +- **理由**：[为什么选择当前方案] +- **后果**： + - 积极影响：[预期的好处] + - 消极影响：[已知的风险和限制] +- **决策时间**：[YYYY-MM-DD] + +#### 【决策2】[决策标题] + +- **状态**：[提议/已接受/已弃用/已替代] +- **背景**：[问题描述和决策动机] +- **候选方案**：[方案列表及对比] +- **决策**：[选择的方案] +- **理由**：[为什么选择当前方案] +- **后果**：[预期的影响] +- **决策时间**：[YYYY-MM-DD] + +### 4.4. 领域模型 + + + +**领域划分**： + +- 核心域：[系统的核心业务领域] +- 支撑域：[支持核心域运作的领域] +- 通用域：[通用的、可复用的领域] + +**聚合识别**： + +- 聚合1：[聚合根 + 聚合边界 + 一致性边界] +- 聚合2：[聚合根 + 聚合边界 + 一致性边界] + +**领域模型图**： + +```text +[插入领域模型图 - UML 类图] +``` + +### 4.5. 专项设计（可选） + + + +#### [专项设计1]：[场景名称] + +**适用场景**：[为什么需要这个专项设计] + +**设计说明**： + +[具体的设计内容] + +**设计图示**： + +```text +[插入状态图/时序图/活动图/数据流图等] +``` + +#### [专项设计2]：[场景名称] + +**适用场景**：[为什么需要这个专项设计] + +**设计说明**： + +[具体的设计内容] + +**设计图示**： + +```text +[插入相应的图示] +``` + +--- + +## 5. 技术债务 + + + +### 【未解决-高风险】[债务标题] + +- **描述**：[具体的问题和现状] +- **原因**：[为什么会产生这个债务] +- **影响**：[影响哪些模块或功能，有什么风险] +- **建议**：[如何解决这个债务] +- **优先级**：[P0/P1/P2，何时应该解决] +- **工作量**：[预计X人日] + +### 【待优化-中风险】[债务标题] + +- **描述**：[具体的问题和现状] +- **原因**：[为什么会产生这个债务] +- **影响**：[影响哪些模块或功能，有什么风险] +- **建议**：[如何解决这个债务] +- **优先级**：[P0/P1/P2，何时应该解决] +- **工作量**：[预计X人日] + +### 【已知问题-低风险】[债务标题] + +- **描述**：[具体的问题和现状] +- **原因**：[为什么会产生这个债务] +- **影响**：[影响哪些模块或功能，有什么风险] +- **建议**：[如何解决这个债务] +- **优先级**：[P0/P1/P2，何时应该解决] +- **工作量**：[预计X人日] + +--- + +**偿还计划**： + +- 短期（下一迭代）：[必须解决的债务] +- 中期（近期计划）：[需要解决的债务] +- 长期（持续跟踪）：[可以延后但需要跟踪的债务] diff --git a/templates/plan-template.md b/templates/plan-template.md index 6a8bfc6c8a..2196de07e4 100644 --- a/templates/plan-template.md +++ b/templates/plan-template.md @@ -41,10 +41,11 @@ specs/[###-feature]/ ├── plan.md # This file (/speckit.plan command output) ├── research.md # Phase 0 output (/speckit.plan command) -├── data-model.md # Phase 1 output (/speckit.plan command) -├── quickstart.md # Phase 1 output (/speckit.plan command) -├── contracts/ # Phase 1 output (/speckit.plan command) -└── tasks.md # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan) +├── design.md # Phase 1 output (/speckit.plan command) +├── data-model.md # Phase 1 output (/speckit.plan command, if needed) +├── quickstart.md # Phase 2 output (/speckit.plan command) +├── contracts/ # Phase 2 output (/speckit.plan command) +└── tasks.md # Phase 3 output (/speckit.tasks command - NOT created by /speckit.plan) ``` ### Source Code (repository root)