mema-kit 1.0.5 → 1.1.0

package/skills/mema.implement/SKILL.md

@@ -0,0 +1,167 @@
+---
+description: Execute implementation plan steps one at a time. Picks up the next step from an existing feature plan, implements it, verifies the result, and tracks progress. Run /mema.plan first to create a plan.
+---
+
+# /mema.implement — Feature Step Execution
+
+You are executing the /mema.implement skill. Follow these steps carefully.
+
+This skill picks up a step from an existing feature plan (created by `/mema.plan`), implements it, verifies the result, and updates progress tracking. By default, it implements **one step at a time** to give the user control.
+
+## 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."
+   - **Stop here.**
+3. If `index.md` is empty, run the **Rebuild Procedure** from `_memory-protocol.md`
+4. Scan `## Active Features` in `index.md` to find features with plans
+5. Load relevant memory:
+   - `project/architecture.md` — technical context
+   - `project/decisions/` — past decisions that affect implementation
+   - `agent/lessons.md` — mistakes to avoid
+   - `agent/patterns.md` — reusable approaches
+
+## Phase 2: WORK
+
+### 2a: Select Feature
+
+Parse the user's input:
+
+- **Feature name or number:** `/mema.implement user-auth` or `/mema.implement 001` → find `features/NNN-name/`
+- **Feature + step:** `/mema.implement user-auth step 3` → implement that specific step
+- **No input:** list active features from index.md and ask which one
+- **"all" modifier:** `/mema.implement user-auth all` → implement all remaining steps (see 2e)
+
+If the feature directory doesn't exist:
+- Tell the user: "No feature found for '[input]'. Run `/mema.specify` and `/mema.plan` first."
+- **Stop here.**
+
+### 2b: Load Feature Context
+
+Read from `features/NNN-name/`:
+
+1. **`tasks.md`** — the ordered task list (prefer this over plan.md for step selection)
+2. **`plan.md`** — the technical design
+3. **`spec.md`** — what the feature is supposed to do
+4. **`status.md`** — current progress
+
+If `tasks.md` is missing, tell the user: "No tasks found. Run `/mema.tasks [feature]` first."
+
+### 2c: Select Step
+
+- **If user specified a step:** validate it exists and isn't already complete. If complete, ask if they want to re-implement it.
+- **If no step specified:** find the first incomplete item (`- [ ]`) in `tasks.md`. If all items are complete, proceed to 2f (Task Completion).
+
+Tell the user which step is being implemented:
+
+```
+## Implementing: [task description]
+
+[Brief description of what this step does]
+```
+
+### 2d: Implement the Step
+
+1. **Read the task details** from `tasks.md` — files to create/modify, what to do
+2. **Check dependencies** — if the task references prior tasks that aren't done, warn the user and ask to confirm before proceeding
+3. **Implement the changes** — create/modify files as specified; follow the project's existing patterns (from architecture.md and patterns.md); apply lessons (from lessons.md) to avoid known pitfalls
+4. **Verify:**
+   - If the project has tests relevant to this step: run them
+   - Check for syntax errors, missing imports, obvious issues
+   - If verification fails: do NOT mark as complete; report what went wrong and suggest a fix
+
+### 2e: Implement All Remaining (if requested)
+
+1. Implement tasks sequentially from first incomplete task
+2. Verify each before moving to next
+3. If any step fails, stop and report — do not continue
+4. Show a brief progress update after each step
+
+### 2f: Update Progress
+
+After each step:
+
+1. **Update `features/NNN-name/status.md`:**
+   - Update status to `in-progress` if this is the first step
+   - Add a progress log entry: date + task + notes
+   - Update "Next Task" field
+   - Update `**Updated:**` date
+
+2. **Update `features/NNN-name/tasks.md`:**
+   - Mark completed task: `- [x]`
+
+3. **Print progress summary:**
+
+```
+## Progress: [Feature Name]
+
+Task complete: [what was done]
+
+[if verified:] Verified: [how]
+[if failed:] Issue: [what went wrong] | Suggested fix: [how to resolve]
+
+### Overall Progress
+[====------] [completed]/[total] tasks
+Next: [next task description]
+
+To continue: /mema.implement [feature-name]
+```
+
+### 2g: Feature Completion
+
+If all tasks in `tasks.md` are now complete:
+
+1. Print completion summary:
+
+```
+## Feature Complete: [Feature Name]
+
+All [N] tasks implemented.
+
+### What was built
+[Summary of changes]
+
+### Files changed
+[List of files created or modified]
+
+Archive this feature? (moves to archive/ and removes from active features)
+```
+
+2. If user confirms, archive in Phase 3.
+
+### 2h: Learn
+
+After completing work, reflect:
+- Unexpected issues → record as lesson
+- Patterns that worked → record as pattern
+- Previous lessons that were wrong → update or delete them
+
+## Phase 3: AUTO-SAVE & CURATE
+
+Follow curation rules in `_memory-protocol.md`:
+
+- **Decisions made** during implementation → 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/NNN-name/status.md` (done in 2f)
+
+Most files will be NOOP.
+
+### Feature Archiving (on completion)
+
+If fully complete and user confirmed:
+
+1. Update `features/NNN-name/status.md`: set `**Status:** complete`
+2. Move `features/NNN-name/` to `archive/NNN-name/`
+3. Remove feature from `## Active Features` in `index.md`
+
+## Phase 4: AUTO-INDEX
+
+Update `.mema/index.md`:
+1. Re-read the current index
+2. Update the feature's summary in `## Active Features` with current progress (e.g., "3/7 tasks complete")
+3. If archived: remove from `## Active Features`
+4. Add entries for new files (decisions, lessons, patterns)
+5. Update `**Updated:**` date

package/skills/mema.onboard/SKILL.md

@@ -0,0 +1,364 @@
+---
+description: Bootstrap the mema-kit memory system for this project. Creates .mema/ directory, scans the project, populates initial memory, and configures CLAUDE.md and .gitignore.
+---
+
+# /mema.onboard — Project Memory Bootstrap
+
+You are setting up the mema-kit memory system for this project. Follow these steps carefully. This command is idempotent — safe to re-run. Never overwrite existing data without confirming.
+
+## Step 1: Check Current State
+
+Before creating anything, assess what already exists:
+
+1. Check if `.mema/` directory exists
+2. Check if it uses the **old structure** (`project-memory/`, `task-memory/`, `agent-memory/`) — if so, migration is needed
+3. Check if `CLAUDE.md` exists and has a `## Memory System` section
+4. Check if `.gitignore` contains `.mema` entries
+
+Report to the user: "Setting up mema-kit. Found existing .mema/ — will verify and update." or "Fresh setup — creating everything from scratch." or "Found old mema-kit structure — will migrate to new layout."
+
+## Step 2: Migrate Old Structure (if needed)
+
+If the old directory structure exists, migrate it before creating anything new:
+
+- If `.mema/project-memory/` exists and `.mema/project/` does not → rename to `.mema/project/`; tell user: "Migrated project-memory/ → project/"
+- If `.mema/agent-memory/` exists and `.mema/agent/` does not → rename to `.mema/agent/`; tell user: "Migrated agent-memory/ → agent/"
+- If `.mema/task-memory/` exists and `.mema/features/` does not → rename to `.mema/features/`; tell user: "Migrated task-memory/ → features/"
+
+If new structure already exists: NOOP on that directory.
+
+## Step 3: Create .mema/ Directory Structure
+
+Create the following directories if they don't already exist:
+
+```
+.mema/
+├── product/
+├── features/
+├── project/
+│   └── decisions/
+├── agent/
+└── archive/
+```
+
+For each directory: if it exists, skip it. If it doesn't, create it.
+
+## Step 4: Write Template Files
+
+Write the following files to `.mema/_templates/`. If a template file already exists, **skip it**.
+
+### `.mema/_templates/decision.md`
+
+```
+# [Decision Title]
+
+**Status:** active | **Updated:** YYYY-MM-DD
+
+## Context
+
+## Decision
+
+## Options Considered
+
+### Option A: [Name]
+
+### Option B: [Name]
+
+## Reasoning
+
+## Consequences
+```
+
+### `.mema/_templates/spec.md`
+
+```
+# [Feature Name] — Spec
+
+**Status:** active | **Updated:** YYYY-MM-DD
+
+## Purpose
+
+## User Scenarios
+
+### Scenario 1
+
+Given [state], When [action], Then [outcome]
+
+## Acceptance Criteria
+
+- [ ] [Criterion]
+
+## Constraints
+```
+
+### `.mema/_templates/status.md`
+
+```
+# [Feature Name] — Status
+
+**Status:** pending | **Updated:** YYYY-MM-DD
+
+## Current Status
+
+`pending` — not started
+
+## Progress Log
+
+| Date | Task | Notes |
+|------|------|-------|
+
+## Next Task
+
+## Blockers
+```
+
+### `.mema/_templates/lessons.md`
+
+```
+# Agent Lessons
+
+**Updated:** YYYY-MM-DD
+
+## Lessons
+
+### [Short Title]
+- **Context:**
+- **Example:**
+
+---
+```
+
+### `.mema/_templates/patterns.md`
+
+```
+# Agent Patterns
+
+**Updated:** YYYY-MM-DD
+
+## Patterns
+
+### [Pattern Name]
+- **Structure:**
+- **Example:**
+
+---
+```
+
+## Step 5: Scan the Project
+
+Read and analyze the project to populate memory with real content.
+
+### 5a: Detect Project Type and Stack
+
+Read (skip any that don't exist):
+1. `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `pom.xml`, or `Gemfile` — language, framework, dependencies
+2. `README.md` — project purpose and setup
+3. `CLAUDE.md` — existing conventions
+4. Config files (`tsconfig.json`, `.eslintrc`, etc.)
+
+### 5b: Scan Directory Structure
+
+List top-level directories and key subdirectories (1-2 levels deep). Note source, test, and config locations.
+
+### 5c: Read Representative Source Files
+
+Pick 2-3 files that best represent the codebase: main entry point, a representative module, a test file.
+
+### 5d: Compile Findings
+
+Before writing memory, note:
+- Project name and purpose
+- Language/framework/stack with versions
+- Architecture pattern
+- Key directories
+- Testing setup
+- Build/run commands
+- Notable conventions
+
+## Step 6: Populate Initial Memory
+
+Using scan findings, create files with **real content** (not empty placeholders).
+
+### `.mema/project/architecture.md`
+
+```
+# Project Architecture
+
+**Status:** active | **Updated:** [today]
+
+## Stack
+- **Language:** [detected]
+- **Framework:** [detected]
+[other stack items]
+
+## Structure
+- `[dir]/` — [purpose]
+[other directories]
+
+## Architecture
+[Pattern in 1-2 sentences. Entry point: path/to/entry]
+
+## Commands
+- `[dev command]` — Start development
+- `[test command]` — Run tests
+```
+
+### `.mema/project/requirements.md`
+
+```
+# Project Requirements
+
+**Status:** active | **Updated:** [today]
+
+## Purpose
+[What this project does, from README and code]
+
+## Key Requirements
+- [Requirement from code/docs]
+
+## Constraints
+- [Constraint discovered]
+```
+
+### `.mema/agent/lessons.md`
+
+```
+# Agent Lessons
+
+**Updated:** [today]
+
+## Lessons
+
+[Add any project-specific gotchas found during scan, or leave as:]
+<!-- Lessons will be added here as development experience accumulates. -->
+```
+
+### `.mema/agent/patterns.md`
+
+```
+# Agent Patterns
+
+**Updated:** [today]
+
+## Patterns
+
+[Add any clear patterns from source files, or leave as:]
+<!-- Patterns will be added here as development experience accumulates. -->
+```
+
+### `.mema/index.md`
+
+Build the index from files just created:
+
+```
+# Memory Index
+
+**Updated:** [today]
+
+## Active Features
+
+## Product Discovery
+
+## Project Knowledge
+- `project/architecture.md` — [one-line stack/architecture summary]
+- `project/requirements.md` — [one-line purpose summary]
+
+## Agent Knowledge
+- `agent/lessons.md` — [N] lessons recorded
+- `agent/patterns.md` — [N] patterns recorded
+```
+
+## Step 7: Update CLAUDE.md
+
+Read the current `CLAUDE.md` (if exists) and follow the appropriate path:
+
+### Path A: CLAUDE.md already exists
+
+1. Search for `## Memory System`
+2. If found → **skip this step** (already configured)
+3. If not found → append the Memory System section below
+
+Memory System section:
+
+```
+## 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.
+```
+
+### Path B: CLAUDE.md does NOT exist — Generate from scratch
+
+Follow sub-steps 7a through 7f.
+
+#### 7a: Ask user "About Me"
+
+Ask one question using AskUserQuestion:
+
+> "Before I generate your CLAUDE.md, how would you describe yourself?"
+
+Options:
+- **Junior developer** — "I'm learning. Explain decisions, be thorough, correct my terminology gently."
+- **Senior developer** — "I'm experienced. Keep explanations brief, focus on trade-offs and edge cases."
+- **Skip** — Use a sensible default
+
+#### 7b–7f: Generate CLAUDE.md sections
+
+Use Step 5 scan data to write:
+- `# About Me` — from user's answer in 7a
+- `## Project Overview` — name, description, directory tree, architecture
+- `## Coding Standards` — naming conventions, style, patterns, tooling detected
+- `## Technical Workflows` — dev/test/build commands from package scripts
+- `## Skill Commands` — scan `.claude/skills/` for SKILL.md frontmatter descriptions
+- `## Memory System` — standard section (same as Path A)
+
+## Step 8: Update .gitignore
+
+1. Read current `.gitignore` (if exists)
+2. If `.mema` is already excluded → skip
+3. If not → append:
+
+```
+# mema-kit memory (developer-local)
+.mema/*
+# Uncomment to share project decisions with your team:
+# !.mema/project/
+```
+
+## Step 9: Confirm to User
+
+Print a summary of what was done:
+
+```
+mema-kit initialized!
+
+[check] .mema/ structure created (product/, features/, project/, agent/)
+[check] CLAUDE.md [generated / updated / already configured]
+[check] .gitignore updated
+
+Project scan:
+- [Language/framework]
+- [Architecture pattern]
+- [Key finding]
+
+Next steps:
+- New idea? Run /mema.seed to start the discovery workflow
+- Existing feature to build? Run /mema.specify to create a feature spec
+- Start a new session? Run /mema.recall to load context
+```
+
+For a re-run with migration:
+
+```
+mema-kit updated!
+
+[check] Migrated project-memory/ → project/
+[check] Migrated agent-memory/ → agent/
+[check] Migrated task-memory/ → features/
+[check] Directory structure verified
+
+Your existing memory is preserved. Run /mema.recall to see current state.
+```

package/skills/mema.plan/SKILL.md

@@ -0,0 +1,150 @@
+---
+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 — Feature Technical Design
+
+You are executing the /mema.plan skill. Follow these steps carefully.
+
+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."
+   - **Stop here.**
+3. If `index.md` is empty, run the **Rebuild Procedure** from `_memory-protocol.md`
+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: Select Feature
+
+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 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.**
+
+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: Load the Feature Spec
+
+Read `features/NNN-name/spec.md` in full.
+
+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 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
+
+Note: current patterns, naming conventions, architectural constraints, and anything the spec didn't mention that affects implementation.
+
+### 2d: Clarify if Needed
+
+If the spec leaves meaningful technical ambiguity, ask **one clarifying question** using AskUserQuestion. Skip this step if the spec is clear.
+
+Good clarifying questions:
+- "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
+
+Produce a technical plan in these parts:
+
+**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?
+
+**Key Entities / Data** (if relevant):
+- Data structures, models, or types involved
+- Database schema changes if applicable
+
+**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
+
+**Implementation Notes** — gotchas, constraints, dependencies:
+- Lessons from lessons.md that apply
+- Patterns from patterns.md to follow
+- Non-obvious dependencies or ordering requirements
+
+### 2f: Write Plan File
+
+Write `features/NNN-name/plan.md`:
+
+```
+# [Feature Name] — Plan
+
+**Status:** active | **Updated:** [today's date]
+
+## Approach
+
+[High-level technical approach from 2e]
+
+## Key Entities
+
+[Data structures / models if applicable]
+
+## File Changes
+
+- `path/to/file` — [what changes]
+- `path/to/file` — [what changes]
+
+## Implementation Notes
+
+[Gotchas, patterns to follow, ordering requirements]
+```
+
+### 2g: Present to User
+
+```
+## Plan: [Feature Name]
+
+### Approach
+[1-2 sentence summary]
+
+### Files to change ([N] total)
+- [file] — [what]
+- [file] — [what]
+
+---
+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`:
+
+- **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`
+
+Most files will be NOOP.
+
+## Phase 4: AUTO-INDEX
+
+Update `.mema/index.md`:
+1. Re-read the current index
+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