huisezhiyin

Professional software vendor delivering innovative solutions on the Softono platform. Specialized in both open-source and proprietary software development.

Visit Website

Total Products

Software by huisezhiyin

Open Source

sdd-riper

# SDD-RIPER Light: AI Agent Harness [English](./README.md) | [简体中文](./README.zh-CN.md) > 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`](./skills/sdd-riper-one-light/SKILL.md). Use the heavier [`sdd-riper-one`](./skills/sdd-riper-one/SKILL.md) 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: ```text 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: ```text 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: ```text 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`](./skills/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`](./skills/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`](./skills/codemap/) | Unfamiliar codebases, legacy systems, large modules, cross-repo tasks | Agent-facing code terrain index | | [`new-chat-ready`](./skills/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: ```text <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`](./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 ```text 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`](./examples/global-agents.md) | Important privacy rule: - The project or human defines the knowledge topology. SDD detects `Project Sync Candidate`s 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: ```text 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`](./skills/sdd-riper-one/references/multi-project.md) for the fuller protocol. ## Repository Map | Path | What It Is | | --- | --- | | [`AGENTS.md`](./AGENTS.md) | Project-level agent rules for this repository | | [`examples/global-agents.md`](./examples/global-agents.md) | System-level / personal `AGENTS.md` template | | [`skills/sdd-riper-one-light`](./skills/sdd-riper-one-light/) | Default daily harness | | [`skills/sdd-riper-one`](./skills/sdd-riper-one/) | Strict control protocol | | [`skills/codemap`](./skills/codemap/) | Code terrain indexing skill | | [`skills/new-chat-ready`](./skills/new-chat-ready/) | New-chat handoff and project-memory sync skill | | [`docs/README.md`](./docs/README.md) | Docs map and reading path | | [`docs/archive/`](./docs/archive/) | Historical essays and writing material | | [`protocols/`](./protocols/) | Older protocol references | ## Reading Path If you want the shortest useful path: 1. Read [`skills/sdd-riper-one-light/README.md`](./skills/sdd-riper-one-light/README.md). 2. Try one real task with the quick-start prompt. 3. Use [`codemap`](./skills/codemap/SKILL.md) on unfamiliar code. 4. Read [`skills/sdd-riper-one/README.md`](./skills/sdd-riper-one/README.md) when you need stricter gates. 5. Use [`docs/README.md`](./docs/README.md) only when you want the long-form articles. Recommended long-form docs: | Document | Core Question | | --- | --- | | [Docs map](./docs/README.md) | Which docs are current and which are archived | | [Hands-on AI Coding Harness](./docs/手把手学会%20AI%20Coding%20Harness：从任务拆分到上下文控盘.md) | How to slice tasks, control context, use codemap, validate output, and leave recoverable state | | [Team adoption guide](./docs/团队落地指南.md) | How to turn personal agent habits into team practice | | [Claude Code source walkthrough](./docs/Claude%20Code%20源码拆解：从启动到多%20Agent%20扩展层.md) | 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.

AI Tools AI Agents

255 Github Stars

Open Source

adaptive-room-harness

# Adaptive Room Harness Adaptive Room Harness is a local-first multi-agent discussion room for coding-agent workflows. It lets a main agent keep ownership of the task while waking a small peer room when work is complex, risky, or ambiguous. The room records the agent discussion, writes durable artifacts, and produces a concise `main_agent_reference.json` packet that the main agent can use as advisory input. The room is runtime-neutral: each participant is backed by the configured adapter, such as `codex-cli`, `claude-cli`, an Anthropic-compatible API, or an OpenAI-compatible API. A requested runtime is authoritative for that wake cycle. If it fails, the room surfaces that failure instead of silently substituting another runtime. This is an early public alpha: useful enough to run locally, intentionally small, and still rough around the edges. ## Keywords coding agents, agentic coding, multi-agent collaboration, local-first AI tools, agent room, peer review, advisory planning, developer workflow automation, Codex CLI. ## Why This Exists Most coding-agent work should stay simple: one main agent, one workspace, one clear owner. But harder tasks often benefit from a second pass: independent drafting, review, revision, risk checks, and a durable summary that can be inspected later. Adaptive Room Harness is the small local harness for that middle ground. It does not try to become a general autonomous multi-agent platform. It gives the main agent a room it can wake when useful, then turns the discussion into artifacts the main agent can actually use. The current alpha ships with Codex CLI, Claude Code CLI, Anthropic-compatible API, and OpenAI-compatible API adapters. Codex-specific commands are convenience wrappers; they are not the room's identity or the only supported runtime. ## What Works Today - `room play --profile <name>` wakes configured participants across supported runtimes. - `room codex-ask` is a Codex-oriented convenience wrapper for local Codex workflows. - Same-capability participants use a deep collaboration chain by default: draft, review, revise, final check. - Simple tasks stay in the main host or agent session. - Complex tasks create a room transcript, design notes, task notes, `main_agent_reference.json`, and a readable `main_agent_brief.md`. - `room serve` opens a read-only local web observer for rooms, discussion turns, and artifacts. - Optional approval commands exist for stricter flows: `accept-plan`, `reject-plan`, and `execution-context`. The main agent remains the writer, decider, and verifier. Other agents provide discussion and reference material. ## Prerequisites - Python 3.11+ - At least one working runtime adapter for live participant calls, such as Codex CLI, Claude Code CLI, an Anthropic-compatible API key, or an OpenAI-compatible API key - Runtime authentication already configured locally for the adapters you choose The test suite uses a fake Codex executable, so development checks do not require live Codex calls. ## Install ```bash git clone <repo-url> cd adaptive-room-harness python3 -m venv .venv .venv/bin/pip install -e ".[dev]" ``` Check the CLI: ```bash .venv/bin/room version ``` ## Quickstart Run the observer UI in one terminal: ```bash .venv/bin/room serve --workspace . --port 8765 ``` Open: ```text http://127.0.0.1:8765 ``` In another terminal, wake a configured room profile: ```bash .venv/bin/room play \ --workspace . \ --task "Review a risky architecture migration with rollback concerns." \ --profile cc-review ``` Or use the Codex-oriented convenience wrapper: ```bash .venv/bin/room codex-ask \ --workspace . \ --task "Design a risky architecture migration with rollback concerns." ``` For a complex task, the room wakes the configured participants, records their discussion, and writes: ```text .room/rooms/<room_id>/ transcript.jsonl artifacts/ main_agent_reference.json main_agent_brief.md design.md tasks.md room_synthesis.json approval_state.json execution_plan.json ``` The normal alpha workflow is: ```text main agent receives task -> room play --profile <name> -> simple task: continue solo -> complex task: wake configured participants -> two-peer profiles can draft/review/revise/final-check -> multi-participant profiles collect independent advisory opinions -> room writes main_agent_reference.json -> main agent reads the reference, decides, implements, verifies ``` In other words: the room advises; the main agent owns the work. ## Core Commands ```bash room ask --workspace <path> --task "<task>" room host-ask --workspace <path> --task "<task>" room codex-ask --workspace <path> --task "<task>" room reference-context --workspace <path> --room <room_id> room serve --workspace <path> --port 8765 room wake --workspace <path> --task "<task>" --goal "<goal>" room play --workspace <path> --task "<task>" --rounds 1 ``` The default collaboration pattern is `draft_review_revise`. Use `--collaboration-pattern parallel_opinion` when you intentionally want independent participant opinions. Use `--collaboration-pattern deliberation` when the room should behave like a real discussion: participants first state positions, then respond to the transcript, then synthesize consensus and disagreement. Profile-driven rooms with `parallel_opinion` or each deliberation phase run participant calls concurrently and record low-authority advisor failures as non-blocking when `can_block = false`. Non-blocking advisors can use a shorter timeout cap so cheap or experimental providers do not drag automatic room wakes. Set `ROOM_ADVISOR_TIMEOUT_SECONDS` for auto/default flows; use about `120` seconds for `quick-deliberation`, because it has three discussion phases, and about `45` seconds for `quick-advisors` fan-out. When it is unset, explicit `room play` calls use the full `--timeout-seconds` value. Manual room operations are also available: ```bash room init --workspace <path> --task "<task>" room triage --workspace <path> --room <room_id> room attach --workspace <path> --room <room_id> --kind agent --id reviewer room say --workspace <path> --room <room_id> --speaker codex_main --content "..." room add-evidence --workspace <path> --room <room_id> --source file:... room decide --workspace <path> --room <room_id> --decision "..." --why "..." room report --workspace <path> --room <room_id> ``` Optional approval flow: ```bash room accept-plan --workspace <path> --room <room_id> room reject-plan --workspace <path> --room <room_id> --reason "..." room execution-context --workspace <path> --room <room_id> ``` ## Observer UI `room serve` is read-only. It watches local room files and shows: - room list and status - recent discussion turns - `main_agent_reference.json` - `main_agent_brief.md` - design and task artifacts - synthesis, approval state, execution plan, and reports The first version uses browser polling. It does not stream partial tokens yet; completed agent turns appear as the room files update. ## Codex CLI Notes The Codex adapter runs `codex exec` for each participant. By default it uses `gpt-5.4` for Codex CLI compatibility. Override the model with: ```bash ROOM_CODEX_MODEL=<model> room codex-ask --workspace . --task "..." ``` or: ```bash room codex-ask --workspace . --task "..." --model <model> ``` ## Claude Code And DeepSeek Runtimes The Claude Code adapter runs `claude -p` in non-interactive mode: ```bash room play \ --workspace . \ --task "Review this architecture plan." \ --runtime claude-cli \ --model sonnet \ --collaboration-pattern parallel_opinion ``` Claude Code keeps its own authentication outside the repository. To route Claude Code through DeepSeek's Anthropic-compatible API, set `ROOM_CLAUDE_PROVIDER=deepseek` in `.env`. The harness maps that to the Claude Code variables documented by DeepSeek: `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL`, and `CLAUDE_CODE_SUBAGENT_MODEL`. The adapter also passes those values through a temporary `--settings` file so project-local DeepSeek configuration can override a stale global Claude Code gateway without putting the API key on the command line. Use `ROOM_CLAUDE_DEEPSEEK_MODEL=deepseek-v4-flash` for the Claude Code path when you want fast, cheap advisory turns, while keeping `ROOM_ANTHROPIC_MODEL=deepseek-v4-pro[1m]` for direct Anthropic-compatible API participants. For project-local credentials, copy `.env.example` to `.env`. The CLI loads `<workspace>/.env` before waking participants, and `.env` is ignored by Git: ```bash cp .env.example .env $EDITOR .env ``` The alpha can also wake participants through an Anthropic-compatible Messages API. The default endpoint is DeepSeek: ```bash export DEEPSEEK_API_KEY=<your-key> room play \ --workspace . \ --task "Review this architecture plan." \ --runtime anthropic-api \ --model deepseek-v4-pro \ --collaboration-pattern parallel_opinion ``` The API key is read from the environment and is not written to room artifacts. Override the endpoint or key variable when using another Anthropic-compatible provider: ```bash room play \ --runtime anthropic-api \ --anthropic-base-url https://api.deepseek.com/anthropic \ --anthropic-api-key-env DEEPSEEK_API_KEY \ --model deepseek-v4-pro \ --task "..." ``` The alpha also supports OpenAI-compatible Chat Completions providers. Qwen / DashScope works well as a lightweight advisory participant when you only have an API key: ```bash export DASHSCOPE_API_KEY=<your-qwen-or-dashscope-key> room play \ --workspace . \ --task "Codex plans; Qwen reviews product value and alternatives." \ --profile qwen-advisory ``` By default, the OpenAI-compatible runtime uses `ROOM_OPENAI_BASE_URL` or `https://dashscope.aliyuncs.com/compatible-mode/v1`, model `qwen-plus`, and key env `DASHSCOPE_API_KEY`. It also accepts `QWEN_API_KEY` when that is the key you have set. Use `ROOM_OPENAI_API_KEY_ENV` if you store the key under a different name. The Qwen participant is advisory-only in the bundled profile; it does not read or write files. For a custom OpenAI-compatible Qwen endpoint, put the provider-specific values in `.env`: ```bash QWEN_API_KEY=<your-key> ROOM_OPENAI_API_KEY_ENV=QWEN_API_KEY ROOM_OPENAI_BASE_URL=https://your-provider.example/api/openai/v1 ROOM_OPENAI_MODEL=your-qwen-model-name ``` `room play` can mix runtimes per participant: ```bash room play \ --workspace . \ --task "Codex drafts the implementation plan; DeepSeek reviews product value." \ --collaboration-pattern parallel_opinion \ --agent-a codex_planner \ --agent-a-runtime codex-cli \ --agent-a-model gpt-5.4 \ --agent-b deepseek_reviewer \ --agent-b-runtime anthropic-api \ --agent-b-model deepseek-v4-pro ``` Participant-specific flags override the default `--runtime` and `--model` values for that speaker. This first alpha slice keeps the mixed-runtime surface intentionally small: `--agent-a-runtime`, `--agent-b-runtime`, `--agent-a-model`, `--agent-b-model`, `--agent-a-bin`, `--agent-b-bin`, `--agent-a-api-base-url`, and `--agent-b-api-base-url`. For repeated use, prefer a profile in `.room-profiles.toml`: ```bash room play \ --workspace . \ --task "Discuss the next implementation slice." \ --profile advisory-mixed ``` Profiles define participant runtime, model, role, capability scores, authority, and advisory weight. Profiles are configuration, not fallback chains: each participant must run through its declared runtime, or the wake cycle should fail clearly. The default profiles map to a simple advisory loop: - `advisory-mixed`: before work, for complex design or unclear tasks. - `qwen-advisory`: before work, when you want Codex grounded in the codebase and Qwen as a cheap OpenAI-compatible advisor. - `quick-advisors`: before work or during review, when the current main Codex session already owns codebase grounding and you only want low-latency DS + Qwen second opinions. - `quick-deliberation`: when the value should come from DS + Qwen responding to each other rather than merely returning two independent opinions. - `advisory-trio`: before work, when you want Codex as primary planner, DeepSeek as secondary cheap critic, and Qwen as a lower-weight OpenAI-compatible advisor. - `debug-recovery`: during work, when the main agent is stuck, tests fail repeatedly, or the bug is unclear. - `final-review`: after work, before commit, push, release, or broad use; Claude Code performs the final review and DeepSeek provides cheap outsider risk, documentation, and usability advice. - `cc-review`: when a stronger Claude Code review pass is useful; with `ROOM_CLAUDE_PROVIDER=deepseek`, Claude Code is routed to DeepSeek while the second participant uses the direct DeepSeek API on `deepseek-v4-flash` for a faster cheap-advisor pass. ## Development ```bash .venv/bin/python -m ruff check src tests .venv/bin/python -m pytest -q ``` The tests use a fake Codex executable, so they do not require network access or a real Codex CLI session. ## Non-Goals - Not a general multi-agent platform. - Not an autonomous infinite loop. - Not a system where multiple agents write to the same workspace by default. - Not a replacement for the main agent's judgment. ## Docs - [Quick Demo](docs/QUICK_DEMO.md) - [Technical Architecture](docs/TECHNICAL_ARCHITECTURE.md) - [Product Direction](docs/PRODUCT_DIRECTION.md) - [Usable Stage Roadmap](docs/USABLE_STAGE_ROADMAP.md) - [Idea Doc v2](docs/IDEA_DOC_V2.md) ## License MIT

AI Agents Low-Code & No-Code Dev

12 Github Stars