spec-kitty-sync-plugin

Original：🇺🇸 English
Translated

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).

8installs
Sourcerichfrem/agent-plugins-skills
Added on

NPX Install

npx skill4agent add richfrem/agent-plugins-skills spec-kitty-sync-plugin

Tags

Translated version includes tags in frontmatter
spec-kittycli-managementplugin-syncagent-integrationknowledge-reconciliation

SKILL.md Content

View Translation Comparison →

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 SkillContainsReview For
skills/spec-kitty-workflow/SKILL.md
End-to-end workflow guide, safety steps, best practicesNew 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 lifecycleNew agent configs, changes to sync scripts
AUGMENTED.md Files (in 
skills/*/references/
, adjacent to auto-synced SKILL.md — never overwritten):
Augmented FileContainsReview For
skills/spec-kitty-merge/references/AUGMENTED.md
Pre-merge safety protocol, branch protection awareness, kitty-specs conflict resolutionNew merge flags, changed CLI behavior
skills/spec-kitty-implement/references/AUGMENTED.md
Worktree discipline, commit hygiene, dependency managementNew implement flags, changed validation rules
skills/spec-kitty-review/references/AUGMENTED.md
Batch review protocol, review standards, dependency verificationNew 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: 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 
install-all
mapping script across the entire 
plugins/
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