@xulthekl/team-flow 0.22.4

package/scripts/lint/lint-skills.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+// lint-skills.mjs — Skill content static analyzer
+// Scans skills/*/SKILL.md against registered rules, outputs structured report.
+
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SKILLS_DIR = join(__dirname, '..', '..', 'skills');
+const RULES_DIR = join(__dirname, 'rules');
+
+async function loadRules() {
+  if (!existsSync(RULES_DIR)) return [];
+  const ruleFiles = readdirSync(RULES_DIR).filter(f => f.endsWith('.mjs'));
+  const rules = [];
+  for (const file of ruleFiles.sort()) {
+    try {
+      const mod = await import(join(RULES_DIR, file));
+      if (mod.default && typeof mod.default.check === 'function') {
+        rules.push(mod.default);
+      }
+    } catch (e) {
+      console.error(`Warning: failed to load rule ${file}: ${e.message}`);
+    }
+  }
+  return rules;
+}
+
+/**
+ * @param {Object} options
+ * @param {string[]} [options.skills] — specific skill names to lint (default: all)
+ * @returns {Promise<{valid: boolean, results: Array, summary: string}>}
+ */
+export async function lintSkills(options = {}) {
+  const rules = await loadRules();
+  const allDirs = readdirSync(SKILLS_DIR, { withFileTypes: true })
+    .filter(d => d.isDirectory())
+    .map(d => d.name);
+
+  const skillDirs = options.skills
+    ? allDirs.filter(s => options.skills.includes(s))
+    : allDirs;
+
+  const results = [];
+  for (const skillName of skillDirs) {
+    const skillMd = join(SKILLS_DIR, skillName, 'SKILL.md');
+    if (!existsSync(skillMd)) {
+      results.push({ skill: skillName, issues: [{ severity: 'error', rule: 'file-existence', message: 'SKILL.md not found' }] });
+      continue;
+    }
+
+    const content = readFileSync(skillMd, 'utf-8');
+    const ctx = { skillDirs: allDirs, skillsDir: SKILLS_DIR };
+    const issues = [];
+
+    for (const rule of rules) {
+      try {
+        const ruleIssues = await rule.check(skillName, content, ctx);
+        if (Array.isArray(ruleIssues)) {
+          issues.push(...ruleIssues.map(i => ({ ...i, rule: rule.name || 'unknown' })));
+        }
+      } catch (e) {
+        issues.push({ severity: 'error', rule: rule.name || 'unknown', message: `Rule threw: ${e.message}` });
+      }
+    }
+
+    results.push({ skill: skillName, issues });
+  }
+
+  const totalIssues = results.reduce((sum, r) => sum + r.issues.length, 0);
+  const errorCount = results.reduce((sum, r) => sum + r.issues.filter(i => i.severity === 'error').length, 0);
+
+  return {
+    valid: errorCount === 0,
+    results,
+    summary: `${totalIssues} issue(s) (${errorCount} errors) across ${results.length} skills`,
+  };
+}
+
+/**
+ * Load only token-specific rules (--include token).
+ */
+async function loadTokenRules() {
+  const tokenRulesPath = join(RULES_DIR, 'token-rules.mjs');
+  if (!existsSync(tokenRulesPath)) return [];
+  try {
+    const mod = await import(tokenRulesPath);
+    return mod.default && typeof mod.default.check === 'function' ? [mod.default] : [];
+  } catch (e) {
+    console.error(`Warning: failed to load token-rules: ${e.message}`);
+    return [];
+  }
+}
+
+// CLI entry
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  const includeToken = process.argv.includes('--include') && process.argv[process.argv.indexOf('--include') + 1] === 'token';
+  const verbose = process.argv.includes('--verbose');
+  const fileArgIdx = process.argv.indexOf('--file');
+  const fileArg = fileArgIdx !== -1 ? process.argv[fileArgIdx + 1] : null;
+
+  let report;
+  if (includeToken) {
+    // Token mode: only run token rules
+    const rules = await loadTokenRules();
+    const skillName = fileArg ? fileArg.replace(/.*skills\/([^/]+)\/.*/, '$1') : 'all';
+    const results = [];
+    const dirs = fileArg
+      ? [skillName]
+      : readdirSync(SKILLS_DIR, { withFileTypes: true }).filter(d => d.isDirectory()).map(d => d.name);
+
+    for (const dir of dirs) {
+      const skillMd = fileArg || join(SKILLS_DIR, dir, 'SKILL.md');
+      const mdPath = fileArg || skillMd;
+      if (!existsSync(mdPath)) {
+        results.push({ skill: dir, issues: [{ severity: 'error', rule: 'file-existence', message: 'SKILL.md not found' }] });
+        continue;
+      }
+      const content = readFileSync(mdPath, 'utf-8');
+      const ctx = { skillDirs: dirs, skillsDir: SKILLS_DIR };
+      const issues = [];
+      for (const rule of rules) {
+        try {
+          const ruleIssues = await rule.check(dir, content, ctx);
+          if (Array.isArray(ruleIssues)) {
+            issues.push(...ruleIssues.map(i => ({ ...i, rule: rule.name || 'unknown' })));
+          }
+        } catch (e) {
+          issues.push({ severity: 'error', rule: rule.name || 'unknown', message: `Rule threw: ${e.message}` });
+        }
+      }
+      results.push({ skill: dir, issues });
+    }
+
+    const totalIssues = results.reduce((sum, r) => sum + r.issues.length, 0);
+    const errorCount = results.reduce((sum, r) => sum + r.issues.filter(i => i.severity === 'error').length, 0);
+    report = { valid: errorCount === 0, results, summary: `${totalIssues} issue(s) (${errorCount} errors) across ${results.length} skills` };
+  } else {
+    report = await lintSkills();
+  }
+
+  if (!report.valid || verbose) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log(`✅ ${report.summary}`);
+  }
+  process.exit(report.valid ? 0 : 1);
+}

package/scripts/lint/rules/behavior-consistency.mjs

@@ -0,0 +1,56 @@
+// Rule: behavior-consistency
+// Detects: Skill description that claims behavior not enforced in guard/phase-guard
+// Detects: "⛔ 禁止操作" without corresponding guard enforcement
+
+const FORBIDDEN_PATTERNS = [
+  { pattern: /⛔\s*禁止操作|Forbidden|Prohibited/i, label: 'forbidden-ops' },
+  { pattern: /cannot be skipped|硬门禁|hard gate|不可跳过/i, label: 'hard-gate' },
+  { pattern: /before.*test|without.*failing test|TDD Iron Law/i, label: 'tdd-requirement' },
+];
+
+export default {
+  name: 'behavior-consistency',
+
+  async check(skillName, content, ctx) {
+    const issues = [];
+
+    // Check 1: "hard gate" claims — should be in contract-builder or build-executor (DP-3, DP-4)
+    const hardGateMatch = content.match(/(hard gate|硬门禁|不可跳过|cannot be skipped)/i);
+    if (hardGateMatch && !['contract-builder', 'build-executor', 'workflow-start', 'release-archivist'].includes(skillName)) {
+      issues.push({
+        severity: 'warning',
+        message: `Claims "hard gate" but ${skillName} is not a gate-owning skill (expected: contract-builder, build-executor, workflow-start, release-archivist)`,
+      });
+    }
+
+    // Check 2: "route to" consistency with workflow-start
+    if (skillName !== 'workflow-start') {
+      const routeRefs = [...content.matchAll(/[Rr]oute to [`""]?([a-z-]+)[`""]?/g)];
+      for (const [, target] of routeRefs) {
+        // This skill says "route to X" — workflow-start should have a corresponding rule
+        // We flag this for manual verification (can't easily cross-check without loading workflow-start)
+        // Instead, check that the routed-to skill exists
+        if (!ctx.skillDirs.includes(target)) {
+          issues.push({
+            severity: 'error',
+            message: `Routes to "${target}" which does not exist in skills/`,
+          });
+        }
+      }
+    }
+
+    // Check 3: Decision point references should align with docs/decision-points.md
+    const dpRefs = [...content.matchAll(/DP-(\d)/g)].map(m => parseInt(m[1]));
+    const validDPs = [0, 1, 2, 3, 4, 5, 6, 7];
+    for (const dp of dpRefs) {
+      if (!validDPs.includes(dp)) {
+        issues.push({
+          severity: 'error',
+          message: `References DP-${dp} which is not a valid decision point (valid: DP-0 through DP-7)`,
+        });
+      }
+    }
+
+    return issues;
+  },
+};

package/scripts/lint/rules/dp-trigger-points.mjs

@@ -0,0 +1,60 @@
+// Rule: dp-trigger-points
+// Detects: Missing DP trigger descriptions and record commands in associated skills
+
+const DP_SKILL_MAP = {
+  'DP-0': { skills: ['workflow-start'], name: '设计前确认' },
+  'DP-1': { skills: ['need-explorer'], name: '需求确认' },
+  'DP-2': { skills: ['spec-writer'], name: '工件审查' },
+  'DP-3': { skills: ['contract-builder'], name: '契约批准' },
+  'DP-4': { skills: ['build-executor'], name: '执行模式选择' },
+  'DP-5': { skills: ['bug-investigator'], name: '调试升级' },
+  'DP-6': { skills: ['release-archivist'], name: '验证失败' },
+  'DP-7': { skills: ['release-archivist'], name: '归档确认' },
+};
+
+export default {
+  name: 'dp-trigger-points',
+
+  async check(skillName, content, ctx) {
+    const issues = [];
+
+    for (const [dp, { skills, name }] of Object.entries(DP_SKILL_MAP)) {
+      if (!skills.includes(skillName)) continue;
+
+      // Check 1: Is DP referenced by name/number?
+      const dpReferenced = content.includes(dp);
+
+      // Check 2: Is there a record command (tf state set ... dp_N_*)?
+      const dpNum = dp.slice(-1);
+      const hasRecordCommand = new RegExp(`dp_${dpNum}_(result|timestamp|confirmed)`).test(content);
+
+      // Check 3: Is the trigger condition described?
+      const hasTriggerDesc = new RegExp(
+        `触发条件|When (to|should)|Trigger|Use (this|the).*${dp}`,
+        'i'
+      ).test(content) || content.includes(`DP-${dpNum}`);
+
+      if (!dpReferenced) {
+        issues.push({
+          severity: 'error',
+          message: `${dp} (${name}) is not referenced in ${skillName} — trigger point missing`,
+        });
+      } else {
+        if (!hasTriggerDesc) {
+          issues.push({
+            severity: 'warning',
+            message: `${dp} is mentioned but has no trigger condition description`,
+          });
+        }
+        if (!hasRecordCommand) {
+          issues.push({
+            severity: 'warning',
+            message: `${dp} has no tf state set dp_${dpNum}_* record command`,
+          });
+        }
+      }
+    }
+
+    return issues;
+  },
+};

package/scripts/lint/rules/exception-handling.mjs

@@ -0,0 +1,59 @@
+// Rule: exception-handling
+// Detects: Missing error handling for common failure scenarios
+// Each skill should cover: parse failures, missing files, user interruption
+
+const REQUIRED_EXCEPTION_PATTERNS = [
+  {
+    id: 'parse-failure',
+    patterns: [/解析失败|parse (error|fail)|malformed|格式不正确/i],
+    message: 'No guidance for parse/malformed-input failures',
+  },
+  {
+    id: 'missing-files',
+    patterns: [/文件缺失|file (not found|missing)|missing (file|artifact)/i],
+    message: 'No guidance for missing file/artifact scenarios',
+  },
+  {
+    id: 'user-interruption',
+    patterns: [/用户中断|user (interrupt|cancel|stop)|恢复|resume|restart/i],
+    message: 'No guidance for user interruption and session recovery',
+  },
+  {
+    id: 'validation-failure',
+    patterns: [/验证失败|validation (fail|error)|check fail/i],
+    message: 'No guidance for validation failure scenarios',
+  },
+];
+
+export default {
+  name: 'exception-handling',
+
+  async check(skillName, content, ctx) {
+    const issues = [];
+
+    // Every skill should have at least basic error guidance
+    for (const { id, patterns, message } of REQUIRED_EXCEPTION_PATTERNS) {
+      const hasCoverage = patterns.some(p => p.test(content));
+
+      // parse-failure is required for all skills
+      // missing-files is required for skills that read artifacts
+      // user-interruption is required for all skills
+      // validation-failure is required for spec-writer and contract-builder
+
+      const isRequired =
+        id === 'parse-failure' ||
+        id === 'user-interruption' ||
+        (id === 'missing-files' && /read|inspect|check|parse/i.test(content)) ||
+        (id === 'validation-failure' && ['spec-writer', 'contract-builder', 'release-archivist'].includes(skillName));
+
+      if (isRequired && !hasCoverage) {
+        issues.push({
+          severity: 'warning',
+          message,
+        });
+      }
+    }
+
+    return issues;
+  },
+};

package/scripts/lint/rules/no-contradictory-instructions.mjs

@@ -0,0 +1,67 @@
+// Rule: no-contradictory-instructions
+// Detects: DP trigger conditions that differ between skills
+// Detects: State transition rules that differ between workflow-start and target skills
+
+const DP_NAMES = {
+  'DP-0': '设计前确认', 'DP-1': '需求确认', 'DP-2': '工件审查', 'DP-3': '契约批准',
+  'DP-4': '执行模式选择', 'DP-5': '调试升级', 'DP-6': '验证失败', 'DP-7': '归档确认',
+};
+
+const DP_SKILL_MAP = {
+  'DP-0': ['workflow-start'],
+  'DP-1': ['need-explorer'],
+  'DP-2': ['spec-writer'],
+  'DP-3': ['contract-builder'],
+  'DP-4': ['build-executor'],
+  'DP-5': ['bug-investigator'],
+  'DP-6': ['release-archivist'],
+  'DP-7': ['release-archivist'],
+};
+
+export default {
+  name: 'no-contradictory-instructions',
+
+  async check(skillName, content, ctx) {
+    const issues = [];
+
+    // Check 1: DP references — is the skill referencing DPs it shouldn't, or missing DPs it should?
+    const referencedDPs = new Set();
+    for (const match of content.matchAll(/DP-(\d)/g)) {
+      referencedDPs.add(`DP-${match[1]}`);
+    }
+
+    for (const [dp, skills] of Object.entries(DP_SKILL_MAP)) {
+      if (skills.includes(skillName) && !referencedDPs.has(dp)) {
+        issues.push({
+          severity: 'error',
+          message: `${dp} (${DP_NAMES[dp]}) should be referenced in ${skillName} but was not found`,
+        });
+      }
+    }
+
+    // Check 2: "hard gate" / "硬门禁" language — must match decision-points.md
+    if (content.includes('hard gate') || content.includes('硬门禁')) {
+      const dp3Refs = [...content.matchAll(/DP-3/g)];
+      if (dp3Refs.length === 0 && skillName === 'contract-builder') {
+        issues.push({
+          severity: 'warning',
+          message: `${skillName} mentions "hard gate" but does not reference DP-3`,
+        });
+      }
+    }
+
+    // Check 3: If skill says "route to `X`", verify X is a real skill
+    // Only match backtick-quoted routes (explicit skill references), not plain text
+    const routeRefs = [...content.matchAll(/[Rr]oute to `([a-z-]+)`/g)];
+    for (const [, target] of routeRefs) {
+      if (!ctx.skillDirs.includes(target)) {
+        issues.push({
+          severity: 'warning',
+          message: `Routes to \`${target}\` but no such skill exists in skills/`,
+        });
+      }
+    }
+
+    return issues;
+  },
+};

package/scripts/lint/rules/no-redundant-checks.mjs

@@ -0,0 +1,50 @@
+// Rule: no-redundant-checks
+// Detects: Skill-internal validation that duplicates guard checks
+// Detects: Same checklist items repeated across multiple skills
+
+const GUARD_CHECK_DIMENSIONS = [
+  'artifacts-exist', 'schema-valid', 'contract-fresh', 'tasks-complete', 'tests-passing',
+];
+
+const REDUNDANT_PATTERNS = [
+  { pattern: /proposal\.md.*has.*## Why/i, dimension: 'schema-valid' },
+  { pattern: /specs?\/.*valid/i, dimension: 'schema-valid' },
+  { pattern: /contract.*fresh|stale.*contract|contract.*stale/i, dimension: 'contract-fresh' },
+  { pattern: /tasks?.*complete|all.*checked/i, dimension: 'tasks-complete' },
+  { pattern: /tests?.*pass/i, dimension: 'tests-passing' },
+  { pattern: /artifacts?.*exist|file.*present/i, dimension: 'artifacts-exist' },
+];
+
+export default {
+  name: 'no-redundant-checks',
+
+  async check(skillName, content, ctx) {
+    const issues = [];
+
+    // Skills that are expected to do validation (NOT redundant):
+    // - spec-writer: validates artifacts it just created (primary validation)
+    // - guard: this IS the guard system
+    // Redundancy only applies when a skill re-checks what guard already checks
+    const SKILLS_THAT_OWN_VALIDATION = ['spec-writer', 'workflow-start'];
+
+    if (SKILLS_THAT_OWN_VALIDATION.includes(skillName)) {
+      return issues; // These skills legitimately validate
+    }
+
+    // For other skills, flag explicit re-checks of guard dimensions
+    for (const { pattern, dimension } of REDUNDANT_PATTERNS) {
+      if (pattern.test(content)) {
+        // Check if this is the skill's own checklist (allowed) or a duplicated guard check
+        const checklistSection = content.match(/##\s*(?:Self-Review|Quality Gate|Validation|Checklist|检查)/i);
+        if (checklistSection) {
+          issues.push({
+            severity: 'warning',
+            message: `Skill includes "${dimension}" check — guard.mjs already performs this check on transition. Consider referencing guard instead of re-checking.`,
+          });
+        }
+      }
+    }
+
+    return issues;
+  },
+};

package/scripts/lint/rules/token-rules.mjs

@@ -0,0 +1,122 @@
+// Bundle: token-rules
+// Collection of token efficiency lint rules for skill files.
+// Each rule is exported individually; also exported as a default bundle.
+
+const MAX_LINES_PER_SKILL = 250;
+const MAX_CHARS_PER_SKILL = 10000;
+const MAX_EMPHASIS_MARKERS = 30;
+const MAX_IMPORTANT_OCCURRENCES = 3;
+const MAX_CODE_BLOCK_LINES = 15;
+
+function countEmphasisMarkers(content) {
+  return (content.match(/\*\*[^*]+\*\*/g) || []).length;
+}
+
+function countImportant(content) {
+  return (content.match(/\bIMPORTANT\b/g) || []).length;
+}
+
+function countExtremelyImportant(content) {
+  return (content.match(/EXTREMELY_IMPORTANT/g) || []).length;
+}
+
+function countCritical(content) {
+  return (content.match(/\bCRITICAL\b/g) || []).length;
+}
+
+function getCodeBlocks(content) {
+  const blocks = [];
+  const regex = /```[\s\S]*?```/g;
+  let match;
+  while ((match = regex.exec(content)) !== null) {
+    const lines = match[0].split('\n').length;
+    blocks.push({ content: match[0], lines });
+  }
+  return blocks;
+}
+
+/**
+ * Check file line count does not exceed max.
+ * @param {string} _skillName
+ * @param {string} content
+ * @param {object} _ctx
+ * @param {number} [max=250]
+ */
+export async function checkMaxLines(_skillName, content, _ctx, max = MAX_LINES_PER_SKILL) {
+  const lineCount = content.split('\n').length;
+  if (lineCount > max) {
+    return [{ severity: 'error', message: `File has ${lineCount} lines (max: ${max})` }];
+  }
+  return [];
+}
+
+/**
+ * Check file character count does not exceed max.
+ */
+export async function checkMaxChars(_skillName, content, _ctx, max = MAX_CHARS_PER_SKILL) {
+  const charCount = content.length;
+  if (charCount > max) {
+    return [{ severity: 'warning', message: `File has ${charCount} chars (max: ${max})` }];
+  }
+  return [];
+}
+
+/**
+ * Check emphasis markers (**bold**) count does not exceed max.
+ * Also checks for banned markers (EXTREMELY_IMPORTANT, CRITICAL).
+ */
+export async function checkMaxEmphasisMarkers(_skillName, content, _ctx, max = MAX_EMPHASIS_MARKERS) {
+  const issues = [];
+  const emphasis = countEmphasisMarkers(content);
+  if (emphasis > max) {
+    issues.push({ severity: 'warning', message: `File has ${emphasis} emphasis markers (max: ${max})` });
+  }
+  const ei = countExtremelyImportant(content);
+  if (ei > 0) {
+    issues.push({ severity: 'error', message: `File contains EXTREMELY_IMPORTANT (${ei}x) — banned marker` });
+  }
+  const cr = countCritical(content);
+  if (cr > 0) {
+    issues.push({ severity: 'error', message: `File contains CRITICAL (${cr}x) — banned marker` });
+  }
+  const imp = countImportant(content);
+  if (imp > MAX_IMPORTANT_OCCURRENCES) {
+    issues.push({ severity: 'warning', message: `File contains IMPORTANT ${imp}x (max: ${MAX_IMPORTANT_OCCURRENCES})` });
+  }
+  return issues;
+}
+
+/**
+ * Check code blocks do not exceed max lines.
+ */
+export async function checkMaxCodeBlockLength(_skillName, content, _ctx, max = MAX_CODE_BLOCK_LINES) {
+  const issues = [];
+  const blocks = getCodeBlocks(content);
+  blocks.forEach((block, i) => {
+    if (block.lines > max) {
+      issues.push({
+        severity: 'warning',
+        message: `Code block #${i + 1} has ${block.lines} lines (max: ${max})`,
+      });
+    }
+  });
+  return issues;
+}
+
+/**
+ * Bundle: run all token rules and return combined issues.
+ */
+async function checkAll(skillName, content, ctx) {
+  const results = await Promise.all([
+    checkMaxLines(skillName, content, ctx),
+    checkMaxChars(skillName, content, ctx),
+    checkMaxEmphasisMarkers(skillName, content, ctx),
+    checkMaxCodeBlockLength(skillName, content, ctx),
+  ]);
+  return results.flat();
+}
+
+export default {
+  name: 'token-rules',
+  check: checkAll,
+};

package/scripts/review-package

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# Generate a review package: commit list, stat summary, and the net
+# diff with extended context, written to a file the reviewer reads in one
+# call. Using the recorded per-task BASE (not HEAD~1) keeps multi-commit
+# tasks intact.
+#
+# Usage: review-package BASE HEAD [OUTFILE]
+# Default OUTFILE: <repo-root>/.superpowers/sdd/review-<base7>..<head7>.diff
+# (named per range, so a re-review after fixes gets a distinct fresh file).
+set -euo pipefail
+
+if [ $# -lt 2 ] || [ $# -gt 3 ]; then
+  echo "usage: review-package BASE HEAD [OUTFILE]" >&2
+  exit 2
+fi
+
+base=$1
+head=$2
+
+git rev-parse --verify --quiet "$base" >/dev/null || { echo "bad BASE: $base" >&2; exit 2; }
+git rev-parse --verify --quiet "$head" >/dev/null || { echo "bad HEAD: $head" >&2; exit 2; }
+
+if [ $# -eq 3 ]; then
+  out=$3
+else
+  dir="$(cd "$(dirname "$0")" && pwd)/sdd-workspace"
+  out="$dir/review-$(git rev-parse --short "$base")..$(git rev-parse --short "$head").diff"
+fi
+
+{
+  echo "# Review package: ${base}..${head}"
+  echo
+  echo "## Commits"
+  git log --oneline "${base}..${head}"
+  echo
+  echo "## Files changed"
+  git diff --stat "${base}..${head}"
+  echo
+  echo "## Diff"
+  git diff -U10 "${base}..${head}"
+} > "$out"
+
+commits=$(git rev-list --count "${base}..${head}")
+echo "wrote ${out}: ${commits} commit(s), $(wc -c < "$out" | tr -d ' ') bytes"

package/scripts/task-brief

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# Extract one task's full text from an implementation plan into a file the
+# implementer reads in one call, so the task text never has to be pasted
+# through the controller's context.
+#
+# Usage: task-brief PLAN_FILE TASK_NUMBER [OUTFILE]
+# Default OUTFILE: <repo-root>/.superpowers/sdd/task-<N>-brief.md
+# (per worktree; concurrent runs in the same working tree share it).
+set -euo pipefail
+
+if [ $# -lt 2 ] || [ $# -gt 3 ]; then
+  echo "usage: task-brief PLAN_FILE TASK_NUMBER [OUTFILE]" >&2
+  exit 2
+fi
+
+plan=$1
+n=$2
+[ -f "$plan" ] || { echo "no such plan file: $plan" >&2; exit 2; }
+
+if [ $# -eq 3 ]; then
+  out=$3
+else
+  dir="$(cd "$(dirname "$0")" && pwd)/sdd-workspace"
+  out="$dir/task-${n}-brief.md"
+fi
+
+awk -v n="$n" '
+  /^```/ { infence = !infence }
+  !infence && /^#+[ \t]+Task[ \t]+[0-9]+/ {
+    intask = ($0 ~ ("^#+[ \t]+Task[ \t]+" n "([^0-9]|$)"))
+  }
+  intask { print }
+' "$plan" > "$out"
+
+if [ ! -s "$out" ]; then
+  echo "task ${n} not found in ${plan} (no heading matching 'Task ${n}')" >&2
+  exit 3
+fi
+
+echo "wrote ${out}: $(wc -l < "$out" | tr -d ' ') lines"