Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

```html

Migrating Tech Blog Workflow to 5-Layer Model Workspace Protocol: Token Efficiency & Reproducibility

What Was Done

We piloted a structural refactor of the tech.sailjada.com blog publication workflow from a monolithic context model to a layered, stage-gated architecture. The goal: reduce per-session token load by 30× while maintaining full editorial control and making the workflow reproducible across teams.

The existing setup loaded ~10,925 tokens on every blog-writing session:

  • repos/CLAUDE.md (942 tokens) — generic root-level map
  • queenofsandiego.com/CLAUDE.md (3,420 tokens) — massive auto-load mixing Layer 0 strategy with Layer 3 pricing/deploy/competitor rules
  • tech_blog_generator.py (6,563 tokens) — monolithic generator with all stage logic inline

The refactor migrated the blog workflow into workspaces/tech-blog/ with five stages (01-topic → 02-research → 03-draft → 04-publish → 05-review), each with its own Layer-2 CONTEXT.md and isolated artifact storage. Target: ~370 tokens to start a post.

Technical Details: The 5-Layer Architecture

Layer 0 (Root Map)

Created workspaces/tech-blog/CLAUDE.md (~80 tokens):

  • Lists the four stage directories and their purpose
  • Pointers to reference/voice.md (brand voice & tone guidelines)
  • No inline logic; purely a router
  • Never auto-loaded; users explicitly cd into stage directories

Layer 1 (Router & Constants)

Created workspaces/tech-blog/CONTEXT.md (~120 tokens):

  • Declares blog metadata: publication domain, S3 bucket, staging domain, social handles
  • Lists all four stages with entry/exit criteria
  • Explains the artifact naming convention: <stage>_<slug>_<timestamp>.md
  • References the voice guide

Layer 2 (Per-Stage Context)

Created four stage directories, each with identical structure:

workspaces/tech-blog/01-topic/
  ├── CONTEXT.md          (~150 tokens)
  └── artifacts/
      └── <artifacts from this stage>

workspaces/tech-blog/02-research/
  ├── CONTEXT.md          (~180 tokens)
  └── artifacts/

workspaces/tech-blog/03-draft/
  ├── CONTEXT.md          (~200 tokens)
  └── artifacts/

workspaces/tech-blog/04-publish/
  ├── CONTEXT.md          (~160 tokens)
  └── artifacts/

Each stage's CONTEXT.md contains:

  • Stage purpose & acceptance criteria — what "done" means for that stage
  • Input expectations — what artifacts it expects from the prior stage
  • Tools & templates — code snippets, shell commands, or Claude instructions specific to that stage
  • Output spec — format & naming of artifacts passed to the next stage
  • No duplication — voice guidelines linked, not embedded

Layer 3 (Reference)

Created workspaces/tech-blog/reference/voice.md (~100 tokens):

  • Brand voice, tone, audience, structural templates (e.g., "Problem → Why It Matters → Technical Explanation → Code Example → Takeaway")
  • Loaded only when explicitly needed, not on every session
  • Single source of truth for editorial standards across all stages

Layer 4 (Artifacts)

Per-run outputs stored in <stage>/artifacts/:

  • 01-topic: topic proposal, audience profile, keyword research
  • 02-research: source list, outline, fact-check notes
  • 03-draft: full post markdown, code samples, diagram descriptions
  • 04-publish: final HTML, metadata JSON, social preview image, schedule payload

Infrastructure & Deployment

Storage

  • Staging bucket: s3://tech-sailjada-staging/ — holds draft posts & assets pre-publish
  • Production bucket: s3://tech-sailjada-prod/posts/ — live published articles
  • CloudFront distribution: DISTID E1AB2C3DEF4GH points to prod bucket; staging uses separate dist E5IJK6L7MNOPQR
  • Cache invalidation: publish stage triggers aws cloudfront create-invalidation --distribution-id E1AB2C3DEF4GH --paths '/*'

DNS & Routing

  • Production: tech.sailjada.com (Route53 alias to CloudFront dist E1AB2C3DEF4GH)
  • Staging: staging-blog.sailjada.com (Route53 CNAME to separate CloudFront dist)
  • Preview generation: post stage 03 creates a short-lived staging URL for editorial review

Key Decisions & Why

Why 5 Layers?

Separating stages isolates context. A researcher doesn't see deploy logic; an editor doesn't see topic brainstorming notes. This reduces cognitive load and keeps prompts focused. Token load scales with *stage scope*, not with entire blog history.

Why Named Artifact Dirs?

Each stage's output becomes input to the next. Explicit artifact naming (01-topic_kubernetes-sidecar-injection_2026-06-03-14h22m.md) makes it unambiguous which version is "current." No digging through timestamps or guessing which markdown file to load.

Why Separate Voice Guide?

Voice & tone guidelines are reference material, not operational context. They're loaded only when writing or reviewing, not when brainstorming topics. This was the single biggest token sink in the old queenofsandiego.com/CLAUDE.md.

Why CloudFront + S3?

Blog posts are static HTML & assets. CloudFront caches at edge;