trustay-agent-workflow 1.15.0

Trustay Agent Workflow CLI and managed agent workflow assets.

Trustay Agent Workflow

tsaw는 AI agent 작업을 대화 기억에만 맡기지 않고, 프로젝트 안의 계약, 실행 상태, evidence, 검증 가능한 명령 표면으로 운영하게 해 주는 agent workflow control plane입니다.

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

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

목차

• 왜 쓰는가
• 언제 쓰는가
• 3분 시작
• 프로젝트에 생기는 것
• 사람이 보는 화면
• Agent가 쓰는 표면
• 설치 방식과 기존 clone 설치 마이그레이션
• 자연어 squad planning
• 첫 작업 흐름
• 기존 프로젝트에 도입하기
• 업데이트
• 자주 쓰는 명령
• 문서 지도
• 이 저장소를 직접 수정하는 maintainer라면

왜 쓰는가

tsaw의 가치는 "다음 세션에서 이어 하기"에만 있지 않습니다. 현재 버전의 핵심 가치는 아래 다섯 가지입니다.

• Context economy: agent가 cat, grep, git diff 출력 전체를 대화에 붙여 넣지 않고 tsaw inspect read README.md --head 120, tsaw search grep auth src --limit 100, tsaw index build .처럼 제한된 context 표면을 사용합니다. 토큰 낭비와 맥락 오염을 줄입니다.
• Human decision surface: 사람은 모든 CLI를 직접 조작하는 operator가 아니라 decision provider가 됩니다. tsaw inbox, tsaw what-next, tsaw doctor --human, tsaw cockpit --next-action이 사람이 결정해야 할 일을 보여줍니다.
• Evidence-backed governance: build evidence, QA finding, review verdict 같은 산출물이 append-only ledger에 남습니다. 구현 완료만이 아니라 검증, 리뷰, 인계 누락도 드러납니다.
• Squad and parallel planning: tsaw squad plan이 자연어 요청을 team, specialist persona, task slice, 병렬 실행 후보로 바꿉니다. 큰 요청을 agent 한 명에게 던지기 전에 작업 구조를 먼저 봅니다.
• Managed project contract: AGENTS.md, .agents/, .work/를 프로젝트마다 일관되게 설치하고 업데이트합니다. 기존 로컬 agent 계약은 --preserve-local로 보존하며 흡수할 수 있습니다.

세션 연속성은 이 다섯 가치 위에서 따라오는 결과입니다. 어느 agent가 어느 세션에서 작업하든, 다음 행동과 근거가 파일, runtime state, evidence에 남습니다.

언제 쓰는가

잘 맞는 경우:

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

과할 수 있는 경우:

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

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

3분 시작

일반 사용자는 trustay-agent-workflow 패키지로 tsaw를 설치합니다.

pipx install trustay-agent-workflow
tsaw --version

사용할 프로젝트 루트에서 초기화합니다.

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

초기 context 표면을 더 작게 시작하려면 optional persona catalog를 제외하는 tsaw init --vendor all --profile minimal을 사용할 수 있습니다.

기본 제공 install profile은 아래와 같습니다.

Profile	용도
standard	전체 managed asset set을 설치하는 기본값입니다. 기존 tsaw init 동작과 같습니다.
minimal	optional .agents/personas/** catalog를 제외하고 core workflow 자산만 설치합니다.
context-economy	minimal과 같은 작은 context 표면을 선택하는 의도 중심 alias입니다.
security-review	security review 세션에서 명시적으로 선택할 수 있는 full asset profile입니다. 현재 asset set은 standard와 같습니다.

초기화가 끝나면 agent에게 자연어로 목표와 제약을 전달합니다.

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

처음에는 아래 명령만 알아도 충분합니다.

하고 싶은 일	명령
프로젝트에 계약과 자산 설치	tsaw init --vendor all
작은 설치 profile로 시작	tsaw init --vendor all --profile minimal
자산 구조 확인	tsaw validate assets
지금 해야 할 일 한 줄 확인	tsaw cockpit --next-action
여러 task의 사람 액션 확인	tsaw inbox
관리형 자산 업데이트 미리 보기	tsaw update --diff
관리형 자산 profile 전환	tsaw update --profile minimal --diff
task readiness 내보내기	tsaw status export .work/tasks/T-100 --format markdown
context budget advisory 확인	tsaw metrics show --accounting

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

프로젝트에 생기는 것

tsaw init --vendor all은 보통 아래 구조를 만듭니다.

your-project/
├── AGENTS.md
├── CLAUDE.md -> AGENTS.md
├── GEMINI.md -> AGENTS.md
├── .agents/
├── .work/
├── .claude/
└── .gemini/

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

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

사람이 보는 화면

사람이 매번 low-level command를 조작하지 않도록, tsaw는 decision 중심의 읽기 표면을 제공합니다.

상황	먼저 볼 명령
지금 할 일을 한 줄로 보고 싶다	tsaw cockpit --next-action
여러 task에서 사람 결정을 기다리는 항목을 보고 싶다	tsaw inbox
gate가 왜 막혔고 어떤 artifact가 필요한지 알고 싶다	tsaw what-next
프로젝트 health를 사람 친화적으로 보고 싶다	tsaw doctor --human
session의 canonical 상태가 필요하다	tsaw session status --name <session>

사람이 직접 결정을 ledger에 남겨야 할 때는 typed artifact 명령을 씁니다.

tsaw artifact list
tsaw artifact template review-verdict > rv.json
tsaw human review-verdict --task-dir .work/tasks/T-001-login-flow --file rv.json
tsaw evidence verify --task-dir .work/tasks/T-001-login-flow

typed artifact는 po-decision, design-spec, build-evidence, qa-finding, review-verdict, replan-request처럼 역할이 분명한 evidence입니다. 잘못된 결정을 되돌려야 할 때도 기존 row를 수정하지 않고 후속 compensating entry를 남기는 방식으로 audit trail을 유지합니다.

Agent가 쓰는 표면

agent는 일반 shell probe 대신 bounded read-only 표면을 우선 사용합니다.

기존 probe	권장 tsaw 표면
파일 목록	tsaw inspect files .
tree 확인	tsaw inspect tree . --max-depth 3
파일 일부 읽기	tsaw inspect read README.md --head 120
문자열 검색	tsaw search grep auth src --limit 100
목표 기반 context pack	tsaw search context --goal "auth flow" --budget-tokens 8000
git 상태	tsaw inspect git status
git diff	tsaw inspect git diff
반복 context lookup	tsaw index build .
절약 효과 확인	tsaw metrics show --accounting

tsaw index build .는 remote embedding provider나 SaaS vector DB를 사용하지 않습니다. .work/state/runtime.sqlite3 아래에 local lexical chunk index를 저장하며, 이 파일은 source of truth가 아니라 재생성 가능한 runtime cache입니다.

설치 방식과 기존 clone 설치 마이그레이션

tsaw 1.12.0부터 일반 사용자 설치 경로는 pipx install trustay-agent-workflow입니다. PyPI distribution 이름은 trustay-agent-workflow이고, 실행 명령과 프로젝트 안의 운영 표면은 계속 tsaw입니다.

source repository를 clone해서 ./install.sh를 실행하는 경로는 maintainer나 contributor가 CLI와 assets/ 원본을 함께 수정할 때 사용합니다. 일반 사용자는 clone checkout을 유지할 필요 없이 pipx로 설치한 tsaw로 tsaw init, tsaw update, tsaw doctor를 실행하면 됩니다.

기존에 git clone 후 ./install.sh로 설치했다면 보통 아래처럼 ~/.local/bin/tsaw가 clone 안의 bin/tsaw를 가리키는 symlink입니다.

command -v tsaw
readlink ~/.local/bin/tsaw

이 상태에서 PyPI 배포가 새로 올라와도 pipx upgrade trustay-agent-workflow는 clone 기반 tsaw를 갱신하지 않습니다. clone 설치는 git pull로 갱신하고, pipx 설치는 pipx upgrade로 갱신하는 별도 경로입니다.

일반 사용자로 전환하려면 clone symlink를 제거한 뒤 pipx 패키지를 설치합니다.

unlink ~/.local/bin/tsaw
pipx install trustay-agent-workflow
tsaw --version

이 전환은 실행 파일의 공급원만 바꿉니다. 각 프로젝트 안의 AGENTS.md, .agents/, .work/와 evidence ledger는 삭제되거나 자동 변경되지 않습니다. 전환 후에도 각 initialized project에서 관리형 자산 변경을 별도로 preview하고 적용합니다.

cd /path/to/your-project
tsaw doctor
tsaw update --diff
tsaw update --apply --resolve preserve-local

source repository를 계속 수정하는 maintainer는 clone 설치를 유지할 수 있습니다.

cd /path/to/agent-workflow
git pull
./install.sh
tsaw --version

한 machine에서 clone 설치와 pipx 설치를 동시에 운영하면 tsaw가 어느 경로에서 실행되는지 헷갈릴 수 있습니다. 일반 사용자는 pipx, source contributor는 clone + ./install.sh 중 하나를 선택하는 편이 안전합니다.

자연어 squad planning

tsaw는 자연어 요청을 squad와 task slice로 해석하는 표면을 제공합니다. 큰 요청을 실행하기 전에 어떤 팀 구성이 맞는지, 어떤 작업이 병렬화될 수 있는지 먼저 볼 수 있습니다.

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

새 task를 만들 때 request를 seed하고 squad를 자동 추론할 수도 있습니다.

tsaw task new "permission management" \
  --request "관리자 권한 관리 API와 화면을 추가하고 이벤트 로깅까지 붙여줘" \
  --auto-squad

이때 생성되는 squad.yaml은 task-local effective squad로 읽히며 hard gate와 tsaw session status에 반영됩니다. 여러 같은 역할의 participant가 있으면 tsaw session orchestrate가 team의 parallel_readers를 기본 dispatch 한도로 사용해 task handoff를 분산합니다.

직접 multi-agent 세션을 시작해야 한다면 canonical entrypoint는 tsaw session orchestrate입니다.

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

tsaw workflow collaborate는 같은 runtime을 감싼 convenience wrapper입니다. 세션의 정식 상태 표면은 tsaw session status --name <session>입니다.

첫 작업 흐름

일반적인 작업은 아래처럼 진행됩니다.

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

planning, build, verify, review, handoff 각 단계의 산출물은 append-only evidence ledger에 남아 audit과 다음 세션 재개의 근거가 됩니다.

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

좋은 요청은 아래 정보를 포함하면 충분합니다.

• 무엇을 바꾸고 싶은지
• 수정 범위나 관련 파일
• 깨지면 안 되는 것
• 완료 판단 기준
• 가능하면 검증 명령

기존 프로젝트에 도입하기

이미 AGENTS.md, CLAUDE.md, GEMINI.md, .agents/가 있다면 기본 tsaw init은 충돌을 피하기 위해 중단합니다. 가장 안전한 도입 방식은 보통 아래입니다.

tsaw init --vendor all --preserve-local

이 옵션은 기존 계약과 로컬 자산을 유지하면서 tsaw 관리형 구조를 합성합니다. AGENTS.md와 CLAUDE.md 또는 GEMINI.md가 함께 있고 어떤 계약을 대표로 삼을지 명시해야 한다면 --contract-source를 함께 사용합니다.

tsaw init --vendor all --preserve-local --contract-source claude

• 기존 AGENTS.md는 root contract의 local section으로 유지합니다.
• AGENTS.md가 없고 CLAUDE.md나 GEMINI.md만 있으면 AGENTS.md로 승격합니다.
• --contract-source claude|gemini을 지정하면 선택한 vendor 계약 내용을 root AGENTS.md로 승격하고, 선택되지 않은 divergent 계약은 legacy contract로 보존합니다. 기본값 auto는 기존처럼 AGENTS.md, CLAUDE.md, GEMINI.md 순서로 선택합니다.
• 관리형 계약 원문은 .agents/contracts/tsaw-managed.md에 둡니다.
• 같은 경로의 기존 .agents/* 파일은 preserved path로 유지합니다.
• 기존 .claude/rules, .claude/skills, .gemini/rules, .gemini/skills 같은 vendor-local 자산은 .agents/* canonical path로 흡수하고, 승격된 AGENTS.md 안의 해당 path도 함께 정규화합니다.
• 로컬 .agents/skills/* 디렉터리가 있으면 .agents/registry/skills.yaml에도 자동 등록합니다.
• CLAUDE.md, GEMINI.md는 최종적으로 AGENTS.md alias로 정규화합니다.

관리형 경로를 교체해도 되는 경우에만 --force를 사용합니다.

tsaw init --vendor all --force

업데이트

패키지로 설치한 사용자는 pipx upgrade trustay-agent-workflow로 CLI를 갱신합니다.

pipx upgrade trustay-agent-workflow
tsaw --version

source repository를 직접 다루는 maintainer는 기존처럼 source checkout을 갱신할 수 있습니다. 이 경로는 pipx 패키지를 갱신하지 않고, checkout의 bin/tsaw를 계속 사용합니다.

cd /path/to/agent-workflow
git pull
./install.sh
tsaw --version

각 initialized project에 복사된 .agents/* 관리형 자산은 별도로 preview하고 적용합니다.

cd /path/to/your-project
tsaw doctor
tsaw update --diff
tsaw update --apply --resolve preserve-local

자주 쓰는 update 명령:

명령	용도
tsaw update --diff	적용 전 변경 확인
tsaw update --apply	충돌이 없을 때 관리형 자산 적용
tsaw update --apply --resolve preserve-local	충돌한 로컬 경로를 보존하며 적용
tsaw update --show-preserved-diff	preserved path의 upstream 변경 확인
tsaw update --rollback	가장 최근 update 백업으로 복원

프로젝트 소유 config

.agents/registry/commands.yaml(명령 프로필)과 .agents/runtime.yaml(런타임 보존 값)은 프로젝트가 채워 쓰는 config 템플릿입니다. 이 두 파일을 직접 편집해도 tsaw update가 conflict로 막거나 덮어쓰지 않습니다. 비어 있을 때만 새로 만들고, 이후에는 프로젝트 소유로 둡니다.

1.11 이전 버전에서 올라온 프로젝트는 새로 추가된 .agents/runtime.yaml이 없을 수 있는데, tsaw doctor 한 번이면 자동으로 생성됩니다. 나머지 관리형 자산 내용 갱신은 계속 tsaw update --apply로 확인하고 적용합니다.

프로젝트 루트 .gitignore에는 아래 경로를 두는 편이 안전합니다.

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

runtime.sqlite3, runtime.sqlite3-wal, runtime.sqlite3-shm는 로컬 생성 runtime 상태입니다. 없어지면 tsaw doctor, tsaw validate assets, tsaw runtime backend show, tsaw runtime repair가 다시 준비할 수 있습니다.

장시간 세션이나 오래 잡고 있는 task가 많다면 .agents/runtime.yaml에서 task_lock_ttl_hours와 session_retention_days를 양의 정수로 조정합니다. 현재 effective 값과 출처는 tsaw runtime backend show에서 확인합니다.

자주 쓰는 명령

명령	용도
tsaw init --vendor all	프로젝트에 계약, 자산, runtime state 초기화
tsaw validate assets	초기화된 자산 구조 검증
tsaw validate platforms	platform registry 검증
tsaw validate command-profiles	문서와 command profile drift 검증
tsaw doctor	호환성, drift, runtime health 점검
tsaw doctor --human	사람이 바로 처리할 action 중심으로 진단
tsaw cockpit --next-action	현재 workflow stage 한 줄 출력
tsaw cockpit --format markdown --interactive off	agent 대화 삽입용 상태 출력
tsaw inbox	여러 task의 pending human action 조회
tsaw what-next	gate block 이후 다음 action 설명
tsaw artifact list	typed artifact 목록 확인
tsaw human review-verdict --task-dir .work/tasks/T-001-login-flow --verdict approve	사람 review 결정을 ledger에 기록
tsaw evidence verify --task-dir .work/tasks/T-001-login-flow	evidence ledger 무결성 검증
tsaw evidence replay-failed	append 실패 저널 재시도
tsaw squad plan --request "..."	자연어 요청을 team, persona, task slice로 해석
tsaw squad adjust --task-dir .work/tasks/T-001-login-flow --add qa	task-local squad 조정
tsaw task new "login flow"	다음 T-NNN ID로 task bundle 생성
tsaw task next-id	다음 자동 task ID 확인
tsaw status workflow-stage .work/tasks/T-001-login-flow	다음 stage와 workspace preflight 확인
tsaw workspace show --task-dir .work/tasks/T-001-login-flow --owner codex	builder workspace provenance 확인
tsaw workflow run feature-team --owner codex	agent-first happy path wrapper
tsaw session orchestrate --name login-session --team experience-squad --agents planner-main:claude,builder-main:codex	canonical session-first 협업 시작
tsaw session status --name login-session	session orchestration 상태 확인
tsaw platform list	지원 platform 목록 확인
tsaw platform show codex	특정 platform capability 확인
tsaw platform audit	platform capability gap과 fallback 확인
tsaw command suggest cat README.md	stale 또는 shell-style command의 대체 표면 확인
tsaw metrics show --accounting	context economy와 runtime metric 확인
tsaw skill eval --skill writing-plans --split selection	skill을 eval rubric으로 결정론 채점
tsaw skill optimize --skill writing-plans --dry-run	eval→reflection→gate 미리보기(SKILL.md 무변경)

자세한 옵션은 tsaw <subcommand> --help로 확인하는 편이 가장 빠릅니다.

skill 평가/개선 (credential-free)

tsaw skill 명령군은 skill 문서를 결정론적으로 평가하고 안전하게 개선하는 워크플로다. 외부 API key가 필요 없고 LLM을 호출하지 않는다.

1. tsaw skill eval: skill의 evals/evals.json을 hard/soft rubric으로 채점한다. 채점 대상은 SKILL.md가 아니라 그 skill을 따른 산출물이 계약을 지키는지다.
2. tsaw skill reflect: 실패/성공을 분리한 reflection 패킷을 만든다. 이걸 보고 사람/agent가 heading-anchored bounded patch(candidate.patch)를 작성한다.
3. tsaw skill gate: held-out selection split에서 current vs candidate를 비교해 개선이 확인될 때만 accept한다(동률은 reject).
4. tsaw skill apply: gate가 accept한 candidate만 반영한다. 자기수정이 아니라 사람이 검토 가능한 gate를 거친 변경만 적용한다.

run 출력과 evidence는 .work/skill-runs/와 evidence ledger에 남아 감사할 수 있다.

문서 지도

• README.md: 사용자 온보딩과 제품 사용 설명
• AGENTS.md: source repository를 다루는 maintainer와 agent 운영 계약
• CHANGELOG.md: 사용자 영향이 있는 릴리즈 변경 이력
• docs/cockpit.md: cockpit view, interactive mode, scripting mode
• assets/agents/guides/context-management.md: session, mailbox, signal 기반 협업 가이드
• assets/agents/skills/tsaw-bridge/references/codex-adapter.md: Codex bridge 예시
• assets/agents/skills/tsaw-bridge/references/claude-adapter.md: Claude bridge 예시
• assets/agents/skills/tsaw-bridge/references/gemini-adapter.md: Gemini bridge 예시

이 저장소를 직접 수정하는 maintainer라면

이 repository는 일반 initialized project가 아니라 tsaw CLI의 source repository입니다. 일반 사용자는 tsaw init으로 프로젝트를 초기화하고, maintainer는 여기서 CLI와 자산 원본을 함께 관리합니다.

source repository에서 기억할 기준:

• canonical asset source: assets/agents/
• self-hosting mirror: 루트 .agents/
• packaged asset mirror: src/tsaw/_assets/
• runtime state root: 루트 .work/
• 공개 제품 표면: bin/, src/, assets/, 문서, 테스트
• tracked source 변경은 current checkout에서 직접 하지 않고 dedicated git worktree에서 진행한다.

문서, CLI, 자산을 바꿨다면 최소 아래를 확인합니다.

python3 -m unittest discover -s tests/tsaw -p 'test_*.py'
python3 -m unittest discover -s tests/agent_runtime -p 'test_*.py'
python3 -m unittest discover -s tests/source_repo -p 'test_*.py'
./bin/tsaw validate source-repo
python3 scripts/refresh_packaged_assets.py --check
tsaw validate skills
tsaw validate registry
tsaw validate platforms
tsaw validate command-profiles

배포 전에는 정제된 release tree와 smoke를 별도로 확인합니다.

python3 scripts/build_release_tree.py /tmp/tsaw-release
python3 scripts/package_smoke.py
python3 scripts/release_smoke.py

TestPyPI 리허설은 GitHub Actions Publish Python Package workflow를 manual dispatch해서 실행합니다. Production PyPI publish는 1.12.0처럼 v prefix가 없는 숫자 semver tag를 push할 때만 실행됩니다.

자세한 운영 계약은 AGENTS.md를 기준으로 봅니다.