momentum

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# Momentum

<div align="center">

**Development environment for Claude Code**

[![Status](https://img.shields.io/badge/Status-Active-green?style=flat)](#)
[![Built for](https://img.shields.io/badge/Built%20for-Claude%20Code-blueviolet?style=flat)](https://claude.ai/download)
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

</div>

---

Momentum wraps Claude Code with an iteration-first workflow, context that survives session limits, and a development partner with actual personality.

You work in focused iterations that ship working software. Context persists across conversations. An assistant named Sable remembers what you're building and why.

## What It Does

**Launches Claude Code with:**
- Identity-first system prompts (role, name, personality, then instructions)
- Project state detection (new → vision → planned → active)
- Hooks for context injection and knowledge capture
- Specialized agents for code review, architecture analysis, planning
- Voice system with configurable personality and verbosity

**Preserves context:**
- `/save-state` before context fills
- `/restore-state` to resume exactly where you left off
- Project expertise persists across sessions
- CAPTURE lines save insights to searchable knowledge base

**Ships working software:**
- Evidence-based planning (investigate before proposing)
- Micro-tasks that fit in one conversation
- Demo-driven completion (prove it works)

## Quick Start

```bash
git clone https://github.com/nickpending/momentum.git
cd momentum && ./install.sh

# Workspace mode - research, ideation, prototypes
momentum

# Project mode - focused building with state tracking
momentum myproject
```

The `momentum` command:
1. Sets up `.claude/` with hooks, commands, skills, agents
2. Renders the system prompt with your personality config
3. Launches Claude Code with `--append-system-prompt`

## Two Modes

| Mode | Command | What You Get |
|------|---------|--------------|
| **Workspace** | `momentum` | Full capabilities, no project constraints. Exploration, ideation, research. |
| **Project** | `momentum <name>` | State tracking, iteration workflow, task management. Ships software. |

## The Workflow

### Project States

```
momentum myproject
    │
    ├─ State: new (no IDEA.md)
    │   └─ Offer ideation to capture vision
    │
    ├─ State: vision (has IDEA.md)
    │   └─ Suggest /plan-iteration
    │
    ├─ State: planned (has ITERATION.md)
    │   └─ Suggest /orchestration:decompose-iteration
    │
    └─ State: active (has TASKS.md)
        └─ Show progress, suggest next task
```

### Orchestrated Task Flow

Once you have tasks, the workflow is **agent-driven with user approval gates**:

```
/plan-iteration                    ← You collaborate on what to build
    ↓
/orchestration:decompose-iteration ← Agent breaks into tasks, you approve
    ↓
┌─────────────────────────────────────────────┐
│  For each task:                             │
│                                             │
│  /orchestration:plan-task N                 │
│      ↓ agent plans, presents approach       │
│      ↓ you approve or request changes       │
│                                             │
│  /orchestration:build-task N                │
│      ↓ agent builds, shows progress         │
│      ↓ you approve when demo works          │
│                                             │
│  /orchestration:test-task N                 │
│      ↓ agent writes tests, runs them        │
│      ↓ you approve when passing             │
│                                             │
│  /complete-task N                           │
│      ↓ capture learnings, update progress   │
└─────────────────────────────────────────────┘
    ↓
/orchestration:audit-production    ← Agents scan for blockers, you get verdict
    ↓
/complete-iteration                ← Archive and synthesize
```

**The pattern: agents do the work, you say yes/no.** Each orchestrated command spawns specialized agents, validates their output, and presents results for your approval before proceeding.

### Commands

| Command | Purpose |
|---------|---------|
| `/plan-iteration` | Collaborative planning — investigate before proposing |
| `/orchestration:decompose-iteration` | Break iteration into concrete tasks (spawns agent) |
| `/orchestration:plan-task N` | Plan task implementation (spawns task-planner) |
| `/orchestration:build-task N` | Build from approved plan |
| `/orchestration:test-task N` | Write and run tests (spawns test-runner) |
| `/orchestration:audit-production` | Pre-release scan for blockers (spawns auditors) |
| `/complete-task` | Verify with working demo, capture to Lore |
| `/complete-iteration` | Archive and synthesize learnings |
| `/save-state` / `/restore-state` | Preserve and resume progress |

**Quick commands:**
- `qcheck` — Senior engineer code review
- `qtest` — Write one integration test
- `qcom` — Commit with conventional message
- `qfix` — Debug and fix an error

## Architecture

### Prompt Composition

```
momentum <project>
    │
    ├── bin/momentum (bash launcher)
    │   └── calls render-project-prompt.ts
    │
    ├── render-project-prompt.ts
    │   └── Mustache renders contexts/*.md with config values
    │
    └── System prompt:
        contexts/{mode}-identity.md
         + contexts/base.md
         + voice style
         + verbosity level
```

Identity comes first: role opener, name, personality. Then mode-specific principles. Then shared mechanics.

### Hooks

TypeScript hooks (Bun runtime) fire on Claude Code lifecycle events:

| Hook | Purpose |
|------|---------|
| **SessionStart** | Detect project state, inject XML context + PROJECT_SUMMARY.md, sync expertise |
| **UserPromptSubmit** | Add per-turn metadata (XML format) |
| **PreToolUse** | Log tool invocation to JSONL |
| **PostToolUse** | Log tool completion, track duration |
| **Stop** | Process CAPTURE lines, generate TTS summary, post to Argus |
| **SubagentStop** | Track agent completion, extract summary for Lore |
| **SessionEnd** | Cleanup session cache |

### Specialized Agents

Agents spawn via orchestrated commands or natural language:

| Agent | Triggered By | Purpose |
|-------|--------------|---------|
| **task-planner** | `/orchestration:plan-task` | Codebase analysis, complexity assessment, implementation plans |
| **test-runner** | `/orchestration:test-task` | Risk-based invariant testing, writes and runs tests |
| **iteration-decomposer** | `/orchestration:decompose-iteration` | Break features into concrete tasks |
| **code-reviewer** | "review the code" | Security, bugs, quality with confidence scoring |
| **architecture-analyst** | "analyze the architecture" | Multiple options with trade-offs |
| **architecture-reviewer** | "is this over-engineered?" | Complexity assessment, right-sizing |
| **architecture-auditor** | "check drift from design" | Compare plan vs implementation |
| **production-auditor** | `/orchestration:audit-production` | Release blockers, secrets scan |
| **implementation-analyst** | "how should I implement X" | Technical approaches |

Agents write operator logs (progress) and reports (findings) to `.workflow/agents/`.

### Personality System

Personality shapes identity, not just output:

**Styles:** sable (ethereal/measured), jarvis (efficient/warm), professional, casual

**12 behavioral dials** across 3 categories:
- **Communication:** Formality, Directness, Warmth, Confidence
- **Thinking:** Skepticism, Curiosity, Caution, Precision
- **Interaction:** Teaching, Pushback, Wit, Initiative

**7 output categories:** GIST, CONTEXT, ANALYSIS, ACTIONS, BREAKDOWN, NEXT, FLAGS

```toml
# ~/.config/momentum/config.toml
[personality]
style = "sable"

[behavior]
formality = 40       # casual ←→ formal
directness = 70      # diplomatic ←→ blunt
teaching = 75        # never ←→ liberally
```

The default "Sable" personality: serene calm, quiet authority, measured wisdom, dry wit. Inspired by Tilda Swinton's Ancient One.

### Skills

For open-ended work without project constraints:

- **exploration** — Technical exploration with structured capture
- **ideation** — Develop project ideas through conversation

### Observability

Three layers of data:

| Layer | Purpose | Location |
|-------|---------|----------|
| **JSONL** | Forensics, audit trail | `~/.local/share/momentum/events/*.jsonl` |
| **Lore** | Searchable knowledge | `~/.local/share/lore/` |
| **Argus** | Real-time dashboard | SQLite + WebSocket |

### Knowledge Capture

**CAPTURE lines** in responses save to Lore:
```
📁 CAPTURE [context] #decision: Why we chose X over Y
📁 CAPTURE [context] #gotcha: This API returns 500 when...
📁 CAPTURE [context] #learning: The pattern for X is...
```

**Project expertise** persists per-project structural knowledge:
```
.workflow/artifacts/PROJECT_EXPERTISE.toml
├── [domains.api] mental_model, patterns, files
├── [domains.frontend] mental_model, patterns, files
└── [insights] gotchas, decisions, learnings
```

## Installation

**Requirements:**
- macOS or Linux
- [Claude Code CLI](https://claude.ai/download)
- [Bun](https://bun.sh) runtime

**Optional integrations:**
- [Argus](https://github.com/nickpending/argus) — Real-time observability dashboard
- [Lore](https://github.com/nickpending/lore) — Knowledge capture and search
- [llmcli-tools](https://github.com/nickpending/llmcli-tools) — @voidwire packages for utilities

```bash
git clone https://github.com/nickpending/momentum.git
cd momentum
./install.sh
```

The installer asks for:
- Code directory (e.g., `~/development/projects/`)
- Documentation directory (e.g., `~/obsidian/projects/`)
- Your name and assistant name

## Configuration

```toml
# ~/.config/momentum/config.toml

[personalization]
name = "Your Name"
assistant_name = "Sable"
timezone = "America/Los_Angeles"

[paths]
dev = "~/development/projects"
projects = "~/obsidian/projects"

[personality]
style = "sable"  # sable, jarvis, professional, casual

[behavior]
# 12 dials across 3 categories (0-100 scale)
formality = 40       # casual ←→ formal
directness = 70      # diplomatic ←→ blunt
warmth = 60          # clinical ←→ warm
confidence = 65      # hedged ←→ assertive
teaching = 75        # never ←→ liberally
wit = 50             # none ←→ liberal
pushback = 60        # agreeable ←→ challenging

[output]
verbosity = "brief"  # terse, brief, normal

[speech]
enabled = true
provider = "elevenlabs"  # system or elevenlabs
```

## Project Structure

```
momentum/
├── bin/              # momentum launcher, setupd
├── hooks/            # TypeScript hooks (Bun)
│   └── shared/       # Config loading, path resolution, Argus client
├── contexts/         # System prompt components
│   ├── project-identity.md
│   ├── workspace-identity.md
│   ├── base.md
│   ├── output/       # Output format templates
│   └── speech/       # TTS summary templates
├── personalities/    # Style TOML files (sable, jarvis, etc.)
├── commands/         # Slash command prompts
│   └── orchestration/ # Multi-agent workflows
├── subagents/        # Specialized agent definitions
├── skills/           # Exploration, ideation
├── templates/        # Artifact scaffolding
└── resources/        # Shared guidelines (agent-rules.md, etc.)
```

**Per-project state** lives in `.workflow/`:
```
.workflow/
├── artifacts/        # TASKS.md, ITERATION.md, PROJECT_SUMMARY.md
│   ├── tasks/        # Individual task files
│   └── subagents/    # Agent reports
├── state/            # Saved state files
└── agents/
    ├── operators/    # Agent activity logs
    └── reports/      # Analysis reports
```

## Philosophy

**Ship working software every iteration.** Not plans. Not docs. Working code you can demo.

**Build first, test after.** Get it running, prove it works. Tests validate, they don't drive.

**Evidence over speculation.** Investigate actual code before proposing. Report findings with file:line references.

**Context survives interruption.** Save state, restore state, keep building.

**Personality shapes identity.** The assistant isn't a tool. It's a development partner with a voice.

## Contributing

```bash
git clone https://github.com/nickpending/momentum.git
cd momentum
momentum  # Explore in workspace mode
```

Areas we'd welcome:
- Additional specialized agents
- Language-specific quality patterns
- Voice personalities
- Integration patterns

## License

[MIT](https://github.com/nickpending/momentum/tree/HEAD/LICENSE)

---

<div align="center">

**Stop planning. Start shipping.**

</div>

Momentum

Development environment for Claude Code

Momentum wraps Claude Code with an iteration-first workflow, context that survives session limits, and a development partner with actual personality.

You work in focused iterations that ship working software. Context persists across conversations. An assistant named Sable remembers what you're building and why.

What It Does

Launches Claude Code with:

Identity-first system prompts (role, name, personality, then instructions)
Project state detection (new → vision → planned → active)
Hooks for context injection and knowledge capture
Specialized agents for code review, architecture analysis, planning
Voice system with configurable personality and verbosity

Preserves context:

/save-state before context fills
/restore-state to resume exactly where you left off
Project expertise persists across sessions
CAPTURE lines save insights to searchable knowledge base

Ships working software:

Evidence-based planning (investigate before proposing)
Micro-tasks that fit in one conversation
Demo-driven completion (prove it works)

Quick Start

git clone https://github.com/nickpending/momentum.git
cd momentum && ./install.sh

# Workspace mode - research, ideation, prototypes
momentum

# Project mode - focused building with state tracking
momentum myproject

The momentum command:

Sets up .claude/ with hooks, commands, skills, agents
Renders the system prompt with your personality config
Launches Claude Code with --append-system-prompt

Two Modes

Mode	Command	What You Get
Workspace	`momentum`	Full capabilities, no project constraints. Exploration, ideation, research.
Project	`momentum <name>`	State tracking, iteration workflow, task management. Ships software.

The Workflow

Project States

momentum myproject
    │
    ├─ State: new (no IDEA.md)
    │   └─ Offer ideation to capture vision
    │
    ├─ State: vision (has IDEA.md)
    │   └─ Suggest /plan-iteration
    │
    ├─ State: planned (has ITERATION.md)
    │   └─ Suggest /orchestration:decompose-iteration
    │
    └─ State: active (has TASKS.md)
        └─ Show progress, suggest next task

Orchestrated Task Flow

Once you have tasks, the workflow is agent-driven with user approval gates:

/plan-iteration                    ← You collaborate on what to build
    ↓
/orchestration:decompose-iteration ← Agent breaks into tasks, you approve
    ↓
┌─────────────────────────────────────────────┐
│  For each task:                             │
│                                             │
│  /orchestration:plan-task N                 │
│      ↓ agent plans, presents approach       │
│      ↓ you approve or request changes       │
│                                             │
│  /orchestration:build-task N                │
│      ↓ agent builds, shows progress         │
│      ↓ you approve when demo works          │
│                                             │
│  /orchestration:test-task N                 │
│      ↓ agent writes tests, runs them        │
│      ↓ you approve when passing             │
│                                             │
│  /complete-task N                           │
│      ↓ capture learnings, update progress   │
└─────────────────────────────────────────────┘
    ↓
/orchestration:audit-production    ← Agents scan for blockers, you get verdict
    ↓
/complete-iteration                ← Archive and synthesize

The pattern: agents do the work, you say yes/no. Each orchestrated command spawns specialized agents, validates their output, and presents results for your approval before proceeding.

Commands

Command	Purpose
`/plan-iteration`	Collaborative planning — investigate before proposing
`/orchestration:decompose-iteration`	Break iteration into concrete tasks (spawns agent)
`/orchestration:plan-task N`	Plan task implementation (spawns task-planner)
`/orchestration:build-task N`	Build from approved plan
`/orchestration:test-task N`	Write and run tests (spawns test-runner)
`/orchestration:audit-production`	Pre-release scan for blockers (spawns auditors)
`/complete-task`	Verify with working demo, capture to Lore
`/complete-iteration`	Archive and synthesize learnings
`/save-state` / `/restore-state`	Preserve and resume progress

Quick commands:

qcheck — Senior engineer code review
qtest — Write one integration test
qcom — Commit with conventional message
qfix — Debug and fix an error

Architecture

Prompt Composition

momentum <project>
    │
    ├── bin/momentum (bash launcher)
    │   └── calls render-project-prompt.ts
    │
    ├── render-project-prompt.ts
    │   └── Mustache renders contexts/*.md with config values
    │
    └── System prompt:
        contexts/{mode}-identity.md
         + contexts/base.md
         + voice style
         + verbosity level

Identity comes first: role opener, name, personality. Then mode-specific principles. Then shared mechanics.

Hooks

TypeScript hooks (Bun runtime) fire on Claude Code lifecycle events:

Hook	Purpose
SessionStart	Detect project state, inject XML context + PROJECT_SUMMARY.md, sync expertise
UserPromptSubmit	Add per-turn metadata (XML format)
PreToolUse	Log tool invocation to JSONL
PostToolUse	Log tool completion, track duration
Stop	Process CAPTURE lines, generate TTS summary, post to Argus
SubagentStop	Track agent completion, extract summary for Lore
SessionEnd	Cleanup session cache

Specialized Agents

Agents spawn via orchestrated commands or natural language:

Agent	Triggered By	Purpose
task-planner	`/orchestration:plan-task`	Codebase analysis, complexity assessment, implementation plans
test-runner	`/orchestration:test-task`	Risk-based invariant testing, writes and runs tests
iteration-decomposer	`/orchestration:decompose-iteration`	Break features into concrete tasks
code-reviewer	"review the code"	Security, bugs, quality with confidence scoring
architecture-analyst	"analyze the architecture"	Multiple options with trade-offs
architecture-reviewer	"is this over-engineered?"	Complexity assessment, right-sizing
architecture-auditor	"check drift from design"	Compare plan vs implementation
production-auditor	`/orchestration:audit-production`	Release blockers, secrets scan
implementation-analyst	"how should I implement X"	Technical approaches

Agents write operator logs (progress) and reports (findings) to .workflow/agents/.

Personality System

Personality shapes identity, not just output:

Styles: sable (ethereal/measured), jarvis (efficient/warm), professional, casual

12 behavioral dials across 3 categories:

Communication: Formality, Directness, Warmth, Confidence
Thinking: Skepticism, Curiosity, Caution, Precision
Interaction: Teaching, Pushback, Wit, Initiative

7 output categories: GIST, CONTEXT, ANALYSIS, ACTIONS, BREAKDOWN, NEXT, FLAGS

# ~/.config/momentum/config.toml
[personality]
style = "sable"

[behavior]
formality = 40       # casual ←→ formal
directness = 70      # diplomatic ←→ blunt
teaching = 75        # never ←→ liberally

The default "Sable" personality: serene calm, quiet authority, measured wisdom, dry wit. Inspired by Tilda Swinton's Ancient One.

Skills

For open-ended work without project constraints:

exploration — Technical exploration with structured capture
ideation — Develop project ideas through conversation

Observability

Three layers of data:

Layer	Purpose	Location
JSONL	Forensics, audit trail	`~/.local/share/momentum/events/*.jsonl`
Lore	Searchable knowledge	`~/.local/share/lore/`
Argus	Real-time dashboard	SQLite + WebSocket

Knowledge Capture

CAPTURE lines in responses save to Lore:

📁 CAPTURE [context] #decision: Why we chose X over Y
📁 CAPTURE [context] #gotcha: This API returns 500 when...
📁 CAPTURE [context] #learning: The pattern for X is...

Project expertise persists per-project structural knowledge:

.workflow/artifacts/PROJECT_EXPERTISE.toml
├── [domains.api] mental_model, patterns, files
├── [domains.frontend] mental_model, patterns, files
└── [insights] gotchas, decisions, learnings

Installation

Requirements:

macOS or Linux
Claude Code CLI
Bun runtime

Optional integrations:

Argus — Real-time observability dashboard
Lore — Knowledge capture and search
llmcli-tools — @voidwire packages for utilities

git clone https://github.com/nickpending/momentum.git
cd momentum
./install.sh

The installer asks for:

Code directory (e.g., ~/development/projects/)
Documentation directory (e.g., ~/obsidian/projects/)
Your name and assistant name

Configuration

# ~/.config/momentum/config.toml

[personalization]
name = "Your Name"
assistant_name = "Sable"
timezone = "America/Los_Angeles"

[paths]
dev = "~/development/projects"
projects = "~/obsidian/projects"

[personality]
style = "sable"  # sable, jarvis, professional, casual

[behavior]
# 12 dials across 3 categories (0-100 scale)
formality = 40       # casual ←→ formal
directness = 70      # diplomatic ←→ blunt
warmth = 60          # clinical ←→ warm
confidence = 65      # hedged ←→ assertive
teaching = 75        # never ←→ liberally
wit = 50             # none ←→ liberal
pushback = 60        # agreeable ←→ challenging

[output]
verbosity = "brief"  # terse, brief, normal

[speech]
enabled = true
provider = "elevenlabs"  # system or elevenlabs

Project Structure

momentum/
├── bin/              # momentum launcher, setupd
├── hooks/            # TypeScript hooks (Bun)
│   └── shared/       # Config loading, path resolution, Argus client
├── contexts/         # System prompt components
│   ├── project-identity.md
│   ├── workspace-identity.md
│   ├── base.md
│   ├── output/       # Output format templates
│   └── speech/       # TTS summary templates
├── personalities/    # Style TOML files (sable, jarvis, etc.)
├── commands/         # Slash command prompts
│   └── orchestration/ # Multi-agent workflows
├── subagents/        # Specialized agent definitions
├── skills/           # Exploration, ideation
├── templates/        # Artifact scaffolding
└── resources/        # Shared guidelines (agent-rules.md, etc.)

Per-project state lives in .workflow/:

.workflow/
├── artifacts/        # TASKS.md, ITERATION.md, PROJECT_SUMMARY.md
│   ├── tasks/        # Individual task files
│   └── subagents/    # Agent reports
├── state/            # Saved state files
└── agents/
    ├── operators/    # Agent activity logs
    └── reports/      # Analysis reports

Philosophy

Ship working software every iteration. Not plans. Not docs. Working code you can demo.

Build first, test after. Get it running, prove it works. Tests validate, they don't drive.

Evidence over speculation. Investigate actual code before proposing. Report findings with file:line references.

Context survives interruption. Save state, restore state, keep building.

Personality shapes identity. The assistant isn't a tool. It's a development partner with a voice.

Contributing

git clone https://github.com/nickpending/momentum.git
cd momentum
momentum  # Explore in workspace mode

Areas we'd welcome:

Additional specialized agents
Language-specific quality patterns
Voice personalities
Integration patterns

License

MIT

Stop planning. Start shipping.