Skip to main content
← Back to list
01Issue
FeatureShippedSwamp CLIPublic
Assigneesstack72

Relationships

#1901 docs(design): reorganise design/ around the six primitives

Opened by stack72 · 8/28/2026· Shipped 8/28/2026

Summary

Reorganise design/ around the six primitives a user reasons in: Models, Data, Workflows, Vaults, Extensions, and Serve. A subsystem earns a doc only by naming the primitive it enables; everything else is a runbook, an ops note, or not worth a doc.

Problem

The design folder has 27 markdown files, 14k lines, no index, no status lines, and the three biggest subsystems (Serve, access control, auth) have no doc at all. The docs are mostly accurate but unnavigable — three audiences (operators, extension authors, maintainers) are interleaved in single 1,400–1,800-line files with no table of contents. Proposals read as shipped; shipped features read as proposals.

Solution

  1. Frame and label — Create folder structure (primitives/, enablers/, surfaces/) and design/README.md with the six-primitives rule as its organising principle. Add audience / enables / last-verified headers to every file. Delete three unbuilt proposals and the superseded execution-drivers doc. Relocate process docs to contributing/.

  2. Write the missing primitivesprimitives/data.md (pulled up from three existing places) and primitives/serve.md (deployment modes, HA, detached runs, boot reconciliation, hot reload, dashboard).

  3. Architecture overviewarchitecture.md tells the story across the six primitives top-down, linking into each doc. Replaces the 82-line high-level.md.

  4. Fix verdict extraction — The verification workflow's verdict parser used head -5 and lowercase-only matching, causing "verdict: missing" failures on large diffs. Fixed to search the full output with case-insensitive grep and markdown bold handling.

What landed on branch

  • Folder shape with primitives/enablers/surfaces hierarchy
  • primitives/data.md and primitives/serve.md written from source
  • architecture.md as the cross-doc story
  • All path references across src/, skills, README, and CLAUDE.md updated
  • Four deletions (quests, workflow-run-output, unification, execution-drivers)
  • contributing/skills-pipeline.md and contributing/cli-and-libswamp.md relocated
  • Verification verdict extraction fix for large diffs
  • Every doc fact-checked against source (120+ claims verified)

Remaining (from the two-week plan)

  • Per-doc refreshes (expressions, inputs, vaults, workflow reorder)
  • Monolith splits (datastores → 3, extension → 2, remote-execution → 3)
  • Stale facts batch fix
  • Glossary
  • operations.md for non-primitive subsystems

Design doc: https://claude.ai/code/artifact/c4da0ae9-98e2-4c2d-8cb0-cd5f30b922da Branch: design-docs-structure

02Bog Flow
OPENTRIAGEDIN PROGRESSSHIPPED+ 1 MOREASSIGNED+ 2 MOREREVIEW+ 11 MOREPR_MERGED+ 2 MORESESSION_SUMMARIZED

Shipped

8/28/2026, 11:10:20 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
stack72 assigned stack728/28/2026, 10:55:43 PM

Sign in to post a ripple.