Context
Creating new Value Streams and Management Practices requires:
- Creating a specific folder structure with 6-10 files
- Populating frontmatter with correct metadata fields
- Following naming conventions (Title Case, “Management” suffix, VS code format)
- Ensuring MECE compliance (no overlap with existing VS/Practices)
- Updating CODEOWNERS entries
- Cross-referencing related practices
This process was entirely manual, relying on Obsidian Templater templates (TMP01, TMP03) and human diligence. This was error-prone (inconsistent frontmatter, missing folders, naming violations) and created friction for contributors.
Decision
Implement a GitHub-native automation system:
- GitHub Issue Forms as the structured input mechanism
- GitHub Actions workflows triggered on issue creation to validate, scaffold, and create PRs
- Node.js ESM scripts for validation, MECE checking, file generation, and CODEOWNERS management
- GitHub Models API for AI-powered semantic overlap detection
- Content validation CI workflow as a quality gate on all content PRs
The scaffolding scripts own the template logic (inline template strings), superseding the Obsidian Templater files TMP01 and TMP03.
Consequences
Positive
- Zero manual scaffolding — complete folder structure generated from structured inputs
- Governance enforcement via deterministic validation
- MECE integrity via AI-assisted semantic analysis
- Audit trail from issue → PR → merge
- CODEOWNERS proactively managed
Negative
- Templates for VS/Practice creation are now in JavaScript, not easily editable Obsidian markdown
- Requires GitHub Actions minutes (minimal — runs only on issue creation)
- AI MECE check adds dependency on GitHub Models API (graceful degradation if unavailable)
Neutral
- Obsidian Templater templates TMP00 (Decision), TMP02 (Guild), TMP05 (Product) remain unchanged
- Obsidian Templater plugin continues to work for remaining template types
- Historical plan documents retain references to TMP01/TMP03 as immutable records
Alternatives Considered
1. Enhanced Obsidian Templater Scripts
Use Templater’s JavaScript execution capabilities to add validation and folder creation.
- Pros: Stays within Obsidian ecosystem; familiar to content authors
- Cons: No CI enforcement; no MECE checking; no audit trail; only works locally; no CODEOWNERS management
- Why not chosen: Doesn’t address governance requirements
2. CLI Script (npm run create:vs)
Local Node.js script with interactive prompts.
- Pros: Fast local feedback; no GitHub dependency
- Cons: No audit trail; no MECE checking; requires local Node.js setup; bypasses governance
- Why not chosen: Doesn’t create the issue → PR → review governance chain
3. GitHub Actions with Manual Trigger (workflow_dispatch)
Workflow triggered manually after issue approval rather than on issue creation.
- Pros: Adds an explicit approval step before scaffolding
- Cons: Extra manual step; the PR itself already serves as the review/approval gate
- Why not chosen: The PR review process provides sufficient governance control
Related Decisions
- Plan 01: Governance Model & Content Structure (established the folder patterns)
- CODEOWNERS Deferred (established team structure expectations)
- Plan 06: Site UX Improvements (established page-list auto-population)
Date: 2026-02-17 Decided By: Leadership Team Approved By: [Pending]