SDD-RIPER Light: AI Agent Harness

English | 简体中文

Let the model move the work forward. Let the human own goals, boundaries, permissions, checkpoints, evidence, and acceptance.

SDD-RIPER is a context-first LLM task automation toolkit for working with strong coding agents. It is not a magic prompt and it is not heavyweight spec-driven development. It is a small set of controls and companion skills that make model-driven work observable, recoverable, reviewable, and safe to resume.

The default entry is sdd-riper-one-light. Use the heavier sdd-riper-one when the task needs stricter gates, denser artifacts, or training/audit-ready traces.

The repository is organized around four complementary skills:

• sdd-riper-one-light and sdd-riper-one control execution, checkpoints, validation, and reverse sync.
• codemap turns unfamiliar code into an agent-facing context index.
• new-chat-ready preserves recovery context for new chats, handoffs, and long pauses.

Quick Start

Use this prompt for ordinary coding or documentation work:

Use sdd-riper-one-light for this task.
Do not change files yet.

First give me:
- your understanding of the task
- the core goal for this loop
- a minimal spec / summary
- Done Contract: what counts as done, and what proves it
- next actions
- risks
- validation method

Wait for my approval before execution.

For unfamiliar code, first ask for a CodeMap:

Use codemap.
Create a feature-level or project-level code terrain index before planning changes.
Focus on entry points, call chains, risk points, validation entry points, and the smallest code slice to read next.

For a fresh-chat handoff:

Use new-chat-ready.
Create a resume pack and a paste-ready next-chat prompt.
Also scan for reusable project knowledge, but do not commit memory/spec/handoff files unless I explicitly approve.

Which Skill To Use

These four skills share the same context principle: keep active context small, persist durable state outside the chat, and load only the slice needed for the next decision.

| Skill | Use When | Output | | --- | --- | --- | | sdd-riper-one-light | Daily coding, docs, bugfixes, ordinary refactors, strong-model work | Same core controls with low-friction checkpoints, minimal spec, validation, reverse sync | | sdd-riper-one | High-risk work, multi-file refactors, audit, training, complex handoff | Same core controls with explicit RIPER gates, fuller spec, denser artifacts, stronger blocking | | codemap | Unfamiliar codebases, legacy systems, large modules, cross-repo tasks | Agent-facing code terrain index | | new-chat-ready | New chat, resume pack, handoff, context compression, recovered sessions | Durable handoff, next-chat prompt, project-memory sync scan |

Minimal Agent Setup

For Codex, Claude Code, and other agentic coding environments, the smallest useful repo layout is:

<repo>/
  AGENTS.md
  skills/
    codemap/
    new-chat-ready/
    sdd-riper-one-light/
    sdd-riper-one/

Recommended defaults:

• Put repo-specific rules in AGENTS.md.
• Put personal or team-wide defaults in a system-level AGENTS.md; use examples/global-agents.md as the template.
• Use sdd-riper-one-light by default.
• Add codemap before planning changes in unfamiliar or large code.
• Use new-chat-ready before long pauses, context resets, or handoffs.
• Switch to sdd-riper-one for high-risk or audit-heavy work.

Core Workflow

read context -> restate goal and risk -> checkpoint -> execute -> validate -> reverse sync

The harness keeps a few hard rules:

• Restate First: restate the task before planning or changing files.
• No Spec, No Code: create or update a minimal source of truth before implementation.
• No Approval, No Execute: wait for explicit approval before code changes or high-impact actions.
• Done by Evidence: completion must be proven by tests, logs, screenshots, manual checks, or equivalent evidence.
• Reverse Sync: write verified conclusions back into the spec, handoff, docs, or project memory when appropriate.

Spec And Memory Boundaries

There are three different layers. Do not mix them.

| Layer | Purpose | Typical Location | | --- | --- | --- | | Feature spec / handoff | Current task truth, decisions, progress, validation, resume state | mydocs/specs/*, mydocs/handoff/*, or project conventions | | Project knowledge / memory | Stable facts, repeated pitfalls, reusable validation commands, project-specific rules | PROJECT_KNOWLEDGE.md, PROJECT_SPEC.md, PROJECT_MEMORY.md, mydocs/project/*, or files indexed by AGENTS.md | | System-level defaults | Personal or team-wide agent routing and safety boundaries | system AGENTS.md, examples/global-agents.md |

Important privacy rule:

• The project or human defines the knowledge topology. SDD detects Project Sync Candidates and routes them according to AGENTS.md or explicit user instruction.
• Agents may proactively detect reusable knowledge and propose a Project Sync Candidate.
• Agents must not stage or commit system-level knowledge, feature specs, handoffs, project memory, or user preference memory by default.
• Commit those files only when the user explicitly asks, the target repository is appropriate, and the content has been sanitized for that repository.

Repository Hygiene

This repository is public and reusable. Keep it clean:

• Do not commit runtime data: .agent-memory/, .expcap/, SQLite files, Milvus Lite data, traces, episodes, candidates, assets, or local cache directories.
• Do not commit .env, credentials, tokens, API keys, private logs, personal paths, or user data.
• Do not edit .gitignore just to force local artifacts into the repo.
• Sanitize examples before committing: preserve the problem shape and reasoning, remove private names, URLs, IDs, logs, secrets, and user data.
• For expcap, prefer user-cache storage such as EXPCAP_STORAGE_PROFILE=user-cache and EXPCAP_HOME="$HOME/.expcap".

Multi-Repo Work

For frontend/backend or microservice work, do not let the model ingest every repository at once.

Start with a project registry:

MULTI / multi-project

This workspace contains multiple repositories.
First discover projects and create a Project Registry.
Do not read all code at once.
Identify the main project, related projects, active_project, and change_scope.
Default to local. Before cross-project edits, stop at a checkpoint and wait for approval.

See skills/sdd-riper-one/references/multi-project.md for the fuller protocol.

Repository Map

| Path | What It Is | | --- | --- | | AGENTS.md | Project-level agent rules for this repository | | examples/global-agents.md | System-level / personal AGENTS.md template | | skills/sdd-riper-one-light | Default daily harness | | skills/sdd-riper-one | Strict control protocol | | skills/codemap | Code terrain indexing skill | | skills/new-chat-ready | New-chat handoff and project-memory sync skill | | docs/README.md | Docs map and reading path | | docs/archive/ | Historical essays and writing material | | protocols/ | Older protocol references |

Reading Path

If you want the shortest useful path:

1. Read skills/sdd-riper-one-light/README.md.
2. Try one real task with the quick-start prompt.
3. Use codemap on unfamiliar code.
4. Read skills/sdd-riper-one/README.md when you need stricter gates.
5. Use docs/README.md only when you want the long-form articles.

Recommended long-form docs:

| Document | Core Question | | --- | --- | | Docs map | Which docs are current and which are archived | | Hands-on AI Coding Harness | How to slice tasks, control context, use codemap, validate output, and leave recoverable state | | Team adoption guide | How to turn personal agent habits into team practice | | Claude Code source walkthrough | What real agent runtimes teach about harness design |

Core Claim

The important move is not to make AI a more obedient coding assistant.

The important move is to accept that the model can now move the event forward, then build a control plane around that agency.

That is the purpose of SDD-RIPER Light.