diff --git a/.claude/commands/full-review.md b/.claude/commands/full-review.md index cb53734..eb9af47 100644 --- a/.claude/commands/full-review.md +++ b/.claude/commands/full-review.md @@ -30,6 +30,20 @@ At start, verify CCO repo using Claude's native tools: **Use Glob/Read for file detection. Git commands are cross-platform.** +## State Management + +Per CCO Rules: State Management. This command uses task prefix `[FR]`. + +| Task | Created | Completed | +|------|---------|-----------| +| `[FR] Inventory` | Step-2 start | Step-2 end | +| `[FR] Analyze Batch 1` | Step-3 Batch 1 launch | Batch 1 done | +| `[FR] Analyze Batch 2` | Step-3 Batch 2 launch | Batch 2 done | +| `[FR] Prioritize` | Step-4 start | Step-4 end | +| `[FR] Apply` | Step-6 start | Step-6 end | + +**Recovery:** At Step-1, run TaskList. If `[FR]` tasks exist with incomplete status → per State Management recovery protocol. + ## Context Check [CRITICAL] If not in CCO repository root: @@ -45,7 +59,7 @@ Run this command from the ClaudeCodeOptimizer directory. |------|------|--------| | 1 | Setup | Q1: Review mode selection | | 2 | Inventory | Detect counts via Glob | -| 3 | Analyze | 4 Explore agent groups (parallel) | +| 3 | Analyze | 2+2 batched Explore agent groups | | 4 | Prioritize | 80/20 findings | | 5 | Approval | Q2: Select fixes (conditional) | | 6 | Apply | Delegate to cco-agent-apply | @@ -74,6 +88,10 @@ if (!isUnattended && !isReportOnly) { ## Step-2: Inventory Detection +**Recovery check:** TaskList → filter `[FR]` prefix. If incomplete tasks found → per State Management recovery protocol. + +TaskCreate `[FR] Inventory` (status: in_progress). + ```javascript // Cross-platform detection using Claude's native tools — all counts are dynamic skills = Glob("skills/cco-*/SKILL.md").length @@ -87,11 +105,20 @@ inventory = { skills, agents, docs, workflows, version } **Note:** Rules are in `rules/cco-rules.md` (single source of truth). Never hardcode expected counts — always detect dynamically and compare across reference files. +TaskUpdate `[FR] Inventory` → completed. Store counts in description. + --- -## Step-3: 8-Category Analysis [PARALLEL AGENTS] +## Step-3: 8-Category Analysis [BATCHED: 2+2 AGENTS] + +Per CCO Rules: Parallel Execution (max 2 Task calls per message). Launch in 2 batches: -Launch 4 parallel Explore agents covering 8 categories: +**Batch 1:** Group A (Inventory & Release) + Group B (Skill & Agent Quality + Architecture) +**Batch 2:** Group C (AI Communication + Efficiency) + Group D (Production Standards + Documentation) + +Wait for Batch 1 to complete before launching Batch 2. After each batch, TaskUpdate corresponding `[FR] Analyze Batch N` → completed, write findings to description in compact format. + +8 categories across 4 groups: ### Group A: Inventory & Release (Cat 1 + Cat 8) @@ -215,11 +242,15 @@ Per CCO Rules: Severity Levels. ## Step-4: Prioritize +TaskCreate `[FR] Prioritize` (status: in_progress). + Rank findings by 80/20 rule: 1. **Quick Win** — CRITICAL + HIGH, auto-fixable 2. **Moderate** — MEDIUM, requires targeted edit 3. **Complex** — LOW or multi-file structural changes +TaskUpdate `[FR] Prioritize` → completed. Store prioritized findings in description. + --- ## Step-5: Fix Approval [SKIP IF --auto or --preview or zero findings] @@ -247,6 +278,10 @@ if (findings.length > 0) { ## Step-6: Apply Fixes [DELEGATE TO AGENT] +TaskCreate `[FR] Apply` (status: in_progress). + +**Recovery-aware read:** If findings not in conversation context (compaction occurred), reconstruct from TaskGet on `[FR] Analyze Batch 1/2` task descriptions. + ```javascript if (toApply.length > 0) { Task("cco-agent-apply", ` @@ -268,6 +303,8 @@ if (toApply.length > 0) { ## Step-7: Summary +**State cleanup:** TaskUpdate all `[FR]` tasks → completed. + ``` ═══════════════════════════════════════════════════════════ CCO FULL REVIEW diff --git a/agents/cco-agent-analyze.md b/agents/cco-agent-analyze.md index a901cc6..cb4488d 100644 --- a/agents/cco-agent-analyze.md +++ b/agents/cco-agent-analyze.md @@ -1,7 +1,11 @@ --- name: cco-agent-analyze description: "Sub-agent: codebase analysis with severity scoring — security, privacy, hygiene, types, performance, robustness, functional-completeness. Used by /cco-optimize, /cco-align, /cco-blueprint and autonomously for code audits." -tools: Glob, Read, Grep, Bash +tools: + - Glob + - Read + - Grep + - Bash model: haiku --- diff --git a/agents/cco-agent-apply.md b/agents/cco-agent-apply.md index 7073cbc..c051068 100644 --- a/agents/cco-agent-apply.md +++ b/agents/cco-agent-apply.md @@ -1,7 +1,15 @@ --- name: cco-agent-apply description: "Sub-agent: batch write operations with verification, cascade fixing, and accounting. Used by /cco-optimize, /cco-align and autonomously for bulk fixes." -tools: Grep, Read, Glob, Bash, Edit, Write, NotebookEdit, AskUserQuestion +tools: + - Grep + - Read + - Glob + - Bash + - Edit + - Write + - NotebookEdit + - AskUserQuestion --- # cco-agent-apply diff --git a/agents/cco-agent-research.md b/agents/cco-agent-research.md index 8f972a9..2b7d29a 100644 --- a/agents/cco-agent-research.md +++ b/agents/cco-agent-research.md @@ -1,7 +1,12 @@ --- name: cco-agent-research description: "Sub-agent: web search, source scoring, and CRAAP+ synthesis. Used by /cco-research skill and autonomously for research tasks." -tools: WebSearch, WebFetch, Read, Grep, Glob +tools: + - WebSearch + - WebFetch + - Read + - Grep + - Glob model: haiku --- diff --git a/docs/architecture.md b/docs/architecture.md index 0f56d8c..1e283f4 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -86,7 +86,16 @@ Rules are loaded automatically at session start via Claude Code's native mechani Skills use Claude Code's native skill mechanism with `SKILL.md` files in `~/.claude/skills/{name}/`. Frontmatter fields (`allowed-tools`, `description`) are enforced by Claude Code, unlike the legacy `commands/` directory. -6 skills have auto-invoke enabled (triggered by natural language), 2 require explicit invocation (`/cco-blueprint`, `/cco-update`). +8 skills total: 6 have auto-invoke enabled (triggered by natural language) and 2 require explicit invocation. + +| Mode | Skills | +|------|--------| +| Auto-invoke | `cco-optimize`, `cco-align`, `cco-commit`, `cco-research`, `cco-docs`, `cco-pr` | +| Explicit only | `cco-blueprint` (`/cco-blueprint`), `cco-update` (`/cco-update`) | + +### Skill Variables + +Claude Code provides `${CLAUDE_SKILL_DIR}` (v2.1.69+), which resolves to the skill's own directory at runtime. CCO skills currently use inline content and reference agents by name, so this variable is not yet used. It becomes relevant when skills need to reference local assets (templates, schemas, config files) stored alongside SKILL.md. ### Shared Patterns @@ -160,6 +169,18 @@ Skills invoke agents using these standard groupings: 5. Merge findings, deduplicate by file:line (keep highest severity) 6. Per CCO Rules: CRITICAL Escalation — validate CRITICAL findings with opus before proceeding +### Compaction Resilience + +Long-running skills use Task tools for compaction-resilient state tracking. + +| Layer | Mechanism | Survives Compaction | +|-------|-----------|---------------------| +| Phase progress | TaskCreate/TaskUpdate status | Yes | +| Findings summary | Task description (compact format) | Yes | +| Recovery anchor | TaskList + prefix filter | Yes | + +Skills with 3+ phases create prefixed tasks (`[BP]`, `[OPT]`, `[ALN]`, `[FR]`, `[RSC]`, `[DOC]`) and update them at phase gates. On compaction, TaskList retrieves completed phases and TaskGet reconstructs findings from compact descriptions. See CCO Rules: State Management. + ### File Manifest Sync The file list in `extras/installer/manifest.go` is the single source of truth for installed files. When adding or removing a skill/agent file, update `manifest.go`. diff --git a/docs/skills.md b/docs/skills.md index 7cbec91..f7acad7 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -266,6 +266,22 @@ Update CCO to the latest version. --- +## CCO vs Built-in Commands + +Claude Code includes built-in `/simplify` and `/batch` commands (v2.1.63+). Key differences from CCO: + +| Feature | `/simplify` (built-in) | `/cco-optimize` | +|---------|----------------------|-----------------| +| Scope | Changed code only (reuse, quality, efficiency) | 9 scopes, 97 checks across entire codebase | +| Severity scoring | No | CRITICAL/HIGH/MEDIUM/LOW with confidence | +| Parallel analysis | No | Batched agent analysis | +| Accounting | No | applied + failed + needs_approval = total | +| Blueprint integration | No | Feeds into `/cco-blueprint` health scores | + +Use `/simplify` for quick post-edit cleanup. Use `/cco-optimize` for comprehensive code quality analysis. + +--- + ## Common Patterns ### Unattended Mode @@ -280,6 +296,16 @@ Update CCO to the latest version. Per CCO Rules: `applied + failed + needs_approval = total` (no silent skips) +### Compaction Resilience + +Long-running skills (`/cco-blueprint`, `/cco-optimize`, `/cco-align`, `/cco-research`, `/cco-docs`, `/full-review`) track progress via Task tools. If context compaction occurs mid-skill: + +1. TaskList shows completed vs pending phases +2. Completed phase findings are preserved in task descriptions +3. Only incomplete phases are re-run + +Per CCO Rules: State Management. + ### Recovery | Situation | Command | diff --git a/release-please-config.json b/release-please-config.json index 485f98d..073abe1 100644 --- a/release-please-config.json +++ b/release-please-config.json @@ -1,4 +1,6 @@ { + "pull-request-title-pattern": "chore: release v${version}", + "pull-request-header": ":bookmark: Automated release — review changelog below, then merge to publish.", "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json", "packages": { ".": { diff --git a/rules/cco-rules.md b/rules/cco-rules.md index 343edeb..3d4b0f0 100644 --- a/rules/cco-rules.md +++ b/rules/cco-rules.md @@ -100,6 +100,20 @@ When --auto active: no questions, no deferrals. Fix everything except large arch Agents return structured data as final text message. Never write to files. On failure: {"error": "message"}. Validate before processing; retry once if malformed. On second failure, continue with remaining groups. Score failed dimensions as N/A. +**Bash sanitization:** When agents construct Bash commands dynamically (file paths from findings, user-provided scope names), never interpolate raw values into shell strings. Use `--` to terminate flag parsing, quote all path arguments, and reject values containing shell metacharacters (`;`, `|`, `&`, `$`, `` ` ``, `\n`). Prefer passing arguments as separate tokens over string concatenation. + +### Hook Integration + +Claude Code supports `PreToolUse`, `PostToolUse`, `Stop`, and `InstructionsLoaded` hooks in skill and agent frontmatter. CCO leverages hooks where they add portable, cross-project value: + +| Hook | Where | Purpose | +|------|-------|---------| +| `InstructionsLoaded` | User config | Auto-trigger `/cco-update --check` on session start (optional, user-configured) | +| `PreToolUse` | Skills using Bash | Validate dynamically constructed commands before execution (sanitization gate) | +| `PostToolUse` | Agent apply | Verify edit/write results against expectations (cascade trigger) | + +Hook commands must be portable (no OS-specific or project-specific tool assumptions). Hooks that require external tools (gitleaks, linters) follow Tool Prerequisites: skip silently if unavailable. + ### Tool Prerequisites Verify required external tools before execution. @@ -128,6 +142,7 @@ When findings > 0 and not --auto, display plan table before asking: 2. If "By Severity": severity filter (multiselect) — CRITICAL / HIGH / MEDIUM / LOW 3. Use `markdown` preview on each option to show the findings that would be affected (full table for Fix All, filtered for By Severity, etc.) 4. If the user's response includes annotations (notes), use them to adjust behavior — e.g., "skip test coverage items" filters findings before apply +5. **Fix planning** (skills with apply phase): Before applying, group findings by file dependency and display execution plan — independent groups can be applied in parallel, dependent groups sequentially ### Needs-Approval Protocol @@ -173,7 +188,7 @@ Agent frontmatter `model: haiku` is the default. Skills override via Task tool's When any analyze agent reports a CRITICAL finding: 1. Skill isolates the CRITICAL finding(s) -2. Single Task call to cco-agent-analyze (model: opus, scopes: [original scope], mode: review) with only the file(s) containing CRITICAL findings +2. Single Task call to cco-agent-analyze (model: opus, scopes: [original scope], mode: review) with only the file(s) containing CRITICAL findings. Include "ultrathink" in the prompt to ensure high effort — default medium effort on Opus 4.6 may miss nuanced security patterns. 3. Opus confirms → keep CRITICAL. Opus rejects → downgrade to HIGH or discard. 4. Applied in all modes including --auto. CRITICAL false positives are costlier than one extra validation. 5. Max 1 escalation call per skill invocation (batch all CRITICALs into one call). @@ -184,6 +199,28 @@ Fix suggestions and applied changes must comply with: DRY (no duplicate logic), Agents verify before suggesting/applying: existing pattern exists? → reference it. New abstraction needed? → only if 3+ uses. Cross-module change? → needs_approval. +### State Management + +Skills with 3+ phases use Task tools for compaction-resilient progress tracking. No files are created. + +**Task lifecycle:** +1. TaskCreate at skill start — one task per major phase group, prefixed: `[BP]`, `[OPT]`, `[ALN]`, `[FR]`, `[RSC]`, `[DOC]` +2. TaskUpdate after each phase gate — status: in_progress → completed, description: compact findings +3. Recovery: TaskList at skill start — if own-prefix tasks exist with incomplete status, offer resume + +**Compact findings format** (stored in task description): + + ID|SEVERITY|file:line|title + +One line per finding. Apply phase reads these via TaskGet to reconstruct context. + +**Recovery protocol:** +- Own-prefix tasks found + incomplete → offer resume (--auto: resume silently, skip completed phases, re-run incomplete) +- Own-prefix tasks found + all completed → stale, start fresh +- No own-prefix tasks → proceed normally + +**Fix planning:** Before apply phase (findings > 0, not --auto, not --preview), group findings by file dependency and display execution plan with independent/dependent groups. + ### Project Types Standard project type taxonomy used across all CCO skills, agents, and scoring. Referenced as `context.projectType`. diff --git a/skills/cco-align/SKILL.md b/skills/cco-align/SKILL.md index 7f681bf..784c95c 100644 --- a/skills/cco-align/SKILL.md +++ b/skills/cco-align/SKILL.md @@ -1,7 +1,14 @@ --- description: Align codebase with ideal architecture — gap analysis and strategic fixes. Use for architecture review, structural improvements, or design pattern evaluation. argument-hint: "[--auto] [--preview] [--force-approve]" -allowed-tools: Read, Grep, Glob, Edit, Bash, Task, AskUserQuestion +allowed-tools: + - Read + - Grep + - Glob + - Edit + - Bash + - Task + - AskUserQuestion --- # /cco-align @@ -22,6 +29,20 @@ For tactical file-level fixes, use `/cco-optimize`. | `--preview` | Analyze only, show gaps and findings, don't apply | | `--force-approve` | Auto-apply needs_approval items (architectural changes). Combines with `--auto`. | +## State Management + +Per CCO Rules: State Management. This skill uses task prefix `[ALN]`. + +| Task | Created | Completed | +|------|---------|-----------| +| `[ALN] Analyze Batch 1` | Phase 2 Batch 1 launch | Batch 1 done | +| `[ALN] Analyze Batch 2` | Phase 2 Batch 2 launch | Batch 2 done | +| `[ALN] Gap+Recs` | Phase 3 start | Phase 4 end | +| `[ALN] Apply` | Phase 6 start | Phase 6 end | +| `[ALN] Summary` | Phase 7 start | Phase 7 end | + +**Recovery:** At Phase 1 start, run TaskList. If `[ALN]` tasks exist with incomplete status → per State Management recovery protocol. + ## Context - Git status: !`git status --short --branch` @@ -38,6 +59,8 @@ Setup → Analyze → Gap Analysis → Recommendations → [Plan] → Apply → **Pre-flight:** Verify git repo: `git rev-parse --git-dir 2>/dev/null` → not a repo: warn "Not a git repo — git context unavailable" and continue (git optional for align). +**Recovery check:** TaskList → filter `[ALN]` prefix. If incomplete tasks found → per State Management recovery protocol. + ```javascript AskUserQuestion([{ question: "Which areas should be reviewed?", @@ -65,12 +88,16 @@ Per CCO Rules: Parallel Execution, Agent Contract, Model Routing. Wait for ALL batches. Phase gate: do not proceed until all tracks return or fail. +**State update:** After each batch, TaskCreate + TaskUpdate `[ALN] Analyze Batch N` → completed, write findings to description in compact format. + Merge findings. Per CCO Rules: CRITICAL Escalation — if any CRITICAL findings, run single opus validation call before proceeding. **Gate:** If findings = 0 → skip Phase 5-6, display gap analysis (Phase 3-4) with: `cco-align: OK | No structural issues | Gaps: {metric table}` ### Phase 3: Gap Analysis [CURRENT vs IDEAL] +TaskCreate `[ALN] Gap+Recs` (status: in_progress). + If blueprint profile exists in CLAUDE.md: use its Ideal Metrics as targets. Otherwise: use project-type defaults per `/cco-blueprint`. Calculate gaps: current vs ideal for coupling, cohesion, complexity, coverage. Display Current vs Ideal table. @@ -106,10 +133,18 @@ Categorize by effort/impact: Quick Win → Moderate → Complex → Major. ### Phase 5: Plan Review [findings > 0, SKIP if --auto] +TaskUpdate `[ALN] Gap+Recs` → completed. + Per CCO Rules: Plan Review Protocol — display findings table (ID, severity, title, file:line), then ask with markdown previews. Options: Fix All (recommended) / By Severity / Review Each / Report Only. +Per CCO Rules: Plan Review Protocol item 5 (fix planning) — display fix execution plan before apply. + ### Phase 6: Apply [SKIP if --preview] +TaskCreate `[ALN] Apply` (status: in_progress). + +**Recovery-aware read:** If findings not in conversation context (compaction occurred), reconstruct from TaskGet on `[ALN] Analyze Batch 1/2` task descriptions. + Send to cco-agent-apply (scope: fix, findings: [...], fixAll: --auto). Count findings, not locations. On error: count as failed, continue. ### Phase 6.1: Needs-Approval Review [CONDITIONAL, SKIP if --auto, AUTO-APPLY if --force-approve] @@ -118,6 +153,8 @@ Per CCO Rules: Needs-Approval Protocol. ### Phase 7: Summary +**State cleanup:** TaskUpdate all `[ALN]` tasks → completed. TaskCreate `[ALN] Summary` with final accounting in description. + Per CCO Rules: Accounting, Auto Mode. Interactive output format: diff --git a/skills/cco-blueprint/SKILL.md b/skills/cco-blueprint/SKILL.md index 29e06f0..475e7f0 100644 --- a/skills/cco-blueprint/SKILL.md +++ b/skills/cco-blueprint/SKILL.md @@ -1,7 +1,14 @@ --- description: Project health system — profile-based assessment, transformation, and progress tracking. Use for project scoring, blueprint init, or health refresh. argument-hint: "[--auto] [--preview] [--init] [--refresh] [--scope=] [--force-approve]" -allowed-tools: Read, Grep, Glob, Edit, Bash, Task, AskUserQuestion +allowed-tools: + - Read + - Grep + - Glob + - Edit + - Bash + - Task + - AskUserQuestion disable-model-invocation: true --- @@ -20,6 +27,26 @@ disable-model-invocation: true | `--scope=X` | Specific area: stack, deps, dx, structure, code, architecture, docs, memory, all | | `--force-approve` | Auto-apply needs_approval items (architectural changes). Combines with `--auto`. | +## State Management + +Per CCO Rules: State Management. This skill uses task prefix `[BP]`. + +| Task | Created | Completed | +|------|---------|-----------| +| `[BP] Discovery+Init` | Phase 1 start | Phase 2 end | +| `[BP] Assess Batch 1` | Phase 3 Batch 1 launch | Batch 1 done | +| `[BP] Assess Batch 2` | Phase 3 Batch 2 launch | Batch 2 done | +| `[BP] Assess Batch 3` | Phase 3 Batch 3 launch | Batch 3 done | +| `[BP] Consolidate+Plan` | Phase 4 start | Phase 5 end | +| `[BP] Apply+Update` | Phase 6 start | Phase 8 end | + +**Recovery:** At Phase 1 start, run TaskList. If `[BP]` tasks exist with incomplete status: +- `--auto`: Resume silently — skip completed phases, re-run from first incomplete +- Interactive: Ask "Resume from {phase} / Start fresh" +- "Start fresh": Mark stale tasks completed, proceed normally + +**Compact findings:** After each agent batch returns, write findings to task description in compact format. Phase 4 (Consolidate) reads from TaskGet if context was compacted. + ## Context - Git status: !`git status --short --branch` @@ -102,6 +129,8 @@ Discovery → [Init Flow] → Assess [PARALLEL] → Consolidate → Plan → [Ap **Pre-flight:** Verify git repo: `git rev-parse --git-dir 2>/dev/null` → not a repo: warn "Not a git repo — git context unavailable" and continue (git optional for blueprint). +**Recovery check:** TaskList → filter `[BP]` prefix. If incomplete tasks found → per State Management recovery protocol. TaskCreate `[BP] Discovery+Init` (status: in_progress). + 1. Search CLAUDE.md for `` 2. Parallel project detection via Glob/Grep/Read: language (majority file ext), framework (express/fastapi/react/etc), project type (routes→API, pages→Web, bin→CLI, src/lib→Library), toolchain (.eslintrc, tsconfig, biome.json), CI/CD, Docker, tests, data sensitivity (password/email/token patterns), git status @@ -288,6 +317,8 @@ If project type has no UI → skip user-facing-defaults entirely. Wait for ALL batches. Phase gate: do not proceed until all 5 tracks return or fail. +**State update:** After each batch completes, TaskUpdate the corresponding `[BP] Assess Batch N` task — set status to completed, write findings to description in compact format. If a track fails, record `TRACK_FAIL|N/A|track_name|Agent returned error` in description. + Per CCO Rules: CRITICAL Escalation — if any CRITICAL findings, run single opus validation call before proceeding to Phase 3.1. ### Phase 3.1: Project Map @@ -298,6 +329,10 @@ Always displayed (including --auto). Written to profile on first run, updated on ### Phase 4: Consolidate +TaskCreate `[BP] Consolidate+Plan` (status: in_progress). + +**Recovery-aware read:** If track results are not in conversation context (compaction occurred), reconstruct from TaskGet on `[BP] Assess Batch 1/2/3` task descriptions → parse compact findings format. + Merge all track results, deduplicate by file:line. **Deduplication rules:** @@ -375,8 +410,14 @@ Display blueprint dashboard: project info, health scores table (Current/Target/G Per CCO Rules: Plan Review Protocol — display findings, ask with markdown previews. Blueprint-specific options: Fix All (recommended) / Critical+High only / Quick wins only / Report Only. +Per CCO Rules: Plan Review Protocol item 5 (fix planning) — display fix execution plan before apply. + +TaskUpdate `[BP] Consolidate+Plan` → completed. User's plan review choice stored in description. + ### Phase 6: Apply [SKIP if --preview] +TaskCreate `[BP] Apply+Update` (status: in_progress). + Send findings to cco-agent-apply (scope: fix, findings: [...], fixAll: --auto) in priority order: CRITICAL/security → Code quality → Architecture → Documentation. Per CCO Rules: on error, count as failed, continue. ### Phase 6.1: Needs-Approval Review [CONDITIONAL, SKIP if --auto, AUTO-APPLY if --force-approve] @@ -423,6 +464,8 @@ In --auto: silent cleanup. Interactive: confirm if >5 entries removed. Partial c ### Phase 8: Summary +**State cleanup:** TaskUpdate all `[BP]` tasks → completed. TaskUpdate `[BP] Apply+Update` description with final accounting. + Per CCO Rules: Accounting, Auto Mode. Before/After delta table (9 dimensions), accounting (applied/failed/needs_approval/total), next steps. diff --git a/skills/cco-commit/SKILL.md b/skills/cco-commit/SKILL.md index 19ee7ae..ec0a315 100644 --- a/skills/cco-commit/SKILL.md +++ b/skills/cco-commit/SKILL.md @@ -1,7 +1,12 @@ --- description: Smart git commits with quality gates, atomic grouping, and conventional commit format. Use when committing changes or the user asks to commit. argument-hint: "[--preview] [--single] [--staged-only]" -allowed-tools: Read, Grep, Edit, Bash, AskUserQuestion +allowed-tools: + - Read + - Grep + - Edit + - Bash + - AskUserQuestion --- # /cco-commit diff --git a/skills/cco-docs/SKILL.md b/skills/cco-docs/SKILL.md index 49bf041..20569d0 100644 --- a/skills/cco-docs/SKILL.md +++ b/skills/cco-docs/SKILL.md @@ -1,7 +1,15 @@ --- description: Documentation gap analysis — compare ideal vs current docs, generate missing content. Use when documentation needs to be created, updated, or audited. argument-hint: "[--auto] [--preview] [--scope=] [--update] [--force-approve]" -allowed-tools: Read, Grep, Glob, Edit, Write, Bash, Task, AskUserQuestion +allowed-tools: + - Read + - Grep + - Glob + - Edit + - Write + - Bash + - Task + - AskUserQuestion --- # /cco-docs @@ -22,6 +30,19 @@ Every sentence earns its place. Show > tell, examples > prose. Headers/bullets/t | `--update` | Regenerate even if docs exist | | `--force-approve` | Auto-apply needs_approval items (architectural changes). Combines with `--auto`. | +## State Management + +Per CCO Rules: State Management. This skill uses task prefix `[DOC]`. + +| Task | Created | Completed | +|------|---------|-----------| +| `[DOC] Analysis` | Phase 2 start | Phase 2 end | +| `[DOC] Gap` | Phase 3 start | Phase 3 end | +| `[DOC] Generate` | Phase 5 start | Phase 5 end | +| `[DOC] Summary` | Phase 6 start | Phase 6 end | + +**Recovery:** At Phase 1 start, run TaskList. If `[DOC]` tasks exist with incomplete status → per State Management recovery protocol. + ## Context - Git status: !`git status --short --branch` @@ -48,6 +69,8 @@ Setup → Analysis → Gap Analysis → [Plan] → Generate → Summary **Pre-flight:** Verify git repo: `git rev-parse --git-dir 2>/dev/null` → not a repo: warn "Not a git repo — git context unavailable" and continue (git optional for docs). +**Recovery check:** TaskList → filter `[DOC]` prefix. If incomplete tasks found → per State Management recovery protocol. + ```javascript AskUserQuestion([ { @@ -78,10 +101,16 @@ In --auto: generation scopes only (refine/verify require explicit `--scope=`). ### Phase 2: Analysis +TaskCreate `[DOC] Analysis` (status: in_progress). + Delegate to cco-agent-analyze (scopes: [doc-sync], mode: auto): scan existing docs, detect project type, detect documentation needs. Per CCO Rules: Agent Contract — validate agent JSON output, retry once on malformed response, on second failure continue with remaining groups, score failed dimensions as N/A. Fallback: file existence checks. +TaskUpdate `[DOC] Analysis` → completed. Write gap findings to description in compact format. + ### Phase 3: Gap Analysis [IDEAL vs CURRENT] +TaskCreate `[DOC] Gap` (status: in_progress). + Ideal docs by project type (Per CCO Rules: Project Types): | Type | README | API | Dev | User | Ops | Changelog | @@ -113,12 +142,18 @@ Display plan (target files, sections, sources). Ask: Generate All (recommended) ### Phase 5: Generate Documentation [SKIP if --preview] +TaskUpdate `[DOC] Gap` → completed. TaskCreate `[DOC] Generate` (status: in_progress). + +**Recovery-aware read:** If gap analysis results not in conversation context (compaction occurred), reconstruct from TaskGet on `[DOC] Analysis` and `[DOC] Gap` task descriptions. + Delegate to cco-agent-apply (scope: docs, operations: [{action, scope, file, sections, sources, projectType}]). Extract from actual source files. Apply: brevity, examples, scannability, actionability. Avoid: filler, "this document explains...", long paragraphs. On error: count as failed, continue. **Source mandate:** Every documented flag, endpoint, or config value MUST have Grep/Read verification before inclusion. Never document features from memory or inference. ### Phase 6: Summary +**State cleanup:** TaskUpdate all `[DOC]` tasks → completed. TaskCreate `[DOC] Summary` with final accounting in description. + Per CCO Rules: Accounting. Interactive output format: diff --git a/skills/cco-optimize/SKILL.md b/skills/cco-optimize/SKILL.md index b286d3a..e8ef9dd 100644 --- a/skills/cco-optimize/SKILL.md +++ b/skills/cco-optimize/SKILL.md @@ -1,7 +1,14 @@ --- description: Fix security, hygiene, types, performance issues in code. Use when code needs quality review, security audit, or cleanup. argument-hint: "[--auto] [--preview] [--scope=] [--force-approve]" -allowed-tools: Read, Grep, Glob, Edit, Bash, Task, AskUserQuestion +allowed-tools: + - Read + - Grep + - Glob + - Edit + - Bash + - Task + - AskUserQuestion --- # /cco-optimize @@ -24,6 +31,22 @@ For strategic architecture assessment, use `/cco-align`. | `--loop` | Re-run until clean or max 3 iterations. Combines with `--auto`. | | `--force-approve` | Auto-apply needs_approval items (architectural changes). Combines with `--auto`. | +## State Management + +Per CCO Rules: State Management. This skill uses task prefix `[OPT]`. + +| Task | Created | Completed | +|------|---------|-----------| +| `[OPT] Analyze Batch 1` | Phase 2 Batch 1 launch | Batch 1 done | +| `[OPT] Analyze Batch 2` | Phase 2 Batch 2 launch | Batch 2 done | +| `[OPT] Plan Review` | Phase 3 start | Phase 3 end | +| `[OPT] Apply` | Phase 4 start | Phase 4 end | +| `[OPT] Summary` | Phase 5 start | Phase 5 end | + +**Recovery:** At Phase 1 start, run TaskList. If `[OPT]` tasks exist with incomplete status → per State Management recovery protocol. + +**Loop mode:** Each iteration appends iteration number to task descriptions (e.g., "iter:2"). + ## Context - Git status: !`git status --short --branch` @@ -37,6 +60,8 @@ Setup → Analyze → Gate → [Plan] → Apply → Summary **Pre-flight:** Verify git repo: `git rev-parse --git-dir 2>/dev/null` → not a repo: warn "Not a git repo — git context unavailable" and continue (git optional for optimize). +**Recovery check:** TaskList → filter `[OPT]` prefix. If incomplete tasks found → per State Management recovery protocol. + ```javascript AskUserQuestion([ { @@ -76,16 +101,28 @@ Per CCO Rules: Parallel Execution, Agent Contract, Model Routing. Wait for ALL batches. Phase gate: do not proceed until all tracks return or fail. +**State update:** After each batch, TaskCreate + TaskUpdate `[OPT] Analyze Batch N` → completed, write findings to description in compact format. + Merge findings. Filter by user-selected scopes. Categorize: autoFixable vs approvalRequired. Per CCO Rules: CRITICAL Escalation — if any CRITICAL findings, run single opus validation call before proceeding. **Gate:** If findings = 0 after analysis → skip Phase 3-4, go directly to Phase 5 with: `cco-optimize: OK | No issues found | Scopes: {scoped list}` ### Phase 3: Plan Review [findings > 0, SKIP if --auto] +TaskCreate `[OPT] Plan Review` (status: in_progress). + Per CCO Rules: Plan Review Protocol — display findings table (ID, severity, title, file:line), then ask with markdown previews. Options: Fix All (recommended) / By Severity / Review Each / Report Only. +Per CCO Rules: Plan Review Protocol item 5 (fix planning) — display fix execution plan before apply. + +TaskUpdate `[OPT] Plan Review` → completed. Store user choice in description. + ### Phase 4: Apply [SYNCHRONOUS, SKIP if --preview] +TaskCreate `[OPT] Apply` (status: in_progress). + +**Recovery-aware read:** If findings not in conversation context (compaction occurred), reconstruct from TaskGet on `[OPT] Analyze Batch 1/2` task descriptions. + Send findings to cco-agent-apply (scope: fix, findings: [...], fixAll: --auto). Group by file. Count findings, not locations. On failure: retry with alternative, then count as failed. ### Phase 4.1: Needs-Approval Review [CONDITIONAL, SKIP if --auto, AUTO-APPLY if --force-approve] @@ -103,6 +140,8 @@ Max 3 iterations. Summary shows per-iteration breakdown. ### Phase 5: Summary +**State cleanup:** TaskUpdate all `[OPT]` tasks → completed. TaskCreate `[OPT] Summary` with final accounting in description. + Per CCO Rules: Accounting, Auto Mode. Interactive output format: diff --git a/skills/cco-pr/SKILL.md b/skills/cco-pr/SKILL.md index 946d0de..71623cc 100644 --- a/skills/cco-pr/SKILL.md +++ b/skills/cco-pr/SKILL.md @@ -1,7 +1,12 @@ --- description: Create pull requests with conventional commit titles for clean release-please changelogs. Use when creating a PR or preparing changes for merge. argument-hint: "[--auto] [--no-auto-merge] [--preview] [--draft]" -allowed-tools: Read, Grep, Glob, Bash, AskUserQuestion +allowed-tools: + - Read + - Grep + - Glob + - Bash + - AskUserQuestion --- # /cco-pr diff --git a/skills/cco-research/SKILL.md b/skills/cco-research/SKILL.md index fea8ee0..c4ca3bd 100644 --- a/skills/cco-research/SKILL.md +++ b/skills/cco-research/SKILL.md @@ -1,7 +1,14 @@ --- description: Multi-source research with CRAAP+ reliability scoring and tiered synthesis. Use when researching a topic, comparing technologies, or investigating solutions. argument-hint: "[--quick] [--deep]" -allowed-tools: WebSearch, WebFetch, Read, Grep, Glob, Task, AskUserQuestion +allowed-tools: + - WebSearch + - WebFetch + - Read + - Grep + - Glob + - Task + - AskUserQuestion --- # /cco-research @@ -21,6 +28,19 @@ Hybrid: Local (Glob/Grep) + Web (cco-agent-research). Without flags: ask depth question. +## State Management + +Per CCO Rules: State Management. This skill uses task prefix `[RSC]`. + +| Task | Created | Completed | +|------|---------|-----------| +| `[RSC] Research Batch N` | Phase 3 each batch launch | Each batch done | +| `[RSC] Synthesize` | Phase 4 start | Phase 4 end | + +**Recovery:** At Phase 1 start, run TaskList. If `[RSC]` tasks exist with incomplete status → per State Management recovery protocol. This provides `--deep` resumable behavior. + +**Compact sources:** After each research batch, write source summaries to task description: `TIER|SCORE|domain|title`. + **Do NOT:** Fabricate sources or URLs, present T5/T6 sources without confidence caveat, skip contradiction resolution when sources disagree, or synthesize without citing specific source tiers. ## Execution Flow @@ -73,10 +93,16 @@ Launch Task calls to cco-agent-research in batches of max 2 per message (runtime | Security (NVD/CVE/Snyk) | scope: dependency | If security query | | Comparison A/B | scope: full | If comparison detected | +**State update:** After each batch, TaskCreate + TaskUpdate `[RSC] Research Batch N` → completed, write sources to description in compact format. + **Batching order:** Group active tracks into pairs and launch sequentially. Example for Standard+ with security: Batch 1 (Local+T1) → Batch 2 (T2+T3) → Batch 3 (T4+Security) → Batch 4 (Comparison if needed). Apply saturation gate after each batch. ### Phase 4: Synthesize +TaskCreate `[RSC] Synthesize` (status: in_progress). + +**Recovery-aware read:** If research results not in conversation context (compaction occurred), reconstruct from TaskGet on `[RSC] Research Batch N` task descriptions. + Validate agent outputs. Malformed → retry once, exclude on second failure. T1-T2 sources → cco-agent-research (scope: synthesize) for conflict resolution. T3+ → aggregate locally. @@ -85,6 +111,8 @@ T1-T2 sources → cco-agent-research (scope: synthesize) for conflict resolution ### Phase 5: Output +**State cleanup:** TaskUpdate all `[RSC]` tasks → completed. + Executive summary, evidence hierarchy (primary T1-T2, supporting T3-T4), contradictions resolved, knowledge gaps, recommendation (DO/DON'T/CONSIDER), sources with tier/score. ## Source Tiers diff --git a/skills/cco-update/SKILL.md b/skills/cco-update/SKILL.md index 8d86835..2990c5f 100644 --- a/skills/cco-update/SKILL.md +++ b/skills/cco-update/SKILL.md @@ -1,7 +1,12 @@ --- description: Check for updates and upgrade CCO to the latest version. Use when checking for CCO updates or upgrading. argument-hint: "[--auto] [--check]" -allowed-tools: WebFetch, Read, Edit, Bash, AskUserQuestion +allowed-tools: + - WebFetch + - Read + - Edit + - Bash + - AskUserQuestion disable-model-invocation: true --- @@ -69,3 +74,20 @@ Read the **installed** `~/.claude/rules/cco-rules.md` from disk → confirm `cco | Interactive | Version info, restart reminder | **Restart reminder:** "Restart Claude Code session to load updated rules." + +## Auto-Check via Hook (Optional) + +Users can configure an `InstructionsLoaded` hook to auto-trigger update checks on session start. Add to Claude Code settings (`~/.claude/settings.json`): + +```json +{ + "hooks": { + "InstructionsLoaded": [{ + "command": "echo 'Run /cco-update --check to check for updates'", + "once": true + }] + } +} +``` + +This fires once per session when CCO rules are loaded. The `once: true` flag prevents repeated triggers.