feat(start,ship): token-efficient flags for cascade gating (#64)#65
Merged
Merged
Conversation
Add four opt-in flags that adapt the cascade to issue/diff scope: - `auto-size` (/start): skip gate1 entirely for small issues per the label/body-length heuristic in gate1.size_heuristic. Default off. - `auto-skip` (/ship): skip docs-only gate2 advisors per the path-pattern rules in gate2.diff_scope_skip. Default off. - `--with-plan` (/start): invoke /superpowers:writing-plans after gate1 and persist the plan to the state file (step 12a + 14.5). - `--parallel` (/start): chain /superpowers:subagent-driven-development as the step 18 continue target. Requires --with-plan. Backward-compat: with no flags and no config opt-in, behavior is byte-identical to v0.8.0. State schema is additive (`plan`, `gate2.skipped_advisors`, `gate2.diff_scope` are all v2-compatible optional fields). Co-locates measurement procedure (CONTRIBUTING.md, tests/fixtures/typo-fix-issue.md) so future PRs can produce reproducible rtk gain numbers. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds opt-in “token-efficient” gating and workflow flags to the gh-issue-driven command specs so /start and /ship can adapt reviewer/skill execution to the scope of work, plus documentation and a fixture for measuring token impact.
Changes:
- Add
/startflagsauto-size,--with-plan, and--parallelwith a size-heuristic gate1 short-circuit and optional plan/subagent chaining. - Add
/shipflagauto-skipwith diff-scope classification to filter gate2 advisors for docs-only diffs. - Document the new config keys and measurement procedure; add a reproducible measurement fixture.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| commands/start.md | Adds size-heuristic gate1 skip plus optional writing-plans and parallel subagent continue-target logic. |
| commands/ship.md | Adds diff-scope detection to optionally skip irrelevant gate2 advisors on docs-only diffs. |
| commands/config.md | Documents gate1.size_heuristic and gate2.diff_scope_skip defaults and behavior. |
| commands/doctor.md | Updates superpowers plugin check messaging to cover --with-plan / --parallel degradation. |
| README.md | Documents the new token-efficiency flags and how they affect /start and /ship. |
| README.ja.md | Japanese documentation for the new token-efficiency flags. |
| CONTRIBUTING.md | Adds a reproducible rtk gain measurement procedure for flag-impact changes. |
| tests/fixtures/typo-fix-issue.md | New fixture issue body for consistent token-consumption measurement runs. |
Comment on lines
+419
to
+421
| Both signals are checked. The issue is **small** when **either**: | ||
| - Any label name (case-insensitive) is in `SMALL_LABELS`, OR | ||
| - `len(PRIMARY_ISSUE.body)` is less than `SMALL_BODY_MAX` |
| Determine what the **continue** option will actually do, based on flags, skill detection from step 17b, and `IS_BATCH`: | ||
|
|
||
| - If `IS_BATCH` is true → continue target is **"draft a per-issue implementation plan in this conversation"**. Do **not** auto-launch `/feature-dev` for batch mode (it is single-feature oriented). | ||
| - If `PARALLEL=true` (the operator opted in via `--parallel`) AND `PLAN_OUTPUT` is non-null (the writing-plans step produced a usable plan) → continue target is **"invoke `/superpowers:subagent-driven-development` via the Skill tool, passing the plan from step 12a as its input"**. This branch is only reachable when `WITH_PLAN=true` as well (step 1's interaction rules guarantee it). If the `/superpowers:subagent-driven-development` skill is not installed OR `PLAN_OUTPUT` is null (writing-plans skill was unavailable or returned nothing usable), fall through to the next applicable branch and log a one-line warning naming the reason. |
Comment on lines
+226
to
+232
| ### `auto-skip` — skip irrelevant gate2 advisors (`/ship`) | ||
|
|
||
| `/gh-issue-driven:ship auto-skip` probes the diff and, when every changed file matches `gate2.diff_scope_skip.docs_only_patterns` (default `README*`, `CHANGELOG*`, `CONTRIBUTING*`, `docs/`, `.github/`), skips the advisors listed in `docs_only_skip_advisors` (default `cso` and `qa-lead`). The remaining advisors (e.g. `cto`) still run, and the binary gate (`gate2.binary_gate`) is never affected. | ||
|
|
||
| A diff that touches even one non-doc file disqualifies docs-only treatment — there is no partial skip. The `commands/*.md` files in this repo are markdown-as-code and are intentionally **not** in the default pattern list. | ||
|
|
||
| Persistent equivalent: set `gate2.diff_scope_skip.enabled: true` in config. |
Comment on lines
+225
to
+231
| ### `auto-skip` — 関係ない gate2 advisor をスキップ (`/ship`) | ||
|
|
||
| `/gh-issue-driven:ship auto-skip` は diff を調べ、変更ファイル**すべて**が `gate2.diff_scope_skip.docs_only_patterns` (デフォルト `README*` / `CHANGELOG*` / `CONTRIBUTING*` / `docs/` / `.github/`) に一致したら、`docs_only_skip_advisors` (デフォルト `cso` と `qa-lead`) をスキップします。残りの advisor (例: `cto`) は走り、binary gate (`gate2.binary_gate`) は影響を受けません。 | ||
|
|
||
| 1ファイルでも非doc 変更があれば docs-only 判定は不成立 — partial skip はありません。このリポジトリの `commands/*.md` は markdown-as-code (実行 spec) なので、意図的にデフォルトパターンから除外されています。 | ||
|
|
||
| 永続化設定は `gate2.diff_scope_skip.enabled: true`。 |
Comment on lines
+91
to
+92
| | /start typo-fix-issue --auto-size | <tokens> | <tokens> | -N% | | ||
| | /ship docs-only-diff --auto-skip | <tokens> | <tokens> | -N% | |
Owner
Author
Code reviewNo issues found. Checked for bugs and CLAUDE.md compliance. 🤖 Generated with Claude Code - If this code review was useful, please react with 👍. Otherwise, react with 👎. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #64. Adds four opt-in flags that adapt the cascade to the actual scope of the work, plus measurement infrastructure for verifying token impact.
auto-size/startgate1.size_heuristic).auto-skip/shipgate2.diff_scope_skip.--with-plan/start/superpowers:writing-plansafter gate1, persist plan to state file.--parallel/start/superpowers:subagent-driven-developmentas the step 18 continue target. Requires--with-plan.Backward-compat: with no flags and no config opt-in, behavior is byte-identical to v0.8.0. State schema is additive (
plan,gate2.skipped_advisors,gate2.diff_scopeare all optional v2-compatible fields).Gate1 outcome
Verdict: yellow (via
/claude-c-suite:ask, CTO lens)The reviewer flagged 5 design concerns; all 5 are addressed in this PR:
step 12aofcommands/start.mdnow documents the in-line execution model explicitly: writing-plans body is injected into Claude's context; the parent (/start) captures the plan output and persists it. No autonomous sub-process.labelandbody_length. ThePM signalproxy mentioned in the issue body was rejected during gate1 review because invoking/pmto decide whether to invoke gate1 would cancel out the savings.enabled=falsedefault).docs_only_patternsdeliberately excludescommands/*.md(markdown-as-code in this plugin). Documented inconfig.mdand both READMEs.tests/fixtures/typo-fix-issue.mdprovides a fixed scenario;CONTRIBUTING.mddocuments the measurement procedure.Gate1 markdown:
~/.claude/cache/gh-issue-driven/64-feat-make-start-token-efficient-with-optional.gate1.mdGate2 outcome
Verdict: green (advisor-only mode —
gate2.binary_gate=null)/claude-c-suite:csocommands/*.mdexclusion is well-designed./claude-c-suite:qa-lead/claude-c-suite:cto--auto-sizeinverse flag could be a follow-up.Gate2 markdown:
~/.claude/cache/gh-issue-driven/64-feat-make-start-token-efficient-with-optional.gate2.mdAcceptance criteria
/start --with-planinvokessuperpowers:writing-plans(step 12a) and persists the plan (step 14.5)./start --parallelinvokessuperpowers:subagent-driven-development(step 18b), requires--with-plan./start auto-sizeapplies an issue-size heuristic (step 7a) usinglabelandbody_length(no PM signal — would self-cancel). Heuristic and override documented inconfig.md./ship auto-skipapplies a diff-scope heuristic (step 4a) for docs-only diffs. Rules documented inconfig.md.references/. Gate1 noted limited effect (Skill loader does not auto-expand@references/paths). Follow-up issue to be filed.rtk gainnumbers usingtests/fixtures/typo-fix-issue.mdand append to this PR description before merge./startand/shipbehavior backward-compatible (no flags -> current cascade).doctorupdated: superpowers entry now mentions--with-plan/--parallelgraceful-degradation path.README.md/README.ja.mddescribe new flags and skipping rules.Out of scope
commands/*.mdextraction toreferences/(deferred per gate1 review's "limited effect" assessment)./propose.Files changed
commands/start.md(+126) — 3 new flags, step 7a (size heuristic), step 12a (writing-plans), step 14.5 (plan persistence), step 18b parallel branch.commands/ship.md(+62) —auto-skipflag, step 4a (diff-scope skip).commands/config.md(+48) —gate1.size_heuristic,gate2.diff_scope_skipkeys + documentation.commands/doctor.md(+6) — superpowers entry updated.README.md(+42) — Token-efficient flags section.README.ja.md(+42) — same in Japanese.CONTRIBUTING.md(+27) — rtk gain measurement procedure.tests/fixtures/typo-fix-issue.md(new) — measurement fixture.How was this tested
bash tests/test_state_schema.sh: 39 passed / 0 failedbash tests/enum-sync-check.sh: 24 in sync / 0 driftedbash tests/jq-sync-check.sh: 5 in sync / 0 driftedpython3 tests/test_verdict_parser.py: 25 passed / 0 failed/propose->/start->/ship), exercising the v0.8.0 pre-change paths. Post-merge, follow-up runs will exercise the new flags.Follow-ups (separate issues)
commands/start.md/commands/ship.mdto reduce primary-load file size.no-auto-size) or per-invocation disable mechanism forgate1.size_heuristic.enabled=trueglobal config.