takt 0.2.3 → 0.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (185) hide show
  1. package/README.md +186 -162
  2. package/dist/agents/runner.d.ts +2 -4
  3. package/dist/agents/runner.d.ts.map +1 -1
  4. package/dist/agents/runner.js +6 -35
  5. package/dist/agents/runner.js.map +1 -1
  6. package/dist/claude/client.d.ts +31 -6
  7. package/dist/claude/client.d.ts.map +1 -1
  8. package/dist/claude/client.js +78 -30
  9. package/dist/claude/client.js.map +1 -1
  10. package/dist/claude/executor.d.ts.map +1 -1
  11. package/dist/claude/executor.js +17 -8
  12. package/dist/claude/executor.js.map +1 -1
  13. package/dist/claude/index.d.ts +1 -1
  14. package/dist/claude/index.d.ts.map +1 -1
  15. package/dist/claude/index.js +1 -1
  16. package/dist/claude/index.js.map +1 -1
  17. package/dist/cli.d.ts +5 -5
  18. package/dist/cli.d.ts.map +1 -1
  19. package/dist/cli.js +160 -119
  20. package/dist/cli.js.map +1 -1
  21. package/dist/codex/client.d.ts +0 -1
  22. package/dist/codex/client.d.ts.map +1 -1
  23. package/dist/codex/client.js +3 -6
  24. package/dist/codex/client.js.map +1 -1
  25. package/dist/commands/addTask.d.ts +15 -8
  26. package/dist/commands/addTask.d.ts.map +1 -1
  27. package/dist/commands/addTask.js +63 -26
  28. package/dist/commands/addTask.js.map +1 -1
  29. package/dist/commands/eject.d.ts +13 -0
  30. package/dist/commands/eject.d.ts.map +1 -0
  31. package/dist/commands/eject.js +105 -0
  32. package/dist/commands/eject.js.map +1 -0
  33. package/dist/commands/index.d.ts +2 -2
  34. package/dist/commands/index.d.ts.map +1 -1
  35. package/dist/commands/index.js +2 -2
  36. package/dist/commands/index.js.map +1 -1
  37. package/dist/commands/interactive.d.ts +28 -0
  38. package/dist/commands/interactive.d.ts.map +1 -0
  39. package/dist/commands/interactive.js +186 -0
  40. package/dist/commands/interactive.js.map +1 -0
  41. package/dist/commands/taskExecution.js +2 -2
  42. package/dist/commands/taskExecution.js.map +1 -1
  43. package/dist/commands/workflowExecution.d.ts.map +1 -1
  44. package/dist/commands/workflowExecution.js +85 -18
  45. package/dist/commands/workflowExecution.js.map +1 -1
  46. package/dist/config/agentLoader.d.ts +3 -1
  47. package/dist/config/agentLoader.d.ts.map +1 -1
  48. package/dist/config/agentLoader.js +17 -24
  49. package/dist/config/agentLoader.js.map +1 -1
  50. package/dist/config/globalConfig.d.ts +2 -0
  51. package/dist/config/globalConfig.d.ts.map +1 -1
  52. package/dist/config/globalConfig.js +14 -0
  53. package/dist/config/globalConfig.js.map +1 -1
  54. package/dist/config/initialization.d.ts +7 -5
  55. package/dist/config/initialization.d.ts.map +1 -1
  56. package/dist/config/initialization.js +23 -21
  57. package/dist/config/initialization.js.map +1 -1
  58. package/dist/config/paths.d.ts +5 -0
  59. package/dist/config/paths.d.ts.map +1 -1
  60. package/dist/config/paths.js +9 -0
  61. package/dist/config/paths.js.map +1 -1
  62. package/dist/config/workflowLoader.d.ts +6 -4
  63. package/dist/config/workflowLoader.d.ts.map +1 -1
  64. package/dist/config/workflowLoader.js +190 -35
  65. package/dist/config/workflowLoader.js.map +1 -1
  66. package/dist/github/issue.d.ts +72 -0
  67. package/dist/github/issue.d.ts.map +1 -0
  68. package/dist/github/issue.js +143 -0
  69. package/dist/github/issue.js.map +1 -0
  70. package/dist/models/index.d.ts +1 -1
  71. package/dist/models/index.d.ts.map +1 -1
  72. package/dist/models/index.js.map +1 -1
  73. package/dist/models/schemas.d.ts +164 -90
  74. package/dist/models/schemas.d.ts.map +1 -1
  75. package/dist/models/schemas.js +77 -51
  76. package/dist/models/schemas.js.map +1 -1
  77. package/dist/models/types.d.ts +51 -20
  78. package/dist/models/types.d.ts.map +1 -1
  79. package/dist/prompt/index.d.ts +0 -7
  80. package/dist/prompt/index.d.ts.map +1 -1
  81. package/dist/prompt/index.js +0 -11
  82. package/dist/prompt/index.js.map +1 -1
  83. package/dist/providers/claude.js +2 -2
  84. package/dist/providers/claude.js.map +1 -1
  85. package/dist/providers/codex.d.ts.map +1 -1
  86. package/dist/providers/codex.js +0 -2
  87. package/dist/providers/codex.js.map +1 -1
  88. package/dist/providers/index.d.ts +2 -1
  89. package/dist/providers/index.d.ts.map +1 -1
  90. package/dist/providers/index.js.map +1 -1
  91. package/dist/resources/index.d.ts +3 -22
  92. package/dist/resources/index.d.ts.map +1 -1
  93. package/dist/resources/index.js +3 -73
  94. package/dist/resources/index.js.map +1 -1
  95. package/dist/task/display.js +1 -1
  96. package/dist/task/display.js.map +1 -1
  97. package/dist/utils/session.d.ts +74 -10
  98. package/dist/utils/session.d.ts.map +1 -1
  99. package/dist/utils/session.js +101 -51
  100. package/dist/utils/session.js.map +1 -1
  101. package/dist/workflow/engine.d.ts +34 -1
  102. package/dist/workflow/engine.d.ts.map +1 -1
  103. package/dist/workflow/engine.js +228 -36
  104. package/dist/workflow/engine.js.map +1 -1
  105. package/dist/workflow/index.d.ts +1 -1
  106. package/dist/workflow/index.d.ts.map +1 -1
  107. package/dist/workflow/index.js +1 -1
  108. package/dist/workflow/index.js.map +1 -1
  109. package/dist/workflow/instruction-builder.d.ts +87 -18
  110. package/dist/workflow/instruction-builder.d.ts.map +1 -1
  111. package/dist/workflow/instruction-builder.js +404 -57
  112. package/dist/workflow/instruction-builder.js.map +1 -1
  113. package/dist/workflow/parallel-logger.d.ts +76 -0
  114. package/dist/workflow/parallel-logger.d.ts.map +1 -0
  115. package/dist/workflow/parallel-logger.js +173 -0
  116. package/dist/workflow/parallel-logger.js.map +1 -0
  117. package/dist/workflow/phase-runner.d.ts +40 -0
  118. package/dist/workflow/phase-runner.d.ts.map +1 -0
  119. package/dist/workflow/phase-runner.js +69 -0
  120. package/dist/workflow/phase-runner.js.map +1 -0
  121. package/dist/workflow/rule-evaluator.d.ts +64 -0
  122. package/dist/workflow/rule-evaluator.d.ts.map +1 -0
  123. package/dist/workflow/rule-evaluator.js +178 -0
  124. package/dist/workflow/rule-evaluator.js.map +1 -0
  125. package/dist/workflow/rule-utils.d.ts +13 -0
  126. package/dist/workflow/rule-utils.d.ts.map +1 -0
  127. package/dist/workflow/rule-utils.js +17 -0
  128. package/dist/workflow/rule-utils.js.map +1 -0
  129. package/dist/workflow/transitions.d.ts +5 -13
  130. package/dist/workflow/transitions.d.ts.map +1 -1
  131. package/dist/workflow/transitions.js +8 -78
  132. package/dist/workflow/transitions.js.map +1 -1
  133. package/dist/workflow/types.d.ts +2 -1
  134. package/dist/workflow/types.d.ts.map +1 -1
  135. package/package.json +1 -1
  136. package/resources/global/en/agents/default/ai-antipattern-reviewer.md +84 -15
  137. package/resources/global/en/agents/default/{architect.md → architecture-reviewer.md} +144 -44
  138. package/resources/global/en/agents/default/coder.md +4 -4
  139. package/resources/global/en/agents/default/planner.md +16 -9
  140. package/resources/global/en/agents/default/{security.md → security-reviewer.md} +23 -5
  141. package/resources/global/en/agents/default/supervisor.md +22 -2
  142. package/resources/global/en/agents/expert/frontend-reviewer.md +0 -17
  143. package/resources/global/en/agents/expert/qa-reviewer.md +0 -16
  144. package/resources/global/en/agents/expert/security-reviewer.md +0 -16
  145. package/resources/global/en/agents/expert/supervisor.md +2 -0
  146. package/resources/global/en/agents/expert-cqrs/cqrs-es-reviewer.md +0 -17
  147. package/resources/global/en/agents/templates/coder.md +128 -0
  148. package/resources/global/en/agents/templates/planner.md +44 -0
  149. package/resources/global/en/agents/templates/reviewer.md +57 -0
  150. package/resources/global/en/agents/templates/supervisor.md +64 -0
  151. package/resources/global/en/workflows/default.yaml +232 -772
  152. package/resources/global/en/workflows/expert-cqrs.yaml +319 -698
  153. package/resources/global/en/workflows/expert.yaml +348 -723
  154. package/resources/global/en/workflows/magi.yaml +45 -52
  155. package/resources/global/en/workflows/research.yaml +18 -99
  156. package/resources/global/en/workflows/simple.yaml +152 -421
  157. package/resources/global/ja/agents/default/ai-antipattern-reviewer.md +84 -15
  158. package/resources/global/ja/agents/default/{architect.md → architecture-reviewer.md} +148 -48
  159. package/resources/global/ja/agents/default/coder.md +4 -4
  160. package/resources/global/ja/agents/default/planner.md +16 -9
  161. package/resources/global/ja/agents/default/{security.md → security-reviewer.md} +23 -5
  162. package/resources/global/ja/agents/default/supervisor.md +22 -2
  163. package/resources/global/ja/agents/expert/frontend-reviewer.md +0 -18
  164. package/resources/global/ja/agents/expert/qa-reviewer.md +0 -16
  165. package/resources/global/ja/agents/expert/security-reviewer.md +0 -16
  166. package/resources/global/ja/agents/expert/supervisor.md +2 -0
  167. package/resources/global/ja/agents/expert-cqrs/cqrs-es-reviewer.md +0 -18
  168. package/resources/global/ja/agents/templates/coder.md +128 -0
  169. package/resources/global/ja/agents/templates/planner.md +44 -0
  170. package/resources/global/ja/agents/templates/reviewer.md +57 -0
  171. package/resources/global/ja/agents/templates/supervisor.md +64 -0
  172. package/resources/global/ja/workflows/default.yaml +227 -773
  173. package/resources/global/ja/workflows/expert-cqrs.yaml +309 -833
  174. package/resources/global/ja/workflows/expert.yaml +325 -712
  175. package/resources/global/ja/workflows/magi.yaml +45 -52
  176. package/resources/global/ja/workflows/research.yaml +18 -99
  177. package/resources/global/ja/workflows/simple.yaml +145 -415
  178. package/dist/commands/help.d.ts +0 -8
  179. package/dist/commands/help.d.ts.map +0 -1
  180. package/dist/commands/help.js +0 -48
  181. package/dist/commands/help.js.map +0 -1
  182. package/dist/commands/refreshBuiltin.d.ts +0 -11
  183. package/dist/commands/refreshBuiltin.d.ts.map +0 -1
  184. package/dist/commands/refreshBuiltin.js +0 -37
  185. package/dist/commands/refreshBuiltin.js.map +0 -1
package/README.md CHANGED
@@ -11,6 +11,7 @@ TAKT is built with TAKT (dogfooding).
11
11
  ## Requirements
12
12
 
13
13
  - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or Codex must be installed and configured
14
+ - [GitHub CLI](https://cli.github.com/) (`gh`) — required only for `takt "#N"` (GitHub Issue execution)
14
15
 
15
16
  TAKT supports both Claude Code and Codex as providers; you can choose the provider during setup.
16
17
 
@@ -26,20 +27,23 @@ npm install -g takt
26
27
  # Run a task (will prompt for workflow selection and optional isolated clone)
27
28
  takt "Add a login feature"
28
29
 
29
- # Add a task to the queue
30
- takt /add-task "Fix the login bug"
30
+ # Run a GitHub issue as a task
31
+ takt "#6"
32
+
33
+ # Add a task via AI conversation
34
+ takt add
31
35
 
32
36
  # Run all pending tasks
33
- takt /run-tasks
37
+ takt run
34
38
 
35
39
  # Watch for tasks and auto-execute
36
- takt /watch
40
+ takt watch
37
41
 
38
42
  # List task branches (merge or delete)
39
- takt /list-tasks
43
+ takt list
40
44
 
41
45
  # Switch workflow
42
- takt /switch
46
+ takt switch
43
47
  ```
44
48
 
45
49
  ### What happens when you run a task
@@ -75,94 +79,140 @@ Choose `y` to run in a `git clone --shared` isolated environment, keeping your w
75
79
 
76
80
  | Workflow | Best for |
77
81
  |----------|----------|
78
- | `default` | Full development tasks. Used for TAKT's own development. Multi-stage review with fix loops. |
82
+ | `default` | Full development tasks. Used for TAKT's own development. Multi-stage review with parallel architect + security review. |
79
83
  | `simple` | Lightweight tasks like README updates or small fixes. Reviews without fix loops. |
80
- | `expert-review` / `expert-cqrs` | Web development projects. Multi-expert review (CQRS, Frontend, Security, QA). |
84
+ | `expert` / `expert-cqrs` | Web development projects. Sequential multi-expert review with fix loops (`expert`: Architecture, Frontend, Security, QA; `expert-cqrs`: CQRS+ES, Frontend, Security, QA). |
81
85
  | `research` | Research and investigation. Autonomous research without asking questions. |
82
86
  | `magi` | Fun deliberation. Three AI personas analyze and vote (Evangelion-inspired). |
83
87
 
84
88
  ## Commands
85
89
 
86
- | Command | Alias | Description |
87
- |---------|-------|-------------|
88
- | `takt "task"` | | Execute task with current workflow (session auto-continued) |
89
- | `takt /run-tasks` | `/run` | Run all pending tasks from `.takt/tasks/` |
90
- | `takt /watch` | | Watch `.takt/tasks/` and auto-execute tasks (stays resident) |
91
- | `takt /add-task` | `/add` | Add a new task interactively (YAML format, multiline supported) |
92
- | `takt /list-tasks` | `/list` | List task branches (try merge, merge & cleanup, or delete) |
93
- | `takt /switch` | `/sw` | Switch workflow interactively |
94
- | `takt /clear` | | Clear agent conversation sessions |
95
- | `takt /refresh-builtin` | | Update builtin agents/workflows to latest version |
96
- | `takt /config` | | Configure permission mode |
97
- | `takt /help` | | Show help |
90
+ | Command | Description |
91
+ |---------|-------------|
92
+ | `takt "task"` | Execute task with current workflow (session auto-continued) |
93
+ | `takt "#N"` | Execute GitHub issue #N as a task |
94
+ | `takt` | Interactive task input mode |
95
+ | `takt run` | Run all pending tasks from `.takt/tasks/` |
96
+ | `takt watch` | Watch `.takt/tasks/` and auto-execute tasks (stays resident) |
97
+ | `takt add` | Add a new task via AI conversation |
98
+ | `takt list` | List task branches (try merge, merge & cleanup, or delete) |
99
+ | `takt switch` | Switch workflow interactively |
100
+ | `takt clear` | Clear agent conversation sessions |
101
+ | `takt eject` | Copy builtin workflow/agents to `~/.takt/` for customization |
102
+ | `takt config` | Configure permission mode |
103
+ | `takt --help` | Show help |
98
104
 
99
105
  ## Workflows
100
106
 
101
- TAKT uses YAML-based workflow definitions. Place them in:
102
- - `~/.takt/workflows/*.yaml`
107
+ TAKT uses YAML-based workflow definitions with rule-based routing. Builtin workflows are embedded in the package; user workflows in `~/.takt/workflows/` take priority. Use `takt eject` to copy a builtin to `~/.takt/` for customization.
103
108
 
104
109
  ### Example Workflow
105
110
 
106
111
  ```yaml
107
112
  name: default
108
113
  max_iterations: 10
114
+ initial_step: plan
109
115
 
110
116
  steps:
111
117
  - name: plan
112
- agent: planner
113
- provider: claude # Optional: claude or codex
114
- model: opus # Claude: opus/sonnet/haiku, Codex: gpt-5.2-codex/gpt-5.1-codex
118
+ agent: ../agents/default/planner.md
119
+ model: opus
120
+ edit: false
121
+ rules:
122
+ - condition: Plan complete
123
+ next: implement
115
124
  instruction_template: |
116
- {task}
117
- transitions:
118
- - condition: done
119
- next_step: implement
125
+ Analyze the request and create an implementation plan.
120
126
 
121
127
  - name: implement
122
- agent: coder
123
- provider: codex
124
- model: gpt-5.2-codex # Codex model example
128
+ agent: ../agents/default/coder.md
129
+ edit: true
130
+ permission_mode: acceptEdits
131
+ rules:
132
+ - condition: Implementation complete
133
+ next: review
134
+ - condition: Cannot proceed
135
+ next: ABORT
125
136
  instruction_template: |
126
- {task}
127
- transitions:
128
- - condition: done
129
- next_step: review
130
- - condition: blocked
131
- next_step: ABORT
137
+ Implement based on the plan.
132
138
 
133
139
  - name: review
134
- agent: architect
135
- model: sonnet # Model alias (no provider = uses global default)
136
- transitions:
137
- - condition: approved
138
- next_step: COMPLETE
139
- - condition: rejected
140
- next_step: implement
140
+ agent: ../agents/default/architecture-reviewer.md
141
+ edit: false
142
+ rules:
143
+ - condition: Approved
144
+ next: COMPLETE
145
+ - condition: Needs fix
146
+ next: implement
147
+ instruction_template: |
148
+ Review the implementation for architecture and code quality.
149
+ ```
150
+
151
+ ### Parallel Steps
152
+
153
+ Steps can execute sub-steps concurrently with aggregate evaluation:
154
+
155
+ ```yaml
156
+ - name: reviewers
157
+ parallel:
158
+ - name: arch-review
159
+ agent: ../agents/default/architecture-reviewer.md
160
+ rules:
161
+ - condition: approved
162
+ - condition: needs_fix
163
+ instruction_template: |
164
+ Review architecture and code quality.
165
+ - name: security-review
166
+ agent: ../agents/default/security-reviewer.md
167
+ rules:
168
+ - condition: approved
169
+ - condition: needs_fix
170
+ instruction_template: |
171
+ Review for security vulnerabilities.
172
+ rules:
173
+ - condition: all("approved")
174
+ next: supervise
175
+ - condition: any("needs_fix")
176
+ next: fix
141
177
  ```
142
178
 
179
+ - `all("X")`: true if ALL sub-steps matched condition X
180
+ - `any("X")`: true if ANY sub-step matched condition X
181
+ - Sub-step `rules` define possible outcomes; `next` is optional (parent handles routing)
182
+
183
+ ### Rule Condition Types
184
+
185
+ | Type | Syntax | Description |
186
+ |------|--------|-------------|
187
+ | Tag-based | `"condition text"` | Agent outputs `[STEP:N]` tag, matched by index |
188
+ | AI judge | `ai("condition text")` | AI evaluates the condition against agent output |
189
+ | Aggregate | `all("X")` / `any("X")` | Aggregates parallel sub-step results |
190
+
143
191
  ## Built-in Workflows
144
192
 
145
193
  TAKT ships with several built-in workflows:
146
194
 
147
195
  | Workflow | Description |
148
196
  |----------|-------------|
149
- | `default` | Full development workflow: plan → implement → architect review → AI review security review → supervisor approval. Includes fix loops for each review stage. |
197
+ | `default` | Full development workflow: plan → implement → AI review → parallel reviewers (architect + security) → supervisor approval. Includes fix loops for each review stage. |
150
198
  | `simple` | Simplified version of default: plan → implement → architect review → AI review → supervisor. No intermediate fix steps. |
151
199
  | `research` | Research workflow: planner → digger → supervisor. Autonomously researches topics without asking questions. |
152
- | `expert-review` | Comprehensive review with domain experts: CQRS+ES, Frontend, AI, Security, QA reviews with fix loops. |
153
- | `expert-cqrs` | Expert review focused on CQRS+ES, Frontend, AI, Security, and QA. Plan implement → multi-expert review → supervise. |
200
+ | `expert` | Sequential review with domain experts: Architecture, Frontend, Security, QA reviews with fix loops. |
201
+ | `expert-cqrs` | Sequential review with domain experts: CQRS+ES, Frontend, Security, QA reviews with fix loops. |
154
202
  | `magi` | Deliberation system inspired by Evangelion. Three AI personas (MELCHIOR, BALTHASAR, CASPER) analyze and vote. |
155
203
 
156
- Switch between workflows with `takt /switch`.
204
+ Switch between workflows with `takt switch`.
157
205
 
158
206
  ## Built-in Agents
159
207
 
160
- - **coder** - Implements features and fixes bugs
161
- - **architect** - Reviews code and provides feedback
162
- - **supervisor** - Final verification and approval
163
- - **planner** - Task analysis and implementation planning
164
- - **ai-reviewer** - AI-generated code quality review
165
- - **security** - Security vulnerability assessment
208
+ | Agent | Description |
209
+ |-------|-------------|
210
+ | **planner** | Task analysis, spec investigation, and implementation planning |
211
+ | **coder** | Implements features and fixes bugs |
212
+ | **ai-antipattern-reviewer** | Reviews for AI-specific anti-patterns (hallucinated APIs, incorrect assumptions, scope creep) |
213
+ | **architecture-reviewer** | Reviews architecture and code quality, verifies spec compliance |
214
+ | **security-reviewer** | Security vulnerability assessment |
215
+ | **supervisor** | Final verification, validation, and approval |
166
216
 
167
217
  ## Custom Agents
168
218
 
@@ -175,64 +225,54 @@ agents:
175
225
  allowed_tools: [Read, Glob, Grep]
176
226
  provider: claude # Optional: claude or codex
177
227
  model: opus # Claude: opus/sonnet/haiku or full name (claude-opus-4-5-20251101)
178
- status_patterns:
179
- approved: "\\[APPROVE\\]"
180
- rejected: "\\[REJECT\\]"
181
-
182
- - name: my-codex-agent
183
- prompt_file: .takt/prompts/analyzer.md
184
- provider: codex
185
- model: gpt-5.2-codex # Codex: gpt-5.2-codex, gpt-5.1-codex, etc.
186
228
  ```
187
229
 
188
- ## Model Selection
230
+ Or create agent prompt files as Markdown:
189
231
 
190
- ### Claude Models
232
+ ```markdown
233
+ # ~/.takt/agents/my-agents/reviewer.md
191
234
 
192
- You can specify models using either **aliases** or **full model names**:
235
+ You are a code reviewer focused on security.
193
236
 
194
- **Aliases** (recommended for simplicity):
195
- - `opus` - Claude Opus 4.5 (highest reasoning capability)
196
- - `sonnet` - Claude Sonnet 4.5 (balanced, best for most tasks)
197
- - `haiku` - Claude Haiku 4.5 (fast and efficient)
198
- - `opusplan` - Opus for planning, Sonnet for execution
199
- - `default` - Recommended model for your account type
237
+ ## Your Role
238
+ - Check for security vulnerabilities
239
+ - Verify input validation
240
+ - Review authentication logic
241
+ ```
242
+
243
+ ## Model Selection
200
244
 
201
- **Full model names** (recommended for production):
202
- - `claude-opus-4-5-20251101`
203
- - `claude-sonnet-4-5-20250929`
204
- - `claude-haiku-4-5-20250101`
245
+ The `model` field in workflow steps, agent configs, and global config is passed directly to the provider (Claude Code CLI or Codex SDK). TAKT does not resolve model aliases — the provider handles that.
205
246
 
206
- ### Codex Models
247
+ ### Claude Code
207
248
 
208
- Available Codex models:
209
- - `gpt-5.2-codex` - Latest agentic coding model (default)
210
- - `gpt-5.1-codex` - Previous generation
211
- - `gpt-5.1-codex-max` - Optimized for long-running tasks
212
- - `gpt-5.1-codex-mini` - Smaller, cost-effective version
213
- - `codex-1` - Specialized model aligned with coding preferences
249
+ Claude Code supports aliases (`opus`, `sonnet`, `haiku`, `opusplan`, `default`) and full model names (e.g., `claude-sonnet-4-5-20250929`). See [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code) for available models.
250
+
251
+ ### Codex
252
+
253
+ The model string is passed to the Codex SDK. Defaults to `codex` if not specified. See Codex documentation for available models.
214
254
 
215
255
  ## Project Structure
216
256
 
217
257
  ```
218
258
  ~/.takt/
219
259
  ├── config.yaml # Global config (provider, model, workflows, etc.)
220
- ├── workflows/ # Workflow definitions
221
- └── agents/ # Agent prompt files
260
+ ├── workflows/ # User workflow definitions (override builtins)
261
+ └── agents/ # User agent prompt files
222
262
 
223
263
  .takt/ # Project-level config
224
264
  ├── agents.yaml # Custom agent definitions
225
265
  ├── tasks/ # Pending task files (.yaml, .md)
226
266
  ├── completed/ # Completed tasks with reports
227
- ├── worktree-meta/ # Metadata for task branches
228
- ├── worktree-sessions/ # Per-clone agent session storage
229
267
  ├── reports/ # Execution reports (auto-generated)
230
- └── logs/ # Session logs (incremental)
268
+ └── logs/ # Session logs in NDJSON format
231
269
  ├── latest.json # Pointer to current/latest session
232
270
  ├── previous.json # Pointer to previous session
233
- └── {sessionId}.json # Full session log per workflow run
271
+ └── {sessionId}.jsonl # NDJSON session log per workflow run
234
272
  ```
235
273
 
274
+ Builtin resources are embedded in the npm package (`dist/resources/`). User files in `~/.takt/` take priority.
275
+
236
276
  ### Global Configuration
237
277
 
238
278
  Configure default provider and model in `~/.takt/config.yaml`:
@@ -268,81 +308,72 @@ This interactive flow ensures each task runs with the right workflow and isolati
268
308
 
269
309
  ### Adding Custom Workflows
270
310
 
271
- Create your own workflow by adding YAML files to `~/.takt/workflows/`:
311
+ Create your own workflow by adding YAML files to `~/.takt/workflows/`, or use `/eject` to customize a builtin:
312
+
313
+ ```bash
314
+ # Copy the default workflow to ~/.takt/workflows/ for editing
315
+ takt eject default
316
+ ```
272
317
 
273
318
  ```yaml
274
319
  # ~/.takt/workflows/my-workflow.yaml
275
320
  name: my-workflow
276
321
  description: My custom workflow
277
-
278
322
  max_iterations: 5
323
+ initial_step: analyze
279
324
 
280
325
  steps:
281
326
  - name: analyze
282
327
  agent: ~/.takt/agents/my-agents/analyzer.md
328
+ edit: false
329
+ rules:
330
+ - condition: Analysis complete
331
+ next: implement
283
332
  instruction_template: |
284
- Analyze this request: {task}
285
- transitions:
286
- - condition: done
287
- next_step: implement
333
+ Analyze this request thoroughly.
288
334
 
289
335
  - name: implement
290
336
  agent: ~/.takt/agents/default/coder.md
291
- instruction_template: |
292
- Implement based on the analysis: {previous_response}
337
+ edit: true
338
+ permission_mode: acceptEdits
293
339
  pass_previous_response: true
294
- transitions:
295
- - condition: done
296
- next_step: COMPLETE
340
+ rules:
341
+ - condition: Done
342
+ next: COMPLETE
343
+ instruction_template: |
344
+ Implement based on the analysis.
297
345
  ```
298
346
 
347
+ > **Note**: `{task}`, `{previous_response}`, and `{user_inputs}` are auto-injected into instructions. You only need explicit placeholders if you want to control their position in the template.
348
+
299
349
  ### Specifying Agents by Path
300
350
 
301
351
  Agents are specified using file paths in workflow definitions:
302
352
 
303
353
  ```yaml
304
- # Use built-in agents
305
- agent: ~/.takt/agents/default/coder.md
306
- agent: ~/.takt/agents/magi/melchior.md
354
+ # Relative to workflow file directory
355
+ agent: ../agents/default/coder.md
307
356
 
308
- # Use project-local agents
309
- agent: ./.takt/agents/my-reviewer.md
357
+ # Home directory
358
+ agent: ~/.takt/agents/default/coder.md
310
359
 
311
- # Use absolute paths
360
+ # Absolute paths
312
361
  agent: /path/to/custom/agent.md
313
362
  ```
314
363
 
315
- Create custom agent prompts as Markdown files:
316
-
317
- ```markdown
318
- # ~/.takt/agents/my-agents/reviewer.md
319
-
320
- You are a code reviewer focused on security.
321
-
322
- ## Your Role
323
- - Check for security vulnerabilities
324
- - Verify input validation
325
- - Review authentication logic
326
-
327
- ## Output Format
328
- - [REVIEWER:APPROVE] if code is secure
329
- - [REVIEWER:REJECT] if issues found (list them)
330
- ```
331
-
332
364
  ### Task Management
333
365
 
334
366
  TAKT supports batch task processing through task files in `.takt/tasks/`. Both `.yaml`/`.yml` and `.md` file formats are supported.
335
367
 
336
- #### Adding Tasks with `/add-task`
368
+ #### Adding Tasks with `takt add`
337
369
 
338
370
  ```bash
339
- # Quick add (no isolation)
340
- takt /add-task "Add authentication feature"
341
-
342
- # Interactive mode (prompts for isolation, branch, workflow options)
343
- takt /add-task
371
+ # Start AI conversation to define and add a task
372
+ takt add
344
373
  ```
345
374
 
375
+ The `takt add` command starts an AI conversation where you discuss and refine your task requirements. After confirming with `/go`, the AI summarizes the conversation and creates a YAML task file with optional worktree/branch/workflow settings.
376
+
346
377
  #### Task File Formats
347
378
 
348
379
  **YAML format** (recommended, supports worktree/branch/workflow options):
@@ -379,12 +410,12 @@ YAML task files can specify `worktree` to run each task in an isolated `git clon
379
410
 
380
411
  > **Note**: The YAML field is named `worktree` for backward compatibility. Internally, `git clone --shared` is used instead of `git worktree` because git worktrees have a `.git` file with `gitdir:` that points back to the main repository, causing Claude Code to recognize the main repo as the project root. Shared clones have an independent `.git` directory that avoids this issue.
381
412
 
382
- Clones are ephemeral. When a task completes successfully, TAKT automatically commits all changes and pushes the branch to the main repository, then deletes the clone. Use `takt /list-tasks` to list, try-merge, or delete task branches.
413
+ Clones are ephemeral. When a task completes successfully, TAKT automatically commits all changes and pushes the branch to the main repository, then deletes the clone. Use `takt list` to list, try-merge, or delete task branches.
383
414
 
384
415
  #### Running Tasks with `/run-tasks`
385
416
 
386
417
  ```bash
387
- takt /run-tasks
418
+ takt run
388
419
  ```
389
420
 
390
421
  - Tasks are executed in alphabetical order (use prefixes like `001-`, `002-` for ordering)
@@ -394,7 +425,7 @@ takt /run-tasks
394
425
  #### Watching Tasks with `/watch`
395
426
 
396
427
  ```bash
397
- takt /watch
428
+ takt watch
398
429
  ```
399
430
 
400
431
  Watch mode polls `.takt/tasks/` for new task files and auto-executes them as they appear. The process stays resident until `Ctrl+C`. This is useful for:
@@ -405,7 +436,7 @@ Watch mode polls `.takt/tasks/` for new task files and auto-executes them as the
405
436
  #### Listing Task Branches with `/list-tasks`
406
437
 
407
438
  ```bash
408
- takt /list-tasks
439
+ takt list
409
440
  ```
410
441
 
411
442
  Lists all `takt/`-prefixed branches with file change counts. For each branch you can:
@@ -416,11 +447,13 @@ Lists all `takt/`-prefixed branches with file change counts. For each branch you
416
447
 
417
448
  ### Session Logs
418
449
 
419
- TAKT writes session logs incrementally to `.takt/logs/`. Logs are saved at workflow start, after each step, and at workflow end — so even if the process crashes mid-execution, partial logs are preserved.
450
+ TAKT writes session logs in NDJSON (`.jsonl`) format to `.takt/logs/`. Each record is appended atomically, so even if the process crashes mid-execution, partial logs are preserved and logs can be tailed in real-time with `tail -f`.
420
451
 
421
452
  - `.takt/logs/latest.json` - Pointer to the current (or most recent) session
422
453
  - `.takt/logs/previous.json` - Pointer to the previous session
423
- - `.takt/logs/{sessionId}.json` - Full session log with step history
454
+ - `.takt/logs/{sessionId}.jsonl` - NDJSON session log with step history
455
+
456
+ Record types: `workflow_start`, `step_start`, `step_complete`, `workflow_complete`, `workflow_abort`.
424
457
 
425
458
  Agents can read `previous.json` to pick up context from a prior run. Session continuity is automatic — simply run `takt "task"` to continue where the previous session left off.
426
459
 
@@ -430,58 +463,49 @@ Available variables in `instruction_template`:
430
463
 
431
464
  | Variable | Description |
432
465
  |----------|-------------|
433
- | `{task}` | Original user request |
466
+ | `{task}` | Original user request (auto-injected if not in template) |
434
467
  | `{iteration}` | Workflow-wide turn count (total steps executed) |
435
468
  | `{max_iterations}` | Maximum iterations allowed |
436
469
  | `{step_iteration}` | Per-step iteration count (how many times THIS step has run) |
437
- | `{previous_response}` | Previous step's output (requires `pass_previous_response: true`) |
438
- | `{user_inputs}` | Additional user inputs during workflow |
439
- | `{git_diff}` | Current git diff (uncommitted changes) |
440
- | `{report_dir}` | Report directory name (e.g., `20250126-143052-task-summary`) |
470
+ | `{previous_response}` | Previous step's output (auto-injected if not in template) |
471
+ | `{user_inputs}` | Additional user inputs during workflow (auto-injected if not in template) |
472
+ | `{report_dir}` | Report directory path (e.g., `.takt/reports/20250126-143052-task-summary`) |
473
+ | `{report:filename}` | Resolves to `{report_dir}/filename` (e.g., `{report:00-plan.md}`) |
441
474
 
442
475
  ### Designing Workflows
443
476
 
444
- Each workflow step requires three key elements:
477
+ Each workflow step requires:
445
478
 
446
479
  **1. Agent** - A Markdown file containing the system prompt:
447
480
 
448
481
  ```yaml
449
- agent: ~/.takt/agents/default/coder.md # Path to agent prompt file
450
- agent_name: coder # Display name (optional)
451
- ```
452
-
453
- **2. Status Rules** - Define how the agent signals completion. Agents output status markers like `[CODER:DONE]` or `[ARCHITECT:REJECT]` that TAKT detects to drive transitions:
454
-
455
- ```yaml
456
- status_rules_prompt: |
457
- Your final output MUST include a status tag:
458
- - `[CODER:DONE]` if implementation is complete
459
- - `[CODER:BLOCKED]` if you cannot proceed
482
+ agent: ../agents/default/coder.md # Path to agent prompt file
483
+ agent_name: coder # Display name (optional)
460
484
  ```
461
485
 
462
- **3. Transitions** - Route to the next step based on status:
486
+ **2. Rules** - Define how the step routes to the next step. The instruction builder auto-injects status output rules so agents know what tags to output:
463
487
 
464
488
  ```yaml
465
- transitions:
466
- - condition: done # Maps to status tag DONE
467
- next_step: review # Go to review step
468
- - condition: blocked # Maps to status tag BLOCKED
469
- next_step: ABORT # End workflow with failure
489
+ rules:
490
+ - condition: "Implementation complete"
491
+ next: review
492
+ - condition: "Cannot proceed"
493
+ next: ABORT
470
494
  ```
471
495
 
472
- Available transition conditions: `done`, `blocked`, `approved`, `rejected`, `improve`, `answer`, `always`.
473
- Special next_step values: `COMPLETE` (success), `ABORT` (failure).
496
+ Special `next` values: `COMPLETE` (success), `ABORT` (failure).
474
497
 
475
- **Step options:**
498
+ **3. Step options:**
476
499
 
477
500
  | Option | Default | Description |
478
501
  |--------|---------|-------------|
502
+ | `edit` | - | Whether the step can edit project files (`true`/`false`) |
479
503
  | `pass_previous_response` | `true` | Pass previous step's output to `{previous_response}` |
480
- | `on_no_status` | - | Behavior when no status is detected: `complete`, `continue`, `stay` |
481
504
  | `allowed_tools` | - | List of tools the agent can use (Read, Glob, Grep, Edit, Write, Bash, etc.) |
482
505
  | `provider` | - | Override provider for this step (`claude` or `codex`) |
483
506
  | `model` | - | Override model for this step |
484
507
  | `permission_mode` | `default` | Permission mode: `default`, `acceptEdits`, or `bypassPermissions` |
508
+ | `report` | - | Report file configuration (name, format) for auto-generated reports |
485
509
 
486
510
  ## API Usage
487
511
 
@@ -14,8 +14,8 @@ export interface RunAgentOptions {
14
14
  agentPath?: string;
15
15
  /** Allowed tools for this agent run */
16
16
  allowedTools?: string[];
17
- /** Status output rules to inject into system prompt */
18
- statusRulesPrompt?: string;
17
+ /** Maximum number of agentic turns */
18
+ maxTurns?: number;
19
19
  /** Permission mode for tool execution (from workflow step) */
20
20
  permissionMode?: PermissionMode;
21
21
  onStream?: StreamCallback;
@@ -24,8 +24,6 @@ export interface RunAgentOptions {
24
24
  /** Bypass all permission checks (sacrifice-my-pc mode) */
25
25
  bypassPermissions?: boolean;
26
26
  }
27
- /** Get git diff for review context */
28
- export declare function getGitDiff(cwd: string): string;
29
27
  /** Run a custom agent */
30
28
  export declare function runCustomAgent(agentConfig: CustomAgentConfig, task: string, options: RunAgentOptions): Promise<AgentResponse>;
31
29
  /** Run an agent by name or path */
@@ -1 +1 @@
1
- {"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/agents/runner.ts"],"names":[],"mappings":"AAAA;;GAEG;AAUH,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,iBAAiB,EAAE,KAAK,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAKhH,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAK3F,YAAY,EAAE,cAAc,EAAE,CAAC;AAE/B,wCAAwC;AACxC,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;IACvC,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,uDAAuD;IACvD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,8DAA8D;IAC9D,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,mBAAmB,CAAC,EAAE,iBAAiB,CAAC;IACxC,iBAAiB,CAAC,EAAE,sBAAsB,CAAC;IAC3C,0DAA0D;IAC1D,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AA6BD,sCAAsC;AACtC,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAoB9C;AAED,yBAAyB;AACzB,wBAAsB,cAAc,CAClC,WAAW,EAAE,iBAAiB,EAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,aAAa,CAAC,CA4DxB;AAqCD,mCAAmC;AACnC,wBAAsB,QAAQ,CAC5B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,aAAa,CAAC,CAoDxB"}
1
+ {"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/agents/runner.ts"],"names":[],"mappings":"AAAA;;GAEG;AASH,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,iBAAiB,EAAE,KAAK,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAKhH,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAK3F,YAAY,EAAE,cAAc,EAAE,CAAC;AAE/B,wCAAwC;AACxC,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;IACvC,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,mBAAmB,CAAC,EAAE,iBAAiB,CAAC;IACxC,iBAAiB,CAAC,EAAE,sBAAsB,CAAC;IAC3C,0DAA0D;IAC1D,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AA8BD,yBAAyB;AACzB,wBAAsB,cAAc,CAClC,WAAW,EAAE,iBAAiB,EAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,aAAa,CAAC,CAyDxB;AAqCD,mCAAmC;AACnC,wBAAsB,QAAQ,CAC5B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,aAAa,CAAC,CAgDxB"}