## COLLABORATION WITH JESHUA — THE ARCHITECT

**Jeshua is the architect of Forge and the entire 100monkeys platform.** He is a seasoned DevOps SRE and Cloud Architect with decades of experience in automation, development, and infrastructure. He is a polyglot developer and the designer of every system, ADR, and specification in this codebase.

**This is a collaboration, not instruction.** Claude assists Jeshua — not the other way around. The following rules are absolute:

| Rule | Detail |
| --- | --- |
| **Never instruct Jeshua** | He already knows the architecture, the compiler pipeline, and the deployment flow. Do not tell him what to do, what to run, or what "needs to happen." |
| **Troubleshoot, don't lecture** | When Jeshua presents an error or problem, he wants collaborative debugging — not a recap of how things work. Investigate the code, find the bug, propose a fix. |
| **Assume full context** | Jeshua is always up to speed. If he says something is broken, he has already taken the obvious steps. Look deeper. |
| **Be direct and concise** | No preamble, no filler, no hedging. State findings, propose fixes, move on. |
| **Ask for diagnostics, don't assume** | When troubleshooting remotely, ask Jeshua to run specific diagnostic commands and share output. Don't guess at environmental state. |

---

## NO QUICK FIXES — EVER

**This is a CRITICAL, NON-NEGOTIABLE directive.**

**DO NOT propose, implement, or suggest quick fixes, workarounds, hacks, or band-aids. EVER.**

When troubleshooting or resolving issues:

1. **Diagnose the root cause** — understand WHY something is broken
2. **Fix the root cause** — implement the correct, permanent solution
3. **Verify the fix** — confirm the underlying issue is resolved

Quick fixes create technical debt, mask real problems, and erode system integrity. In a compiled framework like Forge, a "temporary" workaround in the compiler pipeline or runtime becomes a permanent correctness landmine.

| Anti-Pattern | Correct Approach |
| --- | --- |
| "Just hardcode the transform for now" | Fix the Oxc pipeline stage |
| "Skip the boundary check temporarily" | Ensure the analysis pass is correct |
| "Comment out the failing test" | Fix the code that the test is catching |
| "Add a sleep/retry to paper over timing" | Fix the dependency ordering or readiness check |
| "Use an env var override as a band-aid" | Fix the configuration at its source |

**If you find yourself typing "for now", "temporarily", "as a workaround", or "quick fix" — STOP. You are about to do the wrong thing.**

---

## MANDATORY SUBAGENT DIRECTIVE — READ THIS FIRST

**If you are an AI agent reading this document, the following is NON-NEGOTIABLE:**

**YOU MUST USE SUBAGENTS FOR ALL NON-TRIVIAL WORK. NO EXCEPTIONS.**

The orchestration context is a finite, precious resource. Every token you spend on inline implementation — file reads, code edits, searches, multi-step reasoning — degrades your ability to plan, coordinate, and deliver correct output.

| Task Type | Required Action |
| --- | --- |
| Codebase exploration / research | **Spawn a subagent** |
| Writing or editing any code | **Spawn a subagent** |
| File searches or content reads | **Spawn a subagent** |
| Multi-file edits or refactors | **Spawn a subagent** |
| Testing, validation, or verification | **Spawn a subagent** |
| Generating boilerplate or scaffolding | **Spawn a subagent** |
| Any outbound lookup or fetch | **Spawn a subagent** |
| Editing markdown files (.md) | **Spawn a subagent + MUST run `markdownlint-cli2 --fix`** |

**Your role as the orchestrator is: decompose → delegate → verify → integrate.** Nothing more.

### Post-Edit Verification Checklist

**For Rust Code** — after any edit, the subagent MUST:

```
After editing, you MUST:
1. Run: cargo fmt --all
2. Run: cargo clippy --workspace --locked -- -D warnings
3. Run: cargo build --workspace
4. Run: cargo test --workspace --locked
5. Only report success when ALL commands pass
```

**For Markdown Files (`.md`)** — after any edit, the subagent MUST:

```
After editing, you MUST:
1. Run: markdownlint-cli2 --fix /absolute/path/to/file.md
2. If errors remain, fix them manually
3. Re-run the linter until it exits with zero errors
4. Only report success when the linter passes
```

**These checks are not suggestions — they are blocking requirements. A subagent that returns without passing these checks has not completed its work.**

---

## GIT WORKTREE POLICY — NEVER MODIFY THE MAIN WORKTREE

**This policy applies to code crates** (`compiler/`, `runtime/`, `cli/`, `foundry/`). **Documentation and specifications** (`spec/`, `docs/`) may be edited directly on main.

**For multi-file features and large changes**, the main worktree is READ-ONLY — use an isolated git worktree. **For trivial fixes** (single-file config changes, one-liner fixes), editing directly on main and pushing is acceptable.

**Worktree location:** `/home/theaxiom/100monkeys/worktrees/`

All worktrees MUST be created under this directory:

```bash
cd /home/theaxiom/100monkeys/forgejs
git worktree add /home/theaxiom/100monkeys/worktrees/<branch-name> -b <branch-name>
```

| Anti-Pattern | Correct Approach |
| --- | --- |
| `git checkout -b feature/foo` in main worktree | `git worktree add /home/theaxiom/100monkeys/worktrees/feature-foo -b feature/foo` |
| Editing files directly in the main repo root | Subagent with isolated worktree |
| Running `cargo install` in the main worktree | Run it in the worktree copy |

**Merge workflow:**

```bash
# 1. Commit in the worktree
cd /home/theaxiom/100monkeys/worktrees/<branch-name>
git add <files> && git commit -m "..."

# 2. Merge into main from the main worktree
cd /home/theaxiom/100monkeys/forgejs
git merge <branch-name>

# 3. Resolve conflicts if any, then push
git push origin main

# 4. Clean up
git worktree remove /home/theaxiom/100monkeys/worktrees/<branch-name>
git branch -d <branch-name>
```

---

## Project Overview

**Forge** is a Rust-powered, opinionated full-stack JavaScript framework. Forged, not assembled.

### Repository Structure

| Path | Crate | Purpose |
| --- | --- | --- |
| `compiler/` | `forge-compiler` | Oxc-based parse/analyze/transform/codegen pipeline |
| `runtime/` | `forge-runtime` | deno_core/V8 isolate, HTTP server, SSR, dev server |
| `cli/` | `forge-cli` | The `forge` binary (clap-based): new, dev, build, serve, publish |
| `foundry/server/` | `foundry-server` | Package registry API (axum + sqlx) |
| `foundry/client/` | `foundry-client` | Dependency resolver, lockfile, and cache |
| `shared/` | `forge-shared` | Shared types: manifests, diagnostics, source locations |
| `fsl/` | — | Forge Standard Library: 8 packages (router, data, auth, test, email, jobs, storage, realtime) |
| `spec/` | — | Normative specifications and ADRs |
| `docs/` | — | mdBook developer documentation |

---

## Key Build Commands

```bash
cargo build --workspace         # Build all crates
cargo test --workspace --locked # Run all tests
cargo clippy --workspace --locked -- -D warnings  # Lint
cargo fmt --all                 # Format
cargo check --workspace         # Fast typecheck without building
```

---

## Key Architectural Decisions

All ADRs live in `spec/adrs/`. Key decisions:

| ADR | Decision |
| --- | --- |
| [ADR-001](spec/adrs/001-rust-compiler-pipeline.md) | Rust compiler pipeline via Oxc |
| [ADR-002](spec/adrs/002-single-pass-compilation.md) | Single-pass compilation — transform, type-strip, bundle, emit in one pass |
| [ADR-003](spec/adrs/003-deno-core-runtime.md) | deno_core as the V8 execution host |
| [ADR-006](spec/adrs/006-tc39-signals-reactivity.md) | TC39 Signals for reactivity — no VDOM, no reconciler |
| [ADR-007](spec/adrs/007-compile-time-boundary-enforcement.md) | Server/client boundary enforced at compile time |
| [ADR-008](spec/adrs/008-wintertc-server-apis.md) | WinterTC Minimum Common API — no Node.js-specific APIs |
| [ADR-009](spec/adrs/009-foundry-package-registry.md) | The Foundry as purpose-built package registry — no npm |
| [ADR-010](spec/adrs/010-opinionated-fsl.md) | Opinionated FSL, no plugin system |

---

## Pre-Alpha Note

**We are pre-alpha. DO NOT create any backward compatibility shims or preserve any legacy implementations.** If you find any, remove them immediately.

**AGENT ORCHESTRATION RULE: All implementation work — including removing legacy code, updating tests, and editing any file — MUST be delegated to a subagent. The primary agent context is for orchestration and decision-making only. Violating this rule by performing implementation inline is the main context pollution anti-pattern.**