Agentic Progressive Improvement: snags as nested units

Keep the main seat on the real task. Snags become internal improve units with risk tiers and a skim line, not a second design chat with you.

This is a portable mid-session protocol. When a tool path breaks, a method gap appears, or the same friction shows up again, the orchestration seat spawns a nested improve unit instead of flooding the only context window or debating a low-risk fix with the human. Version pin on this page and the member kit: 0.1.0-rc.1.

The method is open (MIT on GitLab). Community members get a convenience kit: first-run pack, seat snippets, examples, scrubbed skill copy. The kit is polish, not exclusive IP.

What it does

You are mid-task. Something snags: a broken import, a wrong default path, a flake that will eat the next hour if you fix it inline. You have two bad habits available:

1. Stay in the main chat and thrash the fix until the real task is gone.
2. Start a second long design conversation with the human about a T0 or T1 change.

Agentic Progressive Improvement picks a third move. The orchestration seat classifies a risk tier, appends a local ledger entry, and spawns an improve agent (nested brainstorm, not operator-facing for T0 to T2). That agent dispatches builders under a denylist. You keep the real conversation. Re-entry is a single skim line when the tier requires visibility, or silence when green hygiene already has a ledger and an undo story.

  Operator  <->  Orchestration seat  (real task)
                        |
                        | spawn improve unit
                        v
                 Improve agent
                 (nested brainstorm)
                        |
                        | builders (+ optional auditor)
                        v
                 Local trail + digest
                        |
                        v
              skim line if tier needs it
              silent OK for green T0 (ledger + undo)

Role graph (illustration). Labels live in the table below.

Roles

Role	Job
Orchestration seat	Real task; may spawn improve units; holds skim only
Improve agent	Internal brainstorm; not operator-facing for T0 to T2
Builders	Mechanical changes under denylist + tier
Optional auditor	Check risk / scrub when tier warrants

Caps

  CAPS (hard)
  --------------------------------
  <=3 concurrent improve units / session
  <=2 retries on the same error class
  then escalate: needs-operator
  same model as the orchestration seat
  (mechanical builders may use local only with headroom)

Public skim form

↑ improve: <what> · T# · <ref> · undo:<cmd>

Teach surfaces use ↑ improve:. Silent is fine for green T0 (and many T1s) when a ledger exists. Unsure about risk? Bump the tier. Do not downrank when uncertain.

One safety sentence (memorize it):

Silent green T0 is for hygiene with a ledger and undo, not for method, remotes, or secrets. Unsure → bump tier. T3 ask. T4 prepare only.

Thought process

Pain

Mid-session friction is cheap to notice and expensive to host in the only window you have. Operators either flood that window fixing the snag, or they recruit the human into a design chat about a tiny change. Both steal the real task. Low-risk hygiene should not become a committee.

Insight

Context is scarce. Tokens spent on tool streams and bulk reads do not return as clarity. The orchestration seat should stay on the work that matters. Improve work can run as a nested unit: risk tier, local trail, skim re-entry only when the tier requires it.

Method birth

The portable product is the same doctrine in public language: spawn an improve unit (nested brainstorm → builders), classify T0 to T4, hard denylist, caps, same-seat model for the improve agent, local trail by default. Open MIT so any host that can load a skill and (ideally) spawn seats can run it. Serial single-seat fallback stays honest when multi-seat is impossible.

How we built it

Two layers, deliberately thin:

1. Skill: markdown protocol you drop into a seat skills directory: when to spawn, role graph, tier table, denylist categories, skim form, host honesty (dispatch / serial_fallback / partial).
2. Optional local ledger CLI: api-improve for classify, append, brief, skim, tail, trail. Ledger defaults to a local state path (override with env). Trail backend is local or none. No forge credentials required for the RC.

  SKILL-ONLY (floor)              SKILL + CLI (optional clock)
  ------------------              ----------------------------
  drop skill into seat            pip install -e ".[dev]" from clone
  invoke on snag                  api-improve classify|append|...
  obey tiers / caps / denylist    ledger + trail on disk
  host must spawn or serial-fake  same doctrine, better audit surface

Everything is protocol-shaped, not product-shaped. You bring the multi-agent host. This pack is not a full nested-dispatch runtime, not a memory-codify replacement, and not an AFK self-improve loop.

SSOT for method and code lives on public GitLab under agentic-progressive-improvement. The site vends a versioned member zip as a convenience build. History and tags live on the open repo.

How to use it

1. Get the method

• Free learn: this Deep Dive + the public GitLab tree (skill, SPEC, tests, scrub gate).
• Member convenience kit: zip via the CTA at the bottom (login required). First-run pack, seat-rule snippet, examples, scrubbed skill/prompts, tier cheat-card. Same version: 0.1.0-rc.1.

2. Skill-only install

Copy or symlink the skill folder into the directory your agent loads skills from. Invoke when a snag appears:

Run Agentic Progressive Improvement on this snag: <one line>.
Classify T0-T4. Prefer dispatch when multi-seat exists.
Use serial_fallback only if spawn is impossible. Obey denylist.
Re-enter with ↑ improve: when the tier requires it.

3. Skill + CLI (optional)

From a clone of the public repo:

pip install -e ".[dev]"
api-improve classify --snag "..." --path <path>
api-improve append --tier T1 --kind unblock --seat <id> --status building --snag "..."
api-improve skim --what "..." --tier T1 --ref <path> --undo "git revert HEAD"
api-improve tail -n 5
api-improve trail --backend local

Ledger default: XDG state path under api-improve, or API_IMPROVE_LEDGER override. Trail: local or none.

4. Run one unit

1. Classify T0 to T4. Unsure → bump one tier.
2. Ledger append building (local by default).
3. Spawn the improve agent with tier, snag frame, paths, denylist, model = inherit from the orchestration seat.
4. Continue the real task. Do not wait inside a flood loop.
5. On digest: verify claims on disk when ship matters; update ledger; emit one skim line if state change needs visibility.
6. T3 / T4: surface needs-operator with paths. Never silent promote. T4 prepares only; no auto-mutate.

Host honesty

Mode	When	Claim
dispatch	multi-seat spawn works	peer improve unit
serial_fallback	one seat / no spawn	same stages + digests; not peer quality
partial	mix	name which legs

Serial is the portable floor, not the preferred doctrine. Prefer dispatch when multi-seat exists. Never claim peer critique when one seat performed every role.

When not to use it

• Taste decisions the operator must own.
• T4 red-zone mutation (prepare and ask only).
• Replacing principle-capture or memory-codify tools.
• Replacing a full design swarm or a locked build fan-out (pick the sibling below).

Safety

Risk tiers

Tier	Name	Operator	Ship posture
T0	Session hygiene	Silent when green	Local only; ledger + undo story
T1	Task-unblock	Optional skim	Branch; auto-merge only under strict explicit caps
T2	Tool inherit	Batch at pause	Human merge
T3	Method / rules	Ask before promote	Draft until approved
T4	Red zone	Ask	Prepare only · no auto-mutate

Silent green T0 is for hygiene with a ledger and undo, not for method, remotes, or secrets. Unsure → bump tier. T3 ask. T4 prepare only.

Classification floors

• Unsure → bump one tier (never downrank when uncertain).
• Touches seat rules, methodology, or durable process → min T3.
• Touches secrets, remotes, disk cleanup, sudo, public publish → T4.
• Second occurrence of the same pain class may promote T1 → T2 (inherit).
• First occurrence, one-off → prefer T1 unblock, not a permanent new tool.

Denylist (categories)

Mass disk wipe · protected remotes · secret dumps · sudo without approval · public publish without scrub · push main · AFK irreversible.

Full text lives in the kit and the public SPEC. Categories stay free to learn here.

Model policy

The improve agent uses the same model as the orchestration seat. Mechanical builders may use local models only when headroom exists. Never hop cloud vendors only to save cost.

Sibling triangle

Pick by job, not by habit.

                 +---------------------------+
                 | brainstorming swarm       |
                 | many seats on DESIGN      |
                 | stop at written spec      |
                 +------------+--------------+
                              |
           +------------------+------------------+
           |                                     |
           v                                     v
  +------------------+                  +------------------+
  | solo brainstorm  |                  | build swarm      |
  | one seat, design |                  | many seats on    |
  | until approval   |                  | IMPLEMENTATION   |
  +------------------+                  +------------------+

  orthogonal (this pack):
  +----------------------------------------------+
  | Agentic Progressive Improvement              |
  | mid-session SNAG → nested improve unit       |
  | desk/repo better · operator stays in chat    |
  +----------------------------------------------+

Sibling icons (illustration). Job names live in the table below.

Method	Job	Stops at
Solo brainstorm	One seat on design	Spec
Brainstorming swarm	Multi-lens design under parallel pressure	Spec · no build
Build swarm	Implementation fan-out	Shipped units
This	Mid-session snag → nested improve by risk tier	Desk/repo better · real chat continues

If the design is not locked, do not use this pack as a fake design swarm. If you only need one seat and one pass on a small design, use solo brainstorm. If you need many seats on the design itself, use brainstorming swarm. If design is locked and you need hands on code, use a build swarm. Use Agentic Progressive Improvement when the real task is already running and a snag should not steal the window.

Get the convenience kit

Open method free on this page and on GitLab. The member zip is one-click install polish: first-run path, seat snippets, examples, scrubbed skill copy, tier cheat-card. Version 0.1.0-rc.1.

If you enjoyed this: community members can download the convenience kit (first-run pack + seat snippets). The method stays free to learn on this page and on GitLab.