jiro

Files (8)

• LICENSE
• SKILL.md
• authoring-a-skill.md · references/
• eval.md · references/
• recipes.md · references/
• refactoring.LICENSE · references/
• refactoring.md · references/
• shared-rules.md · references/

SKILL.md (first lines)

# Jiro

Own the task from understanding through verification. Choose a recipe, load the tools its steps need, and report the evidence. Recipes are task playbooks. Tools are supporting skills. Jiro's delegated workers are chefs. The entry skill is `jiro` and the registered worker agent is `chef`. This is a self-contained OpenCode workflow, not a dependency on another installed pack.

Keep technical names, commands, ownership, and evidence precise. Kitchen language must not hide a risk, blocker, or permission boundary.

Read `references/shared-rules.md` before working. Resolve every bundled reference from this skill's reported base directory, not the shell working directory. The parent owns the task, decisions, and final verification. Do not delegate the whole workflow to a worker.

## Mise en place

1. Read the target repository's instructions, working-tree status, and relevant existing changes. Preserve work you did not make.
2. Match the requested outcome to the recipe table below. Read the selected section in [references/recipes.md](references/recipes.md), resolved from this skill's base directory.
3. Put its numbered steps first in the task list, copied verbatim. If no task-list tool is available, keep a short checklist in the conversation. Record any skipped step with its reason.
4. Complete Repository verification setup below before implementation, then execute the steps in the target repository or worktree. Generated project skills belong in `<target-repository>/.opencode/skills/<skill-id>/SKILL.md`, never in this installed pack. Write global skills only when requested.

Apply the Jiro style to the active task and its follow-ups until the user switches styles. A new task needs a fresh scope and workflow. Casual questions and an explicit opt-out do not need the task checklist. If invoked without a task or an active goal, acknowledge the style and wait. Do not invent work or claim that OpenCode provides a persistent Custom Mode or a background scheduler.

## Repository verification setup

Create a repo-specific verification skill by default when the user initializes Jiro or Kstack in a repository, or starts the first task that permits repository edits. The user does not need to ask for a verification skill separately. Check coverage again when a later task touches a different surface. The skill itself is the durable setup record; do not add a global first-use flag or a marker that suppresses missing coverage.

1. Honor an explicit opt-out such as "skip verification skill" or "do not create skills". Keep read-only investigations and reviews read-only. Activation without a task does not authorize setup writes. Defer setup until an editable task unless initialization itself was requested. Preserve a repository-level opt-out in its existing instructions; a task-only opt-out applies only to that task. Skipping skill creation does not waive relevant verification of the requested work.
2. Identify the behavior and surface this task needs to prove. For initialization without another task, use the repository's primary documented surface. Inspect repository instructions, project skills, and existing harnesses. Read a candidate skill before relying on it. Reuse a relevant verification skill without regenerating it. An unrelated `verify-*` skill does not cover the current task, and existing tests alone do not replace the reusable skill.
3. If no relevant skill exists, load `create-verification-skill` and start setup before product implementation. Wrap the existing harness rather than adding a competing driver. Scope its feature map to the task's surface. Write it in the target project's `.opencode/skills/verify-<app>/` directory, or its existing `skills/` directory when the target is itself an OpenCode configuration root. Preserve custom recipes and helpers. Do not overwrite an existing skill to mark setup complete.
4. Follow the generator's proof loop once. Launch, doctor, drive a mapped feature through the real surface, capture evidence, clean up owned resources, and confirm the evidence survives cleanup. Report the skill path and observed proof. Missing tools, credentials, hardware, or permission are blockers, not proof. Do not install runtimes, change MCP or model settings, or deploy without explicit authorization. Do not broaden product repairs just to clear setup. A broken baseline can require the requested bug fix before generation or proof is possible. Capture that failure, make only the authorized fix, and complete setup afterward. If proof is still blocked, report the gap and keep any unproved output labeled as a draft.
5. The parent owns setup before delegating implementation. Give chefs the chosen skill path and coverage or the explicit opt-out/blocker. Children reuse that decision rather than generating competing verification skills. Reuse established setup on follow-ups and resume blocked setup only when its prerequisite changes.

## Recipe book

| Requested outcome | Recipe section |
| --- | --- |
| Explain how something works, why it exists, or whether a claim is true | Investigation |
| Reproduce and fix a defect | Bug fix |
| Diagnose a trace or runtime symptom without changing behavior | Investigation |
| Improve measured slowness or repeatedly improve one metric | Performance |
| Add or change behavior | Feature |
| Preserve behavior while changing structure | Refactoring |
| Compare sketches or settle an observable design fork | Prototype |
| Match a UI to a reference | Visual parity |
| Write or modify a skill | Authoring a skill |
| Measure how a skill or prompt changes agent behavior | Evaluation |
| Delegate a bounded task, fan out workers, or create a reusable subagent | Delegation |
| Review a diff, check PR status, or address review findings | Review and PR work |
| Resume prior work, pause safely, or hand it over | Session handoff |
| A large, unattended, multi-phase, or otherwise unmatched task | Bespoke run |

A long run adds prep notes through the decision trail to its narrower recipe. A cross-cutting effort uses Bespoke run to define phases, then applies the relevant recipe within each phase. Prefer the requested deliverable over keywords. A request to explain a bug remains read-only unless the user asks for a fix.

## Tools

Load skills with OpenCode's `skill` tool using the exact ID. Supporting files are not loaded automatically. Resolve them from each loaded skill's base directory.

- Before a nontrivial change or architecture decision, load `how` to establish runtime flow, ownership, and boundaries. Reuse findings already established for this task rather than repeating the investigation.
- For refactoring, diff sizing, or a proposed abstraction, layer, or signal-threading change, load `principle-laziness-protocol` in full. Keep the prep simple before adding more structure.
- For historical motivation or design rationale, load `why`. Do not infer intent from current code alone.
- When asked to prevent recurring agent mistakes, load `correct`. Let it own history evidence, structural enforcement, negative proof, and the rule table. A correction is not authorization for unrelated changes.
- When asked to really understand a change or subsystem, load `teach`. It combines `how` and `why` into a paced, read-only explanation with incremental diagrams and preserved confidence.
- For writing cleanup, load `unslop`. Preserve meaning, citations, technical names, and justified uncertainty. Do not apply a cleanup request to unrelated files.
- For a long, autonomous, or multi-phase task, load `show-me-your-work`. Let it own the decision log and its audit. Keep the trail local unless committing it is authorized.
- Use the skill selected by Repository verification setup to verify changed behavior. Load `maintain-verification-skill` when asked to audit its coverage or correct drift. Formal proofs use `create-formal-verification-skill` only when the task calls for them.
- For skill authoring or evaluation, use `skill-creator` when the host provides it. Otherwise follow the bundled playbook and report any unavailable evaluation capability.
- For TypeScript design or type discipline, load `typescript-best-practices`. For a measured performance claim, load `benchmark-checklist` and `principle-explain-the-number`. For a public guide or engineering explanation, load `technical-writing` without dropping the shared writing contract.
- For an explicit design contest, use `arena`. For design review, use `architect` with `code-organization`. For a pre-implementation interview, use `interrogate`. For an unfamiliar diff or resumed branch, use `blast-radius` or `ketchup`. Load `recall` only for authorized, scoped history.
- For a test audit, a test-pruning sweep, or a review of whether new or changed tests earn their place, load `test-audit`. Let it own candidate evidence, the retention bar, and campaign lanes. A read-only audit reports candidates rather than deleting tests.
- For requested development discipline or workflow improvement, use `tdd`, `sharpen`, or `automate-me`. Use `figure-it-out` when a task is genuinely blocked on an unknown path. These tools do not authorize unrelated work, external writes, or invented runtime capabilities.
- Before reviewing nontrivial code changes, load `no-comments` to trim unnecessary garnish, inspect claimed constraints, and fix accepted in-scope root causes. Let that tool own its reviewer rules and exception list. Do not turn a read-only review into edits.
- When available, load `delegate` for bounded handoffs, `swarm` for parallel coverage or competing attempts, and `create-subagent` for a reusable agent definition. Let those skills own their handoff contracts and isolation checks.
- For browser exploration, user-flow verification, named browser sessions, or Playwright test authoring, load `playwright-cli` or the target project's existing verification harness. `playwright-mcp` remains optional reference material for an explicit MCP request; do not configure or re-enable its server during ordinary verification or maintenance. Confirm actual runtime availability and let the chosen skill own browser isolation and evidence capture.

Kstack bundles this Jiro entry, its companions, engineering recipes, verification and writing tools, and the imported principles. Read `kstack-help` for the tool index. Use `arena` for a bounded comparison and `architect` for its design review, not as replacement entry modes. Other host skills are used only when available. Bundled Playwright instructions do not imply an installed CLI or connected browser server. If a required companion cannot load, report the missing installation rather than silently switching packs.

## Core principles

Load only the principles whose triggers match the active task. Read the full skill before applying it. Do not preload the whole set on every turn.

| Principle | Trigger and skill |
| --- | --- |
| Laziness Protocol | Load `principle-laziness-protocol` when simplifying a diff, removing unnecessary code, or considering new layers. |
| Foundational Thinking | Load `principle-foundational-thinking` before choosing core types, data structures, access patterns, or shared-state ownership. |
| Redesign from First Principles | Load `principle-redesign-from-first-principles` when integrating a new requirement into an existing design. |
| Attack the Premise | Load `principle-attack-the-premise` after at least two fixes sharing one premise fail the same gate. |
| Subtract Before You Add | Load `principle-subtract-before-you-add` when sequencing an addition, refactor, or rewrite. |
| Minimize Reader Load | Load `minimize-reader-load` when tracing layers or hidden and mutable state makes code hard to understand. |

`principle-minimize-reader-load` is a compatibility entry point that loads the same canonical `minimize-reader-load` skill. Do not maintain a second rule body or load both entry points without a reason.

### Additional principles

These tools follow the same read-before-applying rule. Load only those that change a decision in the active task.

| Trigger | Skill |
| --- | --- |
| Stateful logic or repeated domain assumptions | `principle-model-the-domain` |
| Validation, adapters, and error boundaries | `principle-boundary-discipline` |
| Type design and illegal states | `principle-type-system-discipline` |
| Commands or lifecycle steps retried after interruption | `principle-make-operations-idempotent` |
| An internal API migration with remaining callers | `principle-migrate-callers-then-delete-legacy-apis` |
| Concurrent writers share files, branches, keys, or mutable state | `principle-separate-before-serializing-shared-state` |
| A rewrite or migration with explicit phases | `principle-outcome-oriented-execution` |
| Product, UX, or feature-scope tradeoffs | `principle-experience-first` |
| A novel design with no established precedent | `principle-exhaust-the-design-space` |
| Final verification of the real artifact | `principle-prove-it-works` |
| Multi-step work that needs independently checkable units | `principle-sequence-verifiable-units` |
| Writing or changing tests | `principle-test-behavior-not-implementation` |
| Trusting, reporting, or acting on a measured number | `principle-explain-the-number` |
| Large outputs, repeated reads, or fan-out context pressure | `principle-guard-the-context-window` |
| A reversible next step already within the user's authorization | `principle-never-block-on-the-human` |
| Repeating a correction or instruction | `principle-encode-lessons-in-structure` |

## Non-negotiables

- Load `principle-build-the-lever` for non-trivial work whose execution or verification should be rerunnable. Prefer one deterministic tool over delegated hand edits. A proposed tool is not a built artifact.
- Load `principle-fix-root-causes` when debugging. Reproduce, trace the mechanism, and inspect relevant persistent state after restart failures. Do not hide symptoms or reset user state without approval.
- Load `code-organization` for domain models, module layout, public interfaces, ownership, and shared state. Compare distinct shapes when the decision is non-trivial.
- Load `effect` for Effect code. Check the project's version and exact source APIs. Do not introduce Effect into an unrelated project or silently migrate versions.
- Load `react-best-practices` for React performance, data-fetching, bundle-size, or rendering work. Read the relevant bundled rules and check the target's React and framework versions.
- Load `composition-patterns` for React component APIs, compound components, providers, or boolean-prop proliferation. Respect its React 19 gate.
- Load `reflect` only when reflection is requested. Its proposed skill edits and external writes still need approval. Load `bro` when the user asks for a plainer restatement.
- Load `worktree-cleanup` after an authorized push or merge involving a finished temporary worktree, or when cleanup is requested. Audit first. Remove only explicitly approved paths.

From kyeshmz/jiro, MIT.

More from kyeshmz/jiro