9bfa626203
Major documentation restructure to improve discoverability and reduce duplication. ## Changes **Deleted (Archived/Consolidated)**: - Removed duplicate getting started guides - Archived outdated planning documents - Consolidated corpus and configuration docs - Removed obsolete vision/spec files (superseded by vision.md) - Cleaned up scrapyard and old PDFs **New Structure**: - docs/about/ - Project overview and introduction - docs/guides/ - User guides (moved from root) - docs/specs/ - Technical specifications - docs/sdk/ - SDK documentation (Go) - docs/references/ - API references - docs/archive/ - Archived historical docs - applications/aphoria/docs/advanced/ - Advanced topics - applications/aphoria/docs/reference/ - CLI reference - applications/aphoria/docs/archive/ - Archived aphoria docs **Updated**: - README.md - New root README with clear navigation - CONTRIBUTING.md - Contribution guidelines - CLAUDE.md - Updated paths to new structure - roadmap.md - Added recent completions ## Files Changed - 57 files changed - 1,977 insertions(+) - 961 deletions(-) **Net change**: +1,016 lines (added CONTRIBUTING.md, README.md, reorganized content) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
124 lines
4.9 KiB
Markdown
124 lines
4.9 KiB
Markdown
# 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](../../../sdk/go/adk/) - 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](../../dogfood/dbpool/) - 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](./pre-flight-checks.md) - Git hooks and CI integration
|
|
- [Enterprise Quick Start](./enterprise-quick-start.md) - Team deployment
|
|
- [Multi-Team Policy Governance](./multi-team-policy-governance.md) - Scaling to multiple teams
|
|
|
|
---
|
|
|
|
## Getting Started Guides
|
|
|
|
| Guide | Audience | Description |
|
|
|-------|----------|-------------|
|
|
| [Solo Developer Guide](./solo-developer-guide.md) | Individual developers | Get immediate value on personal or side projects |
|
|
| [Enterprise Pilot Guide](./enterprise-pilot-guide.md) | Security teams | Run a measurable pilot with stakeholder buy-in |
|
|
| [Enterprise Quick Start](./enterprise-quick-start.md) | Platform engineering | 5-minute path from git clone to enforcing standards |
|
|
| [The First Scan](./the-first-scan.md) | Everyone | Your first Aphoria scan walkthrough |
|
|
| [Pre-Flight Checks](./pre-flight-checks.md) | DevOps | Pre-commit and CI integration |
|
|
|
|
## Core Workflows
|
|
|
|
| Guide | Description |
|
|
|-------|-------------|
|
|
| [Bulk Claim Import](./bulk-claim-import.md) | Import claims in bulk from TOML files with validation |
|
|
| [Federating Truth](./federating-truth.md) | Trust Pack creation and distribution |
|
|
| [Multi-Team Policy Governance](./multi-team-policy-governance.md) | Managing policies across teams |
|
|
| [Policy Audit Trails](./policy-audit-trails.md) | Compliance and auditing |
|
|
| [Authoritative State Per Project](./authoritative-state-per-project.md) | Project-specific policy management |
|
|
|
|
## Advanced Topics
|
|
|
|
| Guide | Description |
|
|
|-------|-------------|
|
|
| [Golden Path Loop](./golden-path-loop.md) | Continuous policy improvement |
|
|
| [AAA Game Development](./aaa-game-development.md) | Unreal Engine patterns |
|
|
| [LLM Wiki Extraction](./llm-wiki-extraction.md) | Extract claims from technical docs using LLM skill |
|
|
|
|
## Reference Materials
|
|
|
|
| Document | Purpose |
|
|
|----------|---------|
|
|
| [CLI Reference](../reference/cli-reference.md) | Complete command documentation |
|
|
| [Comparison Modes](../reference/comparison-modes.md) | How Aphoria evaluates conflicts |
|
|
| [Configuration](../reference/configuration.md) | .aphoria/config.toml reference |
|
|
| [Architecture](../architecture/README.md) | System design and algorithms |
|
|
|
|
## UAT Results
|
|
|
|
See [UAT Reports](../../uat/) for validation results:
|
|
- [Policy Source Tracking UAT](../../uat/2026-02-04-uat-real-world-policy-source.md) - Trust Pack workflow validation
|
|
|
|
---
|
|
|
|
## Support
|
|
|
|
- **Installation issues:** See [Solo Developer Guide](./solo-developer-guide.md#quick-start-2-minutes)
|
|
- **Scan not finding violations:** Check [Troubleshooting](../reference/cli-reference.md#troubleshooting)
|
|
- **Custom extractors:** See [Architecture: Extractors](../architecture/README.md#extractors)
|
|
- **Enterprise deployment:** See [Enterprise Pilot Guide](./enterprise-pilot-guide.md)
|