Spec Kitty Sync Plugin

---
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:
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 `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:
```bash
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:
```bash
pip install --upgrade spec-kitty-cli
```
Confirm the installed version:
```bash
spec-kitty --version
```

### Step 2: Initialize or Refresh Templates

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

**INIT mode** (first time):
```bash
spec-kitty init . --ai windsurf
```
*This creates `.kittify/`, `.windsurf/workflows/`, 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 `.kittify/` 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 `.kittify/` 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 `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:
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:
- `.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/*`

```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 `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: Bridge to Agent Environments (Interactive)

**ASK THE USER** before bridging:

> Which plugins should I bridge?
> 1. **Only spec-kitty-plugin** (just the updated spec-kitty commands)
> 2. **All plugins** (full ecosystem sync across all plugins)
>
> Which agent environments?
> - antigravity, claude, github, gemini, windsurf, or **all**

**If spec-kitty-plugin only:**
```bash
python3 plugins/plugin-mapper/skills/agent-bridge/scripts/bridge_installer.py --plugin plugins/spec-kitty-plugin --target <agent>
```

**If all plugins:**
```bash
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