Spec Kitty Sync Plugin

You are an active administrator for the Spec-Driven Development framework. This skill handles both initial setup and ongoing updates, ensuring the CLI, templates, plugin, and agent environments are all in sync.

Key principle: This project maintains two layers of knowledge:

Upstream content (auto-synced from spec-kitty CLI) — command templates, rules, mission configs
Custom augmented knowledge (hand-maintained) — best practices, safety guidance, workflow notes, project-specific conventions

The sync must NEVER overwrite custom augmented knowledge. Instead, the agent reviews upstream changes and intelligently reconciles them with existing custom content.

Visual References

Update flow: See sync-plugin-flow.mmd
Initial install flow: See init-install-flow.mmd

Execution Protocol

CRITICAL RULE: Do not simulate these steps. You must invoke the bash commands and read their outputs.

Step 0: Detect Mode (Init vs Update)

Check if .kittify/ exists in the project root:

test -d .kittify && echo "UPDATE" || echo "INIT"

INIT mode: First-time setup. Use spec-kitty init . (no --force).
UPDATE mode: Refresh existing setup. Use spec-kitty init . --force.

Step 1: Install or Upgrade the CLI

Install or update the spec-kitty-cli package:

pip install --upgrade spec-kitty-cli

Confirm the installed version:

spec-kitty --version

Step 2: Initialize or Refresh Templates

Pull the latest command templates, mission configs, and scripts into .kittify/:

INIT mode (first time):

spec-kitty init . --ai windsurf

This creates .kittify/, .windsurf/workflows/, mission configs, and git hooks.

UPDATE mode (existing project):

spec-kitty init . --ai windsurf --force

This refreshes existing templates without affecting project-specific configs.

Step 3: Sync to Spec-Kitty Plugin (Automated)

Convert the refreshed .kittify/ templates into distributable plugin components inside plugins/spec-kitty-plugin/:

python3 plugins/spec-kitty-plugin/skills/spec-kitty-agent/scripts/sync_configuration.py

This generates skills, rules, and templates that agents can consume.

IMPORTANT: This step ONLY touches auto-generated files (14 command skill SKILL.md files, rules, templates). It does NOT touch custom skills listed below.

Step 3b: Review & Reconcile Custom Knowledge (Agent-Reviewed)

This is the intelligence step. After the automated sync, you MUST review what changed and reconcile with custom augmented skills.

3b.1: Identify What Changed

Compare the new .kittify/ content against what was there before:

git diff --stat -- .kittify/ .windsurf/ ../../

Summarize the key changes for the user (new commands, removed commands, changed templates, updated mission configs).

3b.2: Review Custom Skills

The following contain custom augmented knowledge that is NOT generated by sync_configuration.py. They MUST be reviewed for staleness after every upstream update:

Custom Skills (in skills/, never touched by sync):

Custom Skill	Contains	Review For
`skills/spec-kitty-workflow/SKILL.md`	End-to-end workflow guide, safety steps, best practices	New commands/phases added upstream, safety guidance still accurate
`skills/spec-kitty-sync-plugin/SKILL.md`	This skill (meta)	Script paths still valid, new sync features
`skills/spec-kitty-agent/SKILL.md`	Agent config sync, combined lifecycle	New agent configs, changes to sync scripts

AUGMENTED.md Files (in skills/*/references/, adjacent to auto-synced SKILL.md — never overwritten):

Augmented File	Contains	Review For
`skills/spec-kitty-merge/references/AUGMENTED.md`	Pre-merge safety protocol, branch protection awareness, kitty-specs conflict resolution	New merge flags, changed CLI behavior
`skills/spec-kitty-implement/references/AUGMENTED.md`	Worktree discipline, commit hygiene, dependency management	New implement flags, changed validation rules
`skills/spec-kitty-review/references/AUGMENTED.md`	Batch review protocol, review standards, dependency verification	New review commands, changed lane logic

For each custom skill:

Read the current content
Compare against the new upstream .kittify/ command templates
Check if any new features, commands, or workflow changes require updates
Check if any existing custom guidance references deprecated features

3b.3: Propose Updates (Never Overwrite)

If changes are needed in custom skills:

ADD new sections for new upstream features
UPDATE references to renamed or changed commands
PRESERVE all custom best practices, safety guidance, and project-specific notes
FLAG any conflicts between upstream changes and custom guidance for user review

Present proposed changes to the user in diff format before applying them.

3b.4: Protected Files Checklist & Escalation Taxonomy

Before completing the sync, verify these files were NOT deleted or corrupted:

.agent/rules/constitution.md (symlinked from .kittify/memory/)
.agent/rules/standard-workflow-rules.md
.agent/rules/01_PROCESS/* (policy files)
.agent/rules/02_OPERATIONS/*
.agent/rules/03_TECHNICAL/*

test -f .agent/rules/constitution.md && echo "constitution OK" || echo "MISSING!"
ls .agent/rules/01_PROCESS/ .agent/rules/02_OPERATIONS/ .agent/rules/03_TECHNICAL/ 2>/dev/null | head -20

Escalation Taxonomy (Missing Data Response) If ANY protected file is missing or ls returns an error, trigger the Escalation Taxonomy:

Stop: Do not proceed to Step 4 (Bridging).
Alert: 🚨 PROTECTED FILE MISSING 🚨
Explain: State which file is missing (e.g., "constitution.md was deleted during update").
Recommend: "We must restore this file from git history before bridging plugins."
Draft: Ask the user for permission to run git checkout -- <file>.

Step 4: Deploy to Agent Environments (Interactive)

ASK THE USER before deploying:

Which plugins should I install/update?

Only spec-kitty-plugin (just the updated spec-kitty commands)

All plugins (full ecosystem sync across all 80+ plugins)

If spec-kitty-plugin only: Invoke the npx skills installer targeted specifically at plugins/spec-kitty-plugin:

npx skills add ./plugins/spec-kitty-plugin --force

If all plugins: Invoke the npx skills installer across the entire plugins/ directory:

npx skills add ./plugins/ --force

Step 5: Confirmation

Inform the user:

Whether this was an INIT or UPDATE
Which CLI version is now installed
How many skills/rules/templates were synced (auto-generated)
What changed in the upstream update (key diff summary)
Whether any custom skills needed reconciliation (and what was proposed)
Whether all protected files are intact
Which plugins were bridged to which agents
That they must Reload their Window (or restart the agent session) to see the new commands

spec-kitty-sync-plugin