sdd-riper-one

Original：🇨🇳 Chinese

Translated

1 scripts

A skill that implements the SDD-RIPER methodology into strictly executable processes. It is applied in code/architecture tasks for "function-level and project-level CodeMap generation, full-modal requirement context bundling, Spec-driven R&D, and RIPER phase gate advancement", and is suitable for multi-round collaborative development with Claude/Codex/other CLI Agents.

9installs

Sourcehuisezhiyin/sdd-riper

Added on2026-04-09

NPX Install

npx skill4agent add huisezhiyin/sdd-riper sdd-riper-one

SKILL.md Content (Chinese)

View Translation Comparison →

SDD-RIPER-ONE Skill

Global Behaviors and Security Bottom Lines (Global Safeguards)

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

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)

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
```
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)

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
```
, 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)

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)

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

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)

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

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

Automatic Codemap

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)

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

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

Multi-project Review (Extension)

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 / 多项目
```
→ 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=<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

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

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

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

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

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

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)

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 Mode (Log-driven Troubleshooting and Function Verification)

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 / 多项目
```
-> 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)

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
```
(detailed rules for multi-project collaboration)
```
references/commands.md
```
(detailed parameters of native command actions)

sdd-riper-one

NPX Install

Tags

SKILL.md Content (Chinese)

SDD-RIPER-ONE Skill

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

Automatic Codemap

Scope Isolation Rules (Mandatory)

Cross-project Dependencies and Contracts

Multi-project Review (Extension)

Trigger Words

Minimum Startup Example

Native Command Actions (Can Be Entered Directly)

1)
`create_codemap`

2)
`build_context_bundle`

3)
`sdd_bootstrap`

4)
`review_spec`

5)
`review_execute`

6)
`archive`

Phase Constraints (Minimum Set)

Debug Mode (Log-driven Troubleshooting and Function Verification)

Trigger Words

Naming Rules (Unified Time Prefix)

References

sdd-riper-one

NPX Install

Tags

SKILL.md Content (Chinese)

SDD-RIPER-ONE Skill

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

Automatic Codemap

Scope Isolation Rules (Mandatory)

Cross-project Dependencies and Contracts

Multi-project Review (Extension)

Trigger Words

Minimum Startup Example

Native Command Actions (Can Be Entered Directly)

1) create_codemap

2) build_context_bundle

3) sdd_bootstrap

4) review_spec

5) review_execute

6) archive

Phase Constraints (Minimum Set)

Debug Mode (Log-driven Troubleshooting and Function Verification)

Trigger Words

Naming Rules (Unified Time Prefix)

References

1)
`create_codemap`

2)
`build_context_bundle`

3)
`sdd_bootstrap`

4)
`review_spec`

5)
`review_execute`

6)
`archive`