richfrem/spec-kitty-sync-plugin

Dependencies

This skill requires Python 3.8+ and standard library only. No external dependencies.

[!TIP] See INSTALL.md for instructions on how to install missing dependencies.

To install this skill's dependencies:

pip-compile ./requirements.in
pip install -r ./requirements.txt

See ./requirements.txt for the dependency lockfile (currently empty — standard library only).

---

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:

1. Upstream content (auto-synced from spec-kitty CLI) — command templates, rules, mission configs
2. 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 references/diagrams/sync-plugin-flow.mmd
• Initial install flow: See references/diagrams/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 the spec-kitty-plugin directory:

python ./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 | |---|---|---| | references/AUGMENTED.md | Pre-merge safety protocol, branch protection awareness, kitty-specs conflict resolution | New merge flags, changed CLI behavior | | references/AUGMENTED.md | Worktree discipline, commit hygiene, dependency management | New implement flags, changed validation rules | | references/AUGMENTED.md | Batch review protocol, review standards, dependency verification | New review commands, changed lane logic |

For each custom skill:

1. Read the current content
2. Compare against the new upstream .kittify/ command templates
3. Check if any new features, commands, or workflow changes require updates
4. 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:

• ./rules/constitution.md
• ./references/standard-workflow-rules.md

test -f ./rules/constitution.md && echo "constitution OK" || echo "MISSING!"

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

1. Stop: Do not proceed to Step 4 (Bridging).
2. Alert: 🚨 PROTECTED FILE MISSING 🚨
3. Explain: State which file is missing (e.g., "constitution.md was deleted during update").
4. Recommend: "We must restore this file from git history before bridging plugins."
5. 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?

1. Only spec-kitty-plugin (just the updated spec-kitty commands)
2. All plugins (full ecosystem sync across all 80+ plugins)

Step 4: Deploy to Agent Environments (Universal)

After performing the sync, you must deploy the updated plugin to your agent environment.

[!IMPORTANT] Zero Inline Commands: See the central installation guide for the authoritative deployment logic:

👉 INSTALL.md

This handles both forced re-installation and full ecosystem synchronization across all 80+ plugins.

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