spec-kitty-workflow

name	Spec Kitty Workflow
description	Standard operating procedures for the Spec Kitty agentic workflow (Plan -> Implement -> Review -> Merge).

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:

• commands/spec-kitty-merge/AUGMENTED.md — pre-merge safety, branch protection, conflict resolution
• commands/spec-kitty-implement/AUGMENTED.md — worktree discipline, commit hygiene
• commands/spec-kitty-review/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:

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

Anti-Pattern Vaccination (Known Agent Failure Modes)

1. Checkbox theater: Marking [x] without running the command or verification tool
2. Manual file creation: Writing spec.md/plan.md/tasks.md by hand instead of using CLI
3. Kanban neglect: Not updating task lanes, so dashboard shows stale state
4. Closure amnesia: Finishing code but skipping review/merge/closure steps

---

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

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.

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.

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.

---

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

spec-kitty agent tasks move-task <WP-ID> --to 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

1. Navigate: cd .worktrees/<WP-ID> — verify with pwd
2. Setup: Install dependencies if needed
3. Code: Implement the feature
4. Test: Run tests or manual verification
5. 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

spec-kitty agent tasks move-task <WP-ID> --to 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 ❌.

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: Intelligence sync

python3 plugins/rlm-factory/scripts/distill.py --path kitty-specs/<SPEC-ID>/

PROOF: Paste output confirming RLM cache updated.

If vector DB is available, also run:

python3 plugins/vector-db/scripts/ingest.py --path kitty-specs/<SPEC-ID>/

Step 4h: Update kanban to done

spec-kitty agent tasks move-task <WP-ID> --to 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

---

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)
spec-kitty agent tasks move-task <WP-ID> --to <LANE> --note "reason"

# Force-move (when kitty-specs artifacts leak from serial implementation)
spec-kitty agent tasks move-task <WP-ID> --to 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.