# Kano Agent Backlog Skill

> Local-first backlog workflow. Use when planning work, creating/updating backlog items, writing ADRs, enforcing Ready gate, discovering or maintaining hand-authored custom views, or maintaining derived indexes (SQLite/FTS/embeddings).

- Skill: `kanohorizonia/kano-agent-backlog-skill` (Agent Skill, multi-file: 20 files)
- Install (CLI): `npx skillmds@latest add kanohorizonia/kano-agent-backlog-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kanohorizonia/kano-agent-backlog-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: kanohorizonia (https://skillmd.com/u/kanohorizonia)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kanohorizonia/kano-agent-backlog-skill

---


# Kano Agent Backlog Skill (local-first)

## Pre-alpha Status

**This skill is in pre-alpha (experimental) stage:**
- Breaking changes are expected and frequent
- No backward compatibility guarantees
- CLI commands, config schema, and file formats may change without notice
- When implementing new features or refactoring, **do not add backward compatibility layers**
- Simply replace old implementations with new ones
- Update documentation to reflect current state only

**For agents:** When you see deprecated patterns or inconsistent interfaces, refactor them directly. Do not preserve old code paths "for compatibility."

This follows the Kano pre-1.0.0 compatibility policy. See `kano-skill-dev-convention` → `references/pre-1.0-compatibility-policy.md` for the full rule set and examples.

## Scope

Use this skill to:
- Plan new work by creating backlog items before code changes.
- Maintain hierarchy and relationships via `parent` links, as defined by the active process profile.
- Record decisions with ADRs and link them to items.
- Keep a durable, append-only worklog for project evolution.

## Agent compatibility: read the whole skill

- Always load the entire `SKILL.md` before acting; some agent shells only fetch the first ~100 lines by default.
- If your client truncates, fetch in chunks (e.g., lines 1-200, 200-400, …) until you see the footer marker `END_OF_SKILL_SENTINEL`.
- If you cannot confirm the footer marker, stop and ask for help; do not proceed with partial rules.
- When generating per-agent guides, preserve this read-all requirement so downstream agents stay in sync.

## Quick Start for Agents

**If you're helping a user set up this skill from a cloned repository:**

1. **Build the native binary:**
   ```bash
   cd skills/kano-agent-backlog-skill
   pixi run build-dev
   ```

2. **Verify installation:**
   ```bash
   bash scripts/internal/show-version.sh
   kob
   kob doctor
   ```

3. **Initialize backlog:**
   ```bash
   cd /path/to/user/project
   kob admin init --product <product-name> --agent <your-agent-id>
   ```

**See [docs/agent-quick-start.md](docs/agent-quick-start.md) for complete setup instructions.**

## Non-negotiables

- Shared backlog checkout invariant:
  - Treat a configured shared backlog root as one canonical mutable checkout.
  - Never create or use a Git worktree for the shared backlog repository. Source repositories may use worktrees, but every `kob` read, mutation, and ID allocation must still target the canonical shared backlog checkout.
  - Backlog worktrees can carry stale branch state and independent derived sequence databases, causing duplicate Display IDs and large collision sets when branches are later converged.
  - Before creating items, converge the canonical shared backlog checkout and run `kob admin sync-sequences --product <product>`. If it cannot be converged safely, stop and record the blocker instead of switching the backlog to a worktree.
  - Use `kob sandbox` for isolated backlog experiments; do not use a Git worktree as a production-backlog sandbox.
- Planning before coding: create/update items and meet the Ready gate before making code changes.
- Worklog is append-only; never rewrite history.
- Update Worklog whenever:
  - a discussion produces a clear decision or direction,
  - an item state changes,
  - scope/approach changes,
  - or an ADR is created/linked.
- Archive by view: hide `Done`/`Dropped` items in views by default; do not move files unless explicitly requested.
- Backlog volume control:
  - Only create items for work that changes code or design decisions.
  - Avoid new items for exploratory discussion; record in existing Worklog instead.
  - Keep Tasks/SubTasks/Bugs/Issues sized for a single focused session.
  - Avoid ADRs unless a real architectural trade-off is made.
- Ticketing threshold (agent-decided):
  - Open a new Task/SubTask/Bug/Issue when you will change code/docs/views/scripts or when an unclear runtime gap needs pre-triage evidence.
  - Open an ADR (and link it) when a real trade-off or direction change is decided.
  - Otherwise, record the discussion in an existing Worklog; ask if unsure.
- Ticket type selection (keep it lightweight):
  - Initiative: independently releasable component, module, or product narrative layer above Epic/Feature.
  - Epic: multi-release or multi-team milestone spanning multiple Features.
  - Feature: a new capability that delivers multiple UserStories.
  - UserStory: a single user-facing outcome that requires multiple Tasks.
  - Task: a single focused implementation or doc change (typically one session).
  - SubTask: independently delegable executable child work under a Task; use only when a distinct agent/thread can own it with separate validation.
  - Issue: a pre-triage unclear problem, risk, blocker, or runtime gap; split into Task/Bug follow-ups once actionable.
  - Product Line/Portfolio membership above Initiative is catalog metadata, not a backlog item type.
  - Example: "Asset platform" = Initiative; "End-to-end embedding pipeline" = Epic; "Pluggable vector backend" = Feature; "MVP chunking pipeline" = UserStory; "Implement tokenizer adapter" = Task; "Add tokenizer fixture coverage" = SubTask when delegated separately under that Task.
- Bug vs Task triage (when fixing behavior):
  - If you are correcting a behavior that was previously marked `Done` and the behavior violates the original intent/acceptance (defect or regression), open a **Bug** and link it to the original item.
  - If the change is a new requirement/scope change beyond the original acceptance, open a **Task/UserStory** (or Feature) instead, and link it for traceability.
- Bug origin tracing (when diagnosing a defect/regression):
  - Record **when the issue started** and the **evidence path** you used to determine it.
  - Prefer VCS-backed evidence when available:
    - last-known-good revision (commit hash or tag)
    - first-known-bad revision (commit hash or tag)
    - suspected introducing change(s) (commit hash) and why (e.g., `git blame` on specific lines)
  - If git history is unavailable (zip export, shallow clone, missing remote), explicitly record that limitation and what alternative evidence you used (e.g., release notes, timestamps, reproduction reports).
  - Keep evidence lightweight: record commit hashes + 1–2 line summaries; avoid pasting large diffs into Worklog. Attach artifacts when needed.
  - Suggested Worklog template:
    - `Bug origin: last_good=<sha|tag>, first_bad=<sha|tag>, suspect=<sha> (reason: blame <path>:<line>), evidence=<git log/blame/bisect|other>`
- State ownership: the agent decides when to move items to InProgress or Done; humans observe and can add context.
- State semantics:
  - Proposed: needs discovery/confirmation.
  - Planned: approved but not started.
  - Ready gate applies before InProgress: Context, Goal, Approach, Acceptance Criteria, Risks must be filled.
  - InProgress: active work; strict Ready gate enforcement unless `--force` is used.

## Implementation Work Item Lifecycle Gate

For any work that changes code, docs, scripts, views, configs, schemas, tests, build logic, or persistent design decisions:

**Before implementation:**
1. Reuse an existing Task/Bug/Issue if it already covers the work; otherwise create one.
2. Fill the Ready gate: Context, Goal, Approach, Acceptance Criteria, Risks.
3. Move the item to `InProgress` **before** editing implementation files.
4. Append a Worklog entry that implementation is starting.

**During implementation:**
1. Append Worklog entries for meaningful decisions, scope changes, blockers, or validation evidence.
2. Attach artifacts or reports under the corresponding item when useful.
3. Do not create extra duplicate items for the same focused session.

**After implementation:**
1. Run the relevant validation commands.
2. Append a Worklog entry summarizing files changed, commands run, test results, and known gaps.
3. For code-changing Done evidence, record branch convergence in Worklog or Intent Amendments:
   - `Branch convergence: target=<branch>` or `target_branch=<branch>`; the target is the repo default branch unless a human explicitly names another target.
   - `implementation_commit=<sha>`, `reachable_from_target=true`, and `remote_publication=<remote/ref>`.
   - Side-branch-only Done is allowed only when a human explicitly chose it; record `side_branch_delivery=explicit-human-choice` or `side_branch_delivery=human-approved`.
   - Nested/submodule work needs parent pointer evidence such as `nested_gitlink=<parent gitlink/submodule pointer evidence>`.
   - If convergence is blocked, do not close as Done; record `Blocked convergence: branch=<branch>; reason=<reason>; next=<step>; blocker=<owner/item>`.
4. If all acceptance criteria are complete, move the item to `Done`.
5. If incomplete, leave it `InProgress`, `Review`, or `Blocked` with a clear Worklog entry.
6. Review current backlog state in Backboard when human review is needed.

Do not open items for pure exploratory discussion unless it changes code or design direction. Record minor discussion in an existing Worklog instead.

For pre-1.0.0 Kano skills: prefer clean in-place migration over deprecated/superseded compatibility artifacts unless the human explicitly asks for compatibility.

## Intent Engineering Protocol

Intent Engineering keeps the human purpose of work visible across agent sessions. Use this protocol as an operating contract; it does not add new hierarchy levels or require new CLI/schema fields yet.

### Intent Stack

- The Intent Stack is the existing parent chain: Initiative -> Epic -> Feature -> User Story -> Task/Bug.
- Before implementation, trace upward until the highest available parent that still carries relevant intent.
- Summarize inherited intent from parent Context, Goal, Approach, Acceptance Criteria, Risks, Worklog decisions, and any Non-Goals / Do Not notes.
- Do not copy whole parent documents into child items. Use bounded summaries with item IDs and paths when needed.
- Missing parents are warnings, not permission to invent intent.

### Non-Goals / Do Not

- Non-Goals / Do Not are observable negative boundaries: things the agent must avoid, defer, or escalate.
- Good examples:
  - "Do not publish a release tag or upload artifacts in this task."
  - "Do not change existing state-transition blocking behavior; warnings only."
  - "Do not scan arbitrary filesystem paths; resolve only by item id or uid."
- Bad examples:
  - "Do not make it bad" (not observable).
  - "Do not over-engineer" without a concrete forbidden behavior.
  - "Do not touch anything else" when the required implementation necessarily needs tests/docs.
- If a requested plan violates a Do Not boundary, stop and request human review before editing or executing the conflicting action.

### Intent Amendments

- Intent Amendments are append-only corrections from a human, reviewer, or maintainer after the original Ready fields were written.
- Each amendment should record timestamp, author/agent, current state, correction, reason, affected section or scope, and expected follow-up.
- Never rewrite prior Worklog evidence to hide drift. Add the amendment, then record the resulting plan or state decision.
- Proposed: update Ready fields directly when safe, or record the clarification as an amendment if history matters.
- InProgress: pause implementation, re-run preflight, and record whether the plan changed.
- Review: treat the amendment as a drift finding; do not move to Done until it is resolved or explicitly accepted.
- Done: record post-done drift and recommend reopen, follow-up Bug, or follow-up Task depending on impact.

### Reactivation Review

Run a Reactivation Review before executing or resuming a stale or dormant item. This
applies even when the item was previously Ready or implementation had already
started. Use `kob workitem intent-drift-preflight` to collect deterministic evidence,
then have ChatGPT/the operator classify any external candidate evidence.

- Check item age and last validation evidence; the current parent chain; explicit
  relates, blocks, blocked-by, and decisions; parent-related tickets; siblings and
  children; current architecture and tool contracts; stale release terms; and
  Worklog/history.
- Treat the initial result as a warning-level review. Do not automatically close,
  reopen, supersede, re-scope, or dispatch the item.
- Select an explicit outcome: continue as-is, refresh and continue, rewrite the
  approach, supersede, split, close as a no-op, or require a human decision.
- Keep the initial dogfood set explicit when validating this protocol:
  `KOB-TSK-0025`, `KOB-TSK-0006`, `KOB-BUG-0020`, `KOB-TSK-0028`,
  `KOB-TSK-0030`, `KOB-TSK-0001`, and `KOB-TSK-0004`.
- When evidence conflicts or remains insufficient, produce a bounded evidence pack
  and require human confirmation instead of choosing intent automatically.

| Item state | Reactivation handling |
| --- | --- |
| Proposed | Revalidate current need and parent intent before planning or implementation. |
| Ready | Re-run the Ready and intent checks; old Ready status is not proof that assumptions remain current. |
| InProgress | Pause implementation, run preflight, and record whether the plan can resume or must change. |
| Review | Treat drift as a review finding and resolve it before Done. |
| Done / Post-Done | Preserve the completed item as history; use reopen semantics or a linked Bug/Task when current behavior needs work. |

### Stale Solution Check

Separate observed evidence from the solution proposed when that evidence was
recorded. Bug evidence can remain valid even when its old proposed fix is obsolete.
An old proposed fix is untrusted until it is revalidated against current
architecture, current tool contracts, parent intent, and newer related decisions.

- Preserve reproducible symptoms, logs, test failures, and historical observations as
  evidence unless later evidence disproves them.
- Never execute an old proposed fix merely because the original bug evidence is still
  credible.
- Record which assumptions and approaches were accepted, refreshed, or rejected. If
  the solution boundary changed, create or use an Intent Drift Resolution ticket
  before coding-agent handoff.

### Preflight Intent Trace Template

Use this compact block before non-trivial implementation:

```text
Intent Preflight
- Active item: <ID> <title>
- Intent stack: <Epic> -> <Feature> -> <Story> -> <Task>
- Inherited intent: <1-3 bullets>
- Local goal: <1 sentence>
- Non-Goals / Do Not: <bullets or "none documented">
- Intent amendments considered: <latest relevant entries or "none">
- Planned approach: <bounded steps>
- Stop conditions: <Do Not violations, missing parent, unclear acceptance>
```

### Completion Do Not Compliance Template

Use this before closing or reporting completed work:

```text
Do Not Compliance
- Task completion: OK/WARN/VIOLATION - <evidence>
- Parent alignment: OK/WARN/VIOLATION - <Epic/Feature/Story fit>
- Non-Goals checked: OK/WARN/VIOLATION - <each boundary>
- Intent amendments resolved: OK/WARN/VIOLATION - <evidence>
- Validation evidence: <commands/reports>
- Limitations and follow-ups: <known gaps or "none">
```

### Operator UX

- Codex/OpenCode: include the preflight block in the plan or first worklog update, then include the compliance block in the final report or completion worklog.
- ChatGPT/MCP: keep responses compact; expose intent stack, Do Not boundaries, and compliance result through the action response or attached evidence.
- Cross-system TODOs only: KOA, Codex/OpenCode commands, Jenkins gates, and Ark Console visualization may consume these sections later, but this protocol does not implement those integrations.

### Coding-Agent Handoff Rule

- Before ChatGPT recommends or produces a Codex/OpenCode handoff, it must run Intent Drift Preflight. The human is not responsible for knowing whether drift exists.
- Check deterministic KOB evidence first: selected item, item age/last validation evidence, parent chain, explicit relates/blocks/decisions, parent related tickets, siblings/children, stale architecture or release-line terms, newer decisions, current repo/tool-contract evidence, and Worklog/history.
- Optional KOA/Miyo/semantic search results are candidate evidence only. KOB core must not implement embedding, tokenizer, or vector search to become the final intent judge.
- ChatGPT/human synthesis must classify evidence as current authority, stale/legacy, candidate, conflicting, or missing before handoff.
- If no drift is detected, include a compact no-drift preflight note in the handoff.
- If drift is detected, do not hand the original item to the coding agent. Create an Intent Drift Resolution ticket and hand that new ticket to Codex/OpenCode instead.
- If evidence is insufficient or conflicting, produce an evidence pack and require human confirmation. Do not let the coding agent resolve uncertainty by implementation.

Useful command surfaces:

```bash
kob workitem intent-template <ITEM_ID> --kind handoff
kob workitem intent-drift-preflight <ITEM_ID> --result no-drift
kob workitem drift-resolution-template <SOURCE_ITEM_ID> --drift-type "stale architecture"
kob workitem create-drift-resolution <SOURCE_ITEM_ID> --apply --agent <agent-id>
```

Supported drift type labels include stale architecture, stale proposed fix, parent intent conflict, related-ticket conflict, semantic evidence conflict, acceptance mismatch, Done validity drift, and unknown / needs human confirmation.

### Intent Drift Resolution Tickets

- Detected drift is not execution permission.
- The original item preserves history through append-only Intent Drift Finding evidence.
- The new Intent Drift Resolution ticket becomes the executable boundary after human confirmation.
- The resolution ticket must be self-contained enough for a human to hand only that new ticket ID to Codex/OpenCode.
- Include source item, detection stage, detected-by, drift type, why it is drift, evidence pack, relationship map, human confirmation notes, proposed corrected intent, Do Not / Non-Goals, stop conditions, validation plan, and `relates: SOURCE_ITEM_ID`.
- Do not auto-close, auto-reopen, auto-supersede, or auto-reparent source tickets without explicit human confirmation.

- Hierarchy is in frontmatter links, not folder nesting; avoid moving files to reflect scope changes.
- Filenames stay stable; use ASCII slugs.
- Never include secrets in backlog files or logs.
- Language: backlog and documentation content must be English-only (no CJK), to keep parsing and cross-agent collaboration deterministic.
- Agent Identity: In Worklog and audit logs, use your own identity (e.g., `[agent=antigravity]`), never copy `[agent=codex]` blindly.
- Always provide an explicit `--agent` value for auditability (some commands currently default to `cli`, but do not rely on it).
- Model attribution (optional but preferred): provide `--model <name>` (or env `KANO_AGENT_MODEL` / `KANO_MODEL`) when it is known deterministically.
  - Do not guess model names; if unknown, omit the `[model=...]` segment.
- **Agent Identity Protocol**: Supply `--agent <ID>` with your real product name (e.g., `cursor`, `copilot`, `windsurf`, `antigravity`).
  - **Forbidden (Placeholders)**: `auto`, `user`, `assistant`, `<AGENT_NAME>`, `$AGENT_NAME`.
- File operations for backlog/skill artifacts must go through the supported local CLI surface (`kob` or repo-local wrappers under `scripts/core/`) so audit logs capture the action.
- Skill scripts only operate on paths under `_kano/backlog/` or `_kano/backlog_sandbox/`;
  refuse other paths.
- Backboard is the maintained backlog review surface. Custom hand-authored
  Markdown, Dataview, and Bases content remains supported under `views/`.
  `kob view list --product <product>` discovers Markdown custom-view files only;
  it does not discover `.base` files.
- Persona summaries/reports are available via `kob persona summary|report ...`.
- `kob workitem update-state ...` auto-syncs parent states forward-only by default; use `--no-sync-parent`
  for manual re-plans where parent state should stay put.
- Add Obsidian `[[wikilink]]` references in the body (e.g., a `## Links` section) so Graph/backlinks work; frontmatter alone does not create graph edges.
- Artifacts storage: Demo reports, implementation summaries, analysis documents, and other work outputs should be stored in `artifacts/<item-id>/` for the corresponding work item to maintain traceability and context.

## Agent compatibility: read the whole skill

- Always load the entire `SKILL.md` before acting; some agent shells only fetch the first ~100 lines by default.
- If your client truncates, fetch in chunks (e.g., lines 1-200, 200-400, …) until you see the footer marker `END_OF_SKILL_SENTINEL`.
- If you cannot confirm the footer marker, stop and ask for help; do not proceed with partial rules.
- When generating per-agent guides, preserve this read-all requirement so downstream agents stay in sync.

## First-run bootstrap (prereqs + initialization)

Before using this skill in a repo, the agent must confirm:
1) the native `kano-backlog` binary is available (build it if needed), and
2) the backlog scaffold exists for the target product/root.

If the backlog structure is missing, propose the bootstrap commands and wait for user approval before writing files.

### Developer vs user mode (where to declare it)

- **Preferred source of truth**: project config in `.kano/backlog_config.toml`.
  - `[defaults]` applies to all products.
  - `[shared.*]` applies to all products (global defaults).
  - `[products.<name>]` defines each product and its product-specific settings (flattened keys like `vector_enabled`, `analysis_llm_enabled`, `embedding_provider`, etc.).
- **Secondary**: agent guide files (e.g., `AGENTS.md` / `CLAUDE.md`) can document expectations, but are agent-specific and not script-readable.

### Skill developer gate (architecture compliance)

**If `mode.skill_developer=true`**, before writing any skill code (in `scripts/` or `src/`), you **must**:
1. Read **ADR-0013** ("Codebase Architecture and Module Boundaries") in the product decisions folder.
2. Follow the folder rules defined in ADR-0013:
   - `scripts/` is **executable-only**: no reusable module code.
   - `src/` is **import-only**: core logic lives here, never executed directly.
   - All agent-callable operations go through `scripts/kano-backlog` CLI.
3. Place new code in the correct native C++ boundary:
   - Models/config/frontmatter/state/validation → `src/cpp/code/systems/kano_backlog_core/`
   - Use-cases (create/update/view/topic/workset/index) → `src/cpp/code/systems/kano_backlog_ops/`
   - CLI command wiring → `src/cpp/code/apps/kano_backlog_cli/`
   - Tests → `src/cpp/code/tests/`

Violating these boundaries will be flagged in code review.

### Prerequisite install

Detect:
- Run `kob doctor`.

If the native binary is missing, build once:
- `pixi run build-dev`

Python package installation is no longer supported for this skill. Optional exact tokenizer or embedding providers must be added through future native adapters, not in-process Python packages.

### Container/Docker environments (agents)

If you run inside a restricted container, `admin init` requires a native
`kano-backlog` binary built for that container platform. Use a prebuilt native
artifact or run `pixi run build-dev` inside an image with the C++ toolchain
available.

**Minimum requirements in the container**:
- Git
- CMake/Ninja
- A supported C++ compiler toolchain
- The repo-local native binary built from `src/cpp/`

Python and pip are not supported prerequisites for this skill.

### Backlog initialization (file scaffold + config)

Detect (multi-product / platform layout):
- Product is initialized if:
  - `.kano/backlog_config.toml` exists, and
  - `[products.<product>]` is present with a valid `backlog_root` pointing at an existing directory.

Bootstrap:
- Run `kob admin init --product <product> --agent <agent-id> [--backlog-root <path>]` to scaffold backlog directories and write/update `.kano/backlog_config.toml`.
- Manual fallback (only if automation is unavailable): follow `_kano/backlog/README.md` to copy the template scaffold.

## Optional LLM analysis over deterministic reports

This skill can optionally append an LLM-generated analysis to a deterministic report.
The deterministic report is the SSOT; analysis is treated as a derived artifact.

- Deterministic report: `views/Report_<persona>.md`
- Derived LLM output: `views/_analysis/Report_<persona>_LLM.md` (gitignored by default)
- Deterministic prompt artifact: `views/_analysis/Report_<persona>_analysis_prompt.md`

Enable by config (per product):
- `analysis.llm.enabled = true`

Execution:
- The **default workflow** is: generate the deterministic report → use it as SSOT → fill in the analysis template.
  - The skill generates a deterministic prompt file to guide the analysis, and a derived markdown file with placeholder headings.
- Never pass API keys as CLI args; keep secrets in env vars to avoid leaking into audit logs.

## ID prefix derivation

- Source of truth:
  - Product config: `_kano/backlog/products/<product>/_config/config.toml` (`product.name`, `product.prefix`), or
  - Repo config (single-product): `_kano/backlog/_config/config.toml` (`product.name`, `product.prefix`).
- Derivation:
  - Split `product.name` on non-alphanumeric separators and camel-case boundaries.
  - Take the first letter of each segment.
  - If only one letter, take the first letter plus the next consonant (A/E/I/O/U skipped).
  - If still short, use the first two letters.
  - Uppercase the result.
- Example: `product.name=kano-agent-backlog-skill-demo` -> `KABSD`.

## ID allocation and sequence management

### Understanding IDs vs UIDs

The backlog system uses two types of identifiers:

- **UID (UUID)**: The true unique identifier for each work item (e.g., `019c11e6-de87-7218-b89b-38c2e4e9cabd`).
  - Immutable - never changes throughout the item's lifecycle.
  - Guaranteed unique - no collisions possible.
  - Used internally by the system for all operations.
  - Stored in frontmatter: `uid: 019c11e6-de87-7218-b89b-38c2e4e9cabd`

- **Display ID**: Human-readable identifier (e.g., `KABSD-TSK-0335`).
  - Derived from DB sequence counter (auto-incremented).
  - Used in filenames and for human reference.
  - May have collisions if DB sequence is stale.
  - Format: `<PREFIX>-<TYPE>-<NUMBER>` (e.g., `KABSD-TSK-0335`)

**System behavior**: All CLI operations accept both UID and Display ID. When ambiguous (multiple items with same Display ID), the system requires UID.

### ID allocation mechanism

IDs are allocated from a SQLite database sequence to prevent collisions:

1. **DB Sequence**: Tracks the next available ID for each type (EPIC, FTR, USR, TSK, BUG).
2. **Auto-increment**: `item create` queries the DB for the next available ID.
3. **File-first**: Markdown files are the source of truth; the DB is a derived index that must be kept in sync.

### Sequence synchronization workflow

The DB sequence must be synchronized with the filesystem after certain operations.

**When to sync** (run `admin sync-sequences`):
- After cloning the repository (DB doesn't exist yet).
- After pulling changes that add/remove items (DB is out of sync).
- Before bulk item creation (ensure no collisions).
- When seeing "Ambiguous item reference" errors (multiple items with same Display ID).
- After manually creating/deleting item files outside the CLI.

**How to sync**:

`sync-sequences` updates the derived sequence database immediately. The current
native command does not provide a preview or `--dry-run` mode.

```bash
kob admin sync-sequences --product <product>
```

Output example:
```
Updated sequences:
  EPIC: 15
  FTR: 64
  USR: 44
  TSK: 336
  BUG: 10
```

### Correct workflow for creating items

**Always follow this order**:

```bash
# Step 1: Sync sequences (if not done recently)
kob admin sync-sequences --product <product>

# Step 2: Create item (system auto-assigns next available ID)
kob item create \
  --type task \
  --title "Your task title" \
  --agent <agent-id> \
  --product <product> \
  --duplicate-search-query "Your task title" \
  --duplicate-search-scope <product> \
  --duplicate-decision create

# Output: OK: Created: KABSD-TSK-0336
#         Path: KABSD-TSK-0336_your-task-title.md
```

The system automatically:
- Queries the DB for the next sequence number.
- Allocates the Display ID (e.g., `KABSD-TSK-0336`).
- Generates a unique UID (UUID v7).
- Creates the file with both identifiers.

### Handling ID conflicts

If you encounter "Ambiguous item reference" errors (multiple items with same Display ID):

**Option 1: Use UID instead of Display ID**
```bash
# Reference by UID (always unambiguous)
kob workitem update-state \
  019c11e6-de87-7218-b89b-38c2e4e9cabd \
  --state Done \
  --product <product>
```

**Option 2: Trash the incorrect item**
```bash
# Move incorrect item to _trash/ (recoverable)
kob items trash \
  <UID> \
  --agent <agent-id> \
  --product <product> \
  --apply
```

**Option 3: Find which items have the same ID**
```bash
# Identify duplicates
find _kano/backlog/products/<product>/items -name "KABSD-TSK-0001*.md"
```

### Pre-1.0 Display ID remaps

For pre-1.0 clean migrations, prefer a single in-place remap over creating a
deprecated or superseded duplicate item. `workitem remap-id` and
`links remap-id` are dry-run by default; they report the planned filename and
reference updates without changing files. Add `--apply` only after reviewing the
plan.

```bash
# Preview the item file rename and reference rewrites.
kob workitem remap-id KABSD-TSK-0001 --to KABSD-TSK-0042 \
  --agent <agent-id> --product <product> --format json

# Apply the clean migration.
kob workitem remap-id KABSD-TSK-0001 --to KABSD-TSK-0042 \
  --agent <agent-id> --product <product> --apply
```

The remap keeps the item's UID and state, updates frontmatter `id`, renames the
Markdown file, rewrites item ID references across canonical items and custom
views, and appends Worklog evidence. Use this only for intentional display-ID
migrations; routine new work should still use normal item creation.

### Best practices

**DO**:
- ✅ Run `sync-sequences` after cloning or pulling changes.
- ✅ Let the system allocate IDs automatically (never manually assign).
- ✅ Use UID when scripting or in ambiguous situations.
- ✅ Use the `trash` command instead of deleting files directly.
- ✅ Check `admin validate uids` periodically to detect UID collisions.

**DON'T**:
- ❌ Manually assign Display IDs in frontmatter.
- ❌ Delete item files directly (use `admin items trash`).
- ❌ Assume Display ID is unique (always be prepared to use UID).
- ❌ Skip `sync-sequences` after repository operations.
- ❌ Create items without running `sync-sequences` first (if DB might be stale).

### Conflict resolution policy

The system provides configurable conflict handling via product config:

```toml
# _kano/backlog/products/<product>/_config/config.toml
[conflict_policy]
id_conflict = "rename"           # Rename duplicate Display IDs
uid_conflict = "trash_shorter"   # Move shorter duplicate to _trash/
```

See `admin links normalize-ids` and `admin validate uids` commands for conflict detection and resolution.

## Recommended layout

This skill supports both single-product and multi-product layouts:

- Single-product (repo-level): `_kano/backlog/`
- Multi-product (monorepo): `_kano/backlog/products/<product>/`

Within each backlog root:
- `_meta/` (schema, conventions)
- `items/<type>/<bucket>/` (work items)
- `decisions/` (ADR files)
- `views/` (hand-authored custom Markdown, Dataview, or Bases content)

## Item bucket folders (per 100)

- Store items under `_kano/backlog/items/<type>/<bucket>/`.
- Bucket names use 4 digits for the lower bound of each 100 range.
  - Example: `0000`, `0100`, `0200`, `0300`, ...
- Example path:
  - `_kano/backlog/items/task/0000/KABSD-TSK-0007_define-secret-provider-validation.md`

## Index/MOC files

- For Epic, create an adjacent index file:
  - `<ID>_<slug>.index.md`
- Index files should render a tree using Dataview/DataviewJS and rely on `parent` links.
- Track epic index files in `_kano/backlog/_meta/indexes.md` (type, item_id, index_file, updated, notes).

## References

- Reference index: `REFERENCE.md`
- Schema and rules: `references/schema.md`
- Templates: `references/templates.md`
- Workflow SOP: `references/workflow.md`
- View patterns: `references/views.md`
- Obsidian Bases (plugin-free): `references/bases.md`
- Context Graph + Graph-assisted retrieval: `references/context_graph.md`
- Multi-corpus hybrid search: `docs/multi-corpus-search.md`

If the backlog structure is missing, propose creation and wait for user approval before writing files.

## Search Strategy: When to Use Semantic Search vs File Tools

## Backlog Item Lookup Hint (KG IDs)

When resolving backlog item IDs like `KG-FTR-0020`, do first-pass lookup in product backlog paths before reporting not found.

Primary lookup paths:

- `_kano/backlog/products/**/items/**/KG-*.md`
- `_kano/backlog/items/**/KG-*.md` (single-product layout)

Secondary lookup paths:

- `.kano/**` (config/metadata only)

Agent rules:

- Do not assume `KG-*` items live under `.kano/`.
- Always include `_kano/backlog/**/items/**` in the very first discovery pass.
- If user provides an absolute path, read that path directly first, then perform pattern lookup only if needed.

Suggested commands:

```bash
# Specific ID
find _kano/backlog -type f -name "KG-FTR-0020*.md"

# Any KG item
find _kano/backlog -type f -name "KG-*.md"
```

### Use semantic/hybrid search when:
- **Conceptual queries**: "Find items about authentication strategy" (concept-based, not exact string)
- **Cross-file patterns**: "Where do we handle token expiration?" (logic scattered across multiple files)
- **Historical context**: "What decisions were made about embedding models?" (ADRs + items + topics)
- **Fuzzy matching**: "error handling for database connections" (various phrasings, synonyms)
- **Discovery phase**: Exploring unfamiliar codebase or backlog areas

**Commands (unified interface):**
- Backlog corpus: `kob search hybrid "text" --corpus backlog --product <product> --k 10`
- Repo corpus: `kob search hybrid "text" --corpus repo --k 10 --fts-k 200`

**Note**: The `--corpus` parameter provides extensibility for future corpus types (logs, metrics, external-docs, etc.).

### Use find/grep/glob when:
- **Exact strings**: Error messages, function names, class names, specific identifiers
- **File patterns**: "Find all test files", "List all .toml configs", "Locate README files"
- **Quick lookups**: Known file paths or specific code locations
- **Structural search**: AST-based patterns (use ast_grep for code structure)
- **No index available**: Indexes not yet built or known to be stale

**Tools:**
- Glob: File pattern matching (`*.py`, `**/*.md`, `test_*.py`)
- Grep: Content search with regex (`class.*Adapter`, `def test_`)
- AST Grep: Code structure patterns (`function $NAME($$$)`, `class $CLASS`)

### Hybrid approach (recommended):
1. **Start with semantic search** for discovery and conceptual understanding
2. **Verify with grep/glob** to find exact locations and confirm results
3. **Rebuild indexes when stale**: Use `--force` flag if results seem outdated

### Index maintenance:
- **Build backlog index**: `kob embedding build --product <product> --force`
- **Build repo index**: `kob chunks build-repo-vectors --force`
- **Check status**: `ls -lh _kano/backlog/products/<product>/.cache/chunks.sqlite3 .cache/repo_chunks.sqlite3`
- **When to rebuild**: After major refactoring, file moves, or when search results seem outdated

**Unified CLI:**
- Backlog: `kob search hybrid "text" --corpus backlog --product <product> --k 10`
- Repo: `kob search hybrid "text" --corpus repo --k 10 --fts-k 200`
- Both commands: `kob search {query|hybrid} "text" --corpus {backlog|repo} [options]`
- Future: `--corpus all` for cross-corpus search

**See also**: `docs/multi-corpus-search.md` for detailed hybrid search documentation.

## Kano CLI entrypoints (current surface)

Repo-local usage now centers on `kob` plus thin wrappers under `scripts/core/`. The CLI is intentionally organized as nested command groups so agents can discover operations by running `kob` and the wrapper help surfaces on demand.

## Profile overlays (user-facing config presets)

This skill supports **optional, file-based profile overlays** for end users who want
simple presets (for example, switching between `noop`, native heuristic, or a hosted
native embedding provider) without editing the repo’s main `.kano/backlog_config.toml`.

**Where profiles live**
- `<repo>/.kano/backlog_config/<group>/<name>.toml`
  - Example: `.kano/backlog_config/embedding/native-heuristic.toml`

**How to use a profile**
- Pass `--profile <group>/<name>` to `kob` (global option).
  - Example:
    - `kob --profile embedding/local-noop config show --product <product>`
    - `kob --profile embedding/native-heuristic embedding build --product <product>`
    - `kob --profile embedding/gemini-embedding-001 embedding build --product <product>`

**Optional: set a default profile in `.kano/backlog_config.toml`**
- Add either:
  - `[defaults] profile = "embedding/local-noop"`, or
  - `[shared.profiles] active = "embedding/local-noop"`
- CLI `--profile ...` always overrides the default.

**Env file loading (local dev convenience)**
- By default, the CLI will auto-load `env/local.secrets.env` if it exists.
- Override the location with `--env-file <path>` or `KANO_ENV_FILE`.
- Override behavior is path-only; existing environment variables are not replaced.

**Config vs backlog storage locations (intentional separation)**
- The **product list in config** is authoritative; it does not have to match folder names under `_kano/backlog/products/`.
- A product can point to a **backlog stored elsewhere**: another repo, another drive, a mounted NAS path, or a DB-backed store.
- Treat config as the registry of products; the physical backlog location is an implementation detail chosen per product.

**Precedence**
- Profile overlays are merged on top of the effective config (higher priority than repo defaults and topic/workset overlays in the current implementation).
- Explicit CLI flags still have the highest priority.

### Help-driven discovery (preferred)

Run these in order, expanding only what you need:

- `kob`
  - Shows the top-level command surface.
- `bash scripts/core/status.sh`
  - Shows grouped repo-local operational checks for common flows.
- `bash scripts/core/create-workitem.sh --help`
  - Shows a thin, task-oriented wrapper for one common operation.

Guideline: do not paste large `--help` output into chat; inspect it locally and run the command.

### Canonical examples (keep these few memorized)

- Bootstrap:
  - `kob doctor`
  - `kob admin init --product <name> --agent <id>`
- Daily workflow:
  - `kob item create --type task --title "..." --agent <id> --product <name> --duplicate-search-query "..." --duplicate-search-scope <name> --duplicate-decision create`
  - `kob workitem set-ready <item-id> --context "..." --goal "..." --approach "..." --acceptance-criteria "..." --risks "..." --product <name>`
  - `kob workitem check-ready <item-id> --product <name>`
  - `kob workitem update-state <item-ref> --state InProgress --product <name>`
  - `kob workitem attach-artifact <item-id> --path <file> --shared --agent <id> --product <name> [--note "..."]`
  - `kob view list --product <name>`
- Backlog integrity checks:
  - `kob validate uids --product <name>`
- Guarded product-root convergence:
  - `kob migration relocate-product plan --product <slug> --backlog-root <shared-backlog-root>`
  - Review the bounded plan, then use `apply ... --plan-hash <sha256> --confirm`.
  - See [docs/product-root-relocation.md](docs/product-root-re

…(truncated)