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 +```