Skip to content

EliasOulkadi/shokunin / .pack/skills/shokunin-update

shokunin-update

Verified

Detect drift, plan updates, and apply changes to the Shokunin AI Ecosystem. Use this when user asks to update, fix, sync, or verify the ecosystem.

FileKindSize
SKILL.mdskill md6.9 KB
---
name: shokunin-update
description: Detect drift, plan updates, and apply changes to the Shokunin AI Ecosystem. Use this when user asks to update, fix, sync, or verify the ecosystem.
triggers:
  - "update ecosystem"
  - "sync ecosystem"
  - "fix ecosystem"
  - "verify ecosystem"
  - "shokunin update"
  - "ecosystem status"
  - "check drift"
  - "update skills"
  - "repair ecosystem"
  - "ecosystem health"
negatives:
  - "update skill content"
  - "create skill"
  - "memory operations"
  - "session management"
license: MIT
compatibility: opencode
metadata:
  version: "1.0.0"

  workflow: system
  audience: developers
---


> **Note:** The `shokunin-update.ps1` script lives in `.pack/scripts/` and is deployed to `~/.shokunin/scripts/` by the installer.

# Shokunin Update System

Maintains the Shokunin ecosystem by detecting drift between the declarative manifest and the actual filesystem state.

## Workflow

### 1. Load the manifest

Read `~/.shokunin/shokunin.json`. This is the single source of truth. Every component, path, hash, and template is defined here.

### 2. Check status

Run `shokunin-update.ps1 status` to detect drift:

- OK: hash matches manifest
- MISSING: file doesn't exist but manifest expects it
- PROTECTED: data files (chroma_db, sessions) that must never be modified

Report results to the user with counts.

### 3. Plan changes

Run `shokunin-update.ps1 plan` to see what would change without applying anything.

Show the user a clear summary of what will be created, modified, or left alone.

### 4. Apply with confirmation

```powershell
& "$env:USERPROFILE\.shokunin\scripts\shokunin-update.ps1" apply -Confirm
```

This automatically:
1. Backs up each file to `~/.shokunin/backups/<timestamp>/`
2. Applies changes
3. Saves update event to ChromaDB
4. Runs `memory-healthcheck.ps1` to verify

### 5. Rollback if needed

```powershell
& "$env:USERPROFILE\.shokunin\scripts\shokunin-update.ps1" rollback -Timestamp 20260514-120000
```

## When to use this skill

- User notices something broken in the ecosystem
- User wants to add/remove/modify a component
- User asks "is everything up to date?"
- Pre-commit or pre-PR verification

## Do NOT

- Modify files in `protected` groups (chroma_db, sessions, logs, backups)
- Apply changes without user confirmation
- Edit the manifest without understanding every field

## Error Handling

| Cause | Fix |
|-------|-----|
| shokunin.json manifest is missing or malformed | Validate JSON syntax with `Test-Json`. If missing, run installer `~/.shokunin/install.ps1` to regenerate from template. Report exact parse error line if malformed. |
| File hash mismatch but content is identical | Encoding difference (CRLF vs LF) or trailing whitespace. Normalize line endings with `.pack/scripts/normalize-eol.ps1` before re-checking. |
| Backup directory exceeds disk quota | Old backups accumulate over time. Retention policy: keep last 5 backups. Purge older directories with `Remove-Item -Recurse`. |
| Protected file group modified by apply | A bug or misconfiguration in the manifest marked a protected path as writable. Abort immediately. Rollback from backup. Fix manifest before retry. |
| Rollback target timestamp not found | Backup was purged by retention policy or never created. Cannot recover that point in time. Run `status` to assess current state and manually fix drift. |
| Powershell execution policy blocks the script | System execution policy set to Restricted | Run `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser` or invoke with `powershell -ExecutionPolicy Bypass -File script.ps1`. |
| ChromaDB save during apply step fails | MCP server is down or ChromaDB collection is locked | Apply still succeeded on the filesystem. Save the update event manually: `python ~/.shokunin/scripts/chroma-helper.py save "update applied" ...`. |

## Related Scripts

- `~/.shokunin/scripts/validate-skills.ps1` — Validates all installed skills for required sections, size, and referenced script existence
- `~/.shokunin/scripts/shokunin-update.ps1` — Drift detection, manifest-driven update apply, rollback, and status reporting

## Sources

- PowerShell 5.1 documentation (learn.microsoft.com/en-us/powershell/scripting) — execution policy, file hashing, and error handling
- ChromaDB Python client documentation (docs.trychroma.com) — collection management and persistence
- Semantic Versioning 2.0.0 (semver.org) — version comparison logic used in drift detection
- Git documentation on plumbing commands (git-scm.com/docs/git-hash-object) — content-addressable storage pattern inspiration
- "Infrastructure as Code" by Kief Morris (O'Reilly, 2nd Edition, 2020) — drift detection and reconciliation patterns
- NIST SP 800-88 Guidelines for Media Sanitization — secure file overwrite patterns used in backup rotation

## Anti-Patterns

| Pattern | Problem | Fix |
|---------|---------|-----|
| Running `apply` without running `plan` first | Changes are applied without user awareness of what will be modified | Always run `plan` → show summary → get confirmation → then `apply`. |
| Modifying protected paths directly instead of through manifest | Data loss: chroma_db, sessions, logs get overwritten and cannot be recovered | Never touch paths under the protected group. If they need changes, update the manifest logic, not the files. |
| Hand-editing the manifest without understanding every field | A typo in a path or hash field cascades into false drift positives or corrupted apply | Use the declarative format. Every path must be absolute. Every hash must be SHA-256. Validate with `Test-Json` after edits. |
| Ignoring drift warnings for long periods | Drift accumulates, making later applies riskier and harder to roll back | Run `status` weekly. Schedule via Task Scheduler: `shokunin-update.ps1 status > ~/.shokunin/logs/drift.log`. |
| Restoring from backup without verifying backup integrity | A corrupted backup restores corrupted files | Before rollback, verify backup checksums against the original manifest hashes. Abort if mismatch. |
| Running apply while another apply is in progress | Race condition on backup/restore directories causing incomplete state | Use a lock file: `~/.shokunin/.apply-lock`. If lock exists and process is alive, wait or abort. Stale lock (>30 min) can be removed. |

## Checklist

- [ ] Verify shokunin.json is valid JSON and all component paths resolve
- [ ] Run shokunin-update.ps1 status — 0 MISSING, no crashes
- [ ] Run shokunin-update.ps1 apply — all components sync without errors
- [ ] Verify MCP server starts: python ~/.shokunin/memory/mcp-server.py responds to tools/list
- [ ] Verify chroma-helper.py CLI works: python ~/.shokunin/scripts/chroma-helper.py count
- [ ] Verify all 62 skills present in .config/opencode/skills/
- [ ] Verify templates match installed files (no drift)
- [ ] Verify AGENTS.md version matches shokunin.json version
- [ ] Run memory-healthcheck.ps1 — all tests pass
- [ ] Run alidate-skills.ps1 — 0 failures
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall