@accelerationguy/accel 1.0.0

package/modules/momentum/src/framework/tasks/pulse.md

@@ -0,0 +1,83 @@
+<purpose>
+Daily workspace activation. Read workspace state, calculate drift, present health dashboard, prime the operator for their session.
+</purpose>
+
+<user-story>
+As an AI builder, I want a quick workspace health briefing at session start, so that I know what needs attention before I start working.
+</user-story>
+
+<when-to-use>
+- Start of every work session
+- When user says "momentum pulse", "what's the state of things", "workspace status"
+- When the pulse hook detects overdue grooming and injects a prompt
+- Entry point routes here via /momentum:pulse
+</when-to-use>
+
+<steps>
+
+<step name="read_state" priority="first">
+Read workspace state from `.accel/momentum/workspace.json` and `.accel/momentum/STATE.md`.
+
+1. Read `.accel/momentum/workspace.json` — the manifest
+2. Read `.accel/momentum/STATE.md` — the last known state
+3. If either file is missing, suggest running `/momentum:scaffold` first
+4. Extract: last groom date, groom cadence, area list, satellite list
+</step>
+
+<step name="calculate_drift">
+Check each tracked area against filesystem reality.
+
+For each area in the manifest:
+1. Check filesystem timestamps on tracked paths (stat modification dates)
+2. Compare against last groom date and area-specific cadence
+3. Calculate days overdue (0 if within cadence)
+4. Classify: Current (within cadence), Stale (1-2x overdue), Critical (2x+ overdue)
+
+For each registered satellite:
+1. Check if state file exists and is readable
+2. Extract last modification date
+3. Report current phase if parseable
+
+Calculate total drift score: sum of days-overdue across all areas, with Critical areas weighted 2x.
+</step>
+
+<step name="present_dashboard">
+Present the health dashboard to the operator.
+
+Format:
+```
+Momentum Pulse — {workspace-name}
+Last Groom: {date} ({N} days ago)
+Drift Score: {score}
+
+| Area | Status | Age | Due |
+|------|--------|-----|-----|
+...
+
+Satellites:
+| Project | Phase | Last Active |
+...
+
+{Recommendation based on drift score}
+```
+
+Recommendations:
+- Drift 0: "Workspace is clean. Proceed normally."
+- Drift 1-7: "Minor drift in {areas}. Consider grooming this week."
+- Drift 8-14: "Moderate drift. Run /momentum:groom soon."
+- Drift 15+: "Critical drift. Workspace context is stale. Run /momentum:groom now."
+</step>
+
+</steps>
+
+<output>
+Health dashboard with drift score, area statuses, satellite health, and recommended next action.
+</output>
+
+<acceptance-criteria>
+- [ ] All manifest areas checked against filesystem reality
+- [ ] Drift score calculated correctly
+- [ ] Satellites checked for health
+- [ ] Clear recommendation provided based on drift level
+- [ ] Dashboard is concise and scannable (not a wall of text)
+</acceptance-criteria>

package/modules/momentum/src/framework/tasks/scaffold.md

@@ -0,0 +1,202 @@
+<purpose>
+Set up Momentum in a new or existing workspace. Scan the workspace, ask guided questions, generate the manifest, install hooks, initialize JSON data surfaces, and run operator profile setup. Optional --full mode adds CLAUDE.md audit and guided first groom.
+</purpose>
+
+<user-story>
+As an AI builder setting up my workspace, I want a guided scaffolding process that configures workspace management for my specific setup, so that I get maintenance automation without manual configuration.
+</user-story>
+
+<when-to-use>
+- First-time Momentum installation in any workspace
+- When user says "momentum scaffold", "set up momentum", "initialize workspace management"
+- Entry point routes here via /momentum:scaffold
+- Use --full flag for batteries-included mode with CLAUDE.md audit + first groom
+</when-to-use>
+
+<context>
+@templates/workspace-json.md
+</context>
+
+<steps>
+
+<step name="detect_mode" priority="first">
+Determine scaffold mode.
+
+1. Check if user specified `--full` or mentioned wanting full setup
+2. If `--full`: CLAUDE.md audit + first groom will be offered after data layer setup
+3. If standard: data layer + hooks + operator profile
+4. Announce mode: "Running Momentum scaffold ({standard|full} mode)."
+</step>
+
+<step name="scan_workspace">
+Scan the workspace and detect what exists.
+
+1. List top-level directories and files
+2. Detect common patterns:
+   - .accel/momentum/data/ → existing JSON surfaces (v2 data model)
+   - ACTIVE.md, BACKLOG.md → legacy working memory (offer migration)
+   - projects/ → project tracking
+   - apps/ → satellite projects
+   - tools/ → tool management
+   - .claude/ → system layer
+   - .mcp.json → MCP configuration
+   - content/ → content pipeline
+   - clients/ → client work
+   - obsidian/ → knowledge graph
+   - .vector/ → Vector dynamic rules
+3. Detect satellite projects (directories with .drive/ inside apps/)
+4. Present findings: "I found: {list of detected areas}"
+
+**Wait for confirmation before proceeding.**
+</step>
+
+<step name="guided_configuration">
+Walk through each detected area and configure tracking.
+
+For each detected area:
+1. "I found {area}. Want Momentum to track this?"
+2. If yes: "What grooming cadence? (weekly/bi-weekly/monthly)"
+3. Auto-select audit strategy based on area type
+4. Allow override of defaults
+
+Also ask:
+- "What day do you prefer for weekly grooming?" (default: Friday)
+- "Any directories I should scan for satellite projects?" (default: apps/)
+- "Anything else you want tracked that I didn't detect?"
+
+Build workspace.json from responses using `@templates/workspace-json.md` schema.
+</step>
+
+<step name="install_data_layer">
+Create .accel/momentum/ directory and generate JSON data surfaces.
+
+1. Create `.accel/momentum/` directory structure:
+   ```
+   .accel/momentum/
+   ├── workspace.json
+   ├── operator.json
+   ├── data/
+   │   ├── active.json
+   │   ├── backlog.json
+   │   ├── projects.json
+   │   ├── entities.json
+   │   └── state.json
+   ├── hooks/
+   ├── momentum-mcp/
+   ├── grooming/
+   └── audits/
+   ```
+2. Write workspace.json from guided configuration (with surfaces and vector_hygiene sections)
+3. Initialize JSON data surfaces with empty starter content (don't overwrite existing)
+4. Copy operator.json template (don't overwrite existing)
+5. Register any detected satellite projects in workspace.json
+6. Report: "Momentum data layer installed. {N} areas tracked, {N} satellites registered, {N} data surfaces initialized."
+
+**Legacy migration:** If ACTIVE.md or BACKLOG.md exist at workspace root, offer to convert them to JSON surfaces using `/momentum:surface convert`. Do not delete originals — let the user do that after verifying the conversion.
+</step>
+
+<step name="install_hooks">
+Install and register Momentum hooks.
+
+All hooks live in `.accel/momentum/hooks/`. Session hooks are registered in `.claude/settings.json`.
+
+**UserPromptSubmit hooks** (fire every prompt):
+- active-hook.py — active work surface injection
+- backlog-hook.py — backlog surface injection
+- momentum-pulse-check.py — drift detection + groom reminders
+- psmm-injector.py — per-session meta memory injection
+- operator.py — operator identity context injection
+- satellite-detection.py — Drive project auto-registration
+
+**On-demand hooks** (invoked by commands, not auto-registered):
+- mission-control-insights.py — workspace analytics (invoked by /accel:insights)
+
+For each auto-fire hook:
+1. Check if `.accel/momentum/hooks/{hook}` exists
+2. If not: copy from `~/.claude/momentum-framework/hooks/{hook}` (global install source)
+   - If `~/.claude/momentum-framework/hooks/{hook}` doesn't exist either, warn:
+     "Momentum framework not globally installed. Run `npx momentum-framework --global` first, then re-run scaffold."
+3. Check `.claude/settings.json` for hook registration in `UserPromptSubmit` array
+4. If not registered: add the hook entry with absolute path to `.accel/momentum/hooks/{hook}`
+
+Hook registration format in settings.json:
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      { "type": "command", "command": "python3 /absolute/path/.accel/momentum/hooks/{hook}" }
+    ]
+  }
+}
+```
+
+Report: "Hooks installed ({N} auto-fire hooks registered, 1 on-demand hook available)."
+</step>
+
+<step name="operator_profile">
+Guide the operator through their profile setup.
+
+1. Check if `.accel/momentum/operator.json` has completed sections (check `completed_at` fields)
+2. If all sections completed: "Operator profile already configured. Want to update any section?"
+3. If incomplete or new:
+   - Walk through each section of operator.json:
+     a. **Deep Why** — 5 progressively deeper questions about motivation
+     b. **North Star** — One measurable metric with timeframe
+     c. **Key Values** — Rank-ordered values with concrete meanings (max 5)
+     d. **Elevator Pitch** — Layered pitch (1-4 floors)
+     e. **Surface Vision** — Concrete scenes of what success looks like
+   - Each section can be skipped: "Skip for now? You can complete it later."
+   - Write responses to operator.json after each section
+4. Report: "Operator profile {complete|partially complete}. The operator hook will inject your identity context every session."
+</step>
+
+<step name="install_mcp">
+Verify MCP server is wired.
+
+1. Check `.mcp.json` for momentum-mcp registration
+2. If not registered:
+   - Check if `.accel/momentum/momentum-mcp/` exists with node_modules
+   - If no node_modules: run `npm install` in `.accel/momentum/momentum-mcp/`
+   - Add registration to `.mcp.json`:
+     ```json
+     { "momentum-mcp": { "type": "stdio", "command": "node", "args": ["./.accel/momentum/momentum-mcp/index.js"] } }
+     ```
+3. Report: "Momentum MCP server registered. Claude can now manage your data surfaces through tool calls."
+</step>
+
+<step name="full_mode_extras">
+**Full mode only.**
+
+**CLAUDE.md audit:**
+1. Check if CLAUDE.md exists
+2. If exists: "Want me to audit your CLAUDE.md against Momentum conventions?"
+   - If yes: route to `/momentum:audit-claude-md` task
+3. If doesn't exist: "Want me to generate a CLAUDE.md template for your workspace?"
+   - If yes: generate based on detected workspace structure
+
+**First groom:**
+1. "Want to run an initial groom to establish baseline? This reviews each area once."
+2. If yes: run /momentum:groom flow
+3. If no: "Baseline set from filesystem timestamps. First groom due: {date}."
+</step>
+
+</steps>
+
+<output>
+Fully configured Momentum installation. Standard mode: data layer with JSON surfaces, hooks wired, operator profile setup, MCP registered. Full mode: adds CLAUDE.md audit and guided first groom.
+</output>
+
+<acceptance-criteria>
+- [ ] Workspace scanned and areas detected
+- [ ] Operator confirmed tracked areas and cadences
+- [ ] .accel/momentum/ directory created with all required files
+- [ ] workspace.json generated from guided configuration
+- [ ] JSON data surfaces initialized (active, backlog, projects, entities, state)
+- [ ] operator.json created and profile questionnaire offered
+- [ ] Satellite projects detected and registered
+- [ ] All auto-fire hooks installed and registered in settings.json
+- [ ] Momentum MCP server wired in .mcp.json
+- [ ] (Full mode) CLAUDE.md audit offered
+- [ ] (Full mode) First groom offered
+- [ ] Operator informed of next groom date
+</acceptance-criteria>

package/modules/momentum/src/framework/tasks/status.md

@@ -0,0 +1,35 @@
+<purpose>
+Quick one-liner workspace health check. No conversation, just the numbers.
+</purpose>
+
+<user-story>
+As an AI builder, I want a fast health check I can glance at, so that I know if anything needs attention without a full briefing.
+</user-story>
+
+<when-to-use>
+- When user wants a quick check without full pulse
+- Entry point routes here via /momentum:status
+</when-to-use>
+
+<steps>
+
+<step name="quick_check" priority="first">
+Read state and output one-liner.
+
+1. Read `.accel/momentum/STATE.md`
+2. Calculate current drift score from timestamps
+3. Count overdue areas and past-due backlog items
+4. Output single line: "Momentum: Drift {score} | {N} areas overdue | {N} backlog items past review-by | Last groom: {date}"
+</step>
+
+</steps>
+
+<output>
+Single-line health summary. No conversation.
+</output>
+
+<acceptance-criteria>
+- [ ] Output is one line
+- [ ] Drift score is current (not cached)
+- [ ] Overdue counts are accurate
+</acceptance-criteria>

package/modules/momentum/src/framework/tasks/surface-convert.md

@@ -0,0 +1,143 @@
+<purpose>
+Convert an existing @-mentioned markdown file into a structured data surface. Analyzes the markdown structure, proposes a schema, migrates content, and generates all surface artifacts (JSON, hook, registration).
+</purpose>
+
+<user-story>
+As an AI builder, I want to convert my existing markdown tracking files into structured surfaces so Claude gets cheap passive awareness instead of expensive @-file parsing.
+</user-story>
+
+<when-to-use>
+- /momentum:surface convert {file-path}
+- "convert this file to a surface", "make this a data surface"
+- User has a markdown file they @-mention regularly and wants it structured
+</when-to-use>
+
+<context>
+@.accel/momentum/hooks/_template.py
+@.accel/momentum/workspace.json
+</context>
+
+<steps>
+
+<step name="read" priority="first">
+## Step 1: Read & Analyze
+
+1. Read the specified markdown file completely
+2. Detect structure:
+   - **Headings** → potential categories or priority groups
+   - **Bold labels** (e.g., `**Status:**`) → field names
+   - **List items** → individual entries
+   - **Checkboxes** → checklist/progress fields
+   - **Dates** → timestamp fields
+   - **File paths** → location fields
+   - **Tables** → structured data (archived items, reference tables)
+3. Identify patterns:
+   - How many distinct items?
+   - What fields recur across items?
+   - Are there priority/status groupings?
+   - Is there an archived/done section?
+
+Present findings:
+```
+Detected structure in {file}:
+  Items found: {count}
+  Sections: {list of heading-based groups}
+  Recurring fields: {field names}
+  Archived section: {yes/no}
+```
+</step>
+
+<step name="propose">
+## Step 2: Propose Schema
+
+Based on analysis, propose:
+
+1. **Surface name** — infer from filename (e.g., ACTIVE.md → "active")
+2. **Schema** — field names, types, required fields, ID prefix
+3. **Sample conversion** — show 2-3 items converted to JSON
+
+```
+Proposed schema for "{name}":
+  ID prefix: {PREFIX}
+  Required: {fields}
+  Optional: {fields}
+  Priority levels: {if detected}
+
+Sample conversion:
+  "{heading item}" →
+  {
+    "id": "PREFIX-001",
+    "title": "...",
+    "status": "...",
+    ...
+  }
+```
+
+Ask: "Does this schema look right? Adjust anything?"
+
+**Wait for response.**
+</step>
+
+<step name="confirm">
+## Step 3: Confirm
+
+Apply any user adjustments to the schema. Lock it for generation.
+
+If user is satisfied, confirm:
+"Schema locked. I'll generate the surface and migrate {count} items."
+</step>
+
+<step name="generate">
+## Step 4: Generate Artifacts
+
+Same generation as surface-create Step 5:
+- `.accel/momentum/data/{name}.json` — with migrated items (not empty)
+- `.accel/momentum/hooks/{name}-hook.py` — from _template.py with appropriate grouping
+- workspace.json surface registration
+- settings.json hook entry
+
+Include staleness detection with sensible defaults based on detected priority levels.
+</step>
+
+<step name="migrate">
+## Step 5: Migrate Content
+
+Parse every item from the markdown into JSON entries:
+- Map heading groups to priority/category fields
+- Map bold labels to field values
+- Preserve checklists as arrays of {text, done} objects
+- Preserve dates in ISO format
+- Preserve file paths as location fields
+- Map done/closed/archived sections to the archived array
+
+Report:
+```
+Migration complete:
+  Items migrated: {count}
+  Archived items: {count}
+  Unmapped items: {count, if any — list them}
+```
+
+If any items couldn't be auto-mapped, present them for manual resolution.
+</step>
+
+<step name="cleanup">
+## Step 6: Clean Up
+
+1. Check if the original file is @-referenced in CLAUDE.md
+2. If found, offer: "Remove @{file} from CLAUDE.md? The surface hook replaces it."
+3. Suggest: "Original file preserved at {path} for reference."
+
+Do NOT delete the original markdown file — the user decides its fate.
+</step>
+
+</steps>
+
+<verification>
+After conversion:
+- [ ] .accel/momentum/data/{name}.json exists with migrated items
+- [ ] Item count matches source markdown
+- [ ] .accel/momentum/hooks/{name}-hook.py exists and produces output
+- [ ] workspace.json and settings.json updated
+- [ ] Original markdown file is untouched
+</verification>

package/modules/momentum/src/framework/tasks/surface-create.md

@@ -0,0 +1,184 @@
+<purpose>
+Create a new data surface through guided conversation. Generates: JSON data file, injection hook, workspace.json registration, and settings.json hook entry. The user answers questions; Claude generates everything.
+</purpose>
+
+<user-story>
+As an AI builder, I want to create custom data surfaces so Claude has structured, passive awareness of any domain I track — without manually wiring JSON files, hooks, and config.
+</user-story>
+
+<when-to-use>
+- /momentum:surface create {name}
+- "create a surface", "add a new surface", "I want to track X"
+- User wants structured data with hook injection and MCP access
+</when-to-use>
+
+<context>
+@.accel/momentum/hooks/_template.py
+@.accel/momentum/workspace.json
+</context>
+
+<steps>
+
+<step name="define" priority="first">
+## Step 1: Define
+
+Extract surface name from args or ask: "What should this surface be called? (lowercase, no spaces)"
+
+**Validate:**
+1. Name is lowercase, alphanumeric + hyphens only
+2. Not already registered in workspace.json surfaces section
+3. No reserved names: "active", "backlog", "psmm", "staging"
+
+Ask: "What does this surface track? (one sentence)"
+→ This becomes the `description` in workspace.json.
+
+**Wait for response before proceeding.**
+</step>
+
+<step name="schema">
+## Step 2: Schema
+
+Ask: "What fields does each item need?"
+
+Guide through these decisions (one at a time):
+
+1. **Required fields** — What must every item have?
+   - Default minimum: `["title"]`
+   - Common additions: status, priority, category, assignee, due_date
+
+2. **ID prefix** — Auto-suggest first 3 chars of name, uppercase.
+   - e.g., surface "clients" → prefix "CLI"
+   - User can override
+
+3. **Priority/status enums** — If the surface has priority or status fields:
+   - Ask: "What priority levels?" (e.g., high, medium, low)
+   - Ask: "What status values?" (e.g., active, pending, done)
+
+4. **Time rules** (optional) — If the surface benefits from review-by dates:
+   - Ask: "Should items have review-by deadlines? If so, how many days per priority level?"
+   - Default: none
+
+Build the schema object from answers:
+```json
+{
+  "id_prefix": "CLI",
+  "required_fields": ["title", "status"],
+  "priority_levels": ["high", "medium", "low"],
+  "status_values": ["active", "pending", "done"]
+}
+```
+
+**Wait for response before proceeding.**
+</step>
+
+<step name="injection">
+## Step 3: Injection
+
+Ask: "How should items appear in Claude's context each prompt?"
+
+Guide through:
+
+1. **Grouping** — How to organize items in the injection?
+   - By priority (default) | By status | By date | Flat (no grouping)
+
+2. **Summary format** — What fields to show per line?
+   - Default: `- [ID] Title (status)`
+   - Can add: priority tag, due date, custom field
+
+3. **Staleness thresholds** — Days before an item is flagged STALE per priority:
+   - Suggest defaults based on priority levels from Step 2
+   - e.g., high: 5d, medium: 10d, low: 30d
+   - User can adjust
+
+4. **Behavioral mode:**
+   - Silent (default) — passive awareness, respond only when asked
+   - Proactive — mention items unprompted (rare, use for critical surfaces)
+   - Threshold — stay silent unless deadline/staleness threshold crossed
+
+**Wait for response before proceeding.**
+</step>
+
+<step name="tools">
+## Step 4: Tools (Informational)
+
+Inform the user:
+
+"All 7 Momentum MCP tools work automatically with your new surface:
+- `momentum_list_surfaces` — see all surfaces
+- `momentum_get_surface("{name}")` — read all items
+- `momentum_get_item("{name}", id)` — get specific item
+- `momentum_add_item("{name}", data)` — add new item (validates required fields, auto-generates ID)
+- `momentum_update_item("{name}", id, data)` — update fields (resets staleness clock)
+- `momentum_archive_item("{name}", id)` — move to archived
+- `momentum_search(query, "{name}")` — search items
+
+No configuration needed — Momentum MCP auto-discovers surfaces from workspace.json."
+
+**Continue to generation.**
+</step>
+
+<step name="generate" priority="critical">
+## Step 5: Generate
+
+Create all artifacts:
+
+**1. Data file:** `.accel/momentum/data/{name}.json`
+```json
+{
+  "surface": "{name}",
+  "version": 1,
+  "last_modified": "{timestamp}",
+  "items": [],
+  "archived": []
+}
+```
+
+**2. Hook file:** `.accel/momentum/hooks/{name}-hook.py`
+- Read `.accel/momentum/hooks/_template.py` as the starting point
+- Customize SURFACE_NAME, grouping logic, summary format, staleness thresholds, behavioral directive
+- Use the injection decisions from Step 3
+- Include `from datetime import date` for staleness calculation
+- Follow the _template.py contract exactly
+
+**3. Registration:** Add to `.accel/momentum/workspace.json` surfaces section:
+```json
+"{name}": {
+  "file": "data/{name}.json",
+  "description": "{description from Step 1}",
+  "hook": true,
+  "silent": true,
+  "schema": { ...schema from Step 2... }
+}
+```
+
+**4. Hook registration:** Add to `.claude/settings.json` UserPromptSubmit hooks:
+```json
+{
+  "type": "command",
+  "command": "python3 {absolute_workspace_path}/.accel/momentum/hooks/{name}-hook.py"
+}
+```
+Use absolute path resolved from workspace root.
+
+**5. Report:**
+```
+Surface "{name}" created:
+  Data:     .accel/momentum/data/{name}.json (empty, ready for items)
+  Hook:     .accel/momentum/hooks/{name}-hook.py (will inject next prompt)
+  Schema:   {id_prefix}-NNN, {required_fields}
+  Tools:    momentum_get_item("{name}", id), momentum_add_item("{name}", data), etc.
+
+Add your first item: momentum_add_item("{name}", {title: "..."})
+```
+</step>
+
+</steps>
+
+<verification>
+After generation:
+- [ ] .accel/momentum/data/{name}.json exists and is valid JSON
+- [ ] .accel/momentum/hooks/{name}-hook.py exists and parses as valid Python
+- [ ] workspace.json has the surface registration
+- [ ] settings.json has the hook entry with absolute path
+- [ ] Hook outputs correct XML when piped test input
+</verification>

package/modules/momentum/src/framework/tasks/surface-list.md

@@ -0,0 +1,42 @@
+<purpose>
+Display all registered data surfaces with item counts, hook status, and staleness summary.
+</purpose>
+
+<when-to-use>
+- /momentum:surface list
+- "what surfaces exist", "show surfaces", "list surfaces"
+</when-to-use>
+
+<steps>
+
+<step name="read_and_display">
+## Show Surfaces
+
+1. Call `momentum_list_surfaces` to get all registered surfaces with item counts
+2. For each surface, read the data file to count stale items (items with no `updated` field or `updated` older than threshold)
+
+Display as:
+
+```
+Data Surfaces
+═══════════════════════════════════════
+
+| Surface | Items | Hook | Description |
+|---------|-------|------|-------------|
+| active  | 12    | ✓    | Active work items, projects, and tasks |
+| backlog | 8     | ✓    | Future work queue, ideas, and deferred tasks |
+
+Total: {count} surfaces, {total_items} items
+
+Create a new surface: /momentum:surface create {name}
+Convert a file:      /momentum:surface convert {path}
+```
+
+If no surfaces registered:
+```
+No data surfaces registered.
+Run /momentum:surface create {name} to create your first surface.
+```
+</step>
+
+</steps>