# Shokunin Update

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

- Skill: `eliasoulkadi/shokunin-update` (Agent Skill)
- Install (CLI): `npx skillmds@latest add eliasoulkadi/shokunin-update`
- Raw SKILL.md: https://api.skillmd.com/api/skills/eliasoulkadi/shokunin-update/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: eliasoulkadi (https://skillmd.com/u/eliasoulkadi)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/eliasoulkadi/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

```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