kido-workspace 0.1.0

package/.agents/rules/base.md

@@ -0,0 +1,18 @@
+---
+trigger: always_on
+description: Bootstrap the KIDO workflow and apply the current workspace's instructions and source routing.
+---
+
+# KIDO Workspace Bootstrap
+
+This rule is distributed from `rules/base.md` and installed as `.agents/rules/base.md` in the target project. Project paths below are relative to the current workspace root, not the template repository checkout.
+
+Read root `AGENTS.md` when present and any additional instructions governing target paths. Use the entrypoint supported by the environment when the project has another convention. If instructions are missing, report the gap and use onboarding when asked to set them up. Get domain routing, invariants, shell and command rules, permissions, and response conventions from the current workspace; do not copy another project's policy.
+
+Use [kido-workflow](../skills/kido-workflow/SKILL.md) for routing and permission rules. Questions, reviews, and documentation-only requests stay in their scope. Bounded code changes use an approved in-chat design and checks; material business/API/architecture changes use Story/AC/Spec and design/plan gates. Honor explicit user instructions and matching authorization under workspace policy.
+
+For onboarding, follow the default entry flow in [kido-onboarding](../skills/kido-onboarding/SKILL.md). From an initialized workspace, discover the root and FE/BE locally, then ask once whether to move components outside `packages/` into it or create symlinks. After the placement choice, survey BE APIs for TypeSpec and the project for glossary, current-state, and overview. Shared context and the root entrypoint belong in the parent workspace; a component's Git root does not redirect them. Respect an explicit component-only request and authorized filesystem scope. Onboarding does not require creating Epics, Specs, or implementation plans.
+
+Keep document boundaries: `context/` holds system knowledge; `epics/` holds outcomes, AC, and behavior; `packages/<pkg>/plans/` holds implementation details. Put code, hooks, CSS, and source-file lists in plans.
+
+During implementation and review fixes, follow the workflow's document freeze: code/tests and progress/evidence first, pending Spec/contract deltas in the plan or chat, one consolidated synchronization after explicit code acceptance. Code-generation inputs require an explicitly approved strategy, not continuous contract edits. Apply the workflow's action boundaries and report only observed evidence.

package/.agents/skills/kido-brainstorming/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: kido-brainstorming
+description: Use before a KIDO product or executable-code change to prepare a reviewable design and obtain design approval; excludes answer-only and review-only requests.
+---
+
+# KIDO Brainstorming
+
+Follow the permissions and routing in [kido-workflow](../kido-workflow/SKILL.md). Produce an approach grounded in the request and established decisions, ready to inform product documents.
+
+## Choose the depth
+
+| Case | Approach |
+| --- | --- |
+| Feasibility inquiry | Investigate read-only and report a conclusion. Retained prototypes or other mutations require authorization. |
+| Bounded change | Existing flow, clear scope, no material business/API/schema/architecture change: present scope, observable acceptance checks, approach, and verification in chat. No mandatory new Story, Spec, or plan file. |
+| Full-flow change | Material business/API/schema/architecture impact: analyze alternatives, boundaries and interfaces, reuse or prepare Story/AC/Spec, and present a more complete design. |
+
+State the chosen depth. Explain and adjust if the scope grows. Do not turn a question or review into an implementation request.
+
+## Process
+
+1. Read the current flow and relevant domain sources. Reuse related requirements when they exist; bounded work does not require searching for or creating a complete Epic/Story/Spec set. Identify applicable contract and design-system boundaries.
+2. Separate the user's requirements, observed behavior, and assumptions. A mock only proves what it shows; do not invent behavior, exceptions, or AC.
+3. Ask about missing decisions that affect scope, behavior, or acceptance. Group related questions when helpful. Do not re-request authorization already granted for the same result.
+4. Before designing a new function, hook, service, or component, use `rg -n` to find comparable logic and read definitions and callers. Reuse or extend a fitting abstraction; add one only for a distinct responsibility, lifecycle, or interface and explain why. For an architectural change, compare two or three genuine alternatives and their tradeoffs.
+5. Describe the main flow, states, errors, boundaries, and verification at a depth appropriate to the change. Keep module responsibilities clear and avoid unrelated features or refactors. Name the contract and shared design sources that must change.
+6. For independent subsystems, define separately acceptable slices and dependency order. Each slice must serve the requested outcome.
+7. For full-flow work, use [kido-writing-specs](../kido-writing-specs/SKILL.md) once to establish suitable Story, AC, and Spec coverage; record expected contract deltas and keep unapproved material Draft. Present the design before [kido-writing-plans](../kido-writing-plans/SKILL.md). For bounded work, hand the approved in-chat design directly to [kido-executing-plans](../kido-executing-plans/SKILL.md). Apply the workflow's implementation document freeze after either handoff.
+
+## Decision gate
+
+- Present reviewable scope and AC, flows, errors, alternatives, and SSOT impact under the workspace design gate. Record and reuse an explicit approval for the same design and scope.
+- Ask the decision owner about unresolved product decisions; continue independent authorized work while dependent work waits.
+- Developer-authored Draft or Pending PO/BA review documents remain at that status even when ready for technical planning.
+- Bounded work needs approval of its short design, unless matching authorization or an explicit user instruction already establishes the approach. It does not need a separate plan approval. Full-flow work keeps the design and plan gates. Reclassify for material scope changes, not routine fixes.
+
+## Handoff
+
+Summarize scope, approach, open decisions, reused or changed documents, and the next step. Use a diagram or mock only when it clarifies a specific decision.

package/.agents/skills/kido-code-review/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: kido-code-review
+description: Use when reviewing KIDO code, skills, rules, or templates against requirements, or evaluating review feedback before applying corrections.
+---
+
+# KIDO Code Review
+
+Follow [kido-workflow](../kido-workflow/SKILL.md), including its action boundaries and implementation document freeze. Choose review or feedback resolution according to the request; review alone stays read-only.
+
+## Review changes
+
+Read the approved plan or bounded in-chat design, diff, and only requirements needed to assess the change. Do not repeat design/spec audits. Assess against the approved delta; deferred Spec/contract synchronization is pending work, not a defect demanding document edits before review. Flag behavior outside that delta. For documentation/skills/templates, use the request's criteria without creating product documents or plans. Separate task changes from pre-existing changes.
+
+Check:
+
+1. Do behavior and errors meet applicable AC/Spec or bounded chat acceptance checks?
+2. Are interfaces, schemas, business rules, and invariants preserved?
+3. Are races, state loss, missing validation, or side effects unaddressed?
+4. Is there out-of-scope work, code/document drift, or an assumption presented as fact?
+5. What does observed evidence establish, and what remains unverified or lacks a baseline?
+6. Is approval present for the selected bounded or full flow? Does a behavior change have RED → GREEN evidence or an approved TDD exception? Do not flag a missing plan or Story for bounded work when the workflow does not require one.
+7. For new functions, hooks, services, or components, were comparable definitions and callers inspected? Could an existing abstraction be reused? Is the distinct responsibility, lifecycle, or interface explained?
+8. Does code match the currently approved contract and any explicitly planned delta? Are generated or legacy artifacts mistaken for authority? Does frontend work follow and, when needed, update the design system?
+9. For skills, rules, and templates, do triggers route correctly, links resolve from their containing files, instructions respect policy, examples remain examples, and structural or behavioral claims match evidence?
+
+Give each finding its impact, path and line where useful, trigger, consequence, and violated requirement. Prioritize real defects and gaps over preferred refactors or features with no consumer.
+
+If delegation is authorized and useful, brief a reviewer on the request, sources, paths or diff, read/write and command limits, and expected report. Do not require an agent or helper script by default; review directly when delegation is unnecessary.
+
+Report findings by impact, open questions, and verification limits. If none are found, say no findings were identified within the reviewed scope, without asserting the whole system is correct.
+
+## Resolve feedback
+
+1. Read all feedback and identify the requested outcome. Ask about ambiguity that blocks dependent work; continue independent authorized work.
+2. Compare each comment with code, the approved baseline, and user decisions. Read Story/AC/Spec/contract only where needed; neither assume the reviewer is right nor defend code solely because it exists.
+3. Classify comments as defects, requirement gaps, product decisions, or preferences. Ask the owner about unresolved product decisions; do not rewrite AC to justify feedback.
+4. Address authorized corrections within the approved design/plan or bounded chat scope. Routine fixes stay in implementation without Spec/contract synchronization or renewed gates. A material scope/behavior change needs a targeted decision before dependent work. Use [kido-debugging](../kido-debugging/SKILL.md) and [kido-testing](../kido-testing/SKILL.md) where relevant.
+5. Explain evidence and reasons for deferred or rejected feedback. Correct a mistaken earlier conclusion briefly and continue.
+
+Do not add an API, abstraction, or dependency merely for polish without a real outcome or consumer. Do not post comments to an external service without authorization.
+
+## Handoff
+
+Report resolved, deferred, and rejected findings with reasons. Accumulate pending Spec/contract deltas in the existing plan or chat during review fixes; synchronize once after code acceptance. An explicitly requested document-only correction is separate. Use [kido-verification](../kido-verification/SKILL.md) for evidence and limits, and the workflow's action boundaries for integration, external comments, or cleanup.
+
+In implementation, self-review does not replace user review. Hand off a diff, AC or chat-check mapping, TDD evidence, and pending SSOT deltas as `Pending code review`; record acceptance only after explicit feedback.

package/.agents/skills/kido-debugging/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: kido-debugging
+description: Use when investigating a KIDO bug, failed check, intermittent failure, or unexpected behavior before proposing or implementing a fix.
+---
+
+# KIDO Debugging
+
+Follow [kido-workflow](../kido-workflow/SKILL.md), including its action boundaries. Find the cause before proposing a fix. Investigation stays read-only when no fix was requested.
+
+## 1. Collect evidence
+
+- Read the complete error and stack trace, inputs, before/after state, frequency, and reproduction steps. Compare with established Story/Spec/contract behavior or the bounded request's acceptance checks.
+- Inspect relevant code and recent changes read-only. Determine whether the failure predates the current change.
+- Reproduce using an authorized command. If permission or a reliable reproduction is missing, state the evidence gap rather than presenting a hypothesis as a confirmed cause.
+- For multi-component failures, locate the divergence with existing logs or fixtures. Instrumentation edits use the applicable bounded or full flow and matching command authorization; keep temporary diagnostic work within that scope. Do not expose secrets or mutate live data for a probe.
+
+## 2. Trace the data
+
+Starting at the failure, follow the wrong value through its caller, transformations, defaults, validation, and origin. Stop at the first contract violation, not merely where an exception surfaced. Compare with a working flow in the same codebase and identify relevant differences before copying its pattern.
+
+## 3. Test a hypothesis
+
+State a falsifiable cause: “X causes Y because Z,” with evidence. Choose the smallest authorized probe that distinguishes true from false, changing one variable at a time. If disproved, revisit the evidence rather than layering patches.
+
+For timing failures, wait on a real event or state getter instead of increasing arbitrary sleeps. Polling needs a timeout and fresh state on each attempt. Use a controlled clock when timing itself is the behavior under test.
+
+## 4. Fix the cause
+
+If a fix is requested, choose the bounded or full flow under [kido-workflow](../kido-workflow/SKILL.md). A bounded correction uses a short approved design and observable checks in chat; a material behavior/API/architecture change establishes Story/AC/Spec and an approved plan first. For failures inside an approved implementation, reuse its baseline and stay in [kido-executing-plans](../kido-executing-plans/SKILL.md); do not re-audit or update Spec/contract for every failed check. Use [kido-testing](../kido-testing/SKILL.md) for regression evidence.
+
+For bad data, identify independent boundaries that can receive it. Validate at the responsible boundary, check invariants before material side effects, and log according to project conventions. Avoid duplicating checks at every layer or claiming impossibility without evidence.
+
+When repeated patches fail or expose new coupling or state, stop adding patches and reassess the hypothesis and design. Ask for decisions that change scope while continuing read-only work where useful.
+
+## Handoff
+
+Report symptoms, confirmed cause or open hypothesis, evidence, fix scope, and verification. Keep established Spec/contract sources fixed during implementation and record pending deltas in the existing plan or chat. Handle material scope changes through a targeted decision; consolidate document updates after code acceptance. Use [kido-verification](../kido-verification/SKILL.md) before claiming the bug is fixed; state missing reproduction or verification explicitly.

package/.agents/skills/kido-executing-plans/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: kido-executing-plans
+description: Use when implementing an authorized KIDO change with an approved full-flow plan or bounded in-chat design.
+---
+
+# KIDO Executing Plans
+
+Follow [kido-workflow](../kido-workflow/SKILL.md), including its action boundaries and implementation document freeze. Deliver the approved change with traceability and evidence.
+
+## Before editing
+
+1. Confirm implementation was requested and matching authorization exists: an approved full-flow design/plan or bounded in-chat design with acceptance checks. Honor explicit user instructions under the workflow. Do not demand a plan file for bounded work or infer implementation permission from a review-only or plan-only request.
+2. Use that approved baseline throughout implementation. Read only upstream sources needed for a concrete question; do not restart design/spec audits, update Spec/contract after code edits, or rewrite requirements to match code. For a material conflict, pause affected work for a targeted decision rather than refreshing all documents.
+3. Inspect the working tree read-only and distinguish existing changes from task changes. Do not change branch or require a worktree by default. Confirm the package is writable within task scope; a path under `packages/` may be a symlink into a reference repository.
+4. Read the code and callers needed for the current plan task, including comparable implementations when introducing a new function, hook, service, or component. Keep inspection bounded to understanding behavior, side effects, and test seams; do not perform a broad reverse review of the repository.
+5. Consult the relevant contract only when needed for the API boundary, schema, or invariant. Implement against the approved delta and keep canonical Spec/contract sources fixed until code acceptance. If generation requires changed inputs, follow only the temporary-input/artifact strategy explicitly authorized before implementation; otherwise report the specific blocker. Do not create evolving contract copies.
+6. Check needed commands against the workflow's action boundaries, reusing matching session authorization.
+
+## Execution loop
+
+- Track active, completed, and blocked tasks in the existing plan or chat for bounded work. Update progress, evidence, and pending deltas only for work actually done.
+- Make the minimum AC-serving change under current code and design-system conventions. Avoid broad refactors, dependencies, or unrequested behavior.
+- Implement and verify against the approved baseline, then hand off the code and pending document deltas. Code-review fixes within that scope stay in this execution loop; do not call writing-specs or writing-plans again by default. After explicit code acceptance, synchronize affected Specs, contracts, required artifacts, and planned shared UI/context sources once under the workflow.
+- For failures, use [kido-debugging](../kido-debugging/SKILL.md) to establish the cause.
+- For behavior changes and bugs, follow [kido-testing](../kido-testing/SKILL.md) and the approved plan or chat checks: write a meaningful test, observe valid RED, implement GREEN, and refactor as needed. If required TDD cannot run under current authorization, prepare the test and command before the corresponding production edit and follow the workflow's permission gate. Use approved TDD exceptions and suitable checks for mechanical changes.
+- Apply the required project formatter when editing imports. If its command is unauthorized, prepare files and request that exact permission before claiming formatting is complete.
+- Before code acceptance, report pending SSOT deltas without applying them after each edit or review round. Distinguish implemented, verified, deployed, and accepted; do not claim success without evidence.
+- Share concise progress when a finding, blocker, or changed approach affects the outcome. Continue independent authorized work while blocked work waits.
+
+## Blockers
+
+For a missing dependency, permission, source, or product decision, identify the blocked portion and the required input or action. Do not guess requirements or expand authority. Investigate failed verification and distinguish task regressions from baseline failures with evidence.
+
+Use worktrees or delegation only when available and authorized. Give any worker a clear scope, sources, paths, command limits, and evidence requirement; review its diff. Multiple agents are not required by default.
+
+## Finish
+
+Self-review with [kido-code-review](../kido-code-review/SKILL.md); do not create a reviewer agent by default. Use [kido-verification](../kido-verification/SKILL.md) to map AC or chat acceptance checks, diff, RED/GREEN evidence, pending SSOT deltas, and unverified work. Hand off as `Pending code review`; keep Spec/contract synchronization pending until explicit acceptance.
+
+Preserve the working tree, branch, and pre-existing changes; apply the workflow's action boundaries for any integration or cleanup.

package/.agents/skills/kido-onboarding/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: kido-onboarding
+description: Use when asked to onboard a repository to KIDO or refresh its project context and agent instructions from repository evidence; excludes ordinary feature work and requests only explaining installation.
+---
+
+# KIDO Onboarding
+
+Survey the repository and create or update project context, authority mapping, and agent instructions. Produce sourced documents and explicit open decisions. Onboarding is separate from npm installation and feature implementation; installing a skill or finding missing context does not trigger it automatically.
+
+## Scope and permission
+
+- Read the current root entrypoint, instructions governing target paths, and [kido-workflow](../kido-workflow/SKILL.md). Use its action boundaries for common permission rules. Onboarding document/contract creation is independent of the implementation document freeze.
+- A survey or review request is read-only. A setup or onboarding request permits creating or updating in-scope documentation and the TypeSpec contract described below. Component moves or symlinks require the explicit placement choice below; that choice authorizes only the listed placement operations. It does not authorize application source edits, tests, scripts, dependencies, or other repository-layout changes. Stricter project policy still applies.
+- Preserve existing changes. Check symlinks before reading or writing. A reference service is not writable merely because it appears in the workspace; do not traverse symlinks into another repository without scope and permission.
+- Never read environment files, including examples. Avoid credentials, private keys, and customer data. Exclude sensitive sources before searching; do not search the whole repository and filter secrets afterward, or copy incidental secrets into documents.
+- A survey uses read-only operations and does not require running the application. Commands in manifests, CI, or scripts are configuration evidence; any execution follows the workflow's action boundaries.
+
+## 1. Survey selectively
+
+### Default entry flow after init
+
+When invoked in an initialized workspace with a simple request such as “onboard”, use that workspace as the project root unless instructions or component evidence conflict. Do not require the user to repeat the root, component names, or skill path when these are discoverable locally. Installation metadata and root instructions establish the workspace; a sibling component's `.git` does not override it.
+
+For a read-only survey, keep the current layout, report proposed placement, and survey sources in place; do not ask for or perform a move merely to complete the survey. The placement-and-writing sequence below applies to an actual onboarding request.
+
+1. Read applicable instructions and inspect the immediate layout, installation metadata, and component manifests only far enough to identify the workspace and its FE/BE components. Distinguish component repositories from template resources and unrelated directories.
+2. **The first user decision is component placement.** For components outside `packages/`, ask one combined question: move the listed FE/BE directories into `packages/<existing-component-name>/`, or keep their source paths and create symlinks there? Show each source and destination. Apply this whether invoked at the parent workspace or inside a component. Ask only about unresolved components; reuse an existing explicit choice and keep already placed components in place. Clarify the root first only if actual evidence makes it ambiguous.
+3. Wait for the choice before moving, linking, or writing documents with placement-dependent source links. The answer authorizes the listed placement operations within permitted scope; do not request the same choice again. Check real paths, destination collisions, and repository boundaries first. Preserve repository contents, Git metadata, existing changes, and component policy. Do not overwrite a destination or move a parent into its descendant. Use relative symlink targets where possible and verify that each package resolves to the intended source. Do not run source scripts or edit application code to repair assumptions about old paths; report those issues. Record the chosen layout and actual source paths in the onboarding report.
+4. After placement, inventory the owned BE API and write the evidenced TypeSpec contract under `context/contracts/` using the contract procedure below. If no BE is present, record that gap and continue with the available components.
+5. Survey the FE, BE, and relevant shared documents to populate `context/glossary.md`, `context/current-state.md`, and `context/overview.md`, then the architecture maps, onboarding report, and root agent instructions. Cross-check FE API usage against the BE contract and report differences rather than inventing BE behavior. Keep unsurveyed behavior explicit.
+
+This flow does not require creating Epics, Stories, Specs, or implementation plans.
+
+### Resolve the onboarding root before writing
+
+Distinguish the **project/workspace root**, which owns shared context and agent instructions, from each **component repository root**, which owns application source. The current working directory, a component's `.git`, or the location of an API manifest does not by itself select the onboarding root.
+
+- Use the project root explicitly named by the user. For whole-project onboarding, inspect the authorized workspace layout, existing root instructions, KIDO installation metadata, and component mapping before selecting document destinations. A parent workspace may contain multiple independent Git repositories and need not itself have `.git`.
+- When the requested project contains sibling component repositories, initialize shared `context/` (including `context/contracts/`), the root agent entrypoint, and any requested shared product documents under the confirmed project root. Survey each component within authorized scope and link to its source paths; finding an API component does not move shared context into that component. For component placement under `packages/`, follow the explicit move-or-symlink choice described below.
+- Apply the placement decision in the default entry flow to all in-scope components outside `packages/`, including sibling FE/BE repositories when invoked from the parent workspace. If started inside a component source tree, distinguish that component from the workspace before offering placement. Never select the source itself as a move destination beneath that source. Continue independent read-only work while waiting; defer writes whose destination or source links depend on the decision.
+- The target initialized workspace layout is `context/` for shared context and TypeSpec API contracts, `.agents/` for skills, rules, templates and installation metadata, `epics/` for Epics/Stories/Specs, and `packages/` for FE/BE and other component code. Keep `.agents/` as the shared source; agent-specific adapters such as `.claude/` may link to it. Do not create a second `agents/` tree or migrate an existing layout silently. Layout migration belongs to an explicitly requested CLI upgrade or a separately authorized migration.
+- If invoked from a component directory, inspect the parent layout only when it is within authorized scope. Use evidence connecting the components to the requested project, not similar names alone. If the parent cannot be inspected or the project boundary remains ambiguous, ask for the intended project root before writing; do not silently fall back to component-local initialization. An explicit request to onboard only one component keeps that component as the target.
+- Preserve existing component context and instructions. If shared context was previously initialized inside a component, report its location and the conflict; create or update authorized parent documents without silently deleting, moving, or overwriting component policy. A migration of existing material needs matching scope and reconciled links.
+
+State the selected root, component survey scope, and document destinations before writing. Record them in `context/architecture/workspace-onboarding.md`; resolve all destinations below against that selected root. This is not permission to write outside the authorized workspace.
+
+Use `rg --files` to inventory owned directories, excluding environment files, dependencies, vendor code, Git internals, generated output, and artifacts. Use an equivalent read-only listing if `rg` is unavailable. Do not follow symlinks by default.
+
+Read only what each question needs:
+
+| Question | Preferred sources |
+| --- | --- |
+| Purpose, actors, domain language | README, existing context, confirmed requirements |
+| Components and ownership | Workspace manifests, layout, symlink metadata, package instructions |
+| Architecture and integrations | Architecture documents, ADRs, entrypoints, modules, representative callers |
+| Contract authority and actual API | Existing TypeSpec or schema sources, generator chain, routes/controllers/handlers, request and response DTOs, validation, errors, authorization, and API documents |
+| UI standards | Design-system index, tokens, components, patterns |
+| Workflow and commands | Agent instructions, manifests, test configuration, relevant CI or scripts; inspect only |
+| State and backlog | Relevant code, dated and scoped evidence, existing Stories, Specs, plans |
+
+For a large repository, begin with a representative flow per major component, then expand where relationships or conflicts require it. Record unsurveyed areas; do not generalize from a small sample. The contract inventory below must separately state its actual API coverage.
+
+Map components by relative path, responsibility, major dependencies, ownership (`Owned`, `Reference`, or explicitly authorized `External writable`), and survey limits. Record both package paths and real source paths for symlinked components. A chosen link to an in-scope owned component permits surveying that source; unrelated or external symlinks still require matching scope and permission. Do not infer placement from the template.
+
+## 2. Classify evidence and authority
+
+Link material conclusions to real sources and label them:
+
+- **Observed:** present in code, configuration, or documentation, with source and scope. Documentation does not prove runtime behavior.
+- **Confirmed:** a requirement or decision supported by the responsible owner or an authoritative source; preserve its original status.
+- **Inferred / unclear:** explain the basis and needed confirmation. Do not turn it into an approved invariant, AC, permission, or contract.
+
+Distinguish canonical contracts, generated artifacts, and legacy documents using generator evidence or decisions. When authority is uncertain, record candidates and the gap; neither recency nor filename decides it. Do not copy schema into a second SSOT or invent an ADR to approve an inference.
+
+For each contract, record the source edited when an API or schema changes, its entrypoint and imports, generated artifacts, and SSOT confirmation state. TypeSpec `.tsp` files are candidate sources when the project uses TypeSpec; emitted OpenAPI or JSON Schema is an artifact unless the project decided otherwise. An empty TypeSpec scaffold is not a complete business contract.
+
+Group outstanding decisions about purpose, actors, ownership, conflicting sources, and policy. Ask only about blockers to dependent work; continue sourced independent work. Do not re-request facts or permissions already established in the session.
+
+## 3. Create or update project documents
+
+Read target documents before editing. Reuse existing sources; link from context to material in `docs/` or elsewhere instead of copying or moving it without cause. Create files with useful content, not batches of empty placeholders.
+
+| Destination | Required content |
+| --- | --- |
+| `context/overview.md` | Problem, actors and outcomes, system boundaries, constraints, and sources; use the [overview template](../../templates/context/overview.md) when available. |
+| `context/glossary.md` | Domain terms, aliases, sources, and confirmation state; use the [glossary template](../../templates/context/glossary.md) when available. |
+| `context/current-state.md` | State by component, gaps, dated and scoped evidence; distinguish implementation, verification, deployment, and acceptance. Use the [current-state template](../../templates/context/current-state.md) when available. |
+| Existing architecture document, or `context/architecture/system-overview.md` | Major components, data and control flows, integrations, observed boundaries, and links to authority; do not invent an architecture decision. |
+| Existing contract map, or `context/architecture/contracts.md` | Canonical source by domain, TypeSpec entrypoint and module links under `context/contracts/`, generated artifacts, migration status, and open questions; do not duplicate schema. |
+| `context/architecture/workspace-onboarding.md` | Selected project root and why, component repository roots, document destinations, survey scope, ownership map, sources read, document changes, conflicts, questions, and proposed policy decisions. Update it on reruns. |
+| Root agent entrypoint | Project snapshot, layout and ownership, domain routing, workflow, and existing permissions; use the [workspace instructions template](../../templates/workspace-instructions.md) when available. |
+
+Template links resolve from this skill directory. If the skill was distributed without templates, follow the content requirements without adding broken links. Resolve links from their destination files and only link to sources that exist. Replace placeholders with `Unconfirmed`, `Not surveyed`, or `Not applicable` and a reason where appropriate.
+
+### Build a TypeSpec contract from the project
+
+When asked to initialize context, survey existing contracts **and** API/schema in owned source, then write substantive TypeSpec for behavior supported by evidence. The repository need not already have OpenAPI or Proto. A Springdoc dependency indicates a possible toolchain, not a verified specification; routes, DTOs, validation, and error handling provide evidence of the implemented API. Follow a project policy that explicitly selects another contract format or forbids `.tsp`, and record that decision.
+
+1. Locate existing `.tsp`, `tspconfig.yaml`, OpenAPI, Proto, JSON Schema, and generators. Identify canonical sources and generated artifacts. Inventory the owned API from routes, controllers, handlers, request and response DTOs, validation, authorization, and errors. Follow the calls needed to determine actual methods, paths, parameters, bodies, and responses. Do not claim complete API coverage from a representative controller; record what was not surveyed.
+2. Default the TypeSpec project to `context/contracts/`, with `tspconfig.yaml`, a short `main.tsp`, and folders by domain or bounded context. The root `main.tsp` imports each module entrypoint, for example `import "./orders/main.tsp";`. Each `<domain>/main.tsp` imports its smaller model and operation files. Split a large domain further by resource; place genuinely shared models in one shared module. Give each definition one owner, use clear namespaces, and avoid circular imports. Configure `kind: project` and `entrypoint: main.tsp`. Check destination content and symlinks before writing. Keep a project-prescribed TypeSpec location when policy requires it. If a root `contracts/` tree is only an earlier KIDO scaffold, move its content and update imports, links, and configuration rather than leaving two canonical copies.
+3. Put evidenced models, services, and operations into the appropriate modules. Do not put the entire API in `main.tsp` or another monolithic file. On a rerun, use domain routing to read and update affected modules; inspect others for dependencies or cross-domain changes. Do not leave only a comment scaffold when a describable API was found.
+4. Compare each definition with its sources: method and path, request, response, status and errors, validation, and authorization where observed. Do not invent fields, enums, statuses, or business rules. When code and API documentation conflict, record both and the divergence. Put code-supported portions in TypeSpec as Draft; leave unresolved behavior as an open decision rather than choosing silently. If no API/schema is verified in the surveyed scope, report that scope and mark the scaffold as lacking business contract content.
+5. Preserve an existing non-TypeSpec canonical contract during migration. Record the current authority, TypeSpec SSOT target, converted and unconverted coverage, and affected artifacts. With no previous canonical contract, TypeSpec derived from code remains Draft until API coverage, conflicts, and authority are reviewed and approved. Record the real TypeSpec path, domain-module map, coverage, and status (`Confirmed SSOT`, `Draft — derived from code`, `Awaiting migration`, or `Scaffold — no verified API`) in architecture mapping, `context/current-state.md`, and agent routing. Do not add emitters, npm dependencies, scripts, or generated output without separate scope and permission; identify existing toolchain or record a gap.
+
+TypeSpec supports file imports as described in its [official import guide](https://typespec.io/docs/language-basics/imports/). `kind: project` and `entrypoint` are documented in its [configuration guide](https://typespec.io/docs/handbook/configuration/configuration/). Do not run `tsp init`, `tsp compile`, npm install, or generators without command permission. File existence does not prove compilation passes.
+
+Keep new inferred material Draft or Unconfirmed. Do not downgrade approved documents or promote drafts to Approved. Existing code does not prove tests passed, production deployment, or acceptance; old CI results apply only to their revision and scope.
+
+If onboarding includes product templates, add missing Epic, Story, or Spec templates from the installed set to `epics/_template/`, preserving project customizations. Do not invent historical Epics, Stories, or AC for existing features. Write product specifications only for a real request under the specs workflow. Do not create an implementation plan without a task and suitable design.
+
+## 4. Agent instructions and shared resources
+
+- Keep shared skills and rules in `.agents/skills/` and `.agents/rules/`; keep project-specific policy and knowledge in the root entrypoint and `context/`. Do not copy project business rules into shared skills or modify installed skills and rules to finish onboarding.
+- For an existing entrypoint, add missing mapping and facts in place. Preserve its constraints, structure, and manual content. Do not overwrite the whole file, weaken policy, or expand permissions. Record unresolved policy conflicts as proposals while existing policy remains effective.
+- If no entrypoint exists, write a short one for the actual environment, linking to context and shared workflow. Distinguish Draft facts from required KIDO process; do not copy placeholders or invent command allowlists. State missing permissions. Use the shared default workflow when no project decision exists, without importing another project's policy.
+- If `AGENTS.md`, `CLAUDE.md`, or an agent adapter directory is a symlink, update the source once within authorized scope. Preserve independent files as independent policies; link to shared sources when useful without silently merging or replacing them with symlinks.
+- Configure an adapter only when requested and when its format and discovery are verified in existing configuration or official documentation. Otherwise report a gap; do not assume every agent loads `.agents/rules/`.
+- npm installation distributes resources separately. Do not create a package, postinstall, or executable scanner as part of documentation onboarding.
+
+## 5. Review and handoff
+
+Review the actual result:
+
+1. Relative links resolve from their containing files and do not point to merely planned sources. Canonical sources are not duplicated.
+2. Material claims have sources and status; domain rules, invariants, and commands are not borrowed from another project.
+3. Domain routing points to real sources; ownership and symlinks reflect actual permissions.
+4. Draft is not approval; existing policy remains intact; unrun commands are not reported as passed.
+5. Reruns add evidence or update changed gaps without duplicating sections or deleting manual content just because it differs from a template.
+6. When APIs are observed, TypeSpec contains matching definitions and the mapping shows evidence and coverage. `context/contracts/main.tsp` imports modules, imports resolve, and no duplicate root KIDO contract remains. The config, entrypoint, and mapping refer to one project. Unverified portions and conflicts remain gaps; a scaffold is not called complete and an old canonical contract is not silently displaced.
+7. Shared documents and the root entrypoint are at the selected project root. Whole-project onboarding includes the authorized sibling components in its ownership map and reports unsurveyed areas; component Git roots have not redirected shared context into one component. The placement choice was obtained or reused for components outside `packages/`, destinations match that choice, and symlinks resolve to the recorded sources. Reruns do not move or link already placed components again. A single-component target reflects an explicit request or established project boundary.
+
+Hand off changed files, surveyed scope, authority found, checks actually run, and open questions. For a read-only request, deliver proposals instead of writing files. Follow required workspace checks, but do not impose code gates, runtime pilots, or compiler validation on a documentation task without a reason and permission. Suggest next steps grounded in actual gaps; do not continue into code changes, npm publication, or acceptance claims.

package/.agents/skills/kido-testing/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: kido-testing
+description: Use for TDD on authorized KIDO behavior changes and bug fixes, or explicitly requested test work, under the bounded or full change flow.
+---
+
+# KIDO Testing
+
+Follow [kido-workflow](../kido-workflow/SKILL.md), including its action boundaries. Use meaningful TDD for behavior changes and bugs. In-scope implementation approval covers writing tests; match command execution to existing authorization. Choose the bounded or full flow for standalone test-code requests by actual impact, without demanding a plan for bounded work.
+
+## Choose verification
+
+Use cases and expected outcomes in the approved plan or bounded in-chat design. Inspect existing test infrastructure and consult relevant requirements only for a concrete ambiguity. Test failures lead to code/test investigation, not automatic Spec/contract updates; record pending deltas under the implementation freeze. Choose checks that demonstrate the outcome: unit tests for logic, integration tests for boundaries, and native/manual checks for device-dependent behavior. Lint and typecheck do not establish runtime behavior.
+
+Do not add tests for pure documentation, formatting, or mechanical changes without behavior impact. A small forwarding change affecting a contract or side effect still needs suitable behavior coverage. Do not add a framework or harness beyond the approved scope merely to satisfy a checklist.
+
+## RED → GREEN → REFACTOR
+
+Once the applicable design/plan and test command are authorized:
+
+1. Write one test for the specific behavior or bug before editing production code.
+2. Run it and observe failure for the intended reason. Syntax errors, setup failures, and missing dependencies are not valid RED evidence. If it passes already, check whether it actually captures the requirement.
+3. Make the minimum production change that passes the test. Run relevant checks and read output and exit codes.
+4. Refactor only where useful, preserve behavior, and recheck affected paths.
+
+Record the AC or case, command, correct RED failure, and GREEN result for each cycle. Do not ask for permission at each stage when matching approval and command authorization already exist. If required TDD lacks valid RED evidence or permission, do not edit production code for that behavior yet.
+
+Use suitable checks for documents or mechanical changes. If meaningful RED evidence is impossible, such as device behavior without a harness, present the reason and alternative verification for an approved TDD exception before code. Task size or difficulty alone is not an exception.
+
+If code was already written, preserve it and report the actual order; do not delete it to simulate TDD. Reproduce a baseline safely when necessary, without discarding working-tree changes.
+
+## Tests must catch a real defect
+
+- Name a plausible production mutation that would fail the test and explain why it violates AC, contract, or the approved chat acceptance check.
+- Derive expected values independently, using literals or manually checked fixtures rather than the same builder as the implementation.
+- Assert observable results, boundaries, validation, or side effects. Avoid locking private names, source text, exact wording, or constants merely to freeze a design choice.
+- Test project behavior rather than re-testing a framework. Use a narrow characterization test when an upstream assumption truly needs evidence.
+
+For example, test the actual call count and outcome under repeated dependency failure rather than asserting the retry constant.
+
+## Mocks and cleanup
+
+Understand side effects before mocking. Let the logic under test run; mock slow, external, or unauthorized boundaries. Fixtures must fit the schema and include fields used by consumers across relevant success, error, and malformed cases.
+
+Do not assert that a mock exists. Assert arguments, counts, or order only when they are part of the production contract. Put test-only cleanup in test utilities; do not add production APIs solely for tests. Consider an authorized integration test when mock setup becomes more complex than the behavior.
+
+## Async behavior and evidence
+
+Wait on actual events or state with a finite timeout rather than guessed sleeps. For debounce or throttle, use a controlled clock and start measuring after the trigger. Isolate state per test and release test-owned resources.
+
+Before handoff, consider realistic mutations: wrong branch, lost side effect, wrong argument, missing validation, or incorrect default. If tests still pass, improve relevant coverage without unbounded testing. Once sufficient checks pass, rerun only for new changes, failures, or concrete concerns. Report commands, results, and limits; never claim an unobserved pass. Structural skill review does not prove agent behavior. Use [kido-verification](../kido-verification/SKILL.md) for handoff.

package/.agents/skills/kido-verification/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: kido-verification
+description: Use before claiming a KIDO task is complete or a bug is fixed, and when preparing a handoff with requirement coverage, observed evidence, and unverified limits.
+---
+
+# KIDO Verification
+
+Follow [kido-workflow](../kido-workflow/SKILL.md), including its action boundaries and implementation document freeze. Keep each conclusion no broader than observed evidence.
+
+## Evidence gate
+
+Before claiming a check passed or behavior was fixed:
+
+1. Define the claim and evidence required.
+2. Apply the workflow's permission rules and reuse matching authorization. Prepare and request only missing permission for an essential check.
+3. Run authorized checks and read their results and exit codes. Evidence from before a code change does not verify that change.
+4. Compare the evidence with the claim. Report failures, missing output, and unrun checks accurately.
+
+| Claim | Suitable evidence |
+| --- | --- |
+| Diff has the intended scope | Current diff and source requirement |
+| Lint or typecheck passed | Corresponding command output and exit code |
+| Tests passed | Executed test command, result, and scope |
+| Bug was fixed | Relevant before/after reproduction or equivalent direct evidence |
+| AC completed | Evidence for each AC's conditions and result |
+| Skill is structurally valid | Frontmatter, links, references, and consistency review |
+| Skill works in practice | Observed agent outcome in an authorized scenario |
+
+A diff or text scan is not a runtime test. Do not infer typecheck from lint, AC completion from a general test pass, or system-wide correctness from one local check. Do not run a build contrary to project rules merely for extra evidence.
+
+## Reconcile and synchronize
+
+- Use the approved plan or bounded in-chat design as the baseline. Reopen a source only for a concrete ambiguity/conflict. Do not rerun specification audits or synchronize documents after each test/review round. Documentation-only work uses its requested criteria.
+- Review the final diff and separate task changes from existing changes. Do not stage, revert, or claim unrelated work.
+- Map AC or bounded chat checks to changes and evidence: verified, implemented but unverified, not implemented, or blocked. Do not claim an unobserved result.
+- Compare with approval for the selected flow; verify RED/GREEN evidence or an approved exception. Bounded work does not require a plan file, and final passing tests do not prove TDD order.
+- Before code review, compare implementation with the approved baseline and list pending document deltas. Keep Spec/contract sources fixed; deferred synchronization of an approved delta is not a review defect. Flag unplanned behavior and generation blockers; use only explicitly authorized temporary build inputs.
+- After explicit code acceptance, consolidate pending deltas and update affected Specs, canonical contract/imports/artifacts, and other planned SSOT documents once through project procedure. Verify the batch against accepted code and preserve authority/approval states. Update `context/current-state.md` only for an actual state/gap/debt/roadmap change. Do not restart design or rewrite the entire context as part of synchronization. Distinguish implemented, verified, deployed, and accepted.
+- For a new skill, inspect its name and frontmatter, links, trigger, cross-references, permissions, and consistency. Structural review does not replace scenario validation.
+
+## Handoff
+
+Report, at a level appropriate to the task:
+
+- Outcome and changed paths.
+- Served Story/AC, bounded chat acceptance checks, or documentation-task criteria.
+- Updated documents, contracts, and ADRs; for a pre-acceptance code handoff, list planned updates and mark them pending.
+- Checks actually run and observed results.
+- Unrun checks, limits, and open decisions.
+- For code: approval evidence for the selected flow, TDD evidence or exception, a diff, and `Pending code review`. Present work without claiming acceptance. For documentation, hand off against its criteria without imposing an implementation gate.
+
+Preserve the working tree, branch, and existing changes; use the workflow's action boundaries for integration and cleanup. User code review remains a separate handoff, not implied by implementation approval or passing tests.

package/.agents/skills/kido-workflow/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: kido-workflow
+description: Use when receiving a request in a KIDO workspace and selecting the applicable context, workflow, and action boundaries.
+---
+
+# KIDO Workflow
+
+## Intake
+
+Read the root workspace instructions and any instructions governing target paths before acting. Use the entrypoint supported by the environment, such as `AGENTS.md` or `CLAUDE.md`, without assuming both are independent required sources. Follow the environment's priority rules. This skill does not grant permission or replace project policy. Read the relevant skill before using it and briefly state its name and purpose.
+
+Explicit user instructions and matching authorization take precedence over the default skill flow. Do not require the user to approve work they have already explicitly authorized for the same scope. Preserve stricter applicable project policy unless the responsible user explicitly changes it.
+
+Follow workspace response conventions, if any. When listing sources read, name only sources actually inspected and the facts they supplied. A badge or assertion does not replace evidence.
+
+## Route by requested outcome
+
+| Request | Handling |
+| --- | --- |
+| Question, explanation, lookup, or feasibility | Investigate read-only and answer; do not create product documents or implement. |
+| Review, audit, or comparison | Inspect requested sources and report findings; edit only when a fix was requested. |
+| Repository onboarding or project-context refresh | Use `kido-onboarding` to survey evidence, preserve policy, and create or update authorized documents. |
+| Documentation-only edit | Edit the correct document type; use `kido-writing-specs` for product documents and `kido-writing-plans` for a requested technical plan. |
+| Bounded code change | Existing flow, clear scope and observable checks, no material change to business rules, public API/schema, or architecture: short design in chat → approval → tests/implementation → user review. Reuse relevant requirements; no mandatory new Story, Spec, or plan file. |
+| Material business, API/schema, or architectural change | Relevant Story/AC/Spec → design approval → plan approval → tests/implementation → user review. Reuse existing documents and approvals where they cover the change. |
+| Bug investigation or fix | Use `kido-debugging` to establish the cause, then choose the bounded or full change flow. |
+| Data, runtime state, production, or Git | Apply the action boundaries below. |
+
+Classify by impact, not file count or effort. A small edit that changes a public contract or business invariant takes the full flow. For bounded work, retain the approved scope, acceptance checks, approach, verification, and pending document delta in chat; do not create files just to satisfy the full-flow template. Reclassify when concrete evidence expands scope. Documentation-only requests do not start either implementation flow.
+
+Track `Pending design approval`, `Pending plan approval` when a plan is required, `Implementing`, and `Pending code review`. Record approved content, scope, and evidence in the plan or chat handoff. A generic request does not approve unseen content, and silence is not approval. While waiting, continue independent authorized work. Renew approval only for material changes to previously approved scope, behavior, or approach; routine implementation corrections within that scope do not restart the gates. Do not claim user acceptance without explicit feedback.
+
+Questions, read-only reviews, and documentation-only work stay within their own scope. For behavior changes and bugs, prefer meaningful TDD under workspace requirements and exceptions; check command permission separately.
+
+## Load context
+
+For onboarding, follow the default entry flow in [kido-onboarding](../kido-onboarding/SKILL.md). A simple “onboard” from an initialized workspace uses its local instructions, installation metadata, and layout to establish the root and components without requiring the user to repeat them. Ask once for move-or-symlink placement of components outside `packages/`, including sibling FE/BE repositories, before placement-dependent writes. Then survey the BE for TypeSpec and the project for glossary, current-state, and overview. Shared context belongs at the workspace root even when components are separate Git repositories. A component's Git root alone does not select the whole project's root; keep an explicitly requested component-only scope. Onboarding does not require a code design, Epic, Spec, or implementation plan.
+
+1. Use the project's task-domain matrix or authority map to choose required sources. Distinguish canonical contracts from generated artifacts and legacy documents before relying on a schema. For UI, read the applicable design-system sources without assuming a framework, contract format, or domain path.
+2. During design/planning, locate only requirements relevant to the chosen flow; bounded work does not require an Epic/Story/Spec inventory. During implementation, start from the approved baseline and consult other sources only for a concrete gap. Before proposing a new abstraction, use `rg -n` to find equivalent logic and callers, then reuse/extend fitting code or explain the distinct responsibility. A document marked “complete” does not prove current behavior.
+3. When sources conflict, name their paths and disagreement. Do not invent behavior or relax policy to justify implementation. Ask when the conflict blocks a decision and continue independent work.
+4. Do not load the whole repository or read environment files, including samples. Use current workspace paths rather than old personal paths. Report missing required sources; a template or proposed file is not an approved source.
+5. Identify writable packages and reference services. A path under `packages/` does not imply permission to write: it may be a symlink into another repository. Check the real target before editing. Do not edit a reference service's code or plan, or include it in this workspace's Git operations, without matching authorization.
+
+## Document boundaries
+
+| Location | Responsibility |
+| --- | --- |
+| `context/` | System knowledge and authority mapping: terminology, architecture, links to canonical contracts, invariants, and evidence. Do not duplicate canonical schema definitions. |
+| `context/contracts/` or a project-prescribed TypeSpec location | `tspconfig.yaml` identifies the entrypoint; `main.tsp` imports domain modules. For one API, read its mapping and module first; inspect others when dependencies or cross-domain changes require it. `.tsp` becomes canonical after authority is confirmed or migrated. A migration scaffold does not replace an older canonical contract. Emitted OpenAPI or JSON Schema is an artifact unless the project decides otherwise. |
+| `epics/` | Problems, outcomes, scope, Stories, AC, and behavior Specs; no code, hooks, CSS, framework, infrastructure, or source-file lists. |
+| `packages/<pkg>/plans/` | `[NEW]` and `[MODIFY]` files, interfaces, dependencies, algorithms, and verification. |
+
+Full-flow changes need Story, AC, and Spec coverage before coding. Bounded changes use the approved request and observable acceptance checks in chat, with links to existing requirements when relevant. Do not create historical or duplicate documents just to provide coverage.
+
+### Implementation document freeze
+
+Prepare requirements and expected Spec/contract deltas during design/planning. Once implementation starts, use the approved plan and linked requirements, or the approved bounded design, as the fixed baseline. Implement code and tests; record progress, evidence, and pending document deltas in the existing plan or chat handoff. Do not repeatedly audit, rewrite, or synchronize Stories, AC, Specs, contracts, or other planned SSOT documents after each edit, test, or review round.
+
+For a concrete requirement conflict or material scope change, pause only affected work, present the discrepancy, and obtain a targeted decision before resuming. An explicitly requested document correction is handled separately; it does not trigger a whole-project refresh. Do not revise requirements to fit the implementation.
+
+After explicit user code acceptance, consolidate the pending deltas and synchronize affected Specs, the canonical contract, required artifacts, and other planned SSOT updates once. Verify that batch against the accepted code. Preserve document approval and contract authority states; code acceptance does not silently promote Draft material to an approved SSOT. Onboarding and explicitly requested documentation work remain independent of this implementation freeze.
+
+For code generation, establish the build-input strategy before implementation. A separately identified temporary contract input and its generated artifacts may be used only when explicitly authorized in the approved scope. Keep it noncanonical, use the approved delta, and do not regenerate or rewrite it merely to track every code edit. If generation cannot proceed with the agreed inputs, report that specific blocker; do not silently edit the canonical contract or introduce another SSOT.
+
+Use relative repository links. Link a Story only to a plan that exists; link plans back to Story, Spec, and responsible AC. Do not create parallel Spec or plan stores.
+
+## Action boundaries
+
+- Keep common permission rules here; other KIDO skills refer to these boundaries and describe only their step-specific requirements. A skill, template, manifest, or documented command grants no execution permission.
+- Distinguish file edits, command execution, and Git/data/runtime actions. Apply workspace policy and existing session authorization to each. Design or plan approval authorizes in-scope edits when implementation was requested; it does not imply permission for commands or Git actions. Explicit authorization may cover several action categories; honor the scope actually granted.
+- Use the required shell and command process. Reuse authorization for the same action, target, purpose, and scope across RED/GREEN, retries, review fixes, and verification. Do not ask at each stage or import allowances from another project. Ask again only when authorization is missing or the action's scope, target, or impact materially changes.
+- If an essential check is unauthorized, prepare the concrete work and request that exact permission. Report unrun checks accurately.
+- Commit, push, merge, deploy, mutate data/runtime state, delete artifacts, or discard changes only with matching authorization.
+- Preserve existing changes and task scope. Worktrees and delegation are optional when available and authorized. This workflow does not require helper scripts or multiple agents.
+
+## Skills in this set
+
+- [kido-onboarding](../kido-onboarding/SKILL.md): survey a repository and establish project context and instructions.
+- [kido-brainstorming](../kido-brainstorming/SKILL.md): clarify a change and design it.
+- [kido-writing-specs](../kido-writing-specs/SKILL.md): audit and maintain product documents.
+- [kido-writing-plans](../kido-writing-plans/SKILL.md): write a technical plan.
+- [kido-executing-plans](../kido-executing-plans/SKILL.md): implement approved work.
+- [kido-debugging](../kido-debugging/SKILL.md): investigate failures.
+- [kido-testing](../kido-testing/SKILL.md): test when authorized.
+- [kido-code-review](../kido-code-review/SKILL.md): review changes and feedback.
+- [kido-verification](../kido-verification/SKILL.md): reconcile evidence and hand off.
+
+Read only skills relevant to the actual task. For a clearly assigned task, keep its scope rather than restarting a workflow for the whole project.

package/.agents/skills/kido-writing-plans/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: kido-writing-plans
+description: Use for a full-flow KIDO change ready for technical planning, or an explicitly requested technical plan; bounded work does not require a plan file.
+---
+
+# KIDO Writing Plans
+
+Follow [kido-workflow](../kido-workflow/SKILL.md). Full-flow work uses approved design and established Story/AC/Spec coverage; resolve a concrete gap through [kido-writing-specs](../kido-writing-specs/SKILL.md), without repeating a completed audit. Read only relevant contracts, invariants, code, and plans. Bounded work goes directly from its approved in-chat design to execution unless the user requests a plan. For an explicitly requested plan, use the supplied requirements or chat acceptance checks when product documents do not apply. A plan-only request does not authorize implementation.
+
+## Scope and location
+
+Reuse or update a suitable plan. Store one at `packages/<pkg>/plans/<plan-name>.md` for each affected package. For a root-level script, follow project convention or put its work in the responsible package's plan and state the scope. Do not create a parallel planning location.
+
+A plan describes HOW without copying all business context. Group tasks by independently reviewable and verifiable deliverables.
+
+## Required content
+
+Use the [shared plan template](../../templates/implementation-plan.md) when available. If distributed without it, include the fields below without making a broken link. The template is not an approved plan.
+
+Include the goal; linked Story/Spec/AC or explicitly requested plan's requirements; architecture, interfaces, files, reuse, dependencies, and limits; approval evidence; acceptance-linked tasks; verification and command permissions; planned SSOT changes; and unverified work. Record the Spec/contract delta and one synchronization step after code acceptance, not document updates after each task. If code generation needs changed inputs, settle the explicitly authorized temporary-input/artifact strategy here before implementation. Replace placeholders; explain fields that do not apply.
+
+## Write executable tasks
+
+- Specify files, responsibilities, signatures or types, state, and error handling. Use pseudocode only where it removes ambiguity; keep names and types consistent.
+- Before listing a `[NEW]` function, helper, or component, use `rg -n` to find comparable symbols and call sites. Read candidates and callers, then state what will be reused or why a new abstraction is needed. Identify only the canonical contract and design-system sources relevant to the planned change, and state when each is updated.
+- Replace vague tasks such as “handle errors” or “add tests” with concrete conditions and outcomes. Do not add unapproved technology or dependencies.
+- Map verification to applicable AC or supplied acceptance checks with existing commands and expected results; apply the workflow's action boundaries to command execution.
+- For behavior changes and bugs, use [kido-testing](../kido-testing/SKILL.md) to plan RED → GREEN → REFACTOR under project policy. Name test cases, files, expected RED cause, and GREEN outcome. If no meaningful behavior test is possible, document the reason and alternative verification for approval as a TDD exception before code. Use suitable checks for mechanical changes.
+- Name affected SSOT sources or state why no update is needed. Schedule their consolidated synchronization after code acceptance. Implementation tasks update progress/evidence and pending deltas only; do not schedule repeated Spec/contract refreshes. Apply the workflow's action boundaries rather than adding automatic Git or cleanup steps.
+
+## Review and transition
+
+Map each applicable requirement to a task. Check files, dependencies, interfaces, errors, boundaries, and verification. Resolve plan gaps; ask about missing product decisions instead of inventing them. Link existing Story/Spec documents and the plan in both directions when they apply; do not create them merely to support an explicitly requested bounded plan.
+
+Present the plan file, task summary, test cases, SSOT delta, any TDD exception, and commands needing authorization. Mark it `Pending plan approval`. Wait for approval before editing production or test code. An existing plan or generic “implement it” request does not approve unseen plan content. Reuse explicit approval for the same content and scope. Plan approval authorizes implementation only when implementation was requested; a plan-only task ends at handoff.
+
+After approval and an implementation request, use [kido-executing-plans](../kido-executing-plans/SKILL.md). Apply the workflow's action boundaries and seek renewed approval only for material plan changes.