shokunin 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mike Skaife
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,268 @@
+# 職人 shokunin
+
+**Craftsmanship in AI-assisted development.**
+
+Shokunin (職人) is the Japanese word for artisan — a person who devotes themselves to their craft, refining their process with every piece of work. In Japanese culture, a shokunin doesn't just build things; they take pride in *how* they build them. Every detail matters. Every cut is deliberate.
+
+This package brings that philosophy to software engineering with Claude Code. It's a lightweight, structured engineering process — seven skills that guide you from idea to shipped feature with discipline, visibility, and care.
+
+No hidden sub-agents doing work you can't see. No XML plans you can't reason about. Just clean markdown, TDD, and a craftsman's workflow.
+
+## Quick Start
+
+```bash
+# Install into your project
+npx shokunin@latest
+
+# Start a feature
+/start PROJ-123 add user authentication
+
+# In the new worktree
+/plan Add OAuth2 with Google and GitHub providers
+/build
+/review
+/ship
+```
+
+## Philosophy
+
+AI-assisted development is powerful, but power without discipline produces fragile work. Shokunin is built on three principles:
+
+1. **Visibility** — You see every line of code being written. Implementation happens in your conversation, not behind closed doors. You are the craftsman; the AI is your tool.
+
+2. **Discipline** — Plan before you build. Test before you ship. Review before you merge. Each phase has a purpose, and skipping phases produces sloppy work.
+
+3. **Traceability** — Every commit links to a ticket. Every PR links to a plan. When something breaks six months from now, you can trace it back to the decision that caused it.
+
+## Skills
+
+| 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 |
+
+## The Workflow
+
+### 1. `/start` — Begin with Intent
+
+Every feature starts with a clean workspace.
+
+```
+/start PROJ-123 add user authentication
+```
+
+This creates:
+- A git worktree at `../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.
+
+### 2. `/plan` — Measure Twice, Cut Once
+
+Before writing any code, define what you're building.
+
+```
+/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:
+
+- **Summary** — what and why
+- **Acceptance criteria** — how you'll know it's done
+- **Granular task list** — grouped by phase, with exact file paths, dependencies, and scope for each task
+
+Each task is sized for a single TDD red-green-refactor cycle.
+
+### 3. `/build` — Steady Hands
+
+Execute the plan, one task at a time.
+
+```
+/build
+```
+
+Build reads the plan and works through tasks sequentially:
+1. Picks the next pending task (respecting dependencies)
+2. Announces what it's about to do
+3. Implements using TDD — write a failing test, make it pass, refactor
+4. Marks the task complete and makes a WIP commit
+5. Pauses between phases for your confirmation
+
+You see everything. Every test written, every file edited. If something looks wrong, you can intervene immediately.
+
+### 4. `/review` — Critical Eye
+
+Once all tasks are complete, review the full changeset.
+
+```
+/review
+```
+
+The review runs in a forked sub-agent using the code-reviewer, examining:
+- Correctness, edge cases, and error handling
+- Security vulnerabilities
+- Performance issues
+- Code quality and maintainability
+- Test coverage and quality
+
+Results come back to your conversation as a structured report. You decide what to fix.
+
+### 5. `/ship` — Deliver with Pride
+
+Package the work and create a pull request.
+
+```
+/ship
+```
+
+Ship will:
+1. Show you the commits to squash and files changed
+2. Propose a commit message with the Jira ticket prefix: `PROJ-123: feat: add OAuth2 authentication`
+3. Propose a PR title and body (derived from the plan)
+4. **Wait for your confirmation** before doing anything
+5. Squash all WIP commits into a single clean commit
+6. Push and create the PR
+
+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, no merge conflicts.
+
+```markdown
+# Feature: Add user authentication
+
+**Ticket:** PROJ-123
+**Branch:** PROJ-123/add-user-authentication
+**Status:** in-progress
+**Created:** 2026-03-17
+
+## Summary
+Add OAuth2 authentication supporting Google and GitHub providers,
+with session management and token refresh.
+
+## Acceptance Criteria
+- [ ] Users can sign in with Google
+- [ ] Users can sign in with GitHub
+- [ ] Sessions persist across browser restarts
+- [ ] Tokens refresh automatically before expiry
+
+## Tasks
+
+### Phase 1: Data Model
+
+#### Task 1.1: Create user model
+- **Files:** `src/models/user.ts` (create), `prisma/schema.prisma` (modify)
+- **Depends on:** none
+- **Scope:** Define User model with email, name, provider, providerId fields. Add Prisma schema and generate client.
+- **Status:** [x] complete
+
+#### Task 1.2: Create session model
+- **Files:** `src/models/session.ts` (create), `prisma/schema.prisma` (modify)
+- **Depends on:** Task 1.1
+- **Scope:** Define Session model linked to User. Include token, refreshToken, expiresAt fields.
+- **Status:** [~] in-progress
+
+### Phase 2: API Routes
+...
+```
+
+**Task statuses:** `[ ] pending` → `[~] in-progress` → `[x] complete` → `[!] blocked`
+
+## Parallel Development
+
+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)
+```
+
+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:
+
+```
+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                     | —        | —           | —         |
+```
+
+## Git Strategy
+
+- **Branch naming:** `<TICKET>/<kebab-case-description>`
+- **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
+
+## Quick Flow
+
+For small changes that don't need a worktree, skip `/start`:
+
+```bash
+git checkout -b PROJ-789/fix-date-picker
+# then in Claude Code:
+/plan Fix the date picker timezone bug
+/build
+/review
+/ship
+```
+
+## Configuration
+
+### Prerequisites
+
+- **Claude Code** — [claude.com/claude-code](https://claude.com/claude-code)
+- **gh CLI** — installed and authenticated (`brew install gh && gh auth login`)
+- **Git** — version 2.15+ (for worktree support)
+
+### Permissions
+
+Add `Bash(gh *)` to your Claude Code allow list for `/ship` to create PRs:
+
+In `~/.claude/settings.json`, add to the `permissions.allow` array:
+```json
+"Bash(gh *)"
+```
+
+### Customisation
+
+After installation, skills live in your project's `.claude/skills/` directory. You can customise them per-project — they're just markdown files. Changes won't be overwritten unless you run `npx shokunin --force`.
+
+## How It Compares to GSD
+
+| | Shokunin | GSD |
+|---|---|---|
+| **Plans** | Markdown with task list | XML |
+| **Implementation** | Main conversation (visible) | Sub-agents (hidden) |
+| **Complexity** | 7 skills, zero dependencies | 39+ commands, 15 agents |
+| **Git strategy** | WIP commits, squash at ship | Atomic commits per task |
+| **Task tracking** | Checkbox in plan file | XML state management |
+| **Parallel work** | Git worktrees | Git worktrees |
+| **Philosophy** | Craftsman with tool | Autonomous system |
+
+Shokunin is deliberately simpler. You trade automation for visibility and control. If you want an autonomous system that handles everything, use GSD. If you want to see every line of code and stay in the driver's seat, use shokunin.
+
+## Contributing
+
+Contributions welcome. Please:
+
+1. Fork the repo
+2. Create a feature branch
+3. Make your changes (and yes, use shokunin to do it)
+4. Open a PR with a clear description
+
+## License
+
+MIT

package/agents/code-reviewer.md

@@ -0,0 +1,45 @@
+---
+name: code-reviewer
+description: Expert code reviewer for the shokunin engineering process. Reviews code changes for correctness, security, performance, and maintainability.
+model: sonnet
+color: purple
+---
+
+You are an expert code reviewer with deep expertise in software engineering best practices, security, performance, and maintainability. You approach code review as a collaborative process, providing constructive feedback that helps developers improve.
+
+## Your Review Process
+
+1. **Understand Context**: First understand what the code is trying to accomplish
+2. **Check Correctness**: Verify logic, edge cases, and error handling
+3. **Assess Quality**: Evaluate readability, maintainability, and adherence to project conventions
+4. **Identify Issues**: Look for bugs, security vulnerabilities, and performance problems
+5. **Suggest Improvements**: Provide actionable, specific recommendations
+
+## Review Categories
+
+For each review, assess:
+- **Correctness**: Does the code work as intended? Are edge cases handled?
+- **Security**: Are there vulnerabilities? Is input validated? Are secrets exposed?
+- **Performance**: Are there inefficiencies? Unnecessary computations? Memory leaks?
+- **Readability**: Is the code clear? Are names meaningful? Is complexity appropriate?
+- **Maintainability**: Is it testable? Does it follow project patterns? Is it documented?
+- **Error Handling**: Are errors handled gracefully? Are failures recoverable?
+- **Testing**: Is test coverage appropriate? Are tests good quality? Are there any gaps or issues with existing tests?
+
+## Output Format
+
+Structure your review as:
+1. **Summary**: Brief overview of the code and your assessment
+2. **Critical Issues**: Must-fix problems (bugs, security, breaking changes)
+3. **Improvements**: Recommended changes for quality
+4. **Minor Suggestions**: Optional enhancements
+5. **Positive Notes**: What was done well
+
+## Principles
+
+- Be specific: Reference exact lines and provide concrete examples
+- Be constructive: Explain why something is an issue and how to fix it
+- Be balanced: Acknowledge good code, not just problems
+- Prioritize: Distinguish critical issues from nice-to-haves
+- Respect context: Consider project conventions and constraints
+- Ask questions: If intent is unclear, ask rather than assume

package/bin/install.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+const SKILLS = ['start', 'plan', 'build', 'review', 'ship', 'wip', 'docs'];
+const AGENTS = ['code-reviewer'];
+
+function findProjectRoot(startDir) {
+  let dir = startDir;
+  while (dir !== path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, '.git')) || fs.existsSync(path.join(dir, 'package.json'))) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  return startDir;
+}
+
+function copyFileSync(src, dest) {
+  const destDir = path.dirname(dest);
+  if (!fs.existsSync(destDir)) {
+    fs.mkdirSync(destDir, { recursive: true });
+  }
+  fs.copyFileSync(src, dest);
+}
+
+function filesDiffer(src, dest) {
+  if (!fs.existsSync(dest)) return true;
+  const srcContent = fs.readFileSync(src, 'utf8');
+  const destContent = fs.readFileSync(dest, 'utf8');
+  return srcContent !== destContent;
+}
+
+function addToGitignore(projectRoot) {
+  const gitignorePath = path.join(projectRoot, '.gitignore');
+  const entry = '.claude/plans/';
+
+  if (fs.existsSync(gitignorePath)) {
+    const content = fs.readFileSync(gitignorePath, 'utf8');
+    if (content.includes(entry)) return false;
+    fs.appendFileSync(gitignorePath, `\n# Shokunin feature plans (working documents)\n${entry}\n`);
+  } else {
+    fs.writeFileSync(gitignorePath, `# Shokunin feature plans (working documents)\n${entry}\n`);
+  }
+  return true;
+}
+
+async function promptUser(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase());
+    });
+  });
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const force = args.includes('--force');
+
+  const projectRoot = findProjectRoot(process.cwd());
+  const packageRoot = path.resolve(__dirname, '..');
+
+  console.log('');
+  console.log('  \u8077\u4eba shokunin');
+  console.log('  Craftsmanship in AI-assisted development');
+  console.log('');
+  console.log(`  Project: ${projectRoot}`);
+  console.log('');
+
+  const claudeDir = path.join(projectRoot, '.claude');
+  const skillsDir = path.join(claudeDir, 'skills');
+  const agentsDir = path.join(claudeDir, 'agents');
+  const plansDir = path.join(claudeDir, 'plans');
+
+  // Ensure directories exist
+  for (const dir of [skillsDir, agentsDir, plansDir]) {
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+  }
+
+  let installed = 0;
+  let skipped = 0;
+  let updated = 0;
+
+  // Install skills
+  for (const skill of SKILLS) {
+    const src = path.join(packageRoot, 'skills', skill, 'SKILL.md');
+    const dest = path.join(skillsDir, skill, 'SKILL.md');
+
+    if (!fs.existsSync(src)) {
+      console.log(`  [warn] Skill source not found: ${skill}`);
+      continue;
+    }
+
+    if (fs.existsSync(dest) && !force) {
+      if (filesDiffer(src, dest)) {
+        const answer = await promptUser(`  Skill /${skill} already exists and differs. Overwrite? [y/N] `);
+        if (answer !== 'y' && answer !== 'yes') {
+          skipped++;
+          continue;
+        }
+        copyFileSync(src, dest);
+        updated++;
+      } else {
+        skipped++;
+      }
+    } else {
+      copyFileSync(src, dest);
+      installed++;
+    }
+  }
+
+  // Install agents
+  for (const agent of AGENTS) {
+    const src = path.join(packageRoot, 'agents', `${agent}.md`);
+    const dest = path.join(agentsDir, `${agent}.md`);
+
+    if (!fs.existsSync(src)) {
+      console.log(`  [warn] Agent source not found: ${agent}`);
+      continue;
+    }
+
+    if (fs.existsSync(dest) && !force) {
+      if (filesDiffer(src, dest)) {
+        const answer = await promptUser(`  Agent ${agent} already exists and differs. Overwrite? [y/N] `);
+        if (answer !== 'y' && answer !== 'yes') {
+          skipped++;
+          continue;
+        }
+        copyFileSync(src, dest);
+        updated++;
+      } else {
+        skipped++;
+      }
+    } else {
+      copyFileSync(src, dest);
+      installed++;
+    }
+  }
+
+  // Update .gitignore
+  const gitignoreUpdated = addToGitignore(projectRoot);
+
+  // 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 (gitignoreUpdated) console.log('    Added .claude/plans/ to .gitignore');
+  console.log('');
+  console.log('  Skills installed:');
+  for (const skill of SKILLS) {
+    console.log(`    /${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('');
+  console.log('  Prerequisites:');
+  console.log('    - gh CLI installed and authenticated (for /ship)');
+  console.log('    - Add Bash(gh *) to ~/.claude/settings.json allow list');
+  console.log('');
+}
+
+main().catch((err) => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "shokunin",
+  "version": "1.0.0",
+  "description": "Lightweight engineering process skills for Claude Code — craftsmanship in AI-assisted development",
+  "bin": {
+    "shokunin": "bin/install.js"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "agents/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "claude-code",
+    "engineering-process",
+    "developer-tools",
+    "ai-development",
+    "tdd",
+    "code-review",
+    "git-workflow"
+  ],
+  "author": "Mike Skaife",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mskaife/shokunin"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/skills/build/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: 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
+
+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.
+
+## Process
+
+### 1. Load the Plan
+
+Get the current branch name:
+```
+!git branch --show-current
+```
+
+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.
+
+### 2. Update Status
+
+If the plan status is `planning`, update it to `in-progress`.
+
+### 3. Find the Next Task
+
+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.
+
+### 4. Start the Task
+
+Update the task status in the plan file to `**Status:** [~] in-progress`.
+
+Announce to the user:
+- The task name and number (e.g. "Task 2.1: Create auth middleware")
+- The files involved and whether they're being created or modified
+- The scope — what you're about to do
+
+### 5. Implement with TDD
+
+Follow the TDD cycle as defined in the project's CLAUDE.md:
+1. **Red:** Write a failing test that defines the expected behaviour
+2. **Green:** Write the minimum code to make the test pass
+3. **Refactor:** Clean up while keeping tests green
+
+Run tests after each step to confirm the cycle.
+
+### 6. Complete the Task
+
+Once the task passes all tests:
+1. Update the task status in the plan file to `**Status:** [x] complete`
+2. Make a WIP commit: `wip: <task name>`
+
+### 7. Handle Blocked Tasks
+
+If a task cannot be completed (missing dependency, unclear requirement, external blocker):
+1. Update the task status to `**Status:** [!] blocked — <reason>`
+2. Tell the user why it's blocked
+3. Move to the next unblocked task
+
+### 8. Phase Boundaries
+
+When you complete the last task in a phase, **pause and check in with the user** before starting the next phase. Present:
+- What was completed in the phase
+- What's coming in the next phase
+- Any issues or decisions that came up
+
+Wait for the user to confirm before proceeding.
+
+### 9. Completion
+
+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."
+
+## Important
+
+- **One task at a time** — never skip ahead or parallelise
+- **Always update the plan file** — it's the source of truth for progress
+- **Always make WIP commits** — they protect against session loss and get squashed later
+- **Pause between phases** — give the user a checkpoint
+- **Follow existing project conventions** — match the patterns you find in the codebase
+- **TDD is non-negotiable** — red, green, refactor for every task

package/skills/docs/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: 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
+
+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.
+
+## Process
+
+### 1. Determine Scope
+
+If `$ARGUMENTS` is provided, use it as the scope:
+- A specific topic: "auth", "API endpoints", "database schema"
+- A component name: "user-service", "middleware"
+- `"all"` — update all documentation
+
+If no arguments, detect what changed:
+```bash
+git diff main...HEAD --name-only
+```
+Document the areas affected by recent changes.
+
+### 2. Explore the Code
+
+Read the relevant source files to understand the current implementation. Don't document from memory or assumptions — document what actually exists.
+
+Look for:
+- Public APIs, interfaces, and types
+- Configuration and environment variables
+- Architecture decisions and patterns
+- Integration points and dependencies
+- Setup and deployment requirements
+
+### 3. Write Documentation
+
+Create or update files in the `docs/` directory:
+
+```
+docs/
+  README.md              # Project overview, getting started, architecture summary
+  architecture.md        # System architecture, key decisions, component relationships
+  api/                   # API documentation (endpoints, request/response schemas)
+    <resource>.md        # One file per API resource
+  guides/                # How-to guides for common tasks
+    <guide-name>.md      # One file per guide
+  <component>/           # Per-component documentation as needed
+```
+
+### Documentation Principles
+
+- **Document the why and how**, not just the what — the code already shows the what
+- **Reference source file paths** — link docs to the code they describe
+- **Include usage examples** — show, don't just tell
+- **Update existing docs** — don't create duplicates
+- **Keep it current** — stale docs are worse than no docs
+- **Use clear headings** — docs should be scannable
+- **If `docs/README.md` exists**, update its table of contents to include new pages
+
+### 4. Commit
+
+After writing documentation:
+```bash
+git add docs/
+git commit -m "docs: update <scope> documentation"
+```
+
+## Important
+
+- **Read the code first** — never document from assumption
+- **Respect existing structure** — if docs already exist, follow the established pattern
+- **Don't over-document** — focus on what someone new to the codebase needs to know
+- **Keep it maintainable** — docs that are too detailed become stale faster

package/skills/plan/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: 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
+
+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.
+
+## Process
+
+### 1. Detect Context
+
+Get the current branch name:
+```
+!git branch --show-current
+```
+
+Extract the Jira ticket ID from the branch name (the segment before the first `/`, e.g. `PROJ-123/add-auth` → `PROJ-123`). If the branch has no ticket prefix (e.g. `main`), ask the user for the ticket ID.
+
+### 2. Check for Existing Plan
+
+Look for `.claude/plans/<ticket>.md`. If it exists and has tasks, this is a **refinement** — ask the user what they want to change rather than starting from scratch.
+
+If no plan exists, create a new one.
+
+### 3. Understand the Feature
+
+If `$ARGUMENTS` is provided, use it as the starting point. Otherwise, ask the user to describe what they want to build.
+
+Before writing the plan, engage interactively:
+- Ask about scope boundaries — what's in, what's out
+- Ask about edge cases and error scenarios
+- Ask about acceptance criteria — how will we know it's done?
+- Clarify any ambiguity — don't assume
+
+### 4. Explore the Codebase
+
+Before generating tasks, explore the existing codebase to understand:
+- Project conventions and patterns (naming, file structure, test patterns)
+- Existing code that can be reused or extended
+- Related files that will need modification
+- The test framework and patterns in use
+
+### 5. Generate the Plan
+
+Write `.claude/plans/<ticket>.md` using this exact format:
+
+```markdown
+# Feature: <title>
+
+**Ticket:** <PROJ-123>
+**Branch:** <PROJ-123/feature-slug>
+**Status:** planning
+**Created:** <YYYY-MM-DD>
+
+## Summary
+<2-3 sentences: what we're building and why>
+
+## Acceptance Criteria
+- [ ] <criterion 1>
+- [ ] <criterion 2>
+- [ ] <criterion 3>
+
+## Tasks
+
+Tasks are grouped by phase, ordered by dependency, and specify exact file paths.
+
+### Phase 1: <phase name>
+
+#### Task 1.1: <concise task name>
+- **Files:** `path/to/file.ts` (create), `path/to/other.ts` (modify)
+- **Depends on:** none
+- **Scope:** <what this task must accomplish — specific enough to implement without guessing>
+- **Status:** [ ] pending
+
+#### Task 1.2: <concise task name>
+- **Files:** `path/to/file.test.ts` (create)
+- **Depends on:** Task 1.1
+- **Scope:** <what this task must accomplish>
+- **Status:** [ ] pending
+
+### Phase 2: <phase name>
+
+#### Task 2.1: <concise task name>
+- **Files:** `path/to/file.ts` (create)
+- **Depends on:** Task 1.1
+- **Scope:** <what this task must accomplish>
+- **Status:** [ ] pending
+
+## Notes
+<Design decisions, constraints, open questions discovered during planning>
+```
+
+### Task List Guidelines
+
+- **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
+- **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
+
+### 6. Review with the User
+
+After writing the plan, present a summary:
+- Total task count and phase breakdown
+- Key design decisions made
+- Any open questions or risks
+
+Wait for the user to approve or request changes before considering planning complete.
+
+## Important
+
+- **Never implement code** — planning only
+- **Never skip the interactive phase** — always ask before assuming
+- **Always explore the codebase first** — plans grounded in reality, not imagination
+- **Keep plans lean** — enough detail to execute, not a novel

package/skills/review/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: 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
+agent: code-reviewer
+allowed-tools: Read, Grep, Glob, Bash(git diff *), Bash(git log *), Bash(git status *), Bash(git branch *)
+---
+
+# /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.
+
+## Process
+
+### 1. Gather Context
+
+Get the current branch and diff:
+```
+git branch --show-current
+git diff main...HEAD --stat
+git diff main...HEAD --name-only
+git log main..HEAD --oneline
+```
+
+### 2. Read Changed Files
+
+Read every file that was changed. Understand the full context — not just the diff, but the surrounding code.
+
+### 3. Review
+
+Apply a thorough review across these categories:
+
+- **Correctness:** Does the code work as intended? Are edge cases handled?
+- **Security:** Are there vulnerabilities? Is input validated? Are secrets exposed?
+- **Performance:** Are there inefficiencies? Unnecessary computations? Memory leaks?
+- **Readability:** Is the code clear? Are names meaningful? Is complexity appropriate?
+- **Maintainability:** Is it testable? Does it follow project patterns? Is coupling minimised?
+- **Error Handling:** Are errors handled gracefully? Are failures recoverable?
+- **Testing:** Is coverage appropriate? Are tests good quality? Any gaps?
+
+### 4. Output
+
+Structure your review as:
+
+**Summary**
+Brief overview of the changes and your overall assessment.
+
+**Critical Issues**
+Must-fix problems — bugs, security vulnerabilities, breaking changes. These block shipping.
+
+**Improvements**
+Recommended changes that would meaningfully improve quality. Not blockers, but strongly suggested.
+
+**Minor Suggestions**
+Optional enhancements — style, naming, minor optimisations.
+
+**Positive Notes**
+What was done well. Acknowledge good work.
+
+## Principles
+
+- Be specific — reference exact files and lines, provide concrete examples
+- Be constructive — explain why something is an issue and how to fix it
+- Be balanced — acknowledge good code, not just problems
+- Prioritise — distinguish critical issues from nice-to-haves
+- Respect context — consider project conventions and constraints

package/skills/ship/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: 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
+
+You are the shipping phase of the shokunin engineering process. Package the work cleanly — one commit, clear message, traceable to the ticket.
+
+## Process
+
+### 1. Extract Context
+
+Get the current branch:
+```
+!git branch --show-current
+```
+
+Extract the Jira ticket ID from the branch name (segment before the first `/`). If the branch doesn't follow the `TICKET/description` format, ask the user for the ticket ID.
+
+### 2. Assess the Changes
+
+```bash
+git log main..HEAD --oneline
+git diff main...HEAD --stat
+```
+
+Show the user:
+- Number of commits to squash
+- Files changed summary
+- The Jira ticket ID detected
+
+### 3. Read the Plan
+
+Read `.claude/plans/<ticket>.md` if it exists. Use the summary and acceptance criteria to inform the commit message and PR body.
+
+### 4. Propose the Commit
+
+Draft a commit message in this format:
+```
+<TICKET-ID>: <conventional commit type>: <concise description>
+
+<Longer description if needed, derived from the plan summary>
+```
+
+Example:
+```
+PROJ-123: feat: add OAuth2 authentication with Google and GitHub
+
+Implements OAuth2 login flow with Google and GitHub providers.
+Includes session management, token refresh, and logout.
+```
+
+Conventional commit types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`
+
+### 5. Propose the PR
+
+Draft a PR title and body:
+
+**Title:** Short, descriptive (under 70 chars). Use `$ARGUMENTS` as override if provided.
+
+**Body:**
+```markdown
+## Summary
+<Bullet points derived from plan summary and acceptance criteria>
+
+## Changes
+<Key technical changes, derived from the diff>
+
+## Test Plan
+<How to verify this works, derived from acceptance criteria>
+
+## Ticket
+<TICKET-ID>
+```
+
+### 6. Confirm with the User
+
+Present the proposed commit message, PR title, and PR body. **Wait for explicit confirmation** before proceeding. The user may want to adjust the wording.
+
+### 7. Execute
+
+Only after confirmation:
+
+1. Squash all commits into one:
+   ```bash
+   git reset --soft main
+   git commit -m "<approved commit message>"
+   ```
+
+2. Delete the plan file (it served its purpose, PR body captures the summary):
+   ```bash
+   git rm .claude/plans/<ticket>.md 2>/dev/null
+   git commit --amend --no-edit
+   ```
+
+3. Push the branch:
+   ```bash
+   git push -u origin HEAD
+   ```
+
+4. Create the PR:
+   ```bash
+   gh pr create --title "<title>" --body "<body>"
+   ```
+
+### 8. Print Cleanup Instructions
+
+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>
+```
+
+## Important
+
+- **Always confirm before squashing** — squashing is destructive to local history
+- **Always include the Jira ticket** — traceability is non-negotiable
+- **Never merge the PR** — that's a manual step on GitHub
+- **Never force push to main** — only push the feature branch

package/skills/start/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: 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
+
+You are the initialisation phase of the shokunin engineering process. Set up a clean workspace for a new feature.
+
+## Process
+
+### 1. Parse Arguments
+
+`$ARGUMENTS` should contain: `<TICKET-ID> <feature description>`
+
+- First word: Jira ticket ID (e.g. `PROJ-123`, `ENG-42`). Validate it matches the pattern `[A-Z]+-\d+`. If invalid, ask the user for the correct ticket ID.
+- Remaining words: feature description (e.g. "add user authentication")
+
+### 2. Derive Names
+
+- **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`
+
+### 3. Create Worktree
+
+```bash
+git worktree add -b <branch-name> <worktree-dir> main
+```
+
+If the branch already exists, ask the user if they want to resume work on it or start fresh.
+
+### 4. Create Plan Scaffold
+
+Create the directory `.claude/plans/` in the worktree if it doesn't exist.
+
+Write `.claude/plans/<ticket>.md` with this scaffold:
+
+```markdown
+# Feature: <feature description>
+
+**Ticket:** <TICKET-ID>
+**Branch:** <branch-name>
+**Status:** planning
+**Created:** <YYYY-MM-DD>
+
+## Summary
+<To be filled during /plan>
+
+## Acceptance Criteria
+- [ ] <To be defined during /plan>
+
+## Tasks
+<To be generated during /plan>
+
+## Notes
+<To be captured during /plan>
+```
+
+### 5. Print Next Steps
+
+Tell the user:
+
+```
+Feature workspace created:
+  Worktree: <worktree-dir>
+  Branch:   <branch-name>
+  Plan:     .claude/plans/<ticket>.md
+
+Next: Open a new terminal and run:
+  cd <worktree-dir> && claude
+
+Then use /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`

package/skills/wip/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: 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
+
+You are the status overview of the shokunin engineering process. Show the craftsman what's on the workbench.
+
+## Process
+
+### 1. List Worktrees
+
+```bash
+git worktree list
+```
+
+For each worktree, extract:
+- Path
+- Branch name
+- Jira ticket (from branch name, segment before `/`)
+
+### 2. Check Plan Progress
+
+For each worktree, check if `.claude/plans/*.md` exists. If it does, read it and count:
+- Total tasks (lines matching `**Status:**`)
+- Pending (`[ ] pending`)
+- In progress (`[~] in-progress`)
+- Complete (`[x] complete`)
+- Blocked (`[!] blocked`)
+
+Also read the plan status field (`planning`, `in-progress`, `review`, `shipped`).
+
+### 3. Current Branch Details
+
+If the current directory is on a feature branch:
+- Show commit count since main: `git log main..HEAD --oneline | wc -l`
+- Show if there are uncommitted changes: `git status --short`
+
+### 4. Present the Overview
+
+Format as a clear, scannable table:
+
+```
+Shokunin — Work in Progress
+
+| Worktree | Branch | Ticket | Status | Progress |
+|----------|--------|--------|--------|----------|
+| ../PROJ-123-auth | PROJ-123/add-auth | PROJ-123 | in-progress | 4/7 tasks |
+| ../PROJ-456-dash | PROJ-456/fix-dash | PROJ-456 | review | 5/5 tasks |
+| . (main) | main | — | — | — |
+
+Current branch: PROJ-123/add-auth
+  Commits ahead of main: 4
+  Uncommitted changes: 2 files
+```
+
+If there are no feature worktrees, just show the current branch status.