Skip to content

feat(start,ship): token-efficient flags for cascade gating (#64) #65

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JFK merged 1 commit into from
May 19, 2026
Merged

feat(start,ship): token-efficient flags for cascade gating (#64) #65

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
27 changes: 27 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,33 @@ The reviewer skills (`/claude-c-suite:*`, `/claude-phd-panel:*`) are advisory by

If you maintain a c-suite or phd-panel skill, **adding the Verdict line is the single highest-leverage change** for `gh-issue-driven` integration.

## Measuring token consumption (`rtk gain`)

The token-efficiency flags (`auto-size`, `auto-skip`, `--with-plan`, `--parallel` — see [README](README.md#token-efficient-flags-auto-size-auto-skip---with-plan---parallel)) ship with a measurement obligation: each PR that touches them must capture before/after `rtk gain` numbers in the PR description. The procedure below makes the comparison reproducible.

### Fixture-based measurement

A fixed scenario is required so two runs are comparable. The repo ships one at `tests/fixtures/typo-fix-issue.md` — a representative "small issue" body that exercises the docs-only / auto-size paths. Add new fixtures for other scenarios as needed.

### Procedure

1. **Baseline** — checkout the version to compare against (e.g. `git checkout v0.8.0`), run `rtk gain` once to record the current totals, then invoke `/gh-issue-driven:start` (or `/ship`) against the fixture and capture `rtk gain --history` for the resulting delta. Save the output.
2. **HEAD** — checkout the PR branch, repeat step 1 with the same fixture.
3. **Diff table** — in the PR description, paste a table like:

```
| Scenario | v0.8.0 baseline | PR HEAD | delta |
|---|---|---|---|
| /start typo-fix-issue --auto-size | <tokens> | <tokens> | -N% |
| /ship docs-only-diff --auto-skip | <tokens> | <tokens> | -N% |
Comment on lines +91 to +92
```

The fixture itself is markdown-only, so the measurement is not affected by network latency, model variance, or environment drift beyond what `rtk gain` already accounts for.

### When the measurement is not required

Only the four token-efficiency flags (and their config equivalents) carry this measurement obligation. PRs that don't change cascade gating or skill invocation paths can skip the table — `rtk gain` is for verifying claims about token impact, not a universal PR requirement.

## Design principles

A few load-bearing principles that shape what gets accepted into `commands/`:
Expand Down
42 changes: 42 additions & 0 deletions README.ja.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -210,6 +210,48 @@ git worktree prune # 古い登録情報の掃除

---

## Token 効率化フラグ (`auto-size`, `auto-skip`, `--with-plan`, `--parallel`)

`/start` と `/ship` には、作業の実態に応じて cascade を軽量化する opt-in フラグがあります。フラグ未指定時の挙動は v0.8.0 と byte-identical です。

### `auto-size` — small issue で gate1 を完全スキップ (`/start`)

`/gh-issue-driven:start <issue> auto-size` で **issue-size heuristic** を起動。primary issue のラベルが `gate1.size_heuristic.small_labels` (デフォルト: `good first issue`, `documentation`, `docs`, `tests`, `i18n`) に一致するか、本文が `small_body_max_chars` (デフォルト 500 字) 未満なら、gate1 は **完全にスキップ** されます。`/claude-c-suite:ask` も `/ceo` 昇格も走りません。state file には `gate1.reviewer="size-heuristic"` と synthetic verdict markdown が記録されます。

HITL 確認ゲートは引き続き発火するので、「I have feedback」でスキップを上書き可能。batch invocation (`/start 4 5 6`) は決して small 扱いされません — bundling 自体が coherence signal だからです。

毎回 `/start` でデフォルト ON にしたい場合は `~/.claude/gh-issue-driven-config.json` の `gate1.size_heuristic.enabled: true` に設定。

### `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 +225 to +231

### `--with-plan` — gate1 後に実装プランを生成 (`/start`)

`/gh-issue-driven:start <issue> --with-plan` で、gate1 verdict 後・branch 作成前に `superpowers:writing-plans` を起動。plan markdown は会話から取得され、`~/.claude/cache/gh-issue-driven/<branch-flat>.plan.md` に永続化、state file の `plan.path` が pointer になります。

`superpowers` プラグインが必要。未インストール時は warning を出して plan なしで継続 (abort しません)。

plan は `/start` 会話の **in-line で生成** されます — `/claude-c-suite:ask` や `/kagura-memory:session-start` と同じ実行モデルで、autonomous な sub-process は存在しません。

### `--parallel` — subagent dispatch で実装 (`/start`)

`/gh-issue-driven:start <issue> --with-plan --parallel` で plan 生成後に `superpowers:subagent-driven-development` をチェーン: step 18 の continue target が「plan を入力として subagent dispatch を起動」になります (`/feature-dev:feature-dev` 起動や conversation 内 plan 起案の代わり)。

`--parallel` は `--with-plan` を要求します (subagent skill は plan を input として消費する仕様)。`--parallel` 単独は明示エラーで弾きます。

### こんなときは使わない

- **`auto-size` + 複雑 issue**: グローバルに `auto-size` を ON にして heuristic が複雑 issue を small と誤判定した場合、gate1 はそのままスキップされます。HITL gate が safety net なので、override して再実行可能。
- **`auto-skip` + security-sensitive docs**: `docs/` に脅威モデルなど security review 必須の文書がある場合は default `false` のまま、必要 PR で `cso` を手動で追加。
- **`--parallel` + 些細な変更**: subagent dispatch には setup コストがあります。1ファイルの fix なら conversation 内 continue target (「plan を起案」) の方が安価。

---

## Copilot レビューループ

`gh pr create` の後、`/gh-issue-driven:ship` はレビュアの add を発火し、polling loop に入る前に **HITL 確認ゲート** で立ち止まります(v0.3.0 以降):
Expand Down
42 changes: 42 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -211,6 +211,48 @@ If you manually `rm -rf` the directory first (don't), `git worktree prune` alone

---

## Token-efficient flags (`auto-size`, `auto-skip`, `--with-plan`, `--parallel`)

`/start` and `/ship` accept opt-in flags that adapt the cascade to the actual scope of the work. Defaults are unchanged — when no flags are passed, behavior is byte-identical to v0.8.0.

### `auto-size` — skip gate1 for small issues (`/start`)

`/gh-issue-driven:start <issue> auto-size` invokes the **issue-size heuristic**: if the primary issue's labels match `gate1.size_heuristic.small_labels` (default `good first issue`, `documentation`, `docs`, `tests`, `i18n`) **or** the body is shorter than `small_body_max_chars` (default 500), gate1 is **skipped entirely**. No `/claude-c-suite:ask` invocation, no escalation. The state file records `gate1.reviewer="size-heuristic"` and a synthetic verdict markdown.

The HITL confirmation gate still fires so you can override the skip with "I have feedback". Batch invocations (`/start 4 5 6`) are never small — bundling is itself a coherence signal.

To make this the default for every `/start` run, set `gate1.size_heuristic.enabled: true` in `~/.claude/gh-issue-driven-config.json`.

### `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 +226 to +232

### `--with-plan` — generate an implementation plan after gate1 (`/start`)

`/gh-issue-driven:start <issue> --with-plan` invokes `superpowers:writing-plans` after the gate1 verdict and before branch creation. The plan markdown is captured from the conversation and persisted to `~/.claude/cache/gh-issue-driven/<branch-flat>.plan.md`; the state file's `plan.path` points to it.

Requires the `superpowers` plugin. Without it, `/start` logs a warning and continues without a plan (no abort).

The plan is **produced in-line** as part of the `/start` conversation — the same execution model as `/claude-c-suite:ask` and `/kagura-memory:session-start`. There is no autonomous sub-process.

### `--parallel` — implementation via subagent dispatch (`/start`)

`/gh-issue-driven:start <issue> --with-plan --parallel` chains `superpowers:subagent-driven-development` after plan generation: step 18's continue target is set to invoke subagent dispatch on the plan content, rather than launching `/feature-dev:feature-dev` or drafting an implementation outline in the conversation.

`--parallel` requires `--with-plan` (the subagent skill consumes a plan as its input). Setting `--parallel` alone is rejected with an error so the workflow stays explicit.

### When NOT to use these flags

- **`auto-size` + complex issue**: if you set `auto-size` globally and the heuristic misclassifies a complex issue as small, gate1 is skipped without ceremony. The HITL gate is your safety net — override the skip and re-run if needed.
- **`auto-skip` + security-sensitive docs**: if your `docs/` directory contains published threat models or anything that warrants security review on edit, keep the default `false` and re-add `cso` manually for those PRs.
- **`--parallel` for trivial changes**: subagent dispatch has its own setup cost. For one-file fixes, the in-conversation continue target ("draft a plan now") is cheaper.

---

## Copilot review loop

After `gh pr create`, `/gh-issue-driven:ship` fires the reviewer add and pauses at a **HITL confirmation gate** (since v0.3.0) before entering the polling loop:
Expand Down
48 changes: 46 additions & 2 deletions commands/config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,40 @@ To trust a fork, change the URL: `"claude-c-suite": "https://github.com/yourfork

**CI use**: run `doctor verbose` and `grep '^PLUGIN_CHECK'` to parse machine-readable `key=value` lines. Fail on `status=unexpected` to enforce origin pinning in CI.

### `gate1.size_heuristic`

Opt-in mechanism that lets `/gh-issue-driven:start` skip the gate1 cascade entirely for issues that match a "small issue" heuristic. Default is **off** for backward compatibility — when disabled, `/start` runs gate1 (`/claude-c-suite:ask` → optional `/ceo` escalation) on every issue, exactly as in v0.8.0.

| Key | Default | Meaning |
|---|---|---|
| `enabled` | `false` | Master switch. When `true`, the heuristic runs in `/start` step 7a. The CLI flag `auto-size` is the per-invocation equivalent. |
| `small_labels` | `["good first issue", "documentation", "docs", "tests", "i18n"]` | Case-insensitive label list. If the primary issue has any label in this list, the issue is small. |
| `small_body_max_chars` | `500` | If the primary issue body is shorter than this, the issue is small. |

**Trigger logic**: an issue is small when **either** signal fires — label match OR short body. Both proxies capture the same "implementer can act without design review" intuition; the OR captures both labeled triage signals and short-body brevity signals.

**Effect when small**: gate1 (`/claude-c-suite:ask`, optional `/ceo` escalation) is **not** invoked. `GATE1_REVIEWER` is set to the sentinel `"size-heuristic"`, `GATE1_VERDICT` to `green`, and the gate1 markdown captures a synthetic "skipped by policy" record. The HITL gate (`gate1.green_continue_requires_confirm`) still fires so the operator can override the size-heuristic decision by selecting "I have feedback".

**Batch mode**: `IS_BATCH=true` invocations are **never** small. Bundling multiple issues is itself a coherence signal that warrants gate1 review.

**Token savings**: the saved cost is one `/claude-c-suite:ask` invocation per matching issue (plus the rarer `/ceo` escalation when the verdict is decline). For a docs-only typo fix, this is the dominant cost in `/start` — order-of-magnitude reduction is realistic.

### `gate2.diff_scope_skip`

Opt-in mechanism that lets `/gh-issue-driven:ship` skip irrelevant gate2 advisors based on the changed-file scope. Default is **off** for backward compatibility — when disabled, `/ship` runs every advisor in `gate2.advisors`, exactly as in v0.8.0.

| Key | Default | Meaning |
|---|---|---|
| `enabled` | `false` | Master switch. When `true`, ship.md step 4a probes the diff and may filter `ADVISORS`. The CLI flag `auto-skip` is the per-invocation equivalent. |
| `docs_only_patterns` | `["^README", "^CHANGELOG", "^CONTRIBUTING", "^docs/", "^\\.github/"]` | Regex list. A diff is **docs-only** when **every** changed file matches at least one pattern. |
| `docs_only_skip_advisors` | `["/claude-c-suite:cso", "/claude-c-suite:qa-lead"]` | Advisors skipped when the diff is docs-only. The remaining advisors (e.g. `cto`) still run. |

**Important**: this plugin's `commands/*.md` files are markdown-as-code (the runtime spec) — they are intentionally **not** in the default `docs_only_patterns`. Editing `commands/start.md` is a behavioral change, not docs. If you customize the patterns, keep this invariant.

**Effect when docs-only**: the matched advisors are excluded from the parallel battery in ship.md step 6. The binary gate (`gate2.binary_gate`) is never affected — it has its own opt-in via the `binary_gate` key. `SKIPPED_ADVISORS` is recorded in the gate2 state block (`gate2.skipped_advisors`) so `/gh-issue-driven:status` can surface what was skipped and why.

**When NOT to enable**: if your repo treats `docs/` as security-sensitive (e.g. published threat models, secret-management docs that could leak credentials when edited), keep the default `false`. Skipping `cso` is appropriate only when docs changes carry no security review obligation.

### `memory.context_id`

Accepts three forms — in priority order of recommendation:
Expand Down Expand Up @@ -167,7 +201,12 @@ Users without kagura-memory installed can ignore this field — recall is skippe
"primary": "/claude-c-suite:ask",
"fallback": "/claude-c-suite:ceo",
"yellow_continue_requires_confirm": true,
"green_continue_requires_confirm": true
"green_continue_requires_confirm": true,
"size_heuristic": {
"enabled": false,
"small_labels": ["good first issue", "documentation", "docs", "tests", "i18n"],
"small_body_max_chars": 500
}
},
"gate2": {
"binary_gate": null,
Expand All @@ -178,7 +217,12 @@ Users without kagura-memory installed can ignore this field — recall is skippe
],
"yellow_continue_requires_confirm": true,
"green_continue_requires_confirm": true,
"run_tests_before_gate2": false
"run_tests_before_gate2": false,
"diff_scope_skip": {
"enabled": false,
"docs_only_patterns": ["^README", "^CHANGELOG", "^CONTRIBUTING", "^docs/", "^\\.github/"],
"docs_only_skip_advisors": ["/claude-c-suite:cso", "/claude-c-suite:qa-lead"]
}
},
"review": {
"provider": "copilot"
Expand Down
6 changes: 3 additions & 3 deletions commands/doctor.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -361,13 +361,13 @@ CI scripts can parse with `grep '^PLUGIN_CHECK'` and fail on `status=unexpected`
```
(Available from the Claude Code official marketplace — no marketplace add needed.)

11. **Worktree plugin: `superpowers`** (optional — enhances `/gh-issue-driven:start --worktree` with smart directory selection)
- Probe via plugin cache glob: `~/.claude/plugins/cache/superpowers*`. `start.md` step 13b uses the **identical glob probe** (`ls -d ~/.claude/plugins/cache/superpowers*`) so the two commands answer "is superpowers installed?" the same way — they MUST NOT drift. When changing the glob here, update `commands/start.md` step 13b in the same commit.
11. **Worktree plugin: `superpowers`** (optional — enhances `/gh-issue-driven:start --worktree`, `--with-plan`, and `--parallel` with smart directory selection, plan generation, and subagent-driven implementation respectively)
- Probe via plugin cache glob: `~/.claude/plugins/cache/superpowers*`. `start.md` step 13b uses the **identical glob probe** (`ls -d ~/.claude/plugins/cache/superpowers*`) so the two commands answer "is superpowers installed?" the same way — they MUST NOT drift. When changing the glob here, update `commands/start.md` step 13b in the same commit. Steps 12a (`--with-plan` → `/superpowers:writing-plans`) and 18b (`--parallel` → `/superpowers:subagent-driven-development`) rely on the same plugin; this single probe answers for all three flags.
- Run the Plugin Metadata Resolution Procedure with:
- `PMRP_GLOB=superpowers*`
- `PMRP_SKILL=superpowers`
- `PMRP_OFFICIAL=false`
- If `PLUGIN_FOUND=false`: emit ⚠️ `superpowers: not installed — /gh-issue-driven:start --worktree will fall back to direct git worktree add .worktrees/<branch>, which still works (no hard requirement)`.
- If `PLUGIN_FOUND=false`: emit ⚠️ `superpowers: not installed — /gh-issue-driven:start --worktree will fall back to direct git worktree add .worktrees/<branch> (still works); --with-plan and --parallel will degrade with a warning and continue without invoking the missing skills`.
- Otherwise: emit the status line per the procedure's output format.
- When `fix` flag is set AND missing, append a 2-line `try:` block:
```
Expand Down
Loading
Loading