Shokunin Update

> 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

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

This automatically:

1. Backs up each file to ~/.shokunin/backups//
2. Applies changes
3. Saves update event to ChromaDB
4. Runs memory-healthcheck.ps1 to 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 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: EliasOulkadi
• Source: EliasOulkadi/shokunin
• License: MIT
• Homepage: https://eliasoulkadi.github.io/shokunin/

Install and usage instructions live in the source repository linked above.