theslopmachine 0.3.7 → 0.4.0

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

@@ -1,6 +1,6 @@
 ---
 name: developer-session-lifecycle
-description: Startup, canonical developer session persistence, recovery, and initial project structure rules for repo-cwd tracked development.
+description: Startup, primary developer-session persistence, recovery, and initial project structure rules for repo-cwd tracked development.
 ---
 
 # Developer Session Lifecycle
@@ -9,15 +9,16 @@ Use this skill during startup, tracked developer-session creation, and recovery.
 
 ## Usage rules
 
-- Load this skill before starting the canonical developer session.
+- Load this skill before starting the main developer session.
 - Load it again during any recovery or session-consistency check.
 - Treat it as internal orchestration guidance, not developer-visible text.
+- outside the initial clarification approval stop, do not use this skill to create extra pause points; startup should continue directly into development bootup once approval exists
 
-## Canonical developer session
+## Main developer session
 
 - use the current working directory as the live codebase and start the fresh developer session in it
 - ensure the parent project root has the required supporting structure, especially `../sessions/`
-- record the developer session id immediately in Beads
+- record the developer session id immediately in the tracker and `.ai/metadata.json`
 - persist the developer session id in more than one durable place
 - reuse that same session throughout development and remediation whenever possible
 - if the developer session crashes, resume it and continue the same work loop
@@ -41,35 +42,65 @@ Optional startup inputs may include:
 1. receive the prompt and stack context
 2. create `../.ai/metadata.json` for internal workflow state
 3. initialize parent-root `../metadata.json` with the required schema and store the full prompt text in `prompt`
-4. initialize root workflow state and top-level phase Beads
+4. initialize root workflow state and top-level phase tracker items
 5. complete clarification using the clarification skill
-6. stop for approval before development starts
-7. ensure the parent project root has the required working structure, especially `../sessions/`
-8. start the canonical developer session
+6. wait only for the initial clarification approval before development starts
+7. ensure the parent project root has the required working structure, especially `../sessions/` and `../docs/`
+8. start the main developer session
 9. send `Let's plan this project: <original-prompt>` as the first message in that session
 10. wait for the developer's first exchange
 11. send the approved clarification prompt as the next guidance message
 12. continue orchestration from there
 
+## Metadata and workflow files
+
+- the internal workflow mirror is `../.ai/metadata.json`
+- the internal clarification artifact is `../.ai/clarification-prompt.md`
+- the project artifact metadata file is `../metadata.json`
+- do not use `../metadata.json` as internal workflow scratch state
+
+Required internal workflow fields in `../.ai/metadata.json`:
+
+- `workflow_state`
+- `current_phase_item`
+- `session_id`
+- `clarification_approved`
+- `awaiting_human`
+- `remediation_round`
+
+Required project metadata fields in `../metadata.json`:
+
+- `prompt`
+- `project_type`
+- `frontend_language`
+- `backend_language`
+- `database`
+- `session_id`
+- `frontend_framework`
+- `backend_framework`
+
+- maintain `../metadata.json` as a real project artifact from the beginning of the workflow
+- fill known values immediately and keep the file current as the project becomes clearer
+- prefer explicit values; use `null` only when a field is genuinely unknown or not applicable
+
 ## Initial structure rule
 
-- during development, working technical docs live under the current working directory `docs/`
-- parent-root `../docs/` is a final delivery structure created or finalized during submission packaging
+- parent-root `../docs/` is the owner-maintained external documentation directory
+- do not treat repo-local `docs/` as the active documentation location in `v3`
 - parent-root `../sessions/` is the session artifact directory for exported conversation traces
 
 ## Recovery rule
 
 - orchestrator restart is handled externally
 - developer-session restart is your responsibility
-- on recovery, read root Bead metadata, `../.ai/metadata.json`, `../metadata.json`, current phase Bead, latest `SESSION:` comment, latest unresolved `ISSUE:` comments, and any persistent session record before continuing
+- on recovery, read `../.ai/metadata.json`, `../metadata.json`, current phase tracker item, latest `SESSION:` comment, latest unresolved `ISSUE:` comments, and any persistent session record before continuing
 - treat resume as deterministic state recovery, not guesswork
 
 ## Session persistence rule
 
-- store the canonical developer session id in root Bead metadata as `session_id`
-- mirror it in a `SESSION:` comment on the root Bead
+- store the main developer session id in the root tracker item comments using `SESSION:`
 - mirror it in `../.ai/metadata.json`
 - mirror it in parent-root `../metadata.json` as `session_id`
 - once created, treat that session id as locked unless an explicit reset policy is introduced later
 - if these records disagree, stop and resolve the inconsistency before continuing
-- do not silently create a replacement primary developer session if the canonical one can still be resumed
+- do not silently create a replacement main developer session if the existing one can still be resumed

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

@@ -0,0 +1,148 @@
+---
+name: developer-session-lifecycle-v2
+description: Startup, resume detection, metadata consistency, and developer-session recovery rules for slopmachine-v2.
+---
+
+# Developer Session Lifecycle v2
+
+Use this skill during `P0 Intake and Setup` and whenever startup or recovery state is uncertain.
+
+## Purpose
+
+- detect whether the run is new or resumed
+- initialize or recover workflow metadata consistently
+- initialize the planned bounded developer-session slots
+- recover the current active developer session when one already exists
+
+## Usage rules
+
+- keep startup and recovery in one skill; both begin from the same state inspection problem
+- treat this as internal orchestration guidance, not developer-visible text
+- do not launch the developer during `P0` or `P1`
+- do not use this skill to create extra approval stops beyond the two allowed human gates
+
+## State inspection sequence
+
+Inspect:
+
+- Beads root state and current phase
+- `../.ai/metadata.json`
+- `../metadata.json`
+- existing session comments or recorded session ids
+
+Decide whether the run is:
+
+- a fresh startup
+- a resumed run with consistent state
+- a run needing consistency repair before it can continue
+
+## Startup contract
+
+Expect to start from:
+
+- a project prompt
+- tech stack information when it is not already clear from the prompt
+
+Optional startup inputs may include:
+
+- task id
+- project type
+- explicit constraints or preferences
+
+## Startup flow
+
+1. receive the prompt and stack context
+2. create `../.ai/metadata.json` for internal workflow state
+3. initialize parent-root `../metadata.json` with the required schema and store the full prompt text in `prompt`
+4. initialize root workflow state and top-level phase Beads items
+5. complete clarification using the clarification skill
+6. wait only for the initial clarification approval before development starts
+7. ensure the parent project root has the required working structure, especially `../sessions/` and `../docs/`
+8. initialize the bounded developer-session slots
+9. start the build developer session only after `P2` is ready to begin
+10. send `Let's plan this project: <original-prompt>` as the first message in that session
+11. wait for the developer's first exchange
+12. send the approved clarification prompt as the next guidance message
+13. continue orchestration from there
+
+## Required startup outputs
+
+- root workflow state exists
+- `../.ai/metadata.json` exists
+- `../metadata.json` exists
+- planned developer session slots are initialized
+- required parent-root directories exist
+
+## Metadata and workflow files
+
+- the internal workflow mirror is `../.ai/metadata.json`
+- the internal clarification artifact is `../.ai/clarification-prompt.md`
+- the project artifact metadata file is `../metadata.json`
+- do not use `../metadata.json` as internal workflow scratch state
+
+## Suggested metadata fields
+
+Track at least:
+
+- `current_phase`
+- `awaiting_human`
+- `clarification_approved`
+- `remediation_round`
+- `developer_sessions`
+- `active_developer_session_index`
+
+Each planned developer session record should include enough to recover it later, such as:
+
+- `index`
+- `label`
+- `phase_group`
+- `session_id`
+- `status`
+- `handoff_in`
+- `handoff_out`
+
+Required project metadata fields in `../metadata.json` when relevant:
+
+- `prompt`
+- `project_type`
+- `frontend_language`
+- `backend_language`
+- `database`
+- `session_id`
+- `frontend_framework`
+- `backend_framework`
+
+- maintain `../metadata.json` as a real project artifact from the beginning of the workflow
+- fill known values immediately and keep the file current as the project becomes clearer
+- prefer explicit values; use `null` only when a field is genuinely unknown or not applicable
+
+## Bounded session model
+
+Track up to three planned developer sessions:
+
+1. build
+2. stabilization
+3. remediation
+
+Later session slots may remain unused if the workflow never needs them.
+
+## Initial structure rule
+
+- parent-root `../docs/` is the owner-maintained external documentation directory
+- parent-root `../sessions/` is the session artifact directory for exported conversation traces
+- do not treat repo-local `docs/` as the active external documentation location
+
+## Recovery rule
+
+- if session records disagree, stop and resolve the inconsistency before continuing
+- if the current phase already has an active developer session, recover that session instead of silently creating a new one
+- treat resume as deterministic recovery, not guesswork
+- on recovery, read `../.ai/metadata.json`, `../metadata.json`, current phase Beads item, latest `SESSION:` comment, latest unresolved `ISSUE:` comments, and any persistent session record before continuing
+
+## Session persistence rule
+
+- store the active developer session id in Beads comments using `SESSION:`
+- mirror it in `../.ai/metadata.json`
+- mirror the active session id in parent-root `../metadata.json` as `session_id`
+- if these records disagree, stop and resolve the inconsistency before continuing
+- do not silently create a replacement developer session if the intended existing one can still be resumed

package/assets/skills/development-guidance-v2/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: development-guidance-v2
+description: Developer-facing slice execution and local verification guidance for slopmachine-v2.
+---
+
+# Development Guidance v2
+
+Use this skill during `P4 Development` before prompting the developer.
+
+## Slice model
+
+- work in bounded vertical slices
+- complete the real user-facing and admin-facing surface for the slice
+- keep slice-local planning, implementation, verification, and doc sync together
+
+## Module implementation guidance
+
+- define lightweight planning notes for the module before coding
+- define the module purpose, constraints, and edge cases before coding
+- keep the original requirement and clarified interpretation visible while implementing so the module does not silently drift
+- implement real behavior, not partial scattered logic
+- handle failure paths and boundary conditions
+- add or update tests as part of the module work
+- make sure the module is moving toward full definition-of-done completion, not just happy-path completion
+- keep auth, authorization, ownership, validation, and logging concerns in view when relevant
+- keep frontend and backend contracts synchronized when the module spans both sides
+- verify the module integrates cleanly with existing modules, routes, permissions, shared state, and cross-cutting helpers rather than only proving the new feature path in isolation
+- check cross-cutting consistency where relevant, especially permissions, error handling, audit/logging/redaction behavior, and state or context transition behavior
+- verify tenant or ownership isolation where relevant so access is scoped to the authorized context rather than merely functionally working for one actor
+- verify file and export paths are validated and confined to allowed roots when the module reads, writes, imports, or exports files
+- verify error and auth responses are user-safe and do not leak internal reasons, paths, stack details, or sensitive state
+- perform a clean-slate sweep before reporting module completion: remove seeded credentials, weak demo defaults, test-account hints, prototype residue, and other production-inappropriate artifacts
+- do not treat backend existence, composable existence, or partial wiring as completion if the user-visible flow is still incomplete
+- when the prompt says users can manage or configure something, implement full management behavior rather than create-only controls where appropriate
+- if a required user-facing or admin-facing surface is missing, treat that gap as incomplete implementation rather than a reason to bypass the surface with direct API calls or test-only shortcuts
+- do not leave computed-but-unrendered or partially surfaced requirement behavior in place
+- do not treat a module as complete when a meaningful user-facing, release-facing, production-path, or build verification is known to be failing unless the owner explicitly scopes that check out
+- use the `frontend-design` skill for frontend component or page work
+- use the `frontend-design` skill during frontend/UI verification when reviewing Playwright screenshots and tightening the interface
+- do not hardcode secrets or persist local sensitive values in the repo while implementing
+- explain behavior changes clearly enough that the documentation discipline can be satisfied accurately
+- verify the module against its planned behavior before trying to move on
+- do not move on while the module is still obviously weak or half-finished
+
+## Verification model
+
+- use targeted local verification by default
+- use local Playwright on affected flows when UI is material
+- avoid broad Docker/full-suite commands during ordinary slice work
+- prefer fast local language-native or framework-native test commands for the changed area during normal iteration
+- set up and use the local test environment inside the current working directory so normal verification does not depend on hidden global tooling assumptions
+- if the local toolchain is missing, try to install or enable it before falling back to the broad gate path
+- when the slice materially changes frontend code, frontend tooling, or release-facing build behavior, include production build health in meaningful local verification when practical
+
+## Quality rules
+
+- do not bypass required UI surfaces with API shortcuts and call that done
+- do not leave placeholder, demo, setup, or debug UI in product-facing screens
+- do not report completion while known release-facing failures still exist
+- product UI should serve the real workflow only

package/assets/skills/evaluation-triage-v2/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: evaluation-triage-v2
+description: Owner-side evaluation report triage rules for slopmachine-v2.
+---
+
+# Evaluation Triage v2
+
+Use this skill during `P7 Evaluation and Triage` after evaluation reports exist.
+
+## Rules
+
+- evaluation findings are advisory inputs, not automatic orders
+- accept or reject findings explicitly
+- keep accepted findings concrete and bounded
+- do not enter remediation just because a report found something; enter it only when the accepted findings justify it
+- if no remediation is needed, move directly to the final human decision
+
+## Triage rules
+
+- read both reports and merge the findings into one explicit triage set before deciding what happens next
+- use the evaluator priority ordering directly when triaging findings unless stronger direct evidence says otherwise
+- any finding marked `Blocker` or `High` should normally be returned for remediation
+- findings marked `Medium` may be passed in limited cases, but should usually be fixed when they materially improve confidence, correctness, or acceptance readiness
+- findings marked `Low` may be passed without remediation
+- do not treat complaints about test coverage depth, unverifiable tests, or evaluator inability to confirm a test path as automatic blockers by themselves
+- if your own direct evidence shows the tests run and the coverage is acceptable for qualification, defend the project and pass those findings instead of automatically remediating
+- if a report says it could not verify some behavior because of environment limits or avoidable verification setup issues, first decide whether you can remove that constraint and rerun the evaluation in a cleaner state
+- if the evaluator could not verify something but your own verified evidence already shows the behavior is acceptable, do not treat that as an automatic remediation trigger
+- challenge weak, random, or overreaching findings using your stronger project context and direct codebase knowledge
+- never edit or rewrite the evaluation report itself
+- if you need to add context, disagreement, or justification, append it only as a clearly labeled `User comment/message` section at the bottom of the report
+- do not loop forever chasing every newly surfaced medium or low issue once the project is otherwise qualified
+
+## Output standard
+
+- keep a clear accepted-finding set
+- keep a clear rejected or passed set when disagreement matters
+- keep the remediation brief focused on accepted issues only

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

@@ -12,17 +12,18 @@ Use this skill only after integrated verification and hardening are complete eno
 - Load this skill only during final evaluation and evaluation-driven remediation decisions.
 - Treat it as internal orchestration guidance.
 - Do not let evaluator findings automatically override your triage judgment.
+- this phase is the only allowed later human-stop point after development has started; do not create any other approval pauses outside the final evaluation decision itself
 
 ## Prompt sources
 
-- `~/slopmachine/backend-evaluation-prompt.md`
-- `~/slopmachine/frontend-evaluation-prompt.md`
+- `~/backend-evaluation-prompt.md`
+- `~/frontend-evaluation-prompt.md`
 
 ## Evaluation execution rules
 
 - when the project reaches final-evaluation readiness, run two separate evaluations:
-  - backend/non-frontend evaluation using `~/slopmachine/backend-evaluation-prompt.md`
-  - frontend evaluation using `~/slopmachine/frontend-evaluation-prompt.md`
+  - backend/non-frontend evaluation using `~/backend-evaluation-prompt.md`
+  - frontend evaluation using `~/frontend-evaluation-prompt.md`
 - read the full original project prompt from parent-root `../metadata.json` field `prompt`
 - read the respective evaluation prompt file contents yourself before launching evaluation
 - compose each evaluation request yourself as one large final prompt block
@@ -40,10 +41,6 @@ Use this skill only after integrated verification and hardening are complete eno
 - require each evaluation session to produce its own detailed evaluation report artifact
 - always compare both evaluations against the original prompt for alignment, not just the delivered implementation
 
-On the first evaluation round, preserve and use this instruction exactly inside both evaluation prompts/sessions:
-
-"Please confirm whether the current project tests are genuine and effective rather than superficial or fake tests, whether the API tests actually invoke real HTTP endpoints, and whether they cover more than 90% of the overall API surface."
-
 ## Triage rules
 
 - read both reports and merge the findings into one explicit triage set before deciding what happens next
@@ -66,10 +63,11 @@ On the first evaluation round, preserve and use this instruction exactly inside
 ## Remediation loop
 
 - route accepted blocking issues back into remediation in the same long-lived `Developer` session
-- after remediation, rerun full verification before any re-evaluation:
-  - `docker compose up --build`
-  - `run_tests.sh`
+- after remediation, rerun strong local verification before any re-evaluation:
+  - relevant local test commands
+  - local runtime checks when affected behavior needs runtime proof
   - Playwright where applicable, with fresh screenshots
+- if remediation materially reopens an owner-run milestone boundary, route the project back to that milestone gate before any re-evaluation instead of treating every remediation pass as an automatic Docker and `run_tests.sh` moment
 - rerun only the evaluation tracks that have not already passed, each in a brand new fresh `General` session and still sequentially
 - keep the remediation loop bounded and explicit so you never lose track of the active evaluation round or the accepted issue set
 - remember the external process allows a maximum of 3 repair rounds

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

@@ -0,0 +1,57 @@
+---
+name: final-evaluation-orchestration-v2
+description: Evaluation execution rules for slopmachine-v2.
+---
+
+# Final Evaluation Orchestration v2
+
+Use this skill only during `P7 Evaluation and Triage`.
+
+## Usage rules
+
+- load this skill only during final evaluation and evaluation-driven remediation decisions
+- treat it as internal orchestration guidance
+- do not let evaluator findings automatically override your triage judgment
+
+## Prompt sources
+
+- `~/backend-evaluation-prompt.md`
+- `~/frontend-evaluation-prompt.md`
+
+## Evaluation execution rules
+
+- run backend and frontend evaluation in separate fresh `General` sessions
+- compose the evaluation prompts yourself; do not tell the evaluator to read prompt files on its own
+- use the original project prompt from metadata
+- read the respective evaluation prompt file contents yourself before launching evaluation
+- compose each evaluation request yourself as one large final prompt block
+- prefix each evaluation request with a clear instruction that the reviewer must work in the current project directory and evaluate that delivered project
+- inject the full original project prompt into the `{prompt}` placeholder for the chosen evaluation prompt content
+- send that fully composed text block directly to the fresh `General` evaluator session
+- never tell the evaluator to go read prompt files, metadata files, or evaluation template paths on its own
+- never send only a path, filename, or shorthand reference and expect the evaluator to assemble the prompt itself
+- never reuse, resume, or continue a prior evaluation session
+- run the two evaluations sequentially, not in parallel, so shared runtime state, ports, databases, and artifacts do not conflict
+- track backend and frontend evaluation status separately
+- once backend evaluation passes, do not run backend evaluation again in later remediation rounds
+- once frontend evaluation passes, do not run frontend evaluation again in later remediation rounds
+- require each evaluation session to produce its own detailed evaluation report artifact
+- always compare both evaluations against the original prompt for alignment, not just the delivered implementation
+- keep reports file-backed and bring only short summaries into chat
+- rerun only the evaluation track that still needs re-evaluation after remediation
+
+## Remediation loop
+
+- route accepted blocking issues back into the active remediation developer-session slot rather than inventing an untracked side path
+- after remediation, rerun strong local verification before any re-evaluation:
+  - relevant local test commands
+  - local runtime checks when affected behavior needs runtime proof
+  - Playwright where applicable, with fresh screenshots
+- if remediation materially reopens an owner-run broad milestone boundary, route the project back to that boundary before re-evaluation instead of treating every remediation pass as an automatic broad rerun moment
+- keep the remediation loop bounded and explicit so you never lose track of the active evaluation round or the accepted issue set
+- remember the external process allows a maximum of 3 repair rounds
+
+## Boundaries
+
+- this phase is owner-side analysis, not the final human decision gate
+- do not create extra human pauses while evaluation and triage are still active

package/assets/skills/get-overlays/SKILL.md

@@ -15,6 +15,22 @@ Use this skill when you need the detailed developer overlay guidance for one of
 - Pass only the relevant guidance for the current engineering step, not the whole section verbatim unless the moment truly needs it.
 - Prefer short, natural teammate-style prompts.
 
+## Cross-Cutting Documentation Discipline
+
+- the owner maintains external docs under parent-root `../docs/`
+- the developer should keep `README.md` and any codebase-local docs accurate for repo-local use
+- planning and implementation guidance should stay explicit enough that owner-maintained external docs can be updated accurately
+- verification and hardening should check both `README.md` and the owner-maintained external docs against implementation reality
+- `README.md` must stay codebase-specific and must not become an index or explanation of the external docs set
+
+## Cross-Cutting Env-File Discipline
+
+- never create or keep `.env` files anywhere in the repo tree
+- do not allow committed `.env` files even as placeholders or examples
+- keep real secrets out of the repository and rely on Docker-provided runtime variables for sensitive values
+- if the stack requires env-file format at runtime, generate it ephemerally from Docker-provided runtime variables rather than storing it in the repo or package
+- verify the delivered project can start from scratch without any preexisting `.env` file in the repo or package
+
 ## Phase mapping
 
 - `P2 Development Bootstrap and Planning` -> `Planning And Design`
@@ -31,20 +47,44 @@ Use this skill when you need the detailed developer overlay guidance for one of
 - start from the actual project prompt and build the plan from there
 - carry the settled project requirements forward consistently as you plan
 - identify the hard non-negotiable requirements early and do not quietly trade them away for implementation convenience
+- when planning technical items that depend on a library, framework, API, or tool, check Context7 documentation first for authoritative usage details
+- when planning needs targeted outside research beyond direct documentation, use Exa web search next
+- use technical research to strengthen concrete planning decisions, interfaces, constraints, and verification strategy rather than leaving them vague
 - break the problem into explicit requirements, constraints, flows, boundaries, and edge cases
 - map each meaningful requirement to its owning module, visible UI/API surface, failure behavior, test target, and final acceptance check
-- create or update working design notes and API/spec notes when relevant
+- make the planning explicit enough that the owner can maintain external design notes and API/spec docs accurately when relevant
 - keep the spec focused on required behavior rather than turning it into a progress or completion narrative
 - define major modules as meaningful delivery units, not arbitrary folders
 - for fullstack work, map frontend surfaces, routes, components, and state boundaries to the backend modules and contracts that support them
+- for fullstack work, make the frontend-to-backend crosswalk explicit enough that each major route, page, component group, or state boundary has a defined supporting backend module, endpoint, and data shape
+- when the prompt says behavior is configurable, plan the real configuration surface, data model, permissions, and operator flow rather than treating configurability as an implementation detail to invent later
+- when a feature must be admin-manageable or operator-manageable, plan the real usable UI surface for that management flow, not just the backing API or data model
 - define failure paths, permissions, validation, logging, runtime assumptions, and test strategy before coding
+- for complex security, offline, sync, authorization, or data-governance features, define what `done` means across all prompt-promised dimensions rather than stopping at a partial foundation or hook layer
+- define shared lifecycle and state models when the product has meaningful workflow state, and keep those models aligned across design notes and API/spec notes
+- require cross-document consistency so design, API/spec, and test-planning artifacts do not drift on lifecycle/state models, flow coverage, permissions, or operational behavior
 - define logging and observability expectations for both frontend and backend
+- define operator visibility and operator workflow expectations when the prompt implies admin, operational, audit, backup, or support responsibilities
+- when the system has meaningful cross-cutting behavior, define shared implementation contracts early rather than leaving each module to invent its own pattern
+- define error-handling contracts when relevant, including normalization patterns for user-visible errors and backend error-shape expectations
+- define audit contracts when relevant, including centralized helper or service expectations and redaction rules
+- define permission contracts when relevant so navigation visibility, route guards, and API enforcement stay aligned
+- define state-lifecycle contracts when relevant, including context-switch or tenant-switch cleanup expectations
+- define auth edge-case expectations when relevant, such as token refresh, session expiry, or clock-skew tolerance
 - call out operational obligations early when they are prompt-critical, such as scheduling, retention, backups, workers, auditability, or offline behavior
+- define infrastructure requirements early when they are material to correctness, such as rate limiting, encryption boundaries, production-equivalent test infrastructure, and browser-storage rules for sensitive data
+- define frontend validation and accessibility expectations when the product surface materially depends on them, including keyboard, focus, feedback, and other user-interaction quality requirements where relevant
+- if backup or recovery behavior is prompt-critical, plan the designated media, operator drill flow, visibility, and verification expectations explicitly
+- if the prompt names literal storage, indexing, partitioning, retention, or performance dimensions, represent them literally in the planning artifacts rather than abstracting them away
+- for frontend work, unless the prompt, existing repository, or established stack clearly dictates otherwise, default to Tailwind CSS for styling and `shadcn/ui` for component primitives
+- if the existing project already uses a different UI system, preserve and extend that system instead of forcing Tailwind CSS or `shadcn/ui` into it
 - define end-to-end coverage for major user flows before coding
 - for fullstack work, explicitly plan Playwright coverage for the synchronized frontend/backend flows when end-to-end testing is applicable
 - when UI-bearing flows are material, explicitly plan screenshot review as part of Playwright verification so UI correctness is checked, not just browser success
 - aim for at least 90 percent meaningful coverage of the relevant behavior surface
 - define verification strategy, Docker expectations, and documentation implications before coding
+- for each major module, define how it integrates with existing modules and which shared contracts it must follow consistently
+- define verification plans that include cross-module scenarios and seam checks, not just isolated feature checks
 - make the plan detailed enough to guide real implementation and later verification
 - review the module map and make sure it is stable before deeper implementation begins
 - do not move into deeper implementation with vague architecture or unstable module boundaries
@@ -57,13 +97,25 @@ Use this skill when you need the detailed developer overlay guidance for one of
 - create required testing directories and baseline docs structure
 - put baseline config and logging structure in place
 - put migrations, worker/job foundation, and real runtime health surfaces in place when the project needs them
-- keep real secrets out of the repository and rely on Docker-managed runtime injection for any sensitive values
-- keep committed env files to placeholders or clearly non-production defaults only
+- never create or keep `.env` files anywhere in the repo tree
+- treat prompt-critical security controls as real baseline runtime behavior, not placeholder checks or visual wiring
+- if a requirement implies enforcement, persistence, statefulness, or rejection behavior, make that behavior real in the scaffold unless the prompt clearly scopes it down
+- do not accept shape-only security implementations such as header presence checks, passive constants, or partially wired middleware when the requirement implies real protection
+- when applicable at scaffold time, require real security baselines such as nonce reuse rejection rather than nonce-header presence, real lockout behavior rather than config-only lockout values, CSRF rejection on protected mutations, and meaningful server-side state when the protection model depends on it
+- keep real secrets out of the repository and rely on Docker-provided runtime variables for sensitive values
+- do not allow committed `.env` files even as placeholders or examples
+- if the stack requires env-file format at runtime, generate it ephemerally from Docker-provided runtime variables rather than storing it in the repo or package
 - remove prototype residue from runtime foundations: no placeholder titles, hidden setup, fake defaults, or seeded live-path assumptions
 - make prompt-critical runtime behavior visible in the scaffold instead of hand-waving it for later, especially offline, worker, backup, or HTTPS requirements
+- keep Docker runtime isolation clean in shared environments: use self-contained Compose namespacing, avoid fragile generic project names, and prefer Compose-managed service naming over unnecessary hardcoded `container_name` values
+- require reproducible build and tooling foundations: prefer lockfile-driven installs where the stack supports them, keep source and build outputs clearly separated, and do not allow generated runtime artifacts to drift back into source directories
+- for typed build pipelines, keep source-of-truth boundaries clean so compiled output does not create TS/JS or similar dual-source drift in the working tree
 - establish README structure early instead of leaving it until the end
 - prove the scaffold in a clean state before deeper feature work
 - verify `docker compose up` and `run_tests.sh` in the clean scaffold state
+- verify clean `docker compose up --build -d` and `docker compose down` behavior under the chosen project namespace when Dockerized execution is in scope
+- when the architecture materially depends on infrastructure capabilities such as rate limiting, encryption, offline support, or browser-storage policy, put the baseline framework and policy in place during scaffold rather than deferring it to late implementation
+- for backend integration paths, prefer production-equivalent test infrastructure when practical rather than silently substituting a weaker database or runtime model that can hide real defects
 - do not treat scaffold as placeholder boilerplate or rely on hidden setup
 
 ## Module Implementation
@@ -79,17 +131,26 @@ Use this skill when you need the detailed developer overlay guidance for one of
 - set up and use the local test environment inside the current working directory so normal verification does not depend on hidden global tooling assumptions
 - if the local toolchain is missing, try to install or enable it before falling back to `run_tests.sh`
 - for applicable fullstack or UI-bearing work, run local Playwright on the affected flows during implementation and inspect screenshots to confirm the UI actually matches
+- when the slice materially changes frontend code, frontend tooling, or release-facing build behavior, include production build health in meaningful local verification when practical
 - make sure the module is moving toward full definition-of-done completion, not just happy-path completion
 - keep auth, authorization, ownership, validation, and logging concerns in view when relevant
 - keep frontend and backend contracts synchronized when the module spans both sides
+- verify the module integrates cleanly with existing modules, routes, permissions, shared state, and cross-cutting helpers rather than only proving the new feature path in isolation
+- check cross-cutting consistency where relevant, especially permissions, error handling, audit/logging/redaction behavior, and state or context transition behavior
+- verify tenant or ownership isolation where relevant so access is scoped to the authorized context rather than merely functionally working for one actor
+- verify file and export paths are validated and confined to allowed roots when the module reads, writes, imports, or exports files
+- verify error and auth responses are user-safe and do not leak internal reasons, paths, stack details, or sensitive state
+- perform a clean-slate sweep before reporting module completion: remove seeded credentials, weak demo defaults, test-account hints, prototype residue, and other production-inappropriate artifacts
 - do not treat backend existence, composable existence, or partial wiring as completion if the user-visible flow is still incomplete
 - when the prompt says users can manage or configure something, implement full management behavior rather than create-only controls where appropriate
+- if a required user-facing or admin-facing surface is missing, treat that gap as incomplete implementation rather than a reason to bypass the surface with direct API calls or test-only shortcuts
 - do not leave computed-but-unrendered or partially surfaced requirement behavior in place
+- do not treat a module as complete when a meaningful user-facing, release-facing, production-path, or build verification is known to be failing unless the owner explicitly scopes that check out
 - do not ship frontend screens with demo/debug/setup messaging or development-only status text; product UI should serve the real workflow only
 - use the `frontend-design` skill for frontend component or page work
 - use the `frontend-design` skill during frontend/UI verification when reviewing Playwright screenshots and tightening the interface
 - do not hardcode secrets or persist local sensitive values in the repo while implementing
-- update relevant docs when behavior changes
+- explain behavior changes clearly enough that the documentation discipline can be satisfied accurately
 - verify the module against its planned behavior before trying to move on
 - do not move on while the module is still obviously weak or half-finished
 
@@ -106,16 +167,23 @@ Use this skill when you need the detailed developer overlay guidance for one of
 - verify requirement closure, not just feature existence
 - verify behavior against the current plan, the actual requirements, and any settled project decisions that affect the change
 - verify end-to-end flow behavior where the change affects real workflows
+- do not use mocked APIs as integration evidence; integration verification must use real HTTP requests against the actual running service surface
 - for fullstack work, run Playwright coverage for major flows and review screenshots for real UI behavior and regressions
+- end-to-end coverage must use the real intended user-facing or admin-facing surfaces for the flow; if the flow cannot be exercised that way, treat the missing surface as incomplete work
 - use `frontend-design` while reviewing frontend screenshots so UI issues are challenged, not just functionally observed
 - verify screenshots do not contain demo placeholders, scaffold instructions, debug notices, or other development-only UI leakage
 - verify important failure, conflict, stale-state, negative-auth, and cross-user-isolation paths where relevant
 - verify required remediation guidance is actually visible to the user, not just computed internally
 - verify security-sensitive behavior where applicable
+- verify multi-tenant and cross-user isolation where applicable, including negative checks rather than single-actor happy paths only
+- verify file/path safety for file-bearing flows where applicable, including traversal-style negative cases
 - verify secrets are not committed, hardcoded, or leaking through logs/config/docs
-- verify docs do not overstate implementation completeness or claim behavior that is only partial
-- verify docs still match implementation reality
+- apply the cross-cutting env-file discipline during verification
+- verify error surfaces and auth-related failures are sanitized for users and operators appropriately
+- apply the cross-cutting documentation discipline during verification
 - trace the changed tests and verification back to the prompt-critical risks, not just the easiest happy paths
+- challenge integration seams and adjacent-module behavior, not just the changed module's local path
+- when frontend behavior or tooling changed materially, treat known production build breakage as blocking evidence rather than optional cleanup
 - do not treat a module as done until functional behavior, failure behavior, tests, docs, security considerations, and required runtime verification are all in place
 - call out weak evidence, missing coverage, or unresolved issues plainly
 - do not treat developer claims as enough without real verification
@@ -131,6 +199,9 @@ Use this skill when you need the detailed developer overlay guidance for one of
 - re-check frontend and backend observability, redaction, and operator visibility paths
 - run a prompt-fidelity sweep for silent requirement substitution, partially delivered hard requirements, and frontend/backend mismatch
 - run a prototype-residue sweep for hardcoded preview values, placeholder text, seeded defaults, hidden fallbacks, and computed-but-unrendered behavior
+- enforce the cross-cutting env-file discipline during hardening
+- run documentation verification against the real codebase and runtime behavior, not just document existence
+- enforce the cross-cutting documentation discipline during hardening
 - re-check prompt-critical operational obligations such as scheduled jobs, retention, backups, worker behavior, privacy/accountability logging, and admin controls
 - enter release-candidate mode: stop feature work and focus only on fixes, verification, docs, and packaging preparation
 - make sure the system is genuinely reviewable and reproducible