diff --git a/README.ja.md b/README.ja.md index c8a44443..3f34ce4f 100644 --- a/README.ja.md +++ b/README.ja.md @@ -3,1131 +3,191 @@ [![Test](https://github.com/gendosu/agkan/workflows/Test/badge.svg?branch=main)](https://github.com/gendosu/agkan/actions/workflows/test.yml) [![Quality Check](https://github.com/gendosu/agkan/workflows/Quality%20Check/badge.svg?branch=main)](https://github.com/gendosu/agkan/actions/workflows/quality.yml) -TypeScriptで実装された軽量なCLIタスク管理ツールです。エージェント（AIアシスタント）との協働作業に最適化されています。 +人間とAIコーディングエージェントが一緒にタスクを進めるための、軽量なCLI＆カンバンボードです。 -## 特徴 +![agkanのカンバンボード](docs/assets/readme-board.png) -- **シンプルなCLI**: 直感的なコマンドラインインターフェース -- **SQLiteベース**: ローカルでの高速データ管理 -- **カンバン形式**: 7つのステータスでタスクを管理（icebox, backlog, ready, in_progress, review, done, closed） -- **柔軟な入力**: コマンドライン引数またはMarkdownファイルからタスクを作成 -- **フィルタリング**: ステータスや作成者でタスクを絞り込み -- **色分け表示**: ステータスごとに見やすい色分け表示 -- **親子関係**: タスクの階層構造を管理（ツリー表示対応） -- **ブロック関係**: タスク間の依存関係を管理（循環参照検出機能付き） -- **タグ機能**: タスクにタグを付けて分類・検索が可能 +## 特徴 -## Agent Skills +**タスク管理** +- ローカルSQLiteで動く、シンプルで直感的なCLI +- 7つのステータスによるカンバンワークフロー: icebox, backlog, ready, in_progress, review, done, closed +- コマンドライン引数またはMarkdownファイルからタスクを作成。ステータス・作成者・タグで絞り込み +- ステータスごとに見やすい色分け表示 -agkanをClaude Codeのスキル（タスクの自動実行、プランニング、レビューなど）と連携して使用するには、以下のスキルパッケージをインストールしてください： +**依存関係** +- ツリー表示に対応した親子関係（`task list --tree`） +- 循環参照を自動検出するブロック関係 +- タスクを分類・検索するためのタグ機能 -- **[agkan-skills](https://github.com/gendosu/agkan-skills)** - agkanタスク管理用のClaude Codeスキル +**カンバンボード** +- ローカルで動く、設定不要のWeb UI（`agkan board`） +- ブラウザ上でステータス・タグ・作成者によるフィルタリングと閲覧 +- タスク詳細パネルで全履歴とClaude実行ログを確認可能 -## インストール +**AI連携** +- スクリプトや自動化に使える、主要コマンドの機械可読なJSON出力 +- Claude Code用の連携パッケージ [agkan-skills](https://github.com/gendosu/agkan-skills) +- ボードから直接Claudeを実行し、ライブストリーミング出力と実行履歴を確認可能 +- `agkan init` が登録するSessionStart hookにより、Claude Codeが毎セッション自動でagkanのコンテキストを読み込む -### 前提条件 +## クイックスタート -- Node.js 20以上 -- npm +以下の5ステップで、カンバンボードが動くところまで進めます。 -### npmからインストール（推奨） +### 1. インストール -グローバルコマンドとしてインストール: ```bash npm install -g agkan ``` -これで `agkan` コマンドがシステム全体で使用可能になります。 - -### GitHubからインストール - -リポジトリから直接インストール: +Node.js 20以上とnpmが必要です。GitHubから最新のコードを直接インストールする場合: ```bash npm install -g https://github.com/gendosu/agkan.git ``` -## 使用方法 - -### プロジェクトの初期化 - -プロジェクトディレクトリで `agkan init` を実行して agkan をセットアップします: +### 2. プロジェクトを初期化 ```bash agkan init ``` - -以下のファイルが作成されます: -- `.agkan.yml` — 設定ファイル -- `.agkan/` — データディレクトリ - -`agkan init` は `.claude/settings.local.json` に SessionStart hook も登録し、 -Claude Code のセッション開始時に最小限の agkan 使用ガイドを自動でロードします。 -hook は `agkan context --hook` を呼び出します。既存設定との競合を避けるため -冪等にマージし、関係のないキーには触れません。Claude Code を使わない場合は -生成されたファイルを無視しても問題ありません。 - -### タスクの作成 - -基本的なタスク作成: -```bash -agkan task add "タスクのタイトル" "タスクの説明" -``` - -オプション付きでタスク作成: -```bash -agkan task add "ログイン機能の実装" "ユーザー認証システムを実装" \ - --status ready \ - --author "developer-name" -``` - -親タスクを指定してタスク作成: -```bash -agkan task add "子タスク" "詳細な作業項目" --parent 1 -``` - -Markdownファイルからタスク作成: -```bash -agkan task add "設計書レビュー" --file ./design-doc.md --status backlog -``` - -タグ付きでタスク作成（カンマ区切りのタグ名またはID、同じコマンドで付与）: -```bash -agkan task add "ログイン機能の実装" --tag "frontend,urgent" -``` - -### タスク一覧の表示 - -全タスクを表示: -```bash -agkan task list -``` - -ツリー形式で表示（親子関係を含む）: -```bash -agkan task list --tree -``` - -ルートタスクのみ表示（親を持たないタスク）: -```bash -agkan task list --root-only -``` - -ステータスでフィルタリング: -```bash -agkan task list --status in_progress -``` - -作成者でフィルタリング: -```bash -agkan task list --author "developer-name" -``` - -複合フィルター: -```bash -agkan task list --status ready --author "developer-name" -``` - -タグでフィルタリング: -```bash -agkan task list --tag "frontend" -``` - -### タスクの検索 - -キーワードでタスクを検索（タイトルと本文を対象）: -```bash -agkan task find "検索キーワード" -``` - -完了済みタスクも含めて検索: -```bash -agkan task find "検索キーワード" --all -``` - -注: デフォルトでは、`done`と`closed`のタスクは検索結果から除外されます。 - -### タスク詳細の取得 - -```bash -agkan task get 1 -``` - -### タスクの更新 - -ステータスを変更: -```bash -agkan task update 1 status done -``` - -タイトルを変更: -```bash -agkan task update 1 title "新しいタイトル" -``` - -本文を変更: -```bash -agkan task update 1 body "新しい説明文" -``` - -作成者を変更: -```bash -agkan task update 1 author "new-author" -``` - -### 親子関係の管理 - -親タスクの更新: -```bash -# タスク2の親をタスク1に設定 -agkan task update-parent 2 1 - -# タスク2の親を解除（孤立化） -agkan task update-parent 2 null -``` - -注意事項: -- 親タスクを削除すると、子タスクの親参照は自動的に解除されます（孤立化） -- 循環参照は自動的に検出され、エラーとなります - -### ブロック関係の管理 - -ブロック関係の追加（タスク1がタスク2をブロック）: -```bash -agkan task block add 1 2 -``` - -ブロック関係の削除: -```bash -agkan task block remove 1 2 -``` - -ブロック関係の一覧表示: -```bash -# タスク1に関連するブロック関係を表示 -agkan task block list 1 -``` - -注意事項: -- 循環参照は自動的に検出され、エラーとなります -- ブロック関係はタスク削除時に自動的に削除されます（CASCADE DELETE） - -### タスクの削除 - -タスクを削除: -```bash -agkan task delete 1 -``` - -### タグ管理 - -タグを作成: -```bash -agkan tag add "frontend" -``` - -タグ一覧を表示: -```bash -agkan tag list ``` - -タグを削除: -```bash -agkan tag delete "frontend" +Created: .agkan.yml +Created: .agkan/ directory +Created: .claude/settings.local.json (added agkan SessionStart hook) ``` -### タスクへのタグ付け - -タスクにタグを付与: -```bash -agkan tag attach 1 "frontend" -``` +### 3. タスクを作成 -または `task add --tag` でタスク作成と同時にタグを付与（`tag attach` を別途実行する必要がない）: ```bash -agkan task add "ログイン画面の実装" --tag "frontend,urgent" +agkan task add "Implement login feature" "Implement user authentication system" ``` - -タスクからタグを削除: -```bash -agkan tag detach 1 "frontend" ``` +✓ Task created successfully -タスクに付けられたタグを表示: -```bash -agkan tag show 1 +ID: 1 +Title: Implement login feature +Status: backlog +Created: 2026/7/10 15:02:48 ``` -### メタデータの管理 +### 4. タスク一覧を表示 -メタデータを設定: ```bash -agkan task meta set 1 priority high +agkan task list ``` - -メタデータを取得: -```bash -agkan task meta get 1 priority ``` +Found 1 task(s): -メタデータ一覧を表示: -```bash -agkan task meta list 1 -``` +──────────────────────────────────────────────────────────────────────────────── -メタデータを削除: -```bash -agkan task meta delete 1 priority +[1] Implement login feature + Status: backlog + Priority: medium + Created: 2026/7/10 15:02:48 ``` -#### 優先度 (priority) - -タスクの優先度は `priority` キーで管理します: - -| 値 | 意味 | -|-----|------| -| `critical` | 即時対応が必要。ブロッカーとなっている問題 | -| `high` | 優先して着手すべきタスク | -| `medium` | 通常の優先度（デフォルト） | -| `low` | 余裕があれば対応するタスク | +### 5. カンバンボードを開く -### タスクのカウント - -全ステータスのタスク数を表示: -```bash -agkan task count -``` - -特定のステータスのタスク数を表示: -```bash -agkan task count --status in_progress -``` - -スクリプト用の出力（数値のみ）: -```bash -agkan task count -s in_progress -q -``` - -### カンバンボード (Web UI) - -ブラウザでローカルのカンバンボードビューアを起動: ```bash agkan board ``` - -カスタムポートを指定: -```bash -agkan board -p 3000 -``` - -デフォルトでは `http://localhost:8080` でボードが提供されます。 - -#### ボードのClaude連携機能 - -ボードUIにはブラウザから直接Claudeを実行するための機能が組み込まれています: - -- **Runボタン**: タスクカードにある「Run」ボタンをクリックすると、そのタスクに対して `claude` を起動します。ボタン横のドロップダウンからプランモードで実行することもできます。 -- **Planボタン**: タスクを実行せずに計画のみを生成するプランモードで `claude` を起動します。 -- **ストリームモーダル**: Claude実行中はモーダルウィンドウにリアルタイムで出力が表示されます。「Stop」ボタンでプロセスを終了できます。 -- **実行中インジケーター**: Claudeプロセスが動作中の場合、ヘッダーにインジケーターが表示されます。 -- **実行ログタブ**: タスク詳細パネルの「Run Logs」タブに、過去のClaude実行履歴（タイムスタンプと全出力）が表示されます。 - -### Claudeプロセスの状態確認 - -現在実行中のClaudeプロセスを一覧表示します（ボードサーバーが起動している必要があります）: -```bash -agkan ps -``` - -カスタムポートのボードサーバーに接続: -```bash -agkan ps --port 3000 -``` - -このコマンドはボードサーバーに問い合わせて、現在実行中のClaudeプロセスとそれに関連するタスクを表示します。 - -JSON出力フォーマット: -```bash -agkan ps --json -``` -```json -{ - "processes": [ - { - "taskId": 42, - "title": "機能Xの実装", - "command": "claude" - } - ] -} -``` - -### 設定確認 - -`.agkan.yml` の設定値（デフォルト適用後の解決済み値）を取得します: - -```bash -agkan config get # 全設定を表示 -agkan config get board.port # 特定キーを取得（ドット記法） -agkan config get --json # JSON出力 -``` - -出力例: -``` -✓ Resolved config - -path: /workspace/.agkan/data.db -board.port: 8080 -``` - -### ヘルプの表示 - -コマンド一覧: -```bash -agkan --help -``` - -タスクコマンドのヘルプ: -```bash -agkan task --help -``` - -個別コマンドのヘルプ: -```bash -agkan task add --help -``` - -## JSON出力フォーマット - -agkanは10のデータ取得・表示コマンドで、機械可読なJSON出力をサポートしています。`--json`フラグを追加することで、人間が読みやすいテキストの代わりに構造化されたデータを出力できます。 - -### 対応コマンド - -以下のコマンドがJSON出力をサポートしています: - -- `task add` - 新しいタスクを作成 -- `task list` - タスク一覧を表示（フィルタリング付き） -- `task get` - タスク詳細を取得 -- `task find` - キーワードでタスクを検索 -- `task count` - ステータス別のタスク数をカウント -- `task update-parent` - 親子関係を更新 -- `task block list` - ブロック関係を一覧表示 -- `task tag list` - 全タグをタスク数と共に一覧表示 -- `task tag show` - 特定のタスクのタグを表示 -- `task meta list` - タスクのメタデータ一覧を表示 -- `ps` - 現在実行中のClaudeプロセスを一覧表示 - -### 出力構造 - -すべてのJSONレスポンスは以下のパターンに従います: - -**成功レスポンス**には以下が含まれます: -- 操作固有のデータ（task、tasksの配列、counts など） -- 関連データ（parent、blockedBy、blocking、tags など） -- 書き込み操作の場合はオプションで`success: true`フィールド - -**エラーレスポンス**は以下のフォーマットに従います: -```json -{ - "success": false, - "error": { - "message": "エラーの説明" - } -} -``` - -### 一般的な使用例 - -**1. スクリプティングと自動化** -```bash -# CI/CDパイプライン用のタスク数を取得 -TASK_COUNT=$(agkan task count --status backlog --json | jq '.counts.backlog') - -# 処理用にタスクIDを抽出 -agkan task list --status ready --json | jq -r '.tasks[].id' -``` - -**2. 他ツールとの統合** -```bash -# タスクを外部システムにエクスポート -agkan task list --json | jq '.tasks' > tasks.json - -# ブロック関係を処理 -agkan task block list 1 --json | jq '.blockedBy[].title' -``` - -**3. 検証とテスト** -```bash -# タスク作成を検証 -RESULT=$(agkan task add "Test" --json) -echo $RESULT | jq -e '.success == true' && echo "Success" -``` - -JSON出力フォーマット: -```bash -agkan task add "Fix bug in login" --json -``` - -```json -{ - "success": true, - "task": { - "id": 1, - "title": "Fix bug in login", - "status": "backlog", - "body": null, - "author": null, - "parent_id": null, - "created_at": "2026-02-15T00:00:00.000Z", - "updated_at": "2026-02-15T00:00:00.000Z" - }, - "parent": null, - "blockedBy": [], - "blocking": [] -} -``` - -JSON出力フォーマット: -```bash -agkan task list --json -``` - -```json -{ - "tasks": [ - { - "id": 1, - "title": "Implement login feature", - "status": "in_progress", - "body": "Implement user authentication system", - "author": "developer-name", - "parent_id": null, - "created_at": "2026-02-15T00:00:00.000Z", - "updated_at": "2026-02-15T00:00:00.000Z" - }, - { - "id": 2, - "title": "Design review", - "status": "backlog", - "body": null, - "author": null, - "parent_id": null, - "created_at": "2026-02-15T00:00:00.000Z", - "updated_at": "2026-02-15T00:00:00.000Z" - } - ] -} -``` - -JSON出力フォーマット: -```bash -agkan task find "login" --json -``` - -```json -{ - "tasks": [ - { - "id": 1, - "title": "Implement login feature", - "status": "in_progress", - "body": "Implement user authentication system", - "author": "developer-name", - "parent_id": null, - "created_at": "2026-02-15T00:00:00.000Z", - "updated_at": "2026-02-15T00:00:00.000Z" - } - ] -} -``` - -JSON出力フォーマット: -```bash -agkan task get 1 --json -``` - -```json -{ - "task": { - "id": 1, - "title": "Implement login feature", - "status": "in_progress", - "body": "Implement user authentication system", - "author": "developer-name", - "parent_id": null, - "created_at": "2026-02-15T00:00:00.000Z", - "updated_at": "2026-02-15T00:00:00.000Z" - } -} -``` - -JSON出力フォーマット: -```bash -agkan task update-parent 2 1 --json -``` - -```json -{ - "success": true, - "task": { - "id": 2, - "title": "Child Task", - "status": "backlog", - "body": null, - "author": null, - "parent_id": 1, - "created_at": "2026-02-15T00:00:00.000Z", - "updated_at": "2026-02-15T00:00:00.000Z" - }, - "parent": { - "id": 1, - "title": "Parent Task", - "status": "backlog", - "body": null, - "author": null, - "parent_id": null, - "created_at": "2026-02-15T00:00:00.000Z", - "updated_at": "2026-02-15T00:00:00.000Z" - } -} -``` - -JSON出力フォーマット: -```bash -agkan task block list 2 --json -``` - -```json -{ - "task": { - "id": 2, - "title": "API implementation", - "status": "backlog" - }, - "blockedBy": [ - { - "id": 1, - "title": "Database design", - "status": "in_progress" - } - ], - "blocking": [ - { - "id": 3, - "title": "Frontend implementation", - "status": "backlog" - } - ] -} -``` - -全ステータスのJSON出力フォーマット: -```bash -agkan task count --json -``` - -```json -{ - "total": 10, - "counts": { - "backlog": 3, - "ready": 2, - "in_progress": 4, - "done": 1, - "closed": 0 - } -} -``` - -特定ステータスのJSON出力フォーマット: -```bash -agkan task count --status in_progress --json -``` - -```json -{ - "status": "in_progress", - "count": 4 -} -``` - -JSON出力フォーマット: -```bash -agkan tag list --json -``` - -```json -{ - "totalCount": 2, - "tags": [ - { - "id": 1, - "name": "frontend", - "taskCount": 3, - "created_at": "2026-02-15T00:00:00.000Z" - }, - { - "id": 2, - "name": "backend", - "taskCount": 1, - "created_at": "2026-02-15T00:00:00.000Z" - } - ] -} -``` - -JSON出力フォーマット: -```bash -agkan tag show 1 --json -``` - -```json -{ - "task": { - "id": 1, - "title": "Implement login screen", - "status": "in_progress" - }, - "tags": [ - { - "id": 1, - "name": "frontend", - "created_at": "2026-02-15T00:00:00.000Z" - }, - { - "id": 3, - "name": "urgent", - "created_at": "2026-02-15T00:00:00.000Z" - } - ] -} -``` - -## 使用例 - -### 親子関係を使った階層的なタスク管理 - -プロジェクトを親タスク、個別の作業を子タスクとして管理する例: - -```bash -# 親タスクを作成 -agkan task add "Webサイトのリニューアル" -# 出力: Task created with ID: 1 - -# 子タスクを作成 -agkan task add "デザインカンプ作成" --parent 1 -agkan task add "フロントエンド実装" --parent 1 -agkan task add "バックエンド実装" --parent 1 - -# ツリー形式で表示 -agkan task list --tree -# 出力: -# 1 [backlog] Webサイトのリニューアル -# ├─ 2 [backlog] デザインカンプ作成 -# ├─ 3 [backlog] フロントエンド実装 -# └─ 4 [backlog] バックエンド実装 - -# タスク詳細を表示（親情報を含む） -agkan task get 2 -# 出力: -# ID: 2 -# Title: デザインカンプ作成 -# Parent ID: 1 -# ... - -# 親を変更 -agkan task add "UI/UX改善" -# 出力: Task created with ID: 5 -agkan task update-parent 2 5 - -# 親を解除（孤立化） -agkan task update-parent 2 null -``` - -### ブロック関係を使った依存関係の管理 - -タスク間の依存関係を明示的に管理する例: - -```bash -# タスクを作成 -agkan task add "データベース設計" -# 出力: Task created with ID: 1 - -agkan task add "API実装" -# 出力: Task created with ID: 2 - -agkan task add "フロントエンド実装" -# 出力: Task created with ID: 3 - -# ブロック関係を設定（1がデータベース設計、2がAPI実装、3がフロントエンド実装） -# データベース設計がAPI実装をブロック -agkan task block add 1 2 - -# API実装がフロントエンド実装をブロック -agkan task block add 2 3 - -# ブロック関係を確認 -agkan task block list 1 -# 出力: -# Task 1 blocks: -# - Task 2 (API実装) -# Task 1 is blocked by: -# (none) - -agkan task block list 2 -# 出力: -# Task 2 blocks: -# - Task 3 (フロントエンド実装) -# Task 2 is blocked by: -# - Task 1 (データベース設計) - -# 循環参照を試みる（エラーになる） -agkan task block add 3 1 -# 出力: Error: Circular reference detected - -# ブロック関係を削除 -agkan task block remove 1 2 ``` - -### タグを使ったタスク管理 - -タスクにタグを付けて分類する例: - -```bash -# タグを作成 -agkan tag add "frontend" -agkan tag add "backend" -agkan tag add "urgent" - -# タスクを作成してタグを付与 -agkan task add "ログイン画面の実装" -# 出力: Task created with ID: 1 - -agkan tag attach 1 "frontend" -agkan tag attach 1 "urgent" - -agkan task add "API開発" -# 出力: Task created with ID: 2 - -agkan tag attach 2 "backend" - -# --tag を使えば同じコマンドでタグを付与できる -agkan task add "決済フローのバグ修正" --tag "backend,urgent" -# 出力: Task created with ID: 3 - -# タグでフィルタリング -agkan task list --tag "frontend" -# 出力: -# 1 [backlog] ログイン画面の実装 (tags: frontend, urgent) - -# タスクのタグを確認 -agkan tag show 1 -# 出力: -# Tags for task 1: -# - frontend -# - urgent - -# タグを削除 -agkan tag detach 1 "urgent" - -# タグ自体を削除（関連するすべてのタスクから削除される） -agkan tag delete "urgent" -``` - -## タスクステータス - -- **icebox**: 積極的に検討していない凍結タスク（白色表示） -- **backlog**: 未着手のタスク（グレー表示） -- **ready**: 着手可能なタスク（青色表示） -- **in_progress**: 作業中のタスク（黄色表示） -- **review**: レビュー中のタスク（シアン表示） -- **done**: 完了したタスク（緑色表示） -- **closed**: クローズされたタスク（マゼンタ表示） +Server is running on http://localhost:8080 +``` + +別のポートを使いたい場合: `agkan board -p 3000` + +## コマンド早見表 + +各コマンドは `--help` でも使い方を確認できます。 + +| コマンド | 説明 | +|---|---| +| `agkan init` | `.agkan.yml` と `.agkan/` データディレクトリを初期化 | +| `agkan task add [body]` | タスクを作成（`--status`, `--author`, `--parent`, `--tag`, `--file`, `--json`） | +| `agkan task list` | タスク一覧を表示（`--tree`, `--root-only`, `--status`, `--author`, `--tag`, `--json`） | +| `agkan task find <keyword>` | タイトル・本文でタスクを検索（`--all` で done/closed も含める） | +| `agkan task get <id>` | タスク詳細を表示 | +| `agkan task update <id> <field> <value>` | タスクのstatus・title・body・authorを更新 | +| `agkan task update-parent <id> <parent-id>` | 親タスクを設定・解除（`null`） | +| `agkan task delete <id>` | タスクを削除 | +| `agkan task block add <id> <id2>` | `<id>` が `<id2>` をブロックする関係を追加 | +| `agkan task block remove <id> <id2>` | ブロック関係を削除 | +| `agkan task block list <id>` | ブロックしている/されているタスクを表示 | +| `agkan task meta set <id> <key> <value>` | タスクにメタデータを設定（例: `priority`） | +| `agkan task meta get <id> <key>` | タスクのメタデータを取得 | +| `agkan task meta list <id>` | タスクの全メタデータを一覧表示 | +| `agkan task meta delete <id> <key>` | タスクのメタデータを削除 | +| `agkan task count` | ステータス別のタスク数をカウント（`--status`, `--json`） | +| `agkan tag add <name>` | タグを作成 | +| `agkan tag list` | タスク数付きで全タグを一覧表示 | +| `agkan tag delete <name>` | タグを削除 | +| `agkan tag attach <task-id> <tag>` | タスクにタグを付与 | +| `agkan tag detach <task-id> <tag>` | タスクからタグを解除 | +| `agkan tag show <task-id>` | タスクに付与されたタグを一覧表示 | +| `agkan board` | ローカルのカンバンボードWeb UIを起動 | +| `agkan ps` | 現在実行中のClaudeプロセスを一覧表示 | +| `agkan config get [key]` | 解決済みの設定値を表示 | +| `agkan --help` | 全コマンドを表示 | + +全オプション・JSON出力フォーマット・具体的な使用例については **[documentation/cli-reference.ja.md](documentation/cli-reference.ja.md)** を参照してください。 + +## Claude Code連携 + +agkanは、人間だけでなくAIコーディングエージェントからも操作できるように設計されています: + +- **[agkan-skills](https://github.com/gendosu/agkan-skills)** — タスクの自動実行・プランニング・レビューのためのClaude Codeスキル +- **Run / Plan**: ボードの各タスクカードには `claude` を起動する「Run」ボタンがあり、ドロップダウンからプランモードで実行することもできます +- **ストリームモーダル**: Claude実行中はモーダルにリアルタイムで出力が表示され、「Stop」ボタンと実行中インジケーターが利用できます +- **実行ログ**: タスク詳細パネルの「Run Logs」タブに、過去のClaude実行履歴（タイムスタンプと全出力）が保存されます +- **`agkan ps`**: 別のターミナルから、ボードが現在実行中のClaudeプロセスと、それが紐づくタスクを一覧表示できます ## 設定 -### データベースの保存場所 - -agkanは、データベースの保存場所を設定ファイルでカスタマイズできます。 - -#### 設定ファイル: `.agkan.yml` - -プロジェクトのルートディレクトリに`.agkan.yml`ファイルを作成することで、データベースの保存場所を指定できます。 - -**設定例:** - -```yaml -# データベースファイルのパス -path: ./.agkan/data.db -``` - -#### パスの指定方法 - -- **相対パス**: カレントディレクトリからの相対パスとして解決されます - ```yaml - path: ./data/kanban.db - path: ./.agkan/data.db - ``` - -- **絶対パス**: そのままのパスが使用されます - ```yaml - path: /home/user/.config/agkan/data.db - ``` - -#### 環境変数による設定 - -agkanは `AGENT_KANBAN_DB_PATH` 環境変数によるデータベースの場所指定をサポートしています。CI/CD環境や複数環境の管理に特に有用です。 - -**環境変数の設定例:** - -```bash -# カスタムデータベースパスを使用 -export AGENT_KANBAN_DB_PATH=/path/to/your/database.db -agkan task list - -# 絶対パスを使用 -export AGENT_KANBAN_DB_PATH=/home/user/.config/agkan/data.db - -# 相対パスを使用 -export AGENT_KANBAN_DB_PATH=./custom/location/data.db -``` - -**優先順位:** - -データベースパスは以下の優先順位で解決されます: - -**通常モード (`NODE_ENV` が `test` でない場合):** -1. **環境変数**（最高優先）: `AGENT_KANBAN_DB_PATH` -2. **設定ファイル**（フォールバック）: `.agkan.yml` の `path` フィールド -3. **デフォルトパス**（最低優先）: `.agkan/data.db` - -**テストモード (`NODE_ENV=test` の場合):** -1. **環境変数**（最高優先）: `AGENT_KANBAN_DB_PATH` -2. **設定ファイル**（フォールバック）: `.agkan-test.yml` の `path` フィールド -3. **デフォルトパス**（最低優先）: `.agkan-test/data.db` - -**テストモードについて:** - -テストモード（`NODE_ENV=test`）では、テストデータと本番データを自動的に分離します: - -- 別の設定ファイルを使用: `.agkan.yml` の代わりに `.agkan-test.yml` -- 別のデフォルトディレクトリを使用: `.agkan/` の代わりに `.agkan-test/` -- テストモードでも環境変数が最高優先になります - -**使用例:** - -```bash -# CI/CDパイプライン（一時DBを使用） -export AGENT_KANBAN_DB_PATH=/tmp/ci-test-db.db -agkan task list - -# 複数環境の管理 -export AGENT_KANBAN_DB_PATH=./dev/data.db # 開発環境 -export AGENT_KANBAN_DB_PATH=./staging/data.db # ステージング環境 - -# テストの実行 -NODE_ENV=test pnpm test -# デフォルトで .agkan-test/data.db を使用 - -# カスタムテストDBで実行 -NODE_ENV=test AGENT_KANBAN_DB_PATH=/tmp/test.db pnpm test -``` - -#### デフォルトの動作 - -`.agkan.yml`ファイルが存在せず、環境変数も設定されていない場合、データベースは以下の場所に作成されます： - -``` -<カレントディレクトリ>/.agkan/data.db -``` - -テストモード（`NODE_ENV=test`）の場合のデフォルト: - -``` -<カレントディレクトリ>/.agkan-test/data.db -``` - -#### プロジェクトごとの管理 - -プロジェクトごとに異なるタスク管理を行いたい場合は、各プロジェクトのルートに`.agkan.yml`を配置してください： - -```bash -# プロジェクトA -cd /path/to/projectA -cat > .agkan.yml << EOF -path: ./.agkan/data.db -EOF - -# プロジェクトB -cd /path/to/projectB -cat > .agkan.yml << EOF -path: ./.agkan/data.db -EOF -``` - -これにより、各プロジェクトで独立したタスク管理が可能になります。 - -### ボード設定 - -`.agkan.yml` の `board` セクションでは、`agkan board` コマンドの動作をカスタマイズできます。 - -#### 利用可能なフィールド - -| フィールド | 型 | デフォルト値 | 説明 | -|----------|-----|------------|------| -| `board.port` | number | `3000` | ボードWebサーバーのポート番号 | -| `board.title` | string | `"agkan Board"` | ボードUIに表示されるタイトル | - -#### 設定例 +プロジェクトルートの `.agkan.yml` で、データベースの保存場所やボードをカスタマイズできます: ```yaml -# データベースファイルのパス path: ./.agkan/data.db -# ボード設定 board: port: 8080 - title: "マイプロジェクトボード" -``` - -#### フィールドの詳細 - -- **`board.port`**: ボードWebサーバーがリッスンするTCPポートを指定します。デフォルトポート `3000` が既に使用中の場合に有用です。 - ```yaml - board: - port: 8080 - ``` - -- **`board.title`**: ボードUIに表示されるタイトルを設定します。複数のプロジェクトを管理する際に、ボードを区別するのに役立ちます。 - ```yaml - board: - title: "マイプロジェクトボード" - ``` - -### モデル設定 - -`.agkan.yml` の `models` セクションでは、ボード経由でplanningおよびrunコマンドを実行する際に使用するClaudeモデルとeffortレベルを指定できます。 - -#### 利用可能なフィールド - -| フィールド | 型 | デフォルト値 | 説明 | -|----------|-----|------------|------| -| `models.planning.model` | string | (Claude CLIのデフォルト) | planningコマンド実行時に使用するモデル | -| `models.planning.effort` | string | (Claude CLIのデフォルト) | planningコマンドのeffortレベル（`low`, `medium`, `high`, `xhigh`, `max`） | -| `models.run.model` | string | (Claude CLIのデフォルト) | run/prコマンド実行時に使用するモデル | -| `models.run.effort` | string | (Claude CLIのデフォルト) | run/prコマンドのeffortレベル（`low`, `medium`, `high`, `xhigh`, `max`） | - -フルモデル名とClaude CLIのエイリアスの両方が使用できます。`model` と `effort` はいずれも省略可能です。 - -#### 設定例 - -```yaml -# データベースファイルのパス -path: ./.agkan/data.db - -# モデル設定 -models: - planning: - model: claude-opus-4-7 - effort: high - run: - model: claude-sonnet-4-6 - effort: low -``` - -#### エイリアスの使用 - -フルモデル名の代わりに短いエイリアスを使用できます： - -```yaml -models: - planning: - model: opus - effort: high - run: - model: sonnet ``` -使用可能なエイリアス: `opus`、`sonnet`、`haiku`（Claude CLIが解決します） +データベースパスは環境変数 `AGENT_KANBAN_DB_PATH` でも上書きでき、`.agkan.yml` より優先されます。 -#### フィールドの詳細 +テストモード（`NODE_ENV=test`）では、`.agkan-test.yml` と `.agkan-test/` が自動的に使用され、テストが本番のタスクデータベースに影響しないよう分離されます。 -- **`models.planning`**: ボードがplanningタスクを実行する際に使用するClaudeモデルとeffortレベルを指定します。`opus` や `claude-opus-4-7` など高性能なモデルと高いeffortレベルの使用を推奨します。 - ```yaml - models: - planning: - model: opus - effort: high - ``` +プロジェクトごとの管理・モデル選択・パーミッションモードを含む全設定リファレンスは **[documentation/configuration.ja.md](documentation/configuration.ja.md)** を参照してください。 -- **`models.run`**: ボードがrunまたはprコマンドを実行する際に使用するClaudeモデルとeffortレベルを指定します。`pr` コマンドもこの値を使用します。 - ```yaml - models: - run: - model: sonnet - effort: low - ``` - -### パーミッションモード設定 - -`.agkan.yml` の `permissionMode` フィールドで、ボードからタスクを実行する際のClaude CLIのパーミッションチェック方法を制御できます。 - -#### 利用可能な値 - -| 値 | Claude CLI フラグ | 説明 | -|-------|----------------|-------------| -| (未設定) | `--permission-mode auto` | デフォルト。Claudeがautoパーミッションモードを使用 | -| `auto` | `--permission-mode auto` | Claudeがautoパーミッションモードを使用 | -| `bypassPermissions` | `--permission-mode bypassPermissions` | すべてのパーミッションチェックをバイパス | -| `acceptEdits` | `--permission-mode acceptEdits` | ファイル編集を自動的に承認 | -| `dontAsk` | `--permission-mode dontAsk` | パーミッションを確認しない | -| `plan` | `--permission-mode plan` | プランのみモード | -| `default` | `--permission-mode default` | Claudeのデフォルトパーミッションモード | -| `skipPermissions` | `--dangerously-skip-permissions` | レガシーフラグ（すべてのチェックをバイパスする旧来の動作） | - -#### 設定例 - -```yaml -# autoパーミッションモードを使用（デフォルト） -permissionMode: auto - -# レガシーの --dangerously-skip-permissions フラグを使用 -permissionMode: skipPermissions -``` - -> **破壊的変更**: この機能導入以前は常に `--dangerously-skip-permissions` が渡されていました。新しいデフォルトは `--permission-mode auto` です。従来の動作を維持するには `.agkan.yml` に `permissionMode: skipPermissions` を設定してください。 - -## 実装予定機能 - -### タスクの添付ファイル - -タスクへのファイル添付機能は現在開発中です。この機能により、ユーザーはタスクにファイルを添付し、より良いコンテキストとドキュメントを提供できるようになります。 - -**予定されているCLIコマンド:** -- `agkan task attach add <task-id> <file-path>` - タスクにファイルを添付 -- `agkan task attach list <task-id>` - タスクのすべての添付ファイルを一覧表示 -- `agkan task attach delete <attachment-id>` - タスクから添付ファイルを削除 - -実装予定機能の詳細については、[documentation/planned-features.md](documentation/planned-features.md)を参照してください。 - -## 技術スタック - -- **言語**: TypeScript 5.x -- **CLI フレームワーク**: Commander.js -- **データベース**: SQLite3 (better-sqlite3) -- **ターミナル表示**: Chalk -- **ビルドツール**: TypeScript Compiler - -## プロジェクト構成 - -詳細なディレクトリ構成は [documentation/project-structure.ja.md](documentation/project-structure.ja.md) を参照してください。 - -## データベーススキーマ - -詳細なスキーマ情報は [documentation/database-schema.ja.md](documentation/database-schema.ja.md) を参照してください。 - -## 開発 +## タスクステータス -セットアップ手順、テスト、ビルド情報については [documentation/development.ja.md](documentation/development.ja.md) を参照してください。 +タスクは以下の7つのステータスのいずれかで管理されます: + +| ステータス | 意味 | +|---|---| +| `icebox` | 積極的に検討していない凍結タスク | +| `backlog` | 未着手のタスク | +| `ready` | 着手可能なタスク | +| `in_progress` | 作業中のタスク | +| `review` | レビュー中のタスク | +| `done` | 完了したタスク | +| `closed` | クローズされたタスク | + +## ドキュメント + +詳細なリファレンスはこのファイルの外にあります: + +| ドキュメント | 説明 | +|---|---| +| [documentation/cli-reference.ja.md](documentation/cli-reference.ja.md) | 全コマンドリファレンス、オプション、JSON出力フォーマット | +| [documentation/configuration.ja.md](documentation/configuration.ja.md) | `.agkan.yml` リファレンス（パス・ボード・モデル・パーミッションモード） | +| [documentation/project-structure.ja.md](documentation/project-structure.ja.md) | リポジトリのディレクトリ構成 | +| [documentation/database-schema.ja.md](documentation/database-schema.ja.md) | SQLiteスキーマリファレンス | +| [documentation/development.ja.md](documentation/development.ja.md) | 技術スタック、ローカルセットアップ、ビルド情報 | +| [documentation/TESTING.ja.md](documentation/TESTING.ja.md) | テストガイド | +| [CONTRIBUTING.ja.md](CONTRIBUTING.ja.md) | コントリビュート方法 | +| [CHANGELOG.ja.md](CHANGELOG.ja.md) | リリース履歴 | ## ライセンス diff --git a/README.md b/README.md index 14103226..e6b4b2e2 100644 --- a/README.md +++ b/README.md @@ -3,1146 +3,191 @@ [![Test](https://github.com/gendosu/agkan/workflows/Test/badge.svg?branch=main)](https://github.com/gendosu/agkan/actions/workflows/test.yml) [![Quality Check](https://github.com/gendosu/agkan/workflows/Quality%20Check/badge.svg?branch=main)](https://github.com/gendosu/agkan/actions/workflows/quality.yml) -A lightweight CLI task management tool implemented in TypeScript. Optimized for collaborative work with AI agents. +A lightweight CLI & Kanban board for humans and AI coding agents to get things done together. -## Features +![agkan Kanban board](docs/assets/readme-board.png) -- **Simple CLI**: Intuitive command-line interface -- **SQLite-based**: Fast local data management -- **Kanban Format**: Manage tasks with 7 statuses (icebox, backlog, ready, in_progress, review, done, closed) -- **Flexible Input**: Create tasks from command-line arguments or Markdown files -- **Filtering**: Narrow down tasks by status or author -- **Color-coded Display**: Easy-to-read color-coded display by status -- **Parent-Child Relationships**: Manage task hierarchy (tree view supported) -- **Blocking Relationships**: Manage task dependencies (includes circular reference detection) -- **Tag System**: Classify and search tasks with tags -- **Kanban Board**: Local web-based Kanban board viewer +## Features -## Agent Skills +**Task Management** +- Simple, intuitive CLI backed by local SQLite storage +- 7-status Kanban workflow: icebox, backlog, ready, in_progress, review, done, closed +- Create tasks from CLI arguments or Markdown files; filter by status, author, or tag +- Color-coded terminal output -To use agkan with Claude Code skills (automated task execution, planning, review, etc.), install the companion skills package: +**Dependencies** +- Parent-child relationships with tree view (`task list --tree`) +- Blocking relationships with automatic circular-reference detection +- Tag system for classifying and searching tasks -- **[agkan-skills](https://github.com/gendosu/agkan-skills)** - Claude Code skills for agkan task management +**Kanban Board** +- Local, zero-config web UI (`agkan board`) +- Filter and browse tasks by status, tag, or author in the browser +- Task detail panel with full task history and Claude run logs -## Installation +**AI Integration** +- Machine-readable JSON output on key commands for scripting and automation +- Companion [agkan-skills](https://github.com/gendosu/agkan-skills) package for Claude Code +- Run Claude directly from the board, with live streaming output and run history +- `agkan init` installs a SessionStart hook so Claude Code loads agkan context automatically each session -### Prerequisites +## Quick Start -- Node.js 20 or higher -- npm +Go from zero to a running Kanban board in five steps. -### Install from npm (Recommended) +### 1. Install -Install as a global command: ```bash npm install -g agkan ``` -Now the `agkan` command is available system-wide. - -### Install from GitHub - -Install directly from the repository: +Requires Node.js 20+ and npm. To install the latest code directly from GitHub instead: ```bash npm install -g https://github.com/gendosu/agkan.git ``` -## Usage - -### Initialize a Project - -Run `agkan init` in your project directory to set up agkan: +### 2. Initialize your project ```bash agkan init ``` - -This creates: -- `.agkan.yml` — configuration file -- `.agkan/` — data directory - -`agkan init` also installs a SessionStart hook into `.claude/settings.local.json` -so that Claude Code automatically loads a minimal agkan usage brief at the -start of every session. The hook calls `agkan context --hook`. This step is -idempotent and merges into existing settings without touching unrelated keys. -If you are not using Claude Code, you can safely ignore the generated file. - -### Create Tasks - -Basic task creation: -```bash -agkan task add "Task title" "Task description" -``` - -Create with options: -```bash -agkan task add "Implement login feature" "Implement user authentication system" \ - --status ready \ - --author "developer-name" ``` - -Create with parent task: -```bash -agkan task add "Subtask" "Detailed work item" --parent 1 +Created: .agkan.yml +Created: .agkan/ directory +Created: .claude/settings.local.json (added agkan SessionStart hook) ``` -Create from Markdown file: -```bash -agkan task add "Design review" --file ./design-doc.md --status backlog -``` +### 3. Create a task -Create with tags (comma-separated names or IDs, attached in the same command): ```bash -agkan task add "Implement login feature" --tag "frontend,urgent" +agkan task add "Implement login feature" "Implement user authentication system" ``` - -JSON output format: -```bash -agkan task add "Fix bug in login" --json ``` +✓ Task created successfully -```json -{ - "success": true, - "task": { - "id": 1, - "title": "Fix bug in login", - "status": "backlog", - "body": null, - "author": null, - "parent_id": null, - "created_at": "2026-02-15T00:00:00.000Z", - "updated_at": "2026-02-15T00:00:00.000Z" - }, - "parent": null, - "blockedBy": [], - "blocking": [] -} +ID: 1 +Title: Implement login feature +Status: backlog +Created: 2026/7/10 15:02:48 ``` -### List Tasks +### 4. List tasks -Display all tasks: ```bash agkan task list ``` - -Display in tree format (including parent-child relationships): -```bash -agkan task list --tree -``` - -Display root tasks only (tasks without parents): -```bash -agkan task list --root-only -``` - -Filter by status: -```bash -agkan task list --status in_progress -``` - -Filter by author: -```bash -agkan task list --author "developer-name" -``` - -Combined filters: -```bash -agkan task list --status ready --author "developer-name" -``` - -Filter by tag: -```bash -agkan task list --tag "frontend" -``` - -JSON output format: -```bash -agkan task list --json -``` - -```json -{ - "tasks": [ - { - "id": 1, - "title": "Implement login feature", - "status": "in_progress", - "body": "Implement user authentication system", - "author": "developer-name", - "parent_id": null, - "created_at": "2026-02-15T00:00:00.000Z", - "updated_at": "2026-02-15T00:00:00.000Z" - }, - { - "id": 2, - "title": "Design review", - "status": "backlog", - "body": null, - "author": null, - "parent_id": null, - "created_at": "2026-02-15T00:00:00.000Z", - "updated_at": "2026-02-15T00:00:00.000Z" - } - ] -} -``` - -### Search Tasks - -Search by keyword (in title and body): -```bash -agkan task find "search keyword" -``` - -Include completed tasks in search: -```bash -agkan task find "search keyword" --all -``` - -Note: By default, `done` and `closed` tasks are excluded from search results. - -JSON output format: -```bash -agkan task find "login" --json -``` - -```json -{ - "tasks": [ - { - "id": 1, - "title": "Implement login feature", - "status": "in_progress", - "body": "Implement user authentication system", - "author": "developer-name", - "parent_id": null, - "created_at": "2026-02-15T00:00:00.000Z", - "updated_at": "2026-02-15T00:00:00.000Z" - } - ] -} -``` - -### Get Task Details - -```bash -agkan task get 1 ``` +Found 1 task(s): -JSON output format: -```bash -agkan task get 1 --json -``` - -```json -{ - "task": { - "id": 1, - "title": "Implement login feature", - "status": "in_progress", - "body": "Implement user authentication system", - "author": "developer-name", - "parent_id": null, - "created_at": "2026-02-15T00:00:00.000Z", - "updated_at": "2026-02-15T00:00:00.000Z" - } -} -``` - -### Update Tasks - -Change status: -```bash -agkan task update 1 status done -``` +──────────────────────────────────────────────────────────────────────────────── -Change title: -```bash -agkan task update 1 title "New title" +[1] Implement login feature + Status: backlog + Priority: medium + Created: 2026/7/10 15:02:48 ``` -Change body: -```bash -agkan task update 1 body "New description" -``` +### 5. Open the Kanban board -Change author: -```bash -agkan task update 1 author "new-author" -``` - -### Manage Parent-Child Relationships - -Update parent task: -```bash -# Set parent of task 2 to task 1 -agkan task update-parent 2 1 - -# Remove parent (orphan task 2) -agkan task update-parent 2 null -``` - -Notes: -- Deleting a parent task automatically removes the parent reference from child tasks (orphaning them) -- Circular references are automatically detected and prevented - -JSON output format: -```bash -agkan task update-parent 2 1 --json -``` - -```json -{ - "success": true, - "task": { - "id": 2, - "title": "Child Task", - "status": "backlog", - "body": null, - "author": null, - "parent_id": 1, - "created_at": "2026-02-15T00:00:00.000Z", - "updated_at": "2026-02-15T00:00:00.000Z" - }, - "parent": { - "id": 1, - "title": "Parent Task", - "status": "backlog", - "body": null, - "author": null, - "parent_id": null, - "created_at": "2026-02-15T00:00:00.000Z", - "updated_at": "2026-02-15T00:00:00.000Z" - } -} -``` - -### Manage Blocking Relationships - -Add blocking relationship (task 1 blocks task 2): -```bash -agkan task block add 1 2 -``` - -Remove blocking relationship: -```bash -agkan task block remove 1 2 -``` - -List blocking relationships: -```bash -# Show blocking relationships for task 1 -agkan task block list 1 -``` - -Notes: -- Circular references are automatically detected and prevented -- Blocking relationships are automatically deleted when a task is deleted (CASCADE DELETE) - -JSON output format: -```bash -agkan task block list 2 --json -``` - -```json -{ - "task": { - "id": 2, - "title": "API implementation", - "status": "backlog" - }, - "blockedBy": [ - { - "id": 1, - "title": "Database design", - "status": "in_progress" - } - ], - "blocking": [ - { - "id": 3, - "title": "Frontend implementation", - "status": "backlog" - } - ] -} -``` - -### Delete Tasks - -Delete a task: -```bash -agkan task delete 1 -``` - -### Manage Tags - -Create a tag: -```bash -agkan tag add "frontend" -``` - -List all tags: -```bash -agkan tag list -``` - -Delete a tag: -```bash -agkan tag delete "frontend" -``` - -JSON output format for tag list: -```bash -agkan tag list --json -``` - -```json -{ - "totalCount": 2, - "tags": [ - { - "id": 1, - "name": "frontend", - "taskCount": 3, - "created_at": "2026-02-15T00:00:00.000Z" - }, - { - "id": 2, - "name": "backend", - "taskCount": 1, - "created_at": "2026-02-15T00:00:00.000Z" - } - ] -} -``` - -### Attach Tags to Tasks - -Attach a tag to a task: -```bash -agkan tag attach 1 "frontend" -``` - -Or attach tags at creation time with `task add --tag`, instead of a separate `tag attach` call: -```bash -agkan task add "Implement login screen" --tag "frontend,urgent" -``` - -Remove a tag from a task: -```bash -agkan tag detach 1 "frontend" -``` - -Display tags on a task: -```bash -agkan tag show 1 -``` - -JSON output format for tag show: -```bash -agkan tag show 1 --json -``` - -```json -{ - "task": { - "id": 1, - "title": "Implement login screen", - "status": "in_progress" - }, - "tags": [ - { - "id": 1, - "name": "frontend", - "created_at": "2026-02-15T00:00:00.000Z" - }, - { - "id": 3, - "name": "urgent", - "created_at": "2026-02-15T00:00:00.000Z" - } - ] -} -``` - -### Manage Metadata - -Set metadata: -```bash -agkan task meta set 1 priority high -``` - -Get metadata: -```bash -agkan task meta get 1 priority -``` - -List all metadata: -```bash -agkan task meta list 1 -``` - -Delete metadata: -```bash -agkan task meta delete 1 priority -``` - -#### Priority (priority) - -Task priority is managed with the `priority` key: - -| Value | Meaning | -|-------|---------| -| `critical` | Requires immediate action. A blocking issue. | -| `high` | Should be addressed with priority | -| `medium` | Normal priority (default) | -| `low` | Address when time permits | - -### Count Tasks - -Display task count for all statuses: -```bash -agkan task count -``` - -Display task count for a specific status: -```bash -agkan task count --status in_progress -``` - -Script-friendly output (numbers only): -```bash -agkan task count -s in_progress -q -``` - -JSON output format for all statuses: -```bash -agkan task count --json -``` - -```json -{ - "total": 10, - "counts": { - "backlog": 3, - "ready": 2, - "in_progress": 4, - "done": 1, - "closed": 0 - } -} -``` - -JSON output format for specific status: -```bash -agkan task count --status in_progress --json -``` - -```json -{ - "status": "in_progress", - "count": 4 -} -``` - -### Kanban Board (Web UI) - -Start a local Kanban board viewer in your browser: ```bash agkan board ``` - -Specify a custom port: -```bash -agkan board -p 3000 -``` - -The board is served at `http://localhost:8080` by default. - -#### Claude Integration in the Board - -The board UI includes built-in Claude integration for running tasks directly from the browser: - -- **Run button**: Each task card has a "Run" button that launches `claude` for that task. A dropdown arrow next to the button also allows running in plan mode. -- **Plan button**: Runs `claude` in plan mode to generate a plan for the task without executing. -- **Stream modal**: When Claude is running, a modal window displays the live output stream in real time. A "Stop" button allows terminating the process. -- **Running indicator**: A header indicator shows when any Claude process is currently active. -- **Run Logs tab**: The task detail panel includes a "Run Logs" tab that shows the history of all past Claude executions for that task, with timestamps and full output. - -### Claude Process Status - -List currently executing Claude processes (requires the board server to be running): -```bash -agkan ps -``` - -Connect to a board server on a custom port: -```bash -agkan ps --port 3000 ``` - -This command queries the board server to show which Claude processes are currently running and which tasks they are associated with. - -JSON output format: -```bash -agkan ps --json -``` -```json -{ - "processes": [ - { - "taskId": 42, - "title": "Implement feature X", - "command": "claude" - } - ] -} -``` - -### Config - -Get resolved configuration values from `.agkan.yml` (defaults applied): - -```bash -agkan config get # Show full resolved config -agkan config get board.port # Show specific key (dot notation) -agkan config get --json # JSON output -``` - -Example output: -``` -✓ Resolved config - -path: /workspace/.agkan/data.db -board.port: 8080 -``` - -### Display Help - -Show command list: -```bash -agkan --help -``` - -Show task command help: -```bash -agkan task --help -``` - -Show help for specific command: -```bash -agkan task add --help -``` - -## JSON Output Format - -agkan supports machine-readable JSON output for 10 data retrieval and display commands. Add the `--json` flag to output structured data instead of human-readable text. - -### Supported Commands - -The following commands support JSON output: - -- `task add` - Create a new task -- `task list` - List tasks (with filtering) -- `task get` - Get task details -- `task find` - Search tasks by keyword -- `task count` - Count tasks by status -- `task update-parent` - Update parent-child relationship -- `task block list` - List blocking relationships -- `task tag list` - List all tags with task counts -- `task tag show` - Show tags for a specific task -- `task meta list` - List all metadata for a task -- `ps` - List currently executing Claude processes - -### Output Structure - -All JSON responses follow these patterns: - -**Success responses** include: -- Operation-specific data (task, tasks array, counts, etc.) -- Related data (parent, blockedBy, blocking, tags, etc.) -- Optional `success: true` field for write operations - -**Error responses** follow the format: -```json -{ - "success": false, - "error": { - "message": "Error description" - } -} -``` - -### Common Use Cases - -**1. Scripting and Automation** -```bash -# Get task count for CI/CD pipeline -TASK_COUNT=$(agkan task count --status backlog --json | jq '.counts.backlog') - -# Extract task IDs for processing -agkan task list --status ready --json | jq -r '.tasks[].id' -``` - -**2. Integration with Other Tools** -```bash -# Export tasks to external system -agkan task list --json | jq '.tasks' > tasks.json - -# Process blocking relationships -agkan task block list 1 --json | jq '.blockedBy[].title' -``` - -**3. Validation and Testing** -```bash -# Verify task creation -RESULT=$(agkan task add "Test" --json) -echo $RESULT | jq -e '.success == true' && echo "Success" -``` - -## Usage Examples - -### Hierarchical Task Management with Parent-Child Relationships - -Example of managing a project as a parent task with individual work items as children: - -```bash -# Create parent task -agkan task add "Website redesign" -# Output: Task created with ID: 1 - -# Create child tasks -agkan task add "Create design mockup" --parent 1 -agkan task add "Implement frontend" --parent 1 -agkan task add "Implement backend" --parent 1 - -# Display in tree format -agkan task list --tree -# Output: -# 1 [backlog] Website redesign -# ├─ 2 [backlog] Create design mockup -# ├─ 3 [backlog] Implement frontend -# └─ 4 [backlog] Implement backend - -# Display task details (including parent information) -agkan task get 2 -# Output: -# ID: 2 -# Title: Create design mockup -# Parent ID: 1 -# ... - -# Change parent -agkan task add "UI/UX improvements" -# Output: Task created with ID: 5 -agkan task update-parent 2 5 - -# Remove parent (orphan task) -agkan task update-parent 2 null -``` - -### Managing Dependencies with Blocking Relationships - -Example of explicitly managing task dependencies: - -```bash -# Create tasks -agkan task add "Database design" -# Output: Task created with ID: 1 - -agkan task add "API implementation" -# Output: Task created with ID: 2 - -agkan task add "Frontend implementation" -# Output: Task created with ID: 3 - -# Set blocking relationships (1 blocks 2, 2 blocks 3) -# Database design blocks API implementation -agkan task block add 1 2 - -# API implementation blocks Frontend implementation -agkan task block add 2 3 - -# Verify blocking relationships -agkan task block list 1 -# Output: -# Task 1 blocks: -# - Task 2 (API implementation) -# Task 1 is blocked by: -# (none) - -agkan task block list 2 -# Output: -# Task 2 blocks: -# - Task 3 (Frontend implementation) -# Task 2 is blocked by: -# - Task 1 (Database design) - -# Attempt circular reference (error) -agkan task block add 3 1 -# Output: Error: Circular reference detected - -# Remove blocking relationship -agkan task block remove 1 2 -``` - -### Task Management with Tags - -Example of classifying tasks with tags: - -```bash -# Create tags -agkan tag add "frontend" -agkan tag add "backend" -agkan tag add "urgent" - -# Create tasks and attach tags -agkan task add "Implement login screen" -# Output: Task created with ID: 1 - -agkan tag attach 1 "frontend" -agkan tag attach 1 "urgent" - -agkan task add "API development" -# Output: Task created with ID: 2 - -agkan tag attach 2 "backend" - -# Or attach tags in the same command with --tag -agkan task add "Bug fix in payment flow" --tag "backend,urgent" -# Output: Task created with ID: 3 - -# Filter by tag -agkan task list --tag "frontend" -# Output: -# 1 [backlog] Implement login screen (tags: frontend, urgent) - -# Display task tags -agkan tag show 1 -# Output: -# Tags for task 1: -# - frontend -# - urgent - -# Remove a tag -agkan tag detach 1 "urgent" - -# Delete a tag (removes from all associated tasks) -agkan tag delete "urgent" -``` - -## Task Statuses - -- **icebox**: Frozen tasks not actively being considered (white display) -- **backlog**: Not yet started tasks (gray display) -- **ready**: Tasks ready to be started (blue display) -- **in_progress**: Tasks currently being worked on (yellow display) -- **review**: Tasks under review (cyan display) -- **done**: Completed tasks (green display) -- **closed**: Closed tasks (magenta display) +Server is running on http://localhost:8080 +``` + +Need a different port? `agkan board -p 3000`. + +## Command Cheat Sheet + +Every command also accepts `--help` for its own usage details. + +| Command | Description | +|---|---| +| `agkan init` | Initialize `.agkan.yml` and the `.agkan/` data directory | +| `agkan task add <title> [body]` | Create a task (`--status`, `--author`, `--parent`, `--tag`, `--file`, `--json`) | +| `agkan task list` | List tasks (`--tree`, `--root-only`, `--status`, `--author`, `--tag`, `--json`) | +| `agkan task find <keyword>` | Search tasks by title/body (`--all` includes done/closed) | +| `agkan task get <id>` | Show task details | +| `agkan task update <id> <field> <value>` | Update a task's status, title, body, or author | +| `agkan task update-parent <id> <parent-id>` | Set or clear (`null`) a task's parent | +| `agkan task delete <id>` | Delete a task | +| `agkan task block add <id> <id2>` | Mark `<id>` as blocking `<id2>` | +| `agkan task block remove <id> <id2>` | Remove a blocking relationship | +| `agkan task block list <id>` | Show what a task blocks and is blocked by | +| `agkan task meta set <id> <key> <value>` | Set a metadata value on a task (e.g. `priority`) | +| `agkan task meta get <id> <key>` | Get a metadata value from a task | +| `agkan task meta list <id>` | List all metadata for a task | +| `agkan task meta delete <id> <key>` | Delete a metadata value from a task | +| `agkan task count` | Count tasks by status (`--status`, `--json`) | +| `agkan tag add <name>` | Create a tag | +| `agkan tag list` | List all tags with task counts | +| `agkan tag delete <name>` | Delete a tag | +| `agkan tag attach <task-id> <tag>` | Attach a tag to a task | +| `agkan tag detach <task-id> <tag>` | Detach a tag from a task | +| `agkan tag show <task-id>` | List tags attached to a task | +| `agkan board` | Start the local Kanban board web UI | +| `agkan ps` | List currently running Claude processes | +| `agkan config get [key]` | Show resolved configuration values | +| `agkan --help` | Show all commands | + +For full options, JSON output formats, and worked examples, see **[documentation/cli-reference.md](documentation/cli-reference.md)**. + +## Claude Code Integration + +agkan is designed to be driven by AI coding agents as well as humans: + +- **[agkan-skills](https://github.com/gendosu/agkan-skills)** — Claude Code skills for automated task execution, planning, and review +- **Run / Plan**: each task card in the board has a "Run" button that launches `claude` for that task, with a dropdown to run in plan mode instead +- **Stream modal**: while Claude is running, a modal shows the live output stream in real time, with a "Stop" button and a header indicator for active processes +- **Run Logs**: the task detail panel's "Run Logs" tab keeps the full history of past Claude executions, with timestamps and output +- **`agkan ps`**: from any terminal, list which Claude processes the board currently has running and which tasks they belong to ## Configuration -### Database Storage Location - -agkan allows customization of the database storage location via a configuration file. - -#### Configuration File: `.agkan.yml` - -Create a `.agkan.yml` file in your project root directory to specify the database storage location. - -**Configuration Example:** - -```yaml -# Path to database file -path: ./.agkan/data.db -``` - -#### Path Specification - -- **Relative Path**: Resolved relative to the current directory - ```yaml - path: ./data/kanban.db - path: ./.agkan/data.db - ``` - -- **Absolute Path**: Used as-is - ```yaml - path: /home/user/.config/akan/data.db - ``` - -#### Environment Variable Configuration - -agkan supports the `AGENT_KANBAN_DB_PATH` environment variable for specifying the database location. This is particularly useful in CI/CD environments and for managing multiple environments. - -**Setting the Environment Variable:** - -```bash -# Use a custom database path -export AGENT_KANBAN_DB_PATH=/path/to/your/database.db -agkan task list - -# Use absolute path -export AGENT_KANBAN_DB_PATH=/home/user/.config/akan/data.db - -# Use relative path -export AGENT_KANBAN_DB_PATH=./custom/location/data.db -``` - -**Priority Order:** - -The database path is resolved in the following priority order: - -**Normal Mode (when `NODE_ENV` is not `test`):** -1. **Environment Variable** (highest priority): `AGENT_KANBAN_DB_PATH` -2. **Configuration File** (fallback): `path` field in `.agkan.yml` -3. **Default Path** (lowest priority): `.agkan/data.db` - -**Test Mode (when `NODE_ENV=test`):** -1. **Environment Variable** (highest priority): `AGENT_KANBAN_DB_PATH` -2. **Configuration File** (fallback): `path` field in `.agkan-test.yml` -3. **Default Path** (lowest priority): `.agkan-test/data.db` - -**Test Mode Explanation:** - -Test mode (`NODE_ENV=test`) automatically isolates test data from production data: - -- Uses separate configuration file: `.agkan-test.yml` instead of `.agkan.yml` -- Uses separate default directory: `.agkan-test/` instead of `.agkan/` -- Environment variable still takes highest priority in test mode -- Prevents accidental mixing of test and production data - -**Use Cases:** - -1. **CI/CD Pipeline:** - ```bash - # Use temporary database for CI tests - export AGENT_KANBAN_DB_PATH=/tmp/ci-test-db.db - agkan task list - ``` - -2. **Multiple Environments:** - ```bash - # Development environment - export AGENT_KANBAN_DB_PATH=./dev/data.db - - # Staging environment - export AGENT_KANBAN_DB_PATH=./staging/data.db - - # Production environment - export AGENT_KANBAN_DB_PATH=./prod/data.db - ``` - -3. **Testing:** - ```bash - # Automated tests with isolated database - NODE_ENV=test pnpm test - # Uses .agkan-test/data.db by default - - # Override with custom test database - NODE_ENV=test AGENT_KANBAN_DB_PATH=/tmp/test.db pnpm test - ``` - -#### Default Behavior - -If no `.agkan.yml` file exists and no environment variable is set, the database is created in: - -``` -<current-directory>/.agkan/data.db -``` - -In test mode (`NODE_ENV=test`), the default location is: - -``` -<current-directory>/.agkan-test/data.db -``` - -#### Per-Project Management - -To manage separate tasks for different projects, place `.agkan.yml` in each project root: - -```bash -# Project A -cd /path/to/projectA -cat > .agkan.yml << EOF -path: ./.agkan/data.db -EOF - -# Project B -cd /path/to/projectB -cat > .agkan.yml << EOF -path: ./.agkan/data.db -EOF -``` - -This enables independent task management for each project. - -### Board Settings - -The `board` section in `.agkan.yml` allows you to customize the behavior of the `agkan board` command. - -#### Available Fields - -| Field | Type | Default | Description | -|-------|------|---------|-------------| -| `board.port` | number | `3000` | Port number for the board web server | -| `board.title` | string | `"agkan Board"` | Title displayed in the board UI | - -#### Configuration Example +Customize the database location and board via a `.agkan.yml` file in your project root: ```yaml -# Path to database file path: ./.agkan/data.db -# Board settings board: port: 8080 - title: "My Project Board" -``` - -#### Field Details - -- **`board.port`**: Specifies the TCP port on which the board web server listens. Useful when the default port `3000` is already in use. - ```yaml - board: - port: 8080 - ``` - -- **`board.title`**: Sets the title shown in the board UI. Helps distinguish boards when managing multiple projects. - ```yaml - board: - title: "My Project Board" - ``` - -### Models Settings - -The `models` section in `.agkan.yml` allows you to specify the Claude model and effort level used when executing planning and run commands via the board. - -#### Available Fields - -| Field | Type | Default | Description | -|-------|------|---------|-------------| -| `models.planning.model` | string | (Claude CLI default) | Model used for planning command execution | -| `models.planning.effort` | string | (Claude CLI default) | Effort level for planning command (`low`, `medium`, `high`, `xhigh`, `max`) | -| `models.run.model` | string | (Claude CLI default) | Model used for run/pr command execution | -| `models.run.effort` | string | (Claude CLI default) | Effort level for run/pr command (`low`, `medium`, `high`, `xhigh`, `max`) | - -Both full model names and Claude CLI aliases are supported. Both `model` and `effort` are optional within each entry. - -#### Configuration Example - -```yaml -# Database path -path: ./.agkan/data.db - -# Model settings -models: - planning: - model: claude-opus-4-7 - effort: high - run: - model: claude-sonnet-4-6 - effort: low -``` - -#### Using Aliases - -You can use short aliases instead of full model names: - -```yaml -models: - planning: - model: opus - effort: high - run: - model: sonnet ``` -Supported aliases: `opus`, `sonnet`, `haiku` (resolved by the Claude CLI) +The database path can also be overridden with the `AGENT_KANBAN_DB_PATH` environment variable, which takes priority over `.agkan.yml`. -#### Field Details +In test mode (`NODE_ENV=test`), agkan automatically isolates data using `.agkan-test.yml` and `.agkan-test/` instead, so tests never touch your real task database. -- **`models.planning`**: Specifies the Claude model and effort level used when the board executes planning tasks. Recommended to use a high-capability model and effort level such as `opus` with `high`. - ```yaml - models: - planning: - model: opus - effort: high - ``` +See **[documentation/configuration.md](documentation/configuration.md)** for the full reference, including per-project setup, model selection, and permission modes. -- **`models.run`**: Specifies the Claude model and effort level used when the board executes run or pr commands. The `pr` command also uses this value. - ```yaml - models: - run: - model: sonnet - effort: low - ``` - -### Permission Mode Settings - -The `permissionMode` field in `.agkan.yml` controls how Claude CLI permission checks are handled when executing tasks from the board. - -#### Available Values - -| Value | Claude CLI flag | Description | -|-------|----------------|-------------| -| (not set) | `--permission-mode auto` | Default. Claude uses auto permission mode | -| `auto` | `--permission-mode auto` | Claude uses auto permission mode | -| `bypassPermissions` | `--permission-mode bypassPermissions` | Bypass all permission checks | -| `acceptEdits` | `--permission-mode acceptEdits` | Automatically accept file edits | -| `dontAsk` | `--permission-mode dontAsk` | Do not ask for permissions | -| `plan` | `--permission-mode plan` | Plan-only mode | -| `default` | `--permission-mode default` | Claude default permission mode | -| `skipPermissions` | `--dangerously-skip-permissions` | Legacy flag (same as bypassing all checks) | - -#### Configuration Example - -```yaml -# Use auto permission mode (default) -permissionMode: auto - -# Use legacy --dangerously-skip-permissions flag -permissionMode: skipPermissions -``` - -> **Breaking Change**: Prior to this feature, `--dangerously-skip-permissions` was always passed. The new default is `--permission-mode auto`. To restore the previous behavior, set `permissionMode: skipPermissions` in your `.agkan.yml`. - -## Planned Features - -### Task Attachments - -Task attachment management is currently under development. This feature will allow users to attach files to tasks for better context and documentation. - -**Planned CLI Commands:** -- `agkan task attach add <task-id> <file-path>` - Attach a file to a task -- `agkan task attach list <task-id>` - List all attachments for a task -- `agkan task attach delete <attachment-id>` - Remove an attachment from a task - -For detailed information about planned features, see [documentation/planned-features.md](documentation/planned-features.md). - -## Technology Stack - -- **Language**: TypeScript 5.x -- **CLI Framework**: Commander.js -- **Database**: SQLite3 (better-sqlite3) -- **Terminal Display**: Chalk -- **Web Server**: Hono (for Kanban board viewer) -- **Build Tool**: TypeScript Compiler - -## Project Structure - -See [documentation/project-structure.md](documentation/project-structure.md) for the full directory layout. - -## Database Schema - -See [documentation/database-schema.md](documentation/database-schema.md) for the full schema reference. - -## Development +## Task Statuses -See [documentation/development.md](documentation/development.md) for setup instructions, testing, and build information. +Every task moves through one of seven statuses: + +| Status | Meaning | +|---|---| +| `icebox` | Frozen, not actively being considered | +| `backlog` | Not yet started | +| `ready` | Ready to be started | +| `in_progress` | Currently being worked on | +| `review` | Under review | +| `done` | Completed | +| `closed` | Closed | + +## Documentation + +Detailed reference material lives outside this file: + +| Document | Description | +|---|---| +| [documentation/cli-reference.md](documentation/cli-reference.md) | Full command reference, options, and JSON output formats | +| [documentation/configuration.md](documentation/configuration.md) | `.agkan.yml` reference (paths, board, models, permission mode) | +| [documentation/project-structure.md](documentation/project-structure.md) | Repository directory layout | +| [documentation/database-schema.md](documentation/database-schema.md) | SQLite schema reference | +| [documentation/development.md](documentation/development.md) | Technology stack, local setup, and build information | +| [documentation/TESTING.md](documentation/TESTING.md) | Testing guide | +| [CONTRIBUTING.md](CONTRIBUTING.md) | How to contribute | +| [CHANGELOG.md](CHANGELOG.md) | Release history | ## License diff --git a/docs/assets/readme-board.png b/docs/assets/readme-board.png new file mode 100644 index 00000000..834099a5 Binary files /dev/null and b/docs/assets/readme-board.png differ diff --git a/documentation/cli-reference.ja.md b/documentation/cli-reference.ja.md new file mode 100644 index 00000000..9e564f6b --- /dev/null +++ b/documentation/cli-reference.ja.md @@ -0,0 +1,819 @@ +# CLIリファレンス + +agkanの全コマンド・オプション・JSON出力フォーマットを網羅したリファレンスです。 + +## 目次 + +- [使用方法](#使用方法) + - [プロジェクトの初期化](#プロジェクトの初期化) + - [タスクの作成](#タスクの作成) + - [タスク一覧の表示](#タスク一覧の表示) + - [タスクの検索](#タスクの検索) + - [タスク詳細の取得](#タスク詳細の取得) + - [タスクの更新](#タスクの更新) + - [親子関係の管理](#親子関係の管理) + - [ブロック関係の管理](#ブロック関係の管理) + - [タスクの削除](#タスクの削除) + - [タグ管理](#タグ管理) + - [タスクへのタグ付け](#タスクへのタグ付け) + - [メタデータの管理](#メタデータの管理) + - [タスクのカウント](#タスクのカウント) + - [カンバンボード (Web UI)](#カンバンボード-web-ui) + - [Claudeプロセスの状態確認](#claudeプロセスの状態確認) + - [設定確認](#設定確認) + - [ヘルプの表示](#ヘルプの表示) +- [JSON出力フォーマット](#json出力フォーマット) + - [対応コマンド](#対応コマンド) + - [出力構造](#出力構造) + - [一般的な使用例](#一般的な使用例) +- [使用例](#使用例) + - [親子関係を使った階層的なタスク管理](#親子関係を使った階層的なタスク管理) + - [ブロック関係を使った依存関係の管理](#ブロック関係を使った依存関係の管理) + - [タグを使ったタスク管理](#タグを使ったタスク管理) + +## 使用方法 + +### プロジェクトの初期化 + +プロジェクトディレクトリで `agkan init` を実行して agkan をセットアップします: + +```bash +agkan init +``` + +以下のファイルが作成されます: +- `.agkan.yml` — 設定ファイル +- `.agkan/` — データディレクトリ + +`agkan init` は `.claude/settings.local.json` に SessionStart hook も登録し、 +Claude Code のセッション開始時に最小限の agkan 使用ガイドを自動でロードします。 +hook は `agkan context --hook` を呼び出します。既存設定との競合を避けるため +冪等にマージし、関係のないキーには触れません。Claude Code を使わない場合は +生成されたファイルを無視しても問題ありません。 + +### タスクの作成 + +基本的なタスク作成: +```bash +agkan task add "タスクのタイトル" "タスクの説明" +``` + +オプション付きでタスク作成: +```bash +agkan task add "ログイン機能の実装" "ユーザー認証システムを実装" \ + --status ready \ + --author "developer-name" +``` + +親タスクを指定してタスク作成: +```bash +agkan task add "子タスク" "詳細な作業項目" --parent 1 +``` + +Markdownファイルからタスク作成: +```bash +agkan task add "設計書レビュー" --file ./design-doc.md --status backlog +``` + +タグ付きでタスク作成（カンマ区切りのタグ名またはID、同じコマンドで付与）: +```bash +agkan task add "ログイン機能の実装" --tag "frontend,urgent" +``` + +JSON出力フォーマット: +```bash +agkan task add "Fix bug in login" --json +``` + +```json +{ + "success": true, + "task": { + "id": 1, + "title": "Fix bug in login", + "status": "backlog", + "body": null, + "author": null, + "parent_id": null, + "created_at": "2026-02-15T00:00:00.000Z", + "updated_at": "2026-02-15T00:00:00.000Z" + }, + "parent": null, + "blockedBy": [], + "blocking": [] +} +``` + +### タスク一覧の表示 + +全タスクを表示: +```bash +agkan task list +``` + +ツリー形式で表示（親子関係を含む）: +```bash +agkan task list --tree +``` + +ルートタスクのみ表示（親を持たないタスク）: +```bash +agkan task list --root-only +``` + +ステータスでフィルタリング: +```bash +agkan task list --status in_progress +``` + +作成者でフィルタリング: +```bash +agkan task list --author "developer-name" +``` + +複合フィルター: +```bash +agkan task list --status ready --author "developer-name" +``` + +タグでフィルタリング: +```bash +agkan task list --tag "frontend" +``` + +JSON出力フォーマット: +```bash +agkan task list --json +``` + +```json +{ + "tasks": [ + { + "id": 1, + "title": "Implement login feature", + "status": "in_progress", + "body": "Implement user authentication system", + "author": "developer-name", + "parent_id": null, + "created_at": "2026-02-15T00:00:00.000Z", + "updated_at": "2026-02-15T00:00:00.000Z" + }, + { + "id": 2, + "title": "Design review", + "status": "backlog", + "body": null, + "author": null, + "parent_id": null, + "created_at": "2026-02-15T00:00:00.000Z", + "updated_at": "2026-02-15T00:00:00.000Z" + } + ] +} +``` + +### タスクの検索 + +キーワードでタスクを検索（タイトルと本文を対象）: +```bash +agkan task find "検索キーワード" +``` + +完了済みタスクも含めて検索: +```bash +agkan task find "検索キーワード" --all +``` + +注: デフォルトでは、`done`と`closed`のタスクは検索結果から除外されます。 + +JSON出力フォーマット: +```bash +agkan task find "login" --json +``` + +```json +{ + "tasks": [ + { + "id": 1, + "title": "Implement login feature", + "status": "in_progress", + "body": "Implement user authentication system", + "author": "developer-name", + "parent_id": null, + "created_at": "2026-02-15T00:00:00.000Z", + "updated_at": "2026-02-15T00:00:00.000Z" + } + ] +} +``` + +### タスク詳細の取得 + +```bash +agkan task get 1 +``` + +JSON出力フォーマット: +```bash +agkan task get 1 --json +``` + +```json +{ + "task": { + "id": 1, + "title": "Implement login feature", + "status": "in_progress", + "body": "Implement user authentication system", + "author": "developer-name", + "parent_id": null, + "created_at": "2026-02-15T00:00:00.000Z", + "updated_at": "2026-02-15T00:00:00.000Z" + } +} +``` + +### タスクの更新 + +ステータスを変更: +```bash +agkan task update 1 status done +``` + +タイトルを変更: +```bash +agkan task update 1 title "新しいタイトル" +``` + +本文を変更: +```bash +agkan task update 1 body "新しい説明文" +``` + +作成者を変更: +```bash +agkan task update 1 author "new-author" +``` + +### 親子関係の管理 + +親タスクの更新: +```bash +# タスク2の親をタスク1に設定 +agkan task update-parent 2 1 + +# タスク2の親を解除（孤立化） +agkan task update-parent 2 null +``` + +注意事項: +- 親タスクを削除すると、子タスクの親参照は自動的に解除されます（孤立化） +- 循環参照は自動的に検出され、エラーとなります + +JSON出力フォーマット: +```bash +agkan task update-parent 2 1 --json +``` + +```json +{ + "success": true, + "task": { + "id": 2, + "title": "Child Task", + "status": "backlog", + "body": null, + "author": null, + "parent_id": 1, + "created_at": "2026-02-15T00:00:00.000Z", + "updated_at": "2026-02-15T00:00:00.000Z" + }, + "parent": { + "id": 1, + "title": "Parent Task", + "status": "backlog", + "body": null, + "author": null, + "parent_id": null, + "created_at": "2026-02-15T00:00:00.000Z", + "updated_at": "2026-02-15T00:00:00.000Z" + } +} +``` + +### ブロック関係の管理 + +ブロック関係の追加（タスク1がタスク2をブロック）: +```bash +agkan task block add 1 2 +``` + +ブロック関係の削除: +```bash +agkan task block remove 1 2 +``` + +ブロック関係の一覧表示: +```bash +# タスク1に関連するブロック関係を表示 +agkan task block list 1 +``` + +注意事項: +- 循環参照は自動的に検出され、エラーとなります +- ブロック関係はタスク削除時に自動的に削除されます（CASCADE DELETE） + +JSON出力フォーマット: +```bash +agkan task block list 2 --json +``` + +```json +{ + "task": { + "id": 2, + "title": "API implementation", + "status": "backlog" + }, + "blockedBy": [ + { + "id": 1, + "title": "Database design", + "status": "in_progress" + } + ], + "blocking": [ + { + "id": 3, + "title": "Frontend implementation", + "status": "backlog" + } + ] +} +``` + +### タスクの削除 + +タスクを削除: +```bash +agkan task delete 1 +``` + +### タグ管理 + +タグを作成: +```bash +agkan tag add "frontend" +``` + +タグ一覧を表示: +```bash +agkan tag list +``` + +タグを削除: +```bash +agkan tag delete "frontend" +``` + +タグ一覧のJSON出力フォーマット: +```bash +agkan tag list --json +``` + +```json +{ + "totalCount": 2, + "tags": [ + { + "id": 1, + "name": "frontend", + "taskCount": 3, + "created_at": "2026-02-15T00:00:00.000Z" + }, + { + "id": 2, + "name": "backend", + "taskCount": 1, + "created_at": "2026-02-15T00:00:00.000Z" + } + ] +} +``` + +### タスクへのタグ付け + +タスクにタグを付与: +```bash +agkan tag attach 1 "frontend" +``` + +または `task add --tag` でタスク作成と同時にタグを付与（`tag attach` を別途実行する必要がない）: +```bash +agkan task add "ログイン画面の実装" --tag "frontend,urgent" +``` + +タスクからタグを削除: +```bash +agkan tag detach 1 "frontend" +``` + +タスクに付けられたタグを表示: +```bash +agkan tag show 1 +``` + +タグ表示のJSON出力フォーマット: +```bash +agkan tag show 1 --json +``` + +```json +{ + "task": { + "id": 1, + "title": "Implement login screen", + "status": "in_progress" + }, + "tags": [ + { + "id": 1, + "name": "frontend", + "created_at": "2026-02-15T00:00:00.000Z" + }, + { + "id": 3, + "name": "urgent", + "created_at": "2026-02-15T00:00:00.000Z" + } + ] +} +``` + +### メタデータの管理 + +メタデータを設定: +```bash +agkan task meta set 1 priority high +``` + +メタデータを取得: +```bash +agkan task meta get 1 priority +``` + +メタデータ一覧を表示: +```bash +agkan task meta list 1 +``` + +メタデータを削除: +```bash +agkan task meta delete 1 priority +``` + +#### 優先度 (priority) + +タスクの優先度は `priority` キーで管理します: + +| 値 | 意味 | +|-----|------| +| `critical` | 即時対応が必要。ブロッカーとなっている問題 | +| `high` | 優先して着手すべきタスク | +| `medium` | 通常の優先度（デフォルト） | +| `low` | 余裕があれば対応するタスク | + +### タスクのカウント + +全ステータスのタスク数を表示: +```bash +agkan task count +``` + +特定のステータスのタスク数を表示: +```bash +agkan task count --status in_progress +``` + +スクリプト用の出力（数値のみ）: +```bash +agkan task count -s in_progress -q +``` + +全ステータスのJSON出力フォーマット: +```bash +agkan task count --json +``` + +```json +{ + "total": 10, + "counts": { + "backlog": 3, + "ready": 2, + "in_progress": 4, + "done": 1, + "closed": 0 + } +} +``` + +特定ステータスのJSON出力フォーマット: +```bash +agkan task count --status in_progress --json +``` + +```json +{ + "status": "in_progress", + "count": 4 +} +``` + +### カンバンボード (Web UI) + +ブラウザでローカルのカンバンボードビューアを起動: +```bash +agkan board +``` + +カスタムポートを指定: +```bash +agkan board -p 3000 +``` + +デフォルトでは `http://localhost:8080` でボードが提供されます。 + +#### ボードのClaude連携機能 + +ボードUIにはブラウザから直接Claudeを実行するための機能が組み込まれています: + +- **Runボタン**: タスクカードにある「Run」ボタンをクリックすると、そのタスクに対して `claude` を起動します。ボタン横のドロップダウンからプランモードで実行することもできます。 +- **Planボタン**: タスクを実行せずに計画のみを生成するプランモードで `claude` を起動します。 +- **ストリームモーダル**: Claude実行中はモーダルウィンドウにリアルタイムで出力が表示されます。「Stop」ボタンでプロセスを終了できます。 +- **実行中インジケーター**: Claudeプロセスが動作中の場合、ヘッダーにインジケーターが表示されます。 +- **実行ログタブ**: タスク詳細パネルの「Run Logs」タブに、過去のClaude実行履歴（タイムスタンプと全出力）が表示されます。 + +### Claudeプロセスの状態確認 + +現在実行中のClaudeプロセスを一覧表示します（ボードサーバーが起動している必要があります）: +```bash +agkan ps +``` + +カスタムポートのボードサーバーに接続: +```bash +agkan ps --port 3000 +``` + +このコマンドはボードサーバーに問い合わせて、現在実行中のClaudeプロセスとそれに関連するタスクを表示します。 + +JSON出力フォーマット: +```bash +agkan ps --json +``` +```json +{ + "processes": [ + { + "taskId": 42, + "title": "機能Xの実装", + "command": "claude" + } + ] +} +``` + +### 設定確認 + +`.agkan.yml` の設定値（デフォルト適用後の解決済み値）を取得します: + +```bash +agkan config get # 全設定を表示 +agkan config get board.port # 特定キーを取得（ドット記法） +agkan config get --json # JSON出力 +``` + +出力例: +``` +✓ Resolved config + +path: /workspace/.agkan/data.db +board.port: 8080 +``` + +### ヘルプの表示 + +コマンド一覧: +```bash +agkan --help +``` + +タスクコマンドのヘルプ: +```bash +agkan task --help +``` + +個別コマンドのヘルプ: +```bash +agkan task add --help +``` + +## JSON出力フォーマット + +agkanは10のデータ取得・表示コマンドで、機械可読なJSON出力をサポートしています。`--json`フラグを追加することで、人間が読みやすいテキストの代わりに構造化されたデータを出力できます。 + +### 対応コマンド + +以下のコマンドがJSON出力をサポートしています: + +- `task add` - 新しいタスクを作成 +- `task list` - タスク一覧を表示（フィルタリング付き） +- `task get` - タスク詳細を取得 +- `task find` - キーワードでタスクを検索 +- `task count` - ステータス別のタスク数をカウント +- `task update-parent` - 親子関係を更新 +- `task block list` - ブロック関係を一覧表示 +- `task tag list` - 全タグをタスク数と共に一覧表示 +- `task tag show` - 特定のタスクのタグを表示 +- `task meta list` - タスクのメタデータ一覧を表示 +- `ps` - 現在実行中のClaudeプロセスを一覧表示 + +### 出力構造 + +すべてのJSONレスポンスは以下のパターンに従います: + +**成功レスポンス**には以下が含まれます: +- 操作固有のデータ（task、tasksの配列、counts など） +- 関連データ（parent、blockedBy、blocking、tags など） +- 書き込み操作の場合はオプションで`success: true`フィールド + +**エラーレスポンス**は以下のフォーマットに従います: +```json +{ + "success": false, + "error": { + "message": "エラーの説明" + } +} +``` + +### 一般的な使用例 + +**1. スクリプティングと自動化** +```bash +# CI/CDパイプライン用のタスク数を取得 +TASK_COUNT=$(agkan task count --status backlog --json | jq '.counts.backlog') + +# 処理用にタスクIDを抽出 +agkan task list --status ready --json | jq -r '.tasks[].id' +``` + +**2. 他ツールとの統合** +```bash +# タスクを外部システムにエクスポート +agkan task list --json | jq '.tasks' > tasks.json + +# ブロック関係を処理 +agkan task block list 1 --json | jq '.blockedBy[].title' +``` + +**3. 検証とテスト** +```bash +# タスク作成を検証 +RESULT=$(agkan task add "Test" --json) +echo $RESULT | jq -e '.success == true' && echo "Success" +``` + +## 使用例 + +### 親子関係を使った階層的なタスク管理 + +プロジェクトを親タスク、個別の作業を子タスクとして管理する例: + +```bash +# 親タスクを作成 +agkan task add "Webサイトのリニューアル" +# 出力: Task created with ID: 1 + +# 子タスクを作成 +agkan task add "デザインカンプ作成" --parent 1 +agkan task add "フロントエンド実装" --parent 1 +agkan task add "バックエンド実装" --parent 1 + +# ツリー形式で表示 +agkan task list --tree +# 出力: +# 1 [backlog] Webサイトのリニューアル +# ├─ 2 [backlog] デザインカンプ作成 +# ├─ 3 [backlog] フロントエンド実装 +# └─ 4 [backlog] バックエンド実装 + +# タスク詳細を表示（親情報を含む） +agkan task get 2 +# 出力: +# ID: 2 +# Title: デザインカンプ作成 +# Parent ID: 1 +# ... + +# 親を変更 +agkan task add "UI/UX改善" +# 出力: Task created with ID: 5 +agkan task update-parent 2 5 + +# 親を解除（孤立化） +agkan task update-parent 2 null +``` + +### ブロック関係を使った依存関係の管理 + +タスク間の依存関係を明示的に管理する例: + +```bash +# タスクを作成 +agkan task add "データベース設計" +# 出力: Task created with ID: 1 + +agkan task add "API実装" +# 出力: Task created with ID: 2 + +agkan task add "フロントエンド実装" +# 出力: Task created with ID: 3 + +# ブロック関係を設定（1がデータベース設計、2がAPI実装、3がフロントエンド実装） +# データベース設計がAPI実装をブロック +agkan task block add 1 2 + +# API実装がフロントエンド実装をブロック +agkan task block add 2 3 + +# ブロック関係を確認 +agkan task block list 1 +# 出力: +# Task 1 blocks: +# - Task 2 (API実装) +# Task 1 is blocked by: +# (none) + +agkan task block list 2 +# 出力: +# Task 2 blocks: +# - Task 3 (フロントエンド実装) +# Task 2 is blocked by: +# - Task 1 (データベース設計) + +# 循環参照を試みる（エラーになる） +agkan task block add 3 1 +# 出力: Error: Circular reference detected + +# ブロック関係を削除 +agkan task block remove 1 2 +``` + +### タグを使ったタスク管理 + +タスクにタグを付けて分類する例: + +```bash +# タグを作成 +agkan tag add "frontend" +agkan tag add "backend" +agkan tag add "urgent" + +# タスクを作成してタグを付与 +agkan task add "ログイン画面の実装" +# 出力: Task created with ID: 1 + +agkan tag attach 1 "frontend" +agkan tag attach 1 "urgent" + +agkan task add "API開発" +# 出力: Task created with ID: 2 + +agkan tag attach 2 "backend" + +# --tag を使えば同じコマンドでタグを付与できる +agkan task add "決済フローのバグ修正" --tag "backend,urgent" +# 出力: Task created with ID: 3 + +# タグでフィルタリング +agkan task list --tag "frontend" +# 出力: +# 1 [backlog] ログイン画面の実装 (tags: frontend, urgent) + +# タスクのタグを確認 +agkan tag show 1 +# 出力: +# Tags for task 1: +# - frontend +# - urgent + +# タグを削除 +agkan tag detach 1 "urgent" + +# タグ自体を削除（関連するすべてのタスクから削除される） +agkan tag delete "urgent" +``` diff --git a/documentation/cli-reference.md b/documentation/cli-reference.md new file mode 100644 index 00000000..a577157e --- /dev/null +++ b/documentation/cli-reference.md @@ -0,0 +1,819 @@ +# CLI Reference + +Full command reference for agkan, including every subcommand, its options, and JSON output formats. + +## Table of Contents + +- [Usage](#usage) + - [Initialize a Project](#initialize-a-project) + - [Create Tasks](#create-tasks) + - [List Tasks](#list-tasks) + - [Search Tasks](#search-tasks) + - [Get Task Details](#get-task-details) + - [Update Tasks](#update-tasks) + - [Manage Parent-Child Relationships](#manage-parent-child-relationships) + - [Manage Blocking Relationships](#manage-blocking-relationships) + - [Delete Tasks](#delete-tasks) + - [Manage Tags](#manage-tags) + - [Attach Tags to Tasks](#attach-tags-to-tasks) + - [Manage Metadata](#manage-metadata) + - [Count Tasks](#count-tasks) + - [Kanban Board (Web UI)](#kanban-board-web-ui) + - [Claude Process Status](#claude-process-status) + - [Config](#config) + - [Display Help](#display-help) +- [JSON Output Format](#json-output-format) + - [Supported Commands](#supported-commands) + - [Output Structure](#output-structure) + - [Common Use Cases](#common-use-cases) +- [Usage Examples](#usage-examples) + - [Hierarchical Task Management with Parent-Child Relationships](#hierarchical-task-management-with-parent-child-relationships) + - [Managing Dependencies with Blocking Relationships](#managing-dependencies-with-blocking-relationships) + - [Task Management with Tags](#task-management-with-tags) + +## Usage + +### Initialize a Project + +Run `agkan init` in your project directory to set up agkan: + +```bash +agkan init +``` + +This creates: +- `.agkan.yml` — configuration file +- `.agkan/` — data directory + +`agkan init` also installs a SessionStart hook into `.claude/settings.local.json` +so that Claude Code automatically loads a minimal agkan usage brief at the +start of every session. The hook calls `agkan context --hook`. This step is +idempotent and merges into existing settings without touching unrelated keys. +If you are not using Claude Code, you can safely ignore the generated file. + +### Create Tasks + +Basic task creation: +```bash +agkan task add "Task title" "Task description" +``` + +Create with options: +```bash +agkan task add "Implement login feature" "Implement user authentication system" \ + --status ready \ + --author "developer-name" +``` + +Create with parent task: +```bash +agkan task add "Subtask" "Detailed work item" --parent 1 +``` + +Create from Markdown file: +```bash +agkan task add "Design review" --file ./design-doc.md --status backlog +``` + +Create with tags (comma-separated names or IDs, attached in the same command): +```bash +agkan task add "Implement login feature" --tag "frontend,urgent" +``` + +JSON output format: +```bash +agkan task add "Fix bug in login" --json +``` + +```json +{ + "success": true, + "task": { + "id": 1, + "title": "Fix bug in login", + "status": "backlog", + "body": null, + "author": null, + "parent_id": null, + "created_at": "2026-02-15T00:00:00.000Z", + "updated_at": "2026-02-15T00:00:00.000Z" + }, + "parent": null, + "blockedBy": [], + "blocking": [] +} +``` + +### List Tasks + +Display all tasks: +```bash +agkan task list +``` + +Display in tree format (including parent-child relationships): +```bash +agkan task list --tree +``` + +Display root tasks only (tasks without parents): +```bash +agkan task list --root-only +``` + +Filter by status: +```bash +agkan task list --status in_progress +``` + +Filter by author: +```bash +agkan task list --author "developer-name" +``` + +Combined filters: +```bash +agkan task list --status ready --author "developer-name" +``` + +Filter by tag: +```bash +agkan task list --tag "frontend" +``` + +JSON output format: +```bash +agkan task list --json +``` + +```json +{ + "tasks": [ + { + "id": 1, + "title": "Implement login feature", + "status": "in_progress", + "body": "Implement user authentication system", + "author": "developer-name", + "parent_id": null, + "created_at": "2026-02-15T00:00:00.000Z", + "updated_at": "2026-02-15T00:00:00.000Z" + }, + { + "id": 2, + "title": "Design review", + "status": "backlog", + "body": null, + "author": null, + "parent_id": null, + "created_at": "2026-02-15T00:00:00.000Z", + "updated_at": "2026-02-15T00:00:00.000Z" + } + ] +} +``` + +### Search Tasks + +Search by keyword (in title and body): +```bash +agkan task find "search keyword" +``` + +Include completed tasks in search: +```bash +agkan task find "search keyword" --all +``` + +Note: By default, `done` and `closed` tasks are excluded from search results. + +JSON output format: +```bash +agkan task find "login" --json +``` + +```json +{ + "tasks": [ + { + "id": 1, + "title": "Implement login feature", + "status": "in_progress", + "body": "Implement user authentication system", + "author": "developer-name", + "parent_id": null, + "created_at": "2026-02-15T00:00:00.000Z", + "updated_at": "2026-02-15T00:00:00.000Z" + } + ] +} +``` + +### Get Task Details + +```bash +agkan task get 1 +``` + +JSON output format: +```bash +agkan task get 1 --json +``` + +```json +{ + "task": { + "id": 1, + "title": "Implement login feature", + "status": "in_progress", + "body": "Implement user authentication system", + "author": "developer-name", + "parent_id": null, + "created_at": "2026-02-15T00:00:00.000Z", + "updated_at": "2026-02-15T00:00:00.000Z" + } +} +``` + +### Update Tasks + +Change status: +```bash +agkan task update 1 status done +``` + +Change title: +```bash +agkan task update 1 title "New title" +``` + +Change body: +```bash +agkan task update 1 body "New description" +``` + +Change author: +```bash +agkan task update 1 author "new-author" +``` + +### Manage Parent-Child Relationships + +Update parent task: +```bash +# Set parent of task 2 to task 1 +agkan task update-parent 2 1 + +# Remove parent (orphan task 2) +agkan task update-parent 2 null +``` + +Notes: +- Deleting a parent task automatically removes the parent reference from child tasks (orphaning them) +- Circular references are automatically detected and prevented + +JSON output format: +```bash +agkan task update-parent 2 1 --json +``` + +```json +{ + "success": true, + "task": { + "id": 2, + "title": "Child Task", + "status": "backlog", + "body": null, + "author": null, + "parent_id": 1, + "created_at": "2026-02-15T00:00:00.000Z", + "updated_at": "2026-02-15T00:00:00.000Z" + }, + "parent": { + "id": 1, + "title": "Parent Task", + "status": "backlog", + "body": null, + "author": null, + "parent_id": null, + "created_at": "2026-02-15T00:00:00.000Z", + "updated_at": "2026-02-15T00:00:00.000Z" + } +} +``` + +### Manage Blocking Relationships + +Add blocking relationship (task 1 blocks task 2): +```bash +agkan task block add 1 2 +``` + +Remove blocking relationship: +```bash +agkan task block remove 1 2 +``` + +List blocking relationships: +```bash +# Show blocking relationships for task 1 +agkan task block list 1 +``` + +Notes: +- Circular references are automatically detected and prevented +- Blocking relationships are automatically deleted when a task is deleted (CASCADE DELETE) + +JSON output format: +```bash +agkan task block list 2 --json +``` + +```json +{ + "task": { + "id": 2, + "title": "API implementation", + "status": "backlog" + }, + "blockedBy": [ + { + "id": 1, + "title": "Database design", + "status": "in_progress" + } + ], + "blocking": [ + { + "id": 3, + "title": "Frontend implementation", + "status": "backlog" + } + ] +} +``` + +### Delete Tasks + +Delete a task: +```bash +agkan task delete 1 +``` + +### Manage Tags + +Create a tag: +```bash +agkan tag add "frontend" +``` + +List all tags: +```bash +agkan tag list +``` + +Delete a tag: +```bash +agkan tag delete "frontend" +``` + +JSON output format for tag list: +```bash +agkan tag list --json +``` + +```json +{ + "totalCount": 2, + "tags": [ + { + "id": 1, + "name": "frontend", + "taskCount": 3, + "created_at": "2026-02-15T00:00:00.000Z" + }, + { + "id": 2, + "name": "backend", + "taskCount": 1, + "created_at": "2026-02-15T00:00:00.000Z" + } + ] +} +``` + +### Attach Tags to Tasks + +Attach a tag to a task: +```bash +agkan tag attach 1 "frontend" +``` + +Or attach tags at creation time with `task add --tag`, instead of a separate `tag attach` call: +```bash +agkan task add "Implement login screen" --tag "frontend,urgent" +``` + +Remove a tag from a task: +```bash +agkan tag detach 1 "frontend" +``` + +Display tags on a task: +```bash +agkan tag show 1 +``` + +JSON output format for tag show: +```bash +agkan tag show 1 --json +``` + +```json +{ + "task": { + "id": 1, + "title": "Implement login screen", + "status": "in_progress" + }, + "tags": [ + { + "id": 1, + "name": "frontend", + "created_at": "2026-02-15T00:00:00.000Z" + }, + { + "id": 3, + "name": "urgent", + "created_at": "2026-02-15T00:00:00.000Z" + } + ] +} +``` + +### Manage Metadata + +Set metadata: +```bash +agkan task meta set 1 priority high +``` + +Get metadata: +```bash +agkan task meta get 1 priority +``` + +List all metadata: +```bash +agkan task meta list 1 +``` + +Delete metadata: +```bash +agkan task meta delete 1 priority +``` + +#### Priority (priority) + +Task priority is managed with the `priority` key: + +| Value | Meaning | +|-------|---------| +| `critical` | Requires immediate action. A blocking issue. | +| `high` | Should be addressed with priority | +| `medium` | Normal priority (default) | +| `low` | Address when time permits | + +### Count Tasks + +Display task count for all statuses: +```bash +agkan task count +``` + +Display task count for a specific status: +```bash +agkan task count --status in_progress +``` + +Script-friendly output (numbers only): +```bash +agkan task count -s in_progress -q +``` + +JSON output format for all statuses: +```bash +agkan task count --json +``` + +```json +{ + "total": 10, + "counts": { + "backlog": 3, + "ready": 2, + "in_progress": 4, + "done": 1, + "closed": 0 + } +} +``` + +JSON output format for specific status: +```bash +agkan task count --status in_progress --json +``` + +```json +{ + "status": "in_progress", + "count": 4 +} +``` + +### Kanban Board (Web UI) + +Start a local Kanban board viewer in your browser: +```bash +agkan board +``` + +Specify a custom port: +```bash +agkan board -p 3000 +``` + +The board is served at `http://localhost:8080` by default. + +#### Claude Integration in the Board + +The board UI includes built-in Claude integration for running tasks directly from the browser: + +- **Run button**: Each task card has a "Run" button that launches `claude` for that task. A dropdown arrow next to the button also allows running in plan mode. +- **Plan button**: Runs `claude` in plan mode to generate a plan for the task without executing. +- **Stream modal**: When Claude is running, a modal window displays the live output stream in real time. A "Stop" button allows terminating the process. +- **Running indicator**: A header indicator shows when any Claude process is currently active. +- **Run Logs tab**: The task detail panel includes a "Run Logs" tab that shows the history of all past Claude executions for that task, with timestamps and full output. + +### Claude Process Status + +List currently executing Claude processes (requires the board server to be running): +```bash +agkan ps +``` + +Connect to a board server on a custom port: +```bash +agkan ps --port 3000 +``` + +This command queries the board server to show which Claude processes are currently running and which tasks they are associated with. + +JSON output format: +```bash +agkan ps --json +``` +```json +{ + "processes": [ + { + "taskId": 42, + "title": "Implement feature X", + "command": "claude" + } + ] +} +``` + +### Config + +Get resolved configuration values from `.agkan.yml` (defaults applied): + +```bash +agkan config get # Show full resolved config +agkan config get board.port # Show specific key (dot notation) +agkan config get --json # JSON output +``` + +Example output: +``` +✓ Resolved config + +path: /workspace/.agkan/data.db +board.port: 8080 +``` + +### Display Help + +Show command list: +```bash +agkan --help +``` + +Show task command help: +```bash +agkan task --help +``` + +Show help for specific command: +```bash +agkan task add --help +``` + +## JSON Output Format + +agkan supports machine-readable JSON output for 10 data retrieval and display commands. Add the `--json` flag to output structured data instead of human-readable text. + +### Supported Commands + +The following commands support JSON output: + +- `task add` - Create a new task +- `task list` - List tasks (with filtering) +- `task get` - Get task details +- `task find` - Search tasks by keyword +- `task count` - Count tasks by status +- `task update-parent` - Update parent-child relationship +- `task block list` - List blocking relationships +- `task tag list` - List all tags with task counts +- `task tag show` - Show tags for a specific task +- `task meta list` - List all metadata for a task +- `ps` - List currently executing Claude processes + +### Output Structure + +All JSON responses follow these patterns: + +**Success responses** include: +- Operation-specific data (task, tasks array, counts, etc.) +- Related data (parent, blockedBy, blocking, tags, etc.) +- Optional `success: true` field for write operations + +**Error responses** follow the format: +```json +{ + "success": false, + "error": { + "message": "Error description" + } +} +``` + +### Common Use Cases + +**1. Scripting and Automation** +```bash +# Get task count for CI/CD pipeline +TASK_COUNT=$(agkan task count --status backlog --json | jq '.counts.backlog') + +# Extract task IDs for processing +agkan task list --status ready --json | jq -r '.tasks[].id' +``` + +**2. Integration with Other Tools** +```bash +# Export tasks to external system +agkan task list --json | jq '.tasks' > tasks.json + +# Process blocking relationships +agkan task block list 1 --json | jq '.blockedBy[].title' +``` + +**3. Validation and Testing** +```bash +# Verify task creation +RESULT=$(agkan task add "Test" --json) +echo $RESULT | jq -e '.success == true' && echo "Success" +``` + +## Usage Examples + +### Hierarchical Task Management with Parent-Child Relationships + +Example of managing a project as a parent task with individual work items as children: + +```bash +# Create parent task +agkan task add "Website redesign" +# Output: Task created with ID: 1 + +# Create child tasks +agkan task add "Create design mockup" --parent 1 +agkan task add "Implement frontend" --parent 1 +agkan task add "Implement backend" --parent 1 + +# Display in tree format +agkan task list --tree +# Output: +# 1 [backlog] Website redesign +# ├─ 2 [backlog] Create design mockup +# ├─ 3 [backlog] Implement frontend +# └─ 4 [backlog] Implement backend + +# Display task details (including parent information) +agkan task get 2 +# Output: +# ID: 2 +# Title: Create design mockup +# Parent ID: 1 +# ... + +# Change parent +agkan task add "UI/UX improvements" +# Output: Task created with ID: 5 +agkan task update-parent 2 5 + +# Remove parent (orphan task) +agkan task update-parent 2 null +``` + +### Managing Dependencies with Blocking Relationships + +Example of explicitly managing task dependencies: + +```bash +# Create tasks +agkan task add "Database design" +# Output: Task created with ID: 1 + +agkan task add "API implementation" +# Output: Task created with ID: 2 + +agkan task add "Frontend implementation" +# Output: Task created with ID: 3 + +# Set blocking relationships (1 blocks 2, 2 blocks 3) +# Database design blocks API implementation +agkan task block add 1 2 + +# API implementation blocks Frontend implementation +agkan task block add 2 3 + +# Verify blocking relationships +agkan task block list 1 +# Output: +# Task 1 blocks: +# - Task 2 (API implementation) +# Task 1 is blocked by: +# (none) + +agkan task block list 2 +# Output: +# Task 2 blocks: +# - Task 3 (Frontend implementation) +# Task 2 is blocked by: +# - Task 1 (Database design) + +# Attempt circular reference (error) +agkan task block add 3 1 +# Output: Error: Circular reference detected + +# Remove blocking relationship +agkan task block remove 1 2 +``` + +### Task Management with Tags + +Example of classifying tasks with tags: + +```bash +# Create tags +agkan tag add "frontend" +agkan tag add "backend" +agkan tag add "urgent" + +# Create tasks and attach tags +agkan task add "Implement login screen" +# Output: Task created with ID: 1 + +agkan tag attach 1 "frontend" +agkan tag attach 1 "urgent" + +agkan task add "API development" +# Output: Task created with ID: 2 + +agkan tag attach 2 "backend" + +# Or attach tags in the same command with --tag +agkan task add "Bug fix in payment flow" --tag "backend,urgent" +# Output: Task created with ID: 3 + +# Filter by tag +agkan task list --tag "frontend" +# Output: +# 1 [backlog] Implement login screen (tags: frontend, urgent) + +# Display task tags +agkan tag show 1 +# Output: +# Tags for task 1: +# - frontend +# - urgent + +# Remove a tag +agkan tag detach 1 "urgent" + +# Delete a tag (removes from all associated tasks) +agkan tag delete "urgent" +``` diff --git a/documentation/configuration.ja.md b/documentation/configuration.ja.md new file mode 100644 index 00000000..bc9d910e --- /dev/null +++ b/documentation/configuration.ja.md @@ -0,0 +1,266 @@ +# 設定 + +`.agkan.yml` の全フィールド・データベースパスの解決順序・テストモードの挙動・プロジェクトごとの管理方法を網羅した設定リファレンスです。 + +## 目次 + +- [データベースの保存場所](#データベースの保存場所) + - [設定ファイル: `.agkan.yml`](#設定ファイル-agkanyml) + - [パスの指定方法](#パスの指定方法) + - [環境変数による設定](#環境変数による設定) + - [デフォルトの動作](#デフォルトの動作) + - [プロジェクトごとの管理](#プロジェクトごとの管理) +- [ボード設定](#ボード設定) +- [モデル設定](#モデル設定) +- [パーミッションモード設定](#パーミッションモード設定) + +## データベースの保存場所 + +agkanは、データベースの保存場所を設定ファイルでカスタマイズできます。 + +### 設定ファイル: `.agkan.yml` + +プロジェクトのルートディレクトリに`.agkan.yml`ファイルを作成することで、データベースの保存場所を指定できます。 + +**設定例:** + +```yaml +# データベースファイルのパス +path: ./.agkan/data.db +``` + +### パスの指定方法 + +- **相対パス**: カレントディレクトリからの相対パスとして解決されます + ```yaml + path: ./data/kanban.db + path: ./.agkan/data.db + ``` + +- **絶対パス**: そのままのパスが使用されます + ```yaml + path: /home/user/.config/agkan/data.db + ``` + +### 環境変数による設定 + +agkanは `AGENT_KANBAN_DB_PATH` 環境変数によるデータベースの場所指定をサポートしています。CI/CD環境や複数環境の管理に特に有用です。 + +**環境変数の設定例:** + +```bash +# カスタムデータベースパスを使用 +export AGENT_KANBAN_DB_PATH=/path/to/your/database.db +agkan task list + +# 絶対パスを使用 +export AGENT_KANBAN_DB_PATH=/home/user/.config/agkan/data.db + +# 相対パスを使用 +export AGENT_KANBAN_DB_PATH=./custom/location/data.db +``` + +**優先順位:** + +データベースパスは以下の優先順位で解決されます: + +**通常モード (`NODE_ENV` が `test` でない場合):** +1. **環境変数**（最高優先）: `AGENT_KANBAN_DB_PATH` +2. **設定ファイル**（フォールバック）: `.agkan.yml` の `path` フィールド +3. **デフォルトパス**（最低優先）: `.agkan/data.db` + +**テストモード (`NODE_ENV=test` の場合):** +1. **環境変数**（最高優先）: `AGENT_KANBAN_DB_PATH` +2. **設定ファイル**（フォールバック）: `.agkan-test.yml` の `path` フィールド +3. **デフォルトパス**（最低優先）: `.agkan-test/data.db` + +**テストモードについて:** + +テストモード（`NODE_ENV=test`）では、テストデータと本番データを自動的に分離します: + +- 別の設定ファイルを使用: `.agkan.yml` の代わりに `.agkan-test.yml` +- 別のデフォルトディレクトリを使用: `.agkan/` の代わりに `.agkan-test/` +- テストモードでも環境変数が最高優先になります + +**使用例:** + +```bash +# CI/CDパイプライン（一時DBを使用） +export AGENT_KANBAN_DB_PATH=/tmp/ci-test-db.db +agkan task list + +# 複数環境の管理 +export AGENT_KANBAN_DB_PATH=./dev/data.db # 開発環境 +export AGENT_KANBAN_DB_PATH=./staging/data.db # ステージング環境 + +# テストの実行 +NODE_ENV=test pnpm test +# デフォルトで .agkan-test/data.db を使用 + +# カスタムテストDBで実行 +NODE_ENV=test AGENT_KANBAN_DB_PATH=/tmp/test.db pnpm test +``` + +### デフォルトの動作 + +`.agkan.yml`ファイルが存在せず、環境変数も設定されていない場合、データベースは以下の場所に作成されます： + +``` +<カレントディレクトリ>/.agkan/data.db +``` + +テストモード（`NODE_ENV=test`）の場合のデフォルト: + +``` +<カレントディレクトリ>/.agkan-test/data.db +``` + +### プロジェクトごとの管理 + +プロジェクトごとに異なるタスク管理を行いたい場合は、各プロジェクトのルートに`.agkan.yml`を配置してください： + +```bash +# プロジェクトA +cd /path/to/projectA +cat > .agkan.yml << EOF +path: ./.agkan/data.db +EOF + +# プロジェクトB +cd /path/to/projectB +cat > .agkan.yml << EOF +path: ./.agkan/data.db +EOF +``` + +これにより、各プロジェクトで独立したタスク管理が可能になります。 + +## ボード設定 + +`.agkan.yml` の `board` セクションでは、`agkan board` コマンドの動作をカスタマイズできます。 + +### 利用可能なフィールド + +| フィールド | 型 | デフォルト値 | 説明 | +|----------|-----|------------|------| +| `board.port` | number | `8080` | ボードWebサーバーのポート番号 | +| `board.title` | string | `"agkan Board"` | ボードUIに表示されるタイトル | + +### 設定例 + +```yaml +# データベースファイルのパス +path: ./.agkan/data.db + +# ボード設定 +board: + port: 8080 + title: "マイプロジェクトボード" +``` + +### フィールドの詳細 + +- **`board.port`**: ボードWebサーバーがリッスンするTCPポートを指定します。デフォルトポート `8080` が既に使用中の場合に有用です。 + ```yaml + board: + port: 8080 + ``` + +- **`board.title`**: ボードUIに表示されるタイトルを設定します。複数のプロジェクトを管理する際に、ボードを区別するのに役立ちます。 + ```yaml + board: + title: "マイプロジェクトボード" + ``` + +## モデル設定 + +`.agkan.yml` の `models` セクションでは、ボード経由でplanningおよびrunコマンドを実行する際に使用するClaudeモデルとeffortレベルを指定できます。 + +### 利用可能なフィールド + +| フィールド | 型 | デフォルト値 | 説明 | +|----------|-----|------------|------| +| `models.planning.model` | string | (Claude CLIのデフォルト) | planningコマンド実行時に使用するモデル | +| `models.planning.effort` | string | (Claude CLIのデフォルト) | planningコマンドのeffortレベル（`low`, `medium`, `high`, `xhigh`, `max`） | +| `models.run.model` | string | (Claude CLIのデフォルト) | run/prコマンド実行時に使用するモデル | +| `models.run.effort` | string | (Claude CLIのデフォルト) | run/prコマンドのeffortレベル（`low`, `medium`, `high`, `xhigh`, `max`） | + +フルモデル名とClaude CLIのエイリアスの両方が使用できます。`model` と `effort` はいずれも省略可能です。 + +### 設定例 + +```yaml +# データベースファイルのパス +path: ./.agkan/data.db + +# モデル設定 +models: + planning: + model: claude-opus-4-7 + effort: high + run: + model: claude-sonnet-4-6 + effort: low +``` + +### エイリアスの使用 + +フルモデル名の代わりに短いエイリアスを使用できます： + +```yaml +models: + planning: + model: opus + effort: high + run: + model: sonnet +``` + +使用可能なエイリアス: `opus`、`sonnet`、`haiku`（Claude CLIが解決します） + +### フィールドの詳細 + +- **`models.planning`**: ボードがplanningタスクを実行する際に使用するClaudeモデルとeffortレベルを指定します。`opus` や `claude-opus-4-7` など高性能なモデルと高いeffortレベルの使用を推奨します。 + ```yaml + models: + planning: + model: opus + effort: high + ``` + +- **`models.run`**: ボードがrunまたはprコマンドを実行する際に使用するClaudeモデルとeffortレベルを指定します。`pr` コマンドもこの値を使用します。 + ```yaml + models: + run: + model: sonnet + effort: low + ``` + +## パーミッションモード設定 + +`.agkan.yml` の `permissionMode` フィールドで、ボードからタスクを実行する際のClaude CLIのパーミッションチェック方法を制御できます。 + +### 利用可能な値 + +| 値 | Claude CLI フラグ | 説明 | +|-------|----------------|-------------| +| (未設定) | `--permission-mode auto` | デフォルト。Claudeがautoパーミッションモードを使用 | +| `auto` | `--permission-mode auto` | Claudeがautoパーミッションモードを使用 | +| `bypassPermissions` | `--permission-mode bypassPermissions` | すべてのパーミッションチェックをバイパス | +| `acceptEdits` | `--permission-mode acceptEdits` | ファイル編集を自動的に承認 | +| `dontAsk` | `--permission-mode dontAsk` | パーミッションを確認しない | +| `plan` | `--permission-mode plan` | プランのみモード | +| `default` | `--permission-mode default` | Claudeのデフォルトパーミッションモード | +| `skipPermissions` | `--dangerously-skip-permissions` | レガシーフラグ（すべてのチェックをバイパスする旧来の動作） | + +### 設定例 + +```yaml +# autoパーミッションモードを使用（デフォルト） +permissionMode: auto + +# レガシーの --dangerously-skip-permissions フラグを使用 +permissionMode: skipPermissions +``` + +> **破壊的変更**: この機能導入以前は常に `--dangerously-skip-permissions` が渡されていました。新しいデフォルトは `--permission-mode auto` です。従来の動作を維持するには `.agkan.yml` に `permissionMode: skipPermissions` を設定してください。 diff --git a/documentation/configuration.md b/documentation/configuration.md new file mode 100644 index 00000000..77054b4b --- /dev/null +++ b/documentation/configuration.md @@ -0,0 +1,279 @@ +# Configuration + +Full configuration reference for agkan, covering `.agkan.yml` fields, database path resolution, test mode behavior, and per-project setup. + +## Table of Contents + +- [Database Storage Location](#database-storage-location) + - [Configuration File: `.agkan.yml`](#configuration-file-agkanyml) + - [Path Specification](#path-specification) + - [Environment Variable Configuration](#environment-variable-configuration) + - [Default Behavior](#default-behavior) + - [Per-Project Management](#per-project-management) +- [Board Settings](#board-settings) +- [Models Settings](#models-settings) +- [Permission Mode Settings](#permission-mode-settings) + +## Database Storage Location + +agkan allows customization of the database storage location via a configuration file. + +### Configuration File: `.agkan.yml` + +Create a `.agkan.yml` file in your project root directory to specify the database storage location. + +**Configuration Example:** + +```yaml +# Path to database file +path: ./.agkan/data.db +``` + +### Path Specification + +- **Relative Path**: Resolved relative to the current directory + ```yaml + path: ./data/kanban.db + path: ./.agkan/data.db + ``` + +- **Absolute Path**: Used as-is + ```yaml + path: /home/user/.config/akan/data.db + ``` + +### Environment Variable Configuration + +agkan supports the `AGENT_KANBAN_DB_PATH` environment variable for specifying the database location. This is particularly useful in CI/CD environments and for managing multiple environments. + +**Setting the Environment Variable:** + +```bash +# Use a custom database path +export AGENT_KANBAN_DB_PATH=/path/to/your/database.db +agkan task list + +# Use absolute path +export AGENT_KANBAN_DB_PATH=/home/user/.config/akan/data.db + +# Use relative path +export AGENT_KANBAN_DB_PATH=./custom/location/data.db +``` + +**Priority Order:** + +The database path is resolved in the following priority order: + +**Normal Mode (when `NODE_ENV` is not `test`):** +1. **Environment Variable** (highest priority): `AGENT_KANBAN_DB_PATH` +2. **Configuration File** (fallback): `path` field in `.agkan.yml` +3. **Default Path** (lowest priority): `.agkan/data.db` + +**Test Mode (when `NODE_ENV=test`):** +1. **Environment Variable** (highest priority): `AGENT_KANBAN_DB_PATH` +2. **Configuration File** (fallback): `path` field in `.agkan-test.yml` +3. **Default Path** (lowest priority): `.agkan-test/data.db` + +**Test Mode Explanation:** + +Test mode (`NODE_ENV=test`) automatically isolates test data from production data: + +- Uses separate configuration file: `.agkan-test.yml` instead of `.agkan.yml` +- Uses separate default directory: `.agkan-test/` instead of `.agkan/` +- Environment variable still takes highest priority in test mode +- Prevents accidental mixing of test and production data + +**Use Cases:** + +1. **CI/CD Pipeline:** + ```bash + # Use temporary database for CI tests + export AGENT_KANBAN_DB_PATH=/tmp/ci-test-db.db + agkan task list + ``` + +2. **Multiple Environments:** + ```bash + # Development environment + export AGENT_KANBAN_DB_PATH=./dev/data.db + + # Staging environment + export AGENT_KANBAN_DB_PATH=./staging/data.db + + # Production environment + export AGENT_KANBAN_DB_PATH=./prod/data.db + ``` + +3. **Testing:** + ```bash + # Automated tests with isolated database + NODE_ENV=test pnpm test + # Uses .agkan-test/data.db by default + + # Override with custom test database + NODE_ENV=test AGENT_KANBAN_DB_PATH=/tmp/test.db pnpm test + ``` + +### Default Behavior + +If no `.agkan.yml` file exists and no environment variable is set, the database is created in: + +``` +<current-directory>/.agkan/data.db +``` + +In test mode (`NODE_ENV=test`), the default location is: + +``` +<current-directory>/.agkan-test/data.db +``` + +### Per-Project Management + +To manage separate tasks for different projects, place `.agkan.yml` in each project root: + +```bash +# Project A +cd /path/to/projectA +cat > .agkan.yml << EOF +path: ./.agkan/data.db +EOF + +# Project B +cd /path/to/projectB +cat > .agkan.yml << EOF +path: ./.agkan/data.db +EOF +``` + +This enables independent task management for each project. + +## Board Settings + +The `board` section in `.agkan.yml` allows you to customize the behavior of the `agkan board` command. + +### Available Fields + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `board.port` | number | `8080` | Port number for the board web server | +| `board.title` | string | `"agkan Board"` | Title displayed in the board UI | + +### Configuration Example + +```yaml +# Path to database file +path: ./.agkan/data.db + +# Board settings +board: + port: 8080 + title: "My Project Board" +``` + +### Field Details + +- **`board.port`**: Specifies the TCP port on which the board web server listens. Useful when the default port `8080` is already in use. + ```yaml + board: + port: 8080 + ``` + +- **`board.title`**: Sets the title shown in the board UI. Helps distinguish boards when managing multiple projects. + ```yaml + board: + title: "My Project Board" + ``` + +## Models Settings + +The `models` section in `.agkan.yml` allows you to specify the Claude model and effort level used when executing planning and run commands via the board. + +### Available Fields + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `models.planning.model` | string | (Claude CLI default) | Model used for planning command execution | +| `models.planning.effort` | string | (Claude CLI default) | Effort level for planning command (`low`, `medium`, `high`, `xhigh`, `max`) | +| `models.run.model` | string | (Claude CLI default) | Model used for run/pr command execution | +| `models.run.effort` | string | (Claude CLI default) | Effort level for run/pr command (`low`, `medium`, `high`, `xhigh`, `max`) | + +Both full model names and Claude CLI aliases are supported. Both `model` and `effort` are optional within each entry. + +### Configuration Example + +```yaml +# Database path +path: ./.agkan/data.db + +# Model settings +models: + planning: + model: claude-opus-4-7 + effort: high + run: + model: claude-sonnet-4-6 + effort: low +``` + +### Using Aliases + +You can use short aliases instead of full model names: + +```yaml +models: + planning: + model: opus + effort: high + run: + model: sonnet +``` + +Supported aliases: `opus`, `sonnet`, `haiku` (resolved by the Claude CLI) + +### Field Details + +- **`models.planning`**: Specifies the Claude model and effort level used when the board executes planning tasks. Recommended to use a high-capability model and effort level such as `opus` with `high`. + ```yaml + models: + planning: + model: opus + effort: high + ``` + +- **`models.run`**: Specifies the Claude model and effort level used when the board executes run or pr commands. The `pr` command also uses this value. + ```yaml + models: + run: + model: sonnet + effort: low + ``` + +## Permission Mode Settings + +The `permissionMode` field in `.agkan.yml` controls how Claude CLI permission checks are handled when executing tasks from the board. + +### Available Values + +| Value | Claude CLI flag | Description | +|-------|----------------|-------------| +| (not set) | `--permission-mode auto` | Default. Claude uses auto permission mode | +| `auto` | `--permission-mode auto` | Claude uses auto permission mode | +| `bypassPermissions` | `--permission-mode bypassPermissions` | Bypass all permission checks | +| `acceptEdits` | `--permission-mode acceptEdits` | Automatically accept file edits | +| `dontAsk` | `--permission-mode dontAsk` | Do not ask for permissions | +| `plan` | `--permission-mode plan` | Plan-only mode | +| `default` | `--permission-mode default` | Claude default permission mode | +| `skipPermissions` | `--dangerously-skip-permissions` | Legacy flag (same as bypassing all checks) | + +### Configuration Example + +```yaml +# Use auto permission mode (default) +permissionMode: auto + +# Use legacy --dangerously-skip-permissions flag +permissionMode: skipPermissions +``` + +> **Breaking Change**: Prior to this feature, `--dangerously-skip-permissions` was always passed. The new default is `--permission-mode auto`. To restore the previous behavior, set `permissionMode: skipPermissions` in your `.agkan.yml`. diff --git a/documentation/development.ja.md b/documentation/development.ja.md index 89b41e3f..0f92ae29 100644 --- a/documentation/development.ja.md +++ b/documentation/development.ja.md @@ -1,5 +1,14 @@ # 開発 +## 技術スタック + +- **言語**: TypeScript 5.x +- **CLIフレームワーク**: Commander.js +- **データベース**: SQLite3 (better-sqlite3) +- **ターミナル表示**: Chalk +- **Webサーバー**: Hono（カンバンボードビューア用） +- **ビルドツール**: TypeScript Compiler + ## 開発者向けセットアップ agkan自体の開発に参加したい開発者向けの手順: diff --git a/documentation/development.md b/documentation/development.md index 25dfb417..36b9c968 100644 --- a/documentation/development.md +++ b/documentation/development.md @@ -1,5 +1,14 @@ # Development +## Technology Stack + +- **Language**: TypeScript 5.x +- **CLI Framework**: Commander.js +- **Database**: SQLite3 (better-sqlite3) +- **Terminal Display**: Chalk +- **Web Server**: Hono (for Kanban board viewer) +- **Build Tool**: TypeScript Compiler + ## Developer Setup For contributors and developers who want to work on agkan itself: