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
6 changes: 5 additions & 1 deletion .claude/skills/dogfood/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,11 @@ Two mechanics that are easy to get wrong and quietly invalidate the run:
- **Isolate the other host before asking it to review.** Pointing only its own home at a scratch directory is
not enough; it also reads a host-agnostic user skill directory, so it will load the maintainer's personal
skills and the installed package it is supposed to be judging. Point the operating system home there as
well, copy in only the credentials, and check the session header before trusting the output.
well, and check the session header before trusting the output. Never copy credential files into that scratch
home. Authenticate it by the first option the host supports: a dedicated test identity; a narrowly scoped,
short-lived token; an authenticated session the host establishes without duplicating persistent credential
files; a controlled mount or reference to the one minimum credential. Where the host offers none of these,
say so and have a person authenticate the isolated run by hand rather than automating a copy.

A cross-host review round converges when it is told what earlier rounds settled and what was refused, and told
not to raise those again. Without that it re-proposes them, and the rounds do not end.
Expand Down
18 changes: 8 additions & 10 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,29 +4,29 @@ These are contributor rules for developing SkipHow. They do not describe how Ski

## Product direction

Treat the README as the product brief. SkipHow is a small, provider-independent instruction layer for strong agents, not a workflow engine. Its product shape is one plain-language owner skill backed by a thin autonomous kernel and a library of focused internal methods. Preserve autonomous technical judgment, effort proportional to the request, and the least process that reliably reaches a verified result.
Treat the README as the product brief. SkipHow is a small, provider-independent instruction layer for strong agents, not a workflow engine. Its product shape is one plain-language owner skill backed by an always-loaded kernel and eight optional modules. Preserve autonomous technical judgment, effort proportional to the request, and the least process that reliably reaches a verified result.

Keep universal runtime policy in the owner kernel as outcomes, authority boundaries, and non-negotiable invariants. Put reusable task discipline in referenced method files and load only what materially helps. Depth in a method is not the cost to control; whether it reaches the agent is. The 1.8.0 field audit measured references loading three times against roughly twelve applicable triggers, and the rules in the unopened files governed nothing. Judge a method by whether its trigger is decidable from outside the file and whether the guidance changes what a capable agent would otherwise do, not by its word count. Methods are not routes, commands, roles, or an owner-operated chain. Leave sequencing, tools, decomposition, and implementation to the agent unless evidence shows that judgment is unreliable. Audit briefs, checklists, past transcripts, and one-off preferences are evidence for the question they examine; they are not standing product requirements.
Keep universal runtime policy in the kernel as outcomes, authority boundaries, and non-negotiable invariants. Everything else is optional guidance, consulted when the work makes it worth its cost. A module exists only where it covers one distinct failure domain, gives a reason to consult it recognizable without opening it, holds no critical invariant absent from the kernel, duplicates no rule another module owns, and repays the permanent discovery and maintenance cost of a separate file. Those criteria are drawn from the 1.8.0 field audit, which measured references loading three times against roughly twelve applicable triggers while the rules in the unopened files governed nothing. Modules are not routes, commands, roles, stages, or an owner-operated chain. Leave sequencing, tools, decomposition, and implementation to the agent unless evidence shows that judgment is unreliable. Audit briefs, checklists, past transcripts, and one-off preferences are evidence for the question they examine; they are not standing product requirements.

## Changing the runtime contract

Change the shipped instructions to fix an observed defect or protect a high-risk boundary, not to describe an ideal execution in full. One run can prove that wording is missing, ambiguous, or contradictory. It cannot prove that agents generally need a new procedure.

Prefer deleting a contradiction, clarifying intent, or moving a discipline into a focused method over adding universal policy. Add a mandatory step, role, gate, dependency, or persistent state only when evidence shows that capable agents cannot reliably infer the needed behavior and the benefit justifies its ongoing cost. Remove obsolete or redundant text when a rule changes. Review added policy for lost autonomy, extra turns, and provider assumptions as seriously as any functional regression.
Deletion comes first. Prefer removing a contradiction, clarifying intent, or moving a discipline into an existing module over adding universal policy, and treat a rule never shown to change what a capable agent does as a candidate for removal rather than another rewording. Where a rule has more than one home, the copies go. Three rules removed in 3.0.0 had been carried as `UNVERIFIED` for their whole lives. Add a mandatory step, role, gate, dependency, or persistent state only when evidence shows that capable agents cannot reliably infer the needed behavior and the benefit justifies its ongoing cost. Review added policy for lost autonomy, extra turns, and provider assumptions as seriously as any functional regression.

## Reviewing a change to the instructions

This is for the contributor acting on a review of their own change, not for the reviewer producing one. The shipped contract is prose, so a reviewer can always propose a different wording, and a review that is allowed to do so never ends. Treat what comes back as evidence to weigh, not a list to work through, and confirm every finding against the file yourself before acting on it. A reviewer that cannot point at the defect is reporting taste.

A finding qualifies when it names one of these: a factual error, including a number, a claim about what a file says, or a claim about how a host behaves; a contradiction with another shipped sentence or with `docs/decisions.md`; a trigger that cannot be decided without opening the file it guards; a claim presented as demonstrated that no receipt supports; a mandatory step, gate, or persistent state added without the evidence this file requires for one; or an authority, boundary, or portability error. Fix what qualifies, within the scope the change already carries, and record what it was.
A finding qualifies when it names one of these: a factual error, including a number, a claim about what a file says, or a claim about how a host behaves; a contradiction with another shipped sentence or with `docs/decisions.md`; a module whose reason to consult it cannot be recognized without opening it; a claim presented as demonstrated that no receipt supports; a mandatory step, gate, or persistent state added without the evidence this file requires for one; or an authority, boundary, or portability error. Fix what qualifies, within the scope the change already carries, and record what it was.

A finding does not qualify when it offers a rephrasing that changes no behavior, prefers a different degree of hedging, or says a sentence could be clearer without naming what breaks if it is not. Say so and leave the sentence alone. Neither the reviewer's confidence nor the length of its list is evidence.

Stop when a round returns only findings that do not qualify. Do not open another round to see whether it finds more, and do not re-review wording that survived a round unchanged. Improving instructions has no completion condition of its own; the observed defect is the completion condition.

## Evidence

Use current primary documentation for host behavior, plugin formats, and security guidance. Read `docs/decisions.md` before changing the product contract so old alternatives are not reopened without new evidence. The immutable 2.0.1 links in that file preserve the full earlier ADR and research archive.
Use current primary documentation for host behavior, plugin formats, and security guidance. Read `docs/decisions.md` before changing the product contract so old alternatives are not reopened without new evidence; it links the immutable archive of the earlier ADRs and research.

Model behavior is proven only by deliberate receipts from real runs made with the host's own permission and budget controls. A receipt worth keeping holds everything fixed but the package: a throwaway fixture repository, a session carrying only the candidate package and the host's own built-ins, and the same prompt on both sides of the change. Isolate Codex by pointing both its own home and the operating system's home directory at a scratch location, because it also reads a host-agnostic user skill directory that its own home setting does not cover, and Claude by disabling every setting source and passing the package as a session plugin, which leaves authentication alone. Prove the isolation with a control run, and confirm it in the session transcript rather than by asking the model what it can see, before trusting anything built on it. Disabling the setting sources keeps the maintainer's own instruction files out of a session's context but does not stop the session from reading them with a shell command, so search each transcript for those files as well as for the package. Run the failing case before the change as well as after it, because a run that only shows the new behavior proves the wording is compatible with it, not that it produced it.

Expand All @@ -36,19 +36,17 @@ Summarize claims and durable source links in `docs/evidence.md`; do not add one

## Checks

Run focused tests through `python scripts/check.py --pytest <pytest-arguments>`. Before completion, run `python scripts/check.py` and `git diff --check`. For packaging changes, also run `python scripts/check_hosts.py` and report an unavailable host as `UNVERIFIED`. `scripts/check.py` validates the single owner skill, all reachable internal methods and resources, the continuity hook, aligned versions, and portability boundaries such as personal paths and versioned model IDs. Change the check and `docs/decisions.md` together when those invariants change; do not pin a method roster, role set, or prose budget.
Install the pinned dependencies with `python -m pip install -r requirements-dev.txt`; the checks install nothing and stop on an interpreter that misses a pin. Run focused tests through `python scripts/check.py --pytest <pytest-arguments>`. Before completion, run `python scripts/check.py` and `git diff --check`. For packaging changes, also run `python scripts/check_hosts.py` and report an unavailable host as `UNVERIFIED`. `scripts/check.py` validates the single owner skill, its reachable modules and resources, the continuity hook, aligned versions, and portability boundaries such as personal paths and versioned model IDs. Change the check and `docs/decisions.md` together when those invariants change. A deterministic check protects a compatibility or safety property, not editorial wording: do not pin a method roster, role set, or prose budget.

## Versioning and releases

Follow Semantic Versioning 2.0.0. The public surface is the runtime contract, not the file layout: owner-visible behavior, authority boundaries, default side effects, the public skill name and description, and any format a project keeps.

Use `PATCH` for repository, documentation, or wording changes that keep the promised behavior. Use `MINOR` for a capability, method, or behavior a project opts into, compatible with projects already installed. Use `MAJOR` for a change to the owner interface, an authority boundary, or a default side effect with no safe path for those projects.
Use `PATCH` for repository, documentation, or wording changes that keep the promised behavior. Use `MINOR` for a capability, module, or behavior a project opts into, compatible with projects already installed. Use `MAJOR` for a change to the owner interface, an authority boundary, or a default side effect with no safe path for those projects.

Decide the number after the change is complete and its compatibility is known. Do not reserve a major version while planning.

Release one coherent, verified change set at a time. Bump `VERSION` and both manifests once, at the start of the branch that will carry the release, and keep that number through the branch; related work accumulates there rather than as a sequence of releases on `main`. Never edit or re-tag a released version.

Claim a material change in model behavior only after receipts. Until then it stays `UNVERIFIED`.
Release one coherent, verified change set at a time. Bump `VERSION` and both manifests once, at the start of the branch that will carry the release, and keep that number through the branch; related work accumulates there rather than as a sequence of releases on `main`. Never edit or re-tag a released version. Claim a material change in model behavior only after receipts.

## Portability and safety

Expand Down
Loading