Skip to content

SDD bootstrap: governance, agents, CI, scripts, examples [TASK-001..TASK-009] - #1

Merged
lwyBZss8924d merged 12 commits into
mainfrom
sdd-bootstrap-20250909
Sep 9, 2025
Merged

lwyBZss8924d merged 12 commits into
mainfrom
sdd-bootstrap-20250909

Conversation

@lwyBZss8924d

@lwyBZss8924d lwyBZss8924d commented Sep 9, 2025 •

Copy link
Copy Markdown
Owner

SDD Bootstrap: Governance, Agents, CI, Scripts, Examples [TASK-001..TASK-009]

This PR introduces a complete, enforceable Spec-Driven Development (SDD) system to the fork repository. It mirrors the curated SDD bootstrap from the working repo and aligns with our SDD lifecycle and governance.

Scope

  • Governance (dev-docs/sdd): constitution.md, constitution_update_checklist.md, lifecycle.md
  • Agent context files (dev-docs/sdd + dev-docs/cli): CLAUDE.md, AGENTS.md
  • Agents/MCP guide: dev-docs/agents/mcp.md
  • Git worktrees policy: dev-docs/git/worktrees.md
  • CI workflows: .github/workflows/sdd-ci.yml, ai-review.yml
  • SDD validation scripts: scripts/sdd/validate_structure.py, run_semantic_checks.sh, lint_docs.sh
  • Tests: tests/test_sdd_validation.py, tests/test_specify_cli.py
  • Config: .editorconfig, .markdownlint.json, .gitattributes, CHANGELOG.md
  • Example artifacts: specs/000-example/{ISSUE.md, TASK-PLAN.md, spec.md}
  • README Quickstart and WARP.md

SDD Lifecycle Mapping

  1. Raw requirements → PRD: specs/ template + example (specs/000-example/spec.md)
  2. PRD → Issues: specs/000-example/ISSUE.md
  3. Issues → Task Plan → Dev: specs/000-example/TASK-PLAN.md with [TASK-###]
  4. Dev → commits: all commits include TASK-001..TASK-009 traceability
  5. Commits → CI: sdd-ci.yml validates structure, docs style, tests, linters
  6. CI acceptance: advisory AI review + summary job; sdd-validate blocks if errors
  7. Merge → SDD updates: governance files and docs included
  8. Close loop: CHANGELOG.md initialized; future PRs update it

Validation performed locally

  • scripts/sdd/validate_structure.py → PASS
  • grep for "[NEEDS CLARIFICATION" → none unresolved (only policy references)

Reviewer focus

  • Verify SDD gates: simplicity, anti-abstraction, integration-first reflected in lifecycle and templates
  • Confirm agent permissions/safety guidance in CLAUDE.md/AGENTS.md are appropriate
  • Review CI jobs and ensure they are safe-by-default (advisory where needed)
  • Check example artifacts demonstrate traceability from ISSUE → TASK → COMMIT

Checklist (SDD Compliance)

  • Governance docs present and complete
  • Agent context files present under dev-docs/sdd and dev-docs/cli
  • SDD validator passes locally
  • No unresolved [NEEDS CLARIFICATION] markers
  • CI workflows added
  • Tests scaffolded and runnable
  • CHANGELOG initialized (Keep a Changelog)
  • Docs style aligned with Google style via markdownlint

Notes

  • This PR is a foundational bootstrap; future PRs can specialize CI matrices and add stack-specific linters as needed.
  • Upstream sync is configured via the upstream remote in the local environment.

Summary by CodeRabbit

  • 新功能
    • 新增自动AI代码审查工作流与CI汇总/验证;提供本地语义与文档检查脚本;加入示例SDD规范/任务/问题模板。
  • 文档
    • 增补README快速上手、CHANGELOG;新增SDD宪章/生命周期、代理与MCP集成、WARP、Git工作树等全套开发文档。
  • 测试
    • 添加SDD结构与安全校验测试,以及Specify CLI行为与错误场景测试。
  • 风格
    • 引入EditorConfig与Markdownlint规则,统一缩进、行尾与Markdown格式;完善.gitattributes文本/二进制归类与换行规范。
  • 杂务
    • 配置pyproject开发依赖与工具;新增CI工作流与导出忽略规则。

- Add comprehensive WARP.md file for WARP agent guidance
- Include essential commands for specify CLI installation and usage
- Document Spec-Driven Development (SDD) methodology and lifecycle
- Map project structure with key files and directories
- Provide complete development workflow from spec to implementation
- Include architectural constraints from constitution template
- Add command cheatsheet and AI assistant-specific guidance
- Include troubleshooting and maintenance sections

This guide enables future WARP instances to efficiently work with
the spec-kit repository, understanding its unique SDD approach and
tooling.
@coderabbitai

coderabbitai Bot commented Sep 9, 2025 •

Copy link
Copy Markdown

Caution

Review failed

The pull request is closed.

Walkthrough

在仓库中新增并配置了编辑器/Git属性、Markdown 规范、PyProject 工具链;引入两套 GitHub Actions 工作流(AI 评审与SDD CI);添加多份 SDD 治理与多代理文档、MCP 集成与 Git worktree 指南;提供 SDD 校验与文档检查脚本;加入示例规格与任务计划;补充测试套件。

Changes

Cohort / File(s) Change Summary
仓库与编辑器配置
/.editorconfig, /.gitattributes, /.markdownlint.json, /pyproject.toml
新增统一格式/换行策略、Markdown 规则与 Python 开发工具链配置(pytest/coverage/black/ruff)。
GitHub Actions 工作流
.github/workflows/ai-review.yml, .github/workflows/sdd-ci.yml
新增 AI 代码评审与 SDD CI(结构校验、文档风格、测试、Lint、汇总),含占位的深度评审步骤。
顶层文档
/README.md, /CHANGELOG.md, /WARP.md
新增/更新快速入门、变更记录与 WARP 使用指南。
SDD 与多代理文档
/dev-docs/sdd/* (AGENTS.md, CLAUDE.md, constitution.md, constitution_update_checklist.md, lifecycle.md), /dev-docs/agents/mcp.md, /dev-docs/cli/AGENTS.md, /dev-docs/cli/CLAUDE.md, /dev-docs/git/worktrees.md
新增 SDD 宪章、生命周期、变更清单、代理目录与 MCP 集成、CLI/SDD 开发上下文、Git worktree 指南等。
SDD 脚本
/scripts/sdd/lint_docs.sh, /scripts/sdd/run_semantic_checks.sh, /scripts/sdd/validate_structure.py
新增文档 Lint、语义一致性检查与结构校验脚本(含安全扫描与报告)。
示例规格与任务
/specs/000-example/* (spec.md, TASK-PLAN.md, ISSUE.md)
新增 SDD 示例规格、任务计划与议题文档。
测试套件
/tests/test_sdd_validation.py, /tests/test_specify_cli.py
新增仓库/SDD 合规校验与 CLI 行为测试(包含模拟与正则校验)。

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant GH as GitHub Actions
  participant Repo as Repo
  participant Py as review_analysis.py
  participant PR as Pull Request

  GH->>Repo: checkout (fetch-depth: 0)
  GH->>GH: 解析触发上下文/PR编号/类型
  GH->>Repo: 收集变更文件与PR信息
  GH->>Py: 生成并执行分析脚本
  Py-->>GH: 输出JSON(issues, suggestions)
  GH->>PR: 发表AI评审评论
  note over GH,PR: 分支条件:workflow_dispatch 可触发“Claude 深度评审”占位任务
Loading
sequenceDiagram
  autonumber
  participant GH as GitHub Actions (sdd-ci)
  participant Repo as Repo
  participant Py as validate_structure.py
  participant Sh as lint_docs.sh / run_semantic_checks.sh
  participant Sum as Summary

  GH->>Repo: checkout
  par 校验/风格/测试/静态检查
    GH->>Py: sdd-validate(结构/治理/安全/占位符)
    GH->>Sh: docs-style(markdownlint)
    GH->>Repo: tests(pytest 3.11/3.12)
    GH->>Repo: linters(black --check, ruff)
  end
  GH->>Sum: 汇总各作业结果
  alt sdd-validate 失败
    Sum-->>GH: 标记工作流失败
  else
    Sum-->>GH: 通过
  end
Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes

Poem

兔子挥笔抖三行,
新规新流入仓忙。
文档脚本齐上阵,
规格任务把关强。
CI叮当评审响,
一跃成章步稳长。

Tip

👮 Agentic pre-merge checks are now available in preview!

Pro plan users can now enable pre-merge checks in their settings to enforce checklists before merging PRs.

  • Built-in checks – Quickly apply ready-made checks to enforce title conventions, require pull request descriptions that follow templates, validate linked issues for compliance, and more.
  • Custom agentic checks – Define your own rules using CodeRabbit’s advanced agentic capabilities to enforce organization-specific policies and workflows. For example, you can instruct CodeRabbit’s agent to verify that API documentation is updated whenever API schema files are modified in a PR. Note: Upto 5 custom checks are currently allowed during the preview period. Pricing for this feature will be announced in a few weeks.

Example:

reviews:
  pre_merge_checks:
    custom_checks:
		  - name: "Undocumented Breaking Changes"
			  mode: "warning"
			  instructions: |
				  Flag potential breaking changes that are not documented:
				  1. Identify changes to public APIs/exports, CLI flags, environment variables, configuration keys, database schemas, or HTTP/GraphQL endpoints (including removed/renamed items and changes to types, required params, return values, defaults, or behavior).
				  2. Ignore purely internal/private changes (e.g., code not exported from package entry points or marked internal).
				  3. Verify documentation exists: a "Breaking Change" section in the PR description and updates to CHANGELOG.md.

Please share your feedback with us on this Discord post.


📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between e566e90 and 7433bb7.

📒 Files selected for processing (26)
  • .editorconfig (1 hunks)
  • .gitattributes (1 hunks)
  • .github/workflows/ai-review.yml (1 hunks)
  • .github/workflows/sdd-ci.yml (1 hunks)
  • .markdownlint.json (1 hunks)
  • CHANGELOG.md (1 hunks)
  • README.md (1 hunks)
  • WARP.md (1 hunks)
  • dev-docs/agents/mcp.md (1 hunks)
  • dev-docs/cli/AGENTS.md (1 hunks)
  • dev-docs/cli/CLAUDE.md (1 hunks)
  • dev-docs/git/worktrees.md (1 hunks)
  • dev-docs/sdd/AGENTS.md (1 hunks)
  • dev-docs/sdd/CLAUDE.md (1 hunks)
  • dev-docs/sdd/constitution.md (1 hunks)
  • dev-docs/sdd/constitution_update_checklist.md (1 hunks)
  • dev-docs/sdd/lifecycle.md (1 hunks)
  • pyproject.toml (1 hunks)
  • scripts/sdd/lint_docs.sh (1 hunks)
  • scripts/sdd/run_semantic_checks.sh (1 hunks)
  • scripts/sdd/validate_structure.py (1 hunks)
  • specs/000-example/ISSUE.md (1 hunks)
  • specs/000-example/TASK-PLAN.md (1 hunks)
  • specs/000-example/spec.md (1 hunks)
  • tests/test_sdd_validation.py (1 hunks)
  • tests/test_specify_cli.py (1 hunks)
✨ Finishing Touches
  • 📝 Generate Docstrings
🧪 Generate unit tests
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch sdd-bootstrap-20250909

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@lwyBZss8924d
lwyBZss8924d merged commit 08bbed1 into main Sep 9, 2025
lwyBZss8924d added a commit that referenced this pull request Sep 10, 2025
Addresses CodeQL security warnings about missing workflow permissions.
Following the principle of least privilege, all jobs now explicitly
declare 'contents: read' permission only.

Security improvements:
- Added global default permissions at workflow level
- Each job explicitly declares minimal required permissions
- Prevents unintended write access via GITHUB_TOKEN
- Complies with GitHub Actions security best practices

Fixes 6 CodeQL alerts: #1, #2, #3, #4, #6, #7
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant