name: kano-agent-backlog-skill
description: Local-first backlog workflow. Use when planning work, creating/updating backlog items, writing ADRs, enforcing Ready gate, generating views, or maintaining derived indexes (SQLite/FTS/embeddings).
metadata:
short-description: Local backlog system
version: pre-alpha
stability: experimental

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.

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:
1) Python prerequisites are available (or install them), 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: product config in _kano/backlog/products/<product>/_config/config.toml.
• mode.skill_developer: true when this repo actively develops the skill itself (this demo repo).
• mode.persona: optional string describing the primary human persona (e.g. developer, pm, qa), used only for human-facing summaries/views.
• 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 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.

Backlog initialization (file scaffold + config + dashboards)

Detect (multi-product / platform layout):
- Product initialized if _kano/backlog/products/<product>/_config/config.toml exists (or confirm via python skills/kano-agent-backlog-skill/scripts/kano-backlog doctor --product <product>).

Bootstrap:
- Run python skills/kano-agent-backlog-skill/scripts/kano-backlog admin init --product <product> --agent <agent-id> [--backlog-root <path>] to scaffold _kano/backlog/products/<product>/ (items/, decisions/, views/, _config/, _meta/, _index/).
- The init command derives a project prefix, writes _config/config.toml, and refreshes dashboards so views exist immediately after initialization.
- 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.

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

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: 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).

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:
- Path: _kano/backlog/topics//
- Human brief: _kano/backlog/topics//brief.md (and brief.generated.md)
- List: python skills/kano-agent-backlog-skill/scripts/kano-backlog topic list --agent

Topic lifecycle:
1. 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
2. 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>
3. 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)
4. 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)
5. Close: python skills/kano-agent-backlog-skill/scripts/kano-backlog topic close <topic-name> --agent <id>
- Marks topic as closed; eligible for TTL cleanup
6. 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:

_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:
1. 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/
2. Work: Store scratch files in deliverables/ (patches, test outputs, etc.)
3. Refresh: python skills/kano-agent-backlog-skill/scripts/kano-backlog workset refresh <ITEM_ID> --agent <id>
- Updates refreshed_at timestamp
4. 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:

_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

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 → topic → workset → runtime
• Topic config: _kano/backlog/topics/<topic>/config.toml
• Use for temporary overrides (e.g., switch default_product during exploration)
• 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