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: 1 addition & 1 deletion skills/architect/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ Skip Phase A only when the work is genuinely greenfield with no surrounding syst

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 the pstack-models section of `~/.factory/AGENTS.md`, in place of the `arena runners` line. That section is always in context when present, so do not Read it; fall back to the defaults when it is absent. If the section or that line is missing, use `claude-opus-5-5` (judgment seat) and `grok-4.7` (code seat). Seat selection follows the runner rules in the **arena** skill's Phase A.
Take the runners from the `architect runners` line in the pstack-models section of `~/.factory/AGENTS.md`, in place of the `arena runners` line. If the section or that line is missing, use `claude-opus-5-5` (judgment seat) and `grok-4.7` (code seat). Seat selection follows 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
2 changes: 1 addition & 1 deletion 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. Use the `arena runners` line in the pstack-models section of `~/.factory/AGENTS.md`. That section is always in context when present, so do not Read it; fall back to the defaults when it is absent. If the section or that line is missing, default to one each on the judgment seat (`claude-opus-5-5`, `subagent_type: "poteto-judgment"`) and the code seat (`grok-4.7`, `subagent_type: "poteto-agent"`). An `auto` or `inherit-parent` entry on the runners line means the parent model, so spawn the built-in `worker` for it. On the cross-judge line, that entry spawns the built-in `explorer`. Droid model families go by ID prefix such as `claude-*` and `grok-*`. Spawn more runners when the arena covers multiple design directions. Use the same model N times when the work is generation-bound rather than judgment-sensitive. Pick each subagent's complexity for the job, per the Subagents section of the **poteto-mode** skill.
3. Pick the runners. Use the `arena runners` line in the pstack-models section of `~/.factory/AGENTS.md`. If the section or that line is missing, default to one each on the judgment seat (`claude-opus-5-5`, `subagent_type: "poteto-judgment"`) and the code seat (`grok-4.7`, `subagent_type: "poteto-agent"`). An `auto` or `inherit-parent` entry on the runners line means the parent model, so spawn the built-in `worker` for it. On the cross-judge line, that entry spawns the built-in `explorer`. Droid model families go by ID prefix such as `claude-*` and `grok-*`. Spawn more runners when the arena covers multiple design directions. Use the same model N times when the work is generation-bound rather than judgment-sensitive. Pick each subagent per the Subagents section of the **poteto-mode** skill.
4. Give each candidate its own output location (a git worktree where possible, otherwise `/tmp/arena-<slug>/candidate-<n>/`), per the **separate-before-serializing-shared-state** principle skill.

## Phase B: Fan out
Expand Down
2 changes: 1 addition & 1 deletion skills/automate-me/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ Update mode changes the rest of the flow:

Locate the active workspace's transcripts before fanning out. Droid sessions live under `~/.factory/sessions/<workspace-slug>/` (one .jsonl per session), where `<workspace-slug>` is the workspace path with every "/" turned into "-". Use only that path. Never read another project's sessions without being asked.

Survey recent agent conversations within that scope for recurring patterns. Run multiple parallel subagents across slices of history (e.g. last 2-4 weeks, split into 3 slices so each has enough material). Pick each subagent's complexity for the job, per the Subagents section of the **poteto-mode** skill. Each slice mining subagent reads transcripts from the workspace-scoped path the parent provides, looks for the signals below, and returns a short structured list of patterns it saw with evidence pointers. Default signals worth hunting:
Survey recent agent conversations within that scope for recurring patterns. Run multiple parallel subagents across slices of history (e.g. last 2-4 weeks, split into 3 slices so each has enough material). Pick each subagent per the Subagents section of the **poteto-mode** skill. Each slice mining subagent reads transcripts from the workspace-scoped path the parent provides, looks for the signals below, and returns a short structured list of patterns it saw with evidence pointers. Default signals worth hunting:

- Response preferences (length, tone, format, "dumb it down" corrections)
- Delegation habits (subagents, models, specialized workflows, parallelism)
Expand Down
2 changes: 1 addition & 1 deletion skills/figure-it-out/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ Decompose into atomic, independently-landable units. Sequence riskiest-unknown-f

- Build the verification harness before the work, with the baseline captured from the pre-change state, so the check reads as "old value vs new value".
- For one-way-door design decisions, run the **architect** skill (it runs **arena**). Skip it for mechanical work whose shape is already concrete. A second arena over a settled design is over-engineering (the **laziness-protocol** principle skill).
- Decide what fans out. Parallelize only across seams, and give each worker its own worktree or branch (the **separate-before-serializing-shared-state** principle skill). Don't over-fan. Pick each subagent's complexity for the job, per the Subagents section of the **poteto-mode** skill.
- Decide what fans out. Parallelize only across seams, and give each worker its own worktree or branch (the **separate-before-serializing-shared-state** principle skill). Don't over-fan. Pick each subagent per the Subagents section of the **poteto-mode** skill.
- Write the designed phase list down. That list is what the human reviews.

Then execute the design. Add its steps to the todolist as concrete items between the Phase C and Phase D entries. Run each under the Phase C loop discipline, and weave the Phase D log through them, a row as each step lands, rather than saving the whole trail for the end.
Expand Down
2 changes: 1 addition & 1 deletion skills/how/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ disable-model-invocation: true

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 Task subagent. Explorers use the `how explorer` line in the pstack-models section of `~/.factory/AGENTS.md` (default `grok-4.7`, so spawn the read-only code seat, `subagent_type: "poteto-agent-readonly"`), and every explainer uses the `how explainer` line (default `claude-opus-5-5`, so spawn the read-only judgment seat, `subagent_type: "poteto-judgment-readonly"`). That section is always in context when present, so do not Read it; fall back to the defaults when it is absent. When a line's value is `auto` or `inherit-parent`, spawn the built-in `explorer` instead. Pick each subagent's complexity for the job, per the Subagents section of the **poteto-mode** skill.
Every spawn is a Task subagent. Explorers use the `how explorer` line in the pstack-models section of `~/.factory/AGENTS.md` (default `grok-4.7`, so spawn the read-only code seat, `subagent_type: "poteto-agent-readonly"`), and every explainer uses the `how explainer` line (default `claude-opus-5-5`, so spawn the read-only judgment seat, `subagent_type: "poteto-judgment-readonly"`). When a line's value is `auto` or `inherit-parent`, spawn the built-in `explorer` instead. Pick each subagent per the Subagents section of the **poteto-mode** skill.

## 1. Assess complexity

Expand Down
4 changes: 2 additions & 2 deletions skills/interrogate/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Before spawning reviewers, state the intent in one clear paragraph from the user

## Step 3, Spawn Reviewers

Launch all reviewers in a single message with the Task tool, one per entry on the `interrogate reviewers` line in the pstack-models section of `~/.factory/AGENTS.md` (always in context when present; do not Read it), labeled Reviewer A, B, and so on to match the entry count. If the section or that line is missing, use the table defaults.
Launch all reviewers in a single message with the Task tool, one per entry on the `interrogate reviewers` line in the pstack-models section of `~/.factory/AGENTS.md`, labeled Reviewer A, B, and so on to match the entry count. If the section or that line is missing, use the table defaults.

| Subagent | Default model | Seat |
|----------|---------------|------|
Expand All @@ -33,7 +33,7 @@ Launch all reviewers in a single message with the Task tool, one per entry on th

Each reviewer gets `subagent_type` for its entry's model: `claude-opus-5-5` means the read-only judgment seat, `poteto-judgment-readonly`; `grok-4.7` means the read-only code seat, `poteto-agent-readonly`. An `auto` or `inherit-parent` entry means the built-in `explorer`, which runs on the parent model.

Read `references/reviewer-prompt.md` and fill in the same template for every reviewer with the stated intent, the diff or file contents, the rubric from `references/rubric.md`, and the code-quality lens from `references/code-quality-review.md`. Pick each subagent's complexity for the job, per the Subagents section of the **poteto-mode** skill.
Read `references/reviewer-prompt.md` and fill in the same template for every reviewer with the stated intent, the diff or file contents, the rubric from `references/rubric.md`, and the code-quality lens from `references/code-quality-review.md`. Pick each subagent per the Subagents section of the **poteto-mode** skill.

## Step 4, Synthesize

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

## Steps

1. Spawn `Task` with `subagent_type: "comment-sicko"`. Pass the scope. Pick each subagent's complexity for the job, per the Subagents section of the **poteto-mode** skill. Do not restate its rules.
1. Spawn `Task` with `subagent_type: "comment-sicko"`. Pass the scope. Pick each subagent per the Subagents section of the **poteto-mode** skill. 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`.
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.
Expand Down
4 changes: 2 additions & 2 deletions skills/poteto-mode/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,9 +93,9 @@ Read the leaf skill in full for any principle you apply. Each entry names when i

**Use the seat droids for any subagent you spawn inside a playbook step** (code-writing delegates, ad-hoc helpers, review seats): `subagent_type: "poteto-agent"` for the code seat, `subagent_type: "poteto-judgment"` for the judgment seat. The chat that receives `/poteto-mode` runs the playbook. Never spawn a seat droid to run the playbook itself. Routed workflow skills (`how`, `why`, `interrogate`, `reflect`, `swarm`) set their own `subagent_type` for diverse-model review. Respect what the skill prescribes, don't override it.

**Defaults for every `Task` call.** `run_in_background: true`, file pointers not inlined context, and the model seat the role names. Droid's `Task` call has no per-spawn model field, so pstack carries its model panel as droids: `poteto-agent` is the code seat, pinned to `grok-4.7` at `xhigh`, and `poteto-judgment` is the judgment seat, pinned to `claude-opus-5-5` at `xhigh`. Code delegates seat by difficulty. The hardest changes (cross-cutting design, gnarly concurrency, subtle algorithms) go to the judgment seat, whether the task needs judgment on vague intent or is a precisely specified sequence of steps to execute to the letter. Trivial mechanical edits go to the code seat at `complexity: light`. Per-role lines in the `/setup-pstack` section override these defaults and the seat choices in the routed skills (`how`, `why`, `arena`, `swarm`, `architect`, `interrogate`, `reflect`). A role with no line keeps its default, and a role line of `inherit-parent` or `auto` spawns the built-in `worker` droid, which runs on the parent chat model. Each code playbook's configured seat comes from its line (`feature, refactoring`, `bug-fix`, `perf-issue`, or `hillclimb`), and the hardest changes read `hardest tasks`. Prose and judgment read `judgment and prose`.
**Defaults for every `Task` call.** `run_in_background: true`, file pointers not inlined context, and the model seat the role names. Droid's `Task` call has no per-spawn model field, so pstack carries its model panel as droids: `poteto-agent` is the code seat, pinned to `grok-4.7` at `xhigh`, and `poteto-judgment` is the judgment seat, pinned to `claude-opus-5-5` at `xhigh`. Code delegates seat by difficulty. The hardest changes (cross-cutting design, gnarly concurrency, subtle algorithms) go to the judgment seat, whether the task needs judgment on vague intent or is a precisely specified sequence of steps to execute to the letter. Trivial mechanical edits go to the code seat. Effort for a pinned seat is that droid's `reasoningEffort`. Change it with `/setup-pstack`, not per spawn. Per-role lines in the `/setup-pstack` section override these defaults and the seat choices in the routed skills (`how`, `why`, `arena`, `swarm`, `architect`, `interrogate`, `reflect`). A role with no line keeps its default, and a role line of `inherit-parent` or `auto` spawns the built-in `worker` droid, which runs on the parent chat model. Each code playbook's configured seat comes from its line (`feature, refactoring`, `bug-fix`, `perf-issue`, or `hillclimb`), and the hardest changes read `hardest tasks`. Prose and judgment read `judgment and prose`.

**Match the complexity to the job.** Before each spawn, start from the role's line or default and pick the `complexity` the job needs, `light`, `medium`, or `heavy`. Raise it for the hardest or subtlest work. Lower it for routine work. Verification is the exception and stays on the `swarm workers` seat. `/setup-pstack` pins a seat to a different model or effort by writing a personal droid at `~/.factory/droids/<seat>.md`, which Droid resolves ahead of the plugin's droid of the same name, so a diverse panel stays diverse. A role on `auto` or `inherit-parent` stays on the parent model. If the Task tool rejects a `subagent_type`, do not invent a substitute. Use the plugin's seat or `worker` and say so.
**Match the effort to the job.** Before each spawn, start from the role's line or default. Pass `complexity` (`light`, `medium`, or `heavy`) only for an `inherit` droid (`worker`, `explorer`). Raise it for the hardest or subtlest work. Lower it for routine work. Verification is the exception and stays on the `swarm workers` seat. `/setup-pstack` pins a seat to a different model or effort by writing a personal droid at `~/.factory/droids/<seat>.md`, which Droid resolves ahead of the plugin's droid of the same name, so a diverse panel stays diverse. A role on `auto` or `inherit-parent` stays on the parent model. If the Task tool rejects a `subagent_type`, do not invent a substitute. Use the plugin's seat or `worker` and say so.

You own every subagent's work. Review the diff and write your own summary, don't pass through what it said. A second opinion is the same prompt against a different model. Agreement is high-signal.

Expand Down
2 changes: 1 addition & 1 deletion skills/poteto-mode/playbooks/autonomous-run.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
**You own the exit condition. Define done, then drive to it without stopping.**

1. State the exit condition as a checkable predicate before the first iteration (tests green, repro fixed, all N PRs merged, pixel-diff zero).
2. Pick the wake mechanism using Droid's `/loop` command (a built-in, not a pstack skill). An event to watch (CI, a merge, a ref advancing) gets a watcher subagent that wakes you on the event, with a long time-based heartbeat as fallback. No event gets a fixed-interval heartbeat sized to when the result is worth re-checking. Pick each subagent's complexity for the job, per the Subagents section.
2. Pick the wake mechanism using Droid's `/loop` command (a built-in, not a pstack skill). An event to watch (CI, a merge, a ref advancing) gets a watcher subagent that wakes you on the event, with a long time-based heartbeat as fallback. No event gets a fixed-interval heartbeat sized to when the result is worth re-checking. Pick each subagent per the Subagents section.
3. Each iteration makes the smallest change the evidence justifies, verifies it against the predicate, commits if it advanced, discards changes that didn't help. Belt-and-suspenders that "might help" gets reverted, not left to ride.
Sequence the work via the **sequence-verifiable-units** principle skill, verifying each unit before the next instead of batching checks at the end.
4. Mid-run discoveries are yours. Address broken skills, related bugs, flaky verifiers, review noise, tooling failures, orphaned follow-ups, and fixable drift yourself via poteto-mode. Put out-of-band fixes in their own PR. Do not park reversible work for the human or use `AskUser`. Surface only irreversible actions, genuine product or preference calls no experiment can settle, or a real dead end. Keep the predicate as the main drive, and return to it after each side fix.
Expand Down
2 changes: 1 addition & 1 deletion skills/poteto-mode/playbooks/bug-fix.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
### Bug fix

**You own this task. Plan, review, verify.** Delegate investigation and the fix to subagents, stay in the lead. Pick each subagent's complexity for the job, per the Subagents section.
**You own this task. Plan, review, verify.** Delegate investigation and the fix to subagents, stay in the lead. Pick each subagent per the Subagents section.

Be scientific. Every shipped line traces to runtime evidence. Belt-and-suspenders that "might help" is a hypothesis, not a fix. It does not ship. When evidence refutes a hypothesis, revert what it motivated. The smallest change the evidence justifies ships, nothing more.

Expand Down
Loading
Loading