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 docs/guide/01-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ Run:

[`/setup-pstack`](../../skills/setup-pstack/SKILL.md) detects the models you have access to, asks for a reasoning budget, shows you each role (code delegates, judgment, the review panels), and asks what you want. Answer the questions. It writes `~/.grok/rules/pstack-models.md`, a small rule every pstack skill reads.

The `large` budget matches the skill defaults: `grok-4.7` for judgment and `grok-4.7-build-fast` for code, when `grok models` lists both. `unlimited` uses the strongest detected slug for every role. `medium` uses `grok-4.6` for judgment when it is detected, and keeps code on the fast slug. `small` uses `grok-4.5` when it is detected, otherwise the cheapest detected slug. Do not invent an effort suffix. If `spawn_subagent` has no `model` argument, `/setup-pstack` sets `[features] subagent_model_inheritance = false` in `~/.grok/config.toml` when no requirements pin or `GROK_SUBAGENT_MODEL_INHERITANCE` blocks it. Role models start in the next session. This session still inherits the parent.
The budgets are `unlimited — max reasoning`, `large — xhigh reasoning`, `medium — high reasoning`, and `small — medium reasoning`. `unlimited`, `large`, `medium`, and `small` set the effort of every real model entry, panel entries included, to `max`, `xhigh`, `high`, or `medium`, on the ladder `max` > `xhigh` > `high` > `medium` > `low`. Effort is a separate field, written after the model id (`grok-4.6 xhigh`). If the model does not offer that effort, use its highest offered effort at or below the target, else mark the role as needing a choice. On grok 1.0.62, `unlimited` keeps `grok-4.6` at `xhigh`, `large` keeps the defaults, and `small` turns them into `grok-4.6 medium` and `grok-4.5 medium`. If `spawn_subagent` has no `model` argument, `/setup-pstack` sets `[features] subagent_model_inheritance = false` in `~/.grok/config.toml` when no requirements pin or `GROK_SUBAGENT_MODEL_INHERITANCE` blocks it. Role models start in the next session. This session still inherits the parent.

You only override what you care about. A role with no line in the rule keeps the skill's default. To restore a default, delete that role's line. A rerun of `/setup-pstack` keeps any role whose model differs from the default. When a default changes, a rule written before the change still pins the old default, so delete those role lines, or delete the file, then run `/setup-pstack` again.

Expand Down
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.md` rule, in place of the `arena runners` line. If the rule or that line is missing, use `grok-4.7` and `grok-4.7-build-fast`. Alias and rejected entries follow the runner rules in the **arena** skill's Phase A.
Take the runners from the `architect runners` line in the `pstack-models.md` rule, in place of the `arena runners` line. If the rule or that line is missing, use `grok-4.6 xhigh` and `grok-4.5 high`. 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
4 changes: 2 additions & 2 deletions 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 `~/.grok/rules/pstack-models.md`. If the rule or that line is missing, default to one each on `grok-4.7` and `grok-4.7-build-fast`. An `auto` or `inherit-parent` entry in this line or the cross-judge line means the parent model, so omit `model` for it. If `spawn_subagent` has no `model` argument, omit it for this session so the child inherits the parent, and apply step 1 of **setup-pstack** so the next session can pass `model`. If it rejects a slug, use the closest slug from `grok models` and say so. Diversity is a different detected slug, not a different vendor. 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. Use the role slug from the Subagents section of the **poteto-mode** skill. Do not invent an effort suffix.
3. Pick the runners. Use the `arena runners` line in `~/.grok/rules/pstack-models.md`. If the rule or that line is missing, default to one each on `grok-4.6 xhigh` and `grok-4.5 high`. An `auto` or `inherit-parent` entry in this line or the cross-judge line means the parent model, so omit `model` for it. If `spawn_subagent` has no `model` argument, omit it for this session so the child inherits the parent, and apply step 1 of **setup-pstack** so the next session can pass `model`. If it rejects a slug, use the closest slug from `grok models` and say so. Diversity is a different detected slug, not a different vendor. 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 reasoning effort for the job, per the Subagents section.
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 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 model from the `arena cross-judge pool` line in `~/.grok/rules/pstack-models.md`. If the rule or that line is missing, choose from `grok-4.7` and `grok-4.7-build-fast`. Prefer a detected slug different from the parent's when one exists. Spawn one judge subagent on that model. There is no readonly flag. The prompt forbids file edits. 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 model from the `arena cross-judge pool` line in `~/.grok/rules/pstack-models.md`. If the rule or that line is missing, choose from `grok-4.6 xhigh` and `grok-4.5 high`. Prefer a detected slug different from the parent's when one exists. Spawn one judge subagent on that model. There is no readonly flag. The prompt forbids file edits. 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.

## Phase D: Pick a base

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. They live under `~/.grok/sessions/<percent-encoded absolute cwd>/<session-id>/chat_history.jsonl`. Percent-encoding turns `/` into `%2F`. `GROK_HOME` overrides `~/.grok`. Use only that workspace directory. Don't glob across `~/.grok/sessions/*/`. That crosses workspace boundaries and reads private chats from unrelated projects.

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). Use the role slug from the Subagents section of the **poteto-mode** skill. Do not invent an effort suffix. 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's reasoning effort for the job, per the Subagents section. 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. Use the role slug from the Subagents section of the **poteto-mode** skill. Do not invent an effort suffix.
- 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 reasoning effort for the job, per the Subagents section.
- 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 spawn_subagent with omit `subagent_type` and a prompt that forbids file edits (there is no readonly flag). Explorers use the `how explorer` line in the `pstack-models.md` rule (default `grok-4.7-build-fast`), and every explainer uses the `how explainer` line (default `grok-4.7`). Set `model` to that line's value, or to the default if the rule or the line is missing. Leave `model` unset when the value is `auto` or `inherit-parent`. If `spawn_subagent` has no `model` argument, omit it for this session so the child inherits the parent, and apply step 1 of **setup-pstack** so the next session can pass `model`. If it rejects a slug, use the closest slug from `grok models` and say so. Use the role slug from the Subagents section of the **poteto-mode** skill. Do not invent an effort suffix.
Every spawn is a `spawn_subagent` call with no `subagent_type` and a prompt that forbids file edits (there is no readonly flag). Explorers use the `how explorer` line in the `pstack-models.md` rule (default `grok-4.6` at `xhigh`), and every explainer uses the `how explainer` line (default `grok-4.6` at `xhigh`). Set `model` to that line's value, or to the default if the rule or the line is missing. Leave `model` unset when the value is `auto` or `inherit-parent`. If `spawn_subagent` has no `model` argument, omit it for this session so the child inherits the parent, and apply step 1 of **setup-pstack** so the next session can pass `model`. If it rejects a slug, use the closest slug from `grok models` and say so. Pick each subagent's reasoning effort for the job, per the Subagents section.

## 1. Assess complexity

Expand Down
6 changes: 3 additions & 3 deletions skills/interrogate/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,14 +28,14 @@ Launch all reviewers in a single message with spawn_subagent, one per entry on t

| Subagent | Default model |
|----------|---------------|
| Reviewer A | `grok-4.7` |
| Reviewer B | `grok-4.7-build-fast` |
| Reviewer A | `grok-4.6 xhigh` |
| Reviewer B | `grok-4.5 high` |

Each reviewer gets omit `subagent_type`, a prompt that forbids file edits (there is no readonly flag), and `model` set to its configured entry, or its table default when there is no configured line. Omit `model` for an `auto` or `inherit-parent` entry, so that reviewer runs on the parent model.

If `spawn_subagent` has no `model` argument, omit it for this session so the child inherits the parent, and apply step 1 of **setup-pstack** so the next session can pass `model`. If it rejects a configured entry, use the closest slug from `grok models` and say so. Prefer a detected slug different from the parent's when one exists. Do not block the review on the slug issue. Never treat an alias entry as a rejected slug.

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`. Use the role slug from the Subagents section of the **poteto-mode** skill. Do not invent an effort suffix.
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 reasoning effort for the job, per the Subagents section.

## 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 `spawn_subagent` with `subagent_type: "pstack:comment-sicko"`. Pass the scope. Use the role slug from the Subagents section of the **poteto-mode** skill. Do not invent an effort suffix. Do not restate its rules.
1. Spawn `spawn_subagent` with `subagent_type: "pstack:comment-sicko"`. Pass the scope. Pick each subagent's reasoning effort for the job, per the Subagents section. 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
Loading
Loading