theslopmachine 1.0.22 → 1.0.25

package/MANUAL.md

@@ -15,30 +15,36 @@ The installer copies OpenCode agents to `~/.config/opencode/agents`, Claude asse
 ## Initialize A Task
 
 ```sh
-slopmachine init /path/to/task-root
+slopmachine init <github-url>
 ```
 
-The initialized root is intentionally sparse and packaging-friendly. Product code belongs in `repo/`; product-facing docs belong in `docs/`; final kept reports belong in `.tmp/`; project facts belong in `metadata.json`.
+Run init from an empty workflow root. The GitHub repository name becomes the task root directory name. For example, `slopmachine init https://github.com/example/t178.git` clones into `./t178/`.
 
-Use `--claude` for `slopmachine-claude` runs:
+The cloned task root must already contain the task-facing structure: product code in `repo/`, product-facing docs in `docs/`, final kept reports in `.tmp/`, and project facts in `metadata.json`. SlopMachine creates workflow-private state in sibling `./.ai` and `./.beads` directories.
+
+Init relies on normal git authentication. If the repository is private and local git cannot access it, clone fails.
+
+SlopMachine no longer seeds developer-facing docs, API spec placeholders, product README content, `AGENTS.md`, or `.claude/settings.json`. It only writes the allowed task-root `CLAUDE.md` rulebook.
+
+Use `-o` to open OpenCode after bootstrap:
 
 ```sh
-slopmachine init --claude /path/to/task-root
+slopmachine init https://github.com/example/t178.git -o
 ```
 
-The active developer rulebook is recorded in `../.ai/metadata.json` as `developer_rulebook_file`. The unused rulebook is removed from the task folder.
+The active developer rulebook is recorded in `../.ai/metadata.json` as `developer_rulebook_file`.
 
 ## Continue From A Phase Alias
 
 ```sh
-slopmachine init --continue-from P5 /path/to/task-root
+slopmachine init <github-url> --continue-from P5
 ```
 
 Legacy aliases remain accepted for CLI compatibility, but owner-facing language uses Phase 1 through Phase 8.
 
 ## Developer Rulebooks
 
-OpenCode developer agents read `AGENTS.md`. Claude developer agents read `CLAUDE.md`. Only the selected rulebook is seeded into a task root. These files are product engineering rulebooks, not owner workflow instructions.
+Claude developer lanes read `CLAUDE.md`. SlopMachine seeds only this product engineering rulebook into the task root; it is not an owner workflow instruction file.
 
 ## Verification
 

package/README.md

@@ -27,12 +27,11 @@ slopmachine install
 ```sh
 slopmachine --help
 slopmachine install
-slopmachine init <target-dir>
-slopmachine init --claude <target-dir>
+slopmachine init <github-url>
 slopmachine set-token
 ```
 
-Use `slopmachine init` to create or adopt a task root. By default it seeds `AGENTS.md` for OpenCode developer lanes. Use `slopmachine init --claude` to seed `CLAUDE.md` and `.claude/` for script-managed Claude Code lanes. The unused rulebook is not left in the task folder, and `../.ai/metadata.json` records the active `developer_rulebook_file`.
+Use `slopmachine init <github-url>` from an empty workflow root. The CLI clones the GitHub repository into `./<repo-name>/`, uses that cloned folder as the task root, creates workflow-private state under `./.ai` and `./.beads`, and records the repo name as `task_root` and `run_id`. The cloned task root is expected to contain the task-facing `docs/`, `.tmp/`, `metadata.json`, and `repo/` structure. SlopMachine no longer seeds developer-facing docs or product README content; it only writes the allowed task-root `CLAUDE.md` rulebook.
 
 ## Phase Map
 
@@ -69,4 +68,4 @@ npm run check
 
 ## Developer-Facing Boundaries
 
-Developer-facing prompts and rulebooks avoid owner workflow mechanics. They focus on good engineering practice: read the code, follow `AGENTS.md` or `CLAUDE.md`, implement real behavior, keep README claims honest, test meaningful behavior, avoid secrets, do not run Docker or `run_tests.sh` unless asked, and provide proof for completed work.
+Developer-facing prompts and the task-root `CLAUDE.md` rulebook avoid owner workflow mechanics. They focus on good engineering practice: read the code, implement real behavior, keep README claims honest, test meaningful behavior, avoid secrets, do not run Docker or `run_tests.sh` unless asked, and provide proof for completed work.

package/RELEASE.md

@@ -5,6 +5,6 @@
 - Preserves the reference CLI/package behavior.
 - Rebuilds owner agents around Phase 1 through Phase 8 terminology.
 - Adds generic developer prompts for OpenCode and Claude.
-- Adds task-root `AGENTS.md` and `CLAUDE.md` templates focused on product engineering practice.
+- Seeds only the task-root `CLAUDE.md` rulebook; developer-facing docs and product README content come from the cloned task repository and implementation lane work.
 - Includes Claude-specific worker skills and all required slopmachine utility scripts.
 - Keeps legacy `P*` phase aliases for CLI compatibility.

package/assets/agents/slopmachine-claude.md

@@ -108,6 +108,8 @@ Good Claude-message style:
 
 ## Owner Direct Fixes And Developer Awareness
 
+The owner may directly make small safe edits to existing docs, config, wrappers, cleanup, and light glue when the change does not require product-design judgment, broad debugging, new product behavior, or new tests. Inside `./repo`, owner-side edits are limited to existing configuration, Docker files, test wrappers, run scripts, verification scripts, cleanup scripts, and similarly narrow glue. The owner must never create a new file anywhere under `./repo`. New product files, meaningful implementation work, new tests, behavioral changes, and larger fixes must go to the active Claude lane.
+
 When the owner makes direct edits to the task directory (README, config, scripts, docs, glue code, cleanup), the active Claude lane (develop-1, bugfix-1, or test-coverage-1) must always be informed of what changed. Batching is required: make a group of fixes, batch them together, then inform the lane once. Do not notify the lane turn by turn for every small edit.
 
 This rule applies strictly to the persistent implementation lanes — develop-1, bugfix-1, and test-coverage-1. It does not apply to evaluator sessions, clarification workers, faithfulness reviewers, planning subagents, or other temporary owner-side sessions.
@@ -148,7 +150,7 @@ Example: `I made a few edits to the README for the startup docs and fixed a conf
 - Never use `task` with `developer`, `implement`, `helper`, maintenance, or ad hoc coding subagents for product implementation, product bugfixes, product test authoring, product docs authored by the implementation lane, or implementation verification guidance. Those must go through live Claude lanes using the packaged Claude utilities.
 - Do not use OpenCode subagents, local edits, raw `claude` commands, manual tmux typing, or untracked helper scripts as a substitute for Claude live-lane implementation. The only normal interaction path with Claude lanes is `claude_live_launch.mjs`, `claude_live_turn.mjs`, `claude_live_status.mjs`, and `claude_live_stop.mjs`.
 - Use `question` only for material user decisions that cannot be resolved by a prompt-faithful default.
-- Use `edit`/`write` only for owner-side workflow files, reports, and tiny safe owner fixes that do not substitute for Claude implementation work. The owner may directly make small safe edits to docs, config, wrappers, cleanup, and light glue when the change does not require product-design judgment, broad debugging, new product behavior, or new tests. The owner must not create new files under `./repo`; new product files, meaningful implementation work, and larger fixes must go to the active Claude lane. Do not edit installed packaged prompt assets; those must always be read fresh and pasted verbatim under the non-negotiable verbatim prompt paste rule at the top of this file. If a tiny owner fix touches product code/docs, notify the active Claude lane and ask it to inspect/acknowledge before continuing.
+- Use `edit`/`write` only for owner-side workflow files, reports, and tiny safe owner fixes that do not substitute for Claude implementation work. Inside `./repo`, owner-side edits are limited to existing configuration, Docker files, test wrappers, run scripts, verification scripts, cleanup scripts, and similarly narrow glue. The owner must never create a new file anywhere under `./repo`; new product files, meaningful implementation work, new tests, behavioral changes, and larger fixes must go to the active Claude lane. Do not edit installed packaged prompt assets; those must always be read fresh and pasted verbatim under the non-negotiable verbatim prompt paste rule at the top of this file. If a tiny owner fix touches product code/docs, notify the active Claude lane and ask it to inspect/acknowledge before continuing.
 - Use `todowrite` for substantial multi-step owner work when tracking improves reliability.
 - Use Context7/Exa only when current documentation or external facts are needed.
 
@@ -228,7 +230,7 @@ Use these sequential names as the canonical workflow model. Legacy `P*` names ar
 
 - Required skills: `beads-operations`, `developer-session-lifecycle`, `claude-worker-management`, `planning-guidance`, `planning-gate`, `owner-evidence-discipline`, and `report-output-discipline` when reports are long or reusable.
 - Establish or resume the primary Claude lane and start design/planning.
-- Follow the deterministic planning sequence in `planning-guidance` exactly: (1) send original prompt with only "don't write code yet" appended, (2) after acknowledgement send clarifications, (3) after acknowledgement send the design prompt verbatim.
+- Follow the deterministic planning sequence in `planning-guidance` exactly: (1) send original prompt with only the required planning/placeholder sentences appended, (2) after acknowledgement send clarifications, (3) after acknowledgement send the design prompt verbatim.
 - Delegate owner-private `../.ai/plan.md` creation to a general owner-side subagent. Read the installed `~/slopmachine/phase-2-execution-planning-prompt.md` and `~/slopmachine/phase-2-plan-template.md` fresh. Paste both bodies verbatim into the subagent message.
 - Record lane/session and artifact decisions in metadata and Beads.
 - Exit only when `planning-gate` is satisfied.

package/assets/agents/slopmachine.md

@@ -108,7 +108,7 @@ Good worker-message style:
 
 ## Owner Direct Fixes And Developer Awareness
 
-The owner may directly make small safe edits to docs, config, wrappers, cleanup, and light glue when the change does not require product-design judgment, broad debugging, new product behavior, or new tests. The owner must not create new files under `./repo`; new product files, meaningful implementation work, and larger fixes must go to the active developer/bugfix/test-coverage lane.
+The owner may directly make small safe edits to existing docs, config, wrappers, cleanup, and light glue when the change does not require product-design judgment, broad debugging, new product behavior, or new tests. Inside `./repo`, owner-side edits are limited to existing configuration, Docker files, test wrappers, run scripts, verification scripts, cleanup scripts, and similarly narrow glue. The owner must never create a new file anywhere under `./repo`. New product files, meaningful implementation work, new tests, behavioral changes, and larger fixes must go to the active developer/bugfix/test-coverage lane.
 
 When the owner makes direct edits to the task directory (README, config, scripts, docs, glue code, cleanup), the active developer/bugfix/test-coverage lane must always be informed of what changed. Batching is required: make a group of fixes, batch them together, then inform the lane once. Do not notify the lane turn by turn for every small edit.
 
@@ -149,7 +149,7 @@ Example: `I made a few edits to the README for the startup docs and fixed a conf
 - Do not use `implement`, `helper`, maintenance, or extra ad hoc subagents for product implementation unless the user explicitly asks. Keep implementation in the tracked active developer session except for evaluator-isolated work or a recorded recovery/context reason.
 - Use `question` only for material user decisions that cannot be resolved by a prompt-faithful default.
 - Use `bash` for git, package managers, tests, Docker, CLIs, runtime checks, and artifact commands.
-- Use `edit`/`write` for owner-side workflow files, tiny safe fixes, and reports. Do not edit installed packaged prompt assets; those must always be read fresh and pasted verbatim under the non-negotiable verbatim prompt paste rule at the top of this file.
+- Use `edit`/`write` for owner-side workflow files, reports, and tiny safe edits to existing docs/config/wrappers/scripts/glue. Inside `./repo`, never use owner-side editing to create new files; new repo files must be created by the active developer/bugfix/test-coverage lane. Do not edit installed packaged prompt assets; those must always be read fresh and pasted verbatim under the non-negotiable verbatim prompt paste rule at the top of this file.
 - Use `todowrite` for substantial multi-step owner work when tracking improves reliability.
 - Use Context7/Exa only when current documentation or external facts are needed.
 
@@ -197,7 +197,7 @@ Use these sequential names as the canonical workflow model. Legacy `P*` names ar
 
 - Required skills: `beads-operations`, `developer-session-lifecycle`, `planning-guidance`, `planning-gate`, `owner-evidence-discipline`, and `report-output-discipline` when reports are long or reusable.
 - Establish or resume the primary developer session and start design/planning.
-- Follow the deterministic planning sequence in `planning-guidance` exactly: (1) send original prompt with only "don't write code yet" appended, (2) after acknowledgement send clarifications, (3) after acknowledgement send the design prompt verbatim.
+- Follow the deterministic planning sequence in `planning-guidance` exactly: (1) send original prompt with only the required planning/placeholder sentences appended, (2) after acknowledgement send clarifications, (3) after acknowledgement send the design prompt verbatim.
 - Delegate owner-private `../.ai/plan.md` creation to a general owner-side subagent. Read the installed `~/slopmachine/phase-2-execution-planning-prompt.md` and `~/slopmachine/phase-2-plan-template.md` fresh. Paste both bodies verbatim into the subagent message.
 - Record session and artifact decisions in metadata and Beads.
 - Exit only when `planning-gate` is satisfied.

package/assets/skills/deep-retrospective/run.py

@@ -272,7 +272,19 @@ def main():
     beads = read_beads(project_path)
     ai_data = read_ai_metadata(project_path)
     task_dir = project_path if os.path.isdir(os.path.join(project_path, "docs")) \
-               else os.path.join(project_path, "task")
+               else None
+    if not task_dir:
+        ai_meta = os.path.join(project_path, ".ai", "metadata.json")
+        if os.path.isfile(ai_meta):
+            with open(ai_meta) as f:
+                ai_data = json.load(f)
+            task_root_name = ai_data.get("task_root") if isinstance(ai_data, dict) else None
+            candidate = os.path.join(project_path, task_root_name)
+            if os.path.isdir(os.path.join(candidate, "docs")):
+                task_dir = candidate
+    if not task_dir:
+        print(f"  Warning: could not find task root at {project_path} (no docs/ and no .ai/metadata.json with task_root)")
+        task_dir = project_path
     task_docs = read_task_docs(task_dir)
     audit_reports = read_audit_reports(task_dir)
     print(f"  Beads: {len(beads)}, Audit reports: {len(audit_reports)}")

package/assets/skills/deep-retrospective/workflow-reference.md

@@ -238,3 +238,4 @@ Implementation must:
 10. **Module isolation:** Modules built in isolation with no cross-module integration tests proving data/behavior flow between them
 11. **Skipped evaluator passes:** Fewer than 5 internal evaluator passes run in Phase 4
 12. **No browser verification before P6:** Web/fullstack projects reach P6 without any browser verification, finding crashes that should have been caught in P3 or P4
+13. **Owner-created repo files:** Owner creates new files under repo/ instead of routing file creation through the active developer lane

package/assets/skills/developer-session-lifecycle/SKILL.md

@@ -12,7 +12,7 @@ Use this skill for startup preflight, session policy, metadata consistency, lane
 Sessions are the primary deliverable. An incomplete or corrupted session dataset invalidates the submission regardless of code quality. Every session must be preserved, continuous, and authentic.
 
 - Do not edit, rename, restructure, rewrite, clean, delete, or fabricate session files or trajectory records. They are immutable evidence.
-- Do not perform untracked implementation work. Developer/Claude implementation, debugging, and substantive product fixes must happen inside a tracked implementation session. Owner orchestration, verification commands, package checks, and tiny safe owner-side docs/config/wrapper/glue fixes are allowed when recorded in metadata/Beads and the active implementation lane is notified afterward.
+- Do not perform untracked implementation work. Developer/Claude implementation, debugging, and substantive product fixes must happen inside a tracked implementation session. Owner orchestration, verification commands, package checks, and tiny safe owner-side edits to existing docs/config/wrappers/scripts/glue are allowed when recorded in metadata/Beads and the active implementation lane is notified afterward. The owner must never create a new file anywhere under `./repo`; new repo files must be created by the active developer/Claude lane.
 - Sessions must progress strictly forward. Never return to a closed session. The lifecycle is:
   1. Development session → complete → stop/close
   2. Bugfix session → complete both audit cycles → close
@@ -23,7 +23,7 @@ Sessions are the primary deliverable. An incomplete or corrupted session dataset
 ## Preflight
 
 - Confirm cwd is task root `./`.
-- Confirm the current working directory is the task root (the directory containing `repo/`, `docs/`, and `metadata.json`). If the root is not `task/` or its equivalent, stop and reject: sessions must be started from the task root, not from inside `repo/` or any subdirectory.
+- Confirm the current working directory is the task root (the directory containing `repo/`, `docs/`, and `metadata.json`). If the root does not contain these expected paths, stop and reject: sessions must be started from the task root, not from inside `repo/` or any subdirectory.
 - Confirm product repo exists at `./repo`.
 - Confirm workflow-private root exists at `../.ai`, workflow state exists at `../.ai/metadata.json`, and Beads root exists at `../.beads` when initialized.
 - Confirm task docs are limited to `./docs/questions.md`, `./docs/design.md`, and `./docs/api-spec.md` when applicable.
@@ -48,7 +48,7 @@ Sessions are the primary deliverable. An incomplete or corrupted session dataset
 - Phase 5 uses fresh evaluator sessions for full audits. Evaluator-session reuse occurs in three cases: (1) fail-regeneration — same session receives only the regeneration prompt after fixes; (2) Partial Pass fix-check — same session verifies all scoped issues are fixed; (3) Pass-with-items fix-check — same session verifies all scoped recommendations are closed.
 - Audit Cycle 1 and Audit Cycle 2 fixes go through the dedicated bugfix lane. After both audit cycles complete, the bugfix lane is closed and a new test-coverage/final-reconciliation lane takes over for coverage/README remediation.
 - Phase 6 reconciliation uses the currently active developer/Claude lane for Docker, runtime, browser, account, `run_tests.sh`, coverage, README, and final readiness fixes unless a new lane is explicitly justified by context limits or isolation risk.
-- If the owner directly changes docs, wrappers, config, cleanup, or light glue, send the active lane a minimal acknowledgement request that names the changed surface and asks it to inspect/confirm before readiness continues.
+- If the owner directly changes existing docs, wrappers, config, cleanup, scripts, or light glue, send the active lane a minimal acknowledgement request that names the changed surface and asks it to inspect/confirm before readiness continues.
 
 ## Metadata Discipline
 

package/assets/skills/final-evaluation-orchestration/SKILL.md

@@ -58,7 +58,7 @@ No other full-audit or fail-regeneration prompt is allowed. In particular, the o
 
 If any deviation is found from either allowed prompt send, the current audit cycle is invalid. Archive every report or candidate report generated during that invalid cycle unchanged under `../.ai/archive/`, record the restart reason in metadata and Beads, then restart that audit cycle from a fresh evaluator session using the installed asset and exact saved send packet. Do not patch, rename, or reuse invalid-cycle reports as kept reports.
 
-Record the installed prompt asset path, prepared prompt path, exact send packet path, evaluator session id, and report path in metadata and Beads. Treat evaluator reports as immutable once written.
+Record the installed prompt asset path, prepared prompt path, exact send packet path, evaluator session id, and report path in metadata and Beads. Treat evaluator reports as immutable once written except for the narrow minor wording cleanup allowed by cycle validation below.
 
 ## Report Paths And Names
 
@@ -152,6 +152,8 @@ Run this procedure twice: once for Audit Cycle 1 and once for Audit Cycle 2.
 
 Before a cycle can close, validate the whole cycle as a hard gate. If any item fails, archive every candidate/kept/fix-check report produced in that cycle unchanged under `../.ai/archive/`, record the reason, and restart that audit cycle from a fresh evaluator session using the non-negotiable full-audit prompt block.
 
+Exception: if the only issue is minor wording that does not change findings, verdict, severity, evidence, scoped issue identity, fix status, or report meaning, the owner may patch that wording directly in the kept report or fix-check report instead of restarting the cycle. Record the exact wording cleanup, file path, and reason in metadata and Beads. Do not use this exception to alter verdicts, remove real findings, add missing fix evidence, repair a mismatched issue list, or hide a materially invalid regeneration/fix-check.
+
 Required for each cycle:
 - the installed evaluation prompt asset path is recorded and matches the project type;
 - the exact saved send packet path is recorded;
@@ -160,8 +162,10 @@ Required for each cycle:
 - the kept audit report exists at `./.tmp/audit_report-<N>.md`;
 - the kept audit report is rich and complete: at least 150 lines and not materially shallower than the installed prompt's required output structure;
 - the kept audit report includes the required verdict, scope/boundary, prompt/repository mapping, section review or blocker/high panel as applicable, issues/suggestions or explicit no-issue statement, security/data-risk review where applicable, and test/logging/coverage sections required by the installed prompt;
+- the kept audit report has no language that reveals or implies it is a regeneration, rerun, continuation, post-fix report, or comparison against an earlier audit. Forbidden examples include: `regenerated`, `regeneration`, `rerun`, `previous audit`, `previous report`, `prior audit`, `after fixes`, `after the fixes`, `fixed since`, `remaining`, `still`, `now fixed`, `resolved`, `no longer`, `left`, `updated verdict`, or equivalent wording that exposes audit history. If this language is only incidental wording and does not affect findings or meaning, patch it and record the cleanup. If the report is continuation-shaped, fix-oriented, or materially depends on prior audit history, archive and restart the cycle;
 - the cycle fix-check report exists at `./.tmp/audit_report-<N>-fix_check.md`;
 - the cycle fix-check report confirms every issue/recommendation/caveat/suggestion/action item/requested change from the kept audit report is fixed, or explicitly confirms the kept audit report had zero scoped items to close;
+- the scoped issue list in the fix-check exactly matches the scoped issue list from the corresponding kept audit report. Every kept-audit issue/recommendation/caveat/suggestion/action item/requested change must appear in the fix-check with a fixed status and evidence, and the fix-check must not silently drop, merge beyond recognition, rename into a different issue, or add unrelated new audit issues. If the lists do not match, the cycle is invalid and must restart unless the mismatch is only a harmless wording/label discrepancy that can be patched without changing issue identity, fix status, evidence, or meaning;
 - the fix-check report does not perform a broader new audit and does not use history-exposing comparison language.
 
 No audit cycle is complete without both `./.tmp/audit_report-<N>.md` and `./.tmp/audit_report-<N>-fix_check.md` passing this validation gate.

package/assets/skills/p8-readiness-reconciliation/SKILL.md

@@ -74,7 +74,7 @@ If any final runtime, test, browser, account, or platform check cannot run, read
 
 ## Owner Direct Fixes
 
-- The owner may directly fix only minor, safe docs, wrapper, config, cleanup, or light glue issues when the change does not require product-design judgment, new tests, behavioral changes, or non-trivial debugging.
+- The owner may directly fix only minor, safe existing docs, wrapper, config, cleanup, run-script, verification-script, or light glue issues when the change does not require product-design judgment, new tests, behavioral changes, or non-trivial debugging. The owner must never create a new file anywhere under `./repo`; any new repo file must be created by the active developer/Claude lane.
 - If the reconciliation issue is large enough to need real implementation work, meaningful test updates, runtime debugging, README/runtime restructuring, or product judgment, do not fix it owner-side. Send it to the currently active developer/Claude lane.
 - Batch multiple direct fixes into a group, then inform the lane once. Do not notify turn by turn for every small edit. After all fixes in the batch are complete, send a single note describing all changed surfaces and ask the lane to inspect and acknowledge.
 - The note should be concise and developer-facing, not a workflow report.

package/assets/skills/planning-guidance/SKILL.md

@@ -22,7 +22,7 @@ Phase 2 establishes the primary developer session and produces the accepted plan
 - Accepted `./docs/questions.md`.
 - Accepted `../.ai/requirements-breakdown.md`.
 - Accepted `../.ai/clarification-faithfulness-review.md`.
-- Packaged design prompt and design template.
+- Packaged design prompt.
 - Packaged execution planning prompt and plan template.
 
 ## Deterministic Planning Sequence (Must Follow Exactly)
@@ -31,10 +31,11 @@ This sequence is strict. Do not combine, reorder, skip, or batch these steps. Ea
 
 ### Step 1: Send Original Prompt
 
-Send the original product prompt from `./metadata.json` exactly as-is. No prefix, no introduction, no context, no clarifications. Append only this exact sentence at the end:
+Send the original product prompt from `./metadata.json` exactly as-is. No prefix, no introduction, no context, no clarifications. Append only these exact sentences at the end:
 
 ```
 Don't write code yet — we'll plan this first.
+This folder may contain placeholder docs or repo content from the starting skeleton; please inspect it and remove or replace unrelated placeholder material as we go.
 ```
 
 That is the entire message. Wait for the developer to acknowledge before proceeding.
@@ -53,7 +54,7 @@ Wait for the developer to acknowledge before proceeding.
 
 ### Step 3: Send Design Prompt
 
-After the developer acknowledges the clarifications, read the installed `~/slopmachine/phase-1-design-prompt.md` fresh from its asset path and paste its full body verbatim under the non-negotiable verbatim prompt paste rule. The design prompt references the context already provided in Steps 1 and 2 and the template already seeded at `./docs/design.md`. Do not paste the template file body — it is already in the workspace.
+After the developer acknowledges the clarifications, read the installed `~/slopmachine/phase-1-design-prompt.md` fresh from its asset path and paste its full body verbatim under the non-negotiable verbatim prompt paste rule. The design prompt references the context already provided in Steps 1 and 2 and tells the lane what design surfaces to cover because `./docs/design.md` may be missing or placeholder-only.
 
 The design must:
 - be a true product/system design, not an execution plan
@@ -72,7 +73,9 @@ Patch small wording/traceability issues directly when meaning is unchanged. Send
 
 ### Step 5: Create `./docs/api-spec.md` When Applicable
 
-Use the accepted design as input. Require exact endpoint/interface contracts where APIs exist. If no meaningful API exists, mark `./docs/api-spec.md` as not applicable with a short reason. Record the API spec artifact path and applicability decision in metadata and Beads.
+Use the accepted design as input. Require exact endpoint/interface contracts where APIs exist. If `./docs/api-spec.md` is missing or placeholder-only, the implementation lane must create or replace it. If no meaningful API exists, mark `./docs/api-spec.md` as not applicable with a short reason. Record the API spec artifact path and applicability decision in metadata and Beads.
+
+The API spec prompt must ask for, where applicable: endpoint/interface name, purpose, actor/consumer, method/path or call signature, auth and permission model, request fields, response fields, validation rules, success status/result, important error cases, persistence/side effects, frontend or job consumers, and required API/integration tests. Do not provide endpoint conclusions that the design has not established; ask the lane to derive exact contracts from the accepted design and codebase context.
 
 ### Step 6: Owner Reviews Design and API Spec Together
 

package/assets/skills/scaffold-guidance/SKILL.md

@@ -39,7 +39,13 @@ Use casual, direct language. Example:
 ```text
 Let's start with the scaffold. Set up the base project in ./repo for the stack described in docs/design.md. Keep this to the framework, runtime, tests, and README foundation with a minimal proof page or endpoint. Do not add product-specific business logic yet.
 
+The cloned folder may contain placeholder docs, README text, scripts, or config. Remove or replace unrelated placeholder content instead of preserving it.
+
 The scaffold needs a working docker-compose.yml with a profile-gated test service, a run_tests.sh that runs the full test suite through Docker, a separate stack-native local test harness for fast implementation-time checks, a unit_tests directory for unit tests, an API_tests directory for API and integration HTTP tests, and a README baseline with startup, access, verification, and test commands. Make sure the local harness is separate from the Docker test path. The local harness is for fast iteration. run_tests.sh is the broad dockerized verification wrapper for later.
+
+The README needs to be enough for a reviewer to run and verify the project later: project type near the top, what the repo delivers, stack, repo layout, primary startup/access command, legacy docker-compose compatibility string when Docker Compose is used, verification method, auth/demo credentials or "No authentication required", seeded data or empty-state note, mock/local/debug disclosures, known limitations, and the Dockerized ./run_tests.sh contract. Do not leave template placeholders in README.
+
+The run_tests.sh and Docker config must be real, not placeholders: run_tests.sh should execute the broad Docker-contained test path, docker-compose.yml should include the app services needed for runtime and a profile-gated test service, and the local test harness should remain separate for fast implementation-time checks.
 ```
 
 Adjust the exact wording to the project. Do not over-format the message.

package/assets/skills/submission-packaging/SKILL.md

@@ -11,8 +11,8 @@ Packaging is a final-delivery contract, not a reporting exercise. Do not close P
 
 ## Package Boundary
 
-- Package root is `task/`.
-- Product repo is `task/repo`.
+- Package root is the task root directory (named by the task-id from `../.ai/metadata.json`'s `task_root` field).
+- Product repo is `<task-root>/repo`.
 - Workflow-private state remains outside package under `../.ai`, `../.beads`, and `../claude-sessions.zip`.
 - Do not package workflow-private state as product files.
 - The final task-root package allowlist is `docs/`, `repo/`, `.tmp/`, `metadata.json`, plus explicit VCS/validation exceptions.
@@ -81,7 +81,7 @@ Do not run broad Docker prune commands that can affect unrelated projects.
 ## Session Export
 
 - Export tracked developer sessions before closing packaging.
-- Claude-backed lanes produce `../claude-sessions.zip` as a sibling handoff artifact, not as a product file under `task/`.
+- Claude-backed lanes produce `../claude-sessions.zip` as a sibling handoff artifact, not as a product file under the task root.
 - Use packaged session export utilities when available and preserve prompt-anchored session provenance.
 - Verify exported session content is anchored to the original prompt from `./metadata.json` strongly enough to support package lineage.
 - Do not manually edit, rewrite, fabricate, rename, clean, delete, or restructure raw session/trajectory files to make the package look cleaner. Only use packaged export/normalization utilities that preserve provenance.

package/assets/slopmachine/phase-1-design-prompt.md

@@ -1,6 +1,6 @@
 You are helping create the product/system design for a software project.
 
-The original prompt, stack and context, accepted clarifications, and accepted requirements have already been provided in the previous steps. The design template is already seeded at ./docs/design.md.
+The original prompt, stack and context, accepted clarifications, and accepted requirements have already been provided in the previous steps. The task root may contain placeholder docs from the cloned starting repository; inspect them, keep only relevant true information, and replace unrelated placeholder content.
 
 Your task is to write `./docs/design.md`.
 
@@ -10,6 +10,22 @@ This is planning/design work only. Do not write implementation code.
 
 Produce a design document that is faithful to the original prompt and accepted clarifications. The design should be specific enough to guide implementation, but it must not become a step-by-step execution checklist.
 
+## Expected Shape
+
+Use clear sections that cover these surfaces where applicable:
+- project overview: project type, delivery shape, business objective, success outcome, and stack summary
+- prompt and clarification alignment: accepted requirements, accepted clarifications, safe assumptions, and explicit non-goals that do not narrow the prompt
+- actors, roles, permissions, and the main user/system flows
+- module design: purpose, owned behavior, UI/API/job surfaces, data ownership, failure/security cases, and required test surfaces
+- data design: entities/objects, lifecycle rules, visibility, and access rules
+- UI or interaction design, or a brief not-applicable reason
+- API or interface design, including whether `./docs/api-spec.md` is required
+- security and privacy design: auth, authorization, object isolation, sensitive data, logging/redaction, debug/admin protection, file/path safety, and abuse prevention where relevant
+- runtime and configuration design: runtime model, configuration model, persistence, seed/demo data, external integrations, and README startup/access/auth expectations
+- verification strategy: unit, API/integration, E2E/platform, frontend component, frontend-to-backend, README/runtime, Docker, and known proof boundaries
+- API spec handoff: whether a separate API spec is required and which API/interface families it must cover
+- remaining design risks that still need a decision
+
 ## Required Design Qualities
 
 The design must:
@@ -39,6 +55,6 @@ The design should define what the system must be and how its major parts fit tog
 
 ## Output
 
-Write the completed design to `./docs/design.md` using the template already seeded at that path. If a section is not applicable, keep it brief and explain why.
+Write the completed design to `./docs/design.md`. If a placeholder file already exists there, replace unrelated placeholder content rather than preserving it. If a section is not applicable, keep it brief and explain why.
 
 If the project has meaningful APIs or interface contracts, say that `./docs/api-spec.md` should be completed next and summarize the API families that need specification.

package/assets/slopmachine/utils/README.md

@@ -13,7 +13,7 @@ The current type-check gate covers the Claude/session tooling family because the
 
 ## Path Model
 
-- `--task-root` means the workflow task root, usually `<workflow-root>/task`.
+- `--task-root` means the workflow task root directory (named by the task-id from `../.ai/metadata.json`'s `task_root` field).
 - Product code lives under `<task-root>/repo`.
 - Workflow-private state lives outside task root under `<workflow-root>/.ai` and `<workflow-root>/.beads`.
 - Claude project lookup uses the task root because Claude transcripts are keyed by the working directory used to launch Claude.
@@ -115,10 +115,10 @@ Required:
 - `--task-root <task-root>`
 
 Important options:
-- `--output <zip-path>` writes the zip to a custom path; default is `<task-root>/claude-sessions.zip`
+- `--output <zip-path>` writes the zip to a custom path; default is `<workflow-root>/claude-sessions.zip`
 - `--label <text>` adds reporting context
 
-The helper copies the Claude project/session directory as-is, removes `.DS_Store` files and top-level `.jsonl` transcripts under 25KB from the staged copy, zips the folder contents directly, and writes a single zip. It does not normalize or rewrite transcript files.
+The helper copies the Claude project/session directory as-is into a temp directory, removes `.DS_Store` files and top-level `.jsonl` transcripts under 25KB from the staged copy, zips the whole copied folder, and writes a single zip. It does not normalize or rewrite transcript files.
 
 ### `analyze_claude_project_dir.mjs`
 

package/assets/slopmachine/utils/claude_live_common.mjs

@@ -546,13 +546,13 @@ export async function waitForHookEvent(paths, startIndex, labels, timeoutMs, mat
   return waitFor(async () => {
     const events = await readJsonl(paths.hookEventsFile)
     const pending = events.slice(startIndex)
-    const match = pending.find((event) => labels.has(event.label) && (!matcher || matcher(event)))
-    if (!match) {
+    const matchIndex = pending.findIndex((event) => labels.has(event.label) && (!matcher || matcher(event)))
+    if (matchIndex === -1) {
       return null
     }
     return {
-      event: match,
-      eventsLength: events.length,
+      event: pending[matchIndex],
+      eventsLength: startIndex + matchIndex + 1,
     }
   }, {
     timeoutMs,

package/assets/slopmachine/utils/claude_live_turn.mjs

@@ -23,6 +23,7 @@ import {
   readState,
   tmuxHasSession,
   tmuxPasteFileAndEnter,
+  tmuxSendEnter,
   waitForRateLimitReset,
   waitForHookEvent,
   writeState,
@@ -50,6 +51,8 @@ const runtimeDir = argv['runtime-dir']
 const promptFile = typeof argv['prompt-file'] === 'string' ? argv['prompt-file'].trim() : ''
 const turnTimeoutMs = Number.parseInt(argv['timeout-ms'] || String(DEFAULT_TURN_TIMEOUT_MS), 10)
 const retryOnLimit = argv['retry-on-limit'] !== '0'
+const SUBMIT_CONFIRM_TIMEOUT_MS = 5000
+const SUBMIT_ENTER_RETRIES = 3
 
 if (!runtimeDir || !promptFile) {
   emitFailure('claude_live_turn_invalid_args', 'Missing required turn arguments', {
@@ -70,6 +73,38 @@ function emitTurnFailure(resultPayload) {
   })
 }
 
+async function confirmPromptSubmitted({ paths, hookStartIndex, turnId, tmuxSession, runtimeDir, turnDir }) {
+  let currentHookStartIndex = hookStartIndex
+  for (let attempt = 0; attempt <= SUBMIT_ENTER_RETRIES; attempt += 1) {
+    try {
+      const { eventsLength } = await waitForHookEvent(
+        paths,
+        currentHookStartIndex,
+        new Set(['UserPromptSubmit']),
+        SUBMIT_CONFIRM_TIMEOUT_MS,
+        (hookEvent) => hookEvent?.turn_id === turnId,
+      )
+      await writeState(runtimeDir, {
+        current_turn_prompt_submitted_at: new Date().toISOString(),
+        current_turn_submit_enter_retries: attempt,
+      })
+      return { ok: true, eventsLength }
+    } catch {
+      if (attempt === SUBMIT_ENTER_RETRIES) {
+        break
+      }
+      await tmuxSendEnter(tmuxSession)
+      await writeState(runtimeDir, {
+        current_turn_submit_enter_retries: attempt + 1,
+      })
+    }
+  }
+
+  const blockerFile = path.join(turnDir, `prompt-submit-unconfirmed-pane-${Date.now()}.txt`)
+  await captureTmuxPaneArtifact(tmuxSession, blockerFile)
+  return { ok: false, blockerFile }
+}
+
 try {
   const promptSource = path.resolve(promptFile)
 
@@ -237,6 +272,34 @@ try {
       current_turn_prompt_injected_at: new Date().toISOString(),
     })
 
+    const submitConfirmation = await confirmPromptSubmitted({
+      paths,
+      hookStartIndex,
+      turnId,
+      tmuxSession: liveState.tmux_session || state.tmux_session,
+      runtimeDir,
+      turnDir,
+    })
+    if (!submitConfirmation.ok) {
+      const resultPayload = buildFailureResult('claude_prompt_submit_unconfirmed', 'Claude prompt was pasted, but UserPromptSubmit did not fire after repeated Enter sends', liveState.sid || state.sid)
+      await writeTurnArtifacts(paths, turnId, prompt, resultPayload, argv['result-file'] || null)
+      await writeState(runtimeDir, {
+        status: 'failed',
+        current_turn_id: null,
+        current_turn_prompt_file: null,
+        current_turn_prompt_source: null,
+        current_turn_started_at: null,
+        current_turn_transport: 'tmux-paste-buffer',
+        last_completed_turn_id: turnId,
+        last_turn_number: turnNumber + 1,
+        last_error: resultPayload.msg,
+        prompt_submit_unconfirmed_pane_file: submitConfirmation.blockerFile,
+      })
+      emitTurnFailure(resultPayload)
+      process.exit(1)
+    }
+    hookStartIndex = submitConfirmation.eventsLength
+
     const { event, eventsLength } = await waitForHookEvent(
       paths,
       hookStartIndex,

package/assets/slopmachine/utils/package_claude_session.mjs

@@ -18,7 +18,7 @@ Required:
   --task-root <task-root>
 
 Options:
-  --output <zip-path>             Zip output path (default: <task-root>/claude-sessions.zip)
+  --output <zip-path>             Zip output path (default: <workflow-root>/claude-sessions.zip)
   --label <text>                 Optional package label for reporting
 `)
 }
@@ -168,7 +168,7 @@ try {
   }
 
   const sourceProjectDir = await resolveClaudeProjectDir(taskRoot)
-  const outputPath = argv.output ? path.resolve(argv.output) : path.join(taskRoot, 'claude-sessions.zip')
+  const outputPath = argv.output ? path.resolve(argv.output) : path.join(path.dirname(taskRoot), 'claude-sessions.zip')
   const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'slopmachine-claude-project-'))
   const packageRoot = path.join(tempRoot, path.basename(sourceProjectDir))
 
@@ -177,7 +177,7 @@ try {
     await removeDsStoreFiles(packageRoot)
     const tinyRootTranscriptsRemoved = await removeTinyRootTranscripts(packageRoot)
     const included = (await listFilesRecursive(packageRoot)).sort((left, right) => left.localeCompare(right))
-    await createZipArchive(packageRoot, outputPath)
+    await createZipArchive(tempRoot, outputPath)
 
     emitSuccess(path.basename(sourceProjectDir), {
       output: outputPath,
@@ -185,7 +185,7 @@ try {
       label: argv.label || null,
       included,
       tiny_root_transcripts_removed: tinyRootTranscriptsRemoved,
-      packaging_mode: 'raw_claude_project_dir',
+      packaging_mode: 'raw_claude_project_dir_folder',
     })
   } finally {
     await fs.rm(tempRoot, { recursive: true, force: true }).catch(() => {})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "theslopmachine",
-  "version": "1.0.22",
+  "version": "1.0.25",
   "description": "SlopMachine installer and project bootstrap CLI",
   "license": "MIT",
   "type": "module",

package/src/cli.js

@@ -10,7 +10,7 @@ function printHelp() {
 Commands:
   setup     Configure slopmachine in the local user environment
   upgrade   Install slopmachine@latest globally and rerun setup
-  init      Bootstrap a workspace (--claude seeds CLAUDE.md, --opencode seeds AGENTS.md, --adopt wraps existing project, -o opens OpenCode)
+  init <github-url> Clone a task repository into the current workflow root and bootstrap workflow state (-o opens OpenCode)
   cleanup   Remove/archive obsolete installed agents, skills, and assets (--dry-run previews)
   set-token Store the upload token in machine config
   send-data Upload workflow artifacts to Supabase

package/src/constants.js

@@ -44,12 +44,10 @@ export const REQUIRED_SLOPMACHINE_FILES = [
   "clarifier-agent-prompt.md",
   "clarification-faithfulness-review-prompt.md",
   "phase-1-design-prompt.md",
-  "phase-1-design-template.md",
   "phase-2-execution-planning-prompt.md",
   "phase-2-plan-template.md",
   "test-coverage-prompt.md",
   "owner-verification-checklist.md",
-  "exact-readme-template.md",
   "workflow-init.js",
   "templates/AGENTS.md",
   "templates/CLAUDE.md",