@masculinecache/issue-work 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,86 @@
-# Temporary Holding Version
+# issue-work
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+GitHub issue triage + automation for agents. AXI-compliant TOON output, confidence-gated implementation.
+
+## Install
+
+```bash
+npm install -g issue-work
+```
+
+Or via mise:
+
+```toml
+"npm:issue-work" = "0.1.0"
+```
+
+## Usage
+
+```
+issue-work [command] [args] [flags]
+commands[4]:
+  (none)=triage+implement, triage <number>, list, comment <number>
+flags[4]:
+  -R/--repo <OWNER/NAME>, --dry-run, --confidence-threshold <N> (default 95), --help, -v/--version
+```
+
+### Examples
+
+```bash
+# Triage + implement if confidence >= 95
+issue-work 42
+
+# Triage only (never implements)
+issue-work triage 42
+
+# Dry-run — show plan without mutating anything
+issue-work triage 42 --dry-run
+
+# List open issues with classification + confidence
+issue-work list --repo owner/name
+
+# List untriaged issues (no labels)
+issue-work list --repo owner/name --untriaged
+
+# Custom confidence threshold
+issue-work 42 --confidence-threshold 80
+
+# Post a comment
+issue-work comment 42 --body "investigating"
+```
+
+## How it works
+
+1. **Triage**: classifies the issue (bug/feat/chore/docs/question), estimates confidence (0–100), scope (S/M/L/XL), and suggests labels.
+2. **Decision**: if confidence >= threshold (default 95), outputs implementation plan (branch name, steps). If below, outputs triage-only with blockers.
+3. **Comment**: posts a structured triage comment on the issue (unless `--dry-run`).
+4. **Implementation**: the CLI itself does not write code — it signals the calling agent (via stdout) that implementation is warranted. The agent follows the `issue-automation` skill for the actual implementation flow.
+
+## Confidence estimation
+
+The CLI estimates confidence from issue content using heuristic signals:
+
+| Signal | Contribution |
+|---|---|
+| Clear reproduction steps | +20 |
+| Expected/actual behavior | +10 |
+| Acceptance criteria | +15 |
+| Single-file fix indicated | +15 |
+| Existing test pattern mentioned | +10 |
+| Breaking change implied | -20 |
+| Security-sensitive area | -25 |
+| Ambiguous language | -15 |
+| Multi-file change needed | -20 |
+| External API dependency | -15 |
+| Short/unclear description | -10 |
+
+Base score: 50. Adjusted by signals. Clamped to 0–100.
+
+## Dependencies
+
+- `gh-axi` — all GitHub API access goes through gh-axi (never raw `gh`)
+- Node.js >= 18
+
+## License
+
+MIT

package/bin/common.mjs

@@ -0,0 +1,144 @@
+// AXI shared helpers — TOON output, flag parsing, errors, truncation.
+import { execFileSync } from 'node:child_process';
+import { homedir } from 'node:os';
+
+export const HOME = homedir();
+
+export function collapseHome(p) {
+  return p.replace(HOME, '~');
+}
+
+export function list(name, fields, rows, opts = {}) {
+  const lines = [];
+  const n = rows.length;
+  if (opts.total !== undefined && opts.total > n) {
+    lines.push(`count: ${n} of ${opts.total} total`);
+  }
+  lines.push(`${name}[${n}]{${fields.join(',')}}:`);
+  for (const r of rows) {
+    lines.push('  ' + fields.map((f) => fmt(r[f])).join(','));
+  }
+  return lines.join('\n');
+}
+
+export function kv(obj) {
+  return Object.entries(obj)
+    .map(([k, v]) => `${k}: ${fmt(v)}`)
+    .join('\n');
+}
+
+export function fmt(v) {
+  if (v === null || v === undefined) return '';
+  if (typeof v === 'string') {
+    if (v.includes(',') || v.includes('\n') || v.includes(':')) {
+      return `"${v.replace(/"/g, "'")}"`;
+    }
+    return v;
+  }
+  return String(v);
+}
+
+export function help(lines) {
+  return lines.map((l, i) => `help[${i + 1}]: ${l}`).join('\n');
+}
+
+export function fail(message, code = 'ERROR', helpLines = []) {
+  const out = [`error: ${message}`, `code: ${code}`];
+  if (helpLines.length) out.push(help(helpLines));
+  process.stdout.write(out.join('\n') + '\n');
+  process.exit(1);
+}
+
+export function usageError(message, helpLines = []) {
+  const out = [`error: ${message}`, `code: USAGE`];
+  if (helpLines.length) out.push(help(helpLines));
+  process.stdout.write(out.join('\n') + '\n');
+  process.exit(2);
+}
+
+export function truncate(s, max = 500, fullHintCmd = null) {
+  if (s === undefined || s === null) return '';
+  const str = String(s);
+  if (str.length <= max) return str;
+  const head = str.slice(0, max);
+  const note = `... (truncated, ${str.length} chars total)`;
+  let out = head + '\n' + note;
+  if (fullHintCmd) out += '\n' + help([`Run \`${fullHintCmd}\` for full content`]);
+  return out;
+}
+
+export function parseFlags(args, spec = {}) {
+  const bools = new Set(['help', ...(spec.bools || [])]);
+  const values = new Set(spec.values || []);
+  const flags = { help: false, _: [] };
+  const valid = [...bools, ...values];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--') { flags._.push(...args.slice(i + 1)); break; }
+    if (a.startsWith('--')) {
+      const eq = a.indexOf('=');
+      const name = eq > 0 ? a.slice(2, eq) : a.slice(2);
+      if (name === 'help') { flags.help = true; continue; }
+      if (bools.has(name)) {
+        flags[name] = true;
+        continue;
+      }
+      if (values.has(name)) {
+        if (eq > 0) {
+          flags[name] = a.slice(eq + 1);
+        } else {
+          const v = args[i + 1];
+          if (v === undefined || v.startsWith('--')) {
+            usageError(`--${name} requires a value`, [`valid flags: --${valid.join(', --')} (--help always allowed)`]);
+          }
+          flags[name] = v;
+          i++;
+        }
+        continue;
+      }
+      usageError(`unknown flag --${name}`, [`valid flags for this command: --${valid.join(', --')} (--help always allowed)`]);
+    }
+    if (/^-\d+$/.test(a)) { flags._.push(a); continue; }
+    flags._.push(a);
+  }
+  return flags;
+}
+
+export function run(cmd, args, opts = {}) {
+  try {
+    const stdout = execFileSync(cmd, args, {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: opts.timeout || 30000,
+      env: { ...process.env, ...(opts.env || {}) },
+      maxBuffer: 16 * 1024 * 1024,
+    });
+    return { code: 0, stdout, stderr: '' };
+  } catch (e) {
+    return { code: e.status ?? 1, stdout: e.stdout?.toString() ?? '', stderr: e.stderr?.toString() ?? '' };
+  }
+}
+
+export function ghJson(args, opts = {}) {
+  const bin = process.env.GH_BIN || 'gh';
+  const r = run(bin, args, opts);
+  if (r.code !== 0) {
+    const msg = r.stderr.trim() || r.stdout.trim() || `gh exited ${r.code}`;
+    fail(`gh: ${msg}`, 'GH_ERROR', ['Ensure gh is installed and authenticated']);
+  }
+  try {
+    return JSON.parse(r.stdout);
+  } catch {
+    fail('gh returned invalid JSON', 'PARSE_ERROR');
+  }
+}
+
+export function ghMutate(args, opts = {}) {
+  const bin = process.env.GH_AXI_BIN || 'gh-axi';
+  const r = run(bin, args, opts);
+  if (r.code !== 0) {
+    const msg = r.stderr.trim() || r.stdout.trim() || `gh-axi exited ${r.code}`;
+    fail(`gh-axi: ${msg}`, 'GH_AXI_ERROR', ['Ensure gh-axi is installed and authenticated']);
+  }
+  return r.stdout;
+}

package/bin/issue-work

@@ -0,0 +1,343 @@
+#!/usr/bin/env node
+// issue-work — GitHub issue triage + automation for agents. TOON output, confidence-gated.
+import { list, kv, help, fail, usageError, parseFlags, ghJson, ghMutate, truncate, fmt } from './common.mjs';
+
+const VERSION = '0.1.0';
+
+import { run } from './common.mjs';
+
+function resolveRepo(flags) {
+  if (flags.repo) return flags.repo;
+  const r = run('git', ['remote', 'get-url', 'origin']);
+  if (r.code === 0) {
+    const url = r.stdout.trim();
+    const m = url.match(/[:/]([^/:]+\/[^/.]+)(?:\.git)?$/);
+    if (m) return m[1];
+  }
+  return null;
+}
+
+const TOP_HELP = `usage: issue-work [command] [args] [flags]
+commands[4]:
+  (none)=triage+implement, triage <number>, list, comment <number>
+flags[4]:
+  -R/--repo <OWNER/NAME>, --dry-run, --confidence-threshold <N> (default 95), --help, -v/--version
+examples:
+  issue-work 42
+  issue-work triage 42 --repo owner/name --dry-run
+  issue-work list --repo owner/name --label bug
+  issue-work comment 42 --body "triaged: confidence 92, scope M"`;
+
+const COMMAND_HELP = {
+  triage: `usage: issue-work triage <number> [flags]
+Triage a single issue: classify, estimate confidence, suggest labels.
+Does not implement — always outputs triage only.
+flags: -R/--repo, --dry-run, --help`,
+  list: `usage: issue-work list [flags]
+List open issues for a repo.
+flags: -R/--repo, --label <name>, --assignee <login>, --state <open|closed|all>, --limit <n> (default 30), --untriaged, --help`,
+  comment: `usage: issue-work comment <number> [flags]
+Post a structured comment on an issue.
+flags: -R/--repo, --body <text> (required), --help`,
+};
+
+function classifyIssue(issue) {
+  const title = (issue.title || '').toLowerCase();
+  const body = (issue.body || '').toLowerCase();
+  const labels = (issue.labels || []).map((l) => (typeof l === 'string' ? l : l.name || '')).join(' ');
+
+  const titleMatch = (() => {
+    if (/\b(bug|fix|broken|error|crash|fail|regression|wrong)\b/.test(title)) return 'bug';
+    if (/\b(feat|feature|add|new|support|implement|create)\b/.test(title)) return 'feat';
+    if (/\b(chore|refactor|clean|update|maintain|upgrade|bump|deps?)\b/.test(title)) return 'chore';
+    if (/\b(doc|docs|readme|comment|explain|guide)\b/.test(title)) return 'docs';
+    if (/\b(questi|how\s+to|help|confused|unclear)\b/.test(title)) return 'question';
+    return null;
+  })();
+  if (titleMatch) return titleMatch;
+
+  const text = `${title} ${body} ${labels}`;
+  if (/\b(bug|broken|error|crash|regression|wrong)\b/.test(text)) return 'bug';
+  if (/\b(feat|feature|add|new|support|implement|create)\b/.test(text)) return 'feat';
+  if (/\b(chore|refactor|clean|maintain|upgrade|bump|deps?)\b/.test(text)) return 'chore';
+  if (/\b(doc|docs|readme|explain|guide)\b/.test(text)) return 'docs';
+  if (/\b(questi|how\s+to|help|confused|unclear)\b/.test(text)) return 'question';
+  return 'task';
+}
+
+function estimateConfidence(issue) {
+  const body = issue.body || '';
+  const title = issue.title || '';
+  let score = 50;
+
+  if (/steps?\s+to\s+repro|reproduc|how\s+to\s+repro/i.test(body)) score += 20;
+  if (/expected\s+behavior|actual\s+behavior/i.test(body)) score += 10;
+  if (/acceptance\s+criteria|definition\s+of\s+done/i.test(body)) score += 15;
+  if (/single\s+file|one\s+file|only\s+in\s+\S+\.\S+/i.test(body)) score += 15;
+  if (/\b(test|spec|should|expect)\b/i.test(body)) score += 10;
+  if (/breaking|migration|refactor\s+multiple|across\s+\d+\s+file/i.test(body)) score -= 20;
+  if (/security|auth|secret|token|credential|password|encrypt/i.test(body)) score -= 25;
+  if (/\b(unknown|unclear|maybe|might|perhaps|tbd|todo)\b/i.test(body)) score -= 15;
+  if (/\b(multiple|several|many|various)\s+(file|module|component|service)/i.test(body)) score -= 20;
+  if (/external\s+api|third.?party|upstream|downstream/i.test(body)) score -= 15;
+  if (body.length < 100) score -= 10;
+
+  return Math.max(0, Math.min(100, score));
+}
+
+function estimateScope(issue) {
+  const body = (issue.body || '').toLowerCase();
+  const title = (issue.title || '').toLowerCase();
+  const text = `${title} ${body}`;
+  if (/single\s+file|typo|one.?liner|minor|small|quick/i.test(text)) return 'S';
+  if (/multiple\s+file|refactor|module|component|service/i.test(text)) return 'L';
+  if (/across\s+the\s+fleet|multi.?repo|migration|architecture/i.test(text)) return 'XL';
+  return 'M';
+}
+
+function suggestLabels(issue, classification) {
+  const suggested = [classification];
+  const body = (issue.body || '').toLowerCase();
+  if (/security|auth|secret|token/i.test(body)) suggested.push('security');
+  if (/breaking|migration/i.test(body)) suggested.push('breaking-change');
+  if (/fleet|swarm|multi.?host/i.test(body)) suggested.push('fleet');
+  if (/agent|automation|ci\/?cd/i.test(body)) suggested.push('automation');
+  return [...new Set(suggested)];
+}
+
+function branchName(issueNumber, title) {
+  const slug = (title || 'fix')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40);
+  return `issue-${issueNumber}-${slug}`;
+}
+
+function formatTriageOutput(issue, repo, dryRun) {
+  const classification = classifyIssue(issue);
+  const confidence = estimateConfidence(issue);
+  const scope = estimateScope(issue);
+  const labels = suggestLabels(issue, classification);
+  const branch = branchName(issue.number, issue.title);
+  const threshold = 95;
+  const action = confidence >= threshold ? 'implement' : 'triage-only';
+
+  const lines = [];
+  lines.push(`issue #${issue.number} | ${classification} | confidence ${confidence} | scope ${scope} | labels: ${labels.join(', ')}`);
+  lines.push(`action: ${action}${confidence < threshold ? ` (below threshold ${threshold})` : ''}`);
+  lines.push(`branch: ${branch}`);
+  if (dryRun) lines.push('dry-run: no mutations performed');
+  lines.push(`repo: ${repo}`);
+
+  if (confidence >= threshold) {
+    lines.push('');
+    lines.push(`implementation plan:`);
+    lines.push(`  1. branch: ${branch}`);
+    lines.push(`  2. implement fix for: ${truncate(issue.title, 80)}`);
+    lines.push(`  3. open PR targeting default branch`);
+    lines.push(`  4. stop — captain reviews and merges`);
+  } else {
+    lines.push('');
+    lines.push(`blockers for implementation:`);
+    if (confidence < 50) lines.push('  - very low confidence — requirements likely ambiguous');
+    else if (confidence < 70) lines.push('  - low confidence — some ambiguity or complexity');
+    else lines.push('  - near threshold — minor clarification may unlock implementation');
+  }
+
+  return lines.join('\n');
+}
+
+function formatTriageComment(issue) {
+  const classification = classifyIssue(issue);
+  const confidence = estimateConfidence(issue);
+  const scope = estimateScope(issue);
+  const labels = suggestLabels(issue, classification);
+  const threshold = 95;
+
+  const lines = [];
+  lines.push(`**Triage** (automated via \`issue-work\`)`);
+  lines.push('');
+  lines.push(`| Field | Value |`);
+  lines.push(`|---|---|`);
+  lines.push(`| Classification | ${classification} |`);
+  lines.push(`| Confidence | ${confidence}/100 |`);
+  lines.push(`| Scope | ${scope} |`);
+  lines.push(`| Suggested labels | ${labels.map((l) => '`' + l + '`').join(', ')} |`);
+  lines.push(`| Action | ${confidence >= threshold ? 'implement + PR' : 'triage only (below ' + threshold + ' threshold)'} |`);
+  lines.push('');
+  if (confidence < threshold) {
+    lines.push(`Confidence is below the ${threshold}% implementation threshold. The issue needs more detail or clarification before automated implementation can proceed.`);
+  }
+
+  return lines.join('\n');
+}
+
+function cmdTriage(args) {
+  const flags = parseFlags(args, {
+    bools: ['dry-run'],
+    values: ['repo', 'confidence-threshold'],
+  });
+  if (flags.help) { process.stdout.write(COMMAND_HELP.triage + '\n'); return; }
+  const number = flags._[0];
+  if (!number) usageError('triage requires an issue number', ['issue-work triage <number>']);
+  const repo = flags.repo || resolveRepo(flags);
+  if (!repo) fail('no repo specified and could not detect from git remote', 'NO_REPO', ['Pass -R/--repo owner/name']);
+
+  const ghArgs = ['issue', 'view', String(number), '--repo', repo, '--json', 'number,title,body,labels,state,author,createdAt'];
+  const issue = ghJson(ghArgs);
+
+  const dryRun = flags.dryRun || false;
+  const output = formatTriageOutput(issue, repo, dryRun);
+  process.stdout.write(output + '\n');
+
+  if (!dryRun && issue.state === 'OPEN') {
+    const commentBody = formatTriageComment(issue);
+    const commentArgs = ['issue', 'comment', String(number), '--repo', repo, '--body', commentBody];
+    ghMutate(commentArgs);
+  }
+}
+
+function cmdList(args) {
+  const flags = parseFlags(args, {
+    bools: ['dry-run', 'untriaged'],
+    values: ['repo', 'label', 'assignee', 'state', 'limit'],
+  });
+  if (flags.help) { process.stdout.write(COMMAND_HELP.list + '\n'); return; }
+
+  const repo = flags.repo || resolveRepo(flags);
+  if (!repo) fail('no repo specified and could not detect from git remote', 'NO_REPO', ['Pass -R/--repo owner/name']);
+
+  const ghArgs = ['issue', 'list', '--repo', repo, '--json', 'number,title,labels,author,createdAt,state'];
+  if (flags.label) ghArgs.push('--label', flags.label);
+  if (flags.assignee) ghArgs.push('--assignee', flags.assignee);
+  if (flags.state) ghArgs.push('--state', flags.state);
+  if (flags.limit) ghArgs.push('--limit', flags.limit);
+  else ghArgs.push('--limit', '30');
+
+  const issues = ghJson(ghArgs);
+  if (!Array.isArray(issues)) fail('unexpected gh-axi output', 'PARSE_ERROR');
+
+  let filtered = issues;
+  if (flags.untriaged) {
+    filtered = issues.filter((i) => {
+      const lbls = (i.labels || []).map((l) => (typeof l === 'string' ? l : l.name || ''));
+      return lbls.length === 0;
+    });
+  }
+
+  const rows = filtered.map((i) => ({
+    number: i.number,
+    title: truncate(i.title, 60),
+    classification: classifyIssue(i),
+    confidence: estimateConfidence(i),
+    scope: estimateScope(i),
+    state: i.state || 'OPEN',
+  }));
+
+  const output = list('issues', ['number', 'title', 'classification', 'confidence', 'scope', 'state'], rows, { total: issues.length });
+  process.stdout.write(output + '\n');
+}
+
+function cmdComment(args) {
+  const flags = parseFlags(args, {
+    bools: [],
+    values: ['repo', 'body'],
+  });
+  if (flags.help) { process.stdout.write(COMMAND_HELP.comment + '\n'); return; }
+  const number = flags._[0];
+  if (!number) usageError('comment requires an issue number', ['issue-work comment <number> --body "text"']);
+  if (!flags.body) usageError('--body is required', ['issue-work comment <number> --body "text"']);
+
+  const repo = flags.repo || resolveRepo(flags);
+  if (!repo) fail('no repo specified and could not detect from git remote', 'NO_REPO', ['Pass -R/--repo owner/name']);
+
+  ghMutate(['issue', 'comment', String(number), '--repo', repo, '--body', flags.body]);
+  process.stdout.write(`comment posted on #${number} (${repo})\n`);
+}
+
+function cmdMain(args) {
+  const flags = parseFlags(args, {
+    bools: ['dry-run'],
+    values: ['repo', 'confidence-threshold'],
+  });
+  if (flags.help) { process.stdout.write(TOP_HELP + '\n'); return; }
+
+  const number = flags._[0];
+  if (!number) {
+    process.stdout.write(TOP_HELP + '\n');
+    return;
+  }
+
+  const repo = flags.repo || resolveRepo(flags);
+  if (!repo) fail('no repo specified and could not detect from git remote', 'NO_REPO', ['Pass -R/--repo owner/name']);
+
+  const threshold = parseInt(flags['confidence-threshold'] || '95', 10);
+
+  const ghArgs = ['issue', 'view', String(number), '--repo', repo, '--json', 'number,title,body,labels,state,author,createdAt'];
+  const issue = ghJson(ghArgs);
+
+  if (issue.state !== 'OPEN') {
+    process.stdout.write(`issue #${number} is ${issue.state} — no action\n`);
+    return;
+  }
+
+  const dryRun = flags.dryRun || false;
+  const confidence = estimateConfidence(issue);
+  const classification = classifyIssue(issue);
+  const scope = estimateScope(issue);
+  const labels = suggestLabels(issue, classification);
+  const branch = branchName(issue.number, issue.title);
+
+  const triageOutput = formatTriageOutput(issue, repo, dryRun);
+  process.stdout.write(triageOutput + '\n');
+
+  if (!dryRun) {
+    const commentBody = formatTriageComment(issue);
+    const commentArgs = ['issue', 'comment', String(number), '--repo', repo, '--body', commentBody];
+    ghMutate(commentArgs);
+  }
+
+  if (confidence < threshold) {
+    process.stdout.write(`\nconfidence ${confidence} < threshold ${threshold} — stopping at triage\n`);
+    return;
+  }
+
+  if (dryRun) {
+    process.stdout.write(`\ndry-run: would implement on branch ${branch}\n`);
+    return;
+  }
+
+  process.stdout.write(`\nconfidence ${confidence} >= threshold ${threshold} — ready to implement\n`);
+  process.stdout.write(`branch: ${branch}\n`);
+  process.stdout.write(`next: implement fix and open PR\n`);
+  process.stdout.write(`\nissue-automation skill: the calling agent should now implement the fix\n`);
+  process.stdout.write(`  1. git checkout -b ${branch}\n`);
+  process.stdout.write(`  2. implement the fix described in #${number}\n`);
+  process.stdout.write(`  3. open a PR — captain reviews and merges\n`);
+}
+
+const args = process.argv.slice(2);
+
+if (args.includes('-v') || args.includes('-V') || args.includes('--version')) {
+  process.stdout.write(`issue-work ${VERSION}\n`);
+  process.exit(0);
+}
+
+const sub = args[0];
+const rest = args.slice(1);
+
+switch (sub) {
+  case 'triage':
+    cmdTriage(rest);
+    break;
+  case 'list':
+    cmdList(rest);
+    break;
+  case 'comment':
+    cmdComment(rest);
+    break;
+  default:
+    cmdMain(args);
+    break;
+}

package/package.json

@@ -1,6 +1,13 @@
 {
   "name": "@masculinecache/issue-work",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "AXI-compliant GitHub issue triage + automation CLI — TOON output, confidence-gated implementation",
+  "type": "module",
+  "bin": { "issue-work": "bin/issue-work" },
+  "files": ["bin/", "skill/", "README.md"],
+  "engines": { "node": ">=18" },
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/masculinecache/issue-work.git" },
+  "keywords": ["github", "issues", "agents", "cli", "toon", "axi", "triage"],
+  "publishConfig": { "access": "public" }
+}

package/skill/SKILL.md

@@ -0,0 +1,94 @@
+# issue-automation
+
+Automated GitHub issue triage and implementation workflow for agents. Load when triaging, implementing, or working with GitHub issues in an automated workflow.
+
+## Quick reference
+
+```
+issue-work <number>                          # triage + implement if confidence >= 95
+issue-work triage <number> --dry-run         # triage only, no mutations
+issue-work list --repo owner/name --untriaged # list untriaged issues
+issue-work comment <number> --body "text"    # post a comment
+```
+
+## Flow
+
+### 1. Triage (always runs first)
+
+```
+issue-work triage <number> -R owner/name --dry-run
+```
+
+This classifies the issue, estimates confidence, and outputs structured triage. Use `--dry-run` first for safety.
+
+Read the output. If confidence < threshold (default 95):
+- Review the blockers listed
+- If you can clarify the issue (ask the author, check linked PRs/docs), do so
+- Re-run triage after gathering more context
+- Post findings as a comment if helpful
+
+If confidence >= threshold, proceed to implementation.
+
+### 2. Implementation (confidence >= 95 only)
+
+Follow this flow, adapted from the `lfg` skill:
+
+1. **Branch**: `git checkout -b issue-<number>-<slug>` (use the branch name from triage output)
+2. **Explore**: read the codebase to understand the change needed
+3. **Implement**: make minimal, correct changes
+4. **Verify**: run lint, typecheck, tests
+5. **PR**: open a pull request with a description referencing `Closes #<number>`
+6. **Stop**: captain reviews and merges — no auto-merge
+
+Single-issue branches: one issue = one branch = one PR. Never mix.
+
+### 3. Fleet repos (swarm-runbook enhancements)
+
+When the target repo is fleet-managed (dotfiles, fleetdeck, etc.), apply swarm-runbook conventions:
+
+- **Sync-freeze**: check for active fleet operations before modifying host configs
+- **FLEET_NODE**: use `$FLEET_NODE` in attestation comments (not `hostname -s`)
+- **Staggered deployment**: changes that touch fleet host configs deploy via `chezmoi apply` on each host
+- **Per-host verification**: verify on each host after deployment
+
+### 4. Post-implementation
+
+- Post verification results as a comment on the issue
+- Include: what was changed, how it was verified, any findings
+- Do NOT close the issue — captain closes after review
+
+## Confidence rubric
+
+The `issue-work` CLI estimates confidence from issue content. As an agent, you can override the CLI's estimate if you have additional context (e.g. you know the codebase well, or you've already explored the relevant code).
+
+**Override up**: if you've already explored the code and are confident you can implement correctly, bump confidence (e.g. CLI says 88 but you've read the relevant module and the fix is obvious → proceed).
+
+**Override down**: if the CLI says >= 95 but you see a pitfall it missed (security, fleet impact, cross-repo dependency), treat it as below threshold and triage-only.
+
+## Guardrails
+
+- **PR required**: never push to the default branch
+- **Single-issue branches**: one issue per branch/PR
+- **Captain approval for**: closing issues, applying labels, breaking changes, security-sensitive code
+- **Dry-run first**: always `--dry-run` on first pass
+- **No auto-close**: captain closes issues manually after merge
+- **No auto-label in MVP**: suggest labels in triage output but don't apply them
+
+## When to escalate
+
+Escalate to captain when:
+- The issue touches security-sensitive code (auth, secrets, networking)
+- A breaking change is required
+- Multi-repo coordination is needed
+- The fix requires external API changes
+- Confidence is borderline (90–94) and the area is unfamiliar
+
+## Integration with other skills
+
+| Skill | Use |
+|---|---|
+| `gh-axi` | All GitHub API access (issue CRUD, comments, PRs) |
+| `lfg` | Implementation engine — same branch→implement→PR flow |
+| `swarm-runbook` | Fleet-slice conventions when repo is fleet-managed |
+| `no-mistakes` | PR review gate (recommended but not required in MVP) |
+| `dotfiles` | When target is phillias/dotfiles — use dotfiles commit/PR flow |