From 96a39eb8cdd5ebfb52cc025a4767b67d6234bd9a Mon Sep 17 00:00:00 2001 From: arzafran Date: Wed, 3 Jun 2026 12:44:43 -0300 Subject: [PATCH] docs: post-session accuracy pass + remove redundant USAGE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bring all docs in line with the current 34-skill roster and this session's removals (upstream-sync cron, TLDR telemetry). - skill counts → 34 (CLAUDE-FULL, CLAUDE, MANUAL) - purge retired/merged skill names (ask, premortem, compare-approaches, discovery, prd, create-handoff, resume-handoff, long-task, lenis, audit, versions) from MANUAL, skills/README, frontmatter-reference, github-workflow, agents/maestro, skills/checkpoint - add missing skills (freeze, plan-ceo-review, retro, strategist) to MANUAL - remove deleted TLDR telemetry hook rows (MANUAL, hooks-reference) - regenerate frontmatter-reference fork/main/inherit lists + agent-delegation table from on-disk frontmatter ground truth - remove USAGE.md: uninstalled, unlinked onboarding doc duplicating MANUAL.md that drifted repeatedly - remove two empty local dirs No source/behavior changes. lint, lint:skills, typecheck green. --- CHANGELOG.md | 1 + CLAUDE-FULL.md | 2 +- CLAUDE.md | 2 +- MANUAL.md | 10 +- USAGE.md | 274 ---------------------------------- agents/maestro.md | 4 +- docs/frontmatter-reference.md | 44 +++--- docs/github-workflow.md | 3 +- docs/hooks-reference.md | 3 +- skills/README.md | 21 +-- skills/checkpoint/SKILL.md | 2 +- 11 files changed, 46 insertions(+), 320 deletions(-) delete mode 100644 USAGE.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 9279309..95e5ba8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ All notable changes to cc-settings are documented here. ### Changed +- **Docs accuracy pass (post-session).** Skill counts updated to 34 across `CLAUDE-FULL.md`, `CLAUDE.md`, and `MANUAL.md`. Dead skill names (`ask`, `premortem`, `compare-approaches`, `discovery`, `prd`, `create-handoff`, `resume-handoff`, `long-task`, `lenis`, `audit`, `versions`) removed from `MANUAL.md`, `skills/README.md`, `docs/frontmatter-reference.md`. Added missing skills (`freeze`, `plan-ceo-review`, `retro`, `strategist`) to the MANUAL.md All Skills table. Removed deleted TLDR telemetry hook rows from `MANUAL.md` and `docs/hooks-reference.md` (`track-tldr`, `mcp__tldr`). Regenerated fork/main/inherit skill lists and agent-delegation table in `docs/frontmatter-reference.md` to match ground truth. Fixed retired-skill references (`/compare-approaches`, `/long-task`) in `agents/maestro.md` and `docs/github-workflow.md`. **Removed `USAGE.md`** — an uninstalled, unlinked onboarding doc that duplicated `MANUAL.md` and had drifted badly (its skill tables had been swept for dead names repeatedly; the recurring drift was the signal it was redundant). Also removed two empty local dirs (`.claude/worktrees`, `.claude/agent-memory/oracle`). - **Retired the automated upstream-sync cron in favor of manual `/cc sync`.** The daily GitHub Action (`.github/workflows/upstream-sync.yml`) and the `--open-pr` path in `src/upstream/scan.ts` only ever bumped a version number and dumped the drift string into a PR body. The scanner's `diffSets` compares the manifest against cc-settings' *own* zod schema — never upstream — and it never fetched the changelog, so it was structurally blind to new features, settings keys, env vars, hook events, and dedupe opportunities. That triage is the human-reviewed skill's job; the bot's PRs looked actionable but weren't, and raced the manual flow. Removing it also avoids a standing CI credential (making the cron *smarter* would have meant baking an `ANTHROPIC_API_KEY`/OAuth token into repo secrets and burning it unattended on every release). - **Removed** — `.github/workflows/upstream-sync.yml`; `openSyncPr`/`saveManifest` and the `--open-pr` branch in `src/upstream/scan.ts` (now a pure dry-run detector, no `writeFile`/`runProcessFull` imports); stale "daily GH Action"/"bot owns this file" references in the manifest `description`/`source`, `skills/cc/SKILL.md`, `src/schemas/skill.ts`, and the `.github/workflows/ci.yml` `upstream-scan` comment. - **Kept** — `bun run upstream:scan` (the dry-run detector) and its non-gating CI job, now the manual way to spot drift before running `/cc sync`. diff --git a/CLAUDE-FULL.md b/CLAUDE-FULL.md index 4c7bc7b..cf5c04d 100644 --- a/CLAUDE-FULL.md +++ b/CLAUDE-FULL.md @@ -129,4 +129,4 @@ Full threat model + remediation: see `SECURITY.md`. ### Skill library soft cap — 40 -Anthropic's Skills guide flags 20–50 skills as the point where the Skill selector starts struggling to read every description per turn. We sit at 31 cc-settings skills (Tier P1 cleanup May 2026: retired `audit`, `lenis`; merged `create-handoff`+`resume-handoff` → `handoff`, `discovery`+`prd` → `plan-feature`, `ask`+`premortem`+`compare-approaches` → `oracle`, `tdd` folded into `test`, `cc-sync`+`cc-update` → `cc`; folded `long-task` into `orchestrate`; demoted `write-a-skill` to `bun run new-skill` CLI; `nuclear-review` ported from Cursor team-kit May 2026; `share-learning` revived May 2026; `proof-of-work` + `review-batch` added May 2026 from the Orchestration Tax; `freeze` edit-scope lock ported from gstack June 2026). **Adding a new skill past 40 requires removing one** — re-evaluate `skills/` for consolidation candidates first. Validate the library with `bun run lint:skills`, which enforces the spec (kebab-case folders, frontmatter contract, no angle brackets, …) and surfaces the cap as a warning when crossed. Drift hides easily; let the linter catch it. +Anthropic's Skills guide flags 20–50 skills as the point where the Skill selector starts struggling to read every description per turn. We sit at 34 cc-settings skills (Tier P1 cleanup May 2026: retired `audit`, `lenis`; merged `create-handoff`+`resume-handoff` → `handoff`, `discovery`+`prd` → `plan-feature`, `ask`+`premortem`+`compare-approaches` → `oracle`, `tdd` folded into `test`, `cc-sync`+`cc-update` → `cc`; folded `long-task` into `orchestrate`; demoted `write-a-skill` to `bun run new-skill` CLI; `nuclear-review` ported from Cursor team-kit May 2026; `share-learning` revived May 2026; `proof-of-work` + `review-batch` added May 2026 from the Orchestration Tax; `freeze` edit-scope lock ported from gstack June 2026). **Adding a new skill past 40 requires removing one** — re-evaluate `skills/` for consolidation candidates first. Validate the library with `bun run lint:skills`, which enforces the spec (kebab-case folders, frontmatter contract, no angle brackets, …) and surfaces the cap as a warning when crossed. Drift hides easily; let the linter catch it. diff --git a/CLAUDE.md b/CLAUDE.md index d0fa42a..764d88d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -17,7 +17,7 @@ for standards. ## About This Repo -**TypeScript on Bun** (migrated from bash in April 2026; see git log for history). Runtime: `bun >=1.1.30`. Skills: 31 cc-settings skills (Tier P1 cleanup May 2026: retired 3, merged 7 pairs into 4, demoted 1 to CLI; `nuclear-review` ported from Cursor team-kit May 2026; share-learning revived May 2026; `freeze` edit-scope lock ported from gstack June 2026). +**TypeScript on Bun** (migrated from bash in April 2026; see git log for history). Runtime: `bun >=1.1.30`. Skills: 34 cc-settings skills (Tier P1 cleanup May 2026: retired 3, merged 7 pairs into 4, demoted 1 to CLI; `nuclear-review` ported from Cursor team-kit May 2026; share-learning revived May 2026; `freeze` edit-scope lock ported from gstack June 2026). Deps: `zod`, `@inquirer/confirm`, `yaml`. Dev: `@biomejs/biome`, `typescript`, `@types/bun`. diff --git a/MANUAL.md b/MANUAL.md index acd3c22..6f5e27c 100644 --- a/MANUAL.md +++ b/MANUAL.md @@ -35,7 +35,7 @@ You'll be asked to pick a starter — **satus** (Next.js, content sites) or **no | *"review my changes"* | `/review` — checks against TypeScript / React / a11y / performance rules | | *"audit my recent activity"* | `bun ~/.claude/src/scripts/claude-audit.ts` — analyzes Bash command logs | -**4. Don't memorize skills.** Just talk normally. The `Skill` tool auto-matches the right one. To see all 30 cc-settings skills, scroll to [All Skills](#all-skills) below. (Native Claude Code skills like `/loop`, `/schedule`, `/code-review`, `/review`, `/init`, `/security-review`, and any plugins like `sanity:*` or `vercel:*` load in addition — your session typically sees 60–80 skills total.) +**4. Don't memorize skills.** Just talk normally. The `Skill` tool auto-matches the right one. To see all 34 cc-settings skills, scroll to [All Skills](#all-skills) below. (Native Claude Code skills like `/loop`, `/schedule`, `/code-review`, `/review`, `/init`, `/security-review`, and any plugins like `sanity:*` or `vercel:*` load in addition — your session typically sees 60–80 skills total.) **5. When something is unclear**, ask Claude directly: *"what skill handles X?"* or *"what just changed in cc-settings?"*. The setup is self-describing. @@ -445,6 +445,11 @@ These are enforced automatically — no skill needed: | `cc` | sync with claude code, changelog sync, update cc-settings, upgrade cc-settings, pull the latest | | `context-doc` | domain glossary, ADR, shared vocabulary, context doc | | `autoresearch` | autoresearch, optimize skill, improve skill prompt | +| `share-learning` | share this learning, post to team knowledge, team-wide finding | +| `freeze` | freeze edits, lock editing scope, restrict edits to, only edit this folder, unfreeze | +| `plan-ceo-review` | ceo review, founder review, product review, is this the right approach, should we even build this | +| `retro` | retro, retrospective, weekly review, how was my week, engineering metrics, what did I ship | +| `strategist` | strategist, product strategy, market positioning, what should we build, product direction | ### All Agents @@ -475,7 +480,6 @@ Hook types: `command` (shell), `prompt` (LLM yes/no), `agent` (subagent with too | Pre-tool (Edit) | Stale file detection | | Permission request | When a tool needs user permission | | Post-tool (Write/Edit) | Post-edit validation, async TSC | -| Post-tool (TLDR) | Usage tracking | | Post-tool (Bash) | Command audit log | | Post-tool (all) | Consecutive non-Agent call counter (`parallelmax-nudge.ts`) | | Tool failure | Failure tracking | @@ -483,7 +487,7 @@ Hook types: `command` (shell), `prompt` (LLM yes/no), `agent` (subagent with too | Post-compact | After context compaction completes | | Stop | Learning reminder (`stop-summary.ts`) | | Stop failure | Turn ends due to API error (rate limit, auth failure) | -| Session end | TLDR stats, auto-handoff | +| Session end | Auto-handoff | | Subagent start/stop | Swarm logging | | Teammate idle | Agent Teams teammate goes idle | | Task completed | Task marked completed | diff --git a/USAGE.md b/USAGE.md deleted file mode 100644 index 7c3d3e3..0000000 --- a/USAGE.md +++ /dev/null @@ -1,274 +0,0 @@ -# Usage Guide - -Progressive onboarding for Darkroom's Claude Code configuration. - -**Start simple. Scale up when you feel friction.** - ---- - -## Level 0: Just Installed - -After running setup, restart Claude Code. That's it. - -Talk naturally. The system recognizes intent and invokes the right tools: - -``` -"Fix the broken auth" → explores, fixes, tests -"Build a dashboard" → plans, scaffolds, implements -"How does the cart work?" → explores codebase, returns summary -"Review my changes" → runs code review -"Done for today" → saves session state for next time -``` - -No commands to memorize. No configuration to tweak. - ---- - -## Level 1: Guardrails - -Read `AGENTS.md` in your project root. It contains the coding standards and guardrails that protect you: - -### The Big Ones - -- **2-iteration limit**: If something fails twice, Claude stops and presents alternatives instead of burning context on the same broken approach -- **Bug fix scope**: When fixing a bug, Claude stays in the relevant files — no drive-by refactoring -- **Verify after fix**: Build runs after every fix, before moving on -- **Never fake measurements**: No fabricated Lighthouse scores or test results -- **Pre-commit checks**: Type checking + build + tests must pass before any commit - -### Autonomous Execution - -Claude proceeds without asking for non-destructive operations: -- Reading files, searching code, exploring architecture -- Running git status, git log, git diff -- Fetching documentation - -Claude asks before destructive or irreversible actions. - ---- - -## Level 2: Skills - -Skills auto-invoke based on your words. You can also call them directly with `/skill`: - -### Workflows (Multi-Agent) - -| Trigger | Skill | What Happens | -|---------|-------|--------------| -| "fix", "broken", "bug" | `fix` | explore → implement → test | -| "build", "create", "add feature" | `build` | plan → scaffold → implement | -| "refactor", "clean up" | `refactor` | explore → implement → review | -| "review", "check", "PR" | `review` | reviewer agent | -| "test", "coverage" | `test` | tester agent | -| "ship it", "create PR" | `ship` | test → review → PR | -| "coordinate", "complex task" | `orchestrate` | maestro multi-agent delegation | -| "new project", "initialize" | `init` | scaffolds from Satus starter template | -| "compare approaches", "which is better" | `compare-approaches` | parallel evaluation → scoring matrix | -| "overnight", "long running" | `long-task` | phased execution with checkpoints | - -### Research - -| Trigger | Skill | -|---------|-------| -| "how does X work?", "find X" | `explore` | -| "docs for X", "API reference" | `docs` | -| "who calls X?", "dependencies" | `tldr` | -| "what could go wrong?" | `premortem` | -| "advice on X" | `ask` | -| "project status", "update the issue" | `project` — syncs with GitHub Issues and Projects | -| "help me figure out", "define requirements" | `discovery` — structured requirements interview | -| "PRD", "product spec", "feature spec" | `prd` — generates product requirements document | - -### Session Management - -| Trigger | Skill | -|---------|-------| -| "done for today", "context window", "running out of context" | `create-handoff` — end-of-session state save (incl. context-window runbook) | -| "resume", "continue" | `resume-handoff` — loads previous state | -| Non-obvious bug fix discovered | `learn` — **auto-stores** the insight | -| "snapshot", "before risky op", "rollback to" | `checkpoint` — mid-task rollback points | - -### Tools - -| Trigger | Skill | -|---------|-------| -| "compare to design", "inspect in figma" | `figma` — Figma desktop + MCP integration | -| screenshot, visual bug | `chrome-devtools` MCP — `mcp__chrome-devtools__*` tools, no dedicated slash command | -| "QA check", accessibility | `qa` — visual QA validation | -| "design tokens", "type scale", "color palette" | `design-tokens` — generates token systems with math | -| "smooth scroll", "lenis" | `lenis` — Lenis smooth scroll setup | -| "create hook", "custom hook" | `hook` — scaffolds React hook with standards | -| "lighthouse", "page speed", "core web vitals" | `lighthouse` — performance audit + optimization loop | - -### Utility - -| Trigger | Skill | -|---------|-------| -| "create component X" | `component` — scaffolds with standards | -| "parallel agents", "split work", "fan out" | `orchestrate` (teams mode) — multi-instance parallel work | -| "verify", "double check", "are you sure" | `verify` — adversarial multi-agent verification | -| "consolidate", "clean up rules", "maintenance" | `consolidate` — prunes rules, skills, learnings | -| "audit commands", "what did it run" | `audit` — analyzes logged Bash commands | -| "optimize skill", "autoresearch" | `autoresearch` — iterative skill prompt optimization | - ---- - -## Level 3: Agents - -For complex tasks, delegate to specialized agents: - -``` -Agent(explore, "how does the auth module work?") -Agent(planner, "break down the checkout redesign") -Agent(implementer, "implement coupon validation based on the plan") -Agent(reviewer, "review these changes for quality and edge cases") -Agent(tester, "write tests for the payment module") -Agent(security-reviewer, "audit the auth flow for vulnerabilities") -``` - -### When to Delegate - -| Situation | Approach | -|-----------|----------| -| Know the file, small change | Edit directly | -| Need to understand a large area | `Agent(explore, "...")` | -| Multi-file implementation | `Agent(planner, "...")` then `Agent(implementer, "...")` | -| Need a second opinion | `Agent(reviewer, "...")` | -| 3+ independent workstreams | Use Agent Teams | - -### Parallelization - -When spawning multiple agents for independent work, send all Agent calls in one message: - -``` -EFFICIENT: Agent(explore, "auth") + Agent(explore, "routing") ← one message -WASTEFUL: Agent(explore, "auth") → wait → Agent(explore, "routing") ← two messages -``` - ---- - -## Level 4: Full Orchestration - -For power users who want maximum delegation. Activate the maestro profile: - -``` -/profile maestro -``` - -In maestro mode: -- Every request gets delegated to agents -- Parallel pipelines for independent work -- TLDR-first exploration (95% token savings on large codebases) -- Agent Teams for 3+ independent workstreams - -See `profiles/maestro.md` for the full workflow. - ---- - -## TLDR Exploration - -When working with large codebases, TLDR provides token-efficient exploration: - -```bash -tldr context functionName --project . # Understand a function (vs reading the whole file) -tldr semantic "authentication flow" . # Search by meaning (vs grep) -tldr impact functionName . # Who calls this? (vs manual tracing) -tldr arch . # Architecture overview -tldr slice file.ts func 42 # What affects this line? -``` - -Use TLDR when files are large or you need meaning-based search. Use Read/Grep for exact content or small files. - ---- - -## Knowledge System - -### Local (Default) - -```bash -# Store a learning (auto-invoked when Claude discovers something) -/learn store bug "useAuth causes hydration — use dynamic import" -/learn store pattern "Wrap async server components in Suspense" - -# Recall -/learn recall all -/learn recall category bug -/learn recall search hydration -``` - -### Shared (Team Knowledge Base) - -```bash -# Post to the team-knowledge repo (handles dedup automatically) -/share-learning gotcha "Biome ignores .mdx files by default" -/share-learning decision "Chose Lenis over native smooth-scroll" - -# Recall shared knowledge (requires local clone at $KNOWLEDGE_REPO_PATH) -cat $KNOWLEDGE_REPO_PATH/INDEX.md -rg "biome" $KNOWLEDGE_REPO_PATH/ -``` - -See `docs/knowledge-system.md` for setup. - ---- - -## Context Management - -Watch the statusline for context usage: - -``` -Opus 4.8 | my-project | main✱↑ | █░░░░░░░░░ 8% (84k/1.0M) -``` - -| Usage | Action | -|-------|--------| -| 70-79% | Consider wrapping up or handing off | -| 80-89% | Start wrapping up | -| 90%+ | Run `/create-handoff` now | - ---- - -## Ecosystem Contexts - -Switch contexts for different platforms: - -```bash -/context web # Next.js, React, Tailwind (default) -/context webgl # R3F, Three.js, GSAP, shaders -/context desktop # Tauri (Rust + Web) -/context mobile # Expo (React Native) -``` - ---- - -## Example Session - -``` -# Start -"Resume where we left off" -→ Loads: "Working on checkout, coupon validation pending" - -# Understand -"How does the cart work?" -→ explore agent: returns summary with file:line citations - -# Plan -"Add coupon codes to checkout" -→ planner: breaks into 4 tasks - -# Build -"Start with the coupon API" -→ scaffolder + implementer + tester - -# Review -"Review my changes" -→ reviewer: checks quality, suggests edge cases - -# Ship -"Ship it" -→ runs tests, creates PR - -# End -"Done for today" -→ Handoff: "Completed coupon validation. Next: cart integration" -``` diff --git a/agents/maestro.md b/agents/maestro.md index fe095c6..b29f6c4 100644 --- a/agents/maestro.md +++ b/agents/maestro.md @@ -239,8 +239,8 @@ Select thread type based on task shape: - **B** (Base): Simple, < 3 steps → single agent - **P** (Parallel): Independent parts → spawn all in one message - **C** (Chained): Sequential dependencies → pipeline agents -- **F** (Fusion): Compare approaches → `/compare-approaches` -- **L** (Long-duration): Exceeds context window → `/long-task` +- **F** (Fusion): Compare approaches → `/oracle` (compare mode) +- **L** (Long-duration): Exceeds context window → `/orchestrate` Quick decision: Simple? → B. Independent parts? → P. Sequential? → C. Comparison? → F. Long? → L. diff --git a/docs/frontmatter-reference.md b/docs/frontmatter-reference.md index f5c227d..f6b92ea 100644 --- a/docs/frontmatter-reference.md +++ b/docs/frontmatter-reference.md @@ -128,9 +128,11 @@ Skills define slash commands (e.g., `/docs`, `/explore`) that users invoke direc | `fork` | Creates an isolated sub-context. Output is summarized and returned to parent. Does not bloat main context. | Exploration, docs fetching, analysis tasks | | `inherit` | Shares context with the parent conversation. | Skills that need to modify the current session state | -Skills using `fork`: `ask`, `autoresearch`, `build`, `checkpoint`, `compare-approaches`, `consolidate`, `design-tokens`, `discovery`, `explore`, `fix`, `lighthouse`, `long-task`, `orchestrate`, `prd`, `premortem`, `qa`, `refactor`, `review`, `ship`, `test`, `tldr`, `verify`. +Skills using `fork` (21): `autoresearch`, `build`, `checkpoint`, `consolidate`, `design-tokens`, `explore`, `fix`, `handoff`, `lighthouse`, `oracle`, `orchestrate`, `plan-ceo-review`, `plan-feature`, `qa`, `refactor`, `retro`, `review`, `ship`, `test`, `tldr`, `verify`. -Skills using `inherit` (default): `audit`, `component`, `create-handoff`, `dr-init`, `hook`, `lenis`, `project`, `resume-handoff`, `share-learning`, `versions`. +Skills using `main` (3): `freeze`, `nuclear-review`, `zero-tech-debt`. + +Skills using `inherit` (default, 10): `cc`, `component`, `context-doc`, `dr-init`, `hook`, `project`, `proof-of-work`, `review-batch`, `share-learning`, `strategist`. ### Agent Delegation @@ -138,11 +140,10 @@ When `agent` is specified, the skill routes execution to that agent instead of r | Skill | Delegates to Agent | |-------|--------------------| -| `ask` | `oracle` | -| `discovery` | `planner` | | `explore` | `explore` | +| `oracle` | `explore` | | `orchestrate` | `maestro` | -| `premortem` | `oracle` | +| `plan-feature` | `planner` | | `review` | `reviewer` | | `test` | `tester` | @@ -177,12 +178,13 @@ argument-hint: "[save|restore|list] [name]" ```yaml --- -name: docs +name: autoresearch description: | - Fetch latest documentation for libraries and frameworks. - CRITICAL - AUTO-INVOKE when user wants to implement with ANY external library. + Optimize or improve a skill prompt via automated research. + CRITICAL - AUTO-INVOKE when user says "autoresearch", "optimize skill", "improve skill prompt". context: fork -allowed-tools: [mcp__context7__resolve-library-id, mcp__context7__get-library-docs, WebFetch, WebSearch] +allowed-tools: [Read, Grep, Glob, Bash] +argument-hint: "" --- ``` @@ -190,38 +192,40 @@ allowed-tools: [mcp__context7__resolve-library-id, mcp__context7__get-library-do | Skill | Context | Agent | Allowed Tools | Argument Hint | |-------|---------|-------|---------------|---------------| -| `ask` | fork | oracle | -- | -- | -| `audit` | -- | -- | -- | -- | | `autoresearch` | fork | -- | -- | `` | | `build` | fork | -- | -- | -- | +| `cc` | -- | -- | -- | -- | | `checkpoint` | fork | -- | Bash | -- | -| `compare-approaches` | fork | -- | -- | -- | | `component` | -- | -- | -- | -- | | `consolidate` | fork | -- | -- | -- | -| `create-handoff` | -- | -- | -- | -- | +| `context-doc` | -- | -- | -- | -- | | `design-tokens` | fork | -- | -- | -- | -| `discovery` | fork | planner | -- | -- | | `dr-init` | -- | -- | -- | `[project-name]` | | `explore` | fork | explore | -- | -- | | `fix` | fork | -- | -- | -- | +| `freeze` | main | -- | Bash, AskUserQuestion | -- | +| `handoff` | fork | -- | -- | -- | | `hook` | -- | -- | -- | -- | -| `lenis` | -- | -- | -- | -- | | `lighthouse` | fork | -- | Bash, Read, Write, Edit, MultiEdit, Grep, Glob, LS | `` | -| `long-task` | fork | -- | -- | -- | +| `nuclear-review` | main | -- | -- | -- | +| `oracle` | fork | explore | -- | -- | | `orchestrate` | fork | maestro | -- | -- | -| `prd` | fork | -- | -- | -- | -| `premortem` | fork | oracle | -- | -- | +| `plan-ceo-review` | fork | -- | Read, Grep, Glob, Bash, AskUserQuestion | -- | +| `plan-feature` | fork | planner | -- | -- | | `project` | -- | -- | -- | -- | +| `proof-of-work` | -- | -- | -- | -- | | `qa` | fork | -- | Bash | -- | | `refactor` | fork | -- | -- | -- | -| `resume-handoff` | -- | -- | -- | -- | +| `retro` | fork | -- | Bash, Read, Write, Glob | -- | | `review` | fork | reviewer | -- | -- | +| `review-batch` | -- | -- | -- | -- | | `share-learning` | -- | -- | -- | -- | | `ship` | fork | -- | -- | -- | +| `strategist` | -- | -- | Read, Grep, Glob, Bash | -- | | `test` | fork | tester | -- | -- | | `tldr` | fork | -- | -- | -- | | `verify` | fork | -- | -- | -- | -| `versions` | -- | -- | -- | -- | +| `zero-tech-debt` | main | -- | -- | -- | --- diff --git a/docs/github-workflow.md b/docs/github-workflow.md index 46caf46..ee683b6 100644 --- a/docs/github-workflow.md +++ b/docs/github-workflow.md @@ -134,8 +134,7 @@ Use Projects for the big picture. Use Issues for the actual plan. Don't conflate | Skill | GitHub Integration | |-------|-------------------| | `/project` | Reads linked issue on session start, updates on end | -| `/create-handoff` | Posts progress comment on linked issue | -| `/resume-handoff` | Reads linked issue as primary context source | +| `/handoff` | Posts progress comment on linked issue; also loads previous state on resume | | `/share-learning` | Stores team knowledge in the team-knowledge repo | | `/build`, `/fix` | Can reference issue tasks for scope | diff --git a/docs/hooks-reference.md b/docs/hooks-reference.md index 49808f7..ea39832 100644 --- a/docs/hooks-reference.md +++ b/docs/hooks-reference.md @@ -241,7 +241,6 @@ Matchers filter which specific tool invocations or events trigger a hook. | `Edit` | File edit operations | | `Write\|Edit` | Either writes or edits | | `Read` | File read operations | -| `mcp__tldr` | TLDR MCP server tool calls | ### Matcher Values for SubagentStart/SubagentStop @@ -347,7 +346,7 @@ Matchers filter which specific tool invocations or events trigger a hook. |--------|---------|-------| | `log-bash.ts` | Logs every Bash command to `~/.claude/logs/bash-YYYY-MM-DD.log` | Yes | -Logs are used by the `/audit` skill (`claude-audit.ts`) to analyze command patterns, security concerns, and repeated commands. Hook receives JSON on stdin with `tool_input.command`. +Logs are used by `bun ~/.claude/src/scripts/claude-audit.ts` to analyze command patterns, security concerns, and repeated commands. Hook receives JSON on stdin with `tool_input.command`. **Log format:** `[HH:MM:SS] [project] command` diff --git a/skills/README.md b/skills/README.md index 04521b7..e178963 100644 --- a/skills/README.md +++ b/skills/README.md @@ -27,10 +27,10 @@ Claude automatically: | "How does auth work?" | `explore` | Codebase investigation, returns summary | | "Review my changes" | `review` | Code review against Darkroom standards | | "Create a Button component" | `component` | Scaffolds component with CSS module | -| "What could go wrong?" | `premortem` | Risk analysis before implementing | +| "What could go wrong?" | `oracle` | Risk analysis before implementing | | "Double check this is correct" | `verify` | finder → adversary → referee | | "Clean up our rules" | `consolidate` | Audit and merge rules/skills/learnings | -| "Done for today" | `create-handoff` | Saves session state | +| "Done for today" | `handoff` | Saves session state | ## Skill Categories @@ -46,8 +46,6 @@ These fork context and delegate to specialized agents: | `test` | test, write tests, coverage | tester | | `orchestrate` | complex task, coordinate | maestro | | `ship` | ship it, create PR, /pr, /ship | tester → reviewer → implementer | -| `compare-approaches` | compare approaches, architecture decision | parallel oracles → scoring matrix | -| `long-task` | overnight, long running, autonomous task | phased execution with checkpoints | | `verify` | verify, double check, prove it, adversarial, audit | finder → adversary → referee | ### Creation (Direct Output) @@ -66,23 +64,19 @@ These fork context for clean exploration: | Skill | Triggers On | |-------|-------------| | `explore` | how does, where is, find, understand, zoom out, bigger picture, where does this fit | -| `ask` | advice, guidance, what should I | +| `oracle` | advice, guidance, what should I, risks, what could go wrong, compare approaches | | `tldr` | who calls, dependencies, semantic search | -| `premortem` | risks, what could go wrong | -| `discovery` | requirements, scope, figure out | -| `prd` | PRD, requirements document, product spec | +| `plan-feature` | requirements, scope, figure out, PRD, requirements document, product spec | | `project` | project status, update the issue, sync with github, show my tasks | ### Tools | Skill | Triggers On | |-------|-------------| | `qa` | visual QA, accessibility, contrast, touch target | -| `lenis` | smooth scroll, lenis setup | ### Utility | Skill | Triggers On | |-------|-------------| -| `audit` | /audit — analyzes Claude's Bash command log (categories, security, repeats) | | `consolidate` | clean up rules, simplify config, contradictions, spa day, prune | ### Session Management @@ -90,8 +84,7 @@ These fork context for clean exploration: |-------|-------------| | `share-learning` | explicit invocation for team-wide learnings (personal/local notes go to auto-memory) | | `checkpoint` | snapshot, before risky op, rollback to | -| `create-handoff` | done for today, ending session, context window, running out of context | -| `resume-handoff` | resume, continue, last session | +| `handoff` | done for today, ending session, context window, running out of context, resume, continue, last session | ### The `share-learning` Skill (Manual, Team-Only) @@ -155,9 +148,9 @@ allowed-tools: [...] # Restrict available tools |-----------|---------|--------| | 70-79% | Notice | Save checkpoint, consider handoff | | 80-89% | Warning | Save checkpoint + commit work, create handoff soon | -| 90%+ | **Critical** | Save checkpoint, `create-handoff` auto-suggested | +| 90%+ | **Critical** | Save checkpoint, `handoff` auto-suggested | -> Checkpoints (`/checkpoint save`) are lightweight task snapshots. Handoffs (`/create-handoff`) are full session transfers. Use both at thresholds. +> Checkpoints (`/checkpoint save`) are lightweight task snapshots. Handoffs (`/handoff`) are full session transfers. Use both at thresholds. ## Legacy diff --git a/skills/checkpoint/SKILL.md b/skills/checkpoint/SKILL.md index ec8a044..f21807a 100644 --- a/skills/checkpoint/SKILL.md +++ b/skills/checkpoint/SKILL.md @@ -1,6 +1,6 @@ --- name: checkpoint -description: Mid-task rollback points — save/restore state before risky ops (refactors, migrations, destructive edits). For end-of-session save use `/create-handoff`. Triggers "checkpoint", "snapshot", "before this risky op", "rollback to", "list checkpoints", pre-refactor save. +description: Mid-task rollback points — save/restore state before risky ops (refactors, migrations, destructive edits). For end-of-session save use `/handoff`. Triggers "checkpoint", "snapshot", "before this risky op", "rollback to", "list checkpoints", pre-refactor save. context: fork allowed-tools: [Bash] ---