| name | spec-kitty-sync-plugin |
| description | Full-cycle install or update of the Spec-Kitty framework - upgrades the CLI, refreshes templates, syncs the plugin, reconciles custom knowledge, and bridges to agent environments. Custom skill (not from upstream spec-kitty). |
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/ plugins/spec-kitty-plugin/
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 commands/, co-located with auto-synced SKILL.md — never overwritten):
| Augmented File | Contains | Review For |
|---|
commands/spec-kitty-merge/AUGMENTED.md | Pre-merge safety protocol, branch protection awareness, kitty-specs conflict resolution | New merge flags, changed CLI behavior |
commands/spec-kitty-implement/AUGMENTED.md | Worktree discipline, commit hygiene, dependency management | New implement flags, changed validation rules |
commands/spec-kitty-review/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: Bridge to Agent Environments (Interactive)
ASK THE USER before bridging:
Which plugins should I bridge?
- Only spec-kitty-plugin (just the updated spec-kitty commands)
- All plugins (full ecosystem sync across all plugins)
Which agent environments?
- antigravity, claude, github, gemini, windsurf, or all
If spec-kitty-plugin only:
python3 plugins/plugin-mapper/skills/agent-bridge/scripts/bridge_installer.py --plugin plugins/spec-kitty-plugin --target <agent>
If all plugins:
python3 plugins/plugin-mapper/skills/agent-bridge/scripts/install_all_plugins.py --target <agent>
Repeat for each selected agent environment, or run once per target.
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
