theslopmachine 0.4.9 → 0.5.1

package/README.md

@@ -1,234 +1,265 @@
 # theslopmachine
 
-`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.
+`theslopmachine` installs and bootstraps the SlopMachine workflow for OpenCode.
 
-## Features
+It configures:
 
-- 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
-
-## Installation
+- the `slopmachine` owner agent
+- the `slopmachine-claude` owner agent
+- the `developer` implementation agent
+- required skills under `~/.agents/skills/`
+- Claude worker runtime assets under `~/.claude/`
+- workflow support files under `~/slopmachine/`
+- OpenCode MCP entries for `context7` and `exa`
 
-Requirements:
+## Requirements
 
 - Node.js 18+
 - `git`
-- Docker running on the machine
-- `curl` on Unix-like systems for automatic `br` installation
+- Docker
+- `python3`
+- `opencode`
+- `br` (`beads_rust`)
+
+`slopmachine setup` verifies or installs what it can.
+
+## Install
 
-Build and install the package:
+From this package directory:
 
 ```bash
 npm install
 npm run check
 npm pack
-npm install -g ./theslopmachine-<version>.tgz
+npm install -g ./theslopmachine-0.5.0.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 of global install:
+For local development instead:
 
 ```bash
 npm link
 ```
 
-The published package is intentionally source-only. It packages only `bin/`, `src/`, `assets/`, `README.md`, `RELEASE.md`, and `MANUAL.md`.
+## Commands
 
-## Setup
+### `slopmachine setup`
 
-Run machine setup:
+Use this once per machine, then rerun any time you want to refresh packaged assets.
 
 ```bash
 slopmachine setup
 ```
 
-`setup` does the following:
+What it does:
 
-- installs `opencode-ai@latest` when missing and refreshes it to `@latest` when already present
-- installs or verifies `br` (`beads_rust`)
-- installs or refreshes packaged agents
-- installs or refreshes packaged skills
-- installs or refreshes packaged workflow files into `~/slopmachine/`
+- verifies or installs `opencode`
+- verifies `br`, `git`, `python3`, and Docker
+- installs packaged agents into `~/.config/opencode/agents/`
+- installs packaged skills into `~/.agents/skills/`
+- installs Claude runtime assets into `~/.claude/`
+- installs workflow files into `~/slopmachine/`
 - updates `~/.config/opencode/opencode.json`
-- prompts for missing MCP API keys when needed
+- ensures packaged MCP entries for `context7` and `exa`
+- optionally asks for an upload token if one is not already stored
+
+Notes:
+
+- existing upload token is preserved and setup skips that prompt when one already exists
+- existing `context7` and `exa` entries are preserved if already configured
+- package-managed assets are refreshed on rerun
+
+### `slopmachine init`
+
+Use this in a new or empty project directory to create a SlopMachine workspace.
+
+```bash
+mkdir my-project
+cd my-project
+slopmachine init
+```
 
-To refresh an existing machine install to the latest published package in one step:
+Or open OpenCode immediately after bootstrap:
 
 ```bash
-slopmachine upgrade
+slopmachine init -o
 ```
 
-`slopmachine upgrade` installs `theslopmachine@latest` globally and then runs `slopmachine setup` automatically.
+What it creates:
+
+- `repo/`
+- `docs/`
+- `sessions/`
+- `metadata.json`
+- `.ai/metadata.json`
+- root `.beads/`
+- `repo/AGENTS.md`
 
-If `opencode` was newly installed, open a fresh terminal before running OpenCode commands.
+Important details:
 
-MCP API keys:
+- `run_id` is created in `.ai/metadata.json`
+- the workspace root is the parent directory containing `repo/`
+- Beads lives in the workspace root, not inside `repo/`
 
-- Context7: `https://context7.com`
-- Exa: `https://exa.ai`
+### `slopmachine set-token`
 
-Codex login with OpenCode:
+Stores the upload token used by `send-data`.
 
 ```bash
-opencode auth login -p codex
+slopmachine set-token
 ```
 
-Optional verification:
+Behavior:
 
-```bash
-opencode auth list
-```
+- prompts for the plaintext upload token
+- stores it in `~/.config/slopmachine/config.json`
+- replaces an existing token if one is already stored
+- does not validate the token over the network during entry
 
-## Startup
+### `slopmachine send-data <owner-session-id>`
 
-Create and initialize a new project workspace in a new or empty directory:
+Exports workflow artifacts and uploads them to the configured Supabase endpoint.
 
 ```bash
-mkdir my-project
-cd my-project
-slopmachine init
+slopmachine send-data <owner-session-id>
 ```
 
-Or initialize and open OpenCode immediately:
+Supported options:
 
-```bash
-mkdir my-project
-cd my-project
-slopmachine init -o
-```
+- `--dry-run`
+- `--yes`
+- `--label <text>`
+- `--project-id <id>`
+- `--output <path>`
+- `--endpoint <url>`
 
-If you used plain `slopmachine init`, then continue with:
+Examples:
 
 ```bash
-cd repo
-opencode
+slopmachine send-data ses_abc123
+slopmachine send-data ses_abc123 --dry-run
+slopmachine send-data ses_abc123 --yes --label sprint-12
+slopmachine send-data ses_abc123 --endpoint "https://<project-ref>.supabase.co/functions/v1/slopmachine-upload"
 ```
 
-Inside OpenCode, select the `slopmachine` agent to start the workflow.
+Where to run it:
 
-Bootstrapped workspace layout:
+- preferred: workspace root
+- also supported: `repo/`
 
-- `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
+If run from `repo/`, the command resolves the parent workspace root automatically.
 
-`slopmachine init` creates the initial git commit so the workspace starts from a clean tree.
+What it exports live:
 
-## Testing
+- owner session from the positional `owner-session-id`
+- developer sessions from `.ai/metadata.json`
+- `beads-export.json` from root `.beads/`
 
-Package-level checks:
+What it includes when present:
 
-```bash
-npm run check
-npm pack --dry-run
-```
-
-Generated project conventions:
+- `self-test-run.md`
+- `self-test-fixes.md`
+- `retrospective-<run_id>.md`
+- `improvement-actions-<run_id>.md`
+- `metadata.json`
+- `ai-metadata.json`
+- `manifest.json`
 
-- 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`
+Fail-fast conditions:
 
-Verification policy:
+- missing owner session id argument
+- missing `.ai/metadata.json`
+- missing `run_id`
+- missing tracked developer session ids
+- owner session export failure
+- developer session export failure
 
-- 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`
+Warn-only conditions:
 
-## Architecture
+- missing `self-test-run.md`
+- missing `self-test-fixes.md`
+- missing retrospective files
 
-Operating model:
+Output behavior:
 
-- `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
+- creates a flat zip archive
+- keeps the local zip by default
+- default zip path:
+  - `~/slopmachine/retrospectives/send-data-<run_id>.zip`
+- shows a preview before upload unless `--yes` is passed
 
-High-level lifecycle:
+## Config Files
 
-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`
+Machine-level config:
 
-Design constraints:
+- `~/.config/slopmachine/config.json`
 
-- 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
+Current schema:
 
-Database dependency rule:
+```json
+{
+  "upload": {
+    "endpoint": "https://<project-ref>.supabase.co/functions/v1/slopmachine-upload",
+    "token": "sm_u_...",
+    "timeoutMs": 30000
+  }
+}
+```
 
-- 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
+OpenCode config managed by setup:
 
-For this package specifically, the installer ships workflow logic and templates only. It does not ship database dependency files or packaged database state.
+- `~/.config/opencode/opencode.json`
 
-## Installed Configuration
+Packaged MCPs managed by setup:
 
-Main locations:
+- `context7`
+- `exa`
 
-- agents: `~/.config/opencode/agents/`
-- skills: `~/.agents/skills/`
-- OpenCode config: `~/.config/opencode/opencode.json`
-- packaged workflow files: `~/slopmachine/`
+## Installed Assets
 
-Installed agents:
+Agents:
 
 - `~/.config/opencode/agents/slopmachine.md`
+- `~/.config/opencode/agents/slopmachine-claude.md`
 - `~/.config/opencode/agents/developer.md`
 
-Installed skills:
-
-- `~/.agents/skills/clarification-gate/`
-- `~/.agents/skills/developer-session-lifecycle/`
-- `~/.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/submission-packaging/`
-- `~/.agents/skills/retrospective-analysis/`
-- `~/.agents/skills/owner-evidence-discipline/`
-- `~/.agents/skills/report-output-discipline/`
-- `~/.agents/skills/frontend-design/`
-
-Installed workflow files under `~/slopmachine/`:
-
-- `backend-evaluation-prompt.md`
-- `frontend-evaluation-prompt.md`
-- `templates/AGENTS.md`
-- `workflow-init.js`
-- `utils/strip_session_parent.py`
-- `utils/convert_ai_session.py`
-- `utils/cleanup_delivery_artifacts.py`
-
-OpenCode config entries ensured by `setup`:
-
-- plugin: `oc-chatgpt-multi-auth`
-- MCP server: `chrome-devtools`
-- MCP server: `context7`
-- MCP server: `exa`
-- MCP server: `shadcn` disabled by default
-
-These are the user-editable locations if you want to customize agents, skills, plugins, or MCP configuration after setup.
+Skills:
+
+- installed under `~/.agents/skills/`
+
+Claude runtime assets:
+
+- `~/.claude/agents/developer.md`
+- `~/.claude/skills/frontend-design/`
+
+Workflow files:
+
+- installed under `~/slopmachine/`
+
+## Verification
+
+Package-level check:
+
+```bash
+npm run check
+```
+
+Basic machine verification:
+
+```bash
+slopmachine --help
+slopmachine set-token
+slopmachine setup
+```
+
+`send-data` verification:
+
+```bash
+slopmachine send-data <owner-session-id> --dry-run --endpoint "https://<project-ref>.supabase.co/functions/v1/slopmachine-upload"
+```
+
+## Notes
+
+- the upload token is machine-level state and is not stored in the repo
+- the owner session id is currently supplied manually to `send-data`
+- developer session ids come from `.ai/metadata.json`
+- broad workflow files and session exports live at workspace root, not inside `repo/`

package/RELEASE.md

@@ -74,8 +74,11 @@ Check that the tarball includes:
 And specifically verify that the tarball includes the current workflow assets:
 
 - `assets/agents/slopmachine.md`
+- `assets/agents/slopmachine-claude.md`
 - `assets/agents/developer.md`
+- `assets/claude/agents/developer.md`
 - `assets/skills/clarification-gate/`
+- `assets/skills/claude-worker-management/`
 - `assets/skills/planning-guidance/`
 - `assets/skills/submission-packaging/`
 - `assets/slopmachine/templates/AGENTS.md`

package/assets/agents/developer.md

@@ -32,6 +32,7 @@ Read and follow `AGENTS.md` before implementing.
 - do real verification, not confidence theater
 - keep moving until the assigned work is materially complete or concretely blocked
 - do not stop for unnecessary intermediate check-ins
+- use independent engineering judgment; do not behave like a passive worker waiting to be corrected later
 
 ## Requirements And Planning
 
@@ -41,18 +42,28 @@ Before coding:
 - surface meaningful ambiguity instead of silently guessing
 - make the plan concrete enough to drive real implementation
 - keep frontend/backend surfaces aligned when both sides matter
+- check prompt-fit before reporting completion; if the requested result still has visible gaps, keep working or call them out explicitly
 
 Do not narrow scope for convenience.
 
+Do not introduce convenience-based simplifications, `v1` reductions, future-phase deferrals, actor/model reductions, or workflow omissions unless one of these is true:
+
+- the original prompt explicitly allows it
+- the approved clarification explicitly allows it
+- the owner explicitly instructs it in the current session
+
+If a simplification would make implementation easier but is not explicitly authorized, keep the full prompt scope and plan the real complexity instead.
+
 ## Execution Model
 
 - 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` 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 `README.md` as the only documentation file inside the repo unless the user explicitly asks for something else
+- keep the repo self-sufficient and statically reviewable through code plus `README.md`; 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
+- if the work changes acceptance-critical docs or contracts, review those docs yourself before replying instead of assuming the owner will catch inconsistencies later
 
 ## Verification Cadence
 
@@ -89,14 +100,42 @@ Selected-stack defaults:
 - 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
+- for Dockerized web projects, do not require manual `export ...` steps for `docker compose up --build`
+- for Dockerized web projects, prefer an automatically invoked dev-only runtime bootstrap script instead of checked-in `.env` files or hardcoded runtime values
+- if the project uses mock, stub, fake, or local-data behavior, disclose that scope accurately in `README.md` 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
+- disclose feature flags, debug/demo surfaces, and default enabled states clearly in `README.md` when they exist
+- keep frontend state requirements explicit in code and `README.md` for prompt-critical flows when they materially affect usage
 - 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
 
+## Completion Preflight
+
+Before reporting a planning package, scaffold, implementation slice, or fix round as ready, run this preflight yourself:
+
+- prompt-fit: does the result still satisfy the original request without silent narrowing?
+- no convenience narrowing: did you avoid inventing unauthorized `v1` reductions, role simplifications, deferred workflows, or reduced enforcement models?
+- consistency: do code, docs, route contracts, security notes, and runtime/test commands agree?
+- flow completeness: are the user-facing and operator-facing flows touched by this work actually covered end to end?
+- security and permissions: are auth, RBAC, object-level checks, sensitive actions, and audit implications handled where relevant?
+- verification: did you run the strongest targeted checks that are appropriate without using owner-only broad gates?
+- reviewability: can the owner review this work by reading the changed files and a small number of directly related files?
+- test-coverage specificity: if the owner asked you to help shape coverage evidence, does it map concrete requirement/risk points to planned test files, key assertions, coverage status, and real remaining gaps rather than generic categories?
+
+If any answer is no, fix it before replying or call out the blocker explicitly.
+
+When you make an assumption, keep it prompt-preserving by default. If an assumption would reduce scope, mark it as unresolved instead of silently locking it in.
+
+If the owner asks you to help shape test-coverage evidence, make it acceptance-grade on first pass:
+
+- one explicit row or subsection per requirement/risk cluster
+- planned test file or test layer named concretely
+- key assertions named concretely
+- coverage status called out explicitly
+- real remaining gap or next test addition named explicitly
+- include backend/fullstack auth/error/authorization/masking/filter/sort coverage where relevant
+
 ## Skills
 
 - use relevant framework or language skills when they materially help the current task
@@ -109,3 +148,13 @@ Selected-stack defaults:
 - 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
+
+Use this reply shape for substantive work:
+
+1. `Changed files` — exact files changed
+2. `What changed` — the concrete behavior/contract updates in those files
+3. `Why this should pass review` — prompt-fit, no unauthorized narrowing, and consistency check in 2-5 bullets
+4. `Verification` — exact commands run and exact results
+5. `Remaining risks` — only the real unresolved weaknesses, if any
+
+Keep the reply compact. Point to the exact changed files and the narrow supporting files the owner should read next.