Development

Developer & Agent Working Patterns (DEVELOPMENT.md)

1. Architectural Overview & Trunk-Based Development

SiteSwarm operates on a strict Trunk-Based Development Architecture with Worktrunk (wt) worktree isolation and mechanical merge enforcement:

flowchart LR
    Main["Authoritative Trunk\n(origin/main)"] -->|"wt switch --create\nfeature/<N>-<slug>"| Worktree["Isolated Worktree\n(../siteswarm.feature-<N>-<slug>)"]
    Worktree -->|"Two-Tier Verification\n(Machine + Runtime Proof)"| PR["Pull Request\n(Fixes #<N>)"]
    PR -->|"CI Gate + Two-Stage Review"| MergeLatch["Mechanical Merge Latch\n(pnpm run merge <PR>)"]
    MergeLatch -->|"Fast-Forward / Squash"| Main

1. Single Authoritative Trunk (main): All production code merges into main. Direct pushes and force-pushes are blocked via GitHub Repository Rulesets (.github/branch-ruleset.json, see CI_DEPLOYMENT_ENVIRONMENTS.md).
2. Worktree Confinement: Direct editing on main is strictly prohibited. All changes must be authored inside isolated Git worktrees.
3. Mechanical Merge Latch: Pull Requests cannot be merged with raw gh pr merge; all merges are attested and executed via pnpm run merge <PR_NUMBER>.

---

2. Git Worktree Protocol with Worktrunk (wt)

Developers and parallel AI agents isolate development using Worktrunk (wt).

Step-by-Step Worktree Workflow:

1. Verify Workspace State:

   wt list
   git status

2. Spawn Worktree from origin/main: Derive branch name from the tracking issue: feature/<issue-number>-<slug> or fix/<issue-number>-<slug>.

   wt switch --create "feature/<N>-<slug>" --base origin/main

3. Confine Execution Strictly to the Worktree:
   • Execute all shell commands inside the worktree directory (../siteswarm.feature-<N>-<slug>).
   • Edit files exclusively inside the worktree checkout.
   • Never touch shared root dotfiles or other worktrees.
4. Teardown & Cleanup: After PR merge into main:

   wt switch main
   wt remove --reap "feature/<N>-<slug>"
   git worktree prune

---

3. Essential Toolchain Commands

SiteSwarm uses pnpm exclusively across all workspace packages and apps.

Task	Command	Description
Install Dependencies	pnpm install	Installs dependencies across all monorepo packages.
Monorepo Build	pnpm run build	Builds all edge applications and platform libraries.
Comprehensive Verification	pnpm run check	Audits governance schemas, edge linting, and TypeScript typechecking.
Architectural Linter	pnpm run lint:arch	Verifies cross-package boundaries, documentation taxonomy, and import constraints.
Unit & Integration Tests	pnpm run test	Executes hermetic unit tests with zero API keys required (RULES.md).
Tooling Test Suite	pnpm run test:tooling	Executes test suites for root scripts and developer CLI utilities.
Local Dev Runner	pnpm run dev	Interactive multi-app local development runner with dynamic OS port negotiation.
Targeted App Dev	pnpm --filter=@siteswarm/<app> run dev	Runs a single application development server.
Mechanical Merge	pnpm run merge <PR_NUMBER>	Validates status checks and merges PR into main.

---

4. Two-Tier Verification Gate (Passing CI ≠ Verified)

No pull request or deliverable is ready for review solely because automated unit tests pass. Integration verification requires both tiers:

Tier 1: Machine Gate

• TypeScript compiles cleanly (pnpm run check).
• Architectural and edge linters pass (pnpm run lint:arch, pnpm run lint:edge).
• Unit and tooling test suites pass 100% green (pnpm run test, pnpm run test:tooling).

Tier 2: Behavioral Runtime Proof

• Real Runtime Execution: Execute the application or command against the local edge runtime or CLI (e.g. running the command, verifying generated output files, or inspecting HTTP response status).
• Anti-Mocking Invariant: Never rely on unit tests with mocked functions as proof that an integration works. Real runtime proof must be demonstrated in the PR execution evidence.
• End-to-End Verification: Run Playwright test suites where applicable (pnpm run test:e2e).

---

5. Two-Stage Adversarial Review Protocol

To prevent self-grading and ensure code quality, pull requests must pass an independent two-stage review before merge:

1. Stage 1 (Tactical Review):
   • Evaluates PR diff line-by-line against the issue’s 4-part Acceptance Criteria.
   • Verifies TypeScript types, edge runtime safety, and modularity thresholds.
2. Stage 2 (Strategic & Anti-Mocking Review):
   • Verifies intent match against macro-architecture (HIGH_LEVEL_DESIGN.md).
   • Conducts anti-mocking screen to confirm Tier 2 Behavioral Runtime Proof is authentic.
3. Attestation & Enforcement:
   • Reviews are submitted via standard GitHub PR reviews (gh pr review).
   • The status check governance/two-stage-review attests both stages before merge.

---

6. Zero Untracked Work Protocol

Every engineering action falls into one of two tracks:

• Track 1: Active Development: Must be associated with an open GitHub issue assigned to @me with status:in-progress and the mandatory 4-part Acceptance Criteria (Functional Deliverables, Tier 1 Machine Gate, Tier 2 Runtime Proof, Anti-Mocking Guardrails).
• Track 2: Idea Ingestion: Brainstorms, architectural suggestions, or future ideas must be captured immediately as GitHub issues quarantined with needs-grooming without writing source code in the same session.

---

Decisions Intentionally Deferred

• Automated subagent dispatch orchestration across Claude Code and Antigravity is specified directly in .agents/skills/pm/SKILL.md.