# Update Spec-Kit Skill

A skill for keeping the spec-kit ecosystem up-to-date across repository, CLI, and all projects.

## What This Skill Does

Automatically updates three levels of the spec-kit ecosystem:
1. **Spec-kit repository** - Pulls latest commits from upstream
2. **Specify CLI tool** - Upgrades the installed CLI to latest version
3. **Project templates** - Updates all projects using spec-kit to latest templates

## Installation

### Claude Code

```bash
# Link skill to Claude Code skills directory
ln -s $(pwd)/skills/update-spec-kit ~/.claude/skills/update-spec-kit
```

Or via Nix Home Manager:
```nix
home.file.".claude/skills/update-spec-kit" = {
  source = /path/to/skills/skills/update-spec-kit;
  recursive = true;
};
```

### OpenCode

```bash
# Link skill to OpenCode skills directory
ln -s $(pwd)/skills/update-spec-kit ~/.config/opencode/skills/update-spec-kit
```

Or via Nix Home Manager:
```nix
home.file.".config/opencode/skills/update-spec-kit" = {
  source = /path/to/skills/skills/update-spec-kit;
  recursive = true;
};
```

## Usage

Simply ask the agent in natural language:

- "Update spec-kit"
- "Upgrade spec-kit to the latest version"
- "Refresh all my spec-kit projects"
- "Are my spec-kit projects current?"
- "Sync spec-kit templates"

The agent will automatically invoke this skill based on your request.

## How It Works

**Model-Invoked**: The agent decides when to activate this skill. You don't need to explicitly call it.

**Three-Step Process**:
1. **Update Repository**: Pulls latest changes from `~/proj/spec-kit`
2. **Upgrade CLI**: Updates `specify` CLI tool via `uv`
3. **Update Projects**: Refreshes templates in all projects with `.specify` directories

## File Structure

```
update-spec-kit/
├── SKILL.md                     # Skill definition and instructions
├── README.md                    # This file
└── scripts/
    └── update-all-projects.sh   # Batch update script for all projects
```

## Safety Guarantees

**What's Updated**:
- Slash command files (`.claude/commands/*.md`, `.opencode/command/*.md`)
- Helper scripts (`.specify/scripts/`)
- Template files (`.specify/templates/`)

**What's Preserved**:
- All specifications (`.specify/specs/`)
- Source code
- Git history
- VS Code settings (smart-merged, not replaced)

## Manual Usage

### Update All Projects
```bash
./scripts/update-all-projects.sh
```

### Check Current Status
```bash
# Check spec-kit repo status
cd ~/proj/spec-kit && git fetch && git status

# Check CLI version
specify --version

# Compare installed vs latest
git log --oneline HEAD..origin/main
```

## Requirements

- Git repository at `~/proj/spec-kit`
- `uv` package manager installed
- `specify` CLI tool installed
- Projects with `.specify` directories

## Troubleshooting

### Skill doesn't activate
- Ensure deployed: `ls ~/.claude/skills/update-spec-kit/SKILL.md`
- Try explicit language: "update spec-kit"
- Check agent sees the skill in available skills list

### Update script fails
- Verify internet connectivity
- Check git repository is clean: `cd ~/proj/spec-kit && git status`
- Ensure `uv` is installed: `uv --version`
- Verify projects have `.specify` directories: `find ~/proj -name ".specify"`

### Agent detection fails
The script auto-detects the AI agent for each project:
- Checks for `.claude/`, `.cursor/`, `.gemini/` directories
- Checks for `.github/copilot-instructions.md`
- Defaults to `claude` if unclear

## Advanced

### Custom Project Locations
Edit `scripts/update-all-projects.sh` to change the search path:
```bash
# Default: searches ~/proj
projects=($(find ~/proj -name ".specify" -type d 2>/dev/null | sed 's|/.specify$||'))

# Custom: search multiple locations
projects=($(find ~/proj ~/work ~/dev -name ".specify" -type d 2>/dev/null | sed 's|/.specify$||'))
```

### Skip Specific Projects
Exclude projects by filtering the array:
```bash
# After finding projects, filter out unwanted ones
projects=("${projects[@]//*archive*}")
```

## See Also

- [Spec-Kit Repository](https://github.com/github/spec-kit)
- [Specify CLI Documentation](https://github.com/github/spec-kit#cli-usage)

## License

MIT
