theslopmachine 0.3.0

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

@@ -0,0 +1,75 @@
+---
+name: developer-session-lifecycle
+description: Startup, canonical developer session persistence, recovery, and initial project structure rules for repo-cwd tracked development.
+---
+
+# Developer Session Lifecycle
+
+Use this skill during startup, tracked developer-session creation, and recovery.
+
+## Usage rules
+
+- Load this skill before starting the canonical developer session.
+- Load it again during any recovery or session-consistency check.
+- Treat it as internal orchestration guidance, not developer-visible text.
+
+## Canonical 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
+- 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
+- if the owner process crashes, recovery happens externally; when restarted, recover from state and 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
+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
+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
+
+## 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 `../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
+- 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
+- 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

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

@@ -0,0 +1,75 @@
+---
+name: final-evaluation-orchestration
+description: Dual final-evaluation workflow, prompt composition, triage, report integrity, and bounded remediation-loop rules for repo-cwd execution.
+---
+
+# Final Evaluation Orchestration
+
+Use this skill only after integrated verification and hardening are complete enough for final evaluation.
+
+## 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
+
+- `~/slopmachine/backend-evaluation-prompt.md`
+- `~/slopmachine/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`
+- 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
+- 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
+- run each evaluation in its own fresh ephemeral `General` session only
+- never reuse, resume, or continue a prior evaluation session
+- run the two evaluations sequentially, not in parallel, so shared runtime state, Docker containers, 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
+
+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
+- use the evaluator's priority ordering directly when triaging findings
+- any finding marked `Blocker` or `High` must be returned to the original `Developer` session 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
+- evaluation findings are advisory inputs to triage, not automatic implementation orders
+- 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 enter remediation just because a new evaluation found something; the evaluator will almost always find additional issues
+- once all `Blocker` and `High` findings are resolved, do not loop forever chasing every newly surfaced `Medium` or `Low` issue
+- after each re-evaluation, decide explicitly whether the remaining findings still justify another remediation round or whether the project is now qualified to package
+
+## 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`
+  - Playwright where applicable, with fresh screenshots
+- 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/frontend-design/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: frontend-design
+description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
+---
+
+This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
+
+The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
+
+## Design Thinking
+
+Before coding, understand the context and commit to a BOLD aesthetic direction:
+- **Purpose**: What problem does this interface solve? Who uses it?
+- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
+- **Constraints**: Technical requirements (framework, performance, accessibility).
+- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
+
+**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
+
+Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
+- Production-grade and functional
+- Visually striking and memorable
+- Cohesive with a clear aesthetic point-of-view
+- Meticulously refined in every detail
+
+## Frontend Aesthetics Guidelines
+
+Focus on:
+- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
+- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
+- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
+- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
+- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
+
+NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
+
+**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
+
+Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.

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

@@ -0,0 +1,157 @@
+---
+name: get-overlays
+description: Loads the developer phase overlays so the workflow owner can extract only the relevant guidance for the current implementation phase without naming workflow internals to the developer.
+---
+
+# Get Overlays
+
+Use this skill when you need the detailed developer overlay guidance for one of the active implementation phases.
+
+## Usage rules
+
+- Load this skill when entering an overlay-backed developer phase or when switching to a different overlay-backed developer phase.
+- Do not mention the skill or the word `overlay` to the developer.
+- Treat this content as internal scaffolding for composing a natural developer message.
+- 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.
+
+## Phase mapping
+
+- `P2 Development Bootstrap and Planning` -> `Planning And Design`
+- `P3 Scaffold and Foundation` -> `Scaffold And Foundation`
+- `P4 Module Implementation` -> `Module Implementation`
+- `P5 Ongoing Verification` -> `Verification And Review`
+- `P6 Integrated Verification` -> `Verification And Review`
+- `P7 Hardening` -> `Hardening`
+- `P9 Remediation` -> `Remediation`
+- `P10 Submission Packaging` -> `Packaging Preparation`
+
+## Planning And Design
+
+- 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
+- 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
+- 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
+- define failure paths, permissions, validation, logging, runtime assumptions, and test strategy before coding
+- define logging and observability expectations for both frontend and backend
+- call out operational obligations early when they are prompt-critical, such as scheduling, retention, backups, workers, auditability, or offline behavior
+- 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
+- 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
+
+## Scaffold And Foundation
+
+- create the initial project structure intentionally
+- establish Docker as the main runtime contract
+- create `run_tests.sh` as the standard test entrypoint
+- 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
+- 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
+- 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
+- do not treat scaffold as placeholder boilerplate or rely on hidden setup
+
+## Module Implementation
+
+- work module by module in vertical slices
+- define lightweight planning notes for the module before coding
+- define the module's 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
+- 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 `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
+- 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
+- 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
+- do not leave computed-but-unrendered or partially surfaced requirement behavior in place
+- 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
+- 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 And Review
+
+- run the relevant tests for the changed behavior
+- during normal in-phase verification, prefer the fastest meaningful local test commands for the changed area
+- if local tooling is unavailable, try to install or enable the repo-local test setup when practical; otherwise fall back to `run_tests.sh`
+- the workflow owner handles the expensive critical-gate runs for `docker compose up --build` and `run_tests.sh`; use local verification to prepare for those gates rather than duplicating them casually
+- integrated/full verification should rely on owner-run `docker compose up --build`, owner-run `run_tests.sh`, and Playwright gate evidence
+- after post-evaluation remediation, strengthen local verification and rerun affected Playwright checks so the next owner-run gate pass is likely to succeed
+- for applicable fullstack or UI-bearing work, run Playwright for the affected flows in-phase, capture screenshots, and verify the UI behavior and quality directly
+- rerun the runtime startup path when the phase expects it
+- 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
+- for fullstack work, run Playwright coverage for major flows and review screenshots for real UI behavior and regressions
+- 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 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
+- trace the changed tests and verification back to the prompt-critical risks, not just the easiest happy paths
+- 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
+
+## Hardening
+
+- audit security boundaries, validation, ownership, and secret handling
+- audit env/config paths so sensitive values are injected safely and are not baked into committed files or images
+- inspect architecture, coupling, file size, and maintainability risks
+- check for bad engineering practices that accumulated during implementation
+- tighten weak tests, weak docs, and weak operational instructions
+- run exploratory testing around awkward states, repeated actions, and realistic edge behavior
+- 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
+- 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
+
+## Packaging Preparation
+
+- move or copy the final development docs into the required root `docs/` structure
+- make sure package structure matches the blueprint exactly
+- verify required artifacts are present and named correctly
+- prepare screenshots, proof materials, and other delivery evidence
+- review package cleanliness so caches, junk, and local-only files are not included
+- verify no local secret files or sensitive values are included in the package
+- verify docs, specs, and runtime instructions describe what is actually delivered rather than what was only planned or partially built
+- archive or exclude transient review artifacts so delivery evidence stays intentional and clean
+
+## Remediation
+
+- focus only on accepted defects and the work needed to fix them cleanly
+- fix the issue completely instead of layering hacks on top
+- trace the fix back to the original requirement so the remediation restores fidelity instead of only hiding the symptom
+- rerun the relevant verification after each fix
+- if the issue exposed drift, docs overclaim, or missing acceptance coverage, repair that too before closing the issue
+- update docs if behavior or instructions changed
+- report exactly what was fixed, what was rerun, and what still looks risky if anything remains

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

@@ -0,0 +1,68 @@
+---
+name: planning-gate
+description: Owner-side planning acceptance, cross-document consistency, and decomposition gate rules for repo-cwd blueprint-driven projects.
+---
+
+# Planning Gate
+
+Use this skill during `P2 Development Bootstrap and Planning` when reviewing, tightening, or accepting the first real technical plan.
+
+## Usage rules
+
+- Load this skill before accepting planning, before declaring the plan sufficient, and before creating deep execution sub-beads from the plan.
+- Treat it as owner-side planning gate guidance, not developer-visible text.
+- Use `get-overlays` as the source of truth for developer-facing planning guidance.
+- Use this skill as the source of truth for owner-side planning acceptance and decomposition readiness.
+
+## Core planning gate
+
+- the developer should produce the first in-depth technical plan
+- do not create deep execution sub-beads before the technical plan is accepted
+- do not accept planning that reduces, weakens, narrows, or silently reinterprets the original prompt
+- declare prompt-critical planning acceptance criteria before accepting the first planning pass when those criteria are already visible from the prompt
+- require relevant cross-cutting system contracts to be explicitly planned rather than left to per-module invention
+
+## Cross-document discipline
+
+- require working planning docs under `docs/` when relevant, especially `docs/design.md`, `docs/api-spec.md`, and `docs/test-coverage.md`
+- require cross-document consistency so design, API/spec, and test-planning artifacts do not drift on lifecycle/state models, permissions, flow coverage, or operational behavior
+- if planning docs disagree on core system behavior, planning is still in progress
+
+## Cross-cutting planning requirements
+
+- require shared lifecycle and state models to be aligned across planning artifacts when the product has meaningful workflow state
+- require explicit cross-cutting system contracts when relevant, especially:
+  - error normalization and user-visible error behavior
+  - audit/logging and redaction patterns
+  - permission alignment across UI, route guards, and API enforcement
+  - state-transition and context-switch behavior
+  - auth/session edge cases such as expiry, refresh, or clock skew tolerance
+- when the prompt says behavior is configurable, require the real configuration surface, permissions, operator flow, and backend support to be planned explicitly
+- when a feature must be admin-manageable or operator-manageable, require a real usable UI surface for that management flow, not just API endpoints or data-model notes
+
+## Architecture-depth requirements
+
+- for complex security, offline, sync, authorization, storage, or data-governance features, define what `done` means across all prompt-promised dimensions rather than accepting a partial foundation or hook layer
+- 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
+- if the prompt names literal storage, indexing, partitioning, retention, or performance dimensions, represent them literally in the planning artifacts rather than abstracting them away
+
+## Planning acceptance checklist
+
+Before accepting planning, apply this checklist when relevant:
+
+- major user-facing flows are mapped to backend support and verification targets
+- frontend route, page, component, and state boundaries are planned when the UI is material
+- configurable behaviors are concretely planned where the prompt requires configurability
+- lifecycle and state models are aligned across design and API/spec artifacts
+- prompt-critical operational obligations and operator visibility paths are concretely planned
+- prompt-literal storage, partitioning, indexing, retention, or performance requirements are explicitly represented
+- relevant cross-cutting system contracts are explicitly defined rather than left to per-module invention
+- each major module has a clear integration contract with existing modules and shared patterns
+- verification plans include cross-module seam checks, not just isolated feature tests
+
+## Exit conditions
+
+- the first real technical plan is accepted against this gate
+- planning artifacts are internally consistent enough to guide implementation
+- deep execution sub-beads can be created from the accepted plan without guesswork