cc-dev-template 0.1.89 → 0.1.91

package/bin/install.js

@@ -326,6 +326,17 @@ deprecatedAgents.forEach(agent => {
 });
 
 // Remove deprecated bash wrapper files
+// Remove deprecated commands (converted to skills)
+const deprecatedCommands = ['done'];
+deprecatedCommands.forEach(cmd => {
+  const cmdPath = path.join(CLAUDE_DIR, 'commands', `${cmd}.md`);
+  if (fs.existsSync(cmdPath)) {
+    fs.unlinkSync(cmdPath);
+    console.log(`✓ Removed deprecated command: ${cmd} (now a skill)`);
+    cleanupPerformed = true;
+  }
+});
+
 const deprecatedFiles = [
   path.join(CLAUDE_DIR, 'hooks', 'bash-precheck.sh'),
   path.join(CLAUDE_DIR, 'hooks', 'bash-wrapper-helper.sh'),
@@ -466,7 +477,7 @@ These settings are available globally across all your projects.
 
 Commands:
   /prime - Start a session (orientation, scaffolding for new projects)
-  /done  - End a session (sync docs, commit work)
+  /done  - End a session (sync docs, commit, apply learnings)
 `);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-dev-template",
-  "version": "0.1.89",
+  "version": "0.1.91",
   "description": "Structured AI-assisted development framework for Claude Code",
   "bin": {
     "cc-dev-template": "./bin/install.js"

package/src/agents/spec-implementer.md

@@ -5,6 +5,23 @@ tools: Read, Grep, Glob, Edit, Write, Bash, LSP
 memory: project
 ---
 
+<memory>
+**On startup, read your memory file.** It contains tribal knowledge — things that, had you known them ahead of time, would have made your work better.
+
+**What to store** (the "had I known this" test):
+- Codebase patterns that tripped you up or weren't obvious from reading the spec alone
+- Project-specific conventions (import styles, error handling patterns, file organization) that affect implementation
+- Integration gotchas — things that broke when connecting new code to existing systems
+- Build/tooling quirks that slowed you down or caused errors
+
+**What NOT to store:**
+- What tasks you implemented or what code you wrote (that's git history and Implementation Notes)
+- Current implementation state or progress (that's the code and task files)
+- Generic programming knowledge you already know
+
+Curate aggressively. Remove entries that no longer apply. Keep it under 100 lines.
+</memory>
+
 You implement one task from a spec breakdown.
 
 ## Process

package/src/agents/spec-validator.md

@@ -5,6 +5,23 @@ tools: Read, Grep, Glob, Bash
 memory: project
 ---
 
+<memory>
+**On startup, read your memory file.** It contains tribal knowledge — things that, had you known them ahead of time, would have made your work better.
+
+**What to store** (the "had I known this" test):
+- Testing approaches that caught real bugs vs. ones that wasted time in this codebase
+- Project-specific test infrastructure quirks (dev server setup, browser automation gotchas, flaky patterns)
+- Common implementation mistakes you've seen that are worth checking for early
+- E2E testing patterns specific to this project's UI and workflows
+
+**What NOT to store:**
+- What tasks you validated or what bugs you found (that's git history and Review Notes)
+- Current test results or feature state (that's the code and task files)
+- Generic QA knowledge you already know
+
+Curate aggressively. Remove entries that no longer apply. Keep it under 100 lines.
+</memory>
+
 You are a senior QA engineer validating completed work.
 
 ## Process

package/src/agents/spec-writer.md

@@ -6,6 +6,23 @@ memory: project
 permissionMode: bypassPermissions
 ---
 
+<memory>
+**On startup, read your memory file.** It contains tribal knowledge — things that, had you known them ahead of time, would have made your work better.
+
+**What to store** (the "had I known this" test):
+- Spec patterns that led to smoother implementations vs. ones that caused rework
+- Common gaps you've seen in upstream artifacts (intent, research, design) and how you compensated
+- Project-specific conventions for data models, API shapes, or naming that aren't obvious from reading the code once
+- Checklist items that frequently catch real issues in this codebase
+
+**What NOT to store:**
+- What specs you wrote or reviewed (that's git history)
+- Current feature state or progress (that's the code and spec files)
+- Generic spec-writing knowledge you already know
+
+Curate aggressively. Remove entries that no longer apply. Keep it under 100 lines.
+</memory>
+
 You operate in one of two modes depending on your prompt.
 
 ## Write Mode

package/src/agents/task-breakdown.md

@@ -6,6 +6,23 @@ memory: project
 permissionMode: bypassPermissions
 ---
 
+<memory>
+**On startup, read your memory file.** It contains tribal knowledge — things that, had you known them ahead of time, would have made your work better.
+
+**What to store** (the "had I known this" test):
+- Ordering strategies that worked well vs. ones that caused dependency tangles during implementation
+- Task scoping lessons — what was too big, too small, or split wrong for this codebase
+- File path conventions and project structure patterns that affect task planning
+- Checklist items that frequently catch real issues in this project's task breakdowns
+
+**What NOT to store:**
+- What task breakdowns you created or reviewed (that's git history)
+- Current task status or progress (that's the task files themselves)
+- Generic task breakdown knowledge you already know
+
+Curate aggressively. Remove entries that no longer apply. Keep it under 100 lines.
+</memory>
+
 You operate in one of two modes depending on your prompt.
 
 ## Write Mode

package/src/skills/creating-sub-agents/references/create-step-2-design.md

@@ -136,7 +136,9 @@ memory: project
 | `project` | `.claude/agent-memory/<name>/` | Project-specific, shareable via git |
 | `local` | `.claude/agent-memory-local/<name>/` | Project-specific, private |
 
-When enabled, the system auto-includes the first 200 lines of `MEMORY.md` and enables Read, Write, Edit for the memory directory. Include memory instructions in the system prompt.
+When enabled, the system auto-includes the first 200 lines of `MEMORY.md` and enables Read, Write, Edit for the memory directory.
+
+Memory stores tribal knowledge — things that, had the agent known them ahead of time, would have made its work better. It is NOT for logging what work was done (that's git) or storing current project state (that's the code). Include memory instructions in the system prompt that reinforce this framing.
 
 ### Hooks
 

package/src/skills/creating-sub-agents/references/create-step-3-write.md

@@ -124,15 +124,28 @@ Over 200 lines — consider whether the sub-agent's scope is too broad. Split in
 
 ## Memory Instructions
 
-If memory is enabled, include instructions in the prompt:
+If memory is enabled, include a `<memory>` section in the prompt. Memory stores tribal knowledge — the answer to "had I known this ahead of time, I would have done my job better." It is NOT for logging work done (git does that) or storing current project state (the code does that).
 
 ```markdown
-**On startup, read your memory file at the memory directory.**
-Update it when you learn patterns, conventions, or gotchas
-that would help future sessions. Keep it under 100 lines.
-Remove entries that are no longer accurate.
+<memory>
+**On startup, read your memory file.** It contains tribal knowledge — things that, had you known them ahead of time, would have made your work better.
+
+**What to store** (the "had I known this" test):
+- {Role-specific examples: patterns, gotchas, conventions relevant to this agent's job}
+- {Integration points or tooling quirks that aren't obvious from reading the code once}
+- {Decisions and rationale that future sessions would otherwise re-discover}
+
+**What NOT to store:**
+- What work you did or what code you changed (that's git history)
+- Current project state or feature status (that's the code itself)
+- Generic knowledge you already know
+
+Curate aggressively. Remove entries that no longer apply. Keep it under 100 lines.
+</memory>
 ```
 
+Tailor the "What to store" examples to the agent's specific role — a code reviewer stores different tribal knowledge than an implementer or a test runner.
+
 ## Team Coordination Instructions
 
 If this sub-agent will be part of agent teams, include team context:

package/src/skills/creating-sub-agents/templates/domain-specialist.md

@@ -18,12 +18,20 @@ You are a software engineer who owns the {{domain-name}} domain. You write code,
 </domain>
 
 <memory>
-**On startup, read your memory file at `.claude/agent-memory/{{AGENT_NAME}}/MEMORY.md`.**
-This contains accumulated knowledge from previous sessions. Update it when you learn something that would help future sessions.
+**On startup, read your memory file.** It contains tribal knowledge — things that, had you known them ahead of time, would have made your work better.
 
-Memory is tribal knowledge — patterns, gotchas, decisions, integration points. Not documentation of what code does, but how to work effectively in this codebase.
+**What to store** (the "had I known this" test):
+- Patterns, gotchas, and conventions specific to your domain that aren't obvious from reading the code once
+- Integration points with other domains that have tripped you up
+- Decisions and their rationale that future sessions would otherwise have to re-discover
+- Non-obvious build, test, or tooling quirks in your domain
 
-Review and curate your memory. Remove entries that are no longer accurate. Keep it under 100 lines.
+**What NOT to store:**
+- What work you did or what code you changed (that's git history)
+- Current project state or feature status (that's the code itself)
+- Generic programming knowledge you already know
+
+Curate aggressively. Remove entries that no longer apply. Keep it under 100 lines.
 </memory>
 
 <team>

package/src/skills/done/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: done
+description: End a session - sync documentation, commit, and push
+argument-hint: [next task]
+---
+
+# Session Closeout
+
+Bridge the gap between this session and the next. Git captures what was done; CURRENT_WORK.md captures what to do next.
+
+## Execute Directly
+
+This requires full conversation context. Handle it yourself rather than delegating.
+
+## Steps
+
+**1. Commit your work**
+
+Write clear commit messages that explain what was accomplished. This IS your record of completed work.
+
+**2. Update `docs/CURRENT_WORK.md`**
+
+This file is forward-looking. Review it holistically and ensure it contains ONLY:
+
+- **Up Next** — Tasks to tackle in future sessions. If the user specified a next task ($ARGUMENTS), add it here.
+- **In Progress** — Work that's partially done and needs continuation
+- **Blocked / Waiting** — Items waiting on external input (people, services, decisions)
+- **Open Questions** — Unanswered questions that need follow-up
+
+**Remove** anything that doesn't require future action:
+- Completed work (that's in git now)
+- Answered questions (document answers in appropriate docs if needed, then remove from here)
+- Historical context or architecture notes (move to relevant docs/)
+- Status updates about past sessions
+
+The file should be scannable in 30 seconds. If it takes longer, it's too long.
+
+**3. Apply session learnings**
+
+Review the session for anything that passes the "had I known this ahead of time" test — things that, known upfront, would have prevented mistakes or saved real time.
+
+If anything qualifies, read `references/apply-learnings.md` and follow its hierarchy to put the fix in the right place.
+
+If nothing qualifies (most sessions), skip this step entirely.
+
+**4. Prune memory**
+
+Read your MEMORY.md file. Check every entry against `references/memory-rules.md`.
+
+- Entries that are project-specific tribal knowledge (not personal) — relocate using the hierarchy from step 3
+- Entries that are stale, obvious, or discoverable from code — delete
+- Entries that duplicate CLAUDE.md or rules files — delete
+
+If MEMORY.md exceeds 200 lines, stop and deeply reflect. Something is wrong — you're storing things that don't belong.
+
+**5. Push**
+
+Push your commits to the remote.
+
+**6. Report what was updated**
+
+Summarize: commits made, CURRENT_WORK.md changes, memory entries relocated or pruned, any rules/CLAUDE.md files updated.

package/src/skills/done/references/apply-learnings.md

@@ -0,0 +1,67 @@
+# Apply Learnings — Fix Hierarchy
+
+When you identify something that passes the "had I known this ahead of time" test, walk this hierarchy top to bottom. The first level that works is the right one. Higher levels are more reliable because they're deterministic — they don't depend on an agent reading the right file at the right time.
+
+## Level 1: Programmatic Fix
+
+Can a test, linter, build step, or CI gate make this impossible to repeat?
+
+This is the best fix. It's deterministic — no agent or developer needs to "remember" anything. The tooling catches it automatically.
+
+Examples:
+- Add a test case that covers the failure
+- Add or update a lint rule
+- Add a build-time check or CI gate
+- Update a schema validation
+
+If the project has existing tooling (test suites, linters, build checks), use it. If it doesn't and the fix is simple, propose it to the user.
+
+**If this level works, you're done. Don't also add a prompt about it.**
+
+## Level 2: Claude Code Hook
+
+Can a hook intercept the problem at the agent tooling layer?
+
+Hooks fire on tool calls (PreToolUse, PostToolUse, etc.) and can:
+- Block an action and return guidance
+- Inject a contextual warning
+- Redirect agent behavior
+
+Good for guardrails that aren't expressible as code-level checks — things specific to how agents interact with the codebase.
+
+**If this level works, you're done.**
+
+## Level 3: Shared Project Knowledge
+
+Is this something ALL agents and developers working on this project should know?
+
+Then it belongs in the project, not in personal memory. Choose the most specific location:
+
+1. **`.claude/rules/*.md`** — Scoped to file patterns via frontmatter `paths:` globs. Best for rules that apply only when touching specific files. Agents only receive these rules when working on matching files. This is the most targeted option — prefer it when the learning is about a specific type of file or area of code.
+
+2. **Directory-level `CLAUDE.md`** — Scoped to a directory and its children. Good for conventions specific to a module or subsystem. Agents only receive this when working in that directory tree.
+
+3. **Root `CLAUDE.md`** — Project-wide conventions. Every agent sees this on every task. Only put things here that truly apply everywhere.
+
+**Hierarchy matters.** Rules files and directory-level CLAUDE.md files are only loaded when relevant. This keeps agent context lean — agents working on unrelated files don't get noise about your gotcha. Root CLAUDE.md is always loaded, so keep it reserved for universal truths.
+
+When writing the entry, follow these principles:
+- Explain WHY, not just WHAT
+- Be direct — one or two lines, not a paragraph
+- Trust intelligence — state the gotcha, don't over-explain
+- Don't duplicate what a parent file already says
+
+**If this level works, you're done.**
+
+## Level 4: Personal Memory
+
+Only if it's specific to THIS developer or THIS machine.
+
+The test: "Would a different developer cloning this repo need to know this?" If yes, it doesn't belong in memory — go back to Level 3.
+
+What belongs in memory:
+- User preferences and working style ("prefers X over Y")
+- Machine/environment quirks ("macOS on this machine does X differently")
+- Corrections to your own behavioral patterns with this user
+
+That's it. Memory is the personal notebook — small, stable, and rarely changing.

package/src/skills/done/references/memory-rules.md

@@ -0,0 +1,31 @@
+# Memory Rules — What Belongs and What Doesn't
+
+Your MEMORY.md is injected into every conversation's system prompt. Every line costs tokens and attention. It is your personal notebook — not a project wiki.
+
+## The Delineation
+
+| Type of Knowledge | Where It Belongs | Why |
+|---|---|---|
+| Project architecture, conventions, patterns | CLAUDE.md or `.claude/rules/` | Shared — all agents and developers benefit |
+| Codebase gotchas, file-specific rules | `.claude/rules/` with path scoping | Targeted — only loaded when touching those files |
+| Domain knowledge, design decisions | `docs/` | Reference material — not prompt context |
+| What was built, changed, or completed | Git history | That's what git is for |
+| Current/future work items | `docs/CURRENT_WORK.md` | Read at session start |
+| User preferences, working style | MEMORY.md | Personal — not project-specific |
+| Machine/OS-specific quirks | MEMORY.md | Personal — not project-specific |
+| Behavioral corrections for this user | MEMORY.md | Personal — not project-specific |
+
+## Pruning Checklist
+
+For each entry in MEMORY.md, ask:
+
+1. **Is this about the project or about the user?** If the project — it belongs in CLAUDE.md or rules, not here. Relocate it.
+2. **Would a different developer on this project benefit from knowing this?** If yes — it's shared knowledge, not personal memory. Relocate it.
+3. **Is this discoverable by reading the code?** If yes — delete it. Agents can read code.
+4. **Is this already in a CLAUDE.md or rules file?** If yes — delete the duplicate.
+5. **Is this still true?** If outdated — delete or correct it.
+6. **Did this come from a single observation?** If unverified — delete it. Wait until it's confirmed across multiple sessions.
+
+## Relocating Entries
+
+When you find a memory entry that belongs elsewhere, don't just delete it — apply the fix hierarchy from `apply-learnings.md` to put it in the right place. The knowledge is valuable; it's just in the wrong location.

package/src/commands/done.md

@@ -1,93 +0,0 @@
----
-description: End a session - sync documentation, commit, and push
-argument-hint: [next task]
----
-
-# Session Closeout
-
-Bridge the gap between this session and the next. Git captures what was done; CURRENT_WORK.md captures what to do next.
-
-## Why This Matters
-
-CURRENT_WORK.md is read at the start of every session. It should answer one question: "What should I work on?"
-
-Git commits are the historical record of completed work. There's no need to duplicate that in documentation.
-
-## Execute Directly
-
-This requires full conversation context. Handle it yourself rather than delegating.
-
-## Steps
-
-**1. Commit your work**
-
-Write clear commit messages that explain what was accomplished. This IS your record of completed work.
-
-**2. Update `docs/CURRENT_WORK.md`**
-
-This file is forward-looking. Review it holistically and ensure it contains ONLY:
-
-- **Up Next** — Tasks to tackle in future sessions. If the user specified a next task ($ARGUMENTS), add it here.
-- **In Progress** — Work that's partially done and needs continuation
-- **Blocked / Waiting** — Items waiting on external input (people, services, decisions)
-- **Open Questions** — Unanswered questions that need follow-up
-
-**Remove** anything that doesn't require future action:
-- Completed work (that's in git now)
-- Answered questions (document answers in appropriate docs if needed, then remove from here)
-- Historical context or architecture notes (move to relevant docs/)
-- Status updates about past sessions
-
-The file should be scannable in 30 seconds. If it takes longer, it's too long.
-
-**3. Capture workflow discoveries (rarely)**
-
-Add to CLAUDE.md only high-value operational knowledge that can't be found by reading code:
-- Dev commands, ports, local URLs
-- Key paths (logs, config, seed data)
-- Non-obvious project conventions
-
-Most sessions: add nothing.
-
-**4. Reflect on session and update memory**
-
-Review the full session for lessons worth preserving across conversations. Your memory directory persists between sessions — use it to build institutional knowledge.
-
-What belongs in memory:
-- Debugging breakthroughs — "X error was caused by Y, the fix is Z"
-- Gotchas that wasted time — things you'd want to know next time
-- Confirmed patterns — approaches that worked well (or didn't)
-- Corrections — things you assumed wrong and now know better
-- User preferences discovered through interaction (not stated in CLAUDE.md)
-
-What does NOT belong:
-- Anything already in CLAUDE.md (memory supplements it, doesn't duplicate it)
-- Task-specific context (what you worked on today — that's in git and CURRENT_WORK.md)
-- Obvious things discoverable by reading the code
-- Speculative conclusions from a single observation
-
-How to update:
-- Read your existing MEMORY.md first — edit, don't just append
-- Remove or correct entries that turned out wrong
-- Keep MEMORY.md under 200 lines (it's injected into your system prompt)
-- Use topic files (`debugging.md`, `patterns.md`) for detailed notes, link from MEMORY.md
-- Organize by topic, not chronologically
-
-Most sessions: a small edit or nothing. Occasionally: a meaningful addition. The bar is "would this save me real time or prevent a real mistake next session?"
-
-**5. Push**
-
-Push your commits to the remote.
-
-**6. Report what was updated**
-
-Summarize: commits made, CURRENT_WORK.md changes, any items removed/added.
-
-## Mental Model
-
-| File | Purpose | Changes |
-|------|---------|---------|
-| Git history | What was done | Every session |
-| CURRENT_WORK.md | What to do next | Every session (kept minimal) |
-| CLAUDE.md | How to work here | Rarely |
-| Memory | What I've learned | When something non-obvious is discovered |