diff --git a/.claude/skills/cut-release/SKILL.md b/.claude/skills/cut-release/SKILL.md index 6cced02..aea14e5 100644 --- a/.claude/skills/cut-release/SKILL.md +++ b/.claude/skills/cut-release/SKILL.md @@ -1,6 +1,8 @@ --- name: cut-release description: Cut a release of the three npm packages - propose the version from the Unreleased changelog, bump versions in lockstep, open the release PR, and after it merges create the GitHub release that triggers publishing, only on an explicit yes. Use when asked to release, cut a version, tag or publish. +model: sonnet +effort: low --- # Cut a release diff --git a/.claude/skills/design-feature/SKILL.md b/.claude/skills/design-feature/SKILL.md index ca41fc5..96cfca2 100644 --- a/.claude/skills/design-feature/SKILL.md +++ b/.claude/skills/design-feature/SKILL.md @@ -1,6 +1,9 @@ --- name: design-feature description: Design a feature that is too big for one PR - verify the issue's claims against the code, choose the shape (modules, public API, calls vs events, ports), cut it into ordered slices each with its own acceptance criteria, and after a human approves, file one child issue per slice. Use on issues labelled status:needs-design, or when asked to design, shape or break down a feature. +model: opus +effort: high +context: fork --- # Design a feature diff --git a/.claude/skills/e2e-device/SKILL.md b/.claude/skills/e2e-device/SKILL.md index 89b9b58..d1efeea 100644 --- a/.claude/skills/e2e-device/SKILL.md +++ b/.claude/skills/e2e-device/SKILL.md @@ -1,6 +1,9 @@ --- name: e2e-device description: Build and run a playground app on an iOS simulator or Android emulator, connect it to this repo's Appduct daemon and drive it through the CLI - a smoke pass over the five demo tools plus the calls that prove a specific change works. Use when a PR needs device E2E evidence, when asked to test on a simulator, or when a work-issue orchestrator delegates E2E. +model: sonnet +effort: low +context: fork --- # E2E on a device diff --git a/.claude/skills/file-issue/SKILL.md b/.claude/skills/file-issue/SKILL.md index 4c0d396..6f641bd 100644 --- a/.claude/skills/file-issue/SKILL.md +++ b/.claude/skills/file-issue/SKILL.md @@ -1,6 +1,8 @@ --- name: file-issue description: Turn a request or a discovered bug into a GitHub issue in this repo's format - interview the person until the intent is well defined, check for duplicates, then file. Use when asked to file, open, create or write up an issue, when someone describes a feature they want, or when you hit a bug you should not fix in the current change. +model: sonnet +effort: medium --- # File an issue diff --git a/.claude/skills/implement-issue/SKILL.md b/.claude/skills/implement-issue/SKILL.md index f75d12d..f20bdbd 100644 --- a/.claude/skills/implement-issue/SKILL.md +++ b/.claude/skills/implement-issue/SKILL.md @@ -1,6 +1,9 @@ --- name: implement-issue description: Implement a GitHub issue tests-first - take the acceptance criteria from the issue, write red tests against the public API, commit them, open a draft PR, then implement in checkpoint commits until green, with user-facing docs as one of the criteria. Use when asked to implement, build or fix something tracked as an issue, or when a work-issue orchestrator delegates implementation. +model: sonnet +effort: medium +context: fork --- # Implement an issue diff --git a/.claude/skills/review-memory/SKILL.md b/.claude/skills/review-memory/SKILL.md index a76fea8..5f55792 100644 --- a/.claude/skills/review-memory/SKILL.md +++ b/.claude/skills/review-memory/SKILL.md @@ -1,6 +1,9 @@ --- name: review-memory description: Curate agent memory - read the lessons inbox and the curated lessons file, promote what repeats, prune what is stale, open a memory-only PR and merge it. Use weekly, when the inbox has notes, when a lessons section is over its cap, or when asked to review, consolidate or dream over memory. +model: opus +effort: high +context: fork --- # Review memory diff --git a/.claude/skills/review-pr/SKILL.md b/.claude/skills/review-pr/SKILL.md index e6279c7..a04d9a2 100644 --- a/.claude/skills/review-pr/SKILL.md +++ b/.claude/skills/review-pr/SKILL.md @@ -1,6 +1,9 @@ --- name: review-pr description: Adversarial code review of a PR or branch - hunt for concrete failures, drop low-ROI comments, verify every finding, post inline comments and a verdict through gh. Use when asked to review a PR, a branch or the current diff, or when a work-issue orchestrator delegates review. +model: opus +effort: high +context: fork --- # Review a PR diff --git a/.claude/skills/triage-issue/SKILL.md b/.claude/skills/triage-issue/SKILL.md index 5f86f15..5124308 100644 --- a/.claude/skills/triage-issue/SKILL.md +++ b/.claude/skills/triage-issue/SKILL.md @@ -1,6 +1,9 @@ --- name: triage-issue description: Triage a bug report - rank hypotheses, verify the top three by static analysis, name the root cause with path and line, and propose a module-level fix. Sets the status label. Use when asked to triage, investigate or diagnose a bug, or when a type:bug issue carries status:needs-triage. Features are not triaged; they go through file-issue and design-feature. +model: opus +effort: high +context: fork --- # Triage a bug diff --git a/.claude/skills/work-issue/SKILL.md b/.claude/skills/work-issue/SKILL.md index e4ad181..d0c0b11 100644 --- a/.claude/skills/work-issue/SKILL.md +++ b/.claude/skills/work-issue/SKILL.md @@ -1,17 +1,22 @@ --- name: work-issue -description: Orchestrate one GitHub issue from status:ready to a reviewed, device-tested PR by delegating implementation, review and E2E to subagents and reasoning only over their reports. Use when asked to work, deliver, take or drive an issue end to end. +description: Orchestrate one GitHub issue from status:ready to a reviewed, device-tested PR by delegating implementation, review and E2E to their forked skills and reasoning only over their reports. Use when asked to work, deliver, take or drive an issue end to end. --- # Work an issue You are the chief of staff for one issue. You never write code, run builds or post review -comments yourself. You read the issue, decide the next step, delegate it to a subagent with the -matching skill, and reason over the report that comes back. That keeps your context about the -issue, not about file contents. - -Subagents: in Claude Code use the Agent tool with a fresh general-purpose agent per step. In -OpenCode use the task tool. Either way the prompt is short and names the skill to load. +comments yourself. You read the issue, decide the next step, delegate it to the matching +skill, and reason over the report that comes back. That keeps your context about the issue, +not about file contents. + +Delegating: in Claude Code, invoke the stage's skill with the Skill tool and pass the task as +its arguments. Each stage skill is forked (`context: fork` in `AGENTS.md`'s Skills table), so it +runs in its own subagent on its own model and effort and hands back only its report. Never +start an agent that then loads the skill, and never pass a model: either one overrides the +skill's frontmatter. In +OpenCode, use the task tool with a prompt that names the skill to load; there every stage runs +on the session model. Read the `work-issue` section of `.agents/memory/LESSONS.md` before starting, plus General. @@ -35,8 +40,11 @@ phase to resume at. ## 2. Delegate, in order -Each prompt has the same shape: the issue number, the branch, the one thing to do, "load the -`` skill and follow it", and "end with that skill's report and nothing else". +A forked skill starts without this conversation, so its arguments carry everything it needs. +Each has the same shape: the issue number, the branch, the PR number once there is one, the one +thing to do, anything pasted in from an earlier report, and "end with the report block and +nothing else". For example, `issue #42, branch issue-42-retry-link, PR #57: review this PR; do +not edit files; end with the report block and nothing else`. 1. **Implement.** `implement-issue`. Expect the draft PR and a criteria count. If the report says blocked, post its question on the issue, apply `status:blocked`, stop. @@ -76,7 +84,9 @@ Implement: done (5/5 green) Review: round 2, approve E2E: pass (iOS) Ready: y Each skill ends with a fixed block (`implement-issue`, `review-pr`, `e2e-device`, `triage-issue`, `design-feature`). Reason only over those and the issue. If a report is -missing the block or adds narration, ask that subagent for the block, do not guess from prose. +missing the block or adds narration, do not guess from prose: invoke the skill again with the +same arguments plus "the last run ended without its report block; report on the work already +done". ## Your own report diff --git a/AGENTS.md b/AGENTS.md index 73066ee..efe24a6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -69,19 +69,22 @@ no restating the question. Commit subjects: conventional prefix, imperative, und ## Skills Load the skill before starting the matching task. They live in `.claude/skills/`. +Model, Effort and Forked mirror each skill's `model:`, `effort:` and `context: fork` +frontmatter; change both together. A forked skill runs in its own subagent on its model and +effort however it is started, and sees only the arguments it was invoked with. -| Task | Skill | -| --- | --- | -| Designing or writing any non-trivial code | `architecture` | -| Implementing an issue (tests first, draft PR, checkpoints) | `implement-issue` | -| Reviewing a PR or branch | `review-pr` | -| Investigating a bug report | `triage-issue` | -| Designing a feature too big for one PR, or sizing one | `design-feature` | -| Turning a request or a found bug into an issue (interviews first) | `file-issue` | -| Running the app on a simulator and driving it through the CLI | `e2e-device` | -| Writing or editing anything an Appduct user reads: READMEs, `docs/`, website, the shipped skill, CLI help, error messages | `writing-user-docs` | -| Adding, amending or reviewing an entry in `CHANGELOG.md` | `writing-changelog` | -| Cutting a release | `cut-release` | -| Curating agent memory (weekly, or when the inbox has notes) | `review-memory` | -| Taking an issue from `status:ready` to a reviewed, tested PR | `work-issue` (orchestrator) | -| Driving an Appduct-enabled app as a user of Appduct | `appduct` (in `skills/`) | +| Task | Skill | Model | Effort | Forked | +| --- | --- | --- | --- | --- | +| Designing or writing any non-trivial code | `architecture` | none | none | no | +| Implementing an issue (tests first, draft PR, checkpoints) | `implement-issue` | sonnet | medium | yes | +| Reviewing a PR or branch | `review-pr` | opus | high | yes | +| Investigating a bug report | `triage-issue` | opus | high | yes | +| Designing a feature too big for one PR, or sizing one | `design-feature` | opus | high | yes | +| Turning a request or a found bug into an issue (interviews first) | `file-issue` | sonnet | medium | no | +| Running the app on a simulator and driving it through the CLI | `e2e-device` | sonnet | low | yes | +| Writing or editing anything an Appduct user reads: READMEs, `docs/`, website, the shipped skill, CLI help, error messages | `writing-user-docs` | none | none | no | +| Adding, amending or reviewing an entry in `CHANGELOG.md` | `writing-changelog` | none | none | no | +| Cutting a release | `cut-release` | sonnet | low | no | +| Curating agent memory (weekly, or when the inbox has notes) | `review-memory` | opus | high | yes | +| Taking an issue from `status:ready` to a reviewed, tested PR | `work-issue` (orchestrator) | none | none | no | +| Driving an Appduct-enabled app as a user of Appduct | `appduct` (in `skills/`) | none | none | no |