Methodology
How We Build
The composite framework governing how coexo is planned, designed, and built. Borrowing from TOGAF (sequencing), Hoshin Kanri (strategy cascade), and OKRs (measurement) — adapted for a single-author, vision-first product.
Vision, Not Documentation
Coexo describes the ideal Cognitive Exoskeleton — the system we would build if we started fresh, using everything learned from the current prototype (OpenClaw + Telegram + Dymont DB). It is not a documentation site for the running system.
- —Every page is vision content — including Infrastructure, System Context, and Building Blocks.
- —No page should be filled by scraping current server state or inventorying what's running today.
- —Every page needs collaborative discussion to define what the ideal system looks like, then code follows.
- —The current system is the learning lab. Coexo is the blueprint for what comes next.
Strategy Cascade
Mission flows down to every methodological choice and platform feature. Three layers, each building on the one above.
Mission & Vision
Mission, north star metrics, guiding principles. The WHY behind everything. Drives all other layers. Lives at /mission.
Methodology & Runtime
How coexo operates as a system — the framework above, the concrete scenarios below. Lives at /methodology and /runtime.
Building Blocks, Strategy & Infrastructure
The platform that enables Layer 2. Technical building blocks, solution strategy, deployment. Lives at /blocks, /strategy, /infrastructure.
The rule: Every feature must trace back through these layers to the mission. If a feature can't answer "which north star does this serve?" — it either shouldn't exist or is missing its strategic connection.
Planning Sequence
A deliberate sequence from strategy to delivery. Vision comes first — system design follows. Each step depends on the one before. Don't skip ahead.
Define the mission, measurable north stars, and principles on /mission
Document the composite framework on /methodology
Define how coexo should behave — interaction model, ideal workflows
Extract concrete scenarios derived from the behavioral spec on /runtime
Prioritize use cases into MVP / Phase 2 / Future on /roadmap
MVP use cases dictate the tech stack, documented on /strategy
Document decisions on /strategy + /decisions
Create Dymont DB Cases per feature, start development
Traceability
Every element on this site must be able to answer: "Which north star does this serve?" If a feature can't trace back to the mission, it either shouldn't exist or is missing its strategic connection.
The Traceability Chain
Collaboration Protocol
How Stephan and Claude Code work on coexo together — what stays collaborative versus what Claude just does once a direction is locked.
Mission, methodology, section visions
Always discussed before drafting — never write vision unprompted
Concrete scenarios per actor
Claude proposes, Stephan validates against intent
What gets built first
Claude presents options, Stephan picks
Lane changes, new items
No lane changes without explicit confirmation
Tech choices with rationale
Claude researches and recommends, Stephan approves
After vision is locked
Build to spec from /methodology + /developer
Content in src/lib/data/
Content changes — always rebuild + deploy after
Cosmetic fixes
No discussion needed
The rule: If it shapes whatcoexo is → collaborative. If it's how a decided thing gets built → Claude just does it.
Constraints
Constraints that shape every decision — technical, financial, temporal. These directly influence MVP scope and stack choices.
To be drafted.
arc42 Semantics
The site follows an adapted arc42 template. Understanding what goes where prevents content from landing in the wrong section.
The Core Distinction: Structure vs. Behavior
arc42 separates what the system has (structure) from what the system does (behavior). Mixing them up is the most common mistake.
The system's structure. Components, modules, subsystems. "What parts does coexo have?" Think anatomy.
The system's behavior. Concrete use cases showing how requests flow. "What does coexo actually do for people?" Think physiology.
Decision Tree: Where Does Content Go?
Pages → arc42 Section Mapping
Each page on the site maps to an arc42 section. The Building Block View uses C4-inspired progressive zoom (Level 2 grid → Level 3 section → Level 4 component).
| Route | Page | arc42 § | Purpose |
|---|---|---|---|
| / | Overview | §1 Introduction & Goals | What is the Cognitive Exoskeleton? Philosophy, key quality goals. |
| /context | System Context | §3 Context & Scope | External systems and boundaries — what's inside vs outside. |
| /strategy | Strategy | §4 Solution Strategy | Core philosophy (observe → understand → decide → act → learn). Tech choices and rationale. |
| /blocks | Building Blocks | §5 Building Block View | The core of the site. Architecture sections as a navigable grid with C4 zoom. |
| /blocks/[section] | Section detail | §5 Level 3 | Vision, components, and implementation status for a single section. |
| /blocks/[section]/[component] | Component detail | §5 Level 4 | Individual skill/adapter/cron — what it does, config, links. |
| /runtime | Runtime View | §6 Runtime View | How signals flow through the system — sequence diagrams, process flows. |
| /infrastructure | Infrastructure | §7 Deployment View | Servers, containers, services, domains, networking, monitoring. |
| /patterns | Patterns | §8 Crosscutting Concepts | Patterns spanning multiple sections: auth, security, error handling. |
| /decisions | Decisions | §9 Architecture Decisions | ADR-style log of important architecture choices and rationale. |
| /notes | Project Notes | — | Staging inbox for ideas before they are placed into a canonical page. |
| /changelog | Changelog | — | Reverse-chronological log of site changes. |
Sections We Skip
arc42 has 12 standard sections. We adopt the ones that add value and skip the enterprise-heavy ones. The framework is a guide, not a cage — these can be added later if the system grows to need them.
Common Mistakes to Avoid
- 1.Putting use cases inside building blocks
A use case that spans multiple blocks belongs in Runtime — not inside any one block.
- 2.Treating building blocks as features
Blocks are containers, not deliverables. A roadmap item is a deliverable; a building block is a part of the system.
- 3.Confusing Strategy with Decisions
Strategy (/strategy) is the overall approach. Decisions (/decisions) are specific choices with ADR-style rationale.
- 4.Writing current-state documentation
Everything is vision. Don't describe what exists today — describe what the ideal system looks like.