From 4941f8eabf9bb580a9f0601f92471aca84c0722b Mon Sep 17 00:00:00 2001 From: nrslib <38722970+nrslib@users.noreply.github.com> Date: Thu, 19 Feb 2026 21:20:31 +0900 Subject: [PATCH] =?UTF-8?q?README=20=E3=82=92=E5=A4=A7=E5=B9=85=E6=94=B9?= =?UTF-8?q?=E8=A8=82=E3=81=97=E3=80=81=E8=A9=B3=E7=B4=B0=E6=83=85=E5=A0=B1?= =?UTF-8?q?=E3=82=92=20docs/=20=E3=81=AB=E5=88=86=E9=9B=A2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README を約950行から約270行に圧縮し、詳細は個別ドキュメントに分離した。 コンセプトを実態に合わせて再定義（4軸: すぐ始められる・実用的・再現可能・マルチエージェント）し、 基本ユースケースを takt → takt run のフローに修正した。 英語版・日本語版の両方を対応し、日本語版はネイティブ日本語で記述。 --- README.md | 947 +++++-------------------------- docs/README.ja.md | 1085 +++++------------------------------- docs/builtin-catalog.ja.md | 109 ++++ docs/builtin-catalog.md | 109 ++++ docs/ci-cd.ja.md | 178 ++++++ docs/ci-cd.md | 178 ++++++ docs/cli-reference.ja.md | 290 ++++++++++ docs/cli-reference.md | 290 ++++++++++ docs/configuration.ja.md | 400 +++++++++++++ docs/configuration.md | 400 +++++++++++++ docs/task-management.ja.md | 323 +++++++++++ docs/task-management.md | 323 +++++++++++ 12 files changed, 2879 insertions(+), 1753 deletions(-) create mode 100644 docs/builtin-catalog.ja.md create mode 100644 docs/builtin-catalog.md create mode 100644 docs/ci-cd.ja.md create mode 100644 docs/ci-cd.md create mode 100644 docs/cli-reference.ja.md create mode 100644 docs/cli-reference.md create mode 100644 docs/configuration.ja.md create mode 100644 docs/configuration.md create mode 100644 docs/task-management.ja.md create mode 100644 docs/task-management.md diff --git a/README.md b/README.md index 9c7bfda..3a7016b 100644 --- a/README.md +++ b/README.md @@ -2,117 +2,42 @@ 🇯🇵 [日本語ドキュメント](./docs/README.ja.md) -**T**AKT **A**gent **K**oordination **T**opology - Define how AI agents coordinate, where humans intervene, and what gets recorded — in YAML +**T**AKT **A**gent **K**oordination **T**opology — Give your AI coding agents structured review loops, managed prompts, and guardrails — so they deliver quality code, not just code. -TAKT runs multiple AI agents (Claude Code, Codex, OpenCode) through YAML-defined workflows. Each step — who runs, what they see, what's allowed, what happens on failure — is declared in a piece file, not left to the agent. +TAKT runs AI agents (Claude Code, Codex, OpenCode) through YAML-defined workflows with built-in review cycles. You talk to AI to define what you want, queue tasks, and let TAKT handle the execution — planning, implementation, multi-stage review, and fix loops — all governed by declarative piece files. TAKT is built with TAKT itself (dogfooding). -## Metaphor - -TAKT uses a music metaphor to describe orchestration: - -- **Piece**: A task execution definition (what to do and how agents coordinate) -- **Movement**: A step inside a piece (a single stage in the flow) -- **Orchestration**: The engine that coordinates agents across movements - -You can read every term as standard workflow language (piece = workflow, movement = step), but the metaphor is used to keep the system conceptually consistent. - ## Why TAKT -- AI agents are powerful but non-deterministic — TAKT makes their decisions visible and replayable -- Multi-agent coordination needs structure — pieces define who does what, in what order, with what permissions -- CI/CD integration needs guardrails — pipeline mode runs agents non-interactively with full audit logs +**Batteries included** — Architecture, security, and AI antipattern review criteria are built in. Ship code that meets a quality bar from day one. -## What TAKT Controls and Manages +**Practical** — A tool for daily development, not demos. Talk to AI to refine requirements, queue tasks, and run them. Automatic worktree isolation, PR creation, and retry on failure. -TAKT **controls** agent execution and **manages** prompt components. +**Reproducible** — Execution paths are declared in YAML, keeping results consistent. Pieces are shareable — a workflow built by one team member can be used by anyone else to run the same quality process. Every step is logged in NDJSON for full traceability from task to PR. -| | Concern | Description | -|---|---------|-------------| -| Control | **Routing** | State transition rules (who runs when) | -| Control | **Tools & Permissions** | Readonly, edit, full access (what's allowed) | -| Control | **Recording** | Session logs, reports (what gets captured) | -| Manage | **Personas** | Agent roles and expertise (who they act as) | -| Manage | **Policies** | Coding standards, quality criteria, prohibitions (what to uphold) | -| Manage | **Knowledge** | Domain knowledge, architecture info (what to reference) | - -Personas, policies, and knowledge are managed as independent files and freely combined across workflows ([Faceted Prompting](./docs/faceted-prompting.md)). Change a policy in one file and every workflow using it gets the update. - -## What TAKT is NOT - -- **Not an autonomous engineer** — TAKT coordinates agents but doesn't decide what to build. You provide the task, TAKT governs the execution. -- **Not a Skill or Swarm replacement** — Skills extend a single agent's knowledge. Swarm parallelizes agents. TAKT defines the workflow structure across agents — which agent runs, in what order, with what rules. -- **Not fully automatic by default** — Every step can require human approval. Automation is opt-in (pipeline mode), not the default. +**Multi-agent** — Orchestrate multiple agents with different personas, permissions, and review criteria. Run parallel reviewers, route failures back to implementers, aggregate results with declarative rules. Prompts are managed as independent facets (persona, policy, knowledge, instruction) that compose freely across workflows ([Faceted Prompting](./docs/faceted-prompting.md)). ## Requirements Choose one: -- **Use provider CLIs**: [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), or [OpenCode](https://opencode.ai) installed -- **Use direct API**: **Anthropic API Key**, **OpenAI API Key**, or **OpenCode API Key** (no CLI required) +- **Provider CLIs**: [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), or [OpenCode](https://opencode.ai) installed +- **Direct API**: Anthropic / OpenAI / OpenCode API Key (no CLI required) -Additionally required: +Optional: -- [GitHub CLI](https://cli.github.com/) (`gh`) — Only needed for `takt #N` (GitHub Issue execution) +- [GitHub CLI](https://cli.github.com/) (`gh`) — for `takt #N` (GitHub Issue tasks) -**Pricing Note**: When using API Keys, TAKT directly calls the Claude API (Anthropic), OpenAI API, or OpenCode API. The pricing structure is the same as using the respective CLI tools. Be mindful of costs, especially when running automated tasks in CI/CD environments, as API usage can accumulate. +## Quick Start -## Installation +### Install ```bash npm install -g takt ``` -## Quick Start - -```bash -# Interactive mode - refine task requirements with AI, then execute -takt - -# Execute GitHub Issue as task (both work the same) -takt #6 -takt --issue 6 - -# Pipeline execution (non-interactive, for scripts/CI) -takt --pipeline --task "Fix the bug" --auto-pr -``` - -## Usage - -### Interactive Mode - -A mode where you refine task content through conversation with AI before execution. Useful when task requirements are ambiguous or when you want to clarify content while consulting with AI. - -```bash -# Start interactive mode (no arguments) -takt - -# Specify initial message (short word only) -takt hello -``` - -**Note:** `--task` option skips interactive mode and executes the task directly. Issue references (`#6`, `--issue`) are used as initial input in interactive mode. - -**Flow:** -1. Select piece -2. Select interactive mode (assistant / persona / quiet / passthrough) -3. Refine task content through conversation with AI -4. Finalize task instructions with `/go` (you can also add additional instructions like `/go additional instructions`), or use `/play ` to execute a task immediately -5. Execute (create worktree, run piece, create PR) - -#### Interactive Mode Variants - -| Mode | Description | -|------|-------------| -| `assistant` | Default. AI asks clarifying questions before generating task instructions. | -| `persona` | Conversation with the first movement's persona (uses its system prompt and tools). | -| `quiet` | Generates task instructions without asking questions (best-effort). | -| `passthrough` | Passes user input directly as task text without AI processing. | - -Pieces can set a default mode via the `interactive_mode` field in YAML. - -#### Execution Example +### Talk to AI, then execute ``` $ takt @@ -121,748 +46,190 @@ Select piece: ❯ 🎼 default (current) 📁 Development/ 📁 Research/ - Cancel -Interactive mode - Enter task content. Commands: /go (execute), /cancel (exit) +> Add user authentication with JWT -> I want to add user authentication feature - -[AI confirms and organizes requirements] +[AI clarifies requirements and organizes the task] > /go - -Proposed task instructions: -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Implement user authentication feature. - -Requirements: -- Login with email address and password -- JWT token-based authentication -- Password hashing (bcrypt) -- Login/logout API endpoints -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - -Proceed with these task instructions? (Y/n) y - -? Create worktree? (Y/n) y - -[Piece execution starts...] ``` -### Direct Task Execution +TAKT creates an isolated worktree, runs the piece (plan → implement → review → fix loop), and offers to create a PR when done. -Use the `--task` option to skip interactive mode and execute directly. +### Queue tasks, then batch execute + +Use `takt` to queue multiple tasks, then execute them all at once: ```bash -# Specify task content with --task option -takt --task "Fix bug" +# Queue tasks through conversation +takt +> Refactor the auth module +> /go # queues the task -# Specify piece -takt --task "Add authentication" --piece expert +# Or queue from GitHub Issues +takt add #6 +takt add #12 -# Auto-create PR -takt --task "Fix bug" --auto-pr -``` - -**Note:** Passing a string as an argument (e.g., `takt "Add login feature"`) enters interactive mode with it as the initial message. - -### GitHub Issue Tasks - -You can execute GitHub Issues directly as tasks. Issue title, body, labels, and comments are automatically incorporated as task content. - -```bash -# Execute by specifying issue number -takt #6 -takt --issue 6 - -# Issue + piece specification -takt #6 --piece expert - -# Issue + auto-create PR -takt #6 --auto-pr -``` - -**Requirements:** [GitHub CLI](https://cli.github.com/) (`gh`) must be installed and authenticated. - -### Task Management (add / run / watch / list) - -Batch processing using `.takt/tasks.yaml` with task directories under `.takt/tasks/{slug}/`. Useful for accumulating multiple tasks and executing them together later. - -#### Add Task (`takt add`) - -```bash -# Refine task requirements through AI conversation, then add task -takt add - -# Add task from GitHub Issue (issue number reflected in branch name) -takt add #28 -``` - -#### Execute Tasks (`takt run`) - -```bash -# Execute all pending tasks in .takt/tasks.yaml +# Execute all pending tasks takt run ``` -#### Watch Tasks (`takt watch`) +### Manage results ```bash -# Monitor .takt/tasks.yaml and auto-execute tasks (resident process) -takt watch -``` - -#### List Task Branches (`takt list`) - -```bash -# List task branches (merge/delete) +# List completed/failed task branches — merge, retry, or delete takt list - -# Non-interactive mode (for CI/scripts) -takt list --non-interactive -takt list --non-interactive --action diff --branch takt/my-branch -takt list --non-interactive --action delete --branch takt/my-branch --yes -takt list --non-interactive --format json ``` -#### Task Directory Workflow (Create / Run / Verify) +## How It Works -1. Run `takt add` and confirm a pending record is created in `.takt/tasks.yaml`. -2. Open the generated `.takt/tasks/{slug}/order.md` and add detailed specifications/references as needed. -3. Run `takt run` (or `takt watch`) to execute pending tasks from `tasks.yaml`. -4. Verify outputs in `.takt/runs/{slug}/reports/` using the same slug as `task_dir`. +TAKT uses a music metaphor: **piece** = workflow, **movement** = step. -### Pipeline Mode (for CI/Automation) - -Specifying `--pipeline` enables non-interactive pipeline mode. Automatically creates branch → runs piece → commits & pushes. Suitable for CI/CD automation. - -```bash -# Execute task in pipeline mode -takt --pipeline --task "Fix bug" - -# Pipeline execution + auto-create PR -takt --pipeline --task "Fix bug" --auto-pr - -# Link issue information -takt --pipeline --issue 99 --auto-pr - -# Specify piece and branch -takt --pipeline --task "Fix bug" -w magi -b feat/fix-bug - -# Specify repository (for PR creation) -takt --pipeline --task "Fix bug" --auto-pr --repo owner/repo - -# Piece execution only (skip branch creation, commit, push) -takt --pipeline --task "Fix bug" --skip-git - -# Minimal output mode (for CI) -takt --pipeline --task "Fix bug" --quiet -``` - -In pipeline mode, PRs are not created unless `--auto-pr` is specified. - -**GitHub Integration:** When using TAKT in GitHub Actions, see [takt-action](https://github.com/nrslib/takt-action). You can automate PR reviews and task execution. Refer to the [CI/CD Integration](#cicd-integration) section for details. - -### Other Commands - -```bash -# Interactively switch pieces -takt switch - -# Copy builtin pieces/personas to project .takt/ for customization -takt eject - -# Copy to ~/.takt/ (global) instead -takt eject --global - -# Clear agent conversation sessions -takt clear - -# Deploy builtin pieces/personas as Claude Code Skill -takt export-cc - -# List available facets across layers -takt catalog -takt catalog personas - -# Eject a specific facet for customization -takt eject persona coder -takt eject instruction plan --global - -# Preview assembled prompts for each movement and phase -takt prompt [piece] - -# Configure permission mode -takt config - -# Reset piece categories to builtin defaults -takt reset categories -``` - -### Recommended Pieces - -| Piece | Recommended Use | -|----------|-----------------| -| `default` | Serious development tasks. Used for TAKT's own development. Multi-stage review with parallel reviews (architect + security). | -| `default-mini` | Simple fixes and straightforward tasks. Lightweight piece with AI antipattern review + supervisor. | -| `review-fix-minimal` | Review & fix piece. Specialized for iterative improvement based on review feedback. | -| `research` | Investigation and research. Autonomously executes research without asking questions. | - -### Main Options - -| Option | Description | -|--------|-------------| -| `--pipeline` | **Enable pipeline (non-interactive) mode** — Required for CI/automation | -| `-t, --task ` | Task content (alternative to GitHub Issue) | -| `-i, --issue ` | GitHub issue number (same as `#N` in interactive mode) | -| `-w, --piece ` | Piece name or path to piece YAML file | -| `-b, --branch ` | Specify branch name (auto-generated if omitted) | -| `--auto-pr` | Create PR (interactive: skip confirmation, pipeline: enable PR) | -| `--skip-git` | Skip branch creation, commit, and push (pipeline mode, piece-only) | -| `--repo ` | Specify repository (for PR creation) | -| `--create-worktree ` | Skip worktree confirmation prompt | -| `-q, --quiet` | Minimal output mode: suppress AI output (for CI) | -| `--provider ` | Override agent provider (claude\|codex\|opencode\|mock) | -| `--model ` | Override agent model | - -## Pieces - -TAKT uses YAML-based piece definitions and rule-based routing. Builtin pieces are embedded in the package, with user pieces in `~/.takt/pieces/` taking priority. Use `takt eject` to copy builtins to `~/.takt/` for customization. - -> **Note (v0.4.0)**: Internal terminology has changed from "step" to "movement" for piece components. User-facing piece files remain compatible, but if you customize pieces, you may see `movements:` instead of `steps:` in YAML files. The functionality remains the same. - -### Piece Example +A piece defines a sequence of movements. Each movement specifies a persona (who), permissions (what's allowed), and rules (what happens next). Here's a minimal example: ```yaml -name: default -max_movements: 10 +name: simple initial_movement: plan -# Section maps — key: file path (relative to this YAML) personas: planner: ../personas/planner.md coder: ../personas/coder.md reviewer: ../personas/architecture-reviewer.md -policies: - coding: ../policies/coding.md - -knowledge: - architecture: ../knowledge/architecture.md - movements: - name: plan persona: planner - model: opus edit: false rules: - condition: Planning complete next: implement - instruction_template: | - Analyze the request and create an implementation plan. - name: implement persona: coder - policy: coding - knowledge: architecture edit: true - required_permission_mode: edit rules: - condition: Implementation complete next: review - - condition: Blocked - next: ABORT - instruction_template: | - Implement based on the plan. - name: review persona: reviewer - knowledge: architecture edit: false rules: - condition: Approved next: COMPLETE - condition: Needs fix - next: implement - instruction_template: | - Review the implementation from architecture and code quality perspectives. + next: implement # ← fix loop ``` -### Persona-less Movements +Rules determine the next movement. `COMPLETE` ends the piece successfully, `ABORT` ends with failure. See the [Piece Guide](./docs/pieces.md) for the full schema, parallel movements, and rule condition types. -The `persona` field is optional. When omitted, the movement executes using only the `instruction_template` without a system prompt. This is useful for simple tasks that don't require persona customization. +## Recommended Pieces -```yaml - - name: summarize - # No persona specified — uses instruction_template only - edit: false - rules: - - condition: Summary complete - next: COMPLETE - instruction_template: | - Read the report and provide a concise summary. -``` +| Piece | Use Case | +|-------|----------| +| `default-mini` | Quick fixes. Lightweight plan → implement → parallel review → fix loop. | +| `frontend-mini` | Frontend-focused mini configuration. | +| `backend-mini` | Backend-focused mini configuration. | +| `expert-mini` | Expert-level mini configuration. | +| `default` | Serious development. Multi-stage review with parallel reviewers. Used for TAKT's own development. | -You can also write an inline system prompt as the `persona` value (if the specified file doesn't exist): +See the [Builtin Catalog](./docs/builtin-catalog.md) for all pieces and personas. -```yaml - - name: review - persona: "You are a code reviewer. Focus on readability and maintainability." - edit: false - instruction_template: | - Review code quality. -``` +## Key Commands -### Parallel Movements - -Execute sub-movements in parallel within a movement and evaluate with aggregate conditions: - -```yaml - - name: reviewers - parallel: - - name: arch-review - persona: reviewer - rules: - - condition: approved - - condition: needs_fix - instruction_template: | - Review architecture and code quality. - - name: security-review - persona: security-reviewer - rules: - - condition: approved - - condition: needs_fix - instruction_template: | - Review for security vulnerabilities. - rules: - - condition: all("approved") - next: supervise - - condition: any("needs_fix") - next: fix -``` - -- `all("X")`: true if ALL sub-movements matched condition X -- `any("X")`: true if ANY sub-movement matched condition X -- Sub-movement `rules` define possible outcomes, but `next` is optional (parent controls transition) - -### Rule Condition Types - -| Type | Syntax | Description | -|------|--------|-------------| -| Tag-based | `"condition text"` | Agent outputs `[MOVEMENTNAME:N]` tag, matched by index | -| AI judge | `ai("condition text")` | AI evaluates condition against agent output | -| Aggregate | `all("X")` / `any("X")` | Aggregates parallel sub-movement matched conditions | - -## Builtin Pieces - -TAKT includes multiple builtin pieces: - -| Piece | Description | -|----------|-------------| -| `default` | Full development piece: plan → implement → AI review → parallel review (architect + QA) → supervisor approval. Includes fix loops at each review stage. | -| `default-mini` | Mini development piece: plan → implement → parallel review (AI antipattern + supervisor) → fix if needed. Lightweight with review. | -| `frontend-mini` | Mini frontend piece: plan → implement → parallel review (AI antipattern + supervisor) with frontend knowledge injection. | -| `backend-mini` | Mini backend piece: plan → implement → parallel review (AI antipattern + supervisor) with backend knowledge injection. | -| `backend-cqrs-mini` | Mini CQRS+ES piece: plan → implement → parallel review (AI antipattern + supervisor) with CQRS+ES knowledge injection. | -| `review-fix-minimal` | Review-focused piece: review → fix → supervisor. For iterative improvement based on review feedback. | -| `research` | Research piece: planner → digger → supervisor. Autonomously executes research without asking questions. | -| `deep-research` | Deep research piece: plan → dig → analyze → supervise. Discovery-driven investigation that follows emerging questions with multi-perspective analysis. | -| `expert` | Full-stack development piece: architecture, frontend, security, QA reviews with fix loops. | -| `expert-mini` | Mini expert piece: plan → implement → parallel review (AI antipattern + expert supervisor) with full-stack knowledge injection. | -| `expert-cqrs` | Full-stack development piece (CQRS+ES specialized): CQRS+ES, frontend, security, QA reviews with fix loops. | -| `expert-cqrs-mini` | Mini CQRS+ES expert piece: plan → implement → parallel review (AI antipattern + expert supervisor) with CQRS+ES knowledge injection. | -| `magi` | Deliberation system inspired by Evangelion. Three AI personas (MELCHIOR, BALTHASAR, CASPER) analyze and vote. | -| `passthrough` | Thinnest wrapper. Pass task directly to coder as-is. No review. | -| `compound-eye` | Multi-model review: sends the same instruction to Claude and Codex simultaneously, then synthesizes both responses. | -| `review-only` | Read-only code review piece that makes no changes. | -| `structural-reform` | Full project review and structural reform: iterative codebase restructuring with staged file splits. | -| `unit-test` | Unit test focused piece: test analysis → test implementation → review → fix. | -| `e2e-test` | E2E test focused piece: E2E analysis → E2E implementation → review → fix (Vitest-based E2E flow). | -| `frontend` | Frontend-specialized development piece with React/Next.js focused reviews and knowledge injection. | -| `backend` | Backend-specialized development piece with backend, security, and QA expert reviews. | -| `backend-cqrs` | CQRS+ES-specialized backend development piece with CQRS+ES, security, and QA expert reviews. | - -**Per-persona provider overrides:** Use `persona_providers` in config to route specific personas to different providers (e.g., coder on Codex, reviewers on Claude) without duplicating pieces. - -Use `takt switch` to switch pieces. - -## Builtin Personas - -| Persona | Description | +| Command | Description | |---------|-------------| -| **planner** | Task analysis, spec investigation, implementation planning | -| **architect-planner** | Task analysis and design planning: investigates code, resolves unknowns, creates implementation plans | -| **coder** | Feature implementation, bug fixing | -| **ai-antipattern-reviewer** | AI-specific antipattern review (non-existent APIs, incorrect assumptions, scope creep) | -| **architecture-reviewer** | Architecture and code quality review, spec compliance verification | -| **frontend-reviewer** | Frontend (React/Next.js) code quality and best practices review | -| **cqrs-es-reviewer** | CQRS+Event Sourcing architecture and implementation review | -| **qa-reviewer** | Test coverage and quality assurance review | -| **security-reviewer** | Security vulnerability assessment | -| **conductor** | Phase 3 judgment specialist: reads reports/responses and outputs status tags | -| **supervisor** | Final validation, approval | -| **expert-supervisor** | Expert-level final validation with comprehensive review integration | -| **research-planner** | Research task planning and scope definition | -| **research-analyzer** | Research result interpretation and additional investigation planning | -| **research-digger** | Deep investigation and information gathering | -| **research-supervisor** | Research quality validation and completeness assessment | -| **test-planner** | Test strategy analysis and comprehensive test planning | -| **pr-commenter** | Posts review findings as GitHub PR comments | +| `takt` | Talk to AI, refine requirements, execute or queue tasks | +| `takt run` | Execute all pending tasks | +| `takt list` | Manage task branches (merge, retry, instruct, delete) | +| `takt #N` | Execute GitHub Issue as task | +| `takt switch` | Switch active piece | +| `takt eject` | Copy builtin pieces/personas for customization | -## Custom Personas +See the [CLI Reference](./docs/cli-reference.md) for all commands and options. -Create persona prompts in Markdown files: +## Configuration + +Minimal `~/.takt/config.yaml`: + +```yaml +provider: claude # claude, codex, or opencode +model: sonnet # passed directly to provider +language: en # en or ja +``` + +Or use API keys directly (no CLI installation required): + +```bash +export TAKT_ANTHROPIC_API_KEY=sk-ant-... +``` + +See the [Configuration Guide](./docs/configuration.md) for all options, provider profiles, and model resolution. + +## Customization + +### Custom pieces + +```bash +takt eject default # Copy builtin to ~/.takt/pieces/ and edit +``` + +### Custom personas + +Create a Markdown file in `~/.takt/personas/`: ```markdown # ~/.takt/personas/my-reviewer.md - You are a code reviewer specialized in security. - -## Role -- Check for security vulnerabilities -- Verify input validation -- Review authentication logic ``` -## Model Selection +Reference it in your piece: `persona: my-reviewer` -The `model` field (in piece movements, agent config, or global config) is passed directly to the provider (Claude Code CLI / Codex SDK). TAKT does not resolve model aliases. +See the [Piece Guide](./docs/pieces.md) and [Agent Guide](./docs/agents.md) for details. -### Claude Code +## CI/CD -Claude Code supports aliases (`opus`, `sonnet`, `haiku`, `opusplan`, `default`) and full model names (e.g., `claude-sonnet-4-5-20250929`). Refer to the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code) for available models. +TAKT provides [takt-action](https://github.com/nrslib/takt-action) for GitHub Actions: -### Codex +```yaml +- uses: nrslib/takt-action@main + with: + anthropic_api_key: ${{ secrets.TAKT_ANTHROPIC_API_KEY }} + github_token: ${{ secrets.GITHUB_TOKEN }} +``` -The model string is passed to the Codex SDK. If unspecified, defaults to `codex`. Refer to Codex documentation for available models. +For other CI systems, use pipeline mode: + +```bash +takt --pipeline --task "Fix the bug" --auto-pr +``` + +See the [CI/CD Guide](./docs/ci-cd.md) for full setup instructions. ## Project Structure ``` -~/.takt/ # Global configuration directory -├── config.yaml # Global config (provider, model, piece, etc.) -├── pieces/ # User piece definitions (override builtins) -│ └── custom.yaml -└── personas/ # User persona prompt files (.md) - └── my-persona.md +~/.takt/ # Global config +├── config.yaml # Provider, model, language, etc. +├── pieces/ # User piece definitions +└── personas/ # User persona prompts -.takt/ # Project-level configuration -├── config.yaml # Project config (current piece, etc.) -├── tasks/ # Task input directories (.takt/tasks/{slug}/order.md, etc.) -├── tasks.yaml # Pending tasks metadata (task_dir, piece, worktree, etc.) -└── runs/ # Run-scoped artifacts - └── {slug}/ - ├── reports/ # Execution reports (auto-generated) - ├── context/ # knowledge/policy/previous_response snapshots - ├── logs/ # NDJSON session logs for this run - └── meta.json # Run metadata +.takt/ # Project-level +├── config.yaml # Project config +├── tasks.yaml # Pending tasks +├── tasks/ # Task specifications +└── runs/ # Execution reports, logs, context ``` -Builtin resources are embedded in the npm package (`builtins/`). User files in `~/.takt/` take priority. - -### Global Configuration - -Configure default provider and model in `~/.takt/config.yaml`: - -```yaml -# ~/.takt/config.yaml -language: en -default_piece: default -log_level: info -provider: claude # Default provider: claude, codex, or opencode -model: sonnet # Default model (optional) -branch_name_strategy: romaji # Branch name generation: 'romaji' (fast) or 'ai' (slow) -prevent_sleep: false # Prevent macOS idle sleep during execution (caffeinate) -notification_sound: true # Enable/disable notification sounds -notification_sound_events: # Optional per-event toggles - iteration_limit: false - piece_complete: true - piece_abort: true - run_complete: true # Enabled by default; set false to disable - run_abort: true # Enabled by default; set false to disable -concurrency: 1 # Parallel task count for takt run (1-10, default: 1 = sequential) -task_poll_interval_ms: 500 # Polling interval for new tasks during takt run (100-5000, default: 500) -interactive_preview_movements: 3 # Movement previews in interactive mode (0-10, default: 3) - -# Runtime environment defaults (applies to all pieces unless piece_config.runtime overrides) -# runtime: -# prepare: -# - gradle # Prepare Gradle cache/config in .runtime/ -# - node # Prepare npm cache in .runtime/ - -# Per-persona provider overrides (optional) -# Route specific personas to different providers without duplicating pieces -# persona_providers: -# coder: codex # Run coder on Codex -# ai-antipattern-reviewer: claude # Keep reviewers on Claude - -# Provider-specific permission profiles (optional) -# Priority: project override → global override → project default → global default → required_permission_mode (floor) -# provider_profiles: -# codex: -# default_permission_mode: full -# movement_permission_overrides: -# ai_review: readonly -# claude: -# default_permission_mode: edit - -# API Key configuration (optional) -# Can be overridden by environment variables TAKT_ANTHROPIC_API_KEY / TAKT_OPENAI_API_KEY / TAKT_OPENCODE_API_KEY -anthropic_api_key: sk-ant-... # For Claude (Anthropic) -# openai_api_key: sk-... # For Codex (OpenAI) -# opencode_api_key: ... # For OpenCode - -# Codex CLI path override (optional) -# Override the Codex CLI binary used by the Codex SDK (must be an absolute path to an executable file) -# Can be overridden by TAKT_CODEX_CLI_PATH environment variable -# codex_cli_path: /usr/local/bin/codex - -# Builtin piece filtering (optional) -# builtin_pieces_enabled: true # Set false to disable all builtins -# disabled_builtins: [magi, passthrough] # Disable specific builtin pieces - -# Pipeline execution configuration (optional) -# Customize branch names, commit messages, and PR body. -# pipeline: -# default_branch_prefix: "takt/" -# commit_message_template: "feat: {title} (#{issue})" -# pr_body_template: | -# ## Summary -# {issue_body} -# Closes #{issue} -``` - -**Note:** The Codex SDK requires running inside a Git repository. `--skip-git-repo-check` is only available in the Codex CLI. - -**API Key Configuration Methods:** - -1. **Set via environment variables**: - ```bash - export TAKT_ANTHROPIC_API_KEY=sk-ant-... # For Claude - export TAKT_OPENAI_API_KEY=sk-... # For Codex - export TAKT_OPENCODE_API_KEY=... # For OpenCode - ``` - -2. **Set in config file**: - Write `anthropic_api_key`, `openai_api_key`, or `opencode_api_key` in `~/.takt/config.yaml` as shown above - -Priority: Environment variables > `config.yaml` settings - -**Notes:** -- If you set an API Key, installing Claude Code, Codex, or OpenCode is not necessary. TAKT directly calls the respective API. -- **Security**: If you write API Keys in `config.yaml`, be careful not to commit this file to Git. Consider using environment variables or adding `~/.takt/config.yaml` to `.gitignore`. - -**Pipeline Template Variables:** - -| Variable | Available In | Description | -|----------|-------------|-------------| -| `{title}` | Commit message | Issue title | -| `{issue}` | Commit message, PR body | Issue number | -| `{issue_body}` | PR body | Issue body | -| `{report}` | PR body | Piece execution report | - -**Model Resolution Priority:** -1. Piece movement `model` (highest priority) -2. Custom agent `model` -3. Global config `model` -4. Provider default (Claude: sonnet, Codex: codex, OpenCode: provider default) - -## Detailed Guides - -### Task Directory Format - -TAKT stores task metadata in `.takt/tasks.yaml`, and each task's long specification in `.takt/tasks/{slug}/`. - -**Recommended layout**: - -```text -.takt/ - tasks/ - 20260201-015714-foptng/ - order.md - schema.sql - wireframe.png - tasks.yaml - runs/ - 20260201-015714-foptng/ - reports/ -``` - -**tasks.yaml record**: - -```yaml -tasks: - - name: add-auth-feature - status: pending - task_dir: .takt/tasks/20260201-015714-foptng - piece: default - created_at: "2026-02-01T01:57:14.000Z" - started_at: null - completed_at: null -``` - -`takt add` creates `.takt/tasks/{slug}/order.md` automatically and saves `task_dir` to `tasks.yaml`. - -#### Isolated Execution with Shared Clone - -Specifying `worktree` in YAML task files executes each task in an isolated clone created with `git clone --shared`, keeping your main working directory clean: - -- `worktree: true` - Auto-create shared clone in adjacent directory (or location specified by `worktree_dir` config) -- `worktree: "/path/to/dir"` - Create at specified path -- `branch: "feat/xxx"` - Use specified branch (auto-generated as `takt/{timestamp}-{slug}` if omitted) -- Omit `worktree` - Execute in current directory (default) - -> **Note**: The YAML field name remains `worktree` for backward compatibility. Internally, it uses `git clone --shared` instead of `git worktree`. Git worktrees have a `.git` file containing `gitdir:` pointing to the main repository, which Claude Code follows to recognize the main repository as the project root. Shared clones have an independent `.git` directory, preventing this issue. - -Clones are ephemeral. After task completion, they auto-commit + push, then delete the clone. Branches are the only persistent artifacts. Use `takt list` to list, merge, or delete branches. - -### Session Logs - -TAKT writes session logs in NDJSON (`.jsonl`) format to `.takt/runs/{slug}/logs/`. Each record is atomically appended, so partial logs are preserved even if the process crashes, and you can track in real-time with `tail -f`. - -- `.takt/runs/{slug}/logs/{sessionId}.jsonl` - NDJSON session log per piece execution -- `.takt/runs/{slug}/meta.json` - Run metadata (`task`, `piece`, `start/end`, `status`, etc.) - -Record types: `piece_start`, `step_start`, `step_complete`, `piece_complete`, `piece_abort` - -The latest previous response is stored at `.takt/runs/{slug}/context/previous_responses/latest.md` and inherited automatically. - -### Adding Custom Pieces - -Add YAML files to `~/.takt/pieces/` or customize builtins with `takt eject`: - -```bash -# Copy default piece to ~/.takt/pieces/ and edit -takt eject default -``` - -```yaml -# ~/.takt/pieces/my-piece.yaml -name: my-piece -description: Custom piece -max_movements: 5 -initial_movement: analyze - -personas: - analyzer: ~/.takt/personas/analyzer.md - coder: ../personas/coder.md - -movements: - - name: analyze - persona: analyzer - edit: false - rules: - - condition: Analysis complete - next: implement - instruction_template: | - Thoroughly analyze this request. - - - name: implement - persona: coder - edit: true - required_permission_mode: edit - pass_previous_response: true - rules: - - condition: Complete - next: COMPLETE - instruction_template: | - Implement based on the analysis. -``` - -> **Note**: `{task}`, `{previous_response}`, `{user_inputs}` are automatically injected into instructions. Explicit placeholders are only needed if you want to control their position in the template. - -### Specifying Personas by Path - -Map keys to file paths in section maps, then reference keys from movements: - -```yaml -# Section maps (relative to piece file) -personas: - coder: ../personas/coder.md - reviewer: ~/.takt/personas/my-reviewer.md -``` - -### Piece Variables - -Variables available in `instruction_template`: - -| Variable | Description | -|----------|-------------| -| `{task}` | Original user request (auto-injected if not in template) | -| `{iteration}` | Piece-wide turn count (total steps executed) | -| `{max_movements}` | Maximum iteration count | -| `{movement_iteration}` | Per-movement iteration count (times this movement has been executed) | -| `{previous_response}` | Output from previous movement (auto-injected if not in template) | -| `{user_inputs}` | Additional user inputs during piece (auto-injected if not in template) | -| `{report_dir}` | Report directory path (e.g., `.takt/runs/20250126-143052-task-summary/reports`) | -| `{report:filename}` | Expands to `{report_dir}/filename` (e.g., `{report:00-plan.md}`) | - -### Piece Design - -Elements needed for each piece movement: - -**1. Persona** - Referenced by section map key (used as system prompt): - -```yaml -persona: coder # Key from personas section map -persona_name: coder # Display name (optional) -``` - -**2. Rules** - Define routing from movement to next movement. The instruction builder auto-injects status output rules, so agents know which tags to output: - -```yaml -rules: - - condition: "Implementation complete" - next: review - - condition: "Blocked" - next: ABORT -``` - -Special `next` values: `COMPLETE` (success), `ABORT` (failure) - -**3. Movement Options:** - -| Option | Default | Description | -|--------|---------|-------------| -| `edit` | - | Whether movement can edit project files (`true`/`false`) | -| `pass_previous_response` | `true` | Pass previous movement output to `{previous_response}` | -| `allowed_tools` | - | List of tools agent can use (Read, Glob, Grep, Edit, Write, Bash, etc.) | -| `provider` | - | Override provider for this movement (`claude`, `codex`, or `opencode`) | -| `model` | - | Override model for this movement | -| `required_permission_mode` | - | Required minimum permission mode: `readonly`, `edit`, `full` (acts as floor; actual mode resolved via `provider_profiles`) | -| `provider_options` | - | Provider-specific options (e.g. `codex.network_access`, `opencode.network_access`) | -| `output_contracts` | - | Output contract definitions for report files | -| `quality_gates` | - | AI directives for movement completion requirements | -| `mcp_servers` | - | MCP (Model Context Protocol) server configuration (stdio/SSE/HTTP) | - -Piece-level defaults can be set with `piece_config.provider_options`, and movement-level `provider_options` overrides them. - -```yaml -piece_config: - provider_options: - codex: - network_access: true - opencode: - network_access: true - runtime: - prepare: - - gradle - - node -``` - -Runtime `prepare` entries can be builtin presets (`gradle`, `node`) or paths to custom shell scripts. Scripts receive `TAKT_RUNTIME_ROOT` and related env vars, and can export additional variables via stdout. - -## API Usage Example +## API Usage ```typescript -import { PieceEngine, loadPiece } from 'takt'; // npm install takt +import { PieceEngine, loadPiece } from 'takt'; const config = loadPiece('default'); -if (!config) { - throw new Error('Piece not found'); -} -const engine = new PieceEngine(config, process.cwd(), 'My task'); +if (!config) throw new Error('Piece not found'); +const engine = new PieceEngine(config, process.cwd(), 'My task'); engine.on('step:complete', (step, response) => { console.log(`${step.name}: ${response.status}`); }); @@ -870,81 +237,25 @@ engine.on('step:complete', (step, response) => { await engine.run(); ``` -## Contributing - -See [CONTRIBUTING.md](../CONTRIBUTING.md) for details. - -## CI/CD Integration - -### GitHub Actions - -TAKT provides a GitHub Action for automating PR reviews and task execution. See [takt-action](https://github.com/nrslib/takt-action) for details. - -**Piece example** (see [.github/workflows/takt-action.yml](../.github/workflows/takt-action.yml) in this repository): - -```yaml -name: TAKT - -on: - issue_comment: - types: [created] - -jobs: - takt: - if: contains(github.event.comment.body, '@takt') - runs-on: ubuntu-latest - permissions: - contents: write - issues: write - pull-requests: write - - steps: - - name: Checkout - uses: actions/checkout@v4 - - - name: Run TAKT - uses: nrslib/takt-action@main - with: - anthropic_api_key: ${{ secrets.TAKT_ANTHROPIC_API_KEY }} - github_token: ${{ secrets.GITHUB_TOKEN }} -``` - -**Cost Warning**: TAKT uses AI APIs (Claude or OpenAI), which can incur significant costs, especially when tasks are auto-executed in CI/CD environments. Monitor API usage and set up billing alerts. - -### Other CI Systems - -For CI systems other than GitHub, use pipeline mode: - -```bash -# Install takt -npm install -g takt - -# Run in pipeline mode -takt --pipeline --task "Fix bug" --auto-pr --repo owner/repo -``` - -For authentication, set `TAKT_ANTHROPIC_API_KEY`, `TAKT_OPENAI_API_KEY`, or `TAKT_OPENCODE_API_KEY` environment variables (TAKT-specific prefix). - -```bash -# For Claude (Anthropic) -export TAKT_ANTHROPIC_API_KEY=sk-ant-... - -# For Codex (OpenAI) -export TAKT_OPENAI_API_KEY=sk-... - -# For OpenCode -export TAKT_OPENCODE_API_KEY=... -``` - ## Documentation -- [Faceted Prompting](./docs/faceted-prompting.md) - Separation of Concerns for AI prompts (Persona, Policy, Instruction, Knowledge, Output Contract) -- [Piece Guide](./docs/pieces.md) - Creating and customizing pieces -- [Agent Guide](./docs/agents.md) - Configuring custom agents -- [Changelog](../CHANGELOG.md) ([日本語](./docs/CHANGELOG.ja.md)) - Version history -- [Security Policy](../SECURITY.md) - Vulnerability reporting -- [Blog: TAKT - AI Agent Orchestration](https://zenn.dev/nrs/articles/c6842288a526d7) - Design philosophy and practical usage guide (Japanese) +| Document | Description | +|----------|-------------| +| [CLI Reference](./docs/cli-reference.md) | All commands and options | +| [Configuration](./docs/configuration.md) | Global and project settings | +| [Piece Guide](./docs/pieces.md) | Creating and customizing pieces | +| [Agent Guide](./docs/agents.md) | Custom agent configuration | +| [Builtin Catalog](./docs/builtin-catalog.md) | All builtin pieces and personas | +| [Faceted Prompting](./docs/faceted-prompting.md) | Prompt design methodology | +| [Task Management](./docs/task-management.md) | Task queuing, execution, isolation | +| [CI/CD Integration](./docs/ci-cd.md) | GitHub Actions and pipeline mode | +| [Changelog](./CHANGELOG.md) ([日本語](./docs/CHANGELOG.ja.md)) | Version history | +| [Security Policy](./SECURITY.md) | Vulnerability reporting | + +## Contributing + +See [CONTRIBUTING.md](./CONTRIBUTING.md) for details. ## License -MIT - See [LICENSE](../LICENSE) for details. +MIT — See [LICENSE](./LICENSE) for details. diff --git a/docs/README.ja.md b/docs/README.ja.md index 1d61c42..a18ac77 100644 --- a/docs/README.ja.md +++ b/docs/README.ja.md @@ -1,974 +1,246 @@ # TAKT -**T**AKT **A**gent **K**oordination **T**opology - AIエージェントの協調手順・人の介入ポイント・記録をYAMLで定義する +[English](../README.md) -TAKTは複数のAIエージェント（Claude Code、Codex、OpenCode）をYAMLで定義されたワークフローに従って実行します。各ステップで誰が実行し、何を見て、何を許可し、失敗時にどうするかはピースファイルに宣言され、エージェント任せにしません。 +**T**AKT **A**gent **K**oordination **T**opology — AI コーディングエージェントにレビューループ・プロンプト管理・ガードレールを与え、「とりあえず動くコード」ではなく「品質の高いコード」を出させるツールです。 -TAKTはTAKT自身で開発されています（ドッグフーディング）。 +AI と会話してやりたいことを決め、タスクとして積み、`takt run` で実行します。計画・実装・レビュー・修正のループは YAML の piece ファイルで定義されており、エージェント任せにはしません。Claude Code、Codex、OpenCode に対応しています。 -## メタファ +TAKT は TAKT 自身で開発しています（ドッグフーディング）。 -TAKTはオーケストラをイメージした音楽メタファで用語を統一しています。 +## なぜ TAKT か -- **Piece**: タスク実行定義（何をどう協調させるか） -- **Movement**: ピース内の1ステップ（実行フローの1段階） -- **Orchestration**: ムーブメント間でエージェントを協調させるエンジン +**すぐ始められる** — アーキテクチャ、セキュリティ、AI アンチパターンなどのレビュー観点をビルトインで備えています。インストールしたその日から、一定以上の品質のコードを出せます。 -## なぜTAKTか +**実用的** — 日々の開発で使うためのツールです。AI と相談して要件を固め、タスクを積んで実行します。worktree の自動隔離、PR 作成、失敗時のリトライまで面倒を見てくれます。 -- AIエージェントは強力だが非決定的 — TAKTはエージェントの判断を可視化し、再現可能にする -- マルチエージェントの協調には構造が必要 — ピースが誰が何をどの順序でどの権限で行うかを定義する -- CI/CD連携にはガードレールが必要 — パイプラインモードが非対話でエージェントを実行し、完全な監査ログを残す +**再現可能** — 実行パスを YAML で宣言するから、結果のブレを抑えられます。piece は共有できるので、チームの誰かが作ったワークフローを他のメンバーがそのまま使って同じ品質プロセスを回せます。すべてのステップは NDJSON でログに残るため、タスクから PR まで追跡もできます。 -## TAKTが制御・管理するもの +**マルチエージェント** — 異なるペルソナ・権限・レビュー基準を持つ複数のエージェントを協調させます。並列レビュー、失敗時の差し戻し、ルールによる結果の集約に対応しています。プロンプトは persona・policy・knowledge・instruction の独立したファセットとして管理し、ワークフロー間で自由に組み合わせられます（[Faceted Prompting](./faceted-prompting.ja.md)）。 -TAKTはエージェントの実行を**制御**し、プロンプトの構成要素を**管理**します。 +## 必要なもの -| | 対象 | 説明 | -|---|------|------| -| 制御 | **ルーティング** | 状態遷移ルール（誰がいつ動くか） | -| 制御 | **ツール・権限** | 読み取り専用・編集可・フルアクセス（何を許可するか） | -| 制御 | **記録** | セッションログ・レポート（何を残すか） | -| 管理 | **ペルソナ** | エージェントの役割・専門性（誰として振る舞うか） | -| 管理 | **ポリシー** | コーディング規約・品質基準・禁止事項（何を守るか） | -| 管理 | **ナレッジ** | ドメイン知識・アーキテクチャ情報（何を参照するか） | +次のいずれかが必要です。 -ペルソナ・ポリシー・ナレッジは独立したファイルとして管理され、ワークフロー間で自由に組み合わせられます（[Faceted Prompting](./faceted-prompting.ja.md)）。ポリシーを1ファイル変更すれば、それを使うすべてのワークフローに反映されます。 +- **プロバイダー CLI**: [Claude Code](https://docs.anthropic.com/en/docs/claude-code)、[Codex](https://github.com/openai/codex)、[OpenCode](https://opencode.ai) のいずれか +- **API Key 直接利用**: Anthropic / OpenAI / OpenCode の API Key があれば CLI は不要です -## TAKTとは何でないか +任意: -- **自律型AIエンジニアではない** — TAKTはエージェントを協調させるが、何を作るかは決めない。タスクを与えるのはあなたで、TAKTは実行を統制する。 -- **SkillやSwarmの代替ではない** — Skillは単一エージェントの知識を拡張する。Swarmはエージェントを並列化する。TAKTはエージェント間のワークフロー構造を定義する — 誰がどの順序でどのルールで実行するか。 -- **デフォルトで全自動ではない** — すべてのステップで人の承認を要求できる。自動化はオプトイン（パイプラインモード）であり、デフォルトではない。 +- [GitHub CLI](https://cli.github.com/) (`gh`) — `takt #N` で GitHub Issue を使う場合に必要です -## 必要条件 +## クイックスタート -次のいずれかを選択してください。 - -- **プロバイダーCLIを使用**: [Claude Code](https://docs.anthropic.com/en/docs/claude-code)、[Codex](https://github.com/openai/codex)、または [OpenCode](https://opencode.ai) をインストール -- **API直接利用**: **Anthropic API Key**、**OpenAI API Key**、または **OpenCode API Key**（CLI不要） - -追加で必要なもの: - -- [GitHub CLI](https://cli.github.com/) (`gh`) — `takt #N`（GitHub Issue実行）を使う場合のみ必要 - -**料金について**: API Key を使用する場合、TAKT は Claude API（Anthropic）、OpenAI API、または OpenCode API を直接呼び出します。料金体系は各 CLI ツールを使った場合と同じです。特に CI/CD で自動実行する場合、API 使用量が増えるため、コストに注意してください。 - -## インストール +### インストール ```bash npm install -g takt ``` -## クイックスタート - -```bash -# 対話モードでAIとタスク要件を詰めてから実行 -takt - -# GitHub Issueをタスクとして実行（どちらも同じ） -takt #6 -takt --issue 6 - -# パイプライン実行（非対話・スクリプト/CI向け） -takt --pipeline --task "バグを修正して" --auto-pr -``` - -## 使い方 - -### 対話モード - -AI との会話でタスク内容を詰めてから実行するモード。タスクの要件が曖昧な場合や、AI と相談しながら内容を整理したい場合に便利です。 - -```bash -# 対話モードを開始（引数なし） -takt - -# 最初のメッセージを指定（短い単語のみ） -takt hello -``` - -**注意:** `--task` オプションを指定すると対話モードをスキップして直接タスク実行されます。Issue 参照（`#6`、`--issue`）は対話モードの初期入力として使用されます。 - -対話開始時には `takt list` の履歴を自動取得し、`failed` / `interrupted` / `completed` の実行結果を `pieceContext` に注入して会話要約へ反映します。要約では `Worktree ID`、`開始/終了時刻`、`最終結果`、`失敗要約`、`ログ参照キー` を参照できます。`takt list` の取得に失敗しても対話は継続されます。 - -**フロー:** -1. ピース選択 -2. 対話モード選択（assistant / persona / quiet / passthrough） -3. AI との会話でタスク内容を整理 -4. `/go` でタスク指示を確定（`/go 追加の指示` のように指示を追加することも可能）、または `/play <タスク>` で即座に実行 -5. 実行（worktree 作成、ピース実行、PR 作成） - -#### 対話モードの種類 - -| モード | 説明 | -|--------|------| -| `assistant` | デフォルト。AI が質問を通じてタスク要件を明確にしてから指示を生成。 | -| `persona` | 最初のムーブメントのペルソナとの会話（ペルソナのシステムプロンプトとツールを使用）。 | -| `quiet` | 質問なしでタスク指示を生成（ベストエフォート）。 | -| `passthrough` | ユーザー入力をそのままタスクテキストとして使用。AI 処理なし。 | - -ピースの `interactive_mode` フィールドでデフォルトモードを設定可能。 - -#### 実行例 +### AI と相談して実行する ``` $ takt Select piece: - ❯ 🎼 default (current) - 📁 Development/ - 📁 Research/ - Cancel + > 🎼 default (current) + 📁 🚀 クイックスタート/ + 📁 🎨 フロントエンド/ + 📁 ⚙️ バックエンド/ -対話モード - タスク内容を入力してください。コマンド: /go（実行）, /cancel（終了） +対話モード - タスク内容を入力してください。 +コマンド: /go（実行）, /cancel（終了） -> ユーザー認証機能を追加したい +> ユーザー認証を JWT で追加して -[AI が要件を確認・整理] +[AI が要件を整理してくれます] > /go 提案されたタスク指示: -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -ユーザー認証機能を実装する。 + ... -要件: -- メールアドレスとパスワードによるログイン機能 -- JWT トークンを使った認証 -- パスワードのハッシュ化（bcrypt） -- ログイン・ログアウト API エンドポイント -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - -このタスク指示で進めますか？ (Y/n) y - -? Create worktree? (Y/n) y - -[ピース実行開始...] +どうしますか？ + > 実行する + GitHub Issueを建てる + タスクにつむ + 会話を続ける ``` -### 直接タスク実行 +TAKT が隔離された worktree を作り、piece を実行（計画 → 実装 → レビュー → 修正ループ）します。終わったら PR を作成するか聞いてきます。 -`--task` オプションを使うと、対話モードをスキップして直接実行できます。 +### タスクを積んでまとめて実行する ```bash -# --task オプションでタスク内容を指定 -takt --task "バグを修正" +# 会話でタスクを積みます +takt +> auth モジュールをリファクタリングして +> /go +# → どうしますか？ → 「タスクにつむ」を選択 -# ピース指定 -takt --task "認証機能を追加" --piece expert +# GitHub Issue から積むこともできます +takt add #6 +takt add #12 -# PR 自動作成 -takt --task "バグを修正" --auto-pr -``` - -**注意:** `takt "ログイン機能を追加する"` のように引数として文字列を渡した場合は、対話モードの初期メッセージとして使用されます。 - -### GitHub Issue タスク - -GitHub Issue を直接タスクとして実行できます。Issue のタイトル、本文、ラベル、コメントが自動的にタスク内容として取り込まれます。 - -```bash -# Issue番号を指定して実行 -takt #6 -takt --issue 6 - -# Issue + ピース指定 -takt #6 --piece expert - -# Issue + PR自動作成 -takt #6 --auto-pr -``` - -**必要条件:** [GitHub CLI](https://cli.github.com/) (`gh`) がインストールされ、認証済みであること。 - -### タスク管理（add / run / watch / list） - -`.takt/tasks.yaml` と `.takt/tasks/{slug}/` を使ったバッチ処理。複数のタスクを積んでおいて、後でまとめて実行する使い方に便利です。 - -#### タスクを追加（`takt add`） - -```bash -# AI会話でタスクの要件を詰めてからタスクを追加 -takt add - -# GitHub IssueからタスクAdd（Issue番号がブランチ名に反映される） -takt add #28 -``` - -#### タスクを実行（`takt run`） - -```bash -# .takt/tasks.yaml の保留中タスクをすべて実行 +# まとめて実行します takt run ``` -#### タスクを監視（`takt watch`） +### 結果を管理する ```bash -# .takt/tasks.yaml を監視してタスクを自動実行（常駐プロセス） -takt watch -``` - -#### タスクブランチを一覧表示（`takt list`） - -```bash -# タスクブランチ一覧（マージ・削除） +# 完了・失敗したタスクブランチの一覧を確認し、マージ、リトライ、削除ができます takt list - -# 非対話モード（CI/スクリプト向け） -takt list --non-interactive -takt list --non-interactive --action diff --branch takt/my-branch -takt list --non-interactive --action delete --branch takt/my-branch --yes -takt list --non-interactive --format json ``` -対話モードでは、上記の実行履歴（`failed` / `interrupted` / `completed`）を起動時に再利用し、失敗事例や中断済み実行を再作業対象として特定しやすくします。 +## 仕組み -#### タスクディレクトリ運用（作成・実行・確認） +TAKT は音楽のメタファーを使っています。**piece** がワークフロー、**movement** が各ステップにあたります。 -1. `takt add` を実行して `.takt/tasks.yaml` に pending レコードが作られることを確認する。 -2. 生成された `.takt/tasks/{slug}/order.md` を開き、必要なら仕様や参考資料を追記する。 -3. `takt run`（または `takt watch`）で `tasks.yaml` の pending タスクを実行する。 -4. `task_dir` と同じスラッグの `.takt/runs/{slug}/reports/` を確認する。 - -### パイプラインモード（CI/自動化向け） - -`--pipeline` を指定すると非対話のパイプラインモードに入ります。ブランチ作成 → ピース実行 → commit & push を自動で行います。CI/CD での自動化に適しています。 - -```bash -# タスクをパイプライン実行 -takt --pipeline --task "バグを修正" - -# パイプライン実行 + PR自動作成 -takt --pipeline --task "バグを修正" --auto-pr - -# Issue情報を紐付け -takt --pipeline --issue 99 --auto-pr - -# ピース・ブランチ指定 -takt --pipeline --task "バグを修正" -w magi -b feat/fix-bug - -# リポジトリ指定（PR作成時） -takt --pipeline --task "バグを修正" --auto-pr --repo owner/repo - -# ピース実行のみ（ブランチ作成・commit・pushをスキップ） -takt --pipeline --task "バグを修正" --skip-git - -# 最小限の出力モード（CI向け） -takt --pipeline --task "バグを修正" --quiet -``` - -パイプラインモードでは `--auto-pr` を指定しない限り PR は作成されません。 - -**GitHub との統合:** GitHub Actions で TAKT を使う場合は、[takt-action](https://github.com/nrslib/takt-action) を参照してください。PR レビューやタスク実行を自動化できます。詳細は [CI/CD 連携](#cicd連携) セクションを参照してください。 - -### その他のコマンド - -```bash -# ピースを対話的に切り替え -takt switch - -# ビルトインのピース/エージェントをプロジェクト .takt/ にコピーしてカスタマイズ -takt eject - -# ~/.takt/（グローバル）にコピー -takt eject --global - -# エージェントの会話セッションをクリア -takt clear - -# ビルトインピース・エージェントを Claude Code Skill としてデプロイ -takt export-cc - -# 利用可能なファセットをレイヤー別に一覧表示 -takt catalog -takt catalog personas - -# 特定のファセットをカスタマイズ用にコピー -takt eject persona coder -takt eject instruction plan --global - -# 各ムーブメント・フェーズの組み立て済みプロンプトをプレビュー -takt prompt [piece] - -# ピースカテゴリをビルトインのデフォルトにリセット -takt reset categories - -# グローバル config をテンプレートにリセット（旧設定は .old に退避） -takt reset config -``` - -### おすすめピース - -| ピース | おすすめ用途 | -|------------|------------| -| `default` | 本格的な開発タスク。TAKT自身の開発で使用。アーキテクト＋セキュリティの並列レビュー付き多段階レビュー。 | -| `default-mini` | 簡単な修正やシンプルなタスク。AI アンチパターンレビュー＋スーパーバイザー付きの軽量ピース。 | -| `review-fix-minimal` | レビュー＆修正ピース。レビューフィードバックに基づく反復的な改善に特化。 | -| `research` | 調査・リサーチ。質問せずに自律的にリサーチを実行。 | - -### 主要なオプション - -| オプション | 説明 | -|-----------|------| -| `--pipeline` | **パイプライン（非対話）モードを有効化** — CI/自動化に必須 | -| `-t, --task ` | タスク内容（GitHub Issueの代わり） | -| `-i, --issue ` | GitHub Issue番号（対話モードでは `#N` と同じ） | -| `-w, --piece ` | ピース名、またはピースYAMLファイルのパス | -| `-b, --branch ` | ブランチ名指定（省略時は自動生成） | -| `--auto-pr` | PR作成（対話: 確認スキップ、パイプライン: PR有効化） | -| `--skip-git` | ブランチ作成・commit・pushをスキップ（パイプラインモード、ピース実行のみ） | -| `--repo ` | リポジトリ指定（PR作成時） | -| `--create-worktree ` | worktree確認プロンプトをスキップ | -| `-q, --quiet` | 最小限の出力モード: AIの出力を抑制（CI向け） | -| `--provider ` | エージェントプロバイダーを上書き（claude\|codex\|opencode\|mock） | -| `--model ` | エージェントモデルを上書き | - -## ピース - -TAKTはYAMLベースのピース定義とルールベースルーティングを使用します。ビルトインピースはパッケージに埋め込まれており、`~/.takt/pieces/` のユーザーピースが優先されます。`takt eject` でビルトインを`~/.takt/`にコピーしてカスタマイズできます。 - -> **注記 (v0.4.0)**: ピースコンポーネントの内部用語が "step" から "movement" に変更されました。ユーザー向けのピースファイルは引き続き互換性がありますが、ピースをカスタマイズする場合、YAMLファイルで `movements:` の代わりに `movements:` が使用されることがあります。機能は同じです。 - -### ピースの例 +piece は movement の並びを定義します。各 movement では persona（誰が実行するか）、権限（何を許可するか）、ルール（次にどこへ進むか）を指定します。 ```yaml -name: default -max_movements: 10 +name: simple initial_movement: plan -# セクションマップ — キー: ファイルパス（このYAMLからの相対パス） personas: planner: ../personas/planner.md coder: ../personas/coder.md reviewer: ../personas/architecture-reviewer.md -policies: - coding: ../policies/coding.md - -knowledge: - architecture: ../knowledge/architecture.md - movements: - name: plan persona: planner - model: opus edit: false rules: - - condition: 計画完了 + - condition: Planning complete next: implement - instruction_template: | - リクエストを分析し、実装計画を作成してください。 - name: implement persona: coder - policy: coding - knowledge: architecture edit: true - required_permission_mode: edit rules: - - condition: 実装完了 + - condition: Implementation complete next: review - - condition: 進行不可 - next: ABORT - instruction_template: | - 計画に基づいて実装してください。 - name: review persona: reviewer - knowledge: architecture edit: false rules: - - condition: 承認 + - condition: Approved next: COMPLETE - - condition: 修正が必要 - next: implement - instruction_template: | - アーキテクチャとコード品質の観点で実装をレビューしてください。 + - condition: Needs fix + next: implement # <- 修正ループ ``` -### ペルソナレスムーブメント +ルールが次の movement を決めます。`COMPLETE` で成功終了、`ABORT` で失敗終了です。並列 movement やルール条件の詳細は [Piece Guide](./pieces.md) を参照してください。 -`persona` フィールドは省略可能です。省略した場合、ムーブメントはシステムプロンプトなしで `instruction_template` のみを使って実行されます。これはペルソナのカスタマイズが不要なシンプルなタスクに便利です。 +## おすすめ piece -```yaml - - name: summarize - # persona未指定 — instruction_templateのみを使用 - edit: false - rules: - - condition: 要約完了 - next: COMPLETE - instruction_template: | - レポートを読んで簡潔な要約を提供してください。 -``` +| Piece | 用途 | +|-------|------| +| `default-mini` | ちょっとした修正向けです。計画 → 実装 → 並列レビュー → 修正の軽量構成です。 | +| `frontend-mini` | フロントエンド向けの mini 構成です。 | +| `backend-mini` | バックエンド向けの mini 構成です。 | +| `expert-mini` | エキスパート向けの mini 構成です。 | +| `default` | 本格的な開発向けです。並列レビュアーによる多段階レビューが付いています。TAKT 自身の開発にも使用しています。 | +全ピース・ペルソナの一覧は [Builtin Catalog](./builtin-catalog.ja.md) を参照してください。 -また、`persona` の値としてインラインシステムプロンプトを記述することもできます（指定されたファイルが存在しない場合）: +## 主要コマンド -```yaml - - name: review - persona: "あなたはコードレビュアーです。可読性と保守性に焦点を当ててください。" - edit: false - instruction_template: | - コード品質をレビューしてください。 -``` - -### パラレルムーブメント - -ムーブメント内でサブムーブメントを並列実行し、集約条件で評価できます: - -```yaml - - name: reviewers - parallel: - - name: arch-review - persona: reviewer - rules: - - condition: approved - - condition: needs_fix - instruction_template: | - アーキテクチャとコード品質をレビューしてください。 - - name: security-review - persona: security-reviewer - rules: - - condition: approved - - condition: needs_fix - instruction_template: | - セキュリティ脆弱性をレビューしてください。 - rules: - - condition: all("approved") - next: supervise - - condition: any("needs_fix") - next: fix -``` - -- `all("X")`: すべてのサブムーブメントが条件Xにマッチした場合にtrue -- `any("X")`: いずれかのサブムーブメントが条件Xにマッチした場合にtrue -- サブムーブメントの `rules` は可能な結果を定義しますが、`next` は省略可能（親が遷移を制御） - -### ルール条件の種類 - -| 種類 | 構文 | 説明 | -|------|------|------| -| タグベース | `"条件テキスト"` | エージェントが `[MOVEMENTNAME:N]` タグを出力し、インデックスでマッチ | -| AI判定 | `ai("条件テキスト")` | AIが条件をエージェント出力に対して評価 | -| 集約 | `all("X")` / `any("X")` | パラレルサブムーブメントの結果を集約 | - -## ビルトインピース - -TAKTには複数のビルトインピースが同梱されています: - -| ピース | 説明 | -|------------|------| -| `default` | フル開発ピース: 計画 → 実装 → AI レビュー → 並列レビュー（アーキテクト＋QA）→ スーパーバイザー承認。各レビュー段階に修正ループあり。 | -| `default-mini` | ミニ開発ピース: 計画 → 実装 → 並列レビュー（AI アンチパターン＋スーパーバイザー）→ 修正。レビュー付きの軽量構成。 | -| `frontend-mini` | ミニフロントエンドピース: 計画 → 実装 → 並列レビュー（AI アンチパターン＋スーパーバイザー）。フロントエンドナレッジ注入付き。 | -| `backend-mini` | ミニバックエンドピース: 計画 → 実装 → 並列レビュー（AI アンチパターン＋スーパーバイザー）。バックエンドナレッジ注入付き。 | -| `backend-cqrs-mini` | ミニ CQRS+ES ピース: 計画 → 実装 → 並列レビュー（AI アンチパターン＋スーパーバイザー）。CQRS+ES ナレッジ注入付き。 | -| `review-fix-minimal` | レビュー重視ピース: レビュー → 修正 → スーパーバイザー。レビューフィードバックに基づく反復改善向け。 | -| `research` | リサーチピース: プランナー → ディガー → スーパーバイザー。質問せずに自律的にリサーチを実行。 | -| `deep-research` | ディープリサーチピース: 計画 → 深掘り → 分析 → 統括。発見駆動型の調査で、多角的な分析を行う。 | -| `expert` | フルスタック開発ピース: アーキテクチャ、フロントエンド、セキュリティ、QA レビューと修正ループ。 | -| `expert-mini` | ミニエキスパートピース: 計画 → 実装 → 並列レビュー（AI アンチパターン＋エキスパートスーパーバイザー）。フルスタックナレッジ注入付き。 | -| `expert-cqrs` | フルスタック開発ピース（CQRS+ES特化）: CQRS+ES、フロントエンド、セキュリティ、QA レビューと修正ループ。 | -| `expert-cqrs-mini` | ミニ CQRS+ES エキスパートピース: 計画 → 実装 → 並列レビュー（AI アンチパターン＋エキスパートスーパーバイザー）。CQRS+ES ナレッジ注入付き。 | -| `magi` | エヴァンゲリオンにインスパイアされた審議システム。3つの AI ペルソナ（MELCHIOR、BALTHASAR、CASPER）が分析し投票。 | -| `passthrough` | 最小構成。タスクをそのまま coder に渡す薄いラッパー。レビューなし。 | -| `compound-eye` | マルチモデルレビュー: Claude と Codex に同じ指示を同時送信し、両方の回答を統合。 | -| `review-only` | 変更を加えない読み取り専用のコードレビューピース。 | -| `structural-reform` | プロジェクト全体の構造改革: 段階的なファイル分割を伴う反復的なコードベース再構成。 | -| `unit-test` | ユニットテスト重視ピース: テスト分析 → テスト実装 → レビュー → 修正。 | -| `e2e-test` | E2Eテスト重視ピース: E2E分析 → E2E実装 → レビュー → 修正（VitestベースのE2Eフロー）。 | -| `frontend` | フロントエンド特化開発ピース: React/Next.js 向けのレビューとナレッジ注入。 | -| `backend` | バックエンド特化開発ピース: バックエンド、セキュリティ、QA の専門家レビュー。 | -| `backend-cqrs` | CQRS+ES 特化バックエンド開発ピース: CQRS+ES、セキュリティ、QA の専門家レビュー。 | - -**ペルソナ別プロバイダー設定:** 設定ファイルの `persona_providers` で、特定のペルソナを異なるプロバイダーにルーティングできます（例: coder は Codex、レビュアーは Claude）。ピースを複製する必要はありません。 - -`takt switch` でピースを切り替えられます。 - -## ビルトインペルソナ - -| ペルソナ | 説明 | +| コマンド | 説明 | |---------|------| -| **planner** | タスク分析、仕様調査、実装計画 | -| **architect-planner** | タスク分析と設計計画: コード調査、不明点の解決、実装計画の作成 | -| **coder** | 機能の実装、バグ修正 | -| **ai-antipattern-reviewer** | AI特有のアンチパターンレビュー（存在しないAPI、誤った仮定、スコープクリープ） | -| **architecture-reviewer** | アーキテクチャとコード品質のレビュー、仕様準拠の検証 | -| **frontend-reviewer** | フロントエンド（React/Next.js）のコード品質とベストプラクティスのレビュー | -| **cqrs-es-reviewer** | CQRS+Event Sourcingアーキテクチャと実装のレビュー | -| **qa-reviewer** | テストカバレッジと品質保証のレビュー | -| **security-reviewer** | セキュリティ脆弱性の評価 | -| **conductor** | Phase 3 判定専用: レポートやレスポンスを読み取り、ステータスタグを出力 | -| **supervisor** | 最終検証、バリデーション、承認 | -| **expert-supervisor** | 包括的なレビュー統合による専門レベルの最終検証 | -| **research-planner** | リサーチタスクの計画・スコープ定義 | -| **research-analyzer** | リサーチ結果の解釈と追加調査の計画 | -| **research-digger** | 深掘り調査と情報収集 | -| **research-supervisor** | リサーチ品質の検証と網羅性の評価 | -| **test-planner** | テスト戦略分析と包括的なテスト計画 | -| **pr-commenter** | レビュー結果を GitHub PR にコメントとして投稿 | +| `takt` | AI と相談して、タスクを実行または積みます | +| `takt run` | 積まれたタスクをまとめて実行します | +| `takt list` | タスクブランチを管理します（マージ、リトライ、追加指示、削除） | +| `takt #N` | GitHub Issue をタスクとして実行します | +| `takt switch` | 使う piece を切り替えます | +| `takt eject` | ビルトインの piece/persona をコピーしてカスタマイズできます | -## カスタムペルソナ +全コマンド・オプションは [CLI Reference](./cli-reference.ja.md) を参照してください。 -Markdown ファイルでペルソナプロンプトを作成: +## 設定 + +最小限の `~/.takt/config.yaml` は次の通りです。 + +```yaml +provider: claude # claude, codex, or opencode +model: sonnet # プロバイダーにそのまま渡されます +language: ja # en or ja +``` + +API Key を直接使う場合は、CLI のインストールは不要です。 + +```bash +export TAKT_ANTHROPIC_API_KEY=sk-ant-... +``` + +全設定項目・プロバイダープロファイル・モデル解決の詳細は [Configuration Guide](./configuration.ja.md) を参照してください。 + +## カスタマイズ + +### カスタム piece + +```bash +takt eject default # ビルトインを ~/.takt/pieces/ にコピーして編集できます +``` + +### カスタム persona + +`~/.takt/personas/` に Markdown ファイルを置きます。 ```markdown # ~/.takt/personas/my-reviewer.md - -あなたはセキュリティに特化したコードレビュアーです。 - -## 役割 -- セキュリティ脆弱性をチェック -- 入力バリデーションを検証 -- 認証ロジックをレビュー +You are a code reviewer specialized in security. ``` -## モデル選択 +piece から `persona: my-reviewer` で参照できます。 -`model` フィールド（ピースのムーブメント、エージェント設定、グローバル設定）はプロバイダー（Claude Code CLI / Codex SDK）にそのまま渡されます。TAKTはモデルエイリアスの解決を行いません。 +詳細は [Piece Guide](./pieces.md) と [Agent Guide](./agents.md) を参照してください。 -### Claude Code +## CI/CD -Claude Code はエイリアス（`opus`、`sonnet`、`haiku`、`opusplan`、`default`）およびフルモデル名（例: `claude-sonnet-4-5-20250929`）をサポートしています。利用可能なモデルは [Claude Code ドキュメント](https://docs.anthropic.com/en/docs/claude-code)を参照してください。 +GitHub Actions 向けに [takt-action](https://github.com/nrslib/takt-action) を提供しています。 -### Codex +```yaml +- uses: nrslib/takt-action@main + with: + anthropic_api_key: ${{ secrets.TAKT_ANTHROPIC_API_KEY }} + github_token: ${{ secrets.GITHUB_TOKEN }} +``` -モデル文字列はCodex SDKに渡されます。未指定の場合は `codex` がデフォルトです。利用可能なモデルはCodexのドキュメントを参照してください。 +他の CI ではパイプラインモードを使います。 + +```bash +takt --pipeline --task "バグを修正して" --auto-pr +``` + +セットアップの詳細は [CI/CD Guide](./ci-cd.ja.md) を参照してください。 ## プロジェクト構造 ``` -~/.takt/ # グローバル設定ディレクトリ -├── config.yaml # グローバル設定（プロバイダー、モデル、ピース等） -├── pieces/ # ユーザーピース定義（ビルトインを上書き） -│ └── custom.yaml -└── personas/ # ユーザーペルソナプロンプトファイル（.md） - └── my-persona.md +~/.takt/ # グローバル設定 +├── config.yaml # プロバイダー、モデル、言語など +├── pieces/ # ユーザー定義の piece +└── personas/ # ユーザー定義の persona -.takt/ # プロジェクトレベルの設定 -├── config.yaml # プロジェクト設定（現在のピース等） -├── tasks/ # タスク入力ディレクトリ（.takt/tasks/{slug}/order.md など） -├── tasks.yaml # 保留中タスクのメタデータ（task_dir, piece, worktree など） -└── runs/ # 実行単位の成果物 - └── {slug}/ - ├── reports/ # 実行レポート（自動生成） - ├── context/ # knowledge/policy/previous_response のスナップショット - ├── logs/ # この実行専用の NDJSON セッションログ - └── meta.json # run メタデータ +.takt/ # プロジェクトレベル +├── config.yaml # プロジェクト設定 +├── tasks.yaml # 積まれたタスク +├── tasks/ # タスクの仕様書 +└── runs/ # 実行レポート、ログ、コンテキスト ``` -ビルトインリソースはnpmパッケージ（`builtins/`）に埋め込まれています。`~/.takt/` のユーザーファイルが優先されます。 - -### グローバル設定 - -`~/.takt/config.yaml` のサンプルです。 -コメントで「通常設定」と「ピースにも関わる設定」を分けています。 - -```yaml -# ~/.takt/config.yaml - -# ===================================== -# 通常設定（ピース非依存） -# ===================================== -language: ja # 表示言語: ja | en -log_level: info # ログレベル: debug | info | warn | error -provider: claude # デフォルト実行プロバイダー: claude | codex | opencode | mock -# model: sonnet # 省略可。providerに渡すモデル名 - -# 実行制御 -# worktree_dir: ~/takt-worktrees # 共有clone作成先ディレクトリ -# auto_pr: false # worktree実行後に自動PR作成するか -branch_name_strategy: ai # ブランチ名生成: romaji | ai -concurrency: 2 # takt run の同時実行数（1-10） -# task_poll_interval_ms: 500 # takt run のタスク監視間隔ms（100-5000） -# prevent_sleep: false # macOS実行中のスリープ防止（caffeinate） - -# 出力・通知 -# minimal_output: false # 出力を最小化（CI向け） -# verbose: false # 詳細ログを有効化 -# notification_sound: true # 通知音全体のON/OFF -# notification_sound_events: # イベント別通知音（未指定はtrue扱い） -# iteration_limit: true -# piece_complete: true -# piece_abort: true -# run_complete: true -# run_abort: true -# observability: -# provider_events: false # providerイベントログを記録 - -# 認証情報（環境変数優先） -# anthropic_api_key: "sk-ant-..." # Claude APIキー -# openai_api_key: "sk-..." # Codex APIキー -# opencode_api_key: "..." # OpenCode APIキー -# codex_cli_path: "/absolute/path/to/codex" # Codex CLI絶対パス - -# パイプライン -# pipeline: -# default_branch_prefix: "takt/" # pipeline作成ブランチの接頭辞 -# commit_message_template: "feat: {title} (#{issue})" # コミット文テンプレート -# pr_body_template: | # PR本文テンプレート -# ## Summary -# {issue_body} -# Closes #{issue} - -# その他 -# bookmarks_file: ~/.takt/preferences/bookmarks.yaml # ブックマーク保存先 - -# ===================================== -# ピースにも関わる設定（global defaults） -# ===================================== -# 1) ペルソナ単位でプロバイダーを切り替える -# persona_providers: -# coder: codex # coderペルソナはcodexで実行 -# reviewer: claude # reviewerペルソナはclaudeで実行 - -# 2) provider 固有オプション（global < project < piece） -# provider_options: -# codex: -# network_access: true # Codex実行時のネットワークアクセス許可 -# opencode: -# network_access: true # OpenCode実行時のネットワークアクセス許可 -# claude: -# sandbox: -# allow_unsandboxed_commands: false # trueで対象コマンドを非サンドボックス実行 -# excluded_commands: -# - "npm publish" # 非サンドボックス対象コマンド - -# 3) movement の権限ポリシー -# provider_profiles: -# codex: -# default_permission_mode: full # 既定権限: readonly | edit | full -# movement_permission_overrides: -# ai_review: readonly # movement単位の上書き -# claude: -# default_permission_mode: edit - -# 4) 実行前のランタイム準備（推奨: 有効化） -runtime: - prepare: - - gradle # Gradleキャッシュ/環境を .runtime 配下に準備 - - node # npmキャッシュ/環境を .runtime 配下に準備 - -# 5) ピース一覧/カテゴリ -# enable_builtin_pieces: true # builtins/{lang}/pieces を有効化 -# disabled_builtins: -# - magi # 無効化するビルトインピース名 -# piece_categories_file: ~/.takt/preferences/piece-categories.yaml # カテゴリ定義ファイル -# interactive_preview_movements: 3 # 対話モードのプレビュー件数（0-10） -``` - -主要な設定項目の説明: - -**通常設定** -| 項目 | 説明 | -|------|------| -| `language` | 表示言語（`ja` / `en`） | -| `log_level` | ログレベル（`debug` / `info` / `warn` / `error`） | -| `provider` | デフォルト実行プロバイダー（`claude` / `codex` / `opencode` / `mock`） | -| `model` | モデル名（provider にそのまま渡される） | -| `auto_pr` | worktree 実行後のPR作成挙動 | -| `concurrency` | `takt run` の同時実行数（1-10） | -| `task_poll_interval_ms` | `takt run` のタスク監視間隔（100-5000ms） | -| `minimal_output` | CI向けの簡易出力モード | -| `verbose` | 詳細ログ出力 | -| `notification_sound` / `notification_sound_events` | 通知音のON/OFFとイベント別制御 | -| `pipeline.*` | pipeline 実行時のブランチ/コミット/PRテンプレート | - -**ピースにも関わる設定** -| 項目 | 説明 | -|------|------| -| `persona_providers` | ペルソナ単位の provider 上書き | -| `provider_options` | provider固有オプション（例: `codex.network_access`、`claude.sandbox.*`） | -| `provider_profiles` | movement ごとの permission mode 解決ルール | -| `runtime.prepare` | 実行前の環境準備（`gradle` / `node` / 任意スクリプト） | -| `enable_builtin_pieces` / `disabled_builtins` | ビルトインピースの有効化/除外 | -| `piece_categories_file` | ピースカテゴリ定義ファイルの場所 | -| `interactive_preview_movements` | 対話モードで表示する movement プレビュー数 | - -### プロジェクトローカル設定 - -`.takt/config.yaml` のサンプルです。 -チーム/リポジトリごとの既定値を置く用途です。 - -```yaml -# .takt/config.yaml - -# ===================================== -# 通常設定（ピース非依存） -# ===================================== -piece: default # このプロジェクトで使う既定ピース名 -provider: claude # プロジェクト既定プロバイダー: claude | codex | opencode | mock -# verbose: false # このプロジェクトだけ詳細ログを有効化する場合 -# auto_pr: false # worktree実行後に自動PR作成するか - -# ===================================== -# ピースにも関わる設定（project overrides） -# ===================================== -# provider_options: -# codex: -# network_access: true # グローバル設定をこのプロジェクトで上書き -# claude: -# sandbox: -# allow_unsandboxed_commands: false -# excluded_commands: -# - "npm publish" - -# provider_profiles: -# codex: -# default_permission_mode: full -# movement_permission_overrides: -# ai_review: readonly -``` - -プロジェクトローカルで使える主な項目: - -| 項目 | 説明 | -|------|------| -| `piece` | プロジェクト既定のピース | -| `provider` | プロジェクト既定のプロバイダー | -| `verbose` | ローカル詳細ログ | -| `auto_pr` | ローカル既定のPR作成挙動 | -| `provider_options` | provider固有オプションのローカル上書き | -| `provider_profiles` | movement権限ポリシーのローカル上書き | - -設定解決の優先順位（高 → 低）: -1. 環境変数（`TAKT_*`） -2. `.takt/config.yaml`（プロジェクトローカル） -3. `~/.takt/config.yaml`（グローバル） -4. デフォルト値 - -**注意:** Codex SDK は Git 管理下のディレクトリでのみ動作します。`--skip-git-repo-check` は Codex CLI 専用です。 - -**API Key の設定方法:** - -1. **環境変数で設定**: - ```bash - export TAKT_ANTHROPIC_API_KEY=sk-ant-... # Claude の場合 - export TAKT_OPENAI_API_KEY=sk-... # Codex の場合 - export TAKT_OPENCODE_API_KEY=... # OpenCode の場合 - ``` - -2. **設定ファイルで設定**: - 上記の `~/.takt/config.yaml` に `anthropic_api_key`、`openai_api_key`、または `opencode_api_key` を記述 - -優先順位: 環境変数 > `config.yaml` の設定 - -**注意事項:** -- API Key を設定した場合、Claude Code、Codex、OpenCode のインストールは不要です。TAKT が直接各 API を呼び出します。 -- **セキュリティ**: `config.yaml` に API Key を記述した場合、このファイルを Git にコミットしないよう注意してください。環境変数での設定を使うか、`.gitignore` に `~/.takt/config.yaml` を追加することを検討してください。 - -**パイプラインテンプレート変数:** - -| 変数 | 使用可能箇所 | 説明 | -|------|-------------|------| -| `{title}` | コミットメッセージ | Issueタイトル | -| `{issue}` | コミットメッセージ、PR本文 | Issue番号 | -| `{issue_body}` | PR本文 | Issue本文 | -| `{report}` | PR本文 | ピース実行レポート | - -**モデル解決の優先順位:** -1. ピースのムーブメントの `model`（最優先） -2. カスタムエージェントの `model` -3. グローバル設定の `model` -4. プロバイダーデフォルト（Claude: sonnet、Codex: codex、OpenCode: プロバイダーデフォルト） - -## 詳細ガイド - -### タスクディレクトリ形式 - -TAKT は `.takt/tasks.yaml` にタスクのメタデータを保存し、長文仕様は `.takt/tasks/{slug}/` に分離して管理します。 - -**推奨構成**: - -```text -.takt/ - tasks/ - 20260201-015714-foptng/ - order.md - schema.sql - wireframe.png - tasks.yaml - runs/ - 20260201-015714-foptng/ - reports/ -``` - -**tasks.yaml レコード例**: - -```yaml -tasks: - - name: add-auth-feature - status: pending - task_dir: .takt/tasks/20260201-015714-foptng - piece: default - created_at: "2026-02-01T01:57:14.000Z" - started_at: null - completed_at: null -``` - -`takt add` は `.takt/tasks/{slug}/order.md` を自動生成し、`tasks.yaml` には `task_dir` を保存します。 - -#### 共有クローンによる隔離実行 - -YAMLタスクファイルで`worktree`を指定すると、各タスクを`git clone --shared`で作成した隔離クローンで実行し、メインの作業ディレクトリをクリーンに保てます: - -- `worktree: true` - 隣接ディレクトリ（または`worktree_dir`設定で指定した場所）に共有クローンを自動作成 -- `worktree: "/path/to/dir"` - 指定パスに作成 -- `branch: "feat/xxx"` - 指定ブランチを使用（省略時は`takt/{timestamp}-{slug}`で自動生成） -- `worktree`省略 - カレントディレクトリで実行（デフォルト） - -> **Note**: YAMLフィールド名は後方互換のため`worktree`のままです。内部的には`git worktree`ではなく`git clone --shared`を使用しています。git worktreeの`.git`ファイルには`gitdir:`でメインリポジトリへのパスが記載されており、Claude Codeがそれを辿ってメインリポジトリをプロジェクトルートと認識してしまうためです。共有クローンは独立した`.git`ディレクトリを持つため、この問題が発生しません。 - -クローンは使い捨てです。タスク完了後に自動的にコミット＋プッシュし、クローンを削除します。ブランチが唯一の永続的な成果物です。`takt list` でブランチの一覧表示・マージ・削除ができます。 - -### セッションログ - -TAKTはセッションログをNDJSON（`.jsonl`）形式で`.takt/runs/{slug}/logs/`に書き込みます。各レコードはアトミックに追記されるため、プロセスが途中でクラッシュしても部分的なログが保持され、`tail -f`でリアルタイムに追跡できます。 - -- `.takt/runs/{slug}/logs/{sessionId}.jsonl` - ピース実行ごとのNDJSONセッションログ -- `.takt/runs/{slug}/meta.json` - run メタデータ（`task`, `piece`, `start/end`, `status` など） - -レコード種別: `piece_start`, `step_start`, `step_complete`, `piece_complete`, `piece_abort` - -最新の previous response は `.takt/runs/{slug}/context/previous_responses/latest.md` に保存され、実行時に自動的に引き継がれます。 - -### カスタムピースの追加 - -`~/.takt/pieces/` に YAML ファイルを追加するか、`takt eject` でビルトインをカスタマイズします: - -```bash -# defaultピースを~/.takt/pieces/にコピーして編集 -takt eject default -``` - -```yaml -# ~/.takt/pieces/my-piece.yaml -name: my-piece -description: カスタムピース -max_movements: 5 -initial_movement: analyze - -personas: - analyzer: ~/.takt/personas/analyzer.md - coder: ../personas/coder.md - -movements: - - name: analyze - persona: analyzer - edit: false - rules: - - condition: 分析完了 - next: implement - instruction_template: | - このリクエストを徹底的に分析してください。 - - - name: implement - persona: coder - edit: true - required_permission_mode: edit - pass_previous_response: true - rules: - - condition: 完了 - next: COMPLETE - instruction_template: | - 分析に基づいて実装してください。 -``` - -> **Note**: `{task}`、`{previous_response}`、`{user_inputs}` は自動的にインストラクションに注入されます。テンプレート内での位置を制御したい場合のみ、明示的なプレースホルダーが必要です。 - -### ペルソナをパスで指定する - -セクションマップでキーとファイルパスを対応付け、ムーブメントからキーで参照します: - -```yaml -# セクションマップ（ピースファイルからの相対パス） -personas: - coder: ../personas/coder.md - reviewer: ~/.takt/personas/my-reviewer.md -``` - -### ピース変数 - -`instruction_template`で使用可能な変数: - -| 変数 | 説明 | -|------|------| -| `{task}` | 元のユーザーリクエスト（テンプレートになければ自動注入） | -| `{iteration}` | ピース全体のターン数（実行された全ムーブメント数） | -| `{max_movements}` | 最大イテレーション数 | -| `{movement_iteration}` | ムーブメントごとのイテレーション数（このムーブメントが実行された回数） | -| `{previous_response}` | 前のムーブメントの出力（テンプレートになければ自動注入） | -| `{user_inputs}` | ピース中の追加ユーザー入力（テンプレートになければ自動注入） | -| `{report_dir}` | レポートディレクトリパス（例: `.takt/runs/20250126-143052-task-summary/reports`） | -| `{report:filename}` | `{report_dir}/filename` に展開（例: `{report:00-plan.md}`） | - -### ピースの設計 - -各ピースのムーブメントに必要な要素: - -**1. ペルソナ** - セクションマップのキーで参照（system promptとして使用）: - -```yaml -persona: coder # personas セクションマップのキー -persona_name: coder # 表示名（オプション） -``` - -**2. ルール** - ムーブメントから次のムーブメントへのルーティングを定義。インストラクションビルダーがステータス出力ルールを自動注入するため、エージェントはどのタグを出力すべきか把握できます: - -```yaml -rules: - - condition: "実装完了" - next: review - - condition: "進行不可" - next: ABORT -``` - -特殊な `next` 値: `COMPLETE`（成功）、`ABORT`（失敗） - -**3. ムーブメントオプション:** - -| オプション | デフォルト | 説明 | -|-----------|-----------|------| -| `edit` | - | ムーブメントがプロジェクトファイルを編集できるか（`true`/`false`） | -| `pass_previous_response` | `true` | 前のムーブメントの出力を`{previous_response}`に渡す | -| `allowed_tools` | - | エージェントが使用できるツール一覧（Read, Glob, Grep, Edit, Write, Bash等） | -| `provider` | - | このムーブメントのプロバイダーを上書き（`claude`、`codex`、または`opencode`） | -| `model` | - | このムーブメントのモデルを上書き | -| `required_permission_mode` | - | 必要最小パーミッションモード: `readonly`、`edit`、`full`（下限として機能; 実際のモードは `provider_profiles` で解決） | -| `provider_options` | - | プロバイダー固有オプション（例: `codex.network_access`、`opencode.network_access`） | -| `output_contracts` | - | レポートファイルの出力契約定義 | -| `quality_gates` | - | ムーブメント完了要件のAIディレクティブ | -| `mcp_servers` | - | MCP（Model Context Protocol）サーバー設定（stdio/SSE/HTTP） | - -ピース全体のデフォルトは `piece_config.provider_options` で設定でき、ムーブメント側 `provider_options` で上書きできます。 - -```yaml -piece_config: - provider_options: - codex: - network_access: true - opencode: - network_access: true - runtime: - prepare: - - gradle - - node -``` - -`runtime.prepare` にはビルトインプリセット（`gradle`、`node`）またはカスタムシェルスクリプトのパスを指定できます。スクリプトは `TAKT_RUNTIME_ROOT` などの環境変数を受け取り、stdout で追加の環境変数をエクスポートできます。 - -## API使用例 +## API ```typescript -import { PieceEngine, loadPiece } from 'takt'; // npm install takt +import { PieceEngine, loadPiece } from 'takt'; const config = loadPiece('default'); -if (!config) { - throw new Error('Piece not found'); -} -const engine = new PieceEngine(config, process.cwd(), 'My task'); +if (!config) throw new Error('Piece not found'); +const engine = new PieceEngine(config, process.cwd(), 'My task'); engine.on('step:complete', (step, response) => { console.log(`${step.name}: ${response.status}`); }); @@ -976,82 +248,25 @@ engine.on('step:complete', (step, response) => { await engine.run(); ``` -## コントリビュート - -詳細は[CONTRIBUTING.md](../CONTRIBUTING.md)を参照。 - -## CI/CD連携 - -### GitHub Actions - -TAKTはPRレビューやタスク実行を自動化するGitHub Actionを提供しています。詳細は [takt-action](https://github.com/nrslib/takt-action) を参照してください。 - -**ピース例** (このリポジトリの [.github/workflows/takt-action.yml](../.github/workflows/takt-action.yml) を参照): - -```yaml -name: TAKT - -on: - issue_comment: - types: [created] - -jobs: - takt: - if: contains(github.event.comment.body, '@takt') - runs-on: ubuntu-latest - permissions: - contents: write - issues: write - pull-requests: write - - steps: - - name: Checkout - uses: actions/checkout@v4 - - - name: Run TAKT - uses: nrslib/takt-action@main - with: - anthropic_api_key: ${{ secrets.TAKT_ANTHROPIC_API_KEY }} - github_token: ${{ secrets.GITHUB_TOKEN }} -``` - -**コスト警告**: TAKTはAI API（ClaudeまたはOpenAI）を使用するため、特にCI/CD環境でタスクが自動実行される場合、かなりのコストが発生する可能性があります。API使用量を監視し、請求アラートを設定してください。 - -### その他のCIシステム - -GitHub以外のCIシステムでは、パイプラインモードを使用します: - -```bash -# taktをインストール -npm install -g takt - -# パイプラインモードで実行 -takt --pipeline --task "バグ修正" --auto-pr --repo owner/repo -``` - -認証には `TAKT_ANTHROPIC_API_KEY`、`TAKT_OPENAI_API_KEY`、または `TAKT_OPENCODE_API_KEY` 環境変数を設定してください（TAKT 独自のプレフィックス付き）。 - -```bash -# Claude (Anthropic) を使う場合 -export TAKT_ANTHROPIC_API_KEY=sk-ant-... - -# Codex (OpenAI) を使う場合 -export TAKT_OPENAI_API_KEY=sk-... - -# OpenCode を使う場合 -export TAKT_OPENCODE_API_KEY=... -``` - ## ドキュメント -- [Faceted Prompting](./faceted-prompting.ja.md) - AIプロンプトへの関心の分離（Persona, Policy, Instruction, Knowledge, Output Contract） -- [Piece Guide](./pieces.md) - ピースの作成とカスタマイズ -- [Agent Guide](./agents.md) - カスタムエージェントの設定 -- [Retry and Session](./implements/retry-and-session.ja.md) - failed タスクの retry とセッション再開 -- [Changelog](../CHANGELOG.md) ([日本語](./CHANGELOG.ja.md)) - バージョン履歴 -- [Security Policy](../SECURITY.md) - 脆弱性報告 -- [ブログ: TAKT - AIエージェントオーケストレーション](https://zenn.dev/nrs/articles/c6842288a526d7) - 設計思想と実践的な使い方ガイド +| ドキュメント | 内容 | +|-------------|------| +| [CLI Reference](./cli-reference.ja.md) | 全コマンド・オプション | +| [Configuration](./configuration.ja.md) | グローバル設定・プロジェクト設定 | +| [Piece Guide](./pieces.md) | piece の作成・カスタマイズ | +| [Agent Guide](./agents.md) | カスタムエージェントの設定 | +| [Builtin Catalog](./builtin-catalog.ja.md) | ビルトイン piece・persona の一覧 | +| [Faceted Prompting](./faceted-prompting.ja.md) | プロンプト設計の方法論 | +| [Task Management](./task-management.ja.md) | タスクの追加・実行・隔離 | +| [CI/CD Integration](./ci-cd.ja.md) | GitHub Actions・パイプラインモード | +| [Changelog](../CHANGELOG.md) ([日本語](./CHANGELOG.ja.md)) | バージョン履歴 | +| [Security Policy](../SECURITY.md) | 脆弱性の報告 | + +## コントリビュート + +[CONTRIBUTING.md](../CONTRIBUTING.md) を参照してください。 ## ライセンス -MIT - 詳細は[LICENSE](../LICENSE)をご覧ください。 +MIT — [LICENSE](../LICENSE) を参照してください。 diff --git a/docs/builtin-catalog.ja.md b/docs/builtin-catalog.ja.md new file mode 100644 index 0000000..2ca4c58 --- /dev/null +++ b/docs/builtin-catalog.ja.md @@ -0,0 +1,109 @@ +# ビルトインカタログ + +[English](./builtin-catalog.md) + +TAKT に同梱されているすべてのビルトイン piece と persona の総合カタログです。 + +## おすすめ Piece + +| Piece | 推奨用途 | +|----------|-----------------| +| `default-mini` | ちょっとした修正向けです。計画 → 実装 → 並列レビュー → 修正の軽量構成です。 | +| `frontend-mini` | フロントエンド向けの mini 構成です。 | +| `backend-mini` | バックエンド向けの mini 構成です。 | +| `expert-mini` | エキスパート向けの mini 構成です。 | +| `default` | 本格的な開発向けです。並列レビュアーによる多段階レビューが付いています。TAKT 自身の開発にも使用しています。 | + +## 全ビルトイン Piece 一覧 + +カテゴリ順に並べています。 + +| カテゴリ | Piece | 説明 | +|---------|----------|-------------| +| 🚀 クイックスタート | `default-mini` | ミニ開発 piece: plan -> implement -> 並列レビュー (AI antipattern + supervisor) -> 必要に応じて修正。レビュー付き軽量版。 | +| | `frontend-mini` | ミニフロントエンド piece: plan -> implement -> 並列レビュー (AI antipattern + supervisor)。フロントエンドナレッジ注入付き。 | +| | `backend-mini` | ミニバックエンド piece: plan -> implement -> 並列レビュー (AI antipattern + supervisor)。バックエンドナレッジ注入付き。 | +| | `default` | フル開発 piece: plan -> implement -> AI review -> 並列レビュー (architect + QA) -> supervisor 承認。各レビュー段階に修正ループあり。 | +| | `compound-eye` | マルチモデルレビュー: 同じ指示を Claude と Codex に同時送信し、両方のレスポンスを統合。 | +| ⚡ Mini | `backend-cqrs-mini` | ミニ CQRS+ES piece: plan -> implement -> 並列レビュー (AI antipattern + supervisor)。CQRS+ES ナレッジ注入付き。 | +| | `expert-mini` | ミニエキスパート piece: plan -> implement -> 並列レビュー (AI antipattern + expert supervisor)。フルスタックナレッジ注入付き。 | +| | `expert-cqrs-mini` | ミニ CQRS+ES エキスパート piece: plan -> implement -> 並列レビュー (AI antipattern + expert supervisor)。CQRS+ES ナレッジ注入付き。 | +| 🎨 フロントエンド | `frontend` | フロントエンド特化開発 piece。React/Next.js に焦点を当てたレビューとナレッジ注入付き。 | +| ⚙️ バックエンド | `backend` | バックエンド特化開発 piece。バックエンド、セキュリティ、QA エキスパートレビュー付き。 | +| | `backend-cqrs` | CQRS+ES 特化バックエンド開発 piece。CQRS+ES、セキュリティ、QA エキスパートレビュー付き。 | +| 🔧 エキスパート | `expert` | フルスタック開発 piece: architecture、frontend、security、QA レビューと修正ループ付き。 | +| | `expert-cqrs` | フルスタック開発 piece (CQRS+ES 特化): CQRS+ES、frontend、security、QA レビューと修正ループ付き。 | +| 🛠️ リファクタリング | `structural-reform` | プロジェクト全体のレビューと構造改革: 段階的なファイル分割による反復的なコードベース再構築。 | +| 🔍 レビュー | `review-fix-minimal` | レビュー特化 piece: review -> fix -> supervisor。レビューフィードバックに基づく反復改善向け。 | +| | `review-only` | 変更を加えない読み取り専用のコードレビュー piece。 | +| 🧪 テスト | `unit-test` | ユニットテスト特化 piece: テスト分析 -> テスト実装 -> レビュー -> 修正。 | +| | `e2e-test` | E2E テスト特化 piece: E2E 分析 -> E2E 実装 -> レビュー -> 修正 (Vitest ベースの E2E フロー)。 | +| その他 | `research` | リサーチ piece: planner -> digger -> supervisor。質問せずに自律的にリサーチを実行。 | +| | `deep-research` | ディープリサーチ piece: plan -> dig -> analyze -> supervise。発見駆動型の調査で、浮上した疑問を多角的に分析。 | +| | `magi` | エヴァンゲリオンにインスパイアされた合議システム。3つの AI persona (MELCHIOR, BALTHASAR, CASPER) が分析・投票。 | +| | `passthrough` | 最薄ラッパー。タスクを coder にそのまま渡す。レビューなし。 | + +`takt switch` で piece をインタラクティブに切り替えできます。 + +## ビルトイン Persona 一覧 + +| Persona | 説明 | +|---------|-------------| +| **planner** | タスク分析、仕様調査、実装計画 | +| **architect-planner** | タスク分析と設計計画: コード調査、不明点の解消、実装計画の作成 | +| **coder** | 機能実装、バグ修正 | +| **ai-antipattern-reviewer** | AI 固有のアンチパターンレビュー（存在しない API、誤った前提、スコープクリープ） | +| **architecture-reviewer** | アーキテクチャとコード品質のレビュー、仕様準拠の検証 | +| **frontend-reviewer** | フロントエンド (React/Next.js) のコード品質とベストプラクティスのレビュー | +| **cqrs-es-reviewer** | CQRS+Event Sourcing のアーキテクチャと実装のレビュー | +| **qa-reviewer** | テストカバレッジと品質保証のレビュー | +| **security-reviewer** | セキュリティ脆弱性の評価 | +| **conductor** | Phase 3 判定スペシャリスト: レポート/レスポンスを読み取りステータスタグを出力 | +| **supervisor** | 最終検証、承認 | +| **expert-supervisor** | エキスパートレベルの最終検証と包括的なレビュー統合 | +| **research-planner** | リサーチタスクの計画とスコープ定義 | +| **research-analyzer** | リサーチ結果の解釈と追加調査計画 | +| **research-digger** | 深掘り調査と情報収集 | +| **research-supervisor** | リサーチ品質の検証と完全性の評価 | +| **test-planner** | テスト戦略の分析と包括的なテスト計画 | +| **pr-commenter** | レビュー結果を GitHub PR コメントとして投稿 | + +## カスタム Persona + +`~/.takt/personas/` に Markdown ファイルとして persona プロンプトを作成できます。 + +```markdown +# ~/.takt/personas/my-reviewer.md + +You are a code reviewer specialized in security. + +## Role +- Check for security vulnerabilities +- Verify input validation +- Review authentication logic +``` + +piece YAML の `personas` セクションマップからカスタム persona を参照します。 + +```yaml +personas: + my-reviewer: ~/.takt/personas/my-reviewer.md + +movements: + - name: review + persona: my-reviewer + # ... +``` + +## Persona 別 Provider オーバーライド + +`~/.takt/config.yaml` の `persona_providers` を使用して、piece を複製せずに特定の persona を異なる provider にルーティングできます。これにより、例えばコーディングは Codex で実行し、レビューアーは Claude に維持するといった構成が可能になります。 + +```yaml +# ~/.takt/config.yaml +persona_providers: + coder: codex # coder を Codex で実行 + ai-antipattern-reviewer: claude # レビューアーは Claude を維持 +``` + +この設定はすべての piece にグローバルに適用されます。指定された persona を使用する movement は、実行中の piece に関係なく、対応する provider にルーティングされます。 diff --git a/docs/builtin-catalog.md b/docs/builtin-catalog.md new file mode 100644 index 0000000..b800e76 --- /dev/null +++ b/docs/builtin-catalog.md @@ -0,0 +1,109 @@ +# Builtin Catalog + +[日本語](./builtin-catalog.ja.md) + +A comprehensive catalog of all builtin pieces and personas included with TAKT. + +## Recommended Pieces + +| Piece | Recommended Use | +|----------|-----------------| +| `default-mini` | Quick fixes. Lightweight plan → implement → parallel review → fix loop. | +| `frontend-mini` | Frontend-focused mini configuration. | +| `backend-mini` | Backend-focused mini configuration. | +| `expert-mini` | Expert-level mini configuration. | +| `default` | Serious development. Multi-stage review with parallel reviewers. Used for TAKT's own development. | + +## All Builtin Pieces + +Organized by category. + +| Category | Piece | Description | +|----------|----------|-------------| +| 🚀 Quick Start | `default-mini` | Mini development piece: plan -> implement -> parallel review (AI antipattern + supervisor) -> fix if needed. Lightweight with review. | +| | `frontend-mini` | Mini frontend piece: plan -> implement -> parallel review (AI antipattern + supervisor) with frontend knowledge injection. | +| | `backend-mini` | Mini backend piece: plan -> implement -> parallel review (AI antipattern + supervisor) with backend knowledge injection. | +| | `default` | Full development piece: plan -> implement -> AI review -> parallel review (architect + QA) -> supervisor approval. Includes fix loops at each review stage. | +| | `compound-eye` | Multi-model review: sends the same instruction to Claude and Codex simultaneously, then synthesizes both responses. | +| ⚡ Mini | `backend-cqrs-mini` | Mini CQRS+ES piece: plan -> implement -> parallel review (AI antipattern + supervisor) with CQRS+ES knowledge injection. | +| | `expert-mini` | Mini expert piece: plan -> implement -> parallel review (AI antipattern + expert supervisor) with full-stack knowledge injection. | +| | `expert-cqrs-mini` | Mini CQRS+ES expert piece: plan -> implement -> parallel review (AI antipattern + expert supervisor) with CQRS+ES knowledge injection. | +| 🎨 Frontend | `frontend` | Frontend-specialized development piece with React/Next.js focused reviews and knowledge injection. | +| ⚙️ Backend | `backend` | Backend-specialized development piece with backend, security, and QA expert reviews. | +| | `backend-cqrs` | CQRS+ES-specialized backend development piece with CQRS+ES, security, and QA expert reviews. | +| 🔧 Expert | `expert` | Full-stack development piece: architecture, frontend, security, QA reviews with fix loops. | +| | `expert-cqrs` | Full-stack development piece (CQRS+ES specialized): CQRS+ES, frontend, security, QA reviews with fix loops. | +| 🛠️ Refactoring | `structural-reform` | Full project review and structural reform: iterative codebase restructuring with staged file splits. | +| 🔍 Review | `review-fix-minimal` | Review-focused piece: review -> fix -> supervisor. For iterative improvement based on review feedback. | +| | `review-only` | Read-only code review piece that makes no changes. | +| 🧪 Testing | `unit-test` | Unit test focused piece: test analysis -> test implementation -> review -> fix. | +| | `e2e-test` | E2E test focused piece: E2E analysis -> E2E implementation -> review -> fix (Vitest-based E2E flow). | +| Others | `research` | Research piece: planner -> digger -> supervisor. Autonomously executes research without asking questions. | +| | `deep-research` | Deep research piece: plan -> dig -> analyze -> supervise. Discovery-driven investigation that follows emerging questions with multi-perspective analysis. | +| | `magi` | Deliberation system inspired by Evangelion. Three AI personas (MELCHIOR, BALTHASAR, CASPER) analyze and vote. | +| | `passthrough` | Thinnest wrapper. Pass task directly to coder as-is. No review. | + +Use `takt switch` to switch pieces interactively. + +## Builtin Personas + +| Persona | Description | +|---------|-------------| +| **planner** | Task analysis, spec investigation, implementation planning | +| **architect-planner** | Task analysis and design planning: investigates code, resolves unknowns, creates implementation plans | +| **coder** | Feature implementation, bug fixing | +| **ai-antipattern-reviewer** | AI-specific antipattern review (non-existent APIs, incorrect assumptions, scope creep) | +| **architecture-reviewer** | Architecture and code quality review, spec compliance verification | +| **frontend-reviewer** | Frontend (React/Next.js) code quality and best practices review | +| **cqrs-es-reviewer** | CQRS+Event Sourcing architecture and implementation review | +| **qa-reviewer** | Test coverage and quality assurance review | +| **security-reviewer** | Security vulnerability assessment | +| **conductor** | Phase 3 judgment specialist: reads reports/responses and outputs status tags | +| **supervisor** | Final validation, approval | +| **expert-supervisor** | Expert-level final validation with comprehensive review integration | +| **research-planner** | Research task planning and scope definition | +| **research-analyzer** | Research result interpretation and additional investigation planning | +| **research-digger** | Deep investigation and information gathering | +| **research-supervisor** | Research quality validation and completeness assessment | +| **test-planner** | Test strategy analysis and comprehensive test planning | +| **pr-commenter** | Posts review findings as GitHub PR comments | + +## Custom Personas + +Create persona prompts as Markdown files in `~/.takt/personas/`: + +```markdown +# ~/.takt/personas/my-reviewer.md + +You are a code reviewer specialized in security. + +## Role +- Check for security vulnerabilities +- Verify input validation +- Review authentication logic +``` + +Reference custom personas from piece YAML via the `personas` section map: + +```yaml +personas: + my-reviewer: ~/.takt/personas/my-reviewer.md + +movements: + - name: review + persona: my-reviewer + # ... +``` + +## Per-persona Provider Overrides + +Use `persona_providers` in `~/.takt/config.yaml` to route specific personas to different providers without duplicating pieces. This allows you to run, for example, coding on Codex while keeping reviewers on Claude. + +```yaml +# ~/.takt/config.yaml +persona_providers: + coder: codex # Run coder on Codex + ai-antipattern-reviewer: claude # Keep reviewers on Claude +``` + +This configuration applies globally to all pieces. Any movement using the specified persona will be routed to the corresponding provider, regardless of which piece is being executed. diff --git a/docs/ci-cd.ja.md b/docs/ci-cd.ja.md new file mode 100644 index 0000000..eb2cfdd --- /dev/null +++ b/docs/ci-cd.ja.md @@ -0,0 +1,178 @@ +[English](./ci-cd.md) + +# CI/CD 連携 + +TAKT は CI/CD パイプラインに統合して、タスク実行、PR レビュー、コード生成を自動化できます。このガイドでは GitHub Actions のセットアップ、pipeline モードのオプション、その他の CI システムでの設定について説明します。 + +## GitHub Actions + +TAKT は GitHub Actions 連携用の公式アクション [takt-action](https://github.com/nrslib/takt-action) を提供しています。 + +### 完全なワークフロー例 + +```yaml +name: TAKT + +on: + issue_comment: + types: [created] + +jobs: + takt: + if: contains(github.event.comment.body, '@takt') + runs-on: ubuntu-latest + permissions: + contents: write + issues: write + pull-requests: write + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Run TAKT + uses: nrslib/takt-action@main + with: + anthropic_api_key: ${{ secrets.TAKT_ANTHROPIC_API_KEY }} + github_token: ${{ secrets.GITHUB_TOKEN }} +``` + +### パーミッション + +`takt-action` が正しく機能するには次のパーミッションが必要です。 + +| パーミッション | 用途 | +|-------------|------| +| `contents: write` | ブランチの作成、コミット、コードのプッシュ | +| `issues: write` | Issue の読み取りとコメント | +| `pull-requests: write` | PR の作成と更新 | + +## Pipeline モード + +`--pipeline` を指定すると、非インタラクティブな pipeline モードが有効になります。ブランチの作成、piece の実行、コミット、プッシュを自動的に行います。このモードは人的操作が不可能な CI/CD 自動化向けに設計されています。 + +Pipeline モードでは、`--auto-pr` を明示的に指定しない限り PR は作成**されません**。 + +### Pipeline の全オプション + +| オプション | 説明 | +|-----------|------| +| `--pipeline` | **pipeline（非インタラクティブ）モードを有効化** -- CI/自動化に必要 | +| `-t, --task ` | タスク内容（GitHub Issue の代替） | +| `-i, --issue ` | GitHub Issue 番号（インタラクティブモードでの `#N` と同等） | +| `-w, --piece ` | Piece 名または piece YAML ファイルのパス | +| `-b, --branch ` | ブランチ名を指定（省略時は自動生成） | +| `--auto-pr` | PR を作成（インタラクティブ: 確認スキップ、pipeline: PR 有効化） | +| `--skip-git` | ブランチ作成、コミット、プッシュをスキップ（pipeline モード、piece のみ実行） | +| `--repo ` | リポジトリを指定（PR 作成用） | +| `-q, --quiet` | 最小出力モード: AI 出力を抑制（CI 向け） | +| `--provider ` | エージェント provider を上書き（claude\|codex\|opencode\|mock） | +| `--model ` | エージェントモデルを上書き | + +### コマンド例 + +**基本的な pipeline 実行** + +```bash +takt --pipeline --task "Fix bug" +``` + +**PR 自動作成付きの pipeline 実行** + +```bash +takt --pipeline --task "Fix bug" --auto-pr +``` + +**GitHub Issue をリンクして PR を作成** + +```bash +takt --pipeline --issue 99 --auto-pr +``` + +**Piece とブランチ名を指定** + +```bash +takt --pipeline --task "Fix bug" -w magi -b feat/fix-bug +``` + +**PR 作成用にリポジトリを指定** + +```bash +takt --pipeline --task "Fix bug" --auto-pr --repo owner/repo +``` + +**Piece のみ実行（ブランチ作成、コミット、プッシュをスキップ）** + +```bash +takt --pipeline --task "Fix bug" --skip-git +``` + +**最小出力モード（CI ログ向けに AI 出力を抑制）** + +```bash +takt --pipeline --task "Fix bug" --quiet +``` + +## Pipeline テンプレート変数 + +`~/.takt/config.yaml` の pipeline 設定では、コミットメッセージと PR 本文をカスタマイズするためのテンプレート変数をサポートしています。 + +```yaml +pipeline: + default_branch_prefix: "takt/" + commit_message_template: "feat: {title} (#{issue})" + pr_body_template: | + ## Summary + {issue_body} + Closes #{issue} +``` + +| 変数 | 使用可能な場所 | 説明 | +|------|--------------|------| +| `{title}` | コミットメッセージ | Issue タイトル | +| `{issue}` | コミットメッセージ、PR 本文 | Issue 番号 | +| `{issue_body}` | PR 本文 | Issue 本文 | +| `{report}` | PR 本文 | Piece 実行レポート | + +## その他の CI システム + +GitHub Actions 以外の CI システムでは、TAKT をグローバルにインストールして pipeline モードを直接使用します。 + +```bash +# takt のインストール +npm install -g takt + +# pipeline モードで実行 +takt --pipeline --task "Fix bug" --auto-pr --repo owner/repo +``` + +このアプローチは Node.js をサポートする任意の CI システムで動作します。GitLab CI、CircleCI、Jenkins、Azure DevOps などが含まれます。 + +## 環境変数 + +CI 環境での認証には、適切な API キー環境変数を設定してください。これらは他のツールとの衝突を避けるため TAKT 固有のプレフィックスを使用しています。 + +```bash +# Claude（Anthropic）用 +export TAKT_ANTHROPIC_API_KEY=sk-ant-... + +# Codex（OpenAI）用 +export TAKT_OPENAI_API_KEY=sk-... + +# OpenCode 用 +export TAKT_OPENCODE_API_KEY=... +``` + +優先順位: 環境変数は `config.yaml` の設定よりも優先されます。 + +> **注意**: 環境変数で API キーを設定すれば、Claude Code、Codex、OpenCode CLI のインストールは不要です。TAKT が対応する API を直接呼び出します。 + +## コストに関する注意 + +TAKT は AI API（Claude または OpenAI）を使用するため、特に CI/CD 環境でタスクが自動実行される場合、大きなコストが発生する可能性があります。次の点に注意してください。 + +- **API 使用量の監視**: 予期しない請求を避けるため、AI provider で課金アラートを設定してください。 +- **`--quiet` モードの使用**: 出力量は削減されますが、API 呼び出し回数は減りません。 +- **適切な piece の選択**: シンプルな piece（例: `default-mini`）はマルチステージの piece（例: 並列レビュー付きの `default`）よりも API 呼び出しが少なくなります。 +- **CI トリガーの制限**: 意図しない実行を防ぐため、条件付きトリガー（例: `if: contains(github.event.comment.body, '@takt')`）を使用してください。 +- **`--provider mock` でのテスト**: CI パイプラインの開発中は mock provider を使用して、実際の API コストを回避してください。 diff --git a/docs/ci-cd.md b/docs/ci-cd.md new file mode 100644 index 0000000..e9a53cd --- /dev/null +++ b/docs/ci-cd.md @@ -0,0 +1,178 @@ +[日本語](./ci-cd.ja.md) + +# CI/CD Integration + +TAKT can be integrated into CI/CD pipelines to automate task execution, PR reviews, and code generation. This guide covers GitHub Actions setup, pipeline mode options, and configuration for other CI systems. + +## GitHub Actions + +TAKT provides the official [takt-action](https://github.com/nrslib/takt-action) for GitHub Actions integration. + +### Complete Workflow Example + +```yaml +name: TAKT + +on: + issue_comment: + types: [created] + +jobs: + takt: + if: contains(github.event.comment.body, '@takt') + runs-on: ubuntu-latest + permissions: + contents: write + issues: write + pull-requests: write + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Run TAKT + uses: nrslib/takt-action@main + with: + anthropic_api_key: ${{ secrets.TAKT_ANTHROPIC_API_KEY }} + github_token: ${{ secrets.GITHUB_TOKEN }} +``` + +### Permissions + +The following permissions are required for `takt-action` to function correctly: + +| Permission | Required For | +|------------|-------------| +| `contents: write` | Creating branches, committing, and pushing code | +| `issues: write` | Reading and commenting on issues | +| `pull-requests: write` | Creating and updating pull requests | + +## Pipeline Mode + +Specifying `--pipeline` enables non-interactive pipeline mode. It automatically creates a branch, runs the piece, commits, and pushes. This mode is designed for CI/CD automation where no human interaction is available. + +In pipeline mode, PRs are **not** created unless `--auto-pr` is explicitly specified. + +### All Pipeline Options + +| Option | Description | +|--------|-------------| +| `--pipeline` | **Enable pipeline (non-interactive) mode** -- Required for CI/automation | +| `-t, --task ` | Task content (alternative to GitHub Issue) | +| `-i, --issue ` | GitHub issue number (same as `#N` in interactive mode) | +| `-w, --piece ` | Piece name or path to piece YAML file | +| `-b, --branch ` | Specify branch name (auto-generated if omitted) | +| `--auto-pr` | Create PR (interactive: skip confirmation, pipeline: enable PR) | +| `--skip-git` | Skip branch creation, commit, and push (pipeline mode, piece-only) | +| `--repo ` | Specify repository (for PR creation) | +| `-q, --quiet` | Minimal output mode: suppress AI output (for CI) | +| `--provider ` | Override agent provider (claude\|codex\|opencode\|mock) | +| `--model ` | Override agent model | + +### Command Examples + +**Basic pipeline execution:** + +```bash +takt --pipeline --task "Fix bug" +``` + +**Pipeline execution with automatic PR creation:** + +```bash +takt --pipeline --task "Fix bug" --auto-pr +``` + +**Link a GitHub issue and create a PR:** + +```bash +takt --pipeline --issue 99 --auto-pr +``` + +**Specify piece and branch name:** + +```bash +takt --pipeline --task "Fix bug" -w magi -b feat/fix-bug +``` + +**Specify repository for PR creation:** + +```bash +takt --pipeline --task "Fix bug" --auto-pr --repo owner/repo +``` + +**Piece execution only (skip branch creation, commit, push):** + +```bash +takt --pipeline --task "Fix bug" --skip-git +``` + +**Minimal output mode (suppress AI output for CI logs):** + +```bash +takt --pipeline --task "Fix bug" --quiet +``` + +## Pipeline Template Variables + +Pipeline configuration in `~/.takt/config.yaml` supports template variables for customizing commit messages and PR bodies: + +```yaml +pipeline: + default_branch_prefix: "takt/" + commit_message_template: "feat: {title} (#{issue})" + pr_body_template: | + ## Summary + {issue_body} + Closes #{issue} +``` + +| Variable | Available In | Description | +|----------|-------------|-------------| +| `{title}` | Commit message | Issue title | +| `{issue}` | Commit message, PR body | Issue number | +| `{issue_body}` | PR body | Issue body | +| `{report}` | PR body | Piece execution report | + +## Other CI Systems + +For CI systems other than GitHub Actions, install TAKT globally and use pipeline mode directly: + +```bash +# Install takt +npm install -g takt + +# Run in pipeline mode +takt --pipeline --task "Fix bug" --auto-pr --repo owner/repo +``` + +This approach works with any CI system that supports Node.js, including GitLab CI, CircleCI, Jenkins, Azure DevOps, and others. + +## Environment Variables + +For authentication in CI environments, set the appropriate API key environment variable. These use TAKT-specific prefixes to avoid conflicts with other tools. + +```bash +# For Claude (Anthropic) +export TAKT_ANTHROPIC_API_KEY=sk-ant-... + +# For Codex (OpenAI) +export TAKT_OPENAI_API_KEY=sk-... + +# For OpenCode +export TAKT_OPENCODE_API_KEY=... +``` + +Priority: Environment variables take precedence over `config.yaml` settings. + +> **Note**: If you set an API key via environment variable, installing Claude Code, Codex, or OpenCode CLI is not necessary. TAKT directly calls the respective API. + +## Cost Considerations + +TAKT uses AI APIs (Claude or OpenAI), which can incur significant costs, especially when tasks are auto-executed in CI/CD environments. Take the following precautions: + +- **Monitor API usage**: Set up billing alerts with your AI provider to avoid unexpected charges. +- **Use `--quiet` mode**: Reduces output volume but does not reduce API calls. +- **Choose appropriate pieces**: Simpler pieces (e.g., `default-mini`) use fewer API calls than multi-stage pieces (e.g., `default` with parallel reviews). +- **Limit CI triggers**: Use conditional triggers (e.g., `if: contains(github.event.comment.body, '@takt')`) to prevent unintended executions. +- **Test with `--provider mock`**: Use mock provider during CI pipeline development to avoid real API costs. diff --git a/docs/cli-reference.ja.md b/docs/cli-reference.ja.md new file mode 100644 index 0000000..9dea3e5 --- /dev/null +++ b/docs/cli-reference.ja.md @@ -0,0 +1,290 @@ +# CLI リファレンス + +[English](./cli-reference.md) + +このドキュメントは TAKT CLI の全コマンドとオプションの完全なリファレンスです。 + +## グローバルオプション + +| オプション | 説明 | +|-----------|------| +| `--pipeline` | pipeline（非インタラクティブ）モードを有効化 -- CI/自動化に必要 | +| `-t, --task ` | タスク内容（GitHub Issue の代替） | +| `-i, --issue ` | GitHub Issue 番号（インタラクティブモードでの `#N` と同等） | +| `-w, --piece ` | Piece 名または piece YAML ファイルのパス | +| `-b, --branch ` | ブランチ名を指定（省略時は自動生成） | +| `--auto-pr` | PR を作成（インタラクティブ: 確認スキップ、pipeline: PR 有効化） | +| `--skip-git` | ブランチ作成、コミット、プッシュをスキップ（pipeline モード、piece のみ実行） | +| `--repo ` | リポジトリを指定（PR 作成用） | +| `--create-worktree ` | worktree 確認プロンプトをスキップ | +| `-q, --quiet` | 最小出力モード: AI 出力を抑制（CI 向け） | +| `--provider ` | エージェント provider を上書き（claude\|codex\|opencode\|mock） | +| `--model ` | エージェントモデルを上書き | +| `--config ` | グローバル設定ファイルのパス（デフォルト: `~/.takt/config.yaml`） | + +## インタラクティブモード + +AI との会話を通じてタスク内容を精緻化してから実行するモードです。タスクの要件が曖昧な場合や、AI と相談しながら内容を詰めたい場合に便利です。 + +```bash +# インタラクティブモードを開始（引数なし） +takt + +# 初期メッセージを指定（短い単語のみ） +takt hello +``` + +**注意:** `--task` オプションを指定するとインタラクティブモードをスキップして直接実行します。Issue 参照（`#6`、`--issue`）はインタラクティブモードの初期入力として使用されます。 + +### フロー + +1. Piece を選択 +2. インタラクティブモードを選択（assistant / persona / quiet / passthrough） +3. AI との会話でタスク内容を精緻化 +4. `/go` でタスク指示を確定（`/go 追加の指示` のように追記も可能）、または `/play ` でタスクを即座に実行 +5. 実行（worktree 作成、piece 実行、PR 作成） + +### インタラクティブモードの種類 + +| モード | 説明 | +|--------|------| +| `assistant` | デフォルト。AI がタスク指示を生成する前に明確化のための質問を行う。 | +| `persona` | 最初の movement の persona と会話（そのシステムプロンプトとツールを使用）。 | +| `quiet` | 質問なしでタスク指示を生成（ベストエフォート）。 | +| `passthrough` | AI 処理なしでユーザー入力をそのままタスクテキストとして使用。 | + +Piece は YAML の `interactive_mode` フィールドでデフォルトモードを設定できます。 + +### 実行例 + +``` +$ takt + +Select piece: + > default (current) + Development/ + Research/ + Cancel + +Interactive mode - Enter task content. Commands: /go (execute), /cancel (exit) + +> I want to add user authentication feature + +[AI が要件を確認・整理] + +> /go + +Proposed task instructions: +--- +Implement user authentication feature. + +Requirements: +- Login with email address and password +- JWT token-based authentication +- Password hashing (bcrypt) +- Login/logout API endpoints +--- + +Proceed with these task instructions? (Y/n) y + +? Create worktree? (Y/n) y + +[Piece の実行を開始...] +``` + +## 直接タスク実行 + +`--task` オプションを使用して、インタラクティブモードをスキップして直接実行できます。 + +```bash +# --task オプションでタスク内容を指定 +takt --task "Fix bug" + +# piece を指定 +takt --task "Add authentication" --piece expert + +# PR を自動作成 +takt --task "Fix bug" --auto-pr +``` + +**注意:** 引数として文字列を渡す場合（例: `takt "Add login feature"`）は、初期メッセージとしてインタラクティブモードに入ります。 + +## GitHub Issue タスク + +GitHub Issue を直接タスクとして実行できます。Issue のタイトル、本文、ラベル、コメントがタスク内容として自動的に取り込まれます。 + +```bash +# Issue 番号を指定して実行 +takt #6 +takt --issue 6 + +# Issue + piece 指定 +takt #6 --piece expert + +# Issue + PR 自動作成 +takt #6 --auto-pr +``` + +**要件:** [GitHub CLI](https://cli.github.com/)（`gh`）がインストールされ、認証済みである必要があります。 + +## タスク管理コマンド + +`.takt/tasks.yaml` と `.takt/tasks/{slug}/` 配下のタスクディレクトリを使ったバッチ処理です。複数のタスクを蓄積し、後でまとめて実行するのに便利です。 + +### takt add + +AI との会話でタスク要件を精緻化し、`.takt/tasks.yaml` にタスクを追加します。 + +```bash +# AI との会話でタスク要件を精緻化し、タスクを追加 +takt add + +# GitHub Issue からタスクを追加（Issue 番号がブランチ名に反映される） +takt add #28 +``` + +### takt run + +`.takt/tasks.yaml` のすべての pending タスクを実行します。 + +```bash +# .takt/tasks.yaml の pending タスクをすべて実行 +takt run +``` + +### takt watch + +`.takt/tasks.yaml` を監視し、タスクが追加されると自動実行する常駐プロセスです。 + +```bash +# .takt/tasks.yaml を監視してタスクを自動実行（常駐プロセス） +takt watch +``` + +### takt list + +タスクブランチの一覧表示と操作（マージ、削除など）を行います。 + +```bash +# タスクブランチの一覧表示（マージ/削除） +takt list + +# 非インタラクティブモード（CI/スクリプト向け） +takt list --non-interactive +takt list --non-interactive --action diff --branch takt/my-branch +takt list --non-interactive --action delete --branch takt/my-branch --yes +takt list --non-interactive --format json +``` + +### タスクディレクトリワークフロー（作成 / 実行 / 確認） + +1. `takt add` を実行し、`.takt/tasks.yaml` に pending レコードが作成されたことを確認。 +2. 生成された `.takt/tasks/{slug}/order.md` を開き、必要に応じて詳細な仕様や参考資料を追記。 +3. `takt run`（または `takt watch`）を実行して `tasks.yaml` の pending タスクを実行。 +4. `task_dir` と同じ slug の `.takt/runs/{slug}/reports/` で出力を確認。 + +## Pipeline モード + +`--pipeline` を指定すると、非インタラクティブな pipeline モードが有効になります。ブランチの作成、piece の実行、コミットとプッシュを自動的に行います。CI/CD 自動化に適しています。 + +```bash +# pipeline モードでタスクを実行 +takt --pipeline --task "Fix bug" + +# pipeline 実行 + PR 自動作成 +takt --pipeline --task "Fix bug" --auto-pr + +# Issue 情報をリンク +takt --pipeline --issue 99 --auto-pr + +# piece とブランチを指定 +takt --pipeline --task "Fix bug" -w magi -b feat/fix-bug + +# リポジトリを指定（PR 作成用） +takt --pipeline --task "Fix bug" --auto-pr --repo owner/repo + +# piece のみ実行（ブランチ作成、コミット、プッシュをスキップ） +takt --pipeline --task "Fix bug" --skip-git + +# 最小出力モード（CI 向け） +takt --pipeline --task "Fix bug" --quiet +``` + +Pipeline モードでは、`--auto-pr` を指定しない限り PR は作成されません。 + +**GitHub 連携:** GitHub Actions で TAKT を使用する場合は [takt-action](https://github.com/nrslib/takt-action) を参照してください。PR レビューやタスク実行を自動化できます。 + +## ユーティリティコマンド + +### takt switch + +アクティブな piece をインタラクティブに切り替えます。 + +```bash +takt switch +``` + +### takt eject + +ビルトインの piece/persona をローカルディレクトリにコピーしてカスタマイズします。 + +```bash +# ビルトインの piece/persona をプロジェクト .takt/ にコピー +takt eject + +# ~/.takt/（グローバル）にコピー +takt eject --global + +# 特定のファセットをカスタマイズ用にエジェクト +takt eject persona coder +takt eject instruction plan --global +``` + +### takt clear + +エージェントの会話セッションをクリア（状態のリセット）します。 + +```bash +takt clear +``` + +### takt export-cc + +ビルトインの piece/persona を Claude Code Skill としてデプロイします。 + +```bash +takt export-cc +``` + +### takt catalog + +レイヤー間で利用可能なファセットの一覧を表示します。 + +```bash +takt catalog +takt catalog personas +``` + +### takt prompt + +各 movement とフェーズの組み立て済みプロンプトをプレビューします。 + +```bash +takt prompt [piece] +``` + +### takt config + +パーミッションモードを設定します。 + +```bash +takt config +``` + +### takt reset + +Piece カテゴリをビルトインのデフォルトにリセットします。 + +```bash +takt reset categories +``` diff --git a/docs/cli-reference.md b/docs/cli-reference.md new file mode 100644 index 0000000..1fc0b6a --- /dev/null +++ b/docs/cli-reference.md @@ -0,0 +1,290 @@ +# CLI Reference + +[日本語](./cli-reference.ja.md) + +This document provides a complete reference for all TAKT CLI commands and options. + +## Global Options + +| Option | Description | +|--------|-------------| +| `--pipeline` | Enable pipeline (non-interactive) mode -- required for CI/automation | +| `-t, --task ` | Task content (alternative to GitHub Issue) | +| `-i, --issue ` | GitHub issue number (same as `#N` in interactive mode) | +| `-w, --piece ` | Piece name or path to piece YAML file | +| `-b, --branch ` | Specify branch name (auto-generated if omitted) | +| `--auto-pr` | Create PR (interactive: skip confirmation, pipeline: enable PR) | +| `--skip-git` | Skip branch creation, commit, and push (pipeline mode, piece-only) | +| `--repo ` | Specify repository (for PR creation) | +| `--create-worktree ` | Skip worktree confirmation prompt | +| `-q, --quiet` | Minimal output mode: suppress AI output (for CI) | +| `--provider ` | Override agent provider (claude\|codex\|opencode\|mock) | +| `--model ` | Override agent model | +| `--config ` | Path to global config file (default: `~/.takt/config.yaml`) | + +## Interactive Mode + +A mode where you refine task content through conversation with AI before execution. Useful when task requirements are ambiguous or when you want to clarify content while consulting with AI. + +```bash +# Start interactive mode (no arguments) +takt + +# Specify initial message (short word only) +takt hello +``` + +**Note:** `--task` option skips interactive mode and executes the task directly. Issue references (`#6`, `--issue`) are used as initial input in interactive mode. + +### Flow + +1. Select piece +2. Select interactive mode (assistant / persona / quiet / passthrough) +3. Refine task content through conversation with AI +4. Finalize task instructions with `/go` (you can also add additional instructions like `/go additional instructions`), or use `/play ` to execute a task immediately +5. Execute (create worktree, run piece, create PR) + +### Interactive Mode Variants + +| Mode | Description | +|------|-------------| +| `assistant` | Default. AI asks clarifying questions before generating task instructions. | +| `persona` | Conversation with the first movement's persona (uses its system prompt and tools). | +| `quiet` | Generates task instructions without asking questions (best-effort). | +| `passthrough` | Passes user input directly as task text without AI processing. | + +Pieces can set a default mode via the `interactive_mode` field in YAML. + +### Execution Example + +``` +$ takt + +Select piece: + > default (current) + Development/ + Research/ + Cancel + +Interactive mode - Enter task content. Commands: /go (execute), /cancel (exit) + +> I want to add user authentication feature + +[AI confirms and organizes requirements] + +> /go + +Proposed task instructions: +--- +Implement user authentication feature. + +Requirements: +- Login with email address and password +- JWT token-based authentication +- Password hashing (bcrypt) +- Login/logout API endpoints +--- + +Proceed with these task instructions? (Y/n) y + +? Create worktree? (Y/n) y + +[Piece execution starts...] +``` + +## Direct Task Execution + +Use the `--task` option to skip interactive mode and execute directly. + +```bash +# Specify task content with --task option +takt --task "Fix bug" + +# Specify piece +takt --task "Add authentication" --piece expert + +# Auto-create PR +takt --task "Fix bug" --auto-pr +``` + +**Note:** Passing a string as an argument (e.g., `takt "Add login feature"`) enters interactive mode with it as the initial message. + +## GitHub Issue Tasks + +You can execute GitHub Issues directly as tasks. Issue title, body, labels, and comments are automatically incorporated as task content. + +```bash +# Execute by specifying issue number +takt #6 +takt --issue 6 + +# Issue + piece specification +takt #6 --piece expert + +# Issue + auto-create PR +takt #6 --auto-pr +``` + +**Requirements:** [GitHub CLI](https://cli.github.com/) (`gh`) must be installed and authenticated. + +## Task Management Commands + +Batch processing using `.takt/tasks.yaml` with task directories under `.takt/tasks/{slug}/`. Useful for accumulating multiple tasks and executing them together later. + +### takt add + +Refine task requirements through AI conversation, then add a task to `.takt/tasks.yaml`. + +```bash +# Refine task requirements through AI conversation, then add task +takt add + +# Add task from GitHub Issue (issue number reflected in branch name) +takt add #28 +``` + +### takt run + +Execute all pending tasks from `.takt/tasks.yaml`. + +```bash +# Execute all pending tasks in .takt/tasks.yaml +takt run +``` + +### takt watch + +Monitor `.takt/tasks.yaml` and auto-execute tasks as a resident process. + +```bash +# Monitor .takt/tasks.yaml and auto-execute tasks (resident process) +takt watch +``` + +### takt list + +List task branches and perform actions (merge, delete, etc.). + +```bash +# List task branches (merge/delete) +takt list + +# Non-interactive mode (for CI/scripts) +takt list --non-interactive +takt list --non-interactive --action diff --branch takt/my-branch +takt list --non-interactive --action delete --branch takt/my-branch --yes +takt list --non-interactive --format json +``` + +### Task Directory Workflow (Create / Run / Verify) + +1. Run `takt add` and confirm a pending record is created in `.takt/tasks.yaml`. +2. Open the generated `.takt/tasks/{slug}/order.md` and add detailed specifications/references as needed. +3. Run `takt run` (or `takt watch`) to execute pending tasks from `tasks.yaml`. +4. Verify outputs in `.takt/runs/{slug}/reports/` using the same slug as `task_dir`. + +## Pipeline Mode + +Specifying `--pipeline` enables non-interactive pipeline mode. Automatically creates branch, runs piece, commits and pushes. Suitable for CI/CD automation. + +```bash +# Execute task in pipeline mode +takt --pipeline --task "Fix bug" + +# Pipeline execution + auto-create PR +takt --pipeline --task "Fix bug" --auto-pr + +# Link issue information +takt --pipeline --issue 99 --auto-pr + +# Specify piece and branch +takt --pipeline --task "Fix bug" -w magi -b feat/fix-bug + +# Specify repository (for PR creation) +takt --pipeline --task "Fix bug" --auto-pr --repo owner/repo + +# Piece execution only (skip branch creation, commit, push) +takt --pipeline --task "Fix bug" --skip-git + +# Minimal output mode (for CI) +takt --pipeline --task "Fix bug" --quiet +``` + +In pipeline mode, PRs are not created unless `--auto-pr` is specified. + +**GitHub Integration:** When using TAKT in GitHub Actions, see [takt-action](https://github.com/nrslib/takt-action). You can automate PR reviews and task execution. + +## Utility Commands + +### takt switch + +Interactively switch the active piece. + +```bash +takt switch +``` + +### takt eject + +Copy builtin pieces/personas to your local directory for customization. + +```bash +# Copy builtin pieces/personas to project .takt/ for customization +takt eject + +# Copy to ~/.takt/ (global) instead +takt eject --global + +# Eject a specific facet for customization +takt eject persona coder +takt eject instruction plan --global +``` + +### takt clear + +Clear agent conversation sessions (reset state). + +```bash +takt clear +``` + +### takt export-cc + +Deploy builtin pieces/personas as a Claude Code Skill. + +```bash +takt export-cc +``` + +### takt catalog + +List available facets across layers. + +```bash +takt catalog +takt catalog personas +``` + +### takt prompt + +Preview assembled prompts for each movement and phase. + +```bash +takt prompt [piece] +``` + +### takt config + +Configure permission mode. + +```bash +takt config +``` + +### takt reset + +Reset piece categories to builtin defaults. + +```bash +takt reset categories +``` diff --git a/docs/configuration.ja.md b/docs/configuration.ja.md new file mode 100644 index 0000000..260a7ed --- /dev/null +++ b/docs/configuration.ja.md @@ -0,0 +1,400 @@ +# 設定 + +[English](./configuration.md) + +このドキュメントは TAKT の全設定オプションのリファレンスです。クイックスタートについては [README](../README.md) を参照してください。 + +## グローバル設定 + +`~/.takt/config.yaml` で TAKT のデフォルト設定を行います。このファイルは初回実行時に自動作成されます。すべてのフィールドは省略可能です。 + +```yaml +# ~/.takt/config.yaml +language: en # UI 言語: 'en' または 'ja' +default_piece: default # 新規プロジェクトのデフォルト piece +log_level: info # ログレベル: debug, info, warn, error +provider: claude # デフォルト provider: claude, codex, または opencode +model: sonnet # デフォルトモデル（省略可、provider にそのまま渡される） +branch_name_strategy: romaji # ブランチ名生成方式: 'romaji'（高速）または 'ai'（低速） +prevent_sleep: false # 実行中に macOS のアイドルスリープを防止（caffeinate） +notification_sound: true # 通知音の有効/無効 +notification_sound_events: # イベントごとの通知音切り替え（省略可） + iteration_limit: false + piece_complete: true + piece_abort: true + run_complete: true # デフォルト有効。false で無効化 + run_abort: true # デフォルト有効。false で無効化 +concurrency: 1 # takt run の並列タスク数（1-10、デフォルト: 1 = 逐次実行） +task_poll_interval_ms: 500 # takt run での新規タスクポーリング間隔（100-5000、デフォルト: 500） +interactive_preview_movements: 3 # インタラクティブモードでの movement プレビュー数（0-10、デフォルト: 3） + +# ランタイム環境デフォルト（piece_config.runtime で上書きしない限りすべての piece に適用） +# runtime: +# prepare: +# - gradle # .runtime/ に Gradle キャッシュ/設定を準備 +# - node # .runtime/ に npm キャッシュを準備 + +# persona ごとの provider 上書き（省略可） +# piece を複製せずに特定の persona を別の provider にルーティング +# persona_providers: +# coder: codex # coder を Codex で実行 +# ai-antipattern-reviewer: claude # レビュアーは Claude のまま + +# provider 固有のパーミッションプロファイル（省略可） +# 優先順位: プロジェクト上書き > グローバル上書き > プロジェクトデフォルト > グローバルデフォルト > required_permission_mode（下限） +# provider_profiles: +# codex: +# default_permission_mode: full +# movement_permission_overrides: +# ai_review: readonly +# claude: +# default_permission_mode: edit + +# API キー設定（省略可） +# 環境変数 TAKT_ANTHROPIC_API_KEY / TAKT_OPENAI_API_KEY / TAKT_OPENCODE_API_KEY で上書き可能 +# anthropic_api_key: sk-ant-... # Claude（Anthropic）用 +# openai_api_key: sk-... # Codex（OpenAI）用 +# opencode_api_key: ... # OpenCode 用 + +# Codex CLI パス上書き（省略可） +# Codex SDK が使用する Codex CLI バイナリを上書き（実行可能ファイルの絶対パスが必要） +# 環境変数 TAKT_CODEX_CLI_PATH で上書き可能 +# codex_cli_path: /usr/local/bin/codex + +# ビルトイン piece フィルタリング（省略可） +# builtin_pieces_enabled: true # false ですべてのビルトインを無効化 +# disabled_builtins: [magi, passthrough] # 特定のビルトイン piece を無効化 + +# pipeline 実行設定（省略可） +# ブランチ名、コミットメッセージ、PR 本文をカスタマイズ +# pipeline: +# default_branch_prefix: "takt/" +# commit_message_template: "feat: {title} (#{issue})" +# pr_body_template: | +# ## Summary +# {issue_body} +# Closes #{issue} +``` + +### グローバル設定フィールドリファレンス + +| フィールド | 型 | デフォルト | 説明 | +|-----------|------|---------|------| +| `language` | `"en"` \| `"ja"` | `"en"` | UI 言語 | +| `default_piece` | string | `"default"` | 新規プロジェクトのデフォルト piece | +| `log_level` | `"debug"` \| `"info"` \| `"warn"` \| `"error"` | `"info"` | ログレベル | +| `provider` | `"claude"` \| `"codex"` \| `"opencode"` | `"claude"` | デフォルト AI provider | +| `model` | string | - | デフォルトモデル名（provider にそのまま渡される） | +| `branch_name_strategy` | `"romaji"` \| `"ai"` | `"romaji"` | ブランチ名生成方式 | +| `prevent_sleep` | boolean | `false` | macOS アイドルスリープ防止（caffeinate） | +| `notification_sound` | boolean | `true` | 通知音の有効化 | +| `notification_sound_events` | object | - | イベントごとの通知音切り替え | +| `concurrency` | number (1-10) | `1` | `takt run` の並列タスク数 | +| `task_poll_interval_ms` | number (100-5000) | `500` | 新規タスクのポーリング間隔 | +| `interactive_preview_movements` | number (0-10) | `3` | インタラクティブモードでの movement プレビュー数 | +| `worktree_dir` | string | - | 共有クローンのディレクトリ（デフォルトは `../{clone-name}`） | +| `auto_pr` | boolean | - | worktree 実行後に PR を自動作成 | +| `verbose` | boolean | - | 詳細出力モード | +| `minimal_output` | boolean | `false` | AI 出力を抑制（CI 向け） | +| `runtime` | object | - | ランタイム環境デフォルト（例: `prepare: [gradle, node]`） | +| `persona_providers` | object | - | persona ごとの provider 上書き（例: `coder: codex`） | +| `provider_options` | object | - | グローバルな provider 固有オプション | +| `provider_profiles` | object | - | provider 固有のパーミッションプロファイル | +| `anthropic_api_key` | string | - | Claude 用 Anthropic API キー | +| `openai_api_key` | string | - | Codex 用 OpenAI API キー | +| `opencode_api_key` | string | - | OpenCode API キー | +| `codex_cli_path` | string | - | Codex CLI バイナリパス上書き（絶対パス） | +| `enable_builtin_pieces` | boolean | `true` | ビルトイン piece の有効化 | +| `disabled_builtins` | string[] | `[]` | 無効化する特定のビルトイン piece | +| `pipeline` | object | - | pipeline テンプレート設定 | +| `bookmarks_file` | string | - | ブックマークファイルのパス | +| `piece_categories_file` | string | - | piece カテゴリファイルのパス | + +## プロジェクト設定 + +`.takt/config.yaml` でプロジェクト固有の設定を行います。このファイルはプロジェクトディレクトリで初めて TAKT を使用した際に作成されます。 + +```yaml +# .takt/config.yaml +piece: default # このプロジェクトの現在の piece +provider: claude # このプロジェクトの provider 上書き +auto_pr: true # worktree 実行後に PR を自動作成 +verbose: false # 詳細出力モード + +# provider 固有オプション（グローバルを上書き、piece/movement で上書き可能） +# provider_options: +# codex: +# network_access: true + +# provider 固有パーミッションプロファイル（プロジェクトレベルの上書き） +# provider_profiles: +# codex: +# default_permission_mode: full +# movement_permission_overrides: +# ai_review: readonly +``` + +### プロジェクト設定フィールドリファレンス + +| フィールド | 型 | デフォルト | 説明 | +|-----------|------|---------|------| +| `piece` | string | `"default"` | このプロジェクトの現在の piece 名 | +| `provider` | `"claude"` \| `"codex"` \| `"opencode"` \| `"mock"` | - | provider 上書き | +| `auto_pr` | boolean | - | worktree 実行後に PR を自動作成 | +| `verbose` | boolean | - | 詳細出力モード | +| `provider_options` | object | - | provider 固有オプション | +| `provider_profiles` | object | - | provider 固有のパーミッションプロファイル | + +プロジェクト設定の値は、両方が設定されている場合にグローバル設定を上書きします。 + +## API キー設定 + +TAKT は3つの provider をサポートしており、それぞれに API キーが必要です。API キーは環境変数または `~/.takt/config.yaml` で設定できます。 + +### 環境変数（推奨） + +```bash +# Claude（Anthropic）用 +export TAKT_ANTHROPIC_API_KEY=sk-ant-... + +# Codex（OpenAI）用 +export TAKT_OPENAI_API_KEY=sk-... + +# OpenCode 用 +export TAKT_OPENCODE_API_KEY=... +``` + +### 設定ファイル + +```yaml +# ~/.takt/config.yaml +anthropic_api_key: sk-ant-... # Claude 用 +openai_api_key: sk-... # Codex 用 +opencode_api_key: ... # OpenCode 用 +``` + +### 優先順位 + +環境変数は `config.yaml` の設定よりも優先されます。 + +| Provider | 環境変数 | 設定キー | +|----------|---------|---------| +| Claude (Anthropic) | `TAKT_ANTHROPIC_API_KEY` | `anthropic_api_key` | +| Codex (OpenAI) | `TAKT_OPENAI_API_KEY` | `openai_api_key` | +| OpenCode | `TAKT_OPENCODE_API_KEY` | `opencode_api_key` | + +### セキュリティ + +- `config.yaml` に API キーを記載する場合、このファイルを Git にコミットしないよう注意してください。 +- 環境変数の使用を検討してください。 +- 必要に応じて `~/.takt/config.yaml` をグローバル `.gitignore` に追加してください。 +- API キーを設定すれば、対応する CLI ツール（Claude Code、Codex、OpenCode）のインストールは不要です。TAKT が対応する API を直接呼び出します。 + +### Codex CLI パス上書き + +Codex CLI バイナリパスは環境変数または設定ファイルで上書きできます。 + +```bash +export TAKT_CODEX_CLI_PATH=/usr/local/bin/codex +``` + +```yaml +# ~/.takt/config.yaml +codex_cli_path: /usr/local/bin/codex +``` + +パスは実行可能ファイルの絶対パスである必要があります。`TAKT_CODEX_CLI_PATH` は設定ファイルの値よりも優先されます。 + +## モデル解決 + +各 movement で使用されるモデルは、次の優先順位（高い順）で解決されます。 + +1. **Piece movement の `model`** - piece YAML の movement 定義で指定 +2. **カスタムエージェントの `model`** - `.takt/agents.yaml` のエージェントレベルのモデル +3. **グローバル設定の `model`** - `~/.takt/config.yaml` のデフォルトモデル +4. **Provider デフォルト** - provider のビルトインデフォルトにフォールバック（Claude: `sonnet`、Codex: `codex`、OpenCode: provider デフォルト） + +### Provider 固有のモデルに関する注意 + +**Claude Code** はエイリアス（`opus`、`sonnet`、`haiku`、`opusplan`、`default`）と完全なモデル名（例: `claude-sonnet-4-5-20250929`）をサポートしています。`model` フィールドは provider CLI にそのまま渡されます。利用可能なモデルについては [Claude Code ドキュメント](https://docs.anthropic.com/en/docs/claude-code) を参照してください。 + +**Codex** は Codex SDK を通じてモデル文字列をそのまま使用します。未指定の場合、デフォルトは `codex` です。利用可能なモデルについては Codex のドキュメントを参照してください。 + +**OpenCode** は `provider/model` 形式のモデル（例: `opencode/big-pickle`）が必要です。OpenCode provider でモデルを省略すると設定エラーになります。 + +### 設定例 + +```yaml +# ~/.takt/config.yaml +provider: claude +model: opus # すべての movement のデフォルトモデル（上書きされない限り） +``` + +```yaml +# piece.yaml - movement レベルの上書きが最高優先 +movements: + - name: plan + model: opus # この movement はグローバル設定に関係なく opus を使用 + ... + - name: implement + # model 未指定 - グローバル設定（opus）にフォールバック + ... +``` + +## Provider プロファイル + +Provider プロファイルを使用すると、各 provider にデフォルトのパーミッションモードと movement ごとのパーミッション上書きを設定できます。異なる provider を異なるセキュリティポリシーで運用する場合に便利です。 + +### パーミッションモード + +TAKT は provider 非依存の3つのパーミッションモードを使用します。 + +| モード | 説明 | Claude | Codex | OpenCode | +|--------|------|--------|-------|----------| +| `readonly` | 読み取り専用、ファイル変更不可 | `default` | `read-only` | `read-only` | +| `edit` | 確認付きでファイル編集を許可 | `acceptEdits` | `workspace-write` | `workspace-write` | +| `full` | すべてのパーミッションチェックをバイパス | `bypassPermissions` | `danger-full-access` | `danger-full-access` | + +### 設定方法 + +Provider プロファイルはグローバルレベルとプロジェクトレベルの両方で設定できます。 + +```yaml +# ~/.takt/config.yaml（グローバル）または .takt/config.yaml（プロジェクト） +provider_profiles: + codex: + default_permission_mode: full + movement_permission_overrides: + ai_review: readonly + claude: + default_permission_mode: edit + movement_permission_overrides: + implement: full +``` + +### パーミッション解決の優先順位 + +パーミッションモードは次の順序で解決されます（最初にマッチしたものが適用）。 + +1. **プロジェクト** `provider_profiles..movement_permission_overrides.` +2. **グローバル** `provider_profiles..movement_permission_overrides.` +3. **プロジェクト** `provider_profiles..default_permission_mode` +4. **グローバル** `provider_profiles..default_permission_mode` +5. **Movement** `required_permission_mode`（最低限の下限として機能） + +movement の `required_permission_mode` は最低限の下限を設定します。provider プロファイルから解決されたモードが要求モードよりも低い場合、要求モードが使用されます。たとえば、movement が `edit` を要求しているがプロファイルが `readonly` に解決される場合、実効モードは `edit` になります。 + +### Persona Provider + +piece を複製せずに、特定の persona を別の provider にルーティングできます。 + +```yaml +# ~/.takt/config.yaml +persona_providers: + coder: codex # coder persona を Codex で実行 + ai-antipattern-reviewer: claude # レビュアーは Claude のまま +``` + +これにより、単一の piece 内で provider を混在させることができます。persona 名は movement 定義の `persona` キーに対してマッチされます。 + +## Piece カテゴリ + +`takt switch` や piece 選択プロンプトでの UI 表示を改善するために、piece をカテゴリに整理できます。 + +### 設定方法 + +カテゴリは次の場所で設定できます。 +- `builtins/{lang}/piece-categories.yaml` - デフォルトのビルトインカテゴリ +- `~/.takt/config.yaml` または `piece_categories_file` で指定した別のカテゴリファイル + +```yaml +# ~/.takt/config.yaml または専用カテゴリファイル +piece_categories: + Development: + pieces: [default, simple] + children: + Backend: + pieces: [expert-cqrs] + Frontend: + pieces: [expert] + Research: + pieces: [research, magi] + +show_others_category: true # 未分類の piece を表示（デフォルト: true） +others_category_name: "Other Pieces" # 未分類カテゴリの名前 +``` + +### カテゴリ機能 + +- **ネストされたカテゴリ** - 階層的な整理のための無制限の深さ +- **カテゴリごとの piece リスト** - 特定のカテゴリに piece を割り当て +- **その他カテゴリ** - 未分類の piece を自動収集（`show_others_category: false` で無効化可能） +- **ビルトイン piece フィルタリング** - `enable_builtin_pieces: false` ですべてのビルトインを無効化、または `disabled_builtins: [name1, name2]` で選択的に無効化 + +### カテゴリのリセット + +piece カテゴリをビルトインのデフォルトにリセットできます。 + +```bash +takt reset categories +``` + +## Pipeline テンプレート + +Pipeline モード（`--pipeline`）では、ブランチ名、コミットメッセージ、PR 本文をカスタマイズするテンプレートをサポートしています。 + +### 設定方法 + +```yaml +# ~/.takt/config.yaml +pipeline: + default_branch_prefix: "takt/" + commit_message_template: "feat: {title} (#{issue})" + pr_body_template: | + ## Summary + {issue_body} + Closes #{issue} +``` + +### テンプレート変数 + +| 変数 | 使用可能な場所 | 説明 | +|------|--------------|------| +| `{title}` | コミットメッセージ | Issue タイトル | +| `{issue}` | コミットメッセージ、PR 本文 | Issue 番号 | +| `{issue_body}` | PR 本文 | Issue 本文 | +| `{report}` | PR 本文 | Piece 実行レポート | + +### Pipeline CLI オプション + +| オプション | 説明 | +|-----------|------| +| `--pipeline` | pipeline（非インタラクティブ）モードを有効化 | +| `--auto-pr` | 実行後に PR を作成 | +| `--skip-git` | ブランチ作成、コミット、プッシュをスキップ（piece のみ実行） | +| `--repo ` | PR 作成用のリポジトリを指定 | +| `-q, --quiet` | 最小出力モード（AI 出力を抑制） | + +## デバッグ + +### デバッグログ + +`~/.takt/config.yaml` で `debug_enabled: true` を設定するか、`.takt/debug.yaml` ファイルを作成してデバッグログを有効化できます。 + +```yaml +# .takt/debug.yaml +enabled: true +``` + +デバッグログは `.takt/logs/debug.log` に NDJSON 形式で出力されます。 + +### 詳細モード + +空の `.takt/verbose` ファイルを作成すると、詳細なコンソール出力が有効になります。これにより、デバッグログも自動的に有効化されます。 + +または、設定ファイルで `verbose: true` を設定することもできます。 + +```yaml +# ~/.takt/config.yaml または .takt/config.yaml +verbose: true +``` diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..a6dbf50 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,400 @@ +# Configuration + +[日本語](./configuration.ja.md) + +This document is a reference for all TAKT configuration options. For a quick start, see the main [README](../README.md). + +## Global Configuration + +Configure TAKT defaults in `~/.takt/config.yaml`. This file is created automatically on first run. All fields are optional. + +```yaml +# ~/.takt/config.yaml +language: en # UI language: 'en' or 'ja' +default_piece: default # Default piece for new projects +log_level: info # Log level: debug, info, warn, error +provider: claude # Default provider: claude, codex, or opencode +model: sonnet # Default model (optional, passed to provider as-is) +branch_name_strategy: romaji # Branch name generation: 'romaji' (fast) or 'ai' (slow) +prevent_sleep: false # Prevent macOS idle sleep during execution (caffeinate) +notification_sound: true # Enable/disable notification sounds +notification_sound_events: # Optional per-event toggles + iteration_limit: false + piece_complete: true + piece_abort: true + run_complete: true # Enabled by default; set false to disable + run_abort: true # Enabled by default; set false to disable +concurrency: 1 # Parallel task count for takt run (1-10, default: 1 = sequential) +task_poll_interval_ms: 500 # Polling interval for new tasks during takt run (100-5000, default: 500) +interactive_preview_movements: 3 # Movement previews in interactive mode (0-10, default: 3) + +# Runtime environment defaults (applies to all pieces unless piece_config.runtime overrides) +# runtime: +# prepare: +# - gradle # Prepare Gradle cache/config in .runtime/ +# - node # Prepare npm cache in .runtime/ + +# Per-persona provider overrides (optional) +# Route specific personas to different providers without duplicating pieces +# persona_providers: +# coder: codex # Run coder on Codex +# ai-antipattern-reviewer: claude # Keep reviewers on Claude + +# Provider-specific permission profiles (optional) +# Priority: project override > global override > project default > global default > required_permission_mode (floor) +# provider_profiles: +# codex: +# default_permission_mode: full +# movement_permission_overrides: +# ai_review: readonly +# claude: +# default_permission_mode: edit + +# API Key configuration (optional) +# Can be overridden by environment variables TAKT_ANTHROPIC_API_KEY / TAKT_OPENAI_API_KEY / TAKT_OPENCODE_API_KEY +# anthropic_api_key: sk-ant-... # For Claude (Anthropic) +# openai_api_key: sk-... # For Codex (OpenAI) +# opencode_api_key: ... # For OpenCode + +# Codex CLI path override (optional) +# Override the Codex CLI binary used by the Codex SDK (must be an absolute path to an executable file) +# Can be overridden by TAKT_CODEX_CLI_PATH environment variable +# codex_cli_path: /usr/local/bin/codex + +# Builtin piece filtering (optional) +# builtin_pieces_enabled: true # Set false to disable all builtins +# disabled_builtins: [magi, passthrough] # Disable specific builtin pieces + +# Pipeline execution configuration (optional) +# Customize branch names, commit messages, and PR body. +# pipeline: +# default_branch_prefix: "takt/" +# commit_message_template: "feat: {title} (#{issue})" +# pr_body_template: | +# ## Summary +# {issue_body} +# Closes #{issue} +``` + +### Global Config Field Reference + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `language` | `"en"` \| `"ja"` | `"en"` | UI language | +| `default_piece` | string | `"default"` | Default piece for new projects | +| `log_level` | `"debug"` \| `"info"` \| `"warn"` \| `"error"` | `"info"` | Log level | +| `provider` | `"claude"` \| `"codex"` \| `"opencode"` | `"claude"` | Default AI provider | +| `model` | string | - | Default model name (passed to provider as-is) | +| `branch_name_strategy` | `"romaji"` \| `"ai"` | `"romaji"` | Branch name generation strategy | +| `prevent_sleep` | boolean | `false` | Prevent macOS idle sleep (caffeinate) | +| `notification_sound` | boolean | `true` | Enable notification sounds | +| `notification_sound_events` | object | - | Per-event notification sound toggles | +| `concurrency` | number (1-10) | `1` | Parallel task count for `takt run` | +| `task_poll_interval_ms` | number (100-5000) | `500` | Polling interval for new tasks | +| `interactive_preview_movements` | number (0-10) | `3` | Movement previews in interactive mode | +| `worktree_dir` | string | - | Directory for shared clones (defaults to `../{clone-name}`) | +| `auto_pr` | boolean | - | Auto-create PR after worktree execution | +| `verbose` | boolean | - | Verbose output mode | +| `minimal_output` | boolean | `false` | Suppress AI output (for CI) | +| `runtime` | object | - | Runtime environment defaults (e.g., `prepare: [gradle, node]`) | +| `persona_providers` | object | - | Per-persona provider overrides (e.g., `coder: codex`) | +| `provider_options` | object | - | Global provider-specific options | +| `provider_profiles` | object | - | Provider-specific permission profiles | +| `anthropic_api_key` | string | - | Anthropic API key for Claude | +| `openai_api_key` | string | - | OpenAI API key for Codex | +| `opencode_api_key` | string | - | OpenCode API key | +| `codex_cli_path` | string | - | Codex CLI binary path override (absolute) | +| `enable_builtin_pieces` | boolean | `true` | Enable builtin pieces | +| `disabled_builtins` | string[] | `[]` | Specific builtin pieces to disable | +| `pipeline` | object | - | Pipeline template settings | +| `bookmarks_file` | string | - | Path to bookmarks file | +| `piece_categories_file` | string | - | Path to piece categories file | + +## Project Configuration + +Configure project-specific settings in `.takt/config.yaml`. This file is created when you first use TAKT in a project directory. + +```yaml +# .takt/config.yaml +piece: default # Current piece for this project +provider: claude # Override provider for this project +auto_pr: true # Auto-create PR after worktree execution +verbose: false # Verbose output mode + +# Provider-specific options (overrides global, overridden by piece/movement) +# provider_options: +# codex: +# network_access: true + +# Provider-specific permission profiles (project-level override) +# provider_profiles: +# codex: +# default_permission_mode: full +# movement_permission_overrides: +# ai_review: readonly +``` + +### Project Config Field Reference + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `piece` | string | `"default"` | Current piece name for this project | +| `provider` | `"claude"` \| `"codex"` \| `"opencode"` \| `"mock"` | - | Override provider | +| `auto_pr` | boolean | - | Auto-create PR after worktree execution | +| `verbose` | boolean | - | Verbose output mode | +| `provider_options` | object | - | Provider-specific options | +| `provider_profiles` | object | - | Provider-specific permission profiles | + +Project config values override global config when both are set. + +## API Key Configuration + +TAKT supports three providers, each with its own API key. API keys can be configured via environment variables or `~/.takt/config.yaml`. + +### Environment Variables (Recommended) + +```bash +# For Claude (Anthropic) +export TAKT_ANTHROPIC_API_KEY=sk-ant-... + +# For Codex (OpenAI) +export TAKT_OPENAI_API_KEY=sk-... + +# For OpenCode +export TAKT_OPENCODE_API_KEY=... +``` + +### Config File + +```yaml +# ~/.takt/config.yaml +anthropic_api_key: sk-ant-... # For Claude +openai_api_key: sk-... # For Codex +opencode_api_key: ... # For OpenCode +``` + +### Priority + +Environment variables take precedence over `config.yaml` settings. + +| Provider | Environment Variable | Config Key | +|----------|---------------------|------------| +| Claude (Anthropic) | `TAKT_ANTHROPIC_API_KEY` | `anthropic_api_key` | +| Codex (OpenAI) | `TAKT_OPENAI_API_KEY` | `openai_api_key` | +| OpenCode | `TAKT_OPENCODE_API_KEY` | `opencode_api_key` | + +### Security + +- If you write API keys in `config.yaml`, be careful not to commit this file to Git. +- Consider using environment variables instead. +- Add `~/.takt/config.yaml` to your global `.gitignore` if needed. +- If you set an API key, installing the corresponding CLI tool (Claude Code, Codex, OpenCode) is not necessary. TAKT directly calls the respective API. + +### Codex CLI Path Override + +You can override the Codex CLI binary path using either an environment variable or config: + +```bash +export TAKT_CODEX_CLI_PATH=/usr/local/bin/codex +``` + +```yaml +# ~/.takt/config.yaml +codex_cli_path: /usr/local/bin/codex +``` + +The path must be an absolute path to an executable file. `TAKT_CODEX_CLI_PATH` takes precedence over the config file value. + +## Model Resolution + +The model used for each movement is resolved with the following priority order (highest first): + +1. **Piece movement `model`** - Specified in the movement definition in piece YAML +2. **Custom agent `model`** - Agent-level model in `.takt/agents.yaml` +3. **Global config `model`** - Default model in `~/.takt/config.yaml` +4. **Provider default** - Falls back to the provider's built-in default (Claude: `sonnet`, Codex: `codex`, OpenCode: provider default) + +### Provider-specific Model Notes + +**Claude Code** supports aliases (`opus`, `sonnet`, `haiku`, `opusplan`, `default`) and full model names (e.g., `claude-sonnet-4-5-20250929`). The `model` field is passed directly to the provider CLI. Refer to the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code) for available models. + +**Codex** uses the model string as-is via the Codex SDK. If unspecified, defaults to `codex`. Refer to Codex documentation for available models. + +**OpenCode** requires a model in `provider/model` format (e.g., `opencode/big-pickle`). Omitting the model for the OpenCode provider will result in a configuration error. + +### Example + +```yaml +# ~/.takt/config.yaml +provider: claude +model: opus # Default model for all movements (unless overridden) +``` + +```yaml +# piece.yaml - movement-level override takes highest priority +movements: + - name: plan + model: opus # This movement uses opus regardless of global config + ... + - name: implement + # No model specified - falls back to global config (opus) + ... +``` + +## Provider Profiles + +Provider profiles allow you to set default permission modes and per-movement permission overrides for each provider. This is useful when running different providers with different security postures. + +### Permission Modes + +TAKT uses three provider-independent permission modes: + +| Mode | Description | Claude | Codex | OpenCode | +|------|-------------|--------|-------|----------| +| `readonly` | Read-only access, no file modifications | `default` | `read-only` | `read-only` | +| `edit` | Allow file edits with confirmation | `acceptEdits` | `workspace-write` | `workspace-write` | +| `full` | Bypass all permission checks | `bypassPermissions` | `danger-full-access` | `danger-full-access` | + +### Configuration + +Provider profiles can be set at both global and project levels: + +```yaml +# ~/.takt/config.yaml (global) or .takt/config.yaml (project) +provider_profiles: + codex: + default_permission_mode: full + movement_permission_overrides: + ai_review: readonly + claude: + default_permission_mode: edit + movement_permission_overrides: + implement: full +``` + +### Permission Resolution Priority + +Permission mode is resolved in the following order (first match wins): + +1. **Project** `provider_profiles..movement_permission_overrides.` +2. **Global** `provider_profiles..movement_permission_overrides.` +3. **Project** `provider_profiles..default_permission_mode` +4. **Global** `provider_profiles..default_permission_mode` +5. **Movement** `required_permission_mode` (acts as a minimum floor) + +The `required_permission_mode` on a movement sets the minimum floor. If the resolved mode from provider profiles is lower than the required mode, the required mode is used instead. For example, if a movement requires `edit` but the profile resolves to `readonly`, the effective mode will be `edit`. + +### Persona Providers + +Route specific personas to different providers without duplicating pieces: + +```yaml +# ~/.takt/config.yaml +persona_providers: + coder: codex # Run coder persona on Codex + ai-antipattern-reviewer: claude # Keep reviewers on Claude +``` + +This allows mixing providers within a single piece. The persona name is matched against the `persona` key in the movement definition. + +## Piece Categories + +Organize pieces into categories for better UI presentation in `takt switch` and piece selection prompts. + +### Configuration + +Categories can be configured in: +- `builtins/{lang}/piece-categories.yaml` - Default builtin categories +- `~/.takt/config.yaml` or a separate categories file specified by `piece_categories_file` + +```yaml +# ~/.takt/config.yaml or dedicated categories file +piece_categories: + Development: + pieces: [default, simple] + children: + Backend: + pieces: [expert-cqrs] + Frontend: + pieces: [expert] + Research: + pieces: [research, magi] + +show_others_category: true # Show uncategorized pieces (default: true) +others_category_name: "Other Pieces" # Name for uncategorized category +``` + +### Category Features + +- **Nested categories** - Unlimited depth for hierarchical organization +- **Per-category piece lists** - Assign pieces to specific categories +- **Others category** - Automatically collects uncategorized pieces (can be disabled via `show_others_category: false`) +- **Builtin piece filtering** - Disable all builtins via `enable_builtin_pieces: false`, or selectively via `disabled_builtins: [name1, name2]` + +### Resetting Categories + +Reset piece categories to builtin defaults: + +```bash +takt reset categories +``` + +## Pipeline Templates + +Pipeline mode (`--pipeline`) supports customizable templates for branch names, commit messages, and PR bodies. + +### Configuration + +```yaml +# ~/.takt/config.yaml +pipeline: + default_branch_prefix: "takt/" + commit_message_template: "feat: {title} (#{issue})" + pr_body_template: | + ## Summary + {issue_body} + Closes #{issue} +``` + +### Template Variables + +| Variable | Available In | Description | +|----------|-------------|-------------| +| `{title}` | Commit message | Issue title | +| `{issue}` | Commit message, PR body | Issue number | +| `{issue_body}` | PR body | Issue body | +| `{report}` | PR body | Piece execution report | + +### Pipeline CLI Options + +| Option | Description | +|--------|-------------| +| `--pipeline` | Enable pipeline (non-interactive) mode | +| `--auto-pr` | Create PR after execution | +| `--skip-git` | Skip branch creation, commit, and push (piece-only) | +| `--repo ` | Repository for PR creation | +| `-q, --quiet` | Minimal output mode (suppress AI output) | + +## Debugging + +### Debug Logging + +Enable debug logging by setting `debug_enabled: true` in `~/.takt/config.yaml` or by creating a `.takt/debug.yaml` file: + +```yaml +# .takt/debug.yaml +enabled: true +``` + +Debug logs are written to `.takt/logs/debug.log` in NDJSON format. + +### Verbose Mode + +Create an empty `.takt/verbose` file to enable verbose console output. This automatically enables debug logging. + +Alternatively, set `verbose: true` in your config: + +```yaml +# ~/.takt/config.yaml or .takt/config.yaml +verbose: true +``` diff --git a/docs/task-management.ja.md b/docs/task-management.ja.md new file mode 100644 index 0000000..489c195 --- /dev/null +++ b/docs/task-management.ja.md @@ -0,0 +1,323 @@ +[English](./task-management.md) + +# タスク管理 + +## 概要 + +TAKT は複数のタスクを蓄積してバッチ実行するためのタスク管理ワークフローを提供します。基本的な流れは次の通りです。 + +1. **`takt add`** -- AI との会話でタスク要件を精緻化し、`.takt/tasks.yaml` に保存 +2. **タスクの蓄積** -- `order.md` ファイルを編集し、参考資料を添付 +3. **`takt run`** -- すべての pending タスクを一括実行（逐次または並列） +4. **`takt list`** -- 結果を確認し、ブランチのマージ、失敗のリトライ、指示の追加 + +各タスクは隔離された共有クローン（オプション）で実行され、レポートを生成し、`takt list` でマージまたは破棄できるブランチを作成します。 + +## タスクの追加（`takt add`） + +`takt add` を使用して `.takt/tasks.yaml` に新しいタスクエントリを作成します。 + +```bash +# インラインテキストでタスクを追加 +takt add "Implement user authentication" + +# GitHub Issue からタスクを追加 +takt add #28 +``` + +タスク追加時に次の項目を確認されます。 + +- **Piece** -- 実行に使用する piece（ワークフロー） +- **Worktree パス** -- 隔離クローンの作成場所（Enter で自動、またはパスを指定） +- **ブランチ名** -- カスタムブランチ名（Enter で `takt/{timestamp}-{slug}` が自動生成） +- **Auto-PR** -- 実行成功後に PR を自動作成するかどうか + +### GitHub Issue 連携 + +Issue 参照（例: `#28`）を渡すと、TAKT は GitHub CLI（`gh`）を介して Issue のタイトル、本文、ラベル、コメントを取得し、タスク内容として使用します。Issue 番号は `tasks.yaml` に記録され、ブランチ名にも反映されます。 + +**要件:** [GitHub CLI](https://cli.github.com/)（`gh`）がインストールされ、認証済みである必要があります。 + +### インタラクティブモードからのタスク保存 + +インタラクティブモードからもタスクを保存できます。会話で要件を精緻化した後、`/save`（またはプロンプト時の save アクション）を使用して、即座に実行する代わりに `tasks.yaml` にタスクを永続化できます。 + +## タスクディレクトリ形式 + +TAKT はタスクのメタデータを `.takt/tasks.yaml` に、各タスクの詳細仕様を `.takt/tasks/{slug}/` に保存します。 + +### `tasks.yaml` スキーマ + +```yaml +tasks: + - name: add-auth-feature + status: pending + task_dir: .takt/tasks/20260201-015714-foptng + piece: default + created_at: "2026-02-01T01:57:14.000Z" + started_at: null + completed_at: null +``` + +フィールドの説明は次の通りです。 + +| フィールド | 説明 | +|-----------|------| +| `name` | AI が生成したタスクスラグ | +| `status` | `pending`、`running`、`completed`、または `failed` | +| `task_dir` | `order.md` を含むタスクディレクトリのパス | +| `piece` | 実行に使用する piece 名 | +| `worktree` | `true`（自動）、パス文字列、または省略（カレントディレクトリで実行） | +| `branch` | ブランチ名（省略時は自動生成） | +| `auto_pr` | 実行後に PR を自動作成するかどうか | +| `issue` | GitHub Issue 番号（該当する場合） | +| `created_at` | ISO 8601 タイムスタンプ | +| `started_at` | ISO 8601 タイムスタンプ（実行開始時に設定） | +| `completed_at` | ISO 8601 タイムスタンプ（実行完了時に設定） | + +### タスクディレクトリのレイアウト + +```text +.takt/ + tasks/ + 20260201-015714-foptng/ + order.md # タスク仕様（自動生成、編集可能） + schema.sql # 添付の参考資料（任意） + wireframe.png # 添付の参考資料（任意） + tasks.yaml # タスクメタデータレコード + runs/ + 20260201-015714-foptng/ + reports/ # 実行レポート（自動生成） + logs/ # NDJSON セッションログ + context/ # スナップショット（previous_responses など） + meta.json # 実行メタデータ +``` + +`takt add` は `.takt/tasks/{slug}/order.md` を自動作成し、`task_dir` への参照を `tasks.yaml` に保存します。実行前に `order.md` を自由に編集したり、タスクディレクトリに補足ファイル（SQL スキーマ、ワイヤーフレーム、API 仕様など）を追加したりできます。 + +## タスクの実行（`takt run`） + +`.takt/tasks.yaml` のすべての pending タスクを実行します。 + +```bash +takt run +``` + +`run` コマンドは pending タスクを取得して、設定された piece を通じて実行します。各タスクは次の処理を経ます。 + +1. クローン作成（`worktree` が設定されている場合） +2. クローン/プロジェクトディレクトリでの piece 実行 +3. 自動コミットとプッシュ（worktree 実行の場合） +4. 実行後フロー（`auto_pr` 設定時は PR 作成） +5. `tasks.yaml` のステータス更新（`completed` または `failed`） + +### 並列実行（Concurrency） + +デフォルトではタスクは逐次実行されます（`concurrency: 1`）。`~/.takt/config.yaml` で並列実行を設定できます。 + +```yaml +concurrency: 3 # 最大3タスクを並列実行（1-10） +task_poll_interval_ms: 500 # 新規タスクのポーリング間隔（100-5000ms） +``` + +concurrency が 1 より大きい場合、TAKT はワーカープールを使用して次のように動作します。 + +- 最大 N タスクを同時実行 +- 設定された間隔で新規タスクをポーリング +- ワーカーが空き次第、新しいタスクを取得 +- タスクごとに色分けされたプレフィックス付き出力で読みやすさを確保 +- Ctrl+C でのグレースフルシャットダウン（実行中タスクの完了を待機） + +### 中断されたタスクの復旧 + +`takt run` が中断された場合（プロセスクラッシュ、Ctrl+C など）、`running` ステータスのまま残ったタスクは次回の `takt run` または `takt watch` 起動時に自動的に `pending` に復旧されます。 + +## タスクの監視（`takt watch`） + +`.takt/tasks.yaml` を監視し、タスクが追加されると自動実行する常駐プロセスを起動します。 + +```bash +takt watch +``` + +watch コマンドの動作は次の通りです。 + +- Ctrl+C（SIGINT）まで実行を継続 +- `tasks.yaml` の新しい `pending` タスクを監視 +- タスクが現れるたびに実行 +- 起動時に中断された `running` タスクを復旧 +- 終了時に合計/成功/失敗タスク数のサマリを表示 + +これは「プロデューサー-コンシューマー」ワークフローに便利です。一方のターミナルで `takt add` でタスクを追加し、もう一方で `takt watch` がそれらを自動実行します。 + +## タスクブランチの管理（`takt list`） + +タスクブランチの一覧表示とインタラクティブな管理を行います。 + +```bash +takt list +``` + +リストビューでは、すべてのタスクがステータス別（pending、running、completed、failed）に作成日とサマリ付きで表示されます。タスクを選択すると、そのステータスに応じた操作が表示されます。 + +### 完了タスクの操作 + +| 操作 | 説明 | +|------|------| +| **View diff** | デフォルトブランチとの差分をページャで表示 | +| **Instruct** | AI との会話で追加指示を作成し、再実行 | +| **Try merge** | スカッシュマージ（コミットせずにステージング、手動レビュー用） | +| **Merge & cleanup** | スカッシュマージしてブランチを削除 | +| **Delete** | すべての変更を破棄してブランチを削除 | + +### 失敗タスクの操作 + +| 操作 | 説明 | +|------|------| +| **Retry** | 失敗コンテキスト付きのリトライ会話を開き、再実行 | +| **Delete** | 失敗したタスクレコードを削除 | + +### Pending タスクの操作 + +| 操作 | 説明 | +|------|------| +| **Delete** | `tasks.yaml` から pending タスクを削除 | + +### Instruct モード + +完了タスクで **Instruct** を選択すると、TAKT は AI とのインタラクティブな会話ループを開きます。会話には次の情報がプリロードされます。 + +- ブランチコンテキスト（デフォルトブランチとの差分統計、コミット履歴） +- 前回の実行セッションデータ（movement ログ、レポート） +- Piece 構造と movement プレビュー +- 前回の order 内容 + +どのような追加変更が必要かを議論し、AI が指示の精緻化を支援します。準備ができたら次の操作を選択できます。 + +- **Execute** -- 新しい指示でタスクを即座に再実行 +- **Save task** -- 新しい指示でタスクを `pending` として再キューイングし、後で実行 +- **Cancel** -- 破棄してリストに戻る + +### Retry モード + +失敗タスクで **Retry** を選択すると、TAKT は次の処理を行います。 + +1. 失敗の詳細を表示（失敗した movement、エラーメッセージ、最後のエージェントメッセージ） +2. Piece の選択を促す +3. どの movement から開始するかの選択を促す（デフォルトは失敗した movement） +4. 失敗コンテキスト、実行セッションデータ、piece 構造がプリロードされたリトライ会話を開く +5. AI の支援で指示を精緻化 + +リトライ会話は Instruct モードと同じ操作（実行、タスク保存、キャンセル）をサポートします。リトライのメモは複数のリトライ試行にわたってタスクレコードに蓄積されます。 + +### 非インタラクティブモード（`--non-interactive`） + +CI/CD スクリプト向けの非インタラクティブモードを使用できます。 + +```bash +# すべてのタスクをテキストで一覧表示 +takt list --non-interactive + +# すべてのタスクを JSON で一覧表示 +takt list --non-interactive --format json + +# 特定ブランチの差分統計を表示 +takt list --non-interactive --action diff --branch takt/my-branch + +# 特定ブランチをマージ +takt list --non-interactive --action merge --branch takt/my-branch + +# ブランチを削除（--yes が必要） +takt list --non-interactive --action delete --branch takt/my-branch --yes + +# Try merge（コミットせずにステージング） +takt list --non-interactive --action try --branch takt/my-branch +``` + +利用可能なアクションは `diff`、`try`、`merge`、`delete` です。 + +## タスクディレクトリワークフロー + +推奨されるエンドツーエンドのワークフローは次の通りです。 + +1. **`takt add`** -- タスクを作成。`.takt/tasks.yaml` に pending レコードが追加され、`.takt/tasks/{slug}/` に `order.md` が生成される。 +2. **`order.md` を編集** -- 生成されたファイルを開き、必要に応じて詳細な仕様、参考資料、補足ファイルを追加。 +3. **`takt run`**（または `takt watch`）-- `tasks.yaml` の pending タスクを実行。各タスクは設定された piece ワークフローを通じて実行される。 +4. **出力を確認** -- `.takt/runs/{slug}/reports/` の実行レポートを確認（slug はタスクディレクトリと一致）。 +5. **`takt list`** -- 結果を確認し、成功したブランチのマージ、失敗のリトライ、追加指示を行う。 + +## 隔離実行（共有クローン） + +タスク設定で `worktree` を指定すると、各タスクは `git clone --shared` で作成された隔離クローン内で実行され、メインの作業ディレクトリをクリーンに保ちます。 + +### 設定オプション + +| 設定 | 説明 | +|------|------| +| `worktree: true` | 隣接ディレクトリ（または `worktree_dir` 設定で指定した場所）に共有クローンを自動作成 | +| `worktree: "/path/to/dir"` | 指定パスにクローンを作成 | +| `branch: "feat/xxx"` | 指定ブランチを使用（省略時は `takt/{timestamp}-{slug}` が自動生成） | +| *(worktree を省略)* | カレントディレクトリで実行（デフォルト） | + +### 仕組み + +TAKT は `git worktree` の代わりに `git clone --shared` を使用して、独立した `.git` ディレクトリを持つ軽量クローンを作成します。これが重要な理由は次の通りです。 + +- **独立した `.git`**: 共有クローンは独自の `.git` ディレクトリを持ち、エージェントツール（Claude Code など）が `gitdir:` 参照をたどってメインリポジトリに戻ることを防ぎます。 +- **完全な隔離**: エージェントはクローンディレクトリ内でのみ作業し、メインリポジトリを認識しません。 + +> **注意**: YAML フィールド名は後方互換性のため `worktree` のままです。内部的には `git worktree` ではなく `git clone --shared` を使用しています。 + +### エフェメラルなライフサイクル + +クローンはエフェメラルなライフサイクルに従います。 + +1. **作成** -- タスク実行前にクローンを作成 +2. **実行** -- クローンディレクトリ内でタスクを実行 +3. **コミット & プッシュ** -- 成功時に変更を自動コミットしてブランチにプッシュ +4. **保持** -- 実行後もクローンを保持（instruct/retry 操作用） +5. **クリーンアップ** -- ブランチが永続的な成果物。`takt list` でマージまたは削除 + +### デュアルワーキングディレクトリ + +worktree 実行中、TAKT は2つのディレクトリ参照を管理します。 + +| ディレクトリ | 用途 | +|------------|------| +| `cwd`（クローンパス） | エージェントの実行場所、レポートの書き込み先 | +| `projectCwd`（プロジェクトルート） | ログとセッションデータの保存先 | + +レポートは `cwd/.takt/runs/{slug}/reports/`（クローン内）に書き込まれ、エージェントがメインリポジトリのパスを発見することを防ぎます。`cwd !== projectCwd` の場合、クロスディレクトリ汚染を避けるためセッション再開はスキップされます。 + +## セッションログ + +TAKT は NDJSON（改行区切り JSON、`.jsonl`）形式でセッションログを書き込みます。各レコードはアトミックに追加されるため、プロセスがクラッシュしても部分的なログは保存されます。 + +### ログの場所 + +```text +.takt/runs/{slug}/ + logs/{sessionId}.jsonl # piece 実行ごとの NDJSON セッションログ + meta.json # 実行メタデータ（タスク、piece、開始/終了、ステータスなど） + context/ + previous_responses/ + latest.md # 最新の previous response（自動継承） +``` + +### レコードタイプ + +| レコードタイプ | 説明 | +|--------------|------| +| `piece_start` | タスクと piece 名による piece の初期化 | +| `step_start` | Movement の実行開始 | +| `step_complete` | ステータス、内容、マッチしたルール情報を含む movement 結果 | +| `piece_complete` | Piece の正常完了 | +| `piece_abort` | 理由を伴う中断 | + +### リアルタイム監視 + +実行中にログをリアルタイムで監視できます。 + +```bash +tail -f .takt/runs/{slug}/logs/{sessionId}.jsonl +``` diff --git a/docs/task-management.md b/docs/task-management.md new file mode 100644 index 0000000..d826aeb --- /dev/null +++ b/docs/task-management.md @@ -0,0 +1,323 @@ +[日本語](./task-management.ja.md) + +# Task Management + +## Overview + +TAKT provides a task management workflow for accumulating multiple tasks and executing them in batch. The basic flow is: + +1. **`takt add`** -- Refine task requirements through AI conversation and save to `.takt/tasks.yaml` +2. **Tasks accumulate** -- Edit `order.md` files, attach reference materials +3. **`takt run`** -- Execute all pending tasks at once (sequential or parallel) +4. **`takt list`** -- Review results, merge branches, retry failures, or add instructions + +Each task executes in an isolated shared clone (optional), produces reports, and creates a branch that can be merged or discarded via `takt list`. + +## Adding Tasks (`takt add`) + +Use `takt add` to create a new task entry in `.takt/tasks.yaml`. + +```bash +# Add a task with inline text +takt add "Implement user authentication" + +# Add a task from a GitHub Issue +takt add #28 +``` + +When adding a task, you are prompted for: + +- **Piece** -- Which piece (workflow) to use for execution +- **Worktree path** -- Where to create the isolated clone (Enter for auto, or specify a path) +- **Branch name** -- Custom branch name (Enter for auto-generated `takt/{timestamp}-{slug}`) +- **Auto-PR** -- Whether to automatically create a pull request after successful execution + +### GitHub Issue Integration + +When you pass an issue reference (e.g., `#28`), TAKT fetches the issue title, body, labels, and comments via the GitHub CLI (`gh`) and uses them as the task content. The issue number is recorded in `tasks.yaml` and reflected in the branch name. + +**Requirement:** [GitHub CLI](https://cli.github.com/) (`gh`) must be installed and authenticated. + +### Saving Tasks from Interactive Mode + +You can also save tasks from interactive mode. After refining requirements through conversation, use `/save` (or the save action when prompted) to persist the task to `tasks.yaml` instead of executing immediately. + +## Task Directory Format + +TAKT stores task metadata in `.takt/tasks.yaml` and each task's detailed specification in `.takt/tasks/{slug}/`. + +### `tasks.yaml` Schema + +```yaml +tasks: + - name: add-auth-feature + status: pending + task_dir: .takt/tasks/20260201-015714-foptng + piece: default + created_at: "2026-02-01T01:57:14.000Z" + started_at: null + completed_at: null +``` + +Fields: + +| Field | Description | +|-------|-------------| +| `name` | AI-generated task slug | +| `status` | `pending`, `running`, `completed`, or `failed` | +| `task_dir` | Path to the task directory containing `order.md` | +| `piece` | Piece name to use for execution | +| `worktree` | `true` (auto), a path string, or omitted (run in current directory) | +| `branch` | Branch name (auto-generated if omitted) | +| `auto_pr` | Whether to auto-create a PR after execution | +| `issue` | GitHub Issue number (if applicable) | +| `created_at` | ISO 8601 timestamp | +| `started_at` | ISO 8601 timestamp (set when execution begins) | +| `completed_at` | ISO 8601 timestamp (set when execution finishes) | + +### Task Directory Layout + +```text +.takt/ + tasks/ + 20260201-015714-foptng/ + order.md # Task specification (auto-generated, editable) + schema.sql # Attached reference materials (optional) + wireframe.png # Attached reference materials (optional) + tasks.yaml # Task metadata records + runs/ + 20260201-015714-foptng/ + reports/ # Execution reports (auto-generated) + logs/ # NDJSON session logs + context/ # Snapshots (previous_responses, etc.) + meta.json # Run metadata +``` + +`takt add` creates `.takt/tasks/{slug}/order.md` automatically and saves the `task_dir` reference to `tasks.yaml`. You can freely edit `order.md` and add supplementary files (SQL schemas, wireframes, API specs, etc.) to the task directory before execution. + +## Executing Tasks (`takt run`) + +Execute all pending tasks from `.takt/tasks.yaml`: + +```bash +takt run +``` + +The `run` command claims pending tasks and executes them through the configured piece. Each task goes through: + +1. Clone creation (if `worktree` is set) +2. Piece execution in the clone/project directory +3. Auto-commit and push (if worktree execution) +4. Post-execution flow (PR creation if `auto_pr` is set) +5. Status update in `tasks.yaml` (`completed` or `failed`) + +### Parallel Execution (Concurrency) + +By default, tasks run sequentially (`concurrency: 1`). Configure parallel execution in `~/.takt/config.yaml`: + +```yaml +concurrency: 3 # Run up to 3 tasks in parallel (1-10) +task_poll_interval_ms: 500 # Polling interval for new tasks (100-5000ms) +``` + +When concurrency is greater than 1, TAKT uses a worker pool that: + +- Runs up to N tasks simultaneously +- Polls for newly added tasks at the configured interval +- Picks up new tasks as workers become available +- Displays color-coded prefixed output per task for readability +- Supports graceful shutdown on Ctrl+C (waits for in-flight tasks to complete) + +### Interrupted Task Recovery + +If `takt run` is interrupted (e.g., process crash, Ctrl+C), tasks left in `running` status are automatically recovered to `pending` on the next `takt run` or `takt watch` invocation. + +## Watching Tasks (`takt watch`) + +Run a resident process that monitors `.takt/tasks.yaml` and auto-executes tasks as they appear: + +```bash +takt watch +``` + +The watch command: + +- Stays running until Ctrl+C (SIGINT) +- Monitors `tasks.yaml` for new `pending` tasks +- Executes each task as it appears +- Recovers interrupted `running` tasks on startup +- Displays a summary of total/success/failed tasks on exit + +This is useful for a "producer-consumer" workflow where you add tasks with `takt add` in one terminal and let `takt watch` execute them automatically in another. + +## Managing Task Branches (`takt list`) + +List and manage task branches interactively: + +```bash +takt list +``` + +The list view shows all tasks organized by status (pending, running, completed, failed) with creation dates and summaries. Selecting a task shows available actions depending on its status. + +### Actions for Completed Tasks + +| Action | Description | +|--------|-------------| +| **View diff** | Show full diff against the default branch in a pager | +| **Instruct** | Open an AI conversation to craft additional instructions, then re-execute | +| **Try merge** | Squash merge (stages changes without committing, for manual review) | +| **Merge & cleanup** | Squash merge and delete the branch | +| **Delete** | Discard all changes and delete the branch | + +### Actions for Failed Tasks + +| Action | Description | +|--------|-------------| +| **Retry** | Open a retry conversation with failure context, then re-execute | +| **Delete** | Remove the failed task record | + +### Actions for Pending Tasks + +| Action | Description | +|--------|-------------| +| **Delete** | Remove the pending task from `tasks.yaml` | + +### Instruct Mode + +When you select **Instruct** on a completed task, TAKT opens an interactive conversation loop with the AI. The conversation is pre-loaded with: + +- Branch context (diff stat against default branch, commit history) +- Previous run session data (movement logs, reports) +- Piece structure and movement previews +- Previous order content + +You can discuss what additional changes are needed, and the AI helps refine the instructions. When ready, choose: + +- **Execute** -- Re-execute the task immediately with the new instructions +- **Save task** -- Requeue the task as `pending` with the new instructions for later execution +- **Cancel** -- Discard and return to the list + +### Retry Mode + +When you select **Retry** on a failed task, TAKT: + +1. Displays failure details (failed movement, error message, last agent message) +2. Prompts you to select a piece +3. Prompts you to select which movement to start from (defaults to the failed movement) +4. Opens a retry conversation pre-loaded with failure context, run session data, and piece structure +5. Lets you refine instructions with AI assistance + +The retry conversation supports the same actions as Instruct mode (execute, save task, cancel). Retry notes are appended to the task record, accumulating across multiple retry attempts. + +### Non-Interactive Mode (`--non-interactive`) + +For CI/CD scripts, use non-interactive mode: + +```bash +# List all tasks as text +takt list --non-interactive + +# List all tasks as JSON +takt list --non-interactive --format json + +# Show diff stat for a specific branch +takt list --non-interactive --action diff --branch takt/my-branch + +# Merge a specific branch +takt list --non-interactive --action merge --branch takt/my-branch + +# Delete a branch (requires --yes) +takt list --non-interactive --action delete --branch takt/my-branch --yes + +# Try merge (stage without commit) +takt list --non-interactive --action try --branch takt/my-branch +``` + +Available actions: `diff`, `try`, `merge`, `delete`. + +## Task Directory Workflow + +The recommended end-to-end workflow: + +1. **`takt add`** -- Create a task. A pending record is added to `.takt/tasks.yaml` and `order.md` is generated in `.takt/tasks/{slug}/`. +2. **Edit `order.md`** -- Open the generated file and add detailed specifications, reference materials, or supplementary files as needed. +3. **`takt run`** (or `takt watch`) -- Execute pending tasks from `tasks.yaml`. Each task runs through the configured piece workflow. +4. **Verify outputs** -- Check execution reports in `.takt/runs/{slug}/reports/` (the slug matches the task directory). +5. **`takt list`** -- Review results, merge successful branches, retry failures, or add further instructions. + +## Isolated Execution (Shared Clone) + +Specifying `worktree` in task configuration executes each task in an isolated clone created with `git clone --shared`, keeping your main working directory clean. + +### Configuration Options + +| Setting | Description | +|---------|-------------| +| `worktree: true` | Auto-create shared clone in adjacent directory (or location specified by `worktree_dir` config) | +| `worktree: "/path/to/dir"` | Create clone at the specified path | +| `branch: "feat/xxx"` | Use specified branch (auto-generated as `takt/{timestamp}-{slug}` if omitted) | +| *(omit `worktree`)* | Execute in current directory (default) | + +### How It Works + +TAKT uses `git clone --shared` instead of `git worktree` to create lightweight clones with an independent `.git` directory. This is important because: + +- **Independent `.git`**: Shared clones have their own `.git` directory, preventing agent tools (like Claude Code) from traversing `gitdir:` references back to the main repository. +- **Full isolation**: Agents work entirely within the clone directory, unaware of the main repository. + +> **Note**: The YAML field name remains `worktree` for backward compatibility. Internally, it uses `git clone --shared` instead of `git worktree`. + +### Ephemeral Lifecycle + +Clones follow an ephemeral lifecycle: + +1. **Create** -- Clone is created before task execution +2. **Execute** -- Task runs inside the clone directory +3. **Commit & Push** -- On success, changes are auto-committed and pushed to the branch +4. **Preserve** -- Clone is preserved after execution (for instruct/retry operations) +5. **Cleanup** -- Branches are the persistent artifacts; use `takt list` to merge or delete + +### Dual Working Directory + +During worktree execution, TAKT maintains two directory references: + +| Directory | Purpose | +|-----------|---------| +| `cwd` (clone path) | Where agents run, where reports are written | +| `projectCwd` (project root) | Where logs and session data are stored | + +Reports are written to `cwd/.takt/runs/{slug}/reports/` (inside the clone) to prevent agents from discovering the main repository path. Session resume is skipped when `cwd !== projectCwd` to avoid cross-directory contamination. + +## Session Logs + +TAKT writes session logs in NDJSON (Newline-Delimited JSON, `.jsonl`) format. Each record is atomically appended, so partial logs are preserved even if the process crashes. + +### Log Location + +```text +.takt/runs/{slug}/ + logs/{sessionId}.jsonl # NDJSON session log per piece execution + meta.json # Run metadata (task, piece, start/end, status, etc.) + context/ + previous_responses/ + latest.md # Latest previous response (inherited automatically) +``` + +### Record Types + +| Record Type | Description | +|-------------|-------------| +| `piece_start` | Piece initialization with task and piece name | +| `step_start` | Movement execution start | +| `step_complete` | Movement result with status, content, matched rule info | +| `piece_complete` | Successful piece completion | +| `piece_abort` | Abort with reason | + +### Real-Time Monitoring + +You can monitor logs in real-time during execution: + +```bash +tail -f .takt/runs/{slug}/logs/{sessionId}.jsonl +```