agentic-skill-mill 1.0.3

package/dist/index.js

@@ -0,0 +1,13 @@
+// Core domain exports
+export { validateManifest } from './core/validate-manifest.js';
+export { validateSkill } from './core/validate-skill.js';
+export { listProject } from './core/list-project.js';
+export { scaffold } from './core/scaffold.js';
+export { checkExports } from './core/check-exports.js';
+// Cache exports
+export { CacheManager } from './cache/cache-manager.js';
+// Error exports
+export { AppError, NotFoundError, CommandError, CacheError, ConfigError, } from './errors/types.js';
+// CLI exports
+export { OutputFormatter } from './cli/output-formatter.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sBAAsB;AACtB,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAG/D,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAGzD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAGrD,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAG9C,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAGvD,gBAAgB;AAChB,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAGxD,gBAAgB;AAChB,OAAO,EACL,QAAQ,EACR,aAAa,EACb,YAAY,EACZ,UAAU,EACV,WAAW,GACZ,MAAM,mBAAmB,CAAC;AAE3B,cAAc;AACd,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "agentic-skill-mill",
+  "version": "1.0.3",
+  "description": "Forge and refine agent skill projects -- fragment-composed skills compiled to 7 IDE targets with a companion CLI",
+  "type": "module",
+  "bin": {
+    "skillmill": "dist/cli/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "skill",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src",
+    "typecheck": "tsc --noEmit",
+    "setup": "bash install.sh",
+    "setup:all": "bash install.sh --all",
+    "install-skills": "bash install.sh --skills-only",
+    "uninstall-skills": "bash install.sh --uninstall",
+    "compile": "node skill/build/compile.mjs",
+    "compile:validate": "node skill/build/compile.mjs --validate",
+    "compile:watch": "node skill/build/compile.mjs --watch"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^11.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "@typescript-eslint/eslint-plugin": "^8.58.0",
+    "@typescript-eslint/parser": "^8.58.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "eslint": "^8.57.0",
+    "typescript": "^5.3.0",
+    "vitest": "^4.1.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skill/build/compile.mjs

@@ -0,0 +1,385 @@
+#!/usr/bin/env node
+
+/**
+ * Skill compiler: resolves {{include:...}} markers, compiles to IDE-specific
+ * targets, and validates the output.
+ *
+ * This compiler is the core of the fragment-composition architecture.
+ * It is intentionally a single self-contained file with no runtime
+ * dependencies beyond Node.js builtins.
+ *
+ * Usage:
+ *   node skill/build/compile.mjs                        # compile all
+ *   node skill/build/compile.mjs --targets claude,cursor # specific targets
+ *   node skill/build/compile.mjs --validate              # validate only
+ *   node skill/build/compile.mjs --watch                 # recompile on change
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, rmSync, readdirSync, statSync, existsSync, watch as fsWatch } from 'node:fs';
+import { join, dirname, resolve, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const SKILL_ROOT = resolve(__dirname, '..');
+const PROJECT_ROOT = resolve(SKILL_ROOT, '..');
+const FRAGMENTS_DIR = join(SKILL_ROOT, 'fragments');
+const COMPILED_DIR = join(PROJECT_ROOT, 'compiled');
+const MANIFEST_PATH = join(__dirname, 'manifest.json');
+
+const MANAGED_BY = 'managed_by: agentic-skill-mill';
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+const args = process.argv.slice(2);
+const validateOnly = args.includes('--validate');
+const watchMode = args.includes('--watch');
+const targetFlag = args.find(a => a.startsWith('--targets=')) || args[args.indexOf('--targets') + 1];
+const requestedTargets = targetFlag ? targetFlag.replace('--targets=', '').split(',').map(t => t.trim()) : null;
+
+// ---------------------------------------------------------------------------
+// Load manifest
+// ---------------------------------------------------------------------------
+
+const manifest = JSON.parse(readFileSync(MANIFEST_PATH, 'utf-8'));
+const targets = requestedTargets || manifest.targets;
+
+// ---------------------------------------------------------------------------
+// Step 1: Resolve includes
+// ---------------------------------------------------------------------------
+
+function resolveIncludes(content, sourceFile) {
+  const includePattern = /\{\{include:([^}]+)\}\}/g;
+  const errors = [];
+
+  const resolved = content.replace(includePattern, (match, fragmentPath) => {
+    const fullPath = join(FRAGMENTS_DIR, fragmentPath.trim());
+    if (!existsSync(fullPath)) {
+      errors.push(`Missing fragment: ${fragmentPath} (referenced in ${sourceFile})`);
+      return match;
+    }
+    const fragmentContent = readFileSync(fullPath, 'utf-8').trimEnd();
+
+    if (/\{\{include:[^}]+\}\}/.test(fragmentContent)) {
+      errors.push(`Nested include in fragment: ${fragmentPath} (referenced in ${sourceFile}). Only one level of includes is supported.`);
+      return match;
+    }
+
+    return fragmentContent;
+  });
+
+  return { resolved, errors };
+}
+
+// ---------------------------------------------------------------------------
+// Step 2: Frontmatter transforms
+// ---------------------------------------------------------------------------
+
+function extractFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!match) return { frontmatter: {}, body: content };
+
+  const fm = {};
+  for (const line of match[1].split('\n')) {
+    const idx = line.indexOf(':');
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    let val = line.slice(idx + 1).trim();
+    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+      val = val.slice(1, -1);
+    }
+    fm[key] = val;
+  }
+
+  return { frontmatter: fm, body: match[2] };
+}
+
+function buildFrontmatter(fields) {
+  const lines = ['---'];
+  lines.push(MANAGED_BY);
+  for (const [k, v] of Object.entries(fields)) {
+    if (v !== null && typeof v === 'object' && !Array.isArray(v)) {
+      lines.push(`${k}:`);
+      for (const [nk, nv] of Object.entries(v)) {
+        lines.push(`  ${nk}: ${nv}`);
+      }
+    } else if (typeof v === 'string' && (v.includes(':') || v.includes('"') || v.includes("'"))) {
+      lines.push(`${k}: "${v.replace(/"/g, '\\"')}"`);
+    } else {
+      lines.push(`${k}: ${v}`);
+    }
+  }
+  lines.push('---');
+  return lines.join('\n');
+}
+
+function compileTarget(targetName, skillName, resolvedContent) {
+  const { frontmatter: fm, body } = extractFrontmatter(resolvedContent);
+  const desc = fm.description || fm.name || skillName;
+
+  function injectMarker(content) {
+    return content.replace(/^---\n/, `---\n${MANAGED_BY}\n`);
+  }
+
+  switch (targetName) {
+    case 'claude':
+      return injectMarker(resolvedContent);
+
+    case 'cursor-rules':
+      return buildFrontmatter({ description: `"${desc}"`, alwaysApply: 'false' }) + '\n' + body;
+
+    case 'cursor-skills':
+      return injectMarker(resolvedContent);
+
+    case 'windsurf-rules':
+      return buildFrontmatter({ trigger: 'manual', description: `"${desc}"` }) + '\n' + body;
+
+    case 'windsurf-skills':
+      return injectMarker(resolvedContent);
+
+    case 'opencode':
+      return buildFrontmatter({
+        mode: 'subagent',
+        description: `"${desc}"`,
+        permission: { bash: 'allow', edit: 'allow', webfetch: 'allow' }
+      }) + '\n' + body;
+
+    case 'codex':
+      return injectMarker(resolvedContent);
+
+    default:
+      throw new Error(`Unknown target: ${targetName}`);
+  }
+}
+
+function getOutputPath(targetName, skillName) {
+  switch (targetName) {
+    case 'claude':
+      return join(COMPILED_DIR, 'claude', skillName, 'SKILL.md');
+    case 'cursor-rules':
+      return join(COMPILED_DIR, 'cursor', 'rules', `${skillName}.mdc`);
+    case 'cursor-skills':
+      return join(COMPILED_DIR, 'cursor', 'skills', skillName, 'SKILL.md');
+    case 'windsurf-rules':
+      return join(COMPILED_DIR, 'windsurf', 'rules', `${skillName}.md`);
+    case 'windsurf-skills':
+      return join(COMPILED_DIR, 'windsurf', 'skills', skillName, 'SKILL.md');
+    case 'opencode':
+      return join(COMPILED_DIR, 'opencode', `${skillName}.md`);
+    case 'codex':
+      return join(COMPILED_DIR, 'codex', skillName, 'SKILL.md');
+    default:
+      throw new Error(`Unknown target: ${targetName}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Step 3: Validation
+// ---------------------------------------------------------------------------
+
+function validateNaming(skillName) {
+  const errors = [];
+  if (skillName !== skillName.toLowerCase()) {
+    errors.push(`Skill name not lowercase: ${skillName}`);
+  }
+  if (/\s/.test(skillName)) {
+    errors.push(`Skill name contains spaces: ${skillName}`);
+  }
+  for (const suffix of manifest.naming_rules.forbidden_suffixes) {
+    if (skillName.endsWith(`-${suffix}`) || skillName === suffix) {
+      errors.push(`Skill name uses forbidden suffix '${suffix}': ${skillName}`);
+    }
+  }
+  return errors;
+}
+
+function validateResolved(content, skillName) {
+  const errors = [];
+  const unresolvedPattern = /\{\{include:[^}]+\}\}/g;
+  const matches = content.match(unresolvedPattern);
+  if (matches) {
+    for (const m of matches) {
+      errors.push(`Unresolved include in ${skillName}: ${m}`);
+    }
+  }
+  return errors;
+}
+
+function validateFrontmatter(content, skillName) {
+  const errors = [];
+  if (!content.startsWith('---\n')) {
+    errors.push(`Missing frontmatter in ${skillName}`);
+  }
+  return errors;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  const allErrors = [];
+  const stats = { skills: 0, targets: 0, fragments: 0 };
+
+  function countFiles(dir) {
+    let count = 0;
+    if (!existsSync(dir)) return 0;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) count += countFiles(join(dir, entry.name));
+      else if (entry.name.endsWith('.md')) count++;
+    }
+    return count;
+  }
+  stats.fragments = countFiles(FRAGMENTS_DIR);
+
+  if (!validateOnly) {
+    if (existsSync(COMPILED_DIR)) {
+      rmSync(COMPILED_DIR, { recursive: true });
+    }
+  }
+
+  for (const [skillName, skillDef] of Object.entries(manifest.skills)) {
+    stats.skills++;
+
+    allErrors.push(...validateNaming(skillName));
+
+    const sourcePath = join(SKILL_ROOT, skillDef.source);
+    if (!existsSync(sourcePath)) {
+      allErrors.push(`Missing source: ${skillDef.source} (skill: ${skillName})`);
+      continue;
+    }
+    const source = readFileSync(sourcePath, 'utf-8');
+
+    const { resolved, errors: includeErrors } = resolveIncludes(source, skillDef.source);
+    allErrors.push(...includeErrors);
+
+    allErrors.push(...validateResolved(resolved, skillName));
+    allErrors.push(...validateFrontmatter(resolved, skillName));
+
+    if (validateOnly) continue;
+
+    for (const target of targets) {
+      stats.targets++;
+      const compiled = compileTarget(target, skillName, resolved);
+      const outPath = getOutputPath(target, skillName);
+
+      mkdirSync(dirname(outPath), { recursive: true });
+      writeFileSync(outPath, compiled);
+    }
+  }
+
+  // Cross-validate manifest fragment declarations against actual includes
+  for (const [skillName, skillDef] of Object.entries(manifest.skills)) {
+    const sourcePath = join(SKILL_ROOT, skillDef.source);
+    if (!existsSync(sourcePath)) continue;
+    const source = readFileSync(sourcePath, 'utf-8');
+    const includePattern = /\{\{include:([^}]+)\}\}/g;
+    const actualIncludes = new Set();
+    let match;
+    while ((match = includePattern.exec(source)) !== null) {
+      actualIncludes.add(match[1].trim());
+    }
+    const declared = new Set(skillDef.fragments);
+
+    for (const inc of actualIncludes) {
+      if (!declared.has(inc)) {
+        allErrors.push(`Undeclared fragment in ${skillName}: ${inc} (found in source but not in manifest.fragments)`);
+      }
+    }
+    for (const dec of declared) {
+      if (!actualIncludes.has(dec)) {
+        allErrors.push(`Unused declared fragment in ${skillName}: ${dec} (in manifest.fragments but not in source)`);
+      }
+    }
+  }
+
+  // Staleness check (validate-only mode)
+  if (validateOnly) {
+    for (const [skillName, skillDef] of Object.entries(manifest.skills)) {
+      const sourcePath = join(SKILL_ROOT, skillDef.source);
+      if (!existsSync(sourcePath)) continue;
+      const sourceMtime = statSync(sourcePath).mtimeMs;
+
+      let newestInput = sourceMtime;
+      for (const frag of skillDef.fragments) {
+        const fragPath = join(FRAGMENTS_DIR, frag);
+        if (existsSync(fragPath)) {
+          newestInput = Math.max(newestInput, statSync(fragPath).mtimeMs);
+        }
+      }
+      newestInput = Math.max(newestInput, statSync(MANIFEST_PATH).mtimeMs);
+
+      for (const target of manifest.targets) {
+        const outPath = getOutputPath(target, skillName);
+        if (!existsSync(outPath)) {
+          allErrors.push(`Missing compiled output: ${relative(PROJECT_ROOT, outPath)} (run npm run compile)`);
+        } else {
+          const outMtime = statSync(outPath).mtimeMs;
+          if (outMtime < newestInput) {
+            allErrors.push(`Stale compiled output: ${relative(PROJECT_ROOT, outPath)} is older than its source or fragments (run npm run compile)`);
+          }
+        }
+      }
+    }
+  }
+
+  if (allErrors.length > 0) {
+    console.error('\n==> Errors:');
+    for (const e of allErrors) {
+      console.error(`  ERROR: ${e}`);
+    }
+    console.error(`\n${allErrors.length} error(s) found.`);
+    process.exit(1);
+  }
+
+  if (validateOnly) {
+    console.log(`==> Validation passed. ${stats.skills} skills, ${stats.fragments} fragments.`);
+  } else {
+    console.log(`==> Compiled ${stats.skills} skills to ${targets.length} targets (${stats.targets} files). ${stats.fragments} fragments resolved.`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Watch mode
+// ---------------------------------------------------------------------------
+
+function startWatch() {
+  console.log('==> Watch mode: compiling on change...');
+  console.log(`    Watching: skill/fragments/, skill/skills/, skill/build/manifest.json`);
+  console.log('    Press Ctrl+C to stop.\n');
+
+  main();
+
+  let debounceTimer = null;
+  const recompile = (eventType, filename) => {
+    if (debounceTimer) clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => {
+      console.log(`\n--- Change detected${filename ? `: ${filename}` : ''} ---`);
+      try {
+        main();
+      } catch (e) {
+        console.error(`Compile error: ${e.message}`);
+      }
+    }, 300);
+  };
+
+  const watchDirs = [
+    FRAGMENTS_DIR,
+    join(SKILL_ROOT, 'skills'),
+  ];
+
+  for (const dir of watchDirs) {
+    if (existsSync(dir)) {
+      fsWatch(dir, { recursive: true }, recompile);
+    }
+  }
+  fsWatch(MANIFEST_PATH, recompile);
+}
+
+if (watchMode) {
+  startWatch();
+} else {
+  main();
+}

package/skill/build/manifest.json

@@ -0,0 +1,29 @@
+{
+  "targets": [
+    "claude",
+    "cursor-rules",
+    "cursor-skills",
+    "windsurf-rules",
+    "windsurf-skills",
+    "opencode",
+    "codex"
+  ],
+  "skills": {
+    "agentic-skill-mill": {
+      "source": "skills/agentic-skill-mill/agentic-skill-mill.md",
+      "fragments": [
+        "meta/architecture-overview.md",
+        "meta/research-to-code.md",
+        "meta/core-module-pattern.md",
+        "meta/cli-command-pattern.md",
+        "meta/fragment-composition.md",
+        "meta/rename-workflow.md"
+      ]
+    }
+  },
+  "naming_rules": {
+    "case": "lowercase",
+    "separator": "-",
+    "forbidden_suffixes": ["final", "new", "latest", "v2"]
+  }
+}

package/skill/fragments/meta/architecture-overview.md

@@ -0,0 +1,37 @@
+The skill-system-template architecture has two halves that meet at the agent:
+
+```
+Skills (what to do)          CLI Companion (tools to do it with)
+  skill/skills/*.md            src/cli/commands/*.ts
+  skill/fragments/*.md         src/core/*.ts
+          |                            |
+          v                            v
+  compiled/ (7 IDE formats)    dist/ (npm link -> global CLI)
+          |                            |
+          +---------> Agent <----------+
+```
+
+**Skills** are step-by-step runbooks in markdown with YAML frontmatter. They tell the agent *what* to do. Skills reference the CLI by name so the agent can invoke structured commands.
+
+**Fragments** are shared knowledge blocks included by multiple skills via include markers (`\{\{include:path\}\}`). Edit a fragment once, recompile, and every skill that includes it gets the update. Fragments have no frontmatter.
+
+**The compiler** (`skill/build/compile.mjs`) resolves includes, applies IDE-specific frontmatter transforms, and writes to `compiled/` with one subdirectory per target. It validates naming rules, checks for unresolved includes, and cross-validates manifest declarations against actual includes in source files.
+
+**The CLI companion** is a TypeScript package with:
+- `src/core/` — Pure logic modules with typed interfaces
+- `src/cli/commands/` — Thin command wrappers that delegate to core modules
+- `src/cli/index.ts` — Commander.js entry point wiring all commands
+- `src/cli/output-formatter.ts` — JSON, table, and key-value formatters
+- `src/errors/types.ts` — Typed error hierarchy (AppError, NotFoundError, etc.)
+- `src/cache/cache-manager.ts` — Two-tier cache (memory + disk) with TTL
+
+**The installer** (`install.sh`) builds the CLI, compiles skills, and copies compiled outputs to IDE-specific directories (~/.claude/skills, ~/.cursor/rules, etc.) with marker-based stale file cleanup. The installer uses `set -e` for fail-fast behavior. Any function that uses an early-exit guard (`[[ -d ... ]] || return`, `[[ -z ... ]] && return`) **must** use `return 0`, never bare `return`. Bare `return` inherits the exit code of the last command, which for a failed conditional test is 1 -- and `set -e` treats that as a script-terminating failure with no error message.
+
+### Key files to modify when augmenting a project
+
+| What | File(s) |
+|------|---------|
+| Add a CLI command | `src/core/<name>.ts`, `src/cli/commands/<name>.ts`, `src/cli/index.ts`, `src/index.ts` |
+| Add a fragment | `skill/fragments/<category>/<name>.md`, `skill/build/manifest.json`, skill source |
+| Add a skill | `skill/skills/<name>/<name>.md`, `skill/build/manifest.json`, `install.sh` SKILLS array |
+| Rename the project | See the rename workflow |

package/skill/fragments/meta/cli-command-pattern.md

@@ -0,0 +1,83 @@
+### Command wrapper pattern
+
+Each CLI command lives in `src/cli/commands/<name>.ts` as a thin wrapper:
+
+```typescript
+// src/cli/commands/<name>.ts
+import { doThing, type ThingOptions, type ThingResult } from '../../core/<name>.js';
+
+export interface ThingCommandOptions extends ThingOptions {
+  json: boolean;
+}
+
+export async function thingCommand(
+  options: ThingCommandOptions,
+): Promise<ThingResult> {
+  return doThing({
+    param: options.param,
+  });
+}
+```
+
+**Rules for command wrappers:**
+- Import from core module using `.js` extension (ESM resolution)
+- Extend the core options interface with `json: boolean`
+- Delegate immediately to the core function -- no business logic in the wrapper
+- Return the core result type -- formatting happens in `index.ts`
+
+### Wiring into the CLI entry point
+
+Add the command in `src/cli/index.ts`:
+
+```typescript
+import { thingCommand } from './commands/<name>.js';
+
+program
+  .command('<name>')
+  .description('One-line description of what this does')
+  .argument('<required>', 'Description of required positional arg')   // if needed
+  .requiredOption('--param <value>', 'Required option description')   // if needed
+  .option('--json', 'Output as JSON', false)
+  .option('--optional <value>', 'Optional flag', 'default')
+  .action(async (positionalArg, options) => {
+    try {
+      const result = await thingCommand({
+        param: positionalArg,
+        json: options.json,
+      });
+
+      if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        // Human-readable output using chalk
+        console.log();
+        console.log(chalk.bold('Title'));
+        for (const item of result.data) {
+          console.log(`  ${item}`);
+        }
+        console.log();
+      }
+    } catch (error) {
+      handleError(error);
+    }
+  });
+```
+
+**Rules for CLI wiring:**
+- Every command supports `--json` for structured agent consumption
+- Human-readable output uses chalk for color and formatting
+- Errors funnel through the shared `handleError()` function
+- Use `.argument()` for required positional args, `.requiredOption()` for mandatory flags
+- Parse string options to their real types (parseInt, parseFloat) in the action handler
+- Comma-separated list options get `.split(',').map(s => s.trim())` in the action handler
+
+### Updating exports
+
+After adding a new core module, export its public API from `src/index.ts`:
+
+```typescript
+export { doThing } from './core/<name>.js';
+export type { ThingOptions, ThingResult } from './core/<name>.js';
+```
+
+This allows the package to be consumed as a library, not just a CLI.

package/skill/fragments/meta/core-module-pattern.md

@@ -0,0 +1,38 @@
+Every CLI command starts as a **core module** in `src/core/`. Core modules contain pure domain logic with no CLI concerns (no chalk, no console.log, no process.exit). This separation lets the logic be consumed as a library, tested independently, and composed by multiple commands.
+
+### Structure of a core module
+
+```typescript
+// src/core/<name>.ts
+
+/** Input options -- everything the caller needs to provide */
+export interface <Name>Options {
+  requiredParam: string;
+  optionalParam?: number;
+}
+
+/** Output result -- everything the caller gets back */
+export interface <Name>Result {
+  data: SomeType[];
+  warnings: string[];
+}
+
+/** Pure function: options in, result out. No side effects on stdout. */
+export function <name>(options: <Name>Options): <Name>Result {
+  return { data: [], warnings: [] };
+}
+```
+
+### Rules
+
+- **Export typed interfaces** for both input and output so consumers get autocomplete and type safety
+- **Return structured data**, never print to stdout -- the CLI wrapper decides how to format
+- **Include a `warnings` array** in results when the function can detect non-fatal issues
+- **Use `async` only when needed** (file I/O, network) -- synchronous logic stays synchronous
+- **Throw typed errors** from `src/errors/types.ts` for unrecoverable failures
+- **Keep modules focused** -- one concept per file. A pace calculator doesn't also validate outlines
+- **Accept paths and options, not raw CLI strings** -- parsing belongs in the command wrapper
+
+### Shared parsers
+
+When two or more commands need to parse the same input format, extract a shared parser module. The parser returns a structured type that both consumers work with.