Skip to content

docs(rules): subagent cost and a cap of 2, real checks, extras named at the end - #79

Merged
realRaghavGupta merged 1 commit into
mainfrom
lead/agent-work-rules
Nov 11, 2026
Merged

realRaghavGupta merged 1 commit into
mainfrom
lead/agent-work-rules

Conversation

@realRaghavGupta

Copy link
Copy Markdown
Contributor

Closes #78

What changes

rules/org-rules.md, which becomes claudeMd in managed/settings.json:

  • A new "Subagents" section. It says why subagents cost a lot: a fork runs on your model at your effort, and on 2026-11-11 two agent runs with about six forks each used a seat's 5-hour allowance in 18 minutes. It says what to delegate (parallel, separate-context or stateless work only), sets at most 2 at a time unless the task says otherwise, sends searches to Explore, and asks for a suggestion instead of a self-started review of finished work.
  • "Changes", first bullet. Name extra work at the end instead of doing it, because a reviewer reads every added line. A syntax check, or a check command that failed to start, shows nothing.

Source: Anthropic's prompting pages (best practices; Fable 5.2, Opus 5.5, Sonnet 5.5, Haiku 5.5). The guidance gives no number for subagents; 2 is a fleet choice. No model or effort is set: those stay each person's choice.

Wording pass on the rest: I found no absolute or approval category that needed a change for this issue, so nothing else is edited. The file is at the 80-line cap the tests set.

Checks

Step Result
bin/generate --check generated files are current
bash tests/run.sh (macOS) 776/786 passed. The 10 failures are the same 10 that fail on main on this Mac (request-review stubs, 760–784, and 786, which reruns the suite); line cap test 34 passes

Owner step

After merge, Raghav pastes the new managed/settings.json into the Claude org console. The rules in sessions now are older than main: they predate #74's merging text too, so this paste brings in both.

— Claude Lead

🤖 Generated with Claude Code

…at the end

From Anthropic's prompting guidance for current Claude models: a fork runs on the session's model, so delegate only
parallel, separate-context or stateless work, at most 2 at a time; a syntax check or a check that failed to start
shows nothing; name extra work at the end instead of doing it. managed/settings.json regenerated.

Closes #78

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@orion-setkernel orion-setkernel left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed head babe72c.

No merge blockers found. Approving.

What I checked and how

  • Checks: the head has one check run, check, and it completed with success. That job runs bash tests/run.sh, bin/generate --check, ShellCheck and the JSON check (.github/workflows/check.yml). I did not rerun the full test suite locally; CI covers it on this head.
  • Diff: git diff origin/main...HEAD has one commit (babe72c) touching two files: rules/org-rules.md (+7/−1) and managed/settings.json (the generated copy).
  • Acceptance criteria (#78):
    • New short section: rules/org-rules.md gains ## Subagents, which covers when a subagent is worth its cost (it gives the reason: forks run on your model and effort, plus the dated cost incident), the limit of 2 at once "unless your task says otherwise", and briefing/Explore. Verification by a real check is added to the first ## Changes bullet ("a live check that exercises the change; a syntax check, or a check command that failed to start, shows nothing"). Each point gives its reason and none of it shouts. The section names no repository. The CI test for private repo names (tests/run.sh, allowed_repos) passes.
    • Wording pass: the PR body says the rest of the file needed no change. That is a judgment call, and I found nothing in the unchanged lines that this issue requires changing.
    • Regeneration: locally, bin/generate --check prints generated files are current. jq -r .claudeMd managed/settings.json | diff - rules/org-rules.md prints no difference. wc -l rules/org-rules.md gives 80, so the file is exactly at the cap that tests/run.sh:89 enforces (-le 80). CI check passed.
    • Owner paste into the org console: this happens after merge by design, so it is not a blocker for this PR.
  • Scope: only the two files listed under ## Files likely touched. No test edits, so the test-diff guard does not apply.
  • Secrets / R3 security: no secrets, tokens or personal data. Nothing goes live when this merges. Only README.md and AGENTS.md refer to org-rules.md, and managed/settings.json takes effect only when Raghav pastes it into the console (AGENTS.md "Deploy"). No hook or plugin file changes.
  • Authorship: the PR was opened from Raghav's account and signed — Claude Lead, on the lead/ branch prefix, as the org rules require.

Nits (non-blocking)

  1. ## Subagents says to "suggest a deeper review of your own finished work instead of starting one". But plugins/setkernel/skills/ship-pr/SKILL.md:6 tells the agent to run review-blockers on its own work. The phrase "unless your task says otherwise" belongs to the limit of 2, not to this clause. Adding "unless a skill or your task asks for one" would remove the apparent conflict.
  2. "Do one file, a sequence of steps, or work that needs what you just learned yourself" reads as one long noun phrase until the final "yourself". Something like "Do it yourself when it is one file, a sequence of steps, or needs what you just learned" is easier to read.
  3. Criterion 1 asks for verification inside the new section, but it was added to ## Changes instead. The content is there, so this is fine. A short pointer such as "verify as in Changes" in the new section would match the criterion's wording more closely.
  4. The parenthetical "Explore (a cheaper model)" describes Claude Code's current agent definition, which could change. "(read-only, usually a cheaper model)" would stay accurate longer.
  5. The file is now exactly at the 80-line cap. The next rule added will need a trim elsewhere. The dated 2026-11-11 incident takes up most of a line and could be shortened then.

@rigel-setkernel rigel-setkernel left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed head babe72c.

No merge blockers. The change is policy text only, it matches what the issue asks for, and the generated file is current.

What I checked

  • Checks: the one check run on the head, check, completed with success.
  • Diff: git diff origin/main...HEAD changes two files: rules/org-rules.md (+7/−1) and managed/settings.json (generated). These are the two files listed under ## Files likely touched, so the scope is right.
  • Generated file: bin/generate --check printed generated files are current.
  • Tests: bash tests/run.sh on this Ubuntu runner gave 789/789 passed. wc -l rules/org-rules.md gives 80, so the file meets the line cap at tests/run.sh:89.

Acceptance criteria (#78)

  1. New section: when a subagent is worth its cost, a cap of 2, verification by a real check, each with a reason, no shouting, no private repository. Met. rules/org-rules.md:46-51 adds ## Subagents. It explains the cost (forks run on your model and effort, and gives the 18-minute seat example) and says to delegate only parallel, separate-context or stateless work, "at most 2 at a time unless your task says otherwise". It is written in sentence case and names no repository. The real-check point is in the ## Changes bullet (:30), not in the new section: "a live check that exercises the change; a syntax check, or a check command that failed to start, shows nothing". It still says why, so I count the point as met.
  2. Wording pass on the existing rules. The PR says no other rule needed a change, and the diff edits nothing else. I found no absolute without a reason that this issue would require changing.
  3. bin/generate run, then tests/run.sh and bin/generate --check pass. Met; results above.
  4. Owner pastes the file into the org console. This happens after merge, so I could not check it here.

Security (R3, org policy): the diff has no secrets and no executable change. Merging changes nothing live on its own. The new text reaches sessions only when Raghav pastes the file into the console (criterion 4).

Nits (non-blocking)

  1. :50 says to search with Explore. This plugin also ships setkernel:explorer (plugins/setkernel/agents/explorer.md: model: sonnet, effort: low). Naming one or both would keep the rule and the plugin consistent.

  2. :51 says to suggest a deeper review of your own finished work instead of starting one. Two places in the plugin still start that review:

    • plugins/setkernel/agents/reviewer.md's description says "Use … after a long session finishes".
    • ship-pr step 2 runs review-blockers on your own work.

    An explicit skill step can reasonably override the rule, but aligning the reviewer description in a follow-up would remove the mixed message.

  3. :48-49: in "Do one file, a sequence of steps, or work that needs what you just learned yourself", the trailing "yourself" makes the sentence hard to parse. "Do yourself: one file, …" would be clearer.

  4. The dated example (2026-11-11, 18 minutes) will age. A general phrasing such as "a few forks can use a seat's 5-hour allowance in minutes" would keep the reason without the date. Optional.

@realRaghavGupta
realRaghavGupta merged commit 425b959 into main Nov 11, 2026
1 check passed
@realRaghavGupta
realRaghavGupta deleted the lead/agent-work-rules branch November 11, 2026 04:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Org rules: subagent cost, parallel cap and verification, from Anthropic's prompting guidance

3 participants