@anyberg/agent-conventions 1.0.0

package/skills/tech-debt/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: tech-debt
+description: Identify, categorize, and prioritize technical debt. Trigger with "tech debt", "technical debt audit", "what should we refactor", "code health", or when the user asks about code quality, refactoring priorities, or maintenance backlog.
+---
+
+# Tech Debt Management
+
+Systematically identify, categorize, and prioritize technical debt.
+
+## Categories
+
+| Type | Examples | Risk |
+|------|----------|------|
+| **Code debt** | Duplicated logic, poor abstractions, magic numbers | Bugs, slow development |
+| **Architecture debt** | Monolith that should be split, wrong data store | Scaling limits |
+| **Test debt** | Low coverage, flaky tests, missing integration tests | Regressions ship |
+| **Dependency debt** | Outdated libraries, unmaintained dependencies | Security vulns |
+| **Documentation debt** | Missing runbooks, outdated READMEs, tribal knowledge | Onboarding pain |
+| **Infrastructure debt** | Manual deploys, no monitoring, no IaC | Incidents, slow recovery |
+
+## Prioritization Framework
+
+Score each item on:
+- **Impact**: How much does it slow the team down? (1 = negligible, 5 = severe)
+- **Risk**: What happens if we don't fix it? (1 = harmless, 5 = critical)
+- **Effort**: How hard is the fix? (1 = trivial, 5 = very hard)
+
+Priority = (Impact + Risk) × (6 − Effort)
+
+Score Effort on its raw scale — the `(6 − Effort)` term inverts it so cheap, high-value fixes rank highest. Higher score = higher priority.
+
+**Example:** A flaky test suite (Impact 4, Risk 3, Effort 2) scores `(4 + 3) × (6 − 2) = 28`. A monolith split (Impact 5, Risk 4, Effort 5) scores `(5 + 4) × (6 − 5) = 9` — high value, but its cost pushes it below cheaper wins.
+
+## Output
+
+Produce a prioritized list with estimated effort, business justification for each item, and a phased remediation plan that can be done alongside feature work.
+
+Feed the results into the existing workflow rather than letting them sit in a report:
+
+- Add each item to `BACKLOG.md` as a `refactor` (or matching type) row via the **backlog-management** skill.
+- Promote high-priority items to task files through the **task-workflow** skill before starting work.

package/skills/test-driven-development/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: test-driven-development
+description: Use when implementing any feature or bugfix, before writing implementation code
+---
+
+# Test-Driven Development (TDD)
+
+## Overview
+
+Write the test first. Watch it fail. Write minimal code to pass.
+
+**Core principle:** If you didn't watch the test fail, you don't know if it tests the right thing.
+
+**Scope:** TDD is the *loop* for building one behavior at a time. To decide *which* behaviors deserve tests and *what* coverage to aim for, work out the plan with the **testing-strategy** skill first, then drive each item through the cycle below.
+
+## When to Use
+
+**Always:** new features, bug fixes, refactoring, behavior changes.
+
+**Exceptions (confirm with user):** throwaway prototypes, generated code, configuration files.
+
+## The Iron Law
+
+```
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+```
+
+Write code before the test? Delete it. No exceptions — no keeping it as "reference," no "adapting" it. Delete means delete.
+
+## Red-Green-Refactor
+
+### RED — Write Failing Test
+
+Write one minimal test showing what should happen. Pick the behavior from your test plan — cover business-critical paths, error handling, edge cases, and security boundaries first; skip trivial getters/setters and framework code (see the **testing-strategy** skill).
+
+**Requirements:**
+- Tests one behavior
+- Name describes the behavior
+- Uses real code (no mocks unless unavoidable)
+
+### Verify RED — Watch It Fail
+
+**MANDATORY. Never skip.**
+
+Run the test and confirm:
+- It fails (not errors)
+- Failure message is expected
+- It fails because the feature is missing, not due to typos
+
+Test passes immediately? You're testing existing behavior — fix the test.
+
+### GREEN — Write Minimal Code
+
+Write the simplest code that passes the test. Do not add features, refactor other code, or "improve" beyond what the test requires.
+
+### Verify GREEN — Watch It Pass
+
+**MANDATORY.**
+
+Run the test suite and confirm:
+- The new test passes
+- All other tests still pass
+- Output is clean (no errors or warnings)
+
+Test fails? Fix code, not test. Other tests fail? Fix them now.
+
+### REFACTOR — Clean Up
+
+After green only: remove duplication, improve names, extract helpers. Keep tests green. Do not add behavior.
+
+### Repeat
+
+Write the next failing test for the next behavior.
+
+## Good Tests
+
+| Quality | Good | Bad |
+|---------|------|-----|
+| **Minimal** | One thing. "and" in name? Split it. | `test('validates email and domain and whitespace')` |
+| **Clear** | Name describes the behavior | `test('test1')` |
+| **Shows intent** | Demonstrates desired API | Obscures what code should do |
+
+## Red Flags — Stop and Start Over
+
+- Code written before test
+- Test added after implementation
+- Test passes immediately without explanation
+- Can't explain why the test failed
+- Rationalizing "just this once"
+- "I already manually tested it"
+- "Tests after achieve the same purpose"
+- "Keep as reference" or "adapt existing code"
+- "Already spent X hours, deleting is wasteful"
+- "TDD is dogmatic, I'm being pragmatic"
+- "This is different because..."
+- "It's about spirit not ritual"
+
+**All of these mean: delete the code, start over with TDD.**
+
+## Verification Checklist
+
+Before marking work complete:
+
+- [ ] Every new function/method has a test
+- [ ] Watched each test fail before implementing
+- [ ] Each test failed for expected reason (feature missing, not typo)
+- [ ] Wrote minimal code to pass each test
+- [ ] All tests pass
+- [ ] Output pristine (no errors, warnings)
+- [ ] Tests use real code (mocks only if unavoidable)
+- [ ] Edge cases and errors covered
+
+Can't check all boxes? You skipped TDD. Start over.

package/skills/testing-strategy/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: testing-strategy
+description: Design test strategies and test plans. Trigger with "how should we test", "test strategy for", "write tests for", "test plan", "what tests do we need", or when the user needs help with testing approaches, coverage, or test architecture.
+---
+
+# Testing Strategy
+
+Design effective testing strategies balancing coverage, speed, and maintenance.
+
+## Testing Pyramid
+
+```
+        /  E2E  \         Few, slow, high confidence
+       / Integration \     Some, medium speed
+      /    Unit Tests  \   Many, fast, focused
+```
+
+## Strategy by Component Type
+
+- **API endpoints**: Unit tests for business logic, integration tests for HTTP layer, contract tests for consumers
+- **Data pipelines**: Input validation, transformation correctness, idempotency tests
+- **Frontend**: Component tests, interaction tests, visual regression, accessibility
+- **Infrastructure**: Smoke tests, chaos engineering, load tests
+
+## What to Cover
+
+Focus on: business-critical paths, error handling, edge cases, security boundaries, data integrity.
+
+Skip: trivial getters/setters, framework code, one-off scripts.
+
+## Output
+
+Produce a test plan with: what to test, test type for each area, coverage targets, and example test cases. Identify gaps in existing coverage.
+
+Drive each item in the plan through the **test-driven-development** skill's Red-Green-Refactor loop — the plan decides *what* to test; TDD governs *how* each test gets written.

package/skills/typescript-coding-guidelines/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: typescript-coding-guidelines
+description: Rules for TypeScript and JavaScript code — idioms, type system usage, error handling, naming, imports, and eliminating unnecessary complexity. Use when reading or writing .ts, .tsx, .js, or .jsx files.
+---
+
+# TypeScript & JavaScript Coding Guidelines
+
+Applies to all `.ts`, `.tsx`, `.js`, and `.jsx` files. Builds on the **Universal Code Rules** in `code-standards`; only TypeScript/JavaScript-specific rules are listed here. TypeScript-only rules are marked **[TS]**.
+
+## Type System [TS]
+
+- Use `instanceof` for class-based type narrowing; use discriminated unions with a `kind` or `type` literal field for sum-type narrowing — Enables proper type narrowing for static analysis and prevents fragile duck-typing
+- Use `unknown` instead of `any` — forces explicit narrowing before use, catching errors at compile time rather than runtime
+- Avoid `as` type assertions except when runtime logic guarantees safety and static analysis cannot narrow (e.g., after a literal check or known invariant) — use type guards or discriminated unions instead; document the safety reasoning when `as` is genuinely necessary
+- Use `satisfies` to validate an expression against a type without widening the inferred type — preserves literal types while catching structural mismatches at the point of definition
+- Use `as const` assertions for readonly literal tuples and objects — prevents widening to mutable primitive types
+- Use `Literal` union types for fixed string/number value sets in parameters, fields, and return types — Makes valid values explicit in signatures and enables static catch of invalid values
+- Create type aliases for complex types (3+ union branches, object types used 2+ times) — reduces duplication and improves readability; skip aliases for simple one-off internal types
+- Use `interface` for extensible object shapes (declaration merging, class `implements`); use `type` for unions, intersections, mapped types, and aliases — matches the intended extension model of each construct
+- Use `readonly` on arrays (`readonly T[]`) and object properties that must not be mutated — makes immutability intent explicit and catches accidental writes at compile time
+- Use `never` to enforce exhaustive checks in `switch`/`if`-else chains over discriminated unions — a compile-time guarantee that all cases are handled
+- Remove `| undefined` from fields when values are guaranteed to be initialized — prevents false optionality and unnecessary non-null checks
+- Avoid `@ts-ignore`; use `@ts-expect-error` only when unavoidable, always with a comment explaining why the suppression is safe and what error it hides
+- Fix type errors properly — use type annotations, narrowing, or `as` with explanatory comments — prevents masking real type errors that indicate structural problems
+- **`strict: true` is non-negotiable** — it enables `noImplicitAny`, `strictNullChecks`, `strictFunctionTypes`, and related checks; never disable it project-wide
+
+## Error Handling
+
+- Use domain-specific error classes extending `Error` — set `this.name` in the constructor for clear stack traces and `instanceof` checks
+- Use the `cause` option when re-throwing: `throw new AppError("message", { cause: err })` — preserves the original stack trace and error chain
+- Avoid swallowing errors in `.catch(() => {})` — at minimum log them with enough context to diagnose the issue later
+
+## Naming
+
+- Use `camelCase` for variables, functions, and methods; `PascalCase` for classes, interfaces, types, and enums; `UPPER_CASE` for module-level constants (`const MAX_RETRIES = 3`)
+- Prefix internal module constants with `_` when they are not part of the public export surface (`const _CACHE_TTL_MS = 60_000`)
+
+## Imports
+
+- Prefer named exports over default exports — named exports improve refactoring support, IDE discoverability, and make re-exporting explicit
+- Use barrel files (`index.ts`) to define the public API of a module — export only what consumers need; do not re-export internal implementation details
+- Avoid circular imports — if two modules depend on each other, extract shared logic into a third module
+- Group imports consistently: external packages first, then internal modules (`@/`, `~/`, relative), separated by a blank line; enforce with ESLint's `import/order` rule or Biome
+
+## Testing
+
+- Prefer `vi.fn()` / `jest.fn()` stubs over full module mocks when testing units in isolation — avoids over-specification and keeps tests resilient to refactoring
+
+## General
+
+- Use `pnpm` by default unless `package.json` scripts or project docs specify `npm` or `yarn`
+- Run `eslint` and `prettier` (or `biome`) before committing — enforce via pre-commit hooks or CI; never disable rules project-wide without a documented reason
+- Prefer `const` over `let`; never use `var` — `const` communicates immutability of the binding and prevents accidental reassignment
+- Use optional chaining (`?.`) and nullish coalescing (`??`) instead of manual null guards — more concise and avoids incorrectly coalescing on `0`, `""`, or `false`
+- Use `structuredClone()` for deep cloning plain objects instead of `JSON.parse(JSON.stringify(...))` — handles more types correctly and is faster in modern runtimes

package/src/plan.js

@@ -0,0 +1,116 @@
+/**
+ * Build the complete set of writes before performing any of them.
+ *
+ * Planning is separate from writing so the disclosure screen shows exactly what
+ * `--dry-run` would do and exactly what a confirmed run will do — the same
+ * structure, rendered once and executed once. A preview that is computed
+ * differently from the action it previews is worse than no preview.
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { instructionTargets, receiptPath, skillTargets } from './targets.js'
+import { planInstructionWrite } from './write.js'
+
+/** Skill directories shipped in this package. */
+export function bundledSkills(packageRoot) {
+  const dir = path.join(packageRoot, 'skills')
+  return fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && fs.existsSync(path.join(dir, e.name, 'SKILL.md')))
+    .map((e) => ({ name: e.name, dir: path.join(dir, e.name) }))
+    .sort((a, b) => a.name.localeCompare(b.name))
+}
+
+export function buildPlan({
+  packageRoot,
+  scope,
+  components,
+  agents,
+  home,
+  cwd,
+  copy = false,
+}) {
+  const plan = { scope, components, mode: copy ? 'copy' : 'symlink', skills: null, instructions: [] }
+
+  if (components.includes('skills')) {
+    const targets = skillTargets(scope, { home, cwd })
+    const skills = bundledSkills(packageRoot)
+    // Claude Code is the only agent needing a link; skip it if unselected.
+    const links = targets.links.filter((l) => agents.includes(l.agent))
+    plan.skills = {
+      canonical: targets.canonical,
+      canonicalReadBy: targets.canonicalReadBy,
+      names: skills.map((s) => s.name),
+      sources: skills,
+      links,
+    }
+  }
+
+  if (components.includes('instructions')) {
+    // Global only. A project's own AGENTS.md belongs to the project, and
+    // overwriting it with ours is never the right default.
+    if (scope !== 'global') {
+      plan.instructionsSkipped = 'instructions install at global scope only'
+    } else {
+      plan.instructions = instructionTargets({ home })
+        .filter((t) => agents.includes(t.agent))
+        .map((t) => ({ ...planInstructionWrite(t.file), label: t.label, agent: t.agent }))
+    }
+  }
+
+  plan.receipt = receiptPath(scope, { home, cwd })
+  return plan
+}
+
+/** Render the plan as the disclosure the user confirms against. */
+export function renderDisclosure(plan, { packageVersion }) {
+  const lines = []
+  const where = plan.scope === 'global' ? 'GLOBAL' : 'PROJECT'
+  lines.push(`agent-conventions ${packageVersion} — ${where} scope`)
+  lines.push('')
+
+  if (plan.scope === 'global') {
+    lines.push('These paths live outside your project and affect every repo on this machine.')
+    lines.push('')
+  }
+
+  if (plan.skills) {
+    lines.push(`  ${plan.skills.canonical}`)
+    lines.push(`      ${plan.skills.names.length} skills — read by ${plan.skills.canonicalReadBy.join(', ')}`)
+    for (const link of plan.skills.links) {
+      lines.push(`  ${link.dir}`)
+      lines.push(`      ${plan.mode} → the directory above (${link.label} does not read .agents/skills)`)
+    }
+    lines.push('')
+  }
+
+  if (plan.instructionsSkipped) {
+    lines.push(`  instructions: skipped — ${plan.instructionsSkipped}`)
+    lines.push('')
+  }
+
+  if (plan.instructions.length) {
+    for (const item of plan.instructions) {
+      lines.push(`  ${item.file}`)
+      lines.push(`      ${item.detail}`)
+    }
+    lines.push('')
+    lines.push('  Content is wrapped in <!-- BEGIN/END aanyberg/agent-conventions --> markers.')
+    lines.push('  Everything outside the markers is preserved; uninstall removes only the block.')
+    lines.push('')
+  }
+
+  const refusals = plan.instructions.filter((i) => i.action.startsWith('refuse'))
+  if (refusals.length) {
+    lines.push('  REFUSED without --replace-symlinks:')
+    for (const r of refusals) {
+      lines.push(`    ${r.file} is a ${r.detail}`)
+    }
+    lines.push('    Writing through a symlink would modify the file it points at.')
+    lines.push('')
+  }
+
+  lines.push(`  receipt: ${plan.receipt}`)
+  return lines.join('\n')
+}

package/src/targets.js

@@ -0,0 +1,95 @@
+/**
+ * The one place that knows where anything goes.
+ *
+ * Two facts keep this table small, and both were verified by running the
+ * ecosystem's own installer rather than read off documentation:
+ *
+ *  1. `.agents/skills/` is universal. Codex, GitHub Copilot, OpenCode, Cursor,
+ *     Gemini CLI, Cline, Zed and Amp all read it. Claude Code is the sole
+ *     holdout, so it gets a symlink into the same files rather than a copy.
+ *  2. That holds at BOTH scopes. `~/.agents/skills/` is universal too, so the
+ *     global case needs no per-agent table either.
+ *
+ * Instructions are the opposite: every tool keeps global guidance in its own
+ * directory, and two of them expect a different filename there. That is why the
+ * instruction table has real entries while the skills one has two.
+ */
+
+import os from 'node:os'
+import path from 'node:path'
+
+/** Skills: one real directory, plus the agents that need a link into it. */
+export function skillTargets(scope, { home = os.homedir(), cwd = process.cwd() } = {}) {
+  const root = scope === 'global' ? home : cwd
+  return {
+    // The real files. Everything else points here.
+    canonical: path.join(root, '.agents', 'skills'),
+    canonicalReadBy: [
+      'Codex', 'GitHub Copilot', 'OpenCode', 'Cursor',
+      'Gemini CLI', 'Cline', 'Zed', 'Amp',
+    ],
+    // Agents that do not read `.agents/skills` and need their own path.
+    links: [{ agent: 'claude-code', label: 'Claude Code', dir: path.join(root, '.claude', 'skills') }],
+  }
+}
+
+/**
+ * Instructions: global only, and never the project's own AGENTS.md.
+ *
+ * A consumer's project-root AGENTS.md belongs to them. Writing it would clobber
+ * their content with ours, so this installer does not offer to.
+ */
+export const INSTRUCTION_TARGETS = [
+  { agent: 'claude-code', label: 'Claude Code', rel: ['.claude', 'CLAUDE.md'] },
+  { agent: 'github-copilot', label: 'GitHub Copilot', rel: ['.copilot', 'copilot-instructions.md'] },
+  { agent: 'codex', label: 'Codex', rel: ['.codex', 'AGENTS.md'] },
+  { agent: 'gemini-cli', label: 'Gemini CLI', rel: ['.gemini', 'GEMINI.md'] },
+]
+
+export function instructionTargets({ home = os.homedir() } = {}) {
+  return INSTRUCTION_TARGETS.map((t) => ({ ...t, file: path.join(home, ...t.rel) }))
+}
+
+/** Agents selectable at global scope. Project scope needs no selection: one write covers all. */
+export const SELECTABLE_AGENTS = [
+  { id: 'claude-code', label: 'Claude Code' },
+  { id: 'codex', label: 'Codex' },
+  { id: 'github-copilot', label: 'GitHub Copilot' },
+  { id: 'opencode', label: 'OpenCode' },
+  { id: 'cursor', label: 'Cursor' },
+  { id: 'gemini-cli', label: 'Gemini CLI' },
+]
+
+/** Where the receipt lives, so update and uninstall touch only what we wrote. */
+export function receiptPath(scope, { home = os.homedir(), cwd = process.cwd() } = {}) {
+  const root = scope === 'global' ? home : cwd
+  return path.join(root, '.agent-conventions.json')
+}
+
+export const MARKER_BEGIN = '<!-- BEGIN aanyberg/agent-conventions -->'
+export const MARKER_END = '<!-- END aanyberg/agent-conventions -->'
+
+/**
+ * Interpret an answer to the global agent prompt.
+ *
+ * Pure so it can be tested without a terminal: the prompt itself needs a TTY,
+ * but the rule for turning "1 3", "a" or "" into a set of agents is the part
+ * with edge cases worth pinning down.
+ *
+ * An answer that matches nothing is treated as a typo and falls back to the
+ * preset — installing for no agents at all is never what someone meant.
+ */
+export function parseAgentSelection(answer, { preset }) {
+  const all = SELECTABLE_AGENTS.map((a) => a.id)
+  const text = String(answer ?? '').trim()
+  if (text === '') return { agents: preset, reason: 'preset' }
+  if (/^(a|all)$/i.test(text)) return { agents: all, reason: 'all' }
+  const chosen = text
+    .split(/[,\s]+/)
+    .filter(Boolean)
+    .map((n) => SELECTABLE_AGENTS[Number(n) - 1])
+    .filter(Boolean)
+    .map((a) => a.id)
+  const unique = [...new Set(chosen)]
+  return unique.length ? { agents: unique, reason: 'chosen' } : { agents: preset, reason: 'unrecognised' }
+}

package/src/write.js

@@ -0,0 +1,184 @@
+/**
+ * Everything that touches the filesystem, and the rules that keep it safe.
+ *
+ * Two invariants matter more than anything else here:
+ *
+ *  1. **Never write through a symlink.** The previous README told people to run
+ *     `ln -s /path/to/agent-conventions/AGENTS.md ~/.claude/CLAUDE.md`. Opening
+ *     that path in append mode writes *into their clone of this repository* and
+ *     corrupts the source of truth, which then gets committed. Every write
+ *     lstats first and refuses to follow a link.
+ *
+ *  2. **Never remove a file we did not write.** Uninstall works from the
+ *     receipt, not from a guess about what an install would have produced.
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { MARKER_BEGIN, MARKER_END } from './targets.js'
+
+/** What is actually at this path? Uses lstat, so a symlink reports as one. */
+export function classify(file) {
+  let st
+  try {
+    st = fs.lstatSync(file)
+  } catch (err) {
+    if (err.code === 'ENOENT') return { kind: 'absent' }
+    throw err
+  }
+  if (st.isSymbolicLink()) {
+    let resolved = null
+    try {
+      resolved = fs.realpathSync(file)
+    } catch {
+      resolved = fs.readlinkSync(file) // dangling link — report where it pointed
+    }
+    return { kind: 'symlink', resolved }
+  }
+  if (st.isDirectory()) return { kind: 'directory' }
+  return { kind: 'file' }
+}
+
+/** Wrap content in the markers that make it removable later. */
+export function renderBlock(content) {
+  return `${MARKER_BEGIN}\n${content.trimEnd()}\n${MARKER_END}\n`
+}
+
+export function hasBlock(text) {
+  return text.includes(MARKER_BEGIN) && text.includes(MARKER_END)
+}
+
+/**
+ * Insert or replace our block, preserving everything outside it.
+ *
+ * Deliberately string-based rather than regex: the content can contain any
+ * markdown, and a greedy pattern over user text is the kind of thing that
+ * silently eats a paragraph.
+ */
+export function upsertBlock(existing, content) {
+  const block = renderBlock(content)
+  if (!hasBlock(existing)) {
+    const sep = existing.length === 0 || existing.endsWith('\n\n') ? '' : existing.endsWith('\n') ? '\n' : '\n\n'
+    return existing + sep + block
+  }
+  const start = existing.indexOf(MARKER_BEGIN)
+  const end = existing.indexOf(MARKER_END) + MARKER_END.length
+  if (end < start) throw new Error('markers are out of order; refusing to edit')
+  const trailing = existing.slice(end).replace(/^\n/, '')
+  return existing.slice(0, start) + block + trailing
+}
+
+/**
+ * Strip our block and leave the rest untouched.
+ *
+ * `upsertBlock` inserts a blank-line separator before the block when appending
+ * to a file that ends in a single newline, so removal has to take that
+ * separator back out. Without this the file gains one blank line per
+ * install/uninstall cycle — the round-trip tests below are what caught it.
+ */
+export function removeBlock(existing) {
+  if (!hasBlock(existing)) return existing
+  const start = existing.indexOf(MARKER_BEGIN)
+  const end = existing.indexOf(MARKER_END) + MARKER_END.length
+  const before = existing.slice(0, start)
+  const after = existing.slice(end).replace(/^\n/, '')
+  // Only collapse when the block sat at the end; mid-file, the surrounding
+  // blank lines are the user's own and must survive untouched.
+  const restored = after === '' ? before.replace(/\n\n$/, '\n') : before + after
+  return restored.trim().length === 0 ? '' : restored
+}
+
+/**
+ * Decide what an instruction write would do, without doing it.
+ *
+ * Returns an `action` the caller renders in the disclosure screen, so the user
+ * sees "replace symlink" before it happens rather than after.
+ */
+export function planInstructionWrite(file) {
+  const at = classify(file)
+  if (at.kind === 'absent') return { file, action: 'create', detail: 'creates file' }
+  if (at.kind === 'directory') return { file, action: 'refuse', detail: 'a directory exists here' }
+  if (at.kind === 'symlink') {
+    return {
+      file,
+      action: 'refuse-symlink',
+      detail: `symlink → ${at.resolved}`,
+      resolved: at.resolved,
+    }
+  }
+  const text = fs.readFileSync(file, 'utf8')
+  const kept = removeBlock(text).split('\n').filter(Boolean).length
+  return {
+    file,
+    action: hasBlock(text) ? 'update' : 'append',
+    detail: hasBlock(text) ? 'updates existing block' : `appends block (${kept} existing lines kept)`,
+  }
+}
+
+/** Apply an instruction write. Refuses anything the plan marked as refusable. */
+export function applyInstructionWrite(plan, content, { replaceSymlinks = false } = {}) {
+  if (plan.action === 'refuse') {
+    throw new Error(`${plan.file}: ${plan.detail}`)
+  }
+  if (plan.action === 'refuse-symlink' && !replaceSymlinks) {
+    throw new Error(
+      `${plan.file} is a symlink → ${plan.resolved}. Writing through it would modify ` +
+        `that file. Re-run with --replace-symlinks to replace the link with a real file.`,
+    )
+  }
+  fs.mkdirSync(path.dirname(plan.file), { recursive: true })
+  if (plan.action === 'refuse-symlink') {
+    fs.unlinkSync(plan.file) // replace the link itself, never follow it
+    fs.writeFileSync(plan.file, renderBlock(content), 'utf8')
+    return { ...plan, applied: 'replaced-symlink' }
+  }
+  const existing = plan.action === 'create' ? '' : fs.readFileSync(plan.file, 'utf8')
+  fs.writeFileSync(plan.file, upsertBlock(existing, content), 'utf8')
+  return { ...plan, applied: plan.action }
+}
+
+/** Copy a skill directory, replacing any previous copy of the same skill. */
+export function installSkill(sourceDir, destDir) {
+  fs.rmSync(destDir, { recursive: true, force: true })
+  fs.mkdirSync(path.dirname(destDir), { recursive: true })
+  fs.cpSync(sourceDir, destDir, { recursive: true })
+}
+
+/**
+ * Link a skill into an agent-specific directory.
+ *
+ * Relative targets, so a committed project tree still resolves after a clone to
+ * a different path. Falls back to a copy where symlinks are unavailable, which
+ * is Windows without Developer Mode more often than anything else.
+ */
+export function linkSkill(canonicalDir, linkPath, { copy = false } = {}) {
+  fs.rmSync(linkPath, { recursive: true, force: true })
+  fs.mkdirSync(path.dirname(linkPath), { recursive: true })
+  if (copy) {
+    fs.cpSync(canonicalDir, linkPath, { recursive: true })
+    return 'copy'
+  }
+  const rel = path.relative(path.dirname(linkPath), canonicalDir)
+  try {
+    fs.symlinkSync(rel, linkPath, 'dir')
+    return 'symlink'
+  } catch (err) {
+    if (err.code !== 'EPERM' && err.code !== 'EACCES') throw err
+    fs.cpSync(canonicalDir, linkPath, { recursive: true })
+    return 'copy'
+  }
+}
+
+export function readReceipt(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'))
+  } catch (err) {
+    if (err.code === 'ENOENT') return null
+    throw err
+  }
+}
+
+export function writeReceipt(file, receipt) {
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, JSON.stringify(receipt, null, 2) + '\n', 'utf8')
+}