theslopmachine 0.4.2 → 0.4.5

package/MANUAL.md

@@ -63,5 +63,5 @@ slopmachine init -o
 
 - theslopmachine depends on OpenCode, beads_rust (`br`), git, python3, and Docker being available.
 - The workflow-owner agents use mandatory skills for specific phases; skipping them is considered a workflow failure.
-- `slopmachine` is the lighter current engine: it keeps the owner prompt smaller, uses more specialized skills, and uses up to three bounded developer sessions instead of one long-lived session.
-- Submission packaging collects the final docs, reports, screenshots, session export, trajectory, and cleaned repo into the required final structure.
+- `slopmachine` is the lighter current engine: it keeps the owner prompt smaller, uses more specialized skills, and keeps one active developer session at a time while preserving rollover history when new sessions are intentionally started.
+- Submission packaging collects the final docs, accepted evaluation reports, screenshots, cleaned session exports, converted session traces, and cleaned repo into the required final structure.

package/README.md

@@ -1,59 +1,32 @@
 # theslopmachine
 
-Installer package for the theslopmachine workflow owner, developer agents, required skills, templates, and local support files.
+`theslopmachine` installs the SlopMachine owner/developer workflow into OpenCode, sets up the required support files on your machine, and bootstraps new project workspaces.
 
-## What This Package Installs
+**Quickstart**
 
-`slopmachine setup` installs the current workflow assets.
+This is the full machine-to-project flow:
 
-That includes:
-
-- owner agents under `~/.config/opencode/agents/`
-- required skills under `~/.agents/skills/`
-- packaged workflow files under `~/slopmachine/`
-- repo templates, evaluation prompts, bootstrap helpers, and session export utilities
-
-The canonical package documents in `~/slopmachine/` are:
-
-- `backend-evaluation-prompt.md`
-- `frontend-evaluation-prompt.md`
-- `document-completeness.md`
-- `engineering-results.md`
-- `implementation-comparison.md`
-- `quality-document.md`
-
-Usage split:
-
-- the two evaluation prompt files are used exactly in evaluation runs
-- the other four files are used in the submission packaging phase
-
-Installed agent set:
-
-- `slopmachine.md`
-- `developer.md`
-
-The current engine is the lighter workflow line:
-
-- smaller always-loaded owner shell
-- smaller developer rulebook
-- richer phase-specific skills loaded when needed
-- bounded 2/3 developer-session model
-- `beads_rust` bootstrap path
+1. install the package
+2. run `slopmachine setup`
+3. add MCP API keys if prompted
+4. log into Codex with OpenCode
+5. initialize a project workspace
+6. enter `repo/`
+7. start OpenCode and choose the `slopmachine` agent
 
 ## Requirements
 
 - Node.js 18+
-- OpenCode installed and usable on the machine
-- `br` (`beads_rust`) will be installed or verified during setup
-- git available in the shell
+- `git`
+- Docker running on the machine
+- `curl` on Unix-like systems for automatic `br` install
 
-## Commands
+`slopmachine setup` can install or verify:
 
-- `slopmachine setup` - configures agents, files, scripts, and beads_rust (`br`)
-- `slopmachine init` - sets up a project
-- `slopmachine init -o` to bootstrap the project and immediately open OpenCode inside `repo/`
+- `opencode`
+- `br` (`beads_rust`)
 
-## Installation
+## 1. Install The Package
 
 From this package directory:
 
@@ -63,43 +36,75 @@ npm run check
 npm pack
 ```
 
-This produces a tarball such as:
+That produces a tarball such as:
 
 ```bash
-theslopmachine-0.4.0.tgz
+theslopmachine-0.4.5.tgz
 ```
 
-You can then install it globally with:
+Install it globally:
 
 ```bash
-npm install -g ./theslopmachine-0.4.0.tgz
+npm install -g ./theslopmachine-0.4.5.tgz
 ```
 
-For local development instead of global install:
+For local package development instead:
 
 ```bash
 npm link
 ```
 
-## Initial Setup
+## 2. Run Setup
 
-Run once per machine or whenever you want to refresh the packaged assets:
+Run this once per machine, or rerun it any time you want to refresh packaged assets:
 
 ```bash
 slopmachine setup
 ```
 
-What setup does:
+`setup` does the following:
+
+- installs or verifies `git`, `python3`, `opencode`, `br`, and Docker availability
+- installs the packaged OpenCode agents into `~/.config/opencode/agents/`
+- installs the packaged skills into `~/.agents/skills/`
+- installs workflow support files into `~/slopmachine/`
+- updates `~/.config/opencode/opencode.json`
+- prompts for missing Context7 and Exa MCP API keys
+
+If `setup` installs `opencode` for the first time, open a fresh terminal before running `opencode` commands.
+
+## 3. Get MCP API Keys
+
+During `slopmachine setup`, you may be prompted for:
+
+- Context7: `https://context7.com`
+- Exa: `https://exa.ai`
+
+You can leave either blank and add it later by editing:
+
+```bash
+~/.config/opencode/opencode.json
+```
+
+If `context7` or `exa` is already configured in `opencode.json`, `setup` leaves the existing entries in place.
+
+## 4. Log Into Codex With OpenCode
+
+Authenticate OpenCode against Codex:
+
+```bash
+opencode auth login -p codex
+```
+
+Optional check:
 
-- installs or refreshes the packaged agents
-- installs or refreshes the packaged skills
-- installs packaged workflow files into `~/slopmachine/`
-- merges required OpenCode plugin/MCP configuration
-- installs or verifies `br` (`beads_rust`)
+```bash
+opencode auth list
+```
 
-## Project Bootstrap
+## 5. Initialize A Project Workspace
 
-Create a new project root:
+Create a new workspace directory and bootstrap it:
 
 ```bash
 mkdir my-project
@@ -107,97 +112,121 @@ cd my-project
 slopmachine init
 ```
 
-This creates the expected structure, including:
+This creates:
 
-- `repo/` as the working codebase directory
-- parent-root workflow files such as `metadata.json`
-- parent-root `docs/` and `sessions/`
-- repo-local `AGENTS.md`
-- initialized `beads_rust` state
-- an initial git checkpoint
+- `repo/` for the actual codebase work
+- parent-level workflow files such as `metadata.json` and `.ai/metadata.json`
+- parent-level `docs/` and `sessions/`
+- `repo/AGENTS.md`
+- initialized `br` state
+- an initial git commit
 
-To bootstrap and open OpenCode directly in `repo/`:
+If you want `init` to open OpenCode automatically in `repo/`, use:
 
 ```bash
 slopmachine init -o
 ```
 
-## Recommended Operation
+## 6. Enter `repo/`
+
+If you used plain `slopmachine init`, move into the working repository:
+
+```bash
+cd repo
+```
+
+## 7. Start OpenCode
 
-After init:
+Start OpenCode inside `repo/`:
 
-1. open OpenCode in `repo/`
-2. choose the `slopmachine` owner agent
-3. let the owner run the lifecycle using the packaged skills
-4. let the owner delegate implementation work to `developer`
+```bash
+opencode
+```
+
+Then select the `slopmachine` agent and begin the workflow.
 
-The expected high-level lifecycle is:
+The normal operating split is:
 
-1. clarification
-2. planning
-3. scaffold
-4. development
-5. integrated verification
-6. hardening
-7. evaluation and triage
-8. final human decision
-9. remediation when needed
-10. submission packaging
+- `slopmachine` is the owner/orchestrator
+- `developer` is the implementation worker
 
-## How It Is Intended To Operate
+## Configured Items
 
-`slopmachine` is designed to keep the owner prompt light while moving the important operational detail into loaded skills.
+These are the main files and directories `setup` configures.
 
-That means:
+### OpenCode Agents
 
-- the owner shell stays small
-- planning, scaffold, development, verification, hardening, remediation, and packaging load detailed skills only when needed
-- early and late phases do not carry each other's full instruction payloads all the time
+- `~/.config/opencode/agents/slopmachine.md`
+- `~/.config/opencode/agents/developer.md`
 
-The v2 workflow also expects:
+### OpenCode Skills
 
-- targeted reads over broad rereads
-- local and narrow verification during ordinary iteration
-- broad selected-stack owner-run gates used sparingly
-- no `.env` files in the repo
-- real integration evidence, not mocked API integration tests
+- `~/.agents/skills/clarification-gate/`
+- `~/.agents/skills/developer-session-lifecycle/`
+- `~/.agents/skills/session-rollover/`
+- `~/.agents/skills/final-evaluation-orchestration/`
+- `~/.agents/skills/beads-operations/`
+- `~/.agents/skills/planning-guidance/`
+- `~/.agents/skills/planning-gate/`
+- `~/.agents/skills/scaffold-guidance/`
+- `~/.agents/skills/development-guidance/`
+- `~/.agents/skills/verification-gates/`
+- `~/.agents/skills/integrated-verification/`
+- `~/.agents/skills/hardening-gate/`
+- `~/.agents/skills/evaluation-triage/`
+- `~/.agents/skills/remediation-guidance/`
+- `~/.agents/skills/submission-packaging/`
+- `~/.agents/skills/retrospective-analysis/`
+- `~/.agents/skills/owner-evidence-discipline/`
+- `~/.agents/skills/report-output-discipline/`
+- `~/.agents/skills/frontend-design/`
 
-Every bootstrapped project should expose:
+### SlopMachine Support Files
 
-- one primary documented runtime command
-- one primary documented broad test command: `./run_tests.sh`
+Installed under `~/slopmachine/`:
 
-Follow the original prompt and the existing repository first. Use the examples below only when they do not already specify the platform or stack.
+- `backend-evaluation-prompt.md`
+- `frontend-evaluation-prompt.md`
+- `document-completeness.md`
+- `quality-document.md`
+- `engineering-results.md`
+- `implementation-comparison.md`
+- `workflow-init.js`
+- `templates/AGENTS.md`
+- `utils/strip_session_parent.py`
+- `utils/convert_ai_session.py`
 
-Examples:
+### OpenCode Config
 
-- web backend/fullstack: `docker compose up --build` and `./run_tests.sh`
-- mobile or desktop when Docker runtime is not the direct run path: `./run_app.sh` and `./run_tests.sh`
+Config file:
 
-## Files And Locations
+```bash
+~/.config/opencode/opencode.json
+```
 
-Main install locations:
+`setup` ensures these entries exist:
 
-- agents: `~/.config/opencode/agents/`
-- skills: `~/.agents/skills/`
-- packaged workflow files: `~/slopmachine/`
+- plugin: `oc-chatgpt-multi-auth`
+- MCP server: `chrome-devtools`
+- MCP server: `context7`
+- MCP server: `exa`
+- MCP server: `shadcn` disabled by default
 
-Inside a bootstrapped project root:
+If you want to customize agents, MCP settings, or plugins, these are the files to edit.
 
-- working codebase: `repo/`
-- external docs: `docs/`
-- session exports: `sessions/`
-- project metadata: `metadata.json`
+## Daily Use
 
-See also:
+After the machine is set up, the common flow is:
 
-- `MANUAL.md` for the short workflow guide
-- `RELEASE.md` for packaging and release checks
+```bash
+cd my-project/repo
+opencode
+```
 
-## Package layout
+Or for a brand new project in one shot:
 
-- `assets/agents/`
-- `assets/skills/`
-- `assets/slopmachine/`
-- `bin/`
-- `src/`
+```bash
+mkdir my-project
+cd my-project
+slopmachine init -o
+```

package/RELEASE.md

@@ -18,13 +18,14 @@ SLOPMACHINE_HOME="$(pwd)/.tmp-home" SLOPMACHINE_NONINTERACTIVE=1 SLOPMACHINE_PLU
 
 ```bash
 mkdir -p .tmp-project
-SLOPMACHINE_HOME="$(pwd)/.tmp-home" node ./bin/slopmachine.js init
+SLOPMACHINE_HOME="$(pwd)/.tmp-home" node ./bin/slopmachine.js init .tmp-project
 ```
 
 4. Test the open-after-bootstrap path:
 
 ```bash
-SLOPMACHINE_HOME="$(pwd)/.tmp-home" node ./bin/slopmachine.js init -o
+mkdir -p .tmp-project-open
+SLOPMACHINE_HOME="$(pwd)/.tmp-home" node ./bin/slopmachine.js init -o .tmp-project-open
 ```
 
 Note:
@@ -41,13 +42,13 @@ npm pack
 This should produce a tarball such as:
 
 ```bash
-theslopmachine-0.4.0.tgz
+theslopmachine-0.4.5.tgz
 ```
 
 ## Inspect package contents
 
 ```bash
-tar -tzf theslopmachine-0.4.0.tgz
+tar -tzf theslopmachine-0.4.5.tgz
 ```
 
 Check that the tarball includes:

package/assets/agents/developer.md

@@ -62,7 +62,12 @@ During ordinary work, prefer:
 - targeted module or route-family tests
 - the selected stack's local UI or E2E tool on affected flows when UI is material
 
-Do not jump to broad Docker and full-suite commands on ordinary turns.
+Owner-only broad gate commands:
+
+- never run `./run_tests.sh`
+- never run `docker compose up --build`
+- treat both commands as owner-run gate commands only, even if they are documented in the repo or look convenient for debugging
+- if your work would normally call for one of those commands, stop at targeted local verification and report that the change is ready for owner-run broad verification
 
 The owner reserves the limited broad gate budget. Your job is to make those owner-run gates likely to pass.
 
@@ -90,4 +95,6 @@ Selected-stack defaults:
 
 - be direct and technically clear
 - report what changed, what was verified, and what still looks weak
+- always name the exact verification commands you ran and the concrete results they produced
+- if you ran no verification command for part of the work, say that explicitly instead of implying broader proof than you have
 - if a problem needs a real fix, fix it instead of explaining around it

package/assets/agents/slopmachine.md

@@ -67,7 +67,7 @@ Agent-integrity rule:
 
 ## Optimization Goal
 
-The main v2 target is:
+The main target is:
 
 - less token waste
 - less elapsed time
@@ -78,6 +78,7 @@ Default to:
 - targeted reads instead of broad rereads
 - targeted execution instead of broad reruns
 - local and narrow verification before expensive gate commands
+- do not rerun expensive commands just to duplicate clear developer-provided evidence
 - file-backed reports with short in-chat summaries when the output would otherwise bloat context
 
 Stay aggressive about cutting waste, but do not weaken the actual standard.
@@ -171,21 +172,34 @@ Phase rules:
 - `P9 Remediation` stays its own root phase once evaluation has accepted follow-up work
 - `P6 Hardening` may reopen `P5` if hardening exposes unresolved integrated instability
 - `P11 Retrospective` runs automatically after successful packaging and is non-blocking unless it finds a real delivery defect
+- post-submission external evaluation feedback may reopen `P9 Remediation`, then rerun `P10 Submission Packaging`, and then rerun `P11 Retrospective`
 
 ## Developer Session Model
 
-Use up to three bounded developer sessions:
+Maintain exactly one active developer session at a time.
 
-1. build session: planning, scaffold, development
-2. stabilization session: integrated verification and hardening, only if needed
-3. remediation session: evaluation-response remediation, only if needed
+Track every developer session in metadata, but create a new one only in these cases:
+
+1. you explicitly request a new session
+2. after successful submission, you return with external evaluation issues that require more fixes
+
+Session classes:
+
+1. `develop`: every developer session created before the first successful submission packaging
+2. `bugfix`: every developer session created after successful submission packaging when the project is reopened for external-evaluation follow-up
+
+There may be multiple `develop` sessions and multiple `bugfix` sessions over the life of one project.
+
+During the first full run from planning through initial submission packaging, keep all work in the `develop` session class, including integrated verification, hardening, evaluation-driven remediation, and packaging follow-through.
+
+If you explicitly request a new session while one is active, ask the current developer exactly `give me a summary of all the work that has been done`, then use that handoff to seed the next session.
 
 Use `developer-session-lifecycle` for startup, resume detection, session consistency checks, and recovery.
-Use `session-rollover` only for planned transitions between those bounded developer sessions.
+Use `session-rollover` only when intentionally starting a new developer session because of an explicit user request or post-submission external-feedback reopen.
 
 Do not launch the developer during `P0` or `P1`.
 
-When the first build developer session begins in `P2`, start it in this exact order:
+When the first develop developer session begins in `P2`, start it in this exact order:
 
 1. send `lets plan this <original-prompt>`
 2. wait for the developer's first reply
@@ -199,6 +213,14 @@ Do not merge those messages.
 
 Broad project-standard gate commands are expensive and must stay rare.
 
+Owner-side discipline:
+
+- do not run `./run_tests.sh` casually
+- do not run `docker compose up --build` casually
+- do not rerun expensive local test or E2E commands just because the developer already ran them
+- when the developer reports the exact verification command and its result clearly, use that evidence unless there is a concrete reason to challenge it
+- rerun expensive verification only when the developer evidence is weak, contradictory, flaky, high-risk, needed for a true broad gate, or needed to answer a new question
+
 Target budget for the whole workflow:
 
 - at most 3 broad owner-run verification moments using the selected stack's full verification path
@@ -273,7 +295,7 @@ Core map:
 - `P11` -> `retrospective-analysis`, `owner-evidence-discipline`, `report-output-discipline`
 - state mutations -> `beads-operations`
 - evidence-heavy review -> `owner-evidence-discipline`
-- planned developer-session switch -> `session-rollover`
+- intentional new developer session -> `session-rollover`
 
 Do not improvise a phase from memory when a phase skill exists.
 
@@ -285,6 +307,7 @@ When talking to the developer:
 - lead with the engineering point, not process framing
 - keep prompts natural, sharp, and compact unless the moment really needs more context
 - translate workflow intent into normal software-project language
+- for each development slice or bugfix request, require the reply to state the exact verification commands that were run and the concrete results they produced
 
 Do not leak workflow internals such as:
 
@@ -345,6 +368,7 @@ Treat packaging as a first-class delivery contract from the start, not as late c
 - the two evaluation prompt files are used exactly during evaluation runs
 - the four non-evaluation package documents are used during submission packaging to generate the required submission outputs
 - exact packaging file outputs and final paragraph outputs are mandatory in `P10`
+- accepted evaluation reports and cleaned original session exports are mandatory submission artifacts in `P10`
 - do not leave packaging structure, screenshots, self-test outputs, or exports to be improvised at the end
 
 When `P10 Submission Packaging` begins:
@@ -359,7 +383,7 @@ After `P10 Submission Packaging` closes successfully:
 
 - automatically enter `P11 Retrospective`
 - load `retrospective-analysis`
-- write dated retrospective output under `~/slopmachine/retrospectives/`
+- write `run_id`-scoped retrospective output under `~/slopmachine/retrospectives/`
 - keep it owner-only and non-blocking by default
 - reopen packaging only if the retrospective finds a real packaged-result defect
 

package/assets/skills/beads-operations/SKILL.md

@@ -24,7 +24,7 @@ When a root phase changes:
 - do not close multiple root phases in one transition block
 - keep structured comments specific and auditable
 - treat phase-closure failures as real workflow failures to resolve
-- keep Beads and metadata aligned on current phase and active developer session slot when either changes
+- keep Beads and metadata aligned on current phase and active developer session record when either changes
 
 ## Structured comment prefixes
 

package/assets/skills/clarification-gate/SKILL.md

@@ -28,7 +28,7 @@ Use this skill only during `P1 Clarification`.
 - decompose the prompt thoroughly into explicit requirements, implied requirements, user flows, constraints, boundaries, risks, quality expectations, and verification expectations
 - identify and lock safe default decisions that are consistent with the prompt and improve execution quality without changing intent
 - when more than one safe default is available, prefer the one that preserves or slightly over-covers the full prompt scope rather than the one that narrows scope for implementation convenience
-- record meaningful ambiguities, locked safe defaults, and decision rationale in the working questions record that will later become `../docs/questions.md`
+- record meaningful ambiguities, locked safe defaults, and decision rationale directly in mandatory parent-root `../docs/questions.md`
 - prepare a developer-facing clarification prompt in `../.ai/clarification-prompt.md`
 - keep clarification aligned with the original prompt
 - do not let clarification reduce, weaken, narrow, or silently reinterpret the prompt
@@ -50,7 +50,7 @@ Use this skill only during `P1 Clarification`.
 
 ## Required outputs
 
-- working clarification record that will become `../docs/questions.md`
+- parent-root `../docs/questions.md`
 - developer-facing clarification prompt in `../.ai/clarification-prompt.md`
 - explicit list of safe defaults and resolved ambiguities
 
@@ -94,7 +94,7 @@ Preferred entry shape:
 <brief justification tied to prompt faithfulness>
 ```
 
-If nothing material was unclear, keep `questions.md` minimal rather than inventing content.
+If nothing material was unclear, still create `questions.md` and keep it minimal rather than inventing content.
 
 ## Clarification-prompt validation loop
 
@@ -119,5 +119,6 @@ If nothing material was unclear, keep `questions.md` minimal rather than inventi
 - the owner is confident the scope is understood clearly enough to enter planning
 - the clarification prompt is strong enough for the developer to start from the right understanding
 - material ambiguities are resolved or safely locked and documented
+- `../docs/questions.md` exists and reflects the accepted clarification record
 - prompt drift has been checked and rejected
 - human approval exists