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. |
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:
- Diagnose the root cause — understand WHY something is broken
- Fix the root cause — implement the correct, permanent solution
- 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.
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.
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.
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:
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:
# 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>Forge is a Rust-powered, opinionated full-stack JavaScript framework. Forged, not assembled.
| 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 |
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 buildingAll ADRs live in spec/adrs/. Key decisions:
| ADR | Decision |
|---|---|
| ADR-001 | Rust compiler pipeline via Oxc |
| ADR-002 | Single-pass compilation — transform, type-strip, bundle, emit in one pass |
| ADR-003 | deno_core as the V8 execution host |
| ADR-006 | TC39 Signals for reactivity — no VDOM, no reconciler |
| ADR-007 | Server/client boundary enforced at compile time |
| ADR-008 | WinterTC Minimum Common API — no Node.js-specific APIs |
| ADR-009 | The Foundry as purpose-built package registry — no npm |
| ADR-010 | Opinionated FSL, no plugin system |
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.