fawxai · abbudjoe · Apr 3, 2026 · Apr 3, 2026 · Apr 3, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -4,7 +4,7 @@ on:
   push:
     branches: [ main ]
   pull_request:
-    branches: [ main ]
+    branches: [ main, staging ]
 
 env:
   CARGO_TERM_COLOR: always
@@ -40,6 +40,8 @@ jobs:
       - name: Cargo check
         run: cargo check --workspace --all-targets
 
+      - name: Cargo check (oauth-bridge feature)
+        run: cargo check -p fx-cli --features oauth-bridge --all-targets
 
   test:
     name: Test
@@ -62,6 +64,8 @@ jobs:
       - name: Run tests
         run: cargo test --workspace
 
+      - name: Run tests (oauth-bridge feature)
+        run: cargo test -p fx-cli --features oauth-bridge
 
   clippy:
     name: Clippy
@@ -86,6 +90,8 @@ jobs:
       - name: Run clippy
         run: cargo clippy --workspace --all-targets -- -D warnings
 
+      - name: Run clippy (oauth-bridge feature)
+        run: cargo clippy -p fx-cli --features oauth-bridge --all-targets -- -D warnings
 
   fmt:
     name: Format
@@ -100,3 +106,23 @@ jobs:
 
       - name: Check formatting
         run: cargo fmt --all --check
+
+  ci_checks:
+    name: CI Checks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install shellcheck
+        run: |
+          if ! command -v shellcheck >/dev/null 2>&1; then
+            sudo apt-get update
+            sudo apt-get install -y shellcheck
+          fi
+
+      - name: Shellcheck CI scripts
+        run: shellcheck scripts/spec-tests/ci-workflow-cache-paths-check.sh
+
+      - name: Verify workflow cache path safety
+        run: ./scripts/spec-tests/tests/ci-workflow-cache-paths-test.sh
+
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -130,8 +130,8 @@ Fawx skills are WASM modules that extend the engine's capabilities. To create
 a new skill:
 
 1. Use the skill template: `cargo generate fawxai/skill-template`
-2. Implement the `Skill` trait
-3. Test locally with `fawx skill install --path ./target/wasm32-wasi/release/`
+2. Build and install locally with `fawx skill build .`
+3. Test a prebuilt artifact with `fawx skill install ./target/wasm32-wasip1/release/<skill>.wasm`
 4. Publish to the marketplace (coming soon)
 
 See [docs/skills/](docs/skills/) for the full SDK reference.

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/ENGINEERING.md b/ENGINEERING.md
@@ -203,11 +203,42 @@ feature/* → dev → staging → main
 
 - **feature branches**: cut from `dev`, PRs target `dev`
 - **dev**: integration branch — merge freely after CI + TUI smoke test pass. Multiple features tested together here.
-- **staging**: release candidate — maintainer promotes `dev → staging` after integration testing passes
+- **staging**: release candidate — Joe manually promotes `dev → staging` after integration testing passes
 - **main**: production releases only — `staging → main` for releases
 
 All three long-lived branches are protected: no force push, no deletion.
 
 ---
 
-*This file defines the engineering standards for the Fawx codebase. All contributions are held to these rules. For style preferences, see `TASTE.md`.*
+## 7. Agent Execution Model
+
+### Roles
+- **Clawdio main session** is the lead. Orchestrates, designs, reviews results, makes architectural calls. Does NOT write code, regardless of size. All code is delegated to subagents.
+- **Subagents** do all implementation, review, and fix work.
+
+### Model policy
+- **Implementers + Fixers** (code generation): `model: "openai-codex/gpt-5.4"`, `thinking: "xhigh"`.
+- **Reviewers** (code analysis): `model: "anthropic/claude-opus-4-6"`, `thinking: "adaptive"`.
+- GPT-5.4 xhigh for writing code, Opus adaptive for judging code. No Sonnet unless Joe explicitly requests it.
+- Always use full model paths — never aliases (can silently fall back to wrong provider).
+
+### Orchestration model
+- **Main session owns the state machine.** Clawdio directly manages implement → review → fix → re-review loops. Do not delegate lifecycle management to N+1 orchestrator subagents.
+- **Subagents get single-responsibility prompts.** One job each: "implement this spec," "review this diff," "fix these findings."
+- **Spec-driven implementation.** Implementers receive a written spec file, not prose descriptions.
+
+### Concurrency
+- **Simple** (< 50 lines): Direct Codex worker + Opus review. Parallel OK.
+- **Standard** (single-PR features): Main session spawns workers directly. Parallel PRs OK (max 2-3) if no file overlap.
+- **Complex** (multi-crate, architectural): **Sequential only — one PR at a time.** Main session manages full context.
+
+### Rules
+1. Main session NEVER writes code. All code work delegated to subagents, no exceptions.
+2. Implementers + Fixers use `openai-codex/gpt-5.4` with `thinking: "xhigh"`. Reviewers use `anthropic/claude-opus-4-6` with `thinking: "adaptive"`.
+3. Main session chains stages (implement → review → fix → re-review) directly — no N+1 orchestrator layer.
+4. All review findings (blocking, non-blocking, nice-to-have) must be fixed. Fresh reviewer for R2.
+5. Every subagent prompt includes ENGINEERING.md rules and the spec file path.
+
+---
+
+*This file is immutable doctrine. Cite it in PR reviews. Changes require explicit user approval. For evolving preferences and style, see `TASTE.md`.*
diff --git a/README.md b/README.md
@@ -13,15 +13,16 @@ Fawx is a local-first agentic engine. It runs on your machine, calls LLMs for re
 ## Quick Start
 
 ```bash
+# Build
 git clone https://github.com/fawxai/fawx.git
-cd fawx
-./scripts/install.sh
+cd fawx && cargo build --release
 
-fawx setup
-fawx serve
-```
+# Configure (interactive wizard)
+./target/release/fawx setup
 
-This builds from source, installs the `fawx` binary to `~/.local/bin/`, and walks you through configuration. Set `INSTALL_DIR` to change the install location.
+# Run
+./target/release/fawx serve
+```
 
 Bring your own API key (Anthropic, OpenAI, or local models). Fawx never sends data anywhere except the LLM provider you choose.
 
@@ -102,7 +103,7 @@ WASM skills extend Fawx's capabilities. Each skill runs in a sandboxed WebAssemb
 
 ## WASM Skills
 
-Skills are Rust crates compiled to WebAssembly. The [skill marketplace](https://github.com/fawxai) has ready-to-install skills. Building your own takes minutes:
+Skills are Rust crates compiled to WebAssembly. The recommended local-dev workflow is `fawx skill build <project>`: it builds the project for `wasm32-wasip1`, installs it into `~/.fawx/skills/`, and signs it when a signing key is present.
 
 ```rust
 #[no_mangle]
@@ -114,13 +115,29 @@ pub extern "C" fn run() {
 ```
 
 ```bash
-# Install a skill
-fawx skill install fawxai/skill-web-search
-
-# Or build your own
+# Recommended local-dev workflow
 cargo generate fawxai/skill-template
-cargo build --release --target wasm32-unknown-unknown
-fawx skill install ./target/wasm32-unknown-unknown/release/my_skill.wasm
+cd my-skill
+fawx skill build .
+```
+
+Use the other paths when they match your input:
+
+- `fawx skill build <project>` is the canonical local-dev path for a custom skill project.
+- `skills/build.sh --install` is the repo maintainer path for the built-in `skills/` collection.
+- `fawx skill install <path>` is the artifact path for a prebuilt `.wasm` file or skill directory.
+- `fawx keys generate` creates a local signing keypair and trusts the matching public key for local verification.
+- `fawx sign <skill>` signs an already-installed skill when it still needs a signature.
+
+If you generate or trust a key while the server is already running, restart it before expecting the loaded skill state to flip from `invalid` to `valid`.
+
+```bash
+# Prebuilt local artifact
+cargo build --release --target wasm32-wasip1
+fawx skill install ./target/wasm32-wasip1/release/my_skill.wasm
+
+# Built-in repo skills collection
+skills/build.sh --install
 ```
 
 Available skills: [web search](https://github.com/fawxai/skill-brave-search) · [web fetch](https://github.com/fawxai/skill-web-fetch) · [scheduler](https://github.com/fawxai/skill-scheduler) · weather · vision · TTS · STT · browser · canvas

diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,32 @@
+# Fawx Documentation
+
+## Current
+
+| Document | Description |
+|----------|-------------|
+| [SPEC.md](SPEC.md) | Original product specification |
+| [WASM_SKILLS.md](WASM_SKILLS.md) | WASM skill system design |
+| [codex-oauth-bridge-api.md](codex-oauth-bridge-api.md) | OAuth bridge API for OpenAI auth |
+| [squad-constitution.md](squad-constitution.md) | Development standards |
+| [testing-patterns.md](testing-patterns.md) | Test organization and patterns |
+
+## Specs
+
+| Document | Description |
+|----------|-------------|
+| [phase3-roadmap.md](specs/phase3-roadmap.md) | Phase 3 roadmap (docs, polish, launch) |
+
+## Reference
+
+Engineering standards and codebase rules live in the repo root:
+- [`ENGINEERING.md`](../ENGINEERING.md) — Immutable development doctrine
+- [`ARCHITECTURE.md`](../ARCHITECTURE.md) — System architecture overview
+- [`TASTE.md`](../TASTE.md) — Style and design preferences
+
+## Archive
+
+Completed and backlog specs are archived:
+- `archive/completed-specs/` — 52 specs from Phases 0-2 and Waves 1-8
+- `archive/completed-docs/` — 11 completed design documents
+- `archive/backlog-specs/` — 11 future feature specs
+- `deprecated/` — 8 deprecated documents