skills.rest
Priivacy-ai
Priivacy-aiOFFICIAL
Explore all skills by this author →
GitHub

spk-run-next

Drives the spec-kitty next control loop and routes query, step, blocked, and terminal results.

1.6k|156|Updated Oct 9, 2025
Search Tags:#agent workflow#CLI#mission#work packages#control loop#spec-kitty#spec-Driven Development
One-click install
npx skills add https://github.com/Priivacy-ai/spec-kitty --skill spk-run-next
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: spk-run-next
Source: https://github.com/Priivacy-ai/spec-kitty/tree/main/src/charter/offering/skills/spk-run-next
Command: npx skills add https://github.com/Priivacy-ai/spec-kitty --skill spk-run-next

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

When running spec-driven missions with spec-kitty, agents need a deterministic way to know what to do next, how to advance work packages, and how to recover from blocked or decision-pending states without guessing.

Core Features & Use Cases

  • State Querying: Inspect the current mission state with spec-kitty next --mission <handle> --json without executing anything.
  • Step Advancement: Advance a mission by reporting agent results (success, failed, blocked) and executing the generated prompt file for step decisions.
  • Decision & Error Routing: Answer pending runtime decisions with --answer and --decision-id, fix guard failures on blocked results, and route terminal results to the acceptance gate.
  • Use Case: An agent finishes a work package in an isolated git worktree and asks what to do next; this skill queries the mission, receives a step decision, executes the generated prompt, and reports the result back to the control loop.

Quick Start

Ask the agent to check what comes next for the active mission by running the spec-kitty next command with the mission handle and then follow the returned decision kind.

Frequently Asked Questions about spk-run-next

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I advance a spec-kitty mission to the next step?▼

Run `spec-kitty next --agent <name> --mission <handle> --result <success|failed|blocked>` to report the outcome of the current work. The command returns a decision kind that tells you whether to execute a generated prompt, answer a decision, or fix a guard failure.

How do I check mission status without changing anything?▼

Use `spec-kitty next --mission <handle> --json` to query the current state. A `query` decision kind is inspect-only, so you should not execute a prompt or mark a result in that case.

What should I do when spec-kitty next returns decision_required?▼

Answer the pending runtime decision by passing `--answer`, `--result`, `--agent`, and `--decision-id` when multiple decisions are pending. This resolves the decision and lets the control loop continue.

Why does spec-kitty next return a blocked result?▼

A `blocked` decision kind means guard failures prevented the mission from advancing. Fix the reported guard failures first, then retry the next command with the appropriate result.

What happens when a spec-kitty mission reaches a terminal state?▼

A `terminal` decision kind means the mission work is complete and should be routed to the acceptance gate. Use the spk-gate-accept skill to handle review and acceptance of the finished work.

Related Skills

Explore More Software Engineering Skills→
JonusNattapongJonusNattapong

agenttalk-sk-loop

Manage persistent task implementation and review loops for spec-kitty missions via agenttalk.

Community
Advanced
fagemxfagemx

wusanto-scribe

Standardize acceptance and gate review for AI-generated deliverables.

Community
Advanced
akornmeierakornmeier

worktree-manager-skill

Manage Git worktree lifecycles with unique port allocations and services.

Community
Advanced
kimprobablykimprobably

spec-kitty-runtime-next

Execute spec-kitty next runtime decisions for mission step advancement.

Community
Advanced