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
2 changes: 2 additions & 0 deletions .claude/skills/cut-release/SKILL.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
3 changes: 3 additions & 0 deletions .claude/skills/design-feature/SKILL.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
3 changes: 3 additions & 0 deletions .claude/skills/e2e-device/SKILL.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
2 changes: 2 additions & 0 deletions .claude/skills/file-issue/SKILL.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
3 changes: 3 additions & 0 deletions .claude/skills/implement-issue/SKILL.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
3 changes: 3 additions & 0 deletions .claude/skills/review-memory/SKILL.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
3 changes: 3 additions & 0 deletions .claude/skills/review-pr/SKILL.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
3 changes: 3 additions & 0 deletions .claude/skills/triage-issue/SKILL.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
30 changes: 20 additions & 10 deletions .claude/skills/work-issue/SKILL.md
Original file line number Diff line number Diff line change
@@ -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.

Expand All @@ -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>` 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.
Expand Down Expand Up @@ -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

Expand Down
33 changes: 18 additions & 15 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Loading