# 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:

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

```bash
# 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:**
```json
{
  "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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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.**