qa-ai-repo 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pnakhat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# qa-ai-repo
+
+Reusable **QA skills, agents, and MCP servers**, organized by objective and
+installable into any AI coding tool with one command.
+
+```bash
+npx qa-ai-repo list
+npx qa-ai-repo add playwright-e2e
+```
+
+## What it does
+
+Each QA **objective** is a top-level folder containing only the pieces it needs:
+
+```
+playwright-e2e/
+├── objective.json      # title + description (optional)
+├── skills/             # Claude-style SKILL.md skills
+├── agents/             # Claude-style subagent definitions
+└── mcp/                # MCP server definitions (one JSON per server)
+```
+
+The CLI reads an objective and writes each piece into the right place for
+whichever AI tool you target — converting formats where needed:
+
+| Source        | Claude Code                     | Cursor                          | Windsurf                     | Generic          |
+|---------------|---------------------------------|---------------------------------|------------------------------|------------------|
+| `skills/*`    | `.claude/skills/<name>/`        | `.cursor/rules/<name>.mdc`      | `.windsurf/rules/<name>.md`  | `AGENTS.md`      |
+| `agents/*.md` | `.claude/agents/<name>.md`      | `.cursor/rules/<name>.mdc`      | `.windsurf/rules/<name>.md`  | `AGENTS.md`      |
+| `mcp/*.json`  | `.mcp.json` (merged)            | `.cursor/mcp.json` (merged)     | global `mcp_config.json`     | printed to add   |
+
+## Usage
+
+```bash
+npx qa-ai-repo list                              # list objectives
+npx qa-ai-repo add <objective>                   # install into detected tools
+npx qa-ai-repo add <objective> --tool cursor     # target specific tool(s)
+npx qa-ai-repo add <objective> --tool all        # every supported tool
+npx qa-ai-repo add <objective> --dry-run         # preview, write nothing
+npx qa-ai-repo detect                            # show detected tools
+```
+
+`--tool` accepts a comma list of `claude`, `cursor`, `windsurf`, `agents`, or
+`all`. With no `--tool`, the CLI auto-detects tools in the current project
+(`.claude` / `.cursor` / `.windsurf`) and falls back to `claude,cursor`.
+
+MCP servers are **merged** into existing config files, so `add` is safe to run
+repeatedly and across multiple objectives.
+
+## Add a new objective
+
+```bash
+cp -r _template my-objective        # scaffold
+# edit my-objective/objective.json and drop files into skills/ agents/ mcp/
+# remove any of the three folders the objective doesn't use
+npx qa-ai-repo add my-objective     # try it locally
+```
+
+## Local development
+
+```bash
+node bin/qa-ai.js list              # run without publishing
+npm link                            # then `qa-ai list` works anywhere
+```
+
+## Publishing
+
+Bump `version` in `package.json`, then `npm publish`. Objective folders ship
+automatically (see `.npmignore`); no need to enumerate them.

package/_template/README.md

@@ -0,0 +1,20 @@
+# <Objective Name>
+
+> One-line description of the QA objective this folder covers.
+
+## What this objective covers
+Describe the QA goal — e.g. "End-to-end regression for the checkout flow",
+"API contract testing for the payments service", "Flaky-test triage".
+
+## Contents
+
+| Folder | What lives here |
+|--------|-----------------|
+| `skills/` | Reusable skills/prompt workflows for this objective |
+| `agents/` | Agent definitions that carry out this objective |
+| `mcp/`    | MCP server configs/implementations this objective needs |
+
+> Delete any of the folders above that this objective does not use.
+
+## How to use
+Notes on wiring these into Claude Code / your QA workflow.

package/_template/objective.json

@@ -0,0 +1,4 @@
+{
+  "title": "Objective Name",
+  "description": "One-line description of the QA objective this folder covers."
+}

package/bin/qa-ai.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+main(process.argv.slice(2)).catch((err) => {
+  console.error(`\x1b[31merror:\x1b[0m ${err?.message || err}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "qa-ai-repo",
+  "version": "0.1.0",
+  "description": "Install reusable QA skills, agents, and MCP servers into Claude Code, Cursor, Windsurf, and other AI coding tools with one command.",
+  "type": "module",
+  "bin": {
+    "qa-ai": "bin/qa-ai.js",
+    "qa-ai-repo": "bin/qa-ai.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node bin/qa-ai.js",
+    "test": "node --test"
+  },
+  "keywords": [
+    "qa",
+    "testing",
+    "ai",
+    "agents",
+    "skills",
+    "mcp",
+    "claude-code",
+    "cursor",
+    "windsurf",
+    "playwright",
+    "e2e"
+  ],
+  "author": "pnakhat",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pnakhat/qa-ai-repo.git"
+  },
+  "bugs": {
+    "url": "https://github.com/pnakhat/qa-ai-repo/issues"
+  },
+  "homepage": "https://github.com/pnakhat/qa-ai-repo#readme"
+}

package/playwright-e2e/agents/qa-e2e-author.md

@@ -0,0 +1,17 @@
+---
+name: qa-e2e-author
+description: Use to author or extend Playwright end-to-end tests for a user journey. Give it the flow to cover; it produces Page Object Model specs with stable locators and web-first assertions.
+tools: Read, Grep, Glob, Edit, Write, Bash
+---
+
+You are a senior QA automation engineer specializing in Playwright E2E tests.
+
+When asked to cover a user journey:
+1. Inspect the app/routes and existing `tests/` layout before writing anything.
+2. Reuse or create Page Objects under `tests/pages/`; expose intent-level methods.
+3. Write specs under `tests/e2e/` named by journey, each fully isolated.
+4. Use user-facing locators (`getByRole`/`getByLabel`/`getByText`); `getByTestId` only as a fallback.
+5. Assert with web-first, auto-retrying assertions — never `waitForTimeout`.
+6. Run `npx playwright test` for the new spec and iterate until green.
+
+Report: the files you added/changed, the journeys covered, and any gaps you could not test.

package/playwright-e2e/mcp/playwright.json

@@ -0,0 +1,4 @@
+{
+  "command": "npx",
+  "args": ["-y", "@playwright/mcp@latest"]
+}

package/playwright-e2e/objective.json

@@ -0,0 +1,4 @@
+{
+  "title": "Playwright E2E Testing",
+  "description": "Author resilient Playwright end-to-end tests (Page Object Model, fixtures, stable locators) and drive a live browser via the Playwright MCP server."
+}

package/playwright-e2e/skills/playwright-e2e/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: playwright-e2e
+description: Author and maintain resilient Playwright end-to-end tests using the Page Object Model, fixtures, and stable, user-facing locators. Use when writing, reviewing, or debugging Playwright E2E specs.
+---
+
+# Playwright E2E Testing
+
+Write end-to-end tests that survive UI churn and stay fast.
+
+## Locators — prefer user-facing, avoid brittle selectors
+- Prefer `getByRole`, `getByLabel`, `getByPlaceholder`, `getByText` — they mirror how a user finds things.
+- Use `getByTestId` only when no accessible handle exists; keep `data-testid` stable.
+- Never select by CSS/XPath tied to layout or generated class names.
+
+## Page Object Model
+- One class per page/major component under `tests/pages/`.
+- Expose intent-level methods (`login(user)`, `addToCart(sku)`), not raw clicks.
+- Return the next Page Object from navigations so flows read top-to-bottom.
+
+## Waiting — assertions, never sleeps
+- Rely on Playwright's web-first, auto-retrying assertions (`await expect(locator).toBeVisible()`).
+- Never use `page.waitForTimeout()` to "let things settle"; wait for a condition.
+
+## Structure & isolation
+- Each test is independent: set up its own state, no ordering assumptions.
+- Use fixtures for shared setup (authenticated context, seeded data).
+- Keep specs in `tests/e2e/*.spec.ts`; name by user journey, not by page.
+
+## Debugging
+- `npx playwright test --ui` for the time-travel runner.
+- `--trace on` and open `trace.zip` to inspect failures with DOM snapshots.
+- `--headed --debug` to step through with the Inspector.

package/src/cli.js

@@ -0,0 +1,129 @@
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { listObjectives, loadObjective, KINDS } from './registry.js';
+import { install, detectTools, TOOLS } from './install.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+
+const c = {
+  bold: (s) => `\x1b[1m${s}\x1b[0m`,
+  dim: (s) => `\x1b[2m${s}\x1b[0m`,
+  cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+  green: (s) => `\x1b[32m${s}\x1b[0m`,
+};
+
+function parseFlags(args) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--dry-run' || a === '-n') flags.dryRun = true;
+    else if (a === '--tool' || a === '-t') flags.tool = args[++i];
+    else if (a.startsWith('--tool=')) flags.tool = a.slice('--tool='.length);
+    else positional.push(a);
+  }
+  return { flags, positional };
+}
+
+function resolveTools(flag) {
+  if (flag) {
+    const requested = flag.split(',').map((s) => s.trim()).filter(Boolean);
+    if (requested.includes('all')) return { tools: TOOLS, note: '' };
+    for (const t of requested) {
+      if (!TOOLS.includes(t)) throw new Error(`unknown tool "${t}" (known: ${TOOLS.join(', ')}, all)`);
+    }
+    return { tools: requested, note: '' };
+  }
+  const detected = detectTools();
+  if (detected.length) return { tools: detected, note: `auto-detected: ${detected.join(', ')}` };
+  return { tools: ['claude', 'cursor'], note: 'no tool detected — defaulting to claude, cursor (use --tool to override)' };
+}
+
+function cmdList() {
+  const objectives = listObjectives();
+  if (!objectives.length) {
+    console.log('No objectives yet. Add a folder with skills/ agents/ mcp/ under it.');
+    return;
+  }
+  console.log(`\n${c.bold('QA objectives')} ${c.dim('(' + pkg.name + ' v' + pkg.version + ')')}\n`);
+  for (const o of objectives) {
+    console.log(`  ${c.cyan(o.name)}  ${c.dim('— ' + o.title)}`);
+    if (o.description) console.log(`    ${c.dim(o.description)}`);
+    const parts = KINDS
+      .filter((k) => o.contents[k].length)
+      .map((k) => `${o.contents[k].length} ${k}`);
+    console.log(`    ${c.dim(parts.join('  ·  ') || 'empty')}\n`);
+  }
+  console.log(c.dim(`Install with:  npx ${pkg.name} add <objective>\n`));
+}
+
+function cmdDetect() {
+  const detected = detectTools();
+  console.log(detected.length
+    ? `Detected tools in this project: ${c.green(detected.join(', '))}`
+    : 'No AI tools detected in this project (no .claude/.cursor/.windsurf).');
+}
+
+function cmdAdd(positional, flags) {
+  const name = positional[0];
+  if (!name) throw new Error(`missing objective name. Try:  npx ${pkg.name} list`);
+
+  const objective = loadObjective(name);
+  if (!objective) {
+    const available = listObjectives().map((o) => o.name).join(', ');
+    throw new Error(`objective "${name}" not found. Available: ${available || '(none)'}`);
+  }
+
+  const { tools, note } = resolveTools(flags.tool);
+  console.log(`\nInstalling ${c.cyan(objective.name)} into: ${c.bold(tools.join(', '))}`);
+  if (note) console.log(c.dim(note));
+  if (flags.dryRun) console.log(c.dim('(dry run — no files written)'));
+
+  install(objective, tools, { dryRun: flags.dryRun });
+
+  console.log(`\n${flags.dryRun ? c.dim('Dry run complete.') : c.green('Done.')}`);
+}
+
+function help() {
+  console.log(`
+${c.bold(pkg.name)} ${c.dim('v' + pkg.version)}
+${pkg.description}
+
+${c.bold('Usage')}
+  npx ${pkg.name} <command> [options]
+
+${c.bold('Commands')}
+  list                       List available QA objectives
+  add <objective>            Install an objective's skills/agents/mcp
+  detect                     Show which AI tools are detected here
+  help                       Show this help
+
+${c.bold('Options')}
+  -t, --tool <list>          Comma-separated: ${TOOLS.join(', ')}, all
+                             (default: auto-detected, else claude,cursor)
+  -n, --dry-run              Show what would be written without writing
+
+${c.bold('Examples')}
+  npx ${pkg.name} list
+  npx ${pkg.name} add playwright-e2e
+  npx ${pkg.name} add playwright-e2e --tool cursor,claude
+  npx ${pkg.name} add playwright-e2e --tool all --dry-run
+`);
+}
+
+export async function main(argv) {
+  const { flags, positional } = parseFlags(argv);
+  const cmd = positional.shift();
+
+  if (flags.version || cmd === '--version') return void console.log(pkg.version);
+  switch (cmd) {
+    case 'list': case 'ls': return cmdList();
+    case 'add': case 'install': return cmdAdd(positional, flags);
+    case 'detect': return cmdDetect();
+    case undefined: case 'help': case '--help': case '-h': return help();
+    default:
+      throw new Error(`unknown command "${cmd}". Run:  npx ${pkg.name} help`);
+  }
+}

package/src/install.js

@@ -0,0 +1,214 @@
+// Installs an objective's skills/agents/mcp into a target AI tool by writing
+// the files each tool expects. All writes are relative to process.cwd() (the
+// user's project), except Windsurf's MCP config which is global.
+
+import {
+  existsSync, readFileSync, writeFileSync, mkdirSync, cpSync,
+} from 'node:fs';
+import { join, dirname, basename } from 'node:path';
+import { homedir } from 'node:os';
+import { KINDS } from './registry.js';
+
+const c = {
+  dim: (s) => `\x1b[2m${s}\x1b[0m`,
+  green: (s) => `\x1b[32m${s}\x1b[0m`,
+  yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+  cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+};
+
+// ---- small helpers -------------------------------------------------------
+
+function parseFrontmatter(md) {
+  const m = md.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!m) return { data: {}, body: md };
+  const data = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (kv) data[kv[1]] = kv[2].trim().replace(/^["']|["']$/g, '');
+  }
+  return { data, body: m[2] };
+}
+
+function toMdc(data, body) {
+  const desc = (data.description || '').replace(/\n/g, ' ');
+  return `---\ndescription: ${desc}\nglobs:\nalwaysApply: false\n---\n\n${body.trim()}\n`;
+}
+
+// ---- write primitives ----------------------------------------------------
+
+function ensureWrite(ctx, absPath, content) {
+  const rel = relForLog(absPath);
+  if (ctx.dryRun) {
+    ctx.log(`  ${c.yellow('would write')} ${rel}`);
+    return;
+  }
+  mkdirSync(dirname(absPath), { recursive: true });
+  writeFileSync(absPath, content);
+  ctx.log(`  ${c.green('wrote')}       ${rel}`);
+}
+
+function copyDir(ctx, src, dest) {
+  const rel = relForLog(dest);
+  if (ctx.dryRun) {
+    ctx.log(`  ${c.yellow('would copy')}  ${rel}${'/'}`);
+    return;
+  }
+  mkdirSync(dirname(dest), { recursive: true });
+  cpSync(src, dest, { recursive: true });
+  ctx.log(`  ${c.green('copied')}      ${rel}/`);
+}
+
+function mergeMcp(ctx, targetPath, serverName, serverDef) {
+  let config = { mcpServers: {} };
+  if (existsSync(targetPath)) {
+    try {
+      config = JSON.parse(readFileSync(targetPath, 'utf8'));
+    } catch {
+      throw new Error(`${targetPath} exists but is not valid JSON; fix or remove it first`);
+    }
+  }
+  config.mcpServers = config.mcpServers || {};
+  const existed = Boolean(config.mcpServers[serverName]);
+  config.mcpServers[serverName] = serverDef;
+
+  const rel = relForLog(targetPath);
+  const verb = existed ? 'updated mcp' : 'added mcp';
+  if (ctx.dryRun) {
+    ctx.log(`  ${c.yellow('would ' + verb)} "${serverName}" -> ${rel}`);
+    return;
+  }
+  mkdirSync(dirname(targetPath), { recursive: true });
+  writeFileSync(targetPath, JSON.stringify(config, null, 2) + '\n');
+  ctx.log(`  ${c.green(verb)}   "${serverName}" -> ${rel}`);
+}
+
+function relForLog(abs) {
+  const cwd = process.cwd();
+  return abs.startsWith(cwd) ? abs.slice(cwd.length + 1) : abs;
+}
+
+// ---- tool adapters -------------------------------------------------------
+// Each adapter maps the three kinds into the files a given tool consumes.
+
+function readSkill(objective, skillName) {
+  const skillMd = join(objective.dir, 'skills', skillName, 'SKILL.md');
+  const raw = existsSync(skillMd) ? readFileSync(skillMd, 'utf8') : '';
+  const { data, body } = parseFrontmatter(raw);
+  return { skillMd, raw, data, body };
+}
+
+const adapters = {
+  claude: {
+    label: 'Claude Code',
+    skill(ctx, objective, skillName) {
+      copyDir(ctx, join(objective.dir, 'skills', skillName), join(ctx.cwd, '.claude', 'skills', skillName));
+    },
+    agent(ctx, objective, agentFile) {
+      const src = join(objective.dir, 'agents', agentFile);
+      ensureWrite(ctx, join(ctx.cwd, '.claude', 'agents', agentFile), readFileSync(src, 'utf8'));
+    },
+    mcp(ctx, objective, mcpFile) {
+      const name = basename(mcpFile, '.json');
+      const def = JSON.parse(readFileSync(join(objective.dir, 'mcp', mcpFile), 'utf8'));
+      mergeMcp(ctx, join(ctx.cwd, '.mcp.json'), name, def);
+    },
+  },
+
+  cursor: {
+    label: 'Cursor',
+    skill(ctx, objective, skillName) {
+      const { data, body } = readSkill(objective, skillName);
+      ensureWrite(ctx, join(ctx.cwd, '.cursor', 'rules', `${skillName}.mdc`), toMdc(data, body));
+    },
+    agent(ctx, objective, agentFile) {
+      const name = basename(agentFile, '.md');
+      const { data, body } = parseFrontmatter(readFileSync(join(objective.dir, 'agents', agentFile), 'utf8'));
+      ensureWrite(ctx, join(ctx.cwd, '.cursor', 'rules', `${name}.mdc`), toMdc(data, body));
+    },
+    mcp(ctx, objective, mcpFile) {
+      const name = basename(mcpFile, '.json');
+      const def = JSON.parse(readFileSync(join(objective.dir, 'mcp', mcpFile), 'utf8'));
+      mergeMcp(ctx, join(ctx.cwd, '.cursor', 'mcp.json'), name, def);
+    },
+  },
+
+  windsurf: {
+    label: 'Windsurf',
+    skill(ctx, objective, skillName) {
+      const { data, body } = readSkill(objective, skillName);
+      const md = `# ${data.name || skillName}\n\n${data.description || ''}\n\n${body.trim()}\n`;
+      ensureWrite(ctx, join(ctx.cwd, '.windsurf', 'rules', `${skillName}.md`), md);
+    },
+    agent(ctx, objective, agentFile) {
+      const name = basename(agentFile, '.md');
+      const { data, body } = parseFrontmatter(readFileSync(join(objective.dir, 'agents', agentFile), 'utf8'));
+      const md = `# ${data.name || name}\n\n${data.description || ''}\n\n${body.trim()}\n`;
+      ensureWrite(ctx, join(ctx.cwd, '.windsurf', 'rules', `${name}.md`), md);
+    },
+    mcp(ctx, objective, mcpFile) {
+      const name = basename(mcpFile, '.json');
+      const def = JSON.parse(readFileSync(join(objective.dir, 'mcp', mcpFile), 'utf8'));
+      // Windsurf reads a single global MCP config file.
+      mergeMcp(ctx, join(homedir(), '.codeium', 'windsurf', 'mcp_config.json'), name, def);
+    },
+  },
+
+  agents: {
+    label: 'AGENTS.md (generic)',
+    skill(ctx, objective, skillName) {
+      const { data, body } = readSkill(objective, skillName);
+      appendAgentsMd(ctx, data.name || skillName, data.description, body);
+    },
+    agent(ctx, objective, agentFile) {
+      const name = basename(agentFile, '.md');
+      const { data, body } = parseFrontmatter(readFileSync(join(objective.dir, 'agents', agentFile), 'utf8'));
+      appendAgentsMd(ctx, data.name || name, data.description, body);
+    },
+    mcp(ctx, objective, mcpFile) {
+      const name = basename(mcpFile, '.json');
+      const def = readFileSync(join(objective.dir, 'mcp', mcpFile), 'utf8').trim();
+      ctx.log(`  ${c.yellow('mcp (manual)')} add "${name}" to your tool's MCP config:`);
+      ctx.log(c.dim(def.split('\n').map((l) => '      ' + l).join('\n')));
+    },
+  },
+};
+
+function appendAgentsMd(ctx, name, description, body) {
+  const target = join(ctx.cwd, 'AGENTS.md');
+  const heading = `## ${name}`;
+  const section = `${heading}\n\n${description ? description + '\n\n' : ''}${body.trim()}\n`;
+  let existing = existsSync(target) ? readFileSync(target, 'utf8') : '# AGENTS.md\n\n';
+  if (existing.includes(heading)) {
+    ctx.log(`  ${c.dim('skip')}        AGENTS.md already has "${name}"`);
+    return;
+  }
+  ensureWrite(ctx, target, existing.replace(/\s*$/, '\n\n') + section);
+}
+
+export const TOOLS = Object.keys(adapters);
+
+// ---- tool detection ------------------------------------------------------
+
+export function detectTools(cwd = process.cwd()) {
+  const found = [];
+  if (existsSync(join(cwd, '.claude')) || existsSync(join(cwd, '.mcp.json')) || existsSync(join(cwd, 'CLAUDE.md'))) found.push('claude');
+  if (existsSync(join(cwd, '.cursor')) || existsSync(join(cwd, '.cursorrules'))) found.push('cursor');
+  if (existsSync(join(cwd, '.windsurf'))) found.push('windsurf');
+  return found;
+}
+
+// ---- orchestration -------------------------------------------------------
+
+export function install(objective, tools, { dryRun = false, cwd = process.cwd(), log = console.log } = {}) {
+  const ctx = { dryRun, cwd, log };
+  for (const tool of tools) {
+    const adapter = adapters[tool];
+    if (!adapter) throw new Error(`unknown tool "${tool}" (known: ${TOOLS.join(', ')})`);
+    log(`\n${c.cyan('▸ ' + adapter.label)}`);
+    for (const kind of KINDS) {
+      for (const item of objective.contents[kind]) {
+        adapter[kind === 'skills' ? 'skill' : kind === 'agents' ? 'agent' : 'mcp'](ctx, objective, item);
+      }
+    }
+  }
+}

package/src/registry.js

@@ -0,0 +1,68 @@
+// Discovers "objectives" — top-level folders in this repo that contain any of
+// skills/ agents/ mcp/. The package ships its objective folders at the repo
+// root (siblings of bin/ and src/), so we scan REPO_ROOT and skip reserved and
+// underscore-prefixed names (like _template).
+
+import { readdirSync, existsSync, readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export const REPO_ROOT = join(__dirname, '..');
+
+const RESERVED = new Set([
+  'bin', 'src', 'node_modules', 'scripts', 'test', 'tests', 'coverage',
+]);
+
+export const KINDS = ['skills', 'agents', 'mcp'];
+
+function isReserved(name) {
+  return RESERVED.has(name) || name.startsWith('.') || name.startsWith('_');
+}
+
+export function loadObjective(name) {
+  const dir = join(REPO_ROOT, name);
+  if (!existsSync(dir)) return null;
+
+  const contents = {};
+  let hasAny = false;
+  for (const kind of KINDS) {
+    const kdir = join(dir, kind);
+    if (existsSync(kdir)) {
+      contents[kind] = readdirSync(kdir, { withFileTypes: true })
+        .filter((e) => !e.name.startsWith('.'))
+        .map((e) => e.name);
+      if (contents[kind].length) hasAny = true;
+    } else {
+      contents[kind] = [];
+    }
+  }
+
+  const metaPath = join(dir, 'objective.json');
+  let meta = {};
+  if (existsSync(metaPath)) {
+    try {
+      meta = JSON.parse(readFileSync(metaPath, 'utf8'));
+    } catch {
+      /* ignore malformed metadata */
+    }
+  }
+
+  if (!hasAny && !existsSync(metaPath)) return null;
+
+  return {
+    name,
+    dir,
+    title: meta.title || name,
+    description: meta.description || '',
+    contents,
+  };
+}
+
+export function listObjectives() {
+  return readdirSync(REPO_ROOT, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && !isReserved(d.name))
+    .map((d) => loadObjective(d.name))
+    .filter(Boolean)
+    .sort((a, b) => a.name.localeCompare(b.name));
+}