shokunin 1.1.0 → 1.3.0

package/README.md

@@ -15,13 +15,13 @@ No hidden sub-agents doing work you can't see. No XML plans you can't reason abo
 npx shokunin@latest
 
 # Start a feature
-/start PROJ-123 add user authentication
+/shokunin:start PROJ-123 add user authentication
 
 # In the new worktree
-/plan Add OAuth2 with Google and GitHub providers
-/build
-/review
-/ship
+/shokunin:plan Add OAuth2 with Google and GitHub providers
+/shokunin:build
+/shokunin:review
+/shokunin:ship
 ```
 
 ## Philosophy
@@ -38,37 +38,41 @@ AI-assisted development is powerful, but power without discipline produces fragi
 
 | Skill | Purpose |
 |-------|---------|
-| `/start` | Create a git worktree, branch, and plan scaffold for a new feature |
-| `/plan` | Design the feature interactively — produces a granular task list |
-| `/build` | Implement tasks one by one with TDD and progress tracking |
-| `/review` | Run a thorough code review on all changes |
-| `/ship` | Squash commits, add Jira reference, create a pull request |
-| `/wip` | Show all features in flight and their progress |
-| `/docs` | Create or update technical documentation |
+| `/shokunin:start` | Create a git worktree, branch, and plan scaffold for a new feature |
+| `/shokunin:plan` | Design the feature interactively — produces a granular task list |
+| `/shokunin:build` | Implement tasks one by one with TDD and progress tracking |
+| `/shokunin:review` | Run a thorough code review on all changes |
+| `/shokunin:ship` | Squash commits, add Jira reference, create a pull request |
+| `/shokunin:wip` | Show all features in flight and their progress |
+| `/shokunin:docs` | Create or update technical documentation |
 
 ## The Workflow
 
-### 1. `/start` — Begin with Intent
+### 1. `/shokunin:start` — Begin with Intent
 
 Every feature starts with a clean workspace.
 
 ```
-/start PROJ-123 add user authentication
+/shokunin:start PROJ-123 add user authentication
 ```
 
 This creates:
-- A git worktree at `../PROJ-123-add-user-authentication/`
+- A git worktree at `.worktrees/PROJ-123-add-user-authentication/`
 - A branch `PROJ-123/add-user-authentication`
 - A plan scaffold at `.claude/plans/PROJ-123.md`
 
-Open a new terminal, `cd` into the worktree, and start Claude Code.
+Open a new terminal, `cd` into the worktree, and start Claude Code:
 
-### 2. `/plan` — Measure Twice, Cut Once
+```bash
+cd .worktrees/PROJ-123-add-user-authentication && claude
+```
+
+### 2. `/shokunin:plan` — Measure Twice, Cut Once
 
 Before writing any code, define what you're building.
 
 ```
-/plan Add OAuth2 authentication with Google and GitHub providers
+/shokunin:plan Add OAuth2 authentication with Google and GitHub providers
 ```
 
 The plan phase is interactive — Claude will ask about scope, edge cases, and acceptance criteria. The output is a detailed plan file with:
@@ -79,12 +83,12 @@ The plan phase is interactive — Claude will ask about scope, edge cases, and a
 
 Each task is sized for a single TDD red-green-refactor cycle.
 
-### 3. `/build` — Steady Hands
+### 3. `/shokunin:build` — Steady Hands
 
 Execute the plan, one task at a time.
 
 ```
-/build
+/shokunin:build
 ```
 
 Build reads the plan and works through tasks sequentially:
@@ -96,12 +100,12 @@ Build reads the plan and works through tasks sequentially:
 
 You see everything. Every test written, every file edited. If something looks wrong, you can intervene immediately.
 
-### 4. `/review` — Critical Eye
+### 4. `/shokunin:review` — Critical Eye
 
 Once all tasks are complete, review the full changeset.
 
 ```
-/review
+/shokunin:review
 ```
 
 The review runs in a forked sub-agent using the code-reviewer, examining:
@@ -113,12 +117,12 @@ The review runs in a forked sub-agent using the code-reviewer, examining:
 
 Results come back to your conversation as a structured report. You decide what to fix.
 
-### 5. `/ship` — Deliver with Pride
+### 5. `/shokunin:ship` — Deliver with Pride
 
 Package the work and create a pull request.
 
 ```
-/ship
+/shokunin:ship
 ```
 
 Ship will:
@@ -133,7 +137,7 @@ After the PR is merged on GitHub, clean up with `git worktree remove`.
 
 ## Plan File Format
 
-Plans live at `.claude/plans/<TICKET>.md` — one per feature, tracked in git on the feature branch. `/ship` removes the plan file during the squash commit, so plans never reach main.
+Plans live at `.claude/plans/<TICKET>.md` — one per feature, tracked in git on the feature branch. `/shokunin:ship` removes the plan file during the squash commit, so plans never reach main.
 
 ```markdown
 # Feature: Add user authentication
@@ -180,22 +184,25 @@ with session management and token refresh.
 Shokunin uses git worktrees to support working on multiple features simultaneously.
 
 ```
-~/src/myproject/                              main repo
-  +-- ../PROJ-123-add-auth/                   worktree (Claude session B)
-  +-- ../PROJ-456-fix-dashboard/              worktree (Claude session C)
-  +-- ../PROJ-789-api-refactor/               worktree (Claude session D)
+~/src/myproject/
+  .worktrees/                                 gitignored
+    PROJ-123-add-auth/                        worktree (Claude session B)
+    PROJ-456-fix-dashboard/                   worktree (Claude session C)
+    PROJ-789-api-refactor/                    worktree (Claude session D)
+  src/
+  package.json
 ```
 
-Each worktree is a separate directory with its own branch and Claude Code session. Run `/wip` from any session to see all features in flight:
+Each worktree is a separate directory with its own branch and Claude Code session. Run `/shokunin:wip` from any session to see all features in flight:
 
 ```
 Shokunin — Work in Progress
 
-| Worktree                | Branch                   | Ticket   | Status      | Progress  |
-|-------------------------|--------------------------|----------|-------------|-----------|
-| ../PROJ-123-add-auth    | PROJ-123/add-auth        | PROJ-123 | in-progress | 4/7 tasks |
-| ../PROJ-456-fix-dash    | PROJ-456/fix-dash        | PROJ-456 | review      | 5/5 tasks |
-| . (main)                | main                     | —        | —           | —         |
+| Worktree                          | Branch                   | Ticket   | Status      | Progress  |
+|-----------------------------------|--------------------------|----------|-------------|-----------|
+| .worktrees/PROJ-123-add-auth      | PROJ-123/add-auth        | PROJ-123 | in-progress | 4/7 tasks |
+| .worktrees/PROJ-456-fix-dash      | PROJ-456/fix-dash        | PROJ-456 | review      | 5/5 tasks |
+| . (main)                          | main                     | —        | —           | —         |
 ```
 
 ## Git Strategy
@@ -204,19 +211,19 @@ Shokunin — Work in Progress
 - **During development:** WIP commits (`wip: <task name>`) — safe, cheap, squashed later
 - **At ship time:** All commits squashed into one: `PROJ-123: feat: description`
 - **PRs:** Created via `gh pr create`, merged manually on GitHub
-- **Cleanup:** `git worktree remove` after merge
+- **Cleanup:** `git worktree remove .worktrees/<ticket>-<slug>` after merge
 
 ## Quick Flow
 
-For small changes that don't need a worktree, skip `/start`:
+For small changes that don't need a worktree, skip `/shokunin:start`:
 
 ```bash
 git checkout -b PROJ-789/fix-date-picker
 # then in Claude Code:
-/plan Fix the date picker timezone bug
-/build
-/review
-/ship
+/shokunin:plan Fix the date picker timezone bug
+/shokunin:build
+/shokunin:review
+/shokunin:ship
 ```
 
 ## Configuration
@@ -229,7 +236,7 @@ git checkout -b PROJ-789/fix-date-picker
 
 ### Permissions
 
-Add `Bash(gh *)` to your Claude Code allow list for `/ship` to create PRs:
+Add `Bash(gh *)` to your Claude Code allow list for `/shokunin:ship` to create PRs:
 
 In `~/.claude/settings.json`, add to the `permissions.allow` array:
 ```json

package/bin/install.js

@@ -3,6 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 const readline = require('readline');
+const { execSync } = require('child_process');
 
 const SKILLS = ['start', 'plan', 'build', 'review', 'ship', 'wip', 'docs'];
 const AGENTS = ['code-reviewer'];
@@ -50,6 +51,7 @@ async function promptUser(question) {
 async function main() {
   const args = process.argv.slice(2);
   const force = args.includes('--force');
+  const noCommit = args.includes('--no-commit');
 
   const projectRoot = findProjectRoot(process.cwd());
   const packageRoot = path.resolve(__dirname, '..');
@@ -133,27 +135,70 @@ async function main() {
     }
   }
 
+  // Add .worktrees/ to .gitignore
+  const gitignorePath = path.join(projectRoot, '.gitignore');
+  let gitignoreUpdated = false;
+  const worktreeEntry = '.worktrees/';
+  if (fs.existsSync(gitignorePath)) {
+    const content = fs.readFileSync(gitignorePath, 'utf8');
+    if (!content.includes(worktreeEntry)) {
+      fs.appendFileSync(gitignorePath, `\n# Shokunin worktrees\n${worktreeEntry}\n`);
+      gitignoreUpdated = true;
+    }
+  } else {
+    fs.writeFileSync(gitignorePath, `# Shokunin worktrees\n${worktreeEntry}\n`);
+    gitignoreUpdated = true;
+  }
+
+  // Auto-commit skills to git so worktrees inherit them
+  const hasChanges = installed > 0 || updated > 0;
+  let committed = false;
+
+  if ((hasChanges || gitignoreUpdated) && !noCommit) {
+    const isGitRepo = fs.existsSync(path.join(projectRoot, '.git'));
+    if (isGitRepo) {
+      try {
+        execSync('git add .claude/skills/ .claude/agents/', { cwd: projectRoot, stdio: 'pipe' });
+        if (gitignoreUpdated) {
+          execSync('git add .gitignore', { cwd: projectRoot, stdio: 'pipe' });
+        }
+        execSync('git commit -m "chore: install shokunin engineering process skills"', { cwd: projectRoot, stdio: 'pipe' });
+        committed = true;
+      } catch {
+        // Commit may fail if nothing staged (already tracked) or no git user configured
+        committed = false;
+      }
+    }
+  }
+
   // Summary
   console.log('');
   console.log('  Done!');
   if (installed > 0) console.log(`    Installed: ${installed}`);
   if (updated > 0) console.log(`    Updated:   ${updated}`);
   if (skipped > 0) console.log(`    Unchanged: ${skipped}`);
+  if (committed) console.log('    Committed to git (skills available in worktrees)');
   console.log('');
   console.log('  Skills installed:');
   for (const skill of SKILLS) {
-    console.log(`    /${skill}`);
+    console.log(`    /shokunin:${skill}`);
   }
   console.log('');
   console.log('  Quick start:');
-  console.log('    /start PROJ-123 my new feature   # Create workspace');
-  console.log('    /plan                             # Design the feature');
-  console.log('    /build                            # Implement with TDD');
-  console.log('    /review                           # Code review');
-  console.log('    /ship                             # Squash, PR, ship it');
+  console.log('    /shokunin:start PROJ-123 my new feature   # Create workspace');
+  console.log('    /shokunin:plan                             # Design the feature');
+  console.log('    /shokunin:build                            # Implement with TDD');
+  console.log('    /shokunin:review                           # Code review');
+  console.log('    /shokunin:ship                             # Squash, PR, ship it');
   console.log('');
+  if (!committed && hasChanges) {
+    console.log('  [!] Skills were not committed to git.');
+    console.log('      Run: git add .claude/skills/ .claude/agents/ && git commit');
+    console.log('      (Skills must be committed for worktrees to inherit them)');
+    console.log('');
+  }
   console.log('  Prerequisites:');
-  console.log('    - gh CLI installed and authenticated (for /ship)');
+  console.log('    - gh CLI installed and authenticated (for /shokunin:ship)');
   console.log('    - Add Bash(gh *) to ~/.claude/settings.json allow list');
   console.log('');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shokunin",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Lightweight engineering process skills for Claude Code — craftsmanship in AI-assisted development",
   "bin": {
     "shokunin": "bin/install.js"

package/skills/build/SKILL.md

@@ -1,10 +1,10 @@
 ---
-name: build
+name: shokunin:build
 description: Implement features by working through the task list in the plan file. Executes tasks sequentially with TDD, updates progress, and makes WIP commits.
 disable-model-invocation: true
 ---
 
-# /build — Steady Hands
+# /shokunin:build — Steady Hands
 
 You are the build phase of the shokunin engineering process. Your job is to execute the plan methodically — one task at a time, with discipline and visibility.
 
@@ -19,7 +19,7 @@ Get the current branch name:
 
 Extract the Jira ticket ID from the branch name (segment before the first `/`).
 
-Read `.claude/plans/<ticket>.md`. If it doesn't exist, tell the user to run `/plan` first and stop.
+Read `.claude/plans/<ticket>.md`. If it doesn't exist, tell the user to run `/shokunin:plan` first and stop.
 
 ### 2. Update Status
 
@@ -29,7 +29,7 @@ If the plan status is `planning`, update it to `in-progress`.
 
 Scan the plan for the next task with `**Status:** [ ] pending`. Respect dependency order — if a task depends on another task that isn't `[x] complete`, skip it and find the next unblocked task.
 
-If all tasks are complete, update the plan status to `review` and suggest the user runs `/review`. Stop.
+If all tasks are complete, update the plan status to `review` and suggest the user runs `/shokunin:review`. Stop.
 
 ### 4. Start the Task
 
@@ -76,7 +76,7 @@ Wait for the user to confirm before proceeding.
 When all tasks are complete:
 1. Update the plan status to `review`
 2. Present a summary of everything that was built
-3. Suggest: "All tasks complete. Run `/review` to review the changes."
+3. Suggest: "All tasks complete. Run `/shokunin:review` to review the changes."
 
 ## Important
 

package/skills/docs/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: docs
+name: shokunin:docs
 description: Create or update technical documentation in the docs/ directory. Can target a specific topic or auto-detect what needs documenting from recent changes.
 disable-model-invocation: true
 argument-hint: [topic, component, or "all" to update everything]
 ---
 
-# /docs — Record the Craft
+# /shokunin:docs — Record the Craft
 
 You are the documentation phase of the shokunin engineering process. Good documentation is part of the craft — it respects the next person who reads the code.
 

package/skills/plan/SKILL.md

@@ -1,13 +1,13 @@
 ---
-name: plan
+name: shokunin:plan
 description: Create or refine a feature plan with a granular, dependency-ordered task list. Use this when starting to plan a new feature or when you need to adjust an existing plan.
 disable-model-invocation: true
 argument-hint: [feature description or refinement instructions]
 ---
 
-# /plan — Measure Twice, Cut Once
+# /shokunin:plan — Measure Twice, Cut Once
 
-You are the planning phase of the shokunin engineering process. Your job is to produce a detailed, actionable plan that `/build` can execute mechanically. Never start implementation — planning only.
+You are the planning phase of the shokunin engineering process. Your job is to produce a detailed, actionable plan that `/shokunin:build` can execute mechanically. Never start implementation — planning only.
 
 ## Process
 
@@ -99,7 +99,7 @@ Tasks are grouped by phase, ordered by dependency, and specify exact file paths.
 - **Group by phase:** e.g. Data Model, API, UI, Integration Tests
 - **Order by dependency:** each task lists what it depends on
 - **Specify exact file paths:** include whether each file is created or modified
-- **Define scope precisely:** enough detail that `/build` can implement without guessing
+- **Define scope precisely:** enough detail that `/shokunin:build` can implement without guessing
 - **Size for TDD:** each task should map to a single red-green-refactor cycle
 - **Include test tasks:** tests are first-class tasks, not afterthoughts
 - **Be realistic about phases:** don't over-decompose simple features

package/skills/review/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: review
+name: shokunin:review
 description: Run a thorough code review on recent changes using the code-reviewer agent. Use this after building a feature to catch issues before shipping.
 disable-model-invocation: true
 context: fork
@@ -7,7 +7,7 @@ agent: code-reviewer
 allowed-tools: Read, Grep, Glob, Bash(git diff *), Bash(git log *), Bash(git status *), Bash(git branch *)
 ---
 
-# /review — Critical Eye
+# /shokunin:review — Critical Eye
 
 You are the review phase of the shokunin engineering process. Review all changes on the current branch against main with a craftsman's attention to detail.
 

package/skills/ship/SKILL.md

@@ -1,12 +1,12 @@
 ---
-name: ship
+name: shokunin:ship
 description: Squash WIP commits into a single commit with Jira reference, then create a pull request. Use this when a feature is built and reviewed.
 disable-model-invocation: true
 allowed-tools: Bash(git *), Bash(gh *)
 argument-hint: [PR title override]
 ---
 
-# /ship — Deliver with Pride
+# /shokunin:ship — Deliver with Pride
 
 You are the shipping phase of the shokunin engineering process. Package the work cleanly — one commit, clear message, traceable to the ticket.
 
@@ -115,7 +115,7 @@ After the PR is created, tell the user:
 PR created: <URL>
 
 After the PR is merged, clean up the worktree:
-  git worktree remove <worktree-dir>
+  git worktree remove .worktrees/<ticket>-<slug>
 ```
 
 ## Important

package/skills/start/SKILL.md

@@ -1,12 +1,12 @@
 ---
-name: start
+name: shokunin:start
 description: Initialize a new feature with a git worktree, branch, and plan scaffold. Use this when beginning work on a new Jira ticket.
 disable-model-invocation: true
 allowed-tools: Bash(git *), Bash(mkdir *), Write, Read, Glob
 argument-hint: <PROJ-123> <short feature description>
 ---
 
-# /start — Begin with Intent
+# /shokunin:start — Begin with Intent
 
 You are the initialisation phase of the shokunin engineering process. Set up a clean workspace for a new feature.
 
@@ -23,22 +23,60 @@ You are the initialisation phase of the shokunin engineering process. Set up a c
 
 - **Branch name:** `<ticket>/<slugified-description>` — lowercase, hyphens, no special chars
   - Example: `PROJ-123/add-user-authentication`
-- **Worktree directory:** `../<ticket>-<slug>`
-  - Example: `../PROJ-123-add-user-authentication`
+- **Worktree directory:** `.worktrees/<ticket>-<slug>`
+  - Example: `.worktrees/PROJ-123-add-user-authentication`
 
-### 3. Create Worktree
+### 3. Ensure .worktrees/ is Gitignored
+
+Check if `.worktrees/` is in `.gitignore`. If not, add it:
+
+```bash
+grep -q '^\.worktrees/' .gitignore 2>/dev/null || echo '.worktrees/' >> .gitignore
+```
+
+Create the `.worktrees/` directory if it doesn't exist:
 
 ```bash
-git worktree add -b <branch-name> <worktree-dir> main
+mkdir -p .worktrees
+```
+
+### 4. Create Worktree
+
+```bash
+git worktree add -b <branch-name> .worktrees/<ticket>-<slug> main
 ```
 
 If the branch already exists, ask the user if they want to resume work on it or start fresh.
 
-### 4. Create Plan Scaffold
+### 5. Ensure Skills Exist in Worktree
+
+Check if `.claude/skills/` exists in the new worktree. If it doesn't (e.g. skills weren't committed to main), copy them from the source repo:
+
+```bash
+# Check if skills exist in the worktree
+ls <worktree-dir>/.claude/skills/plan/SKILL.md
+```
+
+If missing, copy the entire `.claude/skills/` and `.claude/agents/` directories from the current repo into the worktree:
+
+```bash
+cp -r .claude/skills <worktree-dir>/.claude/skills
+cp -r .claude/agents <worktree-dir>/.claude/agents
+```
+
+Then commit them on the feature branch so they persist:
+
+```bash
+cd <worktree-dir>
+git add .claude/skills/ .claude/agents/
+git commit -m "chore: add shokunin skills to feature branch"
+```
+
+### 7. Create Plan Scaffold
 
 Create the directory `.claude/plans/` in the worktree if it doesn't exist.
 
-Write `.claude/plans/<ticket>.md` with this scaffold:
+Write `.claude/plans/<ticket>.md` in the worktree with this scaffold:
 
 ```markdown
 # Feature: <feature description>
@@ -61,7 +99,7 @@ Write `.claude/plans/<ticket>.md` with this scaffold:
 <To be captured during /plan>
 ```
 
-### 5. Print Next Steps
+### 8. Print Next Steps
 
 Tell the user:
 
@@ -74,11 +112,11 @@ Feature workspace created:
 Next: Open a new terminal and run:
   cd <worktree-dir> && claude
 
-Then use /plan to define the feature.
+Then use /shokunin:plan to define the feature.
 ```
 
 ## Important
 
 - **Never start planning or implementing** — just set up the workspace
 - **Always create a worktree** — this enables parallel feature development
-- **Always scaffold the plan file** — it's the entry point for `/plan`
+- **Always scaffold the plan file** — it's the entry point for `/shokunin:plan`

package/skills/wip/SKILL.md

@@ -1,10 +1,10 @@
 ---
-name: wip
+name: shokunin:wip
 description: Show work in progress — list active feature worktrees, branches, and plan progress. Use this to get an overview of all features in flight.
 allowed-tools: Bash(git worktree *), Bash(git branch *), Bash(git log *), Bash(git status *), Read, Glob
 ---
 
-# /wip — Survey the Workshop
+# /shokunin:wip — Survey the Workshop
 
 You are the status overview of the shokunin engineering process. Show the craftsman what's on the workbench.