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: 3 additions & 3 deletions .agents/skills/architect/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,15 +20,15 @@ Call `todo_write` with one item per phase before starting.

## Phase A: Ground the problem

Build a real mental model of every system the new code touches. Run the **how** skill over the relevant subsystems. Naming a file isn't grounding. Produce the architectural explanation `how` prescribes. If the design redefines ownership or layering, also run the **why** skill on the existing shape so the rationale becomes a constraint, not a guess.
Build a real mental model of every system the new code touches. Trace the relevant subsystems. Naming a file isn't grounding. Write an architectural explanation of each. If the design redefines ownership or layering, also run the **why** skill on the existing shape so the rationale becomes a constraint, not a guess.

Skip Phase A only when the work is genuinely greenfield with no surrounding system to integrate.

## Phase B: Sketch

Run the **arena** skill with the design-sketch task and the Phase A grounding artifacts. Pass `references/runner-prompt.md` as each runner's prompt.

Take the runners from the `architect runners` line in `~/.agents/pstack-models.md`, in place of the `arena runners` line. With no file or line, use two `inherit` seats. Alias and rejected entries follow the runner rules in the **arena** skill's Phase A.
Take the runners from the `architect runners` line in `~/.agents/pstack-models.md`, in place of the `arena runners` line. With no file or line, use three `inherit` seats. Alias and rejected entries follow the runner rules in the **arena** skill's Phase A.

Design it twice. Require at least two structurally distinct candidates before synthesis, even when the first looks sufficient. This is the **exhaust-the-design-space** principle skill made concrete. Whole-shape alternatives, not point fixes inside one shape.

Expand Down Expand Up @@ -69,7 +69,7 @@ Use judgment. A few edge cases don't condemn an architecture. Some problems are

When you scrap:

1. Re-run the **how** skill over what's been built.
1. Trace what's been built.
2. Redesign as if the new constraints had been day-one assumptions, per redesign-from-first-principles.
3. Subtract before adding, per the **subtract-before-you-add** principle skill. The new sketch should be smaller than the old one before it grows.
4. Return to Phase B and re-run arena.
Expand Down
4 changes: 2 additions & 2 deletions .agents/skills/arena/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Every candidate gets the same prompt, so the prompt is the contract.

1. State the artifact each candidate is producing.
2. Derive the rubric, 3-6 concrete gradeable criteria for what success looks like on *this* task. It is the picker's tool in Phase D. Candidates only see the task.
3. Pick the runners from the `arena runners` line in `~/.agents/pstack-models.md`. With no file or line, use two `inherit` seats and say the panel has no route diversity. If the `subagent` tool exposes `provider`, `model`, and `reasoning_effort`, pass each runner's route and effort; otherwise omit them. If DSH rejects a route, fall back to `inherit` and say so. If dropped seats leave fewer than two runners, add runners until there are two, or one when the line has one entry. Run each added runner on a remaining runner's route, or on `inherit` when none remain, and say so. Spawn more runners when the arena covers multiple design directions. Use the same route N times when the work is generation-bound rather than judgment-sensitive.
3. Pick the runners from the `arena runners` line in `~/.agents/pstack-models.md`. With no file or line, use three `inherit` seats and say the panel has no route diversity. An `inherit` entry means the parent model, so omit route fields for it. If the `subagent` tool exposes `provider`, `model`, and `reasoning_effort`, pass each runner's route and effort; otherwise omit them. If DSH rejects a route, fall back to `inherit` and say so. If dropped seats leave fewer than two runners, add runners until there are two, or one when the line has one entry. Run each added runner on a remaining runner's route, or on `inherit` when none remain, and say so. Spawn more runners when the arena covers multiple design directions. Use the same route N times when the work is generation-bound rather than judgment-sensitive.
4. Give each candidate its own output location. For code, create a git worktree with `bash` (`git worktree add ../<repo>-arena-<n> -b <branch>`) and pass its path as the child's `cwd`. For files that are not repo edits, use `/tmp/arena-<slug>/candidate-<n>/`, per the **separate-before-serializing-shared-state** principle skill. DSH children share this machine, so `cwd` is the isolation boundary.

## Phase B: Fan out
Expand All @@ -25,7 +25,7 @@ If a candidate produces no output, proceed with N-1 and note the dropout.

## Phase C: Cross-judge

After all Phase B candidates complete, choose one route from the `arena cross-judge pool` line in `~/.agents/pstack-models.md`. Try only entries that differ from the parent's route, in pool order. An `inherit` entry is the parent model, so it never judges. If the `subagent` tool rejects a route, move to the next entry. If no different route runs, skip the judge, pick the base alone in Phase D, and say so. When a judge runs, spawn one judge `subagent` with a read-only prompt and that route. It sees the rubric and the candidates by path label, scores each criterion, and recommends a base with rationale. It runs in parallel with your reading in Phase D. Don't spawn it while candidates are still writing.
After all Phase B candidates complete, choose one route from the `arena cross-judge pool` line in `~/.agents/pstack-models.md`. With no file or line, the pool is three `inherit` seats. Spawn one judge `subagent` with a read-only prompt when a seat can run. The judge is never from the parent's vendor. A vendor is the route's provider. Try only the entries from another vendor, in pool order. An `inherit` entry is the parent model, so it never judges. If the `subagent` tool rejects a route, move to the next entry. If no entry from another vendor runs, skip the judge, pick the base alone in Phase D, and say so. If you do not know the parent's provider, try the pool's real routes in pool order and say that the vendor check did not run. The judge sees the rubric and the candidates by path label, scores each criterion, and recommends a base with rationale. It runs in parallel with your reading in Phase D. Don't spawn it while candidates are still writing.

## Phase D: Pick a base

Expand Down
4 changes: 2 additions & 2 deletions .agents/skills/blast-radius/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,10 +30,10 @@ Step 4 is usually one small script that imports the same library the app ships a

## Steps

1. Read the change. The diff, the symbols it adds, changes, and deletes, and what it now does differently, including the part the diff doesn't spell out. Use `why` step 2 to pull the PR and commits.
1. Read the change. The diff, the symbols it adds, changes, and deletes, and what it now does differently, including the part the diff doesn't spell out. Pull the PR and its commits.
2. Find the one fact it's safe because of. Most changes that look risky are safe because of a single fact, like "this call only drops already-dead cache entries and does nothing else". Find that fact. If it holds, most risky cases are cleared at once. Spend your time here, not on a long list of maybes.
3. Look where grep stops. Read the source of the library you call, and check its pinned version and any local patch. Work out when things run: microtasks, unmount and teardown, Solid versus React. Follow what a symbol search misses: the JSON an API returns, a DB column, a wire format, another language reading the same bytes, a feature flag, code three hops downstream.
4. Be honest about each risk. Give it a real chance of happening and a real cost if it does. Keep the risks you confirmed. List the ones you checked and cleared separately. Same rules as `why`. Cite a real `file:line`, a search that finds nothing is still an answer, and never make up a caller or an API.
4. Be honest about each risk. Give it a real chance of happening and a real cost if it does. Keep the risks you confirmed. List the ones you checked and cleared separately. Cite a real `file:line`, a search that finds nothing is still an answer, and never make up a caller or an API.
5. Prove the one fact. Write a script or test that runs the real code, run it, and paste what happened.
6. For a big or wide change, run it as an `arena`. Ask more than one model the same question and merge the answers. Different models catch different real bugs.

Expand Down
27 changes: 6 additions & 21 deletions .agents/skills/how/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,31 +6,16 @@ disable-model-invocation: true

# How

Explore the codebase to answer "how does X work?" questions. Produce architectural explanations at the level of a senior engineer onboarding onto a subsystem, enough to build a working mental model, not so much that it reads like annotated source code.

Every spawn is a fresh `subagent` with a read-only prompt: it must not modify files or remotes. Explorers use the `how explorer` role and explainers use `how explainer`. Read `~/.agents/pstack-models.md` when it exists and use the role's line, or `inherit` when the file or line is missing. If the `subagent` tool exposes `provider`, `model`, and `reasoning_effort`, pass the route and effort; otherwise omit them and the child inherits the parent model. If DSH rejects a route, fall back to `inherit` and say so.

## 1. Assess complexity
Explore the codebase to answer "how does X work?" questions.

If the scope is ambiguous, state your interpretation and explore. The user can redirect.

- **Simple** (a single module, a small utility, a narrow question such as "how does function X work"): no explorers. Spawn one explainer that explores and explains in one pass, built from `references/explainer-prompt.md` without the explorer-findings section. Go to step 4.
- **Complex** (a subsystem spanning multiple files or services, a cross-cutting feature, a full architectural overview): go to step 2.

When in doubt, take the simple path.

## 2. Explore (complex only)

Decompose the question into 2 to 4 angles, each a distinct slice of the subsystem. Make all explorer `subagent` calls in one assistant message. Each prompt is `references/explorer-prompt.md` with its angle filled in.

## 3. Synthesize (complex only)

Once all explorers have returned, spawn one explainer with `references/explainer-prompt.md` and every explorer's findings filled in.
## 1. Explain

## 4. Present
Spawn one `subagent` that explores and explains in one pass. Tell it not to modify files or remotes. Give it the user's question and this brief:

Present the explainer's output. Light edits for clarity or context from the conversation are fine. Do not substantially rewrite it.
> You are writing an architectural explanation for a senior engineer. Explore the codebase and write an explanation that a senior engineer unfamiliar with this area could read and walk away with a solid mental model. They should understand the architecture well enough to start working in it confidently. You have read-only access to the codebase.

## Output format
## 2. Present

The explanation uses the sections defined in `references/explainer-prompt.md`, dropping any that do not apply: Overview, Key Concepts, How It Works, Where Things Live, Gotchas.
Present the subagent's output. Light edits for clarity or context from the conversation are fine. Do not substantially rewrite it.
55 changes: 0 additions & 55 deletions .agents/skills/how/references/explainer-prompt.md

This file was deleted.

35 changes: 0 additions & 35 deletions .agents/skills/how/references/explorer-prompt.md

This file was deleted.

2 changes: 1 addition & 1 deletion .agents/skills/no-comments/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Use the caller's files or diff. Otherwise use the current diff against the base
## Steps

1. Read `references/comment-sicko.md` from this skill's directory. Spawn one `subagent` with that body at the top of the prompt, followed by the scope and an instruction to report findings only. Use the `judgment and prose` route when `~/.agents/pstack-models.md` configures one; otherwise omit route fields. Do not restate its rules.
2. Inspect its report and diff. Reject application-code edits, scope escapes, exception-protected deletions, misstated `MUST KILL` reasons, and flags that treat kept intentional code as guilty. Reshape flags on our-code surprises stay actionable. Do not restore those comments. A keep survives only with proof it is about something we cannot change. Audit missed scoped lint and TypeScript suppressions. Correctness or safety suppressions stay actionable `MUST KILL`s. Restore deletions only with exact exceptions and scoped proof. Before accepting thin `IMPORTANT` or `do not remove` kills or keeps, run `/how` or `/why` on their symbol. If a kill is ambiguous, do not restore. If a keep is refuted or still ambiguous, delete it. Revert and rerun one rejected report with the failure named. Reject a second, report it open, and fail `/no-comments`.
2. Inspect its report and diff. Reject application-code edits, scope escapes, exception-protected deletions, misstated `MUST KILL` reasons, and flags that treat kept intentional code as guilty. Reshape flags on our-code surprises stay actionable. Do not restore those comments. A keep survives only with proof it is about something we cannot change. Audit missed scoped lint and TypeScript suppressions. Correctness or safety suppressions stay actionable `MUST KILL`s. Restore deletions only with exact exceptions and scoped proof. Before accepting thin `IMPORTANT` or `do not remove` kills or keeps, trace their symbol or run `/why` on it. If a kill is ambiguous, do not restore. If a keep is refuted or still ambiguous, delete it. Revert and rerun one rejected report with the failure named. Reject a second, report it open, and fail `/no-comments`.
3. Fix trivial accepted flags directly by deleting a dead path, dropping a parameter, or using the real API. If any fix needs a shape, run `/architect` once for the accepted set and surrounding code. Stop at the sketch. Architect shapes. Step 4 implements.
4. Implement the smallest root-cause fix in scope. Remove every named workaround. If the root cause is out of scope, land the smallest in-scope fix and report the rest open. The **principle-fix-root-causes** and **principle-redesign-from-first-principles** skills guide intent only. Neither authorizes widening the fence nor fixing instances outside it. Never bolt on symptom guards.
5. Constraint comments say `do not remove`, `do not change wording`, or `talk to X before changing`. Leave keeps about things we cannot change. Offer the cheapest in-scope type, runtime, test, or CI lint. Wait for interactive approval. Unattended and eval require caller pre-approval. If approved, encode then delete. Otherwise delete, report the constraint open, and sketch out-of-scope work.
Expand Down
2 changes: 1 addition & 1 deletion .agents/skills/no-comments/references/comment-sicko.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ That list is my only leash. When I am not sure a keep clause applies, the commen

`eslint-disable`, `@ts-ignore`, `@ts-expect-error`, and similar suppressions stink. Look up the rule. If it catches real bugs or protects correctness or safety, kill the suppression and mark the exact guilty symbol `MUST KILL`.

`IMPORTANT`, `do not remove`, `too risky`, `fine for now`, and long justifications are scent, not conviction. Before judging, I read nearby code. If its claim is not obvious there, I run `/how`, `/why`, or both from the **how** and **why** skills on the named symbol or call. Only a foreign keep-list gotcha proven true today on a live path crawls away. Our-code surprises die with the reshape flag above. Doubt after the hunt is meat.
`IMPORTANT`, `do not remove`, `too risky`, `fine for now`, and long justifications are scent, not conviction. Before judging, I read nearby code. If its claim is not obvious there, I trace the named symbol or call, run `/why` from the **why** skill on it, or both. Only a foreign keep-list gotcha proven true today on a live path crawls away. Our-code surprises die with the reshape flag above. Doubt after the hunt is meat.

A long justification without a proven keep-list exception is a confession. Kill it. Never polish meat into a shorter alibi. Mark the exact guilty symbol `MUST KILL`. My kill ends there. I do not touch the code.

Expand Down
Loading
Loading