Ready to code?
Here is Claude's plan: ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ Plan: Standards Framework — Scalable Governance Architecture
Context
Standards are currently scattered: validation-standards.adoc in patterns/operations, project-structure.adoc in patterns/documentation, normative rules embedded in CLAUDE.md files. The Pattern Journal is explicitly a "field notebook" (descriptive, dated, experiential) — standards are fundamentally different (prescriptive, undated, enforceable). They need their own first-class section.
The user's vision: become a documentation and standardization expert across all facets of work. The framework must scale infinitely (add domains without restructuring) and be AI-agent-ready (machine-parseable, single lookup point).
Core distinction
┌─────────────┬───────────────────┬─────────────────────┬───────────────────┐
│ │ Standard │ Pattern │ Codex │
├─────────────┼───────────────────┼─────────────────────┼───────────────────┤
│ Voice │ Prescriptive │ Descriptive ("when │ Referential │
│ │ ("MUST") │ I hit X...") │ ("syntax is...") │
├─────────────┼───────────────────┼─────────────────────┼───────────────────┤
│ Temporality │ Undated — current │ Dated entries with │ Rarely changes │
│ │ truth │ context │ │
├─────────────┼───────────────────┼─────────────────────┼───────────────────┤
│ Scope │ Cross-domain, │ Single domain, │ Single tool, │
│ │ enforceable │ experiential │ lookup │
├─────────────┼───────────────────┼─────────────────────┼───────────────────┤
│ Audience │ Humans AND AI │ Humans reviewing │ Humans needing │
│ │ agents │ experience │ syntax │
└─────────────┴───────────────────┴─────────────────────┴───────────────────┘
Architecture
Nav placement: 2nd top-level section (after Strategic Objectives)
Strategic Objectives → WHERE we're going Standards → HOW we enforce quality (governance layer) Training Sessions → HOW we build skill Pattern Journal → WHAT we've learned (descriptive)
Directory structure
pages/standards/ ├── index.adoc # Framework — what is a standard, lifecycle, how to write one ├── registry.adoc # Master registry of ALL standards (including scattered ones) ├── operations/ # Change control, validation, deployment gates ├── documentation/ # Project structure, file naming, AsciiDoc conventions ├── security/ # Secrets handling, hardening ├── ai-interaction/ # Agent behavioral rules, delegation boundary ├── infrastructure/ # Deployment checklists └── workflow/ # CLI quality, verify-before-after
Scaling rule: Add new domain directories as needed. No restructuring required. Each domain gets an index.adoc only when it has ≥1 standard.
Standard document attributes (machine-parseable)
Every standard includes:
:std-id: STD-NNN
:std-status: Draft | Active | Superseded | Retired
:std-domain: operations | documentation | security | ai-interaction | ...
:std-owner: {author}
AI agents grep :std-status: Active to enumerate enforceable standards. CLAUDE.md references standards by STD-NNN ID, not file path.
Registry as bridge
The registry page (standards/registry.adoc) cross-references ALL standards regardless of current location. This solves the scattered problem immediately — no migration needed upfront.
| STD-001 | Project Structure | patterns/documentation/ (pending migration) | Active | | STD-002 | Validation Standards | patterns/operations/ (pending migration) | Active |
Migration path (non-disruptive)
-
Now: Create scaffold + registry. Existing files stay put.
-
Ongoing: New standards go directly into standards/<domain>/.
-
As touched: When an existing scattered standard is edited, migrate it then. Old location gets a note pointing to the new canonical location.
Phase 1 scope (what gets created now)
New files (7)
┌──────────────────────────────────────────┬─────────────────────────────────┐ │ File │ Purpose │ ├──────────────────────────────────────────┼─────────────────────────────────┤ │ │ Framework — defines what a │ │ pages/standards/index.adoc │ standard IS, lifecycle, writing │ │ │ guide │ ├──────────────────────────────────────────┼─────────────────────────────────┤ │ │ Master registry │ │ pages/standards/registry.adoc │ cross-referencing all standards │ │ │ by ID │ ├──────────────────────────────────────────┼─────────────────────────────────┤ │ │ Operations domain overview (has │ │ pages/standards/operations/index.adoc │ 2 existing standards to │ │ │ register) │ ├──────────────────────────────────────────┼─────────────────────────────────┤ │ │ Documentation domain overview │ │ pages/standards/documentation/index.adoc │ (has 1 existing standard to │ │ │ register) │ ├──────────────────────────────────────────┼─────────────────────────────────┤ │ partials/nav/standards.adoc │ Nav partial for the Standards │ │ │ section │ ├──────────────────────────────────────────┼─────────────────────────────────┤ │ pages/templates/TEMPLATE-standard.adoc │ Standard document template │ └──────────────────────────────────────────┴─────────────────────────────────┘
Modified files (2)
┌───────────────────────────┬────────────────────────────────────────────────┐ │ File │ Change │ ├───────────────────────────┼────────────────────────────────────────────────┤ │ │ Add include::partial$nav/standards.adoc[] │ │ nav.adoc │ after Strategic Objectives, add │ │ │ TEMPLATE-standard to Templates section │ ├───────────────────────────┼────────────────────────────────────────────────┤ │ pages/patterns/index.adoc │ Add note distinguishing patterns from │ │ │ standards with xref to standards framework │ └───────────────────────────┴────────────────────────────────────────────────┘
NOT created yet (seeded empty)
Domain directories for security, ai-interaction, infrastructure, workflow — these get created when their first standard is written. No empty stubs.
Framework index structure (standards/index.adoc)
-
Lead paragraph: "This is not a field notebook. These are normative governance documents."
-
Standards vs Patterns vs Codex comparison table
-
What makes a standard (5 criteria: normative language, compliance criteria, cross-context, owned, referenced as authority)
-
Standard lifecycle: Draft → Active → Superseded → Retired
-
How to write a standard (references TEMPLATE-standard.adoc)
-
RFC 2119 keywords: MUST, SHOULD, MAY
-
Domain index with xrefs
-
Relationship to CLAUDE.md (standards = source of truth, CLAUDE.md = enforcement mechanism)
Template structure (TEMPLATE-standard.adoc)
= STD-NNN: Standard Title :std-id: STD-NNN :std-status: Draft :std-domain: <domain> :std-owner: {author}== Principles (the non-negotiable "why") == Requirements (numbered, RFC 2119 keywords) == Compliance (how to verify — pass/fail deterministic) == Platform Adaptation (where behavior differs) == Exceptions (documented, justified — "none" is valid) == Related (patterns, codex, projects, CLAUDE.md)
Registry structure (standards/registry.adoc)
Master table with columns: ID, Title, Domain, Location, Status, Owner. Initially registers: - STD-001: Project Structure (patterns/documentation/, Active) - STD-002: Deployment Validation (patterns/operations/, Active) - STD-003: File Naming Conventions (embedded in CLAUDE.md, Draft — not yet standalone) - STD-004: AsciiDoc Conventions (embedded in CLAUDE.md, Draft — not yet standalone)
Verification
-
-
make 2>&1 | grep -E 'WARN|ERROR' — clean build
-
Nav renders Standards as 2nd top-level section
-
Registry page lists all known standards with correct xrefs
-
Template follows the document structure exactly
-
Framework index clearly distinguishes standards from patterns ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
Claude has written up a plan and is ready to execute. Would you like to proceed?
❯ 1. Yes, auto-accept edits 2. Yes, manually approve edits 3. Tell Claude what to change shift+tab to approve with this feedbackctrl-g to edit in Nvim · ~/.claude/plans/quiet-forging-koala.md
16 files, +1,799 lines, committed and ready. Just needs the push from a shell with your SSH agent.
✻ Baked for 32s
❯ can starndards go here as well and become partials too? where are they? do I not have stanards already that can be organized here?
● Good questions. Let me find what you already have that’s normative — the actual scattered standards hiding in your docs.
● Explore(Find existing normative content) ⎿ Done (35 tool uses · 67.8k tokens · 1m 30s) (ctrl+o to expand)
● That search found a lot. Here’s the honest picture.
You already have ~15 standards — they're just not called that
The normative content is scattered across three layers:
Layer 1: CLAUDE.md files (behavioral enforcement) - File naming conventions (13 prefixes) - AsciiDoc conventions (no :toc:, attributes over literals, build check) - Secrets handling (never print values, redact with <REDACTED>) - Delegation boundary (document-only default, explicit grant) - CLI quality (verify-before-after, idempotent commands)
Layer 2: Pattern Journal (normative disguised as patterns) - project-structure.adoc — "Every new project MUST follow this standard" - validation-standards.adoc — 40+ checks across 8 domains - change-management.adoc — "Verify-change-verify is non-negotiable" - systemd.adoc — "encrypt hook MUST come before btrfs and filesystems" - luks-btrfs.adoc — "Always format mapper devices, never raw partitions" - eap-tls.adoc — "Certificate CN and nmcli identity MUST match" - pki-certificates.adoc — "Each machine MUST have its own keypair" - vault-operations.adoc — "Always use -format=json and tee" - stow-dotfiles.adoc — "ssh:// URL format with :443 is required"
Layer 3: Infrastructure patterns with embedded rules - VLAN troubleshooting — "Services need explicit firewall rules per VLAN" - Hooks — "PreToolUse fires before execution, always exit 0" - Agent orchestration — "Never apply without reviewing the plan first"
On the partials question
You asked if standards should follow the partial+page pattern. Your own STD-001 says "partials hold content, pages are shells" — but that was written for projects. Here's the trade-off:
Partial+page gives you composability. A standard partial can be include::'d into multiple contexts — the standards section, a project's verification phase, a runbook. That's the "AI ready" argument: standards become building blocks, not monoliths.
Standalone pages are simpler. One file per standard, no shell/partial split to maintain. Every pattern journal page is standalone today.
Given your vision — scalable, composable, AI-agent-ready — the partial pattern is the stronger choice. It follows your own architectural principle and it means a project's Phase 11 page could include:: the validation standard directly rather than duplicating or cross-referencing it.
The structure would be:
partials/standards/
├── operations/
│ ├── validation.adoc # Content lives here
│ └── change-control.adoc
├── documentation/
│ ├── project-structure.adoc
│ ├── file-naming.adoc
│ └── asciidoc-conventions.adoc
├── security/
│ └── secrets-handling.adoc
└── ai-interaction/
└── delegation-boundary.adoc
pages/standards/ ├── index.adoc # Framework (standalone — not a shell) ├── registry.adoc # Registry (standalone) ├── operations/ │ ├── index.adoc # Domain overview (standalone) │ ├── validation.adoc # Shell → include::partial$standards/operations/validation.adoc[] │ └── change-control.adoc # Shell ├── documentation/ │ ├── index.adoc │ ├── project-structure.adoc # Shell │ └── ...
Do you want me to restructure to the partial+page pattern now and start migrating the existing scattered standards into the framework? That's a significant batch of work — probably 10-15 partials to extract and write. Or do you want to start with the framework as-is and migrate incrementally as each standard gets touched?
updates:
Here is Claude’s plan: ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ Plan: STD-009 Deep Enhancement + New Standards STD-016 through STD-020
Context
The structural audit of domus-captures found 2,954 .adoc files across 20 top-level page directories, 68 projects, 8 nav partials, and a 500+ file examples library. STD-009 has the abstract and skeleton but is missing critical structural details that would let someone replicate the system. Additionally, 5 content areas have normative conventions but no formal standards, creating deviation risk.
Part 1: Enhance STD-009 with verified structural metrics
What's missing from STD-009
-
Actual metrics: The repo has 2,954 files. STD-009 doesn’t state this — a replicator doesn’t know the expected scale.
-
Partials directory detail: STD-009 shows partials for nav, projects, standards, worklog, trackers, codex. Missing: reports/ (15 files), tasks/ (10), math/ (10), discoveries/ (8), education/ (4), objectives/ (2). These exist but aren’t documented.
-
Examples/ structure: STD-009 mentions examples/ briefly but doesn’t show the 20+ subdirectories (api/, codex/, commands/, diagrams/, etl-drills/, jq-drills/, lua-drills/, math/, monad/, music/, navigation/, python-drills/, regex-drills/, terminal/, etc.).
-
Scripts/ directory: 50+ bash/python scripts at repo root for content generation, PDF export, reMarkable sync. Not mentioned in STD-009 at all.
-
File count per section: education/ is 27% of all pages (789 files). Projects is 8.6% (255). Codex is 3.7% (110). This weight distribution matters for replication.
-
Portfolio section: 70+ project entries across 12 categories — not mentioned in the skeleton.
Changes to partials/standards/documentation/repository-architecture.adoc
Add after the Repository Skeleton section:
-
Repository Metrics section — file counts per directory, total .adoc count, key ratios
-
Partials Deep Structure — expand the partials tree to show ALL subdirectories (reports, tasks, math, discoveries, education, objectives)
-
Examples Library — full tree showing the 20+ subdirectories with purpose annotations
-
Scripts Directory — tree showing maintenance, migration, reMarkable tools
-
Portfolio — add to the pages skeleton (currently missing entirely)
Part 2: New Standards (STD-016 through STD-020)
STD-016: Codex Entry Format — CRITICAL
Why: 77+ pages across 12 categories. The codex is the tactical reference library. Without a format standard, entries drift between inline code, example includes, narrative, and raw snippets.
Governs: How every codex entry MUST be structured — title, description, lead paragraph, include::example$ for code, See Also cross-references.
Key rules: - Code content MUST live in examples/codex/<category>/ and be included via include::example$ - Category index pages MUST list all entries in a table - Every entry MUST have: title, :description:, :navtitle:, lead paragraph - Cross-references MUST link to related codex entries and pattern journal
STD-017: Portfolio Project Format — HIGH
Why: 70 projects across 12 categories with inconsistent status labels (17+ variants). Portfolio is the public-facing summary of all work.
Governs: How portfolio entries MUST be structured — status table, premise, goals, current state, next steps.
Key rules: - Status labels MUST use a controlled vocabulary: Complete, Operational, Active, In Progress, Planned, Parked, Blocked, Not Started - Every entry MUST have: Premise, Goals, Current State, Next Steps (checklist) - Status table MUST include Category and Status fields - Next Steps MUST use [ ] checklist format
STD-018: Training Session Curriculum — HIGH
Why: 8 active training tracks with varying structures (regex has 10 sessions, nvim has books+manuals, some have drills, others don't).
Governs: How training tracks MUST be organized — index with philosophy, sessions table, curriculum phases, guides.
Key rules: - Every track MUST have an index.adoc with Training Philosophy section - Sessions table MUST include: Session #, Focus, Duration (minutes), Status - Total curriculum time MUST be calculated and displayed - Tracks MUST define curriculum phases showing learning progression - Session files MUST use sequential numbering: 01.adoc through NN.adoc
STD-019: Discoveries Lifecycle — MEDIUM
Why: Micro-learning capture system with an explicit graduation rule ("graduate to Codex or Pattern Journal when used 3+ times") but no enforcement mechanism.Governs: How discoveries are captured, organized, and graduated.
Key rules: - Entries are append-only (never edit old entries) - Every entry MUST have: date, title, description, worklog reference - Graduation trigger: used 3+ times → promoted to Codex or Pattern Journal - Categories: tools, system, workflow
STD-020: Diagram Catalog Management — MEDIUM
Why: 77+ diagrams across 9 categories. No naming convention for source files, no standard for when to use D2 vs Graphviz vs Mermaid.
Governs: How diagrams are organized, named, and cataloged.
Key rules: - Diagram source in examples/diagrams/ or images/diagrams/ - Category index MUST include count per category - Naming convention for source files - Tool selection guidance: D2 for architecture, Graphviz for hierarchies, Mermaid for flows
Files to create/modify
Create (10 files — 5 partials + 5 shell pages)
┌─────────────────────────────────────────────────────────────┬──────────────┐ │ File │ Standard │ ├─────────────────────────────────────────────────────────────┼──────────────┤ │ partials/standards/documentation/codex-entry-format.adoc │ STD-016 │ ├─────────────────────────────────────────────────────────────┼──────────────┤ │ partials/standards/documentation/portfolio-format.adoc │ STD-017 │ ├─────────────────────────────────────────────────────────────┼──────────────┤ │ partials/standards/documentation/training-curriculum.adoc │ STD-018 │ ├─────────────────────────────────────────────────────────────┼──────────────┤ │ partials/standards/documentation/discoveries-lifecycle.adoc │ STD-019 │ ├─────────────────────────────────────────────────────────────┼──────────────┤ │ partials/standards/documentation/diagram-catalog.adoc │ STD-020 │ ├─────────────────────────────────────────────────────────────┼──────────────┤ │ pages/standards/documentation/codex-entry-format.adoc │ STD-016 │ │ │ shell │ ├─────────────────────────────────────────────────────────────┼──────────────┤ │ pages/standards/documentation/portfolio-format.adoc │ STD-017 │ │ │ shell │ ├─────────────────────────────────────────────────────────────┼──────────────┤ │ pages/standards/documentation/training-curriculum.adoc │ STD-018 │ │ │ shell │ ├─────────────────────────────────────────────────────────────┼──────────────┤ │ pages/standards/documentation/discoveries-lifecycle.adoc │ STD-019 │ │ │ shell │ ├─────────────────────────────────────────────────────────────┼──────────────┤ │ pages/standards/documentation/diagram-catalog.adoc │ STD-020 │ │ │ shell │ └─────────────────────────────────────────────────────────────┴──────────────┘
Modify (4 files)
File: partials/standards/documentation/repository-architecture.adoc Change: Add metrics, partials deep structure, examples library, scripts dir, portfolio ──────────────────────────────────────── File: pages/standards/documentation/index.adoc Change: Add STD-016 through STD-020 to table ──────────────────────────────────────── File: pages/standards/registry.adoc Change: Add STD-016 through STD-020, update max ID ──────────────────────────────────────── File: partials/nav/standards.adoc Change: Add 5 new nav entries under Documentation
Verification
-
-
make 2>&1 | grep -E 'WARN|ERROR' — clean build
-
Registry shows 20 Active standards
-
STD-009 metrics match find docs/modules/ROOT -name '*.adoc' | wc -l output
-
All 5 new standards have partial+page pairs
-
Nav shows all 20 standards ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
Claude has written up a plan and is ready to execute. Would you like to proceed?
❯ 1. Yes, auto-accept edits 2. Yes, manually approve edits 3. Tell Claude what to change shift+tab to approve with this feedbackctrl-g to edit in Nvim · ~/.claude/plans/quiet-forging-koala.md