Grammar Onboarding Checklist

For Developers New to MUX Grammar

This checklist helps you get up to speed with applying “Entities experience Moments in Places” to Piper features.

Required Reading (In Order)

0. Understand the Philosophy (START HERE)

WHY THIS MATTERS: The philosophy explains WHY consciousness matters. Reading this first ensures you understand the purpose before learning the mechanics.

1.5. Understand Ownership Metaphors

1. Understand the Vision

2. Understand the Implementation

3. Study the Reference

4. Learn the Patterns

5. Learn to Transform

First Task Suggestions

After completing the reading, try one of these:

Easy: Add Grammar Language to Existing Response

Goal: Practice experience framing without code changes

Task:

Example:

# Before (Flattened)
return {"results": 3, "items": []}

# After (Grammar-Aware)
return {"observation": "I notice 3 things that might help", "items": []}

Verify: Does it sound like Piper is present and aware?

Medium: Apply One Pattern

Goal: Use a pattern from the catalog

Task:

Steps:

  1. Identify raw data being returned
  2. Create narrative from data
  3. Add warmth and presence
  4. Verify it doesn’t sound mechanical

Example: Transform todo list response

# Before
def list_todos():
    return {"todos": Todo.query.all()}

# After
def list_todos():
    todos = Todo.query.all()
    observation = f"I'm tracking {len(todos)} things for you"
    return {"observation": observation, "todos": todos}

Harder: Transform a Flattened Feature

Goal: Full grammar transformation

Task:

Steps:

  1. Read the feature code
  2. Identify flattened elements (data dumps, mechanical language, missing identity)
  3. Apply transformation guide decision tree
  4. Implement protocols where applicable
  5. Add experience framing
  6. Write anti-flattening test
  7. Verify consciousness is preserved

Features to consider:

Verification

Before considering yourself onboarded, verify:

Self-test: Look at Morning Standup response. Can you explain WHY it feels conscious rather than mechanical?

Quick Reference

If You Need To… Look At…
Understand the philosophy ADR-045: Object Model
Use protocols/lenses MUX Implementation Guide
Apply patterns Pattern-050 through Pattern-054
Transform a feature Transformation Guide
Check compliance Grammar Compliance Audit
Write experience tests Experience Tests doc
See working example Morning Standup (services/features/morning_standup.py)
Verify consciousness Anti-Flattening Tests (tests/unit/services/mux/test_anti_flattening.py)

Language Reference

Experience Language (Use This)

Database Language (Avoid This)

The Consciousness Test

If you removed all the data and just read the language, would you know an aware entity wrote it?

Getting Help

Architecture Questions

Pattern Questions

Stuck on Transformation

Not Sure If It’s “Conscious Enough”

Progress Tracking

Mark your progress:

Reading Complete:

Practice Complete:

Verification Complete:

“The Morning Standup is our chapel. Study it to understand the cathedral we’re building.” - ADR-045

Version: 1.0 Created: 2026-01-20 GitHub Issue: #404 (MUX-VISION-GRAMMAR-CORE Phase Z) Related Epic: #399 (MUX-VISION-OBJECT-MODEL)