@limina-labs/momentum 0.30.2

package/core/specs-templates/specs/architecture/ecosystem.md

@@ -0,0 +1,214 @@
+---
+type: Architecture Spec
+---
+
+# Ecosystem Layer — Reference
+
+> Single source of truth for how momentum models multi-repo
+> coordination. Shipped with `momentum init` (Phase 9, v0.12.0+).
+> Member repos read this when they need to understand the cross-repo
+> contract; the runtime helpers live in the momentum package itself
+> at `core/ecosystem/`.
+
+## When to use ecosystem mode
+
+| You have… | Use mode | First command |
+|---|---|---|
+| One project | **Single-project** *(default)* | `momentum init` |
+| Several related projects working as one product | **Ecosystem** | `momentum init --ecosystem <name>` |
+| An existing momentum project that should join an existing ecosystem | **Ecosystem** *(join)* | `momentum join <ecosystem-path>` |
+| A member repo you want to detach from its ecosystem | **Standalone** *(leave)* | `momentum leave` |
+| Confusion about what state a repo is in | **Diagnostic** | `momentum doctor` |
+
+**Single-project usage is fully supported and is the default.** Ecosystem mode is strictly additive — when no ecosystem.json is reachable, every `momentum` and slash command behaves identically to single-project use. There is no cost to ignoring this entire document if you only have one project.
+
+## What an ecosystem is
+
+A **momentum ecosystem** is a sibling git repo that coordinates a set
+of related momentum-installed repos as one logical product. It holds
+three things:
+
+1. A **manifest** (`ecosystem.json`) — declares members + roles +
+   dependency edges.
+2. **Initiatives** (`initiatives/NNNN-<slug>.md`) — first-class records
+   of features that span multiple member repos.
+3. A **daily session log** (`sessions/YYYY-MM-DD.md`) — auto-appended
+   by each member's PostToolUse hook on `git commit` / `gh pr` events.
+
+The ecosystem layer is **strictly additive**. It never writes into a
+member's `specs/`. The only touch on a member is one fenced line in
+its `CLAUDE.md` / `AGENTS.md` pointing back at the ecosystem.
+
+## Layout
+
+```
+<ecosystem-root>/                     ← its own git repo
+├── ecosystem.json                    ← manifest (members, roles, edges)
+├── README.md
+├── initiatives/
+│   ├── README.md
+│   └── NNNN-<slug>.md
+├── sessions/
+│   └── YYYY-MM-DD.md
+├── .state/                           ← gitignored runtime
+│   ├── active-initiative
+│   └── last-session
+└── .gitignore
+```
+
+## Member opt-in / opt-out
+
+```bash
+# From inside the ecosystem root:
+momentum ecosystem init <name>                   # scaffold a new ecosystem
+momentum ecosystem add ../<repo>                 # register a member
+momentum ecosystem add ../<repo> --role infra    # with explicit role
+momentum ecosystem remove <id>                   # unregister
+momentum ecosystem status                        # print state
+```
+
+After `add`, the target repo's CLAUDE.md / AGENTS.md gains:
+
+```html
+<!-- ecosystem:begin -->
+> Member of `<name>` ecosystem at `../<name>`.
+> See ecosystem.json for siblings and `momentum ecosystem status` for live state.
+<!-- ecosystem:end -->
+```
+
+Re-running `add` is a no-op. `remove` strips both the manifest entry
+and the fenced block from the member.
+
+## Initiatives
+
+A cross-repo feature is one markdown file at
+`initiatives/NNNN-<slug>.md`. Frontmatter:
+
+```yaml
+---
+id: 1
+slug: memory-module
+status: in-progress      # | closed | abandoned
+started: 2026-06-07
+closed:                  # required when status=closed
+owner: avinash
+repos: [sapience, frontend, infra]
+title: "Memory module v1"
+---
+```
+
+Body sections are fixed: **Why** · **Per-repo contributions** ·
+**Linked decisions** · **Deploy chronology** · **Close**. See the
+template at `core/ecosystem/templates/initiative-template.md`.
+
+The slash-command surface is `/initiative create|status|close|list`
+(see the `/initiative` recipe). Numbering is monotonically increasing
+across the ecosystem; the slug is for human readability.
+
+## Session log
+
+Auto-populated by each member repo's PostToolUse hook. Triggers:
+
+| Trigger | Line emitted |
+|---|---|
+| `git commit` (via Bash tool) | `HH:MMZ [<member>] commit: <subject> (<sha>)` |
+| `gh pr create` / `gh pr merge` (via Bash tool) | `HH:MMZ [<member>] pr: <cmd-preview>` |
+| `/session log <message>` | `HH:MMZ [<member>] note: <message>` |
+
+First write of the day prepends a header:
+
+```markdown
+# Session YYYY-MM-DD
+Active initiative: <slug>           # only when .state/active-initiative is set
+```
+
+Outside any ecosystem the hook is a silent no-op — single-repo
+momentum projects see no change.
+
+## How discovery works
+
+Every command (CLI or hook) finds the ecosystem root via a
+bounded upward walk. From `$PWD`, climb up to 5 parents by default
+(configurable via the `MOMENTUM_MAX_PARENT_WALK` env var) looking for
+a directory whose **siblings** contain an `ecosystem.json`. First hit
+wins; cached per-process.
+
+This means the ecosystem repo and member repos live as **siblings**
+under one parent directory:
+
+```
+<parent>/
+├── <ecosystem>/         ← contains ecosystem.json
+├── <member-1>/          ← contains CLAUDE.md + the ecosystem pointer
+├── <member-2>/
+└── <member-3>/
+```
+
+## What stays per-repo (unchanged)
+
+| Per-repo (member) | Cross-repo (ecosystem) |
+|---|---|
+| `specs/status.md` | `ecosystem.json` |
+| `specs/phases/*` | `initiatives/*` |
+| `specs/backlog/` | (Tier 2) — backlog aggregation |
+| `specs/changelog/` | `sessions/` |
+| `specs/decisions/` (ADRs) | (Tier 2) — federated impact-map |
+| `/track`, `/brainstorm-phase`, `/start-phase`, `/complete-phase`, `/sync-docs` | `/ecosystem`, `/initiative`, `/session` |
+
+## What's NOT in Tier 1
+
+The following are deferred to a future phase ("Tier 2"):
+
+- `/switch-repo` with context carry-over between repos.
+- Federated impact-map and cross-repo `/sync-docs`.
+- Shared rules of record (a single source of truth for Rules 1–12).
+- Deploy-order awareness (e.g. "platform must deploy before client").
+- Multi-repo `/review-code`.
+- Inter-repo parallel agent orchestration (extending Phase 8
+  worktrees across repos).
+
+## Orchestration (Phase 11, v0.14.0+)
+
+Once an ecosystem is set up, momentum gives you three primitives for
+working across member repos from one agent session — three doors into
+one shared library.
+
+| Primitive | Behaviour | Where it lands |
+|---|---|---|
+| `scout <repo> "<prompt>"` | Read-only context fetch from one member | `.momentum/runs/scout-NNN.md` in originating repo; one line in ecosystem session log; `[DISCOVERY]` in scouted repo's active phase history if a meaningful finding |
+| `dispatch <r1> <r2> … --prompt "<text>"` | Parallel fan-out + synthesis across members; sequential fallback labeled when adapter doesn't support parallel sub-agents | `.momentum/runs/dispatch-NNN.md`; one session log line; per-repo `[DISCOVERY]` for meaningful findings; `[NOTE]` in originating phase history for the synthesis |
+| `handoff <repo>` | Cross-session control transfer with a structured context block | `<receiving repo>/.momentum/inbox/handoff-NNN.md`; one session log line; `[DECISION]` in originating phase history |
+| `continue [--handoff <id>]` | Pick up a pending handoff in the current repo | Inbox file moved to `.momentum/inbox/read/`; `[NOTE]` in receiving phase history |
+
+**Three doors, identical output shape:**
+
+- **Slash command** (Claude Code, Codex): `/scout`, `/dispatch`, `/handoff`, `/continue`.
+- **Natural-language inference**: describe the task; the agent picks the primitive ("inferred: scout (single repo, read-only)").
+- **CLI**: `momentum scout|dispatch|handoff|continue` — universal floor, works on every adapter including chat-driven ones.
+
+**Tracking contract — auto when meaningful, never noise:**
+
+- **Cheap layer (always auto):** ecosystem session log line + `.momentum/runs/` artifact + handoff inbox file.
+- **Curated layer (auto when meaningful):** `[DISCOVERY]` / `[DECISION]` / `[NOTE]` entries in the relevant repo's active phase `history.md`, applying Rule 3 thresholds (real bug, real tech debt, real enhancement, real cross-repo decision). **No new entry types.**
+- **Never auto:** `backlog.md` writes — tracking proposes; the user confirms.
+
+**Capability-driven routing.** Some adapters don't support parallel
+sub-agent fan-out (Codex today, until parallel dispatch is validated
+in CI) or SessionStart hooks (Antigravity). The router degrades
+gracefully and labels the degraded mode up front, e.g.:
+
+```
+▸ note: this adapter does not declare parallel subagents — running sequentially
+```
+
+The user sees output of the same shape; just slower in degraded mode.
+
+## Failure modes (operator playbook)
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `not inside an ecosystem root` | cwd is not in/under a known ecosystem | `cd` into one, or `momentum ecosystem init <name>` |
+| `target doesn't look momentum-installed` | `add`'s target lacks CLAUDE.md/AGENTS.md | run `momentum init` on the target first |
+| `member id already registered` | id collision in manifest | `--id <different>` or `remove` first |
+| Session log not updating | hook script missing or unreadable; member not registered | `cat scripts/check-history-reminder.sh`; verify with `momentum ecosystem status` |
+| Manifest rejected by `add` | schema violation in the new state | read the per-path error list; fix `ecosystem.json` by hand or call `remove` then `add` |

package/core/specs-templates/specs/backlog/backlog.md

@@ -0,0 +1,46 @@
+---
+type: Backlog
+---
+
+# Backlog
+
+> **Last Updated**: YYYY-MM-DD
+
+---
+
+## Priority Levels
+
+| Level | Meaning |
+|-------|---------|
+| **P0** | Critical — blocks current phase |
+| **P1** | High — address in current/next phase |
+| **P2** | Medium — within 2 phases |
+| **P3** | Low — nice to have |
+
+**Status**: `open` | `in-progress` | `resolved` | `deferred` | `deprecated`
+
+---
+
+## Bugs
+
+| ID | Title | Priority | Status | Phase | Detail |
+|----|-------|----------|--------|-------|--------|
+| _(none)_ | | | | | |
+
+## Features
+
+| ID | Title | Priority | Status | Phase | Detail |
+|----|-------|----------|--------|-------|--------|
+| _(none)_ | | | | | |
+
+## Tech Debt
+
+| ID | Title | Priority | Status | Phase | Detail |
+|----|-------|----------|--------|-------|--------|
+| _(none)_ | | | | | |
+
+## Enhancements
+
+| ID | Title | Priority | Status | Phase | Detail |
+|----|-------|----------|--------|-------|--------|
+| _(none)_ | | | | | |

package/core/specs-templates/specs/decisions/0000-template.md

@@ -0,0 +1,33 @@
+---
+type: Decision
+---
+
+# NNNN — Decision Title
+
+> **Status**: proposed | accepted | superseded | deprecated
+> **Date**: YYYY-MM-DD
+> **Deciders**: <!-- names or roles -->
+
+## Context
+
+<!-- What is the problem or situation that requires a decision? What forces are at play? -->
+
+## Options Considered
+
+### Option A — Name
+<!-- Describe the option. -->
+**Pros:** …
+**Cons:** …
+
+### Option B — Name
+<!-- Describe the option. -->
+**Pros:** …
+**Cons:** …
+
+## Decision
+
+<!-- What was chosen and why? -->
+
+## Consequences
+
+<!-- What are the positive and negative results of this decision? What becomes easier or harder? -->

package/core/specs-templates/specs/decisions/README.md

@@ -0,0 +1,29 @@
+---
+type: Guide
+---
+
+# Architecture Decision Records
+
+> Lightweight ADRs — one file per decision, append-only once accepted.
+
+## Index
+
+| ID | Title | Status | Date |
+|----|-------|--------|------|
+| [0000](0000-template.md) | ADR Template | template | — |
+
+## Process
+
+1. Copy `0000-template.md` → `NNNN-short-title.md`
+2. Fill in context, options, and decision
+3. Add a row to the index above
+4. Add affected topics to the `impact-map.md` table
+
+## Status Values
+
+| Status | Meaning |
+|--------|---------|
+| `proposed` | Under discussion |
+| `accepted` | Decided, in effect |
+| `superseded` | Replaced by a later ADR |
+| `deprecated` | No longer applicable |

package/core/specs-templates/specs/decisions/impact-map.md

@@ -0,0 +1,14 @@
+---
+type: Impact Map
+title: Decision Impact Map
+description: "Topic keywords → spec files/sections, consumed by /sync-docs."
+---
+
+# Impact Map
+
+Maps topic keywords to the spec files/sections they affect. Used by
+`/sync-docs` to find documents needing updates when a phase history
+entry carries matching `Topics:`.
+
+| Topic | File | Section |
+|-------|------|---------|

package/core/specs-templates/specs/decisions/index.md

@@ -0,0 +1,4 @@
+# Decisions
+
+* [NNNN — Decision Title](/decisions/0000-template.md)
+* [Decision Impact Map](/decisions/impact-map.md) - Topic keywords → spec files/sections, consumed by /sync-docs.

package/core/specs-templates/specs/index.md

@@ -0,0 +1,16 @@
+---
+okf_version: "0.1"
+---
+
+# Specs
+
+* [Status](/status.md) - current project state — the first file to read
+* [Backlog](/backlog/backlog.md) - bugs, features, tech debt, enhancements
+* [Roadmap](/planning/roadmap.md) - phase timeline and upcoming work
+
+# Directories
+
+* [Phases](/phases/index.md) - one directory per phase (overview, plan, tasks, history)
+* [Decisions](/decisions/index.md) - architecture decision records + impact map
+* [Ad-hoc work](/adhoc/) - quick-task and spike records (Rule 14)
+* [Changelog](/changelog/) - month-by-month change log

package/core/specs-templates/specs/phases/README.md

@@ -0,0 +1,41 @@
+---
+type: Guide
+---
+
+# Phases Index
+
+| Phase | Name | Status | Directory |
+|-------|------|--------|-----------|
+| _(none yet)_ | | | |
+
+## Phase Structure
+
+Each phase directory contains:
+
+| File | Purpose |
+|------|---------|
+| `overview.md` | Goal, scope, deliverables, acceptance criteria |
+| `plan.md` | Group execution pattern with tasks |
+| `tasks.md` | Checklist `[ ]` / `[x]` |
+| `history.md` | Append-only log |
+| `retrospective.md` | Post-completion review (created by /complete-phase) |
+
+## Swarm-member briefs (optional)
+
+When a phase is driven by a swarm conductor (Phase 17+), `overview.md`
+MAY carry an optional YAML frontmatter block declaring its swarm
+context. Solo briefs omit this entirely — they remain plain markdown.
+
+```yaml
+---
+swarm: 0007-user-auth
+wave: 2
+initiative: user-auth
+claimed_by_session: <session-uuid>
+---
+```
+
+`/start-phase` populates these when invoked from a swarm context.
+`/validate` checks that `swarm:` resolves to a real swarm manifest,
+that `wave:` matches the wave the swarm has assigned this repo, and
+that `initiative:` matches the swarm's initiative.

package/core/specs-templates/specs/phases/index.md

@@ -0,0 +1,6 @@
+# Phases
+
+
+# Guides
+
+* [Phases guide](/phases/README.md) - conventions for phase directories

package/core/specs-templates/specs/planning/roadmap.md

@@ -0,0 +1,23 @@
+---
+type: Roadmap
+---
+
+# Roadmap
+
+> **Last Updated**: YYYY-MM-DD
+
+## Vision
+
+<!-- One sentence: what does this project become at full maturity? -->
+
+## Release Plan
+
+| Version | Phase | Key Deliverables | Target |
+|---------|-------|-----------------|--------|
+| v0.1.0 | Phase 0 — Bootstrap | _(TBD)_ | _(TBD)_ |
+
+## Guiding Principles
+
+1. Ship working software in every phase
+2. Each phase leaves the project in a releasable state
+3. Defer scope, not quality

package/core/specs-templates/specs/status.md

@@ -0,0 +1,70 @@
+---
+type: Status
+---
+
+# Project Status
+
+> **Last Updated**: YYYY-MM-DD
+> **Current Phase**: Phase 0 — Bootstrap (`not started`)
+> **Latest Release**: None
+> **Health**: On Track
+
+## Summary
+
+<!-- One paragraph describing what this project is and what it does. -->
+
+## Completed Phases
+
+| Phase | Name | Status | Released |
+|-------|------|--------|---------|
+| _(none yet)_ | | | |
+
+## Ad-hoc / Patch Releases
+
+> Releases NOT tied to a numbered phase — hotfixes, patch/audit releases,
+> chores. Keep these out of the Completed Phases table. Work records live in
+> `specs/adhoc/`. See Rule 14 for when ad-hoc work must become a phase instead.
+
+| Version | Date | Type | Summary |
+|---------|------|------|---------|
+| _(none yet)_ | | | |
+
+## Active Phase
+
+> One row per active lane (Rule 15, ADR-0001). Each session's phase is the
+> one bound to its branch; this table is the cross-lane overview and the
+> fallback for branches that don't resolve. Lanes touch only their own row.
+
+| Phase | Branch | Status | Progress |
+|-------|--------|--------|----------|
+| _(none — no active phase)_ | | | |
+
+## Upcoming Phases
+
+| Phase | Name | Status | Key Deliverables |
+|-------|------|--------|-----------------|
+| _(TBD)_ | | | |
+
+## Blockers
+
+| ID | Description | Severity |
+|----|-------------|----------|
+| _(none)_ | | |
+
+## Critical Items (P0)
+
+| ID | Type | Description |
+|----|------|-------------|
+| _(none)_ | | |
+
+## Next Actions
+
+1. Run `/brainstorm-idea` to explore the concept, then `/start-project` to scaffold
+
+## Key Decisions Made
+
+_(none yet)_
+
+## Recent Changes
+
+_(none yet)_

package/core/specs-templates/specs/vision/principles.md

@@ -0,0 +1,16 @@
+---
+type: Vision
+---
+
+# Principles
+
+> Guiding decisions throughout the project. When trade-offs arise, these resolve them.
+
+## Core Principles
+
+1. **Simplicity first** — the simplest solution that solves the problem is the right one
+2. **Ship incrementally** — each phase leaves the project in a releasable state
+3. **Defer scope, not quality** — cut features before cutting correctness
+4. **Document decisions** — every significant choice gets an ADR
+
+<!-- Add or replace principles to match this project's values. -->

package/core/specs-templates/specs/vision/project-charter.md

@@ -0,0 +1,35 @@
+---
+type: Vision
+---
+
+# Project Charter
+
+> **Project**: <Project Name>
+> **Created**: YYYY-MM-DD
+
+## Problem Statement
+
+<!-- What problem does this project solve? Who has this problem? Why does it matter? -->
+
+## Solution
+
+<!-- What does this project build or do? How does it solve the problem? -->
+
+## Stakeholders
+
+| Role | Name / Team | Responsibility |
+|------|-------------|----------------|
+| Owner | _(TBD)_ | Final decisions |
+| Users | _(TBD)_ | Primary audience |
+
+## Scope
+
+### In
+- _(TBD)_
+
+### Out
+- _(TBD)_
+
+## Success
+
+<!-- How will you know this project succeeded? See `success-criteria.md` for measurable targets. -->

package/core/specs-templates/specs/vision/success-criteria.md

@@ -0,0 +1,19 @@
+---
+type: Vision
+---
+
+# Success Criteria
+
+> Measurable targets. When all are met, the project has achieved its goals.
+
+## Phase 0 Targets
+
+| Criterion | Target | How to Measure |
+|-----------|--------|----------------|
+| _(TBD)_ | _(TBD)_ | _(TBD)_ |
+
+## Long-Term Targets
+
+| Criterion | Target | How to Measure |
+|-----------|--------|----------------|
+| _(TBD)_ | _(TBD)_ | _(TBD)_ |