GFramework/.agents/skills/gframework-batch-boot/SKILL.md

name, description

name

description

gframework-batch-boot

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 <baseline>...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 <baseline>...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 <files> <lines>
• $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/<topic>/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.