solveos-cli

Install the solveOS problem-solving framework as slash commands, agents, and hooks into your AI coding assistant.

solveOS teaches you how to think about AI-assisted work. solveos-cli makes sure you actually do it.

What it does

solveos-cli adds a structured Plan -> Build -> Ship cycle to your AI coding assistant with:

• 14 slash commands for every step of the cycle
• 7 specialized agents (planner, researcher, executor, validators, reviewer, debugger)
• Optional quality gates (research, plan validation, build validation, review)
• Wave-based parallel execution for complex builds
• Markdown-based state -- all artifacts live in .solveos/, no databases or cloud accounts

It does not replace your coding assistant. It adds structure on top of it.

Supported runtimes

Runtime	Priority	Command prefix
OpenCode	P0	/solveos-new
Claude Code	P1	/solveos-new
Cursor	P2	/solveos-new
Gemini CLI	P3	/solveos:new

Quick start

1. Install

npm i solveos-cli

Or run without installing:

npx solveos-cli@latest

The installer auto-detects your runtime and copies commands, agents, and templates into the correct directories. Pass --runtime <name> to override detection (e.g., --runtime claude-code).

2. Start a cycle

/solveos-new

This initializes the .solveos/ directory with a config file, state tracker, and empty brief.

3. Plan

/solveos-plan

The planner agent walks you through the 8 Plan Brief questions: Problem, Audience, Goal, Appetite, Constraints, Success Criteria, Core Assumption, and Rabbit Holes.

4. Build

/solveos-build

The executor agent works through the plan using wave-based parallel execution, checking off success criteria as it goes.

5. Ship

/solveos-ship

Final confirmation, archival to .solveos/history/, and cycle completion.

Command reference

Command	Description
/solveos-new	Start a new project or cycle
/solveos-research	Conduct bounded research on a specific question
/solveos-plan	Create a Plan Brief via the planner agent
/solveos-validate-plan	Validate the Plan Brief (catches ambiguity early)
/solveos-build	Execute the Build phase against the Plan Brief
/solveos-validate-build	Validate build output against success criteria
/solveos-review	Pre-ship or post-ship review
/solveos-ship	Ship the current cycle
/solveos-status	Show current cycle status
/solveos-next	Suggest or execute the next step
/solveos-new-cycle	Start a new cycle with feed-forward from review
/solveos-quick	Lightweight workflow: minimal plan + immediate build
/solveos-fast	Zero-overhead inline execution, no artifacts
/solveos-archive	Manually archive/abandon the current cycle

Agents

Agent	Role
solveos-planner	Guides Plan Brief creation through interactive questioning
solveos-researcher	Conducts bounded research to inform planning
solveos-executor	Executes work using wave-based parallel execution
solveos-plan-validator	Validates Plan Brief against 3 core questions
solveos-build-validator	Validates build output against success criteria
solveos-reviewer	Runs pre-ship judgment or post-ship outcome measurement
solveos-debugger	Diagnoses issues found during validation gates

The cycle

         [Research]          [Validate Plan]     [Validate Build]    [Review]
            |                     |                    |                |
INIT -> RESEARCHING -> PLANNING -> VALIDATING_PLAN -> BUILDING -> VALIDATING_BUILD
                                                        |
                                                   REVIEWING_PRE -> READY_TO_SHIP -> SHIPPED
                                                                                       |
                                                                               REVIEWING_POST -> CYCLE_COMPLETE

Gates in [brackets] are optional. Skip any gate to move faster; enable all for maximum rigor.

Rigor scaling

Mode	Commands	Gates	Artifacts	Use when
Full	All 14	All enabled	Full .solveos/	Multi-day features, high-stakes changes
Quick	/solveos-quick	None	Minimal brief	Small features, well-understood problems
Fast	/solveos-fast	None	None	Bug fixes, one-liners, trivial changes

Configuration

Configuration lives in .solveos/config.json. Key options:

{
  "mode": "interactive",
  "gates": {
    "research": true,
    "plan_validation": true,
    "build_validation": true,
    "review_pre_ship": true,
    "review_post_ship": true
  },
  "plan_validation_max_passes": 3,
  "granularity": "standard",
  "domain": "software",
  "runtime": "auto",
  "hooks": {
    "context_monitor": true,
    "context_monitor_threshold": 60,
    "brief_anchor": true,
    "brief_anchor_interval": 10
  }
}

Option	Values	Default	Description
mode	interactive, auto	interactive	Whether gates require human confirmation
gates.*	true, false	true	Enable/disable individual quality gates
plan_validation_max_passes	1-10	3	Max validation loops before escalation
granularity	coarse, standard, fine	standard	Wave execution unit size
domain	software, content, research, strategy, general	software	Domain-specific agent prompt variants
runtime	opencode, claude-code, cursor, gemini, auto	auto	Target runtime (auto-detected if auto)

Project structure

After installation, your project gains:

.solveos/
  config.json          # Configuration
  STATE.md             # Current cycle state (human-readable)
  BRIEF.md             # Plan Brief for current cycle
  research/            # Research summaries
  validations/         # Plan and build validation logs
  reviews/             # Pre-ship and post-ship reviews
  history/             # Archived cycles
  notes/               # Freeform notes

Domain modes

solveos-cli is domain-agnostic. The domain setting adjusts agent prompts:

• software -- Code-focused: PRs, tests, CI, APIs, deployment
• content -- Writing-focused: drafts, outlines, editorial review
• research -- Investigation-focused: hypotheses, evidence, synthesis
• strategy -- Decision-focused: options analysis, stakeholder alignment
• general -- No domain-specific adjustments

Links

• solveOS Framework -- The conceptual framework behind this CLI
• GitHub Repository
• User Guide -- Detailed usage documentation
• Worked Example -- Complete cycle walkthrough

License

MIT