progress

name

progress

description

Use Progress Protocol 1 and the installed progress CLI to guide an Agent or human in moving source-adjacent software outcomes steadily from discovery and planning through design, implementation, verification, review, release, operation, and feedback. Use when Codex needs to adopt Progress; shape, validate, query, or visualize a complete outcome graph; author or change fenced Progress Items; choose, implement, or coordinate ready work, including explicitly requested one-Item-per-subagent parallel work; complete or reopen Items truthfully; consume CLI exports; or diagnose protocol and graph failures. Do not use for generic status reports, progress indicators, or task tracking that is not backed by Progress Protocol 1.

Progress

Drive one verifiable result at a time from a valid dependency graph and keep each wanted result beside the source that owns it. Keep work in progress to one Item by default. Parallelize only when the user explicitly requests it, assign one Item to each subagent, and keep the main Agent responsible for integration and status changes. Assume progress is installed. Treat progress spec and the installed command help as authority when they differ from this skill.

Route the request

• To adopt Progress, plan a milestone, or add work, establish the contract, follow Shape lifecycle outcomes, and then follow Author an Item.
• To inspect or explain work, establish the complete graph and follow Query the graph.
• To choose or implement work, follow Drive a steady lifecycle and Prioritize work. Keep selection read-only unless the user also requests implementation.
• To run explicitly requested parallel work, follow Coordinate parallel work before implementation.
• To edit lifecycle or dependency state, follow Change the graph deliberately.
• To automate, export, or recover from a failure, follow Use machine interfaces or Diagnose and repair.

Drive a steady lifecycle

Repeat one pull loop until the agreed milestone or visible result is done:

1. Orient: Establish and validate the complete graph. Name the current milestone, applicable constraints, and the real evidence that will finish it.
2. Shape: Read the owning sources and make sure the graph contains the next necessary outcomes and gates. Add, split, remove, or reconnect Items before implementation when the graph no longer matches reality.
3. Pull: Choose one ready Item by default. If the desired Item is blocked, walk toward the ready prerequisite that most directly advances it.
4. Make: Change the owning implementation, document, configuration, test, release system, or operating environment until every acceptance condition for the selected Item is true.
5. Prove: Execute the applicable verification and inspect the result and effects. Keep the Item open if any acceptance condition, verification, authority, or required evidence remains unresolved.
6. Integrate: Review the change in its wider system, update status truthfully, validate the complete graph, run relevant repository checks, and inspect newly ready work.
7. Adapt: Report what changed and what was learned. Reshape the graph when evidence, scope, risk, or production feedback changes the needed path, then pull the next Item.

Use the same loop for a human-led project. Keep temporary ownership, active-work claims, schedules, discussions, and approvals in the team's normal coordination systems; Progress does not model doing or prevent two workers from claiming the same Item.

After each loop, report:

• the milestone and important assumptions;
• graph validity and open, ready, blocked, and done counts;
• the selected or completed Item and why it advances the milestone;
• verification actually run and evidence actually observed;
• blockers, changed assumptions, or decisions that need an authority; and
• newly ready work and the recommended next Item.

Keep this report conversational or in the repository's existing status carrier. Do not create a parallel Progress status document.

Shape lifecycle outcomes

Start from the user-visible or operational result and plan its necessary guarantees backward. Then execute forward from ready Items. Consider the whole lifecycle, but create an Item only when its result is independently meaningful, source-owned, observable, and verifiable:

• Record a requirement, product decision, or design contract when later work must rely on that settled guarantee.
• Record architecture, compatibility, security, privacy, accessibility, migration, or performance gates when they are real prerequisites rather than routine concerns inside another Item.
• Record implementation slices that produce coherent behavior a reviewer can accept and verify independently.
• Record integration, review approval, release artifacts, deployment, migration, rollback readiness, or bounded operational observation when downstream work depends on those results.
• Turn production feedback or a retrospective finding into a new Item only after it becomes an agreed, observable improvement. Keep incident history, discussion, and evidence in their real owners.

Do not create one Item for every lifecycle phase, meeting, coding step, test run, review, handoff, or deployment command. Put routine checks in verify; create a separate gate only when another result genuinely depends on its independently accepted guarantee. If a milestone is only a temporary decision target and has no durable owning source, keep it in the current coordination context instead of inventing a synthetic Item.

For cross-boundary delivery, place each Item beside the narrowest source that owns its guarantee and retain a final integration or operational Item only when the visible result needs the combined guarantees. Do not use dependencies to imitate chronology: connect only results that cannot be accepted until their direct prerequisites are true.

Establish the contract and complete graph

1. Read repository instructions, design authority, and the code, tests, schemas, configuration, or documents that own the relevant results.

2. Run progress spec. Read the applicable Protocol 1 rules. Use progress --help and progress COMMAND --help when command syntax is uncertain; inspect progress --version when compatibility matters.

3. Identify the repository's complete authoritative Progress input set. Use . from its root unless repository instructions define narrower or multiple paths.

4. Validate and inspect that full set before narrowing attention:

   progress check .
   progress summary .
   progress list .
   progress list --readiness ready .
   

5. Inspect the relevant Item and both sides of its direct boundary:

   progress show ITEM_ID .
   progress graph --root ITEM_ID --direction both --depth 1 .
   

6. Read the owning implementation, acceptance conditions, verification procedures, tests, and relevant history. Check external environments, credentials, product decisions, and coordination that the graph cannot represent.

Ask the user when the authoritative input set, desired result, acceptance meaning, or permission to mutate cannot be established from repository evidence and the answer would materially change the work. Keep inspection read-only while that choice is unresolved.

All paths selected by one invocation form one graph. With no path, inspection commands use .. Directories are recursive and respect applicable .gitignore files; --no-ignore intentionally includes ignored paths. Explicitly named ignored files and symlinks are read, while discovered symlinks and .git directories are skipped. Use - once for UTF-8 stdin and -- before a path beginning with -. Treat zero Items or an empty filter result as a successful observation, then confirm the intended inputs when Items were expected.

Do not let a narrow query hide an invalid full graph. The CLI validates the complete selected graph before filtering. progress check proves only input, protocol, and graph validity; it does not execute verification, judge acceptance, edit files, change status, or store evidence.

Author an Item

Search the authoritative inputs for existing Items and prose references before adding one. Do not create a second Item for the same owned result. Place a new Item beside the narrowest source that owns its result and remove the leading backslash from this template:

\```progress
id: component.result
status: open
goal: Make the observable result true.
depends:
  - component.prerequisite
accept:
  - State an observable condition that proves the result.
verify:
  - Run `project-specific verification command`.
```

• Put exactly one Item in each fenced progress block and preserve the host file's exact repeated line prefix on every payload and closing line.
• Give the Item a stable, component-scoped ID allowed by progress spec. Start every new Item with status: open.
• State the wanted observable result in goal, not an activity such as "implement" or "investigate."
• Make every accept entry an observable condition that must hold before completion.
• Make verify name commands or manual procedures that can actually cover the acceptance conditions.
• Record only true direct prerequisites in depends; use depends: [] or omit it when there are none. Never encode preferred order, ownership, priority, or transitive reach.

Keep an Item small enough to finish, verify, and review as one coherent result. Split independent product areas into locally owned Items and retain a final integration Item when downstream work needs their combined guarantee. Express an investigation as the observable decision, reproduced failure, measured fact, or reduced uncertainty it must produce. If none of those results is required, do not create an Item for the activity.

When implementation reveals a previously unknown prerequisite, keep the current Item open, author or identify the prerequisite beside its owner, add the direct dependency, and revalidate the complete graph before choosing work again. Never weaken acceptance to preserve an obsolete plan. Run the complete graph checks after every authoring change.

Query the graph

Choose the view that answers the question:

• Run progress or progress summary PATH... for counts and the open queue, ordered with ready work first.
• Run progress check --quiet PATH... when only validity and the exit status matter.
• Run progress list PATH... to enumerate Items. Filter with repeatable --status, --readiness, --id, and --source: repeated values within one filter are ORed; different filter kinds are ANDed.
• Run progress show ITEM_ID PATH... for one Item, its acceptance and verification text, direct dependencies, and direct dependents.
• Run progress graph PATH... for the complete dependency view. Focus with repeatable --root, traverse dependencies, dependents, or both, and bound traversal with --depth. both requires a root.

Every graph edge means dependent -> dependency; traversal direction never reverses that meaning. ID globs match complete IDs. Source globs match normalized paths, where * stays within one component and ** spans directories. Read installed help rather than guessing advanced option syntax.

Prioritize work

Establish the decision target

1. Name the milestone or visible result being optimized. If none is explicit, choose and state a reasonable default.
2. Preserve correctness, safety, compatibility, migration, and release gates as hard constraints.
3. Start from ready Items. When a desired Item is blocked, walk toward its ready prerequisites rather than pretending the blocked Item can begin.

Treat ready as permission to start, not priority. There is no context-free highest-priority Item.

Keep a candidate only when it contributes materially to the milestone, its acceptance meaning is settled, its verification can run with available tools and authority, it can close as one reviewable result, and it preserves required design and safety guarantees. Split an umbrella Item before implementation when it fails those gates.

Rank remaining candidates qualitatively:

priority ~=
  (milestone value + unblocking value + risk reduction + learning value)
  / (implementation + verification + coordination + uncertainty)

Give unblocking value first to direct dependents that become ready when the candidate completes. Inspect actual source gaps before estimating effort. Do not choose only by descendant count or invent numerical precision.

Select one Item unless the user explicitly requested parallel work. Report the milestone and assumption, one recommended first Item, decisive graph and source evidence, the strongest runner-up, and the condition that would change the choice. Separate observed protocol facts from estimated effort and scheduling judgment.

Coordinate parallel work

Do not start subagents merely because several Items are ready. Use parallel work only after the user explicitly requests it. Keep the main Agent as coordinator and integrator; give each subagent exactly one Item to advance.

Choose a parallel batch only when every Item:

• is currently ready in the complete valid graph and materially advances the same agreed milestone;
• has settled acceptance meaning and verification that the assigned worker can execute;
• can be implemented without touching the same expected source files, generated artifacts, mutable external environment, migration state, or release surface as another batch Item;
• does not share an unresolved product, design, security, or operational decision with another batch Item; and
• can succeed, fail, and be reviewed independently without relying on another worker's unintegrated changes.

Use no more workers than eligible Items or available subagent slots. Serialize any Items whose scopes or effects may overlap, even if the dependency graph shows both as ready.

Give each subagent the authoritative input paths, milestone, exact Item ID and source, allowed change boundary, acceptance and verification text, relevant repository instructions, and known constraints. Require the worker to inspect the complete graph and owning source, change only the assigned result, run its verification, leave the Progress status unchanged, and report:

• files and behavior changed;
• acceptance conditions satisfied;
• exact checks run and their results;
• remaining uncertainty, blockers, or required authority; and
• any newly discovered prerequisite, overlap, or graph change.

Keep integrating while workers run when useful, but do not perform the same assigned work. Review every returned diff and claim against the real workspace. If workers overlap unexpectedly, stop treating the work as parallel, reconcile or serialize it, and rerun affected verification. A failed worker leaves its Item open; an independent successful worker may still be integrated and completed after the main Agent's review.

Complete work truthfully

1. Make every acceptance condition true in the owning implementation or environment.
2. Execute every applicable verify command or manual procedure. Require confirmation from the responsible human or external authority for subjective, privileged, destructive, or externally observed acceptance that the Agent cannot establish.
3. Preserve proof in its real owner, such as tests, Git history, benchmark output, review systems, release evidence, dashboards, or operational records. Do not copy proof into the Item.
4. In a single-worker flow, review the result before changing status. In a parallel flow, require each subagent to leave status open and have the main Agent review the integrated result and evidence.
5. Confirm every dependency is already done and the integrated result still satisfies every acceptance condition, then edit the source block to status: done.
6. Re-run progress check and progress summary, inspect the completed Item and newly ready queue, and run the repository's relevant checks.
7. Review the diff for stale references, duplicate inventories, accidental status changes, and unrelated edits.

Do not mark an Item done merely because the graph validates, the code compiles, a worker reports success, or the implementation looks close.

Observe, adapt, and recover

• Keep an Item open when implementation or verification fails. Distinguish a product fault, test fault, environment failure, missing authority, and newly discovered prerequisite before changing the graph.
• Add or reconnect a prerequisite when the current result truly cannot be accepted without it. Report an external wait as a blocker outside Progress unless it is itself a durable, source-owned result that belongs in the graph.
• Split an Item when new evidence shows that it contains independently useful results or cannot be implemented, verified, and reviewed coherently. Preserve its acceptance meaning across the replacements.
• Reopen a done Item when its asserted guarantee is no longer true. Also reopen or repair every done dependent, including transitive dependents, that still relies on that guarantee so the graph remains truthful and valid.
• Create a new Item instead of reopening old work when feedback introduces a genuinely new requirement and the earlier acceptance assertion remains true.
• Represent a post-release observation window as acceptance and manual verification for a bounded rollout or migration result. Keep continuous telemetry, incident history, and proof outside Progress.
• If open work appears to have no ready Item, validate and inspect the unfiltered complete input set before concluding that progress is impossible. Confirm input discovery and graph truth rather than narrowing the query or inventing work.
• When all agreed results are done, verify the milestone itself and stop. Do not manufacture follow-up Items merely to keep the graph active.

Change the graph deliberately

Before renaming, moving, splitting, reopening, or removing an Item, inspect both direct directions and search the repository for prose references.

• Rename an ID by updating every dependency and nearby reference atomically.
• Move a block by preserving its single source of truth, stable ID, and correct host prefix.
• Split an Item by preserving its acceptance meaning across the replacements. Point downstream dependencies at the narrowest guarantee they need and keep an integration gate when they need the whole result.
• Remove an Item only after deciding whether its result is no longer wanted or is supplied elsewhere. Remove a dependency only when the dependent no longer needs that guarantee; otherwise replace it.
• Reopen a done Item by changing it to open and following every dependent path to reopen or otherwise repair done Items that still rely on the now-open guarantee.
• Update nearby fallback, limitation, readiness, and status prose in the same change.

Never weaken acceptance merely to make an Item easier to close. Validate the complete graph after every lifecycle change.

Use machine interfaces

• Use --format json with summary, check, list, or show. Consume the versioned progress-cli/v2 envelope and branch on ok; do not scrape human tables.
• Expect successful data only on stdout and diagnostics only on stderr. Treat exit 0 as success, including an empty result; 1 as input, protocol, query, or output failure; and 2 as invalid command arguments.
• Export graphs with progress graph --format json|dot|mermaid PATH.... Keep the dependent -> dependency edge meaning in every format.
• Generate completion source with progress completion bash|zsh|fish|powershell; add --no-descriptions when needed. The command prints source and does not edit shell configuration.

When old CLI v1 invocations appear, migrate them instead of assuming aliases: progress PATH becomes progress summary PATH, progress ready PATH becomes progress list --readiness ready PATH, and progress --json list PATH becomes progress list --format json PATH.

Diagnose and repair

Start with the complete input set and request structured diagnostics when useful:

progress check --format json PATH...

Repair failures in this order, then rerun the full check after each class of fix:

1. Arguments, exit 2: Read command help. Fix unsupported v1 syntax, missing IDs, invalid option combinations, invalid globs, or a filename that needs --.
2. Input discovery: Confirm the working directory and authoritative paths. Check ignored files, --no-ignore, permissions, UTF-8, symlinks, unreadable .gitignore files, and duplicate stdin. If zero Items were unexpected, search the selected files for escaped or misspelled openers.
3. Block and payload: Follow the diagnostic source path, line, and column. Repair unterminated or nested fences, inconsistent line prefixes, invalid YAML, duplicate or unknown fields, forbidden YAML constructs, missing required fields, invalid IDs, and empty acceptance or verification entries.
4. Graph: Repair duplicate IDs, missing, repeated, self, or cyclic dependencies, and any done Item that depends on an open Item. Preserve actual prerequisite meaning rather than deleting an edge to silence the error.
5. Query: Confirm exact Item IDs, glob semantics, roots, directions, and depth. Remember that --direction both requires at least one --root.

Fix the earliest cause that can create later diagnostics. Do not narrow the input set merely to make an invalid repository appear valid.

Preserve the protocol boundary

• Use only fields allowed by progress spec. Do not add priority, owner, estimate, tag, phase, milestone, timestamps, evidence, scores, or execution notes.
• Store only open or done; ready and blocked are derived and must never appear in status.
• Use dependencies only for required direct guarantees, never to force a preferred schedule, lifecycle order, worker assignment, or parallel batch.
• Keep Progress source-adjacent. Do not turn it into a central backlog, execution log, proof store, Git history, continuation marker, or parallel status document.
• Keep active work and subagent assignments in the current coordination context. Recheck the real graph and workspace at every handoff because Progress does not claim or lock Items.
• Treat graph readiness as neither authority nor approval for destructive, privileged, production, or externally coordinated action.
• Report observed graph state, edits made, verification actually run, and remaining blockers. Never present scheduling judgment as protocol fact or unexecuted verification as evidence.