cc-codeconductor 0.2.9 → 0.3.0

package/presets/agy/workflows/cc-fix.md

@@ -0,0 +1,124 @@
+---
+name: cc-fix
+description:
+  Run the bug fix workflow — risk-based routing through task validation,
+  implementation, testing, and optional review.
+---
+
+# Bug Fix Workflow
+
+Bug description: $ARGUMENTS
+
+Provide the following information in $ARGUMENTS:
+
+- What is the incorrect behavior (actual)
+- What is the expected behavior
+- Steps to reproduce
+- Environment or version where the bug occurs (if known)
+- Any relevant error messages or stack traces
+
+---
+
+## Step 1 — Task Card validation (task-coach)
+
+Invoke `task-coach` with the bug description above.
+
+task-coach must produce a Task Card that includes:
+
+- A clear statement of actual vs. expected behavior
+- Reproduction steps (or a note that they are unknown)
+- Risk classification: `low`, `medium`, or `high`
+- Scope: which files or modules are likely affected
+
+If reproduction steps are missing, task-coach must ask for them before
+classifying risk. A bug without a reproduction path cannot be classified
+reliably.
+
+**STOP here. Show the Task Card and wait for human confirmation.**
+
+---
+
+## Step 2 — Route by risk
+
+Read the risk field from the Task Card and follow the corresponding route.
+
+### Low-risk route
+
+Applies when: the bug is isolated to a single component, existing tests cover
+the affected code, and no public API or shared state is involved.
+
+Route: `task-coach` → `implementer` → `tester`
+
+Proceed directly to Step 3a.
+
+### Medium or high-risk route
+
+Applies when: the bug touches shared state, a public API, auth or payment paths,
+database writes, or the root cause is not yet understood.
+
+Route: `task-coach` → `architect` → `implementer` → `tester` → `reviewer`
+
+Invoke `architect` before implementation. architect must:
+
+- Identify the root cause (or document that it is unknown)
+- Define the fix approach and affected files
+- Flag any regression risk to adjacent components
+- Produce a Technical Plan
+
+**STOP here if high-risk. Show the Technical Plan and wait for human approval
+before continuing.**
+
+---
+
+## Step 3a — Implementation, low-risk (implementer)
+
+Invoke `implementer` with the Task Card.
+Implementer creates a Git Worktree before touching any file; all edits happen inside it.
+
+implementer must:
+
+1. Locate the defect using the reproduction steps
+2. Apply the minimal fix — no unrelated changes
+3. Run the test suite
+4. Produce an Implementation Summary: root cause, fix applied, files changed
+
+---
+
+## Step 3b — Implementation, medium/high-risk (implementer)
+
+Invoke `implementer` with the approved Technical Plan and the Task Card.
+Implementer creates a Git Worktree before touching any file; all edits happen inside it.
+
+implementer must follow the plan exactly. Any deviation requires a new Technical
+Plan approval. After implementation, run the full test suite.
+
+---
+
+## Step 4 — Regression tests (tester)
+
+Invoke `tester` for all risk levels.
+
+tester must:
+
+1. Write a regression test that reproduces the original bug (fails before the
+   fix, passes after)
+2. Verify that existing tests still pass
+3. Produce a Coverage Summary: test added, case covered
+
+---
+
+## Step 5 — Review (reviewer) — medium/high-risk only
+
+Invoke `reviewer` with the diff and Task Card.
+
+reviewer produces a Review Report with CRITICAL / WARNING / SUGGESTION findings.
+If any CRITICAL findings exist, **STOP**. Do not close the fix until they are
+resolved.
+
+---
+
+## Completion
+
+Report: Task Card, Implementation Summary, regression test added, Review Report
+(if applicable). The fix is complete only when: the regression test passes, the
+full suite passes, and no CRITICAL review findings remain.

package/presets/agy/workflows/cc-pagespeed.md

@@ -0,0 +1,101 @@
+---
+name: cc-pagespeed
+description: >-
+  Run the PageSpeed performance audit — 80/20 analysis of Core Web Vitals using
+  the PageSpeed Insights API.
+---
+
+# PageSpeed Performance Audit
+
+Audit URL: $ARGUMENTS
+
+---
+
+## Step 1 — Pre-flight (pagespeed-perf skill)
+
+Invoke `pagespeed-perf` skill.
+
+Read `PAGESPEED_API_KEY` from the environment. Compute the output filename:
+`{YYYY-MM-DD}_pagespeed-{hostname}-claude.md`.
+
+Log whether the API key was found. Proceed regardless — lab data is available
+without a key, but CrUX field data requires it.
+
+---
+
+## Step 2 — Collect
+
+Call the PageSpeed Insights API for the URL provided above.
+
+- Strategy: `both` (mobile + desktop) unless the user specified otherwise.
+- If Bun is available, use `~/.claude/skills/pagespeed-perf/scripts/run.ts`.
+- If Bun is unavailable, call PSI directly via WebFetch and fetch the HTML
+  source for manual resource-hint analysis.
+
+---
+
+## Step 3 — Analyze
+
+Extract from the PSI response:
+
+- Core Web Vitals: LCP, INP, CLS, FCP, TBT, TTFB
+- LCP element (type, selector, HTML snippet)
+- Third-party scripts ordered by blocking time
+- Render-blocking resources
+- Unused JavaScript and CSS (savings in bytes and ms)
+
+From the HTML source:
+
+- Resource hints (`<link rel="preload|preconnect|prefetch">`)
+- Images: lazy loading, `fetchpriority`, format, dimensions
+- Fonts: `font-display`, preloaded subsets
+- Blocking scripts in `<head>` (no `async`/`defer`)
+
+---
+
+## Step 4 — Prioritize
+
+Score each identified optimization using the 80/20 matrix:
+`Score = Impact × Ease` (each 1–5, max 25).
+
+Order findings by descending score. Mark optimizations with Score ≥ 20 as
+**Critical 20%**.
+
+---
+
+## Step 5 — Report
+
+Write the full performance report to
+`{YYYY-MM-DD}_pagespeed-{hostname}-claude.md` in the current directory.
+
+Required sections:
+1. Resumen Ejecutivo (2–3 paragraphs)
+2. Métricas Actuales (lab vs field table)
+3. Recursos con Mayor Impacto
+4. Plan de Acción Priorizado (80/20 table)
+5. Solución Técnica Detallada (per finding: problem, evidence, code, expected gain)
+6. Quick Wins / High Impact Changes / Roadmap
+
+End every report with:
+```
+---
+*Informe generado el {YYYY-MM-DD} · Herramienta: Claude Code + pagespeed-perf skill*
+*API Key usada: {Sí / No} · Datos CrUX: {Disponibles / No disponibles}*
+```
+
+---
+
+## Requirements
+
+**`PAGESPEED_API_KEY`** — Optional but strongly recommended.
+
+- With key: real CrUX field data + 25,000 requests/day quota.
+- Without key: lab data only (Lighthouse); shared rate limit applies.
+
+Set in your shell:
+```powershell
+$env:PAGESPEED_API_KEY = "your-api-key"   # Windows PowerShell
+export PAGESPEED_API_KEY="your-api-key"    # macOS / Linux
+```
+
+Get a free key: <https://developers.google.com/speed/docs/insights/v5/get-started>

package/presets/agy/workflows/cc-refactor.md

@@ -0,0 +1,149 @@
+---
+name: cc-refactor
+description:
+  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 agent is invoked, 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 to the human.
+2. Suggest invoking `/cc:test-plan` first to establish coverage.
+3. Do not proceed with the refactor until coverage is confirmed.
+
+---
+
+## Step 1 — Architectural justification (architect)
+
+Always invoke `architect` first, regardless of risk level. A refactor without a
+written justification is scope creep in disguise.
+
+architect must 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 architect identifies unrelated
+improvements, they must be listed 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)
+
+Invoke `implementer` with the approved Refactor Plan.
+Implementer creates a Git Worktree before touching any file; all edits happen inside it.
+
+implementer must:
+
+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)
+
+Same rules as 3a. Additionally:
+
+- implementer must document any unexpected complexity discovered during
+  implementation and pause if the complexity changes the risk assessment
+- If new risks are found, **STOP** and report to the human 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) — medium/high-risk only
+
+Invoke `reviewer` with the diff and Refactor Plan.
+
+reviewer must 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/agy/workflows/cc-review.md

@@ -0,0 +1,142 @@
+---
+name: cc-review
+description:
+  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 invoking `reviewer`, 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 invoking
+reviewer.
+
+---
+
+## Step 2 — Code review (reviewer)
+
+Invoke `reviewer` with:
+
+- The full diff
+- The Task Card or PR description (if available)
+- The target specification from $ARGUMENTS
+
+reviewer must 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^2) 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
+
+reviewer produces a structured Review Report with findings in three categories:
+
+```markdown
+## Review Report
+
+### CRITICAL
+
+[Findings that must be fixed before merge. Each finding includes:
+
+- Location (file:line)
+- Description of the problem
+- Suggested resolution]
+
+### WARNING
+
+[Findings that should be resolved before merge but are not blockers in
+exceptional cases with human approval. 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 to the human
+- Do not proceed until each CRITICAL finding is resolved
+- After resolution, invoke `/cc: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. Every
+finding must include a location and an actionable description.