# AI Agent Manifest PRD
Execute via Gemini Flash 2.0 Ralph Wiggum Loop

## Context
Build a machine-readable manifest system optimized for AI agents, not humans. Replaces visual sitemaps with grep-friendly, executable, status-aware component registry.

## Design Principles
1. **Machine-first**: YAML over Mermaid, flat over nested
2. **Executable**: Every component has a test command
3. **Queryable**: Grep patterns for common searches
4. **Stateful**: Health checks and last-verified timestamps
5. **Dependency-aware**: Know what breaks when X breaks

---

### US-001: Core Manifest Schema
**Goal:** Create the master YAML manifest with all Genesis components

**Acceptance Criteria:**
- GIVEN Genesis codebase WHEN manifest loaded THEN all 30+ components listed
- AND each component has: id, path, status, entry_cmd, test_cmd, depends_on
- AND includes health_check command for infrastructure components
- AND valid YAML that parses without errors

**Files to Create:**
- `/mnt/e/genesis-system/sitemap/agent_manifest.yaml`

**Technical Hints:**
Use flat YAML structure. Components: genesis_kernel, genesis_heartbeat, memory_cortex, blackboard, tool_router, rlm_bridge, graph_rag, synapse_linker, aiva_daemon, triple_gate_validator, universal_rwl_runner, ghl_mastery_skill, voice_wrapper_skill, telnyx_manager_skill. Status values: healthy, degraded, unknown, offline. Entry commands like "python genesis_kernel.py status". Test commands like "python -c 'from genesis_kernel import GenesisKernel'".

**Dependencies:** None

---

### US-002: Dependency Graph YAML
**Goal:** Create machine-readable dependency graph showing what depends on what

**Acceptance Criteria:**
- GIVEN components WHEN queried THEN can find all downstream dependents
- AND can find all upstream dependencies
- AND graph is acyclic (validates)
- AND includes infrastructure dependencies (postgresql, redis, qdrant)

**Files to Create:**
- `/mnt/e/genesis-system/sitemap/dependency_graph.yaml`

**Technical Hints:**
Structure: each component ID maps to list of dependencies. Include: genesis_kernel depends on [memory_cortex, heartbeat, blackboard], aiva_daemon depends on [genesis_kernel, triple_gate_validator], rlm_bridge depends on [postgresql], graph_rag depends on [qdrant]. Add reverse_index section for "what depends on me" queries.

**Dependencies:** US-001

---

### US-003: Grep Patterns Index
**Goal:** Create index of grep patterns for common agent queries

**Acceptance Criteria:**
- GIVEN question "where is X handled" WHEN index consulted THEN grep pattern provided
- AND covers: error handling, API calls, database queries, config loading
- AND patterns are ripgrep compatible
- AND includes file type filters

**Files to Create:**
- `/mnt/e/genesis-system/sitemap/grep_patterns.yaml`

**Technical Hints:**
Structure: category -> patterns list. Categories: error_handling (patterns: "except.*Error", "raise.*Exception"), api_calls ("requests\\.", "httpx\\.", "aiohttp\\."), database ("SELECT|INSERT|UPDATE|DELETE", "cursor\\.execute"), config ("os\\.environ", "load_dotenv", "\\.env"), entry_points ("if __name__.*main", "def main\\("), class_definitions ("^class \\w+"), function_definitions ("^def \\w+").

**Dependencies:** None

---

### US-004: Health Check Runner
**Goal:** Python script to verify all components and update manifest status

**Acceptance Criteria:**
- GIVEN command python health_runner.py WHEN executed THEN all components checked
- AND updates agent_manifest.yaml with current status
- AND updates last_verified timestamps
- AND outputs summary table to stdout
- AND exits with code 0 if all healthy, 1 if any degraded

**Files to Create:**
- `/mnt/e/genesis-system/sitemap/health_runner.py`

**Technical Hints:**
Load agent_manifest.yaml. For each component: try importing module (importlib), run test_cmd if exists, check infrastructure connectivity. Update status field. Use tabulate for output table. Save updated YAML with ruamel.yaml to preserve comments.

**Dependencies:** US-001

---

### US-005: Quick Query CLI
**Goal:** CLI tool for instant agent queries against manifest

**Acceptance Criteria:**
- GIVEN command query.py --what-uses postgresql THEN lists all dependents
- AND query.py --status shows health summary table
- AND query.py --grep "error handling" returns grep command
- AND query.py --entry genesis_kernel returns entry command
- AND query.py --find "memory" fuzzy searches component names

**Files to Create:**
- `/mnt/e/genesis-system/sitemap/query.py`

**Technical Hints:**
Use argparse with subcommands. Load agent_manifest.yaml and dependency_graph.yaml. Use fuzzywuzzy for fuzzy search. Output in machine-parseable format (one item per line). Include --json flag for JSON output.

**Dependencies:** US-001, US-002, US-003

---

### US-006: Auto-Scanner
**Goal:** Script to scan codebase and regenerate manifest from actual files

**Acceptance Criteria:**
- GIVEN command scanner.py WHEN run THEN manifest regenerated
- AND detects new Python files in core/, AIVA/, skills/
- AND extracts docstrings for descriptions
- AND detects entry points (if __name__ blocks)
- AND preserves manually-set status values

**Files to Create:**
- `/mnt/e/genesis-system/sitemap/scanner.py`

**Technical Hints:**
Use ast module to parse Python files. Extract module docstring, class names, function names. Detect entry_point by searching for "if __name__". Merge with existing manifest (preserve status, last_verified). Output diff of changes.

**Dependencies:** US-001

---

### US-007: Agent Onboarding Prompt
**Goal:** Create a single-file prompt an AI agent can read for instant orientation

**Acceptance Criteria:**
- GIVEN new agent session WHEN prompt read THEN agent knows system state
- AND includes: current health status, top 5 entry points, recent changes
- AND includes: what's working, what's broken, what to avoid
- AND regenerates from manifest data
- AND fits in 2000 tokens

**Files to Create:**
- `/mnt/e/genesis-system/sitemap/AGENT_BRIEFING.md`

**Technical Hints:**
Template-based generation. Sections: System Health (table), Entry Points (list with commands), Recent Activity (from git log), Known Issues (from manifest warnings), Quick Commands (common operations). Keep terse - no prose, just data.

**Dependencies:** US-001, US-004

---

### US-008: Briefing Generator
**Goal:** Script to regenerate AGENT_BRIEFING.md from current state

**Acceptance Criteria:**
- GIVEN command briefing_gen.py WHEN run THEN AGENT_BRIEFING.md updated
- AND pulls health from agent_manifest.yaml
- AND pulls recent commits from git log
- AND includes timestamp of generation
- AND outputs to stdout and file

**Files to Create:**
- `/mnt/e/genesis-system/sitemap/briefing_gen.py`

**Technical Hints:**
Load manifest YAML. Run git log --oneline -10. Build markdown template. Count healthy vs degraded. List entry points with commands. Add "Generated: {timestamp}" footer.

**Dependencies:** US-001, US-007

---
