EliasOulkadi/shokunin / .pack/skills/shokunin-update
shokunin-update
VerifiedDetect drift, plan updates, and apply changes to the Shokunin AI Ecosystem. Use this when user asks to update, fix, sync, or verify the ecosystem.
Note: The
shokunin-update.ps1script 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
& "$env:USERPROFILE\.shokunin\scripts\shokunin-update.ps1" apply -Confirm
This automatically:
- Backs up each file to
~/.shokunin/backups/<timestamp>/ - Applies changes
- Saves update event to ChromaDB
- Runs
memory-healthcheck.ps1to verify
5. Rollback if needed
& "$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
protectedgroups (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 |
| ChromaDB save during apply step fails | MCP server is down or ChromaDB collection is locked |
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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |