stemedb/applications/aphoria/dogfood/dbpool/docs/multi-project-setup.md

Multi-Project Flywheel Setup

Purpose: Demonstrate how Project 2+ benefits from institutional knowledge accumulated in Project 1.

Key Concept: The Aphoria flywheel compounds knowledge across projects. Each new project starts faster because it reuses patterns from previous projects.

---

Pre-Flight: Verify Cross-Project Access

Before starting any project after the first, verify you can see claims from previous projects:

# Query all corpus claims
curl 'http://localhost:18180/v1/aphoria/corpus' | jq '.items | length'
# Should show: Total claims from ALL projects in corpus

# For Project 2+: Check for patterns from Project 1 (dbpool)
curl 'http://localhost:18180/v1/aphoria/corpus' | \
  jq '[.items[] | select(.subject | contains("dbpool"))] | length'
# Should show: 27 claims (if dbpool completed Day 1)

# 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})'
# Should show: vendor (21), owasp (5), community (1)

Success criteria: You can query and see claims from previous projects.

---

Project 2+ Discovery Workflow

Step 1: Query Relevant Patterns Before Starting

Before creating any claims for Project 2, discover what patterns Project 1 established:

# Example: If Project 2 is an HTTP client, query connection-related patterns
curl 'http://localhost:18180/v1/aphoria/corpus' | \
  jq '.items[] | select(
    .subject | contains("connection") or
    .subject | contains("timeout") or
    .subject | contains("pool")
  ) | {subject, predicate, value, source}'

Expected output:

{
  "subject": "vendor://dbpool/connection_timeout",
  "predicate": "maximum",
  "value": 30,
  "source": "vendor://"
}
{
  "subject": "vendor://dbpool/max_connections",
  "predicate": "required",
  "value": true,
  "source": "vendor://"
}
...

What this tells you:

• dbpool established connection_timeout with maximum 30 seconds
• dbpool established max_connections as required
• Your HTTP client should follow similar patterns for consistency

---

Step 2: Use Skills for Pattern Reuse

Available Skills (installed in ~/.claude/skills/):

Skill	When to Use	Purpose for Project 2+
/aphoria-suggest	Before Day 1 claim creation	Discover reusable patterns from Project 1
/aphoria-claims	Day 1 claim authoring	Enforce naming consistency with Project 1
/aphoria-corpus-import	Importing shared standards	Reuse vendor corpus across projects
/aphoria-custom-extractor-creator	Day 3-4 if gaps exist	Generate extractors aligned with Project 1 patterns

Use aphoria-suggest skill to discover reusable patterns:

In Claude Code:
/aphoria-suggest

"I'm building an HTTP client library. What patterns from other projects should I reuse for connection management?"

Expected skill behavior:

1. Queries corpus for connection/timeout/pool patterns
2. Finds dbpool's claims about connection_timeout, max_connections, etc.
3. Suggests: "dbpool project has claims about connection_timeout (max 30s), max_connections (required)..."
4. Proposes: "You should create similar claims for your HTTP client:
   • http_client/connection_timeout (align with dbpool's 30s max)
   • http_client/max_connections (required, like dbpool)"

---

Step 3: Create Claims with Cross-Project Alignment

Use aphoria-claims skill for aligned claim creation:

In Claude Code:
/aphoria-claims

"Extract claims from this HTTP client code. Align naming with dbpool patterns where similar (connection_timeout, max_connections). Follow lowercase slash-separated naming."

Expected skill output:

# Skill generates claims aligned with dbpool naming
aphoria corpus create \
  --subject "http_client/connection_timeout" \
  --predicate "maximum" \
  --value "30" \
  --explanation "Connection timeout MUST NOT exceed 30 seconds to prevent resource exhaustion. Aligns with dbpool/connection_timeout pattern." \
  --authority "Industry Best Practice" \
  --category "safety" \
  --tier 2

aphoria corpus create \
  --subject "http_client/max_connections" \
  --predicate "required" \
  --value "true" \
  --explanation "Max connections MUST be configured to prevent unbounded growth. Aligns with dbpool/max_connections pattern." \
  --authority "Industry Best Practice" \
  --category "safety" \
  --tier 2

Note the alignment:

• Both use connection_timeout (not connectionTimeout or timeout)
• Both use max_connections (not maxConnections or connection_limit)
• Naming consistency enables cross-project pattern recognition

---

Flywheel Demonstration

Success Metrics

Compare Project 1 vs Project 2 to demonstrate flywheel value:

Metric	Project 1 (dbpool)	Project 2 (Expected)	Improvement
Time spent creating claims	3-4 hours (baseline)	1-2 hours	50-60% faster
Claims created	27 (from scratch)	20-25	~25% fewer (reuse)
Naming consistency	Manual (error-prone)	Automatic (skill-enforced)	No mismatch errors
Cross-project awareness	None	High (queries dbpool)	Pattern reuse
Workflow	Manual CLI	Skills-driven	Autonomous

Flywheel working indicator: Project 2 completes faster and with fewer errors because institutional knowledge accumulated.

---

What "Flywheel Working" Looks Like

Without flywheel (both projects manual):

Project 1: 4 hours, 27 claims, no patterns to reference
Project 2: 4 hours, 25 claims, reinvents similar patterns
Total time: 8 hours

With flywheel (Project 2 uses skills + Project 1 patterns):

Project 1: 4 hours, 27 claims (baseline)
Project 2: 1.5 hours, 22 claims (skills discover Project 1 patterns, suggest reuse)
Total time: 5.5 hours (31% faster)

Additional benefits:

• Project 2's claims align with Project 1 (consistent naming)
• Future Project 3 benefits from both Project 1 + Project 2
• Knowledge compounds exponentially

---

Common Patterns to Reuse Across Projects

Based on dbpool (Project 1), these patterns should be reusable:

Connection Management

Pattern	dbpool	HTTP Client	gRPC Client	Database ORM
connection_timeout	✓ 30s max	✓ Reuse	✓ Reuse	✓ Reuse
max_connections	✓ Required	✓ Reuse	✓ Reuse	✓ Reuse
idle_timeout	✓ Required	✓ Reuse	✓ Reuse	✓ Reuse

Security

Pattern	dbpool	HTTP Client	gRPC Client	Database ORM
credentials/plaintext	✓ Prohibited	✓ Reuse	✓ Reuse	✓ Reuse
tls/enabled	✓ Recommended	✓ Reuse	✓ Reuse	✓ Reuse
certificate_validation	✓ Required	✓ Reuse	✓ Reuse	✓ Reuse

Pattern reuse advantage: Don't reinvent "connection timeout should be ≤30s" for every project.

---

Troubleshooting Cross-Project Discovery

Problem: "I can't see Project 1's claims"

Diagnosis:

# Check if claims exist
curl 'http://localhost:18180/v1/aphoria/corpus' | jq '.items | length'
# If 0: Corpus is empty, Project 1 didn't persist claims

# Check if API is using correct corpus DB
ps aux | grep stemedb-api | grep STEMEDB_CORPUS_DB_DIR
# Should show: STEMEDB_CORPUS_DB_DIR=/path/to/corpus-db

Solution:

• Verify API environment: STEMEDB_CORPUS_DB_DIR must point to shared corpus DB
• Both projects must use same corpus DB location
• Restart API with correct env var if needed

---

Problem: "Skills aren't suggesting Project 1 patterns"

Diagnosis:

# Manually check for similar patterns
curl 'http://localhost:18180/v1/aphoria/corpus' | \
  jq '.items[] | select(.subject | contains("connection"))'
# Do connection-related claims exist?

Solution:

• Skills query corpus via API - verify API is accessible
• Try explicit query: "/aphoria-suggest Show me claims about 'connection' from corpus"
• Skills need clear context: "I'm building X, what patterns from Y should I reuse?"

---

Production Automation (Beyond Dogfooding)

For real-world autonomous operation, use automation skills:

Option 1: Post-Commit Hooks (Local Development)

/aphoria-post-commit-hook

"Set up automatic scanning on every commit for this project"

Configures:

• .git/hooks/post-commit → runs aphoria scan --persist --sync
• Autonomous loop: commit → scan → detect violations → suggest fixes
• Knowledge compounds automatically

Use when: Local development, single developer or small team

Option 2: CI/CD Integration (Team/Enterprise)

/aphoria-ci-setup

"Configure GitHub Actions to run Aphoria on every PR"

Configures:

• .github/workflows/aphoria.yml → scan on pull requests
• Fails PR if BLOCK violations detected
• Comments with violation details on PR

Use when: Multi-developer teams, production repositories

Available automation skills:

• /aphoria-post-commit-hook - Local git hooks (developer workflow)
• /aphoria-ci-setup - GitHub Actions, GitLab CI (team workflow)

---

Next Steps After Setup

1. Complete Project 1 (dbpool) - Establish baseline (27 claims)
2. Verify cross-project access - Can see Project 1's 27 claims via API
3. Start Project 2 - Use skills, demonstrate pattern reuse
4. Measure improvement - Time, consistency, alignment
5. Document flywheel value - "Project 2 was X% faster due to pattern reuse"
6. Optional: Set up automation - Post-commit hooks or CI/CD for continuous operation

---

For Demonstration/Documentation

Evidence to collect:

1. Time savings:

   • Project 1: 4 hours (baseline)
   • Project 2: 1.5 hours (with skills + pattern reuse)
   • Improvement: 62.5% time reduction

2. Pattern reuse:

   • Claims from Project 1: 27
   • Claims reused in Project 2: ~8-10
   • New claims in Project 2: ~15-17
   • Reuse rate: ~40%

3. Naming consistency:

   • Project 1 (manual): 2-3 naming errors (had to fix)
   • Project 2 (skills): 0 naming errors (enforced automatically)

4. Cross-project awareness:

   • Project 1: Invented patterns from scratch
   • Project 2: Discovered 8-10 patterns from Project 1, aligned naming

This is the flywheel working.

---

Summary

Flywheel Prerequisites:

1. ✅ Shared corpus database accessible via API
2. ✅ Project 1 claims persisted (27 dbpool claims visible)
3. ✅ Skills installed (aphoria-claims, aphoria-suggest)
4. ✅ Cross-project discovery commands documented

Flywheel Success:

• Project 2 starts faster (discovers existing patterns)
• Project 2 completes faster (skills + pattern reuse)
• Naming aligned across projects (skills enforce consistency)
• Knowledge compounds (each project makes next one easier)

The autonomous flywheel is working when Project 2 asks "what patterns exist?" and skills answer with Project 1's knowledge.