AgentSquad Delivery Language

AgentSquad 딜리버리 언어

이 페이지는 제네릭 AgentSquad 딜리버리의 유비쿼터스 언어(ubiquitous language) 입니다. 이 이름들을 Studio, Temporal, Agent Execution, Armory, workspace tool bridge, 테스트, 런북에서 쓰세요. 고객, source-reference 소스, 스택 이름 같은 제품 특화 이름을 제네릭 AgentSquad lifecycle에 더하지 마세요.

실행 경계(Execution Boundary)

Temporal workflow는 durable한 워크스페이스/소스/프로세스 lifecycle 데드라인을 소유합니다.
Agent Execution은 provider 선택과 adapter를 통한 agent attempt 실행을 소유합니다.
Studio는 mailbox/frontier, next action, operator 제어, read model, report를 소유합니다.
Armory는 MCP, skill, secret, browser-slot, CLI loadout 구성을 소유합니다.
AgentSquad는 제네릭 프로젝트-딜리버리 graph 템플릿입니다.
delivery graph kind는 제품 워크플로 형태의 이름입니다. 현재 정식 값은 project_delivery 하나입니다.
agent process adapter는 한 agent attempt가 실행되는 방식의 이름입니다 — 예: claude-cli, codex-cli, workspace-cli, browser-only.
assembly worktree는 cross-repo 컨텍스트를 위한 공유 read/observation 체크아웃입니다.
agent-owned worktree는 한 agent lane을 위한 쓰기 가능한 Git worktree입니다.
execution surface는 일을 실행할 수 있는 provider 표면의 AgentSquad-facing 이름입니다. 플랫폼/API 경계에서는 여전히 runtime asset입니다.
execution workspace는 agent process가 일하는 per-run 워크스페이스입니다.
workspace bootstrap asset은 agent process가 시작되기 전에 execution workspace로 전달되는 파일입니다.
source ref bundle은 읽기 전용 source-reference 자료로 쓰이는 workspace bootstrap asset 입니다.

에이전트는 terminal을 쓸 수 있습니다. Guardrail은 셸 접근 자체가 아니라 안전하지 않은 소유권과 무효한 lifecycle 주장을 막습니다.

MCP 도구 네이밍과 Loadout 페더레이션

Armory는 ContextForge 게이트웨이 위에서 MCP loadout을 구성하고, 게이트웨이는 각 yamon grid(searxnggrid, agent-memory-archive, datahub, glitchtip, playwright)를 페더레이트합니다. 같은 도구에 세 가지 이름이 있으니 구분하세요.

bare upstream name: grid가 실제로 노출하는 도구. grid는 bare 이름을 노출합니다 — 예: searxnggrid의 search_query. grid는 prefix를 더하지 않습니다.
federated wire name: 게이트웨이가 서빙하는 이름. 각 grid는 yamon-<server_id>라는 federated 게이트웨이로 등록되고, 게이트웨이가 그 grid의 도구에 slug를 prefix합니다 — 그래서 searxnggrid의 search_query는 yamon-searxnggrid-search-query로 서빙됩니다. <server_id>(예: searxnggrid)라는 virtual MCP 서버가 그 prefix된 도구들을 /servers/<hash>/mcp에 묶습니다. yamon-<grid>- prefix는 grid가 아니라 게이트웨이가 더한 것입니다.
agent-facing name: 에이전트에게 보이는 짧은 bare 이름, mcp__<server_id>__<bare_tool>(예: mcp__searxnggrid__websearch_like). 에이전트는 두 번 prefix된 federated 형태(mcp__searxnggrid__yamon-searxnggrid-websearch-like)를 절대 보지 않습니다. 팔레트를 bare로 유지하면 토큰을 아끼고 읽기 쉽습니다.

워크스페이스 런타임 adapter는 agent-facing bare 이름을 프록시 호출에서만 게이트웨이의 federated wire name으로 번역합니다. 에이전트의 도구 팔레트는 절대 페더레이션 prefix를 달지 않습니다.

flowchart LR
  grid["grid (searxnggrid)\nbare: search_query"]
  gw["ContextForge 게이트웨이\nfederated: yamon-searxnggrid-search-query"]
  agent["에이전트 팔레트\nagent-facing: mcp__searxnggrid__search_query"]

  grid -->|게이트웨이가 prefix| gw
  gw -->|adapter가 bare로 표시| agent
  agent -->|프록시 호출 시 federated 로 번역| gw

정식 도구 매칭(Canonical Tool Matching)

grounding first-tool 게이트와 tool-coverage 매칭은 도구 이름을 정식으로(canonically) 비교합니다: yamon-<server>- 페더레이션 prefix를 벗기고 snake/kebab 차이를 정규화합니다. 한 호출은 bare 형태(cliproxy 런타임, 여기서 workspace tool bridge가 팔레트를 만듦)로 관찰되든 federated 형태(claude-native 런타임, 게이트웨이에서 직접 이름을 발견)로 관찰되든 credit 됩니다. 두 런타임 모두 같은 도구에 대해 grounding 게이트를 잘못 trip하지 않습니다.

Allow-List 형태

loadout은 열거된 도구 이름이 아니라 server별 wildcard 하나 mcp__<server_id>__*를 allow-list합니다. wildcard는 cliproxy tool bridge가 확장하는 bare 이름과 claude-native가 발견하는 federated 이름을 모두 매칭하고, upstream 도구 add/rename에도 살아남습니다. 최소권한은 개별 도구가 아니라 server-attachment 레벨(loadout이 어떤 MCP 서버를 mount하는지)에서 강제됩니다.

런타임(Runtimes)

cliproxy runtime (squad 기본): endpoint binding central_cliproxy, 모델은 AgentProcess profile의 CliProxy alias. workspace tool bridge가 bare upstream 이름으로 LLM 도구 팔레트를 만들고 MCP 호출을 프록시하며, 호출 시 federated wire name으로 번역합니다.
claude-native runtime (direct ContextForge): ContextForge 게이트웨이에 직접 연결해 federated wire name을 게이트웨이에서 발견합니다.

실행 네이밍 척추(Execution Naming Spine)

더 좁은 명사가 있을 때 맨 runtime을 절대 쓰지 마세요. AgentSquad 딜리버리에서 runtime은 다음 호환성/플랫폼 명사 중 하나를 뜻할 때만 씁니다: Agent Execution, runtime asset, runtime image. 그 외 모든 곳에서는 코드가 답하는 질문에 따라 명사를 고르세요:

질문	이 이름을 써라	예
lifecycle 데드라인과 activity 재시도를 누가 소유?	`Temporal workflow`	워크스페이스 warmup activity 재시도
session 상태와 next action을 누가 소유?	`Studio`	mailbox/frontier projection
어떤 provider 표면이 일을 실행?	`execution surface`	Daytona, Dokploy executor, PlaywrightGrid
이 attempt의 파일시스템은 어디?	`execution workspace`	Daytona 샌드박스 리스
어떤 프로세스/도구 모드가 attempt를 실행?	`agent process adapter`	`claude-cli`, `codex-cli`, `browser-only`
launch 전에 복사되는 파일은?	`workspace bootstrap asset`	source tarball, proof bundle
배포되는 이미지는?	`deploy image`	`fractalops-api` 컨테이너 이미지

Agent Execution
  -> execution surface
     -> execution workspace
        -> agent process adapter

Temporal workflow: durable lifecycle 소유자. phase 데드라인, activity 재시도, 타이머, 긴 wait를 결정.
Studio: run/session/mailbox 상태와 next action의 소유자.
Agent Execution: provider policy와 실행 adapter 경계.
execution surface: FractalOps가 주소 지정할 수 있는 관리 머신/클러스터/서비스/executor 엔드포인트. 플랫폼/API 경계에서 runtime asset으로 매핑.
execution workspace: per-run/per-session 워크스페이스 리스, 보통 Daytona 샌드박스/워크스페이스.
agent process adapter: 한 attempt 실행기 — 예: Claude CLI, Codex CLI, workspace CLI, browser-only.
deploy image: 배포 가능한 컨테이너 아티팩트. lifecycle 소유자도, 워크스페이스 리스도 아님.

파일 이동은 runtime이 아닙니다. launch 전 전달 파일은 workspace bootstrap asset, source-reference 아카이브는 source ref bundle을 쓰세요.

실행 어휘 스택(Execution Vocabulary Stack)

가장 좁은 명사를 쓰세요. 이 레이어들을 runtime으로 뭉뚱그리지 마세요.

레이어	정식 이름	소유	예시 값
Workflow lifecycle	`Temporal workflow`	워크스페이스/소스/프로세스 데드라인, activity 재시도, 타이머	workspace provision activity
Session lifecycle	`Studio`	mailbox/frontier, slot intent, next action	run/session projection
Delivery shape	`delivery graph kind`	제품 워크플로 템플릿	`project_delivery`
Agent executor	`agent process adapter`	한 attempt의 프로세스/도구 모드	`claude-cli`, `codex-cli`, `browser-only`
Machine surface	`execution surface`	관리 VM/LXC/Kubernetes/서비스 엔드포인트	Daytona, PlaywrightGrid, Dokploy executor
Per-run lease	`execution workspace`	run/session에 배정된 워크스페이스	Daytona 샌드박스/워크스페이스
Source transfer	`workspace bootstrap asset`	launch-time 파일 전달	tarball, CLI 패키지, proof bundle
Deploy artifact	`deploy image`	CI가 빌드/릴리스한 컨테이너 이미지	`fractalops-api`, `fractalops-worker`
Git ownership	`agent-owned worktree`	쓰기 가능한 delivery branch	backend/frontend/tester worktree
Shared context	`assembly worktree`	읽기 전용 cross-repo observation	assembly repo 체크아웃
Operator projection	`Agent Control Surface`	컴팩트 human/control read model	status, wall, blocker, mailbox

금지된 지름길:

execution workspace를 runtime이라 부르지 마라.
workspace bootstrap asset을 runtime asset이라 부르지 마라.
runtime image를 Agent Execution이라 부르지 마라.
deploy image를 execution surface라 부르지 마라.
delivery graph kind를 agent process이라 부르지 마라.
agent process adapter 재시작이나 Claude 세션 reset을 fresh execution workspace라고 부르지 마라.
새 코드에서 BOARD_STATUS를 board 개념이라 부르지 마라. 그것은 AGENT_HUD_STATUS의 wire-supported retired field다.

새 코드와 문서에서 이 과적재(overloaded) 표현들을 은퇴시키세요:

옛 표현	대체
`agent process`	CLI/browser 모드를 뜻하면 `agent process adapter`
`workspace runtime`	`execution workspace`
`runtime source bundle`	`workspace bootstrap asset` 또는 `source ref bundle`
`runtime deploy`	`deploy image release` 또는 `GitOps rollout`
`runtime status`	`executionWorkspacePhase`, `agent attempt status`, 또는 `Agent Control Surface status`
`runner`	실행기는 `agent process adapter`, activity는 `Temporal worker`
AgentSquad 산문의 `runtime asset`	플랫폼 API 계약을 명명하는 게 아니면 `execution surface`
AgentSquad 산문의 `runtime image`	호환성 필드를 명명하는 게 아니면 `deploy image`

네이밍 Guardrail

runtime을 모든 움직이는 부품의 제네릭 동의어로 쓰지 마세요. 그것은 실행 엔진 또는 관리 실행 표면만을 명명합니다. 파일 전달, 소스 materialization, worktree 체크아웃에는 각자의 이름이 있습니다.

쓸 것	의미	이렇게 부르지 마라
`Agent Execution`	agent attempt용 provider adapter 경계	lifecycle 소유자, Studio, worker
`delivery graph kind`	run/template 워크플로 형태	agent process kind
`agent process adapter`	attempt 실행 adapter	delivery graph kind
`execution surface`	소유 머신/서비스 표면	workspace, source asset
`execution workspace`	에이전트용 Daytona/워크스페이스 리스	runtime, repo
`workspace bootstrap asset`	launch 전 복사/다운로드된 파일	runtime asset
`source ref bundle`	읽기 전용 source-reference 아카이브	source repo, runtime
`deploy image`	배포 가능한 컨테이너 아티팩트	Agent Execution, execution workspace
`agent-owned worktree`	쓰기 가능한 Git lane 체크아웃	workspace root
`assembly worktree`	공유 읽기 전용 multi-repo 컨텍스트	owned repo

retired wire 필드는 runtime_kind나 runtimeKind로 들어올 수 있습니다. 새 코드와 새 문서는 아래 표준 필드로 정규화하세요:

Studio run/template/session 메타데이터는 agent_process_kind를 씀.
Harness 페이로드/spec 메타데이터는 agentProcessKind를 씀.
환경·토폴로지 필드의 runtime은 보통 runtime asset이나 provider 설정을 뜻함; 거기서 Harness lifecycle을 추론하지 마라.

새 코드는 명시적 로컬 변수명을 선호하세요. retired wire 필드 이름은 API/DB/페이로드 경계에서만 격리하거나 제거하세요.

BOARD_STATUS는 AGENT_HUD_STATUS의 wire-supported retired field입니다. 새 애플리케이션 코드는 blocker_code, wall_code, executionWorkspacePhase, AGENT_HUD_STATUS를 읽고/쓰며; 페이로드 adapter만 BOARD_STATUS를 보존합니다.

workspaceBootstrapAssets[]와 sourceRefBundleUrl은 retired 파일-전달 계약입니다. 제품 소스는 sourceRefRepos[]를 통해 클러스터가 OCI artifact로 만들고, 워크스페이스는 ORAS/cosign/age 검증 경로로만 가져옵니다. CLI 패키지와 proof bundle도 generic URL bootstrap이 아니라 Dev Container Feature 또는 서명된 OCI artifact로 다룹니다.

에이전트 Identity와 Handoff

코드, 테스트, 문서, 프롬프트, 텔레메트리를 더할 때 이 이름들을 쓰세요:

role_id: frontend, tester, committer 같은 안정적 capability lane.
agent_id: Studio agent session의 영속 라우팅 identity. 옛 레코드에서 role과 같을 수 있으나, 새 언어에서 사람 이름으로 다루지 마세요.
agent_nickname: 사람과 mail을 위한 생성 표시 identity. 라우팅, 소유권, 인가, Git branch 소유에 절대 쓰지 않습니다.
sender_agent_id: handoff 메시지를 만든 에이전트.
recipient_agent_id: handoff 메시지에 반응해야 하는 에이전트.
dialogue_peer_agent_id: 한 session 관점에서 열린 대화의 상대편.
delivery_reference: PR 또는 issue URL + branch/repository 증거.

명사 없는 target을 쓰는 새 코드/문서를 피하세요. 영속 API/DB 필드가 여전히 target_agent_id라면 recipient_agent_id의 wire-호환 alias로, dialogue_target_agent_id라면 dialogue_peer_agent_id의 wire-호환 alias로 다루세요.

handoff 지시는 recipient뿐 아니라 의도와 성공 조건을 운반해야 합니다:

sender_agent_id
recipient_agent_id
handoff_intent
required_result
delivery_reference
guardrail_retry_wall

Product-specific prompts must not redefine the AgentSquad delivery vocabulary. A controller message names the delivery reference it is acting on, and a missing delivery reference blocker means the feature has no acceptable project delivery evidence yet. A handoff must preserve the assembly worktree for shared context, the agent-owned worktree for writes, and the current merge lifecycle decision.

Mechanical Wall is not a blocker by itself. It is a guardrail retry prompt from the mechanical guidance system that keeps the run moving until real delivery evidence exists. Merge handoff language uses explicit lifecycle markers: merge_lifecycle_decision_required, handoff_state=merge_requested, merge_gate_status=qa_passed, and handoff_state=merged.

Run Control Lifecycle

operator-driven agent replay에는 하나의 lifecycle 이름을 쓰세요:

Schedule Run Control -> Execute Pending Run Control -> Record Agent Attempt

Run Control은 Studio run에 저장된 durable operator 명령입니다.
Scheduled Run Control은 Studio가 pendingRunControl을 영속화하고 operator_control:scheduled를 emit했음을 뜻합니다.
Execute Pending Run Control은 백그라운드 executor가 그 pending 명령을 소비해 Temporal-owned lifecycle에 진입함을 뜻합니다.
Agent Attempt는 현재 Temporal phase 아래 Agent Execution이 만든 CLI/browser/runtime 실행입니다.

dispatch queued, session control queued, retry background dispatch 같은 근사 동의어를 새 코드/테스트에서 피하세요. Portal과 Studio Admin은 둘 다 백그라운드 실행 시작 전에 scheduled run control을 영속화해야 합니다.

딜리버리 Proof

controller message: 다음 agent attempt로 운반되는 operator 또는 graph 지시.
delivery reference: 에이전트 작업이 수렴하는 곳을 증명하는 GitHub PR 또는 issue URL.
missing delivery reference blocker: 런타임 blocker github_issue_or_pr_link_missing.
project delivery evidence: issue, PR, report, DataHub lineage, 또는 browser 증거 표면에 붙은 durable proof.
handoff: 다른 에이전트로의 구조적 inbox 전달. handoff는 delivery reference가 아닙니다.

Merge Lifecycle Decision

merge lifecycle decision은 연결된 PR과 tester proof를 검토한 후 committer가 닫은 결정입니다. 정식 런타임 blocker는 merge_lifecycle_decision_required입니다.

committer는 두 가지 방법 중 하나로 결정을 닫을 수 있습니다:

handoff_state=merge_requested
merge_gate_status=qa_passed

또는:

handoff_state=merged

committer_merge_state_required는 retired wire field일 뿐입니다. 새 코드, 문서, 테스트, 프롬프트는 merge_lifecycle_decision_required를 써야 합니다.

기계적 Wall(Mechanical Walls)

Mechanical Wall은 에이전트 행동이 AgentSquad 의도에서 벗어나는 것을 감지해 특정 guardrail retry prompt나 tool 경로로 매핑하는 guardrail입니다. blocker가 아닙니다.

Planner wall: lane이 memory tool 계약을 선언했는데 에이전트가 쓰지 않았으면, memory-tool guardrail retry prompt로 retry.
Tester wall: PlaywrightGrid 같은 증거-가능 도구가 있는데 증거 attachment가 없으면, evidence-capture guardrail retry prompt로 retry.
Closer wall: DataHub 컨텍스트나 lineage 증거가 필요한데 없으면, lineage-publication guardrail retry prompt로 retry.
Committer wall: delivery reference가 있는데 merge lifecycle decision이 없으면, merge-decision guardrail retry prompt로 retry.
Delivery wall: 에이전트가 PR 커밋 없이 소유 worktree에 소스/설정 변경을 남기면, 같은 worktree를 retry하고 commit/push 또는 현재 파일 내용으로 만든 github_app_pr_handoff를 요구.

blocker는 에이전트나 런타임의 no-progress report입니다. wall은 blocker를 만들거나 clear할 수 있지만, wall 자체는 기계적 안내 시스템입니다. 제품 특화 마이그레이션 프롬프트는 작업을 고를 수 있으나, AgentSquad 딜리버리 어휘를 재정의해서는 안 됩니다.