cc-devflow 4.3.0 → 4.5.0

package/docs/v4.3.0-migration-guide.md

@@ -2,275 +2,110 @@
 
 ## Overview
 
-CC-DevFlow v4.3.0 introduces automatic TDD order validation and OpenSpec interoperability to solve requirement drift problems. This guide helps you migrate from v4.2.x to v4.3.0.
+This guide is for teams moving from the old slash-command and harness-heavy mental model to the current skills-first distribution model.
 
----
+The key change is simple:
+
+- visible workflow surface: skills
+- distribution surface: `cc-devflow init` and `cc-devflow adapt`
+- shared skill runtime: internal implementation detail
 
-## What's New in v4.3.0
+---
 
-### 1. Automatic TDD Order Validation
+## What Changed
 
-**Feature**: The harness planner now automatically validates TDD order when parsing TASKS.md.
+### 1. Workflow Entry Changed
 
-**Impact**:
-- [IMPL] tasks MUST depend on corresponding [TEST] tasks
-- [TEST] tasks CANNOT depend on [IMPL] tasks
-- Violations throw detailed error messages at `harness:plan` time
+Old mental model:
 
-**Example Error**:
+```text
+/flow:init -> /flow:spec -> /flow:dev -> /flow:verify -> /flow:release
 ```
-TDD Order Validation Failed (Constitution Article VI):
 
-1. Task T002 (用户登录实现) missing corresponding TEST task.
-   Constitution Article VI requires: NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST.
+Current mental model:
 
-2. Task T004 (用户注册实现) must depend on T003 (用户注册测试).
-   TDD violation: Implementation must come AFTER test.
-```
+```text
+cc-roadmap
 
-**Migration Steps**:
-1. Review your existing TASKS.md files
-2. Ensure all [IMPL] tasks have corresponding [TEST] tasks
-3. Add `dependsOn` to [IMPL] tasks pointing to [TEST] tasks
-4. Use `[P]` marker for parallel tasks that don't follow TEST→IMPL pattern
-
-**Example Fix**:
-```markdown
-<!-- Before (INVALID) -->
-- [ ] T001 [IMPL] 用户登录实现
-- [ ] T002 [TEST] 用户登录测试
-
-<!-- After (VALID) -->
-- [ ] T001 [TEST] 用户登录测试
-- [ ] T002 [IMPL] 用户登录实现 (dependsOn:T001)
+cc-plan -> cc-do -> cc-check -> cc-act
 ```
 
-### 2. OpenSpec Interoperability
-
-**Feature**: Bidirectional conversion between OpenSpec and CC-DevFlow formats.
+The workflow is now represented by explicit skills rather than a slash-command namespace.
 
-**New Commands**:
-- `/flow:import-openspec` - Import OpenSpec spec.md to CC-DevFlow
-- `/flow:export-openspec` - Export CC-DevFlow spec.md to OpenSpec
+### 2. Distribution Entry Changed
 
-**Use Cases**:
+Whole-pack install and platform adaptation now belong to the packaged CLI:
 
-#### Import from OpenSpec
 ```bash
-/flow:import-openspec "/path/to/openspec/specs/auth/spec.md" \
-  --req-id "REQ-123" \
-  --title "用户认证系统"
+npx cc-devflow init --dir /path/to/project
+npx cc-devflow adapt --cwd /path/to/project --platform codex
 ```
 
-**What happens**:
-1. Parses OpenSpec format (Purpose + Requirements + BDD scenarios)
-2. Generates CC-DevFlow spec.md with YAML frontmatter
-3. Auto-generates TDD tasks (TEST + IMPL pairs with correct dependencies)
-4. Adds Design section with [NEEDS CLARIFICATION] markers
-5. Generates Verification checklist
+### 3. `skills.sh` Scope Narrowed
+
+`skills.sh` remains supported, but only for single-skill distribution:
 
-#### Export to OpenSpec
 ```bash
-/flow:export-openspec "REQ-123" \
-  --output "/path/to/openspec/specs/auth/spec.md"
+npx skills add https://github.com/Dimon94/cc-devflow --skill cc-roadmap
 ```
 
-**What happens**:
-1. Parses CC-DevFlow spec.md
-2. Strips YAML frontmatter and metadata
-3. Removes Design, Tasks, Verification sections
-4. Removes [NEEDS CLARIFICATION] markers
-5. Outputs pure Requirements in OpenSpec format
-
-**Round-Trip Guarantee**: Requirements are preserved through import→export→import cycles.
-
----
-
-## Breaking Changes
-
-### 1. TASKS.md Validation
-
-**Before v4.3.0**: TDD order was recommended but not enforced.
+Do not use `skills.sh` as the whole-pack lifecycle anymore.
 
-**After v4.3.0**: TDD order is enforced at `harness:plan` time.
+### 4. `.claude/commands/` Is Optional
 
-**Migration**: Update existing TASKS.md files to follow TDD order.
+The compiler still accepts legacy prompt inputs if a project has `.claude/commands/`, but the repository no longer requires that directory to exist.
 
-### 2. Task Type Detection
+Skills-first repositories are valid.
 
-**Before v4.3.0**: Task types were not tracked.
+### 5. Harness CLI Is Gone
 
-**After v4.3.0**: Tasks are classified as TEST/IMPL/OTHER based on markers.
+`harness:*` is no longer the public CLI surface.
 
-**Migration**: Ensure your TASKS.md uses `[TEST]` and `[IMPL]` markers consistently.
+Shared support code may still exist under `lib/skill-runtime/`, but it should be treated as internal runtime support for the public skills.
 
 ---
 
-## Feature Name Matching Algorithm
+## Old To New Mapping
 
-The TDD validator uses intelligent fuzzy matching to pair TEST and IMPL tasks:
-
-**Normalization Rules**:
-- Removes suffixes: "测试", "实现", "功能", "开发", "编写"
-- Trims whitespace
-- Compares core feature names
-
-**Examples**:
-```
-"用户登录功能测试" ↔ "用户登录功能实现" ✅ Match
-"用户登录测试"     ↔ "用户登录实现"     ✅ Match
-"用户登录"         ↔ "用户登录功能"     ✅ Match
-"用户登录"         ↔ "用户注册"         ❌ No match
-```
+| Old Concept | New Concept |
+|-------------|-------------|
+| `/flow:*` | visible skills |
+| `harness:*` CLI | internal skill runtime only |
+| clone `.claude` manually | `cc-devflow init` |
+| per-platform handwritten setup | `cc-devflow adapt` |
+| skills pack via old CLI lifecycle | whole pack via `cc-devflow`, single skill via `skills.sh` |
 
 ---
 
-## Parallel Tasks
+## Migration Checklist
 
-For tasks that don't follow TEST→IMPL pattern, use the `[P]` marker:
-
-```markdown
-- [ ] T001 [TEST] 用户登录测试
-- [ ] T002 [IMPL] 用户登录实现 (dependsOn:T001)
-- [ ] T003 [OTHER] 数据库迁移 [P]
-- [ ] T004 [OTHER] 配置文件更新 [P]
-```
-
-The `[P]` marker tells the validator to skip dependency checks for that task.
+1. Replace old workflow references in docs with the five visible skills.
+2. Replace old pack-install steps with `cc-devflow init`.
+3. Replace old platform setup steps with `cc-devflow adapt`.
+4. Keep `skills.sh` only for single-skill install or refresh.
+5. Treat `.claude/commands/` as optional compatibility input, not required structure.
+6. Stop documenting `harness:*` as if users should run it directly.
 
 ---
 
-## OpenSpec Format Reference
-
-### OpenSpec Format (Input)
-```markdown
-# Authentication Module
-
-## Purpose
-Provides secure authentication and session management.
-
-## Requirements
-
-### Requirement: User Login
-The system SHALL allow users to log in with email and password.
-
-#### Scenario: Valid credentials
-- GIVEN a registered user
-- WHEN the user submits valid email and password
-- THEN a JWT token is issued
-- AND the user is redirected to dashboard
-```
-
-### CC-DevFlow Format (Output)
-```markdown
----
-req_id: "REQ-123"
-title: "用户认证系统"
-created_at: "2026-03-13T10:00:00Z"
-version: "1.0.0"
-status: "draft"
-source: "openspec"
----
-
-# Authentication Module
-
-## Purpose
-Provides secure authentication and session management.
-
-## Requirements
-
-### Requirement: User Login
-The system SHALL allow users to log in with email and password.
-
-#### Scenario: Valid credentials
-- GIVEN a registered user
-- WHEN the user submits valid email and password
-- THEN a JWT token is issued
-- AND the user is redirected to dashboard
-
-## Design
-[NEEDS CLARIFICATION: 技术实现方案]
-
-## Tasks
-- [ ] T001 [TEST] User Login - 测试
-- [ ] T002 [IMPL] User Login - 实现 (dependsOn:T001)
-
 ## Verification
-- [ ] User Login
-  - [ ] Valid credentials
-```
-
----
-
-## Testing
 
-All v4.3.0 features are covered by automated tests:
+After migration, these commands should succeed:
 
 ```bash
-# Run all tests
-npm test
-
-# Run TDD validation tests only
-npm test -- planner.tdd.test.js
-
-# Run OpenSpec interop tests only
-npm test -- openspec.test.js
+npx cc-devflow --help
+npx cc-devflow init --dir /tmp/cc-devflow-demo
+npx cc-devflow adapt --cwd /tmp/cc-devflow-demo --platform codex
 ```
 
-**Test Coverage**:
-- TDD validation: 10 tests (all passing)
-- OpenSpec interop: 5 tests (all passing)
-- Total: 233 tests (all passing)
-
----
-
-## Troubleshooting
-
-### Error: "Task T002 missing corresponding TEST task"
-
-**Cause**: An [IMPL] task has no matching [TEST] task.
-
-**Solution**: Add a [TEST] task with similar feature name before the [IMPL] task.
-
-### Error: "Task T002 must depend on T001"
-
-**Cause**: An [IMPL] task doesn't depend on its corresponding [TEST] task.
-
-**Solution**: Add `(dependsOn:T001)` to the [IMPL] task.
-
-### Error: "Task T001 depends on IMPL tasks"
-
-**Cause**: A [TEST] task depends on an [IMPL] task (reverse TDD order).
+And the installed project should contain:
 
-**Solution**: Remove the dependency or reorder tasks.
-
-### Feature Name Mismatch
-
-**Cause**: TEST and IMPL tasks have very different feature names.
-
-**Solution**: Rename tasks to have similar core feature names, or use `[P]` marker if they're truly independent.
-
----
-
-## Rollback
-
-If you need to rollback to v4.2.0:
-
-```bash
-npm install cc-devflow@4.2.0
+```text
+.claude/skills/cc-roadmap/SKILL.md
+.claude/skills/cc-plan/SKILL.md
+.claude/skills/cc-investigate/SKILL.md
+.claude/skills/cc-do/SKILL.md
+.claude/skills/cc-check/SKILL.md
+.claude/skills/cc-act/SKILL.md
+.claude/skills/cc-simplify/SKILL.md
 ```
-
-Note: v4.2.0 does not have TDD validation or OpenSpec interop features.
-
----
-
-## Support
-
-- GitHub Issues: https://github.com/anthropics/cc-devflow/issues
-- Documentation: https://github.com/anthropics/cc-devflow/tree/main/docs
-- Constitution: `.claude/rules/project-constitution.md`
-
----
-
-**Last Updated**: 2026-03-13
-**Version**: 4.3.0

package/lib/compiler/CLAUDE.md

@@ -1,125 +1,96 @@
-# Command Emitter - Compiler Module Architecture
+# Skills-First Compiler Module Architecture
 
 ## Purpose
-Multi-platform compiler that transforms `.claude/` modules (commands, skills, agents, rules, hooks) into native formats for Codex, Cursor, Qwen, and Antigravity platforms.
+Multi-platform compiler that transforms `.claude/skills/` plus optional `.claude/commands/*.md` into native outputs for Codex, Cursor, Qwen, and Antigravity platforms.
 
-## Architecture (v3.0)
+## Architecture
 
 ```
 lib/compiler/
-├── parser.js           # Parse .md files, extract frontmatter + detect placeholders
+├── parser.js           # Parse optional command .md files, extract frontmatter + detect placeholders
 ├── transformer.js      # Expand {SCRIPT:*}, {AGENT_SCRIPT}, map $ARGUMENTS
 ├── manifest.js         # Incremental compilation, drift detection
-├── schemas.js          # Zod validation schemas (CommandIR, Manifest)
+├── schemas.js          # Zod validation schemas (PromptIR, Manifest)
 ├── errors.js           # Custom error types (MissingFrontmatter, UnknownAlias, etc.)
 ├── skills-registry.js  # Generate skills registry from .claude/skills/
-├── skill-discovery.js  # Recursive SKILL.md discovery (grouped + root skills)
-├── resource-copier.js  # Resource collection/copy and .claude path rewriting
-├── platforms.js        # Platform configuration registry (v2.0)
-├── context-expander.js # context.jsonl expansion (v3.0)
 ├── index.js            # Compiler entry point, orchestrates pipeline
-├── emitters/
-│   ├── base-emitter.js       # Abstract base class (v2.0: multi-module support)
-│   ├── codex-emitter.js      # .codex/prompts/*.md, .codex/skills/*, AGENTS.md
-│   ├── cursor-emitter.js     # .cursor/commands/*.md, .cursor/rules/*.mdc, subagents/
-│   ├── qwen-emitter.js       # .qwen/commands/*.toml, .qwen/agents/*, CONTEXT.md
-│   ├── antigravity-emitter.js # .agent/workflows/*.md, .agent/skills/*, rules/
-│   └── index.js              # Emitter factory
-└── rules-emitters/           # Legacy rules emitters (deprecated)
-    └── ...
+└── emitters/
+    ├── base-emitter.js       # Abstract base class
+    ├── codex-emitter.js      # .codex/prompts/*.md (YAML frontmatter)
+    ├── cursor-emitter.js     # .cursor/commands/*.md (pure Markdown)
+    ├── qwen-emitter.js       # .qwen/commands/*.toml (TOML format)
+    ├── antigravity-emitter.js # .agent/workflows/*.md (12K limit, auto-split)
+    └── index.js              # Emitter factory
 ```
 
-## Multi-Module Compilation (v3.0)
-
-### Supported Modules
-
-| Module | Source | Codex | Cursor | Qwen | Antigravity |
-|--------|--------|-------|--------|------|-------------|
-| skills | `.claude/skills/` | `.codex/skills/` | `.cursor/rules/*.mdc` | `.qwen/commands/*.toml` | `.agent/skills/` |
-| commands | `.claude/commands/` | `.codex/prompts/` | `.cursor/commands/` | `.qwen/commands/` | `.agent/workflows/` |
-| agents | `.claude/agents/` | `AGENTS.md` | `.cursor/subagents/` | `.qwen/agents/` | `AGENTS.md` |
-| rules | `.claude/rules/` | `AGENTS.md` | `.cursor/rules/*.mdc` | `CONTEXT.md` | `.agent/rules/` |
-| hooks | `.claude/hooks/` | ❌ | `hooks.json` + `hooks/` | ❌ | ❌ |
-
-### Data Flow (v3.0)
+## Data Flow
 
 ```
-.claude/
-├── skills/*/SKILL.md
-├── commands/*.md
-├── agents/*.md
-├── rules/*.md
-└── hooks/*.ts
+.claude/skills/
         │
-        ▼
-┌─────────────────────┐
-│  compileMultiModule │ Orchestrates all modules
-│     (index.js)      │
-└────────┬────────────┘
+        ├──────────────► skills-registry.json + platform rules
+        │
+        └── optional `.claude/commands/*.md`
+                         │
+                         ▼
+┌─────────────────┐
+│     Parser      │ gray-matter → PromptIR
+│  (parser.js)    │ - Extract frontmatter
+│                 │ - Detect placeholders
+│                 │ - Compute SHA-256 hash
+└────────┬────────┘
+         │ PromptIR[]
+         ▼
+┌─────────────────┐
+│   Transformer   │ Platform-specific transforms
+│(transformer.js) │ - {SCRIPT:alias} → "bash <path>"
+│                 │ - $ARGUMENTS → {{args}} / [arguments]
+│                 │ - {AGENT_SCRIPT} + __AGENT__ substitution
+└────────┬────────┘
+         │ TransformedContent
+         ▼
+┌─────────────────┐
+│    Emitters     │ Platform format + file write
+│ (emitters/*.js) │ - Codex: MD + YAML frontmatter
+│                 │ - Cursor: pure MD
+│                 │ - Qwen: TOML
+│                 │ - Antigravity: MD + YAML (12K limit)
+└────────┬────────┘
          │
-    ┌────┴────┬────────┬────────┬────────┐
-    ▼         ▼        ▼        ▼        ▼
-┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐
-│Skills │ │Commands│ │Agents │ │Rules  │ │Hooks  │
-│Emitter│ │Emitter │ │Emitter│ │Emitter│ │Emitter│
-└───┬───┘ └───┬───┘ └───┬───┘ └───┬───┘ └───┬───┘
-    │         │        │        │        │
-    ▼         ▼        ▼        ▼        ▼
-Platform-specific output directories
+         ▼
+┌─────────────────┐
+│    Manifest     │ devflow/.generated/manifest.json
+│ (manifest.js)   │ - Track source/target hashes
+│                 │ - Enable incremental compilation
+│                 │ - Detect drift
+└─────────────────┘
 ```
 
 ## CLI Usage
 
 ```bash
-# Compile commands + modules
 npm run adapt                       # Compile all platforms
 npm run adapt -- --platform codex   # Compile single platform
 npm run adapt -- --check            # Drift detection only
-
-# v3.0: Multi-module compilation
-npm run adapt -- --modules skills,commands,agents,rules
-npm run adapt -- --modules skills --platform cursor
-```
-
-## Key APIs
-
-### compile(options) - Main Flow
-Compiles commands and emits platform modules (skills, agents, rules, hooks).
-
-### compileMultiModule(options) - v3.0
-Compiles all specified modules.
-
-```javascript
-const { compileMultiModule } = require('./lib/compiler');
-
-await compileMultiModule({
-  sourceBaseDir: '.claude/',
-  outputBaseDir: '.',
-  platforms: ['codex', 'cursor', 'qwen', 'antigravity'],
-  modules: ['skills', 'commands', 'agents', 'rules'],
-  verbose: true
-});
+npm run adapt -- --skills           # Generate skills-registry.json
+npm run adapt -- --verbose          # Detailed output
 ```
 
 ## Key Schemas
 
-- **CommandIR**: Intermediate representation after parsing
+- **PromptIR**: Intermediate representation after parsing
 - **ManifestEntry**: Single compilation record (source, target, hash, platform)
 - **Manifest**: Complete compilation history
-- **PlatformConfig**: Platform-specific configuration (v2.0)
 
 ## Dependencies
 
 - `gray-matter`: Frontmatter parsing
 - `@iarna/toml`: TOML serialization (Qwen)
-- `js-yaml`: YAML serialization (Codex, Antigravity, Cursor)
+- `js-yaml`: YAML serialization (Codex, Antigravity)
 - `zod`: Schema validation
 
 ---
 
 **Created**: 2025-12-18
-**Updated**: 2026-02-07
-**REQ**: REQ-005 (RM-007), Multi-Platform Adaptation
-**Version**: 3.0.0
-
-[PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+**REQ**: REQ-005 (RM-007)
+**Version**: 1.0.0

package/lib/compiler/__tests__/drift.test.js

@@ -124,7 +124,7 @@ describe('Drift Detection', () => {
 
   describe('Rules Entry Drift Detection', () => {
     test('should include rules entry files in drift check', async () => {
-      // 规则入口文件应该和普通命令文件一样被检测
+      // 规则入口文件应该和其他编译产物一样被检测
       // 这需要在 Phase 4 扩展 checkDrift 函数
 
       const { checkDrift, hashContent, addRulesEntry, createManifest } = require('../manifest');

package/lib/compiler/__tests__/errors.test.js

@@ -1,7 +1,6 @@
 /**
  * T010: Error Types Tests
  * Tests for compiler error classes
- * Expected: All tests FAIL (errors not implemented)
  */
 
 // ============================================================

package/lib/compiler/__tests__/integration.test.js

@@ -41,6 +41,52 @@ describe('Full Compilation Integration', () => {
       // expect(result.skillsRegistered).toBeGreaterThan(0);
     });
 
+    test('should allow skills-first compilation without .claude/commands', async () => {
+      const { compile } = require('../index');
+      const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-compile-'));
+      const skillsSrc = path.resolve('.claude/skills');
+      const skillsDest = path.join(tmpDir, '.claude', 'skills');
+      const legacyManagedSkill = path.join(tmpDir, '.codex', 'skills', 'cc-devflow', 'SKILL.md');
+      const customSkill = path.join(tmpDir, '.codex', 'skills', 'custom-skill', 'SKILL.md');
+
+      fs.mkdirSync(path.dirname(skillsDest), { recursive: true });
+      fs.cpSync(skillsSrc, skillsDest, { recursive: true });
+      fs.mkdirSync(path.dirname(legacyManagedSkill), { recursive: true });
+      fs.mkdirSync(path.dirname(customSkill), { recursive: true });
+      fs.writeFileSync(legacyManagedSkill, 'legacy aggregate skill\n');
+      fs.writeFileSync(customSkill, 'custom codex skill\n');
+
+      const previousCwd = process.cwd();
+      process.chdir(tmpDir);
+
+      try {
+        const result = await compile({
+          outputBaseDir: '.',
+          platforms: ['codex'],
+          verbose: false,
+          rules: true,
+          skills: true
+        });
+
+        expect(result.success).toBe(true);
+        expect(result.skillsRegistered).toBeGreaterThan(0);
+        expect(result.rulesGenerated).toBe(0);
+        expect(fs.readFileSync(legacyManagedSkill, 'utf8')).toBe('legacy aggregate skill\n');
+        expect(fs.readFileSync(customSkill, 'utf8')).toBe('custom codex skill\n');
+        expect(fs.existsSync(path.join(tmpDir, '.codex', 'skills', 'cc-roadmap', 'SKILL.md'))).toBe(true);
+        expect(fs.existsSync(path.join(tmpDir, '.codex', 'skills', 'cc-plan', 'SKILL.md'))).toBe(true);
+        expect(fs.existsSync(path.join(tmpDir, '.codex', 'skills', 'cc-investigate', 'SKILL.md'))).toBe(true);
+        expect(fs.existsSync(path.join(tmpDir, '.codex', 'skills', 'cc-do', 'SKILL.md'))).toBe(true);
+        expect(fs.existsSync(path.join(tmpDir, '.codex', 'skills', 'cc-check', 'SKILL.md'))).toBe(true);
+        expect(fs.existsSync(path.join(tmpDir, '.codex', 'skills', 'cc-act', 'SKILL.md'))).toBe(true);
+        expect(fs.existsSync(path.join(tmpDir, '.codex', 'skills', 'cc-spec-init', 'SKILL.md'))).toBe(true);
+        expect(fs.existsSync(path.join(tmpDir, '.codex', 'skills', 'cc-simplify', 'SKILL.md'))).toBe(true);
+      } finally {
+        process.chdir(previousCwd);
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+      }
+    });
+
     test('should generate 4 platform rule entry files', async () => {
       const { PLATFORMS, getRulesEntryPath } = require('../platforms');
 
@@ -52,7 +98,7 @@ describe('Full Compilation Integration', () => {
 
       // 验证规则入口路径
       expect(getRulesEntryPath('cursor')).toBe('.cursor/rules/devflow.mdc');
-      expect(getRulesEntryPath('codex')).toBe('.codex/skills/cc-devflow/SKILL.md');
+      expect(getRulesEntryPath('codex')).toBe(null);
       expect(getRulesEntryPath('qwen')).toBe('.qwen/commands/devflow.toml');
       expect(getRulesEntryPath('antigravity')).toBe('.agent/rules/rules.md');
     });
@@ -135,14 +181,14 @@ name = "cc-devflow"
 description = "CC-DevFlow development workflow system"
 
 [commands]
-flow-init = { description = "Initialize requirement" }
+cc-plan = { description = "Plan one requirement" }
 `;
 
       expect(() => TOML.parse(expectedTOML)).not.toThrow();
 
       const parsed = TOML.parse(expectedTOML);
       expect(parsed.skill.name).toBe('cc-devflow');
-      expect(parsed.commands['flow-init']).toBeDefined();
+      expect(parsed.commands['cc-plan']).toBeDefined();
     });
 
     test('should verify Antigravity size limit', async () => {