worclaude 1.0.0

package/templates/skills/universal/claude-md-maintenance.md

@@ -0,0 +1,110 @@
+---
+description: "How Claude writes rules for itself, when to update CLAUDE.md, keeping it lean and effective"
+---
+
+# CLAUDE.md Maintenance
+
+## The Self-Healing Pattern
+
+When Claude makes the same mistake twice, it should update CLAUDE.md to prevent a
+third occurrence. This is "self-healing" — the system learns from its errors.
+
+The cycle:
+1. Claude makes mistake X
+2. User corrects Claude
+3. Claude makes mistake X again
+4. Claude (or user) adds a rule to CLAUDE.md: "Don't do X. Do Y instead."
+5. Mistake X doesn't happen again
+
+This is why the Gotchas section exists. It grows organically from real problems
+encountered during development.
+
+## The 50-Line Target
+
+CLAUDE.md should stay under 50 lines of actual content (excluding blank lines and
+section headers). This is a target, not a hard limit, but exceeding it significantly
+means CLAUDE.md is trying to do too much.
+
+Claude reads CLAUDE.md at the start of every session and after every /compact.
+Long CLAUDE.md files waste context on every single interaction.
+
+## What Belongs in CLAUDE.md
+
+YES:
+- Project identity (name, one-line description)
+- Key file pointers (PROGRESS.md, SPEC.md)
+- Tech stack and build/test/run commands
+- Session protocol (start/during/end)
+- Critical rules (5-10 maximum)
+- Gotchas (grows, but prune regularly)
+- Skills pointer (list of available skills)
+
+NO:
+- Detailed coding standards (put in a skill)
+- Architecture documentation (put in a skill or docs/)
+- API documentation (put in docs/)
+- Full workflow descriptions (put in a skill)
+- Things Claude already knows (common language features, standard libraries)
+
+## What Belongs in Skills vs CLAUDE.md
+
+CLAUDE.md: things Claude needs to know EVERY session, regardless of task.
+Skills: things Claude needs to know SOMETIMES, for specific types of work.
+
+Example:
+- "Use conventional commits" -> CLAUDE.md (applies to every commit)
+- "Commit message format: type(scope): description, body explains why..." -> skill
+  (only needed when actually writing commits)
+
+## Maintaining the Gotchas Section
+
+The Gotchas section captures project-specific traps. Format:
+
+```markdown
+## Gotchas
+- The settings merger must handle comment strings in JSON arrays (they're not valid
+  JSON but we support them for readability)
+- Always use path.join(), never string concatenation for file paths — breaks on Windows
+- The backup directory uses timestamps with colons replaced by hyphens for Windows compat
+```
+
+Each gotcha should be:
+- Specific (not "be careful with paths")
+- Actionable (says what to do, not just what's wrong)
+- Born from real experience (don't pre-populate with hypotheticals)
+
+## When to Prune
+
+Review CLAUDE.md when:
+- It exceeds 50 lines
+- You notice rules that no longer apply
+- A rule has been absorbed into a skill
+- Two rules say the same thing differently
+
+Pruning checklist:
+- Remove rules for code that no longer exists
+- Consolidate duplicate rules
+- Move detailed guidance to skills
+- Remove gotchas that have been fixed at the code level
+
+## Using /update-claude-md
+
+The /update-claude-md command helps at session end:
+1. Reviews what happened during the session
+2. Identifies mistakes that should become rules
+3. Identifies patterns worth documenting
+4. Proposes additions with diffs
+
+Always review proposed changes before applying. Not every mistake needs a rule.
+Only add rules for recurring problems.
+
+## Gotchas
+
+- CLAUDE.md is read as system context, not as a document. Write it as instructions,
+  not as documentation. "Use path.join for file paths" not "The project uses
+  path.join for file paths because..."
+- Don't add rules preemptively. Wait for the mistake to happen twice. Premature
+  rules clutter the file without proven value.
+- If CLAUDE.md contradicts a skill file, CLAUDE.md wins. Keep them consistent.
+- Skills are loaded on demand. CLAUDE.md is always loaded. Use this asymmetry
+  intentionally.

package/templates/skills/universal/context-management.md

@@ -0,0 +1,71 @@
+---
+description: "Context budget awareness, when to compact, when to clear, subagent offloading"
+---
+
+# Context Management
+
+## The 70% Rule
+
+Context windows are finite. When you estimate you've used roughly 70% of available
+context, it's time to act. Don't wait until you're out of room — you lose the ability
+to reason well before you hit the hard limit.
+
+Signs you're running low:
+- You've read many large files in this session
+- You've had a long back-and-forth conversation
+- You're working on a second or third major task
+- Responses are getting slower or less coherent
+
+## Three Tools, Different Jobs
+
+### /compact — Compress and continue
+Use when: you're mid-task and need more room but want to keep working.
+What it does: summarizes conversation history, freeing context.
+Pair with: PostCompact hook that re-reads CLAUDE.md and PROGRESS.md automatically.
+
+After compaction, always re-orient:
+- What task am I working on?
+- What branch am I on?
+- What did I just do?
+
+### /clear — Fresh start
+Use when: you're starting a genuinely new task with no relationship to the current one.
+What it does: wipes conversation entirely.
+Caution: you lose ALL context. Make sure PROGRESS.md is updated first.
+
+### Subagents — Offload without losing context
+Use when: a side task would pollute your main context (research, testing, file generation).
+What it does: spawns a separate context that does work and returns results.
+Your main context stays clean.
+
+## Decision Matrix
+
+| Situation | Action |
+|---|---|
+| ~70% context, mid-task | /compact |
+| Task complete, starting unrelated work | /clear |
+| Need to research something tangential | Subagent |
+| Need to run tests while continuing design | Subagent |
+| Context feels sluggish, responses degrading | /compact |
+| Long debugging session, found the fix | /compact, then implement |
+
+## PostCompact Hook
+
+The workflow installs a PostCompact hook that runs:
+```
+cat CLAUDE.md && cat docs/spec/PROGRESS.md 2>/dev/null || true
+```
+
+This ensures you never lose your bearings after compaction. The hook fires
+automatically — you don't need to re-read these files manually.
+
+## Gotchas
+
+- Compacting doesn't free as much context as you think. If you've read 20 large files,
+  compaction helps but won't get you back to fresh. Consider /clear if the task is done.
+- Subagents don't share your conversation context. They start fresh. Give them explicit
+  instructions and file paths — don't assume they know what you know.
+- Don't compact right before a complex merge or refactor. You'll lose the nuanced
+  understanding of the changes you've been building up.
+- After /compact, always verify your understanding before making changes. The summary
+  may have lost important details.

package/templates/skills/universal/git-conventions.md

@@ -0,0 +1,95 @@
+---
+description: "Branch naming, commit message format, PR workflow, worktree conventions"
+---
+
+# Git Conventions
+
+## Branch Naming
+
+Pattern: `{type}/{short-description}`
+
+Types:
+- `feature/` — New functionality
+- `fix/` — Bug fixes
+- `refactor/` — Code restructuring without behavior change
+- `docs/` — Documentation only
+- `test/` — Test additions or fixes
+- `chore/` — Tooling, dependencies, config
+
+Examples:
+- `feature/auth-flow`
+- `fix/login-timeout`
+- `refactor/extract-merger-module`
+
+Keep branch names under 50 characters. Use hyphens, not underscores.
+
+## Commit Messages
+
+Follow conventional commits format:
+
+```
+type(scope): short description
+
+Longer explanation if needed. Focus on WHY, not WHAT.
+The diff already shows what changed.
+
+Closes #123
+```
+
+Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `perf`, `ci`
+
+Scope is optional but helpful: `feat(auth): add OAuth2 token refresh`
+
+Rules:
+- Subject line under 72 characters
+- Imperative mood ("add" not "added" or "adds")
+- No period at the end of the subject line
+- Blank line between subject and body
+- Body explains motivation, not mechanics
+
+## When to Commit
+
+Commit after each logical unit of work:
+- A function is complete and tested
+- A refactor is done and tests pass
+- A bug is fixed and verified
+
+Don't batch unrelated changes into one commit. Don't commit broken code.
+
+## PR Workflow
+
+1. Push your branch
+2. Create PR with `gh pr create`
+3. PR title follows same format as commit subject: `type(scope): description`
+4. PR body includes: what changed, why, how to test, anything reviewers should know
+5. Request review if the project has reviewers configured
+
+## Squash vs Merge
+
+- Squash when: the branch has many small "wip" commits that don't individually matter
+- Merge when: each commit in the branch is a meaningful, atomic change
+- Rebase when: you need a linear history and commits are clean
+
+Default preference: squash merge for feature branches, regular merge for release branches.
+
+## Worktree Conventions
+
+When using `git worktree` for parallel work:
+
+- Worktrees go in a sibling directory, not inside the repo
+- Naming: `{repo}-{branch-name}` for the worktree directory
+- Always clean up worktrees when done: `git worktree remove {path}`
+- Don't leave stale worktrees — they hold refs and can cause confusion
+
+Agents that use worktree isolation (code-simplifier, test-writer, ci-fixer, etc.)
+create and clean up their own worktrees automatically.
+
+## Gotchas
+
+- Never force-push to main/master. Force-push to feature branches only when you
+  own the branch and have communicated with collaborators.
+- If a rebase goes wrong, `git reflog` is your friend. The old state is still there.
+- Don't commit generated files (build output, node_modules, .pyc) — check .gitignore.
+- When working in worktrees, remember that stashes are shared across the repo.
+  A stash in one worktree is visible in another.
+- Commit messages are documentation. Future you will read them. Write for that person.

package/templates/skills/universal/planning-with-files.md

@@ -0,0 +1,114 @@
+---
+description: "How to structure implementation plans as files, progressive implementation, plan review process"
+---
+
+# Planning with Files
+
+## The IMPLEMENTATION-PROMPT Pattern
+
+Large tasks need a written plan before code. The plan lives as a file so it can be
+reviewed, versioned, and referenced across sessions.
+
+File naming: `IMPLEMENTATION-PROMPT-{FEATURE}.md` in the project root or `docs/` directory.
+
+Structure:
+```markdown
+# Implementation: {Feature Name}
+
+## Goal
+One sentence. What does success look like?
+
+## Context
+What exists today. What needs to change. Links to relevant spec sections.
+
+## Plan
+
+### Phase 1: {Name}
+- Step 1: {specific action}
+  - Verify: {how to confirm it worked}
+- Step 2: {specific action}
+  - Verify: {how to confirm it worked}
+
+### Phase 2: {Name}
+...
+
+## Edge Cases
+- {case}: {how to handle}
+
+## Out of Scope
+- {thing we're explicitly NOT doing}
+```
+
+## Breaking Large Tasks into Phases
+
+Each phase should be:
+- Independently testable
+- Committable on its own
+- Small enough for one session (or one focused block within a session)
+
+Signs a phase is too big:
+- More than 5-7 steps
+- Touches more than 3-4 files substantially
+- You can't describe the verification in one sentence
+
+Signs a phase is too small:
+- It's just one line change
+- The verification is "it compiles"
+- It doesn't move the feature forward meaningfully
+
+## The Plan-Review Workflow
+
+Before implementing, send the plan through the plan-reviewer agent:
+
+1. Write the IMPLEMENTATION-PROMPT file
+2. Use `/review-plan` to trigger review
+3. The plan-reviewer (Opus) acts as a staff engineer:
+   - Flags ambiguity
+   - Identifies missing verification steps
+   - Checks SPEC.md alignment
+   - Questions unrealistic scope
+   - Points out edge cases
+4. Address ALL feedback before proceeding
+5. Update the plan file with revisions
+
+Don't skip review for non-trivial work. The 5 minutes spent reviewing saves hours
+of rework.
+
+## Progressive Implementation
+
+Execute one phase at a time:
+1. Read the plan
+2. Implement the phase
+3. Run verification for that phase
+4. Commit
+5. Update PROGRESS.md
+6. Move to next phase
+
+If a phase reveals the plan was wrong, STOP. Update the plan first. Don't improvise
+your way through a broken plan.
+
+## When to Plan vs When to Just Do It
+
+Plan (write an IMPLEMENTATION-PROMPT):
+- Multi-file changes
+- New features
+- Architectural changes
+- Anything touching more than 2 modules
+
+Just do it:
+- Bug fixes with obvious cause
+- Single-file refactors
+- Documentation updates
+- Config changes
+
+## Gotchas
+
+- Plans rot fast. If a plan is more than 2 sessions old and hasn't been started,
+  re-review it before implementing. The codebase may have changed.
+- Don't over-plan. The plan should be specific enough to implement without guessing
+  but not so detailed that it's pseudo-code. Trust the implementer to make
+  tactical decisions.
+- Every step needs a verification. "Implement the auth module" is not a plan step.
+  "Implement the auth module; verify: login endpoint returns 200 with valid creds
+  and 401 with invalid" is a plan step.
+- Keep plans in version control. They're documentation of decisions and intent.

package/templates/skills/universal/prompt-engineering.md

@@ -0,0 +1,97 @@
+---
+description: "Effective prompting patterns for working with Claude, demanding quality, writing specs"
+---
+
+# Prompt Engineering
+
+## Challenge Claude to Do Better
+
+Claude will give you a reasonable answer. You often want an excellent one.
+The difference is in how you ask.
+
+Weak: "Write a function to parse dates."
+Strong: "Write a date parser that handles ISO 8601, RFC 2822, and common US/EU
+formats. It should return a consistent internal representation and throw specific
+error types for invalid input. Make it elegant — no regex spaghetti."
+
+The strong version sets quality expectations, specifies edge cases, and demands
+craft. Claude responds to these signals.
+
+## Demand Elegance
+
+When Claude produces a working but mediocre solution, push back:
+
+- "This works but it's not elegant. Simplify it."
+- "There's duplication between these three functions. Refactor."
+- "This is too clever. Make it readable."
+- "A junior engineer should understand this. Rewrite for clarity."
+
+Don't accept the first output as final. Iterate.
+
+## When to Be Specific vs When to Delegate
+
+Be specific about:
+- Requirements (what the code MUST do)
+- Constraints (performance, compatibility, patterns to follow)
+- Verification criteria (how to know it works)
+
+Delegate to Claude:
+- Implementation approach (unless you have a strong preference)
+- Variable naming and code organization details
+- Which standard library functions to use
+- Test case generation (give the categories, let Claude enumerate)
+
+## Writing Detailed Specs
+
+A good spec eliminates ambiguity. The SPEC.md pattern works because it forces
+specificity before implementation begins.
+
+Spec checklist:
+- Every feature described with concrete examples
+- Input/output pairs for non-obvious behavior
+- Error cases listed explicitly
+- "Out of scope" section to prevent feature creep
+- Success criteria that can be mechanically verified
+
+## The IMPLEMENTATION-PROMPT as a Prompt
+
+The implementation prompt IS your prompt to Claude for a work session. Write it
+like you're briefing a skilled contractor:
+
+1. Here's what exists (context)
+2. Here's what we need (goal)
+3. Here's how to do it (plan)
+4. Here's how to check your work (verification)
+5. Here's what NOT to do (constraints)
+
+## Prompting Anti-Patterns
+
+- Vague asks: "Make the code better" — better HOW?
+- Kitchen sink: asking for 10 things at once with no priority order
+- Assuming context: referencing decisions made 500 messages ago without restating them
+- Over-constraining: specifying the exact implementation when only the interface matters
+- Under-specifying errors: "handle errors appropriately" — define what appropriate means
+
+## Working with Models at Different Levels
+
+Opus: Use for judgment calls, architectural decisions, plan review. Give it the full
+picture and ask for analysis.
+
+Sonnet: Use for implementation, testing, code review. Give it specific tasks with
+clear scope.
+
+Haiku: Use for validation, formatting checks, simple queries. Give it narrow tasks
+with yes/no or pass/fail outcomes.
+
+Match the task complexity to the model capability.
+
+## Gotchas
+
+- Claude remembers everything in the conversation. You don't need to repeat instructions
+  that are already in context. But after /compact, re-state critical constraints.
+- If Claude keeps making the same mistake, the problem is probably in your instructions,
+  not in Claude. Rephrase, add an example, or add a rule to CLAUDE.md.
+- Long prompts aren't always better. A focused 3-line instruction often outperforms
+  a rambling paragraph. Be concise about what matters.
+- When Claude says "I'll do X" but you wanted Y, correct immediately. Don't let
+  wrong assumptions propagate through a chain of actions.

package/templates/skills/universal/review-and-handoff.md

@@ -0,0 +1,106 @@
+---
+description: "Session ending protocol, HANDOFF document format, seamless continuation between sessions"
+---
+
+# Review and Handoff
+
+## Session Ending Protocol
+
+Every session should end cleanly. The /end command triggers this, but understanding
+the protocol matters more than the command.
+
+Before ending:
+1. Commit any working code (don't leave uncommitted changes)
+2. Run tests to confirm nothing is broken
+3. Update PROGRESS.md
+4. If mid-task, write a HANDOFF document
+
+## PROGRESS.md Update
+
+PROGRESS.md is the single source of truth for project state across sessions.
+
+Update these sections:
+```markdown
+## Current Status
+{What phase/feature is active}
+
+## Completed This Session
+- {Specific thing done}
+- {Another specific thing done}
+
+## In Progress
+- {What's partially done, and where it stands}
+
+## Blockers
+- {Anything preventing forward progress}
+
+## Next Steps
+- {Ordered list of what to do next}
+```
+
+Be specific. "Worked on auth" is useless. "Implemented JWT token generation and
+validation in src/auth/tokens.js; unit tests passing; integration tests not yet
+written" is useful.
+
+## HANDOFF Document Format
+
+When ending mid-task, PROGRESS.md isn't enough. Write a handoff at
+`docs/handoffs/HANDOFF_{date}.md`.
+
+```markdown
+# Handoff: {Date}
+
+## What I Was Doing
+{1-2 sentences on the exact task}
+
+## Current State
+- Branch: {branch name}
+- Last commit: {hash and message}
+- Tests: {passing/failing, which ones}
+- Files changed: {list of modified files}
+
+## What's Left
+1. {Next specific step}
+2. {Step after that}
+3. {Final step for this task}
+
+## Context That Matters
+- {Decision made during this session and why}
+- {Gotcha discovered that isn't documented elsewhere}
+- {Assumption being made that should be validated}
+
+## How to Verify When Done
+{What "done" looks like for this task}
+```
+
+## What Context Matters
+
+Include in handoffs:
+- WHY decisions were made, not just what
+- Failed approaches and why they failed (prevents re-trying dead ends)
+- Dependencies discovered during implementation
+- Anything that surprised you about the codebase
+
+Don't include:
+- Obvious things a fresh session can figure out from the code
+- Full code dumps (the code is in version control)
+- Speculation about future tasks unrelated to the current work
+
+## The Fresh Session Test
+
+A good handoff passes this test: could a fresh Claude session, reading only
+PROGRESS.md and the HANDOFF file, continue the work without asking clarifying
+questions?
+
+If no, the handoff is missing context.
+
+## Gotchas
+
+- Don't skip the handoff because "it's almost done." You might not get back to
+  this task for days. What's obvious now will be opaque later.
+- HANDOFF files are ephemeral. Delete them once the task is complete. Don't let
+  stale handoffs accumulate — they become misleading.
+- Always commit before writing the handoff. The handoff references a commit hash.
+  If the code isn't committed, the handoff points to nothing.
+- Update PROGRESS.md even if you write a HANDOFF. PROGRESS.md is the persistent
+  state; HANDOFF is the detailed supplement.