Formwork Protocol

Earlier versions of this portfolio site were the first casualties. An AI assistant would produce clean, consistent work in the first session. The next session, it would make architectural decisions that contradicted the first. By the third, the conflicts had cascaded: layouts breaking, naming conventions overwritten, dependencies pointing at things that no longer existed. Structural failures too severe to patch, requiring complete teardowns.

The problem wasn’t the AI. The problem was that the project’s decisions lived in my head. A new session had no way to know what had already been settled.

In concrete construction, you build formwork before you pour. The form gives shape while things are still fluid. Once the concrete sets, the form comes off. The shape holds on its own.

That’s what a project needs when the decisions are still moving: a structure that carries the institutional memory so no contributor has to.

I tried written rules first. Agents treat them as suggestions. I tried running agents in parallel. Each one assumed a different definition of “done.” I spent more time reconciling agent disagreements than solving actual problems.

The constraint: you cannot rely on any contributor, human or AI, to remember what’s been decided. The decisions have to be somewhere they’ll be found before new work starts.

The first version was two markdown files at the project root. A conventions file recorded every architectural choice: what was decided, when, why, and what it replaced. A symbol index mapped the dependencies. The project carries its own context.

# CONVENTIONS.md (simplified)

## Storage Configuration [CURRENT]
Last Verified: 2026-01-21

| Drive | Mount            | Role           | Status   |
|-------|------------------|----------------|----------|
| sda2  | /                | System + Media | 94% full |
| sdb1  | /media/5tb-b1    | Mirror         | 100%     |
| sde2  | /media/7tb-main  | Primary        | 91%      |

## Decision Log
- 2025-11-14: Chose rsync over rclone (reason: ...)
  Replaces: manual cp commands
- 2025-12-03: Standardized mount naming (reason: ...)
  Replaces: inconsistent /mnt vs /media paths

The inconsistencies stopped. Fidelity to the original decisions came for free; they were findable before they could be contradicted.

Then I over-built it. A Node.js enforcement engine, JSON prompt blueprints, a meta-orchestrator that validated compliance. I built all of it because I didn’t trust the simple version to hold.

The simple version held. The enforcement engine gathered dust.

When Claude Code shipped native support for CLAUDE.md (a file at the project root that gets read before every session) it adopted the same pattern. Not because I influenced the platform. Because the architecture is obvious once you’ve felt the problem.

# CLAUDE.md — Session Startup

## ⚠️ Do This First
1. Read CONVENTIONS.md completely
2. Check "Last Verified" dates
3. If ANY section is older than 30 days, STOP

## Tech Stack
- Jekyll 4.4.1, SCSS, GitHub Pages
- Collections: _governance/, _infrastructure/, _output/

## Workflow Rules
- Run `bundle exec jekyll build` after pulling
- Edit only main.scss, never main.css
- Use / for internal links

## ⚠️ Copy Work — Mandatory Protocol
Any time you write copy for this site, you MUST
read the voice protocol first. Not optional.

Every active project runs this pattern now. Each one carries its own decisions, conventions, and boundaries in files that get read before anything moves. The homelab infrastructure, the portfolio site, the Savepoint Protocol repo, client projects: all of them carry their own context.

The base protocol generated a toolkit: a traversal skill for mining ideation history, an audit system, a copywriting system with enforced voice protocol. All of them read from the same context files.

# /copy skill — Story Discovery + Voice Enforcement

Commands: /copy check, /copy edit, /copy write

## Knowledge Escalation (mandatory before writing)
1. Read the project file (frontmatter + body)
2. Check _data/index.json artifact summaries
3. Search ideation history (52,000+ indexed documents)
4. If nothing usable: STOP. Interview Peter.

Never invent specifics. Generic is better than false.

## Banned vocabulary
paradigm, leverage, passionate, innovative, synergy,
empower, journey, explores, transformative

## Voice test
- Is there a real person in this text?
- Could you hear someone say this out loud?
- Does every specific detail trace to a verified source?

# Frontmatter schema — every project page

altitude: "01"          # Governance / Infrastructure / Output
context:  "..."         # The problem or constraint
drift:    "..."         # The gap between intent and execution
scaffold: "..."         # The structural solution
fidelity: "..."         # The validation or result
faculty:  [design, engineering, uxia]

The protocol isn’t two markdown files anymore. It’s the architecture the tools operate on. Each project carries its own decisions. Each skill reads them before it moves. Each page’s frontmatter encodes the same four-part structure: what went wrong, what drifted, what was built, what held.

The Colophon shows what this protocol looks like running on the site you’re reading now.