huisezhiyin/sdd-riper

SDD‑RIPER Light – A Control Plane for Coding Agents

What it is – A tiny, repo‑native framework that lets large‑language‑model (LLM) coding agents work on real codebases while keeping the human in charge of goals, boundaries, approvals, and evidence. It does not try to replace prompts; instead it adds a lightweight “harness” that structures the agent’s workflow into clear checkpoints, specifications, validation steps and reversible sync back to the project.

Why it matters – Modern LLMs can now modify files, run tools and verify results. The bottleneck shifts from writing code to controlling that activity so that work stays observable, recoverable and auditable. SDD‑RIPER provides that control without imposing heavyweight, spec‑driven processes.

---

Core Concepts

Concept	Role
Human owns	Goals, boundaries, permissions, checkpoints, acceptance criteria, evidence of completion
Agent owns	Exploration, implementation, iteration, tool use
Project preserves	Specs, context indexes, validation evidence, recovery state, reusable knowledge

The framework is built around four “skills” (small, self‑contained scripts or prompts) that an LLM can invoke:

1. sdd‑riper‑one‑light – The default, low‑friction harness for daily coding, documentation edits, bug‑fixes, or ordinary refactors. It enforces the same core rules (restating the task, requiring a spec, waiting for approval, proving done) but with minimal gates.
2. sdd‑riper‑one – A stricter version for high‑risk work, multi‑file refactors, audit‑ready traces, or training data collection. Adds richer specifications and denser artifacts.
3. codemap – Generates a code terrain index for unfamiliar or large codebases. The agent produces a feature‑level map of entry points, call chains, risk spots and the smallest slice of code to read next.
4. new‑chat‑ready – Packages a concise “resume pack” for hand‑offs, long pauses, or new chat sessions. It snapshots the repo on a protected branch, sanitises sensitive data, and optionally creates a direct Codex thread.

---

How a Typical Session Works

1. Read context – Agent loads the minimal slice of the repo needed for the current loop.
2. Restate goal & risk – Agent repeats the task, identifies the core goal, outlines a minimal spec and a “Done Contract” (what counts as finished and how to prove it).
3. Checkpoint – Human reviews the restatement, spec and validation plan; must explicitly approve before any file changes.
4. Execute – Agent makes the changes, runs tools/tests, collects evidence.
5. Validate – Evidence (tests, logs, screenshots, manual checks) is compared against the Done Contract.
6. Reverse sync – Verified conclusions are written back into the spec, hand‑off docs, or project memory.

All steps keep the active context small and persist durable state outside the chat, enabling recovery and auditability.

---

Quick‑Start Prompt (for everyday tasks)

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.

The same pattern applies to the other skills, just replace the skill name and adjust the request (e.g., ask codemap to create a code terrain index).

---

Repository Layout (what you need to add to any project)

<repo>/
  AGENTS.md                # project‑specific agent rules
  skills/
    codemap/
    new-chat-ready/
    sdd-riper-one-light/
    sdd-riper-one/

• AGENTS.md can be local to the repo or a system‑wide template (examples/global-agents.md).
• The four skill directories contain the prompts, templates and reference docs needed by the LLM.

---

When to Use Which Skill

Skill	Ideal scenario
sdd‑riper‑one‑light	Daily coding, docs, bug fixes, low‑risk refactors
sdd‑riper‑one	High‑risk, multi‑file changes, audit or training data collection
codemap	First‑time work on a large or legacy codebase
new‑chat‑ready	Handoff to another engineer or LLM, long pause, context reset

---

Safety & Hygiene Rules (from the README)

• No spec → no code – A minimal source of truth must exist before any implementation.
• No approval → no execution – Human must explicitly approve each checkpoint.
• Evidence‑based completion – Tests, logs, screenshots, or manual checks must prove “done”.
• Reverse sync – Proven results are written back into specs or project memory.
• Never commit runtime data, secrets, or private logs – Keep .agent-memory/, .expcap/, .env, etc. in .gitignore.
• Sanitise examples before committing any captured sessions.

---

Who Might Benefit?

• Individual developers who want to harness an LLM for real code changes while retaining control.
• Teams building internal “coding agents” that need audit trails and clear hand‑off protocols.
• Organizations looking to formalise AI‑augmented development workflows without adopting heavyweight spec‑driven pipelines.

---

Getting Started

1. Clone the repo and copy the skills/ folder into your own project.
2. Create an AGENTS.md (or use the provided template) to define project‑specific rules.
3. Run the quick‑start prompt with your LLM (e.g., Claude, Codex, GPT‑4) and follow the checkpoint loop.
4. For unfamiliar code, invoke codemap first; for hand‑offs, invoke new‑chat‑ready.

---

Where to Learn More

• skills/sdd-riper-one-light/README.md – the shortest path to a working harness.
• docs/code-is-cheap.md – the philosophical motivation behind the framework.
• docs/ai-coding-harness-guide.md – detailed how‑to on slicing tasks, validation and recovery.
• docs/general-purpose-agents-are-a-trap.md – why specialised, controlled agents often outperform vague “general‑purpose” bots.

---

Bottom Line

SDD‑RIPER Light is not a new LLM model; it is a control plane that lets existing coding agents act safely and transparently on real repositories. By enforcing explicit goals, specs, approvals and evidence, it shifts the engineering value from raw code generation to orchestrating AI‑driven work.