ag-generate-closeout

Files (4)

• SKILL.md
• fail.md · scripts/fixtures/validate-closeout-output/
• pass.md · scripts/fixtures/validate-closeout-output/
• validate-closeout-output.mjs · scripts/

SKILL.md (first lines)

# ag-generate-closeout

## When to Apply

Use this skill when working with ag-generate-closeout workflows, tasks, or system specifications.

## How to Use

Refer to the workflow instructions and command references detailed below.

> Output style: closeout packet leads with the verdict/recommendation, tables for drift/readiness, one-line TL;DR — `process/development-protocols/communication-standards.md`.

Generate the post-EXECUTE closeout packet for a completed plan or phase. Produces a structured summary with archive-readiness classification, drift signal scoring, commit checkpoint recommendation, and the single best next valid state.

## When To Invoke

Invoke this skill at the end of:

- Any non-trivial EXECUTE completion (the execute-agent's own closeout block)
- ENTER UPDATE PROCESS MODE flows before archiving a plan
- fast-mode-agent session end, after implementation and verification are complete
- Phase program closeout between phases (after validate + regression checkpoint, before inter-phase UPDATE PROCESS)

Do not invoke for trivial single-file fixes where the plan file is not involved.

## Mode Selection

Choose one mode before generating the closeout packet.

### Simple Mode (default)

Use when:

- The execute session just ended and all context is fresh in the conversation.
- The plan was a single-phase, straightforward implementation.
- No context compaction occurred during the session.

Behavior: write the 8-item closeout packet directly from the plan file and conversation context. No additional git or file scanning is required.

### Deep Mode

Trigger conditions — use Deep Mode if **any one** of the following applies:

- The session was resumed after a context compaction (conversation context may be incomplete).
- The execute session was long — many sub-steps, multiple checklist sections, or multiple commits.
- The caller explicitly requests deep mode.
- The phase is part of a multi-phase program and accurate phase-completion status is required for the umbrella plan.

Behavior: gather evidence before writing the closeout packet. Run these steps in order:

1. `git diff HEAD~1 --name-only` — confirm which files were actually changed. Cross-reference against the plan's blast radius.
2. `git log --oneline -5` — confirm commit messages match what was planned. Flag any commits that touch files outside the plan's scope.
3. Read the phase report if one was already written — confirm its claims match actual execution output.
4. Read the validate-contract test gates — confirm each gate's final status: green, known-gap, or skipped. Do not rely on memory for gate outcomes.
5. Read the plan Implementation Checklist — for every checked item, confirm a matching file appears in the git diff. Flag any checked item with no corresponding change.

After gathering evidence, write the closeout packet with explicit source citations for every material claim.

**Quality difference between modes:**

- Simple: "Section 2 completed — billing router updated" (from memory)
- Deep: "Section 2 completed — `git diff HEAD~1` confirms `packages/api/src/router/billing.ts` modified (+47/-12 lines); test gate `pnpm test:billing` confirmed green in execute log"

When in doubt, prefer Deep Mode. A false-confident Simple closeout is worse than a slightly slower Deep one.

## Closeout Packet Schema

Every closeout packet must include these 9 items. Present them in order.

1. **Selected plan path**
   - The exact file path of the plan being closed out (e.g. `process/features/foo/active/foo-phase-01_PLAN_03-06-26.md`). Never leave this implicit.

2. **Closeout classification** (one of three states — see §Closeout Classification States)

3. **What was finished**
   - A concrete list of what was actually implemented or changed. Not a restatement of the plan checklist — what was done in practice.

4. **What was verified vs still unverified**
   - What tests or evidence exist that confirm the work.
   - What still requires manual verification, user confirmation, or future test coverage.

4b. **Validate-contract compliance**

- Was VALIDATE run for this plan?
- Is a `## Validate Contract` section present in the plan file?
- If VALIDATE was skipped, state the documented skip reason.
- A plan cannot be classified `Ready for UPDATE PROCESS archival` without a present validate-contract or a documented skip reason.

5. **Cleanup done vs still needed**
   - What context docs, reports, or process artifacts were already updated.
   - What remains: open TODOs, uncommitted changes, missing reports, stale references, or plan debt.

6. **Single best next valid state** (one of the allowed states from §Move-On Semantics)
   - Name the exact next action or plan path. Never end with a generic "move to next task."

7. **Commit-checkpoint recommendation** (see §Commit Checkpoint Classification)
   - Whether to invoke `ag-git-manager` before UPDATE PROCESS, or whether the remaining changes are process-only and the commit belongs after UPDATE PROCESS.

8. **Regression status** (phase programs only)
   - Which previously verified surfaces were checked for regression against this phase's blast radius.
   - Whether all passed, or whether fixes were applied before re-verification.
   - If regression checking was skipped (e.g., first phase with no prior verified surfaces), state why explicitly.

9. **SPEC achievement**
   - For each acceptance criterion in the locked `*_SPEC_*.md`, score **met** or **unmet**.
   - Each unmet criterion → a backlog NOTE (the SPEC is frozen; gaps go to backlog only).
   - If there is no SPEC for this plan (e.g. trivial or phase-program inner loop governed by the umbrella SPEC), state that explicitly.

## Closeout Classification States

Exactly three states are allowed. Choose one and state it verbatim.

- **Ready for UPDATE PROCESS archival**
  - The selected plan path still matches the implemented work.
  - Required verification evidence exists.
  - No material deviations remain unresolved.
  - The user has confirmed or approved cleanup.
  - validate-contract is present in the plan file, or VALIDATE was explicitly skipped with a documented reason.

From ngxccc/agent-skills-kit, MIT.

More from ngxccc/agent-skills-kit