takt 0.2.2 → 0.3.0

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 (210) hide show
  1. package/README.md +223 -166
  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/index.d.ts +1 -1
  11. package/dist/claude/index.d.ts.map +1 -1
  12. package/dist/claude/index.js +1 -1
  13. package/dist/claude/index.js.map +1 -1
  14. package/dist/cli.d.ts +4 -3
  15. package/dist/cli.d.ts.map +1 -1
  16. package/dist/cli.js +41 -20
  17. package/dist/cli.js.map +1 -1
  18. package/dist/codex/client.d.ts +0 -1
  19. package/dist/codex/client.d.ts.map +1 -1
  20. package/dist/codex/client.js +3 -6
  21. package/dist/codex/client.js.map +1 -1
  22. package/dist/commands/addTask.d.ts.map +1 -1
  23. package/dist/commands/addTask.js +23 -7
  24. package/dist/commands/addTask.js.map +1 -1
  25. package/dist/commands/eject.d.ts +13 -0
  26. package/dist/commands/eject.d.ts.map +1 -0
  27. package/dist/commands/eject.js +105 -0
  28. package/dist/commands/eject.js.map +1 -0
  29. package/dist/commands/help.d.ts.map +1 -1
  30. package/dist/commands/help.js +12 -5
  31. package/dist/commands/help.js.map +1 -1
  32. package/dist/commands/index.d.ts +2 -1
  33. package/dist/commands/index.d.ts.map +1 -1
  34. package/dist/commands/index.js +2 -1
  35. package/dist/commands/index.js.map +1 -1
  36. package/dist/commands/listTasks.d.ts +45 -0
  37. package/dist/commands/listTasks.d.ts.map +1 -0
  38. package/dist/commands/{reviewTasks.js → listTasks.js} +93 -73
  39. package/dist/commands/listTasks.js.map +1 -0
  40. package/dist/commands/refreshBuiltin.d.ts +4 -4
  41. package/dist/commands/refreshBuiltin.d.ts.map +1 -1
  42. package/dist/commands/refreshBuiltin.js +13 -29
  43. package/dist/commands/refreshBuiltin.js.map +1 -1
  44. package/dist/commands/taskExecution.d.ts +7 -5
  45. package/dist/commands/taskExecution.d.ts.map +1 -1
  46. package/dist/commands/taskExecution.js +21 -14
  47. package/dist/commands/taskExecution.js.map +1 -1
  48. package/dist/commands/workflowExecution.d.ts.map +1 -1
  49. package/dist/commands/workflowExecution.js +88 -21
  50. package/dist/commands/workflowExecution.js.map +1 -1
  51. package/dist/config/agentLoader.d.ts +3 -1
  52. package/dist/config/agentLoader.d.ts.map +1 -1
  53. package/dist/config/agentLoader.js +17 -24
  54. package/dist/config/agentLoader.js.map +1 -1
  55. package/dist/config/globalConfig.d.ts +2 -0
  56. package/dist/config/globalConfig.d.ts.map +1 -1
  57. package/dist/config/globalConfig.js +18 -0
  58. package/dist/config/globalConfig.js.map +1 -1
  59. package/dist/config/initialization.d.ts +7 -5
  60. package/dist/config/initialization.d.ts.map +1 -1
  61. package/dist/config/initialization.js +23 -21
  62. package/dist/config/initialization.js.map +1 -1
  63. package/dist/config/paths.d.ts +5 -0
  64. package/dist/config/paths.d.ts.map +1 -1
  65. package/dist/config/paths.js +9 -0
  66. package/dist/config/paths.js.map +1 -1
  67. package/dist/config/workflowLoader.d.ts +6 -4
  68. package/dist/config/workflowLoader.d.ts.map +1 -1
  69. package/dist/config/workflowLoader.js +190 -35
  70. package/dist/config/workflowLoader.js.map +1 -1
  71. package/dist/github/issue.d.ts +72 -0
  72. package/dist/github/issue.d.ts.map +1 -0
  73. package/dist/github/issue.js +143 -0
  74. package/dist/github/issue.js.map +1 -0
  75. package/dist/models/index.d.ts +1 -1
  76. package/dist/models/index.d.ts.map +1 -1
  77. package/dist/models/index.js.map +1 -1
  78. package/dist/models/schemas.d.ts +165 -90
  79. package/dist/models/schemas.d.ts.map +1 -1
  80. package/dist/models/schemas.js +79 -51
  81. package/dist/models/schemas.js.map +1 -1
  82. package/dist/models/types.d.ts +53 -20
  83. package/dist/models/types.d.ts.map +1 -1
  84. package/dist/providers/claude.js +2 -2
  85. package/dist/providers/claude.js.map +1 -1
  86. package/dist/providers/codex.d.ts.map +1 -1
  87. package/dist/providers/codex.js +0 -2
  88. package/dist/providers/codex.js.map +1 -1
  89. package/dist/providers/index.d.ts +2 -1
  90. package/dist/providers/index.d.ts.map +1 -1
  91. package/dist/providers/index.js.map +1 -1
  92. package/dist/resources/index.d.ts +3 -22
  93. package/dist/resources/index.d.ts.map +1 -1
  94. package/dist/resources/index.js +9 -76
  95. package/dist/resources/index.js.map +1 -1
  96. package/dist/task/autoCommit.d.ts +9 -6
  97. package/dist/task/autoCommit.d.ts.map +1 -1
  98. package/dist/task/autoCommit.js +21 -12
  99. package/dist/task/autoCommit.js.map +1 -1
  100. package/dist/task/branchList.d.ts +55 -0
  101. package/dist/task/branchList.d.ts.map +1 -0
  102. package/dist/task/branchList.js +131 -0
  103. package/dist/task/branchList.js.map +1 -0
  104. package/dist/task/clone.d.ts +53 -0
  105. package/dist/task/clone.d.ts.map +1 -0
  106. package/dist/task/clone.js +181 -0
  107. package/dist/task/clone.js.map +1 -0
  108. package/dist/task/index.d.ts +3 -2
  109. package/dist/task/index.d.ts.map +1 -1
  110. package/dist/task/index.js +3 -2
  111. package/dist/task/index.js.map +1 -1
  112. package/dist/task/schema.d.ts +4 -4
  113. package/dist/task/schema.js +4 -4
  114. package/dist/task/summarize.d.ts +7 -5
  115. package/dist/task/summarize.d.ts.map +1 -1
  116. package/dist/task/summarize.js +62 -29
  117. package/dist/task/summarize.js.map +1 -1
  118. package/dist/utils/session.d.ts +74 -10
  119. package/dist/utils/session.d.ts.map +1 -1
  120. package/dist/utils/session.js +101 -51
  121. package/dist/utils/session.js.map +1 -1
  122. package/dist/utils/updateNotifier.d.ts +6 -0
  123. package/dist/utils/updateNotifier.d.ts.map +1 -0
  124. package/dist/utils/updateNotifier.js +17 -0
  125. package/dist/utils/updateNotifier.js.map +1 -0
  126. package/dist/workflow/engine.d.ts +35 -2
  127. package/dist/workflow/engine.d.ts.map +1 -1
  128. package/dist/workflow/engine.js +238 -38
  129. package/dist/workflow/engine.js.map +1 -1
  130. package/dist/workflow/index.d.ts +1 -1
  131. package/dist/workflow/index.d.ts.map +1 -1
  132. package/dist/workflow/index.js +1 -1
  133. package/dist/workflow/index.js.map +1 -1
  134. package/dist/workflow/instruction-builder.d.ts +89 -20
  135. package/dist/workflow/instruction-builder.d.ts.map +1 -1
  136. package/dist/workflow/instruction-builder.js +404 -61
  137. package/dist/workflow/instruction-builder.js.map +1 -1
  138. package/dist/workflow/parallel-logger.d.ts +76 -0
  139. package/dist/workflow/parallel-logger.d.ts.map +1 -0
  140. package/dist/workflow/parallel-logger.js +173 -0
  141. package/dist/workflow/parallel-logger.js.map +1 -0
  142. package/dist/workflow/phase-runner.d.ts +40 -0
  143. package/dist/workflow/phase-runner.d.ts.map +1 -0
  144. package/dist/workflow/phase-runner.js +69 -0
  145. package/dist/workflow/phase-runner.js.map +1 -0
  146. package/dist/workflow/rule-evaluator.d.ts +64 -0
  147. package/dist/workflow/rule-evaluator.d.ts.map +1 -0
  148. package/dist/workflow/rule-evaluator.js +178 -0
  149. package/dist/workflow/rule-evaluator.js.map +1 -0
  150. package/dist/workflow/rule-utils.d.ts +13 -0
  151. package/dist/workflow/rule-utils.d.ts.map +1 -0
  152. package/dist/workflow/rule-utils.js +17 -0
  153. package/dist/workflow/rule-utils.js.map +1 -0
  154. package/dist/workflow/transitions.d.ts +5 -13
  155. package/dist/workflow/transitions.d.ts.map +1 -1
  156. package/dist/workflow/transitions.js +8 -78
  157. package/dist/workflow/transitions.js.map +1 -1
  158. package/dist/workflow/types.d.ts +2 -1
  159. package/dist/workflow/types.d.ts.map +1 -1
  160. package/package.json +4 -1
  161. package/resources/global/en/agents/default/ai-antipattern-reviewer.md +193 -0
  162. package/resources/global/en/agents/default/{architect.md → architecture-reviewer.md} +144 -44
  163. package/resources/global/en/agents/default/coder.md +7 -7
  164. package/resources/global/en/agents/default/planner.md +29 -9
  165. package/resources/global/en/agents/default/{security.md → security-reviewer.md} +23 -5
  166. package/resources/global/en/agents/default/supervisor.md +13 -2
  167. package/resources/global/en/agents/expert/frontend-reviewer.md +0 -17
  168. package/resources/global/en/agents/expert/qa-reviewer.md +0 -16
  169. package/resources/global/en/agents/expert/security-reviewer.md +0 -16
  170. package/resources/global/en/agents/expert-cqrs/cqrs-es-reviewer.md +0 -17
  171. package/resources/global/en/agents/templates/coder.md +128 -0
  172. package/resources/global/en/agents/templates/planner.md +44 -0
  173. package/resources/global/en/agents/templates/reviewer.md +57 -0
  174. package/resources/global/en/agents/templates/supervisor.md +64 -0
  175. package/resources/global/en/workflows/default.yaml +235 -770
  176. package/resources/global/en/workflows/expert-cqrs.yaml +325 -697
  177. package/resources/global/en/workflows/expert.yaml +354 -722
  178. package/resources/global/en/workflows/magi.yaml +45 -52
  179. package/resources/global/en/workflows/research.yaml +18 -99
  180. package/resources/global/en/workflows/simple.yaml +156 -421
  181. package/resources/global/ja/agents/default/{ai-reviewer.md → ai-antipattern-reviewer.md} +92 -15
  182. package/resources/global/ja/agents/default/{architect.md → architecture-reviewer.md} +148 -48
  183. package/resources/global/ja/agents/default/coder.md +7 -7
  184. package/resources/global/ja/agents/default/planner.md +29 -9
  185. package/resources/global/ja/agents/default/{security.md → security-reviewer.md} +23 -5
  186. package/resources/global/ja/agents/default/supervisor.md +13 -2
  187. package/resources/global/ja/agents/expert/frontend-reviewer.md +0 -18
  188. package/resources/global/ja/agents/expert/qa-reviewer.md +0 -16
  189. package/resources/global/ja/agents/expert/security-reviewer.md +0 -16
  190. package/resources/global/ja/agents/expert-cqrs/cqrs-es-reviewer.md +0 -18
  191. package/resources/global/ja/agents/templates/coder.md +128 -0
  192. package/resources/global/ja/agents/templates/planner.md +44 -0
  193. package/resources/global/ja/agents/templates/reviewer.md +57 -0
  194. package/resources/global/ja/agents/templates/supervisor.md +64 -0
  195. package/resources/global/ja/workflows/default.yaml +230 -771
  196. package/resources/global/ja/workflows/expert-cqrs.yaml +316 -832
  197. package/resources/global/ja/workflows/expert.yaml +331 -711
  198. package/resources/global/ja/workflows/magi.yaml +45 -52
  199. package/resources/global/ja/workflows/research.yaml +18 -99
  200. package/resources/global/ja/workflows/simple.yaml +149 -415
  201. package/resources/project/dotgitignore +10 -0
  202. package/resources/project/tasks/TASK-FORMAT +37 -0
  203. package/dist/commands/reviewTasks.d.ts +0 -43
  204. package/dist/commands/reviewTasks.d.ts.map +0 -1
  205. package/dist/commands/reviewTasks.js.map +0 -1
  206. package/dist/task/worktree.d.ts +0 -70
  207. package/dist/task/worktree.d.ts.map +0 -1
  208. package/dist/task/worktree.js +0 -221
  209. package/dist/task/worktree.js.map +0 -1
  210. package/resources/global/en/agents/default/ai-reviewer.md +0 -116
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
 
@@ -23,9 +24,12 @@ npm install -g takt
23
24
  ## Quick Start
24
25
 
25
26
  ```bash
26
- # Run a task (will prompt for workflow selection and optional worktree creation)
27
+ # Run a task (will prompt for workflow selection and optional isolated clone)
27
28
  takt "Add a login feature"
28
29
 
30
+ # Run a GitHub issue as a task
31
+ takt "#6"
32
+
29
33
  # Add a task to the queue
30
34
  takt /add-task "Fix the login bug"
31
35
 
@@ -35,95 +39,180 @@ takt /run-tasks
35
39
  # Watch for tasks and auto-execute
36
40
  takt /watch
37
41
 
38
- # Review worktree results (merge or delete)
39
- takt /review-tasks
42
+ # List task branches (merge or delete)
43
+ takt /list-tasks
40
44
 
41
45
  # Switch workflow
42
46
  takt /switch
43
47
  ```
44
48
 
49
+ ### What happens when you run a task
50
+
51
+ When you run `takt "Add a login feature"`, TAKT guides you through an interactive flow:
52
+
53
+ **1. Workflow selection**
54
+
55
+ ```
56
+ Select workflow:
57
+ (↑↓ to move, Enter to select)
58
+
59
+ ❯ default (current) (default)
60
+ expert
61
+ expert-cqrs
62
+ magi
63
+ research
64
+ simple
65
+ Cancel
66
+ ```
67
+
68
+ **2. Isolated clone** (optional)
69
+
70
+ ```
71
+ ? Create worktree? (y/N)
72
+ ```
73
+
74
+ Choose `y` to run in a `git clone --shared` isolated environment, keeping your working directory clean.
75
+
76
+ **3. Execution** — The selected workflow orchestrates multiple agents to complete the task.
77
+
78
+ ### Recommended workflows
79
+
80
+ | Workflow | Best for |
81
+ |----------|----------|
82
+ | `default` | Full development tasks. Used for TAKT's own development. Multi-stage review with parallel architect + security review. |
83
+ | `simple` | Lightweight tasks like README updates or small fixes. Reviews without fix loops. |
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). |
85
+ | `research` | Research and investigation. Autonomous research without asking questions. |
86
+ | `magi` | Fun deliberation. Three AI personas analyze and vote (Evangelion-inspired). |
87
+
45
88
  ## Commands
46
89
 
47
90
  | Command | Alias | Description |
48
91
  |---------|-------|-------------|
49
- | `takt "task"` | | Execute task with current workflow (continues session) |
50
- | `takt -r "task"` | | Execute task, resuming previous session |
92
+ | `takt "task"` | | Execute task with current workflow (session auto-continued) |
93
+ | `takt "#N"` | | Execute GitHub issue #N as a task |
51
94
  | `takt /run-tasks` | `/run` | Run all pending tasks from `.takt/tasks/` |
52
95
  | `takt /watch` | | Watch `.takt/tasks/` and auto-execute tasks (stays resident) |
53
96
  | `takt /add-task` | `/add` | Add a new task interactively (YAML format, multiline supported) |
54
- | `takt /review-tasks` | `/review` | Review worktree task results (try merge, merge & cleanup, or delete) |
55
- | `takt /switch` | | Switch workflow interactively |
97
+ | `takt /list-tasks` | `/list` | List task branches (try merge, merge & cleanup, or delete) |
98
+ | `takt /switch` | `/sw` | Switch workflow interactively |
56
99
  | `takt /clear` | | Clear agent conversation sessions |
100
+ | `takt /eject` | | Copy builtin workflow/agents to `~/.takt/` for customization |
57
101
  | `takt /refresh-builtin` | | Update builtin agents/workflows to latest version |
58
- | `takt /config` | | Display current configuration |
102
+ | `takt /config` | | Configure permission mode |
59
103
  | `takt /help` | | Show help |
60
104
 
61
105
  ## Workflows
62
106
 
63
- TAKT uses YAML-based workflow definitions. Place them in:
64
- - `~/.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 `/eject` to copy a builtin to `~/.takt/` for customization.
65
108
 
66
109
  ### Example Workflow
67
110
 
68
111
  ```yaml
69
112
  name: default
70
113
  max_iterations: 10
114
+ initial_step: plan
71
115
 
72
116
  steps:
73
117
  - name: plan
74
- agent: planner
75
- provider: claude # Optional: claude or codex
76
- 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
77
124
  instruction_template: |
78
- {task}
79
- transitions:
80
- - condition: done
81
- next_step: implement
125
+ Analyze the request and create an implementation plan.
82
126
 
83
127
  - name: implement
84
- agent: coder
85
- provider: codex
86
- 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
87
136
  instruction_template: |
88
- {task}
89
- transitions:
90
- - condition: done
91
- next_step: review
92
- - condition: blocked
93
- next_step: ABORT
137
+ Implement based on the plan.
94
138
 
95
139
  - name: review
96
- agent: architect
97
- model: sonnet # Model alias (no provider = uses global default)
98
- transitions:
99
- - condition: approved
100
- next_step: COMPLETE
101
- - condition: rejected
102
- 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.
103
149
  ```
104
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
177
+ ```
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
+
105
191
  ## Built-in Workflows
106
192
 
107
193
  TAKT ships with several built-in workflows:
108
194
 
109
195
  | Workflow | Description |
110
196
  |----------|-------------|
111
- | `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. |
112
198
  | `simple` | Simplified version of default: plan → implement → architect review → AI review → supervisor. No intermediate fix steps. |
113
199
  | `research` | Research workflow: planner → digger → supervisor. Autonomously researches topics without asking questions. |
114
- | `expert-review` | Comprehensive review with domain experts: CQRS+ES, Frontend, AI, Security, QA reviews with fix loops. |
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. |
115
202
  | `magi` | Deliberation system inspired by Evangelion. Three AI personas (MELCHIOR, BALTHASAR, CASPER) analyze and vote. |
116
203
 
117
204
  Switch between workflows with `takt /switch`.
118
205
 
119
206
  ## Built-in Agents
120
207
 
121
- - **coder** - Implements features and fixes bugs
122
- - **architect** - Reviews code and provides feedback
123
- - **supervisor** - Final verification and approval
124
- - **planner** - Task analysis and implementation planning
125
- - **ai-reviewer** - AI-generated code quality review
126
- - **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 |
127
216
 
128
217
  ## Custom Agents
129
218
 
@@ -136,63 +225,54 @@ agents:
136
225
  allowed_tools: [Read, Glob, Grep]
137
226
  provider: claude # Optional: claude or codex
138
227
  model: opus # Claude: opus/sonnet/haiku or full name (claude-opus-4-5-20251101)
139
- status_patterns:
140
- approved: "\\[APPROVE\\]"
141
- rejected: "\\[REJECT\\]"
142
-
143
- - name: my-codex-agent
144
- prompt_file: .takt/prompts/analyzer.md
145
- provider: codex
146
- model: gpt-5.2-codex # Codex: gpt-5.2-codex, gpt-5.1-codex, etc.
147
228
  ```
148
229
 
149
- ## Model Selection
230
+ Or create agent prompt files as Markdown:
231
+
232
+ ```markdown
233
+ # ~/.takt/agents/my-agents/reviewer.md
150
234
 
151
- ### Claude Models
235
+ You are a code reviewer focused on security.
236
+
237
+ ## Your Role
238
+ - Check for security vulnerabilities
239
+ - Verify input validation
240
+ - Review authentication logic
241
+ ```
242
+
243
+ ## Model Selection
152
244
 
153
- You can specify models using either **aliases** or **full model names**:
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.
154
246
 
155
- **Aliases** (recommended for simplicity):
156
- - `opus` - Claude Opus 4.5 (highest reasoning capability)
157
- - `sonnet` - Claude Sonnet 4.5 (balanced, best for most tasks)
158
- - `haiku` - Claude Haiku 4.5 (fast and efficient)
159
- - `opusplan` - Opus for planning, Sonnet for execution
160
- - `default` - Recommended model for your account type
247
+ ### Claude Code
161
248
 
162
- **Full model names** (recommended for production):
163
- - `claude-opus-4-5-20251101`
164
- - `claude-sonnet-4-5-20250929`
165
- - `claude-haiku-4-5-20250101`
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.
166
250
 
167
- ### Codex Models
251
+ ### Codex
168
252
 
169
- Available Codex models:
170
- - `gpt-5.2-codex` - Latest agentic coding model (default)
171
- - `gpt-5.1-codex` - Previous generation
172
- - `gpt-5.1-codex-max` - Optimized for long-running tasks
173
- - `gpt-5.1-codex-mini` - Smaller, cost-effective version
174
- - `codex-1` - Specialized model aligned with coding preferences
253
+ The model string is passed to the Codex SDK. Defaults to `codex` if not specified. See Codex documentation for available models.
175
254
 
176
255
  ## Project Structure
177
256
 
178
257
  ```
179
258
  ~/.takt/
180
259
  ├── config.yaml # Global config (provider, model, workflows, etc.)
181
- ├── workflows/ # Workflow definitions
182
- └── agents/ # Agent prompt files
260
+ ├── workflows/ # User workflow definitions (override builtins)
261
+ └── agents/ # User agent prompt files
183
262
 
184
263
  .takt/ # Project-level config
185
264
  ├── agents.yaml # Custom agent definitions
186
265
  ├── tasks/ # Pending task files (.yaml, .md)
187
266
  ├── completed/ # Completed tasks with reports
188
- ├── worktrees/ # Git worktrees for isolated task execution
189
267
  ├── reports/ # Execution reports (auto-generated)
190
- └── logs/ # Session logs (incremental)
268
+ └── logs/ # Session logs in NDJSON format
191
269
  ├── latest.json # Pointer to current/latest session
192
270
  ├── previous.json # Pointer to previous session
193
- └── {sessionId}.json # Full session log per workflow run
271
+ └── {sessionId}.jsonl # NDJSON session log per workflow run
194
272
  ```
195
273
 
274
+ Builtin resources are embedded in the npm package (`dist/resources/`). User files in `~/.takt/` take priority.
275
+
196
276
  ### Global Configuration
197
277
 
198
278
  Configure default provider and model in `~/.takt/config.yaml`:
@@ -217,92 +297,70 @@ trusted_directories:
217
297
 
218
298
  ## Practical Usage Guide
219
299
 
220
- ### Resuming Sessions with `-r`
221
-
222
- When TAKT prompts for additional input during execution (e.g., "Please provide more details"), use the `-r` flag to continue the conversation:
223
-
224
- ```bash
225
- # First run - agent might ask for clarification
226
- takt "Fix the login bug"
227
-
228
- # Resume the same session to provide the requested information
229
- takt -r "The bug occurs when the password contains special characters"
230
- ```
231
-
232
- The `-r` flag preserves the agent's conversation history, allowing for natural back-and-forth interaction.
233
-
234
300
  ### Interactive Workflow
235
301
 
236
302
  When running `takt "task"`, you are prompted to:
237
303
 
238
304
  1. **Select a workflow** - Choose from available workflows (arrow keys, ESC to cancel)
239
- 2. **Create a worktree** (optional) - Optionally run the task in an isolated git worktree
305
+ 2. **Create an isolated clone** (optional) - Optionally run the task in a `git clone --shared` for isolation
240
306
 
241
307
  This interactive flow ensures each task runs with the right workflow and isolation level.
242
308
 
243
309
  ### Adding Custom Workflows
244
310
 
245
- 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
+ ```
246
317
 
247
318
  ```yaml
248
319
  # ~/.takt/workflows/my-workflow.yaml
249
320
  name: my-workflow
250
321
  description: My custom workflow
251
-
252
322
  max_iterations: 5
323
+ initial_step: analyze
253
324
 
254
325
  steps:
255
326
  - name: analyze
256
327
  agent: ~/.takt/agents/my-agents/analyzer.md
328
+ edit: false
329
+ rules:
330
+ - condition: Analysis complete
331
+ next: implement
257
332
  instruction_template: |
258
- Analyze this request: {task}
259
- transitions:
260
- - condition: done
261
- next_step: implement
333
+ Analyze this request thoroughly.
262
334
 
263
335
  - name: implement
264
336
  agent: ~/.takt/agents/default/coder.md
265
- instruction_template: |
266
- Implement based on the analysis: {previous_response}
337
+ edit: true
338
+ permission_mode: acceptEdits
267
339
  pass_previous_response: true
268
- transitions:
269
- - condition: done
270
- next_step: COMPLETE
340
+ rules:
341
+ - condition: Done
342
+ next: COMPLETE
343
+ instruction_template: |
344
+ Implement based on the analysis.
271
345
  ```
272
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
+
273
349
  ### Specifying Agents by Path
274
350
 
275
351
  Agents are specified using file paths in workflow definitions:
276
352
 
277
353
  ```yaml
278
- # Use built-in agents
279
- agent: ~/.takt/agents/default/coder.md
280
- agent: ~/.takt/agents/magi/melchior.md
354
+ # Relative to workflow file directory
355
+ agent: ../agents/default/coder.md
281
356
 
282
- # Use project-local agents
283
- agent: ./.takt/agents/my-reviewer.md
357
+ # Home directory
358
+ agent: ~/.takt/agents/default/coder.md
284
359
 
285
- # Use absolute paths
360
+ # Absolute paths
286
361
  agent: /path/to/custom/agent.md
287
362
  ```
288
363
 
289
- Create custom agent prompts as Markdown files:
290
-
291
- ```markdown
292
- # ~/.takt/agents/my-agents/reviewer.md
293
-
294
- You are a code reviewer focused on security.
295
-
296
- ## Your Role
297
- - Check for security vulnerabilities
298
- - Verify input validation
299
- - Review authentication logic
300
-
301
- ## Output Format
302
- - [REVIEWER:APPROVE] if code is secure
303
- - [REVIEWER:REJECT] if issues found (list them)
304
- ```
305
-
306
364
  ### Task Management
307
365
 
308
366
  TAKT supports batch task processing through task files in `.takt/tasks/`. Both `.yaml`/`.yml` and `.md` file formats are supported.
@@ -310,10 +368,13 @@ TAKT supports batch task processing through task files in `.takt/tasks/`. Both `
310
368
  #### Adding Tasks with `/add-task`
311
369
 
312
370
  ```bash
313
- # Quick add (no worktree)
371
+ # Quick add (no isolation)
314
372
  takt /add-task "Add authentication feature"
315
373
 
316
- # Interactive mode (prompts for worktree, branch, workflow options)
374
+ # Add a GitHub issue as a task
375
+ takt /add-task "#6"
376
+
377
+ # Interactive mode (prompts for isolation, branch, workflow options)
317
378
  takt /add-task
318
379
  ```
319
380
 
@@ -324,7 +385,7 @@ takt /add-task
324
385
  ```yaml
325
386
  # .takt/tasks/add-auth.yaml
326
387
  task: "Add authentication feature"
327
- worktree: true # Run in isolated git worktree
388
+ worktree: true # Run in isolated shared clone
328
389
  branch: "feat/add-auth" # Branch name (auto-generated if omitted)
329
390
  workflow: "default" # Workflow override (uses current if omitted)
330
391
  ```
@@ -342,16 +403,18 @@ Requirements:
342
403
  - Error handling for failed attempts
343
404
  ```
344
405
 
345
- #### Git Worktree Isolation
406
+ #### Isolated Execution (Shared Clone)
346
407
 
347
- YAML task files can specify `worktree` to run each task in an isolated git worktree, keeping the main working directory clean:
408
+ YAML task files can specify `worktree` to run each task in an isolated `git clone --shared`, keeping the main working directory clean:
348
409
 
349
- - `worktree: true` - Auto-create at `.takt/worktrees/{timestamp}-{task-slug}/`
410
+ - `worktree: true` - Auto-create a shared clone in a sibling directory (or `worktree_dir` from config)
350
411
  - `worktree: "/path/to/dir"` - Create at specified path
351
412
  - `branch: "feat/xxx"` - Use specified branch (auto-generated as `takt/{timestamp}-{slug}` if omitted)
352
413
  - Omit `worktree` - Run in current working directory (default)
353
414
 
354
- When a worktree task completes successfully, TAKT automatically commits all changes (`auto-commit`). Use `takt /review-tasks` to review, try-merge, or delete completed worktree branches.
415
+ > **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.
416
+
417
+ 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.
355
418
 
356
419
  #### Running Tasks with `/run-tasks`
357
420
 
@@ -374,26 +437,29 @@ Watch mode polls `.takt/tasks/` for new task files and auto-executes them as the
374
437
  - Automated workflows where tasks are added by external processes
375
438
  - Long-running development sessions where tasks are queued over time
376
439
 
377
- #### Reviewing Worktree Results with `/review-tasks`
440
+ #### Listing Task Branches with `/list-tasks`
378
441
 
379
442
  ```bash
380
- takt /review-tasks
443
+ takt /list-tasks
381
444
  ```
382
445
 
383
- Lists all `takt/`-prefixed worktree branches with file change counts. For each branch you can:
384
- - **Try merge** - Attempt merge into main (dry-run check, then actual merge)
385
- - **Merge & cleanup** - Merge and remove the worktree
386
- - **Delete** - Remove the worktree and branch without merging
446
+ Lists all `takt/`-prefixed branches with file change counts. For each branch you can:
447
+ - **Try merge** - Squash merge into main (stage changes without committing)
448
+ - **Instruct** - Give additional instructions via a temporary clone
449
+ - **Merge & cleanup** - Merge and delete the branch
450
+ - **Delete** - Delete the branch without merging
387
451
 
388
452
  ### Session Logs
389
453
 
390
- 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.
454
+ 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`.
391
455
 
392
456
  - `.takt/logs/latest.json` - Pointer to the current (or most recent) session
393
457
  - `.takt/logs/previous.json` - Pointer to the previous session
394
- - `.takt/logs/{sessionId}.json` - Full session log with step history
458
+ - `.takt/logs/{sessionId}.jsonl` - NDJSON session log with step history
459
+
460
+ Record types: `workflow_start`, `step_start`, `step_complete`, `workflow_complete`, `workflow_abort`.
395
461
 
396
- Agents can read `previous.json` to pick up context from a prior run (e.g., when resuming with `takt "続けて"`).
462
+ 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.
397
463
 
398
464
  ### Workflow Variables
399
465
 
@@ -401,58 +467,49 @@ Available variables in `instruction_template`:
401
467
 
402
468
  | Variable | Description |
403
469
  |----------|-------------|
404
- | `{task}` | Original user request |
470
+ | `{task}` | Original user request (auto-injected if not in template) |
405
471
  | `{iteration}` | Workflow-wide turn count (total steps executed) |
406
472
  | `{max_iterations}` | Maximum iterations allowed |
407
473
  | `{step_iteration}` | Per-step iteration count (how many times THIS step has run) |
408
- | `{previous_response}` | Previous step's output (requires `pass_previous_response: true`) |
409
- | `{user_inputs}` | Additional user inputs during workflow |
410
- | `{git_diff}` | Current git diff (uncommitted changes) |
411
- | `{report_dir}` | Report directory name (e.g., `20250126-143052-task-summary`) |
474
+ | `{previous_response}` | Previous step's output (auto-injected if not in template) |
475
+ | `{user_inputs}` | Additional user inputs during workflow (auto-injected if not in template) |
476
+ | `{report_dir}` | Report directory path (e.g., `.takt/reports/20250126-143052-task-summary`) |
477
+ | `{report:filename}` | Resolves to `{report_dir}/filename` (e.g., `{report:00-plan.md}`) |
412
478
 
413
479
  ### Designing Workflows
414
480
 
415
- Each workflow step requires three key elements:
481
+ Each workflow step requires:
416
482
 
417
483
  **1. Agent** - A Markdown file containing the system prompt:
418
484
 
419
485
  ```yaml
420
- agent: ~/.takt/agents/default/coder.md # Path to agent prompt file
421
- agent_name: coder # Display name (optional)
422
- ```
423
-
424
- **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:
425
-
426
- ```yaml
427
- status_rules_prompt: |
428
- Your final output MUST include a status tag:
429
- - `[CODER:DONE]` if implementation is complete
430
- - `[CODER:BLOCKED]` if you cannot proceed
486
+ agent: ../agents/default/coder.md # Path to agent prompt file
487
+ agent_name: coder # Display name (optional)
431
488
  ```
432
489
 
433
- **3. Transitions** - Route to the next step based on status:
490
+ **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:
434
491
 
435
492
  ```yaml
436
- transitions:
437
- - condition: done # Maps to status tag DONE
438
- next_step: review # Go to review step
439
- - condition: blocked # Maps to status tag BLOCKED
440
- next_step: ABORT # End workflow with failure
493
+ rules:
494
+ - condition: "Implementation complete"
495
+ next: review
496
+ - condition: "Cannot proceed"
497
+ next: ABORT
441
498
  ```
442
499
 
443
- Available transition conditions: `done`, `blocked`, `approved`, `rejected`, `improve`, `answer`, `always`.
444
- Special next_step values: `COMPLETE` (success), `ABORT` (failure).
500
+ Special `next` values: `COMPLETE` (success), `ABORT` (failure).
445
501
 
446
- **Step options:**
502
+ **3. Step options:**
447
503
 
448
504
  | Option | Default | Description |
449
505
  |--------|---------|-------------|
506
+ | `edit` | - | Whether the step can edit project files (`true`/`false`) |
450
507
  | `pass_previous_response` | `true` | Pass previous step's output to `{previous_response}` |
451
- | `on_no_status` | - | Behavior when no status is detected: `complete`, `continue`, `stay` |
452
508
  | `allowed_tools` | - | List of tools the agent can use (Read, Glob, Grep, Edit, Write, Bash, etc.) |
453
509
  | `provider` | - | Override provider for this step (`claude` or `codex`) |
454
510
  | `model` | - | Override model for this step |
455
511
  | `permission_mode` | `default` | Permission mode: `default`, `acceptEdits`, or `bypassPermissions` |
512
+ | `report` | - | Report file configuration (name, format) for auto-generated reports |
456
513
 
457
514
  ## API Usage
458
515
 
@@ -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"}