idd
Impact-driven development protocol: run a code change through the ospec CLI, which derives its obligations and decides when it is done. Trigger: a code change, unless SDD is requested or mode: sdd.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-15
- Stars
- ★ 3
- Forks
- 0
01 前言 Front Matter
- name
- idd
- license
- Apache-2.0
- metadata
- { "author": "manuel-retamozo-garcia", "version": "1.0" }
- description
- Impact-driven development protocol: run a code change through the ospec CLI, which derives its obligations and decides when it is done. Trigger: a code change, unless SDD is requested or mode: sdd.
02 资源文件 6
- 参考文档references/approvals.md2.4 KB
- 参考文档references/architecture.md2.0 KB
- 参考文档references/checks.md1.5 KB
- 参考文档references/memory-loop.md2.9 KB
- 参考文档references/open-facts.md1.9 KB
- 参考文档references/repository.md2.0 KB
03 SKILL.md 正文
When to Use
Load this skill once, when the router sends a code change here (IDD is the default). It is the whole protocol — no phases, proposal or specs first. Questions, explanations and read-only work need no change and do not use it.
Outside a git work tree ospec opens no change (not-a-git-repo,
git-not-found): set up the repository first, as references/repository.md
says. It also covers a change across several services or repositories.
The CLI decides
ospec below means {{ospec-cli}}, run from the project root. Add
--json to read its answer; every change command takes --change <id>. The
CLI owns idd/<change>/state.yaml: never write that file, and never move or
delete anything under idd/ by hand.
- Every command that writes a change prints its next step;
ospec next --change <id>gives it in full when you resume. Itsnext_step.howtells how to proceed: run the command that records the evidence or, forconfigure-checks, propose a check command asreferences/checks.mdsays; without one no IDD change can close. Follow it. - An obligation is satisfied only by evidence the CLI records from a run it
observes (
ospec run,ospec check,ospec review). Saying that tests pass satisfies nothing. - The change is done when
ospec closesucceeds, and only then. Never report it done, verified or archived before that.
Rules
-
Read the code the request touches, then list its open facts: each behavior that neither the request nor the code settles and that a careful engineer would ask about. Look for defaults, invalid or edge input, error versus silent handling, normalization (case, rounding, order), who may do it, and whether existing behavior, output or a published API may change. Do not decide them yourself.
-
Open the change: pick a short kebab-case id from the request and record the intent with
ospec record intent --change <id> --kind <bug|feature|refactor|docs> --summary "<what>" --acceptance "<observable result>"plus the open facts, one--open-fact "<question>"each, or--no-open-facts --basis "<what settles every behavior>"when there are none. Afeaturecovers the categories of the templateospec nextprints, asreferences/open-facts.mdsays. Assumptions:ospec record assumption --text(close lists them). With cross-session memory tools, recall prior decisions with thememory_queryit returns, asreferences/memory-loop.mdsays. Openopen-facts: then ask all at once before editing anything. -
If the request is materially ambiguous (no acceptance can be stated), record
ospec record intent --change <id> --ambiguous --request "<request>", ask the user the questionnextreturns, and resolve it with therecord intentthatnextprints, without--ambiguous, filling in their words and the open-facts declaration of rule 2. -
Declare the plan before editing, on
record intentor later withospec signals --change <id>:--path <file>once per file you expect to touch; add--work-units <n>when the work splits into several units,--decision "<text>"per design decision, and--operation <op>for a destructive or irreversible operation. Withdocs/architecture/, declare the ADRs and quality scenarios the change bears on (--adr <id>,--quality <id>) asreferences/architecture.mdsays. If the plan overstated a signal, retract it withospec record retract --change <id> --signal <id> --reason "<why>"; the CLI refuses while the diff confirms it. When itshowoffers the user's answer, ask the user; never answer for them. -
Loop: do what the
next_stepof the last command says, repeat.resolve-gatecomes first while any gate is open: ask itspending_decision(see Gates) and build nothing it decides until the user answers. Work the obligations in the ordernextgives them:repro-test: write the reproduction test first and run it withospec run --obligation repro-test --command "<test>"while it fails; fix the code; run the same command again so it passes.tdd-red-green: the same red-then-green pair, per unit (--unit <name>).contract-spec-and-test: update the contract document and its test.migration-compat-and-test: run the migration test with--plan "<compatibility or rollback plan>".adr-impact-declaration:ospec record impactfor each declared ADR or scenario, and their fitness checks, asreferences/architecture.mdsays.trust-review:ospec review start, hand the whole returned request to the read-onlyreview-trustreviewer, and pass its JSON unchanged toospec review record --result @<file>. Fix what it blocks on, runospec review correct, hand its request to the read-onlyreview-correctionvalidator and pass its result toospec review validate --result @<file>.checks-pass:ospec checkon the current tree, or a run whose command is the only check; atests 0summary is not evidence.--close, when its command has it, closes the change once ready.living-doc: the CLI writes the Plan and Decisions ofchange.mdfrom--pathand--decision; add only what they miss. A development decision stays there; it is never an ADR.
For the
suggestions,referencesandwarningsofnext, readreferences/architecture.md; tell the user each warning. -
ospec checkrecomputes the signals from the real diff. New obligations can appear: work them like the rest. One leavespendingonly through evidence, or throughospec record withdraw --reasonwhen no active signal derives it. -
Edit text files keeping their encoding and line endings: never rewrite a file through a tool or script that changes them (for example Python
open()withoutencoding=andnewline=). -
When
next_step.actionisclose, runospec close --change <id>. A refusal names what is still pending: settle it and close again.
Build it simply
Make the smallest change that meets the acceptance. Reuse what the code
already has and follow its conventions. Add a layer, abstraction, dependency
or configuration switch only for a need present in this change, and record
the choice with --decision "<text>" when it is not obvious. Leave unrelated code as
it is: report a defect outside the change instead of fixing it in passing.
Tests by risk
Test what would cost something if it broke: business rules, validation, non-trivial transformations and mappers, algorithms, contracts, and their error, edge and regression paths. Code with nothing to get wrong (plain accessors, wiring without logic, declarations) needs no test of its own, and no coverage percentage replaces this choice.
- A test must fail when the behavior is wrong: assert observable results, not the calls the code makes, and check that the red run fails for the reason you expect.
- Unit tests are deterministic and offline: replace databases, external APIs and infrastructure with test doubles at the boundary, and inject time and randomness. An integration test, kept apart, proves the wiring.
- A refactor writes no new test: run
ospec checkbefore the first edit, so a recorded run shows the behavior it preserves was tested.
Gates
Stop for the user at the gates: end your turn with the questions, not a
question tool. A user answer given before a turn ends is kept
user-unverified.
A skipped, empty or default answer is not the user's: end your turn with the
questions and wait.
ambiguous-intent: rule 3.open-facts: rule 2; ask all ofpending_decision.questionsat once.irreversible-operation:--operationin rule 4 or a destructive statement in the diff opens it. Before any other destructive or irreversible step (deleting data, rewriting published history), open it yourself:ospec record gate --change <id> --gate irreversible-operation --open --reason "<operation>".adr-amend-or-contradict: an impactamends,supersedesorcontradictsopens it. Declare every one before asking, since the gate is answered once. For a departure no declared reference covers, open it withospec record gate --change <id> --gate adr-amend-or-contradict --open --reason "<ADR>: <how the change departs from it>". A change that conforms opens nothing.review-limit:ospec checkopens it when the trust reviews run out.checks-changed:ospec checkopens it, running nothing, when the checks or the ceremony settings (strict_tdd,impact,contracts) differ from the change's base. The user's approval of exactly those values answers it.
Resolve each one with ospec record gate --change <id> --gate <id> --resolve --answer "<their words>" --source user,
or user-unverified for a relayed answer. The CLI cannot verify who answered:
read references/approvals.md first. Only an explicit answer from the user
resolves a gate. Outside these gates, follow the code and the evidence
without asking.
Delivery
ospec close archives the change under idd/archive/, adds its entry to the
changelog delivery.changelog declares, and leaves the rest of the tree as it
is. Branches, commits, pull requests and releases are the user's decision;
propose the team.delivery_strategy of next, and the delivery it returns
when the work starts and at close: each of its options, why it fits
(reasons) and the rules to follow (how). With a
*-undeclared suggestion, propose that value and its reasons once, and write
it under delivery in idd/config.yaml only after approval, keeping the
rest. Propose the release of close after the merge, ask whether it breaks
compatibility (a major), and cut it only with the user's OK. When they ask, use
work-unit-commits to split commits, branch-pr to open the PR, and
chained-pr when the diff exceeds the review budget. Pitch your replies at
team.mentorship: mentor explains why, expert stays terse.
Memory and roadmap hand-off
After ospec close, and after the delivery the user asks for, follow
references/memory-loop.md: save the records of close when memory tools
exist, and propose the next roadmap item in any case.
04 同仓库更多 Skills
work-unit-commits
Plan commits as reviewable work units. Trigger: implementation, commit splitting, chained PRs, or keeping tests and docs with code.
stack-webmcp
Trigger: WebMCP, document.modelContext, web tools, AI browser agent. Web Model Context Protocol client-side tool standard.
stack-vite
Vite frontend build tool — configuration, plugins, asset loading
stack-starlight
Astro Starlight documentation framework — setup, sidebar navigation, frontmatter, built-in components, asides, theming, i18n, search
stack-sqlserver
Microsoft SQL Server database — indexing, RCSI, set-based operations, SARGable queries, transaction scopes
stack-springboot
Spring Boot architecture patterns — REST API design, layered services, JPA, caching, Spring Security, TDD with MockMvc and Testcontainers, and pre-release verification