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:

   cd skills/kano-agent-backlog-skill
   pixi run build-dev
   

2. Verify installation:

   bash scripts/internal/show-version.sh
   kob
   kob doctor
   

3. Initialize backlog:

   cd /path/to/user/project
   kob admin init --product <product-name> --agent <your-agent-id>
   

See 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.

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:

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:

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:

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.

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:

# 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

# Reference by UID (always unambiguous)
kob workitem update-state \
  019c11e6-de87-7218-b89b-38c2e4e9cabd \
  --state Done \
  --product <product>

Option 2: Trash the incorrect item

# 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

# 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.

# 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:

# _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:

# 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)