sdd-riper-one

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SDD-RIPER-ONE Skill

全局行为与安全底线 (Global Safeguards)

Global Behaviors and Security Bottom Lines (Global Safeguards)

高危操作阻断：永远不要静默或提议执行
```
git clean
```
（包含任何参数，特别是
```
-fdx
```
），防止用户未提交的工作区数据不可逆丢失。
研发纪律：
- ```
No Spec, No Code
```
  ：未形成并持久化 Spec 前，不进入代码实现。
- ```
No Approval, No Execute
```
  ：未得到执行许可前，禁止进行环境修改或高风险变更。
- ```
Spec is Truth
```
  ：任何聊天决议或最新改动必须回源到 Spec，Spec 是唯一真相源。

High-risk Operation Blocking: Never silently execute or propose executing
```
git clean
```
(with any parameters, especially
```
-fdx
```
) to prevent irreversible loss of users' uncommitted workspace data.
R&D Discipline:
- ```
No Spec, No Code
```
  : Do not enter code implementation before the Spec is formed and persisted.
- ```
No Approval, No Execute
```
  : Environment modifications or high-risk changes are prohibited before execution permission is obtained.
- ```
Spec is Truth
```
  : Any chat resolution or latest change must be synced back to the Spec, which serves as the only single source of truth.

核心定位

Core Positioning

先读一次：
```
references/sdd-riper-one-protocol.md
```
总纲：
```
Pre-Research -> RIPER
```
，全程遵循 SDD 并持续维护 Spec

三条底线：

No Spec, No Code

、

Spec is Truth

、

Reverse Sync

```
create_codemap
```
/
```
build_context_bundle
```
是 Pre-Research 输入准备；
```
sdd_bootstrap
```
是 RIPER 启动命令（进入 Research 第一步，同时完成 Pre-Research 收口）

RIPER 主流程：

Research -> (Innovate, 可选) -> Plan -> Execute -> Review

不要在每轮对话里重载整份 Skill / Spec；默认只回读当前阶段需要的小节
Spec 受众分层与上下文保护：Spec 的第一受众是人类（持久化的任务上下文与组织记忆），第二受众才是模型。协议对模型的核心价值是四件事：注意力聚焦（让模型在当前阶段只关注该关注的）、信息索引（需要时按路径回读，而非全量常驻）、防止上下文腐烂（用落盘的 Spec 对抗长对话中的遗忘与漂移）、辅助 Review（提供 Spec vs 代码的交叉验证基准）。协议绝不应导致上下文被塞满挤爆——RIPER 管流程，Spec 管记录，模型按需取用。

Read once first:
```
references/sdd-riper-one-protocol.md
```
General framework:
```
Pre-Research -> RIPER
```
, follow SDD throughout the process and maintain the Spec continuously

Three bottom lines:

No Spec, No Code

Spec is Truth

Reverse Sync

```
create_codemap
```
/
```
build_context_bundle
```
are input preparations for Pre-Research;
```
sdd_bootstrap
```
is the RIPER startup command (the first step to enter Research, while completing the Pre-Research closure)

RIPER main process:

Research -> (Innovate, optional) -> Plan -> Execute -> Review

Do not reload the entire Skill/Spec in each round of dialogue; by default, only read the sections required for the current phase
Spec audience stratification and context protection: The primary audience of Spec is humans (persisted task context and organizational memory), and the secondary audience is models. The core value of the protocol for models lies in four aspects: Attention Focusing (let the model only focus on what it should pay attention to in the current phase), Information Indexing (read back according to the path when needed, instead of keeping all content resident), Prevent Context Rot (fight against forgetting and drift in long conversations with the persisted Spec), Auxiliary Review (provide a cross-validation benchmark for Spec vs code). The protocol should never cause the context to be overfilled - RIPER manages the process, Spec manages records, and the model accesses them on demand.

Recommended Process (Direct Execution)

标准流（中大型任务）：

create_codemap -> build_context_bundle -> sdd_bootstrap -> Research -> (Innovate, 可选) -> Plan -> Execute -> Review

快速流（小任务/需求模糊）：

sdd_bootstrap -> （按需补）create_codemap/build_context_bundle -> Research -> Plan -> Execute -> Review

门禁：
- 首版 spec 落盘前，不进入实现
- 未收到精确字样
```
Plan Approved
```
  ，禁止进入
```
Execute
```
- ```
Review
```
  不通过，回到
```
Research/Plan
```
  修正

Standard flow (medium and large tasks):

create_codemap -> build_context_bundle -> sdd_bootstrap -> Research -> (Innovate, optional) -> Plan -> Execute -> Review

Fast flow (small tasks/ambiguous requirements):

sdd_bootstrap -> (supplement on demand) create_codemap/build_context_bundle -> Research -> Plan -> Execute -> Review

Phase Gates:
- Do not enter implementation before the first version of the spec is persisted to disk
- It is prohibited to enter
```
Execute
```
  before receiving the exact text
```
Plan Approved
```
- If
```
Review
```
  fails, go back to
```
Research/Plan
```
  for correction

上下文装配规则

Context Assembly Rules

```
SDD
```
是完整持久化上下文与记忆层：必须完整落盘、持续维护，但不要求每轮整份常驻输入
```
RIPER
```
是审批驱动状态机：必须在每轮保持当前
```
phase
```
、当前批准状态与下一步动作清晰可见
裁剪目标是减少重复重放，不是减少约束或弱化门禁

```
SDD
```
is the complete persisted context and memory layer: it must be fully persisted to disk and maintained continuously, but it is not required to be fully resident in the input for each round
```
RIPER
```
is an approval-driven state machine: the current
```
phase
```
, current approval status and next action must be clearly visible in each round
The goal of tailoring is to reduce repeated replay, not to reduce constraints or weaken phase gates

热上下文（每轮必带）

Hot Context (Required for Each Round)

当前
```
phase
```
当前
```
approval status
```
当前
```
spec path
```
当前
```
Goal
```
当前
```
In Scope / Out of Scope
```
当前活跃
```
Checklist
```
当前
```
Open Questions
```
当前风险与
```
Next Action
```
热上下文只用于当前轮聚焦，不替代完整 spec；与 spec 冲突时，永远以 spec 为准

Current
```
phase
```
Current
```
approval status
```
Current
```
spec path
```
Current
```
Goal
```
Current
```
In Scope / Out of Scope
```
Current active
```
Checklist
```
Current
```
Open Questions
```
Current risks and
```
Next Action
```
Hot context is only used for focusing in the current round, and does not replace the complete spec; in case of conflict with the spec, the spec shall always prevail

温上下文（切阶段或高风险动作前加载）

Warm Context (Loaded Before Phase Switch or High-risk Actions)

```
Research -> Plan
```
：
```
Research Findings
```
、关键事实、方案结论

Plan -> Execute

：

File Changes

、

Signatures

、原子

Checklist

```
Execute -> Review
```
：
```
Validation
```
、实际改动摘要、偏差说明
执行
```
review_spec
```
/
```
review_execute
```
时，回读对应评审区块

```
Research -> Plan
```
:
```
Research Findings
```
, key facts, scheme conclusions

Plan -> Execute

File Changes

Signatures

, atomic

Checklist

```
Execute -> Review
```
:
```
Validation
```
, actual change summary, deviation description
When executing
```
review_spec
```
/
```
review_execute
```
, read back the corresponding review section

冷上下文（默认不带，命中再加载）

Cold Context (Not Included by Default, Loaded Only When Hit)

全量
```
Change Log
```
历史
```
Research
```
细节
完整
```
codemap
```
完整
```
context bundle
```
```
MULTI
```
/
```
DEBUG
```
/
```
ARCHIVE
```
的完整扩展规则
长示例、长模板、长 quick reference

Full
```
Change Log
```
Historical
```
Research
```
details
Complete
```
codemap
```
Complete
```
context bundle
```
Complete extension rules for
```
MULTI
```
/
```
DEBUG
```
/
```
ARCHIVE
```
Long examples, long templates, long quick references

硬门禁（不可因裁剪而削弱）

Hard Phase Gates (Cannot Be Weakened Due to Tailoring)

没有 spec，不进入代码实现
```
phase
```
与
```
approval status
```
必须是显式状态，不允许根据语气、倾向或不完整表述推断
没有精确字样
```
Plan Approved
```
，不进入
```
Execute
```
phase 切换前，必须回读对应 spec 区块；不能只靠热上下文跨阶段推进
```
Review
```
时必须基于 plan 与 validation，而不是只看聊天摘要
发现冲突、字段缺失、摘要过期或记忆不确定时，立即回读完整 spec 或相关原文区块

Do not enter code implementation without a spec
```
phase
```
and
```
approval status
```
must be explicit states, and inference based on tone, tendency or incomplete statements is not allowed
Do not enter
```
Execute
```
without the exact text
```
Plan Approved
```
Before phase switching, the corresponding spec section must be read back; phase advancement cannot be carried out only by relying on hot context across phases
```
Review
```
must be based on plan and validation, not just chat summaries
When conflicts, missing fields, expired summaries or uncertain memory are found, immediately read back the complete spec or relevant original sections

回读触发规则

Read-back Trigger Rules

每轮必带：

phase

、

approval status

、

spec path

、

Goal

、当前活跃

Checklist

、

Next Action

切阶段时：回读目标阶段对应的 spec 区块（Research Findings / File Changes / Validation 等）
执行 review 时：
```
review_spec
```
回读 Plan 区块，
```
review_execute
```
回读 Plan + Validation + Review 区块
触发全量回读：阶段切换有争议、摘要与 spec 冲突、长对话出现遗忘迹象、高风险改动
禁止：不能用热上下文替代 spec 原文跨阶段推进，不能根据模糊语气推断
```
Plan Approved
```

Required for each round:

phase

approval status

spec path

Goal

, current active

Checklist

Next Action

When switching phases: Read back the spec section corresponding to the target phase (Research Findings / File Changes / Validation, etc.)
When performing review:
```
review_spec
```
reads back the Plan section,
```
review_execute
```
reads back the Plan + Validation + Review sections
Trigger full read-back: Disputes in phase switching, conflict between summary and spec, signs of forgetting in long conversations, high-risk changes
Prohibited: Hot context cannot be used to replace the original spec for cross-phase advancement, and
```
Plan Approved
```
cannot be inferred based on vague tone

多项目协作（自动发现 + 作用域隔离）

Multi-project Collaboration (Auto-discovery + Scope Isolation)

目标：多项目场景下保持"局部理解 + 局部执行 + 显式边界"，用户零额外配置。

详细协议：

references/sdd-riper-one-protocol.md

→

MULTI-PROJECT PROTOCOL

段

Spec 模板：
```
references/spec-template.md
```
→ 多项目模板

Goal: Maintain "local understanding + local execution + explicit boundaries" in multi-project scenarios, zero additional configuration for users

Detailed protocol:

references/sdd-riper-one-protocol.md

→

MULTI-PROJECT PROTOCOL

section

Spec template:
```
references/spec-template.md
```
→ multi-project template

自动发现（Auto-Discovery）

Auto-Discovery

触发：

sdd_bootstrap: mode=multi_project

或触发词

MULTI / 多项目

Agent 自动扫描
```
workdir
```
下子目录，通过标志文件识别子项目：
- JS/TS:
```
package.json
```
  | Java/Kotlin:
```
pom.xml
```
  ,
```
build.gradle
```
  | Go:
```
go.mod
```
  | Python:
```
pyproject.toml
```
  ,
```
setup.py
```
  | Rust:
```
Cargo.toml
```
  | 通用:
```
.git
```
- Monorepo: 额外检查
```
workspaces
```
  、
```
settings.gradle
```
  、
```
pnpm-workspace.yaml
```
产出
```
Project Registry
```
（
```
§0.1
```
），报告给用户确认后继续
用户也可显式提供
```
projects=[...]
```
跳过自动发现
智能降级：仅 1 个子项目 → 自动降级为单项目模式；0 个子项目 → workdir 本身作为单项目

Trigger:

sdd_bootstrap: mode=multi_project

or trigger words

MULTI / 多项目

Agent automatically scans subdirectories under
```
workdir
```
and identifies subprojects through flag files:
- JS/TS:
```
package.json
```
  | Java/Kotlin:
```
pom.xml
```
  ,
```
build.gradle
```
  | Go:
```
go.mod
```
  | Python:
```
pyproject.toml
```
  ,
```
setup.py
```
  | Rust:
```
Cargo.toml
```
  | General:
```
.git
```
- Monorepo: Additional check for
```
workspaces
```
  ,
```
settings.gradle
```
  ,
```
pnpm-workspace.yaml
```
Generate
```
Project Registry
```
(
```
§0.1
```
), report to the user for confirmation before proceeding
Users can also explicitly provide
```
projects=[...]
```
to skip auto-discovery
Intelligent downgrade: Only 1 subproject → automatically downgrade to single-project mode; 0 subprojects → treat workdir itself as a single project

自动 Codemap

Automatic Codemap

发现项目后，自动为每个子项目检查/生成
```
create_codemap(project)
```

产物路径：

mydocs/codemap/YYYY-MM-DD_hh-mm_<project_id>项目总图.md

After discovering projects, automatically check/generate
```
create_codemap(project)
```
for each subproject

Output path:

mydocs/codemap/YYYY-MM-DD_hh-mm_<project_id>项目总图.md

作用域隔离规则（必须）

Scope Isolation Rules (Mandatory)

每轮先声明
```
active_project
```
与
```
active_workdir
```
默认
```
change_scope=local
```
，只允许修改
```
active_project
```
下的文件
仅在显式
```
change_scope=cross
```
（或触发词
```
CROSS / 跨项目
```
）时允许跨项目改动
始终
```
codemap-first
```
：切换到任何项目前，必须先加载该项目的 codemap/context
跨项目执行后，在 spec
```
§6.1 Touched Projects
```
记录改动项目、文件、原因

Declare
```
active_project
```
and
```
active_workdir
```
first in each round
Default
```
change_scope=local
```
, only allow modification of files under
```
active_project
```
Cross-project changes are allowed only when explicitly setting
```
change_scope=cross
```
(or trigger words
```
CROSS / 跨项目
```
)
Always follow
```
codemap-first
```
: Before switching to any project, the codemap/context of the project must be loaded first
After cross-project execution, record the changed projects, files and reasons in spec
```
§6.1 Touched Projects
```

跨项目依赖与契约

Cross-project Dependencies and Contracts

跨项目改动时，必须在 spec
```
§4.4 Contract Interfaces
```
记录：Provider → Interface → Consumer → 是否 Breaking Change → 迁移方案
跨项目 Plan 的 checklist 按项目分组，Provider 优先于 Consumer 执行
修改前检查目标项目是否有活跃 Spec，有冲突则 STOP 等待用户决策

When making cross-project changes, must record in spec
```
§4.4 Contract Interfaces
```
: Provider → Interface → Consumer → Whether it is a Breaking Change → Migration scheme
The checklist of cross-project Plan is grouped by project, and Provider is executed prior to Consumer
Check whether the target project has an active Spec before modification, STOP and wait for user decision if there is a conflict

多项目 Review（扩展）

Multi-project Review (Extension)

校验跨项目契约一致性（Provider 与 Consumer 接口匹配）
校验 Touched Projects 完整性
校验无孤立改动（所有改动文件都在已注册项目内）
按项目分别评估回归风险

Verify the consistency of cross-project contracts (matching of Provider and Consumer interfaces)
Verify the integrity of Touched Projects
Verify that there are no isolated changes (all changed files are within registered projects)
Evaluate regression risk by project respectively

触发词

Trigger Words

```
MULTI / 多项目
```
→ 进入多项目模式，运行自动发现
```
CROSS / 跨项目
```
→ 当前轮
```
change_scope=cross
```

SWITCH <project_id> / 切换 <project_id>

→ 切换

active_project

，自动加载 codemap

```
REGISTRY / 项目列表
```
→ 显示当前 Project Registry

SCOPE LOCAL / 回到本地

→ 重置为

change_scope=local

```
MULTI / 多项目
```
→ Enter multi-project mode, run auto-discovery
```
CROSS / 跨项目
```
→ Current round
```
change_scope=cross
```

SWITCH <project_id> / 切换 <project_id>

→ Switch

active_project

, automatically load codemap

```
REGISTRY / 项目列表
```
→ Display current Project Registry

SCOPE LOCAL / 回到本地

→ Reset to

change_scope=local

最小启动示例

Minimum Startup Example

text

sdd_bootstrap: mode=multi_project, task=<任务名>, goal=<目标>, requirement=<需求文档或描述>

无需手动列项目，Agent 自动发现并确认。

也可显式指定：

projects=[{id:web-console,path:./web-console},{id:api-service,path:./api-service}]

text

sdd_bootstrap: mode=multi_project, task=<task name>, goal=<goal>, requirement=<requirement document or description>

No need to list projects manually, Agent automatically discovers and confirms.

You can also explicitly specify:

projects=[{id:web-console,path:./web-console},{id:api-service,path:./api-service}]

原生命令动作（可直接输入）

Native Command Actions (Can Be Entered Directly)

create_codemap

create_codemap

用途：生成代码索引地图，支持
```
feature
```
/
```
project
```
（默认
```
feature
```
）
本质：CodeMap 是代码上下文索引，用于后续按需加载，而不是每轮全仓扫描。
输入：
```
scope
```
（建议明确）；
```
mode
```
可选；
```
goal
```
可选

输出：

feature

：

mydocs/codemap/YYYY-MM-DD_hh-mm_<feature>功能.md

project

：

mydocs/codemap/YYYY-MM-DD_hh-mm_<project>项目总图.md

要点：
- ```
feature
```
  关注入口、核心链路、依赖、风险
- ```
project
```
  关注架构层、核心模块、跨模块流程、外部依赖；图示建议优先 Mermaid（受限可降级为结构化文字图）

Purpose: Generate code index map, support
```
feature
```
/
```
project
```
(default
```
feature
```
)
Essence: CodeMap is a code context index for subsequent on-demand loading, instead of full repository scanning in each round.
Input:
```
scope
```
(recommended to be clear);
```
mode
```
optional;
```
goal
```
optional

Output:

feature

mydocs/codemap/YYYY-MM-DD_hh-mm_<feature>功能.md

project

mydocs/codemap/YYYY-MM-DD_hh-mm_<project>项目总图.md

Key points:
- ```
feature
```
  focuses on entry, core link, dependency, risk
- ```
project
```
  focuses on architecture layer, core modules, cross-module processes, external dependencies; Mermaid is preferred for diagrams (can be downgraded to structured text diagrams if limited)

build_context_bundle

build_context_bundle

用途：整理需求上下文，替用户读资料并提炼细节
输入：目录路径
解析策略：best effort，支持文本/文档/图片；不可解析文件进入
```
Unparsed Sources
```
，不阻塞产出

输出：

mydocs/context/YYYY-MM-DD_hh-mm_<task>_context_bundle.md

输出级别：

Lite

：

Source Index

、

Requirement Snapshot

、

Open Questions

、

Next Actions

Standard

：

Requirement Facts

、

Business Rules

、

Acceptance Criteria

、

Constraints

、

Conflicts & Ambiguities

等

Purpose: Organize requirement context, read materials for users and extract details
Input: Directory path
Parsing strategy: best effort, support text/document/image; unparseable files enter
```
Unparsed Sources
```
and do not block output

Output:

mydocs/context/YYYY-MM-DD_hh-mm_<task>_context_bundle.md

Output levels:

Lite

Source Index

Requirement Snapshot

Open Questions

Next Actions

Standard

Requirement Facts

Business Rules

Acceptance Criteria

Constraints

Conflicts & Ambiguities

, etc.

sdd_bootstrap

sdd_bootstrap

用途：RIPER 启动命令（进入 Research 第一步，并产出第一版 spec）
输入：只要是“有意义且真实的需求”即可（口述/文档/聊天记录/context bundle 均可）
执行动作：
- 汇总用户输入 + 代码事实 + 历史资产（codemap/context/spec）
- 冲突处理：先落首版 spec 标记冲突，再给
```
Option A/B
```
  和推荐决策
- 形成首版研究结论与下一步动作

输出：

mydocs/specs/YYYY-MM-DD_hh-mm_<TaskName>.md

首版最小内容：

Context Sources

、

Codemap Used

、

Research Findings

、

Open Questions

、

Next Actions

Purpose: RIPER startup command (the first step to enter Research, and generate the first version of spec)
Input: Any "meaningful and real requirement" is acceptable (oral/document/chat record/context bundle are all allowed)
Execution actions:
- Summarize user input + code facts + historical assets (codemap/context/spec)
- Conflict handling: First persist the first version of spec to mark conflicts, then provide
```
Option A/B
```
  and recommended decision
- Form the first version of research conclusions and next actions

Output:

mydocs/specs/YYYY-MM-DD_hh-mm_<TaskName>.md

Minimum content of the first version:

Context Sources

Codemap Used

Research Findings

Open Questions

Next Actions

review_spec

review_spec

用途：在
```
Plan
```
完成后、
```
Execute
```
前进行 spec 质量评审（建议性，不阻塞执行）
输入：
- ```
spec
```
  ：spec 文件路径（可选，默认当前活跃 spec）
- ```
scope
```
  ：
```
plan_only
```
  （默认）或
```
full
```
评审重点：
1. 目标/范围/验收标准是否清晰且可验证
2. ```
Plan
```
  是否可执行（文件、签名、checklist 是否原子化）
3. 风险、回滚、跨项目契约（如有）是否充分
分阶段原则：
- 仅评审“当前阶段应当具备”的章节，不要求一次性覆盖全 spec
- 对尚未到阶段的章节只做
```
Reminder
```
  ，不计入
```
NO-GO
```
输出：
- ```
Spec Review Matrix
```
  （逐项
```
PASS/FAIL/PARTIAL
```
  + 证据）
- ```
Readiness Verdict
```
  ：
```
GO/NO-GO
```
  （建议性结论）
- ```
Risks & Suggestions
```
  （若继续执行需关注项）
- ```
Phase Reminders
```
  （按阶段待补齐项）
约束：
- ```
NO-GO
```
  不构成硬阻塞；若用户坚持执行，允许继续
- 用户选择继续时，必须在 spec 记录
```
User Decision: Proceed despite NO-GO
```

Purpose: Conduct spec quality review after
```
Plan
```
is completed and before
```
Execute
```
(advisory, does not block execution)
Input:
- ```
spec
```
  : spec file path (optional, default current active spec)
- ```
scope
```
  :
```
plan_only
```
  (default) or
```
full
```
Review focus:
1. Whether the goal/scope/acceptance criteria are clear and verifiable
2. Whether
```
Plan
```
  is executable (whether files, signatures, checklist are atomic)
3. Whether risks, rollback, cross-project contracts (if any) are sufficient
Phased principle:
- Only review the chapters that "should be available in the current phase", do not require full spec coverage at one time
- Only give
```
Reminder
```
  for chapters that have not reached the phase, and do not count as
```
NO-GO
```
Output:
- ```
Spec Review Matrix
```
  (item by item
```
PASS/FAIL/PARTIAL
```
  + evidence)
- ```
Readiness Verdict
```
  :
```
GO/NO-GO
```
  (advisory conclusion)
- ```
Risks & Suggestions
```
  (items to note if you continue execution)
- ```
Phase Reminders
```
  (items to be completed by phase)
Constraints:
- ```
NO-GO
```
  does not constitute a hard block; if the user insists on execution, it is allowed to continue
- When the user chooses to continue, must record
```
User Decision: Proceed despite NO-GO
```
  in the spec

review_execute

review_execute

用途：在
```
Execute
```
后执行结构化评审，输出可回写 spec 的审查结论
输入：
- ```
spec
```
  ：spec 文件路径（可选，默认当前活跃 spec）
- ```
scope
```
  ：
```
changed_only
```
  （默认）或
```
full
```
  （全量评审）
评审三轴（必须全部输出）：
1. Spec 质量与目标达成：spec 是否写清目标、范围、验收标准；需求是否完成
2. Spec-代码一致性：代码是否忠实执行
```
Plan
```
  （文件、签名、checklist、行为）
3. 代码自身质量：脱离 spec 后，代码在正确性、鲁棒性、可维护性、测试、风险上的质量

输出：

```
Review Matrix
```
（三轴逐项
```
PASS/FAIL/PARTIAL
```
+ 证据）
```
Overall Verdict
```
（
```
PASS/FAIL
```
）与
```
Blocking Issues
```
```
Plan-Execution Diff
```
（偏差与原因）

门禁：
- 轴 1 或轴 2 任一
```
FAIL
```
  ->
```
Review FAIL
```
  ，回到
```
Research/Plan
```
- 轴 3 存在高风险问题 ->
```
Review FAIL
```
  ，回到
```
Plan
```

Purpose: Perform structured review after
```
Execute
```
, output review conclusions that can be written back to the spec
Input:
- ```
spec
```
  : spec file path (optional, default current active spec)
- ```
scope
```
  :
```
changed_only
```
  (default) or
```
full
```
  (full review)
Three review axes (must all be output):
1. Spec quality and goal achievement: Whether the spec clearly states the goal, scope, acceptance criteria; whether the requirement is completed
2. Spec-code consistency: Whether the code faithfully executes the
```
Plan
```
  (files, signatures, checklist, behavior)
3. Code quality itself: The quality of the code in terms of correctness, robustness, maintainability, testing, and risk after脱离 the spec

Output:

```
Review Matrix
```
(item by item
```
PASS/FAIL/PARTIAL
```
for three axes + evidence)
```
Overall Verdict
```
(
```
PASS/FAIL
```
) and
```
Blocking Issues
```
```
Plan-Execution Diff
```
(deviations and reasons)

Phase Gates:
- Any
```
FAIL
```
  in axis 1 or axis 2 ->
```
Review FAIL
```
  , go back to
```
Research/Plan
```
- High-risk problems exist in axis 3 ->
```
Review FAIL
```
  , go back to
```
Plan
```

archive

archive

用途：对指定 spec/codemap（或目录）做归档沉淀，将“中间产物”提炼为可复用知识
输入：
- ```
targets
```
  ：文件或目录路径（支持多个）
- ```
kind
```
  ：
```
spec
```
  /
```
codemap
```
  /
```
mixed
```
- ```
audience
```
  ：
```
human
```
  /
```
llm
```
  /
```
both
```
  （默认
```
both
```
  ）
- ```
mode
```
  ：
```
snapshot
```
  （单任务归档，默认）/
```
thematic
```
  （跨任务主题归档）
- ```
topic
```
  ：归档主题名（可选，默认从 targets 推断）
输出：
- ```
human
```
  ：
```
mydocs/archive/YYYY-MM-DD_hh-mm_<topic>_human.md
```
  （汇报视角）
- ```
llm
```
  ：
```
mydocs/archive/YYYY-MM-DD_hh-mm_<topic>_llm.md
```
  （后续开发参考视角）
- 每个归档文档必须包含
```
Trace to Sources
```
  （结论 -> 来源文件）避免失真
门禁：
- 有活跃执行中的 spec（未完成 Review）时，禁止归档该 spec
- 默认只归档不删除原文件；删除/移动需用户显式授权

自动化脚本（推荐）：

python3 scripts/archive_builder.py --targets mydocs/specs mydocs/codemap --kind mixed --audience both --mode thematic --topic <主题>

如需强制归档活跃 spec：追加
```
--allow-active-spec
```
（仅在用户明确确认后使用）

Purpose: Archive and precipitate specified spec/codemap (or directory), refine "intermediate products" into reusable knowledge
Input:
- ```
targets
```
  : file or directory paths (support multiple)
- ```
kind
```
  :
```
spec
```
  /
```
codemap
```
  /
```
mixed
```
- ```
audience
```
  :
```
human
```
  /
```
llm
```
  /
```
both
```
  (default
```
both
```
  )
- ```
mode
```
  :
```
snapshot
```
  (single task archive, default) /
```
thematic
```
  (cross-task thematic archive)
- ```
topic
```
  : archive topic name (optional, default inferred from targets)
Output:
- ```
human
```
  :
```
mydocs/archive/YYYY-MM-DD_hh-mm_<topic>_human.md
```
  (report perspective)
- ```
llm
```
  :
```
mydocs/archive/YYYY-MM-DD_hh-mm_<topic>_llm.md
```
  (subsequent development reference perspective)
- Each archived document must include
```
Trace to Sources
```
  (conclusion -> source file) to avoid distortion
Phase Gates:
- When there is an actively executing spec (Review not completed), archiving this spec is prohibited
- By default, only archive without deleting original files; deletion/movement requires explicit user authorization

Automation script (recommended):

python3 scripts/archive_builder.py --targets mydocs/specs mydocs/codemap --kind mixed --audience both --mode thematic --topic <topic>

If you need to force archive active spec: append
```
--allow-active-spec
```
(only used after explicit user confirmation)

阶段约束（最小集合）

Phase Constraints (Minimum Set)

每轮先同步 spec 再推进阶段
默认不在每轮对话中重载整份 spec；优先回读当前阶段区块、活跃 checklist、
```
Open Questions
```
、最近一次
```
Change Log / Validation
```
仅在切换阶段、执行
```
review_spec/review_execute
```
、发现冲突或明显遗忘时，全量回读 spec
```
codemap
```
/
```
context bundle
```
按需读取，不作为每轮固定输入
```
Innovate
```
可选：复杂任务建议 2-3 方案；小任务可跳过但要写原因
```
Plan
```
必须可执行：文件路径 + 签名 + 原子 checklist
```
Plan
```
后建议执行
```
review_spec
```
；其
```
NO-GO
```
为建议项，不是强制门禁

Review

必须按三轴评审并回写结论：

Review Matrix

、

Overall Verdict

、

Plan-Execution Diff

任务闭环后建议执行
```
archive
```
，沉淀 human/llm 双视角知识

Sync the spec first before advancing the phase in each round
Do not reload the entire spec in each round of dialogue by default; prioritize reading back the current phase section, active checklist,
```
Open Questions
```
, latest
```
Change Log / Validation
```
Only read back the full spec when switching phases, executing
```
review_spec/review_execute
```
, finding conflicts or obvious forgetting
```
codemap
```
/
```
context bundle
```
are read on demand, not as fixed input for each round
```
Innovate
```
is optional: 2-3 schemes are recommended for complex tasks; small tasks can be skipped but the reason should be written
```
Plan
```
must be executable: file path + signature + atomic checklist
It is recommended to execute
```
review_spec
```
after
```
Plan
```
; its
```
NO-GO
```
is an advisory item, not a mandatory phase gate
```
Review
```
must be carried out according to the three axes and the conclusions should be written back:
```
Review Matrix
```
,
```
Overall Verdict
```
,
```
Plan-Execution Diff
```
It is recommended to execute
```
archive
```
after the task is closed to precipitate dual-perspective knowledge for human/llm

Debug 模式（日志驱动排查与功能验证）

Debug Mode (Log-driven Troubleshooting and Function Verification)

用途：基于日志 + Spec + 代码三角定位 Bug，或用全链路日志验证功能是否正常

触发词：

DEBUG / 排查 / 日志分析 / 验证功能

输入：
- ```
log_path
```
  ：日志文件或日志目录路径（必须）
- ```
issue
```
  ：发现的问题描述 / 报错信息（可选，排查模式时建议提供）
- ```
spec
```
  ：关联的 Spec 文件路径（可选，验证模式时建议提供）
两种子模式：
- 排查模式（默认）：用户提供日志 + 问题描述，Agent 结合 Spec 和代码定位可能的 Bug 根因
- 验证模式：用户提供全链路日志 + Spec，Agent 逐条比对 Spec 中的预期行为与日志中的实际行为，确认功能是否正常
工作流：
1. 读取日志文件/目录，提取关键错误、异常、调用链信息
2. 加载关联的 Spec 和 CodeMap（如有），建立"预期行为 vs 实际行为"的对照
3. 定位代码中的可疑逻辑（结合 CodeMap 索引精准跳转）
4. 输出结论：Bug 根因分析 / 功能验证报告
5. 如需修复，自动进入 RIPER 流程（Research → Plan → Execute → Review）
约束：
- Debug 模式本身不直接改代码，只做分析和定位
- 需要改代码时，必须走 RIPER 流程（或 FAST 通道处理小修复）
- 分析结论回写到 Spec 的
```
§ Debug Log
```
  段（如有活跃 Spec）

Purpose: Locate bugs based on the triangulation of log + Spec + code, or verify whether the function is normal with full-link logs

Trigger words:

DEBUG / 排查 / 日志分析 / 验证功能

Input:
- ```
log_path
```
  : log file or log directory path (mandatory)
- ```
issue
```
  : discovered problem description / error message (optional, recommended when in troubleshooting mode)
- ```
spec
```
  : associated Spec file path (optional, recommended when in verification mode)
Two sub-modes:
- Troubleshooting mode (default): The user provides logs + problem description, and the Agent combines Spec and code to locate possible root causes of bugs
- Verification mode: The user provides full-link logs + Spec, and the Agent compares the expected behavior in the Spec with the actual behavior in the logs one by one to confirm whether the function is normal
Workflow:
1. Read log files/directories, extract key errors, exceptions, call chain information
2. Load associated Spec and CodeMap (if any), establish a comparison of "expected behavior vs actual behavior"
3. Locate suspicious logic in the code (precise jump combined with CodeMap index)
4. Output conclusion: Bug root cause analysis / function verification report
5. If repair is needed, automatically enter the RIPER process (Research → Plan → Execute → Review)
Constraints:
- Debug mode itself does not directly modify code, only does analysis and positioning
- When code modification is required, must follow the RIPER process (or FAST channel for small fixes)
- Analysis conclusions are written back to the
```
§ Debug Log
```
  section of the Spec (if there is an active Spec)

触发词

Trigger Words

MAP / Code Map / 链路梳理 / 只看代码

create_codemap(feature)

PROJECT MAP / 全局地图 / 项目总图 / MAP ALL

create_codemap(project)

```
MULTI / 多项目
```
-> 多项目轻量模式（父目录 workdir + 局部执行）
```
CROSS / 跨项目
```
-> 允许跨项目改动（强制记录
```
Touched Projects
```
）
```
FAST / 快速 / >>
```
-> 小改快速通道（改后同步 spec）

REVIEW SPEC / 评审规格 / 计划评审

-> 执行

review_spec

（建议性预审）

REVIEW EXECUTE / 代码评审 / 实现复盘

-> 执行

review_execute

（三轴审查）

```
ARCHIVE / 归档 / 沉淀
```
-> 执行
```
archive
```
（总结、合并、精炼）
```
DEBUG / 排查 / 日志分析 / 验证功能
```
-> Debug 模式（日志驱动排查与功能验证）
```
EXIT SDD / 退出协议
```
-> 退出状态机

MAP / Code Map / 链路梳理 / 只看代码

create_codemap(feature)

PROJECT MAP / 全局地图 / 项目总图 / MAP ALL

create_codemap(project)

```
MULTI / 多项目
```
-> Multi-project lightweight mode (parent directory workdir + local execution)
```
CROSS / 跨项目
```
-> Allow cross-project changes (mandatory recording of
```
Touched Projects
```
)
```
FAST / 快速 / >>
```
-> Small change fast channel (sync spec after modification)

REVIEW SPEC / 评审规格 / 计划评审

-> Execute

review_spec

(advisory pre-review)

REVIEW EXECUTE / 代码评审 / 实现复盘

-> Execute

review_execute

(three-axis review)

```
ARCHIVE / 归档 / 沉淀
```
-> Execute
```
archive
```
(summary, merge, refine)
```
DEBUG / 排查 / 日志分析 / 验证功能
```
-> Debug mode (log-driven troubleshooting and function verification)
```
EXIT SDD / 退出协议
```
-> Exit the state machine

命名规则（统一时间前缀）

Naming Rules (Unified Time Prefix)

时间前缀：
```
YYYY-MM-DD_hh-mm_
```

create_codemap(feature)

：

mydocs/codemap/YYYY-MM-DD_hh-mm_<feature>功能.md

create_codemap(project)

：

mydocs/codemap/YYYY-MM-DD_hh-mm_<project>项目总图.md

build_context_bundle

：

mydocs/context/YYYY-MM-DD_hh-mm_<task>_context_bundle.md

sdd_bootstrap

：

mydocs/specs/YYYY-MM-DD_hh-mm_<TaskName>.md

archive(human)

：

mydocs/archive/YYYY-MM-DD_hh-mm_<topic>_human.md

archive(llm)

：

mydocs/archive/YYYY-MM-DD_hh-mm_<topic>_llm.md

Time prefix:
```
YYYY-MM-DD_hh-mm_
```

create_codemap(feature)

mydocs/codemap/YYYY-MM-DD_hh-mm_<feature>功能.md

create_codemap(project)

mydocs/codemap/YYYY-MM-DD_hh-mm_<project>项目总图.md

build_context_bundle

mydocs/context/YYYY-MM-DD_hh-mm_<task>_context_bundle.md

sdd_bootstrap

mydocs/specs/YYYY-MM-DD_hh-mm_<TaskName>.md

archive(human)

mydocs/archive/YYYY-MM-DD_hh-mm_<topic>_human.md

archive(llm)

mydocs/archive/YYYY-MM-DD_hh-mm_<topic>_llm.md

参考

References

```
references/sdd-riper-one-protocol.md
```
```
references/spec-template.md
```
```
references/workflow-quickref.md
```
```
references/usage-examples.md
```
```
references/archive-template.md
```
```
references/multi-project.md
```
（多项目协作详细规则）
```
references/commands.md
```
（原生命令动作详细参数）

```
references/sdd-riper-one-protocol.md
```
```
references/spec-template.md
```
```
references/workflow-quickref.md
```
```
references/usage-examples.md
```
```
references/archive-template.md
```
```
references/multi-project.md
```
(detailed rules for multi-project collaboration)
```
references/commands.md
```
(detailed parameters of native command actions)

sdd-riper-one

Original

Translation

SDD-RIPER-ONE Skill

SDD-RIPER-ONE Skill

全局行为与安全底线 (Global Safeguards)

Global Behaviors and Security Bottom Lines (Global Safeguards)

核心定位

Core Positioning

推荐流程（直接执行）

Recommended Process (Direct Execution)

上下文装配规则

Context Assembly Rules

热上下文（每轮必带）

Hot Context (Required for Each Round)

温上下文（切阶段或高风险动作前加载）

Warm Context (Loaded Before Phase Switch or High-risk Actions)

冷上下文（默认不带，命中再加载）

Cold Context (Not Included by Default, Loaded Only When Hit)

硬门禁（不可因裁剪而削弱）

Hard Phase Gates (Cannot Be Weakened Due to Tailoring)

回读触发规则

Read-back Trigger Rules

多项目协作（自动发现 + 作用域隔离）

Multi-project Collaboration (Auto-discovery + Scope Isolation)

自动发现（Auto-Discovery）

Auto-Discovery

自动 Codemap

Automatic Codemap

作用域隔离规则（必须）

Scope Isolation Rules (Mandatory)

跨项目依赖与契约

Cross-project Dependencies and Contracts

多项目 Review（扩展）

Multi-project Review (Extension)

触发词

Trigger Words

最小启动示例

Minimum Startup Example

原生命令动作（可直接输入）

Native Command Actions (Can Be Entered Directly)

1) create_codemap

1) create_codemap

2) build_context_bundle

2) build_context_bundle

3) sdd_bootstrap

3) sdd_bootstrap

4) review_spec

4) review_spec

5) review_execute

5) review_execute

6) archive

6) archive

阶段约束（最小集合）

Phase Constraints (Minimum Set)

Debug 模式（日志驱动排查与功能验证）

Debug Mode (Log-driven Troubleshooting and Function Verification)

触发词

Trigger Words

命名规则（统一时间前缀）

Naming Rules (Unified Time Prefix)

参考

References

1)
`create_codemap`

1)
`create_codemap`

2)
`build_context_bundle`

2)
`build_context_bundle`

3)
`sdd_bootstrap`

3)
`sdd_bootstrap`

4)
`review_spec`

4)
`review_spec`

5)
`review_execute`

5)
`review_execute`

6)
`archive`

6)
`archive`