@anyberg/agent-conventions 1.0.0

package/bin/cli.js

@@ -0,0 +1,311 @@
+#!/usr/bin/env node
+/**
+ * agent-conventions installer.
+ *
+ * Deliberately dependency-free. This is run through `npx` on machines that have
+ * never seen it before, so every dependency is a supply-chain decision made on
+ * the user's behalf. Prompts are ~40 lines of readline; that is cheaper than
+ * owning a prompt library's transitive tree.
+ */
+
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import readline from 'node:readline/promises'
+import { fileURLToPath } from 'node:url'
+
+import { buildPlan, renderDisclosure } from '../src/plan.js'
+import { SELECTABLE_AGENTS, parseAgentSelection } from '../src/targets.js'
+import {
+  applyInstructionWrite, installSkill, linkSkill, readReceipt, removeBlock, writeReceipt,
+} from '../src/write.js'
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const PKG = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf8'))
+
+const USAGE = `
+agent-conventions ${PKG.version}
+
+  npx @anyberg/agent-conventions            install (prompts for scope and agents)
+  npx @anyberg/agent-conventions uninstall  remove exactly what the receipt records
+
+Options
+  -g, --global            install for every project on this machine
+  -p, --project           install into the current project only
+  -a, --agent <list>      comma-separated, or "all" (claude-code, codex,
+                          github-copilot, opencode, cursor, gemini-cli)
+  -c, --components <list> skills,instructions  (default: both at global scope,
+                          skills only at project scope)
+      --copy              copy instead of symlinking
+      --replace-symlinks  replace an existing instruction symlink with a real
+                          file. Without this, a symlink is refused rather than
+                          written through.
+      --dry-run           print the plan and exit without writing
+  -y, --yes               skip the confirmation prompt (the plan is still printed)
+  -h, --help
+`.trim()
+
+function parseArgs(argv) {
+  const opts = {
+    command: 'install', scope: null, agents: null, components: null,
+    copy: false, replaceSymlinks: false, dryRun: false, yes: false, help: false,
+  }
+  const rest = [...argv]
+  while (rest.length) {
+    const arg = rest.shift()
+    switch (arg) {
+      case 'install': opts.command = 'install'; break
+      case 'uninstall': case 'remove': opts.command = 'uninstall'; break
+      case '-g': case '--global': opts.scope = 'global'; break
+      case '-p': case '--project': opts.scope = 'project'; break
+      case '-a': case '--agent': opts.agents = rest.shift(); break
+      case '-c': case '--components': opts.components = rest.shift(); break
+      case '--copy': opts.copy = true; break
+      case '--replace-symlinks': opts.replaceSymlinks = true; break
+      case '--dry-run': opts.dryRun = true; break
+      case '-y': case '--yes': opts.yes = true; break
+      case '-h': case '--help': opts.help = true; break
+      default:
+        if (arg.startsWith('-')) throw new Error(`unknown option: ${arg}`)
+    }
+  }
+  return opts
+}
+
+/**
+ * Are we being driven by an agent rather than a person?
+ *
+ * A prompt nobody can answer is a hang, so anything non-interactive runs with
+ * defaults and prints the plan instead of asking.
+ */
+function isInteractive() {
+  if (process.env.CI) return false
+  if (process.env.CLAUDECODE || process.env.CLAUDE_CODE) return false
+  if (process.env.AGENT || process.env.OPENCODE || process.env.CURSOR_AGENT) return false
+  return process.stdin.isTTY === true && process.stdout.isTTY === true
+}
+
+/** Which agents show evidence of being installed on this machine? */
+function detectAgents(home) {
+  const probes = {
+    'claude-code': ['.claude'],
+    codex: ['.codex'],
+    'github-copilot': ['.copilot'],
+    opencode: ['.config/opencode'],
+    cursor: ['.cursor'],
+    'gemini-cli': ['.gemini'],
+  }
+  return Object.entries(probes)
+    .filter(([, dirs]) => dirs.some((d) => fs.existsSync(path.join(home, d))))
+    .map(([id]) => id)
+}
+
+function resolveAgents(spec, detected) {
+  const all = SELECTABLE_AGENTS.map((a) => a.id)
+  if (!spec) return detected.length ? detected : all
+  if (spec === 'all') return all
+  const chosen = spec.split(',').map((s) => s.trim()).filter(Boolean)
+  const unknown = chosen.filter((c) => !all.includes(c))
+  if (unknown.length) throw new Error(`unknown agent(s): ${unknown.join(', ')}\nknown: ${all.join(', ')}`)
+  return chosen
+}
+
+async function ask(rl, question, fallback) {
+  const answer = (await rl.question(question)).trim()
+  return answer === '' ? fallback : answer
+}
+
+async function promptForScope(rl) {
+  console.log('Where should this be installed?\n')
+  console.log('  1) Project  — this repository only')
+  console.log('  2) Global   — every project on this machine\n')
+  const answer = await ask(rl, 'Choose [1]: ', '1')
+  return answer.startsWith('2') || answer.toLowerCase().startsWith('g') ? 'global' : 'project'
+}
+
+async function promptForAgents(rl, scope, detected) {
+  const all = SELECTABLE_AGENTS.map((a) => a.id)
+
+  if (scope === 'project') {
+    // One write to .agents/skills already serves every agent here, so the only
+    // real choice is whether to bridge Claude Code — which reads its own path.
+    // Say so explicitly: "all agents" is the default, not something to opt into.
+    console.log('\nInstalling for ALL agents. One .agents/skills/ directory covers Codex,')
+    console.log('GitHub Copilot, OpenCode, Cursor, Gemini CLI and others.\n')
+    console.log('Claude Code is the exception — it reads only .claude/skills/.\n')
+    const answer = await ask(rl, 'Also link Claude Code? [Y/n]: ', 'y')
+    return answer.toLowerCase().startsWith('n') ? all.filter((a) => a !== 'claude-code') : all
+  }
+
+  console.log('\nInstall for which agents?\n')
+  SELECTABLE_AGENTS.forEach((a, i) => {
+    const mark = detected.includes(a.id) ? '*' : ' '
+    console.log(`  ${mark} ${i + 1}) ${a.label}`)
+  })
+  console.log('\n    a) All of the above')
+  console.log('\n  * = detected on this machine')
+  const preset = detected.length ? detected : all
+  const answer = await ask(rl, `\nNumbers, "a" for all, or Enter for detected [${preset.join(', ')}]: `, '')
+  const { agents, reason } = parseAgentSelection(answer, { preset })
+  if (reason === 'unrecognised') {
+    console.log(`Nothing recognised in "${answer}" — using the detected set.`)
+  }
+  return agents
+}
+
+async function runInstall(opts) {
+  const home = os.homedir()
+  const cwd = process.cwd()
+  const detected = detectAgents(home)
+  const interactive = isInteractive() && !opts.yes && !opts.dryRun
+
+  let scope = opts.scope
+  let agents = opts.agents ? resolveAgents(opts.agents, detected) : null
+
+  if (interactive) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+    try {
+      if (!scope) scope = await promptForScope(rl)
+      if (!agents) agents = await promptForAgents(rl, scope, detected)
+    } finally {
+      rl.close()
+    }
+  }
+  scope ??= 'project'
+  agents ??= resolveAgents(opts.agents, detected)
+
+  const components = opts.components
+    ? opts.components.split(',').map((s) => s.trim()).filter(Boolean)
+    : scope === 'global' ? ['skills', 'instructions'] : ['skills']
+
+  const plan = buildPlan({ packageRoot: PACKAGE_ROOT, scope, components, agents, home, cwd, copy: opts.copy })
+
+  console.log('\n' + renderDisclosure(plan, { packageVersion: PKG.version }) + '\n')
+  if (opts.dryRun) {
+    console.log('--dry-run: nothing was written.')
+    return 0
+  }
+
+  if (interactive) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+    let answer
+    try {
+      answer = await ask(rl, 'Proceed? [y/N]: ', 'n')
+    } finally {
+      rl.close()
+    }
+    if (!answer.toLowerCase().startsWith('y')) {
+      console.log('Aborted. Nothing was written.')
+      return 1
+    }
+  }
+
+  const receipt = {
+    package: PKG.name, version: PKG.version, installedAt: new Date().toISOString(),
+    scope, mode: plan.mode, skills: null, instructions: [],
+  }
+
+  if (plan.skills) {
+    const written = []
+    for (const skill of plan.skills.sources) {
+      const dest = path.join(plan.skills.canonical, skill.name)
+      installSkill(skill.dir, dest)
+      written.push(dest)
+    }
+    const links = []
+    let mode = plan.mode
+    for (const link of plan.skills.links) {
+      for (const name of plan.skills.names) {
+        const linkPath = path.join(link.dir, name)
+        mode = linkSkill(path.join(plan.skills.canonical, name), linkPath, { copy: opts.copy })
+        links.push(linkPath)
+      }
+    }
+    receipt.skills = { canonical: plan.skills.canonical, dirs: written, links }
+    receipt.mode = mode
+    console.log(`Installed ${plan.skills.names.length} skills to ${plan.skills.canonical}`)
+    if (links.length) console.log(`Linked ${links.length} into ${plan.skills.links.map((l) => l.dir).join(', ')} (${mode})`)
+  }
+
+  if (plan.instructions.length) {
+    const content = fs.readFileSync(path.join(PACKAGE_ROOT, 'AGENTS.md'), 'utf8')
+    for (const item of plan.instructions) {
+      try {
+        const applied = applyInstructionWrite(item, content, { replaceSymlinks: opts.replaceSymlinks })
+        receipt.instructions.push({ file: applied.file, applied: applied.applied })
+        console.log(`${applied.applied.padEnd(18)} ${applied.file}`)
+      } catch (err) {
+        console.error(`SKIPPED            ${item.file}\n                   ${err.message}`)
+      }
+    }
+  }
+
+  writeReceipt(plan.receipt, receipt)
+  console.log(`\nReceipt: ${plan.receipt}`)
+  // Both forms are printed because either may be the one that works: the
+  // published name until the package is on npm, the git specifier after.
+  const flag = scope === 'global' ? '-g' : '-p'
+  console.log(`Undo:    npx ${PKG.name} uninstall ${flag}`)
+  console.log(`         npx github:aanyberg/agent-conventions uninstall ${flag}`)
+  return 0
+}
+
+async function runUninstall(opts) {
+  const home = os.homedir()
+  const cwd = process.cwd()
+  const scope = opts.scope ?? 'project'
+  const file = path.join(scope === 'global' ? home : cwd, '.agent-conventions.json')
+  const receipt = readReceipt(file)
+  if (!receipt) {
+    console.error(`No receipt at ${file} — nothing recorded as installed at ${scope} scope.`)
+    return 1
+  }
+
+  // Only ever remove what the receipt records. Never infer.
+  for (const link of receipt.skills?.links ?? []) fs.rmSync(link, { recursive: true, force: true })
+  for (const dir of receipt.skills?.dirs ?? []) fs.rmSync(dir, { recursive: true, force: true })
+  for (const item of receipt.instructions ?? []) {
+    try {
+      // Always strip the block and judge by what is left, even for a file this
+      // installer created. Keying off `applied === 'create'` and deleting
+      // outright would take anything the user added to that file afterwards —
+      // a small data-loss case, but the same class as the symlink one.
+      const text = fs.readFileSync(item.file, 'utf8')
+      const stripped = removeBlock(text)
+      if (stripped === '') {
+        fs.rmSync(item.file, { force: true })
+        console.log(`removed  ${item.file}`)
+      } else {
+        fs.writeFileSync(item.file, stripped, 'utf8')
+        console.log(`stripped ${item.file} (kept your content)`)
+      }
+    } catch (err) {
+      console.error(`skipped  ${item.file}: ${err.message}`)
+    }
+  }
+  fs.rmSync(file, { force: true })
+  console.log(`\nRemoved. Receipt deleted: ${file}`)
+  return 0
+}
+
+async function main() {
+  let opts
+  try {
+    opts = parseArgs(process.argv.slice(2))
+  } catch (err) {
+    console.error(err.message)
+    return 2
+  }
+  if (opts.help) {
+    console.log(USAGE)
+    return 0
+  }
+  try {
+    return opts.command === 'uninstall' ? await runUninstall(opts) : await runInstall(opts)
+  } catch (err) {
+    console.error(`error: ${err.message}`)
+    return 1
+  }
+}
+
+process.exitCode = await main()

package/gemini-extension.json

@@ -0,0 +1,5 @@
+{
+  "name": "agent-conventions",
+  "version": "1.0.0",
+  "description": "Skills and agents for backlog management, git conventions, code standards, and planning workflows."
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@anyberg/agent-conventions",
+  "version": "1.0.0",
+  "description": "Skills and agents for backlog management, git conventions, code standards, and planning workflows — installable into Claude Code, Codex, GitHub Copilot, OpenCode, Cursor and Gemini CLI.",
+  "type": "module",
+  "license": "MIT",
+  "author": {
+    "name": "Alexander Nyberg"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aanyberg/agent-conventions.git"
+  },
+  "homepage": "https://github.com/aanyberg/agent-conventions#readme",
+  "bugs": {
+    "url": "https://github.com/aanyberg/agent-conventions/issues"
+  },
+  "keywords": [
+    "agent-skills",
+    "claude-code",
+    "codex",
+    "copilot",
+    "opencode",
+    "cursor",
+    "conventions"
+  ],
+  "bin": {
+    "agent-conventions": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skills",
+    "agents",
+    "AGENTS.md",
+    "plugin.json",
+    "gemini-extension.json",
+    ".claude-plugin",
+    ".codex-plugin"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "scripts": {
+    "test": "node --test tests-js/"
+  }
+}

package/plugin.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "agent-conventions",
+  "version": "1.0.0",
+  "description": "Skills and agents for backlog management, git conventions, code standards, and planning workflows.",
+  "author": {
+    "name": "Alexander Nyberg"
+  },
+  "repository": "https://github.com/aanyberg/agent-conventions",
+  "license": "MIT",
+  "keywords": ["conventions", "code-standards", "git", "backlog", "planning"]
+}

package/skills/api-design/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: api-design
+description: Rules for designing public APIs, managing visibility, backwards compatibility, and API patterns
+---
+
+# API Design & Interfaces
+
+**When to check**: designing or modifying public APIs, parameters, or class interfaces.
+
+## Rules
+
+- Prefix implementation details with `_` and exclude from `__all__` — keeps the public surface minimal and frees internal code from backward-compatibility obligations.
+- Export commonly-used types/classes from the top-level `vcc.<PROJECT>` package — simplifies user imports and lets internal structure be refactored without breaking consumers.
+- Put a `_: KW_ONLY` marker before optional fields in dataclasses/Pydantic models — callers can't pass defaults positionally, so fields can be added or reordered without breakage.
+- Prefer instance methods when accessing `self` or enabling polymorphism; use module-level functions when no instance state is needed — extract shared logic to private top-level helpers to avoid cross-class duplication.
+- Keep old names as deprecated aliases when renaming public API elements — lets users migrate gradually instead of breaking on upgrade.
+- Return new collections from transform functions instead of mutating inputs — avoids surprising side effects (exceptions: performance-critical paths or functions named `update_*`/`*_inplace`).
+- Don't access or modify private attributes (`_prefixed`) — use public APIs, properties, or constructor parameters, so internal changes don't break callers.

package/skills/architecture-planning/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: architecture-planning
+description: Use when making architectural decisions, designing systems or components, choosing technologies, defining boundaries, or evaluating structural trade-offs. Maintains a living architecture.md and records decisions as ADRs. Language- and stack-agnostic.
+---
+
+# Architecture Planning
+
+## When This Applies
+
+Engage this skill when a change touches **structure**, not just implementation:
+
+- Introducing or removing a service, module, layer, or boundary
+- Choosing a technology, framework, datastore, protocol, or external dependency
+- Defining how components communicate (sync/async, API style, events, contracts)
+- Data modelling, ownership, and consistency decisions
+- Cross-cutting concerns: auth, observability, error handling, config, security, scaling
+- Anything expensive to reverse later
+
+If a task surfaces one of these, **stop and plan here before coding** — this is the "Surface blockers" path from **task-workflow** skill.
+
+## Legacy Layout Migration
+
+Older projects may still have `<root>/.agents/architecture.md`. Before reading or editing the architecture doc, check once per project:
+
+1. If `<root>/.agents/architecture.md` exists and `<root>/.planning/architecture.md` does not, create `<root>/.planning/` (if missing) and move the file there.
+2. Do this silently and automatically — it is additive and safe. Do not ask for confirmation.
+
+## Two Artifacts
+
+| Artifact | Location | Purpose |
+|---|---|---|
+| `architecture.md` | in `<root>/.planning/` | Living description of the system **as it is now** |
+| ADR entries | `## Decisions` log in `architecture.md` | Immutable record of **why** a decision was made, with context and alternatives |
+
+Rule of thumb: `architecture.md` answers *"how does this work today?"*; ADRs answer *"why is it this way?"*. Keep `architecture.md` current by editing it; never rewrite history in an ADR — supersede it instead.
+
+## architecture.md Structure
+
+Keep it short and current. Delete stale sections rather than letting them rot.
+
+```markdown
+# Architecture
+
+**Last updated:** <date>
+
+## 1. Overview
+One paragraph: what the system does and its core design philosophy.
+
+## 2. Context & Constraints
+- Business/technical drivers shaping the design
+- Hard constraints (compliance, latency, budget, team size, existing systems)
+- Explicit non-goals — what this system intentionally does NOT do
+
+## 3. System Structure
+- Components/services/modules and their responsibilities
+- A diagram (Mermaid/ASCII) of how they connect
+- Boundaries: what each owns, what it must not reach into
+
+## 4. Data
+- Key entities and ownership (who is the source of truth)
+- Storage choices and why
+- Consistency / migration approach
+
+## 5. Cross-Cutting Concerns
+Auth, observability, error handling, config, security, scaling — one line each, link out for detail.
+
+## 6. Key Decisions
+Index of ADRs with status. Link each.
+
+## 7. Known Trade-offs & Risks
+What was knowingly accepted, and what would force a rethink.
+```
+
+## ADR Structure
+
+One decision per record. Numbered, dated, never deleted.
+
+```markdown
+# ADR-<NNNN>: <short title>
+
+**Status:** proposed | accepted | superseded by ADR-<N> | deprecated
+**Date:** <date>
+
+## Context
+The forces at play: problem, constraints, what made this a decision worth recording.
+
+## Decision
+What we chose, stated plainly.
+
+## Alternatives Considered
+Each real option, with why it was rejected. "No alternatives" usually means the analysis is missing.
+
+## Consequences
+What becomes easier, what becomes harder, what we now owe (follow-ups, risks, migration cost).
+```
+
+## Decision Process
+
+Work through these as a dialogue with the user — do not decide unilaterally on structural matters.
+
+1. **Frame the problem.** State what is actually being decided and why now. Separate the decision from the implementation.
+2. **Surface constraints & drivers.** Quality attributes first (performance, security, scalability, maintainability, cost, team capability). Name the ones that dominate — you cannot maximise all.
+3. **Generate real alternatives.** At least two genuine options, including "do nothing / defer." Bias toward the simplest thing that satisfies the constraints (KISS, YAGNI).
+4. **Evaluate against drivers, not preference.** Trade-offs explicitly: what each option costs. Prefer reversible decisions; spend the analysis budget on the irreversible ones.
+5. **Recommend, then confirm.** Give a clear recommendation with reasoning — not an unranked survey. Get user agreement before recording.
+6. **Record.** Write the ADR and update the affected `architecture.md` sections in the same change.
+
+## Agent Discipline
+
+- A structural decision is a **Blocker** in `/task-workflow` terms — surface it, do not guess.
+- No new service, dependency, or boundary without an ADR and a recommendation the user has confirmed.
+- When a change makes `architecture.md` wrong, update it in the same branch — treat it like a failing test.
+- Superseding a decision: set the old ADR's status to `superseded by ADR-N`, write the new one; never edit the original's reasoning.

package/skills/backlog-management/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: backlog-management
+description: Single interface for every backlog operation. Use whenever work items are listed, created, claimed, released, linked to a PR, de-duplicated, or marked done, cancelled, or blocked, including when another skill or routine says "add to backlog", "update status", "check what is in flight", or "record a follow-up". Resolves the storage backend (GitHub Issues or BACKLOG.md) from `.planning/policy.yml`, never lets callers touch the backend directly.
+---
+
+# Backlog Management
+
+One interface, two backends. Callers use the operations in this file. Backend files hold the mechanics.
+
+## 1. Resolve the backend (once per session)
+
+If `<root>/.planning/policy.yml` does not exist, run `scripts/generate-policy.sh` first — it creates the file from best-practice defaults (backend auto-detected the same way as step 2 below) and prints what it generated. Report that generation in your first response. It never overwrites an existing file, so this is safe to run unconditionally.
+
+Then run `scripts/detect-backend.sh` from the project root, or apply the same order by hand:
+
+1. `.planning/policy.yml` → `backlog.backend`. Explicit value wins.
+2. Auto-detect `github-issues` only if all hold: `git remote get-url origin` matches `github.com`; `gh auth status` succeeds; `gh api repos/{owner}/{repo} --jq .has_issues` is `true`.
+3. Otherwise `markdown`.
+4. Neither usable → stop, report, do nothing.
+
+State the resolved backend in your first report line. Load `backends/<backend>.md` for mechanics.
+
+## 2. Status model
+
+```
+backlog → ready → active → in-review → done
+   ↘ blocked ↙        ↘ cancelled
+```
+
+| Status | Meaning | Who sets it |
+|---|---|---|
+| `backlog` | Identified, criteria may be thin | sweep, humans, agents recording leftovers |
+| `ready` | Criteria clear and testable, no open decisions | triage or human only |
+| `active` | Claimed, task file and branch exist | claimant |
+| `in-review` | PR open, verification pending | claimant |
+| `blocked` | Needs a human decision or an external dependency; evidence recorded | anyone |
+| `done` | Merged, criteria verified | releaser, after merge-readiness passes |
+| `cancelled` | Will not be done, reason recorded | human or triage |
+
+Rules: no `backlog → done`. Autonomous agents select only `ready` (see `policy.yml` `statuses.agent_selectable`). `blocked` is a side state, it keeps the previous state's evidence.
+
+## 3. Operations
+
+| Op | Contract |
+|---|---|
+| `list(filter)` | Returns items with id, title, type, priority, status, depends_on, assignee, pr. Filters: status, type, label, text. |
+| `dedupe(topic)` | Search titles and bodies across all states including done/cancelled. Returns matches. Callers must not create when a match exists. |
+| `create(item)` | Fields: title, type, priority (default medium), goal, acceptance_criteria[], depends_on[], evidence, origin. Returns id. Never assigns an ID by guessing, see backend. |
+| `needsDiscussion(item, question)` | Same as create but marked needs-discussion, status backlog, no `ready`. `question` is mandatory. |
+| `claim(id, run_id)` | Atomic: verify status is `ready` and unassigned, set `active`, assign, record run_id and branch. Fails if already claimed. |
+| `setStatus(id, status, note)` | Any non-terminal transition. `blocked` requires a note with evidence, completed work, blocker, next action. |
+| `link(id, pr)` | Attach PR to item and item to PR. Sets `in-review`. |
+| `release(id, done\|cancelled\|backlog, note)` | Terminal or unclaim. `done` only from `in-review` and only after task-workflow merge readiness passed. |
+| `inFlight()` | All `active` and `in-review` items plus their branches and PRs. Used before selecting work. |
+| `nextEligible(n, policy)` | `ready` items, none of whose `depends_on` are open, ordered by priority then age, excluding types outside `policy.autonomous.allowed_types`. |
+| `render()` | Regenerate the human view (`policy.backlog.render_file`). No-op for markdown backend. |
+
+## 4. Item content standard (both backends)
+
+Every item has: a one-paragraph Goal, testable Acceptance Criteria as checkboxes, Depends On, Evidence (file paths, line numbers, function names, PR links), Origin (source, created date, originating task or PR). Items without evidence are not `ready`.
+
+## 5. Discipline
+
+- Every piece of identified work gets an item, including small chores and leftovers from merge readiness.
+- IDs are permanent, never reused or renumbered.
+- Claim before branch. A branch without a claimed item is a defect.
+- Record leftovers via `create` with origin pointing at the finishing task or PR.
+- Needs-discussion items expire per `policy.backlog.needs_discussion_expiry_days`, triage cancels them with note `stale`.
+- Staleness review: when asked, or when open `backlog` exceeds `policy.backlog.max_open_backlog`, list oldest items for the human to promote, cancel, or reprioritise.
+
+## 6. Legacy migration
+
+If `<root>/.agents/backlog.md` exists and `<root>/BACKLOG.md` does not, move it. If `policy.yml` says `github-issues` but `BACKLOG.md` still contains hand-written tables and `.planning/backlog-migration.json` is absent, the migration is incomplete: treat backend as `markdown` for this session and report it.

package/skills/backlog-management/backends/github-issues.md

@@ -0,0 +1,37 @@
+# Backend: github-issues
+
+ID = issue number. Labels are the state machine. Closed state carries `done`/`cancelled`.
+
+## Label scheme
+
+`type:*`, `priority:*`, `status:*` (backlog, ready, active, in-review, blocked), `ns:*` (optional namespace), `source:*`, `needs-discussion`, `agent-safe`. Exactly one `type:`, one `priority:`, one `status:` per open issue. `done` = closed completed. `cancelled` = closed not planned.
+
+## Body headings (parse and write exactly)
+
+`## Goal`, `## Acceptance Criteria` (checkboxes), `## Depends On` (`#n` list or `none`), `## Evidence`, `## Origin` (`source:`, `created:`, `run:`, `task:` or `pr:`), optional `## Open Question`, optional `## Blocker` (evidence, completed work, blocker, next action).
+
+## Operations
+
+| Op | Command |
+|---|---|
+| `list` | `gh issue list --state all --limit 500 --json number,title,labels,assignees,state,stateReason,body,createdAt` then filter locally. |
+| `dedupe` | `gh issue list --state all --search "<topic>" --json number,title,state` plus a local title fuzzy match on `list`. |
+| `create` | `gh issue create --title "<title>" --body-file <tmp> --label type:x --label priority:x --label status:backlog --label source:x`. Never pass an ID. |
+| `needsDiscussion` | `create` plus `--label needs-discussion`, body includes `## Open Question`. |
+| `claim` | Read issue. Require `status:ready`, no assignee. Then in one `gh issue edit`: `--add-label status:active --remove-label status:ready --add-assignee @me`. Re-read and verify assignee is you and label flipped, otherwise treat as lost race and abort. Comment `claimed by run <run_id>, branch <branch>`. |
+| `setStatus` | `gh issue edit --add-label status:<new> --remove-label status:<old>`. For `blocked`, also comment with the `## Blocker` block and append it to the body. |
+| `link` | PR body must contain `Closes #<id>`. `gh issue edit --add-label status:in-review --remove-label status:active`. Comment with PR URL. |
+| `release done` | Verify PR merged (`gh pr view --json state`). `gh issue close --reason completed --comment "<note>"`, remove `status:*` labels. |
+| `release cancelled` | `gh issue close --reason "not planned" --comment "<reason>"`. |
+| `release backlog` | Remove assignee, set `status:ready` (if criteria intact) or `status:backlog`, comment why. |
+| `inFlight` | `list` filtered to `status:active` or `status:in-review`, join with `gh pr list --state open --json number,headRefName,body` on `Closes #n`. |
+| `nextEligible` | `list` filtered `status:ready`, `agent-safe`, type in policy, no assignee, all `## Depends On` closed. Sort priority high→low, then createdAt asc. |
+| `render` | `scripts/backlog-render.sh > BACKLOG.md`. Commit only from a scheduled job or as part of a sweep PR, never from a task branch. |
+
+## Labels the migration and triage own
+
+`agent-safe` is set only by triage or a human. It means: criteria testable, no product or structural decision, diff expected under policy limits. The implementer treats absence as "not selectable" even if `status:ready`.
+
+## Failure handling
+
+`gh` auth or rate-limit error → stop the operation, report, do not fall back to editing `BACKLOG.md`.

package/skills/backlog-management/backends/markdown.md

@@ -0,0 +1,34 @@
+# Backend: markdown
+
+`<root>/BACKLOG.md` is the source of truth. Two tables: live and `## Archive`. Same columns.
+
+```markdown
+| ID | Title | Type | Priority | Status | Assignee | Task File | PR | Depends On | Created | Acceptance Criteria Summary | Notes |
+```
+
+`policy.ids.scheme` decides ID format: `numeric` (`001`) or `prefixed` (`LMS-001`, namespaces in `policy.ids.prefixes`). Default numeric.
+
+## Operations
+
+| Op | Mechanics |
+|---|---|
+| `list` | Parse both tables. |
+| `dedupe` | Grep both tables and any `## Needs Discussion` sections, case-insensitive, on title words and Notes. |
+| `create` | `git fetch`, read `origin/main:BACKLOG.md` and every open PR's version (`gh pr list --json headRefName`, `git show origin/<branch>:BACKLOG.md`) if `gh` is available. ID = max across all of them plus one. Append row with `Status: backlog`, `Created: today`. Write the claim and the row in the same commit. |
+| `needsDiscussion` | Append to `## Needs Discussion (<date>)` section at end of file, create the section if the date differs from the last one. Title, 2 to 4 sentence rationale, explicit open question. No ID, no status. |
+| `claim` | Requires ability to commit a one-line change to `main` (bot bypass on `BACKLOG.md` only) or to `.planning/active.json`. Set `Status: active`, `Assignee: <run_id>`, commit `chore(backlog): claim <id>`, push. If push is rejected, pull, re-check the row is still `ready`, retry once, else abort. If no bypass exists, the claim is branch-local and weaker, say so in the run report. |
+| `setStatus` | Edit the row. `blocked` writes the four-part blocker note into Notes. |
+| `link` | Fill `PR` cell, set `in-review`. |
+| `release done` | Row → `done`, `Task File: —`, move to Archive. Happens in the task branch as the last commit before merge, per task-workflow step 9. |
+| `release cancelled` | Row → `cancelled`, reason in Notes, move to Archive. |
+| `inFlight` | Rows with `active` or `in-review`, plus open PRs whose diff touches `BACKLOG.md`. |
+| `nextEligible` | Rows `ready`, no Assignee, `Depends On` all in Archive, ordered priority then Created. |
+| `render` | No-op. |
+
+## Known limits
+
+ID collisions and claims are best-effort. If two branches allocate the same ID, the later merge renumbers and fixes cross-references. Prefer the github-issues backend for repos with more than one concurrent agent.
+
+## Compatibility with the sweep's old sectioned layout
+
+A file organised as `## <Topic>` sections with `done` rows in place is a legacy layout. Read it as one live table across sections. Do not restructure it during normal operations; restructuring is its own backlog item.