Linotype v3

Linotype v3 introduces explicit slug intent: Directional vs Build.

What changed

Explicit slug types

Previously, slugs were undifferentiated. Now:

• Directional slugs: explore options, make decisions, sequence work
• Build slugs: implement concrete changes with proof

This separation clarifies when you’re deciding vs doing.

Clearer role boundaries

• PDA (Product Design Authority): owns system coherence, frames work, validates end-to-end
• Module Architect: owns module correctness, designs within boundaries
• Builder: executes build slugs (often same person as Module Architect)
• Reviewer: verifies proof and coherence before completion

Standardized review gate

All build slugs must include proof before moving to review:

• Preview URL
• Screenshot
• Test output
• Commit/diff

The linotype.sh script enforces this requirement.

Enhanced documentation structure

v3 introduces:

• docs/context/app-context.md - High-level product snapshot
• docs/capabilities/ - Module specs and capability registry
• Starter slugs (SLUG-001 and SLUG-002)
• Automated workflow via linotype.sh

Bootstrap script

The linotype-bootstrap.sh script creates the complete structure:

• Core documentation files
• Workflow automation
• Templates
• Starter slugs
• Optional AI assistant integration

Migration from v2

If you’re on v2:

1. Run linotype-bootstrap.sh in a test directory to see the new structure
2. Add docs/context/app-context.md to your existing repo
3. Create docs/capabilities/registry.yml and module specs
4. Update linotype.sh to the v3 version (with start/check/review/done commands)
5. Review existing slugs and ensure build slugs have proof
6. Clarify who owns PDA vs Module Architect responsibilities

Why these changes

v3 emerged from real usage patterns:

• Teams mixed exploration with implementation, causing confusion
• Unclear role boundaries led to bottlenecks
• Slugs moved to “done” without validation
• New team members needed clearer onboarding
• Projects needed better structure for capabilities and modules

The changes make implicit practices explicit and provide better scaffolding for teams.

v4 and beyond

v4 adds Galleys (folder-based, lifecycle with optional queue), focus & optimise, parallel workflow (worktrees, one Executor per galley), and the agent contract (_agent-rules.md + AGENTS.md). See v4 and Galleys.