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

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.

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 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.