theslopmachine 0.4.6 → 0.4.8

package/MANUAL.md

@@ -23,7 +23,7 @@ The installed agent set includes the current `slopmachine` and `developer` agent
 
 ## Start a project
 
-Inside the project root, run:
+Inside a new or empty project directory, run:
 
 ```bash
 slopmachine init
@@ -43,25 +43,26 @@ slopmachine init -o
 - bootstraps beads_rust (`br`)
 - creates `repo/`
 - copies the packaged repo rulebook into `repo/AGENTS.md`
-- creates the initial git checkpoint
+- creates the initial git commit so the workspace starts with a clean tree
 - optionally opens `opencode` in `repo/`
 
 ## Rough workflow
 
-1. Clarification
-2. Planning
-3. Scaffold/foundation
-4. Development
-5. Integrated verification
-6. Hardening
-7. Evaluation and triage
-8. Final human decision
-9. Remediation when needed
+1. Intake and setup
+2. Clarification
+3. Planning
+4. Scaffold/foundation
+5. Development
+6. Integrated verification
+7. Hardening
+8. Evaluation and fix verification
+9. Final human decision
 10. Submission packaging
+11. Retrospective
 
 ## Important notes
 
 - 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 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.
+- Submission packaging collects the final docs, accepted evaluation reports, cleaned session exports, converted session traces, and the cleaned repo into the required final structure.

package/README.md

@@ -1,62 +1,46 @@
 # theslopmachine
 
-`theslopmachine` installs the SlopMachine owner/developer workflow into OpenCode, sets up the required support files on your machine, and bootstraps new project workspaces.
+`theslopmachine` is an installer and bootstrap CLI for the SlopMachine OpenCode workflow. It installs the packaged owner/developer agents, required skills, workflow support files, and project bootstrap logic needed to start a new SlopMachine-managed repository.
 
-**Quickstart**
+## Features
 
-This is the full machine-to-project flow:
+- installs packaged OpenCode agents into `~/.config/opencode/agents/`
+- installs packaged skills into `~/.agents/skills/`
+- installs packaged workflow support files into `~/slopmachine/`
+- bootstraps a new project workspace with `repo/`, `docs/`, `sessions/`, `metadata.json`, `AGENTS.md`, and initialized `br` state
+- configures required OpenCode plugins and MCP entries without overwriting existing `context7` or `exa` configuration
 
-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
+## Installation
 
-## Requirements
+Requirements:
 
 - Node.js 18+
 - `git`
 - Docker running on the machine
-- `curl` on Unix-like systems for automatic `br` install
+- `curl` on Unix-like systems for automatic `br` installation
 
-`slopmachine setup` can install or verify:
-
-- `opencode`
-- `br` (`beads_rust`)
-
-## 1. Install The Package
-
-From this package directory:
+Build and install the package:
 
 ```bash
 npm install
 npm run check
 npm pack
+npm install -g ./theslopmachine-<version>.tgz
 ```
 
-That produces a tarball such as:
-
-```bash
-theslopmachine-0.4.5.tgz
-```
-
-Install it globally:
-
-```bash
-npm install -g ./theslopmachine-0.4.5.tgz
-```
+`package.json` is the package-version source of truth. The packed tarball name and CLI version banner both derive from that version.
 
-For local package development instead:
+For local package development instead of global install:
 
 ```bash
 npm link
 ```
 
-## 2. Run Setup
+The published package is intentionally source-only. It packages only `bin/`, `src/`, `assets/`, `README.md`, `RELEASE.md`, and `MANUAL.md`.
 
-Run this once per machine, or rerun it any time you want to refresh packaged assets:
+## Setup
+
+Run machine setup:
 
 ```bash
 slopmachine setup
@@ -64,47 +48,36 @@ slopmachine setup
 
 `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/`
+- installs or verifies `opencode`
+- installs or verifies `br` (`beads_rust`)
+- installs or refreshes packaged agents
+- installs or refreshes packaged skills
+- installs or refreshes packaged workflow 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.
+- prompts for missing MCP API keys when needed
 
-## 3. Get MCP API Keys
+If `opencode` was newly installed, open a fresh terminal before running OpenCode commands.
 
-During `slopmachine setup`, you may be prompted for:
+MCP API keys:
 
 - 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:
+Codex login with OpenCode:
 
 ```bash
 opencode auth login -p codex
 ```
 
-Optional check:
+Optional verification:
 
 ```bash
 opencode auth list
 ```
 
-## 5. Initialize A Project Workspace
+## Startup
 
-Create a new workspace directory and bootstrap it:
+Create and initialize a new project workspace in a new or empty directory:
 
 ```bash
 mkdir my-project
@@ -112,58 +85,110 @@ cd my-project
 slopmachine init
 ```
 
-This creates:
-
-- `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
-
-If you want `init` to open OpenCode automatically in `repo/`, use:
+Or initialize and open OpenCode immediately:
 
 ```bash
+mkdir my-project
+cd my-project
 slopmachine init -o
 ```
 
-## 6. Enter `repo/`
-
-If you used plain `slopmachine init`, move into the working repository:
+If you used plain `slopmachine init`, then continue with:
 
 ```bash
 cd repo
+opencode
 ```
 
-## 7. Start OpenCode
+Inside OpenCode, select the `slopmachine` agent to start the workflow.
 
-Start OpenCode inside `repo/`:
+Bootstrapped workspace layout:
+
+- `repo/` for the working codebase
+- `docs/` for workflow documentation and evidence
+- `sessions/` for exported session artifacts
+- `metadata.json` for project workflow metadata
+- `repo/AGENTS.md` for the repo-local agent instructions
+
+`slopmachine init` creates the initial git commit so the workspace starts from a clean tree.
+
+## Testing
+
+Package-level checks:
 
 ```bash
-opencode
+npm run check
+npm pack --dry-run
 ```
 
-Then select the `slopmachine` agent and begin the workflow.
+Generated project conventions:
+
+- every bootstrapped project must expose one primary runtime command
+- every bootstrapped project must expose one primary broad test command: `./run_tests.sh`
+- for Dockerized web backend or fullstack projects, the expected broad runtime command is `docker compose up --build`
+- for non-Docker runtime cases, the expected broad runtime command is usually `./run_app.sh`
+
+Verification policy:
 
-The normal operating split is:
+- use local fast verification during normal development
+- treat `./run_tests.sh` as a broad gate, not an ordinary every-step verification command
+- for Dockerized web backend and fullstack projects, scaffold acceptance should establish both `docker compose up --build` and `./run_tests.sh`
 
-- `slopmachine` is the owner/orchestrator
+## Architecture
+
+Operating model:
+
+- `slopmachine` is the owner and orchestrator
 - `developer` is the implementation worker
+- detailed workflow behavior is primarily carried by loaded skills rather than one monolithic owner prompt
+
+High-level lifecycle:
+
+1. `P0 Intake and Setup`
+2. `P1 Clarification`
+3. `P2 Planning`
+4. `P3 Scaffold`
+5. `P4 Development`
+6. `P5 Integrated Verification`
+7. `P6 Hardening`
+8. `P7 Evaluation and Fix Verification`
+9. `P8 Final Human Decision`
+10. `P9 Submission Packaging`
+11. `P10 Retrospective`
+
+Design constraints:
+
+- keep the owner shell small and load phase-specific skills when needed
+- prefer targeted reads and focused local verification during implementation
+- keep environment-specific state out of the package
+- do not package local runtime artifacts, caches, editor folders, or generated dependency environments
+
+Database dependency rule:
+
+- database dependencies must be provisioned by initialization scripts, migrations, container startup hooks, or equivalent runtime setup
+- do not hardcode database-specific environment state into packaged assets
+- do not ship database files such as `.db`, `.sqlite`, dumps, or seeded local database artifacts in the package
 
-## Configured Items
+For this package specifically, the installer ships workflow logic and templates only. It does not ship database dependency files or packaged database state.
 
-These are the main files and directories `setup` configures.
+## Installed Configuration
 
-### OpenCode Agents
+Main locations:
+
+- agents: `~/.config/opencode/agents/`
+- skills: `~/.agents/skills/`
+- OpenCode config: `~/.config/opencode/opencode.json`
+- packaged workflow files: `~/slopmachine/`
+
+Installed agents:
 
 - `~/.config/opencode/agents/slopmachine.md`
 - `~/.config/opencode/agents/developer.md`
 
-### OpenCode Skills
+Installed skills:
 
 - `~/.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/`
@@ -174,37 +199,23 @@ These are the main files and directories `setup` configures.
 - `~/.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/`
 
-### SlopMachine Support Files
-
-Installed under `~/slopmachine/`:
+Installed workflow files under `~/slopmachine/`:
 
 - `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`
+- `workflow-init.js`
 - `utils/strip_session_parent.py`
 - `utils/convert_ai_session.py`
+- `utils/cleanup_delivery_artifacts.py`
 
-### OpenCode Config
-
-Config file:
-
-```bash
-~/.config/opencode/opencode.json
-```
-
-`setup` ensures these entries exist:
+OpenCode config entries ensured by `setup`:
 
 - plugin: `oc-chatgpt-multi-auth`
 - MCP server: `chrome-devtools`
@@ -212,21 +223,4 @@ Config file:
 - MCP server: `exa`
 - MCP server: `shadcn` disabled by default
 
-If you want to customize agents, MCP settings, or plugins, these are the files to edit.
-
-## Daily Use
-
-After the machine is set up, the common flow is:
-
-```bash
-cd my-project/repo
-opencode
-```
-
-Or for a brand new project in one shot:
-
-```bash
-mkdir my-project
-cd my-project
-slopmachine init -o
-```
+These are the user-editable locations if you want to customize agents, skills, plugins, or MCP configuration after setup.

package/RELEASE.md

@@ -39,16 +39,18 @@ Note:
 npm pack
 ```
 
-This should produce a tarball such as:
+This should produce a tarball named like:
 
 ```bash
-theslopmachine-0.4.5.tgz
+theslopmachine-<version>.tgz
 ```
 
+`<version>` comes from `package.json`, which is the single package-version source of truth.
+
 ## Inspect package contents
 
 ```bash
-tar -tzf theslopmachine-0.4.5.tgz
+tar -tzf theslopmachine-<version>.tgz
 ```
 
 Check that the tarball includes:
@@ -87,6 +89,7 @@ npm publish --dry-run
 
 ## Versioning
 
+- `package.json` is the single package-version source of truth for the tarball name and CLI version banner
 - bump `package.json` version before each release
 - keep the CLI command as `slopmachine`
 - keep the npm package name as `theslopmachine`

package/assets/agents/developer.md

@@ -49,7 +49,9 @@ Do not narrow scope for convenience.
 - implement real behavior, not placeholders
 - keep user-facing and admin-facing flows complete through their real surfaces
 - verify the changed area locally and realistically before reporting completion
-- update repo-local docs such as `README.md` when behavior or run/test instructions change
+- update repo-local docs such as `README.md` and `./docs/*` when behavior or run/test instructions change
+- keep repo-local docs and code structure statically reviewable; do not rely on runtime success alone to make the project understandable
+- keep the repo self-sufficient; do not make it depend on parent-directory docs or sibling artifacts for startup, build/preview, configuration, verification, or basic understanding
 - do not touch workflow or rulebook files such as `AGENTS.md` unless explicitly asked
 
 ## Verification Cadence
@@ -85,6 +87,15 @@ Selected-stack defaults:
 - do not ship placeholder, demo, setup, or debug UI in product-facing screens
 - do not create `.env` files or similar env-file variants
 - do not hardcode secrets or leave prototype residue behind
+- when the project has database dependencies, keep database setup in `./init_db.sh` rather than scattered repo logic
+- do not hardcode database connection values or database bootstrap values anywhere in the repo
+- if the project uses mock, stub, fake, or local-data behavior, disclose that scope accurately in the repo-local documentation instead of implying real backend or production behavior
+- if mock or interception behavior is enabled by default, document that clearly
+- disclose feature flags, debug/demo surfaces, and default enabled states clearly in repo-local docs when they exist
+- keep frontend state requirements explicit in code and repo-local docs for prompt-critical flows
+- use a shared logging path and avoid random print-style debugging as the durable implementation pattern
+- use a shared validation/error-handling path when validation materially affects the flow
+- do not hide missing failure handling behind fake-success paths
 
 ## Skills