solveos-cli 0.1.0

package/commands/solveos/fast.md

@@ -0,0 +1,85 @@
+---
+description: Zero-overhead inline execution — no artifacts, no planning, just do it
+---
+
+# /solveos:fast — Fast Execution (Inline, No Artifacts)
+
+Execute a trivial task immediately with zero process overhead. No Plan Brief, no state tracking, no sub-agents, no validation. Just do the thing.
+
+```
+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
+
+- The task is trivial (< 5 minutes of work)
+- The solution is obvious
+- The cost of being wrong is near zero (easy to undo)
+- Planning overhead exceeds the cost of the task itself
+
+**Examples:** Rename a variable, fix a typo, add a comment, update a dependency version, adjust a config value, format a file, add an import.
+
+**When NOT to use this:**
+- If the task involves multiple steps → use `/solveos:quick`
+- If you're unsure about the approach → use `/solveos:plan`
+- If the change affects other systems or users → use the full workflow
+
+## Execution
+
+### 1. Understand the Request
+
+Read the user's request. If it's clear and actionable, proceed immediately. If ambiguous, ask one clarifying question (no more).
+
+### 2. Execute Immediately
+
+Do the work in the current context:
+- Make the change
+- Verify it works (quick check, not a full validation)
+- For software domain: create a single git commit with a descriptive message
+
+### 3. Confirm Completion
+
+Briefly report what was done:
+
+```
+Done. {One-sentence summary of what changed.}
+```
+
+No build summary, no success criteria checklist, no state transitions.
+
+### 4. Optional Logging
+
+If `.solveos/` exists in the project, append a one-line entry to `.solveos/notes/fast-log.md`:
+
+```markdown
+- {ISO timestamp} — {one-line description of what was done}
+```
+
+This creates a lightweight audit trail without the overhead of full state management.
+
+If `.solveos/` does not exist, do not create it. Fast mode works with zero project setup.
+
+## Constraints
+
+- Do NOT create `.solveos/` directory if it doesn't exist
+- Do NOT create or modify `BRIEF.md` or `STATE.md`
+- Do NOT spawn sub-agents
+- Do NOT ask more than one clarifying question
+- Do NOT expand scope beyond the immediate request
+- If the task turns out to be complex, stop and suggest: "This is more involved than a fast task. Consider running `/solveos:quick` or `/solveos:new` instead."
+
+## Escalation Triggers
+
+If any of these are true, suggest upgrading to a higher-rigor path:
+
+| Trigger | Suggest |
+|---------|---------|
+| Task requires 3+ files to be changed | `/solveos:quick` |
+| Task involves unclear requirements | `/solveos:plan` |
+| Task could break existing functionality | `/solveos:quick` with build validation |
+| Task requires research or investigation | `/solveos:new` with research gate |
+| You find yourself planning in your head | `/solveos:quick` — make the plan explicit |

package/commands/solveos/new-cycle.md

@@ -0,0 +1,165 @@
+---
+description: Start a new cycle informed by the previous post-ship review — carries feed-forward items
+---
+
+# /solveos:new-cycle — Start a New Cycle with Feed-Forward
+
+You are starting a **new cycle** of an existing solveOS project. Unlike `/solveos:new` (which starts from scratch), this command carries forward learnings from the previous cycle's post-ship review.
+
+This is the second feedback loop in action: **Ship -> Review -> Plan -> Build -> Ship**.
+
+## Prerequisites
+
+1. Check that `.solveos/` exists. If not: "No solveOS project found. Run `/solveos:new` first."
+2. Read `.solveos/STATE.md`:
+   - Valid entry states: `CYCLE_COMPLETE` (post-ship review done) or `SHIPPED` (review skipped)
+   - If state is `INIT` through `READY_TO_SHIP`: "The current cycle isn't finished yet. Run `/solveos:ship` first, or `/solveos:new` to start fresh."
+3. Read `.solveos/config.json` for current configuration.
+
+## Step 1: Load Previous Review
+
+Read the most recent post-ship review from `.solveos/reviews/cycle-{n}-review.md` where `{n}` is the current cycle number from `STATE.md`.
+
+### If review exists — extract feed-forward items:
+
+Parse the **Feed-Forward for Next Cycle** section:
+
+- **New problems revealed** — problems that became visible after shipping
+- **Deferred scope** — items cut from the last cycle that may still matter
+- **Wrong assumptions** — assumptions that reality corrected
+- **Open questions** — unknowns that might benefit from research
+
+Present the feed-forward summary to the user:
+
+> "Here's what the post-ship review surfaced for this next cycle:
+>
+> **New problems:**
+> - {problem 1}
+> - {problem 2}
+>
+> **Deferred scope:**
+> - {item 1}
+>
+> **Wrong assumptions:**
+> - {assumption} → {reality}
+>
+> **Open questions:**
+> - {question 1}"
+
+### If no review exists (review was skipped):
+
+> "No post-ship review found for cycle {n}. Starting a new cycle without feed-forward context. You can still run `/solveos:review` on the shipped cycle if you'd like."
+
+## Step 2: Loop Termination Check
+
+Before starting a new cycle, check the three stop conditions:
+
+### Condition 1: Problem is solved
+
+If the post-ship review shows all success criteria were fully met:
+
+> "The post-ship review shows all success criteria were met. The original problem may be solved.
+>
+> Is there still a problem to solve, or is this project done?"
+
+Wait for user response. If done, stop here.
+
+### Condition 2: Problem is no longer worth solving
+
+> "Has the context changed since you started? Is this problem still worth solving?"
+
+If the user indicates the context has changed, stop here.
+
+### Condition 3: Building from habit, not signal
+
+If the feed-forward section is empty or contains no actionable items:
+
+> "The post-ship review didn't surface any new problems, deferred scope, or wrong assumptions. Starting another cycle without a clear reason leads to waste.
+>
+> Do you have a specific problem for the next cycle, or should we stop here?"
+
+Wait for user response. If no clear problem, stop here.
+
+If none of the stop conditions apply, proceed.
+
+## Step 3: Archive Current Cycle
+
+Before resetting state, archive the current cycle's artifacts:
+
+1. Create `.solveos/history/cycle-{n}/` where `{n}` is the current cycle number
+2. Move (not copy) into the archive:
+   - `.solveos/BRIEF.md` → `.solveos/history/cycle-{n}/BRIEF.md`
+   - `.solveos/STATE.md` → `.solveos/history/cycle-{n}/STATE.md`
+   - `.solveos/validations/` → `.solveos/history/cycle-{n}/validations/`
+3. Do **NOT** archive `.solveos/reviews/` — reviews persist across cycles as the memory layer
+4. Do **NOT** archive `.solveos/research/` — research may still be relevant
+5. Do **NOT** archive `.solveos/config.json` — configuration carries forward
+
+## Step 4: Reset State for New Cycle
+
+Write a new `.solveos/STATE.md`:
+
+```json
+{
+  "current_state": "INIT",
+  "cycle_number": {n + 1},
+  "gates_skipped": [],
+  "gates_completed": [],
+  "plan_validation_passes": 0,
+  "blockers": [],
+  "created_at": "{now}",
+  "updated_at": "{now}"
+}
+```
+
+## Step 5: Save Feed-Forward Context
+
+If feed-forward items were extracted from the post-ship review, write them to `.solveos/notes/cycle-{n}-feed-forward.md` so they're available when `/solveos:plan` runs:
+
+```markdown
+## Feed-Forward from Cycle {n}
+
+These items were surfaced during the Cycle {n} post-ship review and should inform Cycle {n+1} planning.
+
+### New Problems
+- {problem}
+
+### Deferred Scope
+- {item}
+
+### Wrong Assumptions
+- {assumption} → {reality}
+
+### Open Questions
+- {question}
+```
+
+## Step 6: Suggest Next Step
+
+Based on the feed-forward items and configuration:
+
+### If there are open questions and research gate is enabled:
+
+> "Cycle {n+1} initialized. The previous review raised open questions — I recommend starting with research.
+>
+> Run `/solveos:research` to investigate, or `/solveos:plan` to start planning directly."
+
+### If there are clear new problems and no open questions:
+
+> "Cycle {n+1} initialized with feed-forward from Cycle {n}. The next problem is clear.
+>
+> Run `/solveos:plan` to create the Plan Brief. The feed-forward items from the previous review will be available as context."
+
+### If starting without feed-forward:
+
+> "Cycle {n+1} initialized. No feed-forward from the previous cycle.
+>
+> Run `/solveos:plan` to start planning, or `/solveos:research` to investigate first."
+
+## Important Rules
+
+- **Always check stop conditions** — don't automatically start cycles. Each cycle should have a clear reason to exist.
+- **Feed-forward items inform planning, they don't dictate it** — the user may choose to ignore some feed-forward items or prioritize differently.
+- **Reviews persist** — the `.solveos/reviews/` directory is never archived. It's the project's memory across cycles.
+- **Research persists** — previous research may still be relevant. Don't archive it.
+- **The human decides** — present feed-forward context and let the user decide what matters for the next cycle.

package/commands/solveos/new.md

@@ -0,0 +1,142 @@
+---
+description: Start a new solveOS project or cycle
+---
+
+# /solveos:new — Initialize a New Project or Cycle
+
+You are initializing a new solveOS project. Follow these steps carefully.
+
+## Step 1: Check for Existing Project
+
+Check if a `.solveos/` directory already exists in the current working directory.
+
+- If it exists, read `.solveos/STATE.md` to check the current cycle state.
+  - If the cycle is **not** in `CYCLE_COMPLETE` or `SHIPPED` state, warn the user:
+    > "There's an active solveOS cycle in state `{current_state}`. Starting a new project will archive the current cycle. Continue?"
+  - Wait for user confirmation before proceeding. If they decline, stop.
+  - If they confirm, archive the current cycle using the existing cycle number, then proceed.
+- If it doesn't exist, proceed directly.
+
+## Step 2: Gather Project Information
+
+Ask the user three questions. Be conversational, not robotic.
+
+### Question 1: The Problem
+> "What problem are you trying to solve? Give me 1-2 sentences — the problem, not the solution."
+
+### Question 2: The Stakes
+> "How high are the stakes? This helps me decide how rigorous to be."
+> - **High** — Failure is costly. I'll enable all gates (research, plan validation, build validation, review).
+> - **Medium** — Standard work. I'll enable plan validation and review.
+> - **Low** — Quick task. I'll use a lighter process with fewer gates.
+
+### Question 3: The Domain
+> "What domain is this work in?"
+> - **Software** — Code, APIs, infrastructure
+> - **Content** — Articles, docs, marketing copy
+> - **Research** — Investigation, analysis, literature review
+> - **Strategy** — Decisions, planning, roadmaps
+> - **General** — Doesn't fit the above
+
+## Step 3: Create the Project
+
+Based on the user's answers:
+
+1. Create the `.solveos/` directory structure:
+   - `.solveos/config.json`
+   - `.solveos/STATE.md`
+   - `.solveos/research/`
+   - `.solveos/validations/`
+   - `.solveos/reviews/`
+   - `.solveos/history/`
+   - `.solveos/notes/`
+
+2. Write `config.json` with these settings:
+
+   **High stakes:**
+   ```json
+   {
+     "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": "fine",
+     "auto_advance": false,
+     "domain": "{user's choice}",
+     "runtime": "auto"
+   }
+   ```
+
+   **Medium stakes:**
+   ```json
+   {
+     "mode": "interactive",
+     "gates": {
+       "research": false,
+       "plan_validation": true,
+       "build_validation": false,
+       "review_pre_ship": true,
+       "review_post_ship": false
+     },
+     "plan_validation_max_passes": 2,
+     "granularity": "standard",
+     "auto_advance": false,
+     "domain": "{user's choice}",
+     "runtime": "auto"
+   }
+   ```
+
+   **Low stakes:**
+   ```json
+   {
+     "mode": "interactive",
+     "gates": {
+       "research": false,
+       "plan_validation": false,
+       "build_validation": false,
+       "review_pre_ship": false,
+       "review_post_ship": false
+     },
+     "plan_validation_max_passes": 1,
+     "granularity": "coarse",
+     "auto_advance": false,
+     "domain": "{user's choice}",
+     "runtime": "auto"
+   }
+   ```
+
+3. Write `STATE.md` with:
+   ```json
+   {
+     "current_state": "INIT",
+     "cycle_number": 1,
+     "gates_skipped": [],
+     "gates_completed": [],
+     "plan_validation_passes": 0,
+     "blockers": [],
+     "created_at": "{now}",
+     "updated_at": "{now}"
+   }
+   ```
+
+## Step 4: Suggest Next Step
+
+Based on the gate configuration:
+
+- If `research` gate is enabled:
+  > "Project initialized. I recommend starting with research: run `/solveos:research` to investigate the problem space before planning."
+
+- If `research` gate is disabled:
+  > "Project initialized. Next step: run `/solveos:plan` to create your Plan Brief."
+
+## Important Rules
+
+- Never skip the user questions. The whole point is that the human decides.
+- If the user gives a vague problem statement, ask them to be more specific before proceeding.
+- Always confirm the configuration before writing files.
+- The `.solveos/` directory should be added to the project's `.gitignore` unless the user wants to version-control their planning artifacts.

package/commands/solveos/next.md

@@ -0,0 +1,86 @@
+---
+description: Suggest or execute the next step in the cycle
+---
+
+# /solveos:next — What Should I Do Next?
+
+You are helping the user navigate to the next step 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
+- `.solveos/config.json` — Gate configuration and `auto_advance` setting
+
+## Logic
+
+### 1. Get Valid Next States
+
+Based on the current state, the valid next states are:
+
+| Current State | Valid Next States |
+|---------------|-------------------|
+| `INIT` | `RESEARCHING`, `PLANNING` |
+| `RESEARCHING` | `PLANNING` |
+| `PLANNING` | `VALIDATING_PLAN`, `BUILDING` |
+| `VALIDATING_PLAN` | `PLANNING` (gaps found), `BUILDING` (passed) |
+| `BUILDING` | `VALIDATING_BUILD`, `REVIEWING_PRE`, `READY_TO_SHIP` |
+| `VALIDATING_BUILD` | `BUILDING` (issues), `PLANNING` (major issues), `REVIEWING_PRE` (passed), `READY_TO_SHIP` |
+| `REVIEWING_PRE` | `BUILDING` (not ready), `READY_TO_SHIP` (ready) |
+| `READY_TO_SHIP` | `SHIPPED` |
+| `SHIPPED` | `REVIEWING_POST`, `CYCLE_COMPLETE` |
+| `REVIEWING_POST` | `CYCLE_COMPLETE` |
+| `CYCLE_COMPLETE` | `INIT` (new cycle) |
+
+### 2. Filter by Gate Configuration
+
+If a gate is disabled in `config.json`, skip past it to the next enabled state:
+
+- If `gates.research` is `false` and current state is `INIT` → recommend `PLANNING` (skip research)
+- If `gates.plan_validation` is `false` and current state is `PLANNING` → recommend `BUILDING` (skip plan validation)
+- If `gates.build_validation` is `false` and current state is `BUILDING` → recommend `REVIEWING_PRE` or `READY_TO_SHIP`
+- If `gates.review_pre_ship` is `false` and current state is `BUILDING` or `VALIDATING_BUILD` → recommend `READY_TO_SHIP`
+- If `gates.review_post_ship` is `false` and current state is `SHIPPED` → recommend `CYCLE_COMPLETE`
+
+### 3. Map to Command
+
+| Recommended State | Command |
+|-------------------|---------|
+| `RESEARCHING` | `/solveos:research` |
+| `PLANNING` | `/solveos:plan` |
+| `VALIDATING_PLAN` | `/solveos:validate-plan` |
+| `BUILDING` | `/solveos:build` |
+| `VALIDATING_BUILD` | `/solveos:validate-build` |
+| `REVIEWING_PRE` | `/solveos:review` |
+| `READY_TO_SHIP` | `/solveos:ship` |
+| `SHIPPED` | `/solveos:ship` |
+| `REVIEWING_POST` | `/solveos:review` |
+| `CYCLE_COMPLETE` | `/solveos:new-cycle` |
+| `INIT` | `/solveos:new-cycle` |
+
+### 4. Present or Execute
+
+Check `auto_advance` in `config.json`:
+
+**If `auto_advance: false` (default):**
+> "You're currently in **{state description}**. Next step: run `{command}` to {brief explanation}."
+
+**If `auto_advance: true`:**
+> "Auto-advancing to **{state description}**..."
+Then execute the recommended command.
+
+## Edge Cases
+
+- If there are multiple valid next states and the gate config doesn't disambiguate, present all options:
+  > "You're in **Build phase**. Next options:
+  > 1. `/solveos:validate-build` — Check your output against success criteria
+  > 2. `/solveos:review` — Pre-ship review
+  > 3. `/solveos:ship` — Ship directly (skips validation and review)"
+
+- If the state is `VALIDATING_PLAN` or `VALIDATING_BUILD`, the "next" depends on the result of the validation (passed or failed). Ask:
+  > "How did the validation go? Passed (continue forward) or needs work (go back)?"

package/commands/solveos/plan.md

@@ -0,0 +1,139 @@
+---
+description: Create a Plan Brief for the current cycle
+---
+
+# /solveos:plan — Create the Plan Brief
+
+You are guiding the user through creating a **Plan Brief** — the central artifact of the solveOS cycle. The Plan Brief is both a thinking tool (it forces clarity) and an instruction set (the AI builds from it).
+
+## Prerequisites
+
+1. Check that `.solveos/` exists. If not, tell the user to run `/solveos:new` first.
+2. Read `.solveos/STATE.md` to verify the current state is `INIT`, `RESEARCHING`, or `PLANNING` (re-entering to refine).
+   - If the state is anything else, warn: "The current cycle is in state `{state}`. Planning should happen before building. Continue anyway?" and respect the user's decision.
+3. Load context:
+   - Read all files in `.solveos/research/` (if any) — these are research summaries from the Research gate.
+   - Read all files in `.solveos/reviews/` (if any) — these contain feed-forward items from previous cycles.
+   - Read `.solveos/BRIEF.md` if it exists (this is a refinement pass, not a fresh start).
+
+## Behavior
+
+Invoke the **solveos-planner** agent behavior as defined in `agents/solveos-planner.md`.
+
+Walk the user through each of the 8 Plan Brief questions, one at a time. For each question:
+
+1. Explain what the question is asking and what a good answer looks like.
+2. If research summaries exist, reference relevant findings.
+3. If previous cycle reviews exist, surface feed-forward items.
+4. If the user's answer is vague or incomplete, challenge it (see Common Mistakes below).
+5. Move to the next question only when the current one has a solid answer.
+
+## The 8 Questions
+
+### 1. Problem
+> "What is broken, missing, or needed?"
+
+- Must be 1-2 sentences
+- Must state the problem, NOT the solution
+- Challenge if the answer embeds a solution (e.g., "We need to add caching" → "That's a solution. What's the problem that makes you want caching?")
+
+### 2. Audience
+> "Who experiences this problem?"
+
+- Must be a specific person, role, or group
+- Challenge "users", "everyone", "the team" → ask "which users specifically?"
+- Good: "Backend engineers on the payments team who deploy 3x/day"
+
+### 3. Goal
+> "What does success look like?"
+
+- Must be one sentence
+- Must start with a verb
+- Must be specific enough that someone else could verify it
+- Challenge vague goals (e.g., "improve performance" → "What metric? What threshold?")
+
+### 4. Appetite
+> "How much time/effort are you willing to invest?"
+
+- This is a **bet**, not an estimate
+- It sets the scope ceiling — if the work takes longer, you re-scope, not extend
+- Challenge "as long as it takes" → "What's the maximum you'd invest before reconsidering the approach?"
+
+### 5. Constraints
+> "What are the non-negotiables?"
+
+- Technical constraints (language, framework, existing systems)
+- Process constraints (approval required, backwards compatibility)
+- Resource constraints (can't use X, must use Y)
+- Output as bullet list
+
+### 6. Success Criteria
+> "How will you know it's done?"
+
+- Each criterion must be **measurable** (a human or test can verify it)
+- Each criterion must be **falsifiable** (you can prove it failed)
+- Output as checkbox list: `- [ ] criterion`
+- Challenge unmeasurable criteria ("works well" → "what does 'well' mean? what's the pass/fail test?")
+- Challenge untestable criteria ("users are happy" → "how would you measure that?")
+
+### 7. Core Assumption
+> "What must be true for this plan to work?"
+
+- Every plan has an underlying bet — name it
+- If this assumption is wrong, the plan may need to change
+- Challenge "it should work" → "What's the riskiest thing you're assuming?"
+
+### 8. Rabbit Holes
+> "What unknowns could drag the build off track?"
+
+- Areas where investigation could spiral without progress
+- Naming them is a defense mechanism — you'll notice when you're in one
+- If the user says "none", push back: "Every problem has unknowns. What's the thing you'd most hate to discover mid-build?"
+
+## After All 8 Questions
+
+### 9. Out of Scope
+> "What are you explicitly NOT solving?"
+
+- Prevents scope creep during build
+- Challenge empty lists: "What related problems will you resist solving this cycle?"
+
+## Plan Phase Exit Checklist
+
+Before writing the final BRIEF.md, verify:
+
+- [ ] Problem is stated without embedding a solution
+- [ ] Audience is specific (not "users" or "everyone")
+- [ ] Goal starts with a verb and is one sentence
+- [ ] Appetite is a bet, not an estimate
+- [ ] Constraints are listed (even if few)
+- [ ] Every success criterion is measurable and falsifiable
+- [ ] Core assumption is explicit and testable
+- [ ] At least one rabbit hole is identified
+- [ ] Out of scope is non-empty
+- [ ] A stranger could read this brief and build from it
+
+If any item fails, point it out and ask the user to revise that section.
+
+## Output
+
+1. Write the completed Plan Brief to `.solveos/BRIEF.md` using the template format from `templates/plan-brief.md`.
+2. Update `.solveos/STATE.md`:
+   - Transition `current_state` to the appropriate next state
+   - Update `updated_at` timestamp
+3. Read `.solveos/config.json` to check gate configuration, then suggest the next step:
+   - If `plan_validation` gate is enabled: "Plan Brief created. I recommend validating it: run `/solveos:validate-plan`."
+   - If `plan_validation` gate is disabled: "Plan Brief created. Ready to build: run `/solveos:build`."
+
+## Common Mistakes to Watch For
+
+| Mistake | What the User Says | What to Ask |
+|---------|-------------------|-------------|
+| Solution masquerading as problem | "We need to add a cache" | "What's the problem that makes you want a cache?" |
+| Vague audience | "Users" or "everyone" | "Which users specifically? What role, team, or segment?" |
+| Unmeasurable goal | "Improve performance" | "What metric? What threshold? How would you verify it?" |
+| Infinite appetite | "As long as it takes" | "What's your maximum investment before reconsidering?" |
+| Missing constraints | "No constraints" | "What about language, framework, existing systems, backwards compatibility?" |
+| Vague success criteria | "It works" | "How would you prove it works? What's the test?" |
+| No rabbit holes | "Can't think of any" | "What's the thing you'd most hate to discover mid-build?" |
+| Empty out of scope | Nothing listed | "What related problems will you resist solving this cycle?" |