Metadata-Version: 2.4
Name: trustay-agent-workflow
Version: 1.13.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

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

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

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

## 왜 쓰는가

`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`를 설치합니다.

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

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

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

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

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

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

| 하고 싶은 일 | 명령 |
| --- | --- |
| 프로젝트에 계약과 자산 설치 | `tsaw init --vendor all` |
| 자산 구조 확인 | `tsaw validate assets` |
| 지금 해야 할 일 한 줄 확인 | `tsaw cockpit --next-action` |
| 여러 task의 사람 액션 확인 | `tsaw inbox` |
| 관리형 자산 업데이트 미리 보기 | `tsaw update --diff` |

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

## 프로젝트에 생기는 것

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

```text
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 명령을 씁니다.

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

## 1.12.0: installable distribution

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

source repository를 clone해서 `./install.sh`를 실행하는 경로는 maintainer가
CLI와 `assets/` 원본을 함께 수정할 때 사용합니다. 일반 initialized project는
설치된 `tsaw`로 `tsaw init`, `tsaw update`, `tsaw doctor`를 실행하면 됩니다.

## 1.11.0: 자연어 squad planning

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

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

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

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

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

## 첫 작업 흐름

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

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`은 충돌을 피하기 위해 중단합니다. 가장 안전한 도입 방식은 보통
아래입니다.

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

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

```bash
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`를 사용합니다.

```bash
tsaw init --vendor all --force
```

## 업데이트

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

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

source repository를 직접 다루는 maintainer는 기존처럼 source checkout을 갱신할
수 있습니다.

```bash
cd /path/to/agent-workflow
git pull
tsaw --version
```

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

```bash
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 백업으로 복원 |

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

```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 command suggest cat README.md` | stale 또는 shell-style command의 대체 표면 확인 |
| `tsaw metrics show --accounting` | context economy와 runtime metric 확인 |

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

## 문서 지도

- [README.md](README.md): 사용자 온보딩과 제품 사용 설명
- [AGENTS.md](AGENTS.md): source repository를 다루는 maintainer와 agent 운영 계약
- [CHANGELOG.md](CHANGELOG.md): 사용자 영향이 있는 릴리즈 변경 이력
- [docs/cockpit.md](docs/cockpit.md): cockpit view, interactive mode, scripting mode
- [assets/agents/guides/context-management.md](assets/agents/guides/context-management.md):
  session, mailbox, signal 기반 협업 가이드
- [assets/agents/skills/tsaw-bridge/references/codex-adapter.md](assets/agents/skills/tsaw-bridge/references/codex-adapter.md):
  Codex bridge 예시
- [assets/agents/skills/tsaw-bridge/references/claude-adapter.md](assets/agents/skills/tsaw-bridge/references/claude-adapter.md):
  Claude bridge 예시
- [assets/agents/skills/tsaw-bridge/references/gemini-adapter.md](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, 자산을 바꿨다면 최소 아래를 확인합니다.

```bash
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를 별도로 확인합니다.

```bash
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](AGENTS.md)를 기준으로 봅니다.
