職人 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

# Install into your project
npx shokunin@latest

# Start a feature
/shokunin:start PROJ-123 add user authentication

# In the new worktree
/shokunin:plan Add OAuth2 with Google and GitHub providers
/shokunin:build
/shokunin:review
/shokunin: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 | |-------|---------| | /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. /shokunin:start — Begin with Intent

Every feature starts with a clean workspace.

/shokunin:start PROJ-123 add user authentication

This creates:

• 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:

cd .worktrees/PROJ-123-add-user-authentication && claude

2. /shokunin:plan — Measure Twice, Cut Once

Before writing any code, define what you're building.

/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:

• 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. /shokunin:build — Steady Hands

Execute the plan, one task at a time.

/shokunin: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. /shokunin:review — Critical Eye

Once all tasks are complete, review the full changeset.

/shokunin: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. /shokunin:ship — Deliver with Pride

Package the work and create a pull request.

/shokunin: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, tracked in git on the feature branch. /shokunin:ship removes the plan file during the squash commit, so plans never reach main.

# 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/
  .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 /shokunin:wip from any session to see all features in flight:

Shokunin — Work in Progress

| 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

• 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 .worktrees/<ticket>-<slug> after merge

Quick Flow

For small changes that don't need a worktree, skip /shokunin:start:

git checkout -b PROJ-789/fix-date-picker
# then in Claude Code:
/shokunin:plan Fix the date picker timezone bug
/shokunin:build
/shokunin:review
/shokunin:ship

Configuration

Prerequisites

• Claude Code — 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 /shokunin:ship to create PRs:

In ~/.claude/settings.json, add to the permissions.allow array:

"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