mema-kit 1.0.4 → 1.0.5

package/docs/guide.md

@@ -2,7 +2,7 @@
 
 **A memory protocol kit for Claude Code skills.**
 
-Three built-in skills. Persistent memory across sessions. A protocol for building your own.
+Five built-in skills. Persistent memory across sessions. A protocol for building your own.
 
 ---
 
@@ -64,77 +64,193 @@ Every new Claude Code session starts with a blank context. `/recall` fixes the c
 
 ---
 
-## Example: Building a Spec-Driven Dev Workflow
+## Planning Work: /plan
 
-mema-kit ships with `/onboard` and `/create-skill`. Everything else you build yourself. Here's how to create a 3-skill workflow: **explore → plan → implement**.
+`/plan` takes a high-level goal, explores your codebase, and produces a structured implementation plan with step-by-step specs. Plans are saved to `.mema/task-memory/` so `/implement` can execute them.
 
-### Step 1: Create `/explore`
+### Usage
 
 ```
-> /create-skill
-  Name: explore
-  Purpose: Research technical decisions and save findings
-  Complexity: standard
+> /plan add user authentication
+> /plan refactor the database layer
+> /plan add search functionality to the API
 ```
 
-Creates `.claude/skills/explore/SKILL.md` — a 4-phase skill that loads existing architecture and decisions, helps you research options, then saves new decisions and context to `.mema/`.
+### What it does
 
-**Using it:**
+1. **Loads memory** — architecture, requirements, decisions, lessons, patterns
+2. **Explores the codebase** — reads relevant source files, understands current patterns
+3. **Asks clarifying questions** (1-2 max) if the goal is ambiguous
+4. **Produces a plan** — general approach + detailed steps with file paths and specifics
+5. **Saves to task-memory** — creates `context.md`, `plan.md`, and `status.md` in `task-memory/[task-name]/`
+
+### Example output
 
 ```
-> /explore what auth strategy should we use?
+## Plan: User Authentication
+
+### Approach
+Add JWT-based authentication using the existing Fastify plugin system.
+Follows the controller → service → repository pattern already in the codebase.
+
+### Steps (5 total)
+1. Create auth database schema and migration
+2. Implement auth service (register, login, token refresh)
+3. Create auth route handlers
+4. Add authentication middleware (Fastify plugin)
+5. Add auth integration tests
+
+### Out of Scope
+- OAuth/social login
+- Role-based access control
+- Password reset flow
+
+---
+Plan saved to task-memory/user-authentication/
+To start implementing: /implement user-authentication
 ```
 
-The agent loads your stack from memory, researches JWT vs sessions vs OAuth, and saves the decision:
+### Revising plans
+
+If you run `/plan` for a task that already has a plan, it will offer to revise the existing plan rather than starting from scratch. This makes `/plan` idempotent — safe to re-run.
+
+---
+
+## Implementing Plans: /implement
+
+`/implement` picks up steps from an existing plan, implements them one at a time, verifies the result, and tracks progress. It's designed to give you control — one step at a time by default.
+
+### Usage
 
 ```
-.mema/project-memory/decisions/2026-02-24-auth-strategy.md
-  → "JWT with refresh tokens. Why: stateless, fits our REST API, team has experience."
+> /implement user-authentication          # implement next incomplete step
+> /implement user-authentication step 3   # implement a specific step
+> /implement user-authentication all      # implement all remaining steps
+> /implement                              # list active tasks, then pick one
 ```
 
-Next session, any skill that loads memory will know this decision exists.
+### What it does
 
-### Step 2: Create `/plan`
+1. **Loads the plan** — reads `plan.md`, `status.md`, and `context.md` from the task
+2. **Picks the next step** — first incomplete step, or the one you specified
+3. **Implements the step** — creates/modifies files following the plan's spec
+4. **Verifies** — runs tests, checks for errors, validates against the plan
+5. **Updates progress** — marks the step complete in `status.md`
+6. **Reports** — shows what was done, what's next, overall progress
+
+### Progress tracking
+
+After each step, you'll see a progress summary:
 
 ```
-> /create-skill
-  Name: plan
-  Purpose: Generate implementation plans from exploration findings
-  Complexity: standard
+## Progress: User Authentication
+
+Step 2/5 complete: Implement auth service
+
+Verified: All tests passing (4 new tests)
+
+### Overall Progress
+[====------] 2/5 steps
+Next: Step 3 — Create auth route handlers
+
+To continue: /implement user-authentication
 ```
 
-**Using it:**
+### Task completion
+
+When all steps are done, `/implement` offers to archive the task:
+
+- Marks `status.md` as complete
+- Moves `task-memory/[task-name]/` to `archive/[task-name]/`
+- Removes the task from active tasks in `index.md`
+- Records any lessons learned and patterns discovered
+
+### Learning from implementation
+
+After each step, `/implement` reflects on the work:
+- Unexpected issues become **lessons** in `agent-memory/lessons.md`
+- Effective approaches become **patterns** in `agent-memory/patterns.md`
+- Decisions made during implementation are saved to `project-memory/decisions/`
+
+This means your memory grows smarter with every implementation cycle.
+
+---
+
+## The plan → implement Workflow
+
+`/plan` and `/implement` form a complete spec-driven development workflow:
 
 ```
-> /plan plan the user auth endpoints
+/plan                              /implement
+  │                                    │
+  ├─ reads:                            ├─ reads:
+  │   architecture                     │   plan.md (from /plan)
+  │   requirements                     │   status.md
+  │   decisions                        │   context.md
+  │   lessons & patterns               │   architecture, decisions
+  │                                    │   lessons & patterns
+  ├─ writes:                           │
+  │   task-memory/[task]/context.md    ├─ writes:
+  │   task-memory/[task]/plan.md       │   status.md (mark steps done)
+  │   task-memory/[task]/status.md     │   decisions/ (if any)
+  │                                    │   lessons.md (if any)
+  │                                    │   patterns.md (if any)
+  │                                    │   archive/ (on completion)
+  ▼                                    ▼
+       both flow through .mema/index.md
 ```
 
-The agent loads the auth decision from Step 1, architecture, and requirements — then writes a step-by-step plan to `.mema/task-memory/user-auth/plan.md`.
+### Full workflow example
 
-### Step 3: Create `/implement`
+```bash
+# Session 1: Explore and plan
+> /recall                                    # load project context
+> /plan add user authentication              # explore codebase, produce plan
+
+# Session 2: Implement (pick up where you left off)
+> /recall                                    # load context + active tasks
+> /implement user-authentication             # implement step 1
+> /implement user-authentication             # implement step 2
+
+# Session 3: Finish up
+> /recall
+> /implement user-authentication all         # implement remaining steps
+# → task archived, lessons saved
+```
+
+---
+
+## Extending with Custom Skills
+
+mema-kit ships with five built-in skills (`/onboard`, `/recall`, `/plan`, `/implement`, `/create-skill`). You can create your own skills to extend the workflow.
+
+### Example: Create `/explore`
 
 ```
 > /create-skill
-  Name: implement
-  Purpose: Implement code following a plan, run tests, save lessons
-  Complexity: advanced
+  Name: explore
+  Purpose: Research technical decisions and save findings
+  Complexity: standard
 ```
 
-Advanced complexity adds task tracking and archiving. When the task is done, the agent moves task files to `archive/` and records any lessons learned.
+Creates `.claude/skills/explore/SKILL.md` — a 4-phase skill that loads existing architecture and decisions, helps you research options, then saves new decisions and context to `.mema/`.
 
 **Using it:**
 
 ```
-> /implement implement user auth endpoints
+> /explore what auth strategy should we use?
 ```
 
-The agent loads the plan, architecture, and past lessons. It implements each step, runs tests, and when done:
+The agent loads your stack from memory, researches JWT vs sessions vs OAuth, and saves the decision:
+
+```
+.mema/project-memory/decisions/2026-02-24-auth-strategy.md
+  → "JWT with refresh tokens. Why: stateless, fits our REST API, team has experience."
+```
 
-- Saves "Drizzle needs explicit type casting for enums" to `lessons.md`
-- Archives `task-memory/user-auth/` to `archive/user-auth/`
-- Updates `index.md`
+Next session, any skill that loads memory will know this decision exists — including `/plan`, which can incorporate it into implementation plans.
 
-### How Memory Flows Between Skills
+### How custom skills connect with built-ins
 
 ```
 /explore          /plan             /implement
@@ -207,3 +323,4 @@ The index is a **rebuildable cache** — if it gets out of sync, the next skill
 - **`.mema/` is gitignored by default.** To share decisions with your team, uncomment `!.mema/project-memory/` in `.gitignore`.
 - **Curate, don't hoard.** The value of memory is its signal-to-noise ratio. Prune aggressively.
 - **Any skill can use the protocol.** Use `/create-skill` or manually follow the 4-phase lifecycle.
+- **One step at a time.** `/implement` defaults to one step per invocation. This gives you a chance to review each change before continuing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mema-kit",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Memory protocol kit for Claude Code skills",
   "bin": {
     "mema-kit": "bin/cli.js"

package/skills/implement/SKILL.md

@@ -0,0 +1,184 @@
+---
+description: Execute implementation plan steps one at a time. Picks up the next step from an existing plan, implements it, verifies the result, and tracks progress. Run /plan first to create a plan.
+---
+
+# /implement — Plan Step Execution
+
+You are executing the /implement skill. Follow these steps carefully.
+
+This skill picks up a step from an existing plan (created by `/plan`), implements it, verifies the result, and updates progress tracking. By default, it implements **one step at a time** to give the user control over the process.
+
+## Phase 1: AUTO-LOAD
+
+1. Read `.mema/index.md` to understand current project state
+2. If `index.md` is missing or `.mema/` does not exist:
+   - Tell the user: "No memory found. Run `/onboard` first to set up mema-kit for this project."
+   - **Stop here** — do not continue to further steps.
+3. If `index.md` is empty, run the **Rebuild Procedure** from `_memory-protocol.md`
+4. Scan `## Active Tasks` in `index.md` to find tasks with plans
+5. Load relevant memory files:
+   - `project-memory/architecture.md` — for technical context during implementation
+   - `project-memory/decisions/` — past decisions that affect implementation
+   - `agent-memory/lessons.md` — mistakes to avoid
+   - `agent-memory/patterns.md` — reusable approaches
+
+## Phase 2: WORK
+
+### 2a: Select Task
+
+Parse the user's input to determine which task to implement:
+
+- **Task specified:** `/implement user-auth` → look for `task-memory/user-auth/`
+- **Task + step specified:** `/implement user-auth step 3` → load that specific step
+- **No task specified:** `/implement` → list active tasks from index.md and ask which one
+- **"all" modifier:** `/implement user-auth all` → implement all remaining steps sequentially (see 2e)
+
+If the specified task directory doesn't exist:
+- Tell the user: "No plan found for '[task-name]'. Run `/plan [goal]` first to create an implementation plan."
+- **Stop here.**
+
+### 2b: Load Task Context
+
+Read the task's files from `task-memory/[task-name]/`:
+
+1. **`plan.md`** — the full implementation plan with all steps
+2. **`status.md`** — current progress (which steps are done)
+3. **`context.md`** — exploration findings relevant to this task
+
+If `plan.md` is missing, tell the user: "Task directory exists but has no plan. Run `/plan [goal]` to create one."
+
+### 2c: Select Step
+
+Determine which step to implement:
+
+- **If user specified a step** (e.g., `step 3`): validate it exists in the plan and isn't already complete. If already complete, inform the user and ask if they want to re-implement it.
+- **If no step specified:** find the first incomplete step in `status.md` (first unchecked `- [ ]` item). If all steps are complete, see section 2f (Task Completion).
+
+Tell the user which step you're implementing:
+
+```
+## Implementing Step [N]/[total]: [Step title]
+
+[Brief description of what this step does]
+```
+
+### 2d: Implement the Step
+
+Follow the plan's specification for this step:
+
+1. **Read the step details** from `plan.md` — files to create/modify, specific implementation details, dependencies
+2. **Check dependencies** — verify that all prerequisite steps are marked complete in `status.md`. If a dependency is incomplete, warn the user: "Step [N] depends on Step [M] which isn't complete yet. Proceed anyway?" If the user says no, stop.
+3. **Implement the changes** — create/modify files as specified in the plan. Follow the project's existing coding patterns (from architecture.md and patterns.md). Apply lessons learned (from lessons.md) to avoid known pitfalls.
+4. **Verify the changes:**
+   - If the project has tests and the step involves testable code: run relevant tests
+   - Check for obvious errors (syntax, imports, type errors)
+   - Validate the implementation matches the plan's specification
+   - If verification fails: do NOT mark the step as complete. Inform the user with details about what went wrong and suggest fixes.
+
+### 2e: Implement All Remaining (if requested)
+
+If the user requested "all" (e.g., `/implement user-auth all`):
+
+1. Implement steps sequentially, starting from the first incomplete step
+2. After each step, verify before moving to the next
+3. If any step fails verification, stop and report. Do not continue to subsequent steps.
+4. After each successful step, show a brief progress update:
+   ```
+   Step [N]/[total] complete: [description]
+   ```
+5. After all steps are done, proceed to 2f (Task Completion)
+
+### 2f: Update Progress
+
+After implementing a step (whether it succeeded or failed):
+
+1. **Update `status.md`:**
+   - Mark the completed step: `- [x] Step N: [description]`
+   - Add any notes about deviations from the plan under `## Notes`
+   - Update the `**Updated:**` date
+
+2. **Print a progress summary:**
+
+```
+## Progress: [Task Name]
+
+Step [N]/[total] complete: [what was done]
+
+[if verification passed:]
+Verified: [how — tests passed, no errors, etc.]
+
+[if verification failed:]
+Issue: [what went wrong]
+Suggested fix: [how to resolve]
+
+### Overall Progress
+[====------] [completed]/[total] steps
+Next: Step [N+1] — [description]
+
+To continue: /implement [task-name]
+```
+
+### 2g: Task Completion
+
+If all steps are now complete:
+
+1. Print a completion summary:
+
+```
+## Task Complete: [Task Name]
+
+All [N] steps implemented successfully.
+
+### What was built
+- [Summary of changes made across all steps]
+
+### Files changed
+- [List of files created or modified]
+
+Would you like to archive this task? (This moves it from active tasks to archive/)
+```
+
+2. If the user confirms archiving (or doesn't object), proceed to archive in Phase 3.
+3. If the user wants to keep it active (e.g., for further iteration), leave it in `task-memory/`.
+
+### 2h: Learn
+
+After completing work (whether one step or all steps), reflect:
+
+- Did anything unexpected happen during implementation? → Record as a lesson
+- Did you use a pattern that worked well? → Record as a pattern
+- Did any previous lesson prove wrong or need updating? → Update or delete it
+- Did the plan need adjustment? → Note this for future planning improvements
+
+## Phase 3: AUTO-SAVE & CURATE
+
+Follow the curation rules in `_memory-protocol.md`. For each piece of knowledge produced:
+
+- **Decisions made** during implementation → ADD to `project-memory/decisions/YYYY-MM-DD-short-name.md`
+- **Architecture changes** (if implementation changed the architecture) → UPDATE `project-memory/architecture.md`
+- **Lessons learned** → ADD/UPDATE `agent-memory/lessons.md`
+- **Patterns discovered** → ADD/UPDATE `agent-memory/patterns.md`
+- **Task progress** → UPDATE `task-memory/[task-name]/status.md`
+
+Apply ADD/UPDATE/DELETE/NOOP to each memory file. Most files will be NOOP.
+
+### Task Archiving (on completion)
+
+If the task is fully complete and the user has confirmed archiving:
+
+1. Update `task-memory/[task-name]/status.md`:
+   - Set `**Status:** complete`
+   - Fill in the `**Completed:**` field with today's date
+2. Move the entire `task-memory/[task-name]/` directory to `archive/[task-name]/`
+3. Remove the task from `## Active Tasks` in `index.md`
+
+## Phase 4: AUTO-INDEX
+
+Update `.mema/index.md`:
+1. Re-read the current index
+2. If a step was completed: update the task's summary in `## Active Tasks` (e.g., "3/7 steps complete")
+3. If the task was archived: move entry from `## Active Tasks` to remove it, and optionally note it under a completed tasks record
+4. Add entries for any new files (decisions, lessons, patterns)
+5. Update summaries for modified files
+6. Remove entries for deleted files
+7. Update the `**Updated:**` date

package/skills/onboard/SKILL.md

@@ -341,13 +341,15 @@ Build the index from the files you just created:
 
 ## Step 6: Update CLAUDE.md
 
-1. Read the current `CLAUDE.md` (if it exists)
-2. Search for `## Memory System` in the file content
-3. If found → **skip this step** (already configured)
-4. If not found → append the following section at the end of the file
-5. If `CLAUDE.md` doesn't exist → create the file with this content
+Read the current `CLAUDE.md` (if it exists) and follow the appropriate path:
+
+### Path A: CLAUDE.md already exists
+
+1. Search for `## Memory System` in the file content
+2. If found → **skip this step entirely** (already configured). Record outcome as **skipped**.
+3. If not found → append the Memory System section (see below) at the end of the file. Record outcome as **appended**.
 
-Append this section:
+Memory System section to append:
 
 ```
 ## Memory System
@@ -359,6 +361,134 @@ Memory lives in `.mema/`. At the start of each task, read `.mema/index.md` to lo
 Memory is managed automatically by skills — do not manually modify `.mema/` files unless correcting an error.
 ```
 
+### Path B: CLAUDE.md does NOT exist — Generate comprehensive file
+
+Follow sub-steps 6a through 6f to build a rich CLAUDE.md from scratch. Use the scan data collected in Step 4 for all content. Record outcome as **generated**.
+
+#### 6a: Ask user "About Me"
+
+Ask the user a single question using the AskUserQuestion tool:
+
+> "Before I generate your CLAUDE.md, I'd like to personalize it. How would you describe yourself? (e.g., experience level, preferences for code style, anything you want Claude to know)"
+
+Provide 3 options:
+- **Junior developer** — "I'm learning. Explain decisions, be thorough in comments, correct my terminology gently."
+- **Senior developer** — "I'm experienced. Keep explanations brief, focus on trade-offs and edge cases."
+- **Skip** — "Skip personalization, use a sensible default."
+
+If the user selects "Skip" or doesn't respond, use this default:
+
+```
+When I ask you to implement something, briefly explain key decisions. Prefer clear, well-commented code.
+```
+
+#### 6b: Write the `# About Me` section
+
+Use the user's response from 6a to write a natural-language paragraph (3-5 lines). This section uses **H1** (`# About Me`), matching mema-kit's own CLAUDE.md convention.
+
+#### 6c: Write the `## Project Overview` section
+
+Using Step 4 scan data, generate three sub-sections:
+
+**Opening paragraph:** Project name (from `package.json` name field, `README.md` title, or directory name as fallback) and a 1-2 sentence description of what the project does.
+
+**`### Repository Structure`:** A directory tree (top-level + 1 level deep) with inline comments explaining each directory's purpose. Use the `tree` format:
+
+```
+project-name/
+├── src/           # Source code
+├── tests/         # Test suite
+└── package.json   # Dependencies and scripts
+```
+
+**`### Architecture`:** Architecture pattern (e.g., REST API, CLI tool, library), key entry points, and data flow. Keep to 2-4 sentences. If the project is too simple or unclear for an architecture description, write: "Architecture details will be added as the project grows."
+
+#### 6d: Write the `## Coding Standards` section
+
+Using Step 4c source file analysis, generate a bullet list covering:
+
+- **Naming:** Conventions observed (camelCase, snake_case, kebab-case for files, etc.)
+- **Style:** Formatting patterns (semicolons, quotes, indentation)
+- **Patterns:** Recurring code patterns (e.g., "error-first callbacks", "async/await throughout")
+- **Tooling:** Linting/formatting tools detected (ESLint, Prettier, Black, rustfmt, etc. — check `devDependencies`, config files like `.eslintrc`, `.prettierrc`, `pyproject.toml [tool.black]`)
+
+If insufficient data for any bullet, use a placeholder like: "No linting configuration detected — consider adding one."
+
+#### 6e: Write the `## Technical Workflows` section
+
+Using Step 4a package manager files (`package.json` scripts, `Makefile` targets, `pyproject.toml [tool.poetry.scripts]`, `Cargo.toml`, etc.), generate a list of common commands:
+
+```
+- `npm run dev` — Start development server
+- `npm test` — Run test suite
+- `npm run build` — Build for production
+```
+
+Include dev, test, build, and lint commands at minimum (if they exist). If no commands are detected, write: "No build/test commands detected. Add scripts to `package.json` (or equivalent) as the project matures."
+
+#### 6f: Write the `## Skill Commands` and `## Memory System` sections
+
+**Skill Commands:** Scan the `.claude/skills/` directory. For each subdirectory containing a `SKILL.md`, read the YAML frontmatter `description` field. Generate an entry:
+
+```
+- `/skill-name` — [description from frontmatter]
+```
+
+If no skills are found (shouldn't happen since we just installed them, but as a fallback):
+
+```
+- `/onboard` — Bootstrap the mema-kit memory system
+- `/recall` — Recall project memory into current session
+- `/create-skill` — Generate a new memory-aware skill
+```
+
+**Memory System:** Append the standard Memory System section (same text as Path A).
+
+#### Assemble the final CLAUDE.md
+
+Combine all sections into a single file in this order and write it:
+
+```
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with code in this repository.
+
+# About Me
+[Content from 6b]
+
+## Project Overview
+
+[Content from 6c — opening paragraph]
+
+### Repository Structure
+
+[Content from 6c — tree]
+
+### Architecture
+
+[Content from 6c — architecture description]
+
+## Coding Standards
+
+[Content from 6d]
+
+## Technical Workflows
+
+[Content from 6e]
+
+## Skill Commands
+
+[Content from 6f — skill list]
+
+## Memory System
+
+This project uses mema-kit for persistent memory across sessions.
+
+Memory lives in `.mema/`. At the start of each task, read `.mema/index.md` to load relevant context. After completing work, curate and save knowledge following the memory protocol in `.claude/skills/_memory-protocol.md`.
+
+Memory is managed automatically by skills — do not manually modify `.mema/` files unless correcting an error.
+```
+
 ## Step 7: Update .gitignore
 
 1. Read the current `.gitignore` (if it exists)
@@ -378,14 +508,22 @@ Append this block:
 
 ## Step 8: Confirm to the User
 
-Print a summary of what was done, including what you discovered about the project:
+Print a summary of what was done, including what you discovered about the project. Use the CLAUDE.md outcome recorded in Step 6 to select the appropriate message.
+
+For the CLAUDE.md line, use the matching outcome:
+
+- **generated** → `[check] CLAUDE.md generated with project overview, coding standards, workflows, and memory system`
+- **appended** → `[check] CLAUDE.md updated — memory system section appended`
+- **skipped** → `[check] CLAUDE.md — memory system section already present`
+
+### Fresh setup (first run):
 
 ```
 mema-kit initialized! Here's what was set up:
 
 [check] .mema/ directory structure (memory system)
 [check] Memory templates in .mema/_templates/
-[check] CLAUDE.md updated with memory system conventions
+[check] [CLAUDE.md outcome message from above]
 [check] .gitignore updated to exclude .mema/
 
 Project scan results:
@@ -403,14 +541,16 @@ Memory populated:
 Next: Start working on your project. Memory will be loaded and saved automatically by any mema-kit skill.
 ```
 
-If this was a re-run (some items already existed), adjust the summary to show what was verified vs. created:
+### Re-run (some items already existed):
+
+Adjust the summary to show what was verified vs. created:
 
 ```
 mema-kit verified! Everything looks good:
 
 [check] .mema/ directory structure — already exists, verified
 [check] Memory templates — already exist, skipped
-[check] CLAUDE.md — memory section already present
+[check] [CLAUDE.md outcome message from above]
 [check] .gitignore — .mema/ already excluded
 
 Your setup is intact. No changes were needed.

package/skills/plan/SKILL.md

@@ -0,0 +1,206 @@
+---
+description: Break a high-level goal into a structured implementation plan. Explores the codebase, produces step-by-step specs, and saves them to task-memory/ for use by /implement.
+---
+
+# /plan — Implementation Planning
+
+You are executing the /plan skill. Follow these steps carefully.
+
+This skill takes a user's goal (e.g., `/plan add user authentication`), explores the codebase, and produces a detailed implementation plan saved to `.mema/task-memory/[task-name]/`.
+
+## Phase 1: AUTO-LOAD
+
+1. Read `.mema/index.md` to understand current project state
+2. If `index.md` is missing or `.mema/` does not exist:
+   - Tell the user: "No memory found. Run `/onboard` first to set up mema-kit for this project."
+   - **Stop here** — do not continue to further steps.
+3. If `index.md` is empty, run the **Rebuild Procedure** from `_memory-protocol.md`
+4. Load relevant memory files:
+   - `project-memory/architecture.md` — to understand the current stack and structure
+   - `project-memory/requirements.md` — to check how the goal fits project requirements
+   - `project-memory/decisions/` — recent decisions that might affect the plan
+   - `agent-memory/lessons.md` — mistakes to avoid in the plan
+   - `agent-memory/patterns.md` — reusable approaches to incorporate
+
+Read only what's needed — don't load everything.
+
+## Phase 2: WORK
+
+### 2a: Parse the Goal
+
+Extract the task goal from the user's input. The goal is everything after `/plan`.
+
+- Example: `/plan add user authentication` → goal is "add user authentication"
+- Example: `/plan refactor the database layer` → goal is "refactor the database layer"
+
+If no goal is provided, ask the user: "What would you like to plan? Describe your goal in a sentence or two."
+
+**Derive the task name** from the goal in kebab-case:
+- "add user authentication" → `user-authentication`
+- "refactor the database layer" → `database-layer-refactor`
+- Keep it short (2-4 words max). Drop filler words like "add", "create", "the".
+
+### 2b: Check for Existing Task
+
+Check if `task-memory/[task-name]/` already exists:
+
+- **If it exists:** Read the existing `plan.md`, `context.md`, and `status.md`. Tell the user: "Found an existing plan for [task-name]. Would you like to revise it, or start fresh?" If revising, load the existing plan as a starting point. If starting fresh, overwrite the existing files.
+- **If it doesn't exist:** Continue to the next step.
+
+### 2c: Explore the Codebase
+
+Before writing the plan, explore the codebase to understand what exists and what needs to change. This is the intelligence step — don't skip it.
+
+1. **Identify relevant files** — Based on the goal and loaded architecture, determine which source files, configs, and tests are relevant
+2. **Read representative files** — Read 3-5 key files to understand current patterns, conventions, and structure
+3. **Map dependencies** — Note what existing code the new work depends on or affects
+4. **Identify constraints** — Note any technical constraints, compatibility requirements, or limitations discovered
+
+### 2d: Clarify if Needed
+
+If the goal is ambiguous, ask **1-2 clarifying questions** (no more). Use the AskUserQuestion tool.
+
+Good clarifying questions:
+- "Should X support Y, or is Z sufficient for now?"
+- "Do you want this to follow the existing pattern in [file], or take a different approach?"
+
+Skip this step if the goal is clear from context + exploration.
+
+### 2e: Write the Plan
+
+Using your exploration findings and loaded memory, produce the plan in three parts:
+
+**General Plan** — High-level approach in 1-2 paragraphs:
+- What are we building/changing?
+- How does it fit with the existing architecture?
+- What key architectural decisions does this plan make?
+
+**Detailed Steps** — Step-by-step implementation specs. Each step must include:
+- **Action:** What to do (create file, modify function, add test, etc.)
+- **Files:** Specific file paths to create or modify
+- **Details:** Enough detail that `/implement` can execute the step without ambiguity
+- **Dependencies:** Which prior steps must be complete first (if any)
+
+Rules for steps:
+- Each step should be small enough to implement in a single `/implement` invocation
+- Order steps logically (foundations first, then features, then tests, then cleanup)
+- Be specific about file paths — use the actual paths discovered during exploration
+- Include test steps where appropriate (not just at the end)
+
+**Out of Scope** — Explicitly list what this plan does NOT cover. This prevents scope creep during implementation.
+
+### 2f: Write Task Files
+
+Create `task-memory/[task-name]/` with three files:
+
+**`context.md`** — Exploration findings relevant to this task:
+```
+# [Task Name] — Exploration Context
+
+**Status:** active | **Updated:** [today's date]
+
+## Summary
+[2-3 sentences: what was explored and the key takeaway]
+
+## Key Findings
+- [Important facts, constraints, or insights discovered during exploration]
+
+## Open Questions
+- [Anything unresolved that might affect implementation]
+
+## Relates To
+- [Links to related memory files]
+```
+
+**`plan.md`** — The full implementation plan:
+```
+# [Task Name] — Implementation Plan
+
+**Status:** active | **Updated:** [today's date]
+
+## General Plan
+[High-level approach from 2e]
+
+## Detailed Plan
+
+### Step 1: [Action]
+- **Files:** `path/to/file`
+- **Details:** [Specific implementation details]
+- **Dependencies:** None
+
+### Step 2: [Action]
+- **Files:** `path/to/file`
+- **Details:** [Specific implementation details]
+- **Dependencies:** Step 1
+
+[... more steps ...]
+
+## Out of Scope
+- [What this plan does NOT cover]
+```
+
+**`status.md`** — Progress checklist mirroring the plan:
+```
+# [Task Name] — Status
+
+**Status:** active | **Updated:** [today's date]
+
+## Progress
+
+- [ ] Step 1: [description]
+- [ ] Step 2: [description]
+- [ ] Step 3: [description]
+
+## Notes
+<!-- Any blockers, deviations from plan, or important observations. -->
+
+## Completed
+**Completed:**
+```
+
+### 2g: Present the Plan
+
+Print a summary to the user:
+
+```
+## Plan: [Task Name]
+
+### Approach
+[1-2 sentence summary of general plan]
+
+### Steps ([N] total)
+1. [Step 1 summary]
+2. [Step 2 summary]
+3. [Step 3 summary]
+...
+
+### Out of Scope
+- [Item 1]
+- [Item 2]
+
+---
+Plan saved to task-memory/[task-name]/
+To start implementing: /implement [task-name]
+```
+
+## Phase 3: AUTO-SAVE & CURATE
+
+Follow the curation rules in `_memory-protocol.md`. For each piece of knowledge produced:
+
+- **Decisions made** about approach → ADD to `project-memory/decisions/YYYY-MM-DD-short-name.md` (only if the plan includes a significant architectural or technical decision worth preserving beyond this task)
+- **Architecture insights** discovered during exploration → UPDATE `project-memory/architecture.md` (only if you found something missing or incorrect)
+- **Lessons learned** during planning → ADD/UPDATE `agent-memory/lessons.md`
+- **Patterns discovered** during exploration → ADD/UPDATE `agent-memory/patterns.md`
+
+Apply ADD/UPDATE/DELETE/NOOP to each memory file. Most files will be NOOP.
+
+**Do NOT save the plan itself as a decision.** The plan lives in task-memory. Only save standalone decisions that have value beyond this specific task.
+
+## Phase 4: AUTO-INDEX
+
+Update `.mema/index.md`:
+1. Re-read the current index
+2. Add an entry under `## Active Tasks`: `- \`task-memory/[task-name]/\` — [one-line summary] (plan ready)`
+3. Update summaries for any modified files (decisions, lessons, patterns)
+4. Remove entries for any deleted files
+5. Update the `**Updated:**` date