theslopmachine 0.6.2 → 0.7.1

package/MANUAL.md

@@ -2,7 +2,7 @@
 
 ## What it is
 
-theslopmachine installs a workflow-owner agent, a developer agent, and the supporting skills/templates needed to run the delivery workflow inside OpenCode.
+theslopmachine installs the workflow-owner agents, the developer agents, Claude runtime assets, and the supporting skills/templates needed to run the delivery workflow inside OpenCode and the Claude-backed path.
 
 ## Install
 
@@ -16,10 +16,20 @@ This installs:
 
 - agents into `~/.config/opencode/agents/`
 - skills into `~/.agents/skills/`
+- Claude runtime assets into `~/.claude/`
 - theslopmachine-owned files into `~/slopmachine/`
+- scaffold playbooks into `~/slopmachine/scaffold-playbooks/`
+- the post-bugfix coverage/README audit prompt into `~/slopmachine/test-coverage-prompt.md`
 - merged plugin/MCP config into `~/.config/opencode/opencode.json`
 
-The installed agent set includes the current `slopmachine` and `developer` agents.
+The installed agent set includes the current `slopmachine`, `slopmachine-claude`, and `developer` agents.
+
+The installed scaffold system includes:
+
+- one shared Docker/runtime/test contract
+- one generic unknown-tech scaffold guide
+- family matrices for frontend, backend, database, platform, and overlays
+- concrete verified or partial-proof playbooks for the common scaffold families
 
 ## Start a project
 
@@ -42,7 +52,8 @@ slopmachine init -o
 - updates `.gitignore`
 - bootstraps beads_rust (`br`)
 - creates `repo/`
-- copies the packaged repo rulebook into `repo/AGENTS.md`
+- copies the packaged default repo rulebook into `repo/AGENTS.md`
+- keeps the Claude-specific `CLAUDE.md` template available for `slopmachine-claude` to choose during `P1`
 - creates the initial git commit so the workspace starts with a clean tree
 - optionally opens `opencode` in `repo/`
 
@@ -55,14 +66,18 @@ slopmachine init -o
 5. Development
 6. Integrated verification
 7. Hardening
-8. Evaluation and fix verification
+8. Evaluation and fix verification, including the final coverage and README audit inside `P7`
 9. Final human decision
 10. Submission packaging
 11. Retrospective
 
 ## Important notes
 
-- theslopmachine depends on OpenCode, beads_rust (`br`), git, python3, and Docker being available.
+- theslopmachine depends on Node.js/npm, OpenCode, beads_rust (`br`), git, python3, and Docker being available.
+- Unix-like setup paths also depend on `bash` and `curl`, and Linux fallback archive handling depends on `tar`.
+- the Claude-backed path also depends on the `claude` CLI plus `tmux`.
+- packaging and send-data depend on archive support: `zip` on non-Windows systems or PowerShell on Windows.
 - 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, cleaned session exports, converted session traces, and the cleaned repo into the required final structure.
+- the scaffold playbook inventory now covers the main repeated families used in current tasks: React/Vite, Vue/Vite, Angular, FastAPI, Spring Boot, Django, Laravel, Livewire, Go/Chi, Android Java Views, Android Kotlin Compose, Electron/Vite, Tauri, Expo iOS-on-Linux, plus honest Linux partial-proof native Swift and Objective-C iOS playbooks.
+- Submission packaging collects the final docs, accepted evaluation reports, cleaned OpenCode session exports or one Claude project session zip bundle, and the cleaned repo into the required final structure.

package/README.md

@@ -9,17 +9,26 @@ It configures:
 - the `developer` implementation agent
 - required skills under `~/.agents/skills/`
 - Claude worker runtime assets under `~/.claude/`
-- workflow support files under `~/slopmachine/`
+- workflow support files under `~/slopmachine/`, including scaffold playbooks
+- the post-bugfix coverage/README audit prompt at `~/slopmachine/test-coverage-prompt.md`
 - OpenCode MCP entries for `context7` and `exa`
 
 ## Requirements
 
 - Node.js 18+
+- `npm`
 - `git`
 - Docker
 - `python3`
+- `bash` on Unix-like systems
+- `curl` on Unix-like systems
+- `tar` on Linux for fallback archive handling
 - `opencode`
 - `br` (`beads_rust`)
+- `tmux` for the `slopmachine-claude` live bridge
+- `claude` for the `slopmachine-claude` backend
+- `zip` on non-Windows systems for packaging and send-data archives
+- PowerShell on Windows for packaging and send-data archives
 
 `slopmachine setup` verifies or installs what it can.
 
@@ -31,7 +40,7 @@ From this package directory:
 npm install
 npm run check
 npm pack
-npm install -g ./theslopmachine-0.5.0.tgz
+npm install -g ./theslopmachine-0.6.2.tgz
 ```
 
 For local development instead:
@@ -53,11 +62,13 @@ slopmachine setup
 What it does:
 
 - verifies or installs `opencode`
-- verifies `br`, `git`, `python3`, and Docker
+- verifies `npm`, `br`, `git`, `python3`, Docker, and the Claude/live-bridge packaging dependencies
 - installs packaged agents into `~/.config/opencode/agents/`
 - installs packaged skills into `~/.agents/skills/`
 - installs Claude runtime assets into `~/.claude/`
 - installs workflow files into `~/slopmachine/`
+- installs scaffold playbooks into `~/slopmachine/scaffold-playbooks/`
+- installs `~/slopmachine/test-coverage-prompt.md` for the final post-bugfix audit
 - updates `~/.config/opencode/opencode.json`
 - ensures packaged MCP entries for `context7` and `exa`
 - optionally asks for an upload token if one is not already stored
@@ -67,6 +78,33 @@ 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
+- scaffold assets now include a shared Docker contract, family matrices, and concrete default playbooks under `~/slopmachine/scaffold-playbooks/`
+
+Current scaffold inventory includes:
+
+- shared Docker/runtime/test contract
+- generic unknown-tech scaffold guide
+- frontend, backend, database, platform, and overlay family matrices
+- experimentally verified concrete playbooks for:
+  - React/Vite
+  - Vue/Vite
+  - Angular
+  - FastAPI
+  - Spring Boot
+  - Django
+  - Laravel
+  - Livewire
+  - Go/Chi
+  - Android Java Views
+  - Android Kotlin Compose
+  - Electron/Vite desktop
+  - Tauri desktop
+  - Expo iOS-on-Linux
+- experimentally verified Linux partial-proof playbooks for:
+  - native Swift iOS
+  - native Objective-C iOS
+
+These playbooks are baseline-only scaffold references. Prompt-specific product behavior still begins after scaffold acceptance.
 
 ### `slopmachine init`
 
@@ -94,7 +132,7 @@ What it creates:
 
 - `repo/`
 - `docs/`
-- `self_test_reports/`
+- `.tmp/`
 - `sessions/`
 - `metadata.json`
 - `.ai/metadata.json`
@@ -104,6 +142,8 @@ What it creates:
 - `.ai/startup-context.md`
 - root `.beads/`
 - `repo/AGENTS.md`
+- `repo/.claude/settings.json`
+- `repo/CLAUDE.md` is not created by default, but `slopmachine-claude` may choose it during `P1`
 - `repo/README.md`
 - `docs/questions.md`
 - `docs/design.md`
@@ -114,10 +154,13 @@ Important details:
 
 - `run_id` is created in `.ai/metadata.json`
 - the workspace root is the parent directory containing `repo/`
+- parent-root `.tmp/` is the audit and fix-check artifact directory used during `P7`
+- parent-root `.tmp/` also holds `test_coverage_and_readme_audit_report.md` after the final post-bugfix audit
 - Beads lives in the workspace root, not inside `repo/`
+- `repo/.claude/settings.json` seeds Claude Code to use the custom `developer` agent by default for that repo
 - after non-`-o` bootstrap, the command prints the exact `cd repo` next step so you can continue immediately
 - `--adopt` moves the current project files into `repo/`, preserves root workflow state in the parent workspace, and skips the automatic bootstrap commit
-- `--phase <PX>` records the requested starting phase for owner-side adoption and recovery
+- `--phase <PX>` seeds the initial `current_phase` for adoption/recovery bootstrap; the owner should still fall back if the real repo evidence does not support that later phase
 
 ### `slopmachine set-token`
 
@@ -175,9 +218,13 @@ What it exports live:
 
 What it includes when present:
 
-- `self_test_reports/`
+- `.tmp/`
 - `retrospective-<run_id>.md`
 - `improvement-actions-<run_id>.md`
+- `test_coverage_and_readme_audit_report.md`
+
+What it always includes:
+
 - `metadata.json`
 - `ai-metadata.json`
 - `manifest.json`
@@ -193,7 +240,7 @@ Fail-fast conditions:
 
 Warn-only conditions:
 
-- missing `self_test_reports/`
+- missing `.tmp/`
 - missing retrospective files
 
 Output behavior:
@@ -251,6 +298,7 @@ Claude runtime assets:
 Workflow files:
 
 - installed under `~/slopmachine/`
+- includes `~/slopmachine/test-coverage-prompt.md`
 
 ## Verification
 

package/RELEASE.md

@@ -14,7 +14,7 @@ node ./bin/slopmachine.js --help
 SLOPMACHINE_HOME="$(pwd)/.tmp-home" SLOPMACHINE_NONINTERACTIVE=1 SLOPMACHINE_PLUGIN_BOOTSTRAP=0 node ./bin/slopmachine.js setup
 ```
 
-That setup path should install `opencode-ai@latest` when OpenCode is missing and refresh it to `@latest` when it already exists.
+That setup path should install `opencode-ai` when OpenCode is missing and only refresh it when the detected version is below the minimum supported version.
 
 Users can later refresh to the newest published package with:
 
@@ -48,6 +48,7 @@ Note:
 
 - `slopmachine init` is Node-driven.
 - Workflow bootstrap is driven through the packaged Node helper `workflow-init.js`.
+- before packing or publishing, make sure `git status --short` does not show junk artifacts such as `.DS_Store`, `__pycache__/`, or other accidental packaging noise
 
 ## Pack the npm package
 
@@ -89,8 +90,22 @@ And specifically verify that the tarball includes the current workflow assets:
 - `assets/skills/claude-worker-management/`
 - `assets/skills/planning-guidance/`
 - `assets/skills/submission-packaging/`
+- `assets/slopmachine/scaffold-playbooks/`
+- within `assets/slopmachine/scaffold-playbooks/`, verify the shared contract, family matrices, generic unknown-tech guide, and concrete verified/default playbooks are present for the currently supported scaffold families
 - `assets/slopmachine/templates/AGENTS.md`
+- `assets/slopmachine/templates/CLAUDE.md`
 - `assets/slopmachine/workflow-init.js`
+- `assets/slopmachine/utils/cleanup_delivery_artifacts.py`
+- `assets/slopmachine/utils/package_claude_session.mjs`
+- `assets/slopmachine/utils/prepare_strict_audit_workspace.mjs`
+- `assets/slopmachine/utils/claude_wait_for_rate_limit_reset.mjs`
+- `assets/slopmachine/utils/claude_wait_for_rate_limit_reset.sh`
+- `assets/slopmachine/utils/claude_live_common.mjs`
+- `assets/slopmachine/utils/claude_live_launch.mjs`
+- `assets/slopmachine/utils/claude_live_turn.mjs`
+- `assets/slopmachine/utils/claude_live_status.mjs`
+- `assets/slopmachine/utils/claude_live_stop.mjs`
+- `assets/slopmachine/test-coverage-prompt.md`
 
 ## Publish
 

package/assets/agents/developer.md

@@ -13,6 +13,9 @@ permission:
   "*": allow
   bash: allow
   lsp: allow
+  task: allow
+  todoread: allow
+  todowrite: allow
   "context7_*": allow
   "exa_*": allow
   "grep_app_*": allow
@@ -39,6 +42,10 @@ Read and follow `AGENTS.md` before implementing.
 Before coding:
 
 - identify requirements, constraints, flows, and edge cases
+- identify the actors or personas touched by the work and the concrete path to success for each one
+- make the important business rules explicit before coding, including defaults, thresholds, limits, uniqueness, conflicts, reversals, retry behavior, and ownership rules when those dimensions matter
+- define or confirm the relevant state machine when the feature has meaningful lifecycle state
+- keep explicit out-of-scope boundaries in mind so you do not overbuild speculative features
 - 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
@@ -60,17 +67,46 @@ When accepted planning artifacts already exist, treat them as the primary execut
 - do not wait for the owner to restate what is already in the plan
 - treat owner follow-up prompts mainly as narrow deltas, guardrails, or correction signals
 
+When the owner asks for planning without coding yet:
+
+- produce an exhaustive, section-addressable implementation plan rather than a high-level summary
+- prefer writing almost all important implementation decisions down now instead of deferring them to coding time
+- make unresolved items rare, narrow, and explicit
+- if the owner asks you to write planning artifacts, fill them densely enough that later implementation can mostly execute by following the plan rather than inventing new structure
+- when the owner asks for planning artifacts, prefer putting the real planning depth into the requested planning files rather than leaving the important detail only in chat
+
 ## Execution Model
 
 - implement real behavior, not placeholders
 - keep user-facing and admin-facing flows complete through their real surfaces
+- when roles or privileges matter, keep route-level, object-level, and function-level authorization aligned with the actual actor model
+- when third-party integrations are required but real external integration is not explicitly demanded, prefer internal stubs or adaptors over brittle live-service coupling
+- for backend or fullstack work, keep configuration reads centralized instead of scattering direct environment access through business logic
+- keep logging, validation, and normalized error handling on shared paths when those cross-cutting concerns are material
 - verify the changed area locally and realistically before reporting completion
+- when backend or fullstack API endpoints are added or changed, prefer real HTTP tests for the exact `METHOD + PATH` over controller or service bypasses when practical
+- if mocked HTTP tests or unit-only tests still exist for an API surface, do not overstate them as equivalent to true no-mock endpoint coverage
 - when closing a slice, think briefly about what adjacent flows, runtime paths, or doc/spec claims this slice could have affected before claiming readiness
 - 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
+- keep `README.md` compatible with the strict audit contract as the project matures: project type near the top, startup instructions, access method, verification method, and demo credentials for every role or the exact statement `No authentication required`
+- for backend, fullstack, and web projects, keep the canonical `docker compose up --build` contract in `README.md` and also include the exact legacy compatibility string `docker-compose up` somewhere in startup guidance
+- for Android, iOS, and desktop projects, keep the required Docker-contained final contract while also maintaining the project-type-specific host-side guidance sections expected by the strict README audit
+- before reporting development complete, remove local-only setup traces and host-only dependency assumptions from the delivered README and wrapper scripts
+
+## Parallel Execution Model
+
+- before deeper implementation, do a quick serial-versus-parallel check instead of defaulting to one long serial branch
+- when 2 or 3 independent work items can proceed with stable contracts and minimal shared-file churn, use `Task` fan-out instead of serializing by habit
+- use `TodoWrite` and `TodoRead` to keep a compact live record of shared prerequisites, active branches, merge checkpoints, and remaining blockers when the work is non-trivial
+- good parallel candidates include independent repo reading, verification passes, separate test additions, and implementation branches that touch different modules or well-separated files
+- do not parallelize tightly coupled work that still depends on unresolved contracts, shared abstractions being invented in real time, or overlapping edits to the same files
+- before fan-out, define the branch contract clearly: expected outcome, boundaries, important shared constraints, and merge condition
+- after fan-in, reconcile the branches yourself, resolve any overlap cleanly, and run final targeted verification on the integrated result before reporting completion
+- prefer a small number of meaningful branches over spawning many tiny sub-tasks; 2 or 3 good parallel branches are usually enough
 
 ## Verification Cadence
 
@@ -82,6 +118,8 @@ During ordinary work, prefer:
 - targeted module or route-family tests
 - targeted component, route, page, or state-focused tests when UI behavior is material
 
+- fast local tooling setup is allowed during ordinary iteration, but it must not become a dependency of the final delivered runtime or broad test contract
+
 Broad commands you are not allowed to run during ordinary work:
 
 - never run `./run_tests.sh`
@@ -96,7 +134,7 @@ Your job is to make the broader verification likely to pass without running it y
 Selected-stack defaults:
 
 - follow the original prompt and existing repo first; use these only when they do not already specify the platform or stack
-- web frontend/fullstack: Tailwind CSS plus `shadcn/ui` by default unless the prompt or existing repo says otherwise
+- web frontend/fullstack: Tailwind CSS by default; use `shadcn/ui` when the selected frontend ecosystem supports it cleanly, otherwise use a mainstream documented component library such as Material UI, Ant Design, Ant Design Vue, or Angular Material as appropriate to the stack
 - mobile: Expo plus React Native plus TypeScript by default unless the prompt or existing repo says otherwise
 - desktop: Electron plus Vite plus TypeScript by default unless the prompt or existing repo says otherwise
 
@@ -120,6 +158,8 @@ Selected-stack defaults:
 - 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
+- do not silently swap required interaction models, lifecycle behavior, or data-integrity rules for easier substitutes
+- do not let mocked or indirect API tests masquerade as true endpoint coverage in docs, comments, or completion claims
 
 ## Completion Preflight