specdo 1.0.2

package/dist/core/skill-exporter.js

@@ -0,0 +1,922 @@
+/**
+ * Skill Exporter — OpenSpec core-compatible progressive disclosure
+ *
+ * 把 specdo 的 core 工作流导出为 progressive-disclosure SKILL.md 包，
+ * 投递到各 AI 工具的 skill 目录。
+ *
+ * 每个 skill 包结构：
+ *   <name>/
+ *   ├── SKILL.md           # 精炼指引（agent 默认加载）
+ *   └── references/        # 按需加载的详细参考
+ *       ├── REFERENCE.md   # workflow / protocol
+ *       ├── EXAMPLES.md    # workflow / protocol
+ *       ├── DOMAIN_*.md    # specdo 增强的 domain guidance
+ *       ├── PROTOCOL_*.md  # specdo 增强的 protocol guidance
+ *       └── ARCHIVE_*.md   # 收尾/归档 gate
+ *
+ * 关键不变量：
+ *   - 导出入口始终保持 OpenSpec core 范式：workflow skill 是一等公民，
+ *     domain/protocol 仅作为 workflow references 的增强材料
+ *   - 内容来源全部为运行时数据（DomainModule / Protocol / WORKFLOW_SKILLS
+ *     + 手写的 CROSS_DOMAIN / PROTOCOL_EXAMPLES），不依赖模板文件
+ *   - SKILL.md 严格遵循 Anthropic 标准：YAML frontmatter（name + description）
+ *     + 正文 markdown
+ *   - skill name ≤ 64 字符，仅 lowercase 字母数字短横线（Anthropic 规范）
+ *   - SKILL.md 推荐 ≤ 500 行（agentskills.io）；progressive disclosure 让
+ *     大量内容下沉 references/，单文件保持精炼
+ *
+ * 输出 5 个 core workflow skill：
+ *   - specdo-explore
+ *   - specdo-propose
+ *   - specdo-apply
+ *   - specdo-sync
+ *   - specdo-archive
+ *
+ * domain / protocol 不再作为独立 skill 导出，避免 agent 从工作流主轴偏航。
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { ALL_DOMAINS, extractQuestions, isQuestionPool } from '../domains/index.js';
+import { ALL_PROTOCOLS } from '../protocols/index.js';
+import { WORKFLOW_SKILLS as WORKFLOW_CONTENT } from './skill-content/workflow-content.js';
+import { CROSS_DOMAIN_NOTES } from './skill-content/cross-domain.js';
+import { PROTOCOL_EXAMPLES } from './skill-content/protocol-examples.js';
+const AGENT_REGISTRY = {
+    claude: { name: 'claude', homeSubdir: '.claude/skills', projectSubdir: '.claude/skills' },
+    qoder: { name: 'qoder', homeSubdir: '.qoder/skills', projectSubdir: '.qoder/skills' },
+    cursor: { name: 'cursor', homeSubdir: '.cursor/skills', projectSubdir: '.cursor/skills' },
+    cline: { name: 'cline', homeSubdir: '.cline/skills', projectSubdir: '.cline/skills' },
+    codex: { name: 'codex', homeSubdir: '.codex/skills', projectSubdir: '.codex/skills' },
+    goose: { name: 'goose', homeSubdir: '.goose/skills', projectSubdir: '.goose/skills' },
+    kilo: { name: 'kilo', homeSubdir: '.kilo/skills', projectSubdir: '.kilo/skills' },
+    opencode: { name: 'opencode', homeSubdir: '.opencode/skills', projectSubdir: '.opencode/skills' },
+    // 'universal' 是 escape hatch：写入社区开放标准 .agents/skills/
+    universal: { name: 'universal', homeSubdir: '.agents/skills', projectSubdir: '.agents/skills' },
+};
+/**
+ * 8 家 canonical AI 工具（不含 universal escape hatch）。
+ * 供文档、测试、拼写纠错限定在已审计的工具列表上。
+ */
+export const ALL_AGENTS = [
+    'claude',
+    'qoder',
+    'cursor',
+    'cline',
+    'codex',
+    'goose',
+    'kilo',
+    'opencode',
+];
+/** Universal escape hatch 单独曝露，需要与 ALL_AGENTS 区分对待。 */
+export const UNIVERSAL_AGENT = 'universal';
+export function isAgentName(value) {
+    return Object.prototype.hasOwnProperty.call(AGENT_REGISTRY, value);
+}
+// ─── Suggest helper：为 CLI 提供拼写纠错 ───────────────────────────
+/**
+ * 计算两个字符串的 Levenshtein 距离。用于拼写纠错提示。
+ */
+export function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    const m = a.length;
+    const n = b.length;
+    const prev = new Array(n + 1);
+    const curr = new Array(n + 1);
+    for (let j = 0; j <= n; j++)
+        prev[j] = j;
+    for (let i = 1; i <= m; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= n; j++) {
+            const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+            curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+        }
+        for (let j = 0; j <= n; j++)
+            prev[j] = curr[j];
+    }
+    return prev[n];
+}
+/**
+ * 在 ALL_AGENTS 中寻找与输入最接近的 canonical agent 名。
+ * 近似阈值：Levenshtein 距离 ≤ 1。
+ * 不返回 'universal'：它是 escape hatch，不适合作为拼写纠错候选。
+ */
+export function suggestAgents(input) {
+    if (!input || input.length < 2)
+        return [];
+    const lower = input.toLowerCase();
+    const candidates = ALL_AGENTS.map((name) => ({
+        name,
+        distance: levenshtein(lower, name),
+    }));
+    const minDistance = Math.min(...candidates.map((c) => c.distance));
+    if (minDistance > 1)
+        return [];
+    return candidates
+        .filter((c) => c.distance === minDistance)
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((c) => c.name);
+}
+/**
+ * 渲染 SKILL.md 完整内容（含 frontmatter）。
+ *
+ * description 内的双引号被替换为单引号，避免破坏 YAML 字符串；
+ * 空白序列被压缩，让 YAML 解析器 / agent 列表视图更友好。
+ */
+export function renderSkillFile(doc) {
+    const safeDescription = doc.description.replace(/"/g, "'").replace(/\s+/g, ' ').trim();
+    const frontmatter = ['---', `name: ${doc.name}`, `description: "${safeDescription}"`, '---', ''];
+    return `${frontmatter.join('\n')}\n${doc.body.trimEnd()}\n`;
+}
+// ─── Builders ─────────────────────────────────────────────────
+function renderDomainDiscoveryReference() {
+    const lines = [];
+    lines.push('# Domain discovery guidance');
+    lines.push('');
+    lines.push('SpecDo keeps the OpenSpec-style workflow entrypoint at `explore`, then enriches it with domain scoring, clarifying questions, and cross-domain concerns.');
+    lines.push('');
+    lines.push('## How to use this reference');
+    lines.push('');
+    lines.push('1. Read the user\'s request and scan each domain\'s **Signals** list');
+    lines.push('   below for relevant keywords and concepts.');
+    lines.push('2. For each domain whose signals overlap with the user\'s intent, review');
+    lines.push('   the **Clarifying questions**.');
+    lines.push('3. **Select 1-4 domains** that best cover the user\'s needs. More domains');
+    lines.push('   mean broader coverage but also more complexity — prefer focused selection.');
+    lines.push('4. **Ask the user** the clarifying questions from selected domains. Record');
+    lines.push('   the answers.');
+    lines.push('5. Pass the selected domains to `specdo explore --domains <list>` and');
+    lines.push('   your collected answers via `--answers` or a summary via `--context`.');
+    lines.push('6. Set `--depth standard` (or `deep` if all questions were answered).');
+    lines.push('');
+    lines.push('**Important**: Do not rely on the automatic `scoreDomains()` signal matching');
+    lines.push('to select domains for you. The signal matching uses English keyword heuristics');
+    lines.push('and cannot understand user intent the way you can. You are the intelligent');
+    lines.push('agent — you decide which domains apply.');
+    lines.push('');
+    lines.push('## Available domains (6 total)');
+    lines.push('');
+    for (const domain of ALL_DOMAINS) {
+        lines.push(`## ${domain.name}`);
+        lines.push('');
+        lines.push(domain.description);
+        lines.push('');
+        const signals = domain.explore?.signals ?? [];
+        if (signals.length > 0) {
+            lines.push('**Signals**');
+            lines.push('');
+            for (const signal of signals) {
+                lines.push(`- \`${signal}\``);
+            }
+            lines.push('');
+        }
+        const questionsRaw = domain.explore?.questions ?? [];
+        const questions = extractQuestions(questionsRaw);
+        if (questions.length > 0) {
+            if (isQuestionPool(questionsRaw)) {
+                // Pool format: show with metadata for agent LLM generation
+                lines.push(`**Question pool** (${questionsRaw.items.length} items, default top-${questionsRaw.defaultCount})`);
+                lines.push('');
+                lines.push('Each item includes signals for relevance matching, priority (1-10),');
+                lines.push('and optional dependency chains. Agents can use this taxonomy to generate');
+                lines.push('LLM-tailored questions via `--llm` / `--llm-questions`.');
+                lines.push('');
+                // Show top 10 items with metadata as examples
+                for (const item of questionsRaw.items.slice(0, 10)) {
+                    const meta = [
+                        `priority=${item.priority}`,
+                        item.requiresAnswer?.length ? `requires=[${item.requiresAnswer.join(',')}]` : null,
+                        item.conditional ? `conditional=${JSON.stringify(item.conditional)}` : null,
+                    ].filter(Boolean).join(', ');
+                    lines.push(`- ${item.text}`);
+                    lines.push(`  _signals: ${item.signals.slice(0, 5).join(', ')}${item.signals.length > 5 ? ', …' : ''}_`);
+                    lines.push(`  _${meta}_`);
+                }
+                if (questionsRaw.items.length > 10) {
+                    lines.push(`- _…and ${questionsRaw.items.length - 10} more items (see references/CHECKLIST.md for full list)_`);
+                }
+            }
+            else {
+                // Legacy format: show as before
+                lines.push('**Clarifying questions**');
+                lines.push('');
+                for (const question of questions) {
+                    lines.push(`- ${question}`);
+                }
+            }
+            lines.push('');
+        }
+        const crossDomain = CROSS_DOMAIN_NOTES[domain.name];
+        if (crossDomain) {
+            const summary = crossDomain
+                .split('\n')
+                .filter((line) => line.startsWith('- '))
+                .slice(0, 3);
+            if (summary.length > 0) {
+                lines.push('**Cross-domain coordination**');
+                lines.push('');
+                lines.push(...summary);
+                lines.push('');
+            }
+        }
+    }
+    return lines.join('\n').trimEnd() + '\n';
+}
+function renderDomainDesignReference() {
+    const lines = [];
+    lines.push('# Domain design guidance');
+    lines.push('');
+    lines.push('OpenSpec core keeps `propose` responsible for planning artifacts. SpecDo augments that step with the domain checklists below so the generated proposal/specs/design/tasks stay grounded in the right concerns.');
+    lines.push('');
+    for (const domain of ALL_DOMAINS) {
+        lines.push(`## ${domain.name}`);
+        lines.push('');
+        if (domain.design?.checklist?.length) {
+            lines.push('### Design checklist');
+            lines.push('');
+            for (const item of domain.design.checklist) {
+                lines.push(`- ${item}`);
+            }
+            lines.push('');
+        }
+        if (domain.design?.patterns && Object.keys(domain.design.patterns).length > 0) {
+            lines.push('### Recommended patterns');
+            lines.push('');
+            for (const [name, desc] of Object.entries(domain.design.patterns)) {
+                lines.push(`- **${name}** — ${desc}`);
+            }
+            lines.push('');
+        }
+        if (domain.design?.antiPatterns?.length) {
+            lines.push('### Anti-patterns');
+            lines.push('');
+            for (const item of domain.design.antiPatterns) {
+                lines.push(`- ${item}`);
+            }
+            lines.push('');
+        }
+    }
+    return lines.join('\n').trimEnd() + '\n';
+}
+function renderDomainImplementationReference() {
+    const lines = [];
+    lines.push('# Domain implementation guidance');
+    lines.push('');
+    lines.push('`apply` remains the OpenSpec execution step. SpecDo strengthens it with domain-specific implementation focus and verification obligations instead of splitting execution into extra top-level skills.');
+    lines.push('');
+    for (const domain of ALL_DOMAINS) {
+        lines.push(`## ${domain.name}`);
+        lines.push('');
+        if (domain.implement?.focusAreas?.length) {
+            lines.push('### Implementation focus');
+            lines.push('');
+            for (const item of domain.implement.focusAreas) {
+                lines.push(`- ${item}`);
+            }
+            lines.push('');
+        }
+        if (domain.implement?.patterns && Object.keys(domain.implement.patterns).length > 0) {
+            lines.push('### Implementation patterns');
+            lines.push('');
+            for (const [name, desc] of Object.entries(domain.implement.patterns)) {
+                lines.push(`- **${name}** — ${desc}`);
+            }
+            lines.push('');
+        }
+        if (domain.implement?.antiPatterns?.length) {
+            lines.push('### Implementation anti-patterns');
+            lines.push('');
+            for (const item of domain.implement.antiPatterns) {
+                lines.push(`- ${item}`);
+            }
+            lines.push('');
+        }
+        if (domain.verify?.checklist?.length) {
+            lines.push('### Verification gates');
+            lines.push('');
+            for (const item of domain.verify.checklist) {
+                lines.push(`- ${item}`);
+            }
+            lines.push('');
+        }
+    }
+    return lines.join('\n').trimEnd() + '\n';
+}
+function renderDomainSyncChecksReference() {
+    const lines = [];
+    lines.push('# Domain sync checks');
+    lines.push('');
+    lines.push('`sync` keeps OpenSpec\'s canonical-spec promotion step intact. SpecDo adds domain-aware checks for whether a per-change spec is ready to replace the canonical copy, without turning sync into another implementation phase.');
+    lines.push('');
+    lines.push('## Promotion checks');
+    lines.push('');
+    lines.push('- Confirm each promoted delta spec reflects what actually landed in code, docs, and runbooks.');
+    lines.push('- Resolve same-path canonical conflicts intentionally; `--force` is an overwrite decision, not a merge strategy.');
+    lines.push('- Keep the canonical library coherent: no mixed legacy/capability layout and no stale capability names.');
+    lines.push('- Treat unresolved sync conflicts as a release gate; do not archive through them.');
+    lines.push('');
+    lines.push('## Domain verification before promotion');
+    lines.push('');
+    for (const domain of ALL_DOMAINS) {
+        const items = domain.verify?.checklist ?? [];
+        if (items.length === 0)
+            continue;
+        lines.push(`### ${domain.name}`);
+        lines.push('');
+        for (const item of items) {
+            lines.push(`- ${item}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n').trimEnd() + '\n';
+}
+function renderProtocolWorkflowReference(protocol) {
+    const lines = [];
+    lines.push(`# Protocol enhancement — ${protocol.name}`);
+    lines.push('');
+    lines.push(protocol.description);
+    lines.push('');
+    lines.push(`**Goal:** ${protocol.goal}`);
+    lines.push('');
+    lines.push('## Trigger phrases');
+    lines.push('');
+    for (const phrase of protocol.triggerPhrases) {
+        lines.push(`- \`${phrase}\``);
+    }
+    lines.push('');
+    if (protocol.suppressionPhrases?.length) {
+        lines.push('## Suppression phrases');
+        lines.push('');
+        for (const phrase of protocol.suppressionPhrases) {
+            lines.push(`- \`${phrase}\``);
+        }
+        lines.push('');
+    }
+    lines.push('## Workflow');
+    lines.push('');
+    for (const step of protocol.workflow) {
+        lines.push(`### Step ${step.step} — ${step.title}`);
+        lines.push('');
+        lines.push(`**Goal:** ${step.goal}`);
+        lines.push('');
+        for (const action of step.actions) {
+            lines.push(`- ${action}`);
+        }
+        lines.push('');
+    }
+    lines.push('## Stop conditions');
+    lines.push('');
+    for (const item of protocol.stopConditions) {
+        lines.push(`- ${item}`);
+    }
+    lines.push('');
+    return lines.join('\n').trimEnd() + '\n';
+}
+function renderProtocolContractReference(protocol) {
+    const lines = [];
+    lines.push(`# Protocol output contract — ${protocol.name}`);
+    lines.push('');
+    lines.push('## Required sections');
+    lines.push('');
+    for (const section of protocol.outputContract) {
+        lines.push(`- **${section.name}** (${section.required ? 'required' : 'optional'}, ${section.format}) — ${section.description}`);
+    }
+    lines.push('');
+    if (protocol.severityLevels && Object.keys(protocol.severityLevels).length > 0) {
+        lines.push('## Severity levels');
+        lines.push('');
+        for (const [level, desc] of Object.entries(protocol.severityLevels)) {
+            lines.push(`- **${level}** — ${desc}`);
+        }
+        lines.push('');
+    }
+    lines.push('## Prohibitions');
+    lines.push('');
+    for (const item of protocol.prohibitions) {
+        lines.push(`- ${item}`);
+    }
+    lines.push('');
+    if (protocol.generalConstraints?.length) {
+        lines.push('## General constraints');
+        lines.push('');
+        for (const item of protocol.generalConstraints) {
+            lines.push(`- ${item}`);
+        }
+        lines.push('');
+    }
+    if (protocol.artifactChecklists && Object.keys(protocol.artifactChecklists).length > 0) {
+        lines.push('## Artifact-specific checks');
+        lines.push('');
+        for (const [artifact, checks] of Object.entries(protocol.artifactChecklists)) {
+            lines.push(`### ${artifact}`);
+            lines.push('');
+            for (const item of checks) {
+                lines.push(`- ${item}`);
+            }
+            lines.push('');
+        }
+    }
+    return lines.join('\n').trimEnd() + '\n';
+}
+function renderArchiveGatesReference() {
+    const lines = [];
+    lines.push('# Archive gates');
+    lines.push('');
+    lines.push('Archive stays the final OpenSpec core step. SpecDo adds explicit production gates before a change can be considered closed.');
+    lines.push('');
+    lines.push('## Required before archive');
+    lines.push('');
+    lines.push('- `specdo sync --change <name>` completed against the current working tree');
+    lines.push('- `context.apply` evidence still matches `tasks.md` and no task was silently skipped');
+    lines.push('- delta specs accurately represent the implementation that landed');
+    lines.push('- open risks, rollout notes, and follow-up items are either resolved or explicitly recorded');
+    lines.push('');
+    lines.push('## Domain closure scan');
+    lines.push('');
+    for (const domain of ALL_DOMAINS) {
+        lines.push(`### ${domain.name}`);
+        lines.push('');
+        const items = domain.verify?.checklist ?? [];
+        for (const item of items) {
+            lines.push(`- ${item}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n').trimEnd() + '\n';
+}
+function buildWorkflowAugmentedReferences(slug) {
+    const references = {};
+    if (slug === 'specdo-explore') {
+        references['DOMAIN_DISCOVERY.md'] = renderDomainDiscoveryReference();
+    }
+    if (slug === 'specdo-propose') {
+        references['DOMAIN_DESIGN.md'] = renderDomainDesignReference();
+    }
+    if (slug === 'specdo-apply') {
+        const protocol = ALL_PROTOCOLS.find((item) => item.name === 'review-to-solid');
+        references['DOMAIN_IMPLEMENTATION.md'] = renderDomainImplementationReference();
+        if (protocol) {
+            references['PROTOCOL_REVIEW_TO_SOLID.md'] = renderProtocolWorkflowReference(protocol);
+            references['PROTOCOL_OUTPUT_CONTRACT.md'] = renderProtocolContractReference(protocol);
+            references['PROTOCOL_EXAMPLES.md'] =
+                PROTOCOL_EXAMPLES[protocol.name] ??
+                    `# ${protocol.name} — Examples\n\n_(No code examples authored yet for this protocol.)_\n`;
+        }
+    }
+    if (slug === 'specdo-sync') {
+        references['DOMAIN_SYNC_CHECKS.md'] = renderDomainSyncChecksReference();
+    }
+    if (slug === 'specdo-archive') {
+        references['ARCHIVE_GATES.md'] = renderArchiveGatesReference();
+    }
+    return references;
+}
+/** 构造工作流 skill 文档（直接取自 workflow-content.ts，并注入 core-compatible 增强 references） */
+export function buildWorkflowSkill(slug) {
+    const entry = WORKFLOW_CONTENT.find((s) => s.name === slug);
+    if (!entry) {
+        throw new Error(`Unknown workflow skill: ${slug}`);
+    }
+    return {
+        name: entry.name,
+        description: entry.description,
+        body: entry.body,
+        references: {
+            ...entry.references,
+            ...buildWorkflowAugmentedReferences(slug),
+        },
+    };
+}
+/**
+ * 构造领域 skill 文档（progressive disclosure）。
+ *
+ * SKILL.md：领域描述 + 全部 signals（agent auto-trigger 需要）+ 各阶段前若干条精华
+ * references/CHECKLIST.md：完整 design.checklist + implement.focusAreas + verify.checklist
+ * references/PATTERNS.md：完整 patterns / antiPatterns（设计阶段 + 实施阶段）
+ * references/CROSS_DOMAIN.md：手写的跨领域协同说明（取自 cross-domain.ts）
+ */
+export function buildDomainSkill(domain) {
+    const signals = domain.explore?.signals ?? [];
+    const teaser = signals.slice(0, 8).join(', ');
+    const description = `Auto-invoke during specdo workflows touching ${teaser}` +
+        (signals.length > 8 ? ', etc' : '') +
+        `. Provides domain-specific design checklist, implementation focus areas, anti-patterns, and verification clauses for the ${domain.name} domain. See references/ for full lists, patterns, and cross-domain collaboration notes.`;
+    // ── SKILL.md body (concise) ────────────────────────────────
+    const body = [];
+    body.push(`# specdo-domain-${domain.name}`);
+    body.push('');
+    body.push(domain.description);
+    body.push('');
+    if (signals.length > 0) {
+        body.push('## Trigger signals');
+        body.push('');
+        body.push('When the user input matches any of these, this domain is scored and its checklists are injected:');
+        body.push('');
+        // 全部 signals 留在 SKILL.md（auto-trigger 召回需要）
+        body.push(signals.map((s) => `\`${s}\``).join(', '));
+        body.push('');
+    }
+    const exploreQuestions = domain.explore ? extractQuestions(domain.explore.questions) : [];
+    if (exploreQuestions.length > 0) {
+        body.push('## Top clarifying questions (explore stage)');
+        body.push('');
+        for (const q of exploreQuestions.slice(0, 4)) {
+            body.push(`- ${q}`);
+        }
+        if (exploreQuestions.length > 4) {
+            body.push(`- _…and ${exploreQuestions.length - 4} more (see references/CHECKLIST.md)_`);
+        }
+        body.push('');
+    }
+    if (domain.design && domain.design.checklist.length > 0) {
+        body.push('## Top design checks');
+        body.push('');
+        for (const item of domain.design.checklist.slice(0, 4)) {
+            body.push(`- ${item}`);
+        }
+        if (domain.design.checklist.length > 4) {
+            body.push(`- _…full ${domain.design.checklist.length}-item list in references/CHECKLIST.md_`);
+        }
+        body.push('');
+    }
+    if (domain.implement && domain.implement.focusAreas.length > 0) {
+        body.push('## Top implementation focus');
+        body.push('');
+        for (const item of domain.implement.focusAreas.slice(0, 4)) {
+            body.push(`- ${item}`);
+        }
+        if (domain.implement.focusAreas.length > 4) {
+            body.push(`- _…full ${domain.implement.focusAreas.length}-item list in references/CHECKLIST.md_`);
+        }
+        body.push('');
+    }
+    body.push('## See also');
+    body.push('');
+    body.push('- [`references/CHECKLIST.md`](references/CHECKLIST.md) — full design / implementation / verification lists');
+    body.push('- [`references/PATTERNS.md`](references/PATTERNS.md) — recommended patterns + anti-patterns');
+    body.push('- [`references/CROSS_DOMAIN.md`](references/CROSS_DOMAIN.md) — how this domain interacts with the other five');
+    // ── references/CHECKLIST.md ────────────────────────────────
+    const checklist = [];
+    checklist.push(`# ${domain.name} — Full checklist`);
+    checklist.push('');
+    checklist.push(`Complete design / implementation / verification reference for the **${domain.name}** domain. Loaded on demand when SKILL.md hints at deeper detail.`);
+    checklist.push('');
+    if (domain.explore) {
+        checklist.push('## All clarifying questions (explore stage)');
+        checklist.push('');
+        for (const q of extractQuestions(domain.explore.questions)) {
+            checklist.push(`- ${q}`);
+        }
+        checklist.push('');
+    }
+    if (domain.design && domain.design.checklist.length > 0) {
+        checklist.push('## Design checklist');
+        checklist.push('');
+        for (const item of domain.design.checklist) {
+            checklist.push(`- ${item}`);
+        }
+        checklist.push('');
+    }
+    if (domain.implement && domain.implement.focusAreas.length > 0) {
+        checklist.push('## Implementation focus areas');
+        checklist.push('');
+        for (const item of domain.implement.focusAreas) {
+            checklist.push(`- ${item}`);
+        }
+        checklist.push('');
+    }
+    if (domain.verify && domain.verify.checklist.length > 0) {
+        checklist.push('## Verification checklist');
+        checklist.push('');
+        for (const item of domain.verify.checklist) {
+            checklist.push(`- ${item}`);
+        }
+        checklist.push('');
+    }
+    // ── references/PATTERNS.md ─────────────────────────────────
+    const patterns = [];
+    patterns.push(`# ${domain.name} — Patterns & anti-patterns`);
+    patterns.push('');
+    patterns.push('Recommended patterns and known anti-patterns from both the design and implementation stages.');
+    patterns.push('');
+    if (domain.design?.patterns && Object.keys(domain.design.patterns).length > 0) {
+        patterns.push('## Design patterns');
+        patterns.push('');
+        for (const [name, desc] of Object.entries(domain.design.patterns)) {
+            patterns.push(`### ${name}`);
+            patterns.push('');
+            patterns.push(desc);
+            patterns.push('');
+        }
+    }
+    if (domain.design?.antiPatterns && domain.design.antiPatterns.length > 0) {
+        patterns.push('## Design anti-patterns');
+        patterns.push('');
+        for (const item of domain.design.antiPatterns) {
+            patterns.push(`- ${item}`);
+        }
+        patterns.push('');
+    }
+    if (domain.implement?.patterns && Object.keys(domain.implement.patterns).length > 0) {
+        patterns.push('## Implementation patterns');
+        patterns.push('');
+        for (const [name, desc] of Object.entries(domain.implement.patterns)) {
+            patterns.push(`### ${name}`);
+            patterns.push('');
+            patterns.push(desc);
+            patterns.push('');
+        }
+    }
+    if (domain.implement?.antiPatterns && domain.implement.antiPatterns.length > 0) {
+        patterns.push('## Implementation anti-patterns');
+        patterns.push('');
+        for (const item of domain.implement.antiPatterns) {
+            patterns.push(`- ${item}`);
+        }
+        patterns.push('');
+    }
+    // ── references/CROSS_DOMAIN.md ─────────────────────────────
+    const crossDomain = CROSS_DOMAIN_NOTES[domain.name] ??
+        `# ${domain.name} — Cross-domain collaboration\n\n_(No cross-domain notes authored yet for this domain.)_\n`;
+    return {
+        name: `specdo-domain-${domain.name}`,
+        description,
+        body: body.join('\n'),
+        references: {
+            'CHECKLIST.md': checklist.join('\n').trimEnd() + '\n',
+            'PATTERNS.md': patterns.join('\n').trimEnd() + '\n',
+            'CROSS_DOMAIN.md': crossDomain,
+        },
+    };
+}
+/**
+ * 构造协议 skill 文档（progressive disclosure）。
+ *
+ * SKILL.md：goal + trigger / suppression / doNotUseWhen + workflow step 标题 + stop conditions
+ * references/WORKFLOW.md：完整 workflow 各 step 的 actions / exitCriteria / loopBackTo
+ * references/OUTPUT_CONTRACT.md：outputContract + severityLevels + prohibitions + artifactChecklists + generalConstraints
+ * references/EXAMPLES.md：手写 do/don't 代码示例（取自 protocol-examples.ts）
+ */
+export function buildProtocolSkill(protocol) {
+    const phrases = protocol.triggerPhrases.slice(0, 4).join(', ');
+    const description = `Use when ${protocol.goal} Trigger phrases include: ${phrases}. Avoid for: ${protocol.doNotUseWhen
+        .slice(0, 2)
+        .join('; ')}. See references/ for the full workflow, output contract, and SOLID examples.`;
+    // ── SKILL.md body (concise) ────────────────────────────────
+    const body = [];
+    body.push(`# specdo-protocol-${protocol.name}`);
+    body.push('');
+    body.push(`> ${protocol.description}`);
+    body.push('');
+    body.push('## Goal');
+    body.push('');
+    body.push(protocol.goal);
+    body.push('');
+    body.push('## Trigger phrases');
+    body.push('');
+    for (const phrase of protocol.triggerPhrases) {
+        body.push(`- \`${phrase}\``);
+    }
+    body.push('');
+    if (protocol.suppressionPhrases && protocol.suppressionPhrases.length > 0) {
+        body.push('## Suppression phrases (do NOT trigger when present)');
+        body.push('');
+        for (const phrase of protocol.suppressionPhrases) {
+            body.push(`- \`${phrase}\``);
+        }
+        body.push('');
+    }
+    body.push('## Do NOT use when');
+    body.push('');
+    for (const item of protocol.doNotUseWhen) {
+        body.push(`- ${item}`);
+    }
+    body.push('');
+    body.push('## Workflow (titles only — see references/WORKFLOW.md for actions)');
+    body.push('');
+    for (const step of protocol.workflow) {
+        body.push(`${step.step}. **${step.title}** — ${step.goal}`);
+    }
+    body.push('');
+    body.push('## Stop conditions');
+    body.push('');
+    for (const cond of protocol.stopConditions) {
+        body.push(`- ${cond}`);
+    }
+    body.push('');
+    body.push('## See also');
+    body.push('');
+    body.push('- [`references/WORKFLOW.md`](references/WORKFLOW.md) — per-step actions, exit criteria, loop-back rules');
+    body.push('- [`references/OUTPUT_CONTRACT.md`](references/OUTPUT_CONTRACT.md) — required output sections, severity levels, prohibitions, artifact-specific checks');
+    body.push('- [`references/EXAMPLES.md`](references/EXAMPLES.md) — do/don\'t code examples for each SOLID letter');
+    // ── references/WORKFLOW.md ─────────────────────────────────
+    const workflowLines = [];
+    workflowLines.push(`# ${protocol.name} — Workflow detail`);
+    workflowLines.push('');
+    workflowLines.push('Full per-step actions, exit criteria, and loop-back rules. Each step in this list mirrors the title shown in SKILL.md.');
+    workflowLines.push('');
+    for (const step of protocol.workflow) {
+        workflowLines.push(`## Step ${step.step} — ${step.title}`);
+        workflowLines.push('');
+        workflowLines.push(`**Goal:** ${step.goal}`);
+        workflowLines.push('');
+        workflowLines.push('**Actions:**');
+        for (const action of step.actions) {
+            workflowLines.push(`- ${action}`);
+        }
+        if (step.exitCriteria && step.exitCriteria.length > 0) {
+            workflowLines.push('');
+            workflowLines.push('**Exit criteria:**');
+            for (const c of step.exitCriteria) {
+                workflowLines.push(`- ${c}`);
+            }
+        }
+        if (step.loopBackTo && step.loopBackTo.length > 0) {
+            workflowLines.push('');
+            workflowLines.push(`**May loop back to step(s):** ${step.loopBackTo.join(', ')}`);
+        }
+        workflowLines.push('');
+    }
+    // ── references/OUTPUT_CONTRACT.md ──────────────────────────
+    const contractLines = [];
+    contractLines.push(`# ${protocol.name} — Output contract`);
+    contractLines.push('');
+    contractLines.push('Required output sections, severity levels, prohibitions, and any artifact-specific checks. Loaded on demand when preparing the final deliverable.');
+    contractLines.push('');
+    contractLines.push('## Required sections');
+    contractLines.push('');
+    for (const section of protocol.outputContract) {
+        contractLines.push(`- **${section.name}** (${section.required ? 'required' : 'optional'}, ${section.format}) — ${section.description}`);
+    }
+    contractLines.push('');
+    if (protocol.severityLevels && Object.keys(protocol.severityLevels).length > 0) {
+        contractLines.push('## Severity levels');
+        contractLines.push('');
+        for (const [level, desc] of Object.entries(protocol.severityLevels)) {
+            contractLines.push(`- **${level}** — ${desc}`);
+        }
+        contractLines.push('');
+    }
+    contractLines.push('## Prohibitions');
+    contractLines.push('');
+    for (const item of protocol.prohibitions) {
+        contractLines.push(`- ${item}`);
+    }
+    contractLines.push('');
+    if (protocol.artifactChecklists && Object.keys(protocol.artifactChecklists).length > 0) {
+        contractLines.push('## Artifact-specific checklists');
+        contractLines.push('');
+        for (const [artifact, checks] of Object.entries(protocol.artifactChecklists)) {
+            contractLines.push(`### ${artifact}`);
+            contractLines.push('');
+            for (const c of checks) {
+                contractLines.push(`- ${c}`);
+            }
+            contractLines.push('');
+        }
+    }
+    if (protocol.generalConstraints && protocol.generalConstraints.length > 0) {
+        contractLines.push('## General constraints');
+        contractLines.push('');
+        for (const item of protocol.generalConstraints) {
+            contractLines.push(`- ${item}`);
+        }
+        contractLines.push('');
+    }
+    // ── references/EXAMPLES.md ─────────────────────────────────
+    const examples = PROTOCOL_EXAMPLES[protocol.name] ??
+        `# ${protocol.name} — Examples\n\n_(No code examples authored yet for this protocol.)_\n`;
+    return {
+        name: `specdo-protocol-${protocol.name}`,
+        description,
+        body: body.join('\n'),
+        references: {
+            'WORKFLOW.md': workflowLines.join('\n').trimEnd() + '\n',
+            'OUTPUT_CONTRACT.md': contractLines.join('\n').trimEnd() + '\n',
+            'EXAMPLES.md': examples,
+        },
+    };
+}
+// ─── Aggregate：组装 5 个 core workflow skill ───────────────────
+/** 返回所有应被导出的 SkillDoc */
+export function collectAllSkills() {
+    return WORKFLOW_CONTENT.map((entry) => buildWorkflowSkill(entry.name));
+}
+// ─── 写入实现 ─────────────────────────────────────────────────
+function resolveAgentRoot(agent, scope, cwd) {
+    const spec = AGENT_REGISTRY[agent];
+    if (scope === 'user') {
+        const homeDir = process.env.HOME || process.env.USERPROFILE || os.homedir();
+        return path.join(homeDir, spec.homeSubdir);
+    }
+    return path.join(cwd, spec.projectSubdir);
+}
+/**
+ * 把单个 SkillDoc 写入指定 agent 根目录。
+ *
+ * 落盘结构：
+ *   <root>/<name>/SKILL.md
+ *   <root>/<name>/references/<filename>   （每个 references 条目一个文件）
+ *
+ * 写入语义：
+ *   - 目录不存在则递归创建
+ *   - 同名文件直接覆盖（specdo 视 skill 文件为派生产物）
+ */
+function writeSkillDoc(doc, root) {
+    const written = [];
+    const skillDir = path.join(root, doc.name);
+    fs.mkdirSync(skillDir, { recursive: true });
+    // SKILL.md
+    const skillPath = path.join(skillDir, 'SKILL.md');
+    fs.writeFileSync(skillPath, renderSkillFile(doc), 'utf-8');
+    written.push(skillPath);
+    // references/*
+    if (doc.references) {
+        const refsDir = path.join(skillDir, 'references');
+        fs.mkdirSync(refsDir, { recursive: true });
+        for (const [filename, content] of Object.entries(doc.references)) {
+            const refPath = path.join(refsDir, filename);
+            fs.writeFileSync(refPath, content, 'utf-8');
+            written.push(refPath);
+        }
+    }
+    return written;
+}
+/**
+ * 清理 agent skill 根目录下以 `specdo-` 开头但不再属于当前导出列表的旧目录。
+ *
+ * 场景：skill 从 12 个缩减为 5 个后，用户重新 `specdo init` 时，旧的
+ * `specdo-domain-*` 和 `specdo-protocol-*` 目录会残留，导致 AI 工具同时
+ * 加载新 workflow skill 和旧 domain/protocol skill，产生冲突指令。
+ *
+ * 安全约束：
+ *   - 仅删除以 `specdo-` 开头的子目录（不碰用户自定义 skill）
+ *   - 跳过当前导出列表中存在的目录名
+ *   - 目录不存在时静默跳过
+ */
+function removeOrphanSpecdoSkills(root, currentSkillNames) {
+    const pruned = [];
+    let entries;
+    try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return pruned;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        if (!entry.name.startsWith('specdo-'))
+            continue;
+        if (currentSkillNames.has(entry.name))
+            continue;
+        const orphanDir = path.join(root, entry.name);
+        fs.rmSync(orphanDir, { recursive: true, force: true });
+        pruned.push(orphanDir);
+    }
+    return pruned;
+}
+/**
+ * 主导出函数：把 5 个 core workflow skill 写到指定 agent 的指定 scope 目录。
+ *
+ * 写入前会清理 agent skill 根目录下以 `specdo-` 开头但不再属于当前导出列表
+ * 的旧目录避免 AI 工具加载冲突指令。
+ */
+export function exportSkills(options) {
+    const { cwd, scope } = options;
+    const agentSet = new Set();
+    for (const agent of options.agents) {
+        if (!isAgentName(agent)) {
+            throw new Error(`Unknown agent target: ${String(agent)}`);
+        }
+        agentSet.add(agent);
+    }
+    const agents = [...agentSet];
+    const docs = collectAllSkills();
+    const currentSkillNames = new Set(docs.map((d) => d.name));
+    const filesWritten = [];
+    const pruned = [];
+    for (const agent of agents) {
+        const root = resolveAgentRoot(agent, scope, cwd);
+        pruned.push(...removeOrphanSpecdoSkills(root, currentSkillNames));
+        for (const doc of docs) {
+            const written = writeSkillDoc(doc, root);
+            filesWritten.push(...written);
+        }
+    }
+    return { filesWritten, skillCount: agents.length > 0 ? docs.length : 0, agents, skipped: [], pruned };
+}
+/** 导出供测试与命令层引用 */
+export const __INTERNAL = {
+    AGENT_REGISTRY,
+    WORKFLOW_SKILL_NAMES: WORKFLOW_CONTENT.map((s) => s.name),
+    resolveAgentRoot,
+    writeSkillDoc,
+    removeOrphanSpecdoSkills,
+};
+//# sourceMappingURL=skill-exporter.js.map