From 97d2dcc5fa83b4f00c368538553d5db42836c445 Mon Sep 17 00:00:00 2001 From: nrslib <38722970+nrslib@users.noreply.github.com> Date: Sun, 1 Feb 2026 08:53:01 +0900 Subject: [PATCH] Update README: clarify CLI usage and add CI/CD section - Remove multi-word direct task execution (unintended feature) - Focus on interactive planning mode (takt/takt word) - Clarify --pipeline flag usage for CI/CD - Add CI/CD integration section with takt-action reference - Add API cost warning for CI/CD usage - Fix: Remove unnecessary quotes from takt #6 examples --- README.md | 116 ++++++++++++++++++++++++++++++++++------------ docs/README.ja.md | 112 +++++++++++++++++++++++++++++++++----------- 2 files changed, 170 insertions(+), 58 deletions(-) diff --git a/README.md b/README.md index 943e3dd..1917f6f 100644 --- a/README.md +++ b/README.md @@ -22,23 +22,23 @@ npm install -g takt ## Quick Start ```bash -# Run a task (prompts for workflow selection, worktree, and PR creation) -takt "Add a login feature" - -# Run a GitHub issue as a task (both are equivalent) -takt '#6' -takt --issue 6 - -# Interactive mode — refine task requirements with AI, then execute +# Interactive planning — refine task requirements with AI, then execute takt +# You can also provide an initial message to start the conversation +takt hello + +# Run a GitHub issue as a task (both are equivalent) +takt #6 +takt --issue 6 + # Pipeline mode (non-interactive, for scripts and CI) -takt --task "fix the auth bug" --auto-pr +takt --pipeline --task "fix the auth bug" --auto-pr ``` ### What happens when you run a task -When you run `takt "Add a login feature"`, TAKT guides you through an interactive flow: +When you run `takt #6` (GitHub issue reference), TAKT guides you through an interactive flow: **1. Workflow selection** @@ -90,44 +90,47 @@ If `--auto-pr` is specified, the PR is created automatically without asking. The standard mode for everyday development. Workflow selection, worktree creation, and PR creation are handled interactively. ```bash -# Run a task -takt "Add a login feature" - -# Run a GitHub issue as a task (both are equivalent) -takt '#6' -takt --issue 6 - -# Interactive mode — refine task requirements with AI before executing +# Interactive planning — start AI conversation to refine task requirements takt -# Run a task and automatically create a PR (skip the confirmation prompt) -takt '#6' --auto-pr +# You can also provide an initial message to start the conversation +takt hello + +# Run a GitHub issue as a task (both are equivalent) +takt #6 +takt --issue 6 + +# Automatically create a PR (skip the confirmation prompt) +takt #6 --auto-pr + +# Use --task option to specify task content (alternative to GitHub issue) +takt --task "Add login feature" ``` When `--auto-pr` is not specified, you will be asked whether to create a PR after a successful worktree execution. -### Pipeline Mode (`--task`) +### Pipeline Mode (`--pipeline`) -Specifying `--task` enters pipeline mode — fully non-interactive, suitable for scripts and CI integration. TAKT automatically creates a branch, runs the workflow, commits, and pushes. +Specifying `--pipeline` enters pipeline mode — fully non-interactive, suitable for scripts and CI integration. TAKT automatically creates a branch, runs the workflow, commits, and pushes. ```bash # Run a task in pipeline mode -takt --task "fix the auth bug" +takt --pipeline --task "fix the auth bug" # Pipeline mode + automatic PR creation -takt --task "fix the auth bug" --auto-pr +takt --pipeline --task "fix the auth bug" --auto-pr # Attach GitHub issue context -takt --task "fix the auth bug" --issue 99 --auto-pr +takt --pipeline --issue 99 --auto-pr # Specify workflow and branch -takt --task "fix the auth bug" -w magi -b feat/fix-auth +takt --pipeline --task "fix the auth bug" -w magi -b feat/fix-auth # Specify repository (for PR creation) -takt --task "fix the auth bug" --auto-pr --repo owner/repo +takt --pipeline --task "fix the auth bug" --auto-pr --repo owner/repo # Run workflow only — skip branch creation, commit, and push -takt --task "fix the auth bug" --skip-git +takt --pipeline --task "fix the auth bug" --skip-git ``` In pipeline mode, PRs are **not** created unless `--auto-pr` is explicitly specified. @@ -150,13 +153,15 @@ In pipeline mode, PRs are **not** created unless `--auto-pr` is explicitly speci | Option | Description | |--------|-------------| -| `-t, --task ` | Task content — **triggers pipeline (non-interactive) mode** | +| `--pipeline` | **Enable pipeline (non-interactive) mode** — required for CI/automation | +| `-t, --task ` | Task content (as alternative to GitHub issue) | | `-i, --issue ` | GitHub issue number (equivalent to `#N` in interactive mode) | | `-w, --workflow ` | Workflow to use | | `-b, --branch ` | Branch name (auto-generated if omitted) | | `--auto-pr` | Create PR after execution (interactive: skip confirmation, pipeline: enable PR) | | `--skip-git` | Skip branch creation, commit, and push (pipeline mode, workflow-only) | | `--repo ` | Repository for PR creation | +| `--create-worktree ` | Skip worktree confirmation prompt | ## Workflows @@ -374,7 +379,7 @@ trusted_directories: ### Interactive Workflow -When running `takt "Add a feature"`, you are prompted to: +When running `takt` (interactive planning mode) or `takt #6` (GitHub issue), you are prompted to: 1. **Select a workflow** - Choose from available workflows (arrow keys, ESC to cancel) 2. **Create an isolated clone** (optional) - Run the task in a `git clone --shared` for isolation @@ -605,6 +610,57 @@ await engine.run(); See [CONTRIBUTING.md](./CONTRIBUTING.md) for details. +## CI/CD Integration + +### GitHub Actions + +TAKT provides a GitHub Action for automated PR reviews and task execution. See [takt-action](https://github.com/nrslib/takt-action) for details. + +**Example workflow** (see [.github/workflows/takt-action.yml](.github/workflows/takt-action.yml) in this repository): + +```yaml +name: TAKT + +on: + issue_comment: + types: [created] + +jobs: + takt: + if: contains(github.event.comment.body, '@takt') + runs-on: ubuntu-latest + permissions: + contents: write + issues: write + pull-requests: write + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Run TAKT + uses: nrslib/takt-action@main + with: + anthropic_api_key: ${{ secrets.TAKT_ANTHROPIC_API_KEY }} + github_token: ${{ secrets.GITHUB_TOKEN }} +``` + +**Cost Warning**: TAKT uses AI APIs (Claude or OpenAI) which can incur significant costs, especially in CI/CD environments where tasks run automatically. Monitor your API usage and set billing alerts. + +### Other CI Systems + +For non-GitHub CI systems, use pipeline mode: + +```bash +# Install takt +npm install -g takt + +# Run in pipeline mode +takt --pipeline --task "fix bug" --auto-pr --repo owner/repo +``` + +Set `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` environment variables for authentication. + ## Docker Support Docker environment is provided for testing in other environments: diff --git a/docs/README.ja.md b/docs/README.ja.md index dc42bf8..e9c22a4 100644 --- a/docs/README.ja.md +++ b/docs/README.ja.md @@ -20,23 +20,23 @@ npm install -g takt ## クイックスタート ```bash -# タスクを実行（ワークフロー選択・worktree・PR作成を対話的に案内） -takt ログイン機能を追加して - -# GitHub Issueをタスクとして実行（どちらも同じ） -takt '#6' -takt --issue 6 - # 対話モードでAIとタスク要件を詰めてから実行 takt +# 最初のメッセージを指定して会話を開始することも可能 +takt こんにちは + +# GitHub Issueをタスクとして実行（どちらも同じ） +takt #6 +takt --issue 6 + # パイプライン実行（非対話・スクリプト/CI向け） -takt --task "バグを修正して" --auto-pr +takt --pipeline --task "バグを修正して" --auto-pr ``` ### タスク実行の流れ -`takt ログイン機能を追加して` を実行すると、以下の対話フローが表示されます: +`takt #6` (GitHub Issue参照) を実行すると、以下の対話フローが表示されます: **1. ワークフロー選択** @@ -88,44 +88,47 @@ Select workflow: 日常の開発で使う基本モード。ワークフロー選択、worktree作成、PR作成を対話的に確認します。 ```bash -# タスクを実行 -takt ログイン機能を追加して - -# GitHub Issueをタスクとして実行（どちらも同じ） -takt '#6' -takt --issue 6 - # 対話モードでAIとタスク要件を詰めてから実行 takt -# タスクを実行してPRを自動作成（確認プロンプトをスキップ） -takt '#6' --auto-pr +# 最初のメッセージを指定して会話を開始することも可能 +takt こんにちは + +# GitHub Issueをタスクとして実行（どちらも同じ） +takt #6 +takt --issue 6 + +# PR自動作成（確認プロンプトをスキップ） +takt #6 --auto-pr + +# --taskオプションでタスク内容を指定（GitHub Issueの代わり） +takt --task "ログイン機能を追加" ``` `--auto-pr` を指定しない場合、worktreeでの実行成功後に「PR作成する？」と確認されます。 -### パイプラインモード（`--task`） +### パイプラインモード（`--pipeline`） -`--task` を指定すると非対話のパイプラインモードに入ります。ブランチ作成 → ワークフロー実行 → commit & push を自動で行います。スクリプトやCI連携に適しています。 +`--pipeline` を指定すると非対話のパイプラインモードに入ります。ブランチ作成 → ワークフロー実行 → commit & push を自動で行います。スクリプトやCI連携に適しています。 ```bash # タスクをパイプライン実行 -takt --task "バグを修正" +takt --pipeline --task "バグを修正" # パイプライン実行 + PR自動作成 -takt --task "バグを修正" --auto-pr +takt --pipeline --task "バグを修正" --auto-pr # Issue情報を紐付け -takt --task "バグを修正" --issue 99 --auto-pr +takt --pipeline --issue 99 --auto-pr # ワークフロー・ブランチ指定 -takt --task "バグを修正" -w magi -b feat/fix-bug +takt --pipeline --task "バグを修正" -w magi -b feat/fix-bug # リポジトリ指定（PR作成時） -takt --task "バグを修正" --auto-pr --repo owner/repo +takt --pipeline --task "バグを修正" --auto-pr --repo owner/repo # ワークフロー実行のみ（ブランチ作成・commit・pushをスキップ） -takt --task "バグを修正" --skip-git +takt --pipeline --task "バグを修正" --skip-git ``` パイプラインモードでは `--auto-pr` を指定しない限りPRは作成されません。 @@ -148,13 +151,15 @@ takt --task "バグを修正" --skip-git | オプション | 説明 | |-----------|------| -| `-t, --task ` | タスク内容 — **パイプライン（非対話）モードのトリガー** | +| `--pipeline` | **パイプライン（非対話）モードを有効化** — CI/自動化に必須 | +| `-t, --task ` | タスク内容（GitHub Issueの代わり） | | `-i, --issue ` | GitHub Issue番号（対話モードでは `#N` と同じ） | | `-w, --workflow ` | ワークフロー指定 | | `-b, --branch ` | ブランチ名指定（省略時は自動生成） | | `--auto-pr` | PR作成（対話: 確認スキップ、パイプライン: PR有効化） | | `--skip-git` | ブランチ作成・commit・pushをスキップ（パイプラインモード、ワークフロー実行のみ） | | `--repo ` | リポジトリ指定（PR作成時） | +| `--create-worktree ` | worktree確認プロンプトをスキップ | ## ワークフロー @@ -371,7 +376,7 @@ trusted_directories: ### 対話ワークフロー -`takt ログイン機能を追加して` を実行すると、以下の流れで案内されます: +`takt` （対話モード）または `takt #6` （GitHub Issue）を実行すると、以下の流れで案内されます: 1. **ワークフロー選択** - 利用可能なワークフローから選択（矢印キーで移動、ESCでキャンセル） 2. **隔離クローン作成**（オプション） - `git clone --shared` による隔離環境でタスクを実行 @@ -602,6 +607,57 @@ await engine.run(); 詳細は[CONTRIBUTING.md](../CONTRIBUTING.md)を参照。 +## CI/CD連携 + +### GitHub Actions + +TAKTはPRレビューやタスク実行を自動化するGitHub Actionを提供しています。詳細は [takt-action](https://github.com/nrslib/takt-action) を参照してください。 + +**ワークフロー例** (このリポジトリの [.github/workflows/takt-action.yml](../.github/workflows/takt-action.yml) を参照): + +```yaml +name: TAKT + +on: + issue_comment: + types: [created] + +jobs: + takt: + if: contains(github.event.comment.body, '@takt') + runs-on: ubuntu-latest + permissions: + contents: write + issues: write + pull-requests: write + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Run TAKT + uses: nrslib/takt-action@main + with: + anthropic_api_key: ${{ secrets.TAKT_ANTHROPIC_API_KEY }} + github_token: ${{ secrets.GITHUB_TOKEN }} +``` + +**コスト警告**: TAKTはAI API（ClaudeまたはOpenAI）を使用するため、特にCI/CD環境でタスクが自動実行される場合、かなりのコストが発生する可能性があります。API使用量を監視し、請求アラートを設定してください。 + +### その他のCIシステム + +GitHub以外のCIシステムでは、パイプラインモードを使用します: + +```bash +# taktをインストール +npm install -g takt + +# パイプラインモードで実行 +takt --pipeline --task "バグ修正" --auto-pr --repo owner/repo +``` + +認証には `ANTHROPIC_API_KEY` または `OPENAI_API_KEY` 環境変数を設定してください。 + ## Docker サポート 他の環境でのテスト用にDocker環境が提供されています: