MasteryMade · Foundation PRD

PRD 1: Org Registry + MANUAL.md Spec

1.1 Purpose

The org registry is the coordination layer between all parallel build lanes. Without it, services can't discover each other, contracts diverge, and parallel work creates integration debt. This PRD defines the Supabase schema, the MANUAL.md template, the HC page auto-publish pipeline, and the self-healing loop.

1.2 Supabase Schema — Full Column Definitions

Table: services

Column	Type	Constraints	Description
id	UUID	PK, gen_random_uuid()	Service identifier
name	TEXT	NOT NULL, UNIQUE	Human-readable (e.g., "expert-research")
type	ENUM	'skill'/'service'/'agent'/'workflow'/'mcp'	What kind of thing
status	ENUM	'active'/'building'/'planned'/'deprecated'	Lifecycle state
owner	TEXT	NOT NULL	'jason'/'sumit'/'lee'/'forge'/'agent_swarm'
description	TEXT		One-paragraph capability summary
capabilities_json	JSONB		{ inputs: [], outputs: [], triggers: [], limitations: [] }
input_schema	JSONB		JSON Schema for what this service accepts
output_schema	JSONB		JSON Schema for what this service produces
manual_path	TEXT		File path to MANUAL.md
hc_url	TEXT		Published HC page URL
dependencies	TEXT[]		Array of service names this depends on
gate_access	INT[]		Which gates this operates in (e.g., {1,2,3})
version	TEXT		Current version string
created_at	TIMESTAMPTZ	DEFAULT now()
updated_at	TIMESTAMPTZ	DEFAULT now()	Auto-updated via trigger

Table: entities

Column	Type	Constraints	Description
id	UUID	PK	Entity identifier
name	TEXT	NOT NULL	"Samuel / Align360", "Tony Robbins"
type	ENUM	'expert'/'prospect'/'competitor'/'niche'/'company'/'person'	Classification
gate	INT	NOT NULL, CHECK (1-4)	Primary gate assignment
related_entities	UUID[]		FK references to other entities
ingestion_status	ENUM	'not_started'/'partial'/'complete'	Content ingestion progress
content_sources	JSONB		{ youtube: [], podcast: [], website: "", social: {} }
extraction_progress	JSONB		{ module_1: "complete", module_2: "in_progress", ... }
pipeline_stage	TEXT		"identified"/"researched"/"pre-pitch"/"reveal"/"signed"/"deployed"
metadata	JSONB		Flexible: audience_size, niche, positioning
created_at	TIMESTAMPTZ	DEFAULT now()
updated_at	TIMESTAMPTZ	DEFAULT now()

Table: contracts

Column	Type	Constraints	Description
id	UUID	PK
service_a	TEXT	NOT NULL, FK services.name	Caller
service_b	TEXT	NOT NULL, FK services.name	Called
contract_name	TEXT	NOT NULL	"ingest-to-suggest-edge-detection"
input_schema	JSONB	NOT NULL	What service_a sends
output_schema	JSONB	NOT NULL	What service_b returns
version	TEXT	NOT NULL	Semver
locked_at	TIMESTAMPTZ		When both agreed — NULL if drafting
breaking_changes	TEXT[]		Log of breaking changes
created_at	TIMESTAMPTZ	DEFAULT now()

Table: registry_changelog

Column	Type	Constraints	Description
id	UUID	PK
entity_type	ENUM	'service'/'entity'/'contract'/'manual'	What changed
entity_id	UUID		FK to changed record
change_type	ENUM	'created'/'updated'/'deprecated'/'corrected'/'learned'
change_detail	TEXT	NOT NULL	What changed and why
session_ref	TEXT		Which session triggered this
changed_by	TEXT		'jason'/'sumit'/'forge'/'auto'
timestamp	TIMESTAMPTZ	DEFAULT now()

Indexes

services: UNIQUE on name, INDEX on status, type. entities: INDEX on type, gate, pipeline_stage. contracts: UNIQUE on (service_a, service_b, contract_name, version). registry_changelog: INDEX on entity_type, timestamp DESC.

RLS

All tables readable by any authenticated client. Services can only UPDATE their own row (matched by name). registry_changelog is append-only (no updates, no deletes).

1.3 MANUAL.md Template

# [SERVICE_NAME] — MANUAL.md
**Version:** [semver]  |  **Owner:** [name]  |  **Status:** [active/building/planned]
**Registry:** [link]  |  **HC Page:** [link]

## Identity
[One sentence: what this service does and why it exists.]

## Capabilities
### What it does
- [Capability 1 — input → output]
- [Capability 2 — input → output]

### What it does NOT do
- [Explicit boundary 1]

## Input Schema
{ ... JSON Schema ... }

## Output Schema
{ ... JSON Schema ... }

## Dependencies
| Service | Contract | What we need from it |
|---------|----------|---------------------|

## Failure Modes
| Failure | Symptom | Recovery | Learned from |
|---------|---------|----------|--------------|

## Changelog
| Date | Version | Change | Learned from |
|------|---------|--------|--------------|

## Temporal Traces
[Version history. What used to work vs. what works now and why.]

1.4 HC Page Auto-Publish Pipeline

Trigger: MANUAL.md created or updated (git commit, Forge file write, or manual trigger).

1. Read MANUAL.md from file system
2. Parse frontmatter (version, owner, status)
3. Generate HTML page with: hc-metadata (service identity, compliance tier, capabilities), hc-instructions (behavioral rules for any AI consuming this), hc-context-public (full I/O schemas in machine-readable JSON), visible HTML body (human-readable manual)
4. Publish to plan.jasondmacdonald.com/manual/[service-name] via NowPage MCP (update_mode: replace)
5. Register in command center
6. Update services table: set hc_url, updated_at

Implementation: n8n workflow triggered by webhook (Forge calls after MANUAL.md write) OR scheduled scan of /mnt/skills/ for modified files.

1.5 Self-Healing Loop

On new failure mode

1. Service logs failure to its own MANUAL.md changelog (append)
2. Writes to registry_changelog with change_type='learned'
3. If failure involved a contract → flag contract for review
4. HC page auto-publish triggers, updating web version

On user correction

1. Service logs correction to MANUAL.md with "learned from: [user] in [session]"
2. registry_changelog entry with change_type='corrected'
3. If correction changes I/O behavior → update capabilities_json, trigger contract review

1.6 Runtime Pointer Spec

MANUAL.md = canonical source. Runtime files are thin pointers that add provider-specific behaviors:

CLAUDE.md: "Read MANUAL.md. Apply these Claude-specific prompting patterns, tool-use syntax, context window management strategies." GEMINI.md: "Read MANUAL.md. Apply Gemini-specific visual annotation, multimodal processing." OPENAI.md: "Read MANUAL.md. Use these function-calling conventions."

Manual is permanent institutional knowledge. Runtime config is swappable. Switch from Claude to Gemini → MANUAL.md stays, only runtime pointer changes.

1.7 Batch Generation Plan — 24 Existing Skills

Agent swarm reads /mnt/skills/, for each SKILL.md: extract name/description/triggers/capabilities/dependencies → generate MANUAL.md → identify failure modes → create changelog → publish HC page → register in org registry.

Priority tiers

Tier	Skills	Rationale
1 (no deps)	calibrate, handoff, morning-kickstart, session-close	Standalone, quick wins
2 (frameworks)	321-exec, 321-framework-jason, jason-guardian, 2026-execution	Personal operating system
3 (content)	jason-writer, jason-editor, blue-ocean, linkedin-growth, prompt-architect	Content pipeline
4 (expert)	expert-research, expert-doc-processor, expert-clone-scorer, expert-test-extractor, expert-os-deployment	Core extraction chain
5 (infra)	n8n-builder, n8n-* stack, meta-arch, arch, leverage	Build infrastructure
6 (specialized)	meeting-tracker-sumit, meeting-tracker-will-derek, extract-to-lists	Team-specific

1.8 Registration API

POST /api/registry/register
{
  "name": "new-service-name",
  "type": "skill",
  "owner": "jason",
  "description": "What this does",
  "capabilities_json": { ... },
  "manual_path": "/path/to/MANUAL.md",
  "dependencies": ["other-service"],
  "gate_access": [1, 2]
}
→ Creates services row, registry_changelog entry, returns ID.
Implementation: Supabase Edge Function OR n8n webhook.

1.9 Acceptance Criteria

• All 4 Supabase tables created with proper types, constraints, indexes, RLS
• MANUAL.md template finalized and stored in /mnt/skills/templates/
• HC auto-publish pipeline working end-to-end (MANUAL.md → NowPage page)
• At least 3 existing skills have generated MANUAL.md + HC pages as proof of concept
• Registration API accepting new service registrations
• registry_changelog recording all changes with session references
• Self-healing loop demonstrated (simulate failure, verify logged)