diff --git a/README.md b/README.md index 12f511d..5d331e8 100644 --- a/README.md +++ b/README.md @@ -111,6 +111,7 @@ claude plugin install qute-essentials@qute-marketplace | python-patterns | model-invocable | | image-generator | `/image-generator` | | llm-external-review | `/llm-external-review` | +| architecture-diagram | model-invocable | | code-quality | `/code-quality [path] [--quick\|--deep]` | ### Web Development (webdev bundle) @@ -118,6 +119,7 @@ claude plugin install qute-essentials@qute-marketplace | Skill | Invocation | |-------|------------| | ui-ux-pro-max | `/ui-ux-pro-max` | +| architecture-diagram | model-invocable | | code-quality | `/code-quality [path] [--quick\|--deep]` | ### Output @@ -126,6 +128,7 @@ claude plugin install qute-essentials@qute-marketplace |-------|------------| | gist-report | `/gist-report` (includes transcript upload) | | excalidraw | `/excalidraw` | +| architecture-diagram | model-invocable (dark-themed HTML + SVG architecture diagrams; quant + webdev) | ### Meta / Toolkit @@ -181,6 +184,7 @@ claude plugin install qute-essentials@qute-marketplace |------|----------|---------| | [workflow-qute](docs/playbooks/workflow-qute.md) | `docs/playbooks/` | Full dev session lifecycle with qute-essentials | | [workflow-gstack](docs/playbooks/workflow-gstack.md) | `docs/playbooks/` | Release workflow using gstack `/ship` | +| [impeccable-workflow](docs/playbooks/impeccable-workflow.md) | `docs/playbooks/` | Design polish + anti-pattern detection via Impeccable v2.1 | | [Playbooks](docs/playbooks/) | `docs/playbooks/` | All step-by-step workflows | | [Cheatsheets](docs/cheatsheets/) | `docs/cheatsheets/` | Quick reference lookups | | [Prompts](docs/prompts/) | `docs/prompts/` | Copy-paste into Claude | @@ -206,6 +210,28 @@ claude plugin install gstack@claude-plugins-official # or clone to ~/.claude/sk See `docs/playbooks/workflow-gstack.md` for the ship workflow. +**[Impeccable](https://impeccable.style/)** (v2.1, Apache 2.0) — design skill set for AI harnesses. 18 slash commands teach Claude a concrete design vocabulary; a 25-rule deterministic detection engine catches the usual AI-generated tells (gradient text, Inter everywhere, low-contrast, nested cards). Run `/impeccable teach` once per project to pin brand/fonts/palette in `.impeccable.md`. + +Key Impeccable commands: + +| Command | Purpose | +|---------|---------| +| `/polish` | Default "make this better" pass — typography, spacing, color, hierarchy | +| `/audit` | Run the 25-rule detection engine and report findings with fixes | +| `/typeset` | Pure typography pass — type scale, line-height, font pairings | +| `/layout` | Restructure page or component layout | +| `/harden` | Accessibility + robustness (contrast, focus states, keyboard) | +| `/overdrive` | Aggressive redesign when `/polish` is too timid | + +```bash +# Install (pick one) +/plugin marketplace add pbakaus/impeccable # in Claude Code +npx skills add pbakaus/impeccable # auto-detects harness +npm i -g impeccable # CI / pre-commit scanner only +``` + +See `docs/playbooks/impeccable-workflow.md` for install, setup, and flows. + ## Kit Management ```bash diff --git a/claude/bundles/quant.txt b/claude/bundles/quant.txt index 8aa2031..b73ed8a 100644 --- a/claude/bundles/quant.txt +++ b/claude/bundles/quant.txt @@ -26,6 +26,7 @@ llm-external-review analizy-pl-data gist-report image-generator +architecture-diagram code-quality # MCP Servers diff --git a/claude/bundles/webdev.txt b/claude/bundles/webdev.txt index 7e4ad73..1284669 100644 --- a/claude/bundles/webdev.txt +++ b/claude/bundles/webdev.txt @@ -13,6 +13,7 @@ pyproject/webdev-uv.toml # Skills gist-report ui-ux-pro-max +architecture-diagram code-quality # MCP Servers diff --git a/claude/skills/architecture-diagram/SKILL.md b/claude/skills/architecture-diagram/SKILL.md new file mode 100644 index 0000000..b6e5aac --- /dev/null +++ b/claude/skills/architecture-diagram/SKILL.md @@ -0,0 +1,163 @@ +--- +name: architecture-diagram +description: Create professional, dark-themed architecture diagrams as standalone HTML files with SVG graphics. Use when the user asks for system architecture diagrams, infrastructure diagrams, cloud architecture visualizations, security diagrams, network topology diagrams, or any technical diagram showing system components and their relationships. +license: MIT +metadata: + version: "1.0" + author: Cocoon AI (hello@cocoon-ai.com) +--- + +# Architecture Diagram Skill + +Create professional technical architecture diagrams as self-contained HTML files with inline SVG graphics and CSS styling. + +## Design System + +### Color Palette + +Use these semantic colors for component types: + +| Component Type | Fill (rgba) | Stroke | +|---------------|-------------|--------| +| Frontend | `rgba(8, 51, 68, 0.4)` | `#22d3ee` (cyan-400) | +| Backend | `rgba(6, 78, 59, 0.4)` | `#34d399` (emerald-400) | +| Database | `rgba(76, 29, 149, 0.4)` | `#a78bfa` (violet-400) | +| AWS/Cloud | `rgba(120, 53, 15, 0.3)` | `#fbbf24` (amber-400) | +| Security | `rgba(136, 19, 55, 0.4)` | `#fb7185` (rose-400) | +| Message Bus | `rgba(251, 146, 60, 0.3)` | `#fb923c` (orange-400) | +| External/Generic | `rgba(30, 41, 59, 0.5)` | `#94a3b8` (slate-400) | + +### Typography + +Use JetBrains Mono for all text (monospace, technical aesthetic): +```html + +``` + +Font sizes: 12px for component names, 9px for sublabels, 8px for annotations, 7px for tiny labels. + +### Visual Elements + +**Background:** `#020617` (slate-950) with subtle grid pattern: +```svg + + + +``` + +**Component boxes:** Rounded rectangles (`rx="6"`) with 1.5px stroke, semi-transparent fills. + +**Security groups:** Dashed stroke (`stroke-dasharray="4,4"`), transparent fill, rose color. + +**Region boundaries:** Larger dashed stroke (`stroke-dasharray="8,4"`), amber color, `rx="12"`. + +**Arrows:** Use SVG marker for arrowheads: +```svg + + + +``` + +**Arrow z-order:** Draw connection arrows early in the SVG (after the background grid) so they render behind component boxes. SVG elements are painted in document order, so arrows drawn first will appear behind shapes drawn later. + +**Masking arrows behind transparent fills:** Since component boxes use semi-transparent fills (`rgba(..., 0.4)`), arrows behind them will show through. To fully mask arrows, draw an opaque background rect (e.g., `fill="#0f172a"`) at the same position before drawing the semi-transparent styled rect on top: +```svg + + + + +``` + +**Auth/security flows:** Dashed lines in rose color (`#fb7185`). + +**Message buses / Event buses:** Small connector elements between services. Use orange color (`#fb923c` stroke, `rgba(251, 146, 60, 0.3)` fill): +```svg + +Kafka / RabbitMQ +``` + +### Spacing Rules + +**CRITICAL:** When stacking components vertically, ensure proper spacing to avoid overlaps: + +- **Standard component height:** 60px for services, 80-120px for larger components +- **Minimum vertical gap between components:** 40px +- **Inline connectors (message buses):** Place IN the gap between components, not overlapping + +**Example vertical layout:** +``` +Component A: y=70, height=60 → ends at y=130 +Gap: y=130 to y=170 → 40px gap, place bus at y=140 (20px tall) +Component B: y=170, height=60 → ends at y=230 +``` + +**Wrong:** Placing a message bus at y=160 when Component B starts at y=170 (causes overlap) +**Right:** Placing a message bus at y=140, centered in the 40px gap (y=130 to y=170) + +### Legend Placement + +**CRITICAL:** Place legends OUTSIDE all boundary boxes (region boundaries, cluster boundaries, security groups). + +- Calculate where all boundaries end (y position + height) +- Place legend at least 20px below the lowest boundary +- Expand SVG viewBox height if needed to accommodate + +**Example:** +``` +Kubernetes Cluster: y=30, height=460 → ends at y=490 +Legend should start at: y=510 or below +SVG viewBox height: at least 560 to fit legend +``` + +**Wrong:** Legend at y=470 inside a cluster boundary that ends at y=490 +**Right:** Legend at y=510, below the cluster boundary, with viewBox height extended + +### Layout Structure + +1. **Header** - Title with pulsing dot indicator, subtitle +2. **Main SVG diagram** - Contained in rounded border card +3. **Summary cards** - Grid of 3 cards below diagram with key details +4. **Footer** - Minimal metadata line + +### Component Box Pattern + +```svg + +LABEL +sublabel +``` + +### Info Card Pattern + +```html +
+
+
+

Title

+
+
    +
  • • Item one
    • +
  • • Item two
    • +
+
+``` + +## Template + +Copy and customize the template at `assets/template.html`. Key customization points: + +1. Update the `` and header text +2. Modify SVG viewBox dimensions if needed (default: `1000 x 680`) +3. Add/remove/reposition component boxes +4. Draw connection arrows between components +5. Update the three summary cards +6. Update footer metadata + +## Output + +Always produce a single self-contained `.html` file with: +- Embedded CSS (no external stylesheets except Google Fonts) +- Inline SVG (no external images) +- No JavaScript required (pure CSS animations) + +The file should render correctly when opened directly in any modern browser. diff --git a/claude/skills/architecture-diagram/assets/template.html b/claude/skills/architecture-diagram/assets/template.html new file mode 100644 index 0000000..f5b32fb --- /dev/null +++ b/claude/skills/architecture-diagram/assets/template.html @@ -0,0 +1,319 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="UTF-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <title>[PROJECT NAME] Architecture Diagram + + + + +
+ +
+
+
+

[PROJECT NAME] Architecture

+
+

[Subtitle description]

+
+ + +
+ + + + + + + + + + + + + + + + + + + Users + Browser/Mobile + + + + Auth Provider + OAuth 2.0 + + + + AWS Region: us-west-2 + + + + CloudFront + CDN + + + + S3 Buckets + • bucket-one + • bucket-two + • bucket-three + OAI Protected + + + + sg-name :port + + + + Load Balancer + HTTPS :443 + + + + API Server + FastAPI :8000 + + + + Database + PostgreSQL + + + + Frontend + React + TypeScript + Additional detail + More info + domain.example.com + + + + + + HTTPS + + + + + + + OAI + + + + + TLS + + + + JWT + PKCE + + + Legend + + + Frontend + + + Backend + + + Cloud Service + + + Database + + + Security + + + Auth Flow + + + Security Group + +
+ + +
+
+
+
+

Card Title 1

+
+
    +
  • • Item one
    • +
  • • Item two
    • +
  • • Item three
    • +
  • • Item four
    • +
+
+ +
+
+
+

Card Title 2

+
+
    +
  • • Item one
    • +
  • • Item two
    • +
  • • Item three
    • +
  • • Item four
    • +
+
+ +
+
+
+

Card Title 3

+
+
    +
  • • Item one
    • +
  • • Item two
    • +
  • • Item three
    • +
  • • Item four
    • +
+
+
+ + +

+ [Project Name] • [Additional metadata] +

+
+ + diff --git a/docs/playbooks/impeccable-workflow.md b/docs/playbooks/impeccable-workflow.md new file mode 100644 index 0000000..6a004cd --- /dev/null +++ b/docs/playbooks/impeccable-workflow.md @@ -0,0 +1,139 @@ +# Impeccable Design Workflow + +> Design-aware code review and polish via the [Impeccable](https://impeccable.style/) plugin (v2.1, Apache 2.0, by [@pbakaus](https://github.com/pbakaus/impeccable)). + +Companion plugin — not vendored into this kit. Install it alongside `qute-essentials` when you want Claude to reason about typography, color, spacing, motion, and UX writing instead of only correctness. + +## What it is + +A design skill set plus a deterministic detection engine. 18 slash commands teach Claude a concrete design vocabulary; 25 anti-pattern rules catch the usual AI-generated tells (gradient text, purple gradients, Inter everywhere, nested cards, low-contrast text, emoji-only nodes, etc.) before they ship. + +Release timeline: +- **v2.1** — 2026-04-09 — 21 → 18 commands; `/arrange` → `/layout`, `/normalize` folded into `/polish`, `/onboard` folded into `/harden`, `/extract` became a sub-mode. +- **v2.0** — 2026-04-08 — data-driven rewrite against an internal eval framework that measures output monoculture; stronger font/color diversity; cross-model support. + +## Install + +Pick one. All leave a `.claude/` tree at project or user scope. + +```bash +# Marketplace (recommended — updates cleanly) +/plugin marketplace add pbakaus/impeccable +/plugin # enable "impeccable" + +# Universal installer (auto-detects harness) +npx skills add pbakaus/impeccable + +# CI / pre-commit scanner (no harness needed) +npm i -g impeccable +npx impeccable detect src/ +``` + +Prefixed variant (`/i-polish`, `/i-audit`, …) exists if the default names collide with your other skills. + +## One-time project setup + +``` +/impeccable teach +``` + +Writes `.impeccable.md` with your project's design context (brand, fonts, palette, tone). Every subsequent command reads it — skip this and results regress to generic defaults. + +Commit `.impeccable.md`. Treat it like a design ADR. + +## Core commands + +Grouped by when you reach for them. Exact set per v2.1. + +### Shape & polish + +| Command | Use when | +|---------|----------| +| `/polish` | Default "make this better" pass — typography, spacing, color, hierarchy. Absorbs the old `/normalize`. | +| `/layout` | Restructure page or component layout (renamed from `/arrange`). | +| `/typeset` | Pure typography pass — type scale, line-height, tracking, font pairings. | +| `/overdrive` | Aggressive redesign — use when `/polish` is too timid. | + +### Audit & detect + +| Command | Use when | +|---------|----------| +| `/audit` | Run the 25-rule detection engine against the current view/file and report findings with fixes. | +| `/harden` | Accessibility + robustness pass (contrast, focus states, keyboard nav). Absorbs the old `/onboard`. | + +### Supporting + +The remaining commands cover motion, interaction states, responsive breakpoints, UX writing, color systems, and extraction of existing design tokens. Run `/plugin` after install to see the full list with in-harness descriptions. + +## Typical flows + +### A. New component from scratch + +``` +1. superpowers:brainstorming → clarify what the component is for +2. Claude drafts the component +3. /polish → fixes obvious tells (gradient text, Inter, etc.) +4. /harden → a11y + keyboard +5. /audit → confirm detection engine is clean +6. architecture-diagram → drop a diagram into the PR if it's structural +``` + +### B. Fixing LLM-generated slop in an existing repo + +``` +1. npx impeccable detect src/ # scan first — no harness needed +2. /impeccable teach # if .impeccable.md doesn't exist yet +3. /audit # per-file triage +4. /polish # apply fixes; review diff +5. /gbu # qute-essentials review of the polish pass +``` + +### C. Design system extraction + +``` +1. /audit src/components/ → find what's already in use +2. /typeset → lock the type scale +3. Commit .impeccable.md → now every future change inherits the system +``` + +### D. CI / pre-commit + +```yaml +# .pre-commit-config.yaml +- repo: local + hooks: + - id: impeccable + name: impeccable detect + entry: npx impeccable detect + language: system + pass_filenames: true + files: \.(tsx?|jsx?|css|scss)$ +``` + +Fails the commit on hard rules (gradient text, contrast < AA). Warnings-only for softer rules. + +## Pairing with qute-code-kit + +| Kit component | How it interacts with Impeccable | +|---------------|----------------------------------| +| `ui-ux-pro-max` skill (webdev bundle) | Strategic UX review; Impeccable is the tactical pass after it | +| `code-quality` skill | Runs on code correctness; Impeccable runs on design quality — use both | +| `architecture-diagram` skill | System-level diagrams; Impeccable polishes the UI surface those systems render | +| `/guard` from qute-essentials | Leave guards on — Impeccable only edits files, never shells or network | +| `/gbu`, `/wtf` from qute-essentials | Good review partners for a `/polish` or `/overdrive` diff | +| Chrome extension | Pairs with the `chrome-devtools` MCP (webdev bundle) — overlay detection while you debug live | + +## Gotchas + +- **No `.impeccable.md` = monoculture outputs.** Run `/teach` first, always. +- **`/overdrive` is not idempotent.** Re-running produces a different design each time — commit between runs. +- **Prefix variants are separate commands.** If you installed the prefixed zip, `/polish` won't exist — it's `/i-polish`. Don't mix. +- **The detection engine runs client-side.** No code or content leaves your machine; safe to use on private repos. +- **Cross-harness skill files.** The repo ships `.claude/`, `.cursor/skills`, `.gemini/skills`, etc. — only the `.claude/` tree matters for Claude Code; ignore the rest. + +## Links + +- Site: https://impeccable.style/ +- Install docs: https://impeccable.style/install +- Source: https://github.com/pbakaus/impeccable +- Chrome extension: [Chrome Web Store](https://chromewebstore.google.com/detail/impeccable/bdkgmiklpdmaojlpflclinlofgjfpabf) diff --git a/docs/playbooks/visual-documentation.md b/docs/playbooks/visual-documentation.md index 78c7b91..0e61c59 100644 --- a/docs/playbooks/visual-documentation.md +++ b/docs/playbooks/visual-documentation.md @@ -9,6 +9,7 @@ | visual-explainer | `claude-plugins-official` plugin | Convert terminal output to styled HTML | | gist-report | `gist-report` skill | Share reports via GitHub gist | | image-generator | `image-generator` skill | Generate diagrams and visuals | +| architecture-diagram | `architecture-diagram` skill | Dark-themed HTML+SVG system architecture diagrams | | playground | `claude-plugins-official` plugin | Build interactive explorers | ## When to Use @@ -84,7 +85,50 @@ Ingestion → Processing → Storage → API → Dashboard Use --style technical-diagram, dark background ``` -### D. Share via gist +### D. System diagrams with architecture-diagram + +Model-invocable skill (Cocoon AI, MIT) that produces a single self-contained +`.html` file with inline SVG, semantic color-coding (cyan frontends, emerald +backends, violet databases, amber cloud, rose security, orange message buses), +JetBrains Mono typography, and a dark `#020617` theme. Copies a starter template +from `assets/template.html` and customizes viewBox, components, arrows, legend, +and summary cards. + +Trigger phrases that route here: *"architecture diagram"*, *"infrastructure +diagram"*, *"cloud architecture"*, *"network topology"*, *"security diagram"*. + +**Example usages:** + +``` +Use the architecture-diagram skill to diagram a React + FastAPI + Postgres app +behind CloudFront, with Auth0 OAuth for login and S3 for asset storage. +Save as docs/architecture/web-app.html. +``` + +``` +Create an AWS serverless architecture diagram: API Gateway → Lambda (Python) → +DynamoDB, with SQS for async jobs, EventBridge for cron, and Cognito for auth. +Show the us-west-2 region boundary and a security group around the API layer. +``` + +``` +Diagram our microservices topology: 4 Go services behind an NGINX ingress on +Kubernetes, Kafka event bus between order-service and inventory-service, +Postgres per service, Redis cache, Prometheus + Grafana for observability. +``` + +``` +Read src/ and infer the component graph, then render it with the +architecture-diagram skill — one box per top-level package, arrows for imports, +a violet box for the shared datastore, and a summary card listing entry points. +``` + +Compared with `image-generator` (rasterized PNGs) and `visual-explainer` +(Mermaid / Chart.js), `architecture-diagram` is the right pick when you want +editable SVG in a single HTML file that renders identically on any machine — +good for README embeds, PR artifacts, or stakeholder handoffs. + +### E. Share via gist Any of the above can be shared: @@ -104,6 +148,14 @@ Creates a shareable GitHub gist URL. Works for HTML reports, Markdown summaries, 4. Send to team Slack ``` +### Polished architecture HTML for a design review +``` +1. Describe components + flows (or let Claude infer from the repo) +2. architecture-diagram skill → docs/architecture/.html +3. Open locally to verify spacing / legend placement +4. /gist-report → paste URL into the review doc +``` + ### Test failure dashboard ``` 1. Run tests, capture results @@ -125,3 +177,6 @@ Creates a shareable GitHub gist URL. Works for HTML reports, Markdown summaries, - Playground is better for interactive exploration; visual-explainer for static reports - For recurring reports, save the playground HTML and regenerate data only - Combine with `/handoff` to note which visualizations need updating +- Reach for `architecture-diagram` over Mermaid when you need precise layout + control, named security groups / region boundaries, or a branded dark theme + you can commit into the repo diff --git a/project-templates/quant/.claude/.toolkit-manifest.json b/project-templates/quant/.claude/.toolkit-manifest.json index 1a489be..ed97414 100644 --- a/project-templates/quant/.claude/.toolkit-manifest.json +++ b/project-templates/quant/.claude/.toolkit-manifest.json @@ -1,7 +1,7 @@ { "source": "/home/user/qute-code-kit", "bundle": "quant", - "installed": "2026-04-08T20:12:44Z", + "installed": "2026-04-16T19:43:01Z", "mode": "copy", "components": [ {"type": "rule", "name": "general-rules.md", "src": "rules/general-rules.md"}, @@ -11,6 +11,8 @@ {"type": "rule", "name": "decisions.md", "src": "rules/decisions.md"}, {"type": "root", "name": "CLAUDE.md", "src": "root/CLAUDE.md"}, {"type": "root", "name": "AGENTS.md", "src": "root/AGENTS.md"}, + {"type": "skill", "name": "skill-assessment", "src": "skill-assessment"}, + {"type": "skill", "name": "debug-session", "src": "debug-session"}, {"type": "settings", "name": "project-quant.json", "src": "settings/project-quant.json"}, {"type": "pyproject", "name": "quant-uv.toml", "src": "pyproject/quant-uv.toml"}, {"type": "rule", "name": "python-rules.md", "src": "rules/python-rules.md"}, @@ -28,8 +30,9 @@ {"type": "skill", "name": "llm-external-review", "src": "llm-external-review"}, {"type": "skill", "name": "analizy-pl-data", "src": "analizy-pl-data"}, {"type": "skill", "name": "gist-report", "src": "gist-report"}, - {"type": "skill", "name": "gist-transcript", "src": "gist-transcript"}, {"type": "skill", "name": "image-generator", "src": "image-generator"}, + {"type": "skill", "name": "architecture-diagram", "src": "architecture-diagram"}, + {"type": "skill", "name": "code-quality", "src": "code-quality"}, {"type": "mcp", "name": "firecrawl", "src": "mcp:firecrawl"}, {"type": "mcp", "name": "postgres", "src": "mcp:postgres"} ] diff --git a/project-templates/quant/.claude/rules/git-workflow.md b/project-templates/quant/.claude/rules/git-workflow.md index 3eb4b4e..363feae 100644 --- a/project-templates/quant/.claude/rules/git-workflow.md +++ b/project-templates/quant/.claude/rules/git-workflow.md @@ -5,12 +5,10 @@ | Branch | Purpose | Merge Target | |--------|---------|--------------| | `main` | Production-ready code | — (deploy target) | -| `dev` | Integration + working branch | `main` via PR | -| `feat/*` | Feature development, branched from `dev` | `dev` via PR or merge | +| `dev` | Integration + research exploration | `main` via PR | +| `feat/*` | Specific feature or production change with validation | `dev` via PR | -Standard flow: `feat/xyz` → merge to `dev` → PR `dev` to `main`. - -**Development happens on `feat/*` branches, not directly on `dev`.** This keeps `dev` clean for PRing to main. When a `dev → main` PR is open, any push to `dev` auto-updates it — so only merge finished `feat/*` work into `dev` before creating the PR. +Standard flow: `feat/xyz` → `dev` → `main`. ## Research Code Policy @@ -18,21 +16,21 @@ Standard flow: `feat/xyz` → merge to `dev` → PR `dev` to `main`. ### Why not separate research branches -1. **Directory isolation is sufficient** — `research/selection/`, `research/autoresearch-*/`, `research/{study-name}/` already isolate exploration from production code. -2. **Shared infrastructure must stay in sync** — modules like `research/selection/wf_contract.py` are imported by production pipelines. A research-only branch would fork this shared code. +1. **Directory isolation is sufficient** — `research/{study-name}/` already isolates exploration from production code. +2. **Shared infrastructure must stay in sync** — research modules imported by production pipelines would fork on a separate branch. 3. **Research branches drift and go stale** — team members can't discover exploration work if it's hidden on long-lived branches. 4. **Findings are documentation** — `FINDINGS.md`, experiment results, and baseline numbers are reference material that belongs on mainline. ### Production promotion of research findings -When a research experiment produces a winning configuration and is ready to be adopted in production: +When a research experiment produces a winning configuration: ``` dev (has research exploration) │ - └─ feat/ml-{specific-change} - ├─ Modify production config (e.g., config/fund-selection/scoring.yaml) - ├─ Run production validation (e.g., research/selection/ml_train.py) + └─ feat/{specific-change} + ├─ Modify production config + ├─ Run production validation ├─ Verify quality gates pass ├─ PR to dev └─ Merge dev → main @@ -57,7 +55,7 @@ Split unrelated changes into separate commits: |-------------|---------| | Infrastructure | "research: shared wf_contract for ML fund selection" | | Experiments | "research: autoresearch experiments + findings" | -| Data fix | "fix: default mainunit=1 for 302 unclassified FIO PLN funds" | +| Data fix | "fix: default mainunit=1 for 302 unclassified funds" | | Chore | "chore: add 7-day exclude-newer for supply chain safety" | ## Commit Message Conventions diff --git a/project-templates/quant/.claude/skills/architecture-diagram/SKILL.md b/project-templates/quant/.claude/skills/architecture-diagram/SKILL.md new file mode 100644 index 0000000..b6e5aac --- /dev/null +++ b/project-templates/quant/.claude/skills/architecture-diagram/SKILL.md @@ -0,0 +1,163 @@ +--- +name: architecture-diagram +description: Create professional, dark-themed architecture diagrams as standalone HTML files with SVG graphics. Use when the user asks for system architecture diagrams, infrastructure diagrams, cloud architecture visualizations, security diagrams, network topology diagrams, or any technical diagram showing system components and their relationships. +license: MIT +metadata: + version: "1.0" + author: Cocoon AI (hello@cocoon-ai.com) +--- + +# Architecture Diagram Skill + +Create professional technical architecture diagrams as self-contained HTML files with inline SVG graphics and CSS styling. + +## Design System + +### Color Palette + +Use these semantic colors for component types: + +| Component Type | Fill (rgba) | Stroke | +|---------------|-------------|--------| +| Frontend | `rgba(8, 51, 68, 0.4)` | `#22d3ee` (cyan-400) | +| Backend | `rgba(6, 78, 59, 0.4)` | `#34d399` (emerald-400) | +| Database | `rgba(76, 29, 149, 0.4)` | `#a78bfa` (violet-400) | +| AWS/Cloud | `rgba(120, 53, 15, 0.3)` | `#fbbf24` (amber-400) | +| Security | `rgba(136, 19, 55, 0.4)` | `#fb7185` (rose-400) | +| Message Bus | `rgba(251, 146, 60, 0.3)` | `#fb923c` (orange-400) | +| External/Generic | `rgba(30, 41, 59, 0.5)` | `#94a3b8` (slate-400) | + +### Typography + +Use JetBrains Mono for all text (monospace, technical aesthetic): +```html + +``` + +Font sizes: 12px for component names, 9px for sublabels, 8px for annotations, 7px for tiny labels. + +### Visual Elements + +**Background:** `#020617` (slate-950) with subtle grid pattern: +```svg + + + +``` + +**Component boxes:** Rounded rectangles (`rx="6"`) with 1.5px stroke, semi-transparent fills. + +**Security groups:** Dashed stroke (`stroke-dasharray="4,4"`), transparent fill, rose color. + +**Region boundaries:** Larger dashed stroke (`stroke-dasharray="8,4"`), amber color, `rx="12"`. + +**Arrows:** Use SVG marker for arrowheads: +```svg + + + +``` + +**Arrow z-order:** Draw connection arrows early in the SVG (after the background grid) so they render behind component boxes. SVG elements are painted in document order, so arrows drawn first will appear behind shapes drawn later. + +**Masking arrows behind transparent fills:** Since component boxes use semi-transparent fills (`rgba(..., 0.4)`), arrows behind them will show through. To fully mask arrows, draw an opaque background rect (e.g., `fill="#0f172a"`) at the same position before drawing the semi-transparent styled rect on top: +```svg + + + + +``` + +**Auth/security flows:** Dashed lines in rose color (`#fb7185`). + +**Message buses / Event buses:** Small connector elements between services. Use orange color (`#fb923c` stroke, `rgba(251, 146, 60, 0.3)` fill): +```svg + +Kafka / RabbitMQ +``` + +### Spacing Rules + +**CRITICAL:** When stacking components vertically, ensure proper spacing to avoid overlaps: + +- **Standard component height:** 60px for services, 80-120px for larger components +- **Minimum vertical gap between components:** 40px +- **Inline connectors (message buses):** Place IN the gap between components, not overlapping + +**Example vertical layout:** +``` +Component A: y=70, height=60 → ends at y=130 +Gap: y=130 to y=170 → 40px gap, place bus at y=140 (20px tall) +Component B: y=170, height=60 → ends at y=230 +``` + +**Wrong:** Placing a message bus at y=160 when Component B starts at y=170 (causes overlap) +**Right:** Placing a message bus at y=140, centered in the 40px gap (y=130 to y=170) + +### Legend Placement + +**CRITICAL:** Place legends OUTSIDE all boundary boxes (region boundaries, cluster boundaries, security groups). + +- Calculate where all boundaries end (y position + height) +- Place legend at least 20px below the lowest boundary +- Expand SVG viewBox height if needed to accommodate + +**Example:** +``` +Kubernetes Cluster: y=30, height=460 → ends at y=490 +Legend should start at: y=510 or below +SVG viewBox height: at least 560 to fit legend +``` + +**Wrong:** Legend at y=470 inside a cluster boundary that ends at y=490 +**Right:** Legend at y=510, below the cluster boundary, with viewBox height extended + +### Layout Structure + +1. **Header** - Title with pulsing dot indicator, subtitle +2. **Main SVG diagram** - Contained in rounded border card +3. **Summary cards** - Grid of 3 cards below diagram with key details +4. **Footer** - Minimal metadata line + +### Component Box Pattern + +```svg + +LABEL +sublabel +``` + +### Info Card Pattern + +```html +
+
+
+

Title

+
+
    +
  • • Item one
    • +
  • • Item two
    • +
+
+``` + +## Template + +Copy and customize the template at `assets/template.html`. Key customization points: + +1. Update the `` and header text +2. Modify SVG viewBox dimensions if needed (default: `1000 x 680`) +3. Add/remove/reposition component boxes +4. Draw connection arrows between components +5. Update the three summary cards +6. Update footer metadata + +## Output + +Always produce a single self-contained `.html` file with: +- Embedded CSS (no external stylesheets except Google Fonts) +- Inline SVG (no external images) +- No JavaScript required (pure CSS animations) + +The file should render correctly when opened directly in any modern browser. diff --git a/project-templates/quant/.claude/skills/architecture-diagram/assets/template.html b/project-templates/quant/.claude/skills/architecture-diagram/assets/template.html new file mode 100644 index 0000000..f5b32fb --- /dev/null +++ b/project-templates/quant/.claude/skills/architecture-diagram/assets/template.html @@ -0,0 +1,319 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="UTF-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <title>[PROJECT NAME] Architecture Diagram + + + + +
+ +
+
+
+

[PROJECT NAME] Architecture

+
+

[Subtitle description]

+
+ + +
+ + + + + + + + + + + + + + + + + + + Users + Browser/Mobile + + + + Auth Provider + OAuth 2.0 + + + + AWS Region: us-west-2 + + + + CloudFront + CDN + + + + S3 Buckets + • bucket-one + • bucket-two + • bucket-three + OAI Protected + + + + sg-name :port + + + + Load Balancer + HTTPS :443 + + + + API Server + FastAPI :8000 + + + + Database + PostgreSQL + + + + Frontend + React + TypeScript + Additional detail + More info + domain.example.com + + + + + + HTTPS + + + + + + + OAI + + + + + TLS + + + + JWT + PKCE + + + Legend + + + Frontend + + + Backend + + + Cloud Service + + + Database + + + Security + + + Auth Flow + + + Security Group + +
+ + +
+
+
+
+

Card Title 1

+
+
    +
  • • Item one
    • +
  • • Item two
    • +
  • • Item three
    • +
  • • Item four
    • +
+
+ +
+
+
+

Card Title 2

+
+
    +
  • • Item one
    • +
  • • Item two
    • +
  • • Item three
    • +
  • • Item four
    • +
+
+ +
+
+
+

Card Title 3

+
+
    +
  • • Item one
    • +
  • • Item two
    • +
  • • Item three
    • +
  • • Item four
    • +
+
+
+ + +

+ [Project Name] • [Additional metadata] +

+
+ + diff --git a/project-templates/quant/.claude/skills/code-quality/SKILL.md b/project-templates/quant/.claude/skills/code-quality/SKILL.md new file mode 100644 index 0000000..5e016ce --- /dev/null +++ b/project-templates/quant/.claude/skills/code-quality/SKILL.md @@ -0,0 +1,124 @@ +--- +name: code-quality +description: | + Multi-mode code quality review: blunt critique + static checks + domain-specific patterns. + Use when the user says "review this code", "code review", "quality check", "is this code good", + "find issues in", "check before committing", "review before merging", "lint this", + "is this idiomatic Python/SQL/TypeScript", or wants structured feedback on any code artifact. + Composes with /gbu for the opinionated section, and python-patterns/sql-patterns/ui-ux-pro-max + for domain-specific checks. +argument-hint: "[path/to/file-or-dir | git diff] [--quick | --deep]" +allowed-tools: Read, Glob, Grep, Bash, Agent +--- + +# Code Quality Review + +Multi-mode quality review. Combines blunt critique with static analysis and domain-specific +pattern checks. + +## Modes + +| Mode | When | Depth | +|------|------|-------| +| `--quick` | Single file or function spot-check | GBU + obvious bugs only | +| `--deep` | Module, PR, or directory review | Full: static checks + GBU + domain patterns | +| (default) | Auto-detect: single file → quick, directory or diff → deep | — | + +## Workflow + +### 1. Determine scope + +If an argument is given, read that file or directory. If no argument, review recent changes: + +```bash +git diff --name-only HEAD # files changed since last commit +git diff --name-only main # files changed vs main (for PR review) +``` + +### 2. Static checks (quick wins) + +**Python**: +```bash +ruff check --select E,F --no-fix # syntax + unused imports +``` + +**SQL** (in `.sql` files or embedded in Python): +- `SELECT *` on large tables (missing column specificity) +- `UPDATE`/`DELETE` without `WHERE` clause +- Implicit type coercions or missing index hints + +**TypeScript/JavaScript**: +```bash +npx tsc --noEmit # type errors only, no output +``` + +Skip and note in output if the tool isn't installed. + +### 3. Blunt critique (GBU format) + +Apply `/gbu` semantics to the code under review: + +```markdown +## Good +- What works, is idiomatic, reusable, or well-scoped + +## Bad +- `must` Wrong, broken, or misleading — fix before merging +- `should` Below bar for the goal — fix before shipping +- `could` Style or readability — address when convenient + +## Ugly +- Not broken today but fragile, opaque, or a future cost +``` + +3–7 bullets per section. Anchor each with file path, line number, or short quote. + +### 4. Domain-specific checks + +Apply the relevant domain skill for deeper pattern checks: + +| File type | Skill to apply | +|-----------|----------------| +| `*.py` | `python-patterns` — uv/venv conventions, type hints, test patterns, anti-patterns | +| `*.sql` or SQL strings | `sql-patterns` — query optimization, index hints, safety | +| `*.tsx`, `*.jsx`, UI | `ui-ux-pro-max` — accessibility, responsiveness, component patterns | + +### 5. Output format + +```markdown +## Code Review: + +### Static Checks + + +### Critique (GBU) +#### Good +- ... +#### Bad +- `must` ... +#### Ugly +- ... + +### Domain Findings + + +### Fix Priority +1. [must-fix] +2. [should-fix] +``` + +## Gotchas + +- **Generated files**: skip files with `# generated by`, `# auto-generated`, or `DO NOT EDIT` headers — note and exclude them from review +- **Test files**: apply looser standards — `assert`, magic values, and repetition are acceptable; flag only real bugs and security issues +- **Ruff not installed**: skip static check step and note it; don't abort the review +- **SQL in Python strings**: if no `.sql` files exist, grep for embedded queries: `grep -rn "SELECT\|INSERT\|UPDATE\|DELETE" --include="*.py" ` +- **Scope creep**: review only what was asked — don't audit the whole repo when asked to review one function; expanding scope silently is a failure mode +- **Ugly ≠ Bad**: items that are technically correct but fragile go in Ugly, not Bad; misclassifying these inflates the severity of the review + +## Related + +- `/gbu` — the blunt review engine this skill uses for the critique section +- `python-patterns` skill — Python-specific conventions and idiomatic patterns +- `sql-patterns` skill — SQL query patterns and optimization hints +- `ui-ux-pro-max` skill — UI/UX review checklist for frontend code diff --git a/project-templates/quant/.claude/skills/debug-session/SKILL.md b/project-templates/quant/.claude/skills/debug-session/SKILL.md new file mode 100644 index 0000000..450ae61 --- /dev/null +++ b/project-templates/quant/.claude/skills/debug-session/SKILL.md @@ -0,0 +1,182 @@ +--- +name: debug-session +description: | + Runbook for diagnosing and fixing Claude Code session problems. + Use when: skills aren't triggering, hooks are failing or blocking all tool calls, + context is overloaded (slow responses, repetition), guards are blocking legitimate + commands, plugin cache is corrupt, or the session feels stuck or broken. + Trigger phrases: "why isn't my skill working", "hooks are broken", "all tool calls fail", + "plugin cache", "skill not triggering", "Claude is slow", "context too large", + "guard is blocking", "Claude is stuck", "session is broken". +argument-hint: "[symptom description]" +allowed-tools: Read, Bash, Glob, Grep +--- + +# Debug Session Runbook + +Diagnose and fix Claude Code session problems. Match your symptom, follow the fix. + +## Symptom Index + +| Symptom | Section | +|---------|---------| +| Every tool call fails immediately with a hook error | [Plugin Cache Corruption](#plugin-cache-corruption) | +| Skill invoked (`/skill-name`) but nothing happens | [Skill Not Triggering](#skill-not-triggering) | +| Hook fires but logs an error | [Hook Script Error](#hook-script-error) | +| Slow responses, repetition, losing context | [Context Overload](#context-overload) | +| Guard blocks a command you know is safe | [Guard False Positive](#guard-false-positive) | +| Session breaks after `/clear` or after ~2.5 hours | [Stop Hook Regression](#stop-hook-regression) | + +--- + +## Plugin Cache Corruption + +**Symptom**: Every tool call fails immediately. Error mentions a missing script path under `~/.claude/plugins/cache/`. + +**Cause**: `enabledPlugins` in `settings.json` references plugins that are no longer in cache. + +**Fix sequence — ORDER MATTERS** (wrong order makes it worse): + +1. Clear `enabledPlugins` first: + ```bash + python3 -c " + import json, os + f = os.path.expanduser('~/.claude/settings.json') + s = json.load(open(f)) + s['enabledPlugins'] = {} + json.dump(s, open(f, 'w'), indent=2) + print('enabledPlugins cleared') + " + ``` + +2. Then clear plugin cache: + ```bash + rm -rf ~/.claude/plugins/cache/ + ``` + +3. Reinstall plugins: + ```bash + claude plugin install qute-essentials@qute-marketplace + ``` + +**Why this order**: if you clear the cache while `enabledPlugins` still references plugins, every hook fires and immediately errors — all tool calls fail until fixed. + +--- + +## Skill Not Triggering + +**Symptom**: User types `/skill-name` but Claude ignores it or applies generic behavior. + +**Diagnosis steps**: + +1. Verify the skill file exists in the project: + ```bash + ls .claude/skills/skill-name/SKILL.md + ``` + +2. Check `forced-eval` hook is active (required for reliable skill activation): + ```bash + grep -r "forced" ~/.claude/plugins/cache/qute-marketplace/qute-essentials/*/hooks/hooks.json + ``` + +3. Read the skill's `description` field — does it contain clear trigger phrases matching the user's exact wording? + +**Fixes**: +- Missing skill file → copy from `claude/skills/skill-name/` or re-run `setup-project.sh` +- `forced-eval` absent → reinstall qute-essentials: `claude plugin install qute-essentials@qute-marketplace` +- Weak description → edit the `description:` frontmatter in `SKILL.md` to add more trigger phrases in the user's language + +--- + +## Hook Script Error + +**Symptom**: A hook fires but logs a Python error or missing-file error. Tool call may be blocked or proceed with a warning. + +**Diagnosis**: +```bash +# Validate hooks.json is valid JSON +python3 -m json.tool ~/.claude/plugins/cache/qute-marketplace/qute-essentials/*/hooks/hooks.json + +# List scripts to verify paths +ls ~/.claude/plugins/cache/qute-marketplace/qute-essentials/*/scripts/ + +# Test a suspect script directly +python3 ~/.claude/plugins/cache/qute-marketplace/qute-essentials/*/scripts/suspect-script.py +``` + +**Common causes**: +- Script path in `hooks.json` doesn't match actual filename (e.g., `track_edits.py` renamed to `doc_reminder.py`) +- Python script has a syntax error — run it directly to see the traceback +- Missing import — the script requires a package not in PATH + +--- + +## Context Overload + +**Symptom**: Responses slow down, Claude repeats itself, loses track of earlier instructions, or context window warning appears. + +**Options in order of disruption**: + +| Option | Command | When | +|--------|---------|------| +| Summarize in-place | `/compact` | Still in flow, just bulky context | +| Structured transition | `/handoff "what I was doing"` → new session → `/pickup` | Natural stopping point, multi-day work | +| Quick resume | `claude -c` | Short break, simple continuation | + +**Signs context is the problem (not skill or hook issues)**: +- Same question answered differently than 30 messages ago +- Claude forgets a constraint set early in the session +- Tool calls taking noticeably longer than at session start + +--- + +## Guard False Positive + +**Symptom**: A security guard blocks a shell command or file write you know is safe. + +**Diagnosis**: +``` +/guard status +``` + +**Temporary fix**: +``` +/guard off +# ... do your operation ... +/guard on +``` + +**Guards most likely to false-positive**: + +| Guard | Common false positive | +|-------|----------------------| +| `destructive` | `rm -rf dist/`, `git reset --hard` on clean feature branch | +| `secrets` | Test fixtures with fake API key patterns | +| `malware` | Minified JS or base64-encoded assets in source files | + +--- + +## Stop Hook Regression + +**Symptom**: After `/clear` or after ~2.5 hours, end-of-session hooks stop firing (e.g., handoff not auto-created). + +**Cause**: Known Claude Code regression — `Stop` event hooks fire once then break after `/clear` and after extended sessions. + +**Workaround**: Don't rely on stop hooks for critical end-of-session actions. Always call `/handoff` explicitly before ending a session. + +--- + +## Gotchas + +- **Never clear plugin cache without first clearing `enabledPlugins`** — this is the #1 cause of catastrophic hook failures +- **Settings changes require a Claude Code restart** — edits to `settings.json` are not hot-reloaded; hooks are cached at session start +- **`CLAUDE_SKIP_GUARDS=1` bypasses ALL guards** — never set this in `.env` or shell profile permanently +- **`git worktree remove` fails on uncommitted changes** — stash or commit first; the error is non-obvious +- **After `claude plugin uninstall`, re-run `claude plugin install`** — uninstall clears the cache; the plugins entry in settings.json must also be updated + +## Related + +- `/guard` — toggle security guards, diagnose false positives +- `/guard status` — show current guard state including API key presence +- `/handoff` — proper session-end that survives stop hook regressions +- `/pickup` — load last handoff at session start diff --git a/project-templates/quant/.claude/skills/gist-report/SKILL.md b/project-templates/quant/.claude/skills/gist-report/SKILL.md index 2c0d042..c0755de 100644 --- a/project-templates/quant/.claude/skills/gist-report/SKILL.md +++ b/project-templates/quant/.claude/skills/gist-report/SKILL.md @@ -86,6 +86,24 @@ The template includes pre-built components. Just use these in your body HTML:
Source: link text — Generated by Claude Code
``` +## Transcript Mode + +Upload the current session transcript as a GitHub Gist (JSON format): + +```bash +uvx claude-code-transcripts json --gist "$(ls -t ~/.claude/projects/$(pwd | tr '/' '-')/*.jsonl | head -1)" +``` + +Returns a single gist URL. The gist contains the full conversation — user messages, assistant responses, tool calls, and timestamps. + +**Before sharing**: the transcript includes all tool output as-is; review it if the session touched credentials or sensitive data. + +| Issue | Fix | +|-------|-----| +| "No such file" | No session files found — ensure you're in a project directory | +| gh auth error | Run `gh auth login` to authenticate | +| Empty transcript | Session just started — need at least one exchange | + ## Rules 1. **Write body HTML only** — never include ``, ``, ``, or ` + + +
+ +
+
+
+

[PROJECT NAME] Architecture

+
+

[Subtitle description]

+
+ + +
+ + + + + + + + + + + + + + + + + + + Users + Browser/Mobile + + + + Auth Provider + OAuth 2.0 + + + + AWS Region: us-west-2 + + + + CloudFront + CDN + + + + S3 Buckets + • bucket-one + • bucket-two + • bucket-three + OAI Protected + + + + sg-name :port + + + + Load Balancer + HTTPS :443 + + + + API Server + FastAPI :8000 + + + + Database + PostgreSQL + + + + Frontend + React + TypeScript + Additional detail + More info + domain.example.com + + + + + + HTTPS + + + + + + + OAI + + + + + TLS + + + + JWT + PKCE + + + Legend + + + Frontend + + + Backend + + + Cloud Service + + + Database + + + Security + + + Auth Flow + + + Security Group + +
+ + +
+
+
+
+

Card Title 1

+
+
    +
  • • Item one
    • +
  • • Item two
    • +
  • • Item three
    • +
  • • Item four
    • +
+
+ +
+
+
+

Card Title 2

+
+
    +
  • • Item one
    • +
  • • Item two
    • +
  • • Item three
    • +
  • • Item four
    • +
+
+ +
+
+
+

Card Title 3

+
+
    +
  • • Item one
    • +
  • • Item two
    • +
  • • Item three
    • +
  • • Item four
    • +
+
+
+ + +

+ [Project Name] • [Additional metadata] +

+
+ + diff --git a/project-templates/webdev/.claude/skills/code-quality/SKILL.md b/project-templates/webdev/.claude/skills/code-quality/SKILL.md new file mode 100644 index 0000000..5e016ce --- /dev/null +++ b/project-templates/webdev/.claude/skills/code-quality/SKILL.md @@ -0,0 +1,124 @@ +--- +name: code-quality +description: | + Multi-mode code quality review: blunt critique + static checks + domain-specific patterns. + Use when the user says "review this code", "code review", "quality check", "is this code good", + "find issues in", "check before committing", "review before merging", "lint this", + "is this idiomatic Python/SQL/TypeScript", or wants structured feedback on any code artifact. + Composes with /gbu for the opinionated section, and python-patterns/sql-patterns/ui-ux-pro-max + for domain-specific checks. +argument-hint: "[path/to/file-or-dir | git diff] [--quick | --deep]" +allowed-tools: Read, Glob, Grep, Bash, Agent +--- + +# Code Quality Review + +Multi-mode quality review. Combines blunt critique with static analysis and domain-specific +pattern checks. + +## Modes + +| Mode | When | Depth | +|------|------|-------| +| `--quick` | Single file or function spot-check | GBU + obvious bugs only | +| `--deep` | Module, PR, or directory review | Full: static checks + GBU + domain patterns | +| (default) | Auto-detect: single file → quick, directory or diff → deep | — | + +## Workflow + +### 1. Determine scope + +If an argument is given, read that file or directory. If no argument, review recent changes: + +```bash +git diff --name-only HEAD # files changed since last commit +git diff --name-only main # files changed vs main (for PR review) +``` + +### 2. Static checks (quick wins) + +**Python**: +```bash +ruff check --select E,F --no-fix # syntax + unused imports +``` + +**SQL** (in `.sql` files or embedded in Python): +- `SELECT *` on large tables (missing column specificity) +- `UPDATE`/`DELETE` without `WHERE` clause +- Implicit type coercions or missing index hints + +**TypeScript/JavaScript**: +```bash +npx tsc --noEmit # type errors only, no output +``` + +Skip and note in output if the tool isn't installed. + +### 3. Blunt critique (GBU format) + +Apply `/gbu` semantics to the code under review: + +```markdown +## Good +- What works, is idiomatic, reusable, or well-scoped + +## Bad +- `must` Wrong, broken, or misleading — fix before merging +- `should` Below bar for the goal — fix before shipping +- `could` Style or readability — address when convenient + +## Ugly +- Not broken today but fragile, opaque, or a future cost +``` + +3–7 bullets per section. Anchor each with file path, line number, or short quote. + +### 4. Domain-specific checks + +Apply the relevant domain skill for deeper pattern checks: + +| File type | Skill to apply | +|-----------|----------------| +| `*.py` | `python-patterns` — uv/venv conventions, type hints, test patterns, anti-patterns | +| `*.sql` or SQL strings | `sql-patterns` — query optimization, index hints, safety | +| `*.tsx`, `*.jsx`, UI | `ui-ux-pro-max` — accessibility, responsiveness, component patterns | + +### 5. Output format + +```markdown +## Code Review: + +### Static Checks + + +### Critique (GBU) +#### Good +- ... +#### Bad +- `must` ... +#### Ugly +- ... + +### Domain Findings + + +### Fix Priority +1. [must-fix] +2. [should-fix] +``` + +## Gotchas + +- **Generated files**: skip files with `# generated by`, `# auto-generated`, or `DO NOT EDIT` headers — note and exclude them from review +- **Test files**: apply looser standards — `assert`, magic values, and repetition are acceptable; flag only real bugs and security issues +- **Ruff not installed**: skip static check step and note it; don't abort the review +- **SQL in Python strings**: if no `.sql` files exist, grep for embedded queries: `grep -rn "SELECT\|INSERT\|UPDATE\|DELETE" --include="*.py" ` +- **Scope creep**: review only what was asked — don't audit the whole repo when asked to review one function; expanding scope silently is a failure mode +- **Ugly ≠ Bad**: items that are technically correct but fragile go in Ugly, not Bad; misclassifying these inflates the severity of the review + +## Related + +- `/gbu` — the blunt review engine this skill uses for the critique section +- `python-patterns` skill — Python-specific conventions and idiomatic patterns +- `sql-patterns` skill — SQL query patterns and optimization hints +- `ui-ux-pro-max` skill — UI/UX review checklist for frontend code diff --git a/project-templates/webdev/.claude/skills/debug-session/SKILL.md b/project-templates/webdev/.claude/skills/debug-session/SKILL.md new file mode 100644 index 0000000..450ae61 --- /dev/null +++ b/project-templates/webdev/.claude/skills/debug-session/SKILL.md @@ -0,0 +1,182 @@ +--- +name: debug-session +description: | + Runbook for diagnosing and fixing Claude Code session problems. + Use when: skills aren't triggering, hooks are failing or blocking all tool calls, + context is overloaded (slow responses, repetition), guards are blocking legitimate + commands, plugin cache is corrupt, or the session feels stuck or broken. + Trigger phrases: "why isn't my skill working", "hooks are broken", "all tool calls fail", + "plugin cache", "skill not triggering", "Claude is slow", "context too large", + "guard is blocking", "Claude is stuck", "session is broken". +argument-hint: "[symptom description]" +allowed-tools: Read, Bash, Glob, Grep +--- + +# Debug Session Runbook + +Diagnose and fix Claude Code session problems. Match your symptom, follow the fix. + +## Symptom Index + +| Symptom | Section | +|---------|---------| +| Every tool call fails immediately with a hook error | [Plugin Cache Corruption](#plugin-cache-corruption) | +| Skill invoked (`/skill-name`) but nothing happens | [Skill Not Triggering](#skill-not-triggering) | +| Hook fires but logs an error | [Hook Script Error](#hook-script-error) | +| Slow responses, repetition, losing context | [Context Overload](#context-overload) | +| Guard blocks a command you know is safe | [Guard False Positive](#guard-false-positive) | +| Session breaks after `/clear` or after ~2.5 hours | [Stop Hook Regression](#stop-hook-regression) | + +--- + +## Plugin Cache Corruption + +**Symptom**: Every tool call fails immediately. Error mentions a missing script path under `~/.claude/plugins/cache/`. + +**Cause**: `enabledPlugins` in `settings.json` references plugins that are no longer in cache. + +**Fix sequence — ORDER MATTERS** (wrong order makes it worse): + +1. Clear `enabledPlugins` first: + ```bash + python3 -c " + import json, os + f = os.path.expanduser('~/.claude/settings.json') + s = json.load(open(f)) + s['enabledPlugins'] = {} + json.dump(s, open(f, 'w'), indent=2) + print('enabledPlugins cleared') + " + ``` + +2. Then clear plugin cache: + ```bash + rm -rf ~/.claude/plugins/cache/ + ``` + +3. Reinstall plugins: + ```bash + claude plugin install qute-essentials@qute-marketplace + ``` + +**Why this order**: if you clear the cache while `enabledPlugins` still references plugins, every hook fires and immediately errors — all tool calls fail until fixed. + +--- + +## Skill Not Triggering + +**Symptom**: User types `/skill-name` but Claude ignores it or applies generic behavior. + +**Diagnosis steps**: + +1. Verify the skill file exists in the project: + ```bash + ls .claude/skills/skill-name/SKILL.md + ``` + +2. Check `forced-eval` hook is active (required for reliable skill activation): + ```bash + grep -r "forced" ~/.claude/plugins/cache/qute-marketplace/qute-essentials/*/hooks/hooks.json + ``` + +3. Read the skill's `description` field — does it contain clear trigger phrases matching the user's exact wording? + +**Fixes**: +- Missing skill file → copy from `claude/skills/skill-name/` or re-run `setup-project.sh` +- `forced-eval` absent → reinstall qute-essentials: `claude plugin install qute-essentials@qute-marketplace` +- Weak description → edit the `description:` frontmatter in `SKILL.md` to add more trigger phrases in the user's language + +--- + +## Hook Script Error + +**Symptom**: A hook fires but logs a Python error or missing-file error. Tool call may be blocked or proceed with a warning. + +**Diagnosis**: +```bash +# Validate hooks.json is valid JSON +python3 -m json.tool ~/.claude/plugins/cache/qute-marketplace/qute-essentials/*/hooks/hooks.json + +# List scripts to verify paths +ls ~/.claude/plugins/cache/qute-marketplace/qute-essentials/*/scripts/ + +# Test a suspect script directly +python3 ~/.claude/plugins/cache/qute-marketplace/qute-essentials/*/scripts/suspect-script.py +``` + +**Common causes**: +- Script path in `hooks.json` doesn't match actual filename (e.g., `track_edits.py` renamed to `doc_reminder.py`) +- Python script has a syntax error — run it directly to see the traceback +- Missing import — the script requires a package not in PATH + +--- + +## Context Overload + +**Symptom**: Responses slow down, Claude repeats itself, loses track of earlier instructions, or context window warning appears. + +**Options in order of disruption**: + +| Option | Command | When | +|--------|---------|------| +| Summarize in-place | `/compact` | Still in flow, just bulky context | +| Structured transition | `/handoff "what I was doing"` → new session → `/pickup` | Natural stopping point, multi-day work | +| Quick resume | `claude -c` | Short break, simple continuation | + +**Signs context is the problem (not skill or hook issues)**: +- Same question answered differently than 30 messages ago +- Claude forgets a constraint set early in the session +- Tool calls taking noticeably longer than at session start + +--- + +## Guard False Positive + +**Symptom**: A security guard blocks a shell command or file write you know is safe. + +**Diagnosis**: +``` +/guard status +``` + +**Temporary fix**: +``` +/guard off +# ... do your operation ... +/guard on +``` + +**Guards most likely to false-positive**: + +| Guard | Common false positive | +|-------|----------------------| +| `destructive` | `rm -rf dist/`, `git reset --hard` on clean feature branch | +| `secrets` | Test fixtures with fake API key patterns | +| `malware` | Minified JS or base64-encoded assets in source files | + +--- + +## Stop Hook Regression + +**Symptom**: After `/clear` or after ~2.5 hours, end-of-session hooks stop firing (e.g., handoff not auto-created). + +**Cause**: Known Claude Code regression — `Stop` event hooks fire once then break after `/clear` and after extended sessions. + +**Workaround**: Don't rely on stop hooks for critical end-of-session actions. Always call `/handoff` explicitly before ending a session. + +--- + +## Gotchas + +- **Never clear plugin cache without first clearing `enabledPlugins`** — this is the #1 cause of catastrophic hook failures +- **Settings changes require a Claude Code restart** — edits to `settings.json` are not hot-reloaded; hooks are cached at session start +- **`CLAUDE_SKIP_GUARDS=1` bypasses ALL guards** — never set this in `.env` or shell profile permanently +- **`git worktree remove` fails on uncommitted changes** — stash or commit first; the error is non-obvious +- **After `claude plugin uninstall`, re-run `claude plugin install`** — uninstall clears the cache; the plugins entry in settings.json must also be updated + +## Related + +- `/guard` — toggle security guards, diagnose false positives +- `/guard status` — show current guard state including API key presence +- `/handoff` — proper session-end that survives stop hook regressions +- `/pickup` — load last handoff at session start diff --git a/project-templates/webdev/.claude/skills/gist-report/SKILL.md b/project-templates/webdev/.claude/skills/gist-report/SKILL.md index 2c0d042..c0755de 100644 --- a/project-templates/webdev/.claude/skills/gist-report/SKILL.md +++ b/project-templates/webdev/.claude/skills/gist-report/SKILL.md @@ -86,6 +86,24 @@ The template includes pre-built components. Just use these in your body HTML:
Source: link text — Generated by Claude Code
``` +## Transcript Mode + +Upload the current session transcript as a GitHub Gist (JSON format): + +```bash +uvx claude-code-transcripts json --gist "$(ls -t ~/.claude/projects/$(pwd | tr '/' '-')/*.jsonl | head -1)" +``` + +Returns a single gist URL. The gist contains the full conversation — user messages, assistant responses, tool calls, and timestamps. + +**Before sharing**: the transcript includes all tool output as-is; review it if the session touched credentials or sensitive data. + +| Issue | Fix | +|-------|-----| +| "No such file" | No session files found — ensure you're in a project directory | +| gh auth error | Run `gh auth login` to authenticate | +| Empty transcript | Session just started — need at least one exchange | + ## Rules 1. **Write body HTML only** — never include ``, ``, ``, or `