@cleocode/skills 2.0.0

package/skills/ct-epic-architect/references/shell-escaping.md

@@ -0,0 +1,86 @@
+# Shell Escaping Reference
+
+When passing text to CLEO commands via `--notes`, `--description`, or other text fields, certain characters require escaping to prevent shell interpretation.
+
+---
+
+## Quick Reference
+
+| Character | Escape As | Example |
+|-----------|-----------|---------|
+| `$` | `\$` | `\$100`, `\$HOME` |
+| Backtick | `\`` | Code blocks |
+| `"` | `\"` | Nested quotes |
+| Exclamation | `\!` | History expansion (bash) |
+
+---
+
+## Common Patterns
+
+### Dollar Signs in Notes
+
+```bash
+# CORRECT - escaped dollar sign
+cleo add "Task" --notes "Cost estimate: \$500 per user"
+cleo add "Task" --description "Process \$DATA variable"
+
+# WRONG - $500 and $DATA interpreted as shell variables
+cleo add "Task" --notes "Cost estimate: $500 per user"
+cleo add "Task" --description "Process $DATA variable"
+```
+
+### Quotes in Text
+
+```bash
+# CORRECT - escaped inner quotes
+cleo add "Task" --notes "User said \"hello world\""
+
+# Alternative - use single quotes for outer
+cleo add 'Task with "quotes" inside'
+```
+
+### Backticks for Code
+
+```bash
+# CORRECT - escaped backticks
+cleo add "Task" --notes "Run \`npm install\` first"
+
+# Alternative - use $() syntax in description
+cleo add "Task" --notes 'Run `npm install` first'
+```
+
+---
+
+## Validation Errors
+
+If you see validation exit code 6 (`E_VALIDATION_*`), check for unescaped special characters in your text fields. The shell may have interpolated variables before CLEO received the input.
+
+### Debugging Tips
+
+1. Echo your command first to see what the shell produces:
+   ```bash
+   echo "cleo add \"Task\" --notes \"Price: $500\""
+   # Shows: cleo add "Task" --notes "Price: "
+   # The $500 became empty (no $500 variable exists)
+   ```
+
+2. Use single quotes when escaping is complex:
+   ```bash
+   cleo add 'Task' --notes 'Price: $500 for "premium" tier'
+   ```
+
+---
+
+## HEREDOC for Complex Text
+
+For multi-line or heavily-quoted content, use a HEREDOC:
+
+```bash
+cleo update T001 --notes "$(cat <<'EOF'
+Complex notes with $variables and "quotes"
+that don't need escaping inside HEREDOC.
+EOF
+)"
+```
+
+Note: Use `<<'EOF'` (quoted) to prevent variable expansion, or `<<EOF` (unquoted) if you want variables expanded.

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

@@ -0,0 +1,195 @@
+# Skill-Aware Epic Execution Patterns
+
+This reference documents how to integrate the ct-epic-architect skill with orchestrators, subagents, and CLEO research commands.
+
+---
+
+## Orchestrator Workflow
+
+### When to Invoke ct-epic-architect
+
+Use the ct-epic-architect skill when the user's request involves:
+
+| Trigger | Example Request | Action |
+|---------|-----------------|--------|
+| Epic creation | "Create an epic for user authentication" | Invoke `/ct-epic-architect` |
+| Task decomposition | "Break down this project into tasks" | Invoke `/ct-epic-architect` |
+| Dependency planning | "Plan the dependency order for this feature" | Invoke `/ct-epic-architect` |
+| Wave analysis | "What can run in parallel?" | Invoke `/ct-epic-architect` |
+| Sprint planning | "Plan the sprint backlog" | Invoke `/ct-epic-architect` |
+
+### How to Invoke
+
+```
+# Via Skill tool
+Skill(skill="ct-epic-architect")
+
+# Via slash command
+/ct-epic-architect
+```
+
+**What Loads:**
+1. SKILL.md body (480 lines of core instructions)
+2. Access to references/ files (loaded on-demand when Claude reads them)
+
+### Decision Tree
+
+```
+User Request
+    │
+    ▼
+┌───────────────────────────────┐
+│ Is this about epic/task       │
+│ planning and decomposition?   │
+└───────────────────────────────┘
+    │
+    ├── YES ─► Invoke /ct-epic-architect
+    │
+    └── NO ─► Handle directly or use other skill
+```
+
+---
+
+## Subagent Skill Specification
+
+### Why Subagents Don't Inherit Skills
+
+Per the skill system architecture:
+- **Skills are session-scoped** - They load into the CURRENT context
+- **Subagents are NEW contexts** - They don't automatically get parent skills
+- **This is intentional** - Prevents context bloat and skill pollution
+
+### When Subagents SHOULD Have ct-epic-architect
+
+| Scenario | Should Have Skill? | Rationale |
+|----------|-------------------|-----------|
+| Coder implementing a task | No | Coders execute, not plan |
+| Researcher gathering info | No | Researchers investigate, not plan |
+| Nested orchestrator | Yes | Needs planning capability |
+| Epic architect subagent | Yes | Primary function requires it |
+
+### Declaring Skills for Subagents
+
+When spawning a subagent that needs ct-epic-architect:
+
+```markdown
+# In subagent prompt frontmatter (if using template)
+---
+name: nested-orchestrator
+skills:
+  - ct-epic-architect
+  - orchestrator
+---
+```
+
+Or via Task tool:
+
+```
+Task(
+  subagent_type="general-purpose",
+  prompt="""
+  You have access to the ct-epic-architect skill.
+  Use /ct-epic-architect when you need to create epics.
+
+  [Task description]
+  """
+)
+```
+
+---
+
+## CLEO Research Integration
+
+### Epic-Architect Uses Research Commands
+
+Before creating epics, ct-epic-architect SHOULD check existing research:
+
+```bash
+# Check for related research before planning
+{{TASK_RESEARCH_LIST_CMD}} --status complete --topic {{DOMAIN}}
+{{TASK_RESEARCH_SHOW_CMD}} {{RESEARCH_ID}}
+
+# Link epic to research after creation
+{{TASK_LINK_CMD}} {{EPIC_ID}} {{RESEARCH_ID}}
+```
+
+### Research Output Protocol for Epic Creation
+
+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}}`
+3. **Return summary only**: "Epic created. See MANIFEST.jsonl for summary."
+
+### Querying Prior Research
+
+Epic-architect can leverage prior research for informed planning:
+
+```bash
+# Find research related to the epic domain
+{{TASK_RESEARCH_LIST_CMD}} --topic "authentication"
+
+# Get key findings from specific research
+{{TASK_RESEARCH_SHOW_CMD}} research-auth-options-2026-01-15
+
+# The key_findings array informs epic structure without loading full content
+```
+
+---
+
+## Integration with Orchestrator Skill
+
+### Orchestrator → Epic-Architect Flow
+
+```
+Orchestrator receives "plan authentication feature"
+    │
+    ▼
+Orchestrator spawns ct-epic-architect subagent
+    │
+    ▼
+Epic-architect creates epic and tasks in CLEO
+    │
+    ▼
+Epic-architect writes to manifest
+    │
+    ▼
+Orchestrator reads manifest key_findings
+    │
+    ▼
+Orchestrator proceeds with task execution
+```
+
+### Context Protection
+
+The orchestrator skill enforces context budget (ORC-005). When spawning ct-epic-architect:
+
+1. **Pass minimal context** - Epic-architect reads full task details itself
+2. **Receive minimal response** - Only manifest summary returned
+3. **Query manifest for details** - Don't ask ct-epic-architect for full breakdown
+
+```bash
+# Orchestrator queries manifest for epic details
+tail -1 {{MANIFEST_PATH}} | jq '.key_findings'
+```
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Problem | Solution |
+|--------------|---------|----------|
+| Giving all subagents ct-epic-architect skill | Context bloat | Only nested orchestrators need it |
+| Returning full epic details | Bloats orchestrator context | Return "Epic created. See MANIFEST." |
+| Skipping research check | Duplicate work | Always query research first |
+| Loading all references | Wasted tokens | Load only needed references |
+| Parallel epic creation | Task conflicts | Create epics sequentially |
+
+---
+
+## Cross-References
+
+- **Orchestrator Skill**: skills/ct-orchestrator/SKILL.md
+- **Subagent Protocol**: skills/_shared/subagent-protocol-base.md
+- **Task System Integration**: skills/_shared/task-system-integration.md
+- **Research Commands**: docs/commands/research.md

package/skills/ct-grade/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: ct-grade
+description: Session grading for agent behavioral analysis. Use when evaluating agent session quality, running grade scenarios, or interpreting grade results. Triggers on grading tasks, session quality checks, or behavioral analysis needs.
+version: 1.0.0
+tier: 2
+core: false
+category: quality
+protocol: null
+dependencies: []
+sharedResources: []
+compatibility:
+  - claude-code
+  - cursor
+  - windsurf
+  - gemini-cli
+license: MIT
+---
+
+# Session Grading Guide
+
+Session grading evaluates agent behavioral patterns against the CLEO protocol. It reads the audit log for a completed session and applies a 5-dimension rubric to produce a score (0-100), letter grade (A-F), and diagnostic flags.
+
+## When to Use Grade Mode
+
+Use grading when you need to:
+- Evaluate how well an agent followed CLEO protocol during a session
+- Identify behavioral anti-patterns (skipped discovery, missing session.end, etc.)
+- Track improvement over time across multiple sessions
+- Validate that orchestrated subagents followed protocol
+
+Grading requires audit data. Sessions must be started with the `--grade` flag to enable audit log capture.
+
+## Starting a Grade Session
+
+### CLI
+
+```bash
+# Start a session with grading enabled
+ct session start --scope epic:T001 --name "Feature work" --grade
+
+# The --grade flag enables detailed audit logging
+# All MCP and CLI operations are recorded for later analysis
+```
+
+### MCP
+
+```
+mutate({ domain: "session", operation: "start",
+  params: { scope: "epic:T001", name: "Feature work", grade: true }})
+```
+
+## Running Scenarios
+
+The grading rubric evaluates 5 behavioral scenarios that map to protocol compliance:
+
+### 1. Fresh Discovery
+Tests whether the agent checks existing sessions and tasks before starting work. Evaluates `session.list` and `tasks.find` calls at session start.
+
+### 2. Task Hygiene
+Tests whether task creation follows protocol: descriptions provided, parent existence verified before subtask creation, no duplicate tasks.
+
+### 3. Error Recovery
+Tests whether the agent handles errors correctly: follows up `E_NOT_FOUND` with recovery lookups (`tasks.find` or `tasks.exists`), avoids duplicate creates after failures.
+
+### 4. Full Lifecycle
+Tests session discipline end-to-end: session listed before task ops, session properly ended, MCP-first usage patterns.
+
+### 5. Multi-Domain Analysis
+Tests progressive disclosure: use of `admin.help` or skill lookups, preference for `query` (MCP) over CLI for programmatic access.
+
+## Evaluating Results
+
+### CLI
+
+```bash
+# Grade a specific session
+ct grade <sessionId>
+
+# List all past grade results
+ct grade --list
+```
+
+### MCP
+
+```
+# Grade a session
+# Canonical registry surface (preferred)
+query({ domain: "check", operation: "grade",
+  params: { sessionId: "abc-123" }})
+
+# List past grades
+query({ domain: "check", operation: "grade.list" })
+
+# Compatibility aliases still work at runtime
+query({ domain: "admin", operation: "grade",
+  params: { sessionId: "abc-123" }})
+```
+
+## Understanding the 5 Dimensions
+
+Each dimension scores 0-20 points, totaling 0-100.
+
+### S1: Session Discipline (20 pts)
+
+| Points | Criteria |
+|--------|----------|
+| 10 | `session.list` called before first task operation |
+| 10 | `session.end` called when work is complete |
+
+**What it measures**: Does the agent check existing sessions before starting, and properly close sessions when done?
+
+### S2: Discovery Efficiency (20 pts)
+
+| Points | Criteria |
+|--------|----------|
+| 0-15 | `find:list` ratio >= 80% earns full 15; scales linearly below |
+| 5 | `tasks.show` used for detail retrieval |
+
+**What it measures**: Does the agent prefer `tasks.find` (low context cost) over `tasks.list` (high context cost) for discovery?
+
+### S3: Task Hygiene (20 pts)
+
+Starts at 20 and deducts for violations:
+
+| Deduction | Violation |
+|-----------|-----------|
+| -5 each | `tasks.add` without a description |
+| -3 | Subtasks created without `tasks.exists` parent check |
+
+**What it measures**: Does the agent create well-formed tasks with descriptions and verify parents before creating subtasks?
+
+### S4: Error Protocol (20 pts)
+
+Starts at 20 and deducts for violations:
+
+| Deduction | Violation |
+|-----------|-----------|
+| -5 each | `E_NOT_FOUND` error not followed by recovery lookup within 5 ops |
+| -5 | Duplicate task creates detected (same title in session) |
+
+**What it measures**: Does the agent recover gracefully from errors and avoid creating duplicate tasks?
+
+### S5: Progressive Disclosure Use (20 pts)
+
+| Points | Criteria |
+|--------|----------|
+| 10 | `admin.help` or skill lookup calls made |
+| 10 | `query` (MCP gateway) used for programmatic access |
+
+**What it measures**: Does the agent use progressive disclosure (help/skills) and prefer MCP over CLI?
+
+## Interpreting Scores
+
+### Letter Grades
+
+| Grade | Score Range | Meaning |
+|-------|-----------|---------|
+| **A** | 90-100 | Excellent protocol adherence. Agent follows all best practices. |
+| **B** | 75-89 | Good. Minor gaps in one or two dimensions. |
+| **C** | 60-74 | Acceptable. Several protocol violations need attention. |
+| **D** | 45-59 | Below expectations. Significant anti-patterns present. |
+| **F** | 0-44 | Failing. Major protocol violations across multiple dimensions. |
+
+### Reading the Output
+
+The grade result includes:
+- **score/maxScore**: Raw numeric score (e.g., `85/100`)
+- **percent**: Percentage score
+- **grade**: Letter grade (A-F)
+- **dimensions**: Per-dimension breakdown with score, max, and evidence
+- **flags**: Specific violations or improvement suggestions
+- **entryCount**: Number of audit entries analyzed
+
+### Flags
+
+Flags are actionable diagnostic messages. Each flag identifies a specific behavioral issue:
+
+- `session.list never called` -- Check existing sessions before starting new ones
+- `session.end never called` -- Always end sessions when done
+- `tasks.list used Nx` -- Prefer `tasks.find` for discovery
+- `tasks.add without description` -- Always provide task descriptions
+- `Subtasks created without tasks.exists parent check` -- Verify parent exists first
+- `E_NOT_FOUND not followed by recovery lookup` -- Follow errors with `tasks.find` or `tasks.exists`
+- `No admin.help or skill lookup calls` -- Load `ct-cleo` for protocol guidance
+- `No MCP query calls` -- Prefer `query` over CLI
+
+## Common Anti-patterns
+
+| Anti-pattern | Impact | Fix |
+|-------------|--------|-----|
+| Skipping `session.list` at start | -10 S1 | Always check existing sessions first |
+| Forgetting `session.end` | -10 S1 | End sessions when work is complete |
+| Using `tasks.list` instead of `tasks.find` | -up to 15 S2 | Use `find` for discovery, `list` only for known parent children |
+| Creating tasks without descriptions | -5 each S3 | Always provide a description with `tasks.add` |
+| Ignoring `E_NOT_FOUND` errors | -5 each S4 | Follow up with `tasks.find` or `tasks.exists` |
+| Creating duplicate tasks | -5 S4 | Check for existing tasks before creating new ones |
+| Never using `admin.help` | -10 S5 | Use progressive disclosure for protocol guidance |
+| CLI-only usage (no MCP) | -10 S5 | Prefer `query`/`mutate` for programmatic access |
+
+## Grade Result Schema
+
+Grade results are stored in `.cleo/metrics/GRADES.jsonl` as append-only JSONL. Each entry conforms to `schemas/grade.schema.json` with these fields:
+
+- `sessionId` (string, required) -- Session that was graded
+- `taskId` (string, optional) -- Associated task ID
+- `totalScore` (number, 0-100) -- Aggregate score
+- `maxScore` (number, default 100) -- Maximum possible score
+- `dimensions` (object) -- Per-dimension `{ score, max, evidence[] }`
+- `flags` (string[]) -- Specific violations or suggestions
+- `timestamp` (ISO 8601) -- When the grade was computed
+- `entryCount` (number) -- Audit entries analyzed
+- `evaluator` (`auto` | `manual`) -- How the grade was computed
+
+## MCP Operations
+
+| Gateway | Domain | Operation | Description |
+|---------|--------|-----------|-------------|
+| `query` | `check` | `grade` | Canonical grade read (`params: { sessionId }`) |
+| `query` | `check` | `grade.list` | Canonical grade history read |
+| `query` | `admin` | `grade` | Compatibility alias for runtime handlers |
+| `query` | `admin` | `grade.list` | Compatibility alias for runtime handlers |
+| `query` | `admin` | `token` | Canonical token telemetry read (`action=summary|list|show`) |
+
+
+## API Update Notes
+
+- Prefer the canonical registry surface from `docs/specs/CLEO-API.md`: `check.grade`, `check.grade.list`, and `admin.token` with an `action` param.
+- `admin.grade*` and split `admin.token.*` paths remain compatibility handlers and may still appear in existing automation.
+- Browser clients should target `POST /api/query` and `POST /api/mutate`; LAFS metadata is carried in `X-Cleo-*` headers by default.
+- Treat persisted token transport values `api` and `http` as equivalent during the compatibility window described in `docs/specs/CLEO-WEB-API.md`.