takt-task-builder

TAKT Task Creator

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

Prerequisite takt version: v0.47.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/taskRecordSchemas.ts	Field definitions and validation
TaskExecutionConfig schema	references/takt/src/infra/task/taskExecutionSchemas.ts	Execution configuration field definitions
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	Structural validation of order.md

Important: TaskRecord status transition rules are strictly validated.references/task-schema.md Read to understand the invariants. managed_pr, source / pr_number, resume_point Execution settings such as should also be treated with references/task-schema.md as the source of truth.

Workflow

Step 1: Requirements elicitation

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

1. Task content: What the task executes
2. Workflow: The workflow 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 it is needed
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 taken at clone time)
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 tasks cannot be worked on unless the preceding task is completed first."

Serial factor	Example	Countermeasure
Schema change	DB migration	Integrate into preceding task
Common type definition	Creating a new shared interface / struct	Execute the type definition task first
Config file change	CI/CD, build settings	Integrate into preceding task
API specification design	OpenAPI schema	Execute the specification design first

Interview question: "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	Conflict risk	Recommended countermeasure
Same source file	High	Integrate the tasks
Same config file	High	Integrate the tasks
Same test file	Medium	Consider integration
Different files in the same package	Low	Parallelizable (but be careful about adding imports)
Completely different modules	None	Safely parallelizable

Principle: "If two tasks may modify the same file, integrate 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 a snapshot taken at clone time.

Consistency factor	β impact	Countermeasure
Adding a field 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 about index file conflicts
Type references between independent modules	Low	Parallelizable

e) Decision table for task splitting/integration

#	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	Integrate	1
3	API definition + its implementation	Yes	Yes	Integrate	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 modified	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, split takt run into multiple runs.

g) Parallel pattern collection

Pattern A: Fully parallel (independent modules)

tasks:
  - name: impl-module-a
    status: pending
    workflow: 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
    workflow: 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
    workflow: 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 run in parallel.

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

Tasks with dependencies are integrated into one. The tasks.yaml entries are the same as the minimal configuration in Step 4. Describe both the schema change and the implementation in order.md.

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

Stage 1: Common foundation

tasks:
  - name: define-shared-types
    status: pending
    workflow: 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 → after PR merge, add Stage 2 tasks:

tasks:
  - name: impl-consumer-x
    status: pending
    workflow: 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
    workflow: 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 run in parallel.

Step 3: Creating task directories

Recommended format: task_dir(order.md separation 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 not needed in 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
    workflow: 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
    workflow: 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
    workflow: default
    content: >-
      ログイン画面で認証エラーが発生する問題を修正する。
      原因: セッショントークンの有効期限チェックが不正。
    created_at: "2026-02-23T14:30:00.000Z"
    started_at: null
    completed_at: null

Exclusive constraint on content sources

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 tasks (for details, see references/task-schema.md ):

• task_dir が .takt/tasks/<slug> format
• task_dir When specifying order.md exists
• status: pending で started_at: null, completed_at: null か
• created_at is in ISO8601 format
• content, content_file, task_dir only one of the following is specified
• workflow name matches an existing workflow (built-in or custom)
• Existing task's tasks.yaml Whether the 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 runs the shared type definition task before the consuming task (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

By running the scripts/validate-order-md.sh bundled with this skill, the structure of order.md can be mechanically verified. Run it with a path according to the skill's installation location (.agents/skills/, .claude/skills/, .codex/skills/ , etc.):

bash <このスキルのディレクトリ>/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 in the section (one or more)
• tasks.yaml の task_dir → order.md Existence cross-check

Additional gate when changing the workflow (required)

In this task, .takt/workflows/*.yaml If you have edited takt-workflow-builder , run the validation script of the

bash <takt-workflow-builderスキルのディレクトリ>/scripts/validate-takt-files.sh --workflows

Additionally, confirm the following two points:

• When loop monitor is healthy, next が cycle matches the first node
• loop monitor の {report:...} References are limited to step outputs within the cycle

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

Status transition check (when editing an existing task)

Transition	Valid
pending → running	YES
running → completed	YES
running → failed	YES
running → exceeded	YES (when max_steps 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)