trustay-agent-workflow 1.13.0__tar.gz

trustay_agent_workflow-1.13.0/PKG-INFO

@@ -0,0 +1,447 @@
+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)를 기준으로 봅니다.