roster-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sshworld
+
+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,96 @@
+# roster
+
+Does your agent earn its context?
+
+## Philosophy
+
+Most agent tooling optimizes personas — tone, role-play, instructions. roster
+starts from a different premise: **structure earns value, not persona**. An
+agent's context is a dependency, and dependencies churn — they overlap,
+route badly, cost tokens, and rot. roster is a static analyzer for your agent
+roster (skills, subagents, tool configs) that surfaces those problems before
+they burn context in production.
+
+## Install
+
+```sh
+npm i -g roster-cli
+```
+
+or run it without installing:
+
+```sh
+npx roster-cli audit <dir>
+```
+
+## Usage
+
+```sh
+roster audit <dir>
+roster audit <dir> --user
+roster audit <dir> --repo owner/name
+roster audit <dir> --html report.html
+```
+
+Full flag surface:
+
+```
+roster audit <dir> [--json] [--html <out>] [--user] [--plugin [name]]
+                    [--repo <owner/name[@ref]>] [--top <n>]
+                    [--fail-above <s>] [--no-fail]
+```
+
+## Rules
+
+| Rule | Description | Status |
+| --- | --- | --- |
+| `overlap` | Detects agents/skills covering the same responsibility | stable |
+| `harness` | Flags harness-incompatible or malformed configs | stable |
+| `routing` | Checks routing/trigger ambiguity between agents | stable |
+| `cost` | Estimates context/token cost of a roster | stable |
+| `fluff` | Flags low-signal, filler instructions | experimental |
+
+## Benchmarks
+
+`roster audit --repo` run against well-known public agent rosters (SHA-pinned,
+reproducible via `scripts/bench.sh`). Full reports: `docs/benchmarks/`.
+
+| roster | agents | top overlap pair (score) | no-tools % | fixed cost (est. tokens/turn) |
+| --- | --- | --- | --- | --- |
+| [msitarzewski/agency-agents](./docs/benchmarks/msitarzewski--agency-agents.md) | 277 | Backend Architect ↔ Backend Architect (0.878) | 93.9% | ~14024 |
+| [wshobson/agents](./docs/benchmarks/wshobson--agents.md) | 691 | api-scaffolding-backend-architect ↔ backend-api-security-backend-architect (1.000) | 97.8% | ~24853 |
+| [contains-studio/agents](./docs/benchmarks/contains-studio--agents.md) | 37 | content-creator ↔ instagram-curator (0.565) | 16.2% | ~8421 |
+
+Several top pairs score at or near 1.000 similarity (e.g. wshobson/agents has
+five pairs at a perfect 1.000) — these are near-duplicate agent files (same
+description/body reused across roles), not incidental topic overlap.
+
+## Use as a Claude Code plugin
+
+roster also ships as a Claude Code plugin — a resident guard instead of a
+one-off report.
+
+Install via the bundled marketplace manifest:
+
+```sh
+/plugin marketplace add sshworld/roster
+/plugin install roster
+```
+
+Once installed:
+
+- **`roster-audit` skill** — triggers when you ask to audit an agent roster
+  (overlap, missing harness/tools, routing ambiguity, cost); runs the bundled
+  CLI and explains how to read the findings.
+- **`roster-drift.sh` hook** (`SessionStart`) — on each session, diffs
+  `.claude/agents/` against a cached snapshot and prints a short advisory if
+  agents were added/removed/changed (`ROSTER_DRIFT_DISABLE=1` to opt out).
+  Advisory only — never blocks a session.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License
+
+[MIT](./LICENSE)

package/dist/cli.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+import { writeFileSync } from 'node:fs';
+import { sources } from './sources/index.js';
+import { rules } from './rules/index.js';
+import { renderers } from './render/index.js';
+const HELP_TEXT = `Usage: roster audit [<dir>] [options]
+
+Options:
+  --json                      Output machine-readable JSON
+  --html <out>                Write an HTML report to <out>
+  --user                      Load agents from the user-level agent directory
+  --plugin [name]             Load agents from the plugin cache
+  --repo <owner/name[@ref]>   Load agents from a GitHub repo
+  --top <n>                   Number of top overlapping pairs to report (default 10)
+  --fail-above <score>        Mark overlap findings above <score> as critical
+  --no-fail                   Always exit 0, even with critical findings
+  --help, -h                  Show this help text
+`;
+function parseArgs(argv) {
+    const result = {
+        json: false,
+        user: false,
+        plugin: false,
+        noFail: false,
+        help: false,
+    };
+    let i = 0;
+    while (i < argv.length) {
+        const arg = argv[i];
+        switch (arg) {
+            case '--help':
+            case '-h':
+                result.help = true;
+                i += 1;
+                break;
+            case '--json':
+                result.json = true;
+                i += 1;
+                break;
+            case '--html':
+                result.html = argv[i + 1];
+                i += 2;
+                break;
+            case '--user':
+                result.user = true;
+                i += 1;
+                break;
+            case '--plugin':
+                result.plugin = true;
+                if (argv[i + 1] && !argv[i + 1].startsWith('--')) {
+                    result.pluginName = argv[i + 1];
+                    i += 2;
+                }
+                else {
+                    i += 1;
+                }
+                break;
+            case '--repo':
+                result.repo = argv[i + 1];
+                i += 2;
+                break;
+            case '--top':
+                result.top = Number(argv[i + 1]);
+                i += 2;
+                break;
+            case '--fail-above':
+                result.failAbove = Number(argv[i + 1]);
+                i += 2;
+                break;
+            case '--no-fail':
+                result.noFail = true;
+                i += 1;
+                break;
+            default:
+                if (result.dir === undefined && !arg.startsWith('--')) {
+                    result.dir = arg;
+                }
+                i += 1;
+                break;
+        }
+    }
+    return result;
+}
+export async function main(argv) {
+    if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
+        console.log(HELP_TEXT);
+        return 0;
+    }
+    const [cmd, ...rest] = argv;
+    if (cmd !== 'audit') {
+        console.error(`unknown command: ${cmd}`);
+        console.error(HELP_TEXT);
+        return 1;
+    }
+    const parsed = parseArgs(rest);
+    if (parsed.help) {
+        console.log(HELP_TEXT);
+        return 0;
+    }
+    // 요청된 소스 전부 수집 — 복수 flag 는 병합 스캔 (출처는 sourceLabel 로 구분)
+    const wanted = [];
+    if (parsed.dir)
+        wanted.push('dir');
+    if (parsed.user)
+        wanted.push('user');
+    if (parsed.plugin)
+        wanted.push('plugin-cache');
+    if (parsed.repo)
+        wanted.push('github');
+    if (wanted.length === 0) {
+        console.error('audit requires a <dir> argument or one of --user / --plugin / --repo');
+        return 1;
+    }
+    let rendererId = 'cli';
+    if (parsed.json)
+        rendererId = 'json';
+    else if (parsed.html !== undefined) {
+        if (!parsed.html) {
+            console.error('--html requires an output file path');
+            return 1;
+        }
+        rendererId = 'html';
+    }
+    const renderer = renderers[rendererId];
+    if (!renderer) {
+        console.error(`unknown renderer: ${rendererId}`);
+        return 1;
+    }
+    if (renderer.stub) {
+        console.error(`not implemented: renderer '${rendererId}'`);
+        return 2;
+    }
+    const agents = [];
+    for (const sourceId of wanted) {
+        const source = sources[sourceId];
+        if (!source) {
+            console.error(`unknown source: ${sourceId}`);
+            return 1;
+        }
+        if (source.stub) {
+            console.error(`not implemented: source '${sourceId}'`);
+            return 2;
+        }
+        agents.push(...(await source.load({ dir: parsed.dir, pluginName: parsed.pluginName, repo: parsed.repo })));
+    }
+    const findings = [];
+    for (const rule of Object.values(rules)) {
+        if (rule.stub)
+            continue;
+        findings.push(...rule.run(agents, { top: parsed.top, failAbove: parsed.failAbove }));
+    }
+    const report = {
+        agents,
+        findings,
+        meta: { sourceLabels: [...new Set(agents.map((a) => a.sourceLabel))] },
+    };
+    const output = renderer.render(report, {});
+    if (rendererId === 'html') {
+        writeFileSync(parsed.html, output);
+        console.log(`HTML report written: ${parsed.html}`);
+    }
+    else {
+        console.log(output);
+    }
+    const hasCritical = findings.some((f) => f.severity === 'critical');
+    if (parsed.noFail)
+        return 0;
+    return hasCritical ? 1 : 0;
+}
+const isDirectRun = process.argv[1] !== undefined && import.meta.url === `file://${process.argv[1]}`;
+if (isDirectRun) {
+    main(process.argv.slice(2)).then((code) => process.exit(code));
+}

package/dist/core/types.js

@@ -0,0 +1,6 @@
+export class NotImplementedError extends Error {
+    constructor(id) {
+        super(`not implemented: ${id}`);
+        this.name = 'NotImplementedError';
+    }
+}

package/dist/parse/agent-md.js

@@ -0,0 +1,57 @@
+import path from 'node:path';
+function splitFrontmatter(raw) {
+    const normalized = raw.replace(/\r\n/g, '\n');
+    if (!normalized.startsWith('---\n') && normalized !== '---') {
+        return { frontmatter: {}, body: normalized };
+    }
+    const closingIndex = normalized.indexOf('\n---', 4);
+    if (closingIndex === -1) {
+        return { frontmatter: {}, body: normalized };
+    }
+    const rawFrontmatter = normalized.slice(4, closingIndex);
+    const afterClose = normalized.slice(closingIndex + 4);
+    const body = afterClose.startsWith('\n') ? afterClose.slice(1) : afterClose;
+    const frontmatter = {};
+    for (const line of rawFrontmatter.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        const sepIndex = trimmed.indexOf(':');
+        if (sepIndex === -1)
+            continue;
+        const key = trimmed.slice(0, sepIndex).trim();
+        const value = trimmed.slice(sepIndex + 1).trim();
+        if (key === 'name' || key === 'description' || key === 'tools' || key === 'model') {
+            frontmatter[key] = value;
+        }
+    }
+    return { frontmatter, body };
+}
+function parseTools(raw) {
+    if (raw === undefined || raw === '')
+        return undefined;
+    let value = raw.trim();
+    if (value.startsWith('[') && value.endsWith(']')) {
+        value = value.slice(1, -1);
+    }
+    const tools = value
+        .split(',')
+        .map((t) => t.trim().replace(/^['"]|['"]$/g, ''))
+        .filter(Boolean);
+    return tools.length > 0 ? tools : undefined;
+}
+function fallbackName(filePath) {
+    return path.basename(filePath, path.extname(filePath));
+}
+export function parseAgentMarkdown(raw, filePath, sourceLabel) {
+    const { frontmatter, body } = splitFrontmatter(raw);
+    return {
+        name: frontmatter.name?.trim() || fallbackName(filePath),
+        description: frontmatter.description?.trim() ?? '',
+        tools: parseTools(frontmatter.tools),
+        model: frontmatter.model?.trim() || undefined,
+        body: body.trim(),
+        sourceLabel,
+        filePath,
+    };
+}

package/dist/render/cli.js

@@ -0,0 +1,28 @@
+export const cliRenderer = {
+    id: 'cli',
+    render(report) {
+        const lines = [];
+        lines.push('Roster Audit Report');
+        lines.push(`Agents scanned: ${report.agents.length}`);
+        lines.push(`Sources: ${report.meta.sourceLabels.join(', ')}`);
+        lines.push('');
+        const overlapFindings = report.findings.filter((f) => f.ruleId === 'overlap');
+        lines.push(`Top overlapping pairs (${overlapFindings.length}):`);
+        if (overlapFindings.length === 0) {
+            lines.push('  (none)');
+        }
+        else {
+            for (const f of overlapFindings) {
+                const [a, b] = f.pair ?? ['?', '?'];
+                const scoreStr = f.score !== undefined ? f.score.toFixed(3) : '?';
+                const tag = f.severity === 'critical' ? ' [CRITICAL]' : '';
+                lines.push(`  ${scoreStr}  ${a} <-> ${b}${tag}`);
+            }
+        }
+        lines.push('');
+        const criticalCount = report.findings.filter((f) => f.severity === 'critical').length;
+        const warningCount = report.findings.filter((f) => f.severity === 'warning').length;
+        lines.push(`Findings: ${report.findings.length} total (${criticalCount} critical, ${warningCount} warning)`);
+        return lines.join('\n');
+    },
+};

package/dist/render/html-styles.js

@@ -0,0 +1,90 @@
+export function htmlStyles() {
+    return `
+    :root {
+      color-scheme: light;
+      --bg: #f7f7f9;
+      --card-bg: #ffffff;
+      --border: #e2e2e8;
+      --text: #1c1c22;
+      --muted: #6b6b76;
+      --accent: #3a5fd9;
+      --critical: #c0392b;
+      --warning: #b7791f;
+      --info: #2c7a4b;
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      padding: 2rem;
+      background: var(--bg);
+      color: var(--text);
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+      line-height: 1.5;
+    }
+    h1, h2, h3 { margin-top: 0; }
+    .card {
+      background: var(--card-bg);
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      padding: 1.25rem 1.5rem;
+      margin-bottom: 1.5rem;
+    }
+    .header-stats {
+      display: flex;
+      gap: 2rem;
+      flex-wrap: wrap;
+    }
+    .stat { display: flex; flex-direction: column; }
+    .stat .value { font-size: 1.75rem; font-weight: 700; }
+    .stat .label { font-size: 0.85rem; color: var(--muted); }
+    table {
+      border-collapse: collapse;
+      width: 100%;
+    }
+    th, td {
+      text-align: left;
+      padding: 0.5rem 0.75rem;
+      border-bottom: 1px solid var(--border);
+      font-size: 0.9rem;
+    }
+    th { color: var(--muted); font-weight: 600; }
+    .score-cell {
+      font-weight: 600;
+      border-radius: 4px;
+      padding: 0.15rem 0.5rem;
+      display: inline-block;
+    }
+    .score-strong { background: #fbe4e1; color: var(--critical); }
+    .score-mid { background: #fdf0d5; color: var(--warning); }
+    .score-low { background: #e3f1e9; color: var(--info); }
+    details {
+      border: 1px solid var(--border);
+      border-radius: 6px;
+      padding: 0.5rem 0.75rem;
+      margin-bottom: 0.5rem;
+    }
+    summary {
+      cursor: pointer;
+      font-weight: 600;
+    }
+    .finding-row {
+      padding: 0.35rem 0;
+      border-bottom: 1px solid var(--border);
+      font-size: 0.9rem;
+    }
+    .finding-row:last-child { border-bottom: none; }
+    .severity-badge {
+      display: inline-block;
+      border-radius: 999px;
+      padding: 0.05rem 0.55rem;
+      font-size: 0.75rem;
+      font-weight: 700;
+      text-transform: uppercase;
+      margin-right: 0.5rem;
+    }
+    .severity-critical { background: #fbe4e1; color: var(--critical); }
+    .severity-warning { background: #fdf0d5; color: var(--warning); }
+    .severity-info { background: #e3f1e9; color: var(--info); }
+    .empty-note { color: var(--muted); font-style: italic; }
+  `.trim();
+}

package/dist/render/html-template.js

@@ -0,0 +1,168 @@
+import { htmlStyles } from './html-styles.js';
+export function escapeHtml(input) {
+    return input
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+function estimateTokens(agent) {
+    const text = `${agent.description}\n${agent.body}`;
+    return Math.ceil(text.length / 4);
+}
+function scoreClass(score) {
+    if (score >= 0.6)
+        return 'score-strong';
+    if (score >= 0.3)
+        return 'score-mid';
+    return 'score-low';
+}
+function renderHeaderCard(report) {
+    const costFinding = report.findings.find((f) => f.ruleId === 'cost');
+    const costRow = costFinding
+        ? `<div class="stat"><span class="value">${escapeHtml(costFinding.message)}</span><span class="label">Roster cost</span></div>`
+        : '';
+    return `
+    <section class="card">
+      <h1>Roster Audit Report</h1>
+      <div class="header-stats">
+        <div class="stat">
+          <span class="value">${report.agents.length}</span>
+          <span class="label">Agents scanned</span>
+        </div>
+        <div class="stat">
+          <span class="value">${escapeHtml(report.meta.sourceLabels.join(', ') || '(none)')}</span>
+          <span class="label">Sources</span>
+        </div>
+        ${costRow}
+      </div>
+    </section>
+  `;
+}
+function renderOverlapSection(report) {
+    const overlapFindings = report.findings.filter((f) => f.ruleId === 'overlap');
+    const rows = overlapFindings
+        .map((f) => {
+        const [a, b] = f.pair ?? ['?', '?'];
+        const score = f.score ?? 0;
+        const severityClass = f.severity === 'critical' ? 'severity-critical' : 'severity-info';
+        return `
+        <tr>
+          <td><span class="score-cell ${scoreClass(score)}">${score.toFixed(3)}</span></td>
+          <td>${escapeHtml(a)}</td>
+          <td>${escapeHtml(b)}</td>
+          <td><span class="severity-badge ${severityClass}">${escapeHtml(f.severity)}</span></td>
+        </tr>
+      `;
+    })
+        .join('');
+    const body = overlapFindings.length === 0
+        ? '<p class="empty-note">No overlap findings.</p>'
+        : `
+        <table>
+          <thead>
+            <tr><th>Score</th><th>Agent A</th><th>Agent B</th><th>Severity</th></tr>
+          </thead>
+          <tbody>${rows}</tbody>
+        </table>
+      `;
+    return `
+    <section class="card">
+      <h2>Overlap — top overlapping pairs (${overlapFindings.length})</h2>
+      ${body}
+    </section>
+  `;
+}
+function renderFindingsAccordion(report) {
+    const grouped = new Map();
+    for (const f of report.findings) {
+        if (!grouped.has(f.ruleId))
+            grouped.set(f.ruleId, []);
+        grouped.get(f.ruleId).push(f);
+    }
+    if (grouped.size === 0) {
+        return `
+      <section class="card">
+        <h2>Findings</h2>
+        <p class="empty-note">No findings.</p>
+      </section>
+    `;
+    }
+    const details = [...grouped.entries()]
+        .map(([ruleId, findings]) => {
+        const rows = findings
+            .map((f) => {
+            const severityClass = f.severity === 'critical' ? 'severity-critical' : f.severity === 'warning' ? 'severity-warning' : 'severity-info';
+            const target = f.agent ? escapeHtml(f.agent) : f.pair ? f.pair.map(escapeHtml).join(' <-> ') : '';
+            return `
+            <div class="finding-row">
+              <span class="severity-badge ${severityClass}">${escapeHtml(f.severity)}</span>
+              ${target ? `<strong>${target}</strong> — ` : ''}${escapeHtml(f.message)}
+            </div>
+          `;
+        })
+            .join('');
+        return `
+        <details>
+          <summary>${escapeHtml(ruleId)} (${findings.length})</summary>
+          ${rows}
+        </details>
+      `;
+    })
+        .join('');
+    return `
+    <section class="card">
+      <h2>Findings</h2>
+      ${details}
+    </section>
+  `;
+}
+function renderAgentTable(report) {
+    const rows = report.agents
+        .map((agent) => {
+        const hasTools = agent.tools !== undefined && agent.tools.length > 0;
+        return `
+        <tr>
+          <td>${escapeHtml(agent.name)}</td>
+          <td>${hasTools ? 'yes' : 'no'}</td>
+          <td>${agent.description.length}</td>
+          <td>${estimateTokens(agent)}</td>
+        </tr>
+      `;
+    })
+        .join('');
+    const body = `
+        <table>
+          <thead>
+            <tr><th>Name</th><th>Tools</th><th>Description length</th><th>Est. tokens</th></tr>
+          </thead>
+          <tbody>${rows || '<tr><td colspan="4" class="empty-note">No agents.</td></tr>'}</tbody>
+        </table>
+      `;
+    return `
+    <section class="card">
+      <h2>Agents (${report.agents.length})</h2>
+      ${body}
+    </section>
+  `;
+}
+export function renderHtmlTemplate(report) {
+    const sections = [
+        renderHeaderCard(report),
+        renderOverlapSection(report),
+        renderFindingsAccordion(report),
+        renderAgentTable(report),
+    ].join('\n');
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<title>Roster Audit Report</title>
+<style>${htmlStyles()}</style>
+</head>
+<body>
+${sections}
+</body>
+</html>`;
+}

package/dist/render/html.js

@@ -0,0 +1,7 @@
+import { renderHtmlTemplate } from './html-template.js';
+export const htmlRenderer = {
+    id: 'html',
+    render(report) {
+        return renderHtmlTemplate(report);
+    },
+};

package/dist/render/index.js

@@ -0,0 +1,8 @@
+import { cliRenderer } from './cli.js';
+import { jsonRenderer } from './json.js';
+import { htmlRenderer } from './html.js';
+export const renderers = {
+    cli: cliRenderer,
+    json: jsonRenderer,
+    html: htmlRenderer,
+};

package/dist/render/json.js

@@ -0,0 +1,33 @@
+const SEVERITY_RANK = { critical: 0, warning: 1, info: 2 };
+function findingTarget(finding) {
+    if (finding.agent !== undefined)
+        return finding.agent;
+    if (finding.pair !== undefined)
+        return finding.pair.join('::');
+    return '';
+}
+function sortAgents(agents) {
+    return [...agents].sort((a, b) => a.name.localeCompare(b.name));
+}
+function sortFindings(findings) {
+    return [...findings].sort((a, b) => {
+        const severityDiff = SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity];
+        if (severityDiff !== 0)
+            return severityDiff;
+        const ruleIdDiff = a.ruleId.localeCompare(b.ruleId);
+        if (ruleIdDiff !== 0)
+            return ruleIdDiff;
+        return findingTarget(a).localeCompare(findingTarget(b));
+    });
+}
+export const jsonRenderer = {
+    id: 'json',
+    render(report) {
+        const stable = {
+            agents: sortAgents(report.agents),
+            findings: sortFindings(report.findings),
+            meta: report.meta,
+        };
+        return JSON.stringify(stable, null, 2);
+    },
+};

package/dist/rules/cost.js

@@ -0,0 +1,27 @@
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+export const costRule = {
+    id: 'cost',
+    description: 'Estimates the context-window cost of loading the full agent roster.',
+    run(agents) {
+        const findings = [];
+        let descriptionTokenTotal = 0;
+        for (const agent of agents) {
+            const tokens = estimateTokens(`${agent.description}${agent.body}`);
+            descriptionTokenTotal += estimateTokens(agent.description);
+            findings.push({
+                ruleId: 'cost',
+                severity: 'info',
+                agent: agent.name,
+                message: `${agent.name} estimated token cost ~${tokens} tokens (estimate)`,
+            });
+        }
+        findings.push({
+            ruleId: 'cost',
+            severity: 'info',
+            message: `roster fixed cost per turn ~${descriptionTokenTotal} tokens (estimate)`,
+        });
+        return findings;
+    },
+};

package/dist/rules/fluff.js

@@ -0,0 +1,38 @@
+const MIN_BODY_LINES = 20;
+const NARRATIVE_RATIO_THRESHOLD = 0.7;
+const IMPERATIVE_VERB_PATTERN = /^(run|check|verify|confirm|ensure|use|call|invoke|write|read|add|remove|update|create|delete|build|deploy|test|review|flag|report|notify|tag|push|trigger)\b/i;
+const CHECKLIST_PATTERN = /^-\s*\[( |x|X)\]/;
+const NUMBERED_STEP_PATTERN = /^\d+[.)]\s+/;
+const CODE_FENCE_PATTERN = /^```/;
+function isExecutableLine(line) {
+    const trimmed = line.trim();
+    if (trimmed === '')
+        return false;
+    return (IMPERATIVE_VERB_PATTERN.test(trimmed) ||
+        CHECKLIST_PATTERN.test(trimmed) ||
+        NUMBERED_STEP_PATTERN.test(trimmed) ||
+        CODE_FENCE_PATTERN.test(trimmed));
+}
+export const fluffRule = {
+    id: 'fluff',
+    description: 'Flags agent definitions with low information density (filler prose, vague instructions).',
+    run(agents) {
+        const findings = [];
+        for (const agent of agents) {
+            const lines = agent.body.split('\n').filter((l) => l.trim() !== '');
+            if (lines.length <= MIN_BODY_LINES)
+                continue;
+            const executableCount = lines.filter(isExecutableLine).length;
+            const narrativeRatio = (lines.length - executableCount) / lines.length;
+            if (narrativeRatio > NARRATIVE_RATIO_THRESHOLD) {
+                findings.push({
+                    ruleId: 'fluff',
+                    severity: 'info',
+                    agent: agent.name,
+                    message: `[experimental] ${agent.name} body 는 서사 비율 ${(narrativeRatio * 100).toFixed(0)}% — 실행성 낮음`,
+                });
+            }
+        }
+        return findings;
+    },
+};

package/dist/rules/harness.js

@@ -0,0 +1,24 @@
+const WILDCARD_TOKENS = new Set(['*', 'all']);
+function isWildcardTools(tools) {
+    return tools.some((t) => WILDCARD_TOKENS.has(t.trim().toLowerCase()));
+}
+export const harnessRule = {
+    id: 'harness',
+    description: 'Flags agents that reference tools without a matching harness/permission definition.',
+    run(agents) {
+        const findings = [];
+        for (const agent of agents) {
+            const noTools = agent.tools === undefined || agent.tools.length === 0;
+            const wildcard = agent.tools !== undefined && isWildcardTools(agent.tools);
+            if (noTools || wildcard) {
+                findings.push({
+                    ruleId: 'harness',
+                    severity: 'warning',
+                    agent: agent.name,
+                    message: '도구 제한 없음 — 전 도구 개방 (모자만 있는 agent)',
+                });
+            }
+        }
+        return findings;
+    },
+};

package/dist/rules/index.js

@@ -0,0 +1,12 @@
+import { overlapRule } from './overlap.js';
+import { harnessRule } from './harness.js';
+import { routingRule } from './routing.js';
+import { costRule } from './cost.js';
+import { fluffRule } from './fluff.js';
+export const rules = {
+    overlap: overlapRule,
+    harness: harnessRule,
+    routing: routingRule,
+    cost: costRule,
+    fluff: fluffRule,
+};

package/dist/rules/overlap.js

@@ -0,0 +1,82 @@
+const DEFAULT_TOP = 10;
+function tokenize(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean);
+}
+function buildVectors(docs) {
+    const documentFrequency = new Map();
+    for (const doc of docs) {
+        for (const term of new Set(doc)) {
+            documentFrequency.set(term, (documentFrequency.get(term) ?? 0) + 1);
+        }
+    }
+    const n = docs.length;
+    const idf = new Map();
+    for (const [term, df] of documentFrequency) {
+        idf.set(term, Math.log((n + 1) / (df + 1)) + 1);
+    }
+    return docs.map((doc) => {
+        const termFrequency = new Map();
+        for (const term of doc) {
+            termFrequency.set(term, (termFrequency.get(term) ?? 0) + 1);
+        }
+        const vector = new Map();
+        for (const [term, count] of termFrequency) {
+            const weight = (count / doc.length) * (idf.get(term) ?? 0);
+            vector.set(term, weight);
+        }
+        return vector;
+    });
+}
+function norm(vector) {
+    let sumSquares = 0;
+    for (const weight of vector.values())
+        sumSquares += weight * weight;
+    return Math.sqrt(sumSquares);
+}
+function dotProduct(a, b) {
+    const [small, large] = a.size <= b.size ? [a, b] : [b, a];
+    let dot = 0;
+    for (const [term, weight] of small) {
+        const other = large.get(term);
+        if (other !== undefined)
+            dot += weight * other;
+    }
+    return dot;
+}
+export const overlapRule = {
+    id: 'overlap',
+    description: 'Computes TF-IDF cosine similarity between every pair of agents and reports the top-N most similar pairs.',
+    run(agents, opts) {
+        const top = opts?.top ?? DEFAULT_TOP;
+        const failAbove = opts?.failAbove;
+        const docs = agents.map((agent) => tokenize(`${agent.description}\n${agent.body}`));
+        const vectors = buildVectors(docs);
+        const norms = vectors.map(norm);
+        const pairs = [];
+        for (let i = 0; i < agents.length; i++) {
+            for (let j = i + 1; j < agents.length; j++) {
+                if (norms[i] === 0 || norms[j] === 0)
+                    continue;
+                const score = dotProduct(vectors[i], vectors[j]) / (norms[i] * norms[j]);
+                pairs.push({ i, j, score });
+            }
+        }
+        pairs.sort((a, b) => b.score - a.score);
+        const topPairs = pairs.slice(0, top);
+        return topPairs.map(({ i, j, score }) => {
+            const a = agents[i].name;
+            const b = agents[j].name;
+            const critical = failAbove !== undefined && score > failAbove;
+            return {
+                ruleId: 'overlap',
+                severity: critical ? 'critical' : 'info',
+                pair: [a, b],
+                score,
+                message: `${a} and ${b} overlap (similarity ${score.toFixed(3)})`,
+            };
+        });
+    },
+};

package/dist/rules/routing.js

@@ -0,0 +1,41 @@
+const MAX_DESCRIPTION_LENGTH = 400;
+const TRIGGER_PATTERN = /(use when|use this|invoke|trigger|~할 때|~시 사용)|\b(when|if)\b.+\b(use|call|invoke)\b/i;
+function hasTriggerSignal(description) {
+    return TRIGGER_PATTERN.test(description);
+}
+export const routingRule = {
+    id: 'routing',
+    description: 'Flags ambiguous routing between agents with overlapping trigger descriptions.',
+    run(agents) {
+        const findings = [];
+        for (const agent of agents) {
+            const description = agent.description.trim();
+            if (description === '') {
+                findings.push({
+                    ruleId: 'routing',
+                    severity: 'warning',
+                    agent: agent.name,
+                    message: 'description 부재 — 메인 모델이 위임 판단 불가',
+                });
+                continue;
+            }
+            if (!hasTriggerSignal(description)) {
+                findings.push({
+                    ruleId: 'routing',
+                    severity: 'info',
+                    agent: agent.name,
+                    message: 'description 에 위임 트리거 신호 없음 (use when/트리거 조건절 권장)',
+                });
+            }
+            if (description.length > MAX_DESCRIPTION_LENGTH) {
+                findings.push({
+                    ruleId: 'routing',
+                    severity: 'info',
+                    agent: agent.name,
+                    message: `description 이 ${MAX_DESCRIPTION_LENGTH}자를 초과함 (로스터 목록 비대)`,
+                });
+            }
+        }
+        return findings;
+    },
+};

package/dist/sources/dir.js

@@ -0,0 +1,50 @@
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parseAgentMarkdown } from '../parse/agent-md.js';
+// R0: well-known non-agent documentation basenames (extension stripped, case-insensitive).
+// Recursive scans previously misdetected these as "agents" and produced spurious overlap
+// findings between unrelated projects' README/CONTRIBUTING/etc files.
+const EXCLUDED_DOC_BASENAMES = new Set([
+    'readme',
+    'contributing',
+    'license',
+    'security',
+    'changelog',
+    'quickstart',
+    'install',
+    'code_of_conduct',
+]);
+export function isExcludedDocFile(filePath) {
+    const base = path.basename(filePath, path.extname(filePath)).toLowerCase();
+    return EXCLUDED_DOC_BASENAMES.has(base);
+}
+async function collectMarkdownFiles(root) {
+    const entries = await readdir(root, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const fullPath = path.join(root, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await collectMarkdownFiles(fullPath)));
+        }
+        else if (entry.isFile() && entry.name.endsWith('.md') && !isExcludedDocFile(fullPath)) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+export const dirSource = {
+    id: 'dir',
+    description: 'Recursively scans a local directory for agent markdown files.',
+    async load(opts) {
+        const dir = opts?.dir;
+        if (!dir) {
+            throw new Error('sources/dir: opts.dir is required');
+        }
+        const files = await collectMarkdownFiles(dir);
+        const agents = await Promise.all(files.map(async (filePath) => {
+            const raw = await readFile(filePath, 'utf8');
+            return parseAgentMarkdown(raw, filePath, `dir:${dir}`);
+        }));
+        return agents;
+    },
+};

package/dist/sources/github.js

@@ -0,0 +1,72 @@
+import { parseAgentMarkdown } from '../parse/agent-md.js';
+import { isExcludedDocFile } from './dir.js';
+function parseRepoSpec(repo) {
+    const atIndex = repo.lastIndexOf('@');
+    const withoutRef = atIndex === -1 ? repo : repo.slice(0, atIndex);
+    const ref = atIndex === -1 ? undefined : repo.slice(atIndex + 1);
+    const slashIndex = withoutRef.indexOf('/');
+    if (slashIndex === -1) {
+        throw new Error(`sources/github: invalid repo spec "${repo}", expected owner/name[@ref]`);
+    }
+    return {
+        owner: withoutRef.slice(0, slashIndex),
+        name: withoutRef.slice(slashIndex + 1),
+        ref,
+    };
+}
+function authHeaders() {
+    const token = process.env.GITHUB_TOKEN;
+    return token ? { Authorization: `Bearer ${token}` } : {};
+}
+async function githubJsonFetch(url) {
+    const res = await fetch(url, { headers: { Accept: 'application/vnd.github+json', ...authHeaders() } });
+    if (!res.ok) {
+        if (res.status === 404) {
+            throw new Error(`sources/github: 404 not found — ${url}`);
+        }
+        if (res.status === 403) {
+            throw new Error(`sources/github: 403 rate-limit (or forbidden) — ${url}. Set GITHUB_TOKEN to raise limits.`);
+        }
+        throw new Error(`sources/github: request failed (${res.status}) — ${url}`);
+    }
+    return res.json();
+}
+async function resolveDefaultBranch(owner, name) {
+    const data = (await githubJsonFetch(`https://api.github.com/repos/${owner}/${name}`));
+    if (!data.default_branch) {
+        throw new Error(`sources/github: could not resolve default branch for ${owner}/${name}`);
+    }
+    return data.default_branch;
+}
+function isCandidateMarkdownBlob(entry) {
+    return entry.type === 'blob' && entry.path.endsWith('.md') && !isExcludedDocFile(entry.path);
+}
+export const githubSource = {
+    id: 'github',
+    description: 'Loads agents from a GitHub repository (owner/name[@ref]).',
+    async load(opts) {
+        const repoSpec = opts?.repo;
+        if (!repoSpec) {
+            throw new Error('sources/github: opts.repo is required (owner/name[@ref])');
+        }
+        const { owner, name, ref: pinnedRef } = parseRepoSpec(repoSpec);
+        const ref = pinnedRef ?? (await resolveDefaultBranch(owner, name));
+        const treeUrl = `https://api.github.com/repos/${owner}/${name}/git/trees/${ref}?recursive=1`;
+        const tree = (await githubJsonFetch(treeUrl));
+        if (tree.truncated) {
+            console.warn(`sources/github: tree listing for ${owner}/${name}@${ref} was truncated by the GitHub API — some agent files may be missing`);
+        }
+        const sourceLabel = `github:${owner}/${name}@${ref}`;
+        const candidates = (tree.tree ?? []).filter(isCandidateMarkdownBlob);
+        const agents = await Promise.all(candidates.map(async (entry) => {
+            const rawUrl = `https://raw.githubusercontent.com/${owner}/${name}/${ref}/${entry.path}`;
+            const res = await fetch(rawUrl, { headers: authHeaders() });
+            if (!res.ok) {
+                throw new Error(`sources/github: failed to fetch ${rawUrl} (${res.status})`);
+            }
+            const raw = await res.text();
+            return parseAgentMarkdown(raw, entry.path, sourceLabel);
+        }));
+        return agents;
+    },
+};

package/dist/sources/index.js

@@ -0,0 +1,10 @@
+import { dirSource } from './dir.js';
+import { userSource } from './user.js';
+import { pluginCacheSource } from './plugin-cache.js';
+import { githubSource } from './github.js';
+export const sources = {
+    dir: dirSource,
+    user: userSource,
+    'plugin-cache': pluginCacheSource,
+    github: githubSource,
+};

package/dist/sources/plugin-cache.js

@@ -0,0 +1,89 @@
+import { readFile, readdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { parseAgentMarkdown } from '../parse/agent-md.js';
+import { isExcludedDocFile } from './dir.js';
+async function readInstalledPlugins(pluginsRoot) {
+    const file = path.join(pluginsRoot, 'installed_plugins.json');
+    try {
+        const raw = await readFile(file, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+function resolveActivePlugins(data) {
+    const active = [];
+    const seenInstallPaths = new Set();
+    for (const [key, entries] of Object.entries(data.plugins ?? {})) {
+        const sepIndex = key.indexOf('@');
+        const name = sepIndex === -1 ? key : key.slice(0, sepIndex);
+        const marketplace = sepIndex === -1 ? '' : key.slice(sepIndex + 1);
+        for (const entry of entries) {
+            if (!entry.installPath || seenInstallPaths.has(entry.installPath))
+                continue;
+            seenInstallPaths.add(entry.installPath);
+            active.push({ name, marketplace, version: entry.version, installPath: entry.installPath });
+        }
+    }
+    return active;
+}
+async function collectMarkdownFiles(root) {
+    let entries;
+    try {
+        entries = await readdir(root, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const files = [];
+    for (const entry of entries) {
+        const fullPath = path.join(root, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await collectMarkdownFiles(fullPath)));
+        }
+        else if (entry.isFile() && entry.name.endsWith('.md') && !isExcludedDocFile(fullPath)) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+async function dirExists(dir) {
+    try {
+        return (await stat(dir)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export const pluginCacheSource = {
+    id: 'plugin-cache',
+    description: 'Loads agents from the installed Claude Code plugin cache.',
+    async load(opts) {
+        const home = opts?.home ?? process.env.HOME;
+        if (!home) {
+            console.error('sources/plugin-cache: HOME is not set, no opts.home override provided — returning empty roster');
+            return [];
+        }
+        const pluginsRoot = path.join(home, '.claude', 'plugins');
+        const data = await readInstalledPlugins(pluginsRoot);
+        if (!data) {
+            console.error(`sources/plugin-cache: ${pluginsRoot}/installed_plugins.json not found — returning empty roster`);
+            return [];
+        }
+        const pluginNameFilter = opts?.pluginName;
+        const activePlugins = resolveActivePlugins(data).filter((p) => !pluginNameFilter || p.name === pluginNameFilter);
+        const agentLists = await Promise.all(activePlugins.map(async (plugin) => {
+            const agentsDir = path.join(plugin.installPath, 'agents');
+            if (!(await dirExists(agentsDir)))
+                return [];
+            const files = await collectMarkdownFiles(agentsDir);
+            const sourceLabel = `plugin:${plugin.name}@${plugin.version}`;
+            return Promise.all(files.map(async (filePath) => {
+                const raw = await readFile(filePath, 'utf8');
+                return parseAgentMarkdown(raw, filePath, sourceLabel);
+            }));
+        }));
+        return agentLists.flat();
+    },
+};

package/dist/sources/user.js

@@ -0,0 +1,49 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { parseAgentMarkdown } from '../parse/agent-md.js';
+import { isExcludedDocFile } from './dir.js';
+async function collectMarkdownFiles(root) {
+    const entries = await readdir(root, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const fullPath = path.join(root, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await collectMarkdownFiles(fullPath)));
+        }
+        else if (entry.isFile() && entry.name.endsWith('.md') && !isExcludedDocFile(fullPath)) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+async function exists(dir) {
+    try {
+        const s = await stat(dir);
+        return s.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export const userSource = {
+    id: 'user',
+    description: 'Loads agents from the user-level Claude Code agent directory (~/.claude/agents).',
+    async load(opts) {
+        const home = opts?.home ?? process.env.HOME;
+        if (!home) {
+            console.error('sources/user: HOME is not set, no opts.home override provided — returning empty roster');
+            return [];
+        }
+        const agentsDir = path.join(home, '.claude', 'agents');
+        if (!(await exists(agentsDir))) {
+            console.error(`sources/user: ${agentsDir} does not exist — returning empty roster`);
+            return [];
+        }
+        const files = await collectMarkdownFiles(agentsDir);
+        const agents = await Promise.all(files.map(async (filePath) => {
+            const raw = await readFile(filePath, 'utf8');
+            return parseAgentMarkdown(raw, filePath, 'user');
+        }));
+        return agents;
+    },
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "roster-cli",
+  "version": "0.1.0",
+  "description": "Zero-runtime-dep static auditor for Claude Code agent rosters \u2014 overlap, harness gaps, routing, cost.",
+  "type": "module",
+  "bin": {
+    "roster": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4",
+    "@types/node": "^22.9.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sshworld/roster.git"
+  },
+  "homepage": "https://github.com/sshworld/roster#readme",
+  "bugs": {
+    "url": "https://github.com/sshworld/roster/issues"
+  },
+  "keywords": [
+    "claude-code",
+    "agents",
+    "audit",
+    "lint",
+    "roster",
+    "ai-agents",
+    "static-analysis"
+  ]
+}