feat: import 5 CEP workflow commands and add convert-cc-defs skill (#61)

* feat: import 5 CEP workflow commands and add convert-cc-defs skill

Import brainstorm, compound, plan, review, and work workflow commands
from CEP upstream (04ee7e4). Each command went through mechanical
conversion via the converter pipeline followed by intelligent rewrites:
code block audits, branding fixes, CC-specific feature handling.

Add convert-cc-defs project skill (.opencode/skills/) for importing and
syncing definitions from CEP/Superpowers into Systematic. Includes
5-phase workflow, manifest tracking, manual override preservation, and
re-sync support.

Other changes:
- Extend sync-manifest schema with upstream_content_hash, rewrites,
  manual_overrides fields
- Populate sync-manifest.json with all 5 command entries
- Fix CEP/CC disambiguation in docs (CEP is a plugin FOR Claude Code)
- Add converter tests for new tool mappings and edge cases

* feat: structured manual override tracking with agent workflow

Upgrade manual_overrides from string[] to structured ManualOverride[]
objects with field, reason, original, and overridden_at. This enables
agents to track post-import customizations with provenance, and the
re-sync workflow to detect conflicts between upstream changes and local
overrides.

Changes:
- Add ManualOverride interface and isManualOverride type guard
- Update JSON Schema with structured override object definition
- Add Phase 4e 'Record Manual Edit' sub-workflow to convert-cc-defs skill
- Add override merge matrix and conflict presentation to Re-Sync Workflow
- Add 5 new tests for override validation (structured, empty, string
  rejection, missing fields, optional original)

* docs(solutions): document structured manual override tracking pattern

Add best practice doc for structured ManualOverride[] tracking in sync
manifest. Includes agent workflow for recording post-import edits and
re-sync conflict resolution matrix. Cross-linked with converter doc.

* docs: update AGENTS.md with module and test file counts

- Update module count from 12 to 13 in core implementation section.
- Add details about upstream provenance tracking in data flow.
- Correct test file counts in commands and tests sections.
- Enhance manifest tracking information in key types and modules.

Author: marcusrbrown

.opencode/skills/convert-cc-defs/SKILL.md

@@ -1,10 +1,10 @@
 # AGENTS.md - Coding Agent Guidelines for Systematic
 
-**Generated:** 2026-02-09 | **Commit:** b00201d | **Branch:** main
+**Generated:** 2026-02-10 | **Commit:** b58d17c | **Branch:** feat/import-cep-workflow-commands
 
 ## Overview
 
-OpenCode plugin providing structured engineering workflows. Converts Claude Code (CEP) agents, skills, and commands to OpenCode format.
+OpenCode plugin providing structured engineering workflows. Ported from the [Compound Engineering Plugin (CEP)](https://github.com/EveryInc/compound-engineering-plugin) for Claude Code, with improvements and OpenCode SDK integration. Converts CC-format agents, skills, and commands to OpenCode format. Tracks upstream provenance via `sync-manifest.json`.
 
 **Two distinct parts:**
 1. **TypeScript source** (`src/`) — Plugin logic, tools, config handling
@@ -17,7 +17,7 @@ bun install              # Install deps
 bun run build            # Build to dist/
 bun run typecheck        # Type check (strict)
 bun run lint             # Biome linter
-bun test tests/unit      # Unit tests (10 files)
+bun test tests/unit      # Unit tests (11 files)
 bun test tests/integration  # Integration tests (2 files)
 bun test                 # All tests
 bun test --filter "pattern"  # Filter tests
@@ -42,16 +42,20 @@ systematic/
 ├── src/
 │   ├── index.ts          # Plugin entry (SystematicPlugin)
 │   ├── cli.ts            # CLI entry (list/convert/config commands)
-│   └── lib/              # 12 core modules (see src/lib/AGENTS.md)
+│   └── lib/              # 13 core modules (see src/lib/AGENTS.md)
 ├── skills/               # 8 bundled skills (SKILL.md format)
 ├── agents/               # 11 bundled agents (4 categories: design/research/review/workflow)
-├── commands/             # 9 bundled commands (with workflows/ subdir)
+├── commands/             # 9 bundled commands (5 workflow + 4 utility)
+│   └── workflows/        # brainstorm, compound, plan, review, work
 ├── docs/                 # Starlight docs workspace (see docs/AGENTS.md)
 │   ├── scripts/          # Content generation from bundled assets
 │   └── src/content/      # Manual guides + generated reference
 ├── tests/
-│   ├── unit/             # 10 test files
+│   ├── unit/             # 11 test files
 │   └── integration/      # 2 test files
+├── .opencode/            # Project-specific OC config + skills
+│   └── skills/           # Project-only skills (convert-cc-defs)
+├── sync-manifest.json    # Upstream provenance tracking
 └── dist/                 # Build output
 ```
 
@@ -70,10 +74,12 @@ systematic/
 | Asset discovery | `src/lib/skills.ts`, `agents.ts`, `commands.ts` |
 | Directory walking | `src/lib/walk-dir.ts` |
 | Config loading (JSONC) | `src/lib/config.ts` |
+| Upstream sync manifest | `src/lib/manifest.ts`, `sync-manifest.json` |
 | CLI commands | `src/cli.ts` |
 | Add new skill | `skills/<name>/SKILL.md` |
 | Add new agent | `agents/<category>/<name>.md` |
 | Add new command | `commands/<name>.md` |
+| Import from CEP upstream | `.opencode/skills/convert-cc-defs/SKILL.md` |
 | Docs content generation | `docs/scripts/transform-content.ts` |
 | Docs site config | `docs/astro.config.mjs` |
 
@@ -82,18 +88,22 @@ systematic/
 | Symbol | Type | Location | Refs | Role |
 |--------|------|----------|------|------|
 | `SystematicPlugin` | export | src/index.ts:30 | 2 | Main plugin factory |
-| `createConfigHandler` | fn | src/lib/config-handler.ts:205 | 3 | Config hook — merges bundled assets |
+| `createConfigHandler` | fn | src/lib/config-handler.ts:207 | 3 | Config hook — merges bundled assets |
 | `createSkillTool` | fn | src/lib/skill-tool.ts:87 | 3 | systematic_skill tool factory |
 | `getBootstrapContent` | fn | src/lib/bootstrap.ts:32 | 3 | System prompt injection |
-| `convertContent` | fn | src/lib/converter.ts:234 | 4 | CEP→OpenCode body conversion |
-| `convertFileWithCache` | fn | src/lib/converter.ts:274 | 6 | Cached file conversion (mtime invalidation) |
+| `convertContent` | fn | src/lib/converter.ts:371 | 4 | CEP→OpenCode body conversion |
+| `convertFileWithCache` | fn | src/lib/converter.ts:411 | 6 | Cached file conversion (mtime invalidation) |
 | `findSkillsInDir` | fn | src/lib/skills.ts:90 | 6 | Skill discovery (highest centrality) |
 | `findAgentsInDir` | fn | src/lib/agents.ts:47 | 4 | Agent discovery (category from subdir) |
 | `findCommandsInDir` | fn | src/lib/commands.ts:27 | 4 | Command discovery |
 | `loadConfig` | fn | src/lib/config.ts:47 | 5 | JSONC config loading + 3-source merge |
 | `parseFrontmatter` | fn | src/lib/frontmatter.ts:19 | 7 | YAML frontmatter extraction (regex-based) |
 | `walkDir` | fn | src/lib/walk-dir.ts:17 | 3 | Recursive dir walker (foundation layer) |
 | `loadSkill` | fn | src/lib/skill-loader.ts:31 | 2 | Skill content loading + XML wrapping |
+| `readManifest` | fn | src/lib/manifest.ts:116 | 1 | Read + validate sync-manifest.json |
+| `validateManifest` | fn | src/lib/manifest.ts:100 | 2 | Schema validation for manifest data |
+| `writeManifest` | fn | src/lib/manifest.ts:140 | 1 | Write manifest with sorted keys |
+| `findStaleEntries` | fn | src/lib/manifest.ts:145 | 1 | Detect definitions missing from filesystem |
 
 ## Conventions
 
@@ -134,10 +144,15 @@ Skills registered as commands with `systematic:` prefix (auto-prepended if no co
 
 All disabled lists merge (union), bootstrap config shallow-merges.
 
+## Upstream Sync
+
+CEP definitions are imported via the `convert-cc-defs` skill (`.opencode/skills/`). `sync-manifest.json` tracks provenance: upstream commit, content hash, rewrites applied, and manual overrides. Re-sync compares hashes for idempotency.
+
 ## Notes
 
 - Bootstrap injection is opt-out via `bootstrap.enabled: false`
 - Converter caches results using file mtime
 - CLI commands: `list` (skills/agents/commands), `convert` (file conversion), `config show/path`
 - Experimental hook: `experimental.chat.system.transform`
 - `docs/` is a separate workspace — run `bun run docs:generate` to sync reference content from bundled assets
+- Use `bun src/cli.ts` for local dev instead of `bunx systematic` to avoid slow resolution

AGENTS.md

@@ -146,7 +146,7 @@ Agents are specialized subagents with pre-configured prompts and expertise. They
 
 ### Using Agents
 
-Agents are invoked via OpenCode's `@mention` syntax or `delegate_task`:
+Agents are invoked via OpenCode's `@mention` syntax or `task`:
 
 ```
 @architecture-strategist Review the authentication refactoring in this PR
@@ -155,7 +155,7 @@ Agents are invoked via OpenCode's `@mention` syntax or `delegate_task`:
 Or programmatically in skills/commands:
 
 ```
-delegate_task(subagent_type="architecture-strategist", prompt="Review...")
+task(subagent_type="architecture-strategist", prompt="Review...")
 ```
 
 ## Commands
@@ -387,7 +387,7 @@ See [`AGENTS.md`](./AGENTS.md) for detailed development guidelines, code style c
 
 ## Converting from Claude Code
 
-Migrating skills, agents, or commands from Claude Code (CEP) to Systematic? See the [Conversion Guide](https://fro.bot/systematic/guides/conversion-guide/) for field mappings and examples. Also available as [local Markdown](./docs/CONVERSION-GUIDE.md).
+Migrating skills, agents, or commands from CEP or other Claude Code-format sources to Systematic? See the [Conversion Guide](https://fro.bot/systematic/guides/conversion-guide/) for field mappings and examples. Also available as [local Markdown](./docs/CONVERSION-GUIDE.md).
 
 ## References
 

README.md

@@ -33,21 +33,21 @@ Evaluate whether brainstorming is needed based on the feature description.
 - Constrained, well-defined scope
 
 **If requirements are already clear:**
-Use **AskUserQuestion tool** to suggest: "Your requirements seem detailed enough to proceed directly to planning. Should I run `/workflows:plan` instead, or would you like to explore the idea further?"
+Use the **question tool** to suggest: "Your requirements seem detailed enough to proceed directly to planning. Should I run `/workflows:plan` instead, or would you like to explore the idea further?"
 
 ### Phase 1: Understand the Idea
 
 #### 1.1 Repository Research (Lightweight)
 
 Run a quick repo scan to understand existing patterns:
 
-- Task repo-research-analyst("Understand existing patterns related to: <feature_description>")
+- task repo-research-analyst("Understand existing patterns related to: <feature_description>")
 
-Focus on: similar features, established patterns, CLAUDE.md guidance.
+Focus on: similar features, established patterns, AGENTS.md guidance.
 
 #### 1.2 Collaborative Dialogue
 
-Use the **AskUserQuestion tool** to ask questions **one at a time**.
+Use the **question tool** to ask questions **one at a time**.
 
 **Guidelines (see `brainstorming` skill for detailed techniques):**
 - Prefer multiple choice when natural options exist
@@ -68,7 +68,7 @@ For each approach, provide:
 
 Lead with your recommendation and explain why. Apply YAGNI—prefer simpler solutions.
 
-Use **AskUserQuestion tool** to ask which approach the user prefers.
+Use the **question tool** to ask which approach the user prefers.
 
 ### Phase 3: Capture the Design
 
@@ -80,15 +80,24 @@ Ensure `docs/brainstorms/` directory exists before writing.
 
 ### Phase 4: Handoff
 
-Use **AskUserQuestion tool** to present next steps:
+Use the **question tool** to present next steps:
 
 **Question:** "Brainstorm captured. What would you like to do next?"
 
 **Options:**
-1. **Proceed to planning** - Run `/workflows:plan` (will auto-detect this brainstorm)
-2. **Refine design further** - Continue exploring
+1. **Review and refine** - Improve the document through structured self-review
+2. **Proceed to planning** - Run `/workflows:plan` (will auto-detect this brainstorm)
 3. **Done for now** - Return later
 
+**If user selects "Review and refine":**
+
+Load the `document-review` skill and apply it to the brainstorm document.
+
+When document-review returns "Review complete", present next steps:
+
+1. **Move to planning** - Continue to `/workflows:plan` with this document
+2. **Done for now** - Brainstorming complete. To start planning later: `/workflows:plan [document-path]`
+
 ## Output Summary
 
 When complete, display:

commands/workflows/brainstorm.md

@@ -21,53 +21,83 @@ Captures problem solutions while context is fresh, creating structured documenta
 /workflows:compound [brief context]    # Provide additional context hint
 ```
 
-## Execution Strategy: Parallel Subagents
-
-This command launches multiple specialized subagents IN PARALLEL to maximize efficiency:
-
-### 1. **Context Analyzer** (Parallel)
-   - Extracts conversation history
-   - Identifies problem type, component, symptoms
-   - Validates against CORA schema
-   - Returns: YAML frontmatter skeleton
-
-### 2. **Solution Extractor** (Parallel)
-   - Analyzes all investigation steps
-   - Identifies root cause
-   - Extracts working solution with code examples
-   - Returns: Solution content block
-
-### 3. **Related Docs Finder** (Parallel)
-   - Searches `docs/solutions/` for related documentation
-   - Identifies cross-references and links
-   - Finds related GitHub issues
-   - Returns: Links and relationships
-
-### 4. **Prevention Strategist** (Parallel)
-   - Develops prevention strategies
-   - Creates best practices guidance
-   - Generates test cases if applicable
-   - Returns: Prevention/testing content
-
-### 5. **Category Classifier** (Parallel)
-   - Determines optimal `docs/solutions/` category
-   - Validates category against schema
-   - Suggests filename based on slug
-   - Returns: Final path and filename
-
-### 6. **Documentation Writer** (Parallel)
-   - Assembles complete markdown file
-   - Validates YAML frontmatter
-   - Formats content for readability
-   - Creates the file in correct location
-
-### 7. **Optional: Specialized Agent Invocation** (Post-Documentation)
-   Based on problem type detected, automatically invoke applicable agents:
-   - **performance_issue** → `performance-oracle`
-   - **security_issue** → `security-sentinel`
-   - **database_issue** → `data-integrity-guardian`
-   - **test_failure** → `cora-test-reviewer`
-   - Any code-heavy issue → `kieran-rails-reviewer` + `code-simplicity-reviewer`
+## Execution Strategy: Two-Phase Orchestration
+
+<critical_requirement>
+**Only ONE file gets written - the final documentation.**
+
+Phase 1 subagents return TEXT DATA to the orchestrator. They must NOT use Write, Edit, or create any files. Only the orchestrator (Phase 2) writes the final documentation file.
+</critical_requirement>
+
+### Phase 1: Parallel Research
+
+<parallel_tasks>
+
+Launch these subagents IN PARALLEL. Each returns text data to the orchestrator.
+
+#### 1. **Context Analyzer**
+- Extracts conversation history
+- Identifies problem type, component, symptoms
+- Validates against schema
+- Returns: YAML frontmatter skeleton
+
+#### 2. **Solution Extractor**
+- Analyzes all investigation steps
+- Identifies root cause
+- Extracts working solution with code examples
+- Returns: Solution content block
+
+#### 3. **Related Docs Finder**
+- Searches `docs/solutions/` for related documentation
+- Identifies cross-references and links
+- Finds related GitHub issues
+- Returns: Links and relationships
+
+#### 4. **Prevention Strategist**
+- Develops prevention strategies
+- Creates best practices guidance
+- Generates test cases if applicable
+- Returns: Prevention/testing content
+
+#### 5. **Category Classifier**
+- Determines optimal `docs/solutions/` category
+- Validates category against schema
+- Suggests filename based on slug
+- Returns: Final path and filename
+
+</parallel_tasks>
+
+### Phase 2: Assembly & Write
+
+<sequential_tasks>
+
+**WAIT for all Phase 1 subagents to complete before proceeding.**
+
+The orchestrating agent (main conversation) performs these steps:
+
+1. Collect all text results from Phase 1 subagents
+2. Assemble complete markdown file from the collected pieces
+3. Validate YAML frontmatter against schema
+4. Create directory if needed: `mkdir -p docs/solutions/[category]/`
+5. Write the SINGLE final file: `docs/solutions/[category]/[filename].md`
+
+</sequential_tasks>
+
+### Phase 3: Optional Enhancement
+
+**WAIT for Phase 2 to complete before proceeding.**
+
+<parallel_tasks>
+
+Based on problem type, optionally invoke specialized agents to review the documentation:
+
+- **performance_issue** → `performance-oracle`
+- **security_issue** → `security-sentinel`
+- **database_issue** → `data-integrity-guardian`
+- **test_failure** → `cora-test-reviewer`
+- Any code-heavy issue → `kieran-rails-reviewer` + `code-simplicity-reviewer`
+
+</parallel_tasks>
 
 ## What It Captures
 
@@ -110,24 +140,29 @@ This command launches multiple specialized subagents IN PARALLEL to maximize eff
 - integration-issues/
 - logic-errors/
 
+## Common Mistakes to Avoid
+
+| Wrong | Correct |
+|----------|-----------:|
+| Subagents write files like `context-analysis.md`, `solution-draft.md` | Subagents return text data; orchestrator writes one final file |
+| Research and assembly run in parallel | Research completes, then assembly runs |
+| Multiple files created during workflow | Single file: `docs/solutions/[category]/[filename].md` |
+
 ## Success Output
 
 ```
-✓ Parallel documentation generation complete
-
-Primary Subagent Results:
-  ✓ Context Analyzer: Identified performance_issue in brief_system
-  ✓ Solution Extractor: Extracted 3 code fixes
-  ✓ Related Docs Finder: Found 2 related issues
-  ✓ Prevention Strategist: Generated test cases
-  ✓ Category Classifier: docs/solutions/performance-issues/
-  ✓ Documentation Writer: Created complete markdown
+Subagent Results:
+  Context Analyzer: Identified performance_issue in brief_system
+  Solution Extractor: 3 code fixes
+  Related Docs Finder: 2 related issues
+  Prevention Strategist: Prevention strategies, test suggestions
+  Category Classifier: `performance-issues`
 
 Specialized Agent Reviews (Auto-Triggered):
-  ✓ performance-oracle: Validated query optimization approach
-  ✓ kieran-rails-reviewer: Code examples meet Rails standards
-  ✓ code-simplicity-reviewer: Solution is appropriately minimal
-  ✓ every-style-editor: Documentation style verified
+  performance-oracle: Validated query optimization approach
+  kieran-rails-reviewer: Code examples meet Rails standards
+  code-simplicity-reviewer: Solution is appropriately minimal
+  every-style-editor: Documentation style verified
 
 File created:
 - docs/solutions/performance-issues/n-plus-one-brief-generation.md