mema-kit 1.0.6 → 1.1.0

package/skills/_memory-protocol.md

@@ -63,23 +63,28 @@ Update `.mema/index.md` to reflect all changes made in Phase 3. This is **mandat
 
 ## Per-File-Type Curation Rules
 
-### decision.md — Conservative curation
+### product/ files — Discovery phase outputs (seed, clarify, research, challenge, roadmap)
+- **Overwrite on re-run.** Each file represents the current state of understanding. Re-running a discovery skill replaces stale content with fresh analysis.
+- **NOOP** if the file is recent and the idea hasn't changed.
+- `roadmap.md` is special: UPDATE to add new features, but never delete existing feature entries — features with directories already created should be marked, not removed.
+
+### features/NNN-name/ files — Feature lifecycle files (spec, plan, tasks, status)
+- `spec.md` — **UPDATE** when requirements change; never delete a spec that has a corresponding plan.
+- `plan.md` — **Replace curation**: keep final version only; overwrite on re-run.
+- `tasks.md` — **Replace curation**: regenerate when plan changes; warn if tasks are partially complete.
+- `status.md` — **UPDATE** continuously during implementation; never delete.
+
+### project/decisions/ — Conservative curation
 - **Rarely delete.** Decisions are historical record. Even reversed decisions teach future sessions why something didn't work.
 - **UPDATE** when the decision is refined, expanded, or its status changes.
 - **ADD** reasoning if the original entry lacks a "why."
 - Only **DELETE** if the decision was recorded in error (wrong project, duplicate entry).
 
-### context.md — Aggressive curation
-- **Prune dead-end explorations.** If you explored 5 options and chose 1, delete the notes on the 4 rejected options. The decision file captures what was chosen and why.
-- **Consolidate findings.** If multiple explorations cover overlapping ground, merge them into one concise context file.
-- **DELETE** when a decision supersedes the exploration entirely (the exploration's value is now captured in the decision).
+### project/architecture.md and project/requirements.md — Replace curation
+- **UPDATE** when the stack or requirements change.
+- Keep current state only — these are reference documents, not history logs.
 
-### plan.md — Replace curation
-- **Keep the final version only.** Draft plans are noise once a final plan exists.
-- **UPDATE** during implementation — mark steps as complete, note adjustments.
-- **Do not create multiple plan versions.** Overwrite the plan when it changes.
-
-### lessons.md and patterns.md — Consolidation curation
+### agent/lessons.md and agent/patterns.md — Consolidation curation
 - **Merge similar lessons.** "Drizzle needs type casting" and "Drizzle enum handling requires explicit cast" are the same lesson — keep one entry with both examples.
 - **UPDATE** with new examples when the same pattern/lesson recurs.
 - **DELETE** if a lesson is proven wrong by later experience.
@@ -107,22 +112,24 @@ The index is a structured pointer map with four sections:
 ```
 # Memory Index
 
-**Updated:** 2026-02-23
+**Updated:** 2026-02-27
 
-## Active Tasks
-- `task-memory/api-setup/` — Setting up REST API with Fastify (plan ready, implementing)
+## Active Features
+- `features/001-user-auth/` — JWT authentication for API (in-progress, step 2/5)
+- `features/002-search/` — Full-text search across posts (pending)
 
-## Project Knowledge
-- `project-memory/architecture.md` — Node.js + Fastify + PostgreSQL + Drizzle stack
-- `project-memory/requirements.md` — Core requirements and constraints
+## Product Discovery
+- `product/seed.md` — Async standup tool for remote teams
+- `product/roadmap.md` — 6 features defined, 1 in progress
 
-## Recent Decisions
-- `project-memory/decisions/2026-02-23-tech-stack.md` — Chose Fastify + PostgreSQL + Drizzle
-- `project-memory/decisions/2026-02-23-auth-jwt.md` — JWT with refresh tokens for auth
+## Project Knowledge
+- `project/architecture.md` — Node.js + Fastify + PostgreSQL + Drizzle stack
+- `project/requirements.md` — Core requirements and constraints
+- `project/decisions/2026-02-27-auth-jwt.md` — JWT with refresh tokens for auth
 
-## Agent Lessons
-- `agent-memory/lessons.md` — 3 lessons recorded (Drizzle type casting, Fastify plugin order, test isolation)
-- `agent-memory/patterns.md` — 2 patterns recorded (route registration, error handling middleware)
+## Agent Knowledge
+- `agent/lessons.md` — 4 lessons recorded
+- `agent/patterns.md` — 3 patterns recorded
 ```
 
 Each entry is: `- \`file-path\` — one-line summary`
@@ -137,8 +144,8 @@ After every curated save:
 
 ### Rebuild Procedure (fallback)
 If `index.md` is missing, empty, or clearly stale (references files that don't exist):
-1. List all directories in `.mema/`: `project-memory/`, `task-memory/`, `agent-memory/`, `archive/`
-2. For each directory, list all `.md` files (excluding `_templates/`)
+1. List all directories in `.mema/`: `product/`, `features/`, `project/`, `agent/`, `archive/`
+2. For each directory, list all `.md` files
 3. Read the first 3 lines of each file to get title and metadata
 4. Generate index entries in the format above
 5. Write the rebuilt `index.md`

package/skills/mema.challenge/SKILL.md

@@ -0,0 +1,121 @@
+---
+description: Stress-test your idea by challenging assumptions, identifying risks, and surfacing blind spots. Saves a risk register and recommendations to product/challenge.md.
+---
+
+# /mema.challenge — Idea Stress-Test
+
+You are executing the /mema.challenge skill. Follow these steps carefully.
+
+This skill plays devil's advocate — it examines the idea critically to find what could go wrong before any code is written. A challenge that kills a weak idea is a success.
+
+## AUTO-LOAD
+
+1. Read `.mema/index.md`
+2. Read all available `product/` files:
+   - `product/seed.md` — the raw idea
+   - `product/clarify.md` — refined intent (if exists)
+   - `product/research.md` — competitive and market findings (if exists)
+3. Build a full picture of the idea before proceeding
+
+## WORK
+
+### Identify Assumptions
+
+List every assumption the idea depends on. For each:
+- **Validated**: supported by research or clear logic
+- **Risky**: not yet validated; failure would significantly harm the project
+
+Look for assumptions about: user behavior, market size, technical feasibility, competitive differentiation, and the team's ability to execute.
+
+### Build Risk Register
+
+For each significant risk:
+- **What's the risk?** — specific failure mode, not vague concern
+- **Severity**: High (project-threatening), Medium (costly), Low (manageable)
+- **Likelihood**: High (likely without mitigation), Medium (possible), Low (unlikely)
+- **Mitigation**: concrete action that reduces severity or likelihood
+
+### Identify Blind Spots
+
+What hasn't been considered?
+- Regulatory, legal, or privacy constraints?
+- Distribution and discovery — how will users find this?
+- Monetization — if relevant, is there a clear path?
+- What does the competition do better than this idea, not worse?
+- What's the failure mode if the key assumption is wrong?
+
+### Critical Risks
+
+If any risks are both High severity AND High likelihood:
+- Flag them explicitly
+- Suggest a pivot or alternative approach if possible
+- Do NOT hide critical problems — they're more valuable than false confidence
+
+### Handle Re-run
+
+If `challenge.md` already exists, show the previous summary and ask:
+
+"Previous challenge from [date]. Run fresh challenge, or update specific sections?"
+
+### Save
+
+Write `.mema/product/challenge.md`:
+
+```
+# [Project Name] — Challenge
+
+**Status:** active | **Updated:** [today's date]
+
+## Assumptions
+
+| Assumption | Status | Risk if Wrong |
+|------------|--------|---------------|
+| [Assumption] | ✓ Validated / ⚠ Risky | [Impact] |
+
+## Risk Register
+
+| Risk | Severity | Likelihood | Mitigation |
+|------|----------|------------|------------|
+| [Risk] | High/Med/Low | High/Med/Low | [Action] |
+
+## Blind Spots
+
+- [What hasn't been considered]
+
+## Critical Concerns
+
+[If any High/High risks: flag them clearly with recommended action]
+[If no critical risks: "No critical risks identified. Proceed with caution on the risky assumptions above."]
+
+## Recommended Actions Before Building
+
+- [Validate assumption X by doing Y]
+- [Resolve risk Z before committing to approach]
+```
+
+### Guide Next Step
+
+```
+Next: Run /mema.roadmap to synthesize everything into a project plan and feature list.
+```
+
+Or, if critical concerns were found:
+
+```
+⚠ Critical concerns found. Consider addressing them before building:
+[List critical risks]
+
+You can re-run /mema.clarify or /mema.research to address these, then re-run /mema.challenge.
+Or proceed to /mema.roadmap if you've decided to accept these risks.
+```
+
+## AUTO-SAVE & CURATE
+
+- ADD or UPDATE `product/challenge.md`
+- NOOP on all other memory files
+
+## AUTO-INDEX
+
+Update `.mema/index.md`:
+1. Add or update entry under `## Product Discovery`: `- \`product/challenge.md\` — [N] risks identified; [critical/no critical] concerns`
+2. Update `**Updated:**` date

package/skills/mema.clarify/SKILL.md

@@ -0,0 +1,109 @@
+---
+description: Refine a raw idea through targeted Q&A and save a structured summary of the clarified intent, audience, and scope.
+---
+
+# /mema.clarify — Idea Clarification
+
+You are executing the /mema.clarify skill. Follow these steps carefully.
+
+This skill turns a raw seed into a clear, structured problem statement through 2-3 rounds of targeted questions.
+
+## AUTO-LOAD
+
+1. Read `.mema/index.md`
+2. Read `.mema/product/seed.md`
+3. If `seed.md` is missing:
+   - Tell the user: "No seed found. Run `/mema.seed` first, or describe your idea now and I'll treat it as the seed."
+   - If the user provides an inline description, use it as the seed (save it to `product/seed.md` first)
+4. If `product/clarify.md` exists, read it to understand what was already clarified
+
+## WORK
+
+### Mirror Understanding
+
+Before asking questions, confirm your understanding of the idea:
+
+```
+Here's what I understand from your seed:
+
+[2-3 sentence summary of the idea]
+
+Is this roughly right? (Say yes to proceed, or correct anything)
+```
+
+If the user corrects something significant, update your understanding before continuing.
+
+### Ask Clarifying Questions
+
+Ask **3-5 targeted questions** covering:
+
+1. **Problem**: What specific pain point does this solve? Who experiences it right now?
+2. **Audience**: Who is the primary user? Be specific — not "developers" but "solo developers who use Claude Code daily."
+3. **Motivation**: Why does this need to exist? What's wrong with existing solutions?
+4. **Scope**: What's the smallest version that delivers real value? What's explicitly out of scope?
+5. **Constraints**: Any technical, budget, time, or team constraints to know about?
+
+Do not ask all 5 at once if the seed already answers some. Skip questions that are already clear from context.
+
+Allow follow-up rounds if answers raise new questions. Stop when the idea feels crisp — usually 2-3 exchanges.
+
+### Handle Re-run
+
+If `clarify.md` already exists, show the current summary and ask:
+
+"Clarification exists from [date]. Would you like to refine specific sections or start fresh?"
+
+- **Refine**: update named sections
+- **Fresh**: overwrite `clarify.md`
+
+### Save
+
+Write `.mema/product/clarify.md`:
+
+```
+# [Project Name] — Clarified Intent
+
+**Status:** active | **Updated:** [today's date]
+
+## Problem Being Solved
+
+[Specific problem — not "people need X" but "when Y happens, users can't Z because..."]
+
+## Target Audience
+
+[Specific description — role, context, pain point they experience]
+
+## Motivation
+
+[Why this needs to exist; what's wrong with current alternatives]
+
+## Scope
+
+**In scope:**
+- [Core capability 1]
+- [Core capability 2]
+
+**Out of scope:**
+- [Explicitly deferred item]
+
+## Constraints
+
+[Any technical, time, budget, or team constraints]
+```
+
+### Guide Next Step
+
+```
+Next: Run /mema.research to find what already exists and validate your approach.
+```
+
+## AUTO-SAVE & CURATE
+
+- ADD or UPDATE `product/clarify.md`
+- NOOP on all other memory files
+
+## AUTO-INDEX
+
+Update `.mema/index.md`:
+1. Add or update entry under `## Product Discovery`: `- \`product/clarify.md\` — Clarified intent: [audience] + [core problem in 5 words]`
+2. Update `**Updated:**` date

package/skills/mema.create-skill/SKILL.md

@@ -6,13 +6,23 @@ description: Generate a new memory-aware Claude Code skill. Creates a SKILL.md f
 
 You are creating a new Claude Code skill that integrates with mema-kit's memory protocol. Follow these steps carefully.
 
+## AUTO-LOAD
+
+1. Read `.mema/index.md` to understand current project state
+2. If `index.md` is missing or empty, run the **Rebuild Procedure** from `_memory-protocol.md`
+3. If `agent/patterns.md` exists, read it — check what skills have already been created to avoid duplicating existing skill logic
+
 ## Step 1: Interview
 
 Gather the following from the user. Keep it to **2-3 exchanges max** — don't over-interview.
 
+### Name validation (apply before asking anything else if name is already provided):
+- If the name matches a reserved built-in (`mema.onboard`, `mema.recall`, `mema.plan`, `mema.implement`, `mema.create-skill`), warn: "This name matches a built-in mema-kit skill. Using it in `.claude/skills/` will shadow the built-in. Continue? (yes/no)"
+- If the name is not kebab-case, convert it automatically and inform the user: "Name converted to kebab-case: [converted-name]"
+
 ### Required:
-1. **Skill name** — kebab-case (e.g., `review`, `debug`, `migrate`). If the user gives a name with spaces or camelCase, convert it.
-2. **Purpose** — What does this skill do? One sentence is enough.
+1. **Skill name** — kebab-case (e.g., `review`, `debug`, `migrate`).
+2. **Purpose** — What does this skill do? One sentence is enough. If the answer is a single word or fewer than 5 characters, ask one follow-up question to expand it before proceeding.
 
 ### Optional (offer sensible defaults):
 3. **Memory needs** — Does this skill need to:
@@ -28,10 +38,26 @@ If the user doesn't specify memory needs or complexity, default to **both** and
 
 ## Step 2: Generate SKILL.md
 
-Based on the interview answers, generate a SKILL.md file. Use the appropriate template below based on complexity level.
+Based on the interview answers, generate a SKILL.md file using the appropriate template below.
 
 **Critical rule:** Generated skills reference `_memory-protocol.md` for curation rules. NEVER duplicate the memory protocol content inside generated skills.
 
+### Generating the WORK phase (applies to all templates):
+
+When filling the WORK phase of any template:
+1. **Decompose the purpose** into 2–5 concrete developer actions — ask yourself: "what would a skilled developer do, step by step, to accomplish [purpose]?"
+2. **Write each action** as an imperative instruction sentence (e.g., "Read each changed file and identify…"; "Compare findings against…"; "Write a summary of…")
+3. **If the purpose has multiple distinct concerns** (multiple verbs, the word "and", or conditional logic) — organize into sub-sections: `### 2a: [First concern]`, `### 2b: [Second concern]`
+
+### Generating AUTO-LOAD hints (standard and advanced templates):
+
+Scan the purpose for domain keywords and replace the `[Add or remove entries…]` placeholder with relevant `.mema/` paths:
+- Always include: `project/architecture.md` — technical context; `agent/lessons.md` — mistakes to avoid
+- "decide / choose / compare / evaluate" → add `project/decisions/` — past decisions on this domain
+- "pattern / reuse / template" → add `agent/patterns.md` — reusable approaches
+- "implement / build / create / migrate" → add active `features/[feature-name]/` if one exists in the index
+- "test / validate / check / audit" → note in `agent/lessons.md` entry that testing lessons are especially relevant
+
 ---
 
 ### Simple Template (3 phases)
@@ -54,13 +80,9 @@ You are executing the /[skill-name] skill. Follow these steps carefully.
 
 ## Phase 2: WORK
 
-[Core skill logic goes here — describe what the skill does step by step]
+[Generate 2–5 concrete steps from the purpose — no placeholder text]
 
-1. [First action]
-2. [Second action]
-3. [Third action]
-
-Use the loaded memory context to inform your work. Reference architecture decisions, past lessons, and patterns where relevant.
+Use the loaded memory context to inform your work.
 
 ## Phase 3: REPORT
 
@@ -92,19 +114,13 @@ You are executing the /[skill-name] skill. Follow these steps carefully.
 4. Read only what's needed — don't load everything
 
 **Relevant memory for this skill:**
-- `project-memory/architecture.md` — for technical context
-- `project-memory/decisions/` — for past decisions related to this work
-- `agent-memory/lessons.md` — for mistakes to avoid
-- `agent-memory/patterns.md` — for reusable approaches
-- [Add or remove entries based on the skill's purpose]
+- `project/architecture.md` — for technical context
+- `agent/lessons.md` — for mistakes to avoid
+[Derive additional entries from purpose keywords per Step 2 generation instructions]
 
 ## Phase 2: WORK
 
-[Core skill logic goes here — describe what the skill does step by step]
-
-1. [First action]
-2. [Second action]
-3. [Third action]
+[Generate 2–5 concrete steps from the purpose — no placeholder text]
 
 Use the loaded memory context to inform your work.
 
@@ -112,10 +128,10 @@ Use the loaded memory context to inform your work.
 
 Follow the curation rules in `_memory-protocol.md`. For each piece of knowledge produced:
 
-- **Decisions made** → ADD to `project-memory/decisions/YYYY-MM-DD-short-name.md`
-- **Architecture changes** → UPDATE `project-memory/architecture.md`
-- **Lessons learned** → ADD/UPDATE `agent-memory/lessons.md`
-- **Patterns discovered** → ADD/UPDATE `agent-memory/patterns.md`
+- **Decisions made** → ADD to `project/decisions/YYYY-MM-DD-short-name.md`
+- **Architecture changes** → UPDATE `project/architecture.md`
+- **Lessons learned** → ADD/UPDATE `agent/lessons.md`
+- **Patterns discovered** → ADD/UPDATE `agent/patterns.md`
 - **Exploration findings** → ADD to appropriate `task-memory/` or `project-memory/` file
 
 Apply ADD/UPDATE/DELETE/NOOP to each memory file. Most files will be NOOP.
@@ -148,29 +164,25 @@ You are executing the /[skill-name] skill. Follow these steps carefully.
 1. Read `.mema/index.md` to understand current project state
 2. If `index.md` is missing or empty, run the **Rebuild Procedure** from `_memory-protocol.md`
 3. Based on the user's request, identify and read relevant memory files:
-   - Task-specific: `task-memory/[task-name]/` (context, plan, status)
-   - Project-wide: `project-memory/architecture.md`, relevant decisions
-   - Agent knowledge: `agent-memory/lessons.md`, `agent-memory/patterns.md`
+   - Task-specific: `features/[feature-name]/` (context, plan, status)
+   - Project-wide: `project/architecture.md`, relevant decisions
+   - Agent knowledge: `agent/lessons.md`, `agent/patterns.md`
 4. Read only what's needed — don't load everything
 
 ## Phase 2: WORK
 
 ### 2a: Task Setup
 If no task directory exists for this work:
-1. Create `task-memory/[task-name]/`
+1. Create `features/[feature-name]/`
 2. Write initial `context.md` with the task description and relevant findings
 
 If a task directory exists, read the current status and continue where you left off.
 
 ### 2b: Core Work
 
-[Core skill logic goes here — describe what the skill does step by step]
-
-1. [First action]
-2. [Second action]
-3. [Third action]
+[Generate 2–5 concrete steps from the purpose — no placeholder text]
 
-Track progress by updating `task-memory/[task-name]/status.md` as you go.
+Track progress by updating `features/[feature-name]/status.md` as you go.
 
 ### 2c: Learn
 
@@ -183,18 +195,18 @@ After completing work, reflect:
 
 Follow the curation rules in `_memory-protocol.md`. For each piece of knowledge produced:
 
-- **Decisions made** → ADD to `project-memory/decisions/YYYY-MM-DD-short-name.md`
-- **Architecture changes** → 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`
+- **Decisions made** → ADD to `project/decisions/YYYY-MM-DD-short-name.md`
+- **Architecture changes** → UPDATE `project/architecture.md`
+- **Lessons learned** → ADD/UPDATE `agent/lessons.md`
+- **Patterns discovered** → ADD/UPDATE `agent/patterns.md`
+- **Task progress** → UPDATE `features/[feature-name]/status.md`
 
 Apply ADD/UPDATE/DELETE/NOOP to each memory file. Most files will be NOOP.
 
 ### Task Completion
 If the task is fully complete:
-1. Mark `task-memory/[task-name]/status.md` as `**Status:** complete`
-2. Move `task-memory/[task-name]/` to `archive/[task-name]/`
+1. Mark `features/[feature-name]/status.md` as `**Status:** complete`
+2. Move `features/[feature-name]/` to `archive/[task-name]/`
 3. Remove the task from "Active Tasks" in `index.md`
 
 ## Phase 4: AUTO-INDEX
@@ -209,11 +221,43 @@ Update `.mema/index.md`:
 
 ---
 
+## Step 2.5: Draft Review
+
+Before writing any file to disk, show the user the complete generated SKILL.md for review.
+
+1. Render the full generated SKILL.md content inside a fenced code block
+2. Ask:
+   > "Does this look correct? Reply **APPROVE** to write the file, describe a specific change to revise, or **CANCEL** to exit without writing."
+3. **On a change request**: Apply the change to the named section only. Re-render the full draft. Repeat the prompt. If the user has requested more than 3 revisions, warn: "Multiple revisions requested. Consider re-running `/mema.create-skill` with a more detailed purpose." — then continue with the current draft.
+4. **On CANCEL**: Exit immediately. Do not write, create, or modify any files.
+5. **On APPROVE**: Proceed to Step 3.
+
 ## Step 3: Write the File
 
-1. Write the generated SKILL.md to `.claude/skills/[skill-name]/SKILL.md`
-2. Create the directory if it doesn't exist
-3. If the file already exists, warn the user and ask before overwriting
+### Existence check
+
+Before writing, check whether `.claude/skills/[skill-name]/SKILL.md` already exists.
+
+**If the file does NOT exist:**
+1. Create the directory `.claude/skills/[skill-name]/` if it doesn't exist
+2. Write the approved content to `.claude/skills/[skill-name]/SKILL.md`
+
+**If the file EXISTS:**
+1. Read the existing file; extract the `description` frontmatter value and all `## Phase`, `## Step`, and `## AUTO-*` headings (headings only, not body content)
+2. Show the user:
+   ```
+   Existing skill found: /[skill-name]
+   Description: [existing description]
+   Sections: [list of headings]
+
+   Choose an action:
+   (1) Enhance existing — apply a described change to specific sections
+   (2) Overwrite — start fresh (goes through preview)
+   (3) Cancel — exit without changes
+   ```
+3. **Option 1 — Enhance**: Ask "What specifically should I change?" Apply the directive to the named section(s) only, preserving everything else. Run the modified file through the Step 2.5 Draft Review flow, then write on APPROVE.
+4. **Option 2 — Overwrite**: Discard the existing content. Return to Step 1 and run the full interview → generation → preview flow from scratch.
+5. **Option 3 — Cancel**: Exit. No file changes.
 
 ## Step 4: Verify
 
@@ -223,6 +267,7 @@ Read back the file you just wrote and confirm:
 - Memory file paths use `.mema/` (not `.praxis/` or any other prefix)
 - The skill references `_memory-protocol.md` for curation rules (standard and advanced only)
 - No memory protocol content is duplicated inside the skill
+- No `[…]`-style placeholder text remains
 
 ## Step 5: Confirm
 
@@ -240,3 +285,20 @@ To use it:
 
 The skill follows the mema-kit memory protocol and will [read from / write to / read from and write to] .mema/ automatically.
 ```
+
+## AUTO-SAVE & CURATE
+
+Follow the curation rules in `_memory-protocol.md`.
+
+**If a skill file was written** (user did not CANCEL):
+- ADD/UPDATE `agent/patterns.md` with a lightweight record: skill name, complexity level, one-sentence purpose, action taken (`created` / `enhanced` / `overwritten`), date (`YYYY-MM-DD`)
+
+**If no file was written** (user cancelled at any step):
+- NOOP — no memory changes
+
+## AUTO-INDEX
+
+Update `.mema/index.md`:
+1. Re-read the current index
+2. If `agent/patterns.md` was modified, update its summary entry
+3. Update the `**Updated:**` date