kano-agent-backlog-skill

# Kano Agent Backlog Skill (local-first)

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

## 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.json`.
  - `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.json` 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.json`, 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`

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

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

| 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 is per-agent: `_kano/backlog/.cache/worksets/active_topic.<agent>.txt`
- 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)
- Get active topic: `python skills/kano-agent-backlog-skill/scripts/kano-backlog topic show --agent <id>`

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