--- name: gframework-batch-boot description: Repository-specific bulk-task workflow for the GFramework repo. Use when Codex should start from the normal GFramework boot context and then continue a repetitive or large-scope task in automatic batches without waiting for manual round-by-round prompts, especially for analyzer warning cleanup, repetitive test refactors, documentation waves, or similar multi-file work with an explicit stop condition such as changed-file count, warning count, or timebox. --- # GFramework Batch Boot ## Overview Use this skill when `gframework-boot` is necessary but not sufficient because the task should keep advancing in bounded batches until a clear stop condition is met. Treat `AGENTS.md` as the source of truth. This skill extends `gframework-boot`; it does not replace it. ## Startup Workflow 1. Execute the normal `gframework-boot` startup sequence first: - read `AGENTS.md` - read `.ai/environment/tools.ai.yaml` - read `ai-plan/public/README.md` - read the mapped active topic `todos/` and `traces/` 2. Classify the task as a batch candidate only if all of the following are true: - the work is repetitive, sliceable, or likely to require multiple similar iterations - each batch can be given an explicit ownership boundary - a stop condition can be measured locally 3. Before any delegation, define the batch objective in one sentence: - warning family reduction - repeated test refactor pattern - module-by-module documentation refresh - other repetitive multi-file cleanup ## Baseline Selection When the stop condition depends on branch size or changed-file count, choose the baseline carefully. 1. Prefer the freshest remote-tracking reference that already exists locally: - `origin/main` - or the mapped upstream base branch for the current topic 2. Do not default to local `main` when `refs/heads/main` is behind `refs/remotes/origin/main`. 3. If both local and remote-tracking refs exist, report: - ref name - short SHA - committer date 4. If only a local branch exists, state that the baseline may be stale before using it. 5. When the task is tied to a PR or topic branch rather than `main`, prefer that explicit upstream comparison target over a generic `main`. For changed-file limits, measure branch-wide scope against the chosen baseline, not just the current working tree: - use `git diff --name-only ...HEAD` - do not confuse branch diff size with `git status --short` For changed-line limits, also measure branch-wide scope against the chosen baseline: - prefer `git diff --numstat ...HEAD` - treat "changed lines" as `added + deleted` summed across the branch diff - do not use working-tree-only line counts as a substitute for branch-wide scope For shorthand numeric thresholds, use a fixed default baseline: - compare the current branch's cumulative diff against remote `origin/main` - include all commits reachable from `HEAD` that are not already in `origin/main` - do not reinterpret shorthand thresholds as "this batch only" or "current unstaged changes only" - only use another baseline when the user explicitly names it in the prompt ## Stop Conditions Choose one primary stop condition before the first batch and restate it to the user. Common stop conditions: - branch diff vs baseline approaches a file-count threshold - warnings-only build reaches a target count - a specific hotspot list is exhausted - a timebox or validation budget is reached If multiple stop conditions exist, rank them and treat one as primary. ## Shorthand Stop-Condition Syntax `gframework-batch-boot` may be invoked with shorthand numeric thresholds when the user clearly wants a branch-size stop condition instead of a long natural-language prompt. Interpret shorthand as follows: - `$gframework-batch-boot 75` - means: stop when the current branch's cumulative diff vs remote `origin/main` approaches `75` changed files - `$gframework-batch-boot 75 2000` - means: stop when the current branch's cumulative diff vs remote `origin/main` approaches `75` changed files OR `2000` changed lines - default positional meaning is ` ` - `$gframework-batch-boot 75 | 2000` - may be interpreted as the same OR shorthand in plain-language chat - when restating, planning, or documenting the command, normalize it to `$gframework-batch-boot 75 2000` - prefer the no-pipe form because `|` is easy to confuse with a shell pipeline When shorthand is used: - report the resolved thresholds explicitly before the first batch - report that the baseline is remote `origin/main`, unless the user explicitly overrides it - if two numeric thresholds are present, treat file count as the default primary metric for status reporting unless the user says otherwise - stop when either threshold is reached or exceeded, even if the other threshold still has headroom ## Batch Loop 1. Inspect the current state before the first batch: - current branch and active topic - selected baseline - current stop-condition metric - next candidate slices 2. Keep the critical path local. 3. Delegate only bounded slices with explicit ownership: - one file - one warning family within one project - one module documentation wave 4. For each worker batch, specify: - objective - owned files or subsystem - required validation commands - output format - reminder that other agents may be editing the repo 5. While workers run, use the main thread for non-overlapping tasks: - queue the next candidate slice - inspect the next hotspot - recompute branch size or warning distribution 6. After each completed batch: - integrate or verify the result - rerun the required validation - recompute the primary stop-condition metric - decide immediately whether to continue or stop 7. Do not require the user to manually trigger every round unless: - the next slice is ambiguous - a validation failure changes strategy - the batch objective conflicts with the active topic ## Task Tracking For multi-batch work, keep recovery artifacts current. - Update the active `ai-plan/public//todos/` document when a meaningful batch lands. - Update the matching `traces/` document with: - accepted delegated scope - validation milestones - current stop-condition metric - next recommended batch - Keep the active recovery point concise; archive detailed history when it starts to sprawl. ## Delegation Defaults - Prefer `worker` subagents for independent write slices. - Prefer `explorer` subagents for read-only hotspot ranking or next-batch discovery. - Keep each worker ownership boundary disjoint. - Avoid launching a new batch when the expected write set would push the branch beyond the declared threshold without a deliberate decision. ## Completion Stop the loop when any of the following becomes true: - the primary stop condition has been reached or exceeded - the remaining slices are no longer low-risk - validation failures indicate the task is no longer repetitive - the branch has grown large enough that reviewability would materially degrade When stopping, report: - which baseline was used - the exact metric value at stop time - completed batches - remaining candidate batches - whether further work should continue in a new turn or after rebasing/fetching ## Example Triggers - `Use $gframework-batch-boot 75 to keep reducing analyzer warnings until the branch diff vs baseline approaches 75 files.` - `Use $gframework-batch-boot 75 2000 to keep reducing warnings until the branch diff approaches 75 files or 2000 changed lines.` - `Use $gframework-batch-boot and keep reducing analyzer warnings until the branch diff vs origin/main approaches 75 files.` - `Use $gframework-batch-boot to continue this repetitive test refactor in bounded batches until the warning count drops below 10.` - `Use $gframework-batch-boot and refresh module docs in waves without asking me to trigger every round.`