Use at the start of every agent session, even if the task seems obvious and you think you already know what to do. Activates when the agent has just opened a repository, does not know what to do, needs to orient itself, or is beginning any new session. Also activates for "where do I start?", "what should I work on?", "what is the current state?". Skipping orientation leads to wasted effort and missed context.
Installation
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Use at the start of every agent session, even if the task seems obvious and you think you already know what to do. Activates when the agent has just opened a repository, does not know what to do, needs to orient itself, or is beginning any new session. Also activates for "where do I start?", "what should I work on?", "what is the current state?". Skipping orientation leads to wasted effort and missed context.
metadata
{"kanbanzai-managed":"true","version":"0.4.0"}
SKILL: Kanbanzai Getting Started
Purpose
Orient an agent at the start of a session in a Kanbanzai-managed project.
When to Use
At the beginning of any new agent session
When you don't know what work to do or where to start
When resuming work after a break
Vocabulary
Session orientation — The mandatory startup sequence that establishes what state the project is in, what work is available, and what conventions apply before any implementation begins.
Work queue — The prioritised list of ready tasks returned by next(). The single source of truth for what an agent should work on.
Context packet — The assembled bundle of spec sections, knowledge entries, file paths, and role conventions returned when claiming a task with next(id).
Clean slate — The state where git status shows no uncommitted changes from previous work. Required before starting any new task.
Task claim — The act of calling next(id) to transition a task from ready to active and receive its context packet.
Feature lifecycle state — The current workflow stage of a feature entity (e.g. designing, specifying, implementing). Determines which skills, roles, and gates apply.
AGENTS.md — The project-specific conventions file in the repository root. Contains structure, build commands, Git discipline, and the pre-task checklist.
Stage binding — The mapping in .kbz/stage-bindings.yaml that connects each workflow stage to its required role, skill, and prerequisites.
Project status — The synthesised dashboard returned by status() showing progress, blocked items, and attention items across the project.
Session Start Checklist
Copy this checklist at the beginning of every session:
Server freshness — Call server_info to verify the running MCP binary is current. If in_sync is false or git_sha is unknown, the binary is stale — inform the human. Unexpected test results (passes that should fail, failures that should pass) may indicate a stale server.
Clean slate — Run git status. If changes are coherent and complete, commit them now. If changes are incomplete or belong to a different task, inform the human and stop — do not stash. Never use git stash in a Kanbanzai project: stashed changes hide workflow state from other agents and are silently lost across worktree switches.
Store check — If git status shows uncommitted .kbz/ files, commit them now. These are versioned project state, not ephemeral cache. Do not stash, discard, or .gitignore them.
Corpus integrity check — Call doc(action: "audit") and review its output before proceeding. If audit shows files on disk not registered → call doc(action: "import", path: "work") to register all unregistered documents. If audit shows registered records whose files are missing from disk → call doc(action: "delete", id: "DOC-xxx") for each stale record. After any batch registration, run a classification pass on newly registered documents (see the Classification (Layer 3) section in kanbanzai-documents) before proceeding. Rationale: an incomplete corpus produces false negatives in design searches, and a designer who finds no results cannot distinguish "not addressed" from "not registered".
Read project context — Read AGENTS.md if you have not this session.
Test health check — Call test(action: "verify") to check whether the test
suite on main is green. If the suite has failures, do not start new work — the
first priority is to fix the test suite. Pre-existing test failures are not
acceptable for new feature work to proceed.
Check the work queue — Call next() to see what is ready.
Claim your task — Call next(id: "TASK-xxx") to get full context for your chosen task.
Understand the workflow — If unsure about the current stage, check the kanbanzai-workflow skill.
Clean slate
Run git status. If there are uncommitted changes from previous work:
Changes are coherent and complete → commit them now, then proceed.
Changes belong to a different task or are incomplete → inform the human and stop. Do not stash, do not discard.
Never use git stash in a Kanbanzai project. Stashed changes hide workflow
state from parallel agents, are silently lost when switching worktrees, and
bypass the commit history that makes code review meaningful.
Commit workflow state
Even when the working tree looks clean for code, run:
git status
and look specifically for untracked or modified files under .kbz/state/,
.kbz/index/, or .kbz/context/. These are versioned project state — entity
records, document metadata, knowledge entries — that other agents depend on.
If any appear:
Stage and commit them immediately before starting any new work:
MCP tools (entity, doc, finish, decompose, merge) auto-commit state
changes during normal operation. Orphaned files appear when a previous session
was interrupted before the auto-commit could run. They are rare but consequential:
stale state causes parallel agents to read incorrect entity status and produce
conflicting transitions.
Corpus integrity check
Call doc(action: "audit") at the start of each session and review its output:
Unregistered files — Files on disk in configured roots that have no document record.
If found: call doc(action: "import", path: "work") to register all unregistered
documents in a single batch operation.
Stale records — Registered document records whose files are missing from disk.
If found: call doc(action: "delete", id: "DOC-xxx") for each stale record to remove
the orphaned reference.
After any batch registration triggered by the integrity check, run a classification pass
on the newly registered documents before proceeding. Follow the Classification (Layer 3)
section in kanbanzai-documents for the step-by-step procedure.
Rationale: An incomplete corpus produces false negatives in design searches. A designer
who searches for an architectural decision and finds no results cannot distinguish "this has
not been addressed" from "this was addressed in an unregistered document." Classification
ensures concept search returns accurate results.
Read the project context
Check whether an AGENTS.md exists in the repository root. If it does, read
it — it contains project-specific conventions, structure, and decisions. If it
does not, these Kanbanzai skills are your primary orientation.
Check the work queue
Call next (without an ID) to see what tasks are ready. If the queue is
empty, call status or entity action: list to understand the current
project state — active features, open bugs, what stage things are in.
Verify the entity exists (if working on one)
If your task refers to a plan (P{n}), batch (B{n}), or feature (FEAT-xxx) ID,
call entity(action: "get", id: "...") to confirm it exists before doing
any work. If the entity does not exist, STOP and ask the human whether to
create it. Never proceed with work under an unregistered entity name — it has
no lifecycle state, no worktree isolation, and no task tracking.
Claim your task
Call next with a task ID to claim it and get your instructions and
context. See kanbanzai-agents for the full dispatch-and-complete
protocol.
Understand the workflow
Kanbanzai has stage gates that require human approval at specific points.
See kanbanzai-workflow for the rules, the human/agent ownership boundary,
and when to stop and ask.
Each workflow stage (designing, specifying, developing, reviewing, etc.) maps
to a specific role and skill via .kbz/stage-bindings.yaml. Read the
binding for your current stage to know which role to adopt and which skill
procedure to follow. The task-execution skills themselves live in
.kbz/skills/ (e.g. write-design, write-spec, review-code,
orchestrate-review).
New-Project Onboarding
Applies when Kanbanzai is initialised for the first time in a repository with no
prior .kbz/ directory.
Steps
Configure document roots. Add your document directories to .kbz/config.yaml
under documents.roots. Execution work goes in work/{BatchID}-{batch-slug}/; strategic documents
go in work/{PlanID}-{plan-slug}/; project-level documents go in
work/_project/. See kanbanzai-documents for the canonical filename template.
Import all documents. For each configured root, run:
doc(action: "import", path: "<each-root>")
This registers all existing documents in that root. The import is idempotent —
running it multiple times is safe.
Verify with audit. Call doc(action: "audit") and confirm zero unregistered
files remain. Resolve any residual gaps before proceeding.
Run batch classification. Classify all registered documents in priority order:
Specifications first (most structured, highest value for concept search)
Designs second (narrative + architectural decisions)
Dev-plans third (task-oriented)
Research and reports last (lowest priority)
Follow the Classification (Layer 3) section in kanbanzai-documents for the
step-by-step procedure.
Validate the concept registry. Call:
doc_intel(action: "find", role: "decision")
If results are returned, the concept registry is populated and classification
was successful. If no results are returned, re-check that documents were classified
(not just registered).
Time estimate: Approximately 5–10 minutes per document for classification. For a
50-document corpus, expect approximately 4–8 hours of elapsed time.
Existing-Project Adoption
Applies when Kanbanzai is added to a project that already has documents outside
standard work/ directories.
Steps
Audit the repository for markdown files. Identify files not covered by your
configured roots:
find . -name "*.md" | grep -v ".kbz"
Review the output for design decisions, specifications, architectural rationale,
and requirements documents.
Decide which documents belong in the corpus. Not all markdown files are
workflow documents. Include: design decisions, specifications, architectural
rationale, requirements. Exclude: README files, changelogs, generated documentation,
and transient notes.
Add additional roots as needed. If documents are found outside standard
directories, add those directories to .kbz/config.yaml under documents.roots.
Register and classify. Follow the New-Project Onboarding procedure (above)
to import, verify, and classify all documents.
Key principle: The corpus must be complete enough that a negative search result
means "this has not been addressed" rather than "this might have been addressed in
an unregistered document."
Anti-Patterns
Skipping Orientation
Detect: Agent starts implementing without calling next() or reading AGENTS.md.
BECAUSE: Without orientation, the agent misses project conventions, active decisions, and existing work — leading to duplicated effort or conflicting changes.
Resolve: Always run the session start checklist before writing any code.
Stale Context Carry-Over
Detect: Agent assumes context from a previous session is still current (e.g. task status, branch state, file contents).
BECAUSE: Entity states, knowledge entries, and file contents change between sessions. Stale assumptions produce incorrect implementation decisions that compound as work progresses.
Resolve: Always check git status and call next() at session start. Treat every session as a fresh start.
Store Neglect
Detect: Uncommitted .kbz/state/ files visible in git status at session start.
BECAUSE: Store drift causes race conditions when parallel agents read stale entity state, leading to conflicting transitions and lost updates.
Resolve: Commit .kbz/ files immediately. Do not stash, discard, or gitignore them.
Shell-Querying Workflow State Files
Detect: Agent runs cat, grep, find, or similar shell commands against .kbz/state/, .kbz/index/, or .kbz/context/ directories to retrieve entity data.
BECAUSE: Raw YAML files contain unresolved state. MCP tools apply lifecycle resolution, inheritance, computed fields, and cross-reference validation. Shell queries bypass all of this and produce subtly wrong results — wrong status, missing computed fields, stale index data — that lead to incorrect implementation decisions.
Resolve: Use MCP tools exclusively for all workflow state queries:
Entity status → entity(action: "get", id: "...")
Project overview → status()
Knowledge entries → knowledge(action: "list")
Documents → doc(action: "get", path: "...")
Never read .kbz/state/ files with shell tools or read_file.
Evaluation Criteria
Did the agent run git status and address uncommitted changes before starting work? — Required
Did the agent call next() to check the work queue? — Required
Did the agent claim a specific task before beginning implementation? — High
Did the agent read AGENTS.md if it was their first action in the session? — Medium
Questions This Skill Answers
What do I do at the start of a session?
How do I find out what work is available?
How do I claim a task?
What if there are uncommitted changes from a previous session?
Where are the project conventions?
What is the difference between system skills and task-execution skills?
How do I know what stage the project is in?
Related
kanbanzai-workflow — stage gates, lifecycle, when to stop and ask
kanbanzai-planning — how to run a planning conversation
write-design — how to collaborate on design documents
Resuming an in-flight batch
When returning to a batch started in a previous session, run this checklist before dispatching any sub-agents:
Commit orphaned .kbz/ changes. Run git status in the main repository. If any files under .kbz/state/, .kbz/index/, or .kbz/context/ appear as modified or untracked, commit them immediately: git add .kbz/ && git commit -m "chore(state): commit orphaned workflow state". Do not stash or discard these files — they are versioned project state.
Check the batch lifecycle state.(Transitional — becomes unnecessary after P28 Sprint 2 merges.) Call status(id: "B<N>-<slug>"). If the batch shows proposed, call entity(action: "transition", id: "B<N>-<slug>", status: "designing", override: true, override_reason: "Resuming in-flight batch; bypassing designing stage gate"), then entity(action: "transition", id: "B<N>-<slug>", status: "active").
Confirm dev-plan documents for each feature.(Transitional — becomes unnecessary after P28 Sprint 2 merges.) For each feature at dev-planning or later, call status(id: "FEAT-xxx") and check has_dev_plan. If false, apply the gate override: entity(action: "transition", id: "FEAT-xxx", status: "developing", override: true, override_reason: "Resuming in-flight batch; dev-plan document registered separately").
Confirm worktrees for in-flight features. For each feature at developing, call worktree(action: "get", entity_id: "FEAT-xxx"). If no worktree exists, create one. If worktree(action: "create") times out, fall back to: terminal(cd: "<repo-root>", command: "git worktree add -b <branch-name> .worktrees/<path> main"), then write the YAML state file manually to .kbz/state/worktrees/WT-<id>.yaml.
