Manifold

Constraint-first development framework that makes ALL constraints visible BEFORE implementation.

TRADITIONAL                          MANIFOLD
─────────────────────────────────    ─────────────────────────────────
Spec → Design → Build → Test         All constraints exist NOW
Discover problems during build       Problems visible before build
Sequential planning                  Constraint satisfaction
Forward reasoning                    Backward from outcome

Start Here

I want to...	Go to
Get running in 15 minutes	Quickstart
See a full feature walkthrough	Walkthrough
Look up a CLI command	CLI Reference
Understand the terminology	Glossary
Use pre-built constraint patterns	Templates
Generate PRDs and user stories	PM Guide
Use Manifold for non-software decisions	Non-Programming Guide
Fix something that's broken	Troubleshooting
Contribute to Manifold	Contributing

Features

• Constraint-First Development -- Surface all constraints before writing code
• Backward Reasoning -- Reason from desired outcomes to required truths, with recursive decomposition for multi-level dependency chains
• Tension Detection -- Find conflicts between constraints early, with TRIZ-guided resolution and directional propagation checks
• Pre-mortem Stress Testing -- Mandatory failure-story pass in constraint discovery surfaces assumptions single-pass elicitation misses
• Constraint Genealogy -- Track constraint origins (source) and challengeability (challenger) to guide tension resolution direction
• Probabilistic Bounds -- Express metric constraints as statistical targets (p99, p50, failure rates) rather than only deterministic thresholds
• Bottleneck Identification -- Theory of Constraints integration surfaces the binding constraint before solution generation
• Reversibility Tagging -- Every action step tagged as TWO_WAY, REVERSIBLE_WITH_COST, or ONE_WAY with explicit acknowledgment for irreversible decisions
• Non-Software Domain Support -- --domain=non-software activates universal categories (Obligations, Desires, Resources, Risks, Dependencies) and decision-focused artifacts
• All-at-Once Generation -- Generate code, tests, docs, runbooks, and alerts from a single source
• Evidence System -- Verify constraints with concrete proof
• Drift Detection -- Detect post-verification file changes using SHA-256 hashing
• Guided Workflow -- Structured next-step suggestions guide you through each phase
• Constraint Templates -- Pre-built patterns for auth, CRUD, API, payment, and 13 PM templates
• Light Mode -- Simplified 3-phase workflow for quick changes
• PM Workflows -- Generate PRDs and user stories with constraint traceability
• Parallel Execution -- Run independent tasks concurrently using git worktrees
• Native CLI -- Fast, deterministic operations (<100ms) for CI/CD
• Multi-Agent Support -- Works with Claude Code, AMP, Gemini CLI, and Codex CLI

Recent Changes

v2.30.2 (Current)

Prompt Quality Overhaul -- Comprehensive evaluation and fix of all 8 phase command prompts, raising aggregate quality from 3.7/5 to 4.25/5.

• SKILL.md rewritten -- Was documenting deprecated YAML format; now accurately reflects v3 JSON+Markdown hybrid, all command summaries, and CLI commands
• m4 AutoSuggester fixed -- Non-executable TypeScript block replaced with manifold solve --json CLI invocation that LLMs can actually run
• Binding constraint elevated -- m4 now reads anchors.binding_constraint as a dedicated STEP 0 before artifact planning, ensuring the bottleneck is addressed first
• Validation consistency -- m0-init and m-quick now have the same ⚠️ Mandatory Post-Phase Validation pattern as m1-m5
• Security gate for m-quick -- Light mode now detects security-relevant feature names (auth, token, password, etc.) and suggests full workflow before proceeding
• Self-contained prompts -- All references to repo-only files (docs/GLOSSARY.md, docs/triz-principles.md, cli/lib/structure-schema.ts) replaced with inlined content so the plugin works standalone
• TRIZ principles inlined -- Full parameter pair lookup table (10 conflict patterns + 14 Tier A principles) now embedded directly in m2-tension
• Eval infrastructure -- Golden test framework with 3 test cases (payment-retry, login-timeout, data-export) and assertion-based runner
• Prompt injection guard -- Pre-mortem template in m1 now explicitly instructs LLM to treat outcome text as data, not instructions

v2.30.0

• Enhanced thinking prompts -- Cross-phase data flow tracking and quality gates for constraint handoff between phases

v2.29.0

• Cross-platform hooks -- Hooks now work on macOS, Linux, and Windows
• Structured logging -- Hook output uses structured format for better debugging
• File splitting -- Large manifold files can be split for better context management
• Windows support -- Full Windows compatibility for CLI binary, installer, and hooks

See CHANGELOG.md for complete version history.

Install

Claude Code Plugin (Recommended for Claude Code users)

claude plugin:install github:dhanesh/manifold#plugin

This installs Manifold as a native Claude Code plugin, giving you:

• 12 slash commands (/manifold:m0-init through /manifold:parallel)
• 4 hooks (context preservation, parallel suggestions, schema validation, phase discipline)
• Constraint templates (auth, CRUD, API, payment, + 13 PM templates)
• /manifold:setup command to install the native CLI binary

After installing the plugin, run /manifold:setup inside Claude Code to get the fast CLI binary.

Shell Installer (All Agents)

curl -fsSL https://raw.githubusercontent.com/dhanesh/manifold/main/install/install.sh | bash

The installer auto-detects which AI agents you have and installs per-agent:

Agent	What Gets Installed	Location
Claude Code	12 slash commands (.md), parallel library, hooks, schema snippet in CLAUDE.md	~/.claude/commands/, lib/, hooks/
AMP	Same as Claude Code	~/.amp/commands/, lib/, hooks/
Gemini CLI	Translated .toml commands, parallel bundle (.js), schema snippet in GEMINI.md	~/.gemini/commands/, lib/
Codex CLI	SKILL.md skill dirs, hook skills, parallel bundle, schema snippet in AGENTS.md	~/.agents/skills/manifold-*/, ~/.codex/lib/
CLI binary	manifold binary for your platform (darwin/linux/windows, arm64/x64)	/usr/local/bin/, ~/.local/bin/, or %LOCALAPPDATA%\manifold\bin\

Specifically, the installer creates:

• commands/ -- 12 Manifold slash command files (m0-init through parallel, plus SCHEMA_REFERENCE)
• lib/parallel/ -- 12 TypeScript modules + pre-built bundle for git worktree-based parallel execution
• hooks/ -- 4 hooks: manifold-context.ts (context preservation), auto-suggester.ts (parallel suggestions), manifold-schema-guard.ts (schema validation), prompt-enforcer.ts (phase discipline)
• skills/manifold/SKILL.md -- Overview skill for /manifold command
• Schema snippet appended to your agent's instruction file (CLAUDE.md, GEMINI.md, or AGENTS.md)

The installer is idempotent -- running it again updates existing files without duplication. Run install.sh --validate to check what was installed. See Uninstall to remove.

Verify it worked:

manifold --version

CLI Binary (Standalone)

Download platform-specific binaries from Releases:

macOS / Linux:

# macOS (Apple Silicon)
curl -fsSL https://github.com/dhanesh/manifold/releases/latest/download/manifold-darwin-arm64 -o manifold

# macOS (Intel)
curl -fsSL https://github.com/dhanesh/manifold/releases/latest/download/manifold-darwin-x64 -o manifold

# Linux (x64)
curl -fsSL https://github.com/dhanesh/manifold/releases/latest/download/manifold-linux-x64 -o manifold

# Linux (ARM64)
curl -fsSL https://github.com/dhanesh/manifold/releases/latest/download/manifold-linux-arm64 -o manifold

chmod +x manifold

Windows (PowerShell):

# Download and install via PowerShell
Invoke-WebRequest -Uri "https://github.com/dhanesh/manifold/releases/latest/download/manifold-windows-x64.exe" -OutFile "$env:LOCALAPPDATA\manifold\bin\manifold.exe"

# Or use the install script (handles PATH setup automatically)
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/dhanesh/manifold/main/plugin/bin/install-cli.ps1" -OutFile "$env:TEMP\install-manifold.ps1"
powershell -ExecutionPolicy Bypass -File "$env:TEMP\install-manifold.ps1"

The Windows binary is a standalone .exe -- no runtime (Bun/Node) required.

Quick Start

/manifold:m0-init payment-retry --outcome="95% retry success"
/manifold:m1-constrain payment-retry        # Discover constraints across 5 categories
/manifold:m2-tension payment-retry          # Surface conflicts: latency vs idempotency
/manifold:m3-anchor payment-retry           # Backward reasoning -> solution options
/manifold:m4-generate payment-retry         # Create code, tests, docs, runbooks, alerts
/manifold:m5-verify payment-retry           # Validate all artifacts against constraints

For simple changes that don't need full constraint analysis:

/manifold:m-quick fix-login-bug --outcome="Fix 504 timeout on login"

See Quickstart for a complete 15-minute guide, or When NOT to Use for when simpler approaches work better.

Commands

AI Agent Commands (Claude Code / AMP)

Command	Purpose	Phase
/manifold:m0-init	Initialize constraint manifold	INITIALIZED
/manifold:m1-constrain	Discover constraints (interview-driven)	CONSTRAINED
/manifold:m2-tension	Surface constraint conflicts	TENSIONED
/manifold:m3-anchor	Backward reasoning from outcome	ANCHORED
/manifold:m4-generate	Create all artifacts simultaneously	GENERATED
/manifold:m5-verify	Validate against constraints	VERIFIED
/manifold:m6-integrate	Wire artifacts together	-
/manifold:m-status	Show current state	-
/manifold:m-solve	Generate parallel execution plan	-
/manifold:m-quick	Light mode: 3-phase workflow	-
/manifold:parallel	Execute tasks in parallel worktrees	-

Native CLI

The CLI provides instant operations without AI round-trips. See CLI Reference for complete documentation.

manifold status [feature]          # Show manifold state
manifold validate [feature]        # Validate schema (exit 2 = invalid)
manifold init <feature>            # Initialize new manifold
manifold verify [feature]          # Verify artifacts exist
manifold graph [feature]           # Visualize constraint network
manifold show [feature]            # Combined JSON+MD view
manifold solve [feature]           # Parallel execution plan
manifold migrate [feature]         # Convert YAML -> JSON+MD
manifold drift [feature]          # Detect post-verification file changes
manifold completion [shell]        # Shell completions (bash/zsh/fish)

When to use CLI vs AI commands:

• CLI: Status checks, CI/CD validation, visualization, quick verification
• AI: Constraint discovery, tension analysis, code generation

Phase Workflow

INITIALIZED -> CONSTRAINED -> TENSIONED -> ANCHORED -> GENERATED -> VERIFIED
     ^                                                              |
     +----------------------- (iteration) --------------------------+

Each phase builds on the previous:

1. Initialize -- Name the feature, state the outcome
2. Constrain -- Interview-driven discovery across 5 categories (business, technical, UX, security, operational), with pre-mortem stress testing and constraint genealogy tagging
3. Tension -- Find and resolve conflicts between constraints, with TRIZ principle lookup and directional propagation checks
4. Anchor -- Reason backward from outcome to derive required truths, with recursive decomposition and bottleneck identification
5. Generate -- Create ALL artifacts (code, tests, docs, runbooks, alerts) simultaneously, with reversibility tagging per action step
6. Verify -- Validate every artifact against every constraint with evidence

See the Walkthrough for a real example with actual outputs.

Constraint System

Types

Type	Meaning	Priority	Example
invariant	Must NEVER be violated	Highest	"No duplicate payments"
boundary	Hard limits	Medium	"Retry window <= 72 hours"
goal	Should be optimized	Lowest	"95% retry success rate"

Categories

Category	ID Prefix	Focus
Business	B1, B2...	Revenue, compliance, stakeholders
Technical	T1, T2...	Performance, integration, data
User Experience	U1, U2...	Response times, errors, accessibility
Security	S1, S2...	Data protection, auth, audit
Operational	O1, O2...	Monitoring, incidents, deployment

Schema

Manifold uses JSON+Markdown hybrid format stored in .manifold/:

.manifold/
+-- <feature>.json           # Structure (IDs, types, phases)
+-- <feature>.md             # Content (statements, rationale)
+-- <feature>.verify.json    # Verification results

Legacy YAML format (.yaml files) is still supported. Use manifold migrate to convert.

Valid Values

Field	Valid Values
phase	INITIALIZED, CONSTRAINED, TENSIONED, ANCHORED, GENERATED, VERIFIED
constraint.type	invariant, goal, boundary
tension.type	trade_off, resource_tension, hidden_dependency
tension.status	resolved, unresolved
required_truth.status	SATISFIED, PARTIAL, NOT_SATISFIED, SPECIFICATION_READY
convergence.status	NOT_STARTED, IN_PROGRESS, CONVERGED

See Schema Reference for complete documentation.

Using Templates

Pre-built constraint patterns for common scenarios:

/manifold:m0-init user-auth --template=auth        # Authentication flows
/manifold:m0-init user-crud --template=crud        # CRUD operations
/manifold:m0-init payment-flow --template=payment  # Payment processing
/manifold:m0-init api-endpoint --template=api      # API endpoints

See Constraint Templates for all 17 templates including PM-specific patterns.

CI/CD Integration

# Validate manifolds (exit 2 = validation failure)
manifold validate --json

# Verify artifacts exist
manifold verify --json

# Evidence verification (strict mode for CI)
manifold verify --verify-evidence --strict --json

# Check for post-verification drift (exit 2 = drift detected)
manifold drift --json

GitHub Action

# .github/workflows/ci.yml
jobs:
  manifold:
    uses: dhanesh/manifold/.github/workflows/manifold-verify.yml@main
    with:
      fail-on-gaps: false  # Set true to fail on non-blocking gaps

Parallel Execution

Run independent tasks concurrently using isolated git worktrees:

/manifold:parallel "implement auth module" "add logging middleware" "create user tests"

See Parallel Agents Guide for configuration and advanced usage.

Product Manager Workflow

Generate PRDs and user stories with constraint traceability:

/manifold:m0-init mobile-checkout --template=pm/feature-launch
/manifold:m1-constrain mobile-checkout
/manifold:m2-tension mobile-checkout
/manifold:m3-anchor mobile-checkout
/manifold:m4-generate mobile-checkout --prd --stories

See PM Guide for detailed workflows and PM Templates for all 10 PM-specific templates.

Non-Programming Use Cases

Manifold's constraint-first approach extends beyond software. Use --domain=non-software to activate universal categories and decision-focused artifacts:

/manifold:m0-init career-change --domain=non-software --outcome="Make the right career move"

Domain	Best For
Research/Analysis	Methodology design, study planning
Business	Strategic decisions, expansion planning
Personal	Major life decisions, career choices
Creative	Project planning (not creative direction)

Non-software mode uses five universal categories (Obligations, Desires, Resources, Risks, Dependencies) and generates decision artifacts (decision brief, scenario stress-tests, narrative guide, recovery playbook, risk watch list) instead of code.

See Non-Programming Guide for full details, universal category definitions, and examples.

Documentation

Document	Description
Quickstart	Get started in 15 minutes
CLI Reference	Complete CLI command documentation
Evidence System	Evidence types and verification
Walkthrough	End-to-end feature example
Glossary	Plain-language terminology
Troubleshooting	Common errors and fixes
When NOT to Use	Know when simpler approaches work
TRIZ Principles	40 inventive principles for tension resolution
Non-Programming Guide	Using Manifold for non-software decisions
Scientific Foundations	Research supporting each phase
Contributing	How to contribute

Uninstall

curl -fsSL https://raw.githubusercontent.com/dhanesh/manifold/main/install/uninstall.sh | bash

License

MIT