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

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:

•

Install in development mode:

bash

cd skills/kano-agent-backlog-skill
pip install -e ".[dev]"

•

Verify installation:

bash

kano-backlog --version
kano-backlog doctor

•

Initialize backlog:

bash

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

See docs/agent-quick-start.md for complete setup instructions.

Non-negotiables

•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/Bugs sized for a single focused session.
- •Avoid ADRs unless a real architectural trade-off is made.
•
Ticketing threshold (agent-decided):
- •Open a new Task/Bug when you will change code/docs/views/scripts.
- •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):
- •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).
- •Example: "End-to-end embedding pipeline" = Epic; "Pluggable vector backend" = Feature; "MVP chunking pipeline" = UserStory; "Implement tokenizer adapter" = 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.
•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 kano-backlog CLI (python skills/kano-agent-backlog-skill/scripts/kano-backlog <command>) so audit logs capture the action.
•Skill scripts only operate on paths under _kano/backlog/ or _kano/backlog_sandbox/; refuse other paths.
•
After modifying backlog items, refresh the plain Markdown views immediately using python skills/kano-agent-backlog-skill/scripts/kano-backlog view refresh --agent <agent-id> --backlog-root <path> so the dashboards stay current.
- •Persona summaries/reports are available via python skills/kano-agent-backlog-skill/scripts/kano-backlog admin persona summary|report ....
•python skills/kano-agent-backlog-skill/scripts/kano-backlog 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:

•Python prerequisites are available (or install them), and
•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:

•Read ADR-0013 ("Codebase Architecture and Module Boundaries") in the product decisions folder.
•
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.
•
Place new code in the correct package:
- •Models/config/errors → src/kano_backlog_core/
- •Use-cases (create/update/view) → src/kano_backlog_ops/
- •Storage backends → src/kano_backlog_adapters/
- •CLI commands → src/kano_backlog_cli/commands/

Violating these boundaries will be flagged in code review.

Prerequisite install (Python)

Detect:

•Run python skills/kano-agent-backlog-skill/scripts/kano-backlog doctor --format plain.

If packages are missing, install once (recommended):

•Default: python -m pip install -e skills/kano-agent-backlog-skill
•Skill contributors: python -m pip install -e skills/kano-agent-backlog-skill[dev]
•Optional heavy dependencies (FAISS, sentence-transformers) should be installed manually per platform requirements before running the CLI against embedding features.

Container/Docker environments (agents)

If you run inside a restricted container (no pip, no build tools), admin init will fail because the CLI cannot install its Python dependencies. In that case, use a prebuilt image or rebuild the image with Python + pip available.

Minimum requirements in the container:

•Python 3.11+
•pip (or an equivalent package manager)
•Ability to install the skill dependencies

Recommended flow (container):

bash

python -m venv .venv
./.venv/Scripts/python -m pip install -e skills/kano-agent-backlog-skill
./.venv/Scripts/python skills/kano-agent-backlog-skill/scripts/kano-backlog admin init --product <product> --agent <agent-id>

If your container cannot install packages (no pip / no build tools), do not run the CLI there. Instead, run the CLI in a proper Python environment and mount the generated _kano/backlog and .kano/backlog_config.toml into the container.

Say this to your agent: "I'm in a container without pip. Please run kano-backlog admin init in a Python environment that has pip, then copy/mount _kano/backlog and .kano/backlog_config.toml into the container. If pip is available, install the skill in a venv and run admin init inside the container."

Backlog initialization (file scaffold + config + dashboards)

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 kano-backlog 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, then refresh views via kano-backlog view refresh.

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.
•Optional automation: when analysis.llm.enabled = true in config, view refresh generates views/snapshots/_analysis/Report_<persona>_analysis_prompt.md (deterministic prompt) and Report_<persona>_LLM.md (template or LLM output)
•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:

•DB Sequence: Tracks the next available ID for each type (EPIC, FTR, USR, TSK, BUG).
•Auto-increment: item create queries the DB for the next available ID.
•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:

bash

# Preview changes (dry run)
python skills/kano-agent-backlog-skill/scripts/kano-backlog admin sync-sequences --product <product> --dry-run

# Apply synchronization
python skills/kano-agent-backlog-skill/scripts/kano-backlog admin sync-sequences --product <product>

Output example:

code

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)
python skills/kano-agent-backlog-skill/scripts/kano-backlog admin sync-sequences --product <product>

# Step 2: Create item (system auto-assigns next available ID)
python skills/kano-agent-backlog-skill/scripts/kano-backlog item create \
  --type task \
  --title "Your task title" \
  --agent <agent-id> \
  --product <product>

# 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)
python skills/kano-agent-backlog-skill/scripts/kano-backlog item update-state \
  019c11e6-de87-7218-b89b-38c2e4e9cabd \
  --state Done \
  --agent <agent-id> \
  --product <product>

Option 2: Trash the incorrect item

bash

# Move incorrect item to _trash/ (recoverable)
python skills/kano-agent-backlog-skill/scripts/kano-backlog admin items trash \
  <UID> \
  --agent <agent-id> \
  --reason "ID conflict - incorrect duplicate" \
  --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"

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/ (dashboards / generated Markdown)

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

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: python skills/kano-agent-backlog-skill/scripts/kano-backlog search hybrid "text" --corpus backlog --product <product> --k 10
•Repo corpus: python skills/kano-agent-backlog-skill/scripts/kano-backlog 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):

•Start with semantic search for discovery and conceptual understanding
•Verify with grep/glob to find exact locations and confirm results
•Rebuild indexes when stale: Use --force flag if results seem outdated

Index maintenance:

•Build backlog index: python skills/kano-agent-backlog-skill/scripts/kano-backlog embedding build --product <product> --force
•Build repo index: python skills/kano-agent-backlog-skill/scripts/kano-backlog 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: kano-backlog search hybrid "text" --corpus backlog --product <product> --k 10
•Repo: kano-backlog search hybrid "text" --corpus repo --k 10 --fts-k 200
•Both commands: kano-backlog 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)

scripts/ exposes a single executable: scripts/kano-backlog. The CLI is intentionally organized as nested command groups so agents can discover operations via --help on-demand (instead of hard-coding the full command surface into this skill).

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, local Hugging Face, or a hosted 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/local-sentence-transformers-minilm.toml

How to use a profile

•
Pass --profile <group>/<name> to scripts/kano-backlog (global option).
- •
  Example:
  - •python skills/kano-agent-backlog-skill/scripts/kano-backlog --profile embedding/local-noop config show --product <product> --agent <agent-id>
  - •python skills/kano-agent-backlog-skill/scripts/kano-backlog --profile embedding/local-sentence-transformers-minilm embedding build --product <product>
  - •python skills/kano-agent-backlog-skill/scripts/kano-backlog --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:

•
python skills/kano-agent-backlog-skill/scripts/kano-backlog --help
- •Shows top-level groups (e.g., backlog, item, state, worklog, view) and global options.
•
python skills/kano-agent-backlog-skill/scripts/kano-backlog <group> --help
- •Shows subcommands for that group.
•
python skills/kano-agent-backlog-skill/scripts/kano-backlog <group> <command> --help
- •Shows required args/options for that command.

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

Canonical examples (keep these few memorized)

•
Bootstrap:
- •python skills/kano-agent-backlog-skill/scripts/kano-backlog doctor --format plain
- •python skills/kano-agent-backlog-skill/scripts/kano-backlog admin init --product <name> --agent <id>
•
Daily workflow:
- •python skills/kano-agent-backlog-skill/scripts/kano-backlog workitem create --type task --title "..." --agent <id> --product <name>
- •python skills/kano-agent-backlog-skill/scripts/kano-backlog workitem set-ready <item-id> --context "..." --goal "..." --approach "..." --acceptance-criteria "..." --risks "..." --product <name>
- •python skills/kano-agent-backlog-skill/scripts/kano-backlog workitem check-ready <item-id> --product <name>
- •python skills/kano-agent-backlog-skill/scripts/kano-backlog workitem update-state <item-ref> --state InProgress --agent <id> --message "..." --product <name>
- •python skills/kano-agent-backlog-skill/scripts/kano-backlog workitem attach-artifact <item-id> --path <file> --shared --agent <id> --product <name> [--note "..."]
- •python skills/kano-agent-backlog-skill/scripts/kano-backlog view refresh --agent <id> --product <name>
•
Backlog integrity checks:
- •python skills/kano-agent-backlog-skill/scripts/kano-backlog admin validate uids --product <name>

Conflict handling policy (configurable)

Use product config to control how duplicate IDs and UIDs are handled by maintenance commands such as admin links normalize-ids.

•
Config keys (product _config/config.toml):
- •conflict_policy.id_conflict: default rename (rename duplicate IDs).
- •conflict_policy.uid_conflict: default trash_shorter (move shorter duplicate content to _trash/).
•trash_shorter uses _trash/<YYYYMMDD>/... under the product root; items get a Worklog entry.

Sandbox workflow (isolated experimentation)

For testing, prototyping, or demos without affecting production backlog:

•Create: python skills/kano-agent-backlog-skill/scripts/kano-backlog admin sandbox init <sandbox-name> --product <source-product> --agent <id>
•Use: python skills/kano-agent-backlog-skill/scripts/kano-backlog workitem create --product <sandbox-name> ... (same CLI, different product)
•Cleanup: rm -rf _kano/backlog_sandbox/<sandbox-name> (git will ignore this directory)
•Rationale: Sandboxes mirror production structure but live in _kano/backlog_sandbox/, so changes never leak into _kano/backlog/.

Artifacts policy (local-first)

•
Storage locations:
- •Shared across products: _kano/backlog/_shared/artifacts/<ITEM_ID>/ (use --shared).
- •Product-local: _kano/backlog/products/<product>/artifacts/<ITEM_ID>/ (use --no-shared).
•
Usage:
- •Attach via workitem attach-artifact — copies the file and appends a Worklog link.
- •Prefer lightweight, text-first artifacts (Markdown, Mermaid, small images). Use Git LFS for large binaries if needed.
•
Git policy:
- •Commit human-readable artifacts that aid review. Avoid committing generated binaries unless justified.
- •Sandboxes under _kano/backlog_sandbox/ are gitignored; artifacts there are ephemeral.
- •For derived analysis, store under views/_analysis/ (gitignored by default), and keep deterministic reports in views/.
•
Linking:
- •The CLI appends a Markdown link relative to the item file. Optionally add a ## Links section for richer context.

State update helper

•Use python skills/kano-agent-backlog-skill/scripts/kano-backlog workitem update-state ... to update state + append Worklog.
•Prefer --action on kano-backlog state transition for the common transitions (start, ready, review, done, block, drop).
•Use python skills/kano-agent-backlog-skill/scripts/kano-backlog workitem validate <item-id> to check the Ready gate explicitly.

Topic and Workset workflow (context management)

When to use Topics

Topics are shareable context buffers for multi-step work that spans multiple work items or requires exploratory research before creating formal backlog items.

Use Topics when:

•Exploring a complex problem that may result in multiple work items
•Collecting code snippets, logs, and materials across multiple sessions
•Collaborating across agents/sessions with a shared context
•Refactoring work that requires tracking multiple code locations

Topic creation triggers (practical rubric)

Topics are a shared, mid-term context buffer. Create a Topic when the context is likely to be reused, revisited, handed off, or split into multiple work items.

Hard triggers (agent MAY create immediately):

•2+ backlog work items are expected (or likely to be created) to complete the effort.
•Cross-module / multi-file work requires tracking multiple code locations or snippet refs.
•Work is expected to span multiple sessions or be handed off across agents.
•You are collecting durable evidence/materials (logs, snippet refs, pinned docs) that should be preserved.

Soft triggers (ask the human once before creating):

•You have entered an explore -> adjust -> re-explore loop 2+ times (context is no longer linear).
•The thread references 3+ distinct information sources that should stay linked (files, ADRs/docs, external links).
•There are 2+ unresolved decisions (A vs B) that will change the downstream plan.
•The user keeps appending new constraints/scope in the same thread (for example: 3+ follow-ups).

Anti-triggers (prefer Workset or no Topic):

•Single-item execution where a clear Task/Bug exists and you are ready to implement (use a Workset).
•Small, single-file change with low risk of handoff or revisiting.
•Pure Q&A / explanation with no need to preserve artifacts or evidence.

Post-create human notification (required)

After creating a Topic, always print this (fill in values):

•Topic: <topic-name>
•Path: _kano/backlog/topics/<topic-name>/
•Human brief: _kano/backlog/topics/<topic-name>/brief.md (and brief.generated.md)
•List: python skills/kano-agent-backlog-skill/scripts/kano-backlog topic list --agent <agent-id>

Topic lifecycle:

•
Create: python skills/kano-agent-backlog-skill/scripts/kano-backlog topic create <topic-name> --agent <id>
- •Creates _kano/backlog/topics/<topic>/ with manifest.json, brief.md, brief.generated.md, notes.md, and materials/ subdirectories
•
Collect materials:
- •Add items: topic add <topic-name> --item <ITEM_ID>
- •Add code snippets: topic add-snippet <topic-name> --file <path> --start <line> --end <line> --agent <id>
- •Pin docs: topic pin <topic-name> --doc <path>
•Distill: python skills/kano-agent-backlog-skill/scripts/kano-backlog topic distill <topic-name>

•Generates/overwrites deterministic brief.generated.md from collected materials
•brief.md is a stable, human-maintained brief (do not overwrite it automatically)

•
Switch context: python skills/kano-agent-backlog-skill/scripts/kano-backlog topic switch <topic-name> --agent <id>
- •Sets active topic (affects config overlays and workset behavior)
•
Close: python skills/kano-agent-backlog-skill/scripts/kano-backlog topic close <topic-name> --agent <id>
- •Marks topic as closed; eligible for TTL cleanup
•
Cleanup: python skills/kano-agent-backlog-skill/scripts/kano-backlog topic cleanup --ttl-days <N> [--dry-run]
- •Removes raw materials from closed topics older than TTL

Topic snapshots (retention policy):

•Snapshots are intended for milestone checkpoints (pre-merge/split/restore, risky bulk edits), not every small edit.
•To prevent noise, keep only the latest snapshot per topic in this demo repo.
•
After creating a snapshot (or periodically), prune all but the newest snapshot:
- •python skills/kano-agent-backlog-skill/scripts/kano-backlog topic snapshot cleanup <topic-name> --ttl-days 0 --keep-latest 1 --apply

Topic structure:

code

_kano/backlog/topics/<topic>/
  manifest.json          # refs to items/docs/snippets, status, timestamps
  brief.md               # stable, human-maintained brief (do not overwrite automatically)
  brief.generated.md     # deterministic distilled brief (generated/overwritten by `topic distill`)
  notes.md               # freeform notes (backward compat)
  materials/             # raw collection (gitignored by default)
    clips/               # code snippet refs + cached text
    links/               # urls / notes
    extracts/            # extracted paragraphs
    logs/                # build logs / command outputs
  synthesis/             # intermediate drafts
  publish/               # prepared write-backs (patches/ADRs)
  config.toml            # optional topic-specific config overrides

When to use Worksets

Worksets are per-item working directories (cached, derived data) for a single backlog item.

Use Worksets when:

•Starting work on a specific Task/Bug/UserStory
•Need scratch space for deliverables (patches, test artifacts, etc.)
•Want item-specific config overrides (rare)

Workset lifecycle:

•
Initialize: python skills/kano-agent-backlog-skill/scripts/kano-backlog workset init <ITEM_ID> --agent <id> [--ttl-hours <N>]
- •Creates _kano/backlog/.cache/worksets/items/<ITEM_ID>/ with meta.json, plan.md, notes.md, deliverables/
•Work: Store scratch files in deliverables/ (patches, test outputs, etc.)
•
Refresh: python skills/kano-agent-backlog-skill/scripts/kano-backlog workset refresh <ITEM_ID> --agent <id>
- •Updates refreshed_at timestamp
•
Cleanup: python skills/kano-agent-backlog-skill/scripts/kano-backlog workset cleanup --ttl-hours <N> [--dry-run]
- •Removes stale worksets older than TTL

Workset structure:

code

_kano/backlog/.cache/worksets/items/<ITEM_ID>/
  meta.json              # workset metadata (item_id, agent, timestamps, ttl)
  plan.md                # execution plan template
  notes.md               # work notes with Decision: marker guidance
  deliverables/          # scratch outputs (patches, logs, test artifacts)
  config.toml            # optional item-specific config overrides

Topic vs Workset decision guide

Scenario	Use Topic	Use Workset
Exploring before creating items	✅ Yes	❌ No
Multi-item refactor	✅ Yes	❌ No
Collecting code snippets across files	✅ Yes	❌ No
Shared context for collaboration	✅ Yes	❌ No
Single item scratch space	❌ No	✅ Yes
Item-specific deliverables	❌ No	✅ Yes
Version-controlled distillation	✅ Yes (brief.generated.md)	❌ No

Best practice: Start exploration in a Topic, create work items as scope clarifies, then use Worksets for individual item execution.

Active topic and config overlays

•Active topic state is shared across agents: _kano/backlog/.cache/worksets/state.json
•
When an agent has an active topic, config resolution includes topic overrides:
- •Layer order: defaults → product → profile → topic → workset → runtime
- •Topic config: _kano/backlog/topics/<topic>/config.toml
- •Use for temporary overrides (e.g., switch default_product during exploration)

Named profiles (pipeline experiments)

•Profiles are file-based overrides stored at: .kano/backlog_config/<profile>.toml (supports subfolders)
•
--profile supports two forms:
- •
  Path mode (recommended): repo-root relative or absolute path to a .toml file
  - •--profile .kano/backlog_config/embedding/local-noop.toml
- •
  Shorthand mode: profile ref resolved under .kano/backlog_config/
  - •--profile embedding/local-noop
•
Precedence rule:
- •Explicit paths (absolute, or starting with . or ending in .toml) are honored directly.
- •Shorthand prefers .kano/backlog_config/<ref>.toml first.
- •If no project-local profile exists, shorthand falls back to <repo_root>/<ref>.toml.
•
Use --profile ... on commands like:
- •kano-backlog config show --product <product> --profile .kano/backlog_config/embedding/local-noop.toml
- •kano-backlog embedding build --product <product> --profile embedding/local-noop
•
List and inspect profiles:
- •kano-backlog config profiles list --product <product>
- •kano-backlog config profiles show <profile> --product <product>
•Inspect active topic: python skills/kano-agent-backlog-skill/scripts/kano-backlog topic list --agent <id>
•Inspect shared topic state: python skills/kano-agent-backlog-skill/scripts/kano-backlog topic show-state --agent <id> --format json

Materials buffer (Topic-specific)

•Reference-first snippet collection: Avoid large copy-paste; store file+line+hash+optional snapshot
•
Snippet refs include:
- •file: relative path from workspace root
- •lines: [start, end] (1-based inclusive)
- •hash: sha256:... of content for staleness check
- •cached_text: optional snapshot (use --snapshot to include)
- •revision: git commit hash if available

Human decision materials vs. machine manifest

Dual-Readability Design: Every artifact checks against both human and agent readability:

•Human-Readable: High-level summaries, clear checklists, "manager-friendly" reports for rapid decision-making
•Agent-Readable: Structural precision, file paths, line numbers, explicit markers for action without hallucination

Implementation in Topics:

•
Treat manifest.json as machine-oriented metadata:
- •seed_items: UUID list for precise agent reference
- •snippet_refs: file+line+hash for deterministic loading
- •pinned_docs: absolute paths for unambiguous reference
•
Keep brief.generated.md deterministic and tool-owned (generated/overwritten by topic distill):
- •Readable item titles (e.g., "KABSD-TSK-0042: Implement tokenizer adapter")
- •If available, include item path and keep UID in a hidden HTML comment for deterministic mapping
- •Materials index with items/docs/snippets sorted for repeatability
•
Keep brief.md human-oriented and stable (do not overwrite automatically):
- •Context summary and key decisions
- •Optional: include a human-friendly materials list (do not duplicate raw snippet text)
•
Put human-facing decision support in _kano/backlog/topics/<topic>/notes.md (and/or pinned docs), e.g.:
- •Decision to make
- •Options + trade-offs
- •Evidence (ADR links, snippet refs, benchmark/log artifacts)
- •Recommendation + follow-ups
•Staleness detection: Compare current file hash with stored hash to detect if code changed
•Distillation: topic distill generates deterministic brief.generated.md with a repeatable materials index

END_OF_SKILL_SENTINEL