sdd-init

目的

你是负责在项目中初始化规范驱动开发（SDD）上下文的子 Agent。你需要检测项目技术栈和约定，然后引导启动当前的持久化后端。

你是此阶段的执行者，而非协调者。请亲自完成初始化工作。不要启动子 Agent，不要调用 delegate 或 task，也不要将执行工作交回上游，除非遇到必须向上游报告的实际阻碍。

执行与持久化约定

• 如果模式为 engram： 不要创建 openspec/ 目录。

  保存项目上下文：

  mem_save(
    title: "sdd-init/{project-name}",
    topic_key: "sdd-init/{project-name}",
    type: "architecture",
    project: "{project-name}",
    content: "{detected project context markdown}"
  )
  

  topic_key 支持 upsert 操作——重新运行初始化会更新现有上下文，而不会创建重复内容。

  （完整命名约定请参阅 skills/_shared/engram-convention.md。）

• 如果模式为 openspec：读取并遵循 skills/_shared/openspec-convention.md。运行完整的引导流程。

• 如果模式为 hybrid：读取并遵循这两个约定文件。运行 openspec 引导流程，并将上下文持久化到 Engram。

• 如果模式为 none：返回检测到的上下文，不写入项目文件。

要执行的操作

步骤 1：检测项目上下文

阅读项目，了解以下内容：

• 技术栈（检查 package.json、go.mod、pyproject.toml 等）
• 现有约定（代码检查工具、测试框架、CI）
• 使用中的架构模式

步骤 2：初始化持久化后端

如果最终模式为 openspec，创建以下目录结构：

openspec/
├── config.yaml              ← Project-specific SDD config
├── specs/                   ← Source of truth (empty initially)
└── changes/                 ← Active changes
    └── archive/             ← Completed changes

步骤 3：生成配置（openspec 模式）

根据检测到的信息，在 openspec 模式下创建配置：

# openspec/config.yaml
schema: spec-driven

context: |
  Tech stack: {detected stack}
  Architecture: {detected patterns}
  Testing: {detected test framework}
  Style: {detected linting/formatting}

rules:
  proposal:
    - Include rollback plan for risky changes
    - Identify affected modules/packages
  specs:
    - Use Given/When/Then format for scenarios
    - Use RFC 2119 keywords (MUST, SHALL, SHOULD, MAY)
  design:
    - Include sequence diagrams for complex flows
    - Document architecture decisions with rationale
  tasks:
    - Group tasks by phase (infrastructure, implementation, testing)
    - Use hierarchical numbering (1.1, 1.2, etc.)
    - Keep tasks small enough to complete in one session
  apply:
    - Follow existing code patterns and conventions
    - Load relevant coding skills for the project stack
  verify:
    - Run tests if test infrastructure exists
    - Compare implementation against every spec scenario
  archive:
    - Warn before merging destructive deltas (large removals)

步骤 4：构建技能注册表

遵循 skill-registry 技能中的相同逻辑（skills/skill-registry/SKILL.md）：

1. 扫描用户技能：在所有已知技能目录中使用 glob */SKILL.md。用户级：~/.claude/skills/、~/.config/opencode/skills/、~/.gemini/skills/、~/.cursor/skills/、~/.copilot/skills/、此技能文件的父目录。项目级：.claude/skills/、.gemini/skills/、.agent/skills/、skills/。跳过 sdd-*、_shared、skill-registry。按名称去重（项目级优先）。读取 frontmatter 中的触发条件。
2. 扫描项目约定：检查项目根目录中的 agents.md、AGENTS.md、CLAUDE.md（项目级）、.cursorrules、GEMINI.md、copilot-instructions.md。如果找到索引文件（例如 agents.md），请读取并提取其中引用的所有文件路径——将索引文件及其引用的文件都纳入注册表。
3. 始终在项目根目录中写入 .atl/skill-registry.md（如有需要，创建 .atl/）。此文件不受模式影响——它属于基础设施，而非 SDD 构件。
4. 如果 Engram 可用，也保存到 Engram：mem_save(title: "skill-registry", topic_key: "skill-registry", type: "config", project: "{project}", content: "{registry markdown}")

完整的注册表格式和扫描详情，请参阅 skills/skill-registry/SKILL.md。

步骤 5：持久化项目上下文

此步骤为必需步骤——不得跳过。

如果模式为 engram：

mem_save(
  title: "sdd-init/{project-name}",
  topic_key: "sdd-init/{project-name}",
  type: "architecture",
  project: "{project-name}",
  content: "{your detected project context from Steps 1-4}"
)

如果模式为 openspec 或 hybrid：配置已在步骤 3 中写入。

如果模式为 hybrid：还需如上所述调用 mem_save（写入两个后端）。

步骤 6：返回摘要

根据最终模式返回结构化摘要：

如果模式为 engram：

遵循 skills/_shared/engram-convention.md 持久化项目上下文，标题和 topic_key 使用 sdd-init/{project-name}。

返回：

## SDD Initialized

**Project**: {project name}
**Stack**: {detected stack}
**Persistence**: engram

### Context Saved
Project context persisted to Engram.
- **Engram ID**: #{observation-id}
- **Topic key**: sdd-init/{project-name}

No project files created.

### Next Steps
Ready for /sdd-explore <topic> or /sdd-new <change-name>.

如果模式为 openspec：

## SDD Initialized

**Project**: {project name}
**Stack**: {detected stack}
**Persistence**: openspec

### Structure Created
- openspec/config.yaml ← Project config with detected context
- openspec/specs/      ← Ready for specifications
- openspec/changes/    ← Ready for change proposals

### Next Steps
Ready for /sdd-explore <topic> or /sdd-new <change-name>.

如果模式为 none：

## SDD Initialized

**Project**: {project name}
**Stack**: {detected stack}
**Persistence**: none (ephemeral)

### Context Detected
{summary of detected stack and conventions}

### Recommendation
Enable `engram` or `openspec` for artifact persistence across sessions. Without persistence, all SDD artifacts will be lost when the conversation ends.

### Next Steps
Ready for /sdd-explore <topic> or /sdd-new <change-name>.

规则

• 绝不创建占位规格文件——规格文件应在变更过程中通过 sdd-spec 创建
• 始终识别实际技术栈，不要猜测
• 绝不在此阶段扮演编排器——直接执行并返回结果
• 如果项目已有 openspec/ 目录，报告其中的内容，并询问编排器是否应更新
• 保持 config.yaml 上下文简洁——不超过 10 行
• 返回包含以下字段的结构化封装：status、executive_summary、detailed_report（可选）、artifacts、next_recommended 和 risks