theslopmachine 0.4.0 → 0.4.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/MANUAL.md +3 -3
- package/README.md +36 -12
- package/RELEASE.md +9 -7
- package/assets/agents/developer.md +51 -250
- package/assets/agents/slopmachine.md +253 -401
- package/assets/skills/beads-operations/SKILL.md +44 -38
- package/assets/skills/clarification-gate/SKILL.md +79 -14
- package/assets/skills/developer-session-lifecycle/SKILL.md +97 -35
- package/assets/skills/{development-guidance-v2 → development-guidance}/SKILL.md +9 -6
- package/assets/skills/{evaluation-triage-v2 → evaluation-triage}/SKILL.md +43 -4
- package/assets/skills/final-evaluation-orchestration/SKILL.md +44 -40
- package/assets/skills/{hardening-gate-v2 → hardening-gate}/SKILL.md +3 -3
- package/assets/skills/{integrated-verification-v2 → integrated-verification}/SKILL.md +6 -5
- package/assets/skills/{owner-evidence-discipline-v2 → owner-evidence-discipline}/SKILL.md +3 -3
- package/assets/skills/planning-gate/SKILL.md +32 -11
- package/assets/skills/{planning-guidance-v2 → planning-guidance}/SKILL.md +29 -9
- package/assets/skills/{remediation-guidance-v2 → remediation-guidance}/SKILL.md +3 -3
- package/assets/skills/{report-output-discipline-v2 → report-output-discipline}/SKILL.md +3 -3
- package/assets/skills/retrospective-analysis/SKILL.md +91 -0
- package/assets/skills/scaffold-guidance/SKILL.md +81 -0
- package/assets/skills/{session-rollover-v2 → session-rollover}/SKILL.md +3 -3
- package/assets/skills/submission-packaging/SKILL.md +163 -197
- package/assets/skills/verification-gates/SKILL.md +69 -81
- package/assets/slopmachine/templates/AGENTS.md +77 -101
- package/assets/slopmachine/{workflow-init-v2.js → workflow-init.js} +2 -2
- package/package.json +23 -23
- package/src/constants.js +12 -21
- package/src/init.js +38 -29
- package/src/install.js +123 -23
- package/assets/agents/developer-v2.md +0 -86
- package/assets/agents/slopmachine-v2.md +0 -219
- package/assets/skills/beads-operations-v2/SKILL.md +0 -82
- package/assets/skills/clarification-gate-v2/SKILL.md +0 -74
- package/assets/skills/developer-session-lifecycle-v2/SKILL.md +0 -148
- package/assets/skills/final-evaluation-orchestration-v2/SKILL.md +0 -57
- package/assets/skills/get-overlays/SKILL.md +0 -228
- package/assets/skills/planning-gate-v2/SKILL.md +0 -91
- package/assets/skills/scaffold-guidance-v2/SKILL.md +0 -57
- package/assets/skills/submission-packaging-v2/SKILL.md +0 -142
- package/assets/skills/verification-gates-v2/SKILL.md +0 -102
- package/assets/slopmachine/templates/AGENTS-v2.md +0 -55
- package/assets/slopmachine/tracker-init.js +0 -104
|
@@ -1,91 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: planning-gate-v2
|
|
3
|
-
description: Owner-side planning acceptance and correction rules for slopmachine-v2.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Planning Gate v2
|
|
7
|
-
|
|
8
|
-
Use this skill during `P2 Planning` when reviewing or accepting the plan.
|
|
9
|
-
|
|
10
|
-
## Planning gate priorities
|
|
11
|
-
|
|
12
|
-
Before planning is accepted, the owner should explicitly review the plan against these later audit buckets:
|
|
13
|
-
|
|
14
|
-
1. prompt-fit
|
|
15
|
-
2. security-critical flaws
|
|
16
|
-
3. test sufficiency
|
|
17
|
-
4. major engineering quality
|
|
18
|
-
|
|
19
|
-
Planning should not pass if these have been ignored in a way that is likely to create expensive late failures.
|
|
20
|
-
|
|
21
|
-
## Core rule
|
|
22
|
-
|
|
23
|
-
If the owner notices a concrete role, contract, or scope mismatch, planning does not pass until one of these is true:
|
|
24
|
-
|
|
25
|
-
- the mismatch is corrected
|
|
26
|
-
- an explicit disposition note explains why acceptance is still valid
|
|
27
|
-
|
|
28
|
-
## Usage rules
|
|
29
|
-
|
|
30
|
-
- keep the existing high bar for implementation-grade planning
|
|
31
|
-
- treat this as owner-side planning gate guidance, not developer-visible text
|
|
32
|
-
- do not create deep execution decomposition before the plan is accepted
|
|
33
|
-
- keep planning as a cheap correction point rather than pushing known ambiguity into execution
|
|
34
|
-
|
|
35
|
-
## Core planning gate
|
|
36
|
-
|
|
37
|
-
- the developer should produce the first in-depth technical plan
|
|
38
|
-
- do not create deep execution sub-items before the technical plan is accepted
|
|
39
|
-
- do not accept planning that reduces, weakens, narrows, or silently reinterprets the original prompt
|
|
40
|
-
- declare prompt-critical planning acceptance criteria before accepting the first planning pass when those criteria are already visible from the prompt
|
|
41
|
-
- require relevant cross-cutting system contracts to be explicitly planned rather than left to per-module invention
|
|
42
|
-
|
|
43
|
-
## Cross-document discipline
|
|
44
|
-
|
|
45
|
-
- require owner-maintained planning docs under parent-root `../docs/` when relevant, especially `../docs/design.md`, `../docs/api-spec.md`, and `../docs/test-coverage.md`
|
|
46
|
-
- 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
|
|
47
|
-
- if planning docs disagree on core system behavior, planning is still in progress
|
|
48
|
-
|
|
49
|
-
## Cross-cutting planning requirements
|
|
50
|
-
|
|
51
|
-
- require shared lifecycle and state models to be aligned across planning artifacts when the product has meaningful workflow state
|
|
52
|
-
- require explicit cross-cutting system contracts when relevant, especially:
|
|
53
|
-
- error normalization and user-visible error behavior
|
|
54
|
-
- audit/logging and redaction patterns
|
|
55
|
-
- permission alignment across UI, route guards, and API enforcement
|
|
56
|
-
- state-transition and context-switch behavior
|
|
57
|
-
- auth/session edge cases such as expiry, refresh, or clock skew tolerance
|
|
58
|
-
- when the prompt says behavior is configurable, require the real configuration surface, permissions, operator flow, and backend support to be planned explicitly
|
|
59
|
-
- 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
|
|
60
|
-
|
|
61
|
-
## Architecture-depth requirements
|
|
62
|
-
|
|
63
|
-
- 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
|
|
64
|
-
- 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
|
|
65
|
-
- define frontend validation and accessibility expectations when the product surface materially depends on them
|
|
66
|
-
- if the prompt names literal storage, indexing, partitioning, retention, or performance dimensions, represent them literally in the planning artifacts rather than abstracting them away
|
|
67
|
-
|
|
68
|
-
## Acceptance checklist
|
|
69
|
-
|
|
70
|
-
- scope is still prompt-faithful
|
|
71
|
-
- the plan has explicitly addressed prompt-fit risks and requirement drift
|
|
72
|
-
- major user-facing flows are mapped to backend support and verification targets
|
|
73
|
-
- security-critical areas are planned early enough that they will not be left to accidental late cleanup
|
|
74
|
-
- test sufficiency has been considered at the level of core happy path, major failure paths, security-critical paths, and obvious high-risk boundaries
|
|
75
|
-
- major engineering quality has been addressed through maintainable boundaries, clear decomposition, and shared contracts
|
|
76
|
-
- frontend route, page, component, and state boundaries are planned when the UI is material
|
|
77
|
-
- configurable behaviors are concretely planned where the prompt requires configurability
|
|
78
|
-
- lifecycle and state models are aligned across design and API/spec artifacts
|
|
79
|
-
- prompt-critical operational obligations and operator visibility paths are concretely planned
|
|
80
|
-
- prompt-literal storage, partitioning, indexing, retention, or performance requirements are explicitly represented
|
|
81
|
-
- relevant cross-cutting system contracts are explicitly defined rather than left to per-module invention
|
|
82
|
-
- each major module has a clear integration contract with existing modules and shared patterns
|
|
83
|
-
- verification plans include cross-module seam checks, not just isolated feature tests
|
|
84
|
-
- visible mismatches are corrected or explicitly dispositioned
|
|
85
|
-
- planning comments and artifacts reflect current policy truth
|
|
86
|
-
|
|
87
|
-
## Exit conditions
|
|
88
|
-
|
|
89
|
-
- the first real technical plan is accepted against this gate
|
|
90
|
-
- planning artifacts are internally consistent enough to guide implementation
|
|
91
|
-
- deep execution sub-items can be created from the accepted plan without guesswork
|
|
@@ -1,57 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: scaffold-guidance-v2
|
|
3
|
-
description: Developer-facing scaffold guidance for slopmachine-v2.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Scaffold Guidance v2
|
|
7
|
-
|
|
8
|
-
Use this skill during `P3 Scaffold` before prompting the developer.
|
|
9
|
-
|
|
10
|
-
## Scaffold standard
|
|
11
|
-
|
|
12
|
-
- create real foundations, not decorative boilerplate
|
|
13
|
-
- establish the real runtime contract
|
|
14
|
-
- establish the local verification path and the standardized gate path
|
|
15
|
-
- make prompt-critical baseline behavior real where required
|
|
16
|
-
- keep repo-local `README.md` honest from the start
|
|
17
|
-
|
|
18
|
-
## Scaffold and foundation guidance
|
|
19
|
-
|
|
20
|
-
- create the initial project structure intentionally
|
|
21
|
-
- create `run_tests.sh` as the standard broad test entrypoint when the stack needs it
|
|
22
|
-
- create required testing directories and baseline docs structure
|
|
23
|
-
- put baseline config and logging structure in place
|
|
24
|
-
- put migrations, worker/job foundation, and real runtime health surfaces in place when the project needs them
|
|
25
|
-
- treat prompt-critical security controls as real baseline runtime behavior, not placeholder checks or visual wiring
|
|
26
|
-
- if a requirement implies enforcement, persistence, statefulness, or rejection behavior, make that behavior real in the scaffold unless the prompt clearly scopes it down
|
|
27
|
-
- do not accept shape-only security implementations such as header presence checks, passive constants, or partially wired middleware when the requirement implies real protection
|
|
28
|
-
- 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
|
|
29
|
-
- remove prototype residue from runtime foundations: no placeholder titles, hidden setup, fake defaults, or seeded live-path assumptions
|
|
30
|
-
- make prompt-critical runtime behavior visible in the scaffold instead of hand-waving it for later, especially offline, worker, backup, or HTTPS requirements
|
|
31
|
-
- 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
|
|
32
|
-
- 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
|
|
33
|
-
- 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
|
|
34
|
-
- establish README structure early instead of leaving it until the end
|
|
35
|
-
- prove the scaffold in a clean state before deeper feature work
|
|
36
|
-
- verify clean startup and teardown behavior under the chosen project namespace when Dockerized execution is in scope
|
|
37
|
-
- 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
|
|
38
|
-
- 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
|
|
39
|
-
- do not treat scaffold as placeholder boilerplate or rely on hidden setup
|
|
40
|
-
|
|
41
|
-
## Current policy
|
|
42
|
-
|
|
43
|
-
- no `.env` files or env-file variants in the repo
|
|
44
|
-
- do not edit `AGENTS.md` or other workflow/rulebook files unless explicitly asked
|
|
45
|
-
- keep generated artifacts out of source-of-truth paths
|
|
46
|
-
- keep real secrets out of the repository and rely on Docker-provided runtime variables for sensitive values
|
|
47
|
-
- 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
|
|
48
|
-
|
|
49
|
-
## Acceptance target
|
|
50
|
-
|
|
51
|
-
Scaffold should make later slices easier, not force them to retrofit missing fundamentals.
|
|
52
|
-
|
|
53
|
-
## Verification cadence
|
|
54
|
-
|
|
55
|
-
- use local and narrow checks while correcting scaffold work
|
|
56
|
-
- reserve one broad owner-run scaffold gate for actual scaffold acceptance
|
|
57
|
-
- do not spend extra broad reruns once the acceptance question is already answered
|
|
@@ -1,142 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: submission-packaging-v2
|
|
3
|
-
description: Submission packaging and final closure rules for slopmachine-v2.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Submission Packaging v2
|
|
7
|
-
|
|
8
|
-
Use this skill only during `P10 Submission Packaging`.
|
|
9
|
-
|
|
10
|
-
## Core rules
|
|
11
|
-
|
|
12
|
-
- enter `P10` before packaging work begins
|
|
13
|
-
- keep packaging work inside the formal phase window
|
|
14
|
-
- package from an already-clean state instead of compensating for avoidable earlier drift
|
|
15
|
-
- treat formal workflow closure failures as real packaging failures
|
|
16
|
-
- treat this as internal packaging guidance, not developer-visible workflow text
|
|
17
|
-
- do not use it to justify skipping verification or evaluation gates
|
|
18
|
-
- packaging is not cleanup theater; preserve required evidence and remove only local junk, caches, and accidental noise
|
|
19
|
-
- do not declare packaging complete early
|
|
20
|
-
- packaging is incomplete until every required step in this skill has been executed and every required artifact path has been verified to exist
|
|
21
|
-
- do not stop packaging for approval, status confirmation, or handoff once this phase has begun; continue until the package is complete
|
|
22
|
-
|
|
23
|
-
## Completion discipline
|
|
24
|
-
|
|
25
|
-
- execute packaging in order; do not jump to the end and assume missing pieces can be filled later
|
|
26
|
-
- after each major packaging block, verify the expected outputs before continuing
|
|
27
|
-
- before closing the packaging phase, explicitly check that every required file and directory exists in its final location
|
|
28
|
-
- if any required artifact is missing, packaging is still in progress
|
|
29
|
-
- if any cleanup, move, export, or reporting step is incomplete, packaging is still in progress
|
|
30
|
-
|
|
31
|
-
## Packaging goals
|
|
32
|
-
|
|
33
|
-
- assemble the required final structure
|
|
34
|
-
- preserve required evidence
|
|
35
|
-
- exclude local-only junk and secret material
|
|
36
|
-
- export session and trajectory artifacts correctly
|
|
37
|
-
- make the final package easy to review
|
|
38
|
-
|
|
39
|
-
## Required final structure
|
|
40
|
-
|
|
41
|
-
The final submission layout in the parent project root must be:
|
|
42
|
-
|
|
43
|
-
- `docs/`
|
|
44
|
-
- `design.md`
|
|
45
|
-
- `api-spec.md` when applicable
|
|
46
|
-
- `test-coverage.md`
|
|
47
|
-
- `questions.md`
|
|
48
|
-
- `submission/`
|
|
49
|
-
- generated submission documents based on the reference files in `~/`
|
|
50
|
-
- evaluation reports
|
|
51
|
-
- repo file structure screenshot
|
|
52
|
-
- working app screenshots
|
|
53
|
-
- relocated screenshots and proof materials needed for submission review
|
|
54
|
-
- current working directory delivered as parent-root `repo/`
|
|
55
|
-
- `../sessions/`
|
|
56
|
-
- `../metadata.json`
|
|
57
|
-
- `../session.json`
|
|
58
|
-
- `../session-N.json` when multiple exported sessions exist
|
|
59
|
-
- `../trajectory.json`
|
|
60
|
-
- `../trajectory-N.json` when multiple trajectories exist
|
|
61
|
-
- parent-root `../.tmp/` directory moved out of current `.tmp/` when it exists
|
|
62
|
-
|
|
63
|
-
## Required packaging actions
|
|
64
|
-
|
|
65
|
-
- verify the root package structure matches the blueprint exactly
|
|
66
|
-
- make sure parent-root `../metadata.json` is complete and reflects the delivered project truthfully
|
|
67
|
-
- verify parent-root `../docs/design.md` exists and reflects the final delivered design when applicable
|
|
68
|
-
- verify parent-root `../docs/api-spec.md` exists and reflects the final delivered interfaces when applicable
|
|
69
|
-
- verify parent-root `../docs/test-coverage.md` exists and reflects the final delivered verification coverage
|
|
70
|
-
- verify parent-root `../docs/questions.md` exists from the accepted clarification/question record when applicable
|
|
71
|
-
- create parent-root `../submission/` for final generated submission artifacts and reviewer-facing proof
|
|
72
|
-
- ensure `README.md` matches the delivered codebase, functionality, runtime steps, and test steps, stays friendly to a junior developer, and does not reference the external docs set in `../docs/`
|
|
73
|
-
- include `run_tests.sh`
|
|
74
|
-
- relocate evaluation artifacts into parent-root `../submission/`
|
|
75
|
-
- relocate screenshots and proof materials relevant to runtime behavior and major flows into parent-root `../submission/`
|
|
76
|
-
- include exported session artifacts at the parent project root using the naming rules:
|
|
77
|
-
- `../session.json` for a single exported session
|
|
78
|
-
- `../session-N.json` when multiple exported sessions exist
|
|
79
|
-
- include trajectory artifacts at the parent project root using the naming rules:
|
|
80
|
-
- `../trajectory.json` for a single trajectory
|
|
81
|
-
- `../trajectory-N.json` when multiple trajectories exist
|
|
82
|
-
- preserve parent-root `../sessions/` as the session artifact directory for any additional exported conversation traces the package needs to retain
|
|
83
|
-
|
|
84
|
-
## Session export sequence
|
|
85
|
-
|
|
86
|
-
For the developer session, run these exact steps:
|
|
87
|
-
|
|
88
|
-
1. `opencode export <developer-session-id> > ../session-export.json`
|
|
89
|
-
2. `python3 ~/utils/strip_session_parent.py ../session-export.json --output ../session.json`
|
|
90
|
-
3. `python3 ~/utils/convert_ai_session.py -i ../session.json -o ../trajectory.json`
|
|
91
|
-
|
|
92
|
-
After those steps:
|
|
93
|
-
|
|
94
|
-
- keep the cleaned final exported session as parent-root `../session.json` unless multiple exports require `../session-N.json`
|
|
95
|
-
- keep the generated final trajectory as parent-root `../trajectory.json` unless multiple trajectories require `../trajectory-N.json`
|
|
96
|
-
- treat parent-root `../session-export.json` as a temporary packaging intermediate
|
|
97
|
-
- immediately verify that all expected directories and required files exist before running later packaging steps
|
|
98
|
-
- if the required utilities or output files are missing, packaging is not ready to continue
|
|
99
|
-
|
|
100
|
-
## Required file moves
|
|
101
|
-
|
|
102
|
-
- if repo-local `docs/` exists, treat it as accidental residue, reconcile any missing content into parent-root `../docs/`, and remove it from the delivered `repo/` tree
|
|
103
|
-
- if current `.tmp/` exists, move the whole directory to parent-root `../.tmp/` before harvesting any reviewer-facing artifacts from it
|
|
104
|
-
- after preserving parent-root `../.tmp/`, collect the relevant evaluation reports and proof artifacts from it into parent-root `../submission/`
|
|
105
|
-
- collect screenshots and other required proof materials from repo-local runtime/output directories into parent-root `../submission/`
|
|
106
|
-
- after relocation, the final submission should not require digging through repo-local output directories to find evidence
|
|
107
|
-
- keep screenshot filenames clear enough that the referenced runtime page, flow, or evidence purpose is understandable
|
|
108
|
-
|
|
109
|
-
## Repo cleanup rules
|
|
110
|
-
|
|
111
|
-
- remove runtime, editor, cache, tooling noise, generated artifacts, and environment junk recursively anywhere in the delivered repo tree
|
|
112
|
-
- do not remove required evidence just because it looks noisy
|
|
113
|
-
- remove `.git/`, `.opencode/`, `.codex/`, `.vscode/`, env-file variants, caches, `node_modules/`, build outputs not part of delivery, raw test artifact directories once evidence is relocated, and repo-local `AGENTS.md`
|
|
114
|
-
- if repo-local `.tmp/` existed, do not delete it before preserving it as parent-root `../.tmp/`
|
|
115
|
-
- the cleanup is recursive; do not leave forbidden directories or generated junk buried deeper in the repo hierarchy after required artifacts have been moved out
|
|
116
|
-
|
|
117
|
-
## Validation checklist
|
|
118
|
-
|
|
119
|
-
- confirm the final package contains what reviewers actually need to inspect the project
|
|
120
|
-
- confirm docs describe delivered behavior, not planned or aspirational behavior
|
|
121
|
-
- confirm parent-root `../docs/test-coverage.md` explains the tested flows, coverage boundaries, and how the evaluator should interpret the coverage evidence
|
|
122
|
-
- confirm generated submission documents exist under parent-root `../submission/` and correspond to the final qualified state
|
|
123
|
-
- confirm evaluation reports and screenshots have been relocated into parent-root `../submission/`
|
|
124
|
-
- confirm shared project docs live in parent-root `../docs/` and any accidental repo-local `docs/` copy has been removed from the delivered tree
|
|
125
|
-
- confirm required screenshots have been relocated into parent-root `../submission/`
|
|
126
|
-
- confirm parent-root metadata fields are populated correctly
|
|
127
|
-
- confirm session export naming rules are followed
|
|
128
|
-
|
|
129
|
-
## Submission artifact and response contract
|
|
130
|
-
|
|
131
|
-
- use parent-root `../submission/` for file-based final generated submission artifacts
|
|
132
|
-
- keep the generated content tied to the real delivered project, not generic template text
|
|
133
|
-
- use real screenshots from the delivered product and real project evidence
|
|
134
|
-
- the packaging-stage outputs are `FILE` outputs under `../submission/` plus `PARAGRAPH` outputs in the final packaging-stage response
|
|
135
|
-
|
|
136
|
-
## Final packaging verification
|
|
137
|
-
|
|
138
|
-
- do one final package review before declaring packaging complete
|
|
139
|
-
- confirm the package is coherent as a delivered submission, not just a working repo snapshot
|
|
140
|
-
- confirm the final git checkpoint can be created cleanly for the packaged state
|
|
141
|
-
- if packaging reveals a real defect or missing artifact, fix it before closing the phase
|
|
142
|
-
- do not close packaging until all required docs, exports, submission files, screenshots, and cleanup conditions are satisfied
|
|
@@ -1,102 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: verification-gates-v2
|
|
3
|
-
description: Owner-side review, acceptance, rejection, and gate-interpretation rules for slopmachine-v2.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Verification Gates v2
|
|
7
|
-
|
|
8
|
-
Use this skill after development begins whenever you are reviewing work, deciding acceptance, or interpreting phase exits.
|
|
9
|
-
|
|
10
|
-
## Usage rules
|
|
11
|
-
|
|
12
|
-
- load this skill before review, acceptance, rejection, runtime gate interpretation, hardening readiness decisions, or broad-gate decisions
|
|
13
|
-
- treat it as owner-side review and gate guidance, not developer-visible text
|
|
14
|
-
- use this skill as the source of truth for owner-side verification, review pressure, and gate interpretation
|
|
15
|
-
- outside the final human decision, do not pause execution for human approval while using this skill; continue reviewing, rejecting, fixing, and rerunning until the work qualifies
|
|
16
|
-
|
|
17
|
-
## Documentation and repo hygiene
|
|
18
|
-
|
|
19
|
-
- maintain the owner-managed external docs in parent-root `../docs/` from accepted clarification, accepted planning, accepted major implementation changes, and hardening verification
|
|
20
|
-
- keep `README.md` codebase-specific, junior-friendly, and separate from the external docs set
|
|
21
|
-
- do not allow `.env` files or env-file variants anywhere in the repo tree
|
|
22
|
-
- do not allow a project that requires a preexisting `.env` file in the repo or package to start from scratch
|
|
23
|
-
- if env-file format is needed at runtime, it must be generated ephemerally from Docker-provided runtime variables rather than stored in the repo or package
|
|
24
|
-
|
|
25
|
-
## Review standard
|
|
26
|
-
|
|
27
|
-
- do not accept fake tests, weak evidence, documentation drift, missing real surfaces, or unresolved release-facing failures
|
|
28
|
-
- do not accept mocked APIs as integration evidence
|
|
29
|
-
- do not accept placeholder or demo UI in product-facing flows
|
|
30
|
-
- do not accept `.env` files or similar env-file artifacts
|
|
31
|
-
- do not accept shallow Docker verification
|
|
32
|
-
- do not accept happy-path-only implementation when failure paths matter
|
|
33
|
-
- do not accept unsupported claims
|
|
34
|
-
- do not accept work that looks complete but is not resilient
|
|
35
|
-
- do not accept committed secrets, hardcoded sensitive values, or sloppy env handling
|
|
36
|
-
- do not accept frontend/backend drift in fullstack work
|
|
37
|
-
- do not accept missing end-to-end coverage for major fullstack flows
|
|
38
|
-
- do not accept UI claims without screenshot-backed Playwright evidence when the change affects real frontend behavior
|
|
39
|
-
- do not accept prototype residue such as seeded credentials, weak demo defaults, login hints, or unsanitized user-facing error behavior
|
|
40
|
-
- do not accept multi-tenant or cross-user security claims without negative isolation evidence when that boundary matters
|
|
41
|
-
- do not accept file-bearing flows without path confinement and traversal-style validation when that boundary matters
|
|
42
|
-
- do not accept partial foundation work for complex features when the prompt implies broader usable scope, infrastructure depth, or security depth than what was actually delivered
|
|
43
|
-
- do not accept frontend-bearing slice completion without checking production build health when the change materially affects frontend code or tooling
|
|
44
|
-
- do not accept module completion that ignores integration seams or cross-cutting consistency with the existing system
|
|
45
|
-
- do not accept end-to-end evidence that bypasses a required user-facing or admin-facing surface with direct API shortcuts
|
|
46
|
-
|
|
47
|
-
## Cadence rule
|
|
48
|
-
|
|
49
|
-
- use targeted local verification as the default during scaffold corrections, development, hardening, and remediation
|
|
50
|
-
- reserve the broad Docker/full-suite path for the limited owner-run gate moments in the workflow budget
|
|
51
|
-
- do not turn ordinary acceptance into repeated integrated-style gate runs
|
|
52
|
-
|
|
53
|
-
## Verify-fix loop
|
|
54
|
-
|
|
55
|
-
- inspect the result and evidence, not just the developer claim
|
|
56
|
-
- review technical quality, prompt alignment, architecture impact, and verification depth of the current work
|
|
57
|
-
- during normal implementation iteration, always prefer fast local language-native or framework-native verification for the changed area instead of broad Docker or full-suite proof
|
|
58
|
-
- require the developer to set up and use the project-appropriate local test environment in the current working directory when normal local verification is needed
|
|
59
|
-
- require local runtime proof when relevant by starting the server locally and exercising the changed behavior directly rather than jumping to Docker-based proof
|
|
60
|
-
- if the local toolchain is missing, require the developer to install or enable it first; do not jump to the broad gate path during ordinary iteration just because local setup is inconvenient
|
|
61
|
-
- do not accept hand-wavy claims that local verification is unavailable without a real setup attempt and clear explanation
|
|
62
|
-
- for applicable fullstack or UI-bearing work, require local Playwright on affected flows plus screenshot review and explicit UI validation
|
|
63
|
-
- if verification is weak, missing, or failing, require fixes and reruns before acceptance
|
|
64
|
-
- if documentation or repo hygiene drifts, secrets leak, contracts drift, or frontend integrity is compromised, require cleanup before acceptance
|
|
65
|
-
- keep looping until the current work is genuinely acceptable
|
|
66
|
-
|
|
67
|
-
## Broad-gate definition
|
|
68
|
-
|
|
69
|
-
- a broad gate is an owner-run integrated verification boundary, not every ordinary phase change
|
|
70
|
-
- a phase change alone does not automatically require a broad gate unless that phase exit explicitly calls for one
|
|
71
|
-
- a broad gate normally means some combination of full clean runtime proof, the broad `run_tests.sh` path, and Playwright plus screenshot evidence when UI or fullstack flows exist
|
|
72
|
-
- in v2, the workflow target is at most 3 broad owner-run verification moments across the whole cycle
|
|
73
|
-
- ordinary planning, ordinary slice acceptance, and routine in-phase verification are not broad gates by default and should rely on targeted local verification unless the risk profile says otherwise
|
|
74
|
-
|
|
75
|
-
## Runtime gate interpretation
|
|
76
|
-
|
|
77
|
-
Use evidence such as internal metadata files, structured Beads comments, verification command results, and file/project-state checks.
|
|
78
|
-
|
|
79
|
-
- clarification requires the `clarification-gate-v2` conditions plus explicit approval record
|
|
80
|
-
- planning requires the `developer-session-lifecycle-v2` and planning-gate conditions plus a fresh planning-oriented start and the required documentation and repo hygiene state when relevant
|
|
81
|
-
- scaffold requires evidence for the bounded scaffold gate, baseline logging/config, and when relevant the chosen frontend stack and UI approach being set intentionally
|
|
82
|
-
- scaffold also requires safe env/config handling, no persisted local secrets, real migration/runtime foundations, and a usable local test environment in the current working directory when practical
|
|
83
|
-
- when scaffold includes prompt-critical security controls, acceptance requires real runtime or endpoint verification of the protection rather than helper-only or shape-only proof
|
|
84
|
-
- for security-bearing scaffolds, require applicable rejection evidence such as stale replay rejection, nonce reuse rejection, CSRF rejection on protected mutations, lockout triggering when lockout is in scope, or equivalent proof that the control is truly enforced
|
|
85
|
-
- scaffold acceptance also requires self-contained Compose namespacing, no unnecessary fragile `container_name` usage, and clean startup plus teardown behavior in the intended shared-environment model
|
|
86
|
-
- module implementation requires module planning notes, module definition of done, relevant local verification for the changed area, and for applicable fullstack or UI work local Playwright evidence with screenshots, plus docs sync and review acceptance
|
|
87
|
-
- module implementation acceptance should challenge tenant isolation, path confinement, sanitized error behavior, prototype residue, integration seams, and cross-cutting consistency when those concerns are in scope
|
|
88
|
-
- integrated verification entry requires one of the limited owner-run broad gate moments once development is complete
|
|
89
|
-
- integrated verification completion requires explicit full-system evidence before the phase can close
|
|
90
|
-
- fullstack integrated verification must include Playwright coverage for every major flow, plus screenshots used to evaluate frontend behavior and UI quality along the flow using `frontend-design`
|
|
91
|
-
- if a required flow cannot be exercised through the intended UI surface, treat that as incomplete implementation rather than acceptable E2E coverage
|
|
92
|
-
- hardening requires security, maintainability, exploratory, and release-freeze evidence
|
|
93
|
-
- hardening must explicitly re-check secret handling, redaction, and frontend/backend observability hygiene
|
|
94
|
-
- hardening must explicitly satisfy the documentation and repo hygiene policy in this file before final evaluation can begin
|
|
95
|
-
- final evaluation readiness requires automated evaluation to be complete and triaged, with a clear go-to-packaging vs return-to-fixes decision
|
|
96
|
-
- remediation requires accepted issue records plus rerun local verification and affected Playwright where applicable; if remediation materially reopens the integrated verification boundary, route it back through integrated verification before re-evaluation
|
|
97
|
-
|
|
98
|
-
## Acceptance rule
|
|
99
|
-
|
|
100
|
-
- inspect the result and evidence, not just the developer claim
|
|
101
|
-
- prefer one strong rejection with a concrete correction request over many small nudges
|
|
102
|
-
- keep looping until the current work is genuinely acceptable
|
|
@@ -1,55 +0,0 @@
|
|
|
1
|
-
# Developer Rulebook v2
|
|
2
|
-
|
|
3
|
-
This file is the repo-local engineering rulebook for `slopmachine-v2` projects.
|
|
4
|
-
|
|
5
|
-
## Scope
|
|
6
|
-
|
|
7
|
-
- Treat the current working directory as the project.
|
|
8
|
-
- Ignore parent-directory workflow files unless the user explicitly asks you to use them.
|
|
9
|
-
- Do not treat workflow research, session exports, or sibling directories as hidden implementation instructions.
|
|
10
|
-
|
|
11
|
-
## Working Style
|
|
12
|
-
|
|
13
|
-
- Operate like a strong senior engineer.
|
|
14
|
-
- Read the code before making assumptions.
|
|
15
|
-
- Work in meaningful vertical slices.
|
|
16
|
-
- Do not call work complete while it is still shaky.
|
|
17
|
-
- Reuse and extend shared cross-cutting patterns instead of inventing incompatible local ones.
|
|
18
|
-
|
|
19
|
-
## Verification Rules
|
|
20
|
-
|
|
21
|
-
- During ordinary iteration, prefer the fastest meaningful local verification for the changed area.
|
|
22
|
-
- Prefer targeted unit, integration, module, route-family, or local Playwright checks over broad reruns.
|
|
23
|
-
- Do not rerun full Dockerized startup and the full test suite on every small change.
|
|
24
|
-
- The broad owner-run Docker/full-suite path should be used sparingly, with a target budget of at most 3 times across the whole workflow cycle.
|
|
25
|
-
- If you run a Docker-based verification command sequence, end it with `docker compose down` unless containers must remain up.
|
|
26
|
-
|
|
27
|
-
## Testing Rules
|
|
28
|
-
|
|
29
|
-
- Tests must be real and tied to actual behavior.
|
|
30
|
-
- Do not mock APIs for integration testing.
|
|
31
|
-
- Use real HTTP requests against the actual running service surface for integration evidence.
|
|
32
|
-
- For UI-bearing work, use local Playwright on affected flows and inspect screenshots when practical.
|
|
33
|
-
|
|
34
|
-
## Documentation Rules
|
|
35
|
-
|
|
36
|
-
- Keep `README.md` and any codebase-local docs accurate.
|
|
37
|
-
- The README must explain what the project is, what it does, how to run it, and how to test it.
|
|
38
|
-
- The README must stand on its own for basic codebase use.
|
|
39
|
-
|
|
40
|
-
## Secret And Runtime Rules
|
|
41
|
-
|
|
42
|
-
- Do not create or keep `.env` files anywhere in the repo.
|
|
43
|
-
- Do not rely on `.env`, `.env.local`, `.env.example`, or similar files for project startup.
|
|
44
|
-
- Do not hardcode secrets.
|
|
45
|
-
- If runtime env-file format is required, generate it ephemerally and do not commit or package it.
|
|
46
|
-
|
|
47
|
-
## Product Integrity Rules
|
|
48
|
-
|
|
49
|
-
- Do not leave placeholder, setup, debug, or demo content in product-facing UI.
|
|
50
|
-
- If a real user-facing or admin-facing surface is required, build that surface instead of bypassing it with API shortcuts.
|
|
51
|
-
- Treat missing real surfaces as incomplete implementation.
|
|
52
|
-
|
|
53
|
-
## Rulebook Files
|
|
54
|
-
|
|
55
|
-
- Do not edit `AGENTS.md` or other workflow/rulebook files unless explicitly asked.
|
|
@@ -1,104 +0,0 @@
|
|
|
1
|
-
#!/usr/bin/env node
|
|
2
|
-
|
|
3
|
-
import fs from 'node:fs/promises'
|
|
4
|
-
import path from 'node:path'
|
|
5
|
-
import { spawn } from 'node:child_process'
|
|
6
|
-
|
|
7
|
-
const targetInput = process.argv[2] || '.'
|
|
8
|
-
const target = path.resolve(process.cwd(), targetInput)
|
|
9
|
-
const trackerCommand = process.env.BR_COMMAND || 'br'
|
|
10
|
-
|
|
11
|
-
function log(message) {
|
|
12
|
-
console.log(`[tracker-init] ${message}`)
|
|
13
|
-
}
|
|
14
|
-
|
|
15
|
-
function die(message) {
|
|
16
|
-
console.error(`[tracker-init] ERROR: ${message}`)
|
|
17
|
-
process.exit(1)
|
|
18
|
-
}
|
|
19
|
-
|
|
20
|
-
function run(command, args, options = {}) {
|
|
21
|
-
return new Promise((resolve, reject) => {
|
|
22
|
-
const child = spawn(command, args, {
|
|
23
|
-
cwd: options.cwd,
|
|
24
|
-
env: options.env || process.env,
|
|
25
|
-
stdio: options.stdio || 'pipe',
|
|
26
|
-
shell: false,
|
|
27
|
-
})
|
|
28
|
-
|
|
29
|
-
let stdout = ''
|
|
30
|
-
let stderr = ''
|
|
31
|
-
|
|
32
|
-
if (child.stdout) child.stdout.on('data', (chunk) => { stdout += chunk.toString() })
|
|
33
|
-
if (child.stderr) child.stderr.on('data', (chunk) => { stderr += chunk.toString() })
|
|
34
|
-
|
|
35
|
-
if (options.input !== undefined && child.stdin) {
|
|
36
|
-
child.stdin.write(options.input)
|
|
37
|
-
child.stdin.end()
|
|
38
|
-
}
|
|
39
|
-
|
|
40
|
-
child.on('error', reject)
|
|
41
|
-
child.on('close', (code) => resolve({ code: code ?? 1, stdout, stderr }))
|
|
42
|
-
})
|
|
43
|
-
}
|
|
44
|
-
|
|
45
|
-
async function commandExists(command) {
|
|
46
|
-
const checker = process.platform === 'win32' ? 'where' : 'which'
|
|
47
|
-
const result = await run(checker, [command])
|
|
48
|
-
return result.code === 0
|
|
49
|
-
}
|
|
50
|
-
|
|
51
|
-
async function pathExists(targetPath) {
|
|
52
|
-
try {
|
|
53
|
-
await fs.access(targetPath)
|
|
54
|
-
return true
|
|
55
|
-
} catch {
|
|
56
|
-
return false
|
|
57
|
-
}
|
|
58
|
-
}
|
|
59
|
-
|
|
60
|
-
async function runTracker(args, options = {}) {
|
|
61
|
-
return run(trackerCommand, args, { cwd: target, ...options })
|
|
62
|
-
}
|
|
63
|
-
|
|
64
|
-
async function main() {
|
|
65
|
-
const trackerAvailable = trackerCommand !== 'br' ? await pathExists(trackerCommand) : await commandExists('br')
|
|
66
|
-
if (!trackerAvailable) {
|
|
67
|
-
die(`'${trackerCommand}' is not available. Install beads_rust first.`)
|
|
68
|
-
}
|
|
69
|
-
|
|
70
|
-
if (!(await pathExists(target))) {
|
|
71
|
-
die(`Target directory '${targetInput}' does not exist or is not accessible.`)
|
|
72
|
-
}
|
|
73
|
-
|
|
74
|
-
log(`Target: ${target}`)
|
|
75
|
-
|
|
76
|
-
const beadsDir = path.join(target, '.beads')
|
|
77
|
-
if (!(await pathExists(beadsDir))) {
|
|
78
|
-
log("Running 'br init --quiet'")
|
|
79
|
-
const initResult = await runTracker(['init', '--quiet'], {
|
|
80
|
-
env: { ...process.env, CI: '1' },
|
|
81
|
-
})
|
|
82
|
-
if (initResult.code !== 0) {
|
|
83
|
-
console.error(`${initResult.stdout}${initResult.stderr}`.trim())
|
|
84
|
-
die("'br init' failed. Review output above.")
|
|
85
|
-
}
|
|
86
|
-
} else {
|
|
87
|
-
log('Found existing .beads; skipping init to avoid destructive re-initialization')
|
|
88
|
-
}
|
|
89
|
-
|
|
90
|
-
log("Running 'br sync --flush-only'")
|
|
91
|
-
const syncResult = await runTracker(['sync', '--flush-only'], {
|
|
92
|
-
env: { ...process.env, CI: '1' },
|
|
93
|
-
})
|
|
94
|
-
if (syncResult.code !== 0) {
|
|
95
|
-
console.error(`${syncResult.stdout}${syncResult.stderr}`.trim())
|
|
96
|
-
die("'br sync --flush-only' failed. Review output above.")
|
|
97
|
-
}
|
|
98
|
-
|
|
99
|
-
log('Success: tracker initialized and JSONL exported')
|
|
100
|
-
}
|
|
101
|
-
|
|
102
|
-
main().catch((error) => {
|
|
103
|
-
die(error instanceof Error ? error.message : String(error))
|
|
104
|
-
})
|