mema-kit 1.0.6 → 1.1.0

package/skills/mema.plan/SKILL.md

@@ -1,206 +1,150 @@
 ---
-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 /mema.implement.
+description: Create a technical implementation plan for a feature. Reads the feature spec, explores the codebase, and writes a detailed plan to features/NNN-name/plan.md for use by /mema.tasks and /mema.implement.
 ---
 
-# /mema.plan — Implementation Planning
+# /mema.plan — Feature Technical Design
 
 You are executing the /mema.plan skill. Follow these steps carefully.
 
-This skill takes a user's goal (e.g., `/mema.plan add user authentication`), explores the codebase, and produces a detailed implementation plan saved to `.mema/task-memory/[task-name]/`.
+This skill takes a feature spec (created by `/mema.specify`) and produces a technical implementation plan — what to build, how it fits the existing architecture, and which files to change.
 
 ## 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 `/mema.onboard` first to set up mema-kit for this project."
-   - **Stop here** — do not continue to further steps.
+   - Tell the user: "No memory found. Run `/mema.onboard` first to set up mema-kit."
+   - **Stop here.**
 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.
+4. Load relevant memory:
+   - `project/architecture.md` — current stack and patterns
+   - `project/requirements.md` — constraints to respect
+   - `project/decisions/` — past decisions that affect this plan
+   - `agent/lessons.md` — mistakes to avoid
+   - `agent/patterns.md` — reusable approaches to apply
 
 ## Phase 2: WORK
 
-### 2a: Parse the Goal
-
-Extract the task goal from the user's input. The goal is everything after `/mema.plan`.
+### 2a: Select Feature
 
-- Example: `/mema.plan add user authentication` → goal is "add user authentication"
-- Example: `/mema.plan refactor the database layer` → goal is "refactor the database layer"
+Parse the user's input:
+- **Feature name or number given:** `/mema.plan user-auth` or `/mema.plan 001` → find matching `features/NNN-name/`
+- **No input:** list features that have a `spec.md` but no `plan.md`; ask which to plan
 
-If no goal is provided, ask the user: "What would you like to plan? Describe your goal in a sentence or two."
+If the feature directory doesn't exist:
+- Tell the user: "No feature found for '[input]'. Run `/mema.specify` first to create a feature spec."
+- **Stop here.**
 
-**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".
+If `plan.md` already exists:
+- Tell the user: "A plan already exists for [feature-name]. Would you like to revise it or start fresh?"
+- If revising: load the existing plan as a starting point.
 
-### 2b: Check for Existing Task
+### 2b: Load the Feature Spec
 
-Check if `task-memory/[task-name]/` already exists:
+Read `features/NNN-name/spec.md` in full.
 
-- **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.
+If `spec.md` is missing:
+- Tell the user: "No spec found for [feature-name]. Run `/mema.specify` first."
+- **Stop here.**
 
 ### 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.
+Before writing the plan, explore what already exists. Read 3–5 files relevant to this feature:
+- Entry points or route files the feature will touch
+- Existing patterns for similar features (e.g., if adding auth, read an existing auth-adjacent file)
+- Test files for the area being changed
+- Config files if the feature requires configuration changes
 
-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
+Note: current patterns, naming conventions, architectural constraints, and anything the spec didn't mention that affects implementation.
 
 ### 2d: Clarify if Needed
 
-If the goal is ambiguous, ask **1-2 clarifying questions** (no more). Use the AskUserQuestion tool.
+If the spec leaves meaningful technical ambiguity, ask **one clarifying question** using AskUserQuestion. Skip this step if the spec is clear.
 
 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.
+- "The spec mentions [X]. Should this follow the existing pattern in [file], or take a new approach?"
+- "Should this feature include tests, or is that deferred?"
 
 ### 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 `/mema.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 `/mema.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)
+Produce a technical plan in these parts:
 
-**Out of Scope** — Explicitly list what this plan does NOT cover. This prevents scope creep during implementation.
+**Approach** — 1–2 paragraphs:
+- What architectural approach will be used?
+- How does it fit the existing codebase patterns?
+- What key technical decisions does this plan make?
 
-### 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]
+**Key Entities / Data** (if relevant):
+- Data structures, models, or types involved
+- Database schema changes if applicable
 
-## Summary
-[2-3 sentences: what was explored and the key takeaway]
+**File Changes** — the complete set of files to create or modify:
+- List each file with a one-line description of what changes
+- Include test files
 
-## Key Findings
-- [Important facts, constraints, or insights discovered during exploration]
+**Implementation Notes** — gotchas, constraints, dependencies:
+- Lessons from lessons.md that apply
+- Patterns from patterns.md to follow
+- Non-obvious dependencies or ordering requirements
 
-## Open Questions
-- [Anything unresolved that might affect implementation]
+### 2f: Write Plan File
 
-## Relates To
-- [Links to related memory files]
-```
+Write `features/NNN-name/plan.md`:
 
-**`plan.md`** — The full implementation plan:
 ```
-# [Task Name] — Implementation Plan
+# [Feature Name] — 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
+## Approach
 
-### Step 2: [Action]
-- **Files:** `path/to/file`
-- **Details:** [Specific implementation details]
-- **Dependencies:** Step 1
+[High-level technical approach from 2e]
 
-[... more steps ...]
+## Key Entities
 
-## Out of Scope
-- [What this plan does NOT cover]
-```
+[Data structures / models if applicable]
 
-**`status.md`** — Progress checklist mirroring the plan:
-```
-# [Task Name] — Status
+## File Changes
 
-**Status:** active | **Updated:** [today's date]
+- `path/to/file` — [what changes]
+- `path/to/file` — [what changes]
 
-## Progress
+## Implementation Notes
 
-- [ ] Step 1: [description]
-- [ ] Step 2: [description]
-- [ ] Step 3: [description]
-
-## Notes
-<!-- Any blockers, deviations from plan, or important observations. -->
-
-## Completed
-**Completed:**
+[Gotchas, patterns to follow, ordering requirements]
 ```
 
-### 2g: Present the Plan
-
-Print a summary to the user:
+### 2g: Present to User
 
 ```
-## Plan: [Task Name]
+## Plan: [Feature Name]
 
 ### Approach
-[1-2 sentence summary of general plan]
+[1-2 sentence summary]
 
-### Steps ([N] total)
-1. [Step 1 summary]
-2. [Step 2 summary]
-3. [Step 3 summary]
-...
-
-### Out of Scope
-- [Item 1]
-- [Item 2]
+### Files to change ([N] total)
+- [file] — [what]
+- [file] — [what]
 
 ---
-Plan saved to task-memory/[task-name]/
-To start implementing: /mema.implement [task-name]
+Plan saved to features/[NNN-name]/plan.md
+Next: /mema.tasks [NNN-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`
+Follow the curation rules in `_memory-protocol.md`:
 
-Apply ADD/UPDATE/DELETE/NOOP to each memory file. Most files will be NOOP.
+- **Significant architectural decisions** made during planning → ADD to `project/decisions/YYYY-MM-DD-short-name.md`
+- **Architecture discoveries** (found something missing or wrong in architecture.md) → UPDATE `project/architecture.md`
+- **Lessons** from planning → ADD/UPDATE `agent/lessons.md`
+- **Patterns** identified → ADD/UPDATE `agent/patterns.md`
 
-**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.
+Most files will be NOOP.
 
 ## 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
+2. If the feature's entry in `## Active Features` doesn't mention a plan, update its summary: add "(plan ready)"
+3. Add entries for any new decision files
+4. Update `**Updated:**` date

package/skills/mema.recall/SKILL.md

@@ -12,80 +12,73 @@ Follow these steps carefully.
 
 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
+- **No arguments** or `minimal` → **Minimal mode** (default) — fast overview with active features, project identity, and next action
+- `full` → **Full mode** — everything in Minimal plus decisions, lessons, patterns, and product discovery
 
-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.
+If the user provides an unrecognized argument, warn them and fall back to Minimal mode.
 
 ## 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 `/mema.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.
+   - Tell the user: "No memory found. For an existing project, run `/mema.onboard` to set up mema-kit. For a new idea, run `/mema.seed` to start the discovery workflow."
+   - **Stop here** — do not continue.
+3. Parse the index to identify available memory files.
 
-## Step 3: Load Project Purpose
+## Step 3: Load Active Features
 
-Read the following files (skip any that don't exist):
+Read `features/NNN-name/status.md` for every feature directory listed under `## Active Features` in `index.md` that is NOT marked `complete`.
 
-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
+For each active feature, note:
+- Feature name and number
+- Current status (`pending` or `in-progress`)
+- Last completed task and next task (from status.md progress log)
 
-These form the core context for both Minimal and Full modes.
+This is the most important context — surface it first.
 
-## Step 4: Load Current Status
+## Step 4: Load Project Knowledge
 
-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
+Read the following (skip any that don't exist):
 
-## Step 5: Load Additional Files (Full Mode Only)
+1. `.mema/project/architecture.md` — tech stack, structure, architecture pattern
+2. `.mema/project/requirements.md` — project purpose and constraints
 
-**Skip this step entirely if in Minimal mode.**
+## Step 5: Load Additional Files (Full Mode Only)
 
-In Full mode, also read these files (skip any that don't exist):
+**Skip entirely if in Minimal mode.**
 
-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`
+1. **Recent decisions** — Read files listed under `## Project Knowledge` → `decisions/` in `index.md`
+2. **Lessons** — Read `agent/lessons.md`
+3. **Patterns** — Read `agent/patterns.md`
+4. **Product discovery** — Read `product/roadmap.md` summary if listed in index
 
-Read only files that exist and are listed in the index. Do not scan the directory tree for unlisted files.
+Read only files that exist and are listed in the index.
 
 ## 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)
+## Project Memory
 
-### Purpose
-[Project name and what it does — from requirements.md]
+### Active Features
+[For each active feature:]
+- **[NNN] [Feature name]** — [status] | Next: [next task]
+[If no active features: "No features in progress. Run /mema.specify to start one."]
 
-### Stack & Architecture
-[Tech stack, architecture pattern, key entry points — from architecture.md]
+### Project
+[Name] — [purpose from requirements.md]
+Stack: [tech stack 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
+### What to run next
+[Suggest the most logical next command based on active feature status]
 
 ---
-*Showing minimal recall. Use `/mema.recall full` for decisions, lessons, and patterns.*
+*Use `/mema.recall full` for decisions, lessons, and product discovery.*
 ```
 
 ---
@@ -95,41 +88,42 @@ Use the format below based on the current mode.
 ```
 ## Project Memory (Full)
 
-### Purpose
-[Project name and what it does — from requirements.md]
+### Active Features
+[For each active feature:]
+- **[NNN] [Feature name]** — [status] | Next: [next task]
+[If no active features: "No features in progress. Run /mema.specify to start one."]
 
-### Stack & Architecture
-[Tech stack, architecture pattern, key entry points — from architecture.md]
+### Product Discovery
+[If product/ files exist:]
+- Idea: [summary from seed.md]
+- Roadmap: [N features defined — from roadmap.md]
+[If no product/ files: omit section]
 
-### Current Status
-[Active tasks and their progress — from index.md + status files]
-[If no active tasks: "No active tasks."]
+### Project
+[Name] — [purpose]
+Stack: [tech stack]
+Architecture: [pattern]
 
 ### Recent Decisions
 [For each decision file, list:]
-- **[Decision title]** ([date]) — [one-line summary or key choice made]
-[If no decisions: "No decisions recorded yet."]
+- **[Decision title]** — [one-line summary]
+[If none: "No decisions recorded yet."]
 
 ### Lessons
-[Bullet list of lessons from lessons.md]
-[If no lessons: "No lessons recorded yet."]
+[Bullet list from agent/lessons.md]
+[If none: "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]
+[Bullet list from agent/patterns.md]
+[If none: "No patterns recorded yet."]
 
 ### Memory Map
-- Project Knowledge: [N] files
-- Recent Decisions: [N] decisions
-- Agent Lessons: [N] lessons, [N] patterns
-- Active Tasks: [N] tasks
-- Archived Tasks: [N] archived
+- Active Features: [N]
+- Product Discovery: [files present]
+- Project Knowledge: [N] files, [N] decisions
+- Agent Knowledge: [N] lessons, [N] patterns
 ```
 
 ---
 
-**Important:** This skill is purely informational. If you notice memory files are missing or out of date, suggest the user run `/mema.onboard` or the relevant skill — do not attempt to fix memory yourself.
+**Important:** This skill is purely informational. If memory files are missing or out of date, suggest the user run `/mema.onboard` or the relevant skill — do not modify memory files yourself.

package/skills/mema.research/SKILL.md

@@ -0,0 +1,109 @@
+---
+description: Research competitors, market context, and technical options for your idea using web search. Saves findings to product/research.md.
+---
+
+# /mema.research — Discovery Research
+
+You are executing the /mema.research skill. Follow these steps carefully.
+
+This skill uses web search to investigate what already exists, validate market opportunity, and explore technical options. It informs the challenge and roadmap phases.
+
+## AUTO-LOAD
+
+1. Read `.mema/index.md`
+2. Read `.mema/product/seed.md` (for the idea)
+3. Read `.mema/product/clarify.md` (for audience and scope — skip if missing)
+4. If `product/research.md` exists, read it to understand prior research
+
+## WORK
+
+### Parse Focus Area
+
+If the user provided an optional focus area (e.g., `/mema.research competitors` or `/mema.research tech stack`), narrow the research to that area. Otherwise, run a full research sweep.
+
+### Graceful Degradation
+
+If web search is unavailable:
+- Inform the user: "Web search is unavailable. I'll research from training knowledge and flag where real-time data would be needed."
+- Proceed using training knowledge
+- Clearly mark each finding with `[Training data — verify with current sources]`
+
+### Research Areas
+
+For each area, use the WebSearch tool with targeted queries:
+
+**1. Existing Solutions**
+
+Search for: `"[problem domain] tools"`, `"[problem] software"`, `"alternatives to [category]"`
+
+For each solution found, capture: name, what it does, key strengths, key weaknesses, pricing model (if relevant), and how it relates to this idea.
+
+**2. Market Context**
+
+Search for: `"[domain] market size [current year]"`, `"[domain] trends"`, `"[audience] pain points"`
+
+Capture: market size or growth signals, key trends, validated pain points, and any data that confirms or challenges the idea's assumptions.
+
+**3. Technical Options**
+
+Based on the clarified scope, search for: `"[technical capability] libraries [language]"`, `"how to build [core feature]"`, `"[technology choice 1] vs [technology choice 2]"`
+
+Capture: viable technical approaches, key trade-offs, and any significant constraints or gotchas.
+
+### Save
+
+Write `.mema/product/research.md`:
+
+```
+# [Project Name] — Research
+
+**Status:** active | **Updated:** [today's date]
+
+## Existing Solutions
+
+| Solution | What it does | Strengths | Weaknesses |
+|----------|-------------|-----------|------------|
+| [Name] | [One line] | [+] | [-] |
+
+## Key Insight
+[Most important thing the research revealed about the competitive landscape]
+
+## Market Context
+
+[Market size, trends, validated pain points — with source links]
+
+## Technical Options
+
+### [Option/Approach 1]
+- What it is: [description]
+- Best for: [when to use]
+- Trade-offs: [pros/cons]
+
+### [Option/Approach 2]
+[same format]
+
+## Recommended Approach
+[Based on research findings, what approach fits best for this idea]
+
+## Sources
+
+- [Title](URL)
+- [Title](URL)
+```
+
+### Guide Next Step
+
+```
+Next: Run /mema.challenge to stress-test the idea against these findings.
+```
+
+## AUTO-SAVE & CURATE
+
+- ADD or UPDATE `product/research.md`
+- NOOP on all other memory files
+
+## AUTO-INDEX
+
+Update `.mema/index.md`:
+1. Add or update entry under `## Product Discovery`: `- \`product/research.md\` — [N] competitors found; recommended approach: [one-line]`
+2. Update `**Updated:**` date