takt-task

TAKT Task Creator

Create and edit TAKT's tasks.yaml entries and task directories (order.md).

Prerequisite takt version: v0.30.0

Reference materials

Materials related to takt's task management are located in references/takt/ . Refer to the following as needed.

Material	Path	Purpose
Task management documentation	references/takt/docs/task-management.ja.md	Entire task workflow
TaskRecord schema	references/takt/src/infra/task/schema.ts	Field definitions and validation
Task format specification	references/takt/builtins/project/tasks/TASK-FORMAT	Details of the task_dir format
Schema details	This skill's references/task-schema.md	Field list and status transitions
validation script	This skill's validate-order-md.sh	Structure validation of order.md

Important: TaskRecord status transition rules are strictly validated.references/task-schema.md Read this to understand the invariants.

Workflow

Step 1: Requirements elicitation

Confirm the following (ask the user about anything unclear):

1. Task content: What the task is to execute
2. Piece: The piece name to use (default, dual, custom, etc.)
3. Isolated execution: Whether a worktree is needed (true / path / omitted)
4. Branch: Custom branch name (auto-generated if omitted)
5. Automatic PR creation: auto_pr / draft_pr whether required
6. Issue integration: GitHub Issue number (if applicable)

Step 2: Designing the parallel execution strategy

When creating multiple tasks, design whether parallel execution is possible and the splitting strategy. For a single task, skip this step.

a) TAKT's parallel execution model

TAKTは takt run At times, multiple tasks can be executed in parallel with a worker pool. However, there is no inter-task dependency mechanism (depends_on , etc.).

Characteristic	Details
Execution model	Worker pool (concurrency: 1-10）
Dependencies	None (all pending tasks are immediately eligible for execution)
Isolation	worktree: true Isolation via git worktree with
Synchronization	No live synchronization between tasks (work is done on a snapshot from the time of cloning)
Merge	Individual PR after each task completes → manual merge

Principle: Always set worktree: true for tasks that run in parallel. Parallel execution without isolation leads to destruction of the working directory.

b) Identifying serial sections (from an Amdahl's Law perspective)

Determine whether there is a serial section within the task group where "subsequent work cannot proceed until the earlier one is complete."

Serial factor	Example	Countermeasure
Schema change	DB migration	Integrate into preceding task
Common type definitions	Create new shared interface / struct	Execute type definition task first
Configuration file change	CI/CD, build configuration	Integrate into preceding task
API specification design	OpenAPI schema	Execute specification design first

Hearing questions: "Are there any dependencies between tasks where the output of one task becomes the input of another task?"

c) Analysis of shared resource contention (USL: contention cost α)

When multiple tasks modify the same resource, merge conflicts occur.

Shared resource	Contention risk	Recommended measure
Same source file	High	Merge the tasks
Same configuration file	High	Merge the tasks
Same test file	Medium	Consider merging
Different files in the same package	Low	Parallelizable (but be careful when adding imports)
Completely different modules	None	Safely parallelizable

Principle: "If two tasks may modify the same file, merge them"

d) Analysis of consistency cost (USL: consistency cost β)

The cost of maintaining consistency of shared types and interfaces between tasks. In TAKT, there is no live synchronization between tasks, so each task works on the snapshot at the time of cloning.

Consistency factor	β impact	Measure
Adding fields to a shared type	High	Execute the type definition side first
Changing a common interface	High	Do the interface change first
Adding an export to the same module	Medium	Be careful of index file conflicts
Type references between independent modules	Low	Parallelizable

e) Decision table for task splitting/merging

#	Scenario	File conflict	Serial dependency	Decision	Recommended concurrency
1	Implementation of independent modules A, B, C	None	None	Parallel	min(タスク数, 5)
2	Adding multiple features within the same module	Yes	None	Merge	1
3	API definition + its implementation	Yes	Yes	Merge	1
4	FE + BE (API specification finalized)	None	None	Parallel	2
5	FE + BE (API specification not finalized)	None	Yes	Staged execution	1 → Merge → 1
6	DB schema + application implementation	None	Yes	Staged execution	1 → merge → parallel
7	Independent bug fix group	None	None	Parallel	min(タスク数, 5)
8	Multiple bug fixes in the same file	Yes	None	Integrated	1
9	Refactoring + new feature	Yes	Yes	Integrated	1

f) Recommended concurrency value guide

Inter-task relationship	Recommended concurrency
Completely independent (no file overlap)	min(タスク数, 5)
Partially shared (low risk)	min(タスク数, 3)
Only type definition consumption relationship	1(staged execution)
Same file changes present	1(consider integration)
Tightly coupled (serial dependency + file sharing)	1

Note: concurrency は takt run is a global setting, and cannot be specified per task. If staged execution is required, takt run multiple times.

g) Parallel pattern collection

Pattern A: Fully parallel (independent modules)

tasks:
  - name: impl-module-a
    status: pending
    piece: default
    task_dir: .takt/tasks/20260301-100000-aaaaaa
    worktree: true
    branch: feat/module-a
    auto_pr: true
    created_at: "2026-03-01T10:00:00.000Z"
    started_at: null
    completed_at: null
  - name: impl-module-b
    status: pending
    piece: default
    task_dir: .takt/tasks/20260301-100000-bbbbbb
    worktree: true
    branch: feat/module-b
    auto_pr: true
    created_at: "2026-03-01T10:00:00.000Z"
    started_at: null
    completed_at: null
  - name: impl-module-c
    status: pending
    piece: default
    task_dir: .takt/tasks/20260301-100000-cccccc
    worktree: true
    branch: feat/module-c
    auto_pr: true
    created_at: "2026-03-01T10:00:00.000Z"
    started_at: null
    completed_at: null

takt run --concurrency 3 to run in parallel.

Pattern B: Dependency integration (schema + implementation in one task)

tasks:
  - name: add-user-profile
    status: pending
    piece: default
    task_dir: .takt/tasks/20260301-100000-dddddd
    worktree: true
    branch: feat/user-profile
    auto_pr: true
    created_at: "2026-03-01T10:00:00.000Z"
    started_at: null
    completed_at: null

Describe both the schema change and the implementation in order.md, and execute as one task.

Pattern C: Staged execution (preceding task → merge → subsequent parallel)

Stage 1: Common foundation

tasks:
  - name: define-shared-types
    status: pending
    piece: default
    task_dir: .takt/tasks/20260301-100000-eeeeee
    worktree: true
    branch: feat/shared-types
    auto_pr: true
    created_at: "2026-03-01T10:00:00.000Z"
    started_at: null
    completed_at: null

takt run to execute → after PR merge, add the Stage 2 tasks:

tasks:
  - name: impl-consumer-x
    status: pending
    piece: default
    task_dir: .takt/tasks/20260301-110000-ffffff
    worktree: true
    branch: feat/consumer-x
    auto_pr: true
    created_at: "2026-03-01T11:00:00.000Z"
    started_at: null
    completed_at: null
  - name: impl-consumer-y
    status: pending
    piece: default
    task_dir: .takt/tasks/20260301-110000-gggggg
    worktree: true
    branch: feat/consumer-y
    auto_pr: true
    created_at: "2026-03-01T11:00:00.000Z"
    started_at: null
    completed_at: null

takt run --concurrency 2 to run in parallel.

Step 3: Creating task directories

Recommended format: task_dir(order.md separated type)

slug generation

{YYYYMMDD}-{HHmmss}-{random6} format.

例: 20260223-143000-ab12cd

Directory structure

.takt/tasks/{slug}/
├── order.md          # タスク仕様（必須）
├── schema.sql        # 参考資料（任意）
└── wireframe.png     # 参考資料（任意）

order.md template

# タスク仕様

## 目的

{1-2文でタスクの目的を記述}

## 要件

- [ ] {要件1}
- [ ] {要件2}
- [ ] {要件3}

## 受け入れ基準

- {基準1}
- {基準2}

## 参考情報

{該当する場合に記述。API仕様、設計ドキュメント等}

Note: Template variables ({task}etc.) are unnecessary within order.md. The engine injects them automatically.

Step 4: Generating tasks.yaml entries

.takt/tasks.yaml Add a new task record. If the file does not exist, initialize it with the following:

tasks: []

Minimal configuration (task_dir format)

tasks:
  - name: add-auth-feature
    status: pending
    piece: default
    task_dir: .takt/tasks/20260223-143000-ab12cd
    created_at: "2026-02-23T14:30:00.000Z"
    started_at: null
    completed_at: null

Full configuration

tasks:
  - name: add-auth-feature
    status: pending
    piece: default
    task_dir: .takt/tasks/20260223-143000-ab12cd
    slug: 20260223-143000-ab12cd
    worktree: true
    branch: feat/auth-feature
    auto_pr: true
    draft_pr: false
    issue: 28
    created_at: "2026-02-23T14:30:00.000Z"
    started_at: null
    completed_at: null

content format (legacy, deprecated)

tasks:
  - name: fix-login-bug
    status: pending
    piece: default
    content: >-
      ログイン画面で認証エラーが発生する問題を修正する。
      原因: セッショントークンの有効期限チェックが不正。
    created_at: "2026-02-23T14:30:00.000Z"
    started_at: null
    completed_at: null

Exclusive constraint on content source

content, content_file, task_dir one ofExactly oneis required. Specifying multiple results in a validation error.

Format	Field	Recommendation level
Task directory	task_dir	Recommended
Inline	content	Legacy
External file	content_file	Legacy

Step 5: Validation

Check the consistency of the created task (for details, see references/task-schema.md ):

• task_dir が .takt/tasks/<slug> format
• task_dir when specifying order.md actually exists
• status: pending で started_at: null, completed_at: null か
• created_at is in ISO8601 format
• content, content_file, task_dir only one of these is specified
• piece name matches an existing piece (built-in or custom)
• existing task's tasks.yaml overall structure is not broken

Parallel consistency check (when creating multiple tasks)

• whether tasks that modify the same file are not separated (they should be integrated)
• Whether the configuration is such that shared type definition tasks are executed before consuming tasks (staged execution)
• Whether worktree: true is set for all parallel execution tasks
• Recommended concurrency Whether the value was communicated to the user

order.md structure validation

validate-order-md.sh can be run to mechanically verify the structure of order.md:

bash .agents/skills/takt-task/scripts/validate-order-md.sh

Validation items:

• slug format (YYYYMMDD-HHmmss-xxxxxx）
• ## 目的 Existence and content of the section
• ## 要件 section's - [ ] Checkbox items (one or more)
• ## 受け入れ基準 Items of the section (one or more)
• tasks.yaml の task_dir → order.md Existence cross-check

Additional gate when changing pieces (mandatory)

In this task, .takt/pieces/*.yaml If you have edited , be sure to perform the following before the completion determination.

bash .agents/skills/takt-piece/scripts/validate-takt-files.sh --pieces

Additionally, confirm the following two points:

• When loop monitor is healthy, next が cycle Matches the first node
• loop monitor の {report:...} References are limited to cycle-internal movement artifacts

If either of the above cannot be satisfied, that task is completed do not make it.

Status transition check (when editing an existing task)

Transition	Valid
pending → running	YES
running → completed	YES
running → failed	YES
running → exceeded	YES (when max_movements is exceeded)
running → pr_failed	YES (when PR creation fails)
pending → completed	NO (must go through running)
completed → pending	NO (recreate as a new task)
exceeded → pending	NO (recreate as a new task)
pr_failed → pending	NO (recreate as a new task)