mema-kit 1.0.3 → 1.0.5

package/README.md

@@ -4,7 +4,7 @@ Memory protocol kit for Claude Code skills. Give any skill persistent, curated m
 
 **What it does:** A `.mema/` directory in your project stores architecture decisions, requirements, lessons learned, and reusable patterns as curated markdown. Skills automatically load relevant context at the start of each session and save curated knowledge when done.
 
-**Key differentiator:** The memory protocol (AUTO-LOAD → WORK → AUTO-SAVE & CURATE → AUTO-INDEX) is a reusable pattern. Any skill you build can plug into it — not just the two that ship with mema-kit.
+**Key differentiator:** The memory protocol (AUTO-LOAD → WORK → AUTO-SAVE & CURATE → AUTO-INDEX) is a reusable pattern. Any skill you build can plug into it — not just the three that ship with mema-kit.
 
 ## Quick Start
 
@@ -15,15 +15,19 @@ npx mema-kit
 # 2. Open Claude Code and bootstrap memory
 claude
 > /onboard
+
+# 3. Next session: load memory into context
+> /recall
 ```
 
-`/onboard` scans your project, creates the `.mema/` memory structure, populates initial architecture and requirements docs, and configures CLAUDE.md and `.gitignore`.
+`/onboard` scans your project, creates the `.mema/` memory structure, populates initial architecture and requirements docs, and configures CLAUDE.md and `.gitignore`. `/recall` loads that memory into any future session.
 
 ## Built-in Skills
 
 | Command | Purpose |
 |---------|---------|
 | `/onboard` | Bootstrap memory for a project — scans codebase, creates `.mema/`, populates initial knowledge |
+| `/recall` | Load project memory into the current session — instant context on cold start |
 | `/create-skill` | Generate a new memory-aware skill with the correct lifecycle phases |
 
 ## How Memory Works

package/docs/guide.md

@@ -2,7 +2,7 @@
 
 **A memory protocol kit for Claude Code skills.**
 
-Two 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.
 
 ---
 
@@ -30,83 +30,227 @@ Think of it like a developer's notebook — it doesn't give you a bigger brain,
 npx mema-kit          # install skills to .claude/skills/
 claude
 > /onboard            # scan project, create .mema/, populate initial memory
+> /recall             # next new session: load memory into context
 ```
 
 `/onboard` reads your package.json, README, directory structure, and representative source files, then writes real content to `architecture.md` and `requirements.md`. Idempotent — safe to re-run.
 
+`/recall` loads your project memory into the current session — use it at the start of every new conversation to restore context instantly.
+
+---
+
+## Recalling Memory: /recall
+
+Every new Claude Code session starts with a blank context. `/recall` fixes the cold-start problem by reading `.mema/` and printing a formatted summary into the conversation.
+
+### Modes
+
+| Mode | Command | What you get |
+|------|---------|--------------|
+| **Minimal** (default) | `/recall` or `/recall minimal` | Purpose, stack, architecture, current status, memory map |
+| **Full** | `/recall full` | Everything in Minimal + recent decisions, lessons, patterns, active context & plans |
+
+### When to use which
+
+| Situation | Mode |
+|-----------|------|
+| Starting a new session, need quick context | Minimal |
+| Picking up a multi-day task | Full |
+| Onboarding a teammate to the project | Full |
+| Quick check on what decisions exist | Full |
+| Daily development work | Minimal |
+
+`/recall` is **read-only** — it never modifies memory files. Safe to run at any time.
+
 ---
 
-## 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
+
+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
 
-### Step 2: Create `/plan`
+### 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
+```
+
+### Full workflow example
+
+```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
 ```
 
-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`.
+---
+
+## 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.
 
-### Step 3: Create `/implement`
+### 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
@@ -126,6 +270,8 @@ The agent loads the plan, architecture, and past lessons. It implements each ste
 
 Each skill reads what previous skills wrote. The index ties it all together.
 
+> **Tip:** Start every new session with `/recall` to load project context before using other skills. It takes seconds and saves minutes of re-exploration.
+
 ---
 
 ## The Memory Protocol
@@ -177,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.3",
+  "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

package/skills/recall/SKILL.md

@@ -0,0 +1,135 @@
+---
+description: Recall project memory into the current session. Loads .mema/ knowledge (architecture, decisions, lessons, patterns) and prints a formatted summary. Use at the start of a session to restore context.
+---
+
+# /recall — Session Memory Recall
+
+You are executing the /recall skill. This is a **read-only** skill — it loads memory and prints a summary into the conversation. It never writes to any files.
+
+Follow these steps carefully.
+
+## Step 1: Determine Mode
+
+Parse the user's input to decide which mode to use:
+
+- **No arguments** or `minimal` → **Minimal mode** (default) — fast overview of project purpose, stack, and current status
+- `full` → **Full mode** — everything in Minimal plus decisions, lessons, patterns, and active context/plans
+
+If the user provides an unrecognized argument (not `minimal`, `full`, or empty):
+1. Warn them: "Unknown argument '[arg]'. Available modes: `minimal` (default), `full`."
+2. Fall back to **Minimal mode** and continue.
+
+## Step 2: AUTO-LOAD
+
+1. Read `.mema/index.md`
+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. Parse the index to identify available memory files and their summaries.
+
+## Step 3: Load Project Purpose
+
+Read the following files (skip any that don't exist):
+
+1. `.mema/project-memory/architecture.md` — extract tech stack, project structure, architecture pattern, and key commands
+2. `.mema/project-memory/requirements.md` — extract project purpose, key requirements, and constraints
+
+These form the core context for both Minimal and Full modes.
+
+## Step 4: Load Current Status
+
+1. Check the `## Active Tasks` section in `index.md`
+2. If there are active tasks listed, read any linked status files (e.g., `task-memory/[task-name]/status.md`)
+3. Note which tasks are in progress, their current step, and any blockers
+
+## Step 5: Load Additional Files (Full Mode Only)
+
+**Skip this step entirely if in Minimal mode.**
+
+In Full mode, also read these files (skip any that don't exist):
+
+1. **Recent decisions** — Read files listed under `## Recent Decisions` in `index.md`
+2. **Lessons** — Read `agent-memory/lessons.md`
+3. **Patterns** — Read `agent-memory/patterns.md`
+4. **Active context and plans** — Read any `context.md` and `plan.md` files linked from active tasks in `index.md`
+
+Read only files that exist and are listed in the index. Do not scan the directory tree for unlisted files.
+
+## Step 6: REPORT
+
+Print the memory summary directly into the conversation. **Never write output to a file.**
+
+Use the format below based on the current mode.
+
+---
+
+### Minimal Mode Output
+
+```
+## Project Memory (Minimal)
+
+### Purpose
+[Project name and what it does — from requirements.md]
+
+### Stack & Architecture
+[Tech stack, architecture pattern, key entry points — from architecture.md]
+
+### Current Status
+[Active tasks and their progress — from index.md + status files]
+[If no active tasks: "No active tasks."]
+
+### Memory Map
+[List each section from index.md with file count, e.g.:]
+- Project Knowledge: [N] files
+- Recent Decisions: [N] decisions
+- Agent Lessons: [N] lessons, [N] patterns
+
+---
+*Showing minimal recall. Use `/recall full` for decisions, lessons, and patterns.*
+```
+
+---
+
+### Full Mode Output
+
+```
+## Project Memory (Full)
+
+### Purpose
+[Project name and what it does — from requirements.md]
+
+### Stack & Architecture
+[Tech stack, architecture pattern, key entry points — from architecture.md]
+
+### Current Status
+[Active tasks and their progress — from index.md + status files]
+[If no active tasks: "No active tasks."]
+
+### Recent Decisions
+[For each decision file, list:]
+- **[Decision title]** ([date]) — [one-line summary or key choice made]
+[If no decisions: "No decisions recorded yet."]
+
+### Lessons
+[Bullet list of lessons from lessons.md]
+[If no lessons: "No lessons recorded yet."]
+
+### Patterns
+[Bullet list of patterns from patterns.md]
+[If no patterns: "No patterns recorded yet."]
+
+### Active Context & Plans
+[For each active task, summarize its context and plan]
+[If none: omit this section]
+
+### Memory Map
+- Project Knowledge: [N] files
+- Recent Decisions: [N] decisions
+- Agent Lessons: [N] lessons, [N] patterns
+- Active Tasks: [N] tasks
+- Archived Tasks: [N] archived
+```
+
+---
+
+**Important:** This skill is purely informational. If you notice memory files are missing or out of date, suggest the user run `/onboard` or the relevant skill — do not attempt to fix memory yourself.