mema-kit 1.0.6 → 1.1.0

package/skills/mema.roadmap/SKILL.md

@@ -0,0 +1,134 @@
+---
+description: Synthesize discovery outputs into a prioritized project plan and feature list. Creates numbered feature directories in .mema/features/ ready for specification and implementation.
+---
+
+# /mema.roadmap — Project Roadmap
+
+You are executing the /mema.roadmap skill. Follow these steps carefully.
+
+This skill synthesizes everything from the discovery phase (seed, clarify, research, challenge) into a structured project plan with a prioritized feature list. It creates feature directories ready for `/mema.specify`.
+
+## AUTO-LOAD
+
+1. Read `.mema/index.md`
+2. Read all available `product/` files:
+   - `product/seed.md` — the original idea
+   - `product/clarify.md` — refined intent (if exists)
+   - `product/research.md` — findings and recommended approach (if exists)
+   - `product/challenge.md` — risks and constraints (if exists)
+3. Check what feature directories already exist in `features/` — to avoid creating duplicates
+4. If `product/roadmap.md` exists, read it — re-run will update it
+
+## WORK
+
+### Synthesize the Plan
+
+Using the discovery outputs, derive:
+
+**Problem statement**: One paragraph — specific problem, specific audience, why current solutions fall short.
+
+**Value proposition**: One sentence — what this does better than alternatives, for whom.
+
+**Feature list**: Break the full vision into discrete, independently buildable features. For each feature:
+- Name (kebab-case, 2-4 words)
+- One-line description
+- Priority: P1 (MVP — must have), P2 (important — ship soon), P3 (nice to have)
+- Estimated complexity: Small / Medium / Large
+
+**MVP scope**: The smallest subset that delivers real value — typically P1 features only.
+
+**Out of scope**: Features explicitly deferred.
+
+### Number Features
+
+Assign 3-digit sequential numbers starting from 001. If feature directories already exist in `features/`:
+- Read their names to determine the current highest number N
+- Start new features from N+1
+
+Order features by priority (P1 first), then by logical dependency (if feature B depends on feature A, A gets a lower number).
+
+### Create Feature Directories
+
+For each feature in the roadmap, create a directory `features/NNN-kebab-name/` with a starter `status.md`:
+
+```
+# [Feature Name] — Status
+
+**Status:** pending | **Updated:** [today's date]
+
+## Current Status
+
+`pending` — defined in roadmap, not yet specified
+```
+
+Do NOT create spec.md, plan.md, or tasks.md — those are created by `/mema.specify`, `/mema.plan`, and `/mema.tasks`.
+
+For feature directories that already exist: skip creation, do not overwrite.
+
+### Handle Re-run
+
+If `roadmap.md` already exists:
+- Show current feature list
+- Ask: "Update roadmap (add/reprioritize features), or start fresh?"
+- Updating: ADD new features (with new numbers), UPDATE descriptions/priorities for existing ones. NEVER delete existing feature directories.
+
+### Save
+
+Write `.mema/product/roadmap.md`:
+
+```
+# [Project Name] — Roadmap
+
+**Status:** active | **Updated:** [today's date]
+
+## Problem Statement
+
+[Specific problem, specific audience, why current solutions fail]
+
+## Value Proposition
+
+[What this does better, for whom — one sentence]
+
+## Feature List
+
+| # | Feature | Description | Priority | Complexity | Directory |
+|---|---------|-------------|----------|------------|-----------|
+| 001 | [name] | [one line] | P1 — MVP | Medium | `features/001-name/` |
+| 002 | [name] | [one line] | P2 | Small | `features/002-name/` |
+
+## MVP Scope
+
+[P1 features that form the minimum viable product]
+
+## Out of Scope
+
+- [Explicitly deferred features]
+```
+
+### Present to User
+
+```
+## Roadmap: [Project Name]
+
+[N] features defined. MVP = [P1 feature names].
+
+Feature directories created:
+- features/001-name/ (pending)
+- features/002-name/ (pending)
+[...]
+
+Next: Run /mema.specify to write the spec for your first feature.
+Start with: /mema.specify 001
+```
+
+## AUTO-SAVE & CURATE
+
+- ADD or UPDATE `product/roadmap.md`
+- NOOP on all other memory files
+
+## AUTO-INDEX
+
+Update `.mema/index.md`:
+1. Add or update `## Product Discovery`: `- \`product/roadmap.md\` — [N] features; MVP = [P1 features]`
+2. Add each new feature directory to `## Active Features`: `- \`features/NNN-name/\` — [one-line description] (pending)`
+3. Update `**Updated:**` date

package/skills/mema.seed/SKILL.md

@@ -0,0 +1,88 @@
+---
+description: Capture a raw idea and save it as the starting point for the mema-kit discovery workflow. Run this first when starting a new project from scratch.
+---
+
+# /mema.seed — Idea Capture
+
+You are executing the /mema.seed skill. Follow these steps carefully.
+
+This is the first step of the discovery workflow. It captures a raw idea — exactly as described, no editing — and saves it as the foundation for everything that follows.
+
+## AUTO-LOAD
+
+1. Check if `.mema/` exists
+2. If it does, read `index.md` to check for an existing seed
+3. If `.mema/` doesn't exist, create it with the `product/` subdirectory — this is a new project
+
+## WORK
+
+### Capture the Idea
+
+Get the idea from one of these sources (in priority order):
+1. **Inline argument** — everything after `/mema.seed` in the user's message
+2. **Prompt** — if no argument, ask: "What's your idea? Don't worry about structure — just describe it."
+
+Accept anything: one sentence, bullet points, stream of consciousness, half-formed thoughts. Do not edit, filter, or structure the input.
+
+### Mirror Back
+
+Repeat the idea back to the user exactly as captured:
+
+```
+Got it. Here's what I captured:
+
+---
+[Exact text of the idea]
+---
+
+Saved to .mema/product/seed.md
+```
+
+### Handle Re-run
+
+If `product/seed.md` already exists, show the current content and ask:
+
+"A seed already exists. Replace it with the new idea, or keep the existing one?"
+
+- **Replace**: overwrite `seed.md` with new content
+- **Keep**: exit without changes
+
+### Save
+
+Write `.mema/product/seed.md`:
+
+```
+# [Project Name or Working Title] — Seed
+
+**Status:** active | **Updated:** [today's date]
+
+## Raw Idea
+
+[The idea exactly as described by the user — no editing]
+
+## Initial Thoughts
+
+[If the user included any meta-commentary ("I'm not sure about X", "maybe also Y"), capture it here. Otherwise omit this section.]
+```
+
+For the project name: use any name mentioned by the user, or derive a 2-3 word working title from the idea if no name was given.
+
+### Guide Next Step
+
+Tell the user:
+
+```
+Next: Run /mema.clarify to turn this into a crisp problem statement.
+```
+
+## AUTO-SAVE & CURATE
+
+- ADD `product/seed.md` (or UPDATE on re-run)
+- NOOP on all other memory files
+
+## AUTO-INDEX
+
+Update `.mema/index.md`:
+1. Re-read the current index
+2. Add or update entry under `## Product Discovery`: `- \`product/seed.md\` — [working title]: [one-line idea summary]`
+3. Update `**Updated:**` date

package/skills/mema.specify/SKILL.md

@@ -0,0 +1,120 @@
+---
+description: Create a feature specification. Picks a feature from the roadmap or takes a fresh description, and saves a non-technical spec to features/NNN-name/spec.md.
+---
+
+# /mema.specify — Feature Specification
+
+You are executing the /mema.specify skill. Follow these steps carefully.
+
+This skill creates a feature spec — the "what and why" before any technical planning. It works with or without a prior discovery phase.
+
+## AUTO-LOAD
+
+1. Read `.mema/index.md`
+2. If `.mema/` doesn't exist:
+   - Tell the user: "No memory found. Run `/mema.onboard` first to set up mema-kit."
+   - **Stop here.**
+3. Read if they exist:
+   - `product/roadmap.md` — to present the feature list
+   - `product/research.md` — to inform the spec with competitive context
+   - `product/challenge.md` — to include known constraints
+   - `project/architecture.md` — to note technical constraints in the spec
+
+## WORK
+
+### Select Feature
+
+**If a roadmap exists** and no argument was given:
+- List features from `product/roadmap.md` that don't yet have a `spec.md`
+- Ask: "Which feature would you like to specify? (Enter number or name)"
+
+**If an argument was given** (e.g., `/mema.specify 001` or `/mema.specify "add search"`):
+- If it's a number: find `features/NNN-*/` matching that number
+- If it's a name: find the closest matching feature directory, or create a new one
+- If it's a fresh description (no matching directory): create a new feature directory
+
+**If no roadmap and no argument**:
+- Ask: "Describe the feature you want to specify."
+
+### Create Feature Directory (if needed)
+
+If no directory exists for this feature:
+1. Scan `features/` for the highest existing number N
+2. Create `features/N+1-kebab-name/` (start at 001 if no features exist)
+3. Create a starter `status.md` with `**Status:** pending`
+
+### If spec.md Already Exists
+
+Read the existing spec and ask:
+"A spec already exists for [feature name]. Update specific sections, or rewrite from scratch?"
+- **Update**: modify named sections, preserve rest
+- **Rewrite**: replace entirely (after confirming)
+
+### Write the Spec
+
+Gather the following (from roadmap, user input, or inference):
+- **Purpose**: What does this feature do and why does it exist?
+- **User scenarios**: Who does what, and what happens?
+- **Acceptance criteria**: How do we know it's working?
+- **Constraints**: What must this not break? What must it support?
+- **Out of scope**: What does this feature NOT do?
+
+Reference `product/research.md` and `product/challenge.md` if they exist — constraints and risks belong in the spec.
+
+Write `.mema/features/NNN-name/spec.md`:
+
+```
+# [Feature Name] — Spec
+
+**Status:** active | **Updated:** [today's date]
+
+## Purpose
+
+[What this feature does and why it exists — one paragraph, non-technical]
+
+## User Scenarios
+
+### Scenario 1 — [Title]
+
+**Given** [initial state], **When** [user action], **Then** [expected outcome]
+
+### Scenario 2 — [Title]
+
+**Given** [initial state], **When** [user action], **Then** [expected outcome]
+
+## Acceptance Criteria
+
+- [ ] [Specific, testable criterion]
+- [ ] [Specific, testable criterion]
+
+## Constraints
+
+[Non-negotiables, compatibility requirements, performance needs]
+
+## Out of Scope
+
+[What this feature deliberately does NOT include]
+```
+
+### Confirm to User
+
+```
+Spec saved: features/[NNN-name]/spec.md
+
+[Feature name]: [one-line purpose summary]
+[N] acceptance criteria defined
+
+Next: /mema.plan [NNN-name]
+```
+
+## AUTO-SAVE & CURATE
+
+- ADD or UPDATE `features/NNN-name/spec.md`
+- UPDATE `features/NNN-name/status.md` to note spec is ready
+- NOOP on all other files
+
+## AUTO-INDEX
+
+Update `.mema/index.md`:
+1. Add or update entry in `## Active Features`: `- \`features/NNN-name/\` — [one-line description] (spec ready)`
+2. Update `**Updated:**` date

package/skills/mema.tasks/SKILL.md

@@ -0,0 +1,128 @@
+---
+description: Generate an ordered implementation task list for a feature. Reads the feature spec and plan, then writes a checkable task list to features/NNN-name/tasks.md.
+---
+
+# /mema.tasks — Feature Task Generation
+
+You are executing the /mema.tasks skill. Follow these steps carefully.
+
+This skill turns a technical plan into a concrete, ordered task list that `/mema.implement` can execute step by step.
+
+## AUTO-LOAD
+
+1. Read `.mema/index.md`
+2. If `.mema/` doesn't exist:
+   - Tell the user: "No memory found. Run `/mema.onboard` first."
+   - **Stop here.**
+3. Load relevant memory:
+   - `agent/lessons.md` — to inform task granularity based on past experience
+   - `agent/patterns.md` — to apply known good patterns in task ordering
+
+## WORK
+
+### Select Feature
+
+Parse the user's input:
+- **Number or name given** (e.g., `/mema.tasks 001` or `/mema.tasks user-auth`): find matching `features/NNN-name/`
+- **No input**: list features that have `plan.md` but no `tasks.md`; ask which to generate tasks for
+
+If no matching feature directory:
+- Tell the user: "No feature found for '[input]'. Run `/mema.specify` first."
+- **Stop here.**
+
+### Load Feature Files
+
+Read from `features/NNN-name/`:
+1. **`plan.md`** — the technical design (required)
+2. **`spec.md`** — acceptance criteria to guide task completeness
+
+If `plan.md` is missing:
+- Tell the user: "No plan found for [feature-name]. Run `/mema.plan [feature]` first."
+- **Stop here.**
+
+### Handle Existing tasks.md
+
+If `tasks.md` already exists:
+- Check if any tasks are already checked off (`- [x]`)
+- If tasks are in progress: warn the user: "Tasks are partially complete ([N] done). Regenerating will reset unchecked tasks. Continue?"
+- If no tasks started: regenerate silently
+
+### Generate the Task List
+
+From the plan, derive an ordered sequence of implementation tasks:
+
+**Task properties:**
+- Start with a verb: "Create", "Add", "Update", "Write", "Implement", "Configure"
+- Include the exact file path when a specific file is involved
+- Small enough that each task completes in one `/mema.implement` invocation
+- Ordered logically: foundations before features, features before tests, tests before polish
+
+**Grouping** (use section headers when ≥ 6 tasks):
+- **Setup**: directory creation, config files, schema migrations
+- **Core**: main implementation tasks
+- **Tests**: test files (if the project has tests)
+- **Polish**: documentation, cleanup, edge case handling
+
+**Good task examples:**
+- `- [ ] Create \`src/auth/service.ts\` with login and register functions`
+- `- [ ] Add JWT middleware to \`src/middleware/auth.ts\``
+- `- [ ] Update \`src/routes/index.ts\` to protect authenticated routes`
+
+**Bad task examples (too vague):**
+- `- [ ] Implement authentication` (too broad — what files? what functions?)
+- `- [ ] Write tests` (which tests? for what?)
+
+### Verify Coverage
+
+Before writing, check: do the tasks, when completed, satisfy all acceptance criteria from `spec.md`? If any criterion is not covered by a task, add a task for it.
+
+### Write Task File
+
+Write `.mema/features/NNN-name/tasks.md`:
+
+```
+# [Feature Name] — Tasks
+
+**Status:** active | **Updated:** [today's date]
+
+## Setup
+
+- [ ] [Setup task with file path]
+
+## Core
+
+- [ ] [Core task with file path]
+- [ ] [Core task with file path]
+
+## Tests
+
+- [ ] [Test task with file path]
+
+## Polish
+
+- [ ] [Polish task]
+```
+
+Omit sections that have no tasks (e.g., omit Tests if the project has no test setup).
+
+### Confirm to User
+
+```
+Tasks generated: features/[NNN-name]/tasks.md
+
+[N] tasks across [M] sections.
+
+Next: /mema.implement [NNN-name]
+```
+
+## AUTO-SAVE & CURATE
+
+- ADD or UPDATE `features/NNN-name/tasks.md`
+- UPDATE `features/NNN-name/status.md`: add note "tasks generated on [date]"
+- NOOP on all other files
+
+## AUTO-INDEX
+
+Update `.mema/index.md`:
+1. Update entry in `## Active Features`: `- \`features/NNN-name/\` — [description] (tasks ready, [N] tasks)`
+2. Update `**Updated:**` date

package/templates/agent/lessons.md

@@ -0,0 +1,16 @@
+# Agent Lessons
+
+**Updated:** YYYY-MM-DD
+
+<!-- Lessons learned during development. Each entry is a mistake, surprise, or hard-won insight that future sessions should know about. -->
+
+## Lessons
+
+### [Short Title]
+<!-- One-sentence lesson. -->
+- **Context:** <!-- When/how this was discovered. -->
+- **Example:** <!-- Concrete code example or scenario if applicable. -->
+
+---
+
+<!-- Add new lessons above this line. When entries exceed ~30, consolidate related lessons under grouped headers. -->

package/templates/agent/patterns.md

@@ -0,0 +1,16 @@
+# Agent Patterns
+
+**Updated:** YYYY-MM-DD
+
+<!-- Reusable patterns and approaches that worked well. Load these to apply proven solutions. -->
+
+## Patterns
+
+### [Pattern Name]
+<!-- What this pattern solves and when to use it. -->
+- **Structure:** <!-- How the pattern is organized. -->
+- **Example:** <!-- Concrete usage example. -->
+
+---
+
+<!-- Add new patterns above this line. -->

package/templates/features/feature/plan.md

@@ -0,0 +1,23 @@
+# [Feature Name] — Plan
+
+**Status:** active | **Updated:** YYYY-MM-DD
+
+## Approach
+
+[High-level technical strategy — how this will be implemented]
+
+## Key Entities / Data Model
+
+- **[Entity]**: [What it represents, key fields]
+
+## Key Decisions
+
+- **[Decision topic]**: [What was chosen and why]
+
+## File Structure
+
+[Which files will be created or modified]
+
+## Implementation Notes
+
+[Gotchas, constraints, dependencies to be aware of during implementation]

package/templates/features/feature/spec.md

@@ -0,0 +1,30 @@
+# [Feature Name] — Spec
+
+**Status:** active | **Updated:** YYYY-MM-DD
+
+## Purpose
+
+[What this feature does and why it exists — one paragraph, non-technical]
+
+## User Scenarios
+
+### Scenario 1 — [Title]
+
+**Given** [initial state], **When** [user action], **Then** [expected outcome]
+
+### Scenario 2 — [Title]
+
+**Given** [initial state], **When** [user action], **Then** [expected outcome]
+
+## Acceptance Criteria
+
+- [ ] [Testable criterion 1]
+- [ ] [Testable criterion 2]
+
+## Constraints
+
+[Non-negotiables, performance requirements, compatibility needs]
+
+## Out of Scope
+
+[What this feature deliberately does NOT do]

package/templates/features/feature/status.md

@@ -0,0 +1,23 @@
+# [Feature Name] — Status
+
+**Status:** pending | **Updated:** YYYY-MM-DD
+
+## Current Status
+
+`pending` — not started
+
+Status values: `pending` → `in-progress` → `complete`
+
+## Progress Log
+
+| Date | Task | Notes |
+|------|------|-------|
+| YYYY-MM-DD | [Task completed] | [Any notes] |
+
+## Next Task
+
+[What to work on next — filled in by /mema.implement]
+
+## Blockers
+
+[Anything preventing progress — empty if none]

package/templates/features/feature/tasks.md

@@ -0,0 +1,16 @@
+# [Feature Name] — Tasks
+
+**Status:** active | **Updated:** YYYY-MM-DD
+
+## Setup
+
+- [ ] [Setup task with file path]
+
+## Core
+
+- [ ] [Core implementation task with file path]
+- [ ] [Core implementation task with file path]
+
+## Polish
+
+- [ ] [Polish task with file path]

package/templates/index.md

@@ -4,12 +4,23 @@
 
 <!-- Format: - `file-path` — one-line summary -->
 
-## Active Tasks
+## Active Features
+
+<!-- Features currently in progress -->
+<!-- - `features/001-name/` — Description (in-progress, step N/M) -->
+
+## Product Discovery
+
+<!-- Discovery phase outputs — populated by /mema.seed through /mema.roadmap -->
+<!-- - `product/seed.md` — Raw idea: [brief] -->
+<!-- - `product/roadmap.md` — N features defined -->
 
 ## Project Knowledge
-- `project-memory/architecture.md` — Project architecture (not yet documented)
-- `project-memory/requirements.md` — Project requirements (not yet documented)
 
-## Recent Decisions
+- `project/architecture.md` — Project architecture (not yet documented)
+- `project/requirements.md` — Project requirements (not yet documented)
+
+## Agent Knowledge
 
-## Agent Lessons
+<!-- - `agent/lessons.md` — N lessons recorded -->
+<!-- - `agent/patterns.md` — N patterns recorded -->

package/templates/product/challenge.md

@@ -0,0 +1,23 @@
+# [Project Name] — Challenge
+
+**Status:** active | **Updated:** YYYY-MM-DD
+
+## Assumptions
+
+| Assumption | Validated? | Risk if Wrong |
+|------------|-----------|---------------|
+| [Assumption] | Yes / Risky | [Impact] |
+
+## Risk Register
+
+| Risk | Severity | Likelihood | Mitigation |
+|------|----------|------------|------------|
+| [Risk] | High/Med/Low | High/Med/Low | [How to address] |
+
+## Blind Spots
+
+[What hasn't been considered? What could invalidate the whole approach?]
+
+## Recommended Actions Before Building
+
+[What to validate, research, or decide before committing to implementation]

package/templates/product/clarify.md

@@ -0,0 +1,23 @@
+# [Project Name] — Clarified Intent
+
+**Status:** active | **Updated:** YYYY-MM-DD
+
+## Problem Being Solved
+
+[What specific problem does this address?]
+
+## Target Audience
+
+[Who is this for? Be specific.]
+
+## Motivation
+
+[Why does this need to exist? What's wrong with current alternatives?]
+
+## Scope
+
+[What's included? What's explicitly out of scope?]
+
+## Constraints
+
+[Technical, time, budget, team, or other constraints]