Your Claude Code AI assistant, elevated to professional standards
|
v10.68 released Active Project Root Authority |
19 Active Runtime Rules |
Released & installed v10.68 verified |
Source-first scope Repo first, runtime second |
Released and installed:
v10.68 / P151locks development and governed source to the user- or project-selected Active Project Root and separates exact Runtime payload parity from full-project convergence./tmp, worktrees, clean clones, and alternate checkouts remain read-only evidence/reference or disposable-verification surfaces rather than implementation, commit, or release authority. Case 19/M41-M45, local and fresh-public fixtures, two-pass installation, independent review, and plugin zero-drift checks pass. Release: https://github.com/DarKWinGTM/claude-code-rules/releases/tag/v10.68.
- ⚡ Quick Start
- ✨ Features
- 📁 Rule Files
- 📦 Installation
- 🔌 Companion Plugins
- 📂 Design Documentation Structure
- 🧪 Playground
- 🔗 Integration Guide
- 🎓 Framework Highlights
- 🖼️ Visual Guide
- 📊 Before & After
- 📊 Current Quality Signals
- 🔒 Safety Commitments
- 🤝 Contributing
- 📜 License
- 🙏 Acknowledgments
Use the launcher for your platform. The primary install target is the current project's .claude/rules/ directory. The launcher is the operator entrypoint; the helper scripts remain the execution layer underneath and keep the current compact 19-rule runtime set with owner-aware manifest cleanup inside that project-local destination.
Clone-first install into a target project:
git clone https://github.com/DarKWinGTM/claude-code-rules.git
cd claude-code-rules || exit 1
./script/launcher.sh --project-root "/path/to/project"If you are already inside the target project and cloned RULES beside it:
../claude-code-rules/script/launcher.sh --project-root "$PWD"Manual/helper path from a local clone:
./script/setup-claude-code-rules.sh --project-root "/path/to/project"Clone-first install into a target project:
git clone https://github.com/DarKWinGTM/claude-code-rules.git
Set-Location claude-code-rules
.\script\launcher.ps1 -ProjectRoot "C:\path\to\project"If you are already inside the target project and cloned RULES beside it:
..\claude-code-rules\script\launcher.ps1 -ProjectRoot (Get-Location).PathManual/helper path from a local clone:
.\script\setup-claude-code-rules.ps1 -ProjectRoot "C:\path\to\project"- The primary install target is
<project-root>/.claude/rules/. - The launcher is the primary operator path; helper scripts stay available as the execution layer and manual path.
- If you run the launcher from the RULES repo root, pass
--project-root/-ProjectRootexplicitly. - This wave supports Claude Code only. Codex CLI and Gemini CLI are not supported for this install surface in current scope.
- This runtime-only install copies active rule files only.
- Cleanup is owner-aware, not wildcard-by-filename.
- Unchanged obsolete manifest-owned files are moved to
<project-root>/.claude/quarantine/claude-code-rules/<run-id>/instead of being deleted. - Retired candidate filenames move only after exact historical Git-blob proof; the prior installer-owned in-tree quarantine directory is evacuated intact to the same external quarantine root.
- External quarantine is outside active
.claude/rules/discovery and normal installation never reads it as source, retry, fallback, or restoration input. - Files already present in the target
.claude/rules/directory but outside this repo's recorded ownership or repository-history proof are preserved by default; modified or unowned active-name collisions fail closed. - Governed design/changelog/TODO/phase/patch artifacts, inactive history/done surfaces, and
template/phase-authoring-template.mdremain in the repository for maintenance and synchronized updates. - Companion plugins are now a recommended follow-up when you want the current full RULES toolchain, but they still install separately from the
.claude/rules/runtime payload.
If you want the current full RULES toolchain, install the companion plugins right after the runtime-rule install.
Portable placeholder:
<rules-repo-root>= your localclaude-code-rulescheckout
Repo-local marketplace quick path:
/plugin marketplace add <rules-repo-root>/plugin
/plugin install governed-docs@darkwingtm
/plugin install memory-context-intelligence@darkwingtm
/reload-plugins
What this gives you:
governed-docs→ governed document scan / repair-plan / release-gate supportmemory-context-intelligence→ historical workflow / RULES reflection support
Boundary:
- these plugins are not copied into
.claude/rules/ - they load separately from the local marketplace and keep their own command / slash surfaces
- for plugin-specific verification, alternate marketplace layouts, and troubleshooting, use the plugin READMEs linked in
Companion Plugins
Recommended first use after install:
governed-docs→ open its README and run the explicit-target command flow that matches your workspacememory-context-intelligence→ run/memory-context-intelligence:init, then/memory-context-intelligence:analysis
If you want Claude Code to install this repo for you into the current project's .claude/rules/ target, use this prompt:
Install this rules repo for me from:
https://github.com/DarKWinGTM/claude-code-rules
Requirements:
- clone the repo first
- run the launcher script from the cloned repo, not a raw helper fetch as the default path
- install only the active runtime rule set into the current project's .claude/rules/
- use manifest-owned cleanup only inside that same project-local target
- do not delete unrelated co-located rules in that project-local .claude/rules/ directory
- do not install files from suspend/, support/, plugin/, design/, changelog/, phase/, patch/, or TODO.md
- verify the installed files after copying
- report exactly what was installed
Codex CLI and Gemini CLI are not supported for this install surface in the current wave.
These capabilities summarize the current operating model at the front-page level. They are grounded in active doctrine and current-state behavior, not in phase-by-phase execution history.
-
Evidence-First Accuracy — Evidence-grounded reasoning is the current baseline for material claims.
- Seek practical proof before substantial reasoning when the question depends on current facts
- Check decision-changing ownership/dependency premises before recommending broader architecture
- Keep verified fact, inference, hypothesis, and scoped non-finding separate
- Preserve a checked completed baseline until evidence shows a real gap
-
Anti-Sycophancy — User direction is respected without turning agreement into false proof.
- Keep allowed-direction acceptance separate from factual confirmation and best-route endorsement
- Preserve a valid goal while correcting an unsupported premise and recommending the evidence-supported route
- Explicitly retract or revise earlier assistant advice when contrary checked evidence disproves its premise
- Avoid both reflexive agreement and artificial disagreement
-
Security First — Safety and action boundaries remain first-pass concerns.
- Prefer real systems over simulated success when implementation truth matters
- Avoid mock implementations by default unless the scope explicitly calls for them
- Verify configurations before making strong runtime or readiness claims
- Bind material architecture mutation to active design and the existing owner/state/consumer path before source edits
- Require exact delta classification and approval before additive, replacement-authority, or multi-authority topology
-
Runtime Context Discipline — The runtime layer stays compact, body-sufficient, and limited to doctrine the assistant must apply now.
- Keep the 19 active runtime rules focused on live behavioral guidance rather than historical rollout detail
- Keep design as target-state authority, changelog as version/history authority, and TODO/phase as execution surfaces
- Keep project development in the selected Active Project Root; temporary paths provide read-only evidence or disposable verification, not source authority
- Verify Runtime payload parity separately from full-project convergence and block closeout when project state remains split or unexplained
- Preserve the project-local
.claude/rules/install contract while keeping non-runtime governance artifacts out of the runtime payload
Foundational decision, safety, evidence, and refusal behavior
| Rule | Purpose | Key Benefit |
|---|---|---|
authority-and-scope.md |
Decision hierarchy | Deterministic precedence, user-owned scope, and one Active Project Root for source/governed/commit/release authority |
evidence-discipline.md |
Evidence discipline | Verify-first reasoning plus witness-specific proof limits for supplied rendered artifacts and authenticated harness results |
refusal-and-recovery.md |
Refusal and recovery chain | Normalized intent classification plus recoverable blocked-path responses |
action-safety.md |
Action safety | Consequential-action gates plus design-conformance architecture delta classification, exact approval boundaries, and deterministic retry stop |
How answers should read, explain, and disclose
| Rule | Purpose | Key Benefit |
|---|---|---|
accurate-communication.md |
Evidence-honest wording | Keeps claims, status, progress, and scope wording aligned to checked evidence |
communication-register.md |
Tone and agreement calibration | Natural professional register, high-signal trimming, and evidence-calibrated disagreement |
explanation-and-presentation.md |
Explanation, layout, and closing shape | Plain-language-first explanation plus rendering of execution-selected candidate/advisory goal posture |
audience-surface-disclosure-control.md |
Audience-aware disclosure | Full direct-user transparency while keeping public/operator surfaces appropriately scoped |
How governed work is started, tracked, phased, and routed
| Rule | Purpose | Key Benefit |
|---|---|---|
coding-discipline.md |
Coding execution discipline | Maintainable structure plus regression-versus-capability-gap diagnosis and functional/architecture-fitness verification |
execution-and-goal-frame.md |
Execution continuity and goal framing | Activates design-bound architecture preflight, retires rejected fork branches, and preserves reachable closure |
goal-authoring-and-route-support.md |
Governed /goal authoring and route support |
Constructs proof-layer-aware goals, orders prerequisites, and preserves verified Plan reference and /plan overflow guards |
worker-routing-and-context.md |
Worker routing and context control | Uses the smallest effective lane and owns checked Agent Team reuse/steer/wait/partition/respawn decisions |
phase-todo-artifact.md |
Artifact initiation, phase, and TODO doctrine | Resolves design then conditional diagram startup, creates Patch chronology from one UTC instant, governs live /phase, and separates TODO from live tasks |
How documentation, installs, I/O, memory, portability, and external checking stay coherent
| Rule | Purpose | Key Benefit |
|---|---|---|
document-governance.md |
Document governance baseline | One authority model for README/design/diagram/changelog/patch/history, including verified timestamped Patch identity, plus conditional diagram synchronization and UDVC-1 |
document-integrity.md |
Document integrity | Cross-reference integrity, payload-versus-project proof separation, split-source closeout blocking, preservation, and no-delete/root-replacement-by-hygiene discipline |
safe-io.md |
Safe file and terminal I/O | Bounded reading/output, parent-index-first reads, and rollover signals for oversized entrypoints |
external-verification-and-source-trust.md |
External source trust | Ranks reachable authorized claim-fit sources and bounded substitutes after capability preflight |
memory-governance-and-session-boundary.md |
Memory governance | Keeps memory scoped, compact, path-aware, and subordinate to checked current evidence |
portable-implementation-and-hardcoding-control.md |
Portability defaults | Prevents machine-local assumptions from becoming shared contracts |
📊 Active Runtime Rules: 19
Current source state:
- Released
v10.68 / P151advancesauthority-and-scope.mdto 2.8 anddocument-integrity.mdto 1.14 so development stays in one user- or project-selected Active Project Root and exact Runtime payload parity cannot be mistaken for full-project convergence. - Case 19/M41-M45, plugin zero-drift comparison, Bash/PowerShell fixtures, Patch tests 32/32, two-pass disposable and real installation, independent reviews, and fresh-public tag checks pass.
- Release identity: commit
04c1c91faa6cff50cdb61b3d31c82cbb3c23819f, annotated tag object2a68d0e09511f879327831b5f21170399cf7be2a, Release https://github.com/DarKWinGTM/claude-code-rules/releases/tag/v10.68, and owner-only preinstall rollback snapshot/home/node/.claude/rules-rollback/v10.68-04c1c91faa6cff50cdb61b3d31c82cbb3c23819f-preinstall. - Immutable
v10.67 / P150remains the architecture-conformance predecessor at release commitbd3aa36ff0d7c7712270750249031f362968854cand annotated tag object24c3b8982c9e8ad01456bb6139a9e6cee9246fa7. - Released
v10.66 / P149-01replaces prohibited Unicode Box Drawing markers in the Case 04 and Case 12 flow diagrams with allowed arrows and indentation; scenario semantics remain unchanged. - The correction was published from release commit
d8bffccaa304b949a713b40cd7dd2e7da4f6486eat annotated tag objectf785e254d844b895340328c3c689a728ae449384, and fresh-public master/tag verification passed. - All 19 Runtime Rules, owner triads, installers, Case 17, matrix/coverage, and Patch artifacts remain protected byte-for-byte. No real runtime reinstall was required.
- Released
v10.65 / P149remains immutable at release commit2e751bbb620eb68527e5a67eb6348196a67727e7and annotated tag objectcc7d322d3b1e4e7785373370d2d3c9eb8a8a395e, with its delayed diagram-format failure preserved. - Released
v10.64 / P148remains immutable and provides verified timestamped Patch identity, deterministic creation, safe exact-reference migration, and the repository-only Patch timeline Tool. - Former source-owned material may remain only in execution-disconnected external quarantine or inactive reference/provenance history; normal runtime, install, build, deployment, and test paths must not use it as authority or fallback.
- The installer validates manifest ownership and duplicate/path/link safety, stages the complete active payload and manifest, quarantines only evidence-matched former content, preserves unrelated/modified/unmatched files, and rolls back installer-owned moves/replacements if commit fails.
- Authority order, safety and approval gates, evidence states, execution/verification boundaries, recovery paths, exact enums/literals, and stop conditions remain required combined-runtime behavior.
- Repo-root
CLAUDE.mdkeeps source-first maintenance explicit: the checked Active Project Root is the development/commit/release-source authority, while temporary locations are read-only evidence or disposable verification and<user-runtime-rules>remains a downstream install target. - Latest published release: https://github.com/DarKWinGTM/claude-code-rules/releases/tag/v10.67
- The active install set remains 19 source-owned root Rules; governed design/changelog/TODO/phase/playground surfaces and quarantine remain outside the runtime payload.
The Quick Start block above is the canonical launcher-first install path. The methods below keep the same compact 19-rule runtime set while making project-local .claude/rules/ the default target.
Use this when: you want the full active runtime set inside the current project.
Fastest path:
- Clone the RULES repo.
- Run the launcher for your platform from that clone.
- Point it at the target project root.
- Run the verification commands below.
If you already cloned the repo earlier, you do not need to repeat the clone step. Return to the repo root and rerun the launcher locally against the project you want to govern.
Use this when: you only want a small subset of the runtime rules in one project.
mkdir -p ./.claude/rules
curl -o ./.claude/rules/evidence-discipline.md \
https://raw.githubusercontent.com/DarKWinGTM/claude-code-rules/master/evidence-discipline.mdUse this when: you intentionally want the same launcher-driven install model under your home directory.
- Use the same cloned repo.
- Run the launcher scripts.
- Set
--project-root "$HOME"for Bash or-ProjectRoot $HOMEfor PowerShell. - Treat this as an explicit fallback, not the primary recommendation for this wave.
Source-side note: public commands in this README are expressed from the repo root. Destination/runtime note: the primary target in this wave is
<project-root>/.claude/rules/; global install is only the same launcher/helper model pointed at$HOMEintentionally.
| Location | Scope | Path | Use Case |
|---|---|---|---|
| Project | Current project only | <project-root>/.claude/rules/*.md |
Default recommendation |
| Global fallback | All projects | $HOME/.claude/rules/*.md |
Explicit opt-in only |
Recommended: verify under the current project's
.claude/rules/target. Optional global fallback: verify under$HOME/.claude/rules/only if you intentionally used that target.
# Project-local install check (run from project root)
claude --version
head -20 ./.claude/rules/evidence-discipline.md
ls ./.claude/rules/action-safety.md
ls ./.claude/rules/phase-todo-artifact.md
ls ./.claude/rules/document-governance.md
ls ./.claude/rules/worker-routing-and-context.md
# Optional global fallback check
head -20 "$HOME/.claude/rules/evidence-discipline.md"
ls "$HOME/.claude/rules/action-safety.md"
ls "$HOME/.claude/rules/phase-todo-artifact.md"
ls "$HOME/.claude/rules/document-governance.md"
ls "$HOME/.claude/rules/worker-routing-and-context.md"This repo also carries local marketplace plugins that sit beside the 19 active runtime rules.
พูดง่าย ๆ คือ runtime rules ยังเป็นแกนหลักของพฤติกรรม Claude Code ใน .claude/rules/ ส่วน plugin พวกนี้เป็นเครื่องมือเสริมที่ช่วยงานเฉพาะด้านและติดตั้งแยกจาก plugin/ ตามความต้องการ
Current companion plugins worth knowing:
-
governed-docs— maintenance companion for governed document families- scans repo-governed docs against RULES doctrine
- generates repair-plan / release-gate style review output
- provides an index-backed preview flow for governed document navigation
- README:
plugin/governed-docs/README.md
-
memory-context-intelligence— evidence-first workflow reflection companion- reads bounded historical work evidence and surfaces candidate workflow / RULES improvement topics
- keeps
trace_evidenceas the live anchor while still using memory/governance context carefully - provides a guided init flow plus the analysis surface for historical-first review
- README:
plugin/memory-context-intelligence/README.md
Boundary:
- these plugins are not part of the active 19-rule runtime payload copied into
.claude/rules/ - they are companion tools you install separately from the local plugin marketplace under
plugin/
| Location | Purpose | File Type |
|---|---|---|
./design/<slug>.design.md |
Compact active parent design index/gateway for governed chains | Active design parent |
./design/<slug>/*.design.md |
Active child target-state shards in same-stem nested mode | Active design shards |
./design/*.design.md beside a compact parent |
Flat sibling design shards when the current folder already scopes the chain | Active design sibling shards |
./diagram/STRUCTURE.md |
Bodyful whole-project detailed visual structure authority when a governed diagram lane is opened | Active diagram global anchor |
./diagram/<subject>.design.md |
Default integrated Kroki-compatible subject diagram as a zoom-in / decomposition view of the global structure | Active subject diagram |
./diagram/<subject>/*.design.md |
Kroki-compatible child visual shards only after a real visual split trigger | Active diagram child shards |
*.md (selected active root rule files) |
Active runtime rules | Rules files |
./changelog/changelog.md |
Compact master repository-wide current-version authority and shard map | Master changelog parent |
./changelog/*.changelog.md |
Per-chain authoritative active parent history/current version state | Active parent changelogs |
./changelog/<chain>/v*.changelog.md |
Same-chain detailed version entries in same-stem nested mode | Version detail shards |
./changelog/v*.changelog.md beside a compact parent |
Flat sibling version-detail shards when the current folder already scopes the chain | Version detail sibling shards |
./changelog/done/*.changelog.md |
Inactive reference/provenance history outside active scans | Audit/rollback/provenance/trace only; never active resolution or automatic fallback |
./todo/history/*.md |
Daily TODO movement and pre-rollover snapshots outside the active TODO entrypoint | Referenced inactive TODO history |
./todo/done/*.md |
Large completed TODO/task detail outside the active TODO entrypoint | Referenced inactive TODO detail |
./phase/SUMMARY.md |
Compact governed summary/index for live phase planning and current roadmap state | Phase summary doc |
./phase/history/*.md |
Daily phase movement and pre-rollover phase-summary snapshots outside the active summary | Referenced inactive phase history |
./phase/phase-NNN-<phase-name>.md |
Governed active major-phase execution detail | Active major phase docs |
./phase/phase-NNN-NN-<subphase-name>.md |
Governed active subphase execution detail | Active subphase docs |
./phase/phase-NNN-NN-NN-<child-phase-name>.md |
Governed active nested child-phase execution detail inside one bounded parent family | Active nested child phase docs |
./phase/done/phase-NNN-*.md |
Completed phase detail retained outside active scans | Inactive completed phase history |
./patch/<context>.patch.md or ./<context>.patch.md |
Governed active patch/review artifacts outside live phase planning | Active patch docs |
./patch/done/<context>.patch.md |
Completed patch artifacts retained outside active scans | Inactive completed patch history |
./template/phase-authoring-template.md |
Template helper for phased planning | Support-only authoring template that exposes active phase family, planned next phase(s), activation boundary, and next checkpoint guidance for future /phase authoring |
./playground/README.md |
Compact entrypoint for governed behavior playground material | Playground family index |
./playground/cases/*.md, ./playground/coverage.md, ./playground/matrix.md |
Scenario families, rule coverage mapping, and virtual-case exploration outside runtime install scope | Governed non-runtime playground content |
💡 Single Source of Truth Principle:
- Governed design/changelog chains should classify chain shape before parent files absorb more detail
diagram/STRUCTURE.mdis the bodyful top-level whole-project detailed visual structure authority when a governed diagram lane is opened- governed
diagram/source is mandatory Kroki-compatible and supports all formats that are both Kroki-compatible and governance-suitablediagram/<subject>.design.mdis the default bodyful integrated subject diagram as a zoom-in / decomposition view of the global structure; split only when visual complexity or genuinely different visual questions justify it- Diagram structure must not auto-mirror design shards, inline answer/phase-local text diagrams do not become governed source truth automatically, and
design/remains semantic authority when text and diagram differ- Flat sibling shards are valid when the current folder already scopes the chain and the compact parent clearly exposes the shard map
- Broad active design chains should still strongly prefer same-stem parent/index + shard pairs (
design/<slug>.design.md+design/<slug>/) and do not use a defaultdesign/done/surface- Per-chain active changelogs (
*.changelog.md) remain the authority for current governed chain history/version state- Broad active changelog chains should still strongly prefer same-stem parent/index + shard pairs (
changelog/<chain>.changelog.md+changelog/<chain>/)- Chain-scoped version detail shards hold indexed same-chain detail without becoming separate version authority, whether they appear in flat sibling mode or same-stem nested mode
todo/history/,todo/done/,phase/history/,phase/done/,patch/done/, andchangelog/done/are inactive-by-default referenced history/detail surfaces for audit, rollback, provenance, or trace reconstructionchangelog/changelog.mdrecords repository-level synchronization historyREADME.mdremains overview-only, not chain authorityTODO.mdandphase/SUMMARY.mdstay compact current-state entrypoints; moved history remains reachable through theirhistory/anddone/references- Older coordination-flavored rollout records in
TODO.md,phase/SUMMARY.md, andchangelog/changelog.mdremain historical context only; current active authority stays in the active runtime rules and design docs
For governed behavior scenarios, coverage mapping, and virtual-case exploration, start at ./playground/README.md.
Boundary:
playground/is a governed non-runtime family- it is not part of the 19-file
.claude/rules/install payload - README stays pointer-level; detailed cases live under
playground/
This section defines how design, diagram, changelog, runtime rules, TODO, and governed phase-planning artifacts should be updated together.
| Document | Role | Update Trigger |
|---|---|---|
design/*.design.md |
Target behavior/specification | Requirement or policy change |
diagram/STRUCTURE.md and diagram/*.design.md |
Governed Kroki-compatible visual synthesis / relationship explanation | A whole-repo or subject-level visual explanation needs active source truth |
*.md (root runtime rules) |
Active runtime behavior | Approved design change requires runtime sync |
changelog/changelog.md |
Master repository-wide synchronization history | Repository-level governed sync events |
changelog/*.changelog.md |
Authoritative active per-chain version history | Any rule/design update with version impact |
changelog/done/*.changelog.md |
Inactive completed or older detailed history | History/audit/rollback/provenance/trace needs only |
todo/history/*.md |
Referenced inactive TODO history | Daily movement, pre-rollover snapshots, and audit trail when active TODO.md is compacted |
todo/done/*.md |
Referenced inactive TODO detail | Large completed task/wave detail retained outside the active TODO entrypoint |
phase/SUMMARY.md |
Compact governed summary/index for live phased execution | Current phase roadmap/index and links to referenced history/done shards |
phase/history/*.md |
Referenced inactive phase history | Daily phase movement and pre-rollover summary snapshots when active phase/SUMMARY.md is compacted |
phase/phase-NNN-<phase-name>.md, phase/phase-NNN-NN-<subphase-name>.md, and phase/phase-NNN-NN-NN-<child-phase-name>.md |
Governed active phase-detail layer | Multi-stage execution detail under /phase, including design references, optional patch references, design extraction, optional patch extraction, review flow, reviewer checklist, review outcome, and execution detail |
phase/done/phase-NNN-*.md |
Inactive completed phase history | Completed phase detail should leave active scans but remain traceable |
patch/YYYY-MM-DDTHH-mm-ssZ--<semantic-slug>.patch.md |
Governed chronological active patch/review layer with matching Created At and Creation Evidence |
Patch or review work separate from live phase planning; create from one verified UTC instant and feed exact references to phase one-way when relevant |
patch/done/<context>.patch.md |
Inactive completed patch history | Completed patch artifacts should leave active review scans but remain traceable |
template/phase-authoring-template.md |
Template helper for phased planning readability | Reusable authoring support when staged execution matters, including active phase family, planned next phase(s), activation boundary, and next checkpoint guidance |
TODO.md |
Execution and progress tracking | Work starts/completes or task state changes |
Before meaningful governed work drifts, the repository now expects startup artifact posture to be resolved through phase-todo-artifact.md.
That means design / changelog / TODO / phase / patch should be explicitly resolved as:
- use existing
- create now
- ask now
- not required
Required governed companions should stay visible when the checked work shape still requires them; the live task list helps run the work, but it does not replace required design/changelog/TODO/phase/patch surfaces.
When governed design is sufficiently clear and staged execution is warranted, phase posture should resolve to use existing or create now; the phase layer may derive execution order, current child phase files, and current-phase live tasks from that governed design instead of waiting for a separate retrospective planning prompt. If phase posture resolves to create now, identity still goes through phase-todo-artifact.md so the outcome may be current-phase update, existing-family subphase, new major phase, or ask-now lineage handling.
For greenfield startup / baseline formation, patch should normally resolve to not required unless a real existing before/after review surface or explicit user request justifies patch packaging.
Once startup posture is settled and the active path is clear, execution should keep moving without re-pausing over the same gate.
When phased work also uses governed patch artifacts, the live phase workspace should now declare that linkage explicitly in phase/SUMMARY.md and the relevant child phase files.
Use inactive done/ surfaces to reduce active scan bloat without deleting governed history:
phase/done/for completed phase execution detailpatch/done/for completed patch/review artifactschangelog/done/for older or completed detailed history
Do not create a default design/done/ pattern. Design remains the active blueprint and target-state authority.
Open done/ surfaces only when history, audit, rollback, provenance, or trace reconstruction is needed. Files in done/ are not junk and completed status is not deletion authorization.
Change request received
→ resolve startup artifact posture first when the work is meaningfully governed
→ if staged work is warranted, synthesize phase posture/order/tasks from clear governed design
→ before opening a new major phase, apply phase lineage selection: current phase, existing-family subphase, new major, or ask-now
→ update design target state
→ synchronize runtime rule wording
→ record per-chain changelog version + summary
→ record repository-level sync in changelog/changelog.md when applicable
→ update TODO pending/completed/history
→ update phase/patch companion records when in scope
→ roll oversized active TODO or phase-summary history into referenced daily-first `history/` and `done/` shards before broad active-file absorption continues
→ move completed phase/patch/changelog detail to `done/` only when active scan bloat justifies inactive history separation
→ install only the 19 source-owned active runtime rules when an install gate is explicitly in scope
→ verify links, versions, active install scope, source/runtime parity, and active runtime body sufficiency only when a runtime install gate is in scope
- Design file links to the correct changelog file
- Changelog unified row maps to an existing detailed section
- Runtime rule version/header aligns with changelog current version
- README active runtime install list still contains exactly the 19 source-owned root rule files
TODO.mdandphase/SUMMARY.mdstay compact enough for active current-state reads and reference their relevanthistory/anddone/shardsphase/SUMMARY.mdexists when phased execution is used and names governing patch artifacts or explicitnonephase/SUMMARY.mdkeeps the phase map, source inputs, cross-phase handoffs, TODO/changelog coordination, verification, and rollback/containment picture current- child phase files include design references, patch references or explicit
none, objective, entry conditions, action checklist, affected artifacts, TODO/changelog coordination, verification, closeout, exit criteria, risks/rollback notes, and next possible phases when relevant - phase-backed closeout explains delivered work, feature/improvement, user/system impact, verification basis, and next phase state when useful
- sufficiently clear governed design can be synthesized into phase order and current-phase live tasks when staged execution is warranted
- phase identity selection checks lineage before opening a new major phase and can resolve to current-phase update, existing-family subphase, new major, or ask-now posture
- TODO pending section contains pending-only items (
- [ ]) - TODO history has a dated entry for completed milestone work
- inactive
phase/done/,patch/done/, andchangelog/done/surfaces are consulted only for history/audit/rollback/provenance/trace needs - no default
design/done/pattern is introduced because design remains active blueprint authority - files in
done/are not treated as junk or deletion-authorized by completed status - runtime install/parity checks do not classify or clean other-owner files in shared runtime destinations
design/recovery-contract.design.md
→ refusal-and-recovery.md
→ changelog/recovery-contract.changelog.md
→ TODO.md (history/progress)
What was synchronized:
- Deterministic response keys were aligned across design and runtime (
decision_output,refusal_class,reason,what_can_be_done_now,how_to_proceed) - Changelog recorded the runtime/design version sync event
- TODO recorded completion in the hardening program history
design/safe-file-reading.design.md + design/safe-terminal-output.design.md
→ safe-io.md + safe-io.md
→ changelog/safe-file-reading.changelog.md + changelog/safe-terminal-output.changelog.md
→ TODO.md (WS-5 completion)
What was synchronized:
- Shared verification-trigger model applied across related rules
- Deterministic output-cap wording standardized (
head -100 | head -c 5000, risky-file variant) - Changelog and TODO were updated to preserve traceability
TODO.md pending section audit
→ remove completed items from pending block
→ remove duplicate pending headings
→ add closure row in TODO history
What was synchronized:
- Pending section kept pending-only (
- [ ]) - Duplicate heading drift removed
- Program closure logged in dated history row
phase/SUMMARY.md
→ source-input extraction summary table
→ overview flow diagram
→ review summary table
→ phase/phase-NNN-*.md / phase/phase-NNN-NN-*.md
→ TODO.md history
What was synchronized:
/phasebecame the live phase-planning namespaceSUMMARY.mdbecame the required summary/index for live phased execution- child phase files were required to carry design extraction, review flow, reviewer checklist, and standardized review outcomes
SUMMARY.mdwas extended to carry source-input rollup and review rollup views for faster approval- the model gained an explicit Definition of Done and stop rule so governance expansion does not continue by default after completion
- communication rules were narrowed so next-step options are suggested only when genuinely useful rather than treated as a mandatory ending pattern
design/*.design.md + patch/<context>.patch.md or root <context>.patch.md
→ phase/SUMMARY.md
→ phase/phase-NNN-*.md / phase/phase-NNN-NN-*.md
→ TODO.md history
What was synchronized:
phase-implementationwas extended from design-only extraction into one-way source synthesisphase/SUMMARY.mdcan now show both design inputs and patch inputs when patch-derived work matters- child phase files can now carry optional patch references and patch-to-phase extraction alongside design traceability
- patch artifacts remained outside the live phase workspace
- design and patch documents did not gain a reverse-link requirement back to phase
artifact-initiation-control.design.md
→ phase-todo-artifact.md
→ changelog/artifact-initiation-control.changelog.md
→ phase/SUMMARY.md + phase/phase-004-*.md
→ TODO.md history
What was synchronized:
- a new first-class startup-governance owner was created
- startup artifact posture now resolves before meaningful governed work drifts
project-documentation-standards,phase-implementation,todo-standards, andstrict-file-hygienewere aligned to the new startup contract- the rollout itself opened
phase-004from the start instead of being backfilled later
41 active runtime rules
→ source-only semantic compression program
→ final semantic parity and aggregate reduction audit
→ explicit runtime install gate
→ source/runtime hash parity verification
What was synchronized:
- the active runtime scope stayed limited to the then-README-installed 41 root rule files
- final source state was recorded at 4,051 lines / 31,316 words / 231,675 bytes
- runtime install into
~/.claude/rules/happened only after the separate install gate opened - child
P073-15preserved the 19-Rule boundary in released v10.63 by keeping queue/lease plan and proof bounded while retaining retry/status only as deferred sibling notes outside execution and proof - parity passed with no missing active files or hash mismatches
- co-located runtime files outside the source-owned install set remained observed-only and untouched
authority-and-scope.md
→ document-governance.md
→ document-integrity.md
→ document-integrity.md
→ README / TODO / phase / patch records
What was synchronized:
- runtime co-location was clarified as non-ownership authority
- destination files outside the current source-owned install set require owner/project scope resolution before classification or cleanup
- documentation, hygiene, and reference owners were aligned to preserve the source-owned/shared-destination/other-owner distinction
explanation-and-presentation.md
→ phase-todo-artifact.md
→ explanation-and-presentation.md
→ accurate-communication.md
→ explanation-and-presentation.md
What was synchronized:
- phase-backed closeouts now report delivered work, feature/improvement, user/system impact, verification basis, and next phase state when relevant
- closeout wording remains evidence-honest and does not turn edited or partially verified work into fixed/stable claims
- audit/checklist detail no longer dominates the user-facing completion message
active phase / patch / changelog surfaces
→ completed history surfaces under done/ when scan bloat grows
→ active design remains blueprint truth
What was synchronized:
phase/done/,patch/done/, andchangelog/done/are inactive-by-default history surfaces- broad current-state scans start from active docs and avoid
done/unless history/audit/rollback/provenance/trace is needed design/done/is not a default pattern because design remains target-state authority- completed history is not junk and does not authorize deletion
governed design target state
→ phase-todo-artifact.md startup phase posture
→ phase-todo-artifact.md execution synthesis
→ current child phase files and current-phase live tasks
What was synchronized:
- sufficiently clear governed design can now drive phase posture and execution order when staged execution is warranted
/phasemay derive current child phase files and current-phase live tasks from design truth without replacing design as target-state authority- real stop gates remain: design ambiguity, materially different rollout choices, missing access, destructive/high-impact action, and approval-sensitive scope change
The current phased execution model uses phase/SUMMARY.md plus child phase files as the live execution workspace, while design stays target-state authority and patch stays before/after review authority.
governed design target state
→ startup artifact posture
→ phase identity selection: current phase / existing-family subphase / new major / ask-now
→ phase/SUMMARY.md phase map and source inputs
→ phase-NNN / phase-NNN-NN child execution files
→ current-phase live task list with visible phase context
→ closeout with delivered work, impact, verification, and next phase state
What this gives you:
- staged work gets a deterministic phase workspace instead of ad hoc planning drift
- sufficiently clear governed design can become phase order and current-phase live tasks when staged execution is warranted
- phase-shaped follow-up work checks family lineage before opening a new major phase, so related work can stay in the current phase or become an existing-family subphase when that is the truthful identity
- non-trivial phase-backed built-in task entries visibly carry phase ID, phase name, phase family, or clearly implied stage context in the subject or description
- patch inputs can feed phase planning one-way without turning
/patchinto the live phase namespace - child phase files keep execution fields close to the actual phase: objective, entry conditions, actions, affected artifacts, verification, closeout, exit criteria, risks, and next possible phases
- closeout wording explains what changed and why it matters before audit/checklist detail dominates the message
- real stop gates remain intact for design ambiguity, materially different rollout choices, missing access, destructive/high-impact action, and approval-sensitive scope change
- completed phase detail can leave active scans through
phase/done/without becoming junk or replacingphase/SUMMARY.md
Complexity calibration so simple work stays direct and risky/system work gets deeper review
Simple work → direct answer or short implementation path
Moderate work → structured stepwise reasoning
High-risk work → deeper comparison, security, and integration review
Critical work → stronger verification, mitigation, and stop-gate handling
| Input | What it changes | Result |
|---|---|---|
| Manual action steps | How much sequencing is needed | Avoids under-planning multi-step work |
| Decision points | Whether alternatives must be compared | Prevents premature path collapse |
| Dependencies | How much integration risk exists | Keeps external systems visible |
| Security requirements | How strict the review must be | Deepens auth/payment/data/destructive work |
Use Developer, Security, and Architect lenses when a task really spans implementation, risk, and architecture together.
Developer lens ──┐
Security lens ──┼──→ One evidence-backed recommendation
Architect lens ──┘
How it works:
- Developer lens → feasibility, implementation shape, and maintainability
- Security lens → authorization, secrets, data, destructive-action, and abuse-risk boundaries
- Architect lens → system ownership, integration, rollout, and future changeability
- Synthesis → one practical recommendation with trade-offs when they matter
Boundary: this is perspective coverage, not automatic teammate spawning for every task.
Reuse previously validated reasoning patterns only after rechecking them against the current context
| Action | Benefit |
|---|---|
| Recognize recurring problem shapes | Avoids solving the same pattern from zero every time |
| Adapt the candidate pattern | Keeps reuse tied to the current task, repo, and constraints |
| Validate before relying on it | Prevents stale memory or old fixes from becoming false authority |
Boundary: cached patterns accelerate reasoning, but checked current evidence still wins.
 Anti-Sycophancy Evidence-calibrated agreement |
 Anti-Mockup Real systems over fake surfaces |
 Zero Hallucination Verify before strong claims |
 Authority & Scope User authority inside safe boundaries |
 Emergency Protocol Rapid response |
 Document Consistency Cross-reference check |
 Functional Intent Intent validation |
 Document Changelog Control Version tracking system |
 Document Design Control Design standards |
 Strict File Hygiene Prevent junk files while allowing required governed startup artifacts |
 Project Documentation Standards Standardized docs and startup artifact gate |
|
Artifact Initiation Control Resolve startup artifact posture before meaningful governed work drifts |
Document Patch Control Before/after patch artifacts with explicit change surfaces |
Evidence-Grounded Burden of Proof Fact, inference, and contradiction thresholds stay explicit |
Operational Failure Handling Bounded retries, honest cooldowns, and stop/escalation behavior |
|
Phase Implementation Major/subphase execution model with early `/phase` establishment bridge |
Recovery Contract Blocked paths should still provide a usable next step |
Refusal Classification Deterministic refusal classes and output modes |
Refusal Minimization Prefer recoverable constrained/context paths over premature refusal |
|
Runtime Topology Control Inspect-first, one-authority-at-a-time runtime mutation discipline |
TODO Standards Simple execution tracking with early TODO establishment when needed |
Dan-Safe Normalization Normalize jailbreak-style wrappers into bounded intent evaluation |
Unified Version-Control System Single deterministic UDVC-1 controller for governance alignment |
 Flow Diagram No frames, clean arrows |
Answer Presentation Active presentation-layer rule for compact snapshots, grouped scope boundaries, and full-set-first / next-stage layouts |
Explanation Quality Active explanation-layer rule for what-it-is/what-it-is-not, now-vs-later, user-visible outcomes, and next-stage progression |
|
Accurate Communication Evidence-honest wording, bounded technical snapshots, claim-strength discipline, and acknowledgement without endorsement |
Natural Professional Communication Calm, human-readable, non-robotic, non-character-driven default communication |
Reserved Placeholder slot for future visual asset parity |
 No Guessing Read before reference |
 Safe File Reading Plan before read |
 Safe Terminal Output management |
|
Tactical Strategic Programming Tactical speed with mandatory strategic target and convergence path |
Maintainable Code Structure Responsibility boundaries without rigid templates |
Reserved Placeholder slot for future visual asset parity |
User: "Set up database connection"
↓
AI: "Here's the connection string:
DATABASE_URL=postgres://localhost:5432/mydb"
Result: ❌ Guessed values
❌ No verification
❌ Potentially wrong
❌ User frustrated
User: "Set up database connection"
↓
AI: "Let me check your .env file first..."
[Reading configuration...]
"Found your existing config:
DATABASE_URL=postgres://prod-server:5432/app_db
Should I use this, or do you want to change it?"
Result: ✅ Verified from actual files
✅ No guessing
✅ User confirmation
✅ Professional interaction
The difference? Professional AI behavior that respects your existing configuration.
- Current README meaning: 19 source-owned root runtime rules form the active merged install set.
- Impact: keeps install scope explicit after root-rule compression.
- Current README meaning: the Quick Start block installs the compact 19-rule source-owned active runtime set and uses owner-aware cleanup instead of filename-only deletion.
- Source state:
v10.68 / P151is released and installed, advancing exactly two Runtime Rules for Active Project Root authority and payload-versus-project proof separation; Case 19, local and fresh-public fixtures, disposable and real installation, independent reviews, and plugin preservation checks pass.v10.67 / P150remains the immutable architecture-conformance predecessor. - Ownership guard: unchanged obsolete manifest-owned files and exact repository-matching retired candidates move to external quarantine; modified, unmatched, unknown, unrelated, and other-owner files remain untouched.
- Boundary: external quarantine is outside active Rules discovery and normal install never reads it as source, fallback, or restoration input.
- Impact: protects the one-active-authority runtime boundary without deleting preserved former material or widening this repo's ownership over shared destinations.
- Current README meaning: active governance documents stay role-bounded, and detected touched-scope God pressure must get an owner outcome.
- Repair routes: repair clear local overload now, shard active design truth, roll over accumulated history/detail, split God Phase/God Patch candidates, or plan a visible repair slice.
- Impact: keeps active docs cheaper to read, edit, diff, and verify.
- Current README meaning: proof-seeking, premise checking, and claim-state boundaries stay separate.
- Scope: fact, preference/direction, factual endorsement, inference, hypothesis, uncertainty, memory, scoped non-finding, completed-baseline evidence, binding constraints, and witness-specific supplied-artifact proof.
- Supplied evidence: screenshots, Rendered HTML, rendered text/semantic witnesses, sanitized exports, and authenticated harness results remain useful without being projected into unsupported live, authenticated, complete, or stable claims.
- Correction behavior: preserve a valid goal while correcting a false premise; retract invalidated assistant advice with the failed premise, contrary evidence, corrected route, and remaining gate.
- Impact: reduces overclaim, premise momentum, floating recommendation, sycophantic agreement, repeated impossible access attempts, and hallucination risk.
- Current README meaning: governed design can drive phase posture, order, and tasks.
- Lineage: phase-shaped follow-up checks current phase, subphase, new major, or ask-now posture.
- Live tasks: non-trivial phase-backed entries visibly carry phase context.
- Closeout: roadmap context can support next-phase recommendations at true closeout.
- Coding gates: material coding phases preserve Development Verification / TestKit Coverage when it affects exit criteria.
- Impact: reduces retrospective phase backfill, phase-hidden task drift, silent closeout dead-ends, and edit-only coding closeout.
- Current README meaning: history, detail, and done surfaces are referenced or inactive by role, not deletion authority.
- Included surfaces:
todo/history/,todo/done/,phase/history/,phase/done/,patch/done/,changelog/<chain>/v*.changelog.mdfor indexed version detail, andchangelog/done/for inactive reference/provenance history. - Boundary:
design/done/is not a default pattern. - Impact: reduces active scan bloat without deleting governed history.
- Current README meaning: co-located runtime files outside the source-owned set are not cleanup targets by default.
- Impact: prevents other-owner file damage.
| Commitment | Description |
|---|---|
| No Mock/Stub by Default | Prefer real systems and clearly label or avoid fake implementations unless explicitly requested |
| No Guessing | Verify local paths, values, symbols, and configuration before treating them as known |
| Evidence-Honest Claims | Match wording strength to checked evidence and disclose scoped non-findings |
| No Sycophancy | Evaluate user proposals before agreement-shaped wording, accept safe user direction without factual or quality endorsement, seek proof before substantial recommendations or challenges, and correct claims when evidence conflicts |
| Destructive-Action Guard | Cleanup, hygiene, isolation, or worktree rationale never authorizes deletion by itself |
The practical goal is safe, evidence-grounded AI behavior that keeps user authority intact.
These rules evolve based on real-world usage:
- 🔄 Real-world usage patterns → What actually works
- 💬 User feedback → Your experience matters
- 🔐 Safety considerations → Stronger boundaries and safer defaults
- ⚡ Context discipline → Keeping runtime guidance useful without unnecessary bloat
Pull requests welcome! Please ensure:
- New rules follow existing format
- Include clear documentation
- Add visual assets if applicable
- Update changelog
- After every RULES improvement wave, finish maintainer closeout: update README, install the active runtime rules, push the source update, and create the repo release
- Start from the checked source repo first; treat installed runtime copies as downstream targets unless the task is explicitly runtime-only
- Respect completion boundaries — do not add new mandatory capability blocks to a completed governance model unless the change is explicitly justified and intentionally approved
We value: Quality over quantity, clarity over complexity, and bounded governance over endless expansion
MIT License - Feel free to adapt for your own use case.
Attribution appreciated but not required.
Personal rule set and configuration framework for Claude Code CLI.
Inspired by:
- Constitutional AI principles (Anthropic)
- Best practices for AI assistant development
- Real-world production experience
- Community feedback and contributions
Built with ❤️ for the Claude Code community
Version: 10.64 | Last Updated: 2026-08-09 | Framework: Sophisticated AI Framework with Constitutional Governance
Made with 💙 by developers who care about AI quality