finish-session
Use when the user asks to finish or wrap up the session — checks that all they asked for is delivered, then commits, pushes and archives it. Not for a code review. Self-contained — execute the inlined
SKILL.mdplugins/flowai/skills/finish-session/SKILL.md
GitHub<!-- GENERATED FROM framework/composites/finish-session.md, framework/atoms/check-goals.md, framework/atoms/commit.md, framework/atoms/push.md via scripts/generate-skill-composites.ts — DO NOT EDIT BY HAND -->
Task: Finish the Session
Overview
Closes a working session in one invocation: it proves that the session's goals are met, puts the work on the remote, and archives the session.
- Goals Phase — every goal of the session checked against evidence gathered now, with one verdict line.
- Commit Phase — targeted documentation sync + Conventional Commits + task-status auto-flip.
- Push Phase — safe
git pushwith upstream and divergence gates. - Archive Phase — final report, then the session is archived with the host's own means.
Three explicit gates between phases:
- Goals → Commit — the verdict MUST be
Goals: all met. A goal that is not met or not verified → STOP. The per-goal report reaches the user in the final report, or in the STOP message. - Commit → Push — every change of this session MUST be committed.
- Push → Archive — the push report does NOT end the run; the work MUST be on the remote before the session is archived.
Context
<context> Finishing a session by hand is four separate acts, and the first one — checking that what was asked for exists — is the one that gets skipped. This composite makes it the entrance: nothing is committed for a session whose goals do not hold. There is no review phase and no reflection phase; a user who wants the diff reviewed before the commit asks for that workflow instead. Archiving is the only step that depends on the host: some hosts give the agent a tool that archives its own session and may remove the session's working copy with it, others give nothing. Each phase is FULLY INLINED below. Maintainer note (NOT for runtime): generated by `scripts/generate-skill-composites.ts` from `framework/composites.yaml`. Source-of-truth bookkeeping only. </context>Rules & Constraints
<rules> 1. **No skill re-entry**: All four phases are FULLY INLINED below. Execute the steps directly. Do NOT invoke any goal-check, commit or push skill via the Skill tool — it would re-enter without the composite's gate logic and the workflow would silently exit between phases. 2. **Four Phases, Strict Order**: Goals, then Commit, then Push, then Archive. Never interleave; never skip a gate. 3. **The user sees the goal report in full**: the verdict line and every goal with its status and evidence. On a STOP at the Goals Gate it is the last thing you write. On a run that goes on, the final report of the Archive Phase carries it in full — a bare `Goals: all met` there is not the report. 4. **Goals Gate**: only `Goals: all met` proceeds. Any goal `not met` or `not verified` → STOP. Do NOT repair an unmet goal inside this run to get past the gate: finishing work is a new request, and the user decides whether to make it. 5. **A STOP ends the run**: after a STOP no later phase runs — no commit, no push, no archive. Report which gate stopped you and why, then hand control back to the user and wait. 6. **Nothing to commit is not a failure**: when the session changed no file, the Commit Phase reports "Nothing to commit". Treat that report as a completed Commit Phase and continue with the gate after it. 7. **Archive is the last act**: nothing is written, run or edited after the session is archived. Never imitate archiving by deleting or moving transcripts, branches, worktrees or project files. 8. **Session Scope**: compare current `git status` with the git status snapshot from session start (available in system context). Files already modified/untracked at session start are outside the commit scope — note them but do not commit them. If unsure which changes are yours, ask the user before staging. 9. **Planning**: use a task management tool (e.g. `todo_write`, `todowrite`, `Task`) to track all four phases as a single plan. </rules>Instructions
Goals Phase
<step_by_step>List the goals of the session
- Go through the user's messages in this session in order, the invocation message included. Each thing the user asked for is one goal. Write it in the user's own words, shortened only where nothing is lost.
- A later instruction replaces an earlier one it contradicts. A goal the user cancelled is kept in the list with the status
withdrawnand is not checked. - A message that only answers your question, approves a step or picks an option adds no goal of its own; it shapes the goal it belongs to.
- If the session worked on a task file (the
tasksrole from the project instructions), every item of its Definition of Done is a goal as well. Merge an item with the user's request it restates. - If you kept a task list in this session, an entry the user asked for and you never finished is a goal.
- No goal found — the session held only questions and answers, or the conversation is not available to you → say so in one line and skip to the last step. Do NOT ask the user to dictate the goals.
Gather evidence for each goal — now
- Choose the cheapest observation that would fail if the goal were not met:
- a Definition-of-Done item with an evidence command → run that command;
- a change in behaviour → run the test that covers it, or the project's check command once for all goals it covers;
- a file, section or setting that must exist → read it or
grepfor it; - an answer, an explanation or a report the user asked for → find the message that delivered it;
- something outside this machine (a deploy, a sent message, a CI run) → query it if a command for that exists.
- Reuse a result from earlier in this session only when no file it depends on changed afterwards. Otherwise run it again.
- Run independent read-only commands together where the tool allows it.
- Do not stop at the first unmet goal: check all of them.
- Choose the cheapest observation that would fail if the goal were not met:
Give each goal one status
met— the observation from step 2 confirms it. Name the observation: the command and its result, or the file and line.not met— the observation contradicts it, or part of the goal is missing. Say exactly what is missing. A partly delivered goal isnot met.not verified— nothing available here can confirm or refute it. Say what the user can run or look at to settle it.withdrawn— the user cancelled it in this session.- A ticked checkbox whose evidence command fails is
not met, and the report says that the box is ticked.
List the loose ends — apart from the goals
- Run
git status --porcelainand, if the branch has an upstream,git rev-list --count @{u}..HEAD. - Report, each in one line and only when present: uncommitted changes made in this session; commits not pushed; background processes or sessions this session started that still run; a question of the user you never answered; a follow-up you promised and did not do.
- A loose end does not change the status of a goal. Uncommitted work is not an unmet goal unless the user asked for a commit.
- Run
Compose the report
- First line, exactly one of:
Goals: all met (<N> of <N>)Goals: NOT all met — <K> not met, <U> not verified, of <N>Goals: none found in this session
- Withdrawn goals are not counted in
<N>. - Then one entry per goal: the goal in the user's words, its status, and the evidence. Put
not metfirst, thennot verified, thenmet, thenwithdrawn. - Then the loose ends from step 4, or
Loose ends: none. - Do not soften the verdict: no "essentially done", no "all met except". One unmet goal makes the first line
NOT all met.
- First line, exactly one of:
Hand off to the next phase
- Keep the report from step 5 whole: the verdict line and every goal with its status and evidence. The run's final report must carry it in full — a bare verdict line there is not the report.
- You may also send it now as a progress message; whether you do or not, it still goes into the final report.
- Do not end the turn here and do not start on an unmet goal: the gate that follows this phase reads the verdict line and decides whether the run continues.</step_by_step>
Goals → Commit Gate
Read the verdict line of the goal report from the Goals Phase:
Goals: all met→ continue in this same turn with the Commit Phase below. Keep the report: the Archive Phase sends it in full.Goals: none found in this session→ there is nothing to verify. Say so in one line and continue with the Commit Phase below.Goals: NOT all met→ write the full goal report to the user and STOP. Do NOT commit, push or archive, and do NOT start fixing the unmet goal. End with one line: which goals block the finish, and that the user can ask to finish them or to close the session as it is.- The user replies that the session should be closed as it is → that is a new instruction from the user and it opens the gate: continue with the Commit Phase and name the unmet goals again in the final report.
Commit Phase
<step_by_step>- Gather Changes
- Collect all git state in a single command:
git status -s && echo '---DIFF---' && git diff && echo '---CACHED---' && git diff --cached && echo '---LOG---' && git log --oneline -5 - If working directory is clean (no changes at all), report "Nothing to commit" and STOP.
- Collect all git state in a single command:
- Documentation Sync (mandatory — do NOT skip)
- Determine scope: look at the file paths from step 1. Classify the change:
- Infra-only: ALL changed files are tests (
*_test.*,*.test.*), CI (.github/), acceptance tests (acceptance-tests/), formatting, or dev-environment (.devcontainer/). → Skip doc sync. Output:Documentation sync: skipped — infra-only changes (tests/CI/acceptance-tests). - Product changes: anything else → proceed with doc sync below.
- Infra-only: ALL changed files are tests (
- Resolve the documents first:
SRS,SDS, andindexare ROLES, not filenames. Read./AGENTS.mdand take the path each role is bound to — a project may put its SDS atarchitecture/system.mdor its SRS atspecs/product.md, and the mapping below then means those files. Never go looking fordesign.md/requirements.mdby name, and never create a file at the conventional path when the role already points somewhere else: that leaves the real document stale and adds a second one nobody reads. Take the WHOLE list the project declares, not just the three named roles — a documentation hierarchy that also binds, say, an API reference or an operations runbook is naming documents this step must keep in sync, and a change belonging to one of them does not become the SDS's problem because the SDS is the familiar name. A role you cannot resolve → say so in one line and sync only what you can. The same holds for a role whose bound path does not exist on disk: outputDocumentation sync: <role> → <path> is missing — not created, then continue — nothing in this workflow creates a project document, and a missing document is not a missing input. - Find the mapping: check if
./AGENTS.mdhas a## Documentation Mapsection. If yes → use the path→document mapping from there. If no → use the default mapping:- New/changed exported functions, classes, types → SDS (component section)
- New feature, CLI command, skill, agent → SRS (new FR) + SDS (new component section)
- Removed feature/component → remove from SRS + SDS
- Changed behavior (fix that alters documented contract) → SDS (update description)
- Renamed/moved modules → SDS (update paths and structure)
- Config/build changes → SDS only if architecture section references them
- Renamed or removed name that documents mention → EVERY document that still prints the old one. A CLI flag, subcommand, option, environment variable, or exported symbol that changed its name is not covered by the "new feature" row, and this is the row that catches it. Do not infer the affected set from the kind of change:
grepthe OLD string across the resolved documents and README, and take the set from the hits. Searching for the NEW name instead returns nothing, which reads as "docs are fine" — that is how a rename passes this step with every document left stale. - README.md → update only for user-facing changes (new install steps, new features, changed API). A rename on the user-facing surface IS a changed API — a CLI flag, subcommand, option, or environment variable that changed its name belongs here.
- Sync each affected document:
- For each changed file, identify which document section describes its component (using the mapping).
- READ that specific section from the document.
- COMPARE the section text with the actual code after your changes. Ask: "Does this section accurately describe the code as it is NOW?"
- If inaccurate → update the section. If accurate → no change needed.
- For new functionality with no corresponding section → add a new section.
- For removed functionality → remove the section.
- Renamed or removed identifiers — search by the OLD name, across every resolved document. A flag, command, option, environment variable, function, or path that changed its name leaves the old one printed wherever it was documented, and grepping for the NEW name comes back empty, which reads as "docs are fine" and is how a rename passes this step untouched. Grep the old string verbatim in each resolved document plus README, and fix every hit. One document updated is not the step finished: the same name usually sits in several of them, and stopping at the first is the usual way the rest go stale.
- Gather change context for commit message and doc updates:
- Active task file: If the user referenced a task file in this session, resolve
tasksfrom AGENTS.md and read that file there. Do NOT scan all task files. - Session context: User messages explaining intent, decisions, requirements.
- Active task file: If the user referenced a task file in this session, resolve
- Apply Compression Rules to any doc updates:
- Use combined extractive + abstractive summarization (preserve all facts, minimize words).
- Compact formats: lists, YAML, Mermaid diagrams.
- Concise language, abbreviations after first mention.
- Execute Updates: Edit documents BEFORE proceeding to grouping.
- Report the sync, one line per document: after the edits, print a
Documentation sync:block with one line for EVERY document resolved above —<path>: updated (<section or what changed>)or<path>: no change — <reason>. The block is the step's output, not a courtesy: a closing sentence such as "updated the SRS, SDS and README" does not say which document was checked and why one was left alone, and the user cannot tell a skipped document from an unaffected one. (2026-09-02 and 2026-09-06:commit-doc-sync-gatesynced all three documents correctly in both runs and failed the same item both times because the result was reported only as a summary sentence.)
- Determine scope: look at the file paths from step 1. Classify the change:
- Commit Grouping
- Review the diff from step 1. Determine the primary business purpose.
- Default: ALL changes → 1 commit. Only split if: a. Changes serve genuinely different, unrelated purposes (no causal link), OR b. The user explicitly requested a split.
- Documentation describing a code change → same commit as that code.
- Tests for a feature → same commit as that feature.
- If splitting: use appropriate Conventional Commits types for each group.
- Hunk-level splitting (within a single file) — ONLY when user explicitly requests it.
- Commit Execution Loop
- Iterate through the planned groups:
- Stage specific files for the group.
- Verify the staged content matches the group's intent — check WHICH files are staged with
git status --short. When step 1 reused a diff from a prior phase rather than reading one, that is the whole check: staging moves files, it cannot change content you have already read, so do NOT rungit diffin any form (--cached,--stat, per-file) to re-confirm it. - Task Status Lifecycle (FR-DOC-TASK-LIFECYCLE) — for each staged task file under the resolved
tasksrole withdate:frontmatter (skip legacy flat-path), first check frontmatterstatus:. If it issuperseded, require/keepsuperseded_by:and skip DoD derivation because the stale original DoD no longer maps to current reality. Otherwise count top-level- [ ]/- [x]items in## Definition of Done. Derivestatus:K=0→"to do",0<K<N→"in progress",K=N→"done"(warn if no DoD). Rewrite frontmatter andgit addif it differs. Idempotent. Never downgradedone. Warn-only on parse errors. - Commit with a Conventional Commits message (including any task-status frontmatter edit).
- Iterate through the planned groups:
- Task files are never deleted (only if a task file was used in step 2) — task files of ANY shape (new-shape
date:frontmatter or legacy flat-path) are persistent canonical records;commitMUST NOT delete them, regardless of DoD completion. The only lifecycle action is the status derivation in step 4.3;status: supersededrecords are preserved. - Verify Clean State
- Run
git statusto confirm all changes are committed. - If uncommitted changes remain, investigate and report to the user.</step_by_step>
- Run
Commit → Push Gate
- Run
git status --porcelain. Every file this session created or modified MUST be committed. One of them still listed → STOP and name it. - Files that were already modified or untracked at session start (rule 8) do not stop the push: they are not this session's work. List them — the Archive Phase asks about them.
- The branch has no upstream and nothing to push to (
git remoteprints nothing) → skip the Push Phase, say so in one line, and continue with the Archive Phase. - Otherwise → enter the Push Phase. If the user declines the push at its first-push or divergence gate, STOP — the commits stay local, and a session with unpushed work is not archived.
Push Phase
<step_by_step>Identify Target Branch
- Run
git rev-parse --abbrev-ref HEADto identify the current branch as<CURRENT>. - If the user typed a branch name as argument, compare to
<CURRENT>. If different, STOP and ask "You typed<typed>but the current branch is<CURRENT>. Push<CURRENT>or check out<typed>first?". Wait for an answer. - Otherwise, the push target is
<CURRENT>.
- Run
Resolve Upstream
- Run
git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/nullto find the upstream of<CURRENT>. - If the command exits non-zero (no upstream), ASK the user: "
<CURRENT>has no upstream. Should I rungit push --set-upstream origin <CURRENT>?". Wait for an answer.- Affirmative → proceed to step 3 with
--set-upstream origin <CURRENT>. - Negative → STOP. Report "No upstream and user declined to set one — nothing to do."
- Affirmative → proceed to step 3 with
- Run
Safety Checks
- Protected-branch divergence (HARD REFUSAL — see Rule 4): if the upstream is
origin/mainororigin/master, rungit fetch origin <CURRENT>thengit rev-list --left-right --count HEAD...@{u}. If the right count (commits the remote has and local does not) is > 0, ASK the user with EXACTLY two options: "Remote<CURRENT>is ahead by N commit(s) the local branch does not have. Force is REFUSED on protected branches even with explicit authorization. Pull and rebase first, or abort?".--force/--force-with-leaseare NOT options — never present them, never run them, even if the user volunteers "force", "overwrite", or "yes I want to overwrite the remote". If the user pushes back, restate the refusal and re-offer pull-rebase / abort. - Non-protected branch divergence: if the right count > 0, surface the divergence but proceed with a regular
git push(which will fail safely if non-fast-forward). DO NOT proactively suggest force. --forcerequest: if the user has explicitly asked for--force, decline. Explain--force-with-leaseand proceed only with per-push user authorization (see Rule 2).
- Protected-branch divergence (HARD REFUSAL — see Rule 4): if the upstream is
Push
- Run
GIT_PAGER=cat git push [--set-upstream origin <CURRENT>]. Stream stdout + stderr to the user. Do NOT silence error output. - On a non-fast-forward error: do NOT retry with
--forceor--force-with-lease. Surface the failure and STOP.
- Run
Post-Push Verification
- Run
git rev-parse @{u}andgit rev-parse HEAD. Compare. - Equal → push succeeded. Report the remote ref and the pushed SHA.
- Different → push reported success but upstream did not advance. STOP with "Post-push verification FAILED: @{u} =
<remote>, HEAD =<local>. Investigate before retrying."
- Run
Await CI (FR-ATOM-PUSH.CI-AWAIT)
- Read AGENTS.md
## CI/CDsection.- Absent: output
No CI declared in AGENTS.md — skipping CI await.and continue to step 7 (`7. Hand off to the next phase
- Absent: output
- Final report: target branch, upstream, pushed SHA, post-push verification result, CI await result (
skipped,green, ornot reached — stopped earlier). - Announce: "Push complete; entering the next phase of the composite workflow."
- Do NOT issue a TOTAL STOP, and do NOT wait for the user to tell you to carry on. The push report reads like the end of the work — in
shipandship-taskthe Reflect Phase follows it, in this same turn.`).- Malformed (missing either
Provider:orStatus command:): STOP with## CI/CD section is malformed — required keys: Provider, Status command. Found: <list of present keys>.Do NOT silently fall back. Do NOT continue to step 7. - Well-formed: continue.
- Malformed (missing either
- Resolve tunables (optional keys in
## CI/CD):Poll interval:— seconds between status polls. Default60. Accept integer seconds; a value<5is treated as malformed and STOPs the atom.Wall-clock budget:— soft cap on total await time. Default1800(30 min). Accept integer seconds.- Compute
ITER_CAP = max(1, ceil(<budget> / <poll interval>)). The iteration count — NOT wall-clock — bounds the cap so it stays deterministic across IDE-harness latencies. With defaults,ITER_CAP = 30; a project that setsPoll interval: 10andWall-clock budget: 60getsITER_CAP = 6.
- Export the pushed SHA into the environment:
export SHA=$(git rev-parse HEAD). All CI commands below inherit$SHAfrom the agent's shell. - Detect run trigger (≤60 s window; sized at ~2× the slowest realistic provider lag, observed ~30 s for GitLab pipelines registering after push): invoke the
Status command. Treat:- exit 0 or 1 (terminal on first call) → proceed straight to the poll loop branch.
- exit 2 (in-progress — a run exists) → proceed to the poll loop.
- any other exit → sleep 5 s and retry. After 12 retries (60 s) with no run detected, STOP with
CI declared but no run was triggered by $SHA within 60 s — verify the workflow trigger configuration.Do NOT continue to step 7.
- Poll loop (max
ITER_CAPiterations ×<poll interval>s sleep ≈<wall-clock budget>wall-clock):- Invoke the
Status command. - exit 0 → CI green. Continue to step 7.
- exit 1 → CI red (terminal failure). Go to Investigate Handoff below.
- exit 2 → still running. Sleep
<poll interval>s. Re-invoke. Increment iteration counter. - any other exit → treat as a malformed Status command, STOP with the raw exit code and stderr.
- Invoke the
- Iteration cap (anomaly): if
ITER_CAPiterations completed without a terminal status (exit 0 or 1), STOP with a loud single-line message:CI ANOMALY: <ITER_CAP> iterations × <poll interval>s = <budget>s elapsed without a terminal verdict. Run URL: <result of Run URL command if defined, otherwise "not available">. Last status exit: 2 (in-progress). Treat as an incident (hanging job, queue starvation, runner outage) — do NOT continue silently.Do NOT invokeinvestigate(no failed-job logs to feed it yet — the build is still running, not red). Do NOT continue to step 7. The user owns the next action: extend the budget by re-running the atom after raisingWall-clock budget, cancel the CI run, or investigate the runner. - Investigate Handoff (CI red):
- If the
Logs commandis defined in AGENTS.md, execute it. Capture stdout. Truncate to 12 KB (investigatecan fetch more via the run URL if it needs to drill deeper). - If the
Run URL commandis defined, execute it. Capture stdout as the run URL. - Do NOT assume the working tree is clean:
@{u} == HEAD(step 5) proves only that the commit reached the remote, and a push leaves uncommitted work in place. The investigation therefore runs in a temporary worktree of the pushed commit, which is clean by construction; the handoff prompt below says so. Do NOT stash, reset, restore or commit the developer's uncommitted files to make the tree clean. - Invoke the
investigateskill via the host IDE's skill-invocation primitive (Skill tool //flowai:investigateslash command / inline expansion of itsSKILL.md) with this prompt:CI failed for commit $SHA on branch <CURRENT>. Run URL: <URL or "not available">. Failed-job logs (truncated to 12 KB):\n<LOGS or "not available">\nDiagnose the root cause in a temporary git worktree of $SHA (git worktree add <scratch dir> $SHA), not in the current working tree, and remove that worktree when done. Do not apply a fix; report findings. - After
investigatereturns its report, STOP. Do NOT continue to step 7 — the push succeeded but the build is broken; the user owns the remediation decision.
- If the
- Read AGENTS.md
**7. Hand off to the next phase
- Final report: target branch, upstream, pushed SHA, post-push verification result, CI await result (
skipped,green, ornot reached — stopped earlier). - Announce: "Push complete; entering the next phase of the composite workflow."
- Do NOT issue a TOTAL STOP, and do NOT wait for the user to tell you to carry on. The push report reads like the end of the work — in
shipandship-taskthe Reflect Phase follows it, in this same turn.**
- Final report: target branch, upstream, pushed SHA, post-push verification result, CI await result (
Push → Archive Gate
- The push report is not the end of the run. The next phase here is the Archive Phase below; it runs in this same turn, without waiting for the user to ask for it.
- You are only here if the push succeeded and
git rev-parse @{u}equalsHEAD, or the Push Phase was skipped because the repository has no remote. A failed push, a CI failure handed to an investigation, or a CI anomaly is a STOP (rule 5) and never arrives here.
Archive Phase
Send the final report first
- Archiving can end the conversation, so the report goes out before it:
- Goals: the goal report from the Goals Phase in full — the verdict line, then one entry per goal with its status and the evidence you observed (the command and its result, or the file). A verdict line alone is not enough: this is where the user sees what was checked. Name any goal the user chose to leave unmet.
- Commit: the commits made, or "nothing to commit".
- Push: branch, upstream, pushed SHA, or why there was no push.
- Archiving can end the conversation, so the report goes out before it:
Check what would be lost
- Run
git status --porcelain. On some hosts archiving a session also removes its working copy, and uncommitted files go with it. - The output is empty → continue with step 3.
- Files are listed → name them and ask once: "These files are not committed and may be removed together with the session. Archive anyway?" Wait for the reply. A refusal → say that the session stays open and STOP.
- Run
Archive the session with the host's own means
- Look at the tools you have in this session for one that archives or closes the CURRENT session (e.g. a session-archive tool in the Claude desktop app). Decide from the tool list alone; do not search the file system for a way.
- Such a tool exists → call it for the current session. The invocation of this workflow is the user's request to archive; if the host asks the user for its own approval, that is the host's step, not yours. This call is the last action of the run — write nothing after it. If the host refuses or the user declines the approval, say so in one line and stop.
- No such tool → say in one line that this host gives you no way to archive the session from inside it, and that the user can archive or close it in the host's interface. Then stop.
- Never substitute something else for it: do NOT delete or move session transcripts, do NOT remove branches or worktrees, do NOT clear the conversation.