spec-kitty.tasks-finalize
Validate dependencies, finalize WP metadata, and commit all task artifacts.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- spec-kitty.tasks-finalize
- description
- Validate dependencies, finalize WP metadata, and commit all task artifacts.
- user-invocable
- true
03 SKILL.md 正文
Startup Upgrade Check
Run this at most once per active agent session before the first Spec Kitty command workflow.
If you already ran spec-kitty upgrade --agent-check --json in this session, reuse that result and skip this block.
Do not run or announce an upgrade check again for later Spec Kitty commands in the same session.
Otherwise, before continuing, run:
spec-kitty upgrade --agent-check --json
If JSON action is none, continue.
If action is auto_upgrade, run upgrade_command before continuing. If it fails, tell the user and continue with the current Spec Kitty version.
If action is guidance, show upgrade_note briefly, then continue.
If action is prompt, ask the user with the host-native question UI when available:
Spec Kitty {latest_version} is available. You are on {installed_version}. Upgrade now?
Use these choices:
- Upgrade now (recommended) - record
upgrade_now, runupgrade_command, then continue. - Always keep me up to date - record
always, runupgrade_command, then continue. - Not now - record
not_now, then continue. - Never ask again - record
never_ask, then continue.
Record the selected choice before continuing:
spec-kitty upgrade --agent-choice <upgrade_now|always|not_now|never_ask> --agent-latest <latest_version> --json
If no host-native question UI is available, present the same four choices in plain text and wait for the user.
In non-interactive hosts, choose not_now and continue.
/spec-kitty.tasks-finalize - Finalize Tasks
Version: 3.2.0
Purpose
Run the finalization command to parse dependencies from tasks.md, validate
them, update WP frontmatter, and commit all task artifacts to the target branch.
📍 WORKING DIRECTORY: Stay in the repository root checkout
IMPORTANT: This step works in the repository root checkout. NO worktrees created.
User Input
The content of the user's message that invoked this skill (everything after the skill invocation token, e.g. after /spec-kitty.<command> or $spec-kitty.<command>) is the User Input referenced elsewhere in these instructions.
You MUST consider this user input before proceeding (if not empty).
Steps
1. Run Validate-Only Preflight
CRITICAL: Run this preflight command from repo root before any mutating finalization:
spec-kitty agent mission finalize-tasks --validate-only --mission <mission-slug> --json
This command will:
- Parse dependencies from tasks.md
- Parse
Requirement Refsfrom tasks.md - Preview WP frontmatter updates without writing files
- Validate dependencies (check for cycles, invalid references)
- Validate requirement mapping:
- Every WP has at least one accepted requirement reference (a declared FR, NFR, C or SC; a
<mission-slug>#<ID>citation does not count) - Every ref gets one verdict:
malformedandunknown_spec_idfail;foreign_qualified(another mission's ID) never fails; valid refs always count - Every functional requirement declared in spec.md (
FR-###, including one with a lowercase letter suffix such asFR-###a) is mapped to at least one WP - Declared success criteria (
SC-###) are tracked, not gating: they appear insuccess_criteria_coveragebut never fail validation
- Every WP has at least one accepted requirement reference (a declared FR, NFR, C or SC; a
- Keep every authored
requirement_refsitem: finalize never erases or rewrites refs
If the JSON output contains "error": "Requirement mapping validation failed",
do not run finalization. Report the blocking fields
(missing_requirement_refs_wps, unknown_requirement_refs,
unmapped_functional_requirements, and rejected_requirement_refs with each
ref's reason), compare them with parsed_spec_ids (the IDs finalize read from
spec.md, grouped by kind), then fix mappings with
spec-kitty agent tasks map-requirements --mission <mission-slug> --json or by
updating WP requirement_refs.
1b. Ownership Overlap — domain-focused / refactor missions
If validate-only fails with "error": "Ownership validation failed" and
ownership_errors listing overlapping owned_files:
Ownership collisions are EXPECTED for domain-focused and refactor-oriented missions (cross-cutting strangler work, repo-wide migrations, boundary enforcement) where many work packages legitimately edit the same files. This is not a defect in the slicing. Handle it as follows:
- Linearize shared surfaces (execution safety). Work packages that touch the
same files MUST be made dependent/linear (via
Depends on WPxx) so they execute sequentially in one lane and share a single worktree (or run direct-to-branch). Limited parallelism is acceptable and expected for these missions — do not force artificial parallelism. Note: linearization protects the worktree from concurrent edits; it does not by itself satisfy ownership validation (see step 3). - Declare cross-cutting WPs codebase-wide (the exemption). A WP that is
expected to overlap broadly should carry
scope: codebase-widein its frontmatter; the ownership validator exempts codebase-wide WPs from overlap and authoritative-surface checks. Keep the genuinely-targeted WPs (single test file, single module) narrow and mutually disjoint. codebase-wideis the ONLY exemption. Two narrow WPs that claim the same files always fail ownership validation — regardless of whether they sit in different lanes or are linked in a dependency hierarchy. Dependency/lane structure never bypasses the overlap check. If WPs legitimately share a surface, mark the broadly-overlapping onescope: codebase-wide; otherwise re-slice so the narrow WPs are disjoint.
Do not fabricate disjoint owned_files that misrepresent which WP edits
which files solely to pass validation — linearize and/or declare codebase-wide
instead.
2. Run Finalization Command
Only after validate-only exits successfully, run the mutating finalization command from repo root:
spec-kitty agent mission finalize-tasks --mission <mission-slug> --json
This command will update WP frontmatter, compute lanes, and commit all tasks to the target branch.
3. Check Output
The JSON output includes:
"commit_created": true/false— whether a commit was made"commit_hash"— the commit hash if created"wp_count"— number of WP files processed"dependencies_parsed"— dependency relationships found"requirement_refs_parsed"— requirement reference mapping found"ownership_warnings"— soft warnings (glob-pattern zero-match, audit coverage)"parsed_spec_ids"— requirement IDs parsed from spec.md, grouped asfunctional,non_functional,constraint,success_criteria"rejected_requirement_refs"— per WP, each unusable ref with one reason:malformed,unknown_spec_idorforeign_qualified"success_criteria_coverage"— informational:referenced(SC → WPs) andunreferenced; never fails the run- Validation details when checks fail (
missing_requirement_refs_wps,unknown_requirement_refs,unmapped_functional_requirements,rejected_requirement_refs)
CRITICAL — Ownership warnings require action before proceeding:
If ownership_warnings is non-empty, or if the command emits ERROR: Ownership
lines to stderr, you MUST act on each issue before starting implementation:
-
Hard error (
ownership_literal_path_errorspresent, exit 1): Aowned_filesentry is a literal file path that does not exist in the repository. Fix by:- Correcting the path (typo / wrong relative path), or
- Adding the path to
create_intentin the WP frontmatter if the file will be created by this WP (planned-new-file).
Do NOT proceed to implement while any hard error is present.
-
Soft warning (
ownership_warningsnon-empty, exit 0): Aowned_filesglob pattern matched zero files. This may indicate in-flight work. Verify the pattern is correct and adjust if needed before starting implementation.
Example create_intent frontmatter for a planned-new-file entry:
owned_files:
- "src/app/new_module.py"
create_intent:
- "src/app/new_module.py" # will be created by this WP
4. Verify
IMPORTANT — DO NOT COMMIT AGAIN AFTER THIS COMMAND:
finalize-taskscommits the files automatically- If
commit_created=true, files are ALREADY committed — do not rungit commitagain - Other dirty files shown by
git status(templates, config) are UNRELATED - Verify using the
commit_hashfrom JSON output, not by runninggit add/commitagain
5. Report
Provide a concise outcome summary:
- Path to
tasks.md - Work package count and per-package subtask tallies
- Parallelization highlights
- MVP scope recommendation
- Finalization status (dependencies parsed, X WP files updated, committed to target branch)
Required next step — run /spec-kitty.analyze before /spec-kitty.implement.
/spec-kitty.analyze persists an analysis-report.md and reviews spec/plan/tasks
consistency; /spec-kitty.implement refuses to claim a work package
(analysis_report_required) until that report exists — analyze is not optional, it
is the readiness gate implement enforces. The report is current only while the
spec, plan, tasks and charter are unchanged: editing any of them after analyze
makes the report stale, and implement refuses again until you re-run
/spec-kitty.analyze.
Output
After completing this step:
- All WP files have
dependenciesfield in frontmatter - All WP files have
requirement_refsfield in frontmatter - Dependencies are validated (no cycles, no invalid references)
- Requirement references are validated against spec.md
- Task artifacts are committed to the target branch
Next step: run /spec-kitty.analyze — the required pre-implementation gate —
then /spec-kitty.implement.
04 同仓库更多 Skills
kitty-semi-auto
Use to take a tracker issue or a coherent issue-set through a governed delivery run that works autonomously but pauses to escalate the operator's decisions. Runs BOTH ways — in this session (local) or handed to a fresh cloud runner (cloud) — from one set of standing orders covering orientation, code grounding first, Mission-vs-Ops, the pause-and-escalate contract, brownfield discipline, and the canonical closeout to a draft PR the operator merges. Triggers: semi-auto, semi-auto dispatch, run this semi-automatically, deliver these issues semi-auto, hand this to a cloud runner, dispatch semi-auto.
kitty-report-debrief
Use when a maintainer asks what happened or what is open ("what landed since Friday", "WTF happened with X", a milestone overview). Collects the facts from GitHub, writes a short branded debrief for named readers, and hands the PDF back without committing it. Triggers: what landed since, WTF happened, debrief the weekend, milestone overview, exec overview of open issues, write up what shipped.
kitty-mission-from-issue
Use to take one or more GitHub issues through a full governed Mission (spec, plan, tasks, implementation, review) to a green pull request flipped to ready for review, which a maintainer then merges. Triggers: mission from issue, run a mission for this issue, drive issue to PR.
kitty-land-pr
Use when a ready-for-review pull request needs a maintainer to get it ready to merge. Rebases it, fixes and reviews it, updates its description, changelog and docs, and hands it back without merging by hand. Triggers: land this PR, landing pass, land PR.
kitty-issue-triage
Use to triage a batch of open GitHub issues on spec-kitty/spec-kitty (default, those opened in the last 7 days). Sets type, priority, domain, parent and milestone, and reports stale, duplicate or clustered issues for an operator decision. Triggers: triage issues, triage the tracker, triage new issues.
spk-team-tracker
暂无简介