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
- Initial install flow: See
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
exists in the project root:
bash
test -d .kittify && echo "UPDATE" || echo "INIT"
- INIT mode: First-time setup. Use (no ).
- UPDATE mode: Refresh existing setup. Use
spec-kitty init . --force
Step 1: Install or Upgrade the CLI
Install or update the
package:
bash
pip install --upgrade spec-kitty-cli
Confirm the installed version:
Step 2: Initialize or Refresh Templates
Pull the latest command templates, mission configs, and scripts into
:
INIT mode (first time):
bash
spec-kitty init . --ai windsurf
This creates , , mission configs, and git hooks.
UPDATE mode (existing project):
bash
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
templates into distributable plugin components inside
plugins/spec-kitty-plugin/
:
bash
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
content against what was there before:
bash
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
. They MUST be reviewed for staleness after every upstream update:
Custom Skills (in
, 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
, 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 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
.agent/rules/standard-workflow-rules.md
.agent/rules/01_PROCESS/*
.agent/rules/02_OPERATIONS/*
.agent/rules/03_TECHNICAL/*
bash
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
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 .
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:
Invoke your ecosystem's specific plugin bridge mapping script targeted specifically at
plugins/spec-kitty-plugin
for the selected agent environments.
If all plugins:
Invoke your ecosystem's specific
mapping script across the entire
directory for the selected agent environments.
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