@wipcomputer/wip-ai-devops-toolbox 1.9.55 → 1.9.57

package/.worktrees/wip-ai-devops-toolbox-private--cc-mini--dot-worktrees/tools/wip-release/mcp-server.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+// wip-release/mcp-server.mjs
+// MCP server exposing release pipeline as tools.
+// Wraps core.mjs. Registered via .mcp.json.
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import {
+  release, detectCurrentVersion, bumpSemver, buildReleaseNotes,
+} from './core.mjs';
+
+const server = new Server(
+  { name: 'wip-release', version: '1.3.0' },
+  { capabilities: { tools: {} } }
+);
+
+// ── Tool Definitions ──
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: 'release',
+      description: 'Run the full release pipeline. Bumps version, updates changelog + SKILL.md, commits, tags, publishes to npm + GitHub. Must be run from repo root or provide repoPath.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          repoPath: { type: 'string', description: 'Absolute path to the repo. Defaults to cwd.' },
+          level: { type: 'string', enum: ['patch', 'minor', 'major'], description: 'Semver bump level' },
+          notes: { type: 'string', description: 'Changelog entry and release notes summary' },
+          dryRun: { type: 'boolean', description: 'Preview only, no changes', default: false },
+          noPublish: { type: 'boolean', description: 'Bump + tag only, skip npm/GitHub publish', default: false },
+          skipProductCheck: { type: 'boolean', description: 'Skip product doc freshness check', default: false },
+          skipTechDocsCheck: { type: 'boolean', description: 'Skip technical docs freshness check', default: false },
+          skipCoverageCheck: { type: 'boolean', description: 'Skip interface coverage table check', default: false },
+        },
+        required: ['level', 'notes'],
+      },
+    },
+    {
+      name: 'release_status',
+      description: 'Check current version and what the next version would be for a given bump level.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          repoPath: { type: 'string', description: 'Absolute path to the repo. Defaults to cwd.' },
+          level: { type: 'string', enum: ['patch', 'minor', 'major'], description: 'Semver bump level to preview' },
+        },
+        required: ['level'],
+      },
+    },
+  ],
+}));
+
+// ── Tool Handlers ──
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const { name, arguments: args } = req.params;
+
+  if (name === 'release') {
+    try {
+      const result = await release({
+        repoPath: args.repoPath || process.cwd(),
+        level: args.level,
+        notes: args.notes,
+        dryRun: args.dryRun || false,
+        notesSource: 'flag', // MCP always passes notes directly
+        noPublish: args.noPublish || false,
+        skipProductCheck: args.skipProductCheck || false,
+        skipTechDocsCheck: args.skipTechDocsCheck || false,
+        skipCoverageCheck: args.skipCoverageCheck || false,
+      });
+      return {
+        content: [{
+          type: 'text',
+          text: `Release complete: ${result.currentVersion} -> ${result.newVersion}${result.dryRun ? ' (dry run)' : ''}`,
+        }],
+      };
+    } catch (err) {
+      return {
+        content: [{ type: 'text', text: `Release failed: ${err.message}` }],
+        isError: true,
+      };
+    }
+  }
+
+  if (name === 'release_status') {
+    try {
+      const repoPath = args.repoPath || process.cwd();
+      const current = detectCurrentVersion(repoPath);
+      const next = bumpSemver(current, args.level);
+      return {
+        content: [{
+          type: 'text',
+          text: `Current: ${current}\nNext (${args.level}): ${next}`,
+        }],
+      };
+    } catch (err) {
+      return {
+        content: [{ type: 'text', text: `Status check failed: ${err.message}` }],
+        isError: true,
+      };
+    }
+  }
+
+  return {
+    content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+    isError: true,
+  };
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/.worktrees/wip-ai-devops-toolbox-private--cc-mini--dot-worktrees/tools/wip-release/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@wipcomputer/wip-release",
+  "version": "1.9.15",
+  "type": "module",
+  "description": "One-command release pipeline. Bumps version, updates changelog + SKILL.md, publishes to npm + GitHub.",
+  "main": "core.mjs",
+  "bin": {
+    "wip-release": "cli.js"
+  },
+  "exports": {
+    ".": "./core.mjs",
+    "./cli": "./cli.js"
+  },
+  "scripts": {
+    "test": "node cli.js --help"
+  },
+  "keywords": [
+    "release",
+    "version",
+    "publish",
+    "npm",
+    "agent-native",
+    "sensor",
+    "actuator"
+  ],
+  "author": "Parker Todd Brooks",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wipcomputer/wip-release.git"
+  },
+  "homepage": "https://github.com/wipcomputer/wip-ai-devops-toolbox",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  }
+}

package/.worktrees/wip-ai-devops-toolbox-private--cc-mini--dot-worktrees/tools/wip-repo-init/README.md

@@ -0,0 +1,38 @@
+###### WIP Computer
+
+# Repo Init
+
+Scaffold the standard `ai/` directory in any repo. Plans, notes, ideas, dev updates, todos. One command.
+
+## What it does
+
+- **New repo:** Creates the full `ai/` directory structure
+- **Existing repo:** Moves old `ai/` contents to `ai/_sort/ai_old/` so you can sort at your own pace
+- Nothing is deleted
+
+## The `ai/` directory
+
+```
+ai/
+  plan/              architecture plans, roadmaps
+  dev-updates/       what was built, session logs
+  todos/
+    PUNCHLIST.md     blockers to ship
+    inboxes/         per-agent action items
+  notes/             research, references, raw conversation logs
+```
+
+The `ai/` folder is the development process. It is not part of the published product. Public repos exclude it via deploy-public.sh.
+
+## Usage
+
+```bash
+node tools/wip-repo-init/init.mjs /path/to/repo
+```
+
+## Interfaces
+
+- **CLI**: Run from terminal
+- **Skill**: SKILL.md for agent instructions
+
+## Part of [AI DevOps Toolbox](https://github.com/wipcomputer/wip-ai-devops-toolbox)

package/.worktrees/wip-ai-devops-toolbox-private--cc-mini--dot-worktrees/tools/wip-repo-init/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: wip-repo-init
+description: Scaffold the standard ai/ directory structure in any repo.
+license: MIT
+interface: [cli, skill]
+metadata:
+  display-name: "Repo Init"
+  version: "1.0.0"
+  homepage: "https://github.com/wipcomputer/wip-ai-devops-toolbox"
+  author: "Parker Todd Brooks"
+  category: repo-management
+  capabilities:
+    - scaffold-ai-dir
+    - template-copy
+  requires:
+    bins: [node]
+  openclaw:
+    requires:
+      bins: [node]
+    install:
+      - id: node
+        kind: node
+        package: "@wipcomputer/wip-repo-init"
+        bins: [wip-repo-init]
+        label: "Install via npm"
+    emoji: "📁"
+compatibility: Requires node. Node.js 18+.
+---
+
+# Repo Init
+
+Scaffolds the standard `ai/` directory structure in any repo.
+
+## Commands
+
+```
+wip-repo-init /path/to/repo              # scaffold ai/ in a repo
+wip-repo-init /path/to/repo --dry-run    # preview without changes
+wip-repo-init /path/to/repo --yes        # skip confirmation prompt
+```
+
+## What happens
+
+**New repo (no ai/ folder):** Creates the full standard structure with all READMEs explaining what goes where.
+
+**Existing repo (ai/ folder exists):** Shows you what will happen and asks for confirmation. If you say yes:
+1. Moves your current `ai/` contents to `ai/_sort/ai_old/`
+2. Scaffolds the new standard structure
+3. You sort files from `ai_old/` into the new structure at your own pace
+
+Nothing is deleted. Your old files are all in `ai/_sort/ai_old/`.
+
+## The standard ai/ structure
+
+```
+ai/
+  read-me-first.md          <- explains everything, links to all sections
+  _sort/                    <- holding pen for files that need sorting
+  _trash/                   <- archive (never delete, move here)
+  dev-updates/              <- engineering changelog, auto-detected by wip-release
+  product/
+    readme-first-product.md <- the product bible
+    notes/                  <- freeform notes, research
+    plans-prds/             <- plans with lifecycle stages
+      roadmap.md            <- prioritized roadmap
+      current/              <- plans being built now
+      upcoming/             <- plans that are next
+      archive-complete/     <- plans that shipped
+      todos/                <- per-agent todo files
+    product-ideas/          <- ideas that aren't plans yet
+```
+
+Every folder has a `_trash/` subfolder. Every section has a README explaining what it is, what goes in it, and how to maintain it.
+
+## Interfaces
+
+CLI, Skill

package/.worktrees/wip-ai-devops-toolbox-private--cc-mini--dot-worktrees/tools/wip-repo-init/init.mjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+// wip-repo-init: scaffold the standard ai/ directory structure in any repo.
+//
+// New repo (no ai/ folder):
+//   Copies the template as-is.
+//
+// Existing repo (ai/ folder exists):
+//   1. Creates the new ai/ structure
+//   2. Moves old ai/ contents into ai/_sort/ai_old/
+//   3. You sort from there at your own pace.
+
+import { existsSync, mkdirSync, cpSync, renameSync, readdirSync, statSync, readFileSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createInterface } from 'node:readline';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+if (process.argv.includes('--version') || process.argv.includes('-v')) {
+  const pkg = JSON.parse(readFileSync(join(__dirname, 'package.json'), 'utf8'));
+  console.log(pkg.version);
+  process.exit(0);
+}
+const TEMPLATE = join(__dirname, 'templates');
+
+const targetRepo = resolve(process.argv[2] || process.cwd());
+const aiDir = join(targetRepo, 'ai');
+const dryRun = process.argv.includes('--dry-run');
+
+const forceYes = process.argv.includes('--yes') || process.argv.includes('-y');
+
+function log(msg) { console.log(`  ${msg}`); }
+function ok(msg) { console.log(`  ✓ ${msg}`); }
+function skip(msg) { console.log(`  - ${msg}`); }
+
+async function confirm(question) {
+  if (forceYes) return true;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => {
+    rl.question(`  ${question} (y/N) `, answer => {
+      rl.close();
+      resolve(answer.trim().toLowerCase() === 'y');
+    });
+  });
+}
+
+// Recursively copy template, skipping files that already exist
+function scaffoldDir(src, dest) {
+  if (!existsSync(dest)) {
+    if (!dryRun) mkdirSync(dest, { recursive: true });
+    ok(`Created ${dest.replace(targetRepo + '/', '')}`);
+  }
+
+  for (const entry of readdirSync(src)) {
+    if (entry === '.DS_Store') continue;
+    const srcPath = join(src, entry);
+    const destPath = join(dest, entry);
+    const stat = statSync(srcPath);
+
+    if (stat.isDirectory()) {
+      scaffoldDir(srcPath, destPath);
+    } else {
+      if (existsSync(destPath)) {
+        skip(`${destPath.replace(targetRepo + '/', '')} already exists`);
+      } else {
+        if (!dryRun) cpSync(srcPath, destPath);
+        ok(`${destPath.replace(targetRepo + '/', '')}`);
+      }
+    }
+  }
+}
+
+console.log('');
+console.log(`  wip-repo-init${dryRun ? ' (dry run)' : ''}`);
+console.log(`  Target: ${targetRepo}`);
+console.log(`  ${'─'.repeat(40)}`);
+
+if (!existsSync(targetRepo)) {
+  console.log(`  ✗ Target directory does not exist: ${targetRepo}`);
+  process.exit(1);
+}
+
+if (existsSync(aiDir)) {
+  // Existing ai/ folder: explain what will happen, then confirm
+  log('Found existing ai/ folder.');
+  console.log('');
+  log('Here\'s what will happen:');
+  log('  1. Your current ai/ contents will be moved to ai/_sort/ai_old/');
+  log('  2. The standard ai/ structure will be scaffolded');
+  log('  3. You can sort files from ai_old/ into the new structure at your own pace');
+  console.log('');
+  log('Nothing is deleted. Your old files will all be in ai/_sort/ai_old/.');
+  console.log('');
+
+  const sortDir = join(aiDir, '_sort');
+  const aiOldDir = join(sortDir, 'ai_old');
+
+  if (existsSync(aiOldDir)) {
+    console.log(`  ✗ ai/_sort/ai_old/ already exists. A previous init was run but not sorted yet.`);
+    console.log(`    Sort the files in ai/_sort/ai_old/ first, then run again.`);
+    process.exit(1);
+  }
+
+  if (dryRun) {
+    log('[dry run] Would move old ai/ contents to ai/_sort/ai_old/');
+    log('[dry run] Would scaffold new ai/ structure:');
+    console.log('');
+    scaffoldDir(TEMPLATE, aiDir);
+    console.log(`\n  ${'─'.repeat(40)}`);
+    console.log('  Dry run complete. No changes made.\n');
+    process.exit(0);
+  }
+
+  const proceed = await confirm('Proceed?');
+  if (!proceed) {
+    console.log('  Cancelled.\n');
+    process.exit(0);
+  }
+
+  console.log('');
+  const tmpOld = join(targetRepo, '_ai_old_tmp');
+  renameSync(aiDir, tmpOld);
+  ok('Moved old ai/ to temporary location');
+
+  scaffoldDir(TEMPLATE, aiDir);
+
+  mkdirSync(join(aiDir, '_sort'), { recursive: true });
+  renameSync(tmpOld, aiOldDir);
+  ok('Moved old ai/ contents to ai/_sort/ai_old/');
+} else {
+  // No ai/ folder: scaffold from scratch
+  log('No existing ai/ folder. Scaffolding from template.');
+  console.log('');
+  scaffoldDir(TEMPLATE, aiDir);
+}
+
+console.log(`  ${'─'.repeat(40)}`);
+if (dryRun) {
+  console.log('  Dry run complete. No changes made.');
+} else {
+  ok('Done.');
+  if (existsSync(join(aiDir, '_sort', 'ai_old'))) {
+    console.log('');
+    log('Your old ai/ contents are in ai/_sort/ai_old/');
+    log('Sort them into the new structure at your own pace.');
+  }
+}
+console.log('');

package/.worktrees/wip-ai-devops-toolbox-private--cc-mini--dot-worktrees/tools/wip-repo-init/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@wipcomputer/wip-repo-init",
+  "version": "1.9.26",
+  "description": "Scaffold the standard ai/ directory structure in any repo",
+  "type": "module",
+  "bin": {
+    "wip-repo-init": "init.mjs"
+  },
+  "license": "MIT",
+  "author": "WIP Computer"
+}

package/.worktrees/wip-ai-devops-toolbox-private--cc-mini--dot-worktrees/tools/wip-repo-init/templates/_sort/README.md

@@ -0,0 +1,15 @@
+# _sort/
+
+The holding pen. Files that need to be looked at and filed somewhere.
+
+## What Goes Here
+
+- iCloud duplicates or randomly placed files that need sorting
+- Files you're not sure where to put yet
+- Anything that needs a human to look at it and decide where it belongs
+
+## Rules
+
+- **Not trash.** `_sort/` is for files you want to review. `_trash/` is for files you're done with.
+- **Don't let it pile up.** Check this folder periodically. File things or trash them.
+- **Agents:** If you don't know where a file goes, put it in `_sort/`. A human will sort it later.

package/.worktrees/wip-ai-devops-toolbox-private--cc-mini--dot-worktrees/tools/wip-repo-init/templates/_trash/README.md

@@ -0,0 +1,16 @@
+# _trash/
+
+The archive. Files that are done, replaced, or consumed. Never delete anything. Move it here.
+
+## What Goes Here
+
+- Superseded plans (replaced by a newer version)
+- Consumed release notes (already used by `wip-release`)
+- Abandoned drafts
+- Anything you're done with but might need to reference later
+
+## Rules
+
+- **This is not garbage.** It's the archive. Everything in git history is recoverable, but `_trash/` keeps things findable without digging through commits.
+- **Subfolders have their own `_trash/`.** Use the nearest one. `dev-updates/_trash/` for old dev updates, `product/notes/_trash/` for old notes, etc.
+- **Never delete files from the repo.** Move them to `_trash/` instead.

package/.worktrees/wip-ai-devops-toolbox-private--cc-mini--dot-worktrees/tools/wip-repo-init/templates/dev-updates/README.md

@@ -0,0 +1,50 @@
+# dev-updates/
+
+One file per significant change. Written as you work, auto-detected by `wip-release`.
+
+## What This Folder Is
+
+Dev updates are the engineering changelog. Every time you do significant work (ship a feature, fix a bug, change architecture), write a dev update. `wip-release` picks up today's dev updates and uses them as release notes.
+
+This is not a place for plans or ideas. It's a record of what was built and why.
+
+## Naming Convention
+
+```
+YYYY-MM-DD--HH-MM--agent--description.md
+```
+
+Examples:
+- `2026-03-11--09-30--cc-mini--fix-hook-duplicates.md`
+- `2026-03-10--14-00--lesa-mini--add-voice-call-support.md`
+
+## File Format
+
+```markdown
+# Short title of what changed
+
+**Date:** YYYY-MM-DD HH:MM TZ
+**Author:** Agent Name (agent-id)
+
+## Problem
+
+What was broken or missing.
+
+## Fix / What Changed
+
+What you did and why.
+
+## Files changed
+
+- `path/to/file.js` ... what changed in it
+
+Closes #issue-number (if applicable)
+```
+
+## Rules
+
+- **Write them as you work.** Don't batch them at the end. Each significant change gets its own file.
+- **One file per change.** Not one file per day. If you fix two unrelated bugs, write two files.
+- **Include the "why."** "Fixed X" is a commit message. A dev update explains why it was broken and why the fix works.
+- **Reference issues.** If there's a GitHub issue, add `Closes #N` at the bottom.
+- **Consumed files go to `_trash/`.** `wip-release` doesn't move them automatically, but the release notes files it generates do get trashed after release.

package/.worktrees/wip-ai-devops-toolbox-private--cc-mini--dot-worktrees/tools/wip-repo-init/templates/product/notes/README.md

@@ -0,0 +1,26 @@
+# notes/
+
+Freeform notes, research, and observations. Anything that's useful context but isn't a plan, idea, or dev update.
+
+## What Goes Here
+
+- Research notes ("I looked into X and found...")
+- Meeting notes or conversation summaries
+- Technical investigations
+- Context that multiple plans reference
+- Anything that doesn't fit in `plans-prds/` or `product-ideas/`
+
+## Naming
+
+No strict convention. Use descriptive names:
+
+```
+YYYY-MM-DD--agent--topic.md
+```
+
+Example: `2026-03-10--cc-mini--readme-standard-and-universal-installer-vision.md`
+
+## Rules
+
+- **Not a plan?** Put it here, not in `plans-prds/`.
+- **Done with it?** Move to `_trash/`. Don't delete.

package/.worktrees/wip-ai-devops-toolbox-private--cc-mini--dot-worktrees/tools/wip-repo-init/templates/product/plans-prds/roadmap.md

@@ -0,0 +1,77 @@
+# [Product Name] ... Roadmap
+
+**Last updated:** YYYY-MM-DD
+**Current version:** vX.Y.Z
+
+Items are either **Upcoming**, **Done**, or **Deprecated**. Never delete. Always move.
+
+---
+
+## What This File Is
+
+The prioritized roadmap for this product. Three sections:
+
+- **Upcoming** ... work that's planned, ordered by priority. Top = most important.
+- **Done** ... shipped work. Moved here with a date when it's released.
+- **Deprecated** ... planned work that's no longer needed. Strikethrough, add the reason and date. Not the same as Done. Done means it shipped. Deprecated means the plan changed.
+
+**Keep it honest.** If something isn't going to happen, deprecate it. Don't leave dead items in Upcoming.
+
+**Keep it prioritized.** Upcoming items have priority numbers. When priorities shift, renumber them. The order is the strategy.
+
+---
+
+## Vision
+
+_One paragraph. Where is this product going? Not the feature list. The north star._
+
+---
+
+## Upcoming
+
+### Priority 1 ... [Feature/Epic Name]
+
+_What it is and why it matters in 1-2 sentences._
+
+- [ ] Task one
+- [ ] Task two
+- [ ] Task three
+
+### Priority 2 ... [Feature/Epic Name]
+
+_What it is and why it matters._
+
+- [ ] Task one
+- [ ] Task two
+
+_Add more priorities as needed. Number them. The number is the priority._
+
+---
+
+## Done
+
+### [Feature Name] (YYYY-MM-DD)
+
+- [x] What shipped
+- [x] What shipped
+
+_Move items here when they're released. Include the date. Keep the checkbox format so it's clear what was planned vs what actually shipped._
+
+---
+
+## Deprecated
+
+- ~~[Feature that was planned]~~ ... reason it was dropped. (YYYY-MM-DD)
+
+_Deprecated is not a graveyard. It's a record of decisions. When someone asks "why didn't we build X?" the answer is here._
+
+---
+
+## How to Update This File
+
+- **Shipped a feature?** Move it from Upcoming to Done. Add the date. Check the boxes.
+- **Dropped a plan?** Move it to Deprecated. Strikethrough, add the reason and date.
+- **New idea that's ready to plan?** Add to Upcoming with a priority number. Renumber if needed.
+- **Idea that's NOT ready to plan?** Put it in `../product-ideas/` instead. The roadmap is for committed work.
+- **Priorities shifted?** Renumber the Upcoming section. The order matters.
+- **Always update** "Last updated" and "Current version" at the top.

package/.worktrees/wip-ai-devops-toolbox-private--cc-mini--dot-worktrees/tools/wip-repo-init/templates/product/plans-prds/todos/README.md

@@ -0,0 +1,63 @@
+# todos/
+
+One todo file per person or agent. Three sections per file: To Do, Done, Deprecated.
+
+## What This Folder Is
+
+Todos that are specific to this repo. Each person or agent who works on this repo gets one file. The file tracks what they need to do, what they've done, and what got dropped.
+
+For cross-repo work or bigger items, use GitHub Issues. Todos here are for repo-scoped tasks that don't need the overhead of an issue.
+
+## Files
+
+One file per person/agent. Name it `[Name]-todo.md`.
+
+Example:
+
+| File | Who |
+|------|-----|
+| `Parker-todo.md` | Parker (human tasks: reviews, credentials, approvals) |
+| `CC-Mini-todo.md` | Claude Code on Mac Mini (code, builds, deploys) |
+
+Create the file when that person/agent first has work to do. No empty placeholder files.
+
+## File Format
+
+```markdown
+# [Name] Todos
+
+**Last updated:** YYYY-MM-DD
+
+## To Do
+
+- [ ] Task description
+- [ ] Task description (blocked by: reason)
+
+## Done
+
+- [x] Task description (YYYY-MM-DD)
+- [x] Task description (YYYY-MM-DD)
+
+## Deprecated
+
+- ~~Task description~~ ... reason. (YYYY-MM-DD)
+```
+
+## Rules
+
+- **Never delete anything.** Items move between sections, never off the page.
+- **To Do** ... work that needs to happen.
+- **Done** ... completed work. Check the box, add the date.
+- **Deprecated** ... planned but no longer needed. Strikethrough, add the reason and date. Not the same as Done. Done means it shipped. Deprecated means the requirement changed.
+- **Update the date** at the top of the file every time you edit it.
+- **One file per person/agent.** No dated files, no subfolders, no inboxes.
+- **Blocked items** stay in To Do with a `(blocked by: reason)` note. Don't move them to a separate section.
+
+## When to Use Todos vs GitHub Issues
+
+| Use | When |
+|-----|------|
+| **Todo file** | Quick tasks, repo-scoped work, things you'll do this session or this week |
+| **GitHub Issue** | Bugs, feature requests, cross-repo work, things that need tracking or discussion |
+
+Both is fine. File an issue AND add a todo that references it. The todo is your personal checklist. The issue is the team's record.