Summary
The core config is named "ADR-Driven Development Config", but the development lifecycle it's named for is never stated in the core. ~/.claude/CLAUDE.md is a 13-line pointer, and hooks/ways/core.md is posture/epistemics (trust, directness, uncertainty, no-apology). The actual lifecycle — research → debate → ADR → PR → review → merge → implement → introspect — is emergent across domain ways (documentation/adr, softwaredev/delivery, the GitHub/Introspection ways) and never named centrally. That works, but it leaves the headline concept implicit and a few high-value behaviors un-encoded.
This issue proposes giving the core a little more sophistication, grounded in a full session that ran the framework end-to-end on a clean-sheet repo (aaronsb/transcribbler: 4 PRs, 15 ADRs, a Canonical-IR JSON-Schema contract with CI, architect + code reviews, first working code). Each proposal cites what actually happened.
Caveat: I only fully read CLAUDE.md + core.md; the domain ways I saw via live disclosure. Some of these may already be partially covered in a domain way and just need elevation or a core cross-reference rather than new content. Flagged where I suspect that.
Proposals
1. Name the lifecycle in the core (CLAUDE.md / core.md)
Right now a fresh session infers the loop from whichever domain ways happen to fire. State it once, compactly, in the core as the spine the domain ways hang off:
research → debate → ADR → branch → PR → review → merge → implement → introspect.
Evidence: the loop ran cleanly all session, but only because GitHub Way + ADR Way + Introspection Way each fired separately; nothing tied them into one named cycle.
2. Greenfield / day-zero bootstrap posture (gap)
The ADR Way says "Always use docs/scripts/adr", but on a brand-new repo that tool doesn't exist — and the Sub-Agents Way even notes "This project doesn't have ADR management tooling installed." The two are in tension and the core gives no day-zero guidance. I hand-rolled docs/architecture/, an index, a 0000-template, and MADR format because there was no "you're on a fresh repo, scaffold-or-offer the ADR infra first" posture.
Proposal: a core "day-zero" stance — detect ADR tooling; if absent, scaffold it (or project-init) before improvising, so structure is consistent session-to-session instead of re-invented each greenfield.
3. Review gates as defaults, not on-request (likely an elevation of GitHub Way)
The strongest pattern this session: architect review on design/ADR PRs, code review on code PRs, before merge. It produced the highest-value catches (the architect found a real ADR contradiction; the code review found that format: date-time was an inert/no-op constraint). But it happened only because the human asked each time. GitHub Way already says "offer code-reviewer before merge" — extend that to: design/ADR PRs default to a system-architect review; code PRs default to code-reviewer.
4. Decisions carry their evidence (gap)
A large fraction of the session was web research (models, ROCm/CUDA, tooling) feeding ADRs. There's a research way and a deep-research skill, but no convention for persisting research provenance into the decision record. I improvised docs/design/prior-art.md cross-linked from the ADRs.
Proposal: make "research findings → a prior-art/research doc, cross-linked from the ADRs it informed" a first-class step, so decisions ship with their evidence and citations instead of losing them at session end.
5. ADR lifecycle richness (likely elevation of documentation/adr)
Three sub-patterns I used ad hoc that deserve to be named:
- Stub ADRs (
Proposed/Deferred) to capture known-future decisions a review surfaces, so gaps are tracked not lost (I opened ADR-0011..0014 this way after the architect review).
- Split / supersede mechanics — I split one ADR into two mid-PR; the Way covers status but not the clean split move.
- "Open questions → resolved" capture inside an ADR as they get answered.
6. Validation-with-teeth as a concrete practice (extends Code Quality Way)
Code Quality Way states the principle ("a validation earns its place only if its violation is a real defect"). This session turned it into a practice worth encoding: a contract ships with golden fixtures AND negative fixtures that are asserted to be rejected, plus a CI gate — so "it has teeth" is proven, not claimed. The code review explicitly flagged a constraint that looked rigorous but was inert; negative fixtures would have caught it.
Disclosure-layer calibration (secondary)
Observed firsthand this session:
- Over-firing: Migrations Way, Release Way, and Patch Creation Way were injected when nothing relevant was happening.
- Domain mismatch: a design-phase repo (docs/ADRs, no app code for most of it) still drew code-centric ways (Error Handling, Performance). A notion of project phase (design vs implementation) could gate which ways fire.
Where each belongs
Happy to draft any of these as concrete way edits if useful.
Summary
The core config is named "ADR-Driven Development Config", but the development lifecycle it's named for is never stated in the core.
~/.claude/CLAUDE.mdis a 13-line pointer, andhooks/ways/core.mdis posture/epistemics (trust, directness, uncertainty, no-apology). The actual lifecycle — research → debate → ADR → PR → review → merge → implement → introspect — is emergent across domain ways (documentation/adr,softwaredev/delivery, the GitHub/Introspection ways) and never named centrally. That works, but it leaves the headline concept implicit and a few high-value behaviors un-encoded.This issue proposes giving the core a little more sophistication, grounded in a full session that ran the framework end-to-end on a clean-sheet repo (
aaronsb/transcribbler: 4 PRs, 15 ADRs, a Canonical-IR JSON-Schema contract with CI, architect + code reviews, first working code). Each proposal cites what actually happened.Proposals
1. Name the lifecycle in the core (CLAUDE.md / core.md)
Right now a fresh session infers the loop from whichever domain ways happen to fire. State it once, compactly, in the core as the spine the domain ways hang off:
research → debate → ADR → branch → PR → review → merge → implement → introspect.Evidence: the loop ran cleanly all session, but only because GitHub Way + ADR Way + Introspection Way each fired separately; nothing tied them into one named cycle.
2. Greenfield / day-zero bootstrap posture (gap)
The ADR Way says "Always use
docs/scripts/adr", but on a brand-new repo that tool doesn't exist — and the Sub-Agents Way even notes "This project doesn't have ADR management tooling installed." The two are in tension and the core gives no day-zero guidance. I hand-rolleddocs/architecture/, an index, a0000-template, and MADR format because there was no "you're on a fresh repo, scaffold-or-offer the ADR infra first" posture.Proposal: a core "day-zero" stance — detect ADR tooling; if absent, scaffold it (or
project-init) before improvising, so structure is consistent session-to-session instead of re-invented each greenfield.3. Review gates as defaults, not on-request (likely an elevation of GitHub Way)
The strongest pattern this session: architect review on design/ADR PRs, code review on code PRs, before merge. It produced the highest-value catches (the architect found a real ADR contradiction; the code review found that
format: date-timewas an inert/no-op constraint). But it happened only because the human asked each time. GitHub Way already says "offer code-reviewer before merge" — extend that to: design/ADR PRs default to asystem-architectreview; code PRs default tocode-reviewer.4. Decisions carry their evidence (gap)
A large fraction of the session was web research (models, ROCm/CUDA, tooling) feeding ADRs. There's a
researchway and adeep-researchskill, but no convention for persisting research provenance into the decision record. I improviseddocs/design/prior-art.mdcross-linked from the ADRs.Proposal: make "research findings → a prior-art/research doc, cross-linked from the ADRs it informed" a first-class step, so decisions ship with their evidence and citations instead of losing them at session end.
5. ADR lifecycle richness (likely elevation of
documentation/adr)Three sub-patterns I used ad hoc that deserve to be named:
Proposed/Deferred) to capture known-future decisions a review surfaces, so gaps are tracked not lost (I opened ADR-0011..0014 this way after the architect review).6. Validation-with-teeth as a concrete practice (extends Code Quality Way)
Code Quality Way states the principle ("a validation earns its place only if its violation is a real defect"). This session turned it into a practice worth encoding: a contract ships with golden fixtures AND negative fixtures that are asserted to be rejected, plus a CI gate — so "it has teeth" is proven, not claimed. The code review explicitly flagged a constraint that looked rigorous but was inert; negative fixtures would have caught it.
Disclosure-layer calibration (secondary)
Observed firsthand this session:
Where each belongs
Happy to draft any of these as concrete way edits if useful.