Skip to content
FractalOps

AgentSquad PARA

AgentSquad PARA

Section titled “AgentSquad PARA”

현재 진실(current truth)만. 옛 디테일은 git/evidence에 산다. 간결하게 유지하라.

레일(Rails)

Section titled “레일(Rails)”
  • 제네릭 AgentSquad 런타임만 다룬다. 제품 repo를 직접 패치하지 마라.
  • Mailbox first: inbox/sent/pending-reply/self-kick/handoff 카드가 PR/evidence/proof/merge를 몬다.
  • Wall != blocker: wall은 guardrail retry prompt/tool 경로를 노출하고, blocker는 실패 원인을 기록한다.
  • 첫 턴은 계획만 => self/next kick: 계속하고, diff 만들고, gate 돌리고, PR 제출.
  • 모호한 요청 => 송신자에게 question 카드 반송.
  • Frontend 레일: Astro >=6.4.0, Atomic UI, ubiquitous naming, Tailwind >=4.3.0, DaisyUI 5, flat ESLint, 비주얼 proof.
  • Backend/CLI 레일: Python, DDD bounded context, feature-slice, hexagonal port/adapter, 유용할 때만 CQRS, Tach 게이트; CLI entrypoint는 얇게, feature 로직/테스트는 named slice에 colocate.
  • Backend TDD 레일: *_test.py를 소유 source/adapter 옆에 colocate; root 테스트는 cross-repo 계약만.
  • Behavior 레일: 제네릭 scaffold 금지; 딜리버리에는 named source reference, source-rule map, PR, proof가 필요.
  • GitHub 레일: 모든 에이전트 체크포인트는 fresh PR/issue/comment 증거로 land; stale open GitHub 작업은 refresh/close 전까지 무시.
  • 반복되는 수동 교정 => 프롬프트 길이가 아니라 skill/wall/tool-bridge/execution 계약을 갱신.
  • Tempo 레일: proof 변화당 retry/kick 한 번; pin/secret/rollout/workspace/tool 증거를 기다린다; squad는 harness 패키징/빌드 낭비를 감지하지 controller 미세조정이 아님.

런타임 진실(Runtime Truth)

Section titled “런타임 진실(Runtime Truth)”
  • Temporal이 durable한 워크스페이스/소스/프로세스/evidence lifecycle 데드라인을 소유.
  • Studio가 run/session/mailbox, frontier, slot intent, next action을 소유.
  • Tempo phase: pending -> workspace_provisioning -> toolbox_warming -> source_materializing -> worktree_checkout_proof -> runner_started -> initializing -> waiting_first_tool -> agent_running -> evidence_seen -> terminal.
  • First-tool 데드라인 = INITIALIZE(180s) + FIRST_TOOL_WINDOW(180s) = 360s (execution_tempo_contract.py).
  • 런타임 네이밍: Execution Workspace = Daytona 리스, Agent Process = Claude/Codex/browser adapter, Cache Plane = 단일 Nexus(npm/pypi/apt/docker-pull/buildcache), Delivery Plane = GitHub/Dokploy/Vercel-style release target.
  • Dev preview: Daytona 샌드박스 안 맨몸 dev 서버(vite/next/uvicorn, --host 0.0.0.0), daytona-proxy 서명 프리뷰 URL로 노출(dev-preview MCP). docker는 샌드박스 하드 exit-127 wall; in-sandbox compose/build 플레인 없음.
  • Per-project preview: 하나의 호스트 <slug>.monstore.io가 LIVE dev preview를 서빙(돌 때), 아니면 Dokploy delivery; preview lifecycle에 따른 per-slug edge route(와일드카드 hijack 금지).
  • Dokploy 플레인: 지속 백킹 서비스만(database, static-site/vercel-sim hosting, big-facility compose) — dev 서버 아님.
  • 플랫폼 CI 이미지 빌드는 GitOps-pinned + Nexus buildcache; agent dev 루프와 별개.
  • Repository Pages: per-repo Starlight docs CRUD asset; Vercel-style release command, Dokploy provider, Pomerium yamon-identity 보호; repo별 runner/container 증식 없음.
  • Wall policy는 fractalops-agent-wall-policy에서 로드; 가능하면 GitOps ConfigMap으로 guardrail retry prompt를 튜닝.
  • Workspace asset 규칙: provider workspace/prepared state는 공유, agent slot/worktree/process는 격리; dirty worktree 공유나 PR 증거 전 스냅샷 금지.
  • OpenBao/SPIRE 진실: OpenBao가 secret 저장/회전; SPIRE가 workload 식별; prod secret_backend=env 차단; core workload는 전용 ServiceAccount SVID를 OpenBao JWT auth subject로 제출. seed material은 정적 초기값이 아니라 SPIRE-authenticated seed issuer가 OpenBao에 쓴다.

착륙한 수정(Fixes Landed)

Section titled “착륙한 수정(Fixes Landed)”
  • 공유 repo는 default branch 유지; 소유 repo는 agent delivery branch 사용.
  • 번들 source ref는 허용; 런타임이 로컬 /tmp를 못 볼 땐 durable source 번들 URL 여전히 필요.
  • CLI root는 얇게; registry/project-agents/next-actions/observability/lineage/agentsquad/research는 cli_commands/* feature slice에.
  • retired frontend 패키지 설치 명령은 cliproxy에서 차단.
  • 정식 PR 핸드오프 target은 에이전트가 지어낸 repo/branch를 무시.
  • Frontend skill/atomic guard는 standalone CSS Tailwind/DaisyUI entrypoint와 정식 atomic 재사용을 요구.
  • Harness/skill/wall 딜리버리는 @fractalops/workspace-tools 패키지-first; 설치는 node-local NodePort가 아니라 안정 https://npm.yamon.io.
  • Retry/projection은 runner 페이로드를 current-attempt 진실로; stale first-tool/report/PR 메타데이터는 새 딜리버리 kick을 충족 못 함.
  • Grid MCP는 OpenBao-backed API 토큰 env가 resolve될 때만 실제 /v1/grid/events emit; 미해결 $(GRID_EVENTS_TOKEN)은 sink 비활성.
  • PR URL 있는 blocked 세션은 durable progress comment를 GitHub에 미러; PR URL 없으면 durable AgentSquad progress issue 생성/재사용.
  • GitHub progress dedupe는 workspace/attempt/branch 포함; backlog는 freshness window로 stale open issue/PR 무시, type:agent-progress/type:agent-handoff는 product backlog가 아니라 evidence로 취급.
  • Blocked prompt phase는 current_step blocker를 GitHub에 미러해 agent_first_tool_required가 prompt_dispatched 뒤에 숨지 않게.
  • Coordination 역할은 assembly repo path를 받아야; coordinator retry가 project repo 바인딩을 hydrate해 planner/curator가 PR 전에 GitHub 카드 발행 가능.
  • Backend 핸드오프/projection은 source-ref 상수, 커밋된 source-rule-map 파일, materialize된 PR ref를 stale no-delivery 텍스트보다 durable 증거로 취급.
  • 어긋난 agent worktree branch는 patch/status 백업, stale worktree 제거, 기대 delivery branch 재생성.
  • Agent Memory Archive MCP가 로컬 JSONL store 소유; 백엔드 agent_memory_archive bounded context와 Tach 표면 삭제.
  • Project delivery는 기존 branch PR을 evidence로 lift하고, stale/generated-artifact 핸드오프를 거부하며, PR-required 역할이 prompt-only report 뒤에 숨지 못하게.

관련 문서

Section titled “관련 문서”