Skip to content
FractalOps

AgentSquad PARA

AgentSquad PARA

Section titled “AgentSquad PARA”

Keep <= 90 lines. Current truth only. Old detail lives in git/evidence.

Rails

Section titled “Rails”
  • Generic AgentSquad runtime only; do not patch product repos directly.
  • Mailbox first: inbox/sent/pending replies/self-kick/handoff cards steer PR/evidence/proof/merge.
  • Wall != blocker: wall exposes fallback/tool prompt; blocker records failure cause.
  • First-turn plan only => self/next kick: continue, create diff, run gates, submit PR.
  • Ambiguous request => question card back to sender.
  • Frontend rail: Astro >=6.4.0, Atomic UI, ubiquitous naming, Tailwind >=4.3.0, DaisyUI 5, flat ESLint, visual proof.
  • Backend/CLI rail: Python, DDD bounded context, feature-slice, hexagonal ports/adapters, CQRS only when useful, Tach gates; CLI entrypoints stay thin, feature logic/tests colocate under named slices.
  • Backend TDD rail: colocate *_test.py beside owned source/adapter; root tests only cross-repo contracts.
  • Behavior rail: no generic scaffold; delivery needs named legacy source, source-rule map, PR, proof.
  • GitHub rail: every agent checkpoint must land in fresh PR/issue/comment evidence; stale open GitHub work is ignored until refreshed or closed.
  • Repeated manual correction => update skill/wall/shim/runtime contract, not prompt length.
  • Tempo rail: one retry/kick per proof change; wait for pin/secret/rollout/workspace/tool evidence; squad detects harness packaging/build-waste, not controller micro-fixes.

Runtime Truth

Section titled “Runtime Truth”
  • Temporal owns durable workspace/source/process/evidence lifecycle deadlines.
  • LangGraph owns agent graph, mailbox/frontier, slot intent, checkpoints.
  • Tempo phases: pending -> provisioning -> warming -> materializing -> runnable -> agent_running -> waiting_first_tool -> evidence_seen -> terminal.
  • Runtime naming: Execution Workspace = Daytona lease, Agent Process = Claude/Codex/browser adapter, Cache Plane = single Nexus (npm/pypi/apt/docker-pull/buildcache), Delivery Plane = GitHub/Dokploy/Vercel-shim.
  • Dev preview: bare dev server (vite/next/uvicorn, --host 0.0.0.0) in the Daytona sandbox, exposed via the daytona-proxy signed preview URL (dev-preview MCP). docker is a hard exit-127 wall in the sandbox; there is no in-sandbox compose/build plane.
  • Per-project preview: one host <slug>.monstore.io serves the LIVE dev preview when running, else the Dokploy delivery; per-slug edge route on preview lifecycle (no wildcard hijack).
  • Dokploy plane: persistent backing services only (databases, static-site/vercel-sim hosting, big-facility compose) — not dev servers.
  • Platform CI image builds are GitOps-pinned and use the Nexus buildcache; this is separate from the agent dev loop.
  • Repository Pages: per-repo Starlight docs CRUD asset; Vercel-shim command, Dokploy provider, Pomerium yamon-identity protection; no repo-specific runner/container growth.
  • Wall policy loads from fractalops-agent-wall-policy; tune fallback prompts by GitOps ConfigMap when possible.
  • Workspace asset rule: share provider workspace/prepared state; isolate agent slot/worktree/process; never share dirty worktree or snapshot before PR evidence.
  • OpenBao/SPIRE truth: OpenBao stores/rotates secrets; SPIRE identifies workloads; prod secret_backend=env blocked; JWT-SVID OpenBao auth must be explicit, not assumed.

Fixes Landed

Section titled “Fixes Landed”
  • Shared repos stay on default branch; owned repos use agent delivery branch.
  • Bundled source refs tolerated; durable source bundle URL still required when runtime cannot see local /tmp.
  • CLI root stays thin; registry/project-agents/next-actions/observability/lineage/ouroboros/research live under cli_commands/* feature slices.
  • Legacy frontend package install commands blocked in ClipProxy.
  • Canonical PR handoff target ignores agent-invented repo/branch.
  • Frontend skills/atomic guard require standalone CSS Tailwind/DaisyUI entrypoint and canonical atomic reuse.
  • Harness/skill/wall delivery is package-first via @fractalops/workspace-shims; install uses stable https://npm.yamon.io, not node-local NodePort.
  • Retry/projection treats runner payload as current-attempt truth; stale first-tool/report/PR metadata cannot satisfy new delivery kicks.
  • Grid MCPs emit real /v1/grid/events only when OpenBao-backed API token env resolves; unresolved $(GRID_EVENTS_TOKEN) disables sink.
  • Blocked sessions with PR URL mirror durable progress comments to GitHub from session projection; without PR URL they create/reuse durable AgentSquad progress issues.
  • GitHub progress dedupe includes workspace/attempt/branch; backlog ignores stale open issues/PRs by freshness window and treats type:agent-progress/type:agent-handoff as evidence, not product backlog.
  • Blocked prompt phases mirror current_step blocker to GitHub so agent_first_tool_required is not hidden behind prompt_dispatched.
  • Outcome projection mirrors blocked GitHub progress, not only launch-time runner failures.
  • Coordination roles must receive the assembly repo path; coordinator retries hydrate project repo bindings so planner/curator can publish GitHub cards before PRs exist.
  • Assembly coordinator proof uses workspace root; tester/committer repo-root confusion becomes workspace_repo_root_required wall.
  • Backend handoff/projection treats source-ref constants, committed source-rule-map files, and materialized PR refs as durable evidence over stale no-delivery text.
  • Mismatched agent worktree branch backs up patch/status, removes stale worktree, recreates expected delivery branch.
  • Agent Memory Archive MCP owns its local JSONL store; deleted backend agent_memory_archive bounded context and Tach surface.
  • Session repository preserves workspace/session identity when empty metadata payload arrives.
  • Project delivery lifts existing branch PRs as evidence, rejects stale/generated-artifact handoffs, and keeps PR-required roles from hiding behind prompt-only reports.
Section titled “Related”