Table of Contents

Agent Subcommand Reference

The spec-kitty agent commands are designed for AI agents and automation tooling. They generally emit JSON and update task metadata or feature artifacts directly.

spec-kitty agent

Synopsis: spec-kitty agent [OPTIONS] COMMAND [ARGS]...

Description: Commands for AI agents to execute spec-kitty workflows programmatically.

Options:

Flag Description
--help Show this message and exit

spec-kitty agent feature

Synopsis: spec-kitty agent feature [OPTIONS] COMMAND [ARGS]...

Description: Feature lifecycle commands for AI agents.

Subcommands:

  • create-feature
  • check-prerequisites
  • setup-plan
  • accept
  • merge
  • finalize-tasks

spec-kitty agent feature create-feature

Synopsis: spec-kitty agent feature create-feature [OPTIONS] FEATURE_SLUG

Description: Create new feature directory structure in main repository.

Arguments:

  • FEATURE_SLUG: Feature slug (e.g., user-auth) [required]

Options:

Flag Description
--json Output JSON format
--help Show this message and exit

Example:

spec-kitty agent feature create-feature "new-dashboard" --json

spec-kitty agent feature check-prerequisites

Synopsis: spec-kitty agent feature check-prerequisites [OPTIONS]

Description: Validate feature structure and prerequisites.

Options:

Flag Description
--json Output JSON format
--paths-only Only output path variables
--include-tasks Include tasks.md in validation
--help Show this message and exit

Examples:

spec-kitty agent feature check-prerequisites --json
spec-kitty agent feature check-prerequisites --paths-only --json

spec-kitty agent feature setup-plan

Synopsis: spec-kitty agent feature setup-plan [OPTIONS]

Description: Scaffold implementation plan template in main repository.

Options:

Flag Description
--json Output JSON format
--help Show this message and exit

Example:

spec-kitty agent feature setup-plan --json

spec-kitty agent feature accept

Synopsis: spec-kitty agent feature accept [OPTIONS]

Description: Perform feature acceptance workflow.

Options:

Flag Description
--feature TEXT Feature directory slug (auto-detected if not specified)
--mode TEXT Acceptance mode: auto, pr, local, checklist (default: auto)
--json Output results as JSON for agent parsing
--lenient Skip strict metadata validation
--no-commit Skip auto-commit (report only)
--help Show this message and exit

Examples:

spec-kitty agent feature accept
spec-kitty agent feature accept --json
spec-kitty agent feature accept --lenient --json

spec-kitty agent feature merge

Synopsis: spec-kitty agent feature merge [OPTIONS]

Description: Merge feature branch into target branch.

Options:

Flag Description
--feature TEXT Feature directory slug (auto-detected if not specified)
--target TEXT Target branch to merge into (default: main)
--strategy TEXT Merge strategy: merge, squash, rebase (default: merge)
--push Push to origin after merging
--dry-run Show actions without executing
--keep-branch Keep feature branch after merge (default: delete)
--keep-worktree Keep worktree after merge (default: remove)
--auto-retry, --no-auto-retry Auto-navigate to latest worktree if in wrong location (default: auto-retry)
--help Show this message and exit

Examples:

spec-kitty agent feature merge
spec-kitty agent feature merge --target develop --push
spec-kitty agent feature merge --dry-run
spec-kitty agent feature merge --keep-worktree --keep-branch

spec-kitty agent feature finalize-tasks

Synopsis: spec-kitty agent feature finalize-tasks [OPTIONS]

Description: Parse dependencies from tasks.md and update WP frontmatter, then commit to main.

Options:

Flag Description
--json Output JSON format
--help Show this message and exit

Example:

spec-kitty agent feature finalize-tasks --json

spec-kitty agent tasks

Synopsis: spec-kitty agent tasks [OPTIONS] COMMAND [ARGS]...

Description: Task workflow commands for AI agents.

Subcommands:

  • move-task
  • mark-status
  • list-tasks
  • add-history
  • finalize-tasks
  • validate-workflow
  • status

spec-kitty agent tasks move-task

Synopsis: spec-kitty agent tasks move-task [OPTIONS] TASK_ID

Description: Move task between lanes (planned -> doing -> for_review -> done).

Arguments:

  • TASK_ID: Task ID (e.g., WP01) [required]

Options:

Flag Description
--to TEXT Target lane (planned/doing/for_review/done) [required]
--feature TEXT Feature slug (auto-detected if omitted)
--agent TEXT Agent name
--assignee TEXT Assignee name (sets assignee when moving to doing)
--shell-pid TEXT Shell PID
--note TEXT History note
--review-feedback-file PATH Path to review feedback file (required when moving to planned from review)
--reviewer TEXT Reviewer name (auto-detected from git if omitted)
--force Force move even with unchecked subtasks or missing feedback
--auto-commit, --no-auto-commit Automatically commit WP file changes to main branch (default: auto-commit)
--json Output JSON format
--help Show this message and exit

Examples:

spec-kitty agent tasks move-task WP01 --to doing --assignee claude --json
spec-kitty agent tasks move-task WP02 --to for_review --agent claude --shell-pid $$
spec-kitty agent tasks move-task WP03 --to done --note "Review passed"

spec-kitty agent tasks mark-status

Synopsis: spec-kitty agent tasks mark-status [OPTIONS] TASK_IDS...

Description: Update task checkbox status in tasks.md for one or more tasks.

Arguments:

  • TASK_IDS...: Task ID(s) - space-separated (e.g., T001 T002 T003) [required]

Options:

Flag Description
--status TEXT Status: done or pending [required]
--feature TEXT Feature slug (auto-detected if omitted)
--auto-commit, --no-auto-commit Automatically commit tasks.md changes to main branch (default: auto-commit)
--json Output JSON format
--help Show this message and exit

Examples:

spec-kitty agent tasks mark-status T001 --status done
spec-kitty agent tasks mark-status T001 T002 T003 --status done --json

spec-kitty agent tasks list-tasks

Synopsis: spec-kitty agent tasks list-tasks [OPTIONS]

Description: List tasks with optional lane filtering.

Options:

Flag Description
--lane TEXT Filter by lane
--feature TEXT Feature slug (auto-detected if omitted)
--json Output JSON format
--help Show this message and exit

Examples:

spec-kitty agent tasks list-tasks --json
spec-kitty agent tasks list-tasks --lane doing --json

spec-kitty agent tasks add-history

Synopsis: spec-kitty agent tasks add-history [OPTIONS] TASK_ID

Description: Append history entry to task activity log.

Arguments:

  • TASK_ID: Task ID (e.g., WP01) [required]

Options:

Flag Description
--note TEXT History note [required]
--feature TEXT Feature slug (auto-detected if omitted)
--agent TEXT Agent name
--shell-pid TEXT Shell PID
--json Output JSON format
--help Show this message and exit

Example:

spec-kitty agent tasks add-history WP01 --note "Completed implementation" --json

spec-kitty agent tasks finalize-tasks

Synopsis: spec-kitty agent tasks finalize-tasks [OPTIONS]

Description: Parse tasks.md and inject dependencies into WP frontmatter.

Options:

Flag Description
--feature TEXT Feature slug (auto-detected if omitted)
--json Output JSON format
--help Show this message and exit

Examples:

spec-kitty agent tasks finalize-tasks --json
spec-kitty agent tasks finalize-tasks --feature 001-my-feature

spec-kitty agent tasks validate-workflow

Synopsis: spec-kitty agent tasks validate-workflow [OPTIONS] TASK_ID

Description: Validate task metadata structure and workflow consistency.

Arguments:

  • TASK_ID: Task ID (e.g., WP01) [required]

Options:

Flag Description
--feature TEXT Feature slug (auto-detected if omitted)
--json Output JSON format
--help Show this message and exit

Example:

spec-kitty agent tasks validate-workflow WP01 --json

spec-kitty agent tasks status

Synopsis: spec-kitty agent tasks status [OPTIONS]

Description: Display kanban status board for all work packages in a feature.

Options:

Flag Description
--feature TEXT, -f Feature slug (auto-detected if omitted)
--json Output as JSON
--help Show this message and exit

Examples:

spec-kitty agent tasks status
spec-kitty agent tasks status --feature 012-documentation-mission
spec-kitty agent tasks status --json

spec-kitty agent config

Synopsis: spec-kitty agent config [OPTIONS] COMMAND [ARGS]...

Description: Manage project AI agent configuration (add, remove, list, sync agents).

Subcommands:

Command Description
list View configured agents and available options
add Add one or more agents to your project
remove Remove one or more agents from your project
status Audit agent configuration sync status
sync Synchronize filesystem with config.yaml

See:

spec-kitty agent context

Synopsis: spec-kitty agent context [OPTIONS] COMMAND [ARGS]...

Description: Agent context management commands.

Subcommands:

  • update-context

spec-kitty agent context update-context

Synopsis: spec-kitty agent context update-context [OPTIONS]

Description: Update agent context file with tech stack from plan.md.

Options:

Flag Description
--agent-type TEXT, -a Agent type to update (default: claude)
--json Output results as JSON for agent parsing
--help Show this message and exit

Examples:

spec-kitty agent context update-context
spec-kitty agent context update-context --agent-type gemini --json

spec-kitty agent workflow

Synopsis: spec-kitty agent workflow [OPTIONS] COMMAND [ARGS]...

Description: Workflow commands that display prompts and instructions for agents.

Subcommands:

  • implement
  • review

spec-kitty agent workflow implement

Synopsis: spec-kitty agent workflow implement [OPTIONS] [WP_ID]

Description: Display work package prompt with implementation instructions.

Arguments:

  • WP_ID: Work package ID (e.g., WP01) - auto-detects first planned if omitted

Options:

Flag Description
--feature TEXT Feature slug (auto-detected if omitted)
--agent TEXT Agent name (required for auto-move to doing lane)
--help Show this message and exit

Examples:

spec-kitty agent workflow implement WP01 --agent claude
spec-kitty agent workflow implement --agent gemini

spec-kitty agent workflow review

Synopsis: spec-kitty agent workflow review [OPTIONS] [WP_ID]

Description: Display work package prompt with review instructions.

Arguments:

  • WP_ID: Work package ID (e.g., WP01) - auto-detects first for_review if omitted

Options:

Flag Description
--feature TEXT Feature slug (auto-detected if omitted)
--agent TEXT Agent name (required for auto-move to doing lane)
--help Show this message and exit

Examples:

spec-kitty agent workflow review WP01 --agent claude
spec-kitty agent workflow review --agent gemini

spec-kitty agent release

Synopsis: spec-kitty agent release [OPTIONS] COMMAND [ARGS]...

Description: Release packaging commands for AI agents.

Options:

Flag Description
--help Show this message and exit

Notes:

  • No subcommands are currently exposed in v0.11.0.

Getting Started

Practical Usage

Edit this page