stemedb/applications/aphoria/docs/guides/README.md

Aphoria Guides

Aphoria is an autonomous learning system powered by LLM workflows. Choose your integration path:

---

🤖 I Want Autonomous Operation (Recommended)

LLM-Driven Workflows: Skills, agents, or custom integrations

Claude Code Skills:

• Load /aphoria-claims - Commit-time claim authoring
• Load /aphoria-suggest - Pattern-based claim suggestions
• Load /aphoria-custom-extractor-creator - Generate custom extractors

Go ADK Agents:

• See ADK-Go Integration - Fully autonomous tool-use agents

Custom Integration:

• Any LLM with tool-use capability can drive Aphoria via CLI

Why LLM workflows?

• Enforce naming conventions (manual errors break tail-path matching)
• Reason about consequences (not just pattern matching)
• Suggest claims from patterns automatically
• Create extractors for custom patterns
• Enable the autonomous flywheel (scan→fix→evaluate→claim→create)

The CLI is a debug/fallback interface. For production use, integrate LLM workflows.

---

📚 I Want to Learn It (20 minutes)

Worked Example: Follow a complete use case from documentation → claims → violations → fixes

Database Connection Pool Example - See how a solo developer:

1. Extracts 25-30 claims from HikariCP/PostgreSQL docs
2. Writes code (with intentional violations)
3. Runs Aphoria scan (catches all 7-8 violations)
4. Fixes violations incrementally
5. Reaches production-ready code

What you get:

• Complete claim extraction walkthrough with decision framework
• Pre-flight validator to check your environment
• Expected output examples for every command
• Real scan results showing BLOCK/FLAG/PASS verdicts

Time: 20 minutes to read, 5 days to execute (optional)

---

🚀 Fallback: No LLM Access (Debug Interface)

CLI-Only Mode: For environments without LLM access or debugging

⚠️ Limitations:

• Manual claim authoring (naming errors break tail-path matching)
• No autonomous flywheel (scan only, no evaluate/claim/create)
• Requires manual pattern analysis

🔧 I Want to Integrate It (30 minutes)

Production Integration: Pre-commit hooks, CI/CD, team workflows

See:

• Pre-Flight Checks Guide - Git hooks and CI integration
• Enterprise Quick Start - Team deployment
• Multi-Team Policy Governance - Scaling to multiple teams

---

Getting Started Guides

Guide	Audience	Description
Solo Developer Guide	Individual developers	Get immediate value on personal or side projects
Enterprise Pilot Guide	Security teams	Run a measurable pilot with stakeholder buy-in
Enterprise Quick Start	Platform engineering	5-minute path from git clone to enforcing standards
The First Scan	Everyone	Your first Aphoria scan walkthrough
Pre-Flight Checks	DevOps	Pre-commit and CI integration

Core Workflows

Guide	Description
Bulk Claim Import	Import claims in bulk from TOML files with validation
Federating Truth	Trust Pack creation and distribution
Multi-Team Policy Governance	Managing policies across teams
Policy Audit Trails	Compliance and auditing
Authoritative State Per Project	Project-specific policy management

Advanced Topics

Guide	Description
Golden Path Loop	Continuous policy improvement
AAA Game Development	Unreal Engine patterns
LLM Wiki Extraction	Extract claims from technical docs using LLM skill

Reference Materials

Document	Purpose
CLI Reference	Complete command documentation
Comparison Modes	How Aphoria evaluates conflicts
Configuration	.aphoria/config.toml reference
Architecture	System design and algorithms

UAT Results

See UAT Reports for validation results:

• Policy Source Tracking UAT - Trust Pack workflow validation

---

Support

• Installation issues: See Solo Developer Guide
• Scan not finding violations: Check Troubleshooting
• Custom extractors: See Architecture: Extractors
• Enterprise deployment: See Enterprise Pilot Guide