stemedb/applications/aphoria/dogfood/PROJECT2-QUICKSTART-DEPRECATED.md

# DEPRECATED

This generic guide has been replaced by the specific **httpclient** project.

**Use instead:** `httpclient/README.md` and `httpclient/plan.md`

---

# Project 2 Quick Start: Demonstrating the Flywheel

**You're starting Project 2.** This is where Aphoria's autonomous flywheel compounds knowledge from Project 1.

**What's different:** Project 1 established baseline patterns. Project 2 reuses them and demonstrates 50-60% time savings.

---

## Pre-Flight: Verify Project 1 Knowledge Exists

Before starting, confirm you can access Project 1's corpus:

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

# Expected: 27 claims from dbpool

# Breakdown by source
curl -s 'http://localhost:18180/v1/aphoria/corpus' | \
  jq '[.items[] | select(.subject | contains("dbpool"))] | group_by(.source) | map({source: .[0].source, count: length})'

# Expected:
# [
#   {"source": "community://", "count": 1},
#   {"source": "owasp://", "count": 5},
#   {"source": "vendor://", "count": 21}
# ]
```

**If you see 27 claims:** ✅ Ready to proceed

**If you see 0 claims:** ❌ Project 1 incomplete, start there first

---

## What You'll Demonstrate

### Flywheel Metrics (Evidence to Collect)

| Metric | Project 1 (Baseline) | Project 2 (Target) | How to Measure |
|--------|---------------------|-------------------|----------------|
| **Day 1 Time** | 4 hours | <2 hours (50% faster) | Time Day 1 start to finish |
| **Claims Created** | 27 new | ~22 total (8-10 reused, 12-14 new) | Count in corpus after Day 1 |
| **Claims Reused** | 0 | 8-10 (30-40%) | Query corpus for aligned patterns |
| **Naming Errors** | 2-3 (had to fix) | 0 (skills enforce) | Manual review of claim subjects |
| **Pattern Alignment** | N/A | High (connection, timeout, tls) | Semantic comparison |

**Success = Demonstrable time savings + pattern reuse + perfect naming consistency**

---

## Day 0: Pre-Execution (30 min)

### Step 1: Choose Your Project 2 Domain

**Suggested domains** (reuse connection/security patterns from dbpool):
- HTTP client library (connection pooling, timeouts, TLS)
- gRPC service client (similar patterns to dbpool)
- WebSocket connection manager (connection lifecycle)
- Cache client (connection pooling, TTL)

**Why these:** All share connection management patterns with dbpool, demonstrating cross-domain knowledge reuse.

### Step 2: Verify Skills Installed

```bash
# Check all 8 Aphoria skills exist
ls -la ~/.claude/skills/ | grep aphoria

# Expected output:
# aphoria/
# aphoria-claims/                  ⭐ Primary for Day 1
# aphoria-suggest/                 ⭐ Primary for pattern discovery
# aphoria-custom-extractor-creator/
# aphoria-corpus-import/
# aphoria-install/
# aphoria-post-commit-hook/
# aphoria-ci-setup/
```

**If missing:** Follow `dbpool/docs/multi-project-setup.md` installation section

### Step 3: Run Validator

```bash
cd /home/jml/Workspace/stemedb/applications/aphoria/dogfood/dbpool
./scripts/validate-setup.sh
```

**All checks must pass** (API running, corpus accessible, skills available)

---

## Day 1: Claims with Pattern Discovery (1-2 hours target)

**PRIMARY WORKFLOW: Skills-Driven**

### Step 1: Discover Reusable Patterns (15 min)

**Use aphoria-suggest skill:**

```
In Claude Code:
/aphoria-suggest

"I'm building an HTTP client library. What patterns from dbpool should I reuse?
Show me claims about connection management, timeouts, and security."
```

**Expected skill output:**
```
Found 8-10 reusable patterns from dbpool:

Connection Management:
- connection_timeout: max 30s (vendor://dbpool/connection_timeout)
- max_connections: required (vendor://dbpool/max_connections)
- min_connections: min 2 (vendor://dbpool/min_connections)

Security:
- credentials/plaintext: prohibited (owasp://dbpool/credentials/plaintext)
- tls/enabled: required (owasp://dbpool/tls/enabled)
- certificate_validation: required (owasp://dbpool/certificate_validation)

Lifecycle:
- max_lifetime: required (vendor://dbpool/max_lifetime)
- idle_timeout: recommended (vendor://dbpool/idle_timeout)
```

**Document these** - you'll reference them when creating Project 2 claims.

---

### Step 2: Fetch Project 2 Authority Sources (30 min)

**For HTTP client example:**
- **Fetch:** Requests library documentation (Python/Rust/Node)
- **Fetch:** HTTP client best practices (Mozilla, OWASP)
- **Fetch:** RFC 7230-7235 (HTTP protocol standards)

**Save to:** `project2/docs/sources/`

---

### Step 3: Create Claims Using Skills (30-45 min)

**Use aphoria-claims skill with pattern alignment:**

```
In Claude Code:
/aphoria-claims

"Read project2/docs/sources/requests-docs.md and extract claims for HTTP client.

ALIGN NAMING with dbpool patterns:
- Use 'connection_timeout' (not 'request_timeout') to match dbpool
- Use 'max_connections' (not 'connection_limit') to match dbpool
- Use 'tls/enabled' pattern for security settings

Project prefix: httpclient/"
```

**Skill will:**
1. Extract claims from authority docs
2. Query corpus for similar dbpool patterns
3. Suggest aligned naming (enforces consistency)
4. Generate CLI commands with proper format

**Expected output:**
```bash
# Reused patterns (aligned with dbpool):
aphoria corpus create \
  --subject "httpclient/connection_timeout" \
  --predicate "max_value" \
  --value "30" \
  --explanation "HTTP requests MUST timeout within 30s to prevent resource exhaustion. Aligns with dbpool pattern." \
  --authority "Requests Docs" \
  --category "safety" \
  --tier 2

# New patterns (HTTP-specific):
aphoria corpus create \
  --subject "httpclient/redirect_limit" \
  --predicate "max_value" \
  --value "10" \
  --explanation "..." \
  --authority "RFC 7231" \
  --category "safety" \
  --tier 0
```

**Execute commands** - verify naming aligns with dbpool patterns

---

### Step 4: Verify Pattern Reuse (5 min)

```bash
# Count total claims for Project 2
curl 'http://localhost:18180/v1/aphoria/corpus' | \
  jq '[.items[] | select(.subject | contains("httpclient"))] | length'
# Expected: ~22 claims

# Count aligned patterns (same predicate/category as dbpool)
curl 'http://localhost:18180/v1/aphoria/corpus' | \
  jq '[.items[] | select(.subject | contains("connection_timeout"))] | length'
# Expected: 2 (dbpool + httpclient)

# Verify naming consistency
curl 'http://localhost:18180/v1/aphoria/corpus' | \
  jq '.items[] | select(.subject | contains("httpclient")) | .subject'
# All should be lowercase, slash-separated (no errors)
```

**Success criteria:**
- ✅ 8-10 claims align with dbpool patterns
- ✅ 12-14 new claims (HTTP-specific)
- ✅ 0 naming errors (skills enforced)
- ✅ Completed in <2 hours (vs dbpool's 4 hours)

---

## Day 2-5: Follow dbpool CHECKLIST

**Use:** `dbpool/CHECKLIST.md` Days 2-5

**Key difference:** On Day 3, if built-in extractors don't cover your patterns:

```
/aphoria-custom-extractor-creator

"Generate extractors for these HTTP client violations:
- redirect_limit exceeds 10
- connection_timeout exceeds 30s
- tls disabled"
```

**Skill generates declarative extractors** aligned with your claims.

---

## Measuring Success

### Evidence to Document

**Time savings:**
```markdown
Project 1 (dbpool) Day 1: 4 hours
Project 2 (httpclient) Day 1: 1.5 hours
Improvement: 62.5% time reduction
```

**Pattern reuse:**
```markdown
Project 2 claims: 22 total
  - Reused from dbpool: 9 claims (41%)
  - New HTTP-specific: 13 claims (59%)
```

**Naming consistency:**
```markdown
Project 1 (manual): 2 naming errors, had to fix
Project 2 (skills): 0 naming errors (enforced automatically)
```

**Cross-project awareness:**
```markdown
Before Day 1: Queried corpus, found 27 dbpool patterns
Day 1: Aligned 9 claims with dbpool naming
Result: Consistent vocabulary across projects
```

---

## Troubleshooting

### Problem: Can't see dbpool claims

**Solution:** See `dbpool/docs/multi-project-setup.md` → "Troubleshooting Cross-Project Discovery"

### Problem: Skills not suggesting patterns

**Solution:**
1. Verify API running: `curl http://localhost:18180/health`
2. Verify corpus accessible: Query dbpool claims
3. Give skills clear context: "I'm building X, show patterns from Y"

### Problem: Naming doesn't align with dbpool

**Solution:** Use `/aphoria-claims` skill - it queries corpus and suggests aligned names automatically

---

## Quick Reference

| Phase | Primary Tool | Time |
|-------|-------------|------|
| Pattern Discovery | `/aphoria-suggest` | 15 min |
| Claim Creation | `/aphoria-claims` | 30-45 min |
| Verification | curl + jq | 5 min |
| **Total Day 1** | **Skills-driven** | **1-2 hours** |

Compare to Project 1 (manual): 4 hours

**Time savings: 50-60%**

---

## Next Steps

1. **Complete Day 1** - Create claims with pattern reuse
2. **Measure metrics** - Time, reuse rate, naming consistency
3. **Continue Days 2-5** - Follow dbpool/CHECKLIST.md
4. **Document flywheel** - Write success story with evidence
5. **Optional:** Set up automation (`/aphoria-post-commit-hook` or `/aphoria-ci-setup`)

---

**Ready to start?**

→ Verify Project 1 corpus exists (27 claims)
→ Run validator (`./scripts/validate-setup.sh`)
→ Choose Project 2 domain (httpclient, grpc-client, cache-client)
→ Start Day 1 with `/aphoria-suggest`

**The flywheel is ready. Let's prove it works.**