Skip to content

Commit 2de938e

Browse files
dhaneshclaude
dhanesh
and
claude
committed
docs: update README with current capabilities and v2.5 features
- Add release/license badges - Add CLI binary download instructions for all platforms - Document new commands: /m6-integrate, /m-status, /m-solve, /parallel - Add parallel execution section with configuration - Update schema documentation to v3 - Streamline structure and remove redundant sections Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 8ada2a4 commit 2de938e

1 file changed

Lines changed: 149 additions & 81 deletions

File tree

‎README.md‎

Lines changed: 149 additions & 81 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
# Manifold
22

3+
[![Release](https://img.shields.io/github/v/release/dhanesh/manifold)](https://github.com/dhanesh/manifold/releases)
4+
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
5+
36
Constraint-first development framework that makes ALL constraints visible BEFORE implementation.
47

58
## Philosophy
@@ -13,6 +16,16 @@ Sequential planning Constraint satisfaction
1316
Forward reasoning Backward from outcome
1417
```
1518

19+
## Features
20+
21+
- **Constraint-First Development** - Surface all constraints before writing code
22+
- **Backward Reasoning** - Reason from desired outcomes to required truths
23+
- **Tension Detection** - Find conflicts between constraints early
24+
- **All-at-Once Generation** - Generate code, tests, docs, runbooks, and alerts from a single source
25+
- **Parallel Execution** - Run independent tasks concurrently using git worktrees
26+
- **Native CLI** - Fast, deterministic operations (<100ms) for CI/CD
27+
- **Multi-Agent Support** - Works with Claude Code and AMP
28+
1629
## Install
1730

1831
```bash
@@ -21,28 +34,50 @@ curl -fsSL https://raw.githubusercontent.com/dhanesh/manifold/main/install/insta
2134

2235
This installs:
2336
- **Slash commands** (`/m0-init`, `/m1-constrain`, etc.) for Claude Code and AMP
37+
- **Parallel execution library** for git worktree-based concurrency
38+
- **Context preservation hooks** for session continuity
2439
- **Native CLI** (`manifold`) for fast, deterministic operations
2540

26-
Supports: **Claude Code** and **AMP**
41+
### CLI Binary
42+
43+
Download platform-specific binaries from [Releases](https://github.com/dhanesh/manifold/releases):
44+
45+
```bash
46+
# macOS (Apple Silicon)
47+
curl -fsSL https://github.com/dhanesh/manifold/releases/latest/download/manifold-darwin-arm64 -o manifold
48+
49+
# macOS (Intel)
50+
curl -fsSL https://github.com/dhanesh/manifold/releases/latest/download/manifold-darwin-x64 -o manifold
51+
52+
# Linux (x64)
53+
curl -fsSL https://github.com/dhanesh/manifold/releases/latest/download/manifold-linux-x64 -o manifold
54+
55+
# Linux (ARM64)
56+
curl -fsSL https://github.com/dhanesh/manifold/releases/latest/download/manifold-linux-arm64 -o manifold
57+
58+
chmod +x manifold
59+
```
2760

2861
## Commands
2962

3063
### AI Agent Commands (Claude Code / AMP)
3164

32-
| Command | Purpose |
33-
|---------|---------|
34-
| `/m0-init` | Initialize constraint manifold |
35-
| `/m1-constrain` | Discover constraints (interview-driven) |
36-
| `/m2-tension` | Surface constraint conflicts |
37-
| `/m3-anchor` | Backward reasoning from outcome |
38-
| `/m4-generate` | Create all artifacts |
39-
| `/m5-verify` | Validate against constraints |
40-
| `/m6-integrate` | Wire artifacts together (v2) |
41-
| `/m-status` | Show current state |
65+
| Command | Purpose | Phase |
66+
|---------|---------|-------|
67+
| `/m0-init` | Initialize constraint manifold | INITIALIZED |
68+
| `/m1-constrain` | Discover constraints (interview-driven) | CONSTRAINED |
69+
| `/m2-tension` | Surface constraint conflicts | TENSIONED |
70+
| `/m3-anchor` | Backward reasoning from outcome | ANCHORED |
71+
| `/m4-generate` | Create all artifacts simultaneously | GENERATED |
72+
| `/m5-verify` | Validate against constraints | VERIFIED |
73+
| `/m6-integrate` | Wire artifacts together | - |
74+
| `/m-status` | Show current state | - |
75+
| `/m-solve` | Generate parallel execution plan | - |
76+
| `/parallel` | Execute tasks in parallel worktrees | - |
4277

43-
### Native CLI (Fast, Deterministic)
78+
### Native CLI
4479

45-
The CLI provides instant operations without AI round-trips (<100ms):
80+
The CLI provides instant operations without AI round-trips:
4681

4782
```bash
4883
manifold status [feature] # Show manifold state
@@ -74,40 +109,40 @@ manifold verify [feature] # Verify artifacts exist
74109

75110
```
76111
┌─────────────────────────────────────────────────────────────────────┐
77-
│ PHASE 1: INITIALIZE & CONSTRAIN │
112+
│ PHASE 1: INITIALIZE & CONSTRAIN │
78113
├─────────────────────────────────────────────────────────────────────┤
79114
│ /m0-init feature-name --outcome="Success criteria" │
80115
│ └─→ Creates constraint manifold │
81116
│ │
82117
│ /m1-constrain feature-name │
83118
│ └─→ Interview-driven constraint discovery │
84-
│ └─→ 5 categories: Business, Technical, UX, Security, Ops │
119+
│ └─→ 5 categories: Business, Technical, UX, Security, Ops │
85120
└─────────────────────────────────────────────────────────────────────┘
86-
│
87-
▼
121+
│
122+
▼
88123
┌─────────────────────────────────────────────────────────────────────┐
89-
│ PHASE 2: TENSION ANALYSIS │
124+
│ PHASE 2: TENSION ANALYSIS │
90125
├─────────────────────────────────────────────────────────────────────┤
91126
│ /m2-tension feature-name --resolve │
92127
│ └─→ Surfaces constraint conflicts │
93-
│ └─→ Types: Direct, Resource, Trade-off, Hidden │
128+
│ └─→ Types: Direct, Resource, Trade-off, Hidden │
94129
│ └─→ Suggests resolutions │
95130
└─────────────────────────────────────────────────────────────────────┘
96-
│
97-
▼
131+
│
132+
▼
98133
┌─────────────────────────────────────────────────────────────────────┐
99-
│ PHASE 3: OUTCOME ANCHORING │
134+
│ PHASE 3: OUTCOME ANCHORING │
100135
├─────────────────────────────────────────────────────────────────────┤
101136
│ /m3-anchor feature-name --outcome="Success criteria" │
102137
│ └─→ Reasons BACKWARD from desired outcome │
103138
│ └─→ Derives required truths │
104139
│ └─→ Identifies gaps │
105140
│ └─→ Generates solution space │
106141
└─────────────────────────────────────────────────────────────────────┘
107-
│
108-
▼
142+
│
143+
▼
109144
┌─────────────────────────────────────────────────────────────────────┐
110-
│ PHASE 4: GENERATE & VERIFY │
145+
│ PHASE 4: GENERATE & VERIFY │
111146
├─────────────────────────────────────────────────────────────────────┤
112147
│ /m4-generate feature-name --option=A │
113148
│ └─→ Generates ALL artifacts simultaneously: │
@@ -120,9 +155,48 @@ manifold verify [feature] # Verify artifacts exist
120155
│ /m5-verify feature-name │
121156
│ └─→ Verifies ALL artifacts against ALL constraints │
122157
│ └─→ Reports coverage and gaps │
158+
│ │
159+
│ /m6-integrate feature-name │
160+
│ └─→ Identifies integration points │
161+
│ └─→ Produces wiring checklist │
123162
└─────────────────────────────────────────────────────────────────────┘
124163
```
125164

165+
## Parallel Execution
166+
167+
Run independent tasks concurrently using isolated git worktrees:
168+
169+
```bash
170+
/parallel "implement auth module" "add logging middleware" "create user tests"
171+
```
172+
173+
The parallel system:
174+
1. **Analyzes tasks** - Predicts which files each task will modify
175+
2. **Detects overlaps** - Identifies potential file conflicts
176+
3. **Forms safe groups** - Groups tasks with no file overlap
177+
4. **Executes concurrently** - Creates isolated worktrees for each group
178+
5. **Merges results** - Automatically merges back to main worktree
179+
180+
### Configuration
181+
182+
Create `.parallel.yaml` in your project root:
183+
184+
```yaml
185+
enabled: true
186+
autoSuggest: true
187+
autoParallel: false
188+
maxParallel: 4
189+
maxDiskUsagePercent: 90
190+
maxMemoryUsagePercent: 85
191+
timeout: 300000
192+
cleanupOnComplete: true
193+
mergeStrategy: sequential # sequential, squash, rebase
194+
```
195+
196+
### Auto-Suggestion
197+
198+
The `/m4-generate` command automatically suggests parallel execution when generating 3+ artifacts across different modules.
199+
126200
## Why Manifold?
127201

128202
### 1. Surface Conflicts Before Coding
@@ -162,15 +236,17 @@ Manifold: All artifacts derive from the SAME constraint source:
162236
- Runbooks for failure modes
163237
- Dashboards and alerts
164238

165-
## Constraint Types
239+
## Constraint System
240+
241+
### Constraint Types
166242

167243
| Type | Meaning | Example |
168244
|------|---------|---------|
169245
| **INVARIANT** | Must NEVER be violated | "No duplicate payments" |
170246
| **GOAL** | Should be optimized | "95% retry success rate" |
171247
| **BOUNDARY** | Hard limits | "Retry window ≤ 72 hours" |
172248

173-
## Constraint Categories
249+
### Constraint Categories
174250

175251
| Category | Focus | Example Questions |
176252
|----------|-------|-------------------|
@@ -180,15 +256,17 @@ Manifold: All artifacts derive from the SAME constraint source:
180256
| **Security** | Data protection, auth, audit | What data needs protection? |
181257
| **Operational** | Monitoring, incidents, deployment | What needs monitoring? |
182258

183-
## Verification Status
259+
### Verification Status
184260

185261
| Status | Symbol | Meaning |
186262
|--------|--------|---------|
187263
| SATISFIED | ✓ | Constraint fully satisfied |
188264
| PARTIAL | ◐ | Some evidence, gaps remain |
189265
| NOT SATISFIED | ✗ | Constraint not addressed |
190266

191-
## Storage
267+
## Schema
268+
269+
Manifold uses YAML files stored in `.manifold/`:
192270

193271
```
194272
.manifold/
@@ -197,28 +275,29 @@ Manifold: All artifacts derive from the SAME constraint source:
197275
└── <feature>.verify.yaml # Verification results
198276
```
199277

200-
## Key Principles
278+
### Schema Version 3 (Current)
201279

202-
1. **All constraints exist simultaneously** — business, technical, UX, security, operational are all present-tense constraints
203-
2. **Surface conflicts early** — what fails in tension analysis won't surprise you in production
204-
3. **Reason backward from outcomes** — if outcome X is true, what must be true?
205-
4. **Generate all artifacts at once** — all artifacts derive from same manifold, no drift
206-
207-
## Quality Gates
208-
209-
Always validate manifolds before committing changes:
210-
211-
```bash
212-
# Validate all manifolds (run after any /m* command)
213-
manifold validate
214-
215-
# Exit codes:
216-
# 0 = valid
217-
# 1 = error (file not found, etc)
218-
# 2 = validation failure (schema violations)
280+
```yaml
281+
schema_version: 3
282+
feature: payment-retry
283+
outcome: "95% retry success rate"
284+
phase: INITIALIZED
285+
286+
constraints:
287+
business: []
288+
technical: []
289+
user_experience: []
290+
security: []
291+
operational: []
292+
293+
tensions: []
294+
anchors: []
295+
iterations: []
296+
convergence:
297+
status: NOT_STARTED
219298
```
220299

221-
### Valid Values Reference
300+
### Valid Values
222301

223302
| Field | Valid Values |
224303
|-------|--------------|
@@ -229,13 +308,6 @@ manifold validate
229308
| `required_truth.status` | SATISFIED, PARTIAL, NOT_SATISFIED, SPECIFICATION_READY |
230309
| `convergence.status` | NOT_STARTED, IN_PROGRESS, CONVERGED |
231310

232-
### Pre-Commit Checklist
233-
234-
Before committing manifold changes:
235-
1. Run `manifold validate` — all manifolds must pass
236-
2. Run `manifold status <feature>` — verify phase progression makes sense
237-
3. Check `convergence.status` vs `phase` — they track different things
238-
239311
## CI/CD Integration
240312

241313
### GitHub Action
@@ -270,9 +342,27 @@ manifold validate --json
270342
manifold verify --json
271343
```
272344

345+
## Context Preservation
346+
347+
To preserve manifold state across context compaction, add to `~/.claude/settings.json`:
348+
349+
```json
350+
{
351+
"hooks": {
352+
"PreCompact": [{
353+
"matcher": "",
354+
"hooks": [{
355+
"type": "command",
356+
"command": "bun run ~/.claude/hooks/manifold-context.ts"
357+
}]
358+
}]
359+
}
360+
}
361+
```
362+
273363
## Non-Programming Use Cases
274364

275-
Manifold's constraint-first approach extends beyond software engineering to any complex decision:
365+
Manifold's constraint-first approach extends beyond software engineering:
276366

277367
| Domain | Applicability | Best For |
278368
|--------|--------------|----------|
@@ -281,7 +371,7 @@ Manifold's constraint-first approach extends beyond software engineering to any
281371
| **Personal** | HIGH | Major life decisions, career choices |
282372
| **Creative** | MODERATE | Project planning (not creative direction) |
283373

284-
### Adapted Categories for Non-Programmers
374+
### Adapted Categories
285375

286376
| Original | Adapted | Focus Question |
287377
|----------|---------|----------------|
@@ -291,7 +381,7 @@ Manifold's constraint-first approach extends beyond software engineering to any
291381
| Security | **Risks** | What could go wrong? |
292382
| Operational | **Logistics** | How will this work day-to-day? |
293383

294-
See [Non-Programming Guide](docs/non-programming/guide.md) for detailed documentation and example scenarios.
384+
See [Non-Programming Guide](docs/non-programming/guide.md) for detailed documentation.
295385

296386
## Contributing
297387

@@ -306,29 +396,7 @@ git commit -m "feat: add new feature" # Creates MINOR release
306396
git commit -m "fix: resolve bug" # Creates PATCH release
307397
```
308398

309-
See [Release Automation Guide](docs/release-automation/README.md) for details on:
310-
- Commit message format
311-
- Version bump rules
312-
- Changelog generation
313-
- Manual release triggers
314-
315-
## Context Preservation
316-
317-
To preserve manifold state across context compaction, add to `~/.claude/settings.json`:
318-
319-
```json
320-
{
321-
"hooks": {
322-
"PreCompact": [{
323-
"matcher": "",
324-
"hooks": [{
325-
"type": "command",
326-
"command": "bun run ~/.claude/hooks/manifold-context.ts"
327-
}]
328-
}]
329-
}
330-
}
331-
```
399+
See [Release Automation Guide](docs/release-automation/README.md) for details.
332400

333401
## Uninstall
334402

0 commit comments

Comments
 (0)