{"id":50922420,"url":"https://github.com/qkdxorjs1002/tapl","last_synced_at":"2026-06-16T20:00:25.481Z","repository":{"id":360397662,"uuid":"1246429602","full_name":"qkdxorjs1002/tapl","owner":"qkdxorjs1002","description":"A durable workflow harness for Codex.","archived":false,"fork":false,"pushed_at":"2026-06-16T10:02:35.000Z","size":3916,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-16T10:05:02.762Z","etag":null,"topics":["agents","agentsmd","ai-agents","codex","context-engineering","context-management","harness"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qkdxorjs1002.png","metadata":{"files":{"readme":"README.ko.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-22T07:24:16.000Z","updated_at":"2026-06-16T10:02:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/qkdxorjs1002/tapl","commit_stats":null,"previous_names":["qkdxorjs1002/replta.md","qkdxorjs1002/agents.md","qkdxorjs1002/tapl"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/qkdxorjs1002/tapl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qkdxorjs1002%2Ftapl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qkdxorjs1002%2Ftapl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qkdxorjs1002%2Ftapl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qkdxorjs1002%2Ftapl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qkdxorjs1002","download_url":"https://codeload.github.com/qkdxorjs1002/tapl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qkdxorjs1002%2Ftapl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34421326,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","agentsmd","ai-agents","codex","context-engineering","context-management","harness"],"created_at":"2026-06-16T20:00:15.066Z","updated_at":"2026-06-16T20:00:25.473Z","avatar_url":"https://github.com/qkdxorjs1002.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/tapl-readme-hero-with-text.png\" alt=\"tapl: Harness over prompting. State over files.\" /\u003e\n\u003c/p\u003e\n\n# tapl\n\n[English](README.md)\n\n`tapl`은 Codex를 위한 workflow harness입니다. 사용자 전역에는 하나의\n`taplctl` command를 설치하고, 각 저장소의 workflow state는 SQLite로\nrepo-local에 보관하며, Codex hook으로 agent 작업을 추적 가능하고 다시\n이어갈 수 있게 만듭니다.\n\n## 소개\n\nAgent 작업은 보통 프롬프트에서 시작하지만, 실제 개발 작업에는 프롬프트\n텍스트만으로 부족한 부분이 있습니다. 현재 plan, 실행 가능한 task, finding,\nlifecycle event, 검색 가능한 history, tool 사용을 관찰하거나 차단할 경계가\n필요합니다.\n\n`tapl`은 그 작은 제어면을 제공합니다. Agent를 대체하지 않고, context 압축,\nsession resume, 긴 repository 작업을 지나도 남아 있는 durable workflow surface를\nagent에게 제공합니다.\n\n## 이게 무엇인지\n\n`tapl`은 다섯 가지로 구성됩니다.\n\n- `taplctl`: agent, hook, 사람, VS Code viewer가 함께 사용하는 CLI.\n- `.tapl/tapl.db`: active run, plan, task, finding, approval, event, archive,\n  embedding을 저장하는 repo-local SQLite DB.\n- Codex hooks: `UserPromptSubmit`, `PreToolUse`, `PermissionRequest`,\n  `PostToolUse`, `Stop` lifecycle wiring.\n- Lifecycle context: 현재 repo DB와 config에서 생성되는 짧은 상태 기반 안내.\n- Search/archive 도구: 현재 작업과 완료된 작업을 FTS 및 semantic search로 찾는 기능.\n\n설치된 command는 전역이고 workflow state는 저장소별 local입니다. 이 분리는\n설치를 단순하게 유지하면서도 한 workspace의 상태가 다른 workspace로 새지 않게\n합니다.\n\n## 왜 사용하는지\n\nCodex 작업을 감사 가능하고 복구 가능하게 만들어야 할 때 `tapl`을 사용합니다.\n\n- 긴 작업을 저장된 plan/task state에서 다시 이어갈 수 있습니다.\n- 이전 결정과 finding을 다시 발견하지 않고 검색할 수 있습니다.\n- Active workflow state 없이 durable edit가 일어나려 할 때 hook이 경고할 수 있습니다.\n- 완료된 작업을 archive로 남겨 이후 검색할 수 있습니다.\n- 사람과 agent가 같은 CLI를 통해 같은 SQLite state를 읽습니다.\n- `AGENTS.md`를 workflow source of truth로 쓰지 않아도 됩니다.\n\n실용적인 효과는 프롬프트 기억에 덜 의존하고, 도구가 확인할 수 있는 상태에 더\n의존하게 되는 것입니다.\n\n## 철학\n\n- **프롬프트보다 harness**: 프롬프트는 의도를 안내하고, hook과 state는 workflow\n  경계를 지킵니다.\n- **파일보다 상태**: 진행 중인 workflow record는 흩어진 Markdown 대신 SQLite에\n  저장합니다.\n- **수동 index보다 검색**: 과거 작업은 손으로 관리하는 index 없이 발견할 수 있어야\n  합니다.\n- **enforce 전에 observe**: 먼저 lifecycle event와 warning을 기록하고, 유용성이\n  확인된 경계에서만 blocking을 켭니다.\n- **전역 command, repo-local state**: `taplctl`은 한 번 설치하고, 각 저장소의\n  `.tapl/tapl.db`는 분리합니다.\n- **agent와 hook의 역할 분리**: agent는 사용자 의도를 해석하고, hook은 lifecycle과\n  tool-use 경계를 지킵니다.\n\n## 원리\n\n`tapl`은 작은 운영 모델을 따릅니다.\n\n1. Codex가 시작되거나 사용자의 prompt를 받습니다.\n2. Hook이 `taplctl hook-event`를 호출하고 현재 repo state를 읽습니다.\n3. 작업이 non-trivial이면 agent가 `taplctl status`를 확인하고 과거 작업을 검색합니다.\n4. Durable edit 전에 plan과 실행 가능한 task를 기록합니다.\n5. `PreToolUse`와 `PostToolUse` hook이 workflow boundary를 observe 또는 enforce합니다.\n6. 완료된 작업은 archive로 남기고 이후 `taplctl search`로 찾습니다.\n\n설치에 사용되는 source template은 `tapl/.codex`와 `tapl/.tapl/config.toml`에\n있습니다. `taplctl install user`와 `taplctl install repo`는 이 template을 사용자\nCodex home, 사용자 tapl config 디렉터리, 또는 대상 저장소에 필요한 형태로\n복사합니다. Runtime config는 repo `.tapl/config.toml`을 먼저 읽고, 없으면\n`~/.tapl/config.toml`을 읽습니다.\n\n## 설치방법\n\n### 필요 환경\n\n- Python 3.11 이상. 함께 제공하는 Homebrew formula는 `python@3.12`를 사용합니다.\n- FTS5와 extension loading을 지원하는 SQLite.\n- 함께 제공하는 formula로 설치할 경우 Homebrew.\n- Source 개발 또는 build를 할 경우 `uv`.\n- Workflow viewer를 사용할 경우에만 VS Code.\n\n### `taplctl` 설치\n\nHomebrew 사용시:\n\n```sh\nbrew tap qkdxorjs1002/tap\nbrew trust --formula qkdxorjs1002/tap/taplctl\nbrew install taplctl\n# 또는 의미 검색 사용시\nbrew install taplctl-semantic\n```\n\n그 다음 Codex workflow wiring을 설치합니다.\n\n```sh\n# 사용자 폴더 전역 적용시\ntaplctl install user\n\n# 현재 Repo에 적용시\ntaplctl install repo\n\ntaplctl doctor --json\n```\n\n`install user`는 사용자 레벨 Codex hook과 agent template 및\n`~/.tapl/config.toml`을 기록합니다. `install repo`는 repo-local hook/config\n파일을 만들고 `.tapl/tapl.db`를 초기화합니다.\n\nCodex 설치 병합 정책:\n\n- `hooks.json`은 managed merge를 합니다. 기존 non-tapl hook은 보존하고,\n  tapl이 관리하는 hook만 교체합니다.\n- `config.toml`은 TOML 병합을 합니다. 파일이 없으면 tapl template으로\n  만들고, 파일이 있으면 기존 사용자 값이 우선하며 tapl template에만 있는\n  누락 key만 추가합니다. `[features]` 같은 nested table은 재귀 병합합니다.\n- `--force`는 managed `config.toml` key에 대해 tapl template 값을 우선하게\n  하되, 관련 없는 사용자 key는 보존합니다. 기존 TOML을 파싱할 수 없으면\n  `--force`가 template으로 교체합니다.\n- Agent template은 기본적으로 create-or-skip이며, `--force`를 주면\n  덮어씁니다.\n\nSource 개발:\n\n```sh\ncd tapl\nuv sync\nuv run taplctl --version\nuv build\n```\n\n## 사용 방법\n\n현재 workflow state 확인:\n\n```sh\ntaplctl status --json\ntaplctl validate --json\ntaplctl context --event UserPromptSubmit --json\n```\n\nPlan 기록:\n\n```sh\ntaplctl plan upsert \\\n  --id SPEC-EXAMPLE \\\n  --title \"Example implementation plan\" \\\n  --summary \"REQ-001: 접근, 영향 파일, 실행 순서, 위험, 검증 방법을 기록한다.\" \\\n  --status Finalized \\\n  --json\n```\n\n실행 가능한 task 기록:\n\n```sh\ntaplctl task upsert \\\n  --id TASK-EXAMPLE \\\n  --title \"Implement the change\" \\\n  --status \"In Progress\" \\\n  --spec-id SPEC-EXAMPLE \\\n  --goal \"Make the requested change\" \\\n  --action \"Edit the relevant files\" \\\n  --required-subagent \"@junior-worker\" \\\n  --verification \"Run focused checks\" \\\n  --json\n```\n\ndurable edit 전에 명시적 실행 승인을 기록합니다.\n\n```sh\ntaplctl approval record \\\n  --decision approved \\\n  --prompt \"Execute TASK-EXAMPLE from SPEC-EXAMPLE\" \\\n  --json\n\ntaplctl approval status --json\n```\n\n실행 가능한 task가 남아 있는 상태에서 새 prompt가 들어오면 lifecycle context는\n남은 일을 먼저 할지, 새 요청과 합칠지, 보류하거나 archive할지, active run을\n버리고 새로 시작할지를 물으라고 안내합니다.\n\nFinding 추가와 history 검색:\n\n```sh\ntaplctl finding add \\\n  --title \"Important implementation note\" \\\n  --finding \"What was learned\" \\\n  --impact \"Why it matters\" \\\n  --json\n\ntaplctl search \"workflow dashboard\" --json\n```\n\n완료된 작업 archive:\n\n```sh\ntaplctl archive create \\\n  --slug completed-change \\\n  --summary \"What was completed and how it was verified\" \\\n  --json\n```\n\n완료 보고에는 변경 파일과 동작, 검증 명령과 결과, 남은 위험 또는 block된 일,\nworkflow archive 여부를 짧게 포함합니다. Archive summary에는 원 요청, 선택한\n계획, 완료된 task와 결과, 검증, 남은 일을 compact하게 남깁니다.\n\nSemantic search index 재생성:\n\n```sh\ntaplctl reindex --json\n```\n\n`vscode-extension/`의 VS Code extension은 `taplctl status`,\n`taplctl archive list`, `taplctl search`, `taplctl item show`를 통해 같은 state를\n읽습니다.\n\n## 의존성 목록\n\n`tapl/pyproject.toml` 기준 runtime dependency:\n\n| 의존성 | 용도 |\n| --- | --- |\n| Python `\u003e=3.11` | `taplctl` CLI runtime. |\n| `numpy\u003e=1.26` | Embedding과 vector operation을 위한 numeric support. |\n| `sentence-transformers\u003e=5.0.0` | Archive/search용 semantic embedding. |\n| `sqlite-vec\u003e=0.1.6` | SQLite vector search extension. |\n| SQLite FTS5 | Keyword search fallback과 hybrid search 지원. |\n\n개발 및 packaging dependency:\n\n| 의존성 | 용도 |\n| --- | --- |\n| `uv` | Source environment, lockfile, package build workflow. |\n| `pytest\u003e=8` | Python test dependency. |\n| `pyyaml\u003e=6.0` | Test/development dependency. |\n| Homebrew | Local formula install과 formula test. |\n| Node.js 및 npm | VS Code extension build workflow. |\n| TypeScript | `vscode-extension/src`를 `vscode-extension/out`으로 compile. |\n| VS Code `^1.90.0` | Optional workflow viewer host. |\n\n설치 후 `taplctl doctor --json`으로 dependency 상태를 확인할 수 있습니다.\n\n```json\n{\n  \"numpy\": true,\n  \"sentence_transformers\": true,\n  \"sqlite_vec\": true\n}\n```\n\n## 저장소 구조\n\n```text\n.\n├── .codex/                    # taplctl install repo가 생성하는 repo-local 파일\n├── .tapl/config.toml          # Repo-local runtime config\n├── tapl/.codex/               # taplctl package에 포함되는 Codex hook/agent template\n├── tapl/.tapl/config.toml     # 기본 tapl config template\n├── tapl/taplctl/              # Python CLI와 workflow harness 구현\n├── tapl/tests/                # Python tests\n├── tapl/pyproject.toml        # taplctl package metadata\n├── tap/Formula/taplctl.rb     # Homebrew formula\n├── vscode-extension/          # Optional VS Code workflow viewer\n├── README.md                  # English README\n└── README.ko.md               # Korean README\n```\n\nRuntime state와 local build output은 source contract에 포함하지 않습니다.\n\n```text\n.tapl/tapl.db\ntapl/.venv/\ntapl/dist/\n```\n\n## 개발 검증\n\n```sh\nuv --directory tapl sync --extra test\nuv --directory tapl run --extra test python -m unittest discover -s tests\nuv --directory tapl build\nnpm --prefix vscode-extension run compile\nruby -c tap/Formula/taplctl.rb\ngit diff --check\ntaplctl validate --json\n```\n\n## 라이선스\n\nMIT. [LICENSE.md](LICENSE.md)를 참고하세요.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqkdxorjs1002%2Ftapl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqkdxorjs1002%2Ftapl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqkdxorjs1002%2Ftapl/lists"}