_registry-protocol

Project Defaults Registry Protocol

This protocol is MANDATORY for ALL commands, agents, and phases.

The registry at specs/_defaults/registry.yaml is the single source of truth for project-wide technical decisions. You MUST follow this protocol to ensure consistency.

---

On Entry (Before Any Work)

Step 1: Load Registry

Read: specs/_defaults/registry.yaml

If file doesn't exist, warn user:

⚠️ No project defaults registry found at specs/_defaults/registry.yaml
   Consider running project initialization or creating defaults manually.
   Proceeding without defaults - all decisions will be feature-specific.

Step 2: Filter to Your Domain

Only extract sections relevant to your current work:

If you're working on...	Read these sections
Backend / API	api, backend, database
Frontend / UI	frontend, ui_specs, conventions
Infrastructure / DevOps	infrastructure, testing
Full-stack feature	All sections

Step 3: Apply Defaults

When generating specs, plans, or code:

• Pre-populate fields from registry values
• Mark registry-sourced values with comment: # from: _defaults/registry.yaml
• Never silently use a different value than what's in registry

---

During Work (Decision Detection)

Scenario A: Decision EXISTS in Registry

Action: Use it. No question. No deviation without explicit approval.

Example:

# Registry has:
api:
  versioning: url

# Your spec/plan MUST use:
API Versioning: url-based (/api/v1/*)  # from: _defaults/registry.yaml

Scenario B: Decision NOT in Registry (null or missing)

Action: Check if it's a project-wide concern, then ask.

1. Determine scope:

   • Project-wide: Would other features benefit from this same choice?
   • Feature-specific: Only relevant to this particular feature?

2. If project-wide, use AskUserQuestion:

┌─────────────────────────────────────────────────────────────┐
│ 📋 NEW PROJECT DEFAULT DETECTED                             │
├─────────────────────────────────────────────────────────────┤
│ Key: api.pagination                                         │
│ Proposed value: cursor                                      │
│ Context: Decided during billing feature planning            │
│                                                             │
│ This appears to be a project-wide decision.                 │
│ Future features would benefit from consistency here.        │
├─────────────────────────────────────────────────────────────┤
│ Options:                                                    │
│ ○ Add to project defaults (all features will use this)     │
│ ○ Keep as feature-specific (only this feature)             │
│ ○ Reject (don't use this value)                            │
│ ○ Other...                                                  │
└─────────────────────────────────────────────────────────────┘