Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,10 @@ the risk, and an honest `COMPLETE` / `PARTIAL` / `BLOCKED` report.
coherent slice, then verify. A failure is sorted as an implementation defect, a bad
assumption, an environment problem, or an ambiguous contract, and the agent loops back
to the matching step.
- **Delegation, with one writer.** Fan out only for independent, read-only slices; brief each
worker with an objective, scope, output contract, budget, and timeout; treat returns as
evidence, not verdicts; report failed or unrun slices as gaps; review independently and
keep synthesis in the parent.
- **Evidence scaled to risk.** Pre-fix evidence, recorded commands, and independent review
scale with the mode. A skipped or unavailable check never counts as a pass.
- **Design rules.** Seven rule groups for the code the agent writes (ownership, boundaries,
Expand Down
48 changes: 35 additions & 13 deletions SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ deterministic reproducer or directly observed failure. Never fabricate a red run

**Implement.** Fix the invariant at the smallest correct shared layer. Infer architecture
from the code and reuse its conventions and helpers; do not impose patterns because they
are familiar, and apply the design rules in section 3 to the code you add. Wire every
are familiar, and apply the design rules in section 4 to the code you add. Wire every
required path: unused helpers and fake success paths are not
delivery. Validate untrusted input at boundaries and make failure explicit; never swallow
errors, fabricate data, or weaken authorization. Preserve compatibility unless the change
Expand All @@ -79,15 +79,37 @@ cannot establish intended behavior, keep both and report the ambiguity.
**Review.** Read the final diff and status as a domain engineer: boundaries, failure paths,
security, concurrency, compatibility, resources. Remove debug artifacts, dead code, and
unrelated formatting. For High-risk work, request an independent read-only review scoped to
correctness when available, without blocking required work; its absence is a reported
limitation, not by itself a reason for `PARTIAL`. Self-review, including of a child agent's
work, is not independent. Rerun affected checks after the last relevant edit; an old green
run does not verify a new tree. When available, load
[quality gates](references/quality-gates.md) only for affected domains, and for Substantial
work and above answer its review questions against the final diff; if a reference is
missing, use this protocol and note it only when it materially reduces verification.

## 3. Design
correctness per section 3 when available, without blocking required work; its absence is a
reported limitation, not by itself a reason for `PARTIAL`. Rerun affected checks after the
last relevant edit; an old green run does not verify a new tree. When available, load
[quality gates](references/quality-gates.md) for affected domains; for Substantial work and
above also answer its review questions against the final diff; if a reference is missing,
use this protocol and note it only when it materially reduces verification.

## 3. Delegation

Fan out only for independent, read-only slices whose value justifies roughly an order of
magnitude more tokens than one agent. The parent is the sole code writer; never dispatch
parallel writers. Split research by sub-question, not by source.

- **Brief before dispatch.** Give each worker an objective, output contract, owned scope,
sources or tools, budget, and stop condition; dispatch after acceptance criteria are fixed.
- **Return evidence, not verdicts.** Require `file:line` or a source URL with date, the
command and observed output, and what was not checked. "Done" is a claim, not a pass.
- **Keep context clean.** Workers write detail to a scratch file outside tracked sources and
return a short summary plus its path, not a transcript; or return concise evidence directly.
- **Bound the fan-out.** Dispatch 2–4 workers with distinct slices, per-worker timeouts,
and a total token/time budget; stop dispatch and cancel active workers on exhaustion.
- **Fail closed.** Pin revision and working-tree state; discard returns if either changes.
A worker that times out, fails, or returns partial or malformed output is unverified;
retry once only for transient host/network errors. Report failed or unrun slices as gaps.
- **Synthesize centrally.** Deduplicate, reconcile conflicting observations by evidence
strength (reproduced > read > claimed); contracts govern intended behavior. Preserve
dissent and keep the decision in the parent.
- **Review independently.** A reviewer gets the diff, acceptance criteria, and contracts,
not the author's reasoning; an author, or a parent reviewing its child, is not independent.

## 4. Design

Rules for the code you write, applied within the repository's own structure. The test for
every addition: am I adding code, or a new place future readers must understand?
Expand Down Expand Up @@ -137,7 +159,7 @@ When rules conflict: correctness → explicit invariants → clear ownership →
effects → bounded resources → failure safety → locality → replaceability → extensibility →
optimization.

## 4. Safety
## 5. Safety

- Stay inside the workspace and task scope. Never print environment values, credentials,
or secret files; check a variable's presence, not its value.
Expand All @@ -148,7 +170,7 @@ optimization.
- Commit, push, open a PR, merge, and deploy are separate permissions. When committing,
stage exact paths and inspect the staged diff.

## 5. Findings and evidence
## 6. Findings and evidence

Record material defects you discover as you go. Interrupt only when one changes scope,
safety, strategy, or completion status; otherwise list it in the report with a next action.
Expand All @@ -160,7 +182,7 @@ Keep enough evidence to reproduce each material claim. For performance, migratio
security, or environment-dependent results, record exact commands, environment, and
revision. Report only results you observed.

## 6. Report
## 7. Report

| Status | Meaning |
| --- | --- |
Expand Down
3 changes: 3 additions & 0 deletions references/quality-gates.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,3 +47,6 @@ For Substantial work and above, answer each against the final diff:
9. Do tests protect behavior rather than implementation details?
10. Is the complexity justified by a real requirement, and would another engineer know
where to modify this behavior six months from now?
11. If work was delegated, does the report name each slice's scope, revision, evidence,
read/not-read coverage, status, and which claims remain unverified, and does an
in-scope gap block `COMPLETE`?
4 changes: 4 additions & 0 deletions references/report-template.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,10 @@ Findings:
Operations (High-risk only):
- Migration; rollout; rollback; observability

Delegation (if used):
- Slice -> worker -> revision (clean/dirty) -> evidence path -> read/not read
Status: DONE/FAILED/TIMED_OUT/UNRUN; claims: verified/unverified

Limits:
- Unknowns, unavailable checks or reviews, pre-existing failures, remaining work
```
Expand Down
Loading