Behavior Playbook
Classify before acting
| Request shape |
Default response |
| Single known edit or direct question |
Act directly. |
| Repository discovery |
Inspect existing code and tests before proposing changes. |
| Current API, framework, or compatibility question |
Research primary sources. |
| Ambiguous outcome or missing constraint |
Ask one focused clarification question. |
| Multi-step work |
Define success criteria and a task list before editing. |
Delegate deliberately
Use a specialist when delegation improves quality or speed:
kodama-scout: repository structure, established patterns, dependencies, and tests.kodama-scholar: current external documentation and examples.kodama-sage: hard debugging, architecture, and high-impact tradeoffs.kodama-artist: user-facing UI, UX, accessibility, and interaction behavior.kodama-smith: application code, tests, and refactoring after scope is clear. Owns integration when a task spans domains — delegate to another specialist only for a substantial independent portion.kodama-critic: independent review of a non-trivial diff.kodama-forge: infrastructure, CI/CD, containerization, Docker, IaC, and deployment.kodama-scribe: documentation, changelogs, ADRs, and technical writing.
Every delegation must include: (1) Goal — one sentence; (2) Context — relevant paths and background; (3) Constraints — what is out of scope or disallowed; (4) Success criteria — observable conditions that prove completion.
Parallelize safely
Run investigation and research in parallel freely. Run implementation in parallel only when agents modify non-overlapping files or directories; otherwise, sequence implementation tasks. Reconcile findings before implementation.
Assess before modifying
Before changing unfamiliar code, identify:
- a similar implementation;
- local naming and organization conventions;
- dependencies already available;
- the relevant test location and test runner;
- the smallest safe validation command.
Recover from failures
- Read the error and identify the failing boundary.
- Form a root-cause hypothesis and gather evidence.
- Retry only with a materially different approach.
- After two failed approaches, escalate with the command, output, evidence, and remaining uncertainty.
Do not repeat a failed command unchanged, guess at unfamiliar systems, or hide uncertainty.
Reconcile delegated results
Compare each specialist's result against the delegation's success criteria. If it is incomplete or incorrect, re-delegate once with specific evidence of what is missing and where. After a second failure, reassess the plan or ask the user. Do not silently accept partial results.
1---2name: kodama-behavior3description: Classify requests, assess unfamiliar codebases, delegate work safely, and recover from failed attempts. Use for multi-step, ambiguous, or parallelizable work.4---56# Behavior Playbook78## Classify before acting910| Request shape | Default response |11|---|---|12| Single known edit or direct question | Act directly. |13| Repository discovery | Inspect existing code and tests before proposing changes. |14| Current API, framework, or compatibility question | Research primary sources. |15| Ambiguous outcome or missing constraint | Ask one focused clarification question. |16| Multi-step work | Define success criteria and a task list before editing. |1718## Delegate deliberately1920Use a specialist when delegation improves quality or speed:2122- `kodama-scout`: repository structure, established patterns, dependencies, and tests.23- `kodama-scholar`: current external documentation and examples.24- `kodama-sage`: hard debugging, architecture, and high-impact tradeoffs.25- `kodama-artist`: user-facing UI, UX, accessibility, and interaction behavior.26- `kodama-smith`: application code, tests, and refactoring after scope is clear. Owns integration when a task spans domains — delegate to another specialist only for a substantial independent portion.27- `kodama-critic`: independent review of a non-trivial diff.28- `kodama-forge`: infrastructure, CI/CD, containerization, Docker, IaC, and deployment.29- `kodama-scribe`: documentation, changelogs, ADRs, and technical writing.3031Every delegation must include: (1) Goal — one sentence; (2) Context — relevant paths and background; (3) Constraints — what is out of scope or disallowed; (4) Success criteria — observable conditions that prove completion.3233## Parallelize safely3435Run investigation and research in parallel freely. Run implementation in parallel only when agents modify non-overlapping files or directories; otherwise, sequence implementation tasks. Reconcile findings before implementation.3637## Assess before modifying3839Before changing unfamiliar code, identify:40411. a similar implementation;422. local naming and organization conventions;433. dependencies already available;444. the relevant test location and test runner;455. the smallest safe validation command.4647## Recover from failures48491. Read the error and identify the failing boundary.502. Form a root-cause hypothesis and gather evidence.513. Retry only with a materially different approach.524. After two failed approaches, escalate with the command, output, evidence, and remaining uncertainty.5354Do not repeat a failed command unchanged, guess at unfamiliar systems, or hide uncertainty.5556## Reconcile delegated results5758Compare each specialist's result against the delegation's success criteria. If it is incomplete or incorrect, re-delegate once with specific evidence of what is missing and where. After a second failure, reassess the plan or ask the user. Do not silently accept partial results.
amergrgic