darkroomengineering · arzafran · Jun 3, 2026 · Jun 3, 2026
diff --git 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
@@ -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
@@ -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
@@ -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,15 +480,14 @@ 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 |
 | Pre-compact | Auto-handoff save |
 | 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
diff --git 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.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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.