aif-done

name	aif-done
description	Finalize a verified OpenSpec-native change or legacy AI Factory-only plan, prepare commit/PR summaries, and drive evidence-backed follow-ups.
version	1.2.0
author	ichi

AIF Done

AIFHub/Handoff finalization skill. Finalizes a verified OpenSpec-native change or a legacy AI Factory-only plan, drafts commit and PR summaries, drives evidence-backed governance follow-ups, and can run or recommend evolution follow-ups.

This skill does not duplicate /aif-verify — it runs after a passing verification (PASS or PASS-with-notes).

Resolve mode from .ai-factory/config.yaml:

• Use OpenSpec-native mode when aifhub.artifactProtocol: openspec.
• Use Legacy AI Factory-only mode otherwise.

OpenSpec-native mode

OpenSpec-native mode finalizes the verified change state through scripts/openspec-done-finalizer.mjs. It is the only OpenSpec-native archive/finalization step after /aif-verify passes.

Preconditions

• Resolve exactly one active change or explicit <change-id>.
• Read QA evidence from .ai-factory/qa/<change-id>/.
• Treat verification as passing only when QA evidence clearly records a final PASS or PASS-with-notes for this change.
• Require the latest final fenced aif-gate-result block in verify.md to be valid JSON with "gate": "verify" and status of pass or warn.
• Require .ai-factory/qa/<change-id>/coverage.json to exist, be current, and have coverage status pass or policy-accepted warn.
• If verification has not run or verdict is fail, stop and suggest /aif-verify or /aif-fix.
• If the verify gate result is missing, invalid, or fail, stop and suggest rerunning /aif-verify <change-id> or /aif-fix <change-id>.
• If coverage is missing, invalid, stale, or failed by policy, stop and suggest rerunning /aif-verify <change-id>.
• Refuse unverified changes; do not accept Code verification: PENDING as final verification.
• Check dirty working tree state before archive and either fail or record it only when explicit dirty-state recording is requested.

Canonical Context

Read canonical OpenSpec artifacts:

• openspec/specs/**
• openspec/changes/<change-id>/proposal.md
• openspec/changes/<change-id>/design.md
• openspec/changes/<change-id>/tasks.md
• openspec/changes/<change-id>/specs/**/spec.md

Read generated rules as derived guidance when present:

• .ai-factory/rules/generated/openspec-merged-<change-id>.md
• .ai-factory/rules/generated/openspec-change-<change-id>.md
• .ai-factory/rules/generated/openspec-base.md

Runtime state and QA evidence live outside canonical changes:

• .ai-factory/state/<change-id>/
• .ai-factory/qa/<change-id>/, including verify.md and coverage.json

Archive Policy

• Archive through archiveOpenSpecChange(changeId, options) from scripts/openspec-runner.mjs; this corresponds to openspec archive <change-id> --yes.
• Use archiveOpenSpecChange(changeId) for normal finalization.
• Use archiveOpenSpecChange(changeId, { skipSpecs: true }) for docs/tooling-only finalization; this corresponds to openspec archive <change-id> --yes --skip-specs --no-color.
• Support the user-facing --skip-specs path while still writing final QA evidence and final summaries.
• If OpenSpec CLI is missing or unsupported and archive is required, fail with an explicit OpenSpec CLI requirement.
• Do not archive in /aif-verify; /aif-verify does not archive and only records verification evidence.
• Do not use legacy .ai-factory/specs archive in OpenSpec-native mode.
• OpenSpec-native mode does not use legacy .ai-factory/specs archive.
• Do not silently archive OpenSpec changes through legacy .ai-factory/specs.
• Do not write runtime-only output into openspec/changes/<change-id>/.
• Do not directly mutate openspec/specs/** or manually move OpenSpec change folders.

OpenSpec-Native Output

Normal output must report:

• selected change-id;
• verification status and refusal reason when unverified;
• dirty working tree state;
• archive result;
• canonical artifacts inspected;
• generated rules state when relevant;
• runtime state and QA evidence paths;
• final evidence under .ai-factory/qa/<change-id>/;
• final summaries under .ai-factory/state/<change-id>/;
• commit/PR summary draft;
• next steps: /aif-mode sync, /aif-commit, and optional /aif-evolve.

Post-Finalization Handoff

After successful finalization:

1. Recommend /aif-mode sync to refresh derived artifacts after archive.
2. Recommend /aif-commit as the next AI Factory command.
3. Optionally recommend /aif-evolve when durable learning evidence exists.
4. Do not create commits automatically.
5. Do not create PRs automatically.
6. /aif-done does not replace /aif-commit.

Legacy AI Factory-only mode

Legacy AI Factory-only mode preserves the verified plan finalization contract based on .ai-factory/plans/<plan-id>/ and .ai-factory/specs/<plan-id>/.

Precondition

• Active plan must have a passing verification state (pass or pass-with-notes).
• If verification has not run or verdict is fail, this skill stops and suggests running /aif-verify first.

Workflow

Step 1: Validate Precondition

1. Resolve the active plan (same resolution logic as /aif-implement).
2. Read status.yaml and check verification.verdict.
3. If verdict is missing or not pass/pass-with-notes:
   • Stop with message: "Plan has not passed verification. Run /aif-verify first."
4. Check workspace state:
   • If git status shows uncommitted changes outside the current plan scope:
     • Stop and ask the user to confirm or clean up.
     • Only plan-related changes (files touched by the plan's implementation) are acceptable without confirmation.

Step 2: Archive Plan

1. Resolve archive path: .ai-factory/specs/<plan-id>/.
2. Idempotency check: If .ai-factory/specs/<plan-id>/ already exists:
   • Treat the run as a refresh/finalize-again pass.
   • Rebuild spec.md, refresh the index entry, and regenerate commit/PR/follow-up outputs from current plan evidence.
   • If the archive came from legacy /aif-verify auto-archive behavior, adopt it instead of failing or blindly re-copying.
   • Inform the user that finalization is refreshing an existing archive.
3. If archive does not exist:
   • Copy plan folder contents (minus status.yaml execution metadata) into the archive.
   • Archive the companion plan file as plan.md alongside the folder artifacts.
4. Create or update spec.md summarizing what was implemented, if part of the current contract.
5. Update .ai-factory/specs/index.yaml with the new entry.

Step 3: Prepare Commit Message

1. Analyze all changes made under this plan.
2. Draft a conventional commit message summarizing the implementation.
3. Present the draft to the user for review.

Step 4: Prepare PR Summary (if applicable)

1. Check if a feature branch exists (branch != main/master).
2. If gh CLI is available:
   • Draft PR title and body based on plan scope and implementation evidence.
   • Present the draft; do not create the PR automatically.
3. If gh is not available:
   • Output manual PR instructions with the drafted title and body.

Step 5: Apply Evidence-Driven Follow-ups

1. Check plan for evidence of:
   • roadmap milestone completion or maturity movement;
   • new architecture decisions, boundaries, or modules;
   • new or modified durable project rules;
   • evolution candidates worth feeding into /aif-evolve.
2. Apply follow-ups only when the evidence exists:
   • Roadmap -> update through the roadmap owner or return an exact /aif-roadmap handoff.
   • Architecture -> update through the architecture owner or return an exact /aif-architecture handoff.
   • Rules -> update the project rules owner path or return an exact handoff if direct update is not safe in the current runtime.
3. If the current runtime cannot safely perform the owner update, do not silently skip it — return the exact next command/instruction instead.
4. Run /aif-evolve when the user explicitly asked for integrated finalization and the runtime can chain the action; otherwise propose it as the next step.
5. Never invent governance changes that are not supported by plan evidence.

Step 6: Mark Plan Done

1. Update status.yaml:
   • Set status: done.
   • Record finalization timestamp.
2. Output completion summary:
   • Archive path.
   • Commit message draft.
   • PR summary draft (or manual instructions).
   • Governance updates performed or exact handoffs prepared.
   • /aif-evolve action taken or recommended.

Ownership Boundary

Artifact	Owner	This Skill
openspec/changes/<change-id>/	OpenSpec-native workflow	Reads before archive; OpenSpec CLI owns lifecycle mutation
.ai-factory/qa/<change-id>/	/aif-verify and aif-done	Reads verification and coverage evidence; writes done.md, openspec-archive.json, and raw archive output
.ai-factory/state/<change-id>/	OpenSpec-native runtime and aif-done	Reads traces; writes final-summary.md
.ai-factory/specs/<plan-id>/	aif-done legacy mode only	Creates or refreshes on legacy finalization
.ai-factory/specs/index.yaml	aif-done	Updates
.ai-factory/plans/<plan-id>/status.yaml	aif-done	Updates status: done
Commit/PR drafts	aif-done	Outputs to user
.ai-factory/ROADMAP.md	roadmap owner	Update only with plan-backed evidence; otherwise hand off
.ai-factory/RULES.md	project rules owner	Update only for durable plan-backed rules; otherwise hand off
.ai-factory/ARCHITECTURE.md	architecture owner	Update only with plan-backed evidence; otherwise hand off

Rules

• Never finalize a plan that has not passed verification.
• In OpenSpec-native mode, never finalize an unverified change.
• In OpenSpec-native mode, never finalize a change with missing, stale, invalid, or failed coverage.json.
• In OpenSpec-native mode, archive only through archiveOpenSpecChange; never use custom OpenSpec archive logic.
• In OpenSpec-native mode, never silently archive through legacy .ai-factory/specs.
• Never invent governance changes without evidence from the verified plan.
• When governance updates belong to another owner, use the owning path or return an exact handoff instead of silently skipping the change.
• Never auto-create a PR — always present drafts for user approval.
• Never create commits from /aif-done; hand commit creation to /aif-commit or the user's normal git workflow.
• If gh is unavailable, provide manual instructions instead of failing.
• Keep direct archival writes bounded to the plan status, specs directory, and specs index.
• Do not reintroduce /aif-done as the canonical upstream workflow step, and do not present /aif-done as replacing /aif-commit.

Example Requests

• "Finalize this plan."
• "Archive the verified plan."
• "Prepare commit and PR summary."
• "/aif-done"