{"id":"d36d6ee4-391a-4017-95c4-e09a3f48774f","slug":"ds-spec-loop","kind":"skill","name":"ds-spec-loop","summary":"Portable Agent Skill for repository-native Spec programming, informed by public DeepSeek Harness engineering patterns.","owner":"songyang0603","repoUrl":"https://github.com/songyang0603/ds-spec-loop","license":"MIT","licenseTier":"permissive","trust":"community","stars":39,"match":null,"fewStars":false,"format":"skill","createdAt":null,"addedAt":"2026-10-14T06:05:27.774Z","logoUrl":"https://avatars.githubusercontent.com/u/93965787?u=cc91710fffef1fd050d3d6e75b8a1834841462ae&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools"],"tags":["ai-coding","claude-code","codex","deepseek-harness","developer-tools","dsh-plugin","github-copilot","spec-driven-development"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-14T06:50:15.182Z","sample":false,"url":"https://conduits.dev/tools/ds-spec-loop","language":"","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# ds-spec-loop\n\n**English** | [简体中文](README.zh-CN.md)\n\n> A general Spec programming Skill for coding agents.\n\n`ds-spec-loop` helps coding agents keep requirements, decisions, implementation, tests, and documentation consistent while building features, fixing bugs, changing architecture or interfaces, improving tests and development processes, or removing code.\n\nHere, Spec programming does not mean writing a long plan before coding. It means using the repository itself as the source of truth: instructions describe constraints, current documentation describes the system as it exists, decision records preserve why choices were made, and code plus tests provide executable evidence.\n\n## Method origin\n\nThis independent community project was developed from analysis of Spec and decision practices visible in the public [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) repository and Git history.\n\nThe runtime Skill uses general terms and does not require that repository's directories, framework, or test commands. This project is not official, is not affiliated with or endorsed by DeepSeek, and does not redistribute DeepSeek Harness source code. See [NOTICE](NOTICE).\n\n## 🚀 Install and use\n\n### Community Skills CLI\n\nThe community-maintained [`skills`](https://skills.sh/) installer requires Node.js and lets you choose the target coding agent and installation scope:\n\n```bash\nnpx skills add songyang0603/ds-spec-loop\n```\n\n### GitHub CLI\n\n```bash\ngh skill install songyang0603/ds-spec-loop ds-spec-loop --agent codex --scope user\n```\n\nReplace `codex` with `claude-code` or `github-copilot` when appropriate.\n\n### Manual installation\n\nClone or download this repository, then copy the entire `skills/ds-spec-loop` directory:\n\n| Host | User scope | Repository scope |\n|---|---|---|\n| Codex | `~/.agents/skills/ds-spec-loop` | `.agents/skills/ds-spec-loop` |\n| Claude Code | `~/.claude/skills/ds-spec-loop` | `.claude/skills/ds-spec-loop` |\n| GitHub Copilot | `~/.copilot/skills/ds-spec-loop` or `~/.agents/skills/ds-spec-loop` | `.github/skills/ds-spec-loop`, `.claude/skills/ds-spec-loop`, or `.agents/skills/ds-spec-loop` |\n\nSee the current official documentation for [Codex](https://learn.chatgpt.com/docs/build-skills), [Claude Code](https://code.claude.com/docs/en/skills), and [GitHub Copilot](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills).\n\n### Invoke the Skill\n\n| Host | Command |\n|---|---|\n| Codex | `$ds-spec-loop` |\n| Claude Code | `/ds-spec-loop` |\n| GitHub Copilot CLI | `/ds-spec-loop` |\n\nExamples below use Codex syntax. Replace `$ds-spec-loop` with `/ds-spec-loop` in Claude Code or GitHub Copilot CLI.\n\nImplement a change:\n\n```text\nUse $ds-spec-loop to implement this change. Reuse the repository's existing\ndecision, documentation, test, and CI conventions, and keep them consistent.\n```\n\nWrite a proposal without implementing it:\n\n```text\nUse $ds-spec-loop to investigate this change and write its proposal.\nDo not implement it. Compare real alternatives and define direct checks.\n```\n\nReview without modifying:\n\n```text\nUse $ds-spec-loop to check whether proposals, decisions, code, tests,\ngenerated files, and current documentation agree. Do not modify files.\n```\n\nThe requested task boundary remains binding: review-only stays read-only, and proposal-only does not silently become implementation.\n\n## ✨ What it does\n\n| Feature | What the agent does |\n|---|---|\n| Understand existing conventions | Reads applicable instructions, proposals, decisions, current docs, source, tests, generated files, CI, and relevant Git history |\n| Reuse one decision record | Updates the record already responsible for the change; creates a narrowly scoped record when none exists |\n| Write testable acceptance criteria | States what should be observable, where it can fail, and which direct check can disprove completion |\n| Trace the affected integration path | Checks the layers that actually connect the change to its caller, runtime, persistence, or visible result |\n| Handle changed requirements | Revises an unfinished proposal in place; creates a replacement record only after a delivered decision is reversed |\n| Keep the repository consistent | Updates affected decisions, code, tests, generated files, public contracts, and current docs in the same pull request or linked changes |\n| Remove code completely | Checks real consumers and removes obsolete code, registration, exports, config, tests, docs, and compatibility behavior |\n\nThe core rule is:\n\n> Every non-mechanical change creates or updates one decision record responsible for that change.\n\nA spelling correction, formatting-only edit, or other local mechanical change is exempt only when it changes no behavior, contract, structure, process, test strategy, stored-data format, or rationale.\n\n## 🧭 How it works\n\nThe Skill does not impose one directory layout. It first finds which existing files already perform each job.\n\n| Responsibility | Common repository forms |\n|---|---|\n| Working rules | `AGENTS.md`, `CLAUDE.md`, Copilot instructions |\n| Unfinished decision | Spec, RFC, proposal, design doc, draft ADR |\n| Current decision | ADR, decision record, implemented design, shipped RFC |\n| Current system description | architecture docs, README, API or package docs |\n| Focused checks | `pytest`, `cargo test`, `go test`, `pnpm test`, real CLI/UI/API checks |\n| Full checks | GitHub Actions, Makefile, pre-commit, repository scripts |\n\nA Python project is not told to run `pnpm test`. A repository that already uses ADRs is not told to create another decision directory.\n\nIf no equivalent convention exists, the Skill proposes only a small fallback: repository instructions, current architecture documentation, and a directory such as `docs/decisions/`. It does not create class folders, archives, indexes, validators, translations, or checksum files without a demonstrated need.\n\n### Decision lifecycle\n\nThe method preserves three meanings without forcing particular status words:\n\n| Stage | Meaning |\n|---|---|\n| Working | not delivered yet, partly implemented, or still changing |\n| Current | implementation, direct checks, and current documentation agree |\n| Declined | considered but not adopted; retained only while the reason remains useful |\n\nAn `accepted` ADR does not always mean the code has shipped. A decision becomes Current only when implementation, direct checks, and current documentation agree.\n\nReplacement is a relationship between decisions:\n\n- change an unfinished proposal directly;\n- create a new cross-linked record when a delivered decision is reversed;\n- keep both decisions Current when only part of the earlier decision was replaced;\n- consolidate an old decision only after the new record preserves its unique rationale, consequences, verification requirements, and reintroduction conditions.\n\n## Repository contents\n\n```text\nskills/ds-spec-loop/\n├── SKILL.md\n├── agents/openai.yaml\n└── references/\n    ├── acceptance-and-evidence.md\n    ├── adoption.md\n    ├── decision-classes.md\n    ├── decision-record-lifecycle.md\n    ├── documentation-discipline.md\n    ├── requirement-change.md\n    ├── simplification.md\n    ├── system-of-authority.md\n    └── templates.md\n```\n\n`SKILL.md` contains the portable core. References load only when the task needs them. `agents/openai.yaml` contains optional Codex-specific metadata, including the default invocation prompt.\n\n## 📝 Update log\n\n### v0.2 — 2026-08-17\n\nFurther generalized the Spec programming loop so it can be used in projects with different conventions. The Skill reuses each project's existing Specs, RFCs, ADRs, documentation, testing, and CI conventions, while strengthening rules for mid-development requirement changes, decision ownership, lifecycle transitions, partial replacement, and verification evidence. This update has passed cross-language scenario tests, structural validation, and independent review.\n\n### v0.1 — 2026-08-15\n\nPublished the first open-source version, based on Spec programming patterns observed in the public DeepSeek Harness repository. It included the reusable Skill, English and Chinese documentation, and installation instructions for Codex, Claude Code, and GitHub Copilot.\n\n## Contributing\n\nContributions are welcome. If you find a problem or have a suggestion, please open an Issue with enough context to understand or reproduce it; documentation improvements, usage examples, and focused pull requests are also appreciated.\n\nSee [LICENSE](LICENSE) for the project license.\n"}