Migrate a legacy tile.json plugin to the .tessl-plugin/plugin.json form. Runs `tessl plugin migrate`, renames .tileignore to .tesslignore, removes the obsolete tile.json, re-lints, then reconciles residual "tile" wording to "plugin" in the repo's prose. Use when a repo still has a tile.json (and no .tessl-plugin/plugin.json), or when the user asks to migrate / convert / modernize a tile.json plugin, move off tile.json, or adopt the plugin.json manifest form.

Add the files that run the `jbaruch/coding-policy` coding-rule review on a repo's pull requests: scaffold a `.github/fleet-review-enabled` marker, a `.github/workflows/review-trigger.yml` (on each PR, starts a review of that PR against the coding-policy rules), a `.github/copilot-instructions.md` pointing Copilot at the code-quality lane, and a `.env.example` entry, then open a PR. While the marker is present the same review also runs on a schedule as a backstop; both post as a review. The consumer sets one `FLEET_DISPATCH_TOKEN` secret that `review-trigger.yml` reads. Use when the user wants to add, install, enable, scaffold, set up, wire up, or enroll an automated policy review / PR reviewer / coding-policy reviewer in a consumer repo. Also use to upgrade or refresh the reviewer files in a repo that already has them (override mode).

Structured workflow for shipping code via GitHub pull requests: PR creation, dual-lens automated review (the Codex code-review app for `rules/*.md` compliance + Copilot for correctness and risk), merge, and branch cleanup. Covers readiness checks, version reasoning, review polling, feedback handling, and post-merge verification. Use when the user wants to open a pull request, ship code, merge a branch, or handle post-merge cleanup on GitHub.

On a byAir precheck wake event, reconciles the operator's managed calendar events and composes a user-facing flight notification — delay, gate change, cancellation, boarding, connection risk, inbound delay, time to leave, baggage carousel, day-before check, or arrival logistics. Also configures the plugin (verify credentials, set home base). Use when a tracked-flight wake event needs a notification, or when setting up or diagnosing flight-assist — 'diagnose flight-assist', 'set flight-assist home base', 'configure flight-assist'.

Travel-data refresh bundle: TripIt → Reclaim timezone sync, refresh travel-schedule.json from the TripIt iCal feed with a two-tier Gmail freshness probe, rebuild travel-db.json, log newly-appeared trips to daily memory, then check upcoming trips for booking gaps. Runs daily; precheck-gated on travel-db.json freshness and schema currency. Triggers: 'sync trips', 'sync travel', 'update travel data', 'pull trip info', 'refresh travel schedule', 'rebuild travel db', 'check my bookings'.

Adaptive scheduler for the TripIt/byAir refresh of active-flights.json. Precheck-gated to keep byAir polling responsive on flight days and idle between travel windows. Use when active-flights.json isn't updating, byAir polling cadence isn't matching flight density, troubleshooting flight tracking / flight notifications / flight status updates / travel schedule refresh, or setting up flight-assist on a new install. The gate predicate and threshold constants live in precheck.py.

Shared travel-domain library bundle for the nanoclaw-travel plugin. Hosts the cross-skill Python modules trip_origin (TripIt-over-home position/anchor resolution) and airport_lead (clearance / post-arrival buffer policy) so flight-assist and the drive engine import one source of truth instead of duplicating them. Not a user workflow — background code the other skills load at runtime; never invoke directly.

Kill a running agent container on the NAS by Telegram group JID. The orchestrator respawns a fresh container on the next message. Does NOT delete registration or group folder. Use when a container is stuck, stale, or needs a fresh start.

Promote agent-created skills and rules from NAS staging to plugin GitHub repos — opens a PR from staging, then hands the review, merge, and publish-confirmation lifecycle to the release skill. Use when there are new items on staging, after check-staging shows pending items, or when asked to deploy skills, push to production, or publish rules to a plugin repo. The promote scripts keep the historical `TILE_NAME` env var.

Verify that all tessl plugins are in sync between git source, tessl registry, and the NAS orchestrator. Reports drift, unpublished content, untracked files, and version mismatches. Use when plugin state seems wrong, container behavior looks stale, you suspect out-of-sync plugins, or need to check plugin health before a release. Run after promoting skills or after any manual plugin edits. The script keeps its historical name, `./scripts/reconcile-tiles.sh`.

Ship a committed code change to private NanoClaw (jbaruch/nanoclaw) through a reviewed PR, merge, and branch cleanup. Use when asked to ship a NanoClaw fix, open its PR, or merge its changes. Plugin repositories use the release skill directly.

Pull updates from qwibitai/nanoclaw directly into private NanoClaw through a reviewed PR, then deploy to NAS. Use when upstream has new features, when the user asks to update NanoClaw, or when /update-nanoclaw is invoked.

Get typed structured output from a Koog 1.2 agent — pick between `nodeLLMRequestStructured` (graph DSL, schema-driven JSON) and `responseProcessor` (top-level on the agent factory, simpler shape). Defines the `@Serializable` output class and wires it into the strategy or the factory. Use when the user asks to "return JSON", "get a typed response", "use structured output", "return a data class from the agent", or shows a `data class` they want as the agent's output.

Add token-budgeting and per-provider tokenizer support to a Koog 1.2 agent — install the tokenizer feature, set per-run or per-node budgets, and react to budget exhaustion (compress history, abort, swap models). Use when the user asks to "limit tokens per run", "add a token budget", "prevent runaway agent costs", "use a tokenizer", or describes cost containment requirements.

Add a new tool to an existing Koog 1.2 agent. Pick the right registration style (@Tool + ToolSet annotation, Tool[TArgs,TResult] subclass, or sub-agent-as-tool), define the args, and wire the tool into the agent's ToolRegistry. Use when the user asks to "add a tool to my agent", "expose something to the LLM", "let the agent call a function", or "wrap this agent as a tool for another agent". Assumes a scaffolded Koog 1.2 project — for new projects invoke Skill(skill: "scaffold-agent") first.

Author a custom graph strategy for a Koog 1.2 agent — pick the right node types, chain tool execution correctly, build edges with the infix vocabulary, and reach for subgraphs (`subgraphWithTask`, `subgraphWithVerification`) when steps deserve their own model, prompt, or tool subset while still sharing the agent's message history. Use when the user asks to "write a custom strategy", "build a graph for the agent", "author a strategy DSL", "add a verify-and-fix loop", "use subgraphs", or describes multi-step orchestration that won't fit inside `singleRunStrategy()`. Subgraphs are not for context isolation — for an independent agent that does not see the parent's history, use `Skill(skill: "add-tool")` Step 3 (sub-agent-as-tool).

Add in-process caching of LLM calls to a Koog 1.2 agent via `prompt-executor-cached` — cache whole prompt→response pairs locally so identical calls skip the API. Distinct from provider-side Anthropic prompt caching (covered by `enable-prompt-caching`). Backends include in-memory (default), file-based, and Redis. Use when the user asks to "cache LLM responses", "avoid duplicate API calls", "add a response cache", "cache to Redis", or describes repeated identical prompts in dev/test.

Author prompts for a Koog 1.2 agent using the `prompt { ... }` DSL — system messages, user turns, few-shot examples, mixed media, and runtime augmentation via the `SystemPromptAugmenter` / `UserPromptAugmenter` family. Use when the user asks to "write a system prompt with examples", "add few-shot examples", "build a prompt", "augment the prompt at runtime", or moves beyond the single-string `systemPrompt` parameter on the factory.

Author a Koog 1.2 agent as a typed pipeline of domain-modeled subtasks — tools sliced by access pattern (read / write / communication) into separate ToolSets, inter-subtask handoffs as `@Serializable` `@LLMDescription`-annotated data classes (not text prompts), each subtask wired with `subgraphWithTask[In, Out]` using its own model and tool subset, self-correction loops via `subgraphWithVerification[T]` + `CriticResult[T]`. The integration pattern Koog's own banking demo uses. Use when the user asks to "model the agent as a pipeline", "build a multi-stage agent with typed handoffs", "give each stage its own tools", "build a verify-and-fix loop with typed data", or describes a workflow with distinct phases that should hand structured data to each other.

Enable Anthropic prompt caching for a Koog 1.2 agent — automatic caching is on by default in 1.0, but explicit `cacheControl` breakpoints let you control which parts of long prompts get cached. Surfaces cache-hit metrics through the OpenTelemetry token-usage span. Use when the user asks to "enable prompt caching", "reduce Anthropic costs", "add cache_control", "set cache breakpoints", or describes expensive repeated calls with shared system prompt content.

Install per-step event handlers on a Koog 1.2 agent — tool-call start/end, LLM request/response, agent finish, error events. Useful for stdout logging during development, visualizing planner decisions on stage during demos, or pushing events to a non-OTel sink. Use when the user asks to "log tool calls", "see what the agent is doing", "add event handlers", "visualize the planner", "trace each step" — anything where the goal is human-readable per-step output, not production metrics.

Work with Koog 1.2 agent state — typed key-value `storage` on `AIAgentContext`, history compression strategies (TL;DR, sliding window, fact retrieval), and the `LongTermMemory` feature (which replaces the removed `AgentMemory`) for cross-session recall. Use when the user asks to "store state across nodes", "compress conversation history", "remember things across sessions", "add long-term memory", or names any of these surfaces.

Migrate a Koog 0.x codebase to 1.0. Koog 1.0 (2026-05-21) removed every @Deprecated API in one sweep — 0.x code does not compile against 1.0. Walks through construction surface, planner module split, graph DSL renames, Java interop overhaul, HTTP transport decoupling, memory APIs, OpenTelemetry, persistence, prompt package move, retired models, and JDK/tooling minima. Use when the user asks to "migrate from 0.x", "bump Koog to 1.0", "upgrade Koog", or shows code that uses pre-1.0 APIs (e.g., AIAgent.invoke, AgentMemory, AIAgentPlannerStrategy.builder).

Model a problem domain as a tree of typed subtasks the Koog 1.2 planner can execute — the `PlannerNode` data model, parallel vs sequential composition, accessing in-flight subtasks through `AIAgentStorage`, retry-on-parse-failure edges, and TL;DR compression between phases. Goes deeper than `use-planner` (which only picks the planner factory). Use when the user asks to "decompose into subtasks", "model the agent's work as a tree", "compose parallel and sequential steps", "retry failed subtasks", or describes a richer planner usage than the basic factory.

Persist a Koog 1.2 agent's chat history to a durable backend — JDBC database (`chat-history-jdbc`), AWS storage (`chat-history-aws`), or SQL-typed chat memory (`chat-memory-sql`) — so conversations survive process restarts and can be retrieved by session ID. Distinct from generic agent persistence (state checkpoints) and from LongTermMemory (fact retrieval). Use when the user asks to "save chat history", "persist conversations", "resume a chat by session", "store chat in Postgres / DynamoDB".

Give a Koog 1.2 agent the ability to query a SQL database safely — install `agents-features-sql`, register the database connection, and expose schema-aware query tools the LLM can call. Includes safety guidance (read-only by default, schema scoping, parameterized queries). Use when the user asks to "let the agent query the database", "add SQL to my agent", "expose a database to the LLM", or describes data-retrieval needs the LLM should drive.

Bootstrap a new Koog 1.2 Kotlin agent project from scratch: Gradle setup with the right dependencies, JDK 17 toolchain, application Main that constructs an AIAgent via the top-level factory, and an environment-variable wiring for the LLM API key. Use when the user asks to "create a new Koog agent", "start a Koog project", "scaffold an agent app", or provides a directory and says "set up Koog here". Produces a runnable hello-world agent that the user can extend with tools, strategies, or features. Do NOT use when the user is constructing a planner, picking a strategy variant, or naming a specific agent shape inside an existing project — use `use-planner` or `author-strategy` instead.

Snapshot a running Koog 1.2 agent's state at arbitrary points and restore later — distinct from the persistence checkpoint loop in `add-persistence`. Snapshots are caller-triggered; persistence is automatic and continuous. Use when the user asks to "snapshot the agent", "save state at this point", "restore from a snapshot", or names the `agents-features-snapshot` module.

Test Koog 1.2 agents deterministically — install `agents-test`, mock the prompt executor with scripted responses, inject a fake `KoogClock` for time-sensitive logic, and assert on tool-call sequences. Use when the user asks to "test the agent", "mock the LLM in tests", "write unit tests for my Koog agent", or describes flaky or expensive tests that hit a real LLM.

Install the `agents-features-trace` feature to capture detailed internal trace events from a Koog 1.2 agent — node entries, edge transitions, planner decisions, feature lifecycle. Distinct from OpenTelemetry (production signal, GenAI vocabulary) and event handlers (high-level callbacks). Use when the user asks to "debug what the strategy is doing", "trace internal agent decisions", "see why the planner picked that step", or describes deep diagnostic needs.

Give a Koog 1.2 agent capability bundles it discovers from the filesystem at runtime, using the `skills` module that implements the Agent Skills specification (agentskills.io). Discovers SKILL.md files, generates a catalog prompt block, and registers the file tools the agent needs to disclose and apply them. Use when the user asks to "add agent skills", "use the Agent Skills spec", "let the agent discover capabilities", "load skills from a directory", "add a SKILL.md", or names `discoverSkills` / `generateSkillsPrompt`. New in Koog 1.2.0 — not available on 1.0 or 1.1.

Send non-text content (images, files, audio) to the LLM as message attachments in a Koog 1.2 agent — provider-aware encoding and the `attachments` block in the prompt DSL. Use when the user asks to "send an image to the LLM", "use multimodal input", "attach a file", "pass a PDF", or describes input the LLM should process that isn't plain text.

Drive another vendor's CLI coding agent (Claude Code, OpenAI Codex, or an arbitrary binary) from inside a Koog agent using `CliAIAgent`, and compose it into a graph strategy with `.asNode()`. Authenticates through whatever subscription that CLI is already logged into, so no API key is needed. Use when the user asks to "call Claude Code from Koog", "use my Claude/Codex subscription instead of an API key", "orchestrate multiple coding agents", "use a different vendor for one step", or names `CliAIAgent` / `agents-cli`. New in Koog 1.1.1.

Use `FunctionalAIAgent` — the third concrete agent subtype in Koog 1.2 (alongside `GraphAIAgent` and `PlannerAIAgent`). Wraps a single suspending block, no graph DSL, no planner — just programmer-written logic that calls the LLM and tools directly. Use when the user asks to "skip the graph DSL", "write the agent body as plain code", "use AIAgentFunctionalStrategy", or describes a one-shot agent shape that doesn't warrant a topology.

Use a non-default LLM node variant inside a Koog 1.2 strategy — streaming output, multiple-choice sampling, content moderation, or forcing a specific tool call. Use when the user asks for "streaming", "multiple completions / sampling", "moderation", "force one tool", "force the LLM to call a specific tool", or names any of `nodeLLMRequestStreaming`, `nodeLLMRequestMultipleChoices`, `nodeLLMModerateText`, `nodeLLMRequestForceOneTool`.

Pick and wire a planner-driven Koog 1.2 agent — either LLM-based (the LLM picks the next action each turn, optionally with a critic loop) or GOAP (a classical planner searches a typed state space toward a goal). Pulls `ai.koog:agents-planner`, constructs the planner strategy, and wires it into `AIAgent(...)`. Use when the user asks to "use a planner", "let the agent plan", "use GOAP", "build a planning agent", names any of `Planners.llmBased`, `Planners.llmBasedWithCritic`, `Planners.goap`, `PlannerAIAgent`, `agents-planner`, or describes an open-ended task whose step sequence depends on runtime context.

Wire the Agent-to-Agent (A2A) protocol — expose a Koog 1.2 agent as an A2A server, or consume a remote A2A server as a client (typically to make a remote agent callable as a tool by a local agent). Use when the user asks to "expose the agent via A2A", "use A2A protocol", "call a remote agent", "register an A2A client", or names any of `a2a-server`, `a2a-client`.

Expose a Koog 1.2 agent through the Agent Client Protocol (ACP) — the lower-level bidirectional protocol used by tooling that needs fine-grained control over agent invocation lifecycle (cancellation, streaming progress, multi-turn negotiation). Use when the user asks to "expose the agent via ACP", "use Agent Client Protocol", "wire ACP", or names the `agents-features-acp` module.

Expose a Koog 1.2 agent through a Ktor server — install the `koog-ktor` plugin, load agent configuration from `application.conf` / `.yaml`, and register MCP servers inside the plugin block. Use when the user asks to "expose the agent over HTTP", "add Koog to my Ktor app", "wire the Ktor plugin", or describes a server-shaped deployment.

Connect a Koog 1.2 agent to an MCP (Model Context Protocol) server, using the primary Streamable HTTP transport — or fall back to SSE / stdio when the remote server doesn't speak Streamable HTTP yet. Adds the agents-mcp dependency, builds a ToolRegistry from the MCP server's exposed tools, and merges it with the agent's existing tool registry. Use when the user asks to "connect to an MCP server", "use the GitHub MCP server", "add MCP tools to my agent", "wire Playwright MCP" or similar. Assumes a scaffolded Koog 1.2 project.

Wire Koog 1.2 into a Spring Boot application via `koog-spring-boot-starter` — per-provider autoconfig, `MultiLLMAutoConfiguration` aggregation, and the `application.yml` shape for agent name, model, system prompt, and tools (including MCP entries). Use when the user asks to "use Koog in Spring Boot", "wire the Spring starter", "configure providers via application.yml", "add Koog to my Spring app".

Classify installed skills as proactive (apply to all code, review at every commit) or reactive (domain-specific, use only when working in that domain). Use after installing new skills via skill-search. The classification drives which skills quality-standards includes in CLAUDE.md and which skills self-review checks against.

Orchestrates practice gap discovery and quality improvement. Coordinates gap-analysis, skill-search, skill-classifier, quality-standards, and self-review skills. Use when starting a new project, joining an existing codebase, beginning a major feature, or when the user asks "what skills do I need", "find best practices", "audit this project".

Search the Tessl registry for skills that fill practice gaps identified by gap-analysis. Uses a two-pass strategy: first find language-agnostic best practice skills, then find technology-specific skills for the project's stack. Use after gap-analysis identifies gaps, when entering a new technology domain, or when the user asks "find skills for X", "what best practices exist for Y".

Set up self-verification before building features — test runner, type checking, linting, and feedback loops that let the agent confirm its own work. Use when starting a new project, setting up a codebase for the first time, or when the user asks "how will you test this", "set up testing", "make sure this works", or "verify your work". Run this BEFORE writing feature code.

Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.

Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.

Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.

Sync delta specs from a change to main specs. Use when the user wants to update main specs with changes from a delta spec, without archiving the change.

Reviews the entire PLAN.md of a new project through fixed, file-only provider rounds. Triggered by plan-mode when every plan entry is draft; Round 1 alternates Codex and Claude, then returns control to a human checkpoint.

Builds and maintains openspec/PLAN.md, the human-approved plan that sequences OpenSpec changes toward a stated goal — the tier above tasks.md. Explore read-only, draft entries, then stop and ask for approval; a change cannot start until its entry is approved. Trigger — make a plan, what should we build first, plan the work, roadmap, add this to the plan, approve the plan, why is the plan gate failing, NO-ENTRY, HASH-MISMATCH.

Rewrites a confirmed REFINED_PROMPT.md from prompt-loop into an ENGINEERED_PROMPT.md ready to execute: cleaned of reasoning-scripting and shouting, structured into the task contract (objective, context, scope, tools, action boundaries, verification, output, stop condition), every change traced to a numbered prompting rule, the lock register carried byte-identical, and an effort level recommended. Runs in a fresh-context subagent and never asks the user anything. Trigger — automatically after prompt-loop's output contract is confirmed and before openspec-propose, for non-trivial development work; explicitly on: engineer this prompt, ottimizza il prompt, prompt engineering, ingegnerizza il prompt, make this prompt executable. Do not use it on a prompt that has not been through prompt-loop: without a confirmed REFINED_PROMPT.md there is nothing to engineer.

Refines an incoming prompt through a bounded score → interview → lock → rewrite loop until it is mechanically good enough (rubric score ≥ 9/10) to feed the SDD workflow. Trigger — automatically before openspec-propose when the request is non-trivial development work; explicitly on: refine this prompt, prompt loop, score my prompt, is this prompt ready.

Structured interview process that turns a vague stakeholder request into clear, actionable requirements before any spec or code is written. Trigger — new feature request, unclear requirements, vague task, clarify scope, before proposing a change.

Single entry point to the spec-as-source workflow: given a request, decides which of the plugin's skills to activate — excluding trivial work first, deriving the current phase from the state of the repo second, and matching descriptions last — then runs the chosen skill inline or in a subagent. Use when you do not know which skill applies, or want the workflow driven for you. Trigger — which skill should I use, what do I do next, route this, start working on X, implement X, propose a change, continue the implementation, I want to build X, help me with this project, non so da dove partire.

Installs the spec-as-source OpenSpec schema, enforcement scripts, CI workflow, and pre-commit hooks into a project. Trigger — setup spec enforcement, add spec checks, configure spec-as-source, install spec scripts, add spec CI, install openspec schema.

Syncs .github/workflows/spec-verification.yml with the test runner and test files declared in specs. Trigger — update CI workflow, sync spec CI, regenerate workflow, CI out of sync with specs, add spec test to CI.

Runs an autonomous Ralph-style loop over the tasks of an active OpenSpec change: one task per fresh-context agent invocation, mechanically gated by scripts/verify.sh, with runaway guardrails. Trigger — run the loop, ralph loop, autonomous apply, loop the tasks, implement the change unattended.

Deletes all files declared as targets in openspec/specs/**/spec.md and rebuilds them from the specs to verify spec-as-source integrity. Trigger — clean rebuild, verify source of truth, spec drift check, regenerate from specifications, rebuild from spec.

Runs all spec consistency checks (link integrity, target ownership, manifest build), the test suite, and a semantic drift spot-check, then reports results. Trigger — verify specs, spec check, run spec suite, check spec consistency, validate spec links, spec integrity, spec drift.

Creates and maintains capability spec.md files under openspec/specs/: requirements, scenarios, targets frontmatter, and Verified by test links. Trigger — write a spec, update a spec, document requirements, create capability spec, spec drift in frontmatter or links.

Reviews completed implementation requirement-by-requirement against its capability spec, with file:line evidence, before declaring work done. Trigger — review my work, is this done, verify completeness, check against spec before merging, final review.

Shared utility scripts for DLD skills. Not intended for direct invocation — used internally by other DLD skills.

Record a single development decision as a markdown file with YAML frontmatter. Collects context, rationale, and code references interactively.

Implement one or more proposed decisions. Makes code changes, adds `@decision` annotations, and updates decision status.

Bootstrap DLD (Decision-Linked Development) in a repository. Creates dld.config.yaml, the decisions/ directory, and INDEX.md. Run once per project.

Look up decisions by ID, tag, code path, or keyword. IMPORTANT — use this proactively whenever you encounter `@decision` annotations in code you are about to read or modify.

Break down a feature into multiple decisions interactively. Creates a set of decision records grouped by a shared tag.

Resolve decision ID collisions between a local branch and the base branch (and open PRs) before rebasing. Renames colliding local decisions with git mv, rewrites cross-references and annotations, then squashes branch commits into a single rebase-clean reindex commit.

Bootstrap DLD decisions from an existing codebase. Analyzes code to infer rationale, generates decision records, and adds `@decision` annotations.

Generate SNAPSHOT.md (detailed decision reference) and OVERVIEW.md (narrative synthesis with diagrams) from the decision log.

Quick overview of the decision log state — counts by status, recent decisions, and run tracking info.