@cleocode/skills 2026.9.20 → 2026.9.22

package/skills/{ct-docs-review/__tests__/skill-docs-review.test.ts → ct-documentor/__tests__/reviewing-reference.test.ts}

@@ -1,5 +1,5 @@
 /**
- * Regression test for ct-docs-review/SKILL.md (T9642 / Epic T9629 / Saga T9625).
+ * Regression test for the ct-docs-review content, now ct-documentor/references/reviewing.md (T9642 / Epic T9629 / Saga T9625).
  *
  * Pins the SDK-first review contract: reviewers MUST read docs through
  * `cleo docs fetch <slug>` rather than the working-tree file. Documents
@@ -19,10 +19,11 @@ import { describe, expect, it } from 'vitest';
 
 const thisFile = fileURLToPath(import.meta.url);
 const skillRoot = resolve(dirname(thisFile), '..');
-const skillPath = join(skillRoot, 'SKILL.md');
+// T12649: ct-docs-review merged into ct-documentor/references/reviewing.md (D11157).
+const skillPath = join(skillRoot, 'references', 'reviewing.md');
 const skillContent = readFileSync(skillPath, 'utf-8');
 
-describe('ct-docs-review SKILL.md — SDK-first contract (T9642)', () => {
+describe('ct-documentor references/reviewing.md (was ct-docs-review) — SDK-first contract (T9642)', () => {
   it('teaches `cleo docs fetch` as the canonical read path', () => {
     expect(skillContent).toContain('cleo docs fetch');
   });

package/skills/{ct-docs-write/__tests__/skill-docs-write.test.ts → ct-documentor/__tests__/writing-reference.test.ts}

@@ -1,5 +1,5 @@
 /**
- * Regression test for ct-docs-write/SKILL.md (T9641 / Epic T9629 / Saga T9625).
+ * Regression test for the ct-docs-write content, now ct-documentor/references/writing.md (T9641 / Epic T9629 / Saga T9625).
  *
  * Pins the SDK-first writing contract: every new doc MUST flow through
  * `cleo docs add --type X --slug Y` rather than direct filesystem writes.
@@ -18,10 +18,11 @@ import { describe, expect, it } from 'vitest';
 
 const thisFile = fileURLToPath(import.meta.url);
 const skillRoot = resolve(dirname(thisFile), '..');
-const skillPath = join(skillRoot, 'SKILL.md');
+// T12649: ct-docs-write merged into ct-documentor/references/writing.md (D11157).
+const skillPath = join(skillRoot, 'references', 'writing.md');
 const skillContent = readFileSync(skillPath, 'utf-8');
 
-describe('ct-docs-write SKILL.md — SDK-first contract (T9641)', () => {
+describe('ct-documentor references/writing.md (was ct-docs-write) — SDK-first contract (T9641)', () => {
   it('teaches `cleo docs add` as the canonical write path', () => {
     expect(skillContent).toContain('cleo docs add');
   });

package/skills/ct-documentor/references/anti-patterns.md

@@ -42,12 +42,12 @@ existing page; do not create a sibling.
 **Symptom.** A how-to or reference cites a library API that has been
 renamed, deprecated, or removed.
 
-**Detection cue.** `ct-docs-lookup` was NOT invoked for the topic.
+**Detection cue.** the Context7 MCP was NOT invoked for the topic.
 
 **Root cause.** Documentor coordinator skipped lookup because "I know
 the API" or assumed training data was current.
 
-**Fix.** Always invoke `ct-docs-lookup` when documenting external
+**Fix.** Always invoke the Context7 MCP when documenting external
 library behavior. Training data is stale by definition — Context7 is
 the current source.
 
@@ -118,7 +118,7 @@ was assembled from multiple sources without normalization.
 
 **Fix.** CLEO style is "you" (second person) for how-tos and tutorials;
 "CLEO" (third person) for explanations and references. Apply
-consistently. Pass the choice explicitly to ct-docs-write as input.
+consistently. Pass the choice explicitly to the writing guide (`ct-documentor/references/writing.md`) as input.
 
 ## 8. The Forbidden Word Sneak-In
 
@@ -154,7 +154,7 @@ step bodies.
 
 **Fix.** Tutorials and how-tos use imperative voice — "Run the
 command", "Open the file", "Set the value". Pass that constraint
-explicitly to ct-docs-write.
+explicitly to the writing guide (`ct-documentor/references/writing.md`).
 
 ## 10. The Lost Manifest
 
@@ -172,10 +172,10 @@ of the children appended in a wrong format).
 children — owns the entry. Run:
 
 ```bash
-cleo manifest append <(cat <<EOF
+cleo manifest append --entry "$(cat <<'JSON'
 {"id":"docs-<topic>-<date>", "file":"<path>", "title":"...", ...}
-EOF
-)
+JSON
+)"
 ```
 
 After append, verify with:
@@ -211,6 +211,6 @@ violations the local review didn't catch.
 **Root cause.** Documentor ran review on the draft, but not on the
 PR diff. Integration introduced drift (rebase fixups, merge prose).
 
-**Fix.** Always run `ct-docs-review --mode=pr` on the PR's diff
+**Fix.** Always run `references/reviewing.md` in PR mode on the PR's diff
 before requesting merge. Catches drift that slipped through during
 integration.

package/skills/{ct-docs-write → ct-documentor}/references/audience-targeting.md

@@ -28,8 +28,8 @@ exploring.
 Conversational, practical, second-person.
 
 ```markdown
-You can run the release pipeline manually with `cleo release ship`.
-Just kidding — never use "just". Run it with `cleo release ship`,
+You can run the release pipeline manually with `cleo release plan`.
+Just kidding — never use "just". Run it with `cleo release plan`,
 and CLEO walks through the gates one by one.
 ```
 
@@ -40,7 +40,7 @@ Do not explain why unless the why directly affects behavior.
 
 ```markdown
 GOOD (end-user):
-Run `cleo release ship 2026.5.82 --epic T9567`.
+Run `cleo release plan v2026.5.82 --epic T9567`.
 
 You see:
 - The 12 release steps run in order.
@@ -51,7 +51,7 @@ If a step fails, CLEO stops and prints the failing gate. Fix the issue
 and re-run.
 
 BAD (end-user, too deep):
-The `cleo release ship` command dispatches through `dispatch.ts`,
+The `cleo release plan` command dispatches through `dispatch.ts`,
 loading the `release` handler from the registry built at module
 init. The handler then constructs a release plan using the 12-stage
 state machine defined in `packages/cleo/src/commands/release/...`
@@ -198,7 +198,7 @@ The most common style failure is mixing audiences within a single doc.
 
 ```markdown
 BAD:
-Run `cleo release ship`.
+Run `cleo release plan`.
 
 (Internally, this dispatches through `dispatch.ts` to the release
 handler registered via the registry pattern...)

package/skills/ct-documentor/references/chain-orchestration.md

@@ -1,8 +1,8 @@
 # Chain Orchestration
 
 `ct-documentor` is a coordinator skill — it does not produce documentation
-directly. Its job is to orchestrate three child skills (`ct-docs-lookup`,
-`ct-docs-write`, `ct-docs-review`) in the right sequence with the right
+directly. Its job is to run three phases (a Context7 MCP lookup, the writing
+guide in `references/writing.md`, the review guide in `references/reviewing.md`) in the right sequence with the right
 inputs. This reference defines when to invoke each child, what to pass,
 and how to handle returns.
 
@@ -10,9 +10,9 @@ and how to handle returns.
 
 | Child | Purpose | Owns |
 |-------|---------|------|
-| `ct-docs-lookup` | Library/framework API lookup via Context7 | Current external docs |
-| `ct-docs-write` | Drafts content following CLEO style guide | New content |
-| `ct-docs-review` | Reviews against style guide; supports PR mode | Quality validation |
+| the Context7 MCP | Library/framework API lookup via Context7 | Current external docs |
+| `ct-documentor` (`references/writing.md`) | Drafts content following CLEO style guide | New content |
+| `ct-documentor` (`references/reviewing.md`) | Reviews against style guide; supports PR mode | Quality validation |
 
 A complete documentation task usually invokes write + review. Lookup is
 optional — only when the doc must cite a library's actual current API.
@@ -33,9 +33,9 @@ For every documentation task, run this sequence before invoking any child.
    - Lifecycle: new file | update existing | consolidate scattered
 
 3. CHAIN
-   - If type touches library APIs → ct-docs-lookup first
-   - Always → ct-docs-write
-   - Always → ct-docs-review
+   - If type touches library APIs → the Context7 MCP first
+   - Always → the writing guide (`ct-documentor/references/writing.md`)
+   - Always → the review guide (`ct-documentor/references/reviewing.md`)
 
 4. REPORT
    - Manifest entry with "Files NOT Created (Avoided Duplication)" section
@@ -45,7 +45,7 @@ For every documentation task, run this sequence before invoking any child.
 The Discovery step is mandatory. Skipping it produces duplicate
 documentation — the dominant failure mode of past documentation tasks.
 
-## Invoking ct-docs-lookup
+## Lookup phase (Context7 MCP)
 
 Use when the task touches a specific library, framework, or external
 API. Pass the library name, the user's actual question (full sentence,
@@ -77,10 +77,10 @@ not a single word), and any version qualifier.
 **Return.** Documentation excerpts with citations. Do not paste blindly —
 synthesize into the doc body, citing the library version.
 
-## Invoking ct-docs-write
+## Writing phase (`references/writing.md`)
 
 The write child owns content production. Its frontmatter (under
-`packages/skills/skills/ct-docs-write/SKILL.md`) describes the style
+`packages/skills/skills/ct-documentor/references/writing.md`) describes the style
 guide it enforces. Always invoke for any new or updated content.
 
 **Input shape:**
@@ -105,7 +105,7 @@ into tutorial mode when reference was needed (and vice versa).
 **Return.** A drafted markdown file. The documentor does not edit it
 directly — the next step is review.
 
-## Invoking ct-docs-review
+## Review phase (`references/reviewing.md`)
 
 The review child owns quality validation. It checks against the CLEO
 style guide and is the gate before the documentation task can complete.
@@ -131,7 +131,7 @@ file):
 
 **Return.** A numbered list of issues with line refs and suggested
 fixes. If the issue count is 0, the doc passes. If non-zero, the
-documentor MUST loop — pass the issues back to `ct-docs-write` for
+documentor MUST loop — pass the issues back to `ct-documentor` (`references/writing.md`) for
 revision, then re-review.
 
 ## The Review Loop
@@ -141,11 +141,11 @@ The documentor MUST loop until review returns zero issues OR escalates
 to HITL.
 
 ```text
-draft = ct-docs-write(input)
-issues = ct-docs-review(draft)
+draft = write_phase(input)
+issues = review_phase(draft)
 while issues != [] and iteration < 3:
-  draft = ct-docs-write(input + issues)
-  issues = ct-docs-review(draft)
+  draft = write_phase(input + issues)
+  issues = review_phase(draft)
 if issues != []:
   escalate_to_HITL("3 review iterations did not converge")
 ```
@@ -170,7 +170,7 @@ would inflate the manifest.
   "topics": ["documentation", "auth", "saml"],
   "key_findings": [
     "Created docs/guides/auth-setup.md (how-to, end-user audience)",
-    "Cited Next.js 15 middleware API via ct-docs-lookup",
+    "Cited Next.js 15 middleware API via the Context7 MCP",
     "Review converged in 2 iterations (8 issues → 3 → 0)",
     "Updated docs/index.md to reference new guide"
   ],
@@ -188,7 +188,7 @@ ran. This lets the orchestrator confirm the contract was honored.
 | Symptom | Cause | Fix |
 |---------|-------|-----|
 | Doc duplicates existing content | Skipped Discovery | Always Glob + Grep before write |
-| Doc cites stale API | Skipped ct-docs-lookup | Invoke lookup for any library API claim |
+| Doc cites stale API | Skipped the Context7 MCP | Invoke lookup for any library API claim |
 | Doc fails review repeatedly | Audience or type mismatch | Re-classify; pass corrected to write |
 | Review iteration count >3 | Mis-scoped task | Escalate to HITL with summary |
 | Manifest missing iteration data | Children appended their own entries | Children MUST return to documentor; one entry only |

package/skills/{ct-docs-write → ct-documentor}/references/cleo-style-guide.md

@@ -2,7 +2,7 @@
 
 The canonical style guide lives at
 `packages/skills/skills/_shared/cleo-style-guide.md` and is consumed
-by both ct-docs-write and ct-docs-review. This reference makes the
+by both the writing guide (`ct-documentor/references/writing.md`) and the review guide (`ct-documentor/references/reviewing.md`). This reference makes the
 guide's most-violated rules concrete with positive/negative examples
 and the rationale for each.
 

package/skills/ct-documentor/references/doc-types-and-templates.md

@@ -282,7 +282,7 @@ or that wasn't registered via `cleo docs add` / `cleo memory observe`.
 
 ## CLEO-Native: Skill
 
-Lives in `packages/skills/skills/<name>/SKILL.md`. The ct-skill-creator
+Lives in `packages/skills/skills/<name>/SKILL.md`. The ct-skill-author
 skill is the canonical template — see its references/.
 
 ## When to Pick Which Type

package/skills/{ct-docs-review → ct-documentor}/references/pr-review-mode.md

@@ -1,6 +1,6 @@
 # PR Review Mode
 
-When the GitHub MCP tools are available, ct-docs-review uses the
+When the GitHub MCP tools are available, the review guide (`ct-documentor/references/reviewing.md`) uses the
 pending-review workflow to post all findings as one cohesive GitHub
 review. This reference codifies the workflow, the comment format,
 and the integration with `gh` CLI for the cases where MCP tools are

package/skills/{ct-docs-review/SKILL.md → ct-documentor/references/reviewing.md}

@@ -1,20 +1,4 @@
----
-name: ct-docs-review
-description: This skill should be used when the user asks to "review documentation", "check docs style", "review this markdown file", "check style guide compliance", "review PR documentation", or needs documentation reviewed against the CLEO writing style guide. Supports both local file review and GitHub PR review modes with inline comments.
-version: 1.0.0
-tier: 3
-core: false
-category: composition
-protocol: null
-dependencies: []
-sharedResources: []
-compatibility:
-  - claude-code
-  - cursor
-  - windsurf
-  - gemini-cli
-license: MIT
----
+<!-- Merged from the ct-docs-review skill into ct-documentor (T12649, D11157). Load it from the documentor skill's writing/review phase. -->
 
 # Documentation Review Skill
 
@@ -45,7 +29,7 @@ storage path for larger blobs).
 
 ### Diff two versions of the same doc
 
-CLEO doesn't ship a dedicated `cleo docs diff` verb. Use version listing
+CLEO doesn't ship a dedicated docs diff verb. Use version listing
 plus two fetches to compose the diff:
 
 ```bash
@@ -298,10 +282,10 @@ The "(UPDATED)" tag signals iteration, not a brand-new flag.
 
 ---
 
-## See references/
+## See also
 
 Progressive disclosure — load on demand only:
 
-- `references/style-violations.md` — taxonomy of violations with detection patterns, issue titles, and remediation messages
-- `references/pr-review-mode.md` — pending-review workflow, comment format, gh CLI fallback, materiality filter
-- `references/inline-comment-patterns.md` — comment anatomy, single-line/multi-line/pattern fixes, anti-patterns
+- `style-violations.md` — taxonomy of violations with detection patterns, issue titles, and remediation messages
+- `pr-review-mode.md` — pending-review workflow, comment format, gh CLI fallback, materiality filter
+- `inline-comment-patterns.md` — comment anatomy, single-line/multi-line/pattern fixes, anti-patterns

package/skills/ct-documentor/references/style-coordination.md

@@ -2,7 +2,7 @@
 
 The CLEO documentation style guide lives at
 `packages/skills/skills/_shared/cleo-style-guide.md` and is referenced
-by both `ct-docs-write` and `ct-docs-review`. As coordinator, the
+by both `ct-documentor` (`references/writing.md`) and `ct-documentor` (`references/reviewing.md`). As coordinator, the
 documentor's role is to ensure the style guide is enforced consistently
 across the chain — write applies it; review verifies it. This reference
 covers the parts of the style guide most commonly violated and how the
@@ -73,7 +73,7 @@ These never appear in CLEO docs. The review child rejects them on sight.
 - "as mentioned above" — use a stable cross-reference
 
 The forbidden list is the most common reason a draft fails review.
-Pass the list to ct-docs-write as part of the input contract so it
+Pass the list to the writing guide (`ct-documentor/references/writing.md`) as part of the input contract so it
 knows what to avoid.
 
 ## Link Discipline
@@ -162,8 +162,8 @@ Documentor MUST check that write's output and review's checks agree.
 If they disagree, the style guide reference is the tiebreaker.
 
 ```text
-write_output = ct-docs-write(input)
-review_findings = ct-docs-review(write_output)
+write_output = write_phase(input)
+review_findings = review_phase(write_output)
 
 # Possible drift case:
 # write produced "users" (it should have used "people")
@@ -187,7 +187,7 @@ run review one more time on the diff:
 
 ```bash
 # Review the diff for style violations
-gh pr diff <PR_NUMBER> | ct-docs-review --mode=diff
+gh pr diff <PR_NUMBER> | review_phase --mode=diff  # references/reviewing.md, diff mode
 ```
 
 PR-mode review uses the `mcp__github__*` tools when available;

package/skills/{ct-docs-review → ct-documentor}/references/style-violations.md

@@ -1,6 +1,6 @@
 # Style Violations
 
-The taxonomy of style violations that ct-docs-review catches. Each
+The taxonomy of style violations that the review guide (`ct-documentor/references/reviewing.md`) catches. Each
 violation type carries a detection pattern, an issue title format,
 and a remediation message. The numbering scheme below (V-NNN) is
 informational — issues in reviews are numbered sequentially per

package/skills/{ct-docs-write/SKILL.md → ct-documentor/references/writing.md}

@@ -1,20 +1,4 @@
----
-name: ct-docs-write
-description: This skill should be used when creating, editing, or reviewing documentation files (markdown, MDX, README, guides). Use when the user asks to "write docs", "create documentation", "edit the README", "improve doc clarity", "make docs more readable", "follow the style guide", or "write user-facing content". Applies CLEO's conversational, clear, and user-focused writing style.
-version: 1.2.0
-tier: 3
-core: false
-category: composition
-protocol: null
-dependencies: []
-sharedResources: []
-compatibility:
-  - claude-code
-  - cursor
-  - windsurf
-  - gemini-cli
-license: MIT
----
+<!-- Merged from the ct-docs-write skill into ct-documentor (T12649, D11157). Load it from the documentor skill's writing/review phase. -->
 
 # Documentation Writing Skill
 
@@ -292,10 +276,10 @@ done
 
 ---
 
-## See references/
+## See also
 
 Progressive disclosure — load on demand only:
 
-- `references/cleo-style-guide.md` — the three pillars, forbidden phrases, format conventions, hidden drift
-- `references/markdown-patterns.md` — code-block / table / list / link / callout patterns with positive/negative examples
-- `references/audience-targeting.md` — end-user / agent / maintainer profiles, mixed-audience pitfalls, re-targeting
+- `cleo-style-guide.md` — the three pillars, forbidden phrases, format conventions, hidden drift
+- `markdown-patterns.md` — code-block / table / list / link / callout patterns with positive/negative examples
+- `audience-targeting.md` — end-user / agent / maintainer profiles, mixed-audience pitfalls, re-targeting

package/skills/ct-epic-architect/SKILL.md

@@ -1,12 +1,8 @@
 ---
 name: ct-epic-architect
 description: Epic planning and task decomposition for breaking down large initiatives into atomic, executable tasks. Provides dependency analysis, wave-based parallel execution planning, hierarchy management, and research linking. Use when creating epics, decomposing initiatives into task trees, planning parallel workflows, or analyzing task dependencies. Triggers on epic creation, task decomposition requests, or planning phase work.
-version: 3.0.0
-tier: 1
-core: false
-category: recommended
+version: 3.0.3
 protocol: decomposition
-loomStage: decomposition
 adrRefs:
   - ADR-066
   - ADR-073
@@ -20,6 +16,16 @@ compatibility:
   - windsurf
   - gemini-cli
 license: MIT
+metadata:
+  version: 3.0.3
+  tier: on-demand
+  install: harness
+  covers:
+    - packages/core/src/validation/protocols/cant/decomposition.cant
+    - packages/core/src/validation/protocols/protocols-markdown/decomposition.md
+  loomStage: decomposition
+  lastReviewed: 2026-09-28
+  stability: stable
 ---
 
 # Epic Architect Context Injection
@@ -57,7 +63,7 @@ Context injection for epic planning and task decomposition tasks spawned via cle
 3. Check existing work: `cleo find "keyword"`, `cleo list --type epic`
 4. Create epic and child tasks
 5. Attach files and link research
-6. Start session: `cleo session start --scope epic:{{EPIC_ID}} --auto-start`
+6. Start session: `cleo session start --scope epic:{{EPIC_ID}} --name "<what you are doing>"`
 7. Complete task: `cleo complete {{TASK_ID}}`
 
 ---
@@ -244,7 +250,8 @@ cleo list --parent T001 --status pending,active | jq '.tasks | length'
 
 ```bash
 cleo phase show                              # Current phase
-cleo list --phase $(cleo phase show -q)      # Tasks in phase
+cleo phase show                              # Current phase (slug)
+cleo list --phase <slug>                     # Tasks in that phase
 ```
 
 ---
@@ -278,8 +285,8 @@ Recommendation: [Your recommendation]
 
 ### Output Requirements
 
-1. MUST write decomposition to: `{{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md`
-2. MUST append ONE line to: `{{MANIFEST_PATH}}`
+1. MUST record decomposition with `cleo docs add {{TASK_ID}} --content - --type plan --slug {{TOPIC_SLUG}}` (never a raw file under `.cleo/agent-outputs/`)
+2. MUST record ONE manifest entry: `cleo manifest append --entry '<entry JSON>'` (the flat manifest file is retired, ADR-027)
 3. MUST return ONLY: "Decomposition complete. Manifest appended to pipeline_manifest."
 4. MUST NOT return full decomposition in response
 

package/skills/ct-epic-architect/references/commands.md

@@ -156,7 +156,7 @@ cleo list --tree --parent {{EPIC_ID}}      # Show epic subtree
 | `{{TASK_TREE_CMD}}` | `cleo list --tree` |
 | `{{TASK_ANALYZE_CMD}}` | `cleo analyze` |
 | `{{TASK_ARCHIVE_CMD}}` | `cleo archive` |
-| `{{TASK_VALIDATE_CMD}}` | `cleo validate` |
+| `{{TASK_VALIDATE_CMD}}` | `cleo check task <id>` |
 
 ### Session Tokens
 
@@ -174,7 +174,7 @@ cleo list --tree --parent {{EPIC_ID}}      # Show epic subtree
 | Token | CLEO Default |
 |-------|--------------|
 | `{{TASK_CURRENT_CMD}}` | `cleo current` |
-| `{{TASK_NOTE_CMD}}` | `cleo note` |
+| `{{TASK_NOTE_CMD}}` | `cleo update <id> --notes "..."` |
 | `{{TASK_STOP_CMD}}` | `cleo stop` |
 
 ### Verification Tokens
@@ -187,15 +187,15 @@ cleo list --tree --parent {{EPIC_ID}}      # Show epic subtree
 
 | Token | CLEO Default |
 |-------|--------------|
-| `{{TASK_RESEARCH_INIT_CMD}}` | `cleo research init` |
+| `{{TASK_RESEARCH_INIT_CMD}}` | `cleo research add` |
 | `{{TASK_RESEARCH_LIST_CMD}}` | `cleo research list` |
 | `{{TASK_RESEARCH_SHOW_CMD}}` | `cleo research show` |
 | `{{TASK_RESEARCH_PENDING_CMD}}` | `cleo research pending` |
-| `{{TASK_RESEARCH_INJECT_CMD}}` | `cleo research inject` |
+| `{{TASK_RESEARCH_INJECT_CMD}}` | `cleo orchestrate spawn <taskId>` (embeds the protocol; there is no inject verb) |
 
 ### Output Tokens
 
 | Token | Default |
 |-------|---------|
-| `{{OUTPUT_DIR}}` | `.cleo/agent-outputs` |
+| `{{OUTPUT_DIR}}` | `.cleo/agent-outputs` (legacy token — do not write there; record output with `cleo docs add`) |
 

package/skills/ct-epic-architect/references/output-format.md

@@ -6,7 +6,7 @@ Template for epic creation output files.
 
 ## Output File Location
 
-Write to `{{OUTPUT_DIR}}/{{DATE}}_epic-{{FEATURE_SLUG}}.md`
+Record it with `cleo docs add {{TASK_ID}} --content - --type plan --slug epic-{{FEATURE_SLUG}}` (never a raw file under `.cleo/agent-outputs/`)
 
 ---
 
@@ -85,7 +85,7 @@ Write to `{{OUTPUT_DIR}}/{{DATE}}_epic-{{FEATURE_SLUG}}.md`
 
 ## Manifest Entry Format
 
-Append ONE line (no pretty-printing) to `{{MANIFEST_PATH}}`:
+Record it with `cleo manifest append --entry '<entry JSON>'` (the flat manifest file is retired, ADR-027):
 
 ```json
 {"id":"epic-{{FEATURE_SLUG}}-{{DATE}}","file":"{{DATE}}_epic-{{FEATURE_SLUG}}.md","title":"Epic Created: {{FEATURE_NAME}}","date":"{{DATE}}","status":"complete","topics":["epic","planning","{{DOMAIN}}"],"key_findings":["Created Epic {{EPIC_ID}} with {{N}} child tasks","Dependency chain: {{T1}} -> {{T2}}/{{T3}} -> {{T4}} -> {{T5}}","Wave 0 (parallel start): [{{T1_ID}}]","Wave 1 (parallel): [{{T2_ID}}, {{T3_ID}}]","Critical path: {{T1}} -> {{T2}} -> {{T4}} -> {{T5}}","Session started: {{SESSION_ID}}"],"actionable":true,"needs_followup":["{{FIRST_READY_TASK_ID}}"],"linked_tasks":["{{EPIC_ID}}","{{ALL_TASK_IDS}}"]}

package/skills/ct-epic-architect/references/patterns.md

@@ -56,8 +56,8 @@ Each research task SHOULD address exactly ONE research question:
 
 ### Research Output Integration
 
-- Subagents write findings to `{{OUTPUT_DIR}}/`
-- Subagents append entry to `{{MANIFEST_PATH}}` with `linked_tasks: ["{{TASK_ID}}"]`
+- Subagents record findings with `cleo docs add` (never raw files under `.cleo/agent-outputs/`)
+- Subagents record an entry with `cleo manifest append --task {{TASK_ID}}` (its `linked_tasks` starts with the task)
 - Orchestrator reads only manifest summaries (key_findings) for context efficiency
 - Use `{{TASK_RESEARCH_INJECT_CMD}}` to get subagent protocol block
 

package/skills/ct-epic-architect/references/skill-aware-execution.md

@@ -117,8 +117,8 @@ Before creating epics, ct-epic-architect SHOULD check existing research:
 
 When ct-epic-architect creates an epic, it follows the subagent protocol:
 
-1. **Write output file**: `{{OUTPUT_DIR}}/{{DATE}}_epic-{{FEATURE_SLUG}}.md`
-2. **Append manifest entry**: Single line JSON to `{{MANIFEST_PATH}}`
+1. **Record output**: `cleo docs add {{TASK_ID}} --content - --type plan --slug {{TOPIC_SLUG}}`
+2. **Record manifest entry**: `cleo manifest append --entry '<entry JSON>'` (the flat manifest file is retired, ADR-027)
 3. **Return summary only**: "Epic created. Manifest appended to pipeline_manifest."
 
 ### Querying Prior Research
@@ -170,7 +170,7 @@ The orchestrator skill enforces context budget (ORC-005). When spawning ct-epic-
 
 ```bash
 # Orchestrator queries manifest for epic details
-tail -1 {{MANIFEST_PATH}} | jq '.key_findings'
+cleo manifest list --task {{TASK_ID}} --json
 ```
 
 ---

package/skills/ct-grade/SKILL.md

@@ -13,12 +13,9 @@ description: >-
   analysis and comparative report. Triggers on: grade session, evaluate agent behavior,
   A/B test CLEO configurations, run grade scenario, token usage analysis, behavioral rubric,
   protocol compliance scoring.
-version: 2.1.0
+version: 2.1.1
 argument-hint: "[mode=scenario|ab|blind] [scenario=s1-s5|all] [runs=N] [session-id=<id>]"
 allowed-tools: ["Bash(python *)", "Bash(cleo-dev *)", "Bash(cleo *)", "Bash(kill *)", "Bash(lsof *)", "Agent", "Read", "Write", "Glob"]
-tier: 2
-core: false
-category: quality
 protocol: null
 dependencies: []
 sharedResources: []
@@ -28,6 +25,12 @@ compatibility:
   - windsurf
   - gemini-cli
 license: MIT
+metadata:
+  version: 2.1.1
+  tier: internal
+  install: internal
+  lastReviewed: 2026-09-28
+  stability: stable
 ---
 
 # Session Grading Guide

package/skills/ct-grade/agents/scenario-runner.md

@@ -43,7 +43,7 @@ cleo session end
 ### Step 5: Grade the session
 
 ```bash
-cleo check grade --session "<saved-id>"
+cleo grade "<saved-id>"
 ```
 
 Save the full GradeResult JSON.