stemedb/applications/aphoria/dogfood/README.md

Aphoria Dogfood Projects

Purpose: Demonstrate Aphoria's autonomous flywheel through real-world projects.

---

Quick Navigation

Starting Fresh?

→ Project 1 (dbpool) - Database connection pool library

• Status: Day 1 complete (27 claims created)
• Purpose: Establish baseline patterns
• Start here if: This is your first dogfood project
• Time: 5 days (Days 2-5 remaining)

→ Project 2 (httpclient) - HTTP client library (autonomous flywheel demo)

• Status: Ready to start (requires Project 1 complete)
• Purpose: Demonstrate 50-60% time savings via pattern reuse from dbpool
• Start here if: Project 1 Day 1 is complete (27 claims in corpus)
• Time: 4 days (Day 1 faster due to skills + pattern reuse)

---

Project Status

✅ Project 1: dbpool (Database Connection Pool)

Current State: Day 1 complete, ready for Day 2

What's done:

• ✅ 27 claims created in corpus
  • 21 vendor (HikariCP + PostgreSQL)
  • 5 owasp (security requirements)
  • 1 community (Rust best practices)

Next steps: Follow dbpool/CHECKLIST.md Day 2+

Documentation:

• dbpool/CHECKLIST.md - Day-by-day execution guide
• dbpool/STATE-2026-02-10.md - Current state and progress
• dbpool/docs/ - Claim extraction examples, flywheel setup, multi-project guide

---

🚀 Project 2: httpclient (HTTP Client Library)

What we're building: Production-ready HTTP client with connection pooling, timeout management, TLS enforcement

Pre-requisites:

• ✅ Project 1 Day 1 complete (27 claims in corpus)
• ✅ Skills installed (~/.claude/skills/aphoria*)
• ✅ API running with corpus access

Why this project:

• Reuses dbpool connection/timeout/TLS patterns
• Demonstrates skills-driven pattern discovery
• Shows measurable flywheel value (60% time reduction, 40% pattern reuse)

Start here: httpclient/README.md

What you'll demonstrate:

• 50-60% time reduction (Day 1: <2 hours vs dbpool's 4 hours)
• 30-40% pattern reuse (8-10 claims aligned with dbpool)
• 0 naming errors (skills enforce consistency)
• Cross-project knowledge compounding

---

Documentation Index

Getting Started

• New to dogfooding? → dbpool/README.md
• Ready for Project 2? → PROJECT2-QUICKSTART.md
• Skills setup? → dbpool/CHECKLIST.md (Pre-Execution section)

Deep Dives

• Claim extraction walkthrough: dbpool/docs/claim-extraction-example.md
• Custom extractors guide: dbpool/docs/CUSTOM-EXTRACTOR-GUIDE.md
• Flywheel setup (persistent mode): dbpool/docs/flywheel-setup.md
• Multi-project pattern reuse: dbpool/docs/multi-project-setup.md

Reference

• Authority sources: dbpool/docs/sources/ (HikariCP, PostgreSQL, OWASP)
• Evaluation reports: dbpool/eval/ (what we learned from Project 1)

---

Quick Verification Commands

Check Project 1 Corpus

# Verify 27 dbpool claims exist
curl 'http://localhost:18180/v1/aphoria/corpus' | \
  jq '[.items[] | select(.subject | contains("dbpool"))] | length'

# Expected: 27

Check Skills Installation

# List installed Aphoria skills
ls -la ~/.claude/skills/ | grep aphoria

# Expected: 8 skills
# aphoria, aphoria-claims, aphoria-suggest, aphoria-custom-extractor-creator,
# aphoria-corpus-import, aphoria-install, aphoria-post-commit-hook, aphoria-ci-setup

Check API Running

# Health check
curl http://localhost:18180/health

# Expected: {"status":"healthy","version":"0.1.0"}

---

What Each Project Demonstrates

Project 1 (Baseline)

Goal: Establish authoritative patterns from vendor docs (HikariCP, PostgreSQL)

Workflow:

1. Extract claims from authority sources (manual or skills)
2. Create library with intentional violations
3. Scan and detect violations
4. Fix incrementally with verification
5. Document success story

Value: Proves Aphoria can detect real violations with high accuracy

Time: 16-20 hours (spread over 5 days)

---

Project 2 (Flywheel)

Goal: Demonstrate autonomous knowledge compounding across projects

Workflow:

1. Skills discover patterns from Project 1 (not starting from scratch)
2. Skills enforce naming alignment (consistency across projects)
3. Create library aligned with Project 1 patterns
4. Skills generate extractors if needed (autonomous coverage)
5. Document flywheel metrics (time savings, reuse rate)

Value: Proves Aphoria compounds knowledge, teams get faster over time

Time: 12-15 hours (spread over 4 days) - 25-30% faster than Project 1

---

Success Criteria

Project 1

• ✅ 25-30 claims created
• ✅ 7-8 intentional violations embedded in code
• ✅ 85-100% detection accuracy
• ✅ Scan performance ≤0.3s
• ✅ Final scan: 0 conflicts (all fixed)

Project 2

• ✅ Day 1 completed in <2 hours (50% faster than Project 1)
• ✅ 8-10 claims reused from Project 1 (30-40% reuse rate)
• ✅ 0 naming errors (skills enforce consistency)
• ✅ Pattern alignment high (connection, timeout, TLS)
• ✅ Flywheel metrics documented (evidence of knowledge compounding)

---

Need Help?

Pre-Flight Issues

• Validator fails? → Run dbpool/scripts/validate-setup.sh for diagnostics
• No claims in corpus? → Check API env var: STEMEDB_CORPUS_DB_DIR
• Skills not found? → Follow installation in dbpool/CHECKLIST.md

During Dogfooding

• Scan returns 0 observations? → dbpool/docs/CUSTOM-EXTRACTOR-GUIDE.md
• Cross-project patterns not showing? → dbpool/docs/multi-project-setup.md
• Naming inconsistencies? → Use /aphoria-claims skill (enforces automatically)

---

Architecture Reminder

What Aphoria IS:

• Autonomous LLM-driven system (runs on every commit in production)
• Skills ARE the primary workflow (/aphoria-claims, /aphoria-suggest)
• Manual CLI is debug interface (fallback when LLM unavailable)

What Aphoria is NOT:

• ❌ NOT a CLI tool you run manually
• ❌ NOT "42 extractors + custom additions"
• ❌ NOT optional LLM features

For dogfooding: Skills demonstrate the autonomous flywheel. Manual CLI is available but not the primary workflow.

---

Ready to start?

• First time: → dbpool/README.md
• Project 2: → PROJECT2-QUICKSTART.md