cc-codeconductor 0.4.3 → 0.5.0

package/presets/cursor/commands/cc/openspec.md

@@ -0,0 +1,144 @@
+---
+description: >-
+  [cc: alias] Run OpenSpec backlog delivery — validate BACKLOG.md, plan TaskCards,
+  orchestrate agents by phase, review gate, and update backlog state.
+---
+
+# OpenSpec Backlog Workflow
+
+Scope: $ARGUMENTS
+
+Orchestrate FIFO delivery from `BACKLOG.md`. CodeConductor owns planning; agents execute one TaskCard per phase with the installed preset model for each role.
+
+---
+
+## Step 0 — Validate (mandatory gate)
+
+Run:
+
+```bash
+npx cc-codeconductor openspec validate
+```
+
+If validation fails:
+
+1. List all errors and recommendations from the CLI output.
+2. Show the canonical BACKLOG.md structure (## Global, ## Items, ### BC-001 | Title, Priority, Status, Type, Depends on, Description, Scope, Acceptance).
+3. **STOP.** Do not scan, plan, or execute until the user fixes BACKLOG.md.
+
+---
+
+## Step 1 — Scan
+
+Run:
+
+```bash
+npx cc-codeconductor openspec scan
+```
+
+Report: new items, modified items, closed/archived items, and whether the file changed.
+
+---
+
+## Step 2 — Select item
+
+If `$ARGUMENTS` contains a `BC-xxx` ID, use that item. Otherwise run:
+
+```bash
+npx cc-codeconductor openspec status
+```
+
+Pick the next `READY` item with satisfied dependencies (FIFO by priority). Skip items in `DONE` or `Archive`.
+
+**STOP if no eligible item.** Report backlog status and wait for the user.
+
+---
+
+## Step 3 — Plan
+
+Run:
+
+```bash
+npx cc-codeconductor openspec plan <BC-id>
+```
+
+Show:
+
+- Generated TaskCards (discover → design → test → implement → review when TDD required)
+- Path to `openspec/changes/<slug>/` (proposal, design, tasks, specs)
+
+Update BACKLOG item status to `PLANNED` (CLI does this automatically).
+
+---
+
+## Step 4 — Model matrix and execute loop
+
+Before executing phases, show resolved models:
+
+```bash
+npx cc-codeconductor scorecard models
+```
+
+For each pending TaskCard, run:
+
+```bash
+npx cc-codeconductor openspec next
+```
+
+Invoke the agent named on the card with **isolated** context (`/clear` between phases unless continuation is required):
+
+| Phase | Agent | Role |
+|-------|-------|------|
+| discover | repo-explorer | Map repo and impact |
+| design | architect | Technical plan |
+| test | tester | TDD tests (before implement if TDD required) |
+| implement | implementer | Minimal diff in worktree |
+| review | reviewer | Acceptance + scope gate |
+
+Use the model configured in the installed preset for each agent role.
+
+After each phase:
+
+- Mark progress in deliverable summary.
+- Set TaskCard status to `done` in `.codeconductor/openspec-state.json` when phase completes.
+
+Implementer: create a Git worktree before editing (`git worktree add ../<branch>-session <branch>`).
+
+---
+
+## Step 5 — Review gate
+
+Run regression when BACKLOG Global `Review required: yes`:
+
+```bash
+npx cc-codeconductor scorecard regression
+```
+
+The `reviewer` agent must verify:
+
+- All acceptance criteria from BACKLOG.md
+- Tests pass
+- Scope matches the backlog item
+- No architectural violations
+
+If **rejected**: set item status `IN_PROGRESS`, record findings in state, **STOP** and report to user.
+
+If **approved**: proceed to Step 6.
+
+---
+
+## Step 6 — Scorecard and update backlog
+
+1. `npx cc-codeconductor scorecard create --task <BC-id> --from-diff`
+2. Complete criteria; `scorecard record` with verdict and optional cost/tokens
+3. Set item `Progress: 100%`, `Status: DONE` if PASS
+4. Move item to `## Archive` in BACKLOG.md if DONE
+5. Run `npx cc-codeconductor openspec scan`
+
+Report completion: Task Cards executed, scorecard verdict, change folder path, files changed.
+
+---
+
+## Skill
+
+Apply `.claude/skills/openspec/SKILL.md` for backlog format rules and state transitions.

package/presets/cursor/commands/cc/pagespeed.md

@@ -0,0 +1,103 @@
+# PageSpeed Performance Audit
+
+Audit web performance using the PageSpeed Insights API. Applies the 80/20
+principle: identify the 20% of changes that produce 80% of the performance gain.
+Produces a prioritized report in the current working directory.
+
+## Usage
+
+```
+/cc-pagespeed --url <url> [--strategy mobile|desktop|both]
+```
+
+## Parameters
+
+| Parameter     | Required | Description                                                    |
+| ------------- | -------- | -------------------------------------------------------------- |
+| `--url`       | Yes      | Full URL to audit (must include scheme: https://...)           |
+| `--strategy`  | No       | Analysis strategy: `mobile`, `desktop`, or `both` (default: `both`) |
+
+## Requirements
+
+### `PAGESPEED_API_KEY` — Optional but strongly recommended
+
+| Mode         | Lab data | CrUX field data | Rate limits      |
+| ------------ | -------- | --------------- | ---------------- |
+| **With key** | ✅        | ✅ (real users)  | 25,000 req/day   |
+| **Without**  | ✅        | ❌               | ~2 req/s shared  |
+
+Without the key, Core Web Vitals field data (real user experience via CrUX) is
+unavailable. Lab data from Lighthouse still runs.
+
+Set the key before invoking the command:
+
+```powershell
+# Windows PowerShell
+$env:PAGESPEED_API_KEY = "your-api-key"
+
+# macOS / Linux
+export PAGESPEED_API_KEY="your-api-key"
+```
+
+Get a free key (Google account required):
+<https://developers.google.com/speed/docs/insights/v5/get-started>
+
+## Workflow
+
+When `/cc-pagespeed` is invoked, load the `pagespeed-perf` skill and execute
+the following steps in order:
+
+1. **Pre-flight** — Read `$env:PAGESPEED_API_KEY` from the environment. Compute
+   the output filename: `{YYYY-MM-DD}_pagespeed-{hostname}-claude.md`.
+
+2. **Collect** — Call the PageSpeed Insights API for the requested strategy
+   (`mobile`, `desktop`, or `both`). Prefer the Bun scripts in
+   `~/.claude/skills/pagespeed-perf/scripts/run.ts` if Bun is available.
+   Otherwise, use `WebFetch` to call the PSI endpoint directly.
+
+3. **Analyze** — Extract Core Web Vitals (LCP, INP, CLS, FCP, TTFB, TBT),
+   identify the LCP element, enumerate third-party scripts by blocking time,
+   and inspect resource hints in the HTML `<head>`.
+
+4. **Prioritize** — Score each identified optimization using the 80/20 matrix:
+   `Impact × Ease` (each 1–5). Order findings by descending score. Highlight
+   the top actions with Score ≥ 20 as the critical 20%.
+
+5. **Report** — Write the structured markdown report to
+   `{YYYY-MM-DD}_pagespeed-{hostname}-claude.md` in the current directory.
+
+## Output File
+
+The report is saved as `{YYYY-MM-DD}_pagespeed-{hostname}-claude.md`.
+
+- Hostname characters outside `[a-zA-Z0-9]` are replaced with `-`.
+- Example: `https://www.example.com` → `2026-06-07_pagespeed-www-example-com-claude.md`
+
+## Skills Loaded
+
+- `pagespeed-perf` — Web Performance Engineering: PSI API, Core Web Vitals
+  thresholds, 80/20 optimization matrix, resource-hint analysis, third-party
+  script auditing, framework-specific implementation templates.
+
+## Examples
+
+```bash
+# Full audit — mobile + desktop
+/cc-pagespeed --url https://www.example.com
+
+# Mobile only
+/cc-pagespeed --url https://www.example.com --strategy mobile
+
+# Desktop only
+/cc-pagespeed --url https://www.example.com --strategy desktop
+```
+
+## Hard Rules
+
+- **GET only.** Never send POST, PUT, or DELETE to the target URL.
+- **No auth.** Never include cookies, tokens, or auth headers.
+- **No external crawling.** Audit only the provided URL.
+- **Quantify every finding.** Never write "it would improve LCP". Always cite
+  the observed value and estimated gain (e.g., "reduces LCP from 4.2 s to ~3.0 s").
+- **No generic recommendations.** Every finding must be backed by data from
+  the audit of this specific URL.

package/presets/cursor/commands/cc/refactor.md

@@ -0,0 +1,148 @@
+---
+description: >-
+  [cc: alias] Run the refactor workflow — mandatory architectural justification,
+  test verification, risk-based implementation, and scope enforcement.
+---
+
+# Refactor Workflow
+
+Refactor description: $ARGUMENTS
+
+Describe what you want to refactor and why. Include:
+
+- The current structure or pattern being changed
+- The target structure or pattern
+- The motivation (performance, readability, architectural alignment, etc.)
+- Known risk areas or dependencies
+
+---
+
+## Prerequisite — Test coverage check
+
+Before any role is adopted, verify that the code being refactored has adequate
+test coverage.
+
+A refactor without tests is not a refactor — it is a rewrite with unknown
+behavioral consequences.
+
+If coverage is insufficient:
+
+1. **STOP**. Report the coverage gap.
+2. Suggest running `/test-plan` first to establish coverage.
+3. Do not proceed with the refactor until coverage is confirmed.
+
+---
+
+## Step 1 — Architectural justification (Architect role)
+
+Invoke the `architect` subagent via the Task tool. Always invoke this step
+first, regardless of risk level. A refactor without a written justification is
+scope creep in disguise.
+
+Produce a Refactor Plan that includes:
+
+- Statement of the problem with the current structure
+- Proposed target structure and rationale
+- Affected files and module boundaries
+- Risk level: `low`, `medium`, or `high`
+- Behavioral invariants that must not change
+- Open questions requiring human input
+
+**Scope creep warning:** If during planning you identify unrelated improvements,
+list them separately as "Out of scope." They are not part of this refactor.
+
+**STOP here. Show the Refactor Plan and wait for explicit human approval. Do not
+proceed without written approval of the plan.**
+
+---
+
+## Step 2 — Route by risk
+
+Read the risk field from the Refactor Plan and follow the corresponding route.
+
+### Low-risk route
+
+Applies when: the refactor is purely internal, no public interfaces change, full
+test coverage exists for the affected code, and behavioral impact is isolated to
+the refactored module.
+
+Route: Architect (done) → Implementer
+
+Proceed to Step 3a.
+
+### Medium or high-risk route
+
+Applies when: module boundaries change, shared interfaces are affected,
+performance characteristics may change, or the refactor touches more than two
+files with behavioral impact.
+
+Route: Architect (done) → Implementer → Reviewer
+
+Proceed to Step 3b.
+
+---
+
+## Step 3a — Implementation, low-risk (Implementer role)
+
+Invoke the `implementer` subagent via the Task tool. Use the approved
+Refactor Plan.
+Implementer creates a Git Worktree before touching any file; all edits happen inside it.
+
+1. Read the Refactor Plan before opening any file.
+2. Apply only the changes specified in the plan.
+3. Run the full test suite before and after — both runs must pass.
+4. Produce an Implementation Summary: what changed, what did not change, test
+   results before and after.
+
+Any deviation from the plan — including "obvious improvements" encountered
+during implementation — must be flagged and held for a separate task.
+
+---
+
+## Step 3b — Implementation, medium/high-risk (Implementer role)
+
+Same rules as Step 3a. Additionally:
+
+- Document any unexpected complexity discovered during implementation.
+- Pause and report if complexity changes the risk assessment.
+- If new risks are found, **STOP** and report before continuing.
+
+---
+
+## Step 4 — Test suite verification
+
+For all risk levels, confirm:
+
+- All tests that existed before the refactor still pass.
+- No test was deleted or commented out to make the suite pass.
+- Behavior documented in the Task Card remains unchanged.
+
+If any test fails that was passing before, the refactor has introduced a
+regression. **STOP and report.**
+
+---
+
+## Step 5 — Code review (Reviewer role) — medium/high-risk only
+
+Invoke the `reviewer` subagent via the Task tool. Use the diff and Refactor
+Plan.
+
+Verify:
+
+- The implementation matches the approved plan.
+- No behavior was changed beyond the plan's scope.
+- No unrelated files were modified.
+
+Review Report must include CRITICAL / WARNING / SUGGESTION findings. CRITICAL
+findings block completion.
+
+---
+
+## Completion
+
+Report: Refactor Plan (approved), Implementation Summary, test results before
+and after, Review Report (if applicable).
+
+The refactor is complete only when: all pre-existing tests still pass, the
+implementation matches the approved plan exactly, and no CRITICAL review
+findings remain.

package/presets/cursor/commands/cc/review.md

@@ -0,0 +1,137 @@
+---
+description: >-
+  [cc: alias] Run a structured code review — produces a Review Report with
+  CRITICAL, WARNING, and SUGGESTION findings; CRITICAL findings block merge.
+---
+
+# Code Review Workflow
+
+Review target: $ARGUMENTS
+
+Specify what to review. Accepted formats:
+
+- A branch name: `feature/my-branch`
+- A file or set of files: `src/api/UserController.kt`
+- A pull request reference: `PR #42`
+- Empty — defaults to the current working diff (`git diff`)
+
+---
+
+## Step 1 — Diff collection
+
+Before adopting the Reviewer role, collect the diff for the specified target.
+
+If $ARGUMENTS is empty or not provided:
+
+- Use `git diff HEAD` as the review target.
+
+If $ARGUMENTS is a branch name:
+
+- Use `git diff main...$ARGUMENTS` (or `develop` if main is not the base).
+
+If $ARGUMENTS is a PR reference:
+
+- Retrieve the PR diff and the PR description for context.
+
+If $ARGUMENTS is a file path:
+
+- Use `git diff HEAD -- $ARGUMENTS`.
+
+Show the diff summary (files changed, lines added/removed) before proceeding.
+
+---
+
+## Step 2 — Code review (Reviewer role)
+
+Invoke the `reviewer` subagent via the Task tool.
+
+Evaluate the diff against the following checklist:
+
+**Correctness**
+
+- Does the implementation match the stated intent?
+- Are there logic errors, off-by-one errors, or unhandled edge cases?
+
+**Architecture alignment**
+
+- Does the change follow existing module boundaries?
+- Does it introduce unplanned coupling or layering violations?
+
+**Security**
+
+- Are inputs validated before use?
+- Is there any credential, token, or secret in the diff?
+- Are there SQL injection, XSS, or injection risks?
+
+**Performance**
+
+- Does the change introduce N+1 queries, blocking I/O, or O(n²) loops?
+
+**Test coverage**
+
+- Do tests exist for the new or changed behavior?
+- Are assertions meaningful (not just checking that no exception is thrown)?
+
+**Documentation**
+
+- Are public interfaces documented?
+- Is CHANGELOG updated if behavior changed?
+
+---
+
+## Step 3 — Review Report
+
+Produce a structured Review Report with findings in three categories:
+
+```markdown
+## Review Report
+
+### CRITICAL
+[Findings that must be fixed before merge — file:line, description, suggested resolution]
+
+### WARNING
+[Findings that should be resolved before merge — same format as CRITICAL]
+
+### SUGGESTION
+[Optional improvements — style, readability, future-proofing. These do not block merge.]
+
+### Summary
+- Files reviewed: N
+- Total findings: N (X critical, Y warnings, Z suggestions)
+- Merge recommendation: APPROVED | BLOCKED
+```
+
+---
+
+## Step 4 — Merge decision
+
+If any CRITICAL findings exist:
+
+- The Review Report status is **BLOCKED**.
+- Report all CRITICAL findings.
+- Do not proceed until each CRITICAL finding is resolved.
+- After resolution, run `/review` again on the same target.
+
+If no CRITICAL findings exist:
+
+- The Review Report status is **APPROVED**.
+- Report any WARNINGs and SUGGESTIONs for human awareness.
+- The human makes the final merge decision.
+
+---
+
+## Completion
+
+Deliver the complete Review Report. Never summarize or omit findings.
+
+---
+
+## Step 5 — Scorecard and outcome
+
+```bash
+npx cc-codeconductor scorecard create --from-diff --agent reviewer
+npx cc-codeconductor scorecard record --verdict PASS|REVISE|REJECT --score <weighted>
+npx cc-codeconductor scorecard regression
+```
+
+Map merge recommendation to scorecard verdict. Record outcome for trend tracking.

package/presets/cursor/commands/cc/scorecard.md

@@ -0,0 +1,65 @@
+---
+description: >-
+  [cc: alias] Evaluate deliverable quality — scorecard, outcome tracking, regression
+  checklist, and aggregate stats.
+---
+
+# Scorecard Evaluation Workflow
+
+Scope: $ARGUMENTS
+
+---
+
+## Step 1 — Identify task
+
+Use `$ARGUMENTS` as task id (e.g. `BC-001`) or read active item from `npx cc-codeconductor openspec status`.
+
+---
+
+## Step 2 — Create scorecard with auto-signals
+
+```bash
+npx cc-codeconductor scorecard create --task <id> --agent reviewer --from-diff
+```
+
+Review auto-suggested criteria (minimal diff, cc-gain). Complete remaining scores 0–3 per [`docs/agent-scorecard.md`](docs/agent-scorecard.md).
+
+---
+
+## Step 3 — Regression (optional)
+
+```bash
+npx cc-codeconductor scorecard regression
+```
+
+If required checks fail, **STOP** and report failures.
+
+---
+
+## Step 4 — Record outcome
+
+```bash
+npx cc-codeconductor scorecard record --task <id> --agent reviewer --model <model> --verdict PASS --score 2.5
+```
+
+Include `--cost` and `--tokens` when available from session metrics.
+
+---
+
+## Step 5 — Aggregate
+
+```bash
+npx cc-codeconductor scorecard aggregate
+```
+
+Report pass rate and average weighted score.
+
+---
+
+## Routing on verdict
+
+- **PASS** — accept deliverable; update backlog if applicable
+- **REVISE** — return to implementer/tester with findings
+- **REJECT** — route to task-coach for re-scoping
+
+Apply skill `evaluation`.