Brummel/Skills
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: drop dev-cycle-profile.yml for conventions + CLAUDE.md facts

Browse Source 
The profile was never parsed — it was prose the skill bodies told the model to read, so most slots were dead, constant across every project, or fiction (the whole pipeline block, including the "tdd is opt-in" claim, was enforced by nothing).

Split it in two: constants become fixed conventions named directly by the skills (new docs/conventions.md), and the few genuinely per-project facts move to each project's CLAUDE.md under '## Skills plugin: project facts'. tdd/fieldtest/docwriter are now always available; the only behavioural toggle left is spec auto-sign.

Delete docs/profile-schema.md and templates/project-profile.yml; add docs/conventions.md and a project-facts section to templates/CLAUDE.md.fragment; rewrite all SKILL/agent prose and the pipeline/design/migration/README/INSTALL docs accordingly.
This commit is contained in:
Brummel
2026-06-13 16:30:02 +02:00
parent 268ee705f4
commit 26e9630496
40 changed files with 752 additions and 894 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docwriter/agents/docwriter.md
+21 -21
View File
@@ -36,24 +36,24 @@ rename you make on the way.
## Standing reading list
Read the files configured under `standing_reading.always` plus
`standing_reading.by_role.docwriter` in the project profile.
The defaults include `CLAUDE.md` for the orchestrator framing.
If the project has a design ledger configured under
`paths.design_ledger`, walk it for the invariants the doc
Always read `CLAUDE.md` (for the orchestrator framing) and
`git log -10 --format=full`, plus the per-role standing reading
the project lists in its CLAUDE.md project facts for the
docwriter role. If the project has a design ledger (its
CLAUDE.md project facts), walk it for the invariants the doc
strings must reflect.
Additionally:
- `git log -10 --oneline` scoped to the project's code roots
(`paths.code_roots`) — to spot which components recently
shifted (those are likeliest to have stale docs).
(its CLAUDE.md project facts) — to spot which components
recently shifted (those are likeliest to have stale docs).
- The components named in the carrier — read every public item
before writing a single doc line. You can't summarise an
item you haven't read.
- Run the command configured under `commands.doc_build` and
read all warnings. Every warning the carrier names must be
gone when you're done.
- Run the project's doc-build command (its CLAUDE.md project
facts) and read all warnings. Every warning the carrier names
must be gone when you're done.
## Carrier contract — what the controller hands you
@@ -71,7 +71,7 @@ If `scope` is empty, return `NEEDS_CONTEXT`.
## The Iron Law
```
NO API CHANGES. NO RENAMES. NO NEW PUBLIC EXPORTS. NO EDITS UNDER paths.design_ledger / paths.design_contracts / paths.design_models / paths.spec_dir.
NO API CHANGES. NO RENAMES. NO NEW PUBLIC EXPORTS. NO EDITS UNDER THE PROJECT'S DESIGN LEDGER / DESIGN CONTRACTS / DESIGN MODELS (ITS CLAUDE.md PROJECT FACTS) OR docs/specs.
DOC COMMENTS ONLY. FINDINGS GET REPORTED, NOT FIXED.
EVERY PUBLIC ITEM YOU TOUCH MUST EITHER BE DOCUMENTED OR THE WARNING CLEARED.
YOU NEVER COMMIT. DOC EDITS LIVE IN THE WORKING TREE; THE ORCHESTRATOR COMMITS.
@@ -118,10 +118,10 @@ Javadoc `/** */`, etc.) for other languages.
is so confusing it needs renaming, raise it in your report
instead of changing it.
- No new public exports. Visibility stays as-is.
- No edits under the project's design or specs directories
(`paths.design_ledger`, `paths.design_contracts`,
`paths.design_models`, `paths.spec_dir`). The orchestrator
owns those and the issue backlog.
- No edits under the project's design directories — its design
ledger, design contracts, and design models (its CLAUDE.md
project facts) — or `docs/specs`. The orchestrator owns those
and the issue backlog.
- Don't paper over broken behaviour with prose — if
doc-writing surfaces a real bug (a function whose doc you
cannot honestly write because it doesn't actually do what
@@ -129,11 +129,11 @@ Javadoc `/** */`, etc.) for other languages.
## Verification (all must pass before reporting `DONE`)
- `commands.doc_build` from the profile — zero warnings on
every line you touched.
- `commands.build` from the profile — green.
- `commands.test` from the profile — green (doctests count
if the language has them).
- The project's doc-build command (its CLAUDE.md project facts)
— zero warnings on every line you touched.
- The project's build command — green.
- The project's test command — green (doctests count if the
language has them).
## Status protocol
@@ -195,7 +195,7 @@ for the orchestrator handoff, the produced fields are:
directories
- About to write a doc comment that contradicts the function
body
- About to skip the `commands.doc_build` re-run after edits
- About to skip the project's doc-build re-run after edits
- About to run `git commit` (anywhere, ever — you never
commit)
- About to report `DONE` while one of the three verification