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)](./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)](./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

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

# Expected: 27
```

### Check Skills Installation

```bash
# 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

```bash
# 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`