Metadata-Version: 2.4
Name: trustay-agent-workflow
Version: 1.16.0
Summary: Trustay Agent Workflow CLI and managed agent workflow assets.
Author: Trustay
Project-URL: Homepage, https://github.com/trustay-inc/agent-workflow
Project-URL: Repository, https://github.com/trustay-inc/agent-workflow
Project-URL: Changelog, https://github.com/trustay-inc/agent-workflow/blob/main/CHANGELOG.md
Keywords: agent,workflow,cli,automation
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# Trustay Agent Workflow

[![PyPI version](https://img.shields.io/pypi/v/trustay-agent-workflow.svg)](https://pypi.org/project/trustay-agent-workflow/)
[![Python versions](https://img.shields.io/pypi/pyversions/trustay-agent-workflow.svg)](https://pypi.org/project/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인가](#왜-tsaw인가)에서 자세히 다룹니다.

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

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

## 목차

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

## tsaw는 어디에 있나

```mermaid
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는 그 위에서 이어 갑니다. 채팅을 옮길 필요가 없습니다.

```bash
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, 병렬 실행 후보로 해석해 줍니다.

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

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

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

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

```bash
# 한 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가 붙어, 에이전트는 "잘렸는지, 더 읽어야 하는지"를 알면서 딱 필요한 만큼만 가져갑니다.

```bash
# 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`는 사람의 역할을 **결정 제공자**로 좁힙니다. 사람이 보는 표면은 "지금 결정할 일"만 보여 줍니다.

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

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

```bash
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를 열든 같은 계약을 읽습니다.

```bash
# 새 프로젝트에 관리형 계약 설치
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](docs/getting-started.md)에 있습니다.

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

```bash
pipx install trustay-agent-workflow
tsaw --version
```

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

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

```bash
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](docs/commands.md#install-profile)를 참고하세요.

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

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

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

```bash
# 지금 해야 할 일 한 줄
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)

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

| 경로 | 역할 |
| --- | --- |
| `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별 노출 표면 |

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

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

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

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

`tsaw`의 명령은 두 갈래입니다. 사람은 **결정**에 필요한 것만 보고([Human decision surface](#-사람은-cli를-외우지-않는다)), 에이전트는 **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](docs/commands.md), 옵션 세부는 `tsaw <subcommand> --help`로 확인하는 편이 가장 빠릅니다.

## 첫 작업 흐름

```mermaid
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`입니다.

```bash
tsaw init --vendor all --preserve-local
```

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

## 업데이트

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

```bash
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/commands.md#update)에 정리돼 있습니다.

## 더 알아보기

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

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