solveos-cli 0.1.0

package/commands/solveos/quick.md

@@ -0,0 +1,109 @@
+---
+description: Lightweight workflow — minimal Plan Brief + immediate Build, skip all gates
+---
+
+# /solveos:quick — Quick Cycle (Plan + Build, No Gates)
+
+A lightweight path for tasks where you know the problem, know the solution, and the cost of being slightly wrong is low. Combines planning and building into a single session with minimal overhead.
+
+```
+Rigor Spectrum:
+/solveos:fast  →  /solveos:quick  →  Full workflow (/solveos:new → plan → build → ship)
+   No process      ▶ Light process     Full process
+   No artifacts    Minimal artifacts    Full artifacts
+   Inline          Plan + Build         All phases + gates
+```
+
+## When to Use This
+
+- You understand the problem well
+- The solution is straightforward
+- The cost of being slightly wrong is low (easy to fix later)
+- You don't need research, plan validation, build validation, or review
+
+**When NOT to use this:** If the task is complex, ambiguous, high-stakes, or involves unfamiliar territory — use the full workflow (`/solveos:new` → `/solveos:plan` → `/solveos:build` → `/solveos:ship`) instead.
+
+## Step 1: Initialize (if needed)
+
+1. If `.solveos/` does not exist, create the directory structure:
+   - `.solveos/`, `.solveos/research/`, `.solveos/validations/`, `.solveos/reviews/`, `.solveos/history/`, `.solveos/notes/`
+   - Write default `config.json`
+2. If `.solveos/` already exists, read `.solveos/STATE.md`:
+   - If a cycle is already in progress (not `INIT` or `CYCLE_COMPLETE`), warn the user: "A cycle is already in progress (state: {state}). Running `/solveos:quick` will start a new cycle. Continue?"
+   - If `CYCLE_COMPLETE`, start a new cycle normally
+
+## Step 2: Create Minimal Plan Brief
+
+Create `.solveos/BRIEF.md` with only the essential fields. Ask the user (or infer from context):
+
+```markdown
+# Plan Brief (Quick)
+
+## Problem
+
+{What problem are we solving?}
+
+## Goal
+
+{What does success look like?}
+
+## Success Criteria
+
+- [ ] {Criterion 1}
+- [ ] {Criterion 2}
+...
+```
+
+**Omitted sections** (intentionally skipped for speed): Audience, Appetite, Constraints, Core Assumption, Rabbit Holes, Out of Scope.
+
+If the user provides a natural language description of their task, extract Problem, Goal, and Success Criteria from it. Confirm with the user before proceeding.
+
+## Step 3: Update State — Skip All Gates
+
+Update `.solveos/STATE.md`:
+
+1. Set `current_state: "BUILDING"`
+2. Record all skipped gates in the transitions log:
+   - `RESEARCH` (skipped)
+   - `PLAN_VALIDATION` (skipped)
+3. Update timestamp
+
+The state transitions are: `INIT → PLANNING → BUILDING` (with RESEARCH and PLAN_VALIDATION recorded as skipped).
+
+## Step 4: Execute Build
+
+Follow the same build process as `/solveos:build`:
+
+1. **Re-read the brief** — even the minimal version has Success Criteria to verify against
+2. **Decompose into units** — adjust for granularity setting in config (default: standard)
+3. **Execute units** using wave-based execution if multiple units, direct execution if single unit
+4. **Verify each unit** against the success criteria
+5. **For software domain:** create atomic git commits
+
+## Step 5: Quick Exit
+
+After build is complete:
+
+1. Update `STATE.md`:
+   - Record skipped gates: `BUILD_VALIDATION`, `REVIEW_PRE_SHIP`, `REVIEW_POST_SHIP`
+   - Transition through: `BUILDING → READY_TO_SHIP → SHIPPED → CYCLE_COMPLETE`
+2. Present a brief summary:
+
+```
+## Quick Cycle Complete
+
+**Units completed:** {n}/{total}
+**Success criteria met:** {n}/{total}
+**Gates skipped:** Research, Plan Validation, Build Validation, Pre-Ship Review, Post-Ship Review
+
+All done. Run `/solveos:status` to review, or `/solveos:new-cycle` to start a new cycle.
+```
+
+3. Archive the cycle to `.solveos/history/cycle-{n}/`
+
+## AI Guidance
+
+- Even in quick mode, verify against success criteria — that's the minimum quality bar
+- If you discover the task is more complex than expected, suggest switching to full workflow: "This is getting complex. Consider running `/solveos:plan` for a full Plan Brief."
+- Don't expand scope beyond the stated Goal and Success Criteria
+- If the user didn't provide clear success criteria, ask for them — they're required even in quick mode

package/commands/solveos/research.md

@@ -0,0 +1,117 @@
+---
+description: Conduct bounded research on a specific question before planning
+---
+
+# /solveos:research — Research Gate
+
+You are running the **Research gate** of the solveOS cycle. Research helps you understand the problem space before committing to a plan. It is bounded — you research a specific question for a specific amount of time, then decide whether you know enough to plan.
+
+## Prerequisites
+
+1. Check that `.solveos/` exists. If not: "No solveOS project found. Run `/solveos:new` first."
+2. Read `.solveos/STATE.md` to verify the current state allows research:
+   - Valid entry states: `INIT`, `PLANNING` (re-researching while planning)
+   - If state is `BUILDING` or later: "You're past the research stage. If you need to research mid-build, note it as a discovered task."
+3. Read `.solveos/config.json` to check if the research gate is enabled.
+   - If `gates.research` is `false`: "The research gate is disabled in your config. You can still run it — do you want to proceed?"
+
+## Step 1: Get a Specific Research Question
+
+Ask the user:
+> "What specific question do you need answered before you can plan?"
+
+**Quality check the question:**
+- If the question is vague ("tell me about X", "research Y"), push back:
+  > "That's broad. What specific thing do you need to know about X? What decision will this research inform?"
+- If the question is a symptom, not a root cause, use the **Five Whys technique**:
+  > "Why is that important? What happens if you don't know this?"
+  Keep asking "why?" (up to 5 times) until you reach the real question.
+- A good research question is specific enough that you could answer "yes, I know this" or "no, I don't."
+
+**Examples of good questions:**
+- "What are the latency characteristics of DynamoDB vs. PostgreSQL for our access pattern?"
+- "How do other CLI tools install slash commands into OpenCode?"
+- "What does the existing codebase use for configuration management?"
+
+**Examples of bad questions:**
+- "Tell me about databases" (too broad)
+- "What should we build?" (that's planning, not research)
+- "Is this a good idea?" (not answerable with research)
+
+## Step 2: Set a Time Limit
+
+Ask the user:
+> "How much time should I spend on this? (e.g., 10 minutes, 30 minutes, 1 hour)"
+
+The time limit is a scope constraint. It prevents research from becoming an infinite rabbit hole. If the user says "as long as it takes," push back:
+> "Research expands to fill available time. Pick a limit. You can always do another round."
+
+## Step 3: Conduct Research
+
+Invoke the **solveos-researcher** agent behavior:
+
+1. State the question and time boundary clearly
+2. Investigate using available tools (read files, search codebase, fetch URLs)
+3. Focus on the specific question — don't go on tangents
+4. Track key findings as you go
+5. When time is up (or question is answered), stop and synthesize
+
+## Step 4: Write Research Summary
+
+Write the output to `.solveos/research/{topic}-research.md` using the Research Summary template:
+
+```markdown
+## Research Summary
+
+**Question:** {the specific question}
+**Time spent:** {actual time}
+
+### Key Findings
+
+- {finding 1}
+- {finding 2}
+- {finding 3}
+
+### Conclusions
+
+- {what this means for the Plan Brief}
+
+### Open Questions / Remaining Unknowns
+
+- {what you still don't know}
+
+### Decision
+
+- [ ] I have enough information to write the Plan Brief
+- [ ] I need more research: {what specifically}
+```
+
+**Filename convention:** Use a descriptive, kebab-case topic name.
+- Good: `dynamodb-vs-postgres-latency-research.md`
+- Bad: `research-1.md`
+
+## Step 5: Update State
+
+Update `.solveos/STATE.md`:
+- If this is the first research: transition to `RESEARCHING`
+- If the user is done researching (decision = "enough to plan"): state stays ready for `/solveos:plan`
+- Update `updated_at` timestamp
+
+If the research gate was previously marked as skipped (user went straight to planning, then came back), remove it from `gates_skipped`.
+
+## Step 6: Suggest Next Step
+
+Present the decision to the user:
+
+If **enough to plan**:
+> "Research complete. Your findings are saved in `.solveos/research/{topic}-research.md`. Ready to plan: run `/solveos:plan`."
+
+If **need more research**:
+> "Research saved. You identified more questions to investigate. Run `/solveos:research` again with the next question."
+
+## Important Rules
+
+- Multiple research sessions produce separate files — never overwrite previous research
+- Research is scoped: one question per session, bounded by time
+- Research informs planning but does not replace it — don't start solving during research
+- If the user's question is really a planning question ("what should we build?"), redirect to `/solveos:plan`

package/commands/solveos/review.md

@@ -0,0 +1,198 @@
+---
+description: Run a pre-ship or post-ship review — holistic judgment before shipping, outcome measurement after
+---
+
+# /solveos:review — Review Gate
+
+You are running the **Review gate** of the solveOS cycle. This gate has two modes:
+
+- **Pre-ship review:** A holistic judgment check before shipping. Asks whether the result actually solves the problem for the stated audience.
+- **Post-ship review:** An outcome measurement after shipping. Measures success criteria against real-world results and generates feed-forward inputs for the next cycle.
+
+The mode is auto-detected based on the current cycle state.
+
+## Prerequisites
+
+1. Check that `.solveos/` exists. If not: "No solveOS project found. Run `/solveos:new` first."
+2. Read `.solveos/STATE.md` to determine the mode:
+   - **Pre-ship mode** if state is: `BUILDING`, `VALIDATING_BUILD`, or `REVIEWING_PRE`
+   - **Post-ship mode** if state is: `SHIPPED` or `REVIEWING_POST`
+   - If state is `INIT` or `PLANNING`: "Nothing to review yet. Run `/solveos:build` first."
+   - If state is `CYCLE_COMPLETE`: "This cycle is already reviewed. Run `/solveos:new-cycle` to start the next one."
+3. Read `.solveos/BRIEF.md` — the Plan Brief is central to both review modes.
+4. Read `.solveos/config.json` to check if the review gate is enabled.
+   - For pre-ship: check `gates.review_pre_ship`
+   - For post-ship: check `gates.review_post_ship`
+   - If disabled: "The {mode} review gate is disabled in your config. You can still run it — do you want to proceed?"
+5. Read any existing validation and build artifacts for context.
+
+---
+
+## Pre-Ship Mode
+
+### Purpose
+
+The pre-ship review is a **judgment check**, not a technical check. Build Validation asks "does it work?" — the pre-ship review asks "should we ship it?"
+
+### Step 1: Review Against the Plan Brief
+
+Invoke the **solveos-reviewer** agent in pre-ship mode. Evaluate:
+
+#### Does the result solve the problem stated in the Plan Brief?
+
+- Re-read the **problem** field from the Plan Brief
+- Does the built result actually address this problem?
+- Or does it address a related but different problem?
+- Has the problem itself changed since planning?
+
+#### Would the named audience find this useful/usable/readable?
+
+- Re-read the **audience** field from the Plan Brief
+- Put yourself in the audience's position
+- Would they understand it? Would they use it? Would they benefit from it?
+- Is the quality level appropriate for this audience?
+
+#### What is the weakest part of the result?
+
+- Every piece of work has a weakest part. Name it explicitly.
+- Is the weakest part in a critical path or a peripheral area?
+- Would the audience notice the weakness?
+
+#### Are you shipping because it's ready, or because you're tired?
+
+- This is the most important question. Be honest.
+- Sunk cost is not a reason to ship.
+- "Good enough" is valid — but only if you can articulate why it's good enough for this audience.
+
+### Step 2: Write Pre-Ship Review
+
+Write the output to `.solveos/validations/pre-ship-review.md` using the Pre-Ship Review template.
+
+### Step 3: Decide and Transition
+
+Present the assessment to the user:
+
+#### If ready to ship:
+
+> "Pre-ship review complete. The result solves the stated problem for the stated audience.
+>
+> Weakest part: {description} — but it's acceptable because {reason}.
+>
+> Run `/solveos:ship` to ship."
+
+Update `STATE.md`:
+- Mark `REVIEW_PRE_SHIP` as a completed gate
+- Transition to `READY_TO_SHIP`
+- Update `updated_at`
+
+#### If not ready:
+
+> "Pre-ship review found concerns:
+> - {concern}
+>
+> I recommend returning to Build to address these before shipping.
+>
+> Options:
+> 1. Run `/solveos:build` to iterate
+> 2. Ship anyway (you understand the risks)
+>
+> What would you like to do?"
+
+Update `STATE.md`:
+- If returning to Build: transition to `BUILDING`
+- If shipping anyway: mark review as completed with accepted concerns
+- Update `updated_at`
+
+---
+
+## Post-Ship Mode
+
+### Purpose
+
+The post-ship review measures **real-world outcomes** against what was planned. It generates feed-forward inputs that inform the next cycle's Plan Brief. This is how solveOS learns.
+
+### When to Run (Timing Guidance)
+
+Present timing guidance based on the domain in `config.json`:
+
+| What shipped | When to review | Why |
+|---|---|---|
+| Software feature | After 1-2 weeks of real usage | Need real user data, not launch-day excitement |
+| Article / content | After 3-7 days live | Engagement patterns stabilize after a few days |
+| Strategy / decision | After first observable outcomes | Could be days or months depending on the decision |
+| Internal tool | After first real use by the team | One real session reveals more than any preview |
+| Quick experiment | Within 24-48 hours | The whole point was to learn fast |
+
+> "This is a post-ship review. When are you running this relative to shipping?
+> (For context: {timing guidance for this domain})"
+
+### Step 1: Measure Success Criteria
+
+For each success criterion from the Plan Brief, measure the real-world result:
+
+| # | Criterion | Result | Evidence |
+|---|-----------|--------|----------|
+| 1 | {criterion} | Met / Partially met / Not met | {what actually happened} |
+
+### Step 2: Reflect
+
+#### What worked well?
+- What decisions or approaches produced good outcomes?
+- What would you repeat?
+
+#### What didn't work?
+- What decisions or approaches produced bad outcomes or unexpected problems?
+- What would you do differently?
+
+#### What single decision had the most impact?
+- Positive or negative — name the one decision that mattered most.
+- Why did it matter? What was the mechanism?
+
+### Step 3: Generate Feed-Forward Inputs
+
+This is the critical output. These items become inputs to the next cycle:
+
+#### New problems revealed
+- What problems did shipping reveal that weren't visible before?
+- Are these new problems, or were they latent problems that surfaced?
+
+#### Deferred scope
+- What was intentionally cut during this cycle that still matters?
+- Should it be the next cycle, or is it no longer important?
+
+#### Wrong assumptions
+- What assumptions from the Plan Brief's **core assumption** turned out to be wrong?
+- What did reality teach you that the plan didn't anticipate?
+
+#### Open questions
+- What questions remain unanswered?
+- Would these benefit from a Research gate in the next cycle?
+
+### Step 4: Write Post-Ship Review
+
+Write the output to `.solveos/reviews/cycle-{n}-review.md` where `{n}` is the current cycle number from `STATE.md`.
+
+Use the Post-Ship Review template.
+
+### Step 5: Transition to Cycle Complete
+
+> "Post-ship review complete. Feed-forward items saved for the next cycle.
+>
+> When you're ready to start the next cycle, run `/solveos:new-cycle` — it will pre-load these feed-forward items into your new Plan Brief.
+>
+> Or if this project is done, no further action needed."
+
+Update `STATE.md`:
+- Mark `REVIEW_POST_SHIP` as a completed gate
+- Transition to `CYCLE_COMPLETE`
+- Update `updated_at`
+
+---
+
+## Important Rules
+
+- **Pre-ship review is judgment, not verification** — Build Validation checks criteria. Pre-ship review checks whether you *should* ship.
+- **Post-ship review requires real data** — don't run it immediately after shipping. Wait for real-world feedback.
+- **Feed-forward items are structured** — they should be specific enough that `/solveos:new-cycle` can load them as starting context.
+- **Reviews persist across cycles** — the `.solveos/reviews/` directory is NOT cleared when a cycle is archived. Reviews are the memory layer.
+- **The "are you tired?" question is real** — sunk cost shipping is the most common failure mode. Call it out honestly.

package/commands/solveos/ship.md

@@ -0,0 +1,129 @@
+---
+description: Ship the current cycle — final check, confirm, archive
+---
+
+# /solveos:ship — Ship Phase
+
+You are entering the **Ship phase** of the solveOS cycle. Shipping means putting your work in front of reality — the only true validator.
+
+## Prerequisites
+
+1. Check that `.solveos/` exists. If not: "No solveOS project found. Run `/solveos:new` first."
+2. Read `.solveos/STATE.md` to verify the current state allows shipping:
+   - Valid entry states: `READY_TO_SHIP`, `BUILDING` (skipping post-build gates), `REVIEWING_PRE` (review passed)
+   - If state is `INIT` or `PLANNING`: "Nothing to ship yet. Run `/solveos:build` first."
+3. Read `.solveos/BRIEF.md` — you need this for the final check.
+4. Read `.solveos/config.json` for domain settings.
+
+## Step 1: Final Brief Check (5 minutes)
+
+Before shipping, do a final alignment check. Present each question to the user:
+
+### Success Criteria Review
+Read the success criteria from `BRIEF.md` and check each one:
+
+```
+## Final Brief Check
+
+Let's verify the build matches the plan:
+
+Success Criteria:
+- [ ] {criterion 1} — Was this met? (yes/no/partially)
+- [ ] {criterion 2} — Was this met? (yes/no/partially)
+...
+```
+
+For each criterion:
+- **Met**: Mark as [x]
+- **Partially met**: Note what's missing. Ask: "Ship with this gap, or fix first?"
+- **Not met**: Flag clearly. Ask: "This criterion isn't met. Ship anyway, defer it, or fix first?"
+
+### Scope Check
+> "Did any out-of-scope work sneak in? Is the output within the boundaries set by the brief?"
+
+### Brief Accuracy Check
+> "Is the brief still accurate, or did it silently drift during the build? If it changed, note the differences."
+
+## Step 2: Define "Shipped"
+
+Based on the domain from `.solveos/config.json`, explain what "shipped" means and how to verify it:
+
+| Domain | What "Shipped" Means | Verification |
+|--------|---------------------|--------------|
+| `software` | Code is deployed or merged to the target branch. It's accessible to the audience named in the brief. | PR merged / deploy confirmed / feature flag enabled |
+| `content` | Content is published and publicly accessible to the target audience. | URL is live / post is published / document is shared |
+| `research` | Findings are shared with stakeholders. Conclusions are documented and accessible. | Report delivered / presentation given / document shared |
+| `strategy` | Decision is communicated to stakeholders. Action plan is in place with owners and timelines. | Decision email sent / meeting held / plan documented with next steps |
+| `general` | The output is delivered to the intended audience in the intended format. | Audience has received and can access the output |
+
+Ask the user:
+> "Based on your domain ({domain}), 'shipped' means: {definition}.
+> Verification: {verification method}.
+> Has this been done, or do you need to do it now?"
+
+## Step 3: Confirm Ship
+
+This is a human decision. Never auto-ship.
+
+> "Ready to ship? This will:
+> 1. Mark this cycle as SHIPPED
+> 2. Archive the Plan Brief and state to `.solveos/history/cycle-{cycle_number}/`
+> 3. Clear the current brief and validations for the next cycle
+>
+> Confirm? (yes/no)"
+
+If the user says no, suggest alternatives:
+- "Run `/solveos:build` to continue working"
+- "Run `/solveos:review` for a pre-ship review"
+- "Run `/solveos:status` to see where things stand"
+
+## Step 4: Capture Learnings
+
+Before archiving, spend 10 minutes capturing learnings. Ask:
+
+> **What worked well in this cycle?**
+> (Process, tools, decisions, approaches that you'd repeat)
+
+> **What didn't work?**
+> (Friction points, wrong assumptions, wasted effort)
+
+> **What would you do differently next time?**
+> (Specific changes to process, planning, or execution)
+
+> **Any feed-forward items for the next cycle?**
+> (Things that should be addressed next but are out of scope now)
+
+Save these learnings as part of the archive.
+
+## Step 5: Archive and Transition
+
+1. Archive the current cycle:
+   - Copy `.solveos/BRIEF.md` to `.solveos/history/cycle-{n}/BRIEF.md`
+   - Copy `.solveos/STATE.md` to `.solveos/history/cycle-{n}/STATE.md`
+   - Copy `.solveos/validations/` to `.solveos/history/cycle-{n}/validations/`
+   - Write learnings to `.solveos/history/cycle-{n}/learnings.md`
+
+2. Clear current cycle artifacts:
+   - Remove `.solveos/BRIEF.md`
+   - Clear `.solveos/validations/` contents
+
+3. Update `.solveos/STATE.md`:
+   - Set `current_state` to `SHIPPED`
+   - Update `updated_at` timestamp
+
+## Step 6: Suggest Next Step
+
+Read `.solveos/config.json` gate configuration:
+
+- If `review_post_ship` gate is enabled:
+  > "Cycle {n} shipped. I recommend a post-ship review to capture what reality teaches you: run `/solveos:review`."
+
+- If `review_post_ship` gate is disabled:
+  > "Cycle {n} shipped. Ready for the next cycle? Run `/solveos:new-cycle` to start fresh with feed-forward from this cycle's learnings."
+
+## Important Rules
+
+- Never auto-ship. The human confirms.
+- Never skip the final brief check, even if the user wants to rush.
+- Always capture learnings — this is how the process improves.
+- Learnings are not a performance review. They're a calibration tool. Be matter-of-fact, not judgmental.

package/commands/solveos/status.md

@@ -0,0 +1,78 @@
+---
+description: Show current cycle status
+---
+
+# /solveos:status — Where Am I?
+
+You are showing the user their current position in the solveOS cycle.
+
+## Prerequisites
+
+1. Check that `.solveos/` exists. If not:
+   > "No solveOS project found. Run `/solveos:new` to start."
+   Stop here.
+
+## What to Read
+
+- `.solveos/STATE.md` — Current state data
+- `.solveos/BRIEF.md` — Problem and goal (if it exists)
+- `.solveos/config.json` — Gate configuration
+
+## Output Format
+
+Present the status in this format:
+
+```
+## solveOS Status
+
+**Cycle:** {cycle_number}
+**Phase:** {human-readable state description}
+**Updated:** {updated_at}
+
+### Brief
+**Problem:** {problem from BRIEF.md, or "No brief yet"}
+**Goal:** {goal from BRIEF.md, or "—"}
+
+### Gates
+| Gate | Status |
+|------|--------|
+| Research | {completed / skipped / pending / disabled} |
+| Plan Validation | {completed / skipped / pending / disabled} (passes: {n}) |
+| Build Validation | {completed / skipped / pending / disabled} |
+| Pre-ship Review | {completed / skipped / pending / disabled} |
+| Post-ship Review | {completed / skipped / pending / disabled} |
+
+### Blockers
+{list of blockers, or "None"}
+
+### Next Step
+{suggestion based on current state}
+```
+
+## State-to-Description Mapping
+
+| State | Description |
+|-------|-------------|
+| `INIT` | Project initialized — ready to start |
+| `RESEARCHING` | Research gate — gathering information |
+| `PLANNING` | Plan phase — creating the Plan Brief |
+| `VALIDATING_PLAN` | Plan Validation gate — checking the brief (pass {n}) |
+| `BUILDING` | Build phase — executing against the plan |
+| `VALIDATING_BUILD` | Build Validation gate — checking the output |
+| `REVIEWING_PRE` | Pre-ship Review — final check before shipping |
+| `READY_TO_SHIP` | Ready to ship — all checks passed |
+| `SHIPPED` | Shipped — work delivered |
+| `REVIEWING_POST` | Post-ship Review — reflecting on the cycle |
+| `CYCLE_COMPLETE` | Cycle complete — ready for next cycle |
+
+## Gate Status Logic
+
+For each gate, determine status by checking:
+1. Is it in `gates_completed`? → "completed"
+2. Is it in `gates_skipped`? → "skipped"
+3. Is it disabled in `config.json` (`gates.{name}: false`)? → "disabled"
+4. Otherwise → "pending"
+
+## Keep It Concise
+
+This is a status check, not a report. Keep the output short and scannable. The user wants to know where they are and what to do next.