Parchment Programming Methodology 0.1

Create your own magic with Web 7.0 DIDLibOS™ / TDW AgenticOS™. Imagine the possibilities.

Copyright © 2026 Michael Herman (Bindloss, Alberta, Canada) – Creative Commons Attribution-ShareAlike 4.0 International Public License
Web 7.0™, Web 7.0 DILibOS™, TDW AgenticOS™, TDW™, Trusted Digital Web™ and Hyperonomy™ are trademarks of the Web 7.0 Foundation. All Rights Reserved.

Parchment Programming is an architecture-first software development methodology where a richly annotated visual diagram — the “parchment” — serves as the primary design document and intermediate representation (IR) that an AI coding assistant (like Claude) reads directly to generate correct, idiomatic code.

Rather than translating requirements through layers of prose specifications, the diagram itself encodes stereotypes, interface contracts, project boundaries, data models, and protocol annotations in a form that is simultaneously human-readable and AI-actionable — invented by Michael Herman, Chief Digital Officer, Web 7.0 Foundation. April 2026.

How Claude Processes Parchment Inputs

Claude receives a conversation context containing images + text. The key facts:

• Claude can see a diagram image and reason about it
• Claude can read structured Markdown/text with full fidelity
• Claude cannot cross-reference between an image region and a text table by coordinate — it reasons about both holistically
• Therefore: the diagram handles spatial/structural truth; the companion document handles behavioral/contractual truth

This is actually a clean separation of concerns.

The Recommended Hybrid Architecture

ParchmentSpec_DSA_0.16_Epoch0/
├── diagram.png                  ← the visual (spatial truth)
├── PARCHMENT.md                 ← master spec (behavioral truth)
└── schemas/
    ├── didcomm-envelope.json
    ├── did-doc.json
    └── vc-doc.json

The PARCHMENT.md is the primary AI coding input. The diagram is embedded in it — not appended, not separate — embedded at the top, so Claude sees it as the structural foundation before reading the annotations.

PARCHMENT.md Optimal Structure for Claude

# Web 7.0 DSA 0.16 Epoch 0 — Parchment Spec
## 1. Architecture Diagram
![DSA 0.16 Epoch 0](./diagram.png)
## 2. System Identity
- Spec DID: did:drn:...
- Epoch: 0  |  Version: 0.16
- Target runtime: .NET 8 / C# 12
- Codegen mode: AI-scaffolded + human-completed
## 3. Component Fact Table
| Component | Artifact | Lifecycle | Multiplicity | Thread-safe |
|-----------|----------|-----------|--------------|-------------|
| RunspacePool | RunspacePoolManager.cs | Singleton | 1 | Yes |
| Agent Runspace | AgentRunspace.cs | Pooled | 1..N | Isolated |
| LOBE | LobeLoader.cs | On-demand | 0..N | No |
| DIDComm Switchboard | DIDCommSwitchboard.cs | Singleton | 1 | Yes |
...
## 4. Connector / Protocol Index
| From | To | Protocol | Payload Type | Schema Ref |
|------|----|----------|--------------|------------|
| Internet | DIDComm Listener | DIDComm V2 | DIDCommEnvelope | schemas/didcomm-envelope.json |
| Switchboard | Agent Runspace | Internal | AgentMessage | (inline below) |
...
## 5. Data Contracts
### Fast Cache (LiteDB)
- Key: `msg:{did}:{timestamp}`
- TTL: 300s
- Fields: SenderId, Payload, ReceivedAt
### DID Doc Registry (LiteDB)
- Key: `did:drn:{resourceId}`
- Fields: (per did:drn spec, draft-herman-did-drn-00)
...
## 6. Trust Boundary Policies
- **Green zone (TDA-internal):** No encryption required; integrity only
- **Purple zone (DIDComm-authenticated):** All messages MUST be SignThenEncrypt
- **Yellow zone (Internet):** Untrusted until Unpack validates DIDComm envelope
## 7. AI Codegen Manifest
| Component | Generation Mode | Acceptance Criteria |
|-----------|----------------|---------------------|
| RunspacePoolManager | AI-generated | Min/max pool size enforced |
| DIDCommSwitchboard | AI-scaffolded | Routes all registered types |
| Svrn7XferService | Hand-authored | SRC ledger integrity |
## 8. Open Questions (Do Not Invent)
- LOBE hot-reload: supported or restart-required?
- Fast Cache eviction policy when LiteDB full?
- CIPHER algorithm selection: Ed25519 only or negotiated?
## 9. Excluded from AI Generation
- SVRN7 SRC transaction signing
- NEO4J CIPHER graph schema
- VTC7 federation handshake

Why This Works Best With Claude

The critical insight is section 8 — the Open Questions Log. Claude’s failure mode when coding from underspecified inputs is silent invention. Explicitly naming unknowns instructs Claude to emit // TODO: [OPEN QUESTION - LOBE hot-reload policy] rather than inventing an answer.

Three additional Claude-specific optimizations:

1. Use the diagram as a spatial index, not a spec. In your prompt to Claude, say: “The diagram shows containment and flow. The PARCHMENT.md sections 3–9 are authoritative for all behavioral details. Where they conflict, the Markdown wins.” This prevents Claude from over-reading visual ambiguities.

2. Keep sections 3–7 machine-parseable. Claude handles Markdown tables extremely well as structured input. Avoid prose paragraphs for anything that should drive code generation — tables and bullet lists are more reliably parsed into code structure.

3. Submit diagram + PARCHMENT.md together in every coding prompt. Claude has no persistent memory of previous sessions, so the full parchment must be present each time. The compact table format makes this token-efficient.

The Better Approach You Asked About

There is one additional technique worth considering: annotated diagram variants. Rather than modifying the master diagram, you maintain lightweight overlay versions for specific concerns:

diagram.png              ← master (as-is, no changes)
diagram-trust-zones.png  ← same diagram + colored zone overlays
diagram-dataflow.png     ← same diagram + numbered flow sequence

These are fast to produce (PowerPoint/draw.io layer toggles) and can be embedded in targeted sections of PARCHMENT.md. Claude sees each as a focused lens on the same architecture without the master diagram becoming cluttered.

Bottom Line

The PARCHMENT.md is the intermediate representation. The diagram is its most important section — but only one section.