V1.0.0_beta

.agents/skills/add-converter/SKILL.md

@@ -1,69 +1,26 @@
 ---
 name: add-converter
-description: >-
-  Add a new resource type converter to acplugin (e.g., adding support for
-  converting a new Claude Code resource type)
+description: Add or change a canonical acplugin Component and its Platform compilation, including schema, Resource discovery, compatibility, Package Assets, and tests. Use when adding a new authoring resource or changing how Commands, Skills, or Agents compile.
 ---
 
-# 添加新资源类型转换器
+# Add a canonical Component
 
-当需要支持转换新的 Claude Code 资源类型时，按以下步骤操作。
+1. Decide whether the feature belongs in Core. Only cross-platform authoring concepts may become Components; optional horizontal capabilities belong in Extensions. Do not add Instructions as a Component.
+2. Add canonical and author contracts in `packages/core/src/contracts/components.ts`, with related configuration or public authoring surfaces kept in `packages/core/src/contracts/config.ts` and `packages/core/src/api/author.ts`. Keep Platform wire fields out of canonical types; use semantic fields and Platform-owned `platforms` metadata only where a verified capability requires it.
+3. Update the focused providers under `packages/core/src/resources/canonical/` and the graph in `packages/core/src/resources/project-graph.ts` with strict path, Frontmatter, identity, dependency, and symlink validation. Providers return normalized data and diagnostics, never Platform files.
+4. Update every built-in Platform owner under `packages/platforms/<id>/`. Each Platform decides its own native representation or explicit transformation and owns its Manifest, output paths, serialization, and candidate validation.
+5. For every Platform, report `native`, `transform`, `degraded`, or `unsupported`. Strict mode must fail on degraded/unsupported; relaxed mode must emit the explicit result and warning.
+6. Create only Core-signed AssetRef values, then map them into Platform base/final Package or add-only Extension Contribution. Platform/Extension code receives no physical output or workDir authority and never writes `dist` directly.
+7. Add Core schema/graph tests under `packages/core/test/contracts/` and `packages/core/test/resources/`, per-Platform golden/schema tests under `packages/platforms/<id>/test/`, and cross-package strictness/collision tests in the matching domain under `packages/test/test/platforms/` or another existing integration-test domain.
+8. Update the six-Platform compatibility tables, `AGENTS.md`, package README files, and the affected `llmdoc/` references.
 
-## 步骤
+Run:
 
-### 1. 定义类型 (`src/types.ts`)
-
-添加新资源的接口定义和 frontmatter 类型（如果有），以及在 `ScanResult` 中添加字段。在 `ConvertedFile.type` 联合类型中添加新值。
-
-### 2. 添加扫描函数 (`src/scanner/claude.ts`)
-
-创建并导出可复用的扫描函数（如 `scanXxxDir()`），这样 `plugin.ts` 也能使用。
-
-在 `scanClaudeProject()` 中调用新函数。
-
-### 3. 集成 Plugin Scanner (`src/scanner/plugin.ts`)
-
-在 `scanPlugin()` 中调用新扫描函数，注意 plugin 目录结构与 .claude/ 不同：
-- 项目: `.claude/xxx/`
-- Plugin: `xxx/`（直接在 plugin 根目录下）
-
-更新 `countResources()` 包含新资源。
-
-### 4. 创建 Converter (`src/converter/xxx.ts`)
-
-实现 `convertXxx(item, platform)` 函数，处理三个平台：
-
-```typescript
-export function convertXxx(item: Xxx, platform: Platform): ConvertedFile {
-  switch (platform) {
-    case 'codex': return convertToCodex(item);
-    case 'opencode': return convertToOpenCode(item);
-    case 'cursor': return convertToCursor(item);
-  }
-}
+```bash
+pnpm run lint
+pnpm run typecheck
+pnpm run test
+pnpm run build
 ```
 
-**关键原则**：
-- Converter 无副作用，只返回 `ConvertedFile`
-- 不支持的功能用降级策略（合并到 AGENTS.md 或 rules）
-- 返回 warnings 告知用户不兼容项
-
-### 5. 集成 Writer (`src/writer/*.ts`)
-
-在三个 writer 文件中调用新 converter，处理合并逻辑。
-
-### 6. 更新 CLI 输出 (`src/index.ts`)
-
-更新 `printScanResult()` 和 `convertSingleScan()` 中的资源计数。
-
-### 7. 添加测试 (`src/__tests__/xxx.test.ts`)
-
-为新 converter 创建测试，覆盖三个平台的转换逻辑。
-
-### 8. 更新 test-fixture/
-
-在 `test-fixture/` 中添加新资源类型的示例文件，确保 `scanner.test.ts` 覆盖。
-
-## Frontmatter 解析容错
-
-社区插件的 YAML 可能格式不规范。扫描函数中必须 try-catch `parseFrontmatter()`，解析失败时用空 frontmatter + 原始内容兜底。
+Preserve deterministic path ordering, stable diagnostics, transactional all-Platform behavior, and independent public Platform package/peer boundaries.

.agents/skills/add-platform/SKILL.md

@@ -1,75 +1,30 @@
 ---
 name: add-platform
-description: 'Add support for a new target platform to acplugin (e.g., Windsurf, Zed, etc.)'
+description: Add a new acplugin Platform through an independent public package and official Extension Contributors. Use when introducing another AI platform or revising a Platform manifest, Component, Hooks, MCP, Package, Distribution, or compatibility contract.
 ---
 
-# 添加新目标平台
-
-当需要支持新的 AI 编程工具作为转换目标时，按以下步骤操作。
-
-## 前置调研
-
-1. 了解目标平台的配置格式：
-   - Skills/技能文件格式和路径
-   - 自定义指令文件（类似 CLAUDE.md / AGENTS.md）
-   - MCP 服务器配置格式
-   - Agent 定义方式（如果有）
-   - 命令/斜杠命令格式
-   - Hooks 系统（如果有）
-
-2. 确认格式差异和降级策略
-
-## 实施步骤
-
-### 1. 类型注册 (`src/types.ts`)
-
-在 `Platform` 联合类型中添加新值：
-```typescript
-export type Platform = 'codex' | 'opencode' | 'cursor' | 'newplatform';
+# Add a Platform
+
+1. Verify the current target contract from primary documentation. Record whether delivery is a static Plugin, workspace overlay, or package; then record schema/path/install-root semantics, Component discovery, Hooks events/protocol, MCP transports/config, secret handling, and a real validation/install command.
+2. Create one independent public `packages/platforms/<id>/` package. It imports only `@tokenroll/acplugin/sdk`, declares the main package as a `workspace:^` peer, implements `definePlatform()`, and owns an accurate `deliveryType`.
+3. Keep all target-specific behavior in that package:
+   - validate Platform-specific Component fields;
+   - compile every canonical Component and report complete compatibility;
+   - own base Documents, extension points, Manifest fields, Package identity, and optional Distribution;
+   - create only Core-signed AssetRef values without direct output writes;
+   - validate identities, references, paths, tree closure, and the final materialized candidate.
+4. Do not add a main-package re-export/subpath, Core Platform-ID branch, package registry, or official-only lifecycle path. The main package bundles private Core but never bundles an official Platform/Extension.
+5. Add `PlatformContributor` implementations to Hooks/MCP only for verified capabilities. Every Contributor reads the same immutable base Package and returns an add-only Contribution; the Platform exposes controlled Document extension points and never imports an Extension.
+6. Add the Platform to CLI selection, init metadata, ecosystem version snapshot, docs, and release verifier only after compatibility and empty-state behavior are defined. Do not silently expand the default Claude Code + Codex cohort.
+7. Add package-owned golden/schema/candidate tests, strict/relaxed integration cases, real-consumer smoke appropriate to the delivery type, Hook runtime tests, MCP protocol tests, and owner/collision isolation.
+8. Update the Platform matrices, `AGENTS.md`, package docs, TypeDoc entry set, tarball consumer verification, primary-source links, and contract verification date.
+
+Run the full repository and packed-consumer checks:
+
+```bash
+pnpm run lint
+pnpm run typecheck
+pnpm run test
+pnpm run build
+pnpm run docs:check
 ```
-
-### 2. 每个 Converter 添加分支
-
-在所有 `src/converter/*.ts` 文件中，给 `switch (platform)` 添加新的 case。
-
-参考现有平台的转换逻辑，特别关注：
-- **路径映射**：新平台的目录结构
-- **Frontmatter 差异**：新平台是否需要特殊字段
-- **降级策略**：不支持的功能如何处理
-
-### 3. 创建 Writer (`src/writer/newplatform.ts`)
-
-复制 `cursor.ts` 作为模板，修改平台名：
-```typescript
-export function generateNewPlatform(scan: ScanResult): ConvertResult { ... }
-```
-
-### 4. CLI 注册 (`src/index.ts`)
-
-- `generateForPlatform()` 添加新 case
-- `validPlatforms` 数组添加新值
-- import 新 writer
-
-### 5. TUI 注册 (`src/tui.ts`)
-
-在 `selectPlatforms()` 的 choices 中添加新选项。
-
-### 6. 测试
-
-- 每个 converter 测试文件添加新平台的用例
-- 新增 `src/__tests__/newplatform-writer.test.ts`（可选）
-
-### 7. 文档
-
-- 更新 README.md 和 README.zh-CN.md 的支持矩阵表格
-- 更新 llmdoc/reference/conversion-matrix.md
-
-## 降级策略参考
-
-| 场景 | 推荐策略 |
-|------|---------|
-| 平台无 Agent 系统 | 降级为指令/规则文件 |
-| 平台无 Hooks | 记录为文档 + 输出 warning |
-| 平台 MCP 格式不同 | 做字段映射转换 |
-| 平台无 Skills 概念 | 转为命令或规则文件 |
-| Claude 特有字段 | 保留为 HTML 注释 |