feat: sync all CEP skills from upstream e8f3bbc (#63)

* feat: sync all CEP skills from upstream e8f3bbc

Re-sync 7 existing skills and import 3 new skills from
EveryInc/compound-engineering-plugin@e8f3bbcb35 with full folder
contents (references, assets, scripts, workflows, templates).

Existing skills re-synced (28 files):
- agent-browser, agent-native-architecture, brainstorming,
  compound-docs, create-agent-skills, file-todos, git-worktree

New skills imported (3 files):
- document-review (referenced by brainstorm/plan commands)
- frontend-design (referenced by design agents)
- orchestrating-swarms (referenced by work command)

Conversion applied across all files:
- CC→OC branding in prose (Claude Code → OpenCode)
- CLAUDE.md → AGENTS.md, .claude/ → .opencode/
- Tool name mappings (Read/Write/Edit/Bash/etc.)
- CLAUDE_PLUGIN_ROOT paths simplified to relative paths
- CC frontmatter fields preserved (document upstream intent)
- Version attribution footers removed (nonsensical after rewrite)

Also updates convert-cc-defs skill with 5 learnings from this batch
and updates sync-manifest.json with provenance for all 10 skills.

* fix: correct tool name capitalization in orchestrating-swarms code examples

Fix 47 instances of Task({ → task({ in code block examples that were
missed during the initial code block audit (converter skips fenced
blocks by design).

Also adds a high-risk pattern note to the convert-cc-defs skill
reinforcing that long files with many code examples need targeted
post-conversion search for capitalized tool names.

* docs: document converter code-block tool name capitalization issue

Compound documentation for the orchestrating-swarms fix: converter
intentionally skips code blocks, creating a manual audit gap that
missed 47 Task({ → task({ conversions. Includes root cause analysis,
prevention strategies, and a post-conversion validation script.

Author: marcusrbrown

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

@@ -96,6 +96,21 @@ for agent_path in "${AGENTS[@]}"; do
 done
 ```
 
+**Recursive file listing** — the contents API fails on subdirectories. Use the git tree API for a complete one-shot listing:
+
+```bash
+# List ALL files under skills/ recursively (one API call)
+gh api "repos/EveryInc/compound-engineering-plugin/git/trees/<COMMIT_SHA>?recursive=1" \
+  --jq '.tree[] | select(.path | startswith("plugins/compound-engineering/skills/")) | select(.type == "blob") | .path' \
+  | sed 's|plugins/compound-engineering/skills/||'
+```
+
+**Skill folders** — Skills are directories, not just SKILL.md files. A skill folder may contain references/, templates/, workflows/, scripts/, assets/, and schema files. The CLI converter (`bun src/cli.ts convert skill`) ONLY processes SKILL.md files. All other files in the skill folder must be:
+1. Fetched from upstream individually via the contents API
+2. Copied to the local skill directory, preserving the folder structure
+3. Manually rewritten with CC→OC text replacements (`.claude/` → `.opencode/`, `CLAUDE.md` → `AGENTS.md`, `Claude Code` → `OpenCode`, `compound-engineering:` → `systematic:`, etc.)
+4. `${CLAUDE_PLUGIN_ROOT}/skills/<name>/...` paths simplified to relative paths (skills are bundled in the plugin — no env var prefix needed)
+
 ### 1b. Check Existing Manifest
 
 Read `sync-manifest.json` to determine if this is a new import or an update:
@@ -120,10 +135,15 @@ If updating an existing definition:
 2. **Philosophy fit:** Is it consistent with Systematic's opinionated workflow approach? (Structured phases, explicit deliverables, skill-driven discipline)
 3. **Overlap check:** Does it duplicate an existing bundled definition? If partial overlap, propose enhancing the existing definition instead.
 4. **Dependency check:** Does the definition reference agents, skills, or commands that don't exist in Systematic? List any missing dependencies — note as WARN (they can be imported later using this skill, and references should be kept).
-5. **Phantom check:** If importing agents referenced by commands, verify the agents actually exist upstream. Commands may reference agents that were never created upstream ("phantom agents"). Fetch the upstream directory listing to confirm:
+5. **Phantom check:** If importing agents or skills referenced by commands, verify they actually exist upstream. Commands may reference definitions that were never created upstream ("phantoms"). Fetch the upstream directory listing to confirm:
    ```bash
+   # Check agents
    gh api repos/EveryInc/compound-engineering-plugin/contents/plugins/compound-engineering/agents/review \
      --jq '.[].name'
+   # Check skills
+   gh api "repos/EveryInc/compound-engineering-plugin/git/trees/<COMMIT_SHA>?recursive=1" \
+     --jq '.tree[] | select(.path | startswith("plugins/compound-engineering/skills/")) | select(.type == "tree") | .path' \
+     | sed 's|plugins/compound-engineering/skills/||' | grep -v '/'
    ```
 6. **User value:** Would a Systematic plugin user actually invoke this? Niche CC-specific tools (e.g., `feature-video`, `test-browser`) may not translate.
 
@@ -222,6 +242,8 @@ The mechanical converter catches regex-matchable patterns. You must catch contex
 | `TodoWrite` in prose (not just tool calls) | `todowrite` or "update your task list" |
 | "the built-in grep tool" (lowercase tool name) | "the built-in Grep tool" (OC capitalizes tool names) |
 | `compound-engineering pipeline artifacts` | Remove or replace with "systematic pipeline artifacts" |
+| Version attribution footers (e.g., `*Based on Claude Code v2.1.19*`) | **Remove entirely** — CC version numbers are not applicable to Systematic. Blind `Claude Code` → `OpenCode` rewrite turns these into nonsensical `Based on OpenCode v2.1.19`. |
+| Source attribution URLs (e.g., `claude.com`, `docs.anthropic.com`) | **Keep as-is** — these are upstream source references, not branding |
 
 ### 3c. Content Adaptation
 
@@ -259,6 +281,8 @@ The mechanical converter intentionally skips content inside fenced code blocks t
 | Attribution badges/footers (`Compound Engineered`, `Claude Code` links) | → Systematic branding |
 | `AskUserQuestion` | → `question tool` |
 
+> **High-risk pattern:** Long skills with many code examples (e.g., orchestrating-swarms has 47 `Task({` calls across 1700+ lines). After mechanical conversion, run a targeted search for capitalized tool names inside code blocks: `grep -n "Task(\|TodoWrite\|AskUserQuestion" <file>`. Fix all occurrences — users copying broken examples will get runtime errors.
+
 ### 3e. CC-Specific Features
 
 Some CC features have no direct OC equivalent. For each, make a case-by-case decision:
@@ -267,7 +291,8 @@ Some CC features have no direct OC equivalent. For each, make a case-by-case dec
 |------------|---------------|----------------|
 | `Teammate` API (spawnTeam, requestShutdown, cleanup) | None — `task` with `run_in_background` is partial | Keep as aspirational reference with explanatory note |
 | "Remote" execution (Claude Code web background) | None | Remove — no OC equivalent exists |
-| `${CLAUDE_SESSION_ID}` | None | Remove |
+| `${CLAUDE_SESSION_ID}` | None | Remove (keep in upstream API spec docs as-is) |
+| `${CLAUDE_PLUGIN_ROOT}` | None — bundled skills use relative paths | Simplify to relative paths (e.g., `scripts/worktree-manager.sh` not `${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh`) |
 | `AskUserQuestion` with complex schemas | `question` tool (simpler) | Adapt to OC's question tool format |
 
 Present CC-specific feature decisions to the user before proceeding.

docs/solutions/integration-issues/converter-code-block-tool-name-capitalization-20260210.md

@@ -0,0 +1,183 @@
+---
+title: "Converter Skips Code Blocks: 47 Broken Tool Name Examples in orchestrating-swarms"
+date: 2026-02-10
+severity: high
+category: integration-issues
+component: converter
+tags:
+  - converter
+  - code-blocks
+  - tool-names
+  - cep-migration
+  - orchestrating-swarms
+  - convert-cc-defs
+environment: "Bun 1.x / TypeScript 5.7+ / OpenCode"
+symptoms:
+  - "Code examples show Task({ instead of task({ after CC→OC conversion"
+  - "Users copying code examples from skill documentation get runtime errors"
+  - "47 instances of capitalized Task({ in orchestrating-swarms SKILL.md"
+root_cause: "Converter intentionally skips fenced code blocks to avoid false positives (e.g., 'Task' as a noun). Manual code block audit step in convert-cc-defs skill was missed during batch import of a 1718-line file."
+resolution_type: process
+confidence: verified
+related:
+  - docs/solutions/integration-issues/batch-import-cep-agents-to-systematic-20260210.md
+  - docs/CONVERSION-GUIDE.md
+  - .opencode/skills/convert-cc-defs/SKILL.md
+---
+
+# Converter Skips Code Blocks: 47 Broken Tool Name Examples in orchestrating-swarms
+
+## Problem
+
+After batch-importing 10 CEP skills from upstream (`EveryInc/compound-engineering-plugin@e8f3bbcb35`), the `orchestrating-swarms` skill contained 47 instances of `Task({` (Claude Code capitalization) in its code examples instead of `task({` (OpenCode lowercase). Every code example in this 1718-line file was broken — users copying examples would get runtime errors.
+
+### Symptoms
+
+- All code examples in `skills/orchestrating-swarms/SKILL.md` used `Task({...})` instead of `task({...})`
+- `const research = await Task({...})` instead of `const research = await task({...})`
+- One-liner spawns like `Task({ team_name: "codebase-review", ... })` also affected
+- 47 total occurrences, all inside fenced JavaScript code blocks
+
+## Investigation
+
+### Step 1: Understand the converter's design
+
+The converter (`src/lib/converter.ts`) uses `CODE_BLOCK_PATTERN` to identify fenced code blocks (` ```...``` `) and inline code (`` `...` ``). In `transformBody()`, these regions are replaced with placeholders before applying tool name mappings, then restored after. This is **intentional** — it prevents false positives like:
+
+- "Complete the Task today" → would incorrectly become "Complete the task today"
+- "Task list management" → would incorrectly become "task list management"
+- CSS class names, variable names in non-JS contexts
+
+The converter's behavior is tested and correct. The problem is downstream.
+
+### Step 2: Check the convert-cc-defs workflow
+
+The `convert-cc-defs` skill (`.opencode/skills/convert-cc-defs/SKILL.md`) documents a "Phase 3d: Code Block Audit" step with a table of patterns to manually fix after mechanical conversion:
+
+| Pattern in code blocks | Action |
+|------------------------|--------|
+| `Task(agent-name)` or `Task({ ... })` | → `task(agent-name)` / `task({ ... })` |
+| `TodoWrite` | → `todowrite` |
+| `CLAUDE.md` | → `AGENTS.md` |
+| `.claude/skills/` paths | → `.opencode/skills/` |
+| `Teammate({ operation: ... })` | Aspirational note or adapt to `task` |
+| `AskUserQuestion` | → `question tool` |
+
+The documentation was correct. The audit step was simply skipped during execution — easy to miss in a batch import of 10 skills, especially when the problematic file is 1718 lines with 47 occurrences spread across dozens of code blocks.
+
+### Step 3: Verify scope
+
+Searched all skills for capitalized tool names in code blocks:
+
+```bash
+grep -rn "Task(" skills/ --include="*.md" | grep -v "Task Analysis\|Task List\|task("
+```
+
+Only `orchestrating-swarms` was affected. Other skills either had no code examples or had already been correctly audited. The `agent-native-architecture` references contained Swift iOS API calls (`endBackgroundTask`) — correct and unrelated.
+
+## Root Cause
+
+**Two-factor failure:**
+
+1. **Converter design (correct):** Skips code blocks to avoid false positives in prose text. This is the right tradeoff — false positives in prose are worse than requiring manual code block review.
+
+2. **Process gap (the bug):** The manual "Code Block Audit" step (Phase 3d) in the convert-cc-defs workflow was missed during batch execution. The orchestrating-swarms file is unusually large (1718 lines, 47 tool calls in code blocks) making the omission high-impact.
+
+The convert-cc-defs skill documented the audit requirement, but under batch pressure (10 skills, 52 files), the step was skipped for this file. The workflow lacked enforcement — it was advisory, not gated.
+
+## Solution
+
+### Immediate fix (applied)
+
+```bash
+sed -i '' 's/Task({/task({/g' skills/orchestrating-swarms/SKILL.md
+sed -i '' 's/await Task(/await task(/g' skills/orchestrating-swarms/SKILL.md
+```
+
+Verified: 0 `Task({` remaining, 47 `task({` present.
+
+### Manifest tracking (applied)
+
+Added rewrite entry to `sync-manifest.json`:
+
+```json
+{
+  "field": "body:code-block-tool-names",
+  "reason": "Fixed 47 instances of Task({ → task({ in code examples. Converter skips code blocks by design; these were missed during initial manual code block audit."
+}
+```
+
+### Skill improvement (applied)
+
+Added a high-risk pattern note to the convert-cc-defs skill's Code Block Audit section:
+
+> **High-risk pattern:** Long skills with many code examples (e.g., orchestrating-swarms has 47 `Task({` calls across 1700+ lines). After mechanical conversion, run a targeted search for capitalized tool names inside code blocks: `grep -n "Task(\|TodoWrite\|AskUserQuestion" <file>`. Fix all occurrences — users copying broken examples will get runtime errors.
+
+## Prevention
+
+### 1. Post-conversion validation command
+
+Run after any conversion to detect CC tool markers inside code blocks:
+
+```bash
+python3 -c "
+import re, sys, pathlib
+CODE_BLOCKS = re.compile(r'\x60\x60\x60[\s\S]*?\x60\x60\x60|\x60[^\x60\n]+\x60')
+FORBIDDEN = [
+  (re.compile(r'\bTask\s*\('), 'Task('),
+  (re.compile(r'\b(TodoWrite|AskUserQuestion|WebSearch|WebFetch)\b'), 'CC tool'),
+  (re.compile(r'CLAUDE\.md'), 'CLAUDE.md'),
+  (re.compile(r'\.claude/'), '.claude/ path'),
+]
+total = 0
+for f in pathlib.Path(sys.argv[1] if len(sys.argv) > 1 else 'skills').rglob('*.md'):
+  text = f.read_text()
+  for m in CODE_BLOCKS.finditer(text):
+    block = m.group(0)
+    for rx, label in FORBIDDEN:
+      for mm in rx.finditer(block):
+        line = text.count('\n', 0, m.start()) + 1
+        print(f'  {f}:{line}: {label}: {mm.group(0)}')
+        total += 1
+print(f'\n{\"FAIL: \" + str(total) + \" issues\" if total else \"OK: no CC markers in code blocks\"}')
+sys.exit(1 if total else 0)
+"
+```
+
+### 2. Workflow guardrails
+
+Make Phase 3d a hard gate in `convert-cc-defs`:
+- Run the validation command; if exit code != 0, do not proceed to Phase 4
+- Record audit counts in manifest notes: `CODE_BLOCK_AUDIT: PASS (Task(:0, TodoWrite:0)`
+
+### 3. Bundled-assets integration test
+
+Add a test in `tests/integration/` that scans all shipped `skills/`, `agents/`, `commands/` for CC markers inside code blocks. This catches misses at CI time, not review time.
+
+### 4. Batch import backstop
+
+For multi-file imports, run the validator on `git diff --name-only --diff-filter=AM` after the batch completes.
+
+## Verification
+
+```bash
+# Confirm fix
+grep -c "Task({" skills/orchestrating-swarms/SKILL.md  # 0
+grep -c "task({" skills/orchestrating-swarms/SKILL.md  # 47
+
+# Full build
+bun run build && bun run typecheck && bun run lint && bun test
+# 328/328 tests pass, 617 expect() calls
+```
+
+## Cross-References
+
+- **Related solution:** [Batch Importing CEP Agents](./batch-import-cep-agents-to-systematic-20260210.md) — same batch import session, different issue (phantom agents)
+- **Conversion guide:** [docs/CONVERSION-GUIDE.md](../../CONVERSION-GUIDE.md) — tool name mappings reference
+- **Workflow skill:** [convert-cc-defs](../../../.opencode/skills/convert-cc-defs/SKILL.md) — Phase 3d Code Block Audit
+- **PR:** [#63](https://github.com/marcusrbrown/systematic/pull/63) — feat: sync all CEP skills from upstream
+- **Converter source:** `src/lib/converter.ts` — `CODE_BLOCK_PATTERN` and `transformBody()`
+
+## Key Takeaway
+
+The converter's code-block-skipping is a correct safety measure. The failure was a process gap: a manual audit step documented in the workflow but not enforced. The fix is twofold: (1) targeted grep after every conversion, and (2) automated validation that fails CI if CC markers remain in code blocks. **Don't trust humans to manually audit 1700-line files under batch pressure — automate the check.**

skills/agent-browser/SKILL.md

@@ -221,3 +221,4 @@ Use Playwright MCP when:
 - You need deep MCP tool integration
 - You want tool-based responses
 - You're building complex automation
+

skills/agent-native-architecture/SKILL.md

@@ -6,13 +6,13 @@ description: Build applications where agents are first-class citizens. Use this
 <why_now>
 ## Why Now
 
-Software agents work reliably now. Claude Code demonstrated that an LLM with access to bash and file tools, operating in a loop until an objective is achieved, can accomplish complex multi-step tasks autonomously.
+Software agents work reliably now. Modern coding agents like OpenCode have demonstrated that an LLM with access to bash and file tools, operating in a loop until an objective is achieved, can accomplish complex multi-step tasks autonomously.
 
-The surprising discovery: **a really good coding agent is actually a really good general-purpose agent.** The same architecture that lets Claude Code refactor a codebase can let an agent organize your files, manage your reading list, or automate your workflows.
+The surprising discovery: **a really good coding agent is actually a really good general-purpose agent.** The same architecture that lets an agent refactor a codebase can let it organize your files, manage your reading list, or automate your workflows.
 
-The Claude Code SDK makes this accessible. You can build applications where features aren't code you write—they're outcomes you describe, achieved by an agent with tools, operating in a loop until the outcome is reached.
+Agent SDKs make this accessible. You can build applications where features aren't code you write—they're outcomes you describe, achieved by an agent with tools, operating in a loop until the outcome is reached.
 
-This opens up a new field: software that works the way Claude Code works, applied to categories far beyond coding.
+This opens up a new field: software that works the way modern coding agents work, applied to categories far beyond coding.
 </why_now>
 
 <core_principles>

skills/agent-native-architecture/references/files-universal-interface.md

@@ -5,7 +5,7 @@ Files are the universal interface for agent-native applications. Agents are natu
 <why_files>
 ## Why Files
 
-Agents are naturally good at files. Claude Code works because bash + filesystem is the most battle-tested agent interface. When building agent-native apps, lean into this.
+Agents are naturally good at files. OpenCode works because bash + filesystem is the most battle-tested agent interface. When building agent-native apps, lean into this.
 
 ### Agents Already Know How
 

skills/agent-native-architecture/references/product-implications.md

@@ -11,7 +11,7 @@ The best agent-native applications are simple to start but endlessly powerful.
 
 Excel is the canonical example: you can use it for a grocery list, or you can build complex financial models. The same tool, radically different depths of use.
 
-Claude Code has this quality: fix a typo, or refactor an entire codebase. The interface is the same—natural language—but the capability scales with the ask.
+OpenCode has this quality: fix a typo, or refactor an entire codebase. The interface is the same—natural language—but the capability scales with the ask.
 
 ### The Pattern
 

skills/brainstorming/SKILL.md

@@ -188,3 +188,4 @@ Planning answers **HOW** to build it:
 - Testing strategy and verification
 
 When brainstorm output exists, `/workflows:plan` should detect it and use it as input, skipping its own idea refinement phase.
+