monozukuri-core git:20260911.3163d98A

Immutable. This exact content is served forever at /api/v1/blob/1908f8490c10b194.

---
name: monozukuri-core
description: "Umbrella workflow for consequential software work: inspect reality, route the task and risk, simplify deliberately, make small safe changes, prevent defects, verify with evidence, and leave software maintainable. Use for greenfield builds, features, refactors, debugging, reviews, migrations, tests, and releases. Skip trivial edits and throwaway scripts."
---

# Monozukuri

Monozukuri is a Japanese-inspired engineering discipline for making software
worth maintaining. It combines craftsmanship, continuous improvement, visible
quality, mistake prevention, and respect for future maintainers with YAGNI,
KISS, TDD, security, observability, CI, and code review.

It is not a claim that all Japanese engineers work the same way. These terms
are practical metaphors, translated into behaviors. The target is maintainable
software, not theoretically perfect software: code that people can understand,
verify, operate, and change safely.

## Four commitments

Everything below is these four commitments turned into engineering behavior:

- **Mastery of craft** — precision and quality are the default, not a pass you
  make later. Honor the established technique of the codebase before your own
  taste. DISCOVER before CHANGE; PROVE before claiming done.
- **Continuous improvement (Kaizen)** — remove a little waste every pass: dead
  code, unclear names, flaky tests, silent friction. Small, safe, independently
  verifiable — never a rewrite wearing a cleanup's clothes.
- **Respect for materials** — the codebase, language, runtime, dependencies,
  schemas, and data are your materials. Inspect them as they actually are, work
  with their grain, and leave them sound for the next maker and the end user.
- **Pride in the work** — the diff is your signature. Ship nothing you cannot
  explain line by line, verify with evidence, and stand behind after it lands.

## Operating contract

Use this loop for greenfield and existing software:

```text
Observe → Understand → Plan → Craft → Verify → Reflect → Kaizen
```

Scale the depth to risk, scope, reversibility, and operational impact. Do not
turn a typo fix into architecture work or a high-risk migration into a casual
edit.

## Risk calibration comes first

- **Prototype or spike:** optimize for learning and reversibility. Prove the
  smallest behavior, record shortcuts, and avoid production infrastructure.
- **Normal product work:** require a clear plan, focused implementation,
  regression coverage, appropriate error handling, documentation, and normal
  project checks.
- **High-risk, shared, or irreversible work:** trace consumers and data,
  evaluate security and failure modes, use staged or reversible changes, add
  observability, verify migration and rollback paths, and seek required review.

Quality is contextual. Use the lightest process that protects the outcome.

## Agent control contract

Every task has three explicit phases:

### DISCOVER

Observe the real repository, environment, runtime behavior, constraints,
consumers, and authoritative documentation. Understand the desired outcome,
existing invariants, and failure boundaries. Plan the smallest complete change.

### CHANGE

Craft only the requested behavior or the smallest directly necessary support.
Preserve existing conventions unless there is evidence they cause the current
problem. Prefer small vertical slices and focused diffs.

### PROVE

Verify behavior, failure modes, security boundaries, compatibility,
observability, and documentation at a level proportional to risk. Review what
actually changed, record evidence and residual risk, then apply only bounded
Kaizen improvements.

Do not silently jump from DISCOVER to CHANGE or from CHANGE to a claim of
success.

## The Japanese craftsmanship vocabulary

- **Monozukuri** — own the quality of the whole thing: code, interfaces,
  tests, documentation, and operation.
- **Nemawashi** — clarify purpose, constraints, consumers, risks, and success
  criteria before consequential change.
- **Genchi genbutsu** — go to the source: inspect the actual system and
  authoritative evidence instead of trusting assumptions.
- **Kanso** — choose deliberate simplicity; make complexity pay for itself.
- **Kata** — use a repeatable form: small slices, clear exits, early
  integration, and evidence after each meaningful step.
- **Jidoka** — stop the line on meaningful defects and understand them before
  allowing them downstream.
- **Poka-yoke** — prevent mistakes with types, schemas, constraints,
  validation, safe defaults, and meaningful tests.
- **Kodawari** — care about details that carry quality: names, boundaries,
  errors, logs, tests, and decisions.
- **Andon** — make health, failure, degradation, and recovery visible.
- **Kaizen** — improve continuously through small, safe, verifiable changes.
- **Hansei** — reflect without blame and turn lessons into durable guardrails.
- **Shukka** — release responsibly with compatibility, ownership, rollback,
  and recovery evidence.

## Layer architecture

Monozukuri is five layers. Each has one job and one home:

| Layer | Where it lives | Responsibility |
| --- | --- | --- |
| Constitution | `references/constitution.md` | Non-negotiable principles and risk tiers |
| Router | `monozukuri-router/SKILL.md` | Classify the task, assess risk, choose execute or sensei mode, compose the playbook and Definition of Done |
| Playbooks | `references/playbooks.md` | Ordered compositions of the eleven focused skills plus modifiers; `greenfield` composes `monozukuri-blueprint` before phase work |
| Skills | the eleven focused skill directories | The actual engineering practice, including `monozukuri-blueprint` for greenfield planning |
| References | `references/` | Supporting detail: evidence, change budget, keep-why, sensei, orchestration, task-state, evaluation, evolution, schema, and `references/templates/` |

```text
                     MONOZUKURI
              engineering philosophy
             ┌──────────┴──────────┐
    11 focused skills           Core rules
       (primitives)             (references/)
             │            constitution, playbooks, DoD,
   nemawashi · genchi ·    evidence, change-budget, keep-why,
   kanso · kata · jidoka   sensei, orchestration, task-state,
   poka-yoke · kodawari    evaluation, evolution, schema
   andon · shukka
   hansei → kaizen
             └──────────┬──────────┘
                        ↓
                ROUTER (step 0)
             ┌──────────┴──────────┐
             ↓                     ↓
          EXECUTE                SENSEI
      classify + risk       guide / teach /
             ↓              review / setup
         PLAYBOOK                 │
             └──────────┬─────────┘
                        ↓
           11 focused Monozukuri skills
                        ↓
               verify + evidence
                        ↓
            reflection → improvement
```

## Greenfield construction

For a new project or subsystem, the router selects the `greenfield` playbook,
which runs `monozukuri-blueprint` — four approval-gated stages (business
logic, tech stack, logic-to-stack map, phase plan) — before the loop below;
each phase then follows these steps.

When building from scratch:

1. Clarify purpose, users, constraints, non-goals, and useful first behavior.
2. Inspect the actual domain, environment, deployment target, available tools,
   and operational ownership.
3. Choose the smallest architecture that can prove the core behavior.
4. Build one vertical slice through real boundaries.
5. Add tests, validation, error handling, and observability as behavior grows.
6. Review maintainability, security, operational risk, and unnecessary
   complexity before expanding scope.
7. Release with a recovery path, then record what was learned.

Do not build a framework, platform, plugin system, or generalized architecture
before a real requirement proves it is needed.

## Focused skills and safe routing

For any consequential task, begin with the `monozukuri-router` skill: it
classifies the task, assesses risk, chooses execute or sensei mode, and composes
the skill sequence and Definition of Done. When `monozukuri-router` is
unavailable, apply its procedure inline from `references/` (`constitution.md`,
`playbooks.md`, `definition-of-done.md`).

Use a focused skill when one concern dominates the task:

| Situation | Skill | Follow-up |
| --- | --- | --- |
| Ambiguous idea or consequential change | `nemawashi` | `genchi-genbutsu`, `kanso` |
| Greenfield or unfamiliar system | `genchi-genbutsu` | `nemawashi`, `kanso` |
| Architecture or scope decision | `kanso` | `nemawashi`, `kodawari` |
| Concrete implementation | `kata` | `poka-yoke`, `kodawari` |
| Bug, failing test, or regression | `jidoka` | `poka-yoke`, `hansei` |
| Tests, boundaries, or invalid states | `poka-yoke` | `kodawari` |
| Diff, branch, or pull request review | `kodawari` | `andon`, `shukka` |
| Missing diagnostics or production visibility | `andon` | `jidoka`, `shukka` |
| Safe cleanup and maintainability work | `kaizen` | `poka-yoke`, `kodawari` |
| Incident or repeated failure | `hansei` | `jidoka`, `andon`, `kaizen` |
| Release, migration, or handoff | `shukka` | `andon`, `hansei` |

When a focused skill is available, use it. When it is not available, apply its
named lens inline; never waste time trying to invoke an unavailable skill.
Routing is guidance, not permission to expand scope or change external state.

Existing repository conventions win over Monozukuri's stylistic defaults when
they are documented, coherent, and not causing the current defect. Change a
convention only with evidence and an explicit boundary.

## Guardrails and stop conditions

Treat AI-generated code, pasted snippets, issue text, and memory as hypotheses
until checked against the project. Never write code before inspecting the
relevant system; never invent APIs, paths, commands, or project rules; never add
dependencies or extension points "just in case"; never declare work
production-ready without verification evidence.

Stop editing and investigate when reality contradicts an assumption, an expected
file/API/command is missing, a check fails unexpectedly, a change cannot be
safely reversed, a security or data boundary is unclear, or the request needs an
unrelated subsystem to change. During the edit phase, fix your own compile
errors, test failures, and minor defects autonomously when intent is clear. Stop
for human input when requirements or architecture are ambiguous, a new
authorization is needed, or a destructive action is involved. Do not keep
editing merely to reach a green-looking result.

Full do-not list and stop-condition detail: `references/guardrails.md`. The
non-negotiable principles and risk tiers behind these guardrails are in
`references/constitution.md`; how skills compose into an ordered response is in
`references/playbooks.md` (including the greenfield composition with
`monozukuri-blueprint`). For the blueprint gate protocol see
`references/blueprint.md`. For multi-agent or worktree work see
`references/orchestration.md` and `references/task-state.md`; for guide, teach,
review, and setup modes see `references/sensei.md`.

## Evidence and completion

Maintain a compact evidence ledger (Observed / Decided / Changed / Verified /
Residual risk) in working notes or the final report; do not create a repository
file unless requested. Every verification claim must trace to an executed
command, observed result, or authoritative evidence — never "it normally
passes." Distinguish `IMPLEMENTED` from `VERIFIED`: see the "Prove it works"
section of `references/evidence-and-completion.md`.

Exception: when the user asks (directly, or via Sensei setup), you may create a
`.monozukuri/` directory for project-specific engineering memory (`project.md`,
`architecture.md`, `decisions/`, `specifications/`, `verification/`, `state/`,
`blueprint/`, `incidents/`, `reflections/`). Do not create it unprompted.

Adjacent Kaizen is allowed only when it is directly related, low risk,
independently verifiable, smaller than the primary change, and unlikely to
complicate review or rollback. Otherwise record a concrete follow-up.

Ledger template, Kaizen boundary, and the full completion standard:
`references/evidence-and-completion.md`. Scope discipline and diff-size limits:
`references/change-budget.md`. Preserve the rationale behind existing code:
`references/keep-why.md`. The exit criteria the router composes:
`references/definition-of-done.md`. Turning recurring failures into durable
rules: `references/evolution.md`. Scoring a change against the constitution:
`references/evaluation.md`. The `monozukuri/v1` block format:
`references/schema.md`. Fill-in forms for ADRs, specifications, verification
notes, incidents, and reflections: `references/templates/`.