Spec Kitty Workflow

Standard lifecycle for implementing features using Spec Kitty.

Command-specific guidance: For detailed best practices on individual commands, see the AUGMENTED.md files co-located with each auto-synced command:

skills/spec-kitty-merge/references/AUGMENTED.md — pre-merge safety, branch protection, conflict resolution
skills/spec-kitty-implement/references/AUGMENTED.md — worktree discipline, commit hygiene
skills/spec-kitty-review/references/AUGMENTED.md — review standards, batch review protocol

🚫 CRITICAL: Anti-Simulation Rules & Escalation Taxonomy

YOU MUST ACTUALLY RUN EVERY COMMAND LISTED BELOW. Describing what you "would do", summarizing expected output, or marking a step complete without pasting real tool output is a PROTOCOL VIOLATION.

Proof = pasted command output. No output = not done.

Escalation Taxonomy (Protocol Violation Response)

If you detect a tool or user attempting to bypass the closure protocol or manually create spec files, you MUST interrupt the workflow using the strict 5-step Escalation Protocol:

Stop: Halt workflow creation immediately.
Alert: Loudly print: 🚨 PROTOCOL VIOLATION 🚨.
Explain: State precisely which rule was broken (e.g., "Cannot skip review.").
Recommend: Output the standard operating procedure (e.g., "Please submit WP-xx for review: spec-kitty review WP-xx").
Draft: Refuse to execute the dangerous command until the state is fixed.

Anti-Pattern Vaccination (Known Agent Failure Modes)

Checkbox theater: Marking [x] without running the command or verification tool
Manual file creation: Writing spec.md/plan.md/tasks.md by hand instead of using CLI
Kanban neglect: Not updating task lanes, so dashboard shows stale state
Closure amnesia: Finishing code but skipping review/merge/closure steps
Phase skipping: Advancing from specify -> plan -> tasks -> implement without user approval at each gate (see Human Gate below)

🔴 THE HUMAN GATE (Constitutional Supreme Law)

NEVER advance between phases without EXPLICIT user approval. Approval means: "Proceed", "Go", "Execute", or equivalent affirmative command. "Sounds good", "Looks right", "That's correct" are NOT approval. VIOLATION = SYSTEM FAILURE

Required Approval Gates

Gate	After	Before	What to Show User
Gate 0	You write s spec	Planning any plan	Show spec.md, ask for approval
Gate 1	User approves spec	You write a plan	Show plan.md, ask for approval
Gate 2	User approves plan	You generate tasks/WPs	Show tasks.md + WP list, ask for approval
Gate 3	User approves tasks	You run `spec-kitty implement`	Confirm WP scope, ask to proceed
Gate 4	WP implementation done	You move to for_review	Show what was built, ask for review

Gate Enforcement Rule (MANDATORY)

After each phase-generating step:

STOP - Do not run the next phase command
SHOW - Present the artifact to the user
WAIT - End your turn with explicit request for approval
PROCEED only on explicit approval word ("Proceed", "Go", "Execute")

❌ WRONG: spec -> plan -> tasks -> implement (all in one agent turn)
✅ RIGHT: spec -> [STOP, show spec, wait] -> plan -> [STOP, show plan, wait] -> tasks

0. Mandatory Planning Phase (Do NOT Skip)

Before implementing any code, you MUST generate artifacts using the CLI. Manual creation of spec.md, plan.md, or tasks/ files is STRICTLY FORBIDDEN.

Pre-Execution Workflow Commitment

Visual Reference: pure-spec-kitty-workflow.mmd This diagram shows the full lifecycle including all HITL Gate nodes (red diamonds) where agent execution MUST stop and wait for user approval before advancing.

Before starting, display the following visual map to commit to the workflow state:

┌────────────────────────────────────────────────────────┐
│               SPEC-KITTY LIFECYCLE MAP                 │
├────────────────────────────────────────────────────────┤
│ [ ] Phase 0: Plan (specify -> plan -> tasks)           │
│ [ ] Phase 1: Implement (implement WP -> code -> review)│
│ [ ] Phase 2: Close (accept -> retro -> merge -> sync)  │
└────────────────────────────────────────────────────────┘

Check the box corresponding to your current execution phase.

Step 0a: Specify

To specify a feature, read the workflow instructions in .windsurf/workflows/spec-kitty.specify.md or use the CLI:

spec-kitty agent feature create-feature "<slug>"

PROOF: Paste output confirming spec.md was generated.

⛔ HUMAN GATE 0: Show the user spec.md and STOP. Do NOT proceed to plan until the user explicitly approves with "Proceed", "Go", or "Execute".

Step 0b: Plan

To plan a feature, read the workflow instructions in .windsurf/workflows/spec-kitty.plan.md or use the CLI:

spec-kitty agent feature setup-plan --feature <SLUG>

PROOF: Paste output confirming plan.md was generated.

⛔ HUMAN GATE 1: Show the user plan.md and STOP. Do NOT proceed to task generation until the user explicitly approves.

Step 0c: Tasks

To generate tasks, read the workflow instructions in .windsurf/workflows/spec-kitty.tasks.md.

/spec-kitty.tasks

PROOF: Paste output confirming tasks.md and WP files were generated.

⛔ HUMAN GATE 2: Show the user tasks.md (the WP breakdown) and STOP. Do NOT run spec-kitty implement until the user explicitly approves.

1. Start a Work Package (WP)

Step 1a: Create worktree

spec-kitty agent workflow implement --task-id <WP-ID> --agent "<AGENT-NAME>"

PROOF: Paste the output. Extract the worktree path from it.

If output is truncated or unclear:

git worktree list

CRITICAL: Do NOT guess the path. Verify it exists before proceeding.

Step 1b: Update kanban

python3 .kittify/scripts/tasks/tasks_cli.py update <FEATURE-SLUG> <WP-ID> doing --note "Starting implementation"

PROOF: Paste the CLI output confirming lane change.

Then verify the board:

/spec-kitty.status

PROOF: Paste the kanban board. Confirm your WP shows in "doing" lane. STOP: Do NOT start coding until the kanban shows the WP in "doing".

2. Implementation Loop

Navigate: cd .worktrees/<WP-ID> — verify with pwd
Setup: Install dependencies if needed
Code: Implement the feature
Test: Run tests or manual verification
Commit: git add . && git commit -m "feat(<WP>): description" (local worktree)

3. Review & Handover

Pre-Review Checklist (verify ALL before proceeding)

All files committed in worktree (git status shows clean)
Worktree path confirmed (pwd matches .worktrees/<WP-ID>)
WP lane is doing (not already for_review or done)
No untracked files that should be committed

Step 3a: Verify clean state

Run git status to ensure all files are committed. PROOF: Paste the output. Must show "nothing to commit, working tree clean". STOP: Do NOT proceed if there are uncommitted changes.

Step 3b: Update kanban to for_review

python3 .kittify/scripts/tasks/tasks_cli.py update <FEATURE-SLUG> <WP-ID> for_review --note "Implementation complete, ready for review"

PROOF: Paste the CLI output.

Step 3c: Verify kanban updated

/spec-kitty.status

PROOF: Paste the board. WP must show in "for_review" lane.

Step 3d: Sync specs in main repo

cd <PROJECT_ROOT>
git add kitty-specs
git commit -m "docs(specs): mark <WP-ID> complete"

4. Deterministic Closure Protocol

CRITICAL: Every step below is MANDATORY. Skipping any step is a protocol violation. The closure chain is: Review → Accept → Retrospective → Merge → Verify → Intel Sync

Step 4a: Review each WP

spec-kitty agent workflow review --task-id <WP-ID>

PROOF: Paste the review output. WP must move to done lane.

Repeat for each WP. Verify all WPs are in done lane:

/spec-kitty.status

PROOF: Paste the board. ALL WPs must show in "done" lane before proceeding.

Step 4b: Accept feature

cd <PROJECT_ROOT>
spec-kitty accept --feature <SLUG>

The agent will ask for acceptance mode:

--mode local: Merge locally (no branch protection on target)
--mode pr: Push to feature branch and create PR (for protected branches)
--mode checklist: Readiness check only, no merge

PROOF: Paste the JSON output showing summary.ok: true.

Known Issue: Accept may fail with "missing shell_pid in WP frontmatter". Fix: Add shell_pid: N/A to the WP frontmatter, or use --lenient flag:
spec-kitty accept --mode local --feature <SLUG> --lenient

STOP: Do NOT proceed if accept fails. Resolve all outstanding issues first.

Step 4c: Retrospective (MANDATORY)

/spec-kitty_retrospective

PROOF: Paste confirmation that kitty-specs/<SPEC-ID>/retrospective.md was created/updated.

This step is NOT optional. Every feature closure MUST include a retrospective. The retrospective file MUST exist in kitty-specs/<SPEC-ID>/ before merge.

Step 4d: Pre-merge remote backup (MANDATORY)

⚠️ DATA SAFETY: Before ANY merge or worktree cleanup, ALL WP branches MUST be pushed to GitHub origin and verified. This prevents data loss if the merge fails or worktrees are deleted before content is preserved.

Push each WP branch to origin:

cd <PROJECT_ROOT>
for wt in .worktrees/<FEATURE>-WP*/; do
  branch=$(basename "$wt")
  echo "Pushing $branch..."
  git -C "$wt" push origin "$branch"
done

PROOF: Paste push output for each branch.

Verify remote state:

for wt in .worktrees/<FEATURE>-WP*/; do
  branch=$(basename "$wt")
  local_sha=$(git -C "$wt" rev-parse HEAD)
  remote_sha=$(git ls-remote origin "$branch" | cut -f1)
  if [ "$local_sha" = "$remote_sha" ]; then
    echo "✅ $branch: verified on origin ($local_sha)"
  else
    echo "❌ $branch: MISMATCH (local=$local_sha remote=$remote_sha)"
  fi
done

PROOF: Paste verification output. ALL branches must show ✅. STOP: Do NOT proceed to merge if any branch shows ❌.

⚠️ RESEARCH/PLANNING FILES IN WORKTREE: Any files created under kitty-specs/ INSIDE a worktree directory are physically located in the worktree's filesystem only. When spec-kitty merge runs git worktree remove, ALL untracked files in that directory are permanently deleted. You MUST sync them to the main checkout first:
rsync -av --ignore-existing \
  .worktrees/<FEATURE>-WP01/kitty-specs/<FEATURE>/research/ \
  kitty-specs/<FEATURE>/research/
git add kitty-specs/<FEATURE>/
git commit -m "docs: sync research artifacts from worktree to main before merge"
Also: kitty-specs/ is blocked by the pre-commit hook on WP branches. It can ONLY be committed from the main/target branch. This is by design.

Step 4e: Pre-merge safety check (deterministic forecasting)

cd <PROJECT_ROOT>
git status
git worktree list
spec-kitty merge --feature <SLUG> --dry-run --json

PROOF: Paste all outputs. From the JSON, verify:

You are in the main repo root (NOT inside a worktree)
git status shows clean working tree
effective_wp_branches lists only the branches that need merging
all_wp_branches may be larger than effective_wp_branches (expected)
No conflict warnings in the output

v1.0.1 Feature: The --dry-run --json flag outputs a deterministic merge plan showing exactly which branches will be merged. Confirm the effective tips before proceeding.

Step 4f: Merge from main repo

cd <PROJECT_ROOT>
spec-kitty merge --feature <SLUG> --push

ALWAYS use --push to ensure merged main is immediately backed up to origin. Without --push, worktree cleanup can destroy the only copies of feature branches.

LOCATION RULE: ALWAYS run merge from the main repository root. NEVER cd into a worktree to merge. The @require_main_repo decorator will block execution from worktrees.

If merge fails mid-way:

spec-kitty merge --feature <SLUG> --resume

PROOF: Paste the merge output showing success.

Step 4f: Post-merge verification

git log --oneline -5
git worktree list
git branch
git status
rm -f .kittify/workspaces/<SLUG>-WP*.json

PROOF: Paste all outputs. Verify:

Merge commit(s) visible in log
No orphaned worktrees remain for this feature
WP branches have been deleted
Working tree is clean
Workspace tracking JSONs removed from .kittify/workspaces/

Step 4g: Update kanban to done

python3 .kittify/scripts/tasks/tasks_cli.py update <FEATURE-SLUG> <WP-ID> done --note "Merged and cleaned up"

PROOF: Paste CLI output + final /spec-kitty.status board.

Known Back-End Failure Modes

Failure	Root Cause	Fix
Merge blocked by `@require_main_repo`	Agent ran merge from inside a worktree	`cd <PROJECT_ROOT>` first, then `spec-kitty merge --feature <SLUG>`
Accept fails with "missing shell_pid"	WP frontmatter missing `shell_pid` field	Add `shell_pid: N/A` to frontmatter, or use `--lenient`
Orphaned worktrees after merge	Merge failed mid-cleanup	`git worktree remove .worktrees/<WP-FOLDER>` then `git branch -d <WP-BRANCH>`
Lost data during merge	Agent merged from worktree instead of main repo	Always use `--feature <SLUG>` flag from project root
Retrospective skipped	Agent treated it as optional	Retrospective file must exist before merge is allowed
No closure state recorded	No post-merge verification step	Run Step 4f verification checklist
Merge preflight: "uncommitted changes" despite restored tracked files	spec-kitty uses `git status --porcelain` which includes `??` untracked files	Run `git stash -u` before merge, then `git stash pop` after
Research/planning files deleted when worktree removed	Untracked files in worktree physical dir are deleted by `git worktree remove`	Copy files to main checkout before merge: `rsync -av --ignore-existing .worktrees/<WP>/kitty-specs/ kitty-specs/` then commit on main
spec-kitty can't read WP lane for skeleton WPs	WP files without YAML frontmatter (`---`) are invisible to spec-kitty lane tracking	Add minimal frontmatter: `---\nlane: "planned"\ndependencies: []\nbase_branch: main\n---`
Accept fails: unchecked tasks in tasks.md	`- [ ]` items anywhere in tasks.md block accept even with `--lenient`	Run `sed -i '' 's/- \[ \]/- [x]/g' kitty-specs/<FEATURE>/tasks.md`
accept `--actor` or `--test` flags rejected	These flags are NOT supported by `spec-kitty agent feature accept` CLI	Use only: `--feature SLUG --mode local
Path violations: research/data/findings/reports not found	`research` mission requires these dirs in feature dir	Create at planning time: `mkdir -p kitty-specs/<FEATURE>/{research,data,findings,reports} && touch kitty-specs/<FEATURE>/{data,findings,reports}/.gitkeep`

5. Dual-Loop Mode (Protocol 133)

When Spec Kitty runs inside a Dual-Loop session, roles are split:

Step	Who	Action
Specify/Plan/Tasks	Outer Loop (Antigravity)	Generates all artifacts
Implement	Outer Loop creates worktree, then Inner Loop codes	Inner Loop receives Strategy Packet
Review/Merge	Outer Loop	Verifies output, commits, merges

Inner Loop constraints:

No git commands — Outer Loop owns version control
Scope limited to the Strategy Packet — no exploratory changes
If worktree is inaccessible, may implement on feature branch (fallback — log in friction log)

Cross-reference: dual-loop SKILL

6. Task Management CLI

The tasks CLI manages WP lane transitions. Always use this instead of manually editing frontmatter or checkboxes.

# Move a WP between lanes (planned -> doing -> for_review -> done)
python3 .kittify/scripts/tasks/tasks_cli.py update <FEATURE-SLUG> <WP-ID> <LANE> --note "reason"

# Force-move (when kitty-specs artifacts leak from serial implementation)
python3 .kittify/scripts/tasks/tasks_cli.py update <FEATURE-SLUG> <WP-ID> done --force --note "reason"

# View kanban board
/spec-kitty.status

# Accept feature readiness
spec-kitty accept --feature <FEATURE-SLUG>

# Validate encoding (prevents dashboard blank pages)
spec-kitty validate-encoding --feature <FEATURE-SLUG>
spec-kitty validate-encoding --feature <FEATURE-SLUG> --fix

Valid lanes: planned, doing, for_review, done

Dashboard: /spec-kitty.dashboard reads lane data from WP frontmatter.

Common Issues

"Base workspace not found": WP depends on a merged WP. Create worktree off main:

git worktree add .worktrees/<WP-FOLDER> main
cd .worktrees/<WP-FOLDER>
git checkout -b <WP-BRANCH-NAME>

"Already on main": Merge commands must run from project root, not inside a worktree.
Kanban not updating: Verify you're using the CLI, not manually editing frontmatter.

Spec Kitty Workflow

Spec Kitty Workflow

🚫 CRITICAL: Anti-Simulation Rules & Escalation Taxonomy

Escalation Taxonomy (Protocol Violation Response)

Anti-Pattern Vaccination (Known Agent Failure Modes)

🔴 THE HUMAN GATE (Constitutional Supreme Law)

Required Approval Gates

Gate Enforcement Rule (MANDATORY)

0. Mandatory Planning Phase (Do NOT Skip)

Pre-Execution Workflow Commitment

Step 0a: Specify

Step 0b: Plan

Step 0c: Tasks

1. Start a Work Package (WP)

Step 1a: Create worktree

Step 1b: Update kanban

2. Implementation Loop

3. Review & Handover

Pre-Review Checklist (verify ALL before proceeding)

Step 3a: Verify clean state

Step 3b: Update kanban to for_review

Step 3c: Verify kanban updated

Step 3d: Sync specs in main repo

4. Deterministic Closure Protocol

Step 4a: Review each WP

Step 4b: Accept feature

Step 4c: Retrospective (MANDATORY)

Step 4d: Pre-merge remote backup (MANDATORY)

Step 4e: Pre-merge safety check (deterministic forecasting)

Step 4f: Merge from main repo

Step 4f: Post-merge verification

Step 4g: Update kanban to done

Known Back-End Failure Modes

5. Dual-Loop Mode (Protocol 133)

6. Task Management CLI

Common Issues