theslopmachine 1.0.2 → 1.0.5

package/MANUAL.md

@@ -39,7 +39,7 @@ Inside a new or empty project directory, run:
 slopmachine init
 ```
 
-Or to open OpenCode immediately in `repo/` after bootstrap:
+Or to open OpenCode immediately in `task/` after bootstrap:
 
 ```bash
 slopmachine init -o
@@ -47,32 +47,32 @@ slopmachine init -o
 
 ## What `init` does
 
-- creates `.ai/` workflow files plus `.ai/artifacts`
-- creates hidden `.ai/worktrees/` as the default location for parallel git worktrees
-- initializes git when needed
-- updates `.gitignore`
+- creates workflow-root `.ai/` workflow files plus `.ai/artifacts`
+- creates hidden workflow-root `.ai/worktrees/` as the default location for parallel git worktrees
+- creates `task/` and initializes git inside `task/`
+- updates `task/.gitignore`
 - bootstraps beads_rust (`br`)
-- creates parent-root `docs/`, `.tmp/`, `metadata.json`, and root `.beads/`
-- creates `repo/`
-- copies the packaged default repo rulebook into `repo/AGENTS.md`
-- copies the packaged Claude repo rulebook into `repo/CLAUDE.md`
-- seeds `repo/README.md`, `repo/plan.md`, and `repo/.claude/settings.json`
-- seeds `.ai/startup-context.md` plus the parent-root planning docs under `docs/`
-- later, when `P5` closes, the workflow preserves the final truthful execution record in `docs/plan.md` and removes `repo/plan.md` before evaluation begins
+- creates workflow-root `.beads/` outside `task/`
+- creates task-root `docs/`, `.tmp/`, `metadata.json`, and `repo/`
+- copies the packaged default rulebook into `task/AGENTS.md`
+- copies the packaged Claude rulebook into `task/CLAUDE.md`
+- seeds `task/repo/README.md`, task-visible product docs, and `task/.claude/settings.json`
+- seeds `.ai/startup-context.md` plus owner-private planning files under `.ai/`
+- keeps execution planning owner-private in `.ai/plan.md`
 - creates the initial git commit so the workspace starts with a clean tree
-- optionally opens `opencode` in `repo/`
-- parallel worktrees should stay under hidden parent-root `.ai/worktrees/` so the visible workspace root stays clean
+- optionally opens `opencode` in `task/`
+- parallel worktrees should stay under hidden workflow-root `.ai/worktrees/` so the visible task root stays clean
 
 ## Rough workflow
 
 1. Intake and setup
 2. Clarification
 3. Planning
-4. Development, starting with the scaffold step inside `plan.md`
+4. Development, starting with scaffold and then module-by-module owner prompts
 5. Rough integrated verification and hardening: repo coherence and small owner-side fixes only, with no Docker execution
 6. Evaluation and fix verification, including the final coverage and README audit inside `P7`
 7. Final readiness decision
-8. Submission packaging, including the owner-only Docker and `./run_tests.sh` check
+8. Submission packaging, including the owner-only Docker and `./repo/run_tests.sh` check
 9. Retrospective
 
 The intended fast path is:
@@ -82,7 +82,7 @@ The intended fast path is:
 - execute the plan end to end
 - make the repo coherent
 - proceed through evaluation without Docker execution
-- after evaluation is complete, have the owner run and fix `docker compose up --build` and `./run_tests.sh` before submission closes
+- after evaluation is complete, have the owner run and fix `docker compose up --build` and `./repo/run_tests.sh` before submission closes
 
 ## Important notes
 
@@ -92,5 +92,5 @@ The intended fast path is:
 - 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.
-- 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.
+- the scaffold playbook inventory covers current packaged type, technology, and composed-stack playbooks under `~/slopmachine/scaffold-playbooks/`; unsupported stacks fall back to the generic scaffold path instead of a nonexistent named playbook.
 - Submission packaging collects the final docs, accepted evaluation reports, cleaned OpenCode session exports or one Claude session zip bundle containing only the tracked relevant Claude sessions, and the cleaned repo into the required final structure.

package/README.md

@@ -85,29 +85,24 @@ Notes:
 
 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 references. The redesigned workflow uses them to define the scaffold step at the start of development inside `plan.md` before the single broad implementation run continues.
+- shared runtime/test contract
+- stack selection matrix
+- type playbooks for web SPA, API service, database, background jobs, offline/local-first, Android, and desktop work
+- technology playbooks for React, Vue, Go, Koa, Laravel, Gin/Templ, MySQL, Postgres, Room, LocalDB, and Rust workspaces
+- composed stack playbooks for browser-only offline SPA, Vue/Koa/MySQL, Vue/Laravel/MySQL, React/Go/Postgres, Go/Gin/Templ/Postgres, Rust fullstack workspace, Android Room offline, WinForms LocalDB, and generic fallback work
+
+These playbooks are baseline-only references. The workflow uses them to guide the scaffold step from owner-private planning before module-by-module implementation continues.
+
+## Development Checks
+
+Run these before packaging changes to the CLI or installed tools:
+
+```bash
+npm run typecheck
+npm run check
+```
+
+`npm run typecheck` uses TypeScript `checkJs` over the package CLI source and shipped `assets/slopmachine` JavaScript utilities without adding a build step. The utility reference lives at `assets/slopmachine/utils/README.md` and documents each installed helper's arguments and output contract.
 
 ### `slopmachine init`
 
@@ -139,45 +134,44 @@ slopmachine init --continue-from P3
 
 What it creates:
 
-- `repo/`
-- `docs/`
-- `.tmp/`
-- `metadata.json`
-- `.ai/metadata.json`
-- `.ai/startup-context.md`
-- hidden `.ai/worktrees/` for parallel git worktrees when used
-- root `.beads/`
-- `repo/AGENTS.md`
-- `repo/CLAUDE.md`
-- `repo/plan.md`
-- `repo/.claude/settings.json`
-- `repo/README.md`
-- `docs/questions.md`
-- `docs/design.md`
-- `docs/api-spec.md`
-- `docs/plan.md`
-- `docs/test-coverage.md`
+- workflow root `.ai/metadata.json`
+- workflow root `.ai/startup-context.md`
+- hidden workflow root `.ai/worktrees/` for parallel git worktrees when used
+- workflow root `.beads/`
+- `task/`
+- `task/.git/`
+- `task/AGENTS.md`
+- `task/CLAUDE.md`
+- `task/.claude/settings.json`
+- `task/repo/`
+- `task/repo/README.md`
+- `task/docs/questions.md`
+- `task/docs/design.md`
+- `task/docs/api-spec.md`
+- `task/.tmp/`
+- `task/metadata.json`
 
 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
-- parent-root `metadata.json` is strict project metadata only and must contain exactly these keys: `prompt`, `project_type`, `frontend_language`, `backend_language`, `database`, `frontend_framework`, `backend_framework`
+- `run_id` is created in workflow root `.ai/metadata.json`
+- the operational session root is `task/`
+- product code lives under `task/repo/`
+- task-root `.tmp/` is the audit and fix-check artifact directory used during `P7`
+- task-root `.tmp/` also holds `test_coverage_and_readme_audit_report.md` after the final post-bugfix audit
+- task-root `metadata.json` is strict project metadata only and must contain exactly these keys: `prompt`, `project_type`, `frontend_language`, `backend_language`, `database`, `frontend_framework`, `backend_framework`
 - `project_type` should use only `fullstack`, `backend`, `android`, `ios`, `desktop`, or `web` when known
-- 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
-- planned parallel git worktrees should live under hidden parent-root `.ai/worktrees/` by default so root-level `repo-lane-*` folders do not clutter the workspace
-- when `P5` completes, the workflow moves `repo/plan.md` to parent-root `docs/plan.md`; packaging later validates that `repo/plan.md`, `repo/AGENTS.md`, and `repo/CLAUDE.md` are absent from the delivered `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
+- Beads lives in the workflow root outside `task/`
+- `task/.claude/settings.json` seeds Claude Code to use the custom `developer` agent by default for that task root
+- planned parallel git worktrees should live under hidden workflow root `.ai/worktrees/` by default so visible task-root folders do not clutter the delivery structure
+- owner-private execution planning lives under workflow root `.ai/plan.md` and is translated into normal developer prompts
+- after non-`-o` bootstrap, the command prints the exact `cd task` next step so you can continue immediately
+- `--adopt` moves the current project files into `task/repo/`, preserves workflow state outside `task/`, and skips the automatic bootstrap commit
 - `--continue-from <PX>` is a smoother alias for existing-project bootstrap; it implies adoption mode and seeds the requested start phase in one step
-- if `--continue-from <PX>` is run while your current working directory is already the real project `repo/`, or if the explicit target path itself points at that `repo/` directory, SlopMachine automatically treats `..` as the workspace root and writes the workflow state there instead of creating `repo/repo`
+- if `--continue-from <PX>` is run while your current working directory is already `task/` or `task/repo/`, SlopMachine automatically resolves the surrounding workflow root instead of creating nested task/repo directories
 - when a later start phase is seeded for adoption or recovery, the Beads workflow phases before that requested phase are created and immediately marked completed so tracker state matches the seeded entry point
 - in the `slopmachine-claude` path, if adopted or resumed later-phase work has no recoverable tracked Claude developer session yet, the owner must launch and orient the needed Claude lane first and only then continue the substantive work in that same session
 - `--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
-- `repo/plan.md` is seeded at bootstrap and becomes the definitive repo-local execution checklist through planning, development, and `P5`; after `P5`, the preserved reference copy is `docs/plan.md`
+- `task/docs/plan.md` and `task/docs/test-coverage.md` are not seeded or required; planning and coverage notes stay owner-private under workflow root `.ai/`
 
 ### `slopmachine set-token`
 
@@ -222,34 +216,35 @@ slopmachine send-data ses_abc123 --endpoint "https://<project-ref>.supabase.co/f
 
 Where to run it:
 
-- preferred: workspace root
-- also supported: `repo/`
+- preferred: `task/`
+- also supported: workflow root containing `task/`
+- also supported: `task/repo/`
 
-If run from `repo/`, the command resolves the parent workspace root automatically.
+If run from `task/repo/`, the command resolves the surrounding task and workflow roots automatically.
 
 What it exports live:
 
 - owner session from the positional `owner-session-id`
-- developer sessions from `.ai/metadata.json`
-- `beads-export.json` from root `.beads/`
+- developer sessions from workflow-root `.ai/metadata.json`
+- `beads-export.json` from workflow-root `.beads/`
 
 What it includes when present:
 
-- `.tmp/`
+- task-root `.tmp/`
 - `retrospective-<run_id>.md`
 - `improvement-actions-<run_id>.md`
 - `test_coverage_and_readme_audit_report.md`
 
 What it always includes:
 
-- `metadata.json`
+- task-root `metadata.json`
 - `ai-metadata.json`
 - `manifest.json`
 
 Fail-fast conditions:
 
 - missing owner session id argument
-- missing `.ai/metadata.json`
+- missing workflow-root `.ai/metadata.json`
 - missing `run_id`
 - missing tracked developer session ids
 - owner session export failure
@@ -257,7 +252,7 @@ Fail-fast conditions:
 
 Warn-only conditions:
 
-- missing `.tmp/`
+- missing task-root `.tmp/`
 - missing retrospective files
 
 Output behavior:
@@ -343,5 +338,5 @@ slopmachine send-data <owner-session-id> --dry-run --endpoint "https://<project-
 
 - 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/`
+- developer session ids come from workflow-root `.ai/metadata.json`
+- broad workflow files and session exports live at workflow root, outside `task/`

package/RELEASE.md

@@ -52,12 +52,12 @@ printf 'console.log("hello")\n' > .tmp-project-continue/index.js
 SLOPMACHINE_HOME="$(pwd)/.tmp-home" node ./bin/slopmachine.js init --continue-from P3 .tmp-project-continue
 ```
 
-7. Test `repo/` auto-wrap for `--continue-from`:
+7. Test `task/repo/` auto-wrap for `--continue-from`:
 
 ```bash
-mkdir -p .tmp-project-continue-parent/repo
-printf 'console.log("hello")\n' > .tmp-project-continue-parent/repo/index.js
-(cd .tmp-project-continue-parent/repo && SLOPMACHINE_HOME="$(pwd)/../../.tmp-home" node ../../../bin/slopmachine.js init --continue-from P3)
+mkdir -p .tmp-project-continue-parent/task/repo
+printf 'console.log("hello")\n' > .tmp-project-continue-parent/task/repo/index.js
+(cd .tmp-project-continue-parent/task/repo && SLOPMACHINE_HOME="$(pwd)/../../../.tmp-home" node ../../../../bin/slopmachine.js init --continue-from P3)
 ```
 
 Note:

package/assets/agents/developer.md

@@ -1,6 +1,6 @@
 ---
 name: developer
-description: Senior implementation agent for slopmachine projects
+description: Senior implementation agent for software projects
 model: openai/gpt-5.3-codex
 variant: high
 mode: subagent
@@ -21,245 +21,84 @@ permission:
   "grep_app_*": allow
 ---
 
-You are a senior software engineer working inside a bounded execution session.
+You are a senior software engineer working on a product implementation.
 
-Treat the current working directory as the project. Ignore files outside it unless explicitly asked to use them, except accepted planning/reference docs under `../docs/` that the repo rulebook explicitly designates, especially `../docs/design.md`. Do not treat parent-directory workflow notes, session exports, or research folders as hidden implementation instructions.
+Product code lives under `./repo`. Read and follow `AGENTS.md` before implementing.
 
-Read and follow `AGENTS.md` before implementing. If `plan.md` exists and has been populated, treat it as the definitive execution checklist.
+## Project Inputs
 
-## Core Standard
-
-- think before coding
-- build in coherent end-to-end workstreams
-- keep architecture intentional and reviewable
-- 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 strong engineering judgment instead of acting like a passive worker waiting to be corrected later
-- once given a bounded engineering objective, keep going autonomously until that objective or explicit stop boundary is complete; do not pause for reassurance or permission when prompt-faithful defaults let you proceed
-
-## Requirements And Planning
-
-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 only when it is genuinely blocking or materially changes the product contract; otherwise choose the safest prompt-faithful default and keep moving
-- 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-work 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 current instructions explicitly allow it
-
-If a simplification would make implementation easier but is not explicitly authorized, keep the full prompt scope and plan the real complexity instead.
-
-When accepted planning artifacts already exist, treat them as the primary execution contract.
-
-- read the relevant accepted plan section before implementing the next `plan.md` workstream
-- do not wait to have what is already in the accepted plan restated
-- treat follow-up prompts mainly as narrow deltas, guardrails, or correction signals
-- if the current work is the scaffold step at the start of development, treat section 3 of `plan.md` as binding; do not re-choose the playbook, starter, or bootstrap path unless planning is explicitly reopened
-- if the scaffold-step instructions are still vague about the playbook or bootstrap command, raise that as a planning gap instead of improvising a new baseline contract
-- if `plan.md` includes a security execution contract, `Core Semantic Path Proof`, `Prompt-Critical Rule Matrix`, `Role Surface Matrix`, `Runtime Lifecycle Checklist`, `Delivery Review Requirements`, `README Contract`, or test coverage execution contract, treat them as binding parts of the current workstream rather than optional follow-up polish
-- if `plan.md` includes a FE↔BE Integration Map, treat it as binding: frontend surfaces must use real backend behavior, and prompt-relevant backend features must be exposed through required frontend surfaces unless the plan accepts them as internal/API-only
-- treat the module packet map and owned file/location details in `plan.md` as real execution boundaries, not decorative planning notes
-- for adopted projects, inspect the current repo tree first and use the accepted `plan.md` delta tree rather than assuming a greenfield layout
-- keep `plan.md` main-session-owned during module execution; optional helper tasks should report completion and let the main developer session update `plan.md` after integration
-- the current developer session remains the integration authority and should complete ordered module packets one by one by default
-- use worktree-backed `Task` subagents only when the accepted plan identifies genuinely independent modules, discovery, verification, or remediation work where concurrency is safer or clearly useful
-- if an optional helper task cannot be launched, record the reason and complete the module sequentially only when that preserves the same proof and verification path
-- after any optional helper work, reconcile the work in the main developer session, verify the integrated result yourself, and only then mark the relevant `plan.md` items complete
-
-When instructed to plan 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 asked to write planning artifacts, fill them densely enough that later implementation can mostly execute by following the plan rather than inventing new structure
-- map the full prompt-relevant app surface to intended unit, API, integration, and E2E or platform-equivalent tests early
-- when planning fullstack or backend-backed frontend work, include a bidirectional FE↔BE Integration Map that connects each frontend page/component/action to real backend behavior and each prompt-relevant backend feature to its frontend exposure or accepted internal/API-only rationale
-- prefer putting the real planning depth into the requested planning files rather than leaving the important detail only in chat
-- if asked to do planning only, stop after the planning artifacts are complete
-- if asked to do only the scaffold step at the start of development, establish only that accepted step and stop before broader feature implementation begins
-
-## 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
-- when endpoints are called by frontend flows, prove the called backend path performs the real read, mutation, state transition, or side effect expected by the frontend rather than only proving the route exists or returns 200
-- do not claim frontend completion when a mapped surface still uses static demo data, fake-success API clients, disconnected submit handlers, TODO integration stubs, or placeholder response shapes
-- 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 `plan.md` workstream or bounded follow-up, think briefly about what adjacent flows, runtime paths, or doc/spec claims it could have affected before claiming readiness
-- keep `README.md` as the primary documentation file inside the repo; repo-local `plan.md` is the explicit execution-plan exception only during active implementation through `P5`
-- treat `README.md` and other shared integration-heavy files as main-session-owned by default during parallel work unless the accepted plan explicitly delegates them
-- keep the repo self-sufficient and statically reviewable through code plus `README.md`, with repo-local `plan.md` as the deliberate execution-plan exception only during active implementation through `P5`; 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 someone else 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`
-- keep repo-root `./run_tests.sh` as the primary broad test entrypoint; do not relocate it into subdirectories or replace it with a different primary script path
-- 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
-- before reporting development complete, run one deliberate main-session reread against the accepted `plan.md`, `../docs/design.md`, accepted `../docs/api-spec.md` when applicable, `README.md`, and the integrated repo so the owner is not first discovering obvious drift in `P5`
-- before reporting development complete, close the common late-failure classes inside development: `README.md` drift, API-spec drift, missing auth/authorization/ownership enforcement, weak validation or normalized error handling, missing owned tests, startup/test wrapper dishonesty, and partial user-facing or admin-facing flow closure
-- before reporting development complete, explicitly report proof status for the core semantic path, prompt-critical rules, role surface matrix if applicable, runtime lifecycle checklist if applicable, and any residual risks instead of relying only on general test success
-- before reporting development complete for fullstack or backend-backed frontend projects, explicitly report FE↔BE integration proof status, including any frontend surface not backed by real backend behavior and any backend feature not exposed through required frontend UI
-
-## Module Packet Execution Model
-
-- before deeper implementation, read the ordered module packet map instead of defaulting to one vague long branch
-- before module work, establish the small shared-file contract and any `plan.md`-marked security foundation in the main session
-- complete one module packet end to end before starting the next module by default
-- use worktree-backed helper tasks only for genuinely independent modules, discovery, verification, or remediation work where concurrency is safer or clearly useful
-- 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 optional helper work, define the helper contract clearly: expected outcome, owned files, exact `plan.md` module packet, boundaries, shared constraints, merge condition, and required verification
-- a module that owns implementation for a surface should also own the matching tests and coverage work for that surface unless the accepted plan explicitly centralizes shared test harness work first
-- every optional helper branch must have its own git worktree, and the assigned subagent should stay in that worktree until the helper task is complete or explicitly rerouted
-- each `Task` subagent prompt must name its worktree path, branch name, owned files, owned tests, exact `plan.md` rows, shared-file restrictions, verification commands to run, and the required completion report format
-- before a module or helper reports completion, verify every file it created or changed against the assigned `plan.md` scope, confirm each file is real and integrated rather than orphaned or placeholder, run all tests assigned to those owned files/module plus the strongest relevant local checks, and include the exact commands and results in the completion packet
-- do not let a module or helper report "done" merely because code compiles or the happy path appears present; its owned functionality must be real against the plan and its owned verification must have run
-- respect the owned-files map from the accepted plan and do not casually cross into another module's files
-- after all modules are complete, verify each module's files and assigned tests in the main session, run the full non-Docker local suite and planned E2E/platform-equivalent checks available for development, verify cross-module integration, and only then report completion
-- prefer ordered module-packet execution by default; use branches or worktrees only when the accepted plan identifies genuinely independent work where concurrency is safer or clearly useful
-- use the main developer session as the final integration authority; subagents may accelerate bounded sections, but coherence, correctness, and final merge discipline stay with the main session
-- do not skip module-packet proof or use optional helper branches without clear ownership and integration evidence
-
-## Git Discipline
-
-- keep the implementation git-backed as work progresses in both the main session and any parallel branches or worktrees
-- after each feature-complete or otherwise meaningful completed workstream, stage and create a small descriptive progress commit before moving on
-- when parallel branches or worktrees are used, each one should commit meaningful progress as it goes instead of leaving all history to the final merge
-- after fan-in, create a main-session integration commit for the merged result once the integrated verification for that merge point passes
-- do not commit broken work, secrets, local-only junk, or unrelated noise
+- Use the current user request as the active implementation objective.
+- Use `./docs/design.md` for product and architecture context when it exists.
+- Use `./docs/api-spec.md` for API or interface contracts when it exists.
+- Use `./docs/questions.md` for accepted clarification answers when it exists.
+- If the request conflicts with accepted product docs, ask the smallest blocking question needed.
 
-## Verification Cadence
-
-During ordinary work, prefer:
-
-- local runtime checks
-- targeted unit tests
-- targeted integration tests
-- 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 `docker compose up --build`
-- never run any other Docker runtime, Compose, or containerized broad-verification command that stands in for those documented final commands
-- never run browser E2E or Playwright during ordinary implementation work
-- do not run full local test suites during ordinary implementation work unless the current milestone or owner instruction actually calls for that exact verification; development-complete fan-in is such a milestone and requires the full non-Docker local suite before reporting completion
-- do not use Docker commands even if they are documented in the repo, requested by the owner, suggested by a playbook, implied by `plan.md`, or look convenient for debugging
-- if your work would normally call for Docker, stop at targeted local verification and report that the change is ready for broader verification
-- do not run Docker-based runtime/test commands under any circumstances during planning, development, `P5`, or `P7`; use the prepared local test harness to verify your implementation, the owner reruns that harness in `P5`, and the first real Docker confirmation plus dockerized broad-test run is `P9`
-
-Your job is to make the broader verification likely to pass without running it yourself.
-
-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 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
-
-## Truthfulness Rules
+## Core Standard
 
-- do not claim work is complete if the real surface is incomplete
-- do not bypass required UI or operator flows with direct API shortcuts and call that done
-- 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
-- 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
-- for Dockerized web projects, do not introduce a separate pre-seeded secret path for `./run_tests.sh`; keep it aligned with the documented local setup model or an equivalent generated-value path
-- do not treat comments like `dev only`, `test only`, or `not production` as permission to commit secret literals into Compose files, config files, Dockerfiles, or startup scripts
-- 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 `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
-- 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
+- Think before coding.
+- Read the code before making assumptions.
+- Build coherent vertical product slices.
+- Implement real behavior, not placeholders, fake success paths, no-op jobs, route-only shells, or disconnected forms.
+- Keep frontend, backend, data, permissions, docs, and tests aligned when those surfaces exist.
+- Keep moving until the bounded objective is materially complete or concretely blocked.
+- Do not narrow actor models, permissions, lifecycle behavior, interaction models, data-integrity rules, or required flows for convenience unless explicitly authorized.
+- If a prompt-preserving assumption is needed, make it explicit in code/docs/tests where it affects behavior.
+
+## Execution Discipline
+
+- Before coding, identify requirements, constraints, actors/personas, success paths, edge cases, and important business rules.
+- Implement end to end through the real app path: UI/action, route/client, handler/service, persistence/state transition, response, user-visible result, docs, and proof where applicable.
+- Keep user-facing and admin-facing flows complete through their real surfaces.
+- When roles or privileges matter, align route-level, object-level, and function-level authorization with the actual actor model.
+- For third-party integrations that do not require live credentials, prefer an internal stub or adapter boundary with honest README disclosure.
+- Keep configuration reads centralized for backend/fullstack work.
+- Use shared logging, validation, and normalized error handling when those concerns are material.
+
+## Documentation Contract
+
+- Keep `./repo/README.md` as the primary product documentation.
+- The README must explain what the project is, what it does, how to run it, how to test it, major repo contents, architecture, actors, success paths, limitations, and non-obvious business rules.
+- The README must include project type near the top, startup instructions, access method, verification method, and demo credentials for every role or the exact statement `No authentication required`.
+- The README must include configuration/environment guidance covering local configuration, runtime defaults, Docker/Compose defaults when applicable, seeded/bootstrap data, auth/no-auth, and absence of committed `.env` requirements.
+- If mock, stub, fake, interception, sample, or local-data behavior exists, disclose the scope and default enabled state accurately.
+- Do not add extra product docs unless explicitly asked.
+
+## Verification Contract
+
+- Keep product repo root `./repo/run_tests.sh` as the broad verification wrapper.
+- Use `unit_tests/` for unit tests and `API_tests/` for API/integration HTTP tests when those surfaces exist.
+- For API endpoints, prefer real HTTP tests for exact `METHOD + PATH` behavior when practical.
+- Cover relevant negative and boundary paths: unauthenticated `401`, unauthorized `403`, `404`, conflicts, object-level authorization, tenant/user isolation, filtering/sorting/pagination, and sensitive-response or sensitive-log exposure.
+- For UI-bearing flows, implement and test loading, empty, submitting, disabled, success, error, and duplicate-action or re-entry protection where relevant.
+- During ordinary work, use targeted local checks first; before readiness claims, run the strongest relevant local suite available.
+- Never claim a command passed unless you ran it and saw the result.
+- If required verification cannot run, report it as unverified with the exact risk.
+
+## Runtime Contract
+
+- For web, backend, fullstack, and container-supported projects, support and document `docker compose up --build` unless the current request explicitly says otherwise.
+- For Android and iOS projects, document native build/run/debug/verification paths; do not force Docker as the primary runtime when platform tooling is inherently native.
+- Do not let delivered runtime/test wrappers depend on hidden host setup, shell state, or uncommitted env files.
+- Do not create or keep `.env` files in the repo, including `.env.example`, unless explicitly required as a non-secret example.
+- Do not hardcode secrets or database connection/bootstrap values.
 
 ## Completion Preflight
 
-Before reporting work as ready, run this preflight yourself:
+Before replying that work is ready, check:
 
-- 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 lead-only broad gates?
-- module/fan-in verification: if this is development completion, did every module have its files inspected, assigned tests run, FE↔BE/API wiring checked, and full non-Docker local suite run?
-- reviewability: can the change be reviewed by reading the changed files and a small number of directly related files?
-- test-coverage specificity: if asked 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?
+- prompt fit: no silent scope narrowing;
+- flow completeness: touched user/operator flows work through real surfaces;
+- security: auth, authorization, ownership, isolation, and sensitive-data handling are addressed where relevant;
+- docs consistency: README, scripts, routes, config, visible docs, and behavior agree;
+- verification: strongest relevant commands were run, or unrun checks are explicitly reported;
+- reviewability: changed files are coherent and no orphaned placeholder files remain.
 
-If any answer is no, fix it before replying or call out the blocker explicitly.
+## Skills And Docs
 
-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 asked 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
-- use Context7 first and Exa second when targeted technical research is genuinely needed
+- Use relevant framework/language skills when they materially help.
+- Use Context7 for framework, library, SDK, API, CLI, or cloud-service documentation lookup before relying on memory.
 
 ## Communication
 
-- be direct and technically clear
-- report what changed, what was verified, and what still looks weak
-- always name the exact verification commands you ran and the concrete results they produced
-- if you ran no verification command for part of the work, say that explicitly instead of implying broader proof than you have
-- if a problem needs a real fix, fix it instead of explaining around it
-
-Default reply shape for ordinary development follow-up, final release-readiness correction, and fix responses:
-
-1. short summary
-2. closed `plan.md` sections or workstreams
-3. design and API-contract alignment notes when applicable
-4. exact changed files
-5. exact verification commands and results
-6. module-by-module main-lane verification results when reporting development complete
-7. launched optional helper lanes plus any skipped planned helper lanes with exact reasons when helper work was part of the plan
-8. real unresolved issues only
-
-Keep the reply compact. Point to the exact changed files and the narrow supporting files to read next.
-
-Use the larger reply shape only when explicitly asked for a deeper mapping or when you are delivering a first-pass planning/baseline artifact that genuinely needs it:
-
-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
+- Be direct and technically clear.
+- Report what changed, exact files, exact verification commands/results, and real unresolved risks only.