4e9c02091a
- Add takt-default piece (5-parallel review, takt knowledge) - Add takt-default-team-leader piece (team_leader implement variant) - Add takt.md knowledge facet (EN/JA) covering TAKT architecture - Add team-leader-implement instruction facet (EN/JA) - Add TAKT Development category to piece-categories
152 lines
4.9 KiB
Markdown
152 lines
4.9 KiB
Markdown
# TAKT Architecture Knowledge
|
|
|
|
## Core Structure
|
|
|
|
PieceEngine is a state machine. It manages movement transitions via EventEmitter.
|
|
|
|
```
|
|
CLI → PieceEngine → Runner (4 types) → RuleEvaluator → next movement
|
|
```
|
|
|
|
| Runner | Purpose | When to Use |
|
|
|--------|---------|-------------|
|
|
| MovementExecutor | Standard 3-phase execution | Default |
|
|
| ParallelRunner | Concurrent sub-movements | parallel block |
|
|
| ArpeggioRunner | Data-driven batch processing | arpeggio block |
|
|
| TeamLeaderRunner | Task decomposition → parallel sub-agents | team_leader block |
|
|
|
|
Runners are mutually exclusive. Do not specify multiple runner types on a single movement.
|
|
|
|
### 3-Phase Execution Model
|
|
|
|
Normal movements execute in up to 3 phases. Sessions persist across phases.
|
|
|
|
| Phase | Purpose | Tools | Condition |
|
|
|-------|---------|-------|-----------|
|
|
| Phase 1 | Main work | Movement's allowed_tools | Always |
|
|
| Phase 2 | Report output | Write only | When output_contracts defined |
|
|
| Phase 3 | Status judgment | None (judgment only) | When tag-based rules exist |
|
|
|
|
## Rule Evaluation
|
|
|
|
RuleEvaluator determines the next movement via 5-stage fallback. Earlier match takes priority.
|
|
|
|
| Priority | Method | Target |
|
|
|----------|--------|--------|
|
|
| 1 | aggregate | parallel parent (all/any) |
|
|
| 2 | Phase 3 tag | `[STEP:N]` output |
|
|
| 3 | Phase 1 tag | `[STEP:N]` output (fallback) |
|
|
| 4 | ai() judge | ai("condition") rules |
|
|
| 5 | AI fallback | AI evaluates all conditions |
|
|
|
|
When multiple tags appear in output, the **last match** wins.
|
|
|
|
### Condition Syntax
|
|
|
|
| Syntax | Parsing | Regex |
|
|
|--------|---------|-------|
|
|
| `ai("...")` | AI condition evaluation | `AI_CONDITION_REGEX` |
|
|
| `all("...")` / `any("...")` | Aggregate condition | `AGGREGATE_CONDITION_REGEX` |
|
|
| Plain string | Tag or AI fallback | — |
|
|
|
|
Adding new special syntax requires updating both pieceParser.ts regex and RuleEvaluator.
|
|
|
|
## Provider Integration
|
|
|
|
Abstracted through the Provider interface. SDK-specific details are encapsulated within each provider.
|
|
|
|
```
|
|
Provider.setup(AgentSetup) → ProviderAgent
|
|
ProviderAgent.call(prompt, options) → AgentResponse
|
|
```
|
|
|
|
| Criteria | Judgment |
|
|
|----------|----------|
|
|
| SDK-specific error handling leaking outside Provider | REJECT |
|
|
| Errors not propagated to AgentResponse.error | REJECT |
|
|
| Session key collision between providers | REJECT |
|
|
| Session key format `{persona}:{provider}` | OK |
|
|
|
|
### Model Resolution
|
|
|
|
Models resolve through 5-level priority. Higher takes precedence.
|
|
|
|
1. persona_providers model specification
|
|
2. Movement model field
|
|
3. CLI `--model` override
|
|
4. config.yaml (when resolved provider matches)
|
|
5. Provider default
|
|
|
|
## Facet Assembly
|
|
|
|
The faceted-prompting module is independent from TAKT core.
|
|
|
|
```
|
|
compose(facets, options) → ComposedPrompt { systemPrompt, userMessage }
|
|
```
|
|
|
|
| Criteria | Judgment |
|
|
|----------|----------|
|
|
| Import from faceted-prompting to TAKT core | REJECT |
|
|
| TAKT core depending on faceted-prompting | OK |
|
|
| Facet path resolution logic outside faceted-prompting | Warning |
|
|
|
|
### 3-Layer Facet Resolution Priority
|
|
|
|
Project `.takt/` → User `~/.takt/` → Builtin `builtins/{lang}/`
|
|
|
|
Same-named facets are overridden by higher-priority layers. Customize builtins by overriding in upper layers.
|
|
|
|
## Testing Patterns
|
|
|
|
Uses vitest. Test file naming conventions distinguish test types.
|
|
|
|
| Prefix | Type | Content |
|
|
|--------|------|---------|
|
|
| None | Unit test | Individual function/class verification |
|
|
| `it-` | Integration test | Piece execution simulation |
|
|
| `engine-` | Engine test | PieceEngine scenario verification |
|
|
|
|
### Mock Provider
|
|
|
|
`--provider mock` returns deterministic responses. Scenario queues compose multi-turn tests.
|
|
|
|
```typescript
|
|
// NG - Calling real API in tests
|
|
const response = await callClaude(prompt)
|
|
|
|
// OK - Set up scenario with mock provider
|
|
setMockScenario([
|
|
{ persona: 'coder', status: 'done', content: '[STEP:1]\nDone.' },
|
|
{ persona: 'reviewer', status: 'done', content: '[STEP:1]\napproved' },
|
|
])
|
|
```
|
|
|
|
### Test Isolation
|
|
|
|
| Criteria | Judgment |
|
|
|----------|----------|
|
|
| Tests sharing global state | REJECT |
|
|
| Environment variables not cleared in test setup | Warning |
|
|
| E2E tests assuming real API | Isolate via `provider` config |
|
|
|
|
## Error Propagation
|
|
|
|
Provider errors propagate through: `AgentResponse.error` → session log → console output.
|
|
|
|
| Criteria | Judgment |
|
|
|----------|----------|
|
|
| SDK error results in empty `blocked` status | REJECT |
|
|
| Error details not recorded in session log | REJECT |
|
|
| No ABORT transition defined for error cases | Warning |
|
|
|
|
## Session Management
|
|
|
|
Agent sessions are stored per-cwd. Session resume is skipped during worktree/clone execution.
|
|
|
|
| Criteria | Judgment |
|
|
|----------|----------|
|
|
| Session resuming when `cwd !== projectCwd` | REJECT (cross-project contamination) |
|
|
| Session key missing provider identifier | REJECT (cross-provider contamination) |
|
|
| Session broken between phases | REJECT (context loss) |
|