spectra-cli 4.1.1

package/plugins/spec-driver/workflows/spec-driver-feature.yaml

@@ -0,0 +1,29 @@
+id: spec-driver-feature
+title: "新功能研发"
+persona: "功能开发者"
+useCases:
+  - "全新功能"
+  - "大型需求"
+  - "需要完整调研与质量门"
+entryCommand:
+  claude: "/spec-driver:spec-driver-feature <需求描述>"
+  codex: "$spec-driver-feature <需求描述>"
+requiredInputs:
+  - "需求描述"
+  - "项目宪法"
+keyGates:
+  - "GATE_RESEARCH"
+  - "GATE_DESIGN"
+  - "GATE_ANALYSIS"
+  - "GATE_TASKS"
+  - "GATE_VERIFY"
+artifacts:
+  - "specs/<feature>/research/"
+  - "specs/<feature>/spec.md"
+  - "specs/<feature>/plan.md"
+  - "specs/<feature>/tasks.md"
+  - "specs/<feature>/verification/verification-report.md"
+recommendedWhen:
+  - "需求范围较大"
+  - "需要完整调研、规划和验证闭环"
+templateVersion: "1.0.0"

package/plugins/spec-driver/workflows/spec-driver-fix.yaml

@@ -0,0 +1,21 @@
+id: spec-driver-fix
+title: "快速问题修复"
+persona: "修复者"
+useCases:
+  - "Bug 修复"
+  - "定位与修复回归问题"
+entryCommand:
+  claude: "/spec-driver:spec-driver-fix <问题描述>"
+  codex: "$spec-driver-fix <问题描述>"
+requiredInputs:
+  - "问题描述"
+keyGates:
+  - "GATE_VERIFY"
+artifacts:
+  - "specs/<feature>/spec.md"
+  - "specs/<feature>/tasks.md"
+  - "specs/<feature>/verification/verification-report.md"
+recommendedWhen:
+  - "问题范围明确"
+  - "需要最短修复闭环"
+templateVersion: "1.0.0"

package/plugins/spec-driver/workflows/spec-driver-implement.yaml

@@ -0,0 +1,23 @@
+id: spec-driver-implement
+title: "成熟 Spec 实施"
+persona: "实施负责人"
+useCases:
+  - "已具备成熟 spec.md 与 plan.md"
+  - "聚焦计划审查、任务细化、代码实施与验证"
+entryCommand:
+  claude: "/spec-driver:spec-driver-implement [<feature-dir-or-id>]"
+  codex: "$spec-driver-implement [<feature-dir-or-id>]"
+requiredInputs:
+  - "specs/<feature>/spec.md"
+  - "specs/<feature>/plan.md"
+keyGates:
+  - "GATE_TASKS"
+  - "GATE_VERIFY"
+artifacts:
+  - "specs/<feature>/plan.md"
+  - "specs/<feature>/tasks.md"
+  - "specs/<feature>/verification/verification-report.md"
+recommendedWhen:
+  - "需求与设计已成熟，只需聚焦实施和验证"
+  - "希望避免重复调研与重写 spec/plan"
+templateVersion: "1.0.0"

package/plugins/spec-driver/workflows/spec-driver-resume.yaml

@@ -0,0 +1,20 @@
+id: spec-driver-resume
+title: "恢复中断流程"
+persona: "流程恢复者"
+useCases:
+  - "上次 feature/story/fix 流程中断"
+  - "从已有产物断点继续"
+entryCommand:
+  claude: "/spec-driver:spec-driver-resume"
+  codex: "$spec-driver-resume"
+requiredInputs:
+  - "已存在的 specs/<feature>/ 制品"
+keyGates:
+  - "GATE_VERIFY"
+artifacts:
+  - "复用既有特性目录"
+  - "补齐缺失阶段制品"
+recommendedWhen:
+  - "不想重跑完整流程"
+  - "需要在已有产物上继续推进"
+templateVersion: "1.0.0"

package/plugins/spec-driver/workflows/spec-driver-story.yaml

@@ -0,0 +1,24 @@
+id: spec-driver-story
+title: "快速需求实现"
+persona: "迭代开发者"
+useCases:
+  - "中等规模增量需求"
+  - "已有上下文的功能迭代"
+entryCommand:
+  claude: "/spec-driver:spec-driver-story <需求描述>"
+  codex: "$spec-driver-story <需求描述>"
+requiredInputs:
+  - "需求描述"
+  - "现有代码上下文"
+keyGates:
+  - "GATE_DESIGN"
+  - "GATE_VERIFY"
+artifacts:
+  - "specs/<feature>/spec.md"
+  - "specs/<feature>/plan.md"
+  - "specs/<feature>/tasks.md"
+  - "specs/<feature>/verification/verification-report.md"
+recommendedWhen:
+  - "不需要完整市场或技术调研"
+  - "目标是快速交付增量能力"
+templateVersion: "1.0.0"

package/plugins/spec-driver/workflows/spec-driver-sync.yaml

@@ -0,0 +1,34 @@
+id: spec-driver-sync
+title: "产品事实聚合"
+persona: "产品文档负责人"
+useCases:
+  - "聚合增量 spec"
+  - "更新 current-spec 与产品 Catalog"
+entryCommand:
+  claude: "/spec-driver:spec-driver-sync"
+  codex: "$spec-driver-sync"
+requiredInputs:
+  - "specs/NNN-xxx/spec.md"
+  - "产品映射或可推断产品归属"
+keyGates:
+  - "GATE_RESEARCH"
+artifacts:
+  - "specs/products/product-mapping.yaml"
+  - "specs/products/<product>/current-spec.md"
+  - "specs/products/<product>/_generated/entity.yaml"
+  - "specs/products/_generated/catalog-index.yaml"
+  - "specs/products/<product>/_generated/quality-report.md"
+  - "specs/products/<product>/_generated/quality-report.json"
+  - "specs/products/_generated/quality-report-index.yaml"
+  - "specs/products/<product>/_generated/scorecard-report.md"
+  - "specs/products/<product>/_generated/scorecard-report.json"
+  - "specs/products/_generated/scorecard-index.yaml"
+  - "specs/products/spec-driver/_generated/adoption-report.md"
+  - "specs/products/spec-driver/_generated/adoption-report.json"
+  - ".specify/project-context.suggestions.yaml"
+  - ".specify/project-context.suggestions.md"
+recommendedWhen:
+  - "需要刷新产品事实源"
+  - "为 doc/scorecard/adoption 提供上游事实"
+  - "需要刷新持续治理与反馈视图"
+templateVersion: "1.0.0"

package/plugins/spectra/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "spectra",
+  "version": "4.1.1",
+  "description": "把任意代码库变成可查询、可视化、可按场景伸缩的代码阅读平台。AST + LLM 混合 pipeline 生成分层 Spec、知识图谱、技术债清单、自然语言问答与交互式 graph.html",
+  "author": {
+    "name": "Connor Lu",
+    "url": "https://github.com/connor-git-yaml"
+  },
+  "homepage": "https://github.com/connor-git-yaml/cc-plugin-market",
+  "repository": "https://github.com/connor-git-yaml/cc-plugin-market",
+  "license": "MIT",
+  "keywords": [
+    "spectra",
+    "spec",
+    "ast",
+    "documentation",
+    "claude-code"
+  ],
+  "mcpServers": "./.mcp.json"
+}

package/plugins/spectra/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "spectra": {
+      "command": "spectra",
+      "args": ["mcp-server"]
+    }
+  }
+}

package/plugins/spectra/README.md

@@ -0,0 +1,128 @@
+# Spectra — Claude Code Plugin
+
+> 当前发布版本: v4.1.1
+
+通过 AST 静态分析 + LLM 混合流水线，将遗留源代码逆向工程为结构化 Spec 文档。
+
+## 功能
+
+### Skills（3 个）
+
+| Skill | 触发方式 | 说明 |
+|-------|---------|------|
+| `spectra` | `/spectra <path>` | 对单个文件或目录生成 9 段式 Spec 文档 |
+| `spectra-batch` | `/spectra-batch` | 批量生成整个项目的 Spec（按模块级聚合） |
+| `spectra-diff` | `/spectra-diff` | 检测 Spec 与源代码之间的漂移 |
+
+### MCP Server（4 个工具）
+
+通过 MCP 协议暴露以下工具供 Claude Code 直接调用：
+
+| 工具 | 说明 |
+|------|------|
+| `prepare` | AST 预处理 + 上下文组装（无需 API Key） |
+| `generate` | 完整 Spec 生成流水线 |
+| `batch` | 批量 Spec 生成 |
+| `diff` | Spec 漂移检测 |
+
+## 安装方式
+
+### 方式一：Marketplace 安装（推荐）
+
+1. 将本仓库添加为 Claude Code Plugin Marketplace（命令只接收一个 source 参数；marketplace 名 `cc-plugin-market` 由 `.claude-plugin/marketplace.json` 定义）：
+
+   ```bash
+   # GitHub 简写（推荐）
+   claude plugin marketplace add connor-git-yaml/cc-plugin-market
+
+   # 或使用完整 HTTPS URL
+   claude plugin marketplace add https://github.com/connor-git-yaml/cc-plugin-market.git
+   ```
+
+2. 安装 Spectra plugin：
+
+   ```bash
+   claude plugin install spectra
+   ```
+
+3. 重启 Claude Code 会话，plugin 自动加载。
+
+### 方式二：npm 全局安装
+
+```bash
+npm install -g spectra-cli
+```
+
+安装后可直接使用 CLI：
+
+```bash
+spectra generate src/auth/ --deep
+spectra batch --force
+spectra diff specs/auth.spec.md src/auth/
+spectra mcp-server  # 启动 MCP stdio server
+```
+
+## 配置
+
+## Skill Source Contract
+
+- `plugins/spectra/skills/**` 是 Spectra Skill 的 **canonical source**
+- `src/skills-global/**` 与 `skills/**` 是 compatibility mirrors，不再手工维护
+- 同步命令：
+
+  ```bash
+  npm run spectra:sync:skills
+  ```
+
+- 校验命令：
+
+  ```bash
+  npm run spectra:check:skills
+  ```
+
+若本次改动同时触及 release contract、shared docs 或 spec-driver 包装层，优先直接运行：
+
+```bash
+npm run repo:sync
+npm run repo:check
+```
+
+### 认证
+
+支持两种认证方式（自动检测，优先级从高到低）：
+
+1. **ANTHROPIC_API_KEY** 环境变量 — 直接 SDK 调用
+2. **Claude Code CLI 订阅登录** — spawn CLI 子进程代理
+
+### MCP Server 配置
+
+Plugin 安装后，`.mcp.json` 自动配置 MCP server：
+
+```json
+{
+  "mcpServers": {
+    "spectra": {
+      "command": "npx",
+      "args": ["spectra", "mcp-server"],
+      "cwd": "${CLAUDE_PLUGIN_ROOT}"
+    }
+  }
+}
+```
+
+## 使用示例
+
+```bash
+# 单模块 Spec 生成
+/spectra src/auth/
+
+# 批量生成
+/spectra-batch
+
+# 漂移检测
+/spectra-diff specs/auth.spec.md src/auth/
+```
+
+## 许可证
+
+MIT

package/plugins/spectra/contracts/skill-source-of-truth.yaml

@@ -0,0 +1,34 @@
+schemaVersion: 1
+plugin:
+  id: "spectra"
+  sourceRoot: "plugins/spectra"
+  metadataSource: "plugins/spectra/.claude-plugin/plugin.json"
+  marketplaceManifest: ".claude-plugin/marketplace.json"
+
+skills:
+  canonicalRoot: "plugins/spectra/skills"
+  generator:
+    script: "plugins/spectra/scripts/sync-skill-mirrors.mjs"
+    command: "npm run spectra:sync:skills"
+  entries:
+    - id: "spectra"
+      source: "plugins/spectra/skills/spectra/SKILL.md"
+      mirrors:
+        - id: "published-compat"
+          path: "src/skills-global/spectra/SKILL.md"
+        - id: "repo-local-compat"
+          path: "skills/spectra/SKILL.md"
+    - id: "spectra-batch"
+      source: "plugins/spectra/skills/spectra-batch/SKILL.md"
+      mirrors:
+        - id: "published-compat"
+          path: "src/skills-global/spectra-batch/SKILL.md"
+        - id: "repo-local-compat"
+          path: "skills/spectra-batch/SKILL.md"
+    - id: "spectra-diff"
+      source: "plugins/spectra/skills/spectra-diff/SKILL.md"
+      mirrors:
+        - id: "published-compat"
+          path: "src/skills-global/spectra-diff/SKILL.md"
+        - id: "repo-local-compat"
+          path: "skills/spectra-diff/SKILL.md"

package/plugins/spectra/hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/postinstall.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/spectra/scripts/postinstall.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+# spectra plugin — 环境检查脚本
+# 在 SessionStart 时执行，确保 CLI 工具可用
+set -euo pipefail
+
+if command -v spectra >/dev/null 2>&1; then
+  echo "[spectra] CLI 已就绪 ($(spectra --version 2>/dev/null || echo 'unknown version'))" >&2
+else
+  echo "[spectra] CLI 未找到。请执行以下命令安装后重新启动 Claude Code：" >&2
+  echo "  npm install -g spectra-cli" >&2
+  echo "[spectra] 安装完成前 MCP server 无法启动。" >&2
+fi

package/plugins/spectra/scripts/sync-skill-mirrors.mjs

@@ -0,0 +1,148 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseYamlDocument } from '../../spec-driver/scripts/lib/simple-yaml.mjs';
+
+function parseArgs(argv) {
+  const options = {
+    projectRoot: process.cwd(),
+    json: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--project-root') {
+      const value = argv[index + 1];
+      if (!value) {
+        throw new Error('缺少 --project-root 参数值');
+      }
+      options.projectRoot = path.resolve(value);
+      index += 1;
+      continue;
+    }
+    if (arg === '--json') {
+      options.json = true;
+      continue;
+    }
+    if (arg === '--help' || arg === '-h') {
+      options.help = true;
+      continue;
+    }
+    throw new Error(`未知参数: ${arg}`);
+  }
+
+  return options;
+}
+
+export function loadSkillSourceContract(projectRoot) {
+  const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+  const contractPath = path.resolve(
+    scriptDir,
+    '..',
+    'contracts',
+    'skill-source-of-truth.yaml',
+  );
+  const contract = parseYamlDocument(fs.readFileSync(contractPath, 'utf-8'));
+  return { contractPath, contract };
+}
+
+function toProjectRelative(projectRoot, targetPath) {
+  const root = fs.realpathSync(projectRoot);
+  const target = fs.realpathSync(targetPath);
+  return path.relative(root, target).split(path.sep).join('/');
+}
+
+function syncMirrors(projectRoot, contract) {
+  const entries = Array.isArray(contract.skills?.entries)
+    ? contract.skills.entries
+    : [];
+  const results = [];
+
+  for (const entry of entries) {
+    const sourcePath = path.resolve(projectRoot, entry.source);
+    if (!fs.existsSync(sourcePath)) {
+      throw new Error(`缺少 canonical source skill: ${entry.source}`);
+    }
+
+    const content = fs.readFileSync(sourcePath, 'utf-8');
+    const mirrors = Array.isArray(entry.mirrors) ? entry.mirrors : [];
+    const synced = [];
+
+    for (const mirror of mirrors) {
+      const targetPath = path.resolve(projectRoot, mirror.path);
+      fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+      fs.writeFileSync(targetPath, content, 'utf-8');
+      synced.push({
+        id: mirror.id,
+        path: mirror.path,
+      });
+    }
+
+    results.push({
+      id: entry.id,
+      source: entry.source,
+      synced,
+    });
+  }
+
+  return results;
+}
+
+function formatText(result) {
+  const lines = ['[spectra-skills] synchronized', ''];
+  for (const entry of result.entries) {
+    lines.push(`- ${entry.id}`);
+    lines.push(`  source: ${entry.source}`);
+    for (const mirror of entry.synced) {
+      lines.push(`  -> ${mirror.id}: ${mirror.path}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+export function syncSpectraSkillMirrors(options = {}) {
+  const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
+  const { contractPath, contract } = loadSkillSourceContract(projectRoot);
+  const entries = syncMirrors(projectRoot, contract);
+  return {
+    status: 'pass',
+    contractPath: toProjectRelative(projectRoot, contractPath),
+    entries,
+  };
+}
+
+function main() {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.help) {
+    console.log(
+      '用法: node plugins/spectra/scripts/sync-skill-mirrors.mjs --project-root . [--json]',
+    );
+    return;
+  }
+
+  const result = syncSpectraSkillMirrors(options);
+
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log(formatText(result));
+}
+
+function isDirectExecution() {
+  if (!process.argv[1]) {
+    return false;
+  }
+  return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+}
+
+if (isDirectExecution()) {
+  try {
+    main();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    process.exit(1);
+  }
+}