trustay-agent-workflow 1.17.0

Trustay Agent Workflow CLI and managed agent workflow assets.

Trustay Agent Workflow

여러 AI 코딩 에이전트를, 대화 기억이 아니라 검증 가능한 evidence 위에서 함께 굴리세요.

문제. Claude Code, Codex, Gemini 같은 AI 코딩 에이전트를 여러 세션·여러 플랫폼에서 돌리다 보면 작업 맥락이 각 대화에 갇힙니다. "계획은 누가 세웠고, 검증은 했고, 리뷰에서 뭐가 나왔지?" 같은 결정은 채팅이 닫히면 사라지고, 에이전트 간 인계는 transcript 복붙에 의존합니다.

tsaw(Trustay Agent Workflow). 이 에이전트들을 대체하지 않고 그 위에 얹혀 작업을 조율하는 control plane입니다. 모든 작업이 프로젝트 안의 운영 계약, append-only evidence ledger, 파일 상태로 남기 때문에 — 어느 에이전트가 어느 세션에서 일하든 다음 행동과 그 근거가 남습니다.

한 번 설치한 뒤 프로젝트에서 tsaw init을 실행하면 AGENTS.md, .agents/, .work/가 준비됩니다. 이후 에이전트는 같은 계약 위에서 planning → build → verification → review → handoff를 이어 가고, 사람은 목표·제약·승인·피드백만 제공합니다.

핵심 가치는 다섯 가지입니다. 각각은 왜 tsaw인가에서 자세히 다룹니다.

• 🤝 멀티 에이전트·멀티 플랫폼 조율 — Claude로 계획하고 Codex로 구현하고 Gemini로 리뷰하는 흐름을, 채팅 복붙이 아니라 공유 evidence로 이어 줍니다.
• 🧾 Evidence 기반 거버넌스·감사 — 빌드·QA·리뷰 결정이 위변조를 감지할 수 있는 ledger에 봉인되어, 구현뿐 아니라 검증·리뷰·인계 누락까지 드러납니다.
• 💰 Context economy — 에이전트가 raw shell 출력 대신 bounded read 표면을 쓰게 해 토큰 낭비와 맥락 오염을 줄입니다.
• 🧭 Human decision surface — 사람은 CLI를 외우는 operator가 아니라, 정리된 결정 대기 목록만 보는 결정 제공자가 됩니다.
• 📦 Managed project contract — 프로젝트마다 흩어진 에이전트 계약을 하나의 관리형 구조로 설치·업데이트합니다.

최근 사용자 영향 변경은 CHANGELOG.md에서 확인할 수 있습니다.

목차

• tsaw는 어디에 있나
• 왜 tsaw인가
• 언제 쓰나
• 3분 시작
• 프로젝트에 생기는 것
• 두 가지 표면: 사람 vs 에이전트
• 첫 작업 흐름
• 기존 프로젝트에 도입하기
• 업데이트
• 더 알아보기

tsaw는 어디에 있나

flowchart LR
    person["사람<br/>목표 · 제약 · 승인 · 결정"] --> plane
    subgraph plane["tsaw — control plane"]
        direction TB
        c["운영 계약 · 검증 가능한 명령 표면"]
        e["append-only evidence ledger · task 상태"]
    end
    plane --> agents["AI 코딩 에이전트<br/>Claude Code · Codex · Gemini"]
    agents -->|코드 변경| repo["repository"]
    agents -.->|evidence · 산출물| plane
    plane -.->|다음 행동 · 근거| person

tsaw는 에이전트 CLI를 대체하지 않습니다. 사람의 결정과 에이전트의 실행 사이에 앉아 계약·상태·evidence를 관리하는 layer입니다. 에이전트는 평소대로 코드를 바꾸고, tsaw는 "지금 어디까지 됐고, 무엇이 증거로 남았고, 다음에 누가 무엇을 해야 하는지"를 책임집니다.

왜 tsaw인가

🤝 여러 에이전트가 서로를 놓치지 않는다

큰 작업은 보통 한 에이전트로 끝나지 않습니다. 계획은 Claude, 구현은 Codex, 리뷰는 Gemini가 더 나을 수 있습니다. 문제는 인계입니다. 보통은 한 대화의 transcript를 다음 에이전트에게 복붙하고, 받은 쪽은 "무엇이 이미 결정됐는지"를 다시 추론합니다.

tsaw는 세션을 canonical entrypoint로 두고, 참여 에이전트가 같은 typed slot(공유 evidence)을 읽게 합니다. planner가 끝내면 근거가 ledger에 남고, builder는 그 위에서 이어 갑니다. 채팅을 옮길 필요가 없습니다.

tsaw session orchestrate \
  --name login-session \
  --team experience-squad \
  --task-dir .work/tasks/T-001-login-flow \
  --agents planner-main:claude,builder-main:codex,verifier-main:codex,reviewer-main:gemini

# 세션의 canonical 상태(누가 다음 차례인지, 무엇이 막혔는지)
tsaw session status --name login-session

큰 요청은 에이전트 한 명에게 던지기 전에 작업 구조를 먼저 봅니다. tsaw squad plan이 자연어 요청을 팀 구성(squad), specialist persona, task slice, 병렬 실행 후보로 해석해 줍니다.

tsaw squad plan --request "관리자 백오피스에 권한 관리 API와 화면을 추가하고 이벤트 로깅까지 붙여줘"

API·화면·로깅처럼 독립적인 concern이 보이면 여러 task slice와 병렬 세션(session orchestrate --jobs N) 후보를 제안하므로, "전부 한 에이전트가 순차로" 대신 "나눠서 동시에"가 기본 선택지가 됩니다.

작업이 더 커져서 수십 개의 독립 job prompt를 반복 가능한 패턴으로 조율해야 하면 dynamic workflow를 사용합니다. workflow spec은 .agents/workflows/*.yaml에 저장되고, 실행 상태·job prompt·agent 결과는 .work/workflows/<run>/에 남습니다.

tsaw workflow dynamic list
tsaw workflow dynamic propose --request "src/routes 권한 검사를 여러 관점에서 감사해줘"

tsaw workflow dynamic run \
  codebase-audit \
  --name audit-main \
  --agents researcher=alice:codex:researcher,reviewer=bob:codex:reviewer

tsaw workflow dynamic run deep-research \
  --name node-permissions \
  --arg question="Node.js v20과 v22 permission model 차이"

tsaw workflow dynamic status --name audit-main

# agent가 다음 job을 claim하고 결과를 제출하면 dependent phase가 열린다
tsaw workflow dynamic next --name audit-main --agent researcher
tsaw workflow dynamic run-job --name audit-main --agent researcher -- codex exec --prompt-file {prompt}
tsaw workflow dynamic submit --name audit-main --job explore-001 --result-file .work/workflows/audit-main/results/explore-001.md --usage-file usage.json
tsaw workflow dynamic usage --name audit-main

# cockpit 기본 overview에서도 active workflow와 task 요약을 함께 본다
tsaw cockpit
tsaw cockpit --view workflows

session orchestrate가 실제 task progression을 역할별 agent에게 넘기는 경로라면, workflow dynamic은 많은 job의 계획·prompt·중간 상태를 대화 context 밖의 durable runtime state에 두는 경로입니다. agent는 생성된 prompt를 기준으로 실제 조사·수정·검증을 수행하고, submit 결과를 기준으로 다음 phase가 열립니다. 실패한 job은 retry, 사람 판단이 필요한 job은 escalate, 실행 중 새 follow-up이 필요하면 replan으로 run-local phase를 추가합니다. 실행 중인 dynamic workflow는 기본 tsaw cockpit의 Active Workflows 패널에 같이 나타나며, 전체 run 목록·job 진행률·token/cost 합계는 tsaw cockpit --view workflows에서 확인합니다. .agents/runtime.yaml에서 dynamic workflow를 끄거나, project-wide max concurrency/job cap과 실행 전 승인 요구를 설정할 수 있습니다. 외부 agent/스크립트를 한 job 단위로 바로 실행해야 하면 run-job이 {prompt} placeholder와 TSAW_WORKFLOW_* 환경변수를 주입하고 stdout/stderr/exit code를 result artifact와 run metrics에 남깁니다. agent wrapper가 token/cost 값을 알 수 있으면 --usage key=value 또는 --usage-file usage.json으로 함께 제출하고, usage로 run 전체의 token/cost 합계를 확인합니다.

🧾 결정이 채팅과 함께 사라지지 않는다

"이거 테스트는 했어?"라는 질문의 답이 50개 메시지 뒤로 사라지면 안 됩니다. tsaw에서 빌드 증거, QA finding, 리뷰 verdict 같은 결정은 append-only evidence ledger에 SHA256으로 봉인됩니다. 누가(역할/persona), 언제, 무엇을 결정했는지가 시간순으로 남고, row를 몰래 고치면 검증 단계에서 잡힙니다.

# 한 task의 evidence를 시간순으로 본다
tsaw evidence list --task .work/tasks/T-001-login-flow

# 체인 끊김·위변조 여부 검증
tsaw evidence verify --task-dir .work/tasks/T-001-login-flow

여기서 한 걸음 더 나아가, hard gate가 프로세스를 강제합니다. squad 구성에 따라 필요한 typed artifact(po-decision, design-spec, build-evidence, qa-finding, review-verdict)가 ledger에 없으면 다음 단계로 못 넘어갑니다. 즉, QA 증거 없이 "다 됐다"며 리뷰로 건너뛸 수 없습니다. 잘못된 결정을 되돌릴 때도 기존 기록을 수정하지 않고 후속 compensating entry를 남겨 audit trail을 유지합니다.

💰 토큰은 구현에 쓰고, 탐색에 낭비하지 않는다

에이전트가 cat, grep, git diff 출력을 통째로 대화에 붙이면 context window가 한 번의 탐색으로 오염됩니다. 이후 모든 추론이 그 잡음 위에서 일어나고, 같은 파일을 다시 읽을 때마다 비용이 반복됩니다.

tsaw는 read-only 탐색을 bounded 표면으로 바꿉니다. 모든 출력에 line/byte/row limit과 truncation metadata가 붙어, 에이전트는 "잘렸는지, 더 읽어야 하는지"를 알면서 딱 필요한 만큼만 가져갑니다.

# cat 대신 — 처음 120줄만, 잘림 여부 표시
tsaw inspect read src/auth/session.py --head 120

# grep 대신 — 결과 수 제한 + truncation metadata
tsaw search grep "session_token" src --limit 100

# 목표 기반 컨텍스트 묶음 — 토큰 예산 안에서 관련 파일 조각만
tsaw search context --goal "로그인 실패 처리 흐름" --budget-tokens 8000

# 반복 탐색용 로컬 lexical index (외부 embedding provider 불필요)
tsaw index build .

절감 효과는 측정 가능합니다. tsaw metrics show --accounting이 bounded 표면 사용량과 context budget advisory를 보여 주고, advisory가 attention이면 에이전트가 다음 handoff 전에 context를 줄입니다. index는 .work/state/의 로컬 SQLite 캐시라서 코드가 외부로 나가지 않습니다.

🧭 사람은 CLI를 외우지 않는다

멀티 에이전트 운영에서 사람이 모든 명령과 상태를 추적하는 operator가 되면, 에이전트를 늘릴수록 사람이 병목이 됩니다. tsaw는 사람의 역할을 결정 제공자로 좁힙니다. 사람이 보는 표면은 "지금 결정할 일"만 보여 줍니다.

# 전체 러닝 상태 overview
tsaw cockpit
# 지금 해야 할 일 한 줄
tsaw cockpit --next-action
# 여러 task에 걸친 사람 결정 대기 항목
tsaw inbox
# 진단 jargon 없이, 사람이 풀어야 할 blocker만
tsaw doctor --human

사람이 결정을 내리면 그 결정은 말로 사라지지 않고 typed artifact로 ledger에 서명·봉인됩니다.

tsaw human review-verdict --task-dir .work/tasks/T-001-login-flow --verdict approve
tsaw human po-decision --task-dir .work/tasks/T-001-login-flow \
  --goal "이메일 로그인 안정화" --scope-boundary "SSO는 이번 범위에서 제외"

approve 하나가 다음 단계 게이트를 풀고, changes 하나가 builder 단계를 다시 엽니다. 사람의 개입 지점이 명확하니, 그 외 시간에는 에이전트가 계약대로 진행합니다.

📦 프로젝트가 10개여도 계약은 하나

에이전트를 쓰는 프로젝트가 늘면 AGENTS.md, CLAUDE.md, .cursorrules, vendor별 설정이 제각각 자라고, 어느 프로젝트의 계약이 최신인지 아무도 모르게 됩니다.

tsaw init 한 번이 AGENTS.md, .agents/(rules·guides·policies·teams·skills), .work/를 일관된 관리형 구조로 설치합니다. vendor 파일(CLAUDE.md, GEMINI.md)은 AGENTS.md를 가리키는 alias로 단일화되어, 어떤 에이전트 CLI를 열든 같은 계약을 읽습니다.

# 새 프로젝트에 관리형 계약 설치
tsaw init --vendor all
# 기존 계약을 보존하며 흡수
tsaw init --vendor all --preserve-local
# 관리형 자산 변경 미리 보기 후 적용 (백업·잠금 포함)
tsaw update --diff
tsaw update --apply

설치와 업데이트 모두 안전장치가 기본입니다. 기존 로컬 계약은 덮어쓰지 않고 합성하며, 적용 전 diff preview·자동 백업·동시 실행 잠금을 거치고, 프로젝트가 직접 채우는 config(registry/commands.yaml, runtime.yaml)는 건드리지 않습니다. 자세한 절차는 기존 프로젝트에 도입하기와 업데이트를 참고하세요.

다섯 가치가 만드는 결과: 세션 연속성

위 다섯 가지가 갖춰지면 자연히 따라오는 것이 있습니다 — 어느 에이전트가 어느 세션·플랫폼에서 일하든, 다음 행동과 그 근거가 task 상태·runtime state·evidence ledger에 남습니다. 대화가 닫혀도 작업은 끊기지 않고, 새 세션이 tsaw session status 한 번으로 이어받습니다.

언제 쓰나

잘 맞는 경우

• 여러 AI 에이전트·여러 플랫폼·여러 대화 세션이 같은 repository를 다룬다. (예: 에이전트가 3명 이상이고 서로의 진행 상황을 놓친다)
• QA·리뷰 결정이 말로만 보고되고 사라지는 대신, audit 가능한 evidence로 남아야 한다.
• 계획·구현·검증·리뷰를 분리하고 각 단계의 산출물을 남기고 싶다.
• 사람은 방향과 판단에 집중하고, 에이전트가 정해진 계약대로 작업을 진행하게 하고 싶다.
• 에이전트가 큰 shell 출력으로 context를 낭비하는 일을 줄이고 싶다.
• 프로젝트마다 흩어진 AGENTS.md, .agents/, vendor 설정을 하나의 관리형 구조로 표준화하고 싶다.

과할 수 있는 경우

• 단발성 스크립트 실행이나 한 사람이 한 번에 끝내는 작은 수정이다.
• task bundle·evidence·review gate 없이 빠르게 실험만 하면 된다.

이 경우에는 AGENTS.md만 참고하고 .work/tasks/*까지 만들지 않아도 됩니다.

3분 시작

설치부터 첫 요청, 사람 결정, 일상 루프까지 따라가는 전체 안내는 docs/getting-started.md에 있습니다.

trustay-agent-workflow 패키지로 tsaw를 설치합니다.

pipx install trustay-agent-workflow
tsaw --version

선행 조건: Python 3.11+와 pipx. tsaw 자체는 계정 없이 로컬에서 동작합니다. 멀티 에이전트 조율은 사용하는 에이전트 CLI(Claude Code·Codex·Gemini)를 그대로 부르므로, 해당 CLI가 설치·로그인되어 있어야 합니다.

사용할 프로젝트 루트에서 초기화하고 점검합니다. (이미 AGENTS.md나 .agents/가 있는 repo라면 먼저 기존 프로젝트에 도입하기를 보세요.)

cd /path/to/your-project
tsaw init --vendor all
tsaw validate assets
tsaw doctor

초기 context 표면을 더 작게 시작하려면 tsaw init --vendor all --profile minimal(optional persona catalog 제외)을 쓸 수 있습니다. install profile은 standard(기본), minimal, context-economy, security-review 네 가지이며, 자세한 차이는 docs/commands.md를 참고하세요.

이제 에이전트에게 자연어로 목표와 제약을 전달합니다.

사용자 인증 기능을 구현해줘.
로그인, 회원가입, 검증, 리뷰 산출물까지 같은 task bundle에서 이어가줘.
기존 세션 저장 방식은 바꾸지 말고, 테스트와 handoff도 남겨줘.

에이전트가 작업하는 동안 사람은 "다음에 결정할 일"만 확인하면 됩니다.

# 지금 해야 할 일 한 줄
tsaw cockpit --next-action
# 여러 task의 사람 결정 대기 항목
tsaw inbox
# 봉인된 결정 기록 확인 (--task로 task 필터)
tsaw evidence list --task .work/tasks/T-001-login-flow

설치와 업데이트를 빼면, task progression 명령은 보통 사람이 직접 치지 않습니다. 에이전트가 AGENTS.md와 .work/ 상태를 읽고 필요한 tsaw 명령을 내부적으로 선택합니다.

프로젝트에 생기는 것

tsaw init --vendor all은 보통 아래 구조를 만듭니다. (✓ 커밋 / ✗ ignore / ◆ 프로젝트 소유 config)

your-project/
├── AGENTS.md                      # 프로젝트 대표 운영 계약            ✓
├── CLAUDE.md → AGENTS.md          # vendor 호환 alias                  ✓
├── GEMINI.md → AGENTS.md          # vendor 호환 alias                  ✓
├── .agents/                       # rules·guides·policies·teams·skills·workflows ✓
│   ├── registry/commands.yaml     # 명령 프로필 (프로젝트가 채움)      ◆
│   ├── workflows/                 # 재사용 dynamic workflow spec       ✓
│   ├── runtime.yaml               # runtime 보존값 (프로젝트가 채움)   ◆
│   └── .backups/  .update.lock    # update 백업·잠금                   ✗
├── .work/                         # task bundle·ADR·evidence·runtime
│   ├── tasks/  decisions/  patterns.md  …                             ✓
│   ├── workflows/                 # dynamic workflow run 산출물        ✗
│   └── state/runtime.sqlite3*     # 로컬 생성 runtime 캐시            ✗
└── .claude/  .gemini/             # vendor별 노출 표면(symlink)        ✓

경로	역할
AGENTS.md	프로젝트의 대표 운영 계약
.agents/	rules, guides, policies, loops, templates, teams, registry, skills, workflows
.work/	task bundle, ADR, runtime state, evidence ledger, dynamic workflow runs
CLAUDE.md, GEMINI.md	vendor 호환 alias
.claude/, .gemini/	vendor별 노출 표면

.gitignore에는 로컬 생성물만 빼 두는 편이 안전합니다. runtime.sqlite3는 source of truth가 아니라 재생성 가능한 runtime cache이며, 없어지면 tsaw doctor/tsaw runtime repair가 다시 준비합니다.

.agents/.backups/
.agents/.update.lock
.work/state/runtime.sqlite3*
.work/workflows/

특정 환경만 쓴다면 --vendor codex, --vendor claude, --vendor gemini처럼 좁게 시작할 수 있습니다. 여러 에이전트 환경을 함께 쓸 가능성이 있으면 --vendor all이 무난합니다.

두 가지 표면: 사람 vs 에이전트

tsaw의 명령은 두 갈래입니다. 사람은 결정에 필요한 것만 보고(Human decision surface), 에이전트는 bounded read로 context를 아낍니다(Context economy).

	사람 (결정자)	에이전트 (실행자)
목적	다음에 결정할 일 파악	토큰을 아끼며 맥락 수집
먼저 보는 것	tsaw cockpit --next-action, tsaw inbox, tsaw what-next, tsaw doctor --human	tsaw inspect files ., tsaw search grep auth src --limit 100, tsaw index build .
결정을 남길 때	tsaw human review-verdict --task-dir .work/tasks/T-001-login-flow --verdict approve (ledger에 서명)	typed artifact를 evidence로 append

전체 명령 레퍼런스는 docs/commands.md, 옵션 세부는 tsaw <subcommand> --help로 확인하는 편이 가장 빠릅니다.

첫 작업 흐름

flowchart LR
    person["사람<br/>목표·제약·승인·피드백"] -->|요청| plan
    subgraph agent["Agent (tsaw 계약 위 자율 실행)"]
        plan[planning] --> build
        build --> verify
        verify --> review
        review --> handoff
        verify -.->|replan| plan
        review -.->|findings| build
    end
    handoff -->|evidence·산출물| person

1. 사용자가 목표, 범위, 깨지면 안 되는 조건, 완료 기준을 말한다.
2. 에이전트가 AGENTS.md와 현재 .work/ 상태를 읽는다.
3. 에이전트가 tsaw task new "<title>"로 task bundle을 만들거나 기존 task를 이어 간다.
4. 에이전트가 brief.md, design.md, plan.md, plan.yaml을 정리한다.
5. 구현이 필요하면 dedicated git worktree에서 변경한다.
6. 검증·리뷰·인계 결과를 verification.md, review.md, handoff.md에 남기고 evidence를 확인한다.

각 단계의 산출물은 append-only evidence ledger에 남아 audit과 다음 세션 재개의 근거가 됩니다. 좋은 요청은 무엇을 바꿀지 / 수정 범위 / 깨지면 안 되는 것 / 완료 판단 기준 / (가능하면) 검증 명령을 포함하면 충분합니다.

기존 프로젝트에 도입하기

이미 AGENTS.md, CLAUDE.md, GEMINI.md, .agents/가 있다면 기본 tsaw init은 충돌을 피하려고 중단합니다. 가장 안전한 도입은 보통 --preserve-local입니다.

tsaw init --vendor all --preserve-local

기존 계약과 로컬 자산을 유지하면서 tsaw 관리형 구조를 합성합니다. 어떤 계약을 대표로 삼을지 명시해야 하면 --contract-source claude|gemini를 함께 씁니다. 관리형 계약 원문은 .agents/contracts/tsaw-managed.md에 두고, 같은 경로의 기존 .agents/*는 preserved path로 유지합니다. 관리형 경로를 교체해도 되는 경우에만 --force를 씁니다.

업데이트

패키지 사용자는 CLI를 pipx로 갱신하고, 각 프로젝트의 관리형 자산은 별도로 preview·적용합니다.

pipx upgrade trustay-agent-workflow

cd /path/to/your-project
# 적용 전 변경 확인
tsaw update --diff
# 충돌한 로컬 경로를 보존하며 적용 (충돌이 없으면 --resolve 생략 가능)
tsaw update --apply --resolve preserve-local

터미널에서 직접 tsaw update --apply를 실행했다가 충돌을 만나면, 중단하는 대신 충돌 목록과 함께 preserve-local/theirs/skip/quit을 대화형으로 선택할 수 있습니다. CI나 파이프 환경에서는 기존처럼 안내와 함께 중단합니다.

.agents/registry/commands.yaml과 .agents/runtime.yaml은 프로젝트가 채워 쓰는 config입니다. 직접 편집해도 tsaw update가 덮어쓰지 않습니다. 자주 쓰는 update 명령은 docs/commands.md에 정리돼 있습니다.

더 알아보기

• docs/getting-started.md: 설치부터 첫 요청·결정·일상 루프까지 따라가는 시작 가이드
• docs/commands.md: 전체 명령 레퍼런스(사람·에이전트 표면, 자주 쓰는 명령, update, skill 평가)
• docs/cockpit.md: cockpit view, interactive mode, scripting mode
• AGENTS.md: 에이전트·maintainer 운영 계약
• CONTRIBUTING.md: 이 저장소(tsaw source repo)에 기여하거나 CLI·자산을 직접 수정할 때
• CHANGELOG.md: 사용자 영향이 있는 릴리즈 변경 이력
• assets/agents/guides/context-management.md: session·mailbox·signal 기반 협업 가이드
• 멀티 플랫폼 bridge 예시: codex · claude · gemini

전체 옵션은 언제든 tsaw <subcommand> --help로 확인할 수 있습니다.