Specs vs Docs Architecture

Overview

JellyLabs.ai maintains a deliberate separation between two types of content:

Content Type	Location	Purpose	Mutability
Specifications	/spec/*	Normative, authoritative definitions	Immutable per version
Documentation	/docs/*	Explanatory, educational content	Can evolve freely

Why Separate?

Specifications are Contracts

When you publish a specification:

• External systems may depend on its exact wording
• Version numbers carry semantic meaning
• Breaking changes require new major versions
• Past versions must remain accessible and unchanged

Documentation is Living

Educational content should:

• Improve based on user feedback
• Add examples as questions arise
• Clarify confusing sections
• Stay current with best practices

Mixing these concerns creates problems:

• Fear of improving explanations (might break something)
• Unclear what’s normative vs illustrative
• Difficulty tracking which changes are breaking

Current Architecture

Single Site, Dual Routes

jellylabs.ai/
├── /spec/          # Specifications (normative)
│   ├── /didp/v1    # DIDP v1 - frozen
│   └── /ppp/v1     # PPP v1 - frozen
└── /docs/          # Documentation (explanatory)
    ├── /methodology
    ├── /workflow-contract
    └── ...

Why Not Separate Sites Now?

Decision: Single site during early development Rationale: Splitting now would stifle development velocity

Early-stage concerns:

• Overhead of managing two repositories
• Coordination cost for simple changes
• Unclear boundaries while protocols evolve
• Need for rapid iteration

Future Architecture

Mandatory Split at Maturity

When trigger conditions are met, the architecture MUST split:

specs.jellylabs.ai/     # Canonical specifications only
docs.jellylabs.ai/      # All explanatory content

Trigger Conditions

Split when ANY of these occur:

1. External Contributors

   • Multiple external contributors to documentation
   • Different governance needs for specs vs docs

2. Velocity Divergence

   • Documentation updates exceed spec updates 10:1
   • Different release cadences needed

3. Governance Requirements

   • Need separate approval workflows
   • Different review standards

4. Community Confusion

   • Users unclear what’s normative vs explanatory
   • Citation issues in academic/professional contexts

Migration Path

When triggered:

1. Create jellylabs-ai/docs repository
2. Move /docs/* content to new repo
3. Deploy to docs.jellylabs.ai
4. Add cross-links between sites
5. Update canonical URLs if needed
6. Announce to community

Content Guidelines

What Belongs in /spec/

• Protocol definitions
• Formal requirements (MUST, SHOULD, MAY)
• Version-locked behavior
• Normative examples
• Schema definitions

What Belongs in /docs/

• Tutorials and guides
• Best practices
• FAQ and troubleshooting
• Architecture explanations
• Illustrative examples
• Decision logs
• Contributor guides

Gray Areas

When unsure, ask:

• “Would changing this break existing implementations?” → Spec
• “Would changing this help users understand better?” → Docs
• “Is this prescriptive or descriptive?” → Prescriptive = Spec

Examples

Spec Content (Normative)

## Phase Transitions

Phases MUST transition in the following order:
planning → analysis → spec_lock → implementation → testing → archive → merge → complete

Back-transitions are ONLY permitted from analysis to planning
when `replan_required: true`.

Doc Content (Explanatory)

## Understanding Phase Transitions

Think of phases like a one-way street with a single U-turn point.
You can only go forward, except during analysis where you might
realize "wait, we need to rethink this" and loop back to planning.

This constraint exists because...

Summary

• Specs = frozen contracts, versioned, immutable
• Docs = living explanations, can evolve freely
• Current = single site for development velocity
• Future = mandatory split at maturity
• Rule = when in doubt, it’s probably docs