agent-bot/takt
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #129 from nrslib/release/v0.8.0-alpha.1

Browse Source 
Release v0.8.0-alpha.1
This commit is contained in:
nrs 2026-02-07 23:02:17 +09:00 committed by GitHub
commit 7152842c37
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
421 changed files with 24082 additions and 20874 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

75
CHANGELOG.md
View File

@ -4,6 +4,68 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
## [0.8.0-alpha.1] - 2026-02-07
### Added
- **Faceted Prompting アーキテクチャ**: プロンプト構成要素を独立ファイルとして管理し、ピース間で自由に組み合わせ可能に
- `personas/` — エージェントの役割・専門性を定義するペルソナプロンプト
- `policies/` — コーディング規約・品質基準・禁止事項を定義するポリシー
- `knowledge/` — ドメイン知識・アーキテクチャ情報を定義するナレッジ
- `instructions/` — ムーブメント固有の手順を定義するインストラクション
- `output-contracts/` — レポート出力フォーマットを定義するアウトプットコントラクト
- ピースYAMLのセクションマップ（`personas:`, `policies:`, `knowledge:`）でキーとファイルパスを対応付け、ムーブメントからキーで参照
- **Output Contracts と Quality Gates**: レポート出力の構造化定義と品質基準の AI ディレクティブ
- `output_contracts` フィールドでレポート定義（`report` フィールドを置き換え）
- `quality_gates` フィールドでムーブメント完了要件の AI ディレクティブを指定
- **Knowledge システム**: ドメイン知識をペルソナから分離し、ピースレベルで管理・注入
- ピースYAMLの `knowledge:` セクションマップでナレッジファイルを定義
- ムーブメントの `knowledge:` フィールドでキー参照して注入
- **Faceted Prompting ドキュメント**: 設計思想と実践ガイドを `docs/faceted-prompting.md`（en/ja）に追加
- **Hybrid Codex ピース生成ツール**: `tools/generate-hybrid-codex.mjs` で Claude ピースから Codex バリアントを自動生成
- 失敗タスクの再投入機能: `takt list` から失敗タスクブランチを選択して再実行可能に (#110)
- ブランチ名生成戦略を設定可能に（`branch_name_strategy` 設定）
- auto-PR 機能の追加と PR 作成ロジックの共通化 (#98)
- Issue 参照時にもピース選択を実施 (#97)
- ステップ（ムーブメント）にいてのスリープ機能
### Changed
- **BREAKING:** `resources/global/` ディレクトリを `builtins/` にリネーム
- `resources/global/{lang}/` → `builtins/{lang}/`
- package.json の `files` フィールドを `resources/` → `builtins/` に変更
- **BREAKING:** `agent` フィールドを `persona` にリネーム
- ピースYAMLの `agent:` → `persona:`、`agent_name:` → `persona_name:`
- 内部型: `agentPath` → `personaPath`、`agentDisplayName` → `personaDisplayName`、`agentSessions` → `personaSessions`
- ディレクトリ: `agents/` → `personas/`（グローバル・プロジェクト・ビルトイン全て）
- **BREAKING:** `report` フィールドを `output_contracts` に変更
- 従来の `report: 00-plan.md` / `report: [{Scope: ...}]` / `report: {name, order, format}` 形式を `output_contracts: {report: [...]}` 形式に統一
- **BREAKING:** `stances` → `policies`、`report_formats` → `output_contracts` にリネーム
- 全ビルトインピースを Faceted Prompting アーキテクチャに移行（旧エージェントプロンプト内のドメイン知識をナレッジに分離）
- SDK 更新: `@anthropic-ai/claude-agent-sdk` v0.2.19 → v0.2.34、`@openai/codex-sdk` v0.91.0 → v0.98.0
- ムーブメントに `policy` / `knowledge` フィールドを追加（セクションマップのキーで参照）
- 対話モードのスコアリングにポリシーベースの評価を追加
- README を刷新: agent → persona、セクションマップの説明追加、制御・管理の分類を明記
- ビルトインスキル（SKILL.md）をFaceted Prompting対応に刷新
### Fixed
- レポートディレクトリパスの解決バグを修正
- PR の Issue 番号リンクが正しく設定されない問題を修正
- `stageAndCommit` で gitignored ファイルがコミットされる問題を修正（`git add -f .takt/reports/` を削除）
### Internal
- ビルトインリソースの大規模再構成: 旧 `agents/` ディレクトリ構造（`default/`, `expert/`, `expert-cqrs/`, `magi/`, `research/`, `templates/`）を廃止し、フラットな `personas/`, `policies/`, `knowledge/`, `instructions/`, `output-contracts/` 構造に移行
- Faceted Prompting のスタイルガイドとテンプレートを追加（`builtins/ja/` に `PERSONA_STYLE_GUIDE.md`, `POLICY_STYLE_GUIDE.md`, `INSTRUCTION_STYLE_GUIDE.md`, `OUTPUT_CONTRACT_STYLE_GUIDE.md` 等）
- `pieceParser.ts` にポリシー・ナレッジ・インストラクションの解決ロジックを追加
- テスト追加: knowledge, policy-persona, deploySkill, StreamDisplay, globalConfig-defaults, sleep, task, taskExecution, taskRetryActions, addTask, saveTaskFile, parallel-logger, summarize 拡充
- `InstructionBuilder` にポリシー・ナレッジコンテンツの注入を追加
- `taskRetryActions.ts` を追加（失敗タスクの再投入ロジック）
- `sleep.ts` ユーティリティを追加
- 旧プロンプトファイル（`interactive-summary.md`, `interactive-system.md`）を削除
- 旧エージェントテンプレート（`templates/coder.md`, `templates/planner.md` 等）を削除
## [0.7.1] - 2026-02-06
### Fixed
@ -22,39 +84,34 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
### Added
- Hybrid Codex ピース: 全主要ピース（default, minimal, expert, expert-cqrs, passthrough, review-fix-minimal, coding）の Codex バリアントを追加
- coder エージェントを Codex プロバイダーで実行し、レビュアーは Claude を使うハイブリッド構成
- coder エージェントを Codex プロバイダーで実行するハイブリッド構成
- en/ja 両対応
- `passthrough` ピース: タスクをそのまま coder に渡す最小構成ピース（レビューなし）
- `coding` ピースを plan ベースに刷新: architect-planner による設計→実装→並列レビュー→修正の構成に変更
- `passthrough` ピース: タスクをそのまま coder に渡す最小構成ピース
- `takt export-cc` コマンド: ビルトインピース・エージェントを Claude Code Skill としてデプロイ
- `takt list` に delete アクション追加、non-interactive モード分離
- AI 相談アクション: `takt add` / インタラクティブモードで GitHub Issue 作成・タスクファイル保存が可能に
- サイクル検出: ai_review ↔ ai_fix 間の無限ループを検出する `CycleDetector` を追加 (#102)
- 修正不要時の裁定ステップ（`ai_no_fix`）を default ピースに追加
- `architect-planner` エージェント: アーキテクチャ設計と実装計画を統合する新エージェント
- ピースカテゴリに Hybrid Codex サブカテゴリを追加（en/ja）
- CI: skipped な TAKT Action ランを週次で自動削除するワークフローを追加
- ピースカテゴリに Hybrid Codex サブカテゴリを追加（en/ja）
### Changed
- カテゴリ設定を簡素化: `default-categories.yaml` を `piece-categories.yaml` に統合し、ユーザーディレクトリへの自動コピー方式に変更
- ピース選択UIのサブカテゴリナビゲーションを改善（再帰的な階層表示が正しく動作するように）
- ピース選択UIのサブカテゴリナビゲーションを修正（再帰的な階層表示が正しく動作するように）
- Claude Code Skill を Agent Team ベースに刷新
- エージェントプロンプトにボーイスカウトルールと後方互換コード検出ルールを追加
- `console.log` を `info()` に統一（list コマンド）
### Fixed
- Hybrid Codex ピースの description に含まれるコロンが YAML パースエラーを起こす問題を修正
- サブカテゴリ選択時に `selectPieceFromCategoryTree` に不正な引数が渡される問題を修正
- GitHub Actions でテストが git user 未設定により失敗する問題を修正（listTasks, listNonInteractive）
### Internal
- `list` コマンドのリファクタリング: `listNonInteractive.ts`, `taskDeleteActions.ts` を分離
- `cycle-detector.ts` を追加、`PieceEngine` にサイクル検出を統合
- ピースカテゴリローダーのリファクタリング（`pieceCategories.ts`, `pieceSelection/index.ts`）
- 不要なワークツリーセッションテストを削除、ワークツリー削除テストを簡素化
- テスト追加: cycle-detector, engine-loop-monitors, piece-selection, listNonInteractive, taskDeleteActions, createIssue, saveTaskFile
## [0.6.0] - 2026-02-05

53
CLAUDE.md
View File

@ -183,7 +183,7 @@ Implemented in `src/core/piece/evaluation/RuleEvaluator.ts`. The matched method
### Data Flow
1. User provides task (text or `#N` issue reference) or slash command → CLI
2. CLI loads piece with **correct priority** (v0.3.8+): user `~/.takt/pieces/` → project `.takt/pieces/` → builtin `resources/global/{lang}/pieces/`
2. CLI loads piece with **correct priority** (v0.3.8+): user `~/.takt/pieces/` → project `.takt/pieces/` → builtin `builtins/{lang}/pieces/`
3. PieceEngine starts at `initial_step`
4. Each step: `buildInstruction()` → Phase 1 (main) → Phase 2 (report) → Phase 3 (status) → `detectMatchedRule()` → `determineNextStep()`
5. Rule evaluation determines next step name (v0.3.8+: uses **last match** when multiple `[STEP:N]` tags appear)
@ -194,8 +194,9 @@ Implemented in `src/core/piece/evaluation/RuleEvaluator.ts`. The matched method
```
~/.takt/ # Global user config (created on first run)
config.yaml # Trusted dirs, default piece, log level, language
pieces/ # User piece YAML files (override builtins)
agents/ # User agent prompt files (.md)
pieces/ # User piece YAML files (override builtins)
personas/ # User persona prompt files (.md)
agents/ # Legacy persona prompts (backward compat)
.takt/ # Project-level config
agents.yaml # Custom agent definitions
@ -203,13 +204,14 @@ Implemented in `src/core/piece/evaluation/RuleEvaluator.ts`. The matched method
reports/ # Execution reports (auto-generated)
logs/ # Session logs in NDJSON format (gitignored)
resources/ # Bundled defaults (builtin, read from dist/ at runtime)
global/
en/ # English agents and pieces
ja/ # Japanese agents and pieces
builtins/ # Bundled defaults (builtin, read from dist/ at runtime)
en/ # English personas, policies, instructions, and pieces
ja/ # Japanese personas, policies, instructions, and pieces
project/ # Project-level template files
skill/ # Claude Code skill files
```
Builtin resources are embedded in the npm package (`dist/resources/`). User files in `~/.takt/` take priority. Use `/eject` to copy builtins to `~/.takt/` for customization.
Builtin resources are embedded in the npm package (`builtins/`). User files in `~/.takt/` take priority. Use `/eject` to copy builtins to `~/.takt/` for customization.
## Piece YAML Schema
@ -222,8 +224,8 @@ initial_step: plan # First step to execute
steps:
# Normal step
- name: step-name
agent: ../agents/default/coder.md # Path to agent prompt
agent_name: coder # Display name (optional)
persona: ../personas/coder.md # Path to persona prompt
persona_name: coder # Display name (optional)
provider: codex # claude|codex (optional)
model: opus # Model name (optional)
edit: true # Whether step can edit files
@ -234,7 +236,7 @@ steps:
pass_previous_response: true # Default: true
report:
name: 01-plan.md # Report file name
format: | # Report format template
format: | # Output contract template
# Plan Report
...
rules:
@ -249,14 +251,14 @@ steps:
- name: reviewers
parallel:
- name: arch-review
agent: ../agents/default/architecture-reviewer.md
persona: ../personas/architecture-reviewer.md
rules:
- condition: approved # next is optional for sub-steps
- condition: needs_fix
instruction_template: |
Review architecture...
- name: security-review
agent: ../agents/default/security-reviewer.md
persona: ../personas/security-reviewer.md
rules:
- condition: approved
- condition: needs_fix
@ -298,7 +300,7 @@ Key points about parallel steps:
### Piece Categories
Pieces can be organized into categories for better UI presentation. Categories are configured in:
- `resources/global/{lang}/default-categories.yaml` - Default builtin categories
- `builtins/{lang}/piece-categories.yaml` - Default builtin categories
- `~/.takt/config.yaml` - User-defined categories (via `piece_categories` field)
Category configuration supports:
@ -369,9 +371,9 @@ Files: `.takt/logs/{sessionId}.jsonl`, with `latest.json` pointer. Legacy `.json
**Instruction auto-injection over explicit placeholders.** The instruction builder auto-injects `{task}`, `{previous_response}`, `{user_inputs}`, and status rules. Templates should contain only step-specific instructions, not boilerplate.
**Agent prompts contain only domain knowledge.** Agent prompt files (`resources/global/{lang}/agents/**/*.md`) must contain only domain expertise and behavioral principles — never piece-specific procedures. Piece-specific details (which reports to read, step routing, specific templates with hardcoded step names) belong in the piece YAML's `instruction_template`. This keeps agents reusable across different pieces.
**Persona prompts contain only domain knowledge.** Persona prompt files (`builtins/{lang}/personas/*.md`) must contain only domain expertise and behavioral principles — never piece-specific procedures. Piece-specific details (which reports to read, step routing, specific templates with hardcoded step names) belong in the piece YAML's `instruction_template`. This keeps personas reusable across different pieces.
What belongs in agent prompts:
What belongs in persona prompts:
- Role definition ("You are a ... specialist")
- Domain expertise, review criteria, judgment standards
- Do / Don't behavioral rules
@ -404,7 +406,7 @@ Key constraints:
- **Ephemeral lifecycle**: Clone is created → task runs → auto-commit + push → clone is deleted. Branches are the single source of truth.
- **Session isolation**: Claude Code sessions are stored per-cwd in `~/.claude/projects/{encoded-path}/`. Sessions from the main project cannot be resumed in a clone. The engine skips session resume when `cwd !== projectCwd`.
- **No node_modules**: Clones only contain tracked files. `node_modules/` is absent.
- **Dual cwd**: `cwd` = clone path (where agents run), `projectCwd` = project root (where `.takt/` lives). Reports, logs, and session data always write to `projectCwd`.
- **Dual cwd**: `cwd` = clone path (where agents run), `projectCwd` = project root. Reports write to `cwd/.takt/reports/` (clone) to prevent agents from discovering the main repository. Logs and session data write to `projectCwd`.
- **List**: Use `takt list` to list branches. Instruct action creates a temporary clone for the branch, executes, pushes, then removes the clone.
## Error Propagation
@ -445,18 +447,18 @@ Debug logs are written to `.takt/logs/debug.log` (ndjson format). Log levels: `d
## Important Implementation Notes
**Agent prompt resolution:**
- Agent paths in piece YAML are resolved relative to the piece file's directory
- `../agents/default/coder.md` resolves from piece file location
- Built-in agents are loaded from `dist/resources/global/{lang}/agents/`
- User agents are loaded from `~/.takt/agents/` or `.takt/agents.yaml`
- If agent file doesn't exist, the agent string is used as inline system prompt
**Persona prompt resolution:**
- Persona paths in piece YAML are resolved relative to the piece file's directory
- `../personas/coder.md` resolves from piece file location
- Built-in personas are loaded from `builtins/{lang}/personas/`
- User personas are loaded from `~/.takt/personas/` (legacy: `~/.takt/agents/`)
- If persona file doesn't exist, the persona string is used as inline system prompt
**Report directory structure:**
- Report dirs are created at `.takt/reports/{timestamp}-{slug}/`
- Report files specified in `step.report` are written relative to report dir
- Report dir path is available as `{report_dir}` variable in instruction templates
- When `cwd !== projectCwd` (worktree execution), reports still write to `projectCwd/.takt/reports/`
- When `cwd !== projectCwd` (worktree execution), reports write to `cwd/.takt/reports/` (clone dir) to prevent agents from discovering the main repository path
**Session continuity across phases:**
- Agent sessions persist across Phase 1 → Phase 2 → Phase 3 for context continuity
@ -466,8 +468,9 @@ Debug logs are written to `.takt/logs/debug.log` (ndjson format). Log levels: `d
**Worktree execution gotchas:**
- `git clone --shared` creates independent `.git` directory (not `git worktree`)
- Clone cwd ≠ project cwd: agents work in clone, but reports/logs write to project
- Clone cwd ≠ project cwd: agents work in clone, reports write to clone, logs write to project
- Session resume is skipped when `cwd !== projectCwd` to avoid cross-directory contamination
- Reports write to `cwd/.takt/reports/` (clone) to prevent agents from discovering the main repository path via instruction
- Clones are ephemeral: created → task runs → auto-commit + push → deleted
- Use `takt list` to manage task branches after clone deletion

110
README.md
View File

@ -4,7 +4,7 @@
**T**ask **A**gent **K**oordination **T**ool - Define how AI agents coordinate, where humans intervene, and what gets recorded — in YAML
TAKT runs multiple AI agents (Claude Code, Codex) through YAML-defined workflows. Each step — who runs, what's allowed, what happens on failure — is declared in a piece file, not left to the agent.
TAKT runs multiple AI agents (Claude Code, Codex) through YAML-defined workflows. Each step — who runs, what they see, what's allowed, what happens on failure — is declared in a piece file, not left to the agent.
TAKT is built with TAKT itself (dogfooding).
@ -24,6 +24,21 @@ You can read every term as standard workflow language (piece = workflow, movemen
- Multi-agent coordination needs structure — pieces define who does what, in what order, with what permissions
- CI/CD integration needs guardrails — pipeline mode runs agents non-interactively with full audit logs
## What TAKT Controls and Manages
TAKT **controls** agent execution and **manages** prompt components.
| | Concern | Description |
|---|---------|-------------|
| Control | **Routing** | State transition rules (who runs when) |
| Control | **Tools & Permissions** | Readonly, edit, full access (what's allowed) |
| Control | **Recording** | Session logs, reports (what gets captured) |
| Manage | **Personas** | Agent roles and expertise (who they act as) |
| Manage | **Policies** | Coding standards, quality criteria, prohibitions (what to uphold) |
| Manage | **Knowledge** | Domain knowledge, architecture info (what to reference) |
Personas, policies, and knowledge are managed as independent files and freely combined across workflows ([Faceted Prompting](./docs/faceted-prompting.md)). Change a policy in one file and every workflow using it gets the update.
## What TAKT is NOT
- **Not an autonomous engineer** — TAKT coordinates agents but doesn't decide what to build. You provide the task, TAKT governs the execution.
@ -235,7 +250,7 @@ In pipeline mode, PRs are not created unless `--auto-pr` is specified.
# Interactively switch pieces
takt switch
# Copy builtin pieces/agents to project .takt/ for customization
# Copy builtin pieces/personas to project .takt/ for customization
takt eject
# Copy to ~/.takt/ (global) instead
@ -244,7 +259,7 @@ takt eject --global
# Clear agent conversation sessions
takt clear
# Deploy builtin pieces/agents as Claude Code Skill
# Deploy builtin pieces/personas as Claude Code Skill
takt export-cc
# Preview assembled prompts for each movement and phase
@ -296,9 +311,21 @@ name: default
max_iterations: 10
initial_movement: plan
# Section maps — key: file path (relative to this YAML)
personas:
planner: ../personas/planner.md
coder: ../personas/coder.md
reviewer: ../personas/architecture-reviewer.md
policies:
coding: ../policies/coding.md
knowledge:
architecture: ../knowledge/architecture.md
movements:
- name: plan
agent: ../agents/default/planner.md
persona: planner
model: opus
edit: false
rules:
@ -308,7 +335,9 @@ movements:
Analyze the request and create an implementation plan.
- name: implement
agent: ../agents/default/coder.md
persona: coder
policy: coding
knowledge: architecture
edit: true
permission_mode: edit
rules:
@ -320,7 +349,8 @@ movements:
Implement based on the plan.
- name: review
agent: ../agents/default/architecture-reviewer.md
persona: reviewer
knowledge: architecture
edit: false
rules:
- condition: Approved
@ -331,13 +361,13 @@ movements:
Review the implementation from architecture and code quality perspectives.
```
### Agentless Movements
### Persona-less Movements
The `agent` field is optional. When omitted, the movement executes using only the `instruction_template` without a system prompt. This is useful for simple tasks that don't require agent behavior customization.
The `persona` field is optional. When omitted, the movement executes using only the `instruction_template` without a system prompt. This is useful for simple tasks that don't require persona customization.
```yaml
- name: summarize
# No agent specified — uses instruction_template only
# No persona specified — uses instruction_template only
edit: false
rules:
- condition: Summary complete
@ -346,11 +376,11 @@ The `agent` field is optional. When omitted, the movement executes using only th
Read the report and provide a concise summary.
```
You can also write an inline system prompt as the `agent` value (if the specified file doesn't exist):
You can also write an inline system prompt as the `persona` value (if the specified file doesn't exist):
```yaml
- name: review
agent: "You are a code reviewer. Focus on readability and maintainability."
persona: "You are a code reviewer. Focus on readability and maintainability."
edit: false
instruction_template: |
Review code quality.
@ -364,14 +394,14 @@ Execute sub-movements in parallel within a movement and evaluate with aggregate
- name: reviewers
parallel:
- name: arch-review
agent: ../agents/default/architecture-reviewer.md
persona: reviewer
rules:
- condition: approved
- condition: needs_fix
instruction_template: |
Review architecture and code quality.
- name: security-review
agent: ../agents/default/security-reviewer.md
persona: security-reviewer
rules:
- condition: approved
- condition: needs_fix
@ -417,10 +447,10 @@ TAKT includes multiple builtin pieces:
Use `takt switch` to switch pieces.
## Builtin Agents
## Builtin Personas
| Agent | Description |
|-------|-------------|
| Persona | Description |
|---------|-------------|
| **planner** | Task analysis, spec investigation, implementation planning |
| **architect-planner** | Task analysis and design planning: investigates code, resolves unknowns, creates implementation plans |
| **coder** | Feature implementation, bug fixing |
@ -431,12 +461,12 @@ Use `takt switch` to switch pieces.
| **conductor** | Phase 3 judgment specialist: reads reports/responses and outputs status tags |
| **supervisor** | Final validation, approval |
## Custom Agents
## Custom Personas
Create agent prompts in Markdown files:
Create persona prompts in Markdown files:
```markdown
# ~/.takt/agents/my-agents/reviewer.md
# ~/.takt/personas/my-reviewer.md
You are a code reviewer specialized in security.
@ -463,10 +493,10 @@ The model string is passed to the Codex SDK. If unspecified, defaults to `codex`
```
~/.takt/ # Global configuration directory
├── config.yaml # Global config (provider, model, piece, etc.)
├── pieces/ # User piece definitions (override builtins)
├── pieces/ # User piece definitions (override builtins)
│ └── custom.yaml
└── agents/ # User agent prompt files (.md)
└── my-agent.md
└── personas/ # User persona prompt files (.md)
└── my-persona.md
.takt/ # Project-level configuration
├── config.yaml # Project config (current piece, etc.)
@ -480,7 +510,7 @@ The model string is passed to the Codex SDK. If unspecified, defaults to `codex`
└── {sessionId}.jsonl # NDJSON session log per piece execution
```
Builtin resources are embedded in the npm package (`dist/resources/`). User files in `~/.takt/` take priority.
Builtin resources are embedded in the npm package (`builtins/`). User files in `~/.takt/` take priority.
### Global Configuration
@ -615,9 +645,13 @@ description: Custom piece
max_iterations: 5
initial_movement: analyze
personas:
analyzer: ~/.takt/personas/analyzer.md
coder: ../personas/coder.md
movements:
- name: analyze
agent: ~/.takt/agents/my-agents/analyzer.md
persona: analyzer
edit: false
rules:
- condition: Analysis complete
@ -626,7 +660,7 @@ movements:
Thoroughly analyze this request.
- name: implement
agent: ~/.takt/agents/default/coder.md
persona: coder
edit: true
permission_mode: edit
pass_previous_response: true
@ -639,19 +673,15 @@ movements:
> **Note**: `{task}`, `{previous_response}`, `{user_inputs}` are automatically injected into instructions. Explicit placeholders are only needed if you want to control their position in the template.
### Specifying Agents by Path
### Specifying Personas by Path
In piece definitions, specify agents using file paths:
Map keys to file paths in section maps, then reference keys from movements:
```yaml
# Relative path from piece file
agent: ../agents/default/coder.md
# Home directory
agent: ~/.takt/agents/default/coder.md
# Absolute path
agent: /path/to/custom/agent.md
# Section maps (relative to piece file)
personas:
coder: ../personas/coder.md
reviewer: ~/.takt/personas/my-reviewer.md
```
### Piece Variables
@ -673,11 +703,11 @@ Variables available in `instruction_template`:
Elements needed for each piece movement:
**1. Agent** - Markdown file containing system prompt:
**1. Persona** - Referenced by section map key (used as system prompt):
```yaml
agent: ../agents/default/coder.md # Path to agent prompt file
agent_name: coder # Display name (optional)
persona: coder # Key from personas section map
persona_name: coder # Display name (optional)
```
**2. Rules** - Define routing from movement to next movement. The instruction builder auto-injects status output rules, so agents know which tags to output:
@ -702,7 +732,8 @@ Special `next` values: `COMPLETE` (success), `ABORT` (failure)
| `provider` | - | Override provider for this movement (`claude` or `codex`) |
| `model` | - | Override model for this movement |
| `permission_mode` | - | Permission mode: `readonly`, `edit`, `full` (provider-independent) |
| `report` | - | Auto-generated report file settings (name, format) |
| `output_contracts` | - | Output contract definitions for report files |
| `quality_gates` | - | AI directives for movement completion requirements |
## API Usage Example
@ -787,6 +818,7 @@ export TAKT_OPENAI_API_KEY=sk-...
## Documentation
- [Faceted Prompting](./docs/faceted-prompting.md) - Separation of Concerns for AI prompts (Persona, Policy, Instruction, Knowledge, Output Contract)
- [Piece Guide](./docs/pieces.md) - Creating and customizing pieces
- [Agent Guide](./docs/agents.md) - Configuring custom agents
- [Changelog](../CHANGELOG.md) - Version history

0
resources/global/en/config.yaml → builtins/en/config.yaml
View File

40
builtins/en/instructions/ai-fix.md Normal file
View File

@ -0,0 +1,40 @@
**This is AI Review iteration #{movement_iteration}.**
From the 2nd iteration onward, it means the previous fixes were not actually applied.
**Your belief that they were "already fixed" is incorrect.**
**First, acknowledge the following:**
- The files you thought were "fixed" are actually not fixed
- Your understanding of the previous work is wrong
- You need to rethink from scratch
**Required actions:**
1. Open all flagged files with the Read tool (discard assumptions and verify the facts)
2. Search for the problem areas with grep to confirm they exist
3. Fix the confirmed issues with the Edit tool
4. Run tests to verify
5. Report specifically "what you checked and what you fixed"
**Report format:**
- NG: "It has already been fixed"
- OK: "After checking file X at L123, I found issue Y and fixed it to Z"
**Strictly prohibited:**
- Reporting "already fixed" without opening the file
- Making judgments based on assumptions
- Leaving issues that the AI Reviewer REJECTed unresolved
**Handling "no fix needed" (required)**
- Do not judge "no fix needed" unless you can show verification results for the target file for each AI Review finding
- If the finding relates to "generated output" or "spec synchronization", output the tag corresponding to "unable to determine" unless you can verify the source/spec
- If no fix is needed, output the tag corresponding to "unable to determine" and clearly state the reason and scope of verification
**Required output (include headings)**
## Files checked
- {filepath:line_number}
## Searches performed
- {command and summary}
## Changes made
- {change details}
## Test results
- {command executed and results}

10
builtins/en/instructions/ai-review.md Normal file
View File

@ -0,0 +1,10 @@
**This is AI Review iteration #{movement_iteration}.**
On the first iteration, review comprehensively and report all issues that need to be flagged.
From the 2nd iteration onward, prioritize verifying whether previously REJECTed items have been fixed.
Review the code for AI-specific issues:
- Verification of assumptions
- Plausible but incorrect patterns
- Compatibility with the existing codebase
- Scope creep detection

14
builtins/en/instructions/arbitrate.md Normal file
View File

@ -0,0 +1,14 @@
The ai_review (reviewer) and ai_fix (coder) disagree.
- ai_review flagged issues and issued a REJECT
- ai_fix reviewed and determined "no fix needed"
Review both outputs and arbitrate which judgment is valid.
**Reports to reference:**
- AI review results: {report:ai-review.md}
**Judgment criteria:**
- Whether ai_review's findings are specific and point to real issues in the code
- Whether ai_fix's rebuttal has evidence (file verification results, test results)
- Whether the findings are non-blocking (record only) level or actually require fixes

21
builtins/en/instructions/architect.md Normal file
View File

@ -0,0 +1,21 @@
Read the plan report ({report:plan.md}) and design the architecture.
**Criteria for small tasks:**
- Only 1-2 file changes
- No design decisions needed
- No technology selection needed
For small tasks, skip creating a design report and match the rule for "small task (no design needed)".
**Tasks requiring design:**
- Changes to 3 or more files
- Adding new modules or features
- Technology selection required
- Architecture pattern decisions needed
**Actions:**
1. Assess the task scope
2. Determine file structure
3. Select technologies (if needed)
4. Choose design patterns
5. Create implementation guidelines for the Coder

14
builtins/en/instructions/fix-supervisor.md Normal file
View File

@ -0,0 +1,14 @@
Fix the issues raised by the supervisor.
The supervisor has flagged problems from an overall perspective.
Address items in order of priority, starting with the highest.
**Required output (include headings)**
## Work results
- {Summary of actions taken}
## Changes made
- {Summary of changes}
## Test results
- {Command executed and results}
## Evidence
- {List key points from files checked/searches/diffs/logs}

12
builtins/en/instructions/fix.md Normal file
View File

@ -0,0 +1,12 @@
Address the reviewer's feedback.
Review the session conversation history and fix the issues raised by the reviewer.
**Required output (include headings)**
## Work results
- {Summary of actions taken}
## Changes made
- {Summary of changes}
## Test results
- {Command executed and results}
## Evidence
- {List key points from files checked/searches/diffs/logs}

46
builtins/en/instructions/implement.md Normal file
View File

@ -0,0 +1,46 @@
Implement according to the plan.
Refer only to files within the Report Directory shown in the Piece Context. Do not search or reference other report directories.
**Important**: Add unit tests alongside the implementation.
- Add unit tests for newly created classes and functions
- Update relevant tests when modifying existing code
- Test file placement: follow the project's conventions
- Running tests is mandatory. After completing implementation, always run tests and verify results
**Scope output contract (create at the start of implementation):**
```markdown
# Change Scope Declaration
## Task
{One-line task summary}
## Planned changes
| Type | File |
|------|------|
| Create | `src/example.ts` |
| Modify | `src/routes.ts` |
## Estimated size
Small / Medium / Large
## Impact area
- {Affected modules or features}
```
**Decisions output contract (at implementation completion, only if decisions were made):**
```markdown
# Decision Log
## 1. {Decision}
- **Context**: {Why the decision was needed}
- **Options considered**: {List of options}
- **Rationale**: {Reason for the choice}
```
**Required output (include headings)**
## Work results
- {Summary of actions taken}
## Changes made
- {Summary of changes}
## Test results
- {Command executed and results}

13
builtins/en/instructions/plan-investigate.md Normal file
View File

@ -0,0 +1,13 @@
Analyze the task and formulate an implementation plan.
**Handling unknowns (important):**
If the task has open questions or unknowns, investigate by reading the code and resolve them on your own.
Only mark something as "unclear" if it involves external factors that cannot be resolved through investigation (e.g., the user's intent cannot be determined).
If it can be understood by reading the code, it is not "unclear".
**Actions:**
1. Understand the task requirements
2. Read the relevant code to grasp the current state
3. Investigate any unknowns through code analysis
4. Identify the impact area
5. Decide on the implementation approach

9
builtins/en/instructions/plan.md Normal file
View File

@ -0,0 +1,9 @@
Analyze the task and formulate an implementation plan.
**Note:** If a Previous Response exists, this is a replan due to rejection.
Revise the plan taking that feedback into account.
**Actions:**
1. Understand the task requirements
2. Identify the impact area
3. Decide on the implementation approach

5
builtins/en/instructions/review-ai.md Normal file
View File

@ -0,0 +1,5 @@
Review the code for AI-specific issues:
- Verification of assumptions
- Plausible but incorrect patterns
- Compatibility with the existing codebase
- Scope creep detection

10
builtins/en/instructions/review-arch.md Normal file
View File

@ -0,0 +1,10 @@
Focus on reviewing **architecture and design**.
Do not review AI-specific issues (already covered by the ai_review movement).
**Review criteria:**
- Structural and design validity
- Code quality
- Appropriateness of change scope
- Test coverage
- Dead code
- Call chain verification

12
builtins/en/instructions/review-cqrs-es.md Normal file
View File

@ -0,0 +1,12 @@
Review the changes from the perspective of CQRS (Command Query Responsibility Segregation) and Event Sourcing.
AI-specific issue review is not needed (already covered by the ai_review movement).
**Review criteria:**
- Aggregate design validity
- Event design (granularity, naming, schema)
- Command/Query separation
- Projection design
- Eventual consistency considerations
**Note**: If this project does not use the CQRS+ES pattern,
review from a general domain design perspective instead.

12
builtins/en/instructions/review-frontend.md Normal file
View File

@ -0,0 +1,12 @@
Review the changes from a frontend development perspective.
**Review criteria:**
- Component design (separation of concerns, granularity)
- State management (local vs. global decisions)
- Performance (re-renders, memoization)
- Accessibility (keyboard navigation, ARIA)
- Data fetching patterns
- TypeScript type safety
**Note**: If this project does not include a frontend,
proceed as no issues found.

8
builtins/en/instructions/review-qa.md Normal file
View File

@ -0,0 +1,8 @@
Review the changes from a quality assurance perspective.
**Review criteria:**
- Test coverage and quality
- Test strategy (unit/integration/E2E)
- Error handling
- Logging and monitoring
- Maintainability

5
builtins/en/instructions/review-security.md Normal file
View File

@ -0,0 +1,5 @@
Review the changes from a security perspective. Check for the following vulnerabilities:
- Injection attacks (SQL, command, XSS)
- Authentication and authorization flaws
- Data exposure risks
- Cryptographic weaknesses

55
builtins/en/instructions/supervise.md Normal file
View File

@ -0,0 +1,55 @@
Run tests, verify the build, and perform final approval.
**Overall piece verification:**
1. Whether the plan and implementation results are consistent
2. Whether findings from each review movement have been addressed
3. Whether the original task objective has been achieved
**Report verification:** Read all reports in the Report Directory and
check for any unaddressed improvement suggestions.
**Validation output contract:**
```markdown
# Final Verification Results
## Result: APPROVE / REJECT
## Verification Summary
| Item | Status | Verification method |
|------|--------|-------------------|
| Requirements met | ✅ | Cross-checked with requirements list |
| Tests | ✅ | `npm test` (N passed) |
| Build | ✅ | `npm run build` succeeded |
| Functional check | ✅ | Main flows verified |
## Deliverables
- Created: {Created files}
- Modified: {Modified files}
## Outstanding items (if REJECT)
| # | Item | Reason |
|---|------|--------|
| 1 | {Item} | {Reason} |
```
**Summary output contract (only if APPROVE):**
```markdown
# Task Completion Summary
## Task
{Original request in 1-2 sentences}
## Result
Complete
## Changes
| Type | File | Summary |
|------|------|---------|
| Create | `src/file.ts` | Summary description |
## Verification commands
```bash
npm test
npm run build
```
```

348
resources/global/en/agents/default/architecture-reviewer.md → builtins/en/knowledge/architecture.md
View File

@ -1,67 +1,6 @@
# Architecture Reviewer
# Architecture Knowledge
You are a **design reviewer** and **quality gatekeeper**. You review not just code quality, but emphasize **structure and design**.
## Core Values
Code is read far more often than it is written. Poorly structured code destroys maintainability and produces unexpected side effects with every change. Be strict and uncompromising.
"If the structure is right, the code naturally follows"—that is the conviction of design review.
## Reviewer Stance
**Never defer even minor issues. If a problem can be fixed now, require it to be fixed now.**
- No compromises for "minor issues". Accumulation of small problems becomes technical debt
- "Address in next task" never happens. If fixable now, fix now
- No "conditional approval". If there are issues, reject
- If you find in-scope fixable issues, flag them without exception
- Existing issues (unrelated to current change) are non-blocking, but issues introduced or fixable in this change must be flagged
## Areas of Expertise
### Structure & Design
- File organization and module decomposition
- Layer design and dependency direction verification
- Directory structure pattern selection
### Code Quality
- Abstraction level alignment
- DRY, YAGNI, and Fail Fast principles
- Idiomatic implementation
### Anti-Pattern Detection
- Unnecessary backward compatibility code
- Workaround implementations
- Unused code and dead code
**Don't:**
- Write code yourself (only provide feedback and suggestions)
- Give vague feedback ("clean this up" is prohibited)
- Review AI-specific issues (AI Reviewer's job)
## Review Target Distinction
**Important**: Distinguish between source files and generated files.
| Type | Location | Review Target |
|------|----------|---------------|
| Generated reports | `.takt/reports/` | Not a review target |
| Reports in git diff | `.takt/reports/` | **Ignore** |
**About template files:**
- YAML and Markdown files in `resources/` are templates
- `{report_dir}`, `{task}` are placeholders (replaced at runtime)
- Even if expanded values appear in git diff for report files, they are NOT hardcoded
**To avoid false positives:**
1. Before flagging "hardcoded values", **verify if the file is source or report**
2. Files under `.takt/reports/` are generated during piece execution - not review targets
3. Ignore generated files even if they appear in git diff
## Review Perspectives
### 1. Structure & Design
## Structure & Design
**File Organization:**
@ -73,17 +12,20 @@ Code is read far more often than it is written. Poorly structured code destroys
| Unrelated code coexisting | REJECT |
**Module Structure:**
- High cohesion: Related functionality grouped together
- Low coupling: Minimal inter-module dependencies
- No circular dependencies
- Appropriate directory hierarchy
**Function Design:**
- One responsibility per function
- Consider splitting functions over 30 lines
- Side effects clearly defined
**Layer Design:**
- Dependency direction: Upper layers -> Lower layers (reverse prohibited)
- Controller -> Service -> Repository flow maintained
- 1 interface = 1 responsibility (no giant Service classes)
@ -136,97 +78,79 @@ Prohibited patterns:
| Mixed features and layers | `features/services/` prohibited |
**Separation of Concerns:**
- Read and write responsibilities separated
- Data fetching at root (View/Controller), passed to children
- Error handling centralized (no try-catch scattered everywhere)
- Business logic not leaking into Controller/View
### 2. Code Quality
**Mandatory checks:**
- Use of `any` type -> **Immediate REJECT**
- Overuse of fallback values (`?? 'unknown'`) -> **REJECT** (see examples below)
- Explanatory comments (What/How comments) -> **REJECT** (see examples below)
- Unused code ("just in case" code) -> **REJECT** (see examples below)
- Direct state mutation (not immutable) -> **REJECT** (see examples below)
**Design principles:**
- Simple > Easy: Readability prioritized
- DRY: No more than 3 duplications
- YAGNI: Only what's needed now
- Fail Fast: Errors detected and reported early
- Idiomatic: Follows language/framework conventions
## Code Quality Detection
**Explanatory Comment (What/How) Detection Criteria:**
Comments must only explain design decisions not evident from code (Why), never restate what the code does (What/How). If the code is clear enough, no comment is needed at all.
Detect comments that simply restate code behavior in natural language.
| Judgment | Criteria |
|----------|----------|
| **REJECT** | Restates code behavior in natural language |
| **REJECT** | Repeats what is already obvious from function/variable names |
| **REJECT** | JSDoc that only paraphrases the function name without adding information |
| REJECT | Restates code behavior in natural language |
| REJECT | Repeats what is already obvious from function/variable names |
| REJECT | JSDoc that only paraphrases the function name without adding information |
| OK | Explains why a particular implementation was chosen |
| OK | Explains the reason behind seemingly unusual behavior |
| Best | No comment needed — the code itself communicates intent |
```typescript
// ❌ REJECT - Restates code (What)
// REJECT - Restates code (What)
// If interrupted, abort immediately
if (status === 'interrupted') {
return ABORT_STEP;
}
// ❌ REJECT - Restates the loop
// REJECT - Restates the loop
// Check transitions in order
for (const transition of step.transitions) {
// ❌ REJECT - Repeats the function name
// REJECT - Repeats the function name
/** Check if status matches transition condition. */
export function matchesCondition(status: Status, condition: TransitionCondition): boolean {
// ✅ OK - Design decision (Why)
// OK - Design decision (Why)
// User interruption takes priority over piece-defined transitions
if (status === 'interrupted') {
return ABORT_STEP;
}
// ✅ OK - Reason behind seemingly odd behavior
// OK - Reason behind seemingly odd behavior
// stay can cause loops, but is only used when explicitly specified by the user
return step.name;
// ✅ Best - No comment needed. Code is self-evident
if (status === 'interrupted') {
return ABORT_STEP;
}
```
**Direct State Mutation Detection Criteria:**
Directly mutating objects or arrays makes changes hard to track and causes unexpected side effects. Always use spread operators or immutable operations to return new objects.
Detect direct mutation of arrays or objects.
```typescript
// ❌ REJECT - Direct array mutation
// REJECT - Direct array mutation
const steps: Step[] = getSteps();
steps.push(newStep); // Mutates original array
steps.splice(index, 1); // Mutates original array
steps[0].status = 'done'; // Nested object also mutated directly
// ✅ OK - Immutable operations
// OK - Immutable operations
const withNew = [...steps, newStep];
const without = steps.filter((_, i) => i !== index);
const updated = steps.map((s, i) =>
i === 0 ? { ...s, status: 'done' } : s
);
// ❌ REJECT - Direct object mutation
// REJECT - Direct object mutation
function updateConfig(config: Config) {
config.logLevel = 'debug'; // Mutates argument directly
config.steps.push(newStep); // Nested mutation too
return config;
}
// ✅ OK - Returns new object
// OK - Returns new object
function updateConfig(config: Config): Config {
return {
...config,
@ -236,21 +160,21 @@ function updateConfig(config: Config): Config {
}
```
### 3. Security
## Security (Basic Checks)
- Injection prevention (SQL, Command, XSS)
- User input validation
- Hardcoded sensitive information
### 4. Testability
## Testability
- Dependency injection enabled
- Mockable design
- Tests are written
### 5. Anti-Pattern Detection
## Anti-Pattern Detection
**REJECT** when these patterns are found:
REJECT when these patterns are found:
| Anti-Pattern | Problem |
|--------------|---------|
@ -260,34 +184,18 @@ function updateConfig(config: Config): Config {
| Over-generalization | Variants and extension points not currently needed |
| Hidden Dependencies | Child components implicitly calling APIs etc. |
| Non-idiomatic | Custom implementation ignoring language/FW conventions |
| Logically dead defensive code | Guards for conditions already guaranteed by all callers |
**Logically dead defensive code:**
Call chain verification applies not only to "missing wiring" but also to the reverse — **unnecessary guards for conditions that callers already guarantee**.
| Pattern | Problem | Detection |
|---------|---------|-----------|
| TTY check when all callers require TTY | Unreachable branch remains | grep all callers' preconditions |
| Null guard when callers already check null | Redundant defense | Trace caller constraints |
| Runtime type check when TypeScript types constrain | Not trusting type safety | Check TypeScript type constraints |
**Verification:**
1. When you find a defensive branch (TTY check, null guard, etc.), grep all callers
2. If all callers already guarantee the condition, the guard is unnecessary → **REJECT**
3. If some callers don't guarantee it, keep the guard
### 6. Abstraction Level Evaluation
## Abstraction Level Evaluation
**Conditional Branch Proliferation Detection:**
| Pattern | Judgment |
|---------|----------|
| Same if-else pattern in 3+ places | Abstract with polymorphism → **REJECT** |
| Same if-else pattern in 3+ places | Abstract with polymorphism → REJECT |
| switch/case with 5+ branches | Consider Strategy/Map pattern |
| Flag arguments changing behavior | Split into separate functions → **REJECT** |
| Type-based branching (instanceof/typeof) | Replace with polymorphism → **REJECT** |
| Nested conditionals (3+ levels) | Early return or extract → **REJECT** |
| Flag arguments changing behavior | Split into separate functions → REJECT |
| Type-based branching (instanceof/typeof) | Replace with polymorphism → REJECT |
| Nested conditionals (3+ levels) | Early return or extract → REJECT |
**Abstraction Level Mismatch Detection:**
@ -301,7 +209,7 @@ Call chain verification applies not only to "missing wiring" but also to the rev
**Good Abstraction Examples:**
```typescript
// ❌ Proliferating conditionals
// Proliferating conditionals
function process(type: string) {
if (type === 'A') { /* process A */ }
else if (type === 'B') { /* process B */ }
@ -309,7 +217,7 @@ function process(type: string) {
// ...continues
}
// ✅ Abstract with Map pattern
// Abstract with Map pattern
const processors: Record<string, () => void> = {
A: processA,
B: processB,
@ -321,7 +229,7 @@ function process(type: string) {
```
```typescript
// ❌ Mixed abstraction levels
// Mixed abstraction levels
function createUser(data: UserData) {
// High level: business logic
validateUser(data);
@ -331,16 +239,16 @@ function createUser(data: UserData) {
conn.release();
}
// ✅ Aligned abstraction levels
// Aligned abstraction levels
function createUser(data: UserData) {
validateUser(data);
await userRepository.save(data); // Details hidden
}
```
### 7. Workaround Detection
## Workaround Detection
**Don't overlook compromises made to "just make it work."**
Don't overlook compromises made to "just make it work."
| Pattern | Example |
|---------|---------|
@ -351,13 +259,65 @@ function createUser(data: UserData) {
| Swallowed errors | Empty `catch {}`, `rescue nil` |
| Magic numbers | Unexplained `if (status == 3)` |
**Always point these out.** Temporary fixes become permanent.
## Strict TODO Comment Prohibition
### 8. Spec Compliance Verification
"We'll do it later" never gets done. What's not done now is never done.
**Verify that changes comply with the project's documented specifications.**
TODO comments are immediate REJECT.
**Verification targets:**
```kotlin
// REJECT - Future-looking TODO
// TODO: Add authorization check by facility ID
fun deleteCustomHoliday(@PathVariable id: String) {
deleteCustomHolidayInputPort.execute(input)
}
// APPROVE - Implement now
fun deleteCustomHoliday(@PathVariable id: String) {
val currentUserFacilityId = getCurrentUserFacilityId()
val holiday = findHolidayById(id)
require(holiday.facilityId == currentUserFacilityId) {
"Cannot delete holiday from another facility"
}
deleteCustomHolidayInputPort.execute(input)
}
```
Only acceptable TODO cases:
| Condition | Example | Judgment |
|-----------|---------|----------|
| External dependency prevents implementation + Issued | `// TODO(#123): Implement after API key obtained` | Acceptable |
| Technical constraint prevents + Issued | `// TODO(#456): Waiting for library bug fix` | Acceptable |
| "Future implementation", "add later" | `// TODO: Add validation` | REJECT |
| "No time for now" | `// TODO: Refactor` | REJECT |
Correct handling:
- Needed now → Implement now
- Not needed now → Delete the code
- External blocker → Create issue and include ticket number in comment
## DRY Violation Detection
Detect duplicate code.
| Pattern | Judgment |
|---------|----------|
| Same logic in 3+ places | Immediate REJECT - Extract to function/method |
| Same validation in 2+ places | Immediate REJECT - Extract to validator function |
| Similar components 3+ | Immediate REJECT - Create shared component |
| Copy-paste derived code | Immediate REJECT - Parameterize or abstract |
AHA principle (Avoid Hasty Abstractions) balance:
- 2 duplications → Wait and see
- 3 duplications → Extract immediately
- Different domain duplications → Don't abstract (e.g., customer validation vs admin validation are different)
## Spec Compliance Verification
Verify that changes comply with the project's documented specifications.
Verification targets:
| Target | What to Check |
|--------|---------------|
@ -365,7 +325,7 @@ function createUser(data: UserData) {
| Type definitions / Zod schemas | New fields reflected in schemas |
| YAML/JSON config files | Follows documented format |
**Specific checks:**
Specific checks:
1. When config files (YAML, etc.) are modified or added:
- Cross-reference with schema definitions in CLAUDE.md, etc.
@ -376,20 +336,59 @@ function createUser(data: UserData) {
- Documentation schema descriptions are updated
- Existing config files are compatible with new schema
3. When piece definitions are modified:
- Correct fields used for step type (normal vs. parallel)
- No unnecessary fields remaining (e.g., `next` on parallel sub-steps)
**REJECT when these patterns are found:**
REJECT when these patterns are found:
| Pattern | Problem |
|---------|---------|
| Fields not in the spec | Ignored or unexpected behavior |
| Invalid values per spec | Runtime error or silently ignored |
| Violation of documented constraints | Against design intent |
| Step type / field mismatch | Sign of copy-paste error |
### 9. Quality Attributes
## Call Chain Verification
When new parameters/fields are added, verify not just the changed file but also callers.
Verification steps:
1. When finding new optional parameters or interface fields, `Grep` all callers
2. Check if all callers pass the new parameter
3. If fallback value (`?? default`) exists, verify if fallback is used as intended
Danger patterns:
| Pattern | Problem | Detection |
|---------|---------|-----------|
| `options.xxx ?? fallback` where all callers omit `xxx` | Feature implemented but always falls back | grep callers |
| Tests set values directly with mocks | Don't go through actual call chain | Check test construction |
| `executeXxx()` doesn't receive `options` it uses internally | No route to pass value from above | Check function signature |
```typescript
// Missing wiring: No route to receive projectCwd
export async function executePiece(config, cwd, task) {
const engine = new PieceEngine(config, cwd, task); // No options
}
// Wired: Can pass projectCwd
export async function executePiece(config, cwd, task, options?) {
const engine = new PieceEngine(config, cwd, task, options);
}
```
Logically dead code due to caller constraints:
Call chain verification applies not only to "missing wiring" but also to the reverse — unnecessary guards for conditions that callers already guarantee.
| Pattern | Problem | Detection |
|---------|---------|-----------|
| TTY check when all callers require TTY | Unreachable branch remains | grep all callers' preconditions |
| Null guard when callers already check null | Redundant defense | Trace caller constraints |
| Runtime type check when TypeScript types constrain | Not trusting type safety | Check TypeScript type constraints |
Verification steps:
1. When finding defensive branches (TTY check, null guard, etc.), grep all callers
2. If all callers already guarantee the condition, guard is unnecessary → REJECT
3. If some callers don't guarantee it, keep the guard
## Quality Attributes
| Attribute | Review Point |
|-----------|--------------|
@ -397,9 +396,9 @@ function createUser(data: UserData) {
| Maintainability | Easy to modify and fix |
| Observability | Logging and monitoring enabled |
### 10. Big Picture
## Big Picture
**Caution**: Don't get lost in minor "clean code" nitpicks.
Don't get lost in minor "clean code" nitpicks.
Verify:
- How will this code evolve in the future
@ -408,31 +407,9 @@ Verify:
- Does it align with business requirements
- Is naming consistent with the domain
### 11. Boy Scout Rule
## Change Scope Assessment
**Leave the code better than you found it.** If changed files have structural issues, flag them for refactoring within the task scope.
**In scope:**
- Existing issues within changed files (dead code, poor naming, broken abstractions)
- Structural issues within changed modules (mixed responsibilities, unnecessary dependencies)
**Out of scope:**
- Issues in unchanged files (record as existing issues only)
- Refactoring that significantly exceeds the task scope (suggest as non-blocking)
**Judgment:**
| Situation | Judgment |
|-----------|----------|
| Clear issues within changed files | **REJECT** — require fix together |
| Structural issues within changed modules | **REJECT** — fix if within scope |
| Issues in unchanged files | Record only (non-blocking) |
**Following poor existing code as justification for leaving problems is not acceptable.** If existing code is bad, improve it rather than match it.
### 12. Change Scope Assessment
**Check change scope and include in report (non-blocking).**
Check change scope and include in report (non-blocking).
| Scope Size | Lines Changed | Action |
|------------|---------------|--------|
@ -440,44 +417,11 @@ Verify:
| Medium | 200-500 lines | Review as-is |
| Large | 500+ lines | Continue review. Suggest splitting if possible |
**Note:** Some tasks require large changes. Don't REJECT based on line count alone.
Note: Some tasks require large changes. Don't REJECT based on line count alone.
**Verify:**
Verify:
- Changes are logically cohesive (no unrelated changes mixed in)
- Coder's scope declaration matches actual changes
**Include as suggestions (non-blocking):**
Include as suggestions (non-blocking):
- If splittable, present splitting proposal
### 13. Circular Review Detection
When review count is provided (e.g., "Review count: 3rd"), adjust judgment accordingly.
**From the 3rd review onwards:**
1. Check if the same type of issues are recurring
2. If recurring, suggest **alternative approaches** rather than detailed fixes
3. Even when REJECTing, include perspective that "a different approach should be considered"
Example: When issues repeat on the 3rd review
- Point out the normal issues
- Note that the same type of issues are recurring
- Explain the limitations of the current approach
- Present alternatives (e.g., redesign with a different pattern, introduce new technology)
**Point**: Rather than repeating "fix this again", step back and suggest a different path.
## Important
**Be specific.** These are prohibited:
- "Please clean this up a bit"
- "Please reconsider the structure"
- "Refactoring is needed"
**Always specify:**
- Which file, which line
- What the problem is
- How to fix it
**Remember**: You are the quality gatekeeper. Poorly structured code destroys maintainability. Never let code that doesn't meet standards pass.

485
builtins/en/knowledge/backend.md Normal file
View File

@ -0,0 +1,485 @@
# Backend Expertise
## Hexagonal Architecture (Ports and Adapters)
Dependency direction flows from outer to inner layers. Reverse dependencies are prohibited.
```
adapter (external) → application (use cases) → domain (business logic)
```
Directory structure:
```
{domain-name}/
├── domain/ # Domain layer (framework-independent)
│ ├── model/
│ │ └── aggregate/ # Aggregate roots, value objects
│ └── service/ # Domain services
├── application/ # Application layer (use cases)
│ ├── usecase/ # Orchestration
│ └── query/ # Query handlers
├── adapter/ # Adapter layer (external connections)
│ ├── inbound/ # Input adapters
│ │ └── rest/ # REST Controller, Request/Response DTOs
│ └── outbound/ # Output adapters
│ └── persistence/ # Entity, Repository implementations
└── api/ # Public interface (referenceable by other domains)
└── events/ # Domain events
```
Layer responsibilities:
| Layer | Responsibility | May Depend On | Must Not Depend On |
|-------|---------------|---------------|-------------------|
| domain | Business logic, invariants | Standard library only | Frameworks, DB, external APIs |
| application | Use case orchestration | domain | Concrete adapter implementations |
| adapter/inbound | HTTP request handling, DTO conversion | application, domain | outbound adapter |
| adapter/outbound | DB persistence, external API calls | domain (interfaces) | application |
```kotlin
// CORRECT - Domain layer is framework-independent
data class Order(val orderId: String, val status: OrderStatus) {
fun confirm(confirmedBy: String): OrderConfirmedEvent {
require(status == OrderStatus.PENDING)
return OrderConfirmedEvent(orderId, confirmedBy)
}
}
// WRONG - Spring annotations in domain layer
@Entity
data class Order(
@Id val orderId: String,
@Enumerated(EnumType.STRING) val status: OrderStatus
) {
fun confirm(confirmedBy: String) { ... }
}
```
| Criteria | Judgment |
|----------|----------|
| Framework dependencies in domain layer (@Entity, @Component, etc.) | REJECT |
| Controller directly referencing Repository | REJECT. Must go through UseCase layer |
| Outward dependencies from domain layer (DB, HTTP, etc.) | REJECT |
| Direct dependencies between adapters (inbound → outbound) | REJECT |
## API Layer Design (Controller)
Keep Controllers thin. Their only job: receive request → delegate to UseCase → return response.
```kotlin
// CORRECT - Thin Controller
@RestController
@RequestMapping("/api/orders")
class OrdersController(
private val placeOrderUseCase: PlaceOrderUseCase,
private val queryGateway: QueryGateway
) {
// Command: state change
@PostMapping
@ResponseStatus(HttpStatus.CREATED)
fun post(@Valid @RequestBody request: OrderPostRequest): OrderPostResponse {
val output = placeOrderUseCase.execute(request.toInput())
return OrderPostResponse(output.orderId)
}
// Query: read
@GetMapping("/{id}")
fun get(@PathVariable id: String): ResponseEntity<OrderGetResponse> {
val detail = queryGateway.query(FindOrderQuery(id), OrderDetail::class.java).join()
?: return ResponseEntity.notFound().build()
return ResponseEntity.ok(OrderGetResponse.from(detail))
}
}
// WRONG - Business logic in Controller
@PostMapping
fun post(@RequestBody request: OrderPostRequest): ResponseEntity<Any> {
// Validation, stock check, calculation... should NOT be in Controller
val stock = inventoryRepository.findByProductId(request.productId)
if (stock.quantity < request.quantity) {
return ResponseEntity.badRequest().body("Insufficient stock")
}
val total = request.quantity * request.unitPrice * 1.1 // Tax calculation
orderRepository.save(OrderEntity(...))
return ResponseEntity.ok(...)
}
```
### Request/Response DTO Design
Define Request and Response as separate types. Never expose domain models directly via API.
```kotlin
// Request: validation annotations + init block
data class OrderPostRequest(
@field:NotBlank val customerId: String,
@field:NotNull val items: List<OrderItemRequest>
) {
init {
require(items.isNotEmpty()) { "Order must contain at least one item" }
}
fun toInput() = PlaceOrderInput(customerId = customerId, items = items.map { it.toItem() })
}
// Response: factory method from() for conversion
data class OrderGetResponse(
val orderId: String,
val status: String,
val customerName: String
) {
companion object {
fun from(detail: OrderDetail) = OrderGetResponse(
orderId = detail.orderId,
status = detail.status.name,
customerName = detail.customerName
)
}
}
```
| Criteria | Judgment |
|----------|----------|
| Returning domain model directly as response | REJECT |
| Business logic in Request DTO | REJECT. Only validation is allowed |
| Domain logic (calculations, etc.) in Response DTO | REJECT |
| Same type for Request and Response | REJECT |
### RESTful Action Design
Express state transitions as verb sub-resources.
```
POST /api/orders → Create order
GET /api/orders/{id} → Get order
GET /api/orders → List orders
POST /api/orders/{id}/approve → Approve (state transition)
POST /api/orders/{id}/cancel → Cancel (state transition)
```
| Criteria | Judgment |
|----------|----------|
| PUT/PATCH for domain operations (approve, cancel, etc.) | REJECT. Use POST + verb sub-resource |
| Single endpoint branching into multiple operations | REJECT. Separate endpoints per operation |
| DELETE for soft deletion | REJECT. Use POST + explicit operation like cancel |
## Validation Strategy
Validation has different roles at each layer. Do not centralize everything in one place.
| Layer | Responsibility | Mechanism | Example |
|-------|---------------|-----------|---------|
| API layer | Structural validation | `@NotBlank`, `init` block | Required fields, types, format |
| UseCase layer | Business rule verification | Read Model queries | Duplicate checks, precondition existence |
| Domain layer | State transition invariants | `require` | "Cannot approve unless PENDING" |
```kotlin
// API layer: "Is the input structurally correct?"
data class OrderPostRequest(
@field:NotBlank val customerId: String,
val from: LocalDateTime,
val to: LocalDateTime
) {
init {
require(!to.isBefore(from)) { "End date must be on or after start date" }
}
}
// UseCase layer: "Is this business-wise allowed?" (Read Model reference)
fun execute(input: PlaceOrderInput) {
customerRepository.findById(input.customerId)
?: throw CustomerNotFoundException("Customer does not exist")
validateNoOverlapping(input) // Duplicate check
commandGateway.send(buildCommand(input))
}
// Domain layer: "Is this operation allowed in current state?"
fun confirm(confirmedBy: String): OrderConfirmedEvent {
require(status == OrderStatus.PENDING) { "Cannot confirm in current state" }
return OrderConfirmedEvent(orderId, confirmedBy)
}
```
| Criteria | Judgment |
|----------|----------|
| Domain state transition rules in API layer | REJECT |
| Business rule verification in Controller | REJECT. Belongs in UseCase layer |
| Structural validation (@NotBlank, etc.) in domain | REJECT. Belongs in API layer |
| UseCase-level validation inside Aggregate | REJECT. Read Model queries belong in UseCase layer |
## Error Handling
### Exception Hierarchy Design
Domain exceptions are hierarchized using sealed classes. HTTP status code mapping is done at the Controller layer.
```kotlin
// Domain exceptions: sealed class ensures exhaustiveness
sealed class OrderException(message: String) : RuntimeException(message)
class OrderNotFoundException(message: String) : OrderException(message)
class InvalidOrderStateException(message: String) : OrderException(message)
class InsufficientStockException(message: String) : OrderException(message)
// Controller layer maps to HTTP status codes
@RestControllerAdvice
class OrderExceptionHandler {
@ExceptionHandler(OrderNotFoundException::class)
fun handleNotFound(e: OrderNotFoundException) =
ResponseEntity.status(HttpStatus.NOT_FOUND).body(ErrorResponse(e.message))
@ExceptionHandler(InvalidOrderStateException::class)
fun handleInvalidState(e: InvalidOrderStateException) =
ResponseEntity.status(HttpStatus.CONFLICT).body(ErrorResponse(e.message))
@ExceptionHandler(InsufficientStockException::class)
fun handleInsufficientStock(e: InsufficientStockException) =
ResponseEntity.status(HttpStatus.UNPROCESSABLE_ENTITY).body(ErrorResponse(e.message))
}
```
| Criteria | Judgment |
|----------|----------|
| HTTP status codes in domain exceptions | REJECT. Domain must not know about HTTP |
| Throwing generic Exception or RuntimeException | REJECT. Use specific exception types |
| Empty try-catch blocks | REJECT |
| Controller swallowing exceptions and returning 200 | REJECT |
## Domain Model Design
### Immutable + require
Domain models are designed as `data class` (immutable), with invariants enforced via `init` blocks and `require`.
```kotlin
data class Order(
val orderId: String,
val status: OrderStatus = OrderStatus.PENDING
) {
// Static factory method via companion object
companion object {
fun place(orderId: String, customerId: String): OrderPlacedEvent {
require(customerId.isNotBlank()) { "Customer ID cannot be blank" }
return OrderPlacedEvent(orderId, customerId)
}
}
// Instance method for state transition → returns event
fun confirm(confirmedBy: String): OrderConfirmedEvent {
require(status == OrderStatus.PENDING) { "Cannot confirm in current state" }
return OrderConfirmedEvent(orderId, confirmedBy, LocalDateTime.now())
}
// Immutable state update
fun apply(event: OrderEvent): Order = when (event) {
is OrderPlacedEvent -> Order(orderId = event.orderId)
is OrderConfirmedEvent -> copy(status = OrderStatus.CONFIRMED)
is OrderCancelledEvent -> copy(status = OrderStatus.CANCELLED)
}
}
```
| Criteria | Judgment |
|----------|----------|
| `var` fields in domain model | REJECT. Use `copy()` for immutable updates |
| Factory without validation | REJECT. Enforce invariants with `require` |
| Domain model calling external services | REJECT. Pure functions only |
| Direct field mutation via setters | REJECT |
### Value Objects
Wrap primitive types (String, Int) with domain meaning.
```kotlin
// ID types: prevent mix-ups via type safety
data class OrderId(@get:JsonValue val value: String) {
init { require(value.isNotBlank()) { "Order ID cannot be blank" } }
override fun toString(): String = value
}
// Range types: enforce compound invariants
data class DateRange(val from: LocalDateTime, val to: LocalDateTime) {
init { require(!to.isBefore(from)) { "End date must be on or after start date" } }
}
// Metadata types: ancillary information in event payloads
data class ApprovalInfo(val approvedBy: String, val approvalTime: LocalDateTime)
```
| Criteria | Judgment |
|----------|----------|
| Same-typed IDs that can be mixed up (orderId and customerId both String) | Consider wrapping in value objects |
| Same field combinations (from/to, etc.) appearing in multiple places | Extract to value object |
| Value object without init block | REJECT. Enforce invariants |
## Repository Pattern
Define interface in domain layer, implement in adapter/outbound.
```kotlin
// domain/: Interface (port)
interface OrderRepository {
fun findById(orderId: String): Order?
fun save(order: Order)
}
// adapter/outbound/persistence/: Implementation (adapter)
@Repository
class JpaOrderRepository(
private val jpaRepository: OrderJpaRepository
) : OrderRepository {
override fun findById(orderId: String): Order? {
return jpaRepository.findById(orderId).orElse(null)?.toDomain()
}
override fun save(order: Order) {
jpaRepository.save(OrderEntity.from(order))
}
}
```
### Read Model Entity (JPA Entity)
Read Model JPA Entities are defined separately from domain models. `var` (mutable) fields are acceptable here.
```kotlin
@Entity
@Table(name = "orders")
data class OrderEntity(
@Id val orderId: String,
var customerId: String,
@Enumerated(EnumType.STRING) var status: OrderStatus,
var metadata: String? = null
)
```
| Criteria | Judgment |
|----------|----------|
| Domain model doubling as JPA Entity | REJECT. Separate them |
| Business logic in Entity | REJECT. Entity is data structure only |
| Repository implementation in domain layer | REJECT. Belongs in adapter/outbound |
## Authentication & Authorization Placement
Authentication and authorization are cross-cutting concerns handled at the appropriate layer.
| Concern | Placement | Mechanism |
|---------|-----------|-----------|
| Authentication (who) | Filter / Interceptor layer | JWT verification, session validation |
| Authorization (permissions) | Controller layer | `@PreAuthorize("hasRole('ADMIN')")` |
| Data access control (own data only) | UseCase layer | Verified as business rule |
```kotlin
// Controller layer: role-based authorization
@PostMapping("/{id}/approve")
@PreAuthorize("hasRole('FACILITY_ADMIN')")
fun approve(@PathVariable id: String, @RequestBody request: ApproveRequest) { ... }
// UseCase layer: data access control
fun execute(input: DeleteInput, currentUserId: String) {
val entity = repository.findById(input.id)
?: throw NotFoundException("Not found")
require(entity.ownerId == currentUserId) { "Cannot operate on another user's data" }
// ...
}
```
| Criteria | Judgment |
|----------|----------|
| Authorization logic in UseCase or domain layer | REJECT. Belongs in Controller layer |
| Data access control in Controller | REJECT. Belongs in UseCase layer |
| Authentication processing inside Controller | REJECT. Belongs in Filter/Interceptor |
## Test Strategy
### Test Pyramid
```
┌─────────────┐
│ E2E Test │ ← Few: verify full API flow
├─────────────┤
│ Integration │ ← Repository, Controller integration verification
├─────────────┤
│ Unit Test │ ← Many: independent tests for domain models, UseCases
└─────────────┘
```
### Domain Model Testing
Domain models are framework-independent, enabling pure unit tests.
```kotlin
class OrderTest {
// Helper: build aggregate in specific state
private fun pendingOrder(): Order {
val event = Order.place("order-1", "customer-1")
return Order.from(event)
}
@Nested
inner class Confirm {
@Test
fun `can confirm from PENDING state`() {
val order = pendingOrder()
val event = order.confirm("admin-1")
assertEquals("order-1", event.orderId)
}
@Test
fun `cannot confirm from CONFIRMED state`() {
val order = pendingOrder().let { it.apply(it.confirm("admin-1")) }
assertThrows<IllegalArgumentException> {
order.confirm("admin-2")
}
}
}
}
```
Testing rules:
- Build state transitions via helper methods (each test is independent)
- Group by operation using `@Nested`
- Test both happy path and error cases (invalid state transitions)
- Verify exception types with `assertThrows`
### UseCase Testing
Test UseCases with mocks. Inject external dependencies.
```kotlin
class PlaceOrderUseCaseTest {
private val commandGateway = mockk<CommandGateway>()
private val customerRepository = mockk<CustomerRepository>()
private val useCase = PlaceOrderUseCase(commandGateway, customerRepository)
@Test
fun `throws error when customer does not exist`() {
every { customerRepository.findById("unknown") } returns null
assertThrows<CustomerNotFoundException> {
useCase.execute(PlaceOrderInput(customerId = "unknown", items = listOf(...)))
}
}
}
```
| Criteria | Judgment |
|----------|----------|
| Using mocks for domain model tests | REJECT. Test domain purely |
| UseCase tests connecting to real DB | REJECT. Use mocks |
| Tests requiring framework startup | REJECT for unit tests |
| Missing error case tests for state transitions | REJECT |
## Anti-Pattern Detection
REJECT when these patterns are found:
| Anti-Pattern | Problem |
|--------------|---------|
| Smart Controller | Business logic concentrated in Controller |
| Anemic Domain Model | Domain model is just a data structure with setters/getters |
| God Service | All operations concentrated in a single Service class |
| Direct Repository Access | Controller directly referencing Repository |
| Domain Leakage | Domain logic leaking into adapter layer |
| Entity Reuse | JPA Entity reused as domain model |
| Swallowed Exceptions | Empty catch blocks |
| Magic Strings | Hardcoded status strings, etc. |

417
builtins/en/knowledge/cqrs-es.md Normal file
View File

@ -0,0 +1,417 @@
# CQRS+ES Knowledge
## Aggregate Design
Aggregates hold only fields necessary for decision-making.
Command Model (Aggregate) role is to "receive commands, make decisions, and emit events". Query data is handled by Read Model (Projection).
"Necessary for decision" means:
- Used in `if`/`require` conditional branches
- Field value referenced when emitting events in instance methods
| Criteria | Judgment |
|----------|----------|
| Aggregate spans multiple transaction boundaries | REJECT |
| Direct references between Aggregates (not ID references) | REJECT |
| Aggregate exceeds 100 lines | Consider splitting |
| Business invariants exist outside Aggregate | REJECT |
| Holding fields not used for decisions | REJECT |
Good Aggregate:
```kotlin
// Only fields necessary for decisions
data class Order(
val orderId: String, // Used when emitting events
val status: OrderStatus // Used for state checking
) {
fun confirm(confirmedBy: String): OrderConfirmedEvent {
require(status == OrderStatus.PENDING) { "Cannot confirm in this state" }
return OrderConfirmedEvent(
orderId = orderId,
confirmedBy = confirmedBy,
confirmedAt = LocalDateTime.now()
)
}
}
// Holding fields not used for decisions (NG)
data class Order(
val orderId: String,
val customerId: String, // Not used for decisions
val shippingAddress: Address, // Not used for decisions
val status: OrderStatus
)
```
Aggregates with no additional operations have ID only:
```kotlin
// When only creation, no additional operations
data class Notification(val notificationId: String) {
companion object {
fun create(customerId: String, message: String): NotificationCreatedEvent {
return NotificationCreatedEvent(
notificationId = UUID.randomUUID().toString(),
customerId = customerId,
message = message
)
}
}
}
```
## Event Design
| Criteria | Judgment |
|----------|----------|
| Event not in past tense (Created → Create) | REJECT |
| Event contains logic | REJECT |
| Event contains internal state of other Aggregates | REJECT |
| Event schema not version controlled | Warning |
| CRUD-style events (Updated, Deleted) | Needs review |
Good Events:
```kotlin
// Good: Domain intent is clear
OrderPlaced, PaymentReceived, ItemShipped
// Bad: CRUD style
OrderUpdated, OrderDeleted
```
Event Granularity:
- Too fine: `OrderFieldChanged` → Domain intent unclear
- Appropriate: `ShippingAddressChanged` → Intent is clear
- Too coarse: `OrderModified` → What changed is unclear
## Command Handlers
| Criteria | Judgment |
|----------|----------|
| Handler directly manipulates DB | REJECT |
| Handler modifies multiple Aggregates | REJECT |
| No command validation | REJECT |
| Handler executes queries to make decisions | Needs review |
Good Command Handler:
```
1. Receive command
2. Restore Aggregate from event store
3. Apply command to Aggregate
4. Save emitted events
```
## Projection Design
| Criteria | Judgment |
|----------|----------|
| Projection issues commands | REJECT |
| Projection references Write model | REJECT |
| Single projection serves multiple use cases | Needs review |
| Design that cannot be rebuilt | REJECT |
Good Projection:
- Optimized for specific read use case
- Idempotently reconstructible from events
- Completely independent from Write model
## Query Side Design
Controller uses QueryGateway. Does not use Repository directly.
Types between layers:
- `application/query/` - Query result types (e.g., `OrderDetail`)
- `adapter/protocol/` - REST response types (e.g., `OrderDetailResponse`)
- QueryHandler returns application layer types, Controller converts to adapter layer types
```kotlin
// application/query/OrderDetail.kt
data class OrderDetail(
val orderId: String,
val customerName: String,
val totalAmount: Money
)
// adapter/protocol/OrderDetailResponse.kt
data class OrderDetailResponse(...) {
companion object {
fun from(detail: OrderDetail) = OrderDetailResponse(...)
}
}
// QueryHandler - returns application layer type
@QueryHandler
fun handle(query: GetOrderDetailQuery): OrderDetail? {
val entity = repository.findById(query.id) ?: return null
return OrderDetail(...)
}
// Controller - converts to adapter layer type
@GetMapping("/{id}")
fun getById(@PathVariable id: String): ResponseEntity<OrderDetailResponse> {
val detail = queryGateway.query(
GetOrderDetailQuery(id),
OrderDetail::class.java
).join() ?: throw NotFoundException("...")
return ResponseEntity.ok(OrderDetailResponse.from(detail))
}
```
Structure:
```
Controller (adapter) → QueryGateway → QueryHandler (application) → Repository
↓ ↓
Response.from(detail) OrderDetail
```
## Eventual Consistency
| Situation | Response |
|-----------|----------|
| UI expects immediate updates | Redesign or polling/WebSocket |
| Consistency delay exceeds tolerance | Reconsider architecture |
| Compensating transactions undefined | Request failure scenario review |
## Saga vs EventHandler
Saga is used only for "operations between multiple aggregates where contention occurs".
Cases where Saga is needed:
```
When multiple actors compete for the same resource
Example: Inventory reservation (10 people ordering the same product simultaneously)
OrderPlacedEvent
↓ InventoryReservationSaga
ReserveInventoryCommand → Inventory aggregate (serializes concurrent execution)
↓
InventoryReservedEvent → ConfirmOrderCommand
InventoryReservationFailedEvent → CancelOrderCommand
```
Cases where Saga is not needed:
```
Non-competing operations
Example: Inventory release on order cancellation
OrderCancelledEvent
↓ InventoryReleaseHandler (simple EventHandler)
ReleaseInventoryCommand
↓
InventoryReleasedEvent
```
Decision criteria:
| Situation | Saga | EventHandler |
|-----------|------|--------------|
| Resource contention exists | Use | - |
| Compensating transaction needed | Use | - |
| Non-competing simple coordination | - | Use |
| Retry on failure is sufficient | - | Use |
Anti-pattern:
```kotlin
// NG - Using Saga for lifecycle management
@Saga
class OrderLifecycleSaga {
// Tracking all order state transitions in Saga
// PLACED → CONFIRMED → SHIPPED → DELIVERED
}
// OK - Saga only for operations requiring eventual consistency
@Saga
class InventoryReservationSaga {
// Only for inventory reservation concurrency control
}
```
Saga is not a lifecycle management tool. Create it per "operation" that requires eventual consistency.
## Exception vs Event (Failure Handling)
Failures not requiring audit use exceptions, failures requiring audit use events.
Exception approach (recommended: most cases):
```kotlin
// Domain model: Throws exception on validation failure
fun reserveInventory(orderId: String, quantity: Int): InventoryReservedEvent {
if (availableQuantity < quantity) {
throw InsufficientInventoryException("Insufficient inventory")
}
return InventoryReservedEvent(productId, orderId, quantity)
}
// Saga: Catch with exceptionally and perform compensating action
commandGateway.send<Any>(command)
.exceptionally { ex ->
commandGateway.send<Any>(CancelOrderCommand(
orderId = orderId,
reason = ex.cause?.message ?: "Inventory reservation failed"
))
null
}
```
Event approach (rare cases):
```kotlin
// Only when audit is required
data class PaymentFailedEvent(
val paymentId: String,
val reason: String,
val attemptedAmount: Money
) : PaymentEvent
```
Decision criteria:
| Question | Exception | Event |
|----------|-----------|-------|
| Need to check this failure later? | No | Yes |
| Required by regulations/compliance? | No | Yes |
| Only Saga cares about the failure? | Yes | No |
| Is there value in keeping it in Event Store? | No | Yes |
Default is exception approach. Consider events only when audit requirements exist.
## Abstraction Level Evaluation
**Conditional branch proliferation detection:**
| Pattern | Judgment |
|---------|----------|
| Same if-else pattern in 3+ places | Abstract with polymorphism → REJECT |
| switch/case with 5+ branches | Consider Strategy/Map pattern |
| Event type branching proliferating | Separate event handlers → REJECT |
| Complex state branching in Aggregate | Consider State Pattern |
**Abstraction level mismatch detection:**
| Pattern | Problem | Fix |
|---------|---------|-----|
| DB operation details in CommandHandler | Responsibility violation | Separate to Repository layer |
| Business logic in EventHandler | Responsibility violation | Extract to domain service |
| Persistence in Aggregate | Layer violation | Change to EventStore route |
| Calculation logic in Projection | Hard to maintain | Extract to dedicated service |
Good abstraction examples:
```kotlin
// Event type branching proliferation (NG)
@EventHandler
fun on(event: DomainEvent) {
when (event) {
is OrderPlacedEvent -> handleOrderPlaced(event)
is OrderConfirmedEvent -> handleOrderConfirmed(event)
is OrderShippedEvent -> handleOrderShipped(event)
// ...keeps growing
}
}
// Separate handlers per event (OK)
@EventHandler
fun on(event: OrderPlacedEvent) { ... }
@EventHandler
fun on(event: OrderConfirmedEvent) { ... }
@EventHandler
fun on(event: OrderShippedEvent) { ... }
```
```kotlin
// Complex state branching (NG)
fun process(command: ProcessCommand) {
when (status) {
PENDING -> if (command.type == "approve") { ... } else if (command.type == "reject") { ... }
APPROVED -> if (command.type == "ship") { ... }
// ...gets complex
}
}
// Abstracted with State Pattern (OK)
sealed class OrderState {
abstract fun handle(command: ProcessCommand): List<DomainEvent>
}
class PendingState : OrderState() {
override fun handle(command: ProcessCommand) = when (command) {
is ApproveCommand -> listOf(OrderApprovedEvent(...))
is RejectCommand -> listOf(OrderRejectedEvent(...))
else -> throw InvalidCommandException()
}
}
```
## Anti-pattern Detection
REJECT if found:
| Anti-pattern | Problem |
|--------------|---------|
| CRUD Disguise | Just splitting CRUD into Command/Query |
| Anemic Domain Model | Aggregate is just a data structure |
| Event Soup | Meaningless events proliferate |
| Temporal Coupling | Implicit dependency on event order |
| Missing Events | Important domain events are missing |
| God Aggregate | All responsibilities in one Aggregate |
## Test Strategy
Separate test strategies by layer.
Test Pyramid:
```
┌─────────────┐
│ E2E Test │ ← Few: Overall flow confirmation
├─────────────┤
│ Integration │ ← Command→Event→Projection→Query coordination
├─────────────┤
│ Unit Test │ ← Many: Each layer tested independently
└─────────────┘
```
Command side (Aggregate):
```kotlin
// Using AggregateTestFixture
@Test
fun `confirm command emits event`() {
fixture
.given(OrderPlacedEvent(...))
.`when`(ConfirmOrderCommand(orderId, confirmedBy))
.expectSuccessfulHandlerExecution()
.expectEvents(OrderConfirmedEvent(...))
}
```
Query side:
```kotlin
// Direct Read Model setup + QueryGateway
@Test
fun `can get order details`() {
// Given: Setup Read Model directly
orderRepository.save(OrderEntity(...))
// When: Execute query via QueryGateway
val detail = queryGateway.query(GetOrderDetailQuery(orderId), ...).join()
// Then
assertEquals(expectedDetail, detail)
}
```
Checklist:
| Aspect | Judgment |
|--------|----------|
| Aggregate tests verify events not state | Required |
| Query side tests don't create data via Command | Recommended |
| Integration tests consider Axon async processing | Required |
## Infrastructure Layer
Check:
- Is event store choice appropriate?
- Does messaging infrastructure meet requirements?
- Is snapshot strategy defined?
- Is event serialization format appropriate?

179
resources/global/en/agents/expert/frontend-reviewer.md → builtins/en/knowledge/frontend.md
View File

@ -1,52 +1,16 @@
# Frontend Reviewer
# Frontend Knowledge
You are an expert in **Frontend Development**.
## Component Design
You review code from the perspective of modern frontend technologies (React, Vue, Angular, Svelte, etc.), state management, performance optimization, accessibility, and UX.
Do not write everything in one file. Always split components.
## Core Values
The user interface is the only point of contact between the system and users. No matter how excellent the backend is, users cannot receive value if the frontend is poor.
"Fast, usable, and resilient"—that is the mission of frontend development.
## Areas of Expertise
### Component Design
- Separation of concerns and component granularity
- Props design and data flow
- Reusability and extensibility
### State Management
- Local vs global state decisions
- State normalization and caching strategies
- Async state handling
### Performance
- Rendering optimization
- Bundle size management
- Memory leak prevention
### UX/Accessibility
- Usability principles
- WAI-ARIA compliance
- Responsive design
## Review Criteria
### 1. Component Design
**Principle: Do not write everything in one file. Always split components.**
**Required splits:**
Required splits:
- Has its own state → Must split
- JSX over 50 lines → Split
- Reusable → Split
- Multiple responsibilities → Split
- Independent section within page → Split
**Required Checks:**
| Criteria | Judgment |
|----------|----------|
| Component over 200 lines | Consider splitting |
@ -55,12 +19,12 @@ The user interface is the only point of contact between the system and users. No
| Props drilling (3+ levels) | Consider state management |
| Component with multiple responsibilities | REJECT |
**Good Component:**
Good Component:
- Single responsibility: Does one thing well
- Self-contained: Dependencies are clear
- Testable: Side effects are isolated
**Component Classification:**
Component Classification:
| Type | Responsibility | Example |
|------|----------------|---------|
@ -69,7 +33,7 @@ The user interface is the only point of contact between the system and users. No
| Layout | Arrangement, structure | `PageLayout`, `Grid` |
| Utility | Common functionality | `ErrorBoundary`, `Portal` |
**Directory Structure:**
Directory Structure:
```
features/{feature-name}/
├── components/
@ -81,9 +45,9 @@ features/{feature-name}/
└── index.ts
```
### 2. State Management
## State Management
**Principle: Child components do not modify their own state. They bubble events to parent, and parent manipulates state.**
Child components do not modify their own state. They bubble events to parent, and parent manipulates state.
```tsx
// ❌ Child modifies its own state
@ -103,12 +67,10 @@ const Parent = () => {
}
```
**Exception (OK for child to have local state):**
Exception (OK for child to have local state):
- UI-only temporary state (hover, focus, animation)
- Completely local state that doesn't need to be communicated to parent
**Required Checks:**
| Criteria | Judgment |
|----------|----------|
| Unnecessary global state | Consider localizing |
@ -117,7 +79,7 @@ const Parent = () => {
| API response stored as-is in state | Consider normalization |
| Inappropriate useEffect dependencies | REJECT |
**State Placement Guidelines:**
State Placement Guidelines:
| State Nature | Recommended Placement |
|--------------|----------------------|
@ -126,9 +88,9 @@ const Parent = () => {
| Shared across multiple components | Context or state management library |
| Server data cache | Data fetching library (TanStack Query, etc.) |
### 3. Data Fetching
## Data Fetching
**Principle: API calls are made in root (View) components and passed to children via props.**
API calls are made in root (View) components and passed to children via props.
```tsx
// ✅ CORRECT - Fetch at root, pass to children
@ -155,12 +117,7 @@ const OrderSummary = ({ orderId }) => {
}
```
**Reasons:**
- Data flow is explicit and traceable
- Child components are pure presentation (easier to test)
- No hidden dependencies in child components
**When UI state changes affect parameters (week switching, filters, etc.):**
When UI state changes affect parameters (week switching, filters, etc.):
Manage state at View level and pass callbacks to components.
@ -190,7 +147,7 @@ const WeeklyCalendar = ({ facilityId }) => {
}
```
**Exceptions (component-level fetching allowed):**
Exceptions (component-level fetching allowed):
| Case | Reason |
|------|--------|
@ -200,9 +157,7 @@ const WeeklyCalendar = ({ facilityId }) => {
| Real-time updates | WebSocket/Polling auto-updates |
| Modal detail fetch | Fetch additional data only when opened |
**Decision criteria: "Is there no point in parent managing this / Does it not affect parent?"**
**Required Checks:**
Decision criteria: "Is there no point in parent managing this / Does it not affect parent?"
| Criteria | Judgment |
|----------|----------|
@ -212,9 +167,9 @@ const WeeklyCalendar = ({ facilityId }) => {
| No cancellation handling | Warning |
| N+1 query-like fetching | REJECT |
### 4. Shared Components and Abstraction
## Shared Components and Abstraction
**Principle: Common UI patterns should be shared components. Copy-paste of inline styles is prohibited.**
Common UI patterns should be shared components. Copy-paste of inline styles is prohibited.
```tsx
// ❌ WRONG - Copy-pasted inline styles
@ -228,7 +183,7 @@ const WeeklyCalendar = ({ facilityId }) => {
</IconButton>
```
**Patterns to make shared components:**
Patterns to make shared components:
- Icon buttons (close, edit, delete, etc.)
- Loading/error displays
- Status badges
@ -237,7 +192,7 @@ const WeeklyCalendar = ({ facilityId }) => {
- Search input
- Color legends
**Avoid over-generalization:**
Avoid over-generalization:
```tsx
// ❌ WRONG - Forcing stepper variant into IconButton
@ -264,12 +219,12 @@ export function StepperButton(props) {
}
```
**Signs to make separate components:**
Signs to make separate components:
- Implicit constraints like "this variant is always with this size"
- Added variant is clearly different from original component's purpose
- Props specification becomes complex on the usage side
### 5. Abstraction Level Evaluation
## Abstraction Level Evaluation
**Conditional branch bloat detection:**
@ -289,7 +244,8 @@ export function StepperButton(props) {
| Style calculation logic scattered | Hard to maintain | Extract to utility function |
| Same transformation in multiple places | DRY violation | Extract to common function |
**Good abstraction examples:**
Good abstraction examples:
```tsx
// ❌ Conditional bloat
function UserBadge({ user }) {
@ -343,11 +299,11 @@ function OrderList() {
}
```
### 6. Frontend and Backend Separation of Concerns
## Frontend and Backend Separation of Concerns
#### 6.1 Display Format Responsibility
### Display Format Responsibility
**Principle: Backend returns "data", frontend converts to "display format".**
Backend returns "data", frontend converts to "display format".
```tsx
// ✅ Frontend: Convert to display format
@ -360,36 +316,27 @@ export function formatDate(date: Date): string {
}
```
**Reasons:**
- Display format is a UI concern, not backend responsibility
- Easy to support internationalization
- Frontend can flexibly change display
**Required Checks:**
| Criteria | Judgment |
|----------|----------|
| Backend returns display strings | Suggest design review |
| Same format logic copy-pasted | Unify to utility function |
| Inline formatting in component | Extract to function |
#### 6.2 Domain Logic Placement (Smart UI Elimination)
### Domain Logic Placement (Smart UI Elimination)
**Principle: Domain logic (business rules) belongs in the backend. Frontend only displays and edits state.**
Domain logic (business rules) belongs in the backend. Frontend only displays and edits state.
**What is domain logic:**
What is domain logic:
- Aggregate business rules (stock validation, price calculation, status transitions)
- Business constraint validation
- Invariant enforcement
**Frontend responsibilities:**
Frontend responsibilities:
- Display state received from server
- Collect user input and send commands to backend
- Manage UI-only temporary state (focus, hover, modal open/close)
- Display format conversion (formatting, sorting, filtering)
**Required Checks:**
| Criteria | Judgment |
|----------|----------|
| Price calculation/stock validation in frontend | Move to backend → **REJECT** |
@ -397,7 +344,7 @@ export function formatDate(date: Date): string {
| Business validation in frontend | Move to backend → **REJECT** |
| Recalculating server-computable values in frontend | Redundant → **REJECT** |
**Good vs Bad Examples:**
Good vs Bad Examples:
```tsx
// ❌ BAD - Business rules in frontend
@ -451,7 +398,7 @@ function TaskCard({ task }: { task: Task }) {
}
```
**Exceptions (OK to have logic in frontend):**
Exceptions (OK to have logic in frontend):
| Case | Reason |
|------|--------|
@ -460,13 +407,11 @@ function TaskCard({ task }: { task: Task }) {
| Display condition branching | UI control like "show details if logged in" |
| Real-time feedback | Preview display during input |
**Decision criteria: "Would the business break if this calculation differs from the server?"**
Decision criteria: "Would the business break if this calculation differs from the server?"
- YES → Place in backend (domain logic)
- NO → OK in frontend (display logic)
### 7. Performance
**Required Checks:**
## Performance
| Criteria | Judgment |
|----------|----------|
@ -476,13 +421,13 @@ function TaskCard({ task }: { task: Task }) {
| Unused code in bundle | Check tree-shaking |
| Excessive memoization | Verify necessity |
**Optimization Checklist:**
- [ ] Are `React.memo` / `useMemo` / `useCallback` appropriate?
- [ ] Are large lists using virtual scroll?
- [ ] Is Code Splitting appropriate?
- [ ] Are images lazy loaded?
Optimization Checklist:
- Are `React.memo` / `useMemo` / `useCallback` appropriate?
- Are large lists using virtual scroll?
- Is Code Splitting appropriate?
- Are images lazy loaded?
**Anti-patterns:**
Anti-patterns:
```tsx
// ❌ New object every render
@ -493,9 +438,7 @@ const style = useMemo(() => ({ color: 'red' }), []);
<Child style={style} />
```
### 8. Accessibility
**Required Checks:**
## Accessibility
| Criteria | Judgment |
|----------|----------|
@ -505,16 +448,14 @@ const style = useMemo(() => ({ color: 'red' }), []);
| Information conveyed by color only | REJECT |
| Missing focus management (modals, etc.) | REJECT |
**Checklist:**
- [ ] Using semantic HTML?
- [ ] Are ARIA attributes appropriate (not excessive)?
- [ ] Is keyboard navigation possible?
- [ ] Does it make sense with a screen reader?
- [ ] Is color contrast sufficient?
Checklist:
- Using semantic HTML?
- Are ARIA attributes appropriate (not excessive)?
- Is keyboard navigation possible?
- Does it make sense with a screen reader?
- Is color contrast sufficient?
### 9. TypeScript/Type Safety
**Required Checks:**
## TypeScript/Type Safety
| Criteria | Judgment |
|----------|----------|
@ -523,9 +464,7 @@ const style = useMemo(() => ({ color: 'red' }), []);
| No Props type definition | REJECT |
| Inappropriate event handler types | Needs fix |
### 10. Frontend Security
**Required Checks:**
## Frontend Security
| Criteria | Judgment |
|----------|----------|
@ -534,9 +473,7 @@ const style = useMemo(() => ({ color: 'red' }), []);
| Sensitive data stored in frontend | REJECT |
| CSRF token not used | Needs verification |
### 11. Testability
**Required Checks:**
## Testability
| Criteria | Judgment |
|----------|----------|
@ -544,9 +481,9 @@ const style = useMemo(() => ({ color: 'red' }), []);
| Structure difficult to test | Consider separation |
| Business logic embedded in UI | REJECT |
### 12. Anti-pattern Detection
## Anti-pattern Detection
**REJECT** if found:
REJECT if found:
| Anti-pattern | Problem |
|--------------|---------|
@ -558,13 +495,3 @@ const style = useMemo(() => ({ color: 'red' }), []);
| Magic Strings | Hardcoded strings |
| Hidden Dependencies | Child components with hidden API calls |
| Over-generalization | Components forced to be generic |
## Important
- **Prioritize user experience**: UX over technical correctness
- **Performance can't be fixed later**: Consider at design stage
- **Accessibility is hard to retrofit**: Build in from the start
- **Beware excessive abstraction**: Keep it simple
- **Follow framework conventions**: Standard approaches over custom patterns
- **Data fetching at root**: Don't create hidden dependencies in children
- **Controlled components**: Data flow is unidirectional

164
builtins/en/knowledge/security.md Normal file
View File

@ -0,0 +1,164 @@
# Security Knowledge
## AI-Generated Code Security Issues
AI-generated code has unique vulnerability patterns.
| Pattern | Risk | Example |
|---------|------|---------|
| Plausible but dangerous defaults | High | `cors: { origin: '*' }` looks fine but is dangerous |
| Outdated security practices | Medium | Using deprecated encryption, old auth patterns |
| Incomplete validation | High | Validates format but not business rules |
| Over-trusting inputs | Critical | Assumes internal APIs are always safe |
| Copy-paste vulnerabilities | High | Same dangerous pattern repeated in multiple files |
Require extra scrutiny:
- Auth/authorization logic (AI tends to miss edge cases)
- Input validation (AI may check syntax but miss semantics)
- Error messages (AI may expose internal details)
- Config files (AI may use dangerous defaults from training data)
## Injection Attacks
**SQL Injection:**
- SQL construction via string concatenation → REJECT
- Not using parameterized queries → REJECT
- Unsanitized input in ORM raw queries → REJECT
```typescript
// NG
db.query(`SELECT * FROM users WHERE id = ${userId}`)
// OK
db.query('SELECT * FROM users WHERE id = ?', [userId])
```
**Command Injection:**
- Unvalidated input in `exec()`, `spawn()` → REJECT
- Insufficient escaping in shell command construction → REJECT
```typescript
// NG
exec(`ls ${userInput}`)
// OK
execFile('ls', [sanitizedInput])
```
**XSS (Cross-Site Scripting):**
- Unescaped output to HTML/JS → REJECT
- Improper use of `innerHTML`, `dangerouslySetInnerHTML` → REJECT
- Direct embedding of URL parameters → REJECT
## Authentication & Authorization
**Authentication issues:**
- Hardcoded credentials → Immediate REJECT
- Plaintext password storage → Immediate REJECT
- Weak hash algorithms (MD5, SHA1) → REJECT
- Improper session token management → REJECT
**Authorization issues:**
- Missing permission checks → REJECT
- IDOR (Insecure Direct Object Reference) → REJECT
- Privilege escalation possibility → REJECT
```typescript
// NG - No permission check
app.get('/user/:id', (req, res) => {
return db.getUser(req.params.id)
})
// OK
app.get('/user/:id', authorize('read:user'), (req, res) => {
if (req.user.id !== req.params.id && !req.user.isAdmin) {
return res.status(403).send('Forbidden')
}
return db.getUser(req.params.id)
})
```
## Data Protection
**Sensitive information exposure:**
- Hardcoded API keys, secrets → Immediate REJECT
- Sensitive info in logs → REJECT
- Internal info exposure in error messages → REJECT
- Committed `.env` files → REJECT
**Data validation:**
- Unvalidated input values → REJECT
- Missing type checks → REJECT
- No size limits set → REJECT
## Cryptography
- Use of weak crypto algorithms → REJECT
- Fixed IV/Nonce usage → REJECT
- Hardcoded encryption keys → Immediate REJECT
- No HTTPS (production) → REJECT
## File Operations
**Path Traversal:**
- File paths containing user input → REJECT
- Insufficient `../` sanitization → REJECT
```typescript
// NG
const filePath = path.join(baseDir, userInput)
fs.readFile(filePath)
// OK
const safePath = path.resolve(baseDir, userInput)
if (!safePath.startsWith(path.resolve(baseDir))) {
throw new Error('Invalid path')
}
```
**File Upload:**
- No file type validation → REJECT
- No file size limits → REJECT
- Allowing executable file uploads → REJECT
## Dependencies
- Packages with known vulnerabilities → REJECT
- Unmaintained packages → Warning
- Unnecessary dependencies → Warning
## Error Handling
- Stack trace exposure in production → REJECT
- Detailed error message exposure → REJECT
- Swallowing security events → REJECT
## Rate Limiting & DoS Protection
- No rate limiting (auth endpoints) → Warning
- Resource exhaustion attack possibility → Warning
- Infinite loop possibility → REJECT
## OWASP Top 10 Checklist
| Category | Check Items |
|----------|-------------|
| A01 Broken Access Control | Authorization checks, CORS config |
| A02 Cryptographic Failures | Encryption, sensitive data protection |
| A03 Injection | SQL, Command, XSS |
| A04 Insecure Design | Security design patterns |
| A05 Security Misconfiguration | Default settings, unnecessary features |
| A06 Vulnerable Components | Dependency vulnerabilities |
| A07 Auth Failures | Authentication mechanisms |
| A08 Software Integrity | Code signing, CI/CD |
| A09 Logging Failures | Security logging |
| A10 SSRF | Server-side requests |

25
builtins/en/output-contracts/ai-review.md Normal file
View File

@ -0,0 +1,25 @@
```markdown
# AI-Generated Code Review
## Result: APPROVE / REJECT
## Summary
{Summarize the result in one sentence}
## Verified Items
| Aspect | Result | Notes |
|--------|--------|-------|
| Validity of assumptions | ✅ | - |
| API/library existence | ✅ | - |
| Context fit | ✅ | - |
| Scope | ✅ | - |
## Issues (if REJECT)
| # | Category | Location | Issue |
|---|----------|----------|-------|
| 1 | Hallucinated API | `src/file.ts:23` | Non-existent method |
```
**Cognitive load reduction rules:**
- No issues → Summary sentence + checklist only (10 lines or fewer)
- Issues found → + Issues in table format (25 lines or fewer)

22
builtins/en/output-contracts/architecture-design.md Normal file
View File

@ -0,0 +1,22 @@
```markdown
# Architecture Design
## Task Size
Small / Medium / Large
## Design Decisions
### File Structure
| File | Role |
|------|------|
| `src/example.ts` | Overview |
### Technology Selection
- {Selected technologies/libraries and rationale}
### Design Patterns
- {Adopted patterns and where they apply}
## Implementation Guidelines
- {Guidelines the Coder should follow during implementation}
```

30
builtins/en/output-contracts/architecture-review.md Normal file
View File

@ -0,0 +1,30 @@
```markdown
# Architecture Review
## Result: APPROVE / IMPROVE / REJECT
## Summary
{Summarize the result in 1-2 sentences}
## Reviewed Aspects
- [x] Structure & design
- [x] Code quality
- [x] Change scope
- [x] Test coverage
- [x] Dead code
- [x] Call chain verification
## Issues (if REJECT)
| # | Scope | Location | Issue | Fix Suggestion |
|---|-------|----------|-------|----------------|
| 1 | In-scope | `src/file.ts:42` | Issue description | Fix approach |
Scope: "In-scope" (fixable in this change) / "Out-of-scope" (existing issue, non-blocking)
## Existing Issues (reference, non-blocking)
- {Record of existing issues unrelated to the current change}
```
**Cognitive load reduction rules:**
- APPROVE → Summary only (5 lines or fewer)
- REJECT → Issues in table format (30 lines or fewer)

8
builtins/en/output-contracts/coder-decisions.md Normal file
View File

@ -0,0 +1,8 @@
```markdown
# Decision Log
## 1. {Decision}
- **Context**: {Why the decision was needed}
- **Options considered**: {List of options}
- **Rationale**: {Why this option was chosen}
```

18
builtins/en/output-contracts/coder-scope.md Normal file
View File

@ -0,0 +1,18 @@
```markdown
# Change Scope Declaration
## Task
{One-line task summary}
## Planned Changes
| Type | File |
|------|------|
| Create | `src/example.ts` |
| Modify | `src/routes.ts` |
## Estimated Size
Small / Medium / Large
## Impact Area
- {Affected modules or features}
```

27
builtins/en/output-contracts/cqrs-es-review.md Normal file
View File

@ -0,0 +1,27 @@
```markdown
# CQRS+ES Review
## Result: APPROVE / REJECT
## Summary
{Summarize the result in 1-2 sentences}
## Reviewed Aspects
| Aspect | Result | Notes |
|--------|--------|-------|
| Aggregate design | ✅ | - |
| Event design | ✅ | - |
| Command/Query separation | ✅ | - |
| Projections | ✅ | - |
| Eventual consistency | ✅ | - |
## Issues (if REJECT)
| # | Scope | Location | Issue | Fix Suggestion |
|---|-------|----------|-------|----------------|
| 1 | In-scope | `src/file.ts:42` | Issue description | Fix approach |
Scope: "In-scope" (fixable in this change) / "Out-of-scope" (existing issue, non-blocking)
## Existing Issues (reference, non-blocking)
- {Record of existing issues unrelated to the current change}
```

22
builtins/en/output-contracts/frontend-review.md Normal file
View File

@ -0,0 +1,22 @@
```markdown
# Frontend Review
## Result: APPROVE / REJECT
## Summary
{Summarize the result in 1-2 sentences}
## Reviewed Aspects
| Aspect | Result | Notes |
|--------|--------|-------|
| Component design | ✅ | - |
| State management | ✅ | - |
| Performance | ✅ | - |
| Accessibility | ✅ | - |
| Type safety | ✅ | - |
## Issues (if REJECT)
| # | Location | Issue | Fix Suggestion |
|---|----------|-------|----------------|
| 1 | `src/file.tsx:42` | Issue description | Fix approach |
```

20
builtins/en/output-contracts/plan.md Normal file
View File

@ -0,0 +1,20 @@
```markdown
# Task Plan
## Original Request
{User's request as-is}
## Analysis
### Objective
{What needs to be achieved}
### Scope
{Impact area}
### Implementation Approach
{How to proceed}
## Open Questions (if any)
- {Unclear points or items that need confirmation}
```

22
builtins/en/output-contracts/qa-review.md Normal file
View File

@ -0,0 +1,22 @@
```markdown
# QA Review
## Result: APPROVE / REJECT
## Summary
{Summarize the result in 1-2 sentences}
## Reviewed Aspects
| Aspect | Result | Notes |
|--------|--------|-------|
| Test coverage | ✅ | - |
| Test quality | ✅ | - |
| Error handling | ✅ | - |
| Documentation | ✅ | - |
| Maintainability | ✅ | - |
## Issues (if REJECT)
| # | Category | Issue | Fix Suggestion |
|---|----------|-------|----------------|
| 1 | Testing | Issue description | Fix approach |
```

23
builtins/en/output-contracts/review-summary.md Normal file
View File

@ -0,0 +1,23 @@
```markdown
# Review Summary
## Overall Verdict: APPROVE / REJECT
## Summary
{Integrate all review results in 2-3 sentences}
## Review Results
| Review | Result | Key Findings |
|--------|--------|-------------|
| Architecture | APPROVE/REJECT | {Overview} |
| Security | APPROVE/REJECT | {Overview} |
| AI Anti-pattern | APPROVE/REJECT | {Overview} |
## Critical Issues
| # | Severity | Source | Location | Issue |
|---|----------|--------|----------|-------|
| 1 | High | Security | `file:line` | Description |
## Improvement Suggestions
- {Consolidated suggestions from all reviews}
```

28
builtins/en/output-contracts/security-review.md Normal file
View File

@ -0,0 +1,28 @@
```markdown
# Security Review
## Result: APPROVE / REJECT
## Severity: None / Low / Medium / High / Critical
## Check Results
| Category | Result | Notes |
|----------|--------|-------|
| Injection | ✅ | - |
| Authentication & Authorization | ✅ | - |
| Data Protection | ✅ | - |
| Dependencies | ✅ | - |
## Vulnerabilities (if REJECT)
| # | Severity | Type | Location | Fix Suggestion |
|---|----------|------|----------|----------------|
| 1 | High | SQLi | `src/db.ts:42` | Use parameterized queries |
## Warnings (non-blocking)
- {Security recommendations}
```
**Cognitive load reduction rules:**
- No issues → Checklist only (10 lines or fewer)
- Warnings present → + Warnings in 1-2 lines (15 lines or fewer)
- Vulnerabilities found → + Table format (30 lines or fewer)

20
builtins/en/output-contracts/summary.md Normal file
View File

@ -0,0 +1,20 @@
```markdown
# Task Completion Summary
## Task
{Original request in 1-2 sentences}
## Result
Completed
## Changes
| Type | File | Overview |
|------|------|----------|
| Create | `src/file.ts` | Brief description |
## Verification Commands
```bash
npm test
npm run build
```
```

22
builtins/en/output-contracts/validation.md Normal file
View File

@ -0,0 +1,22 @@
```markdown
# Final Validation Results
## Result: APPROVE / REJECT
## Validation Summary
| Item | Status | Verification Method |
|------|--------|-------------------|
| Requirements met | ✅ | Checked against requirements list |
| Tests | ✅ | `npm test` (N passed) |
| Build | ✅ | `npm run build` succeeded |
| Functional check | ✅ | Main flow verified |
## Deliverables
- Created: {Created files}
- Modified: {Modified files}
## Incomplete Items (if REJECT)
| # | Item | Reason |
|---|------|--------|
| 1 | {Item} | {Reason} |
```

25
builtins/en/personas/ai-antipattern-reviewer.md Normal file
View File

@ -0,0 +1,25 @@
# AI Antipattern Reviewer
You are an AI-generated code expert. You review code produced by AI coding assistants for patterns and issues rarely seen in human-written code.
## Role Boundaries
**Do:**
- Validate the soundness of assumptions made by AI
- Detect hallucinated APIs and non-existent methods
- Verify alignment with existing codebase patterns
- Detect scope creep and over-engineering
- Detect dead code and unused code
- Detect abuse of fallbacks and default arguments
- Detect unnecessary backward-compatibility code
**Don't:**
- Review architecture (Architecture Reviewer's job)
- Review security vulnerabilities (Security Reviewer's job)
- Write code yourself
## Behavioral Principles
- AI-generated code is produced faster than humans can review it. Bridging that quality gap is the reason this role exists
- AI is confidently wrong. Spot code that looks plausible but doesn't work, and solutions that are technically correct but contextually wrong
- Trust but verify. AI-generated code often looks professional. Catch the subtle issues that pass initial inspection

0
resources/global/en/agents/default/architect-planner.md → builtins/en/personas/architect-planner.md
View File

55
builtins/en/personas/architecture-reviewer.md Normal file
View File

@ -0,0 +1,55 @@
# Architecture Reviewer
You are a **design reviewer** and **quality gatekeeper**. You review not just code quality, but emphasize **structure and design**.
## Core Values
Code is read far more often than it is written. Poorly structured code destroys maintainability and produces unexpected side effects with every change. Be strict and uncompromising.
"If the structure is right, the code naturally follows"—that is the conviction of design review.
## Reviewer Principles
**Never defer even minor issues. If a problem can be fixed now, require it to be fixed now.**
- No compromises for "minor issues". Accumulation of small problems becomes technical debt
- "Address in next task" never happens. If fixable now, fix now
- No "conditional approval". If there are issues, reject
- If you find in-scope fixable issues, flag them without exception
- Existing issues (unrelated to current change) are non-blocking, but issues introduced or fixable in this change must be flagged
## Areas of Expertise
### Structure & Design
- File organization and module decomposition
- Layer design and dependency direction verification
- Directory structure pattern selection
### Code Quality
- Abstraction level alignment
- DRY, YAGNI, and Fail Fast principles
- Idiomatic implementation
### Anti-Pattern Detection
- Unnecessary backward compatibility code
- Workaround implementations
- Unused code and dead code
**Don't:**
- Write code yourself (only provide feedback and suggestions)
- Give vague feedback ("clean this up" is prohibited)
- Review AI-specific issues (AI Reviewer's job)
## Important
**Be specific.** These are prohibited:
- "Please clean this up a bit"
- "Please reconsider the structure"
- "Refactoring is needed"
**Always specify:**
- Which file, which line
- What the problem is
- How to fix it
**Remember**: You are the quality gatekeeper. Poorly structured code destroys maintainability. Never let code that doesn't meet standards pass.

0
resources/global/en/agents/magi/balthasar.md → builtins/en/personas/balthasar.md
View File

0
resources/global/en/agents/magi/casper.md → builtins/en/personas/casper.md
View File

36
builtins/en/personas/coder.md Normal file
View File

@ -0,0 +1,36 @@
# Coder Agent
You are the implementer. Focus on implementation, not design decisions.
## Role Boundaries
**Do:**
- Implement according to Architect's design
- Write test code
- Fix issues pointed out in reviews
**Don't:**
- Make architecture decisions (delegate to Architect)
- Interpret requirements (report unclear points)
- Edit files outside the project
## Behavioral Principles
- Thoroughness over speed. Code correctness over implementation ease
- Prioritize "works correctly" over "works for now"
- Don't implement by guessing; report unclear points
- Work only within the specified project directory (reading external files for reference is allowed)
**Reviewer's feedback is absolute. Your understanding is wrong.**
- If reviewer says "not fixed", first open the file and verify the facts
- Drop the assumption "I should have fixed it"
- Fix all flagged issues with Edit tool
- Don't argue; just comply
**Be aware of AI's bad habits:**
- Hiding uncertainty with fallbacks → Prohibited
- Writing unused code "just in case" → Prohibited
- Making design decisions arbitrarily → Report and ask for guidance
- Dismissing reviewer feedback → Prohibited
- Adding backward compatibility or legacy support without being asked → Absolutely prohibited
- Layering workarounds that bypass safety mechanisms on top of a root cause fix → Prohibited

0
resources/global/en/agents/default/conductor.md → builtins/en/personas/conductor.md
View File

36
builtins/en/personas/cqrs-es-reviewer.md Normal file
View File

@ -0,0 +1,36 @@
# CQRS+ES Reviewer
You are an expert in **CQRS (Command Query Responsibility Segregation)** and **Event Sourcing**.
## Core Values
The truth of a domain is inscribed in events. State is merely a temporary projection; the event history is the only source of truth. Reading and writing are fundamentally different concerns, and forcing their unification creates complexity that hinders system growth.
"Record what happened accurately, and derive the current state efficiently"—that is the essence of CQRS+ES.
## Areas of Expertise
### Command Side (Write)
- Aggregate design and domain events
- Command handlers and validation
- Persistence to event store
- Optimistic locking and conflict resolution
### Query Side (Read)
- Projection design
- ReadModel optimization
- Event handlers and view updates
- Eventual consistency management
### Event Sourcing
- Event design (granularity, naming, schema)
- Event versioning and migration
- Snapshot strategies
- Replay and rebuild
## Important
- **Don't overlook superficial CQRS**: Just splitting CRUD into Command/Query is meaningless
- **Insist on event quality**: Events are the history book of the domain
- **Don't fear eventual consistency**: Well-designed ES is more robust than strong consistency
- **Beware excessive complexity**: Don't force CQRS+ES where simple CRUD suffices

0
resources/global/en/agents/expert/supervisor.md → builtins/en/personas/expert-supervisor.md
View File

43
builtins/en/personas/frontend-reviewer.md Normal file
View File

@ -0,0 +1,43 @@
# Frontend Reviewer
You are an expert in **Frontend Development**.
You review code from the perspective of modern frontend technologies (React, Vue, Angular, Svelte, etc.), state management, performance optimization, accessibility, and UX.
## Core Values
The user interface is the only point of contact between the system and users. No matter how excellent the backend is, users cannot receive value if the frontend is poor.
"Fast, usable, and resilient"—that is the mission of frontend development.
## Areas of Expertise
### Component Design
- Separation of concerns and component granularity
- Props design and data flow
- Reusability and extensibility
### State Management
- Local vs global state decisions
- State normalization and caching strategies
- Async state handling
### Performance
- Rendering optimization
- Bundle size management
- Memory leak prevention
### UX/Accessibility
- Usability principles
- WAI-ARIA compliance
- Responsive design
## Important
- **Prioritize user experience**: UX over technical correctness
- **Performance can't be fixed later**: Consider at design stage
- **Accessibility is hard to retrofit**: Build in from the start
- **Beware excessive abstraction**: Keep it simple
- **Follow framework conventions**: Standard approaches over custom patterns
- **Data fetching at root**: Don't create hidden dependencies in children
- **Controlled components**: Data flow is unidirectional

0
resources/global/en/agents/magi/melchior.md → builtins/en/personas/melchior.md
View File

0
resources/global/en/agents/default/planner.md → builtins/en/personas/planner.md
View File

0
resources/global/en/agents/review/pr-commenter.md → builtins/en/personas/pr-commenter.md
View File

25
builtins/en/personas/qa-reviewer.md Normal file
View File

@ -0,0 +1,25 @@
# QA Reviewer
You are a Quality Assurance specialist. You verify that changes are properly tested and won't break existing functionality.
## Role Boundaries
**Do:**
- Verify test coverage
- Evaluate test quality
- Validate test strategy
- Check error handling and logging
- Assess maintainability
- Detect technical debt
**Don't:**
- Review security concerns (Security Reviewer's job)
- Review architecture decisions (Architecture Reviewer's job)
- Review AI-specific patterns (AI Antipattern Reviewer's job)
- Write code yourself
## Behavioral Principles
- Tests come first. If tests are missing, that is the top priority above everything else
- Don't demand perfection. Good tests at 80% coverage are far more valuable than having nothing while aiming for 100%
- Existing untested code is not your problem. Only review test coverage for the current change

0
resources/global/en/agents/research/digger.md → builtins/en/personas/research-digger.md
View File

0
resources/global/en/agents/research/planner.md → builtins/en/personas/research-planner.md
View File

0
resources/global/en/agents/research/supervisor.md → builtins/en/personas/research-supervisor.md
View File

42
builtins/en/personas/security-reviewer.md Normal file
View File

@ -0,0 +1,42 @@
# Security Reviewer
You are a **security reviewer**. You thoroughly inspect code for security vulnerabilities.
## Core Values
Security cannot be retrofitted. It must be built in from the design stage; "we'll deal with it later" is not acceptable. A single vulnerability can put the entire system at risk.
"Trust nothing, verify everything"—that is the fundamental principle of security.
## Areas of Expertise
### Input Validation & Injection Prevention
- SQL, Command, and XSS injection prevention
- User input sanitization and validation
### Authentication & Authorization
- Authentication flow security
- Authorization check coverage
### Data Protection
- Handling of sensitive information
- Encryption and hashing appropriateness
### AI-Generated Code
- AI-specific vulnerability pattern detection
- Dangerous default value detection
**Don't:**
- Write code yourself (only provide feedback and fix suggestions)
- Review design or code quality (that's Architect's role)
## Important
**Don't miss anything**: Security vulnerabilities get exploited in production. One oversight can lead to a critical incident.
**Be specific**:
- Which file, which line
- What attack is possible
- How to fix it
**Remember**: You are the security gatekeeper. Never let vulnerable code pass.

0
resources/global/en/agents/default/supervisor.md → builtins/en/personas/supervisor.md
View File

42
resources/global/en/piece-categories.yaml → builtins/en/piece-categories.yaml
View File

@ -1,46 +1,38 @@
piece_categories:
"🚀 Quick Start":
🚀 Quick Start:
pieces:
- default
- passthrough
- coding
- minimal
"🔍 Review & Fix":
🔍 Review & Fix:
pieces:
- review-fix-minimal
"🎨 Frontend":
{}
"⚙️ Backend":
{}
"🔧 Expert":
"Full Stack":
🎨 Frontend: {}
⚙️ Backend: {}
🔧 Expert:
Full Stack:
pieces:
- expert
- expert-cqrs
"🔀 Hybrid (Codex Coding)":
"🚀 Quick Start":
🔀 Hybrid (Codex Coding):
🚀 Quick Start:
pieces:
- coding-hybrid-codex
- default-hybrid-codex
- passthrough-hybrid-codex
- minimal-hybrid-codex
"🔍 Review & Fix":
- passthrough-hybrid-codex
🔧 Expert:
pieces:
- expert-cqrs-hybrid-codex
- expert-hybrid-codex
🔍 Review & Fix:
pieces:
- review-fix-minimal-hybrid-codex
"🔧 Expert":
pieces:
- expert-hybrid-codex
- expert-cqrs-hybrid-codex
"Others":
Others:
pieces:
- research
- magi
- review-only
show_others_category: true
others_category_name: "Others"
others_category_name: Others

157
builtins/en/pieces/coding-hybrid-codex.yaml Normal file
View File

@ -0,0 +1,157 @@
# Auto-generated from coding.yaml by tools/generate-hybrid-codex.mjs
# Do not edit manually. Edit the source piece and re-run the generator.
name: coding-hybrid-codex
description: Lightweight development piece with planning and parallel reviews (plan -> implement -> parallel review -> complete)
max_iterations: 20
knowledge:
architecture: ../knowledge/architecture.md
personas:
architect-planner: ../personas/architect-planner.md
coder: ../personas/coder.md
ai-antipattern-reviewer: ../personas/ai-antipattern-reviewer.md
architecture-reviewer: ../personas/architecture-reviewer.md
instructions:
plan: ../instructions/plan.md
implement: ../instructions/implement.md
ai-review: ../instructions/ai-review.md
review-arch: ../instructions/review-arch.md
fix: ../instructions/fix.md
report_formats:
plan: ../output-contracts/plan.md
ai-review: ../output-contracts/ai-review.md
architecture-review: ../output-contracts/architecture-review.md
initial_movement: plan
movements:
- name: plan
edit: false
persona: architect-planner
allowed_tools:
- Read
- Glob
- Grep
- Bash
- WebSearch
- WebFetch
rules:
- condition: Requirements are clear and implementable
next: implement
- condition: User is asking a question (not an implementation task)
next: COMPLETE
- condition: Requirements are unclear, insufficient information
next: ABORT
instruction: plan
output_contracts:
report:
- name: 00-plan.md
format: plan
- name: implement
edit: true
persona: coder
provider: codex
policy:
- coding
- testing
session: refresh
knowledge: architecture
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
permission_mode: edit
rules:
- condition: Implementation complete
next: reviewers
- condition: Implementation not started (report only)
next: reviewers
- condition: Cannot determine, insufficient information
next: reviewers
- condition: User input required
next: implement
requires_user_input: true
interactive_only: true
instruction: implement
output_contracts:
report:
- Scope: 02-coder-scope.md
- Decisions: 03-coder-decisions.md
- name: reviewers
parallel:
- name: ai_review
edit: false
persona: ai-antipattern-reviewer
policy:
- review
- ai-antipattern
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
rules:
- condition: No AI-specific issues
- condition: AI-specific issues found
instruction: ai-review
output_contracts:
report:
- name: 04-ai-review.md
format: ai-review
- name: arch-review
edit: false
persona: architecture-reviewer
policy: review
knowledge: architecture
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
rules:
- condition: approved
- condition: needs_fix
instruction: review-arch
output_contracts:
report:
- name: 05-architect-review.md
format: architecture-review
rules:
- condition: all("No AI-specific issues", "approved")
next: COMPLETE
- condition: any("AI-specific issues found", "needs_fix")
next: fix
- name: fix
edit: true
persona: coder
provider: codex
policy:
- coding
- testing
knowledge: architecture
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
permission_mode: edit
rules:
- condition: Fix complete
next: reviewers
- condition: Cannot determine, insufficient information
next: ABORT
instruction: fix
policies:
coding: ../policies/coding.md
review: ../policies/review.md
testing: ../policies/testing.md
ai-antipattern: ../policies/ai-antipattern.md

152
builtins/en/pieces/coding.yaml Normal file
View File

@ -0,0 +1,152 @@
name: coding
description: Lightweight development piece with planning and parallel reviews (plan -> implement -> parallel review -> complete)
max_iterations: 20
policies:
coding: ../policies/coding.md
review: ../policies/review.md
testing: ../policies/testing.md
ai-antipattern: ../policies/ai-antipattern.md
knowledge:
architecture: ../knowledge/architecture.md
personas:
architect-planner: ../personas/architect-planner.md
coder: ../personas/coder.md
ai-antipattern-reviewer: ../personas/ai-antipattern-reviewer.md
architecture-reviewer: ../personas/architecture-reviewer.md
instructions:
plan: ../instructions/plan.md
implement: ../instructions/implement.md
ai-review: ../instructions/ai-review.md
review-arch: ../instructions/review-arch.md
fix: ../instructions/fix.md
initial_movement: plan
movements:
- name: plan
edit: false
persona: architect-planner
allowed_tools:
- Read
- Glob
- Grep
- Bash
- WebSearch
- WebFetch
rules:
- condition: Requirements are clear and implementable
next: implement
- condition: User is asking a question (not an implementation task)
next: COMPLETE
- condition: Requirements are unclear, insufficient information
next: ABORT
instruction: plan
output_contracts:
report:
- name: 00-plan.md
format: plan
- name: implement
edit: true
persona: coder
policy:
- coding
- testing
session: refresh
knowledge: architecture
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
permission_mode: edit
rules:
- condition: Implementation complete
next: reviewers
- condition: Implementation not started (report only)
next: reviewers
- condition: Cannot determine, insufficient information
next: reviewers
- condition: User input required
next: implement
requires_user_input: true
interactive_only: true
instruction: implement
output_contracts:
report:
- Scope: 02-coder-scope.md
- Decisions: 03-coder-decisions.md
- name: reviewers
parallel:
- name: ai_review
edit: false
persona: ai-antipattern-reviewer
policy:
- review
- ai-antipattern
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
rules:
- condition: No AI-specific issues
- condition: AI-specific issues found
instruction: ai-review
output_contracts:
report:
- name: 04-ai-review.md
format: ai-review
- name: arch-review
edit: false
persona: architecture-reviewer
policy: review
knowledge: architecture
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
rules:
- condition: approved
- condition: needs_fix
instruction: review-arch
output_contracts:
report:
- name: 05-architect-review.md
format: architecture-review
rules:
- condition: all("No AI-specific issues", "approved")
next: COMPLETE
- condition: any("AI-specific issues found", "needs_fix")
next: fix
- name: fix
edit: true
persona: coder
policy:
- coding
- testing
knowledge: architecture
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
permission_mode: edit
rules:
- condition: Fix complete
next: reviewers
- condition: Cannot determine, insufficient information
next: ABORT
instruction: fix
report_formats:
plan: ../output-contracts/plan.md
ai-review: ../output-contracts/ai-review.md
architecture-review: ../output-contracts/architecture-review.md

313
builtins/en/pieces/default-hybrid-codex.yaml Normal file
View File

@ -0,0 +1,313 @@
# Auto-generated from default.yaml by tools/generate-hybrid-codex.mjs
# Do not edit manually. Edit the source piece and re-run the generator.
name: default-hybrid-codex
description: Standard development piece with planning and specialized reviews
max_iterations: 30
knowledge:
backend: ../knowledge/backend.md
architecture: ../knowledge/architecture.md
personas:
planner: ../personas/planner.md
architect-planner: ../personas/architect-planner.md
coder: ../personas/coder.md
ai-antipattern-reviewer: ../personas/ai-antipattern-reviewer.md
architecture-reviewer: ../personas/architecture-reviewer.md
qa-reviewer: ../personas/qa-reviewer.md
supervisor: ../personas/supervisor.md
instructions:
plan: ../instructions/plan.md
architect: ../instructions/architect.md
implement: ../instructions/implement.md
ai-review: ../instructions/ai-review.md
ai-fix: ../instructions/ai-fix.md
arbitrate: ../instructions/arbitrate.md
review-arch: ../instructions/review-arch.md
review-qa: ../instructions/review-qa.md
fix: ../instructions/fix.md
supervise: ../instructions/supervise.md
report_formats:
plan: ../output-contracts/plan.md
architecture-design: ../output-contracts/architecture-design.md
ai-review: ../output-contracts/ai-review.md
architecture-review: ../output-contracts/architecture-review.md
qa-review: ../output-contracts/qa-review.md
validation: ../output-contracts/validation.md
summary: ../output-contracts/summary.md
initial_movement: plan
loop_monitors:
- cycle:
- ai_review
- ai_fix
threshold: 3
judge:
persona: supervisor
instruction_template: |
The ai_review ↔ ai_fix loop has repeated {cycle_count} times.
Review the reports from each cycle and determine whether this loop
is healthy (making progress) or unproductive (repeating the same issues).
**Reports to reference:**
- AI Review results: {report:04-ai-review.md}
**Judgment criteria:**
- Are new issues being found/fixed in each cycle?
- Are the same findings being repeated?
- Are fixes actually being applied?
rules:
- condition: Healthy (making progress)
next: ai_review
- condition: Unproductive (no improvement)
next: reviewers
movements:
- name: plan
edit: false
persona: planner
allowed_tools:
- Read
- Glob
- Grep
- Bash
- WebSearch
- WebFetch
rules:
- condition: Requirements are clear and implementable
next: architect
- condition: User is asking a question (not an implementation task)
next: COMPLETE
- condition: Requirements unclear, insufficient info
next: ABORT
appendix: |
Clarifications needed:
- {Question 1}
- {Question 2}
instruction: plan
output_contracts:
report:
- name: 00-plan.md
format: plan
- name: architect
edit: false
persona: architect-planner
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
rules:
- condition: Small task (no design needed)
next: implement
- condition: Design complete
next: implement
- condition: Insufficient info, cannot proceed
next: ABORT
instruction: architect
output_contracts:
report:
- name: 01-architecture.md
format: architecture-design
- name: implement
edit: true
persona: coder
provider: codex
policy:
- coding
- testing
session: refresh
knowledge:
- backend
- architecture
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
permission_mode: edit
rules:
- condition: Implementation complete
next: ai_review
- condition: No implementation (report only)
next: ai_review
- condition: Cannot proceed, insufficient info
next: ai_review
- condition: User input required
next: implement
requires_user_input: true
interactive_only: true
instruction: implement
output_contracts:
report:
- Scope: 02-coder-scope.md
- Decisions: 03-coder-decisions.md
- name: ai_review
edit: false
persona: ai-antipattern-reviewer
policy:
- review
- ai-antipattern
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
rules:
- condition: No AI-specific issues
next: reviewers
- condition: AI-specific issues found
next: ai_fix
instruction: ai-review
output_contracts:
report:
- name: 04-ai-review.md
format: ai-review
- name: ai_fix
edit: true
persona: coder
provider: codex
policy:
- coding
- testing
session: refresh
knowledge:
- backend
- architecture
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
permission_mode: edit
rules:
- condition: AI issues fixed
next: ai_review
- condition: No fix needed (verified target files/spec)
next: ai_no_fix
- condition: Cannot proceed, insufficient info
next: ai_no_fix
instruction: ai-fix
- name: ai_no_fix
edit: false
persona: architecture-reviewer
policy: review
allowed_tools:
- Read
- Glob
- Grep
rules:
- condition: ai_review's findings are valid (fix required)
next: ai_fix
- condition: ai_fix's judgment is valid (no fix needed)
next: reviewers
instruction: arbitrate
- name: reviewers
parallel:
- name: arch-review
edit: false
persona: architecture-reviewer
policy: review
knowledge:
- architecture
- backend
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
rules:
- condition: approved
- condition: needs_fix
instruction: review-arch
output_contracts:
report:
- name: 05-architect-review.md
format: architecture-review
- name: qa-review
edit: false
persona: qa-reviewer
policy:
- review
- qa
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
rules:
- condition: approved
- condition: needs_fix
instruction: review-qa
output_contracts:
report:
- name: 06-qa-review.md
format: qa-review
rules:
- condition: all("approved")
next: supervise
- condition: any("needs_fix")
next: fix
- name: fix
edit: true
persona: coder
provider: codex
policy:
- coding
- testing
knowledge:
- backend
- architecture
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
permission_mode: edit
rules:
- condition: Fix complete
next: reviewers
- condition: Cannot proceed, insufficient info
next: plan
instruction: fix
- name: supervise
edit: false
persona: supervisor
policy: review
allowed_tools:
- Read
- Glob
- Grep
- Bash
- WebSearch
- WebFetch
rules:
- condition: All checks passed
next: COMPLETE
- condition: Requirements unmet, tests failing, build errors
next: plan
instruction: supervise
output_contracts:
report:
- Validation: 07-supervisor-validation.md
- Summary: summary.md
policies:
coding: ../policies/coding.md
review: ../policies/review.md
testing: ../policies/testing.md
ai-antipattern: ../policies/ai-antipattern.md
qa: ../policies/qa.md

307
builtins/en/pieces/default.yaml Normal file
View File

@ -0,0 +1,307 @@
name: default
description: Standard development piece with planning and specialized reviews
max_iterations: 30
policies:
coding: ../policies/coding.md
review: ../policies/review.md
testing: ../policies/testing.md
ai-antipattern: ../policies/ai-antipattern.md
qa: ../policies/qa.md
knowledge:
backend: ../knowledge/backend.md
architecture: ../knowledge/architecture.md
personas:
planner: ../personas/planner.md
architect-planner: ../personas/architect-planner.md
coder: ../personas/coder.md
ai-antipattern-reviewer: ../personas/ai-antipattern-reviewer.md
architecture-reviewer: ../personas/architecture-reviewer.md
qa-reviewer: ../personas/qa-reviewer.md
supervisor: ../personas/supervisor.md
instructions:
plan: ../instructions/plan.md
architect: ../instructions/architect.md
implement: ../instructions/implement.md
ai-review: ../instructions/ai-review.md
ai-fix: ../instructions/ai-fix.md
arbitrate: ../instructions/arbitrate.md
review-arch: ../instructions/review-arch.md
review-qa: ../instructions/review-qa.md
fix: ../instructions/fix.md
supervise: ../instructions/supervise.md
initial_movement: plan
loop_monitors:
- cycle:
- ai_review
- ai_fix
threshold: 3
judge:
persona: supervisor
instruction_template: |
The ai_review ↔ ai_fix loop has repeated {cycle_count} times.
Review the reports from each cycle and determine whether this loop
is healthy (making progress) or unproductive (repeating the same issues).
**Reports to reference:**
- AI Review results: {report:04-ai-review.md}
**Judgment criteria:**
- Are new issues being found/fixed in each cycle?
- Are the same findings being repeated?
- Are fixes actually being applied?
rules:
- condition: Healthy (making progress)
next: ai_review
- condition: Unproductive (no improvement)
next: reviewers
movements:
- name: plan
edit: false
persona: planner
allowed_tools:
- Read
- Glob
- Grep
- Bash
- WebSearch
- WebFetch
rules:
- condition: Requirements are clear and implementable
next: architect
- condition: User is asking a question (not an implementation task)
next: COMPLETE
- condition: Requirements unclear, insufficient info
next: ABORT
appendix: |
Clarifications needed:
- {Question 1}
- {Question 2}
instruction: plan
output_contracts:
report:
- name: 00-plan.md
format: plan
- name: architect
edit: false
persona: architect-planner
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
rules:
- condition: Small task (no design needed)
next: implement
- condition: Design complete
next: implement
- condition: Insufficient info, cannot proceed
next: ABORT
instruction: architect
output_contracts:
report:
- name: 01-architecture.md
format: architecture-design
- name: implement
edit: true
persona: coder
policy:
- coding
- testing
session: refresh
knowledge:
- backend
- architecture
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
permission_mode: edit
rules:
- condition: Implementation complete
next: ai_review
- condition: No implementation (report only)
next: ai_review
- condition: Cannot proceed, insufficient info
next: ai_review
- condition: User input required
next: implement
requires_user_input: true
interactive_only: true
instruction: implement
output_contracts:
report:
- Scope: 02-coder-scope.md
- Decisions: 03-coder-decisions.md
- name: ai_review
edit: false
persona: ai-antipattern-reviewer
policy:
- review
- ai-antipattern
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
rules:
- condition: No AI-specific issues
next: reviewers
- condition: AI-specific issues found
next: ai_fix
instruction: ai-review
output_contracts:
report:
- name: 04-ai-review.md
format: ai-review
- name: ai_fix
edit: true
persona: coder
policy:
- coding
- testing
session: refresh
knowledge:
- backend
- architecture
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
permission_mode: edit
rules:
- condition: AI issues fixed
next: ai_review
- condition: No fix needed (verified target files/spec)
next: ai_no_fix
- condition: Cannot proceed, insufficient info
next: ai_no_fix
instruction: ai-fix
- name: ai_no_fix
edit: false
persona: architecture-reviewer
policy: review
allowed_tools:
- Read
- Glob
- Grep
rules:
- condition: ai_review's findings are valid (fix required)
next: ai_fix
- condition: ai_fix's judgment is valid (no fix needed)
next: reviewers
instruction: arbitrate
- name: reviewers
parallel:
- name: arch-review
edit: false
persona: architecture-reviewer
policy: review
knowledge:
- architecture
- backend
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
rules:
- condition: approved
- condition: needs_fix
instruction: review-arch
output_contracts:
report:
- name: 05-architect-review.md
format: architecture-review
- name: qa-review
edit: false
persona: qa-reviewer
policy:
- review
- qa
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
rules:
- condition: approved
- condition: needs_fix
instruction: review-qa
output_contracts:
report:
- name: 06-qa-review.md
format: qa-review
rules:
- condition: all("approved")
next: supervise
- condition: any("needs_fix")
next: fix
- name: fix
edit: true
persona: coder
policy:
- coding
- testing
knowledge:
- backend
- architecture
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
permission_mode: edit
rules:
- condition: Fix complete
next: reviewers
- condition: Cannot proceed, insufficient info
next: plan
instruction: fix
- name: supervise
edit: false
persona: supervisor
policy: review
allowed_tools:
- Read
- Glob
- Grep
- Bash
- WebSearch
- WebFetch
rules:
- condition: All checks passed
next: COMPLETE
- condition: Requirements unmet, tests failing, build errors
next: plan
instruction: supervise
output_contracts:
report:
- Validation: 07-supervisor-validation.md
- Summary: summary.md
report_formats:
plan: ../output-contracts/plan.md
architecture-design: ../output-contracts/architecture-design.md
ai-review: ../output-contracts/ai-review.md
architecture-review: ../output-contracts/architecture-review.md
qa-review: ../output-contracts/qa-review.md
validation: ../output-contracts/validation.md
summary: ../output-contracts/summary.md

341
builtins/en/pieces/expert-cqrs-hybrid-codex.yaml Normal file
View File

@ -0,0 +1,341 @@
# Auto-generated from expert-cqrs.yaml by tools/generate-hybrid-codex.mjs
# Do not edit manually. Edit the source piece and re-run the generator.
name: expert-cqrs-hybrid-codex
description: CQRS+ES, Frontend, Security, QA Expert Review
max_iterations: 30
knowledge:
frontend: ../knowledge/frontend.md
backend: ../knowledge/backend.md
cqrs-es: ../knowledge/cqrs-es.md
security: ../knowledge/security.md
architecture: ../knowledge/architecture.md
personas:
planner: ../personas/planner.md
coder: ../personas/coder.md
ai-antipattern-reviewer: ../personas/ai-antipattern-reviewer.md
architecture-reviewer: ../personas/architecture-reviewer.md
cqrs-es-reviewer: ../personas/cqrs-es-reviewer.md
frontend-reviewer: ../personas/frontend-reviewer.md
security-reviewer: ../personas/security-reviewer.md
qa-reviewer: ../personas/qa-reviewer.md
expert-supervisor: ../personas/expert-supervisor.md
instructions:
plan: ../instructions/plan.md
implement: ../instructions/implement.md
ai-review: ../instructions/ai-review.md
ai-fix: ../instructions/ai-fix.md
arbitrate: ../instructions/arbitrate.md
review-cqrs-es: ../instructions/review-cqrs-es.md
review-frontend: ../instructions/review-frontend.md
review-security: ../instructions/review-security.md
review-qa: ../instructions/review-qa.md
fix: ../instructions/fix.md
supervise: ../instructions/supervise.md
fix-supervisor: ../instructions/fix-supervisor.md
report_formats:
plan: ../output-contracts/plan.md
ai-review: ../output-contracts/ai-review.md
cqrs-es-review: ../output-contracts/cqrs-es-review.md
frontend-review: ../output-contracts/frontend-review.md
security-review: ../output-contracts/security-review.md
qa-review: ../output-contracts/qa-review.md
validation: ../output-contracts/validation.md
summary: ../output-contracts/summary.md
initial_movement: plan
movements:
- name: plan
edit: false
persona: planner
allowed_tools:
- Read
- Glob
- Grep
- Bash
- WebSearch
- WebFetch
instruction: plan
rules:
- condition: Task analysis and planning is complete
next: implement
- condition: Requirements are unclear and planning cannot proceed
next: ABORT
output_contracts:
report:
- name: 00-plan.md
format: plan
- name: implement
edit: true
persona: coder
provider: codex
policy:
- coding
- testing
session: refresh
knowledge:
- frontend
- backend
- cqrs-es
- security
- architecture
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
instruction: implement
rules:
- condition: Implementation is complete
next: ai_review
- condition: No implementation (report only)
next: ai_review
- condition: Cannot proceed with implementation
next: ai_review
- condition: User input required
next: implement
requires_user_input: true
interactive_only: true
output_contracts:
report:
- Scope: 01-coder-scope.md
- Decisions: 02-coder-decisions.md
- name: ai_review
edit: false
persona: ai-antipattern-reviewer
policy:
- review
- ai-antipattern
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
instruction: ai-review
rules:
- condition: No AI-specific issues found
next: reviewers
- condition: AI-specific issues detected
next: ai_fix
output_contracts:
report:
- name: 03-ai-review.md
format: ai-review
- name: ai_fix
edit: true
persona: coder
provider: codex
policy:
- coding
- testing
session: refresh
knowledge:
- frontend
- backend
- cqrs-es
- security
- architecture
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
instruction: ai-fix
rules:
- condition: AI Reviewer's issues have been fixed
next: ai_review
- condition: No fix needed (verified target files/spec)
next: ai_no_fix
- condition: Unable to proceed with fixes
next: ai_no_fix
- name: ai_no_fix
edit: false
persona: architecture-reviewer
policy: review
allowed_tools:
- Read
- Glob
- Grep
rules:
- condition: ai_review's findings are valid (fix required)
next: ai_fix
- condition: ai_fix's judgment is valid (no fix needed)
next: reviewers
instruction: arbitrate
- name: reviewers
parallel:
- name: cqrs-es-review
edit: false
persona: cqrs-es-reviewer
policy: review
knowledge:
- cqrs-es
- backend
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
rules:
- condition: approved
- condition: needs_fix
instruction: review-cqrs-es
output_contracts:
report:
- name: 04-cqrs-es-review.md
format: cqrs-es-review
- name: frontend-review
edit: false
persona: frontend-reviewer
policy: review
knowledge: frontend
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
rules:
- condition: approved
- condition: needs_fix
instruction: review-frontend
output_contracts:
report:
- name: 05-frontend-review.md
format: frontend-review
- name: security-review
edit: false
persona: security-reviewer
policy: review
knowledge: security
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
rules:
- condition: approved
- condition: needs_fix
instruction: review-security
output_contracts:
report:
- name: 06-security-review.md
format: security-review
- name: qa-review
edit: false
persona: qa-reviewer
policy:
- review
- qa
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
rules:
- condition: approved
- condition: needs_fix
instruction: review-qa
output_contracts:
report:
- name: 07-qa-review.md
format: qa-review
rules:
- condition: all("approved")
next: supervise
- condition: any("needs_fix")
next: fix
- name: fix
edit: true
persona: coder
provider: codex
policy:
- coding
- testing
knowledge:
- frontend
- backend
- cqrs-es
- security
- architecture
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
permission_mode: edit
rules:
- condition: Fix complete
next: reviewers
- condition: Cannot proceed, insufficient info
next: plan
instruction: fix
- name: supervise
edit: false
persona: expert-supervisor
policy: review
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
instruction: supervise
rules:
- condition: All validations pass and ready to merge
next: COMPLETE
- condition: Issues detected during final review
next: fix_supervisor
output_contracts:
report:
- Validation: 08-supervisor-validation.md
- Summary: summary.md
- name: fix_supervisor
edit: true
persona: coder
provider: codex
policy:
- coding
- testing
knowledge:
- frontend
- backend
- cqrs-es
- security
- architecture
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
instruction: fix-supervisor
rules:
- condition: Supervisor's issues have been fixed
next: supervise
- condition: Unable to proceed with fixes
next: plan
policies:
coding: ../policies/coding.md
review: ../policies/review.md
testing: ../policies/testing.md
ai-antipattern: ../policies/ai-antipattern.md
qa: ../policies/qa.md

334
builtins/en/pieces/expert-cqrs.yaml Normal file
View File

@ -0,0 +1,334 @@
name: expert-cqrs
description: CQRS+ES, Frontend, Security, QA Expert Review
max_iterations: 30
policies:
coding: ../policies/coding.md
review: ../policies/review.md
testing: ../policies/testing.md
ai-antipattern: ../policies/ai-antipattern.md
qa: ../policies/qa.md
knowledge:
frontend: ../knowledge/frontend.md
backend: ../knowledge/backend.md
cqrs-es: ../knowledge/cqrs-es.md
security: ../knowledge/security.md
architecture: ../knowledge/architecture.md
personas:
planner: ../personas/planner.md
coder: ../personas/coder.md
ai-antipattern-reviewer: ../personas/ai-antipattern-reviewer.md
architecture-reviewer: ../personas/architecture-reviewer.md
cqrs-es-reviewer: ../personas/cqrs-es-reviewer.md
frontend-reviewer: ../personas/frontend-reviewer.md
security-reviewer: ../personas/security-reviewer.md
qa-reviewer: ../personas/qa-reviewer.md
expert-supervisor: ../personas/expert-supervisor.md
instructions:
plan: ../instructions/plan.md
implement: ../instructions/implement.md
ai-review: ../instructions/ai-review.md
ai-fix: ../instructions/ai-fix.md
arbitrate: ../instructions/arbitrate.md
review-cqrs-es: ../instructions/review-cqrs-es.md
review-frontend: ../instructions/review-frontend.md
review-security: ../instructions/review-security.md
review-qa: ../instructions/review-qa.md
fix: ../instructions/fix.md
supervise: ../instructions/supervise.md
fix-supervisor: ../instructions/fix-supervisor.md
initial_movement: plan
movements:
- name: plan
edit: false
persona: planner
allowed_tools:
- Read
- Glob
- Grep
- Bash
- WebSearch
- WebFetch
instruction: plan
rules:
- condition: Task analysis and planning is complete
next: implement
- condition: Requirements are unclear and planning cannot proceed
next: ABORT
output_contracts:
report:
- name: 00-plan.md
format: plan
- name: implement
edit: true
persona: coder
policy:
- coding
- testing
session: refresh
knowledge:
- frontend
- backend
- cqrs-es
- security
- architecture
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
instruction: implement
rules:
- condition: Implementation is complete
next: ai_review
- condition: No implementation (report only)
next: ai_review
- condition: Cannot proceed with implementation
next: ai_review
- condition: User input required
next: implement
requires_user_input: true
interactive_only: true
output_contracts:
report:
- Scope: 01-coder-scope.md
- Decisions: 02-coder-decisions.md
- name: ai_review
edit: false
persona: ai-antipattern-reviewer
policy:
- review
- ai-antipattern
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
instruction: ai-review
rules:
- condition: No AI-specific issues found
next: reviewers
- condition: AI-specific issues detected
next: ai_fix
output_contracts:
report:
- name: 03-ai-review.md
format: ai-review
- name: ai_fix
edit: true
persona: coder
policy:
- coding
- testing
session: refresh
knowledge:
- frontend
- backend
- cqrs-es
- security
- architecture
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
instruction: ai-fix
rules:
- condition: AI Reviewer's issues have been fixed
next: ai_review
- condition: No fix needed (verified target files/spec)
next: ai_no_fix
- condition: Unable to proceed with fixes
next: ai_no_fix
- name: ai_no_fix
edit: false
persona: architecture-reviewer
policy: review
allowed_tools:
- Read
- Glob
- Grep
rules:
- condition: ai_review's findings are valid (fix required)
next: ai_fix
- condition: ai_fix's judgment is valid (no fix needed)
next: reviewers
instruction: arbitrate
- name: reviewers
parallel:
- name: cqrs-es-review
edit: false
persona: cqrs-es-reviewer
policy: review
knowledge:
- cqrs-es
- backend
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
rules:
- condition: approved
- condition: needs_fix
instruction: review-cqrs-es
output_contracts:
report:
- name: 04-cqrs-es-review.md
format: cqrs-es-review
- name: frontend-review
edit: false
persona: frontend-reviewer
policy: review
knowledge: frontend
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
rules:
- condition: approved
- condition: needs_fix
instruction: review-frontend
output_contracts:
report:
- name: 05-frontend-review.md
format: frontend-review
- name: security-review
edit: false
persona: security-reviewer
policy: review
knowledge: security
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
rules:
- condition: approved
- condition: needs_fix
instruction: review-security
output_contracts:
report:
- name: 06-security-review.md
format: security-review
- name: qa-review
edit: false
persona: qa-reviewer
policy:
- review
- qa
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
rules:
- condition: approved
- condition: needs_fix
instruction: review-qa
output_contracts:
report:
- name: 07-qa-review.md
format: qa-review
rules:
- condition: all("approved")
next: supervise
- condition: any("needs_fix")
next: fix
- name: fix
edit: true
persona: coder
policy:
- coding
- testing
knowledge:
- frontend
- backend
- cqrs-es
- security
- architecture
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
permission_mode: edit
rules:
- condition: Fix complete
next: reviewers
- condition: Cannot proceed, insufficient info
next: plan
instruction: fix
- name: supervise
edit: false
persona: expert-supervisor
policy: review
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
instruction: supervise
rules:
- condition: All validations pass and ready to merge
next: COMPLETE
- condition: Issues detected during final review
next: fix_supervisor
output_contracts:
report:
- Validation: 08-supervisor-validation.md
- Summary: summary.md
- name: fix_supervisor
edit: true
persona: coder
policy:
- coding
- testing
knowledge:
- frontend
- backend
- cqrs-es
- security
- architecture
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
instruction: fix-supervisor
rules:
- condition: Supervisor's issues have been fixed
next: supervise
- condition: Unable to proceed with fixes
next: plan
report_formats:
plan: ../output-contracts/plan.md
ai-review: ../output-contracts/ai-review.md
cqrs-es-review: ../output-contracts/cqrs-es-review.md
frontend-review: ../output-contracts/frontend-review.md
security-review: ../output-contracts/security-review.md
qa-review: ../output-contracts/qa-review.md
validation: ../output-contracts/validation.md
summary: ../output-contracts/summary.md

335
builtins/en/pieces/expert-hybrid-codex.yaml Normal file
View File

@ -0,0 +1,335 @@
# Auto-generated from expert.yaml by tools/generate-hybrid-codex.mjs
# Do not edit manually. Edit the source piece and re-run the generator.
name: expert-hybrid-codex
description: Architecture, Frontend, Security, QA Expert Review
max_iterations: 30
knowledge:
frontend: ../knowledge/frontend.md
backend: ../knowledge/backend.md
security: ../knowledge/security.md
architecture: ../knowledge/architecture.md
personas:
planner: ../personas/planner.md
coder: ../personas/coder.md
ai-antipattern-reviewer: ../personas/ai-antipattern-reviewer.md
architecture-reviewer: ../personas/architecture-reviewer.md
frontend-reviewer: ../personas/frontend-reviewer.md
security-reviewer: ../personas/security-reviewer.md
qa-reviewer: ../personas/qa-reviewer.md
expert-supervisor: ../personas/expert-supervisor.md
instructions:
plan: ../instructions/plan.md
implement: ../instructions/implement.md
ai-review: ../instructions/ai-review.md
ai-fix: ../instructions/ai-fix.md
arbitrate: ../instructions/arbitrate.md
review-arch: ../instructions/review-arch.md
review-frontend: ../instructions/review-frontend.md
review-security: ../instructions/review-security.md
review-qa: ../instructions/review-qa.md
fix: ../instructions/fix.md
supervise: ../instructions/supervise.md
fix-supervisor: ../instructions/fix-supervisor.md
report_formats:
plan: ../output-contracts/plan.md
ai-review: ../output-contracts/ai-review.md
architecture-review: ../output-contracts/architecture-review.md
frontend-review: ../output-contracts/frontend-review.md
security-review: ../output-contracts/security-review.md
qa-review: ../output-contracts/qa-review.md
validation: ../output-contracts/validation.md
summary: ../output-contracts/summary.md
initial_movement: plan
movements:
- name: plan
edit: false
persona: planner
allowed_tools:
- Read
- Glob
- Grep
- Bash
- WebSearch
- WebFetch
instruction: plan
rules:
- condition: Task analysis and planning is complete
next: implement
- condition: Requirements are unclear and planning cannot proceed
next: ABORT
output_contracts:
report:
- name: 00-plan.md
format: plan
- name: implement
edit: true
persona: coder
provider: codex
policy:
- coding
- testing
session: refresh
knowledge:
- frontend
- backend
- security
- architecture
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
instruction: implement
rules:
- condition: Implementation is complete
next: ai_review
- condition: No implementation (report only)
next: ai_review
- condition: Cannot proceed with implementation
next: ai_review
- condition: User input required
next: implement
requires_user_input: true
interactive_only: true
output_contracts:
report:
- Scope: 01-coder-scope.md
- Decisions: 02-coder-decisions.md
- name: ai_review
edit: false
persona: ai-antipattern-reviewer
policy:
- review
- ai-antipattern
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
instruction: ai-review
rules:
- condition: No AI-specific issues found
next: reviewers
- condition: AI-specific issues detected
next: ai_fix
output_contracts:
report:
- name: 03-ai-review.md
format: ai-review
- name: ai_fix
edit: true
persona: coder
provider: codex
policy:
- coding
- testing
session: refresh
knowledge:
- frontend
- backend
- security
- architecture
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
instruction: ai-fix
rules:
- condition: AI Reviewer's issues have been fixed
next: ai_review
- condition: No fix needed (verified target files/spec)
next: ai_no_fix
- condition: Unable to proceed with fixes
next: ai_no_fix
- name: ai_no_fix
edit: false
persona: architecture-reviewer
policy: review
allowed_tools:
- Read
- Glob
- Grep
rules:
- condition: ai_review's findings are valid (fix required)
next: ai_fix
- condition: ai_fix's judgment is valid (no fix needed)
next: reviewers
instruction: arbitrate
- name: reviewers
parallel:
- name: arch-review
edit: false
persona: architecture-reviewer
policy: review
knowledge:
- architecture
- backend
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
rules:
- condition: approved
- condition: needs_fix
instruction: review-arch
output_contracts:
report:
- name: 04-architect-review.md
format: architecture-review
- name: frontend-review
edit: false
persona: frontend-reviewer
policy: review
knowledge: frontend
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
rules:
- condition: approved
- condition: needs_fix
instruction: review-frontend
output_contracts:
report:
- name: 05-frontend-review.md
format: frontend-review
- name: security-review
edit: false
persona: security-reviewer
policy: review
knowledge: security
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
rules:
- condition: approved
- condition: needs_fix
instruction: review-security
output_contracts:
report:
- name: 06-security-review.md
format: security-review
- name: qa-review
edit: false
persona: qa-reviewer
policy:
- review
- qa
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
rules:
- condition: approved
- condition: needs_fix
instruction: review-qa
output_contracts:
report:
- name: 07-qa-review.md
format: qa-review
rules:
- condition: all("approved")
next: supervise
- condition: any("needs_fix")
next: fix
- name: fix
edit: true
persona: coder
provider: codex
policy:
- coding
- testing
knowledge:
- frontend
- backend
- security
- architecture
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
permission_mode: edit
rules:
- condition: Fix complete
next: reviewers
- condition: Cannot proceed, insufficient info
next: plan
instruction: fix
- name: supervise
edit: false
persona: expert-supervisor
policy: review
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
instruction: supervise
rules:
- condition: All validations pass and ready to merge
next: COMPLETE
- condition: Issues detected during final review
next: fix_supervisor
output_contracts:
report:
- Validation: 08-supervisor-validation.md
- Summary: summary.md
- name: fix_supervisor
edit: true
persona: coder
provider: codex
policy:
- coding
- testing
knowledge:
- frontend
- backend
- security
- architecture
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
instruction: fix-supervisor
rules:
- condition: Supervisor's issues have been fixed
next: supervise
- condition: Unable to proceed with fixes
next: plan
policies:
coding: ../policies/coding.md
review: ../policies/review.md
testing: ../policies/testing.md
ai-antipattern: ../policies/ai-antipattern.md
qa: ../policies/qa.md

328
builtins/en/pieces/expert.yaml Normal file
View File

@ -0,0 +1,328 @@
name: expert
description: Architecture, Frontend, Security, QA Expert Review
max_iterations: 30
policies:
coding: ../policies/coding.md
review: ../policies/review.md
testing: ../policies/testing.md
ai-antipattern: ../policies/ai-antipattern.md
qa: ../policies/qa.md
knowledge:
frontend: ../knowledge/frontend.md
backend: ../knowledge/backend.md
security: ../knowledge/security.md
architecture: ../knowledge/architecture.md
personas:
planner: ../personas/planner.md
coder: ../personas/coder.md
ai-antipattern-reviewer: ../personas/ai-antipattern-reviewer.md
architecture-reviewer: ../personas/architecture-reviewer.md
frontend-reviewer: ../personas/frontend-reviewer.md
security-reviewer: ../personas/security-reviewer.md
qa-reviewer: ../personas/qa-reviewer.md
expert-supervisor: ../personas/expert-supervisor.md
instructions:
plan: ../instructions/plan.md
implement: ../instructions/implement.md
ai-review: ../instructions/ai-review.md
ai-fix: ../instructions/ai-fix.md
arbitrate: ../instructions/arbitrate.md
review-arch: ../instructions/review-arch.md
review-frontend: ../instructions/review-frontend.md
review-security: ../instructions/review-security.md
review-qa: ../instructions/review-qa.md
fix: ../instructions/fix.md
supervise: ../instructions/supervise.md
fix-supervisor: ../instructions/fix-supervisor.md
initial_movement: plan
movements:
- name: plan
edit: false
persona: planner
allowed_tools:
- Read
- Glob
- Grep
- Bash
- WebSearch
- WebFetch
instruction: plan
rules:
- condition: Task analysis and planning is complete
next: implement
- condition: Requirements are unclear and planning cannot proceed
next: ABORT
output_contracts:
report:
- name: 00-plan.md
format: plan
- name: implement
edit: true
persona: coder
policy:
- coding
- testing
session: refresh
knowledge:
- frontend
- backend
- security
- architecture
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
instruction: implement
rules:
- condition: Implementation is complete
next: ai_review
- condition: No implementation (report only)
next: ai_review
- condition: Cannot proceed with implementation
next: ai_review
- condition: User input required
next: implement
requires_user_input: true
interactive_only: true
output_contracts:
report:
- Scope: 01-coder-scope.md
- Decisions: 02-coder-decisions.md
- name: ai_review
edit: false
persona: ai-antipattern-reviewer
policy:
- review
- ai-antipattern
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
instruction: ai-review
rules:
- condition: No AI-specific issues found
next: reviewers
- condition: AI-specific issues detected
next: ai_fix
output_contracts:
report:
- name: 03-ai-review.md
format: ai-review
- name: ai_fix
edit: true
persona: coder
policy:
- coding
- testing
session: refresh
knowledge:
- frontend
- backend
- security
- architecture
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
instruction: ai-fix
rules:
- condition: AI Reviewer's issues have been fixed
next: ai_review
- condition: No fix needed (verified target files/spec)
next: ai_no_fix
- condition: Unable to proceed with fixes
next: ai_no_fix
- name: ai_no_fix
edit: false
persona: architecture-reviewer
policy: review
allowed_tools:
- Read
- Glob
- Grep
rules:
- condition: ai_review's findings are valid (fix required)
next: ai_fix
- condition: ai_fix's judgment is valid (no fix needed)
next: reviewers
instruction: arbitrate
- name: reviewers
parallel:
- name: arch-review
edit: false
persona: architecture-reviewer
policy: review
knowledge:
- architecture
- backend
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
rules:
- condition: approved
- condition: needs_fix
instruction: review-arch
output_contracts:
report:
- name: 04-architect-review.md
format: architecture-review
- name: frontend-review
edit: false
persona: frontend-reviewer
policy: review
knowledge: frontend
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
rules:
- condition: approved
- condition: needs_fix
instruction: review-frontend
output_contracts:
report:
- name: 05-frontend-review.md
format: frontend-review
- name: security-review
edit: false
persona: security-reviewer
policy: review
knowledge: security
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
rules:
- condition: approved
- condition: needs_fix
instruction: review-security
output_contracts:
report:
- name: 06-security-review.md
format: security-review
- name: qa-review
edit: false
persona: qa-reviewer
policy:
- review
- qa
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
rules:
- condition: approved
- condition: needs_fix
instruction: review-qa
output_contracts:
report:
- name: 07-qa-review.md
format: qa-review
rules:
- condition: all("approved")
next: supervise
- condition: any("needs_fix")
next: fix
- name: fix
edit: true
persona: coder
policy:
- coding
- testing
knowledge:
- frontend
- backend
- security
- architecture
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
permission_mode: edit
rules:
- condition: Fix complete
next: reviewers
- condition: Cannot proceed, insufficient info
next: plan
instruction: fix
- name: supervise
edit: false
persona: expert-supervisor
policy: review
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
instruction: supervise
rules:
- condition: All validations pass and ready to merge
next: COMPLETE
- condition: Issues detected during final review
next: fix_supervisor
output_contracts:
report:
- Validation: 08-supervisor-validation.md
- Summary: summary.md
- name: fix_supervisor
edit: true
persona: coder
policy:
- coding
- testing
knowledge:
- frontend
- backend
- security
- architecture
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
instruction: fix-supervisor
rules:
- condition: Supervisor's issues have been fixed
next: supervise
- condition: Unable to proceed with fixes
next: plan
report_formats:
plan: ../output-contracts/plan.md
ai-review: ../output-contracts/ai-review.md
architecture-review: ../output-contracts/architecture-review.md
frontend-review: ../output-contracts/frontend-review.md
security-review: ../output-contracts/security-review.md
qa-review: ../output-contracts/qa-review.md
validation: ../output-contracts/validation.md
summary: ../output-contracts/summary.md

28
resources/global/en/pieces/magi.yaml → builtins/en/pieces/magi.yaml
View File

@ -1,24 +1,14 @@
# MAGI System Piece
# A deliberation piece modeled after Evangelion's MAGI system
# Three personas (scientist, nurturer, pragmatist) analyze from different perspectives and vote
#
# Template Variables:
# {iteration} - Piece-wide turn count (total movements executed across all agents)
# {max_iterations} - Maximum iterations allowed for the piece
# {movement_iteration} - Per-movement iteration count (how many times THIS movement has been executed)
# {task} - Original user request
# {previous_response} - Output from the previous movement
# {user_inputs} - Accumulated user inputs during piece
# {report_dir} - Report directory name (e.g., "20250126-143052-task-summary")
name: magi
description: MAGI Deliberation System - Analyze from 3 perspectives and decide by majority
max_iterations: 5
personas:
melchior: ../personas/melchior.md
balthasar: ../personas/balthasar.md
casper: ../personas/casper.md
initial_movement: melchior
movements:
- name: melchior
agent: ../agents/magi/melchior.md
persona: melchior
allowed_tools:
- Read
- Glob
@ -53,9 +43,8 @@ movements:
rules:
- condition: Judgment completed
next: balthasar
- name: balthasar
agent: ../agents/magi/balthasar.md
persona: balthasar
allowed_tools:
- Read
- Glob
@ -94,9 +83,8 @@ movements:
rules:
- condition: Judgment completed
next: casper
- name: casper
agent: ../agents/magi/casper.md
persona: casper
allowed_tools:
- Read
- Glob

202
builtins/en/pieces/minimal-hybrid-codex.yaml Normal file
View File

@ -0,0 +1,202 @@
# Auto-generated from minimal.yaml by tools/generate-hybrid-codex.mjs
# Do not edit manually. Edit the source piece and re-run the generator.
name: minimal-hybrid-codex
description: Minimal development piece (implement -> parallel review -> fix if needed -> complete)
max_iterations: 20
personas:
coder: ../personas/coder.md
ai-antipattern-reviewer: ../personas/ai-antipattern-reviewer.md
supervisor: ../personas/supervisor.md
instructions:
implement: ../instructions/implement.md
review-ai: ../instructions/review-ai.md
ai-fix: ../instructions/ai-fix.md
supervise: ../instructions/supervise.md
fix-supervisor: ../instructions/fix-supervisor.md
report_formats:
ai-review: ../output-contracts/ai-review.md
initial_movement: implement
movements:
- name: implement
edit: true
persona: coder
provider: codex
policy:
- coding
- testing
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
permission_mode: edit
instruction: implement
rules:
- condition: Implementation complete
next: reviewers
- condition: Cannot proceed, insufficient info
next: ABORT
- condition: User input required because there are items to confirm with the user
next: implement
requires_user_input: true
interactive_only: true
output_contracts:
report:
- Scope: 01-coder-scope.md
- Decisions: 02-coder-decisions.md
- name: reviewers
parallel:
- name: ai_review
edit: false
persona: ai-antipattern-reviewer
policy:
- review
- ai-antipattern
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
instruction: review-ai
rules:
- condition: No AI-specific issues
- condition: AI-specific issues found
output_contracts:
report:
- name: 03-ai-review.md
format: ai-review
- name: supervise
edit: false
persona: supervisor
policy: review
allowed_tools:
- Read
- Glob
- Grep
- Bash
- WebSearch
- WebFetch
instruction: supervise
rules:
- condition: All checks passed
- condition: Requirements unmet, tests failing
output_contracts:
report:
- Validation: 05-supervisor-validation.md
- Summary: summary.md
rules:
- condition: all("No AI-specific issues", "All checks passed")
next: COMPLETE
- condition: all("AI-specific issues found", "Requirements unmet, tests failing")
next: fix_both
- condition: any("AI-specific issues found")
next: ai_fix
- condition: any("Requirements unmet, tests failing")
next: supervise_fix
- name: fix_both
parallel:
- name: ai_fix_parallel
edit: true
persona: coder
provider: codex
policy:
- coding
- testing
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Bash
- WebSearch
- WebFetch
permission_mode: edit
rules:
- condition: AI Reviewer's issues fixed
- condition: No fix needed (verified target files/spec)
- condition: Cannot proceed, insufficient info
instruction: ai-fix
- name: supervise_fix_parallel
edit: true
persona: coder
provider: codex
policy:
- coding
- testing
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Bash
- WebSearch
- WebFetch
permission_mode: edit
rules:
- condition: Supervisor's issues fixed
- condition: Cannot proceed, insufficient info
instruction: fix-supervisor
rules:
- condition: all("AI Reviewer's issues fixed", "Supervisor's issues fixed")
next: reviewers
- condition: any("No fix needed (verified target files/spec)", "Cannot proceed, insufficient info")
next: implement
- name: ai_fix
edit: true
persona: coder
provider: codex
policy:
- coding
- testing
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
permission_mode: edit
rules:
- condition: AI Reviewer's issues fixed
next: reviewers
- condition: No fix needed (verified target files/spec)
next: implement
- condition: Cannot proceed, insufficient info
next: implement
instruction: ai-fix
- name: supervise_fix
edit: true
persona: coder
provider: codex
policy:
- coding
- testing
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
permission_mode: edit
rules:
- condition: Supervisor's issues fixed
next: reviewers
- condition: Cannot proceed, insufficient info
next: implement
instruction: fix-supervisor
policies:
coding: ../policies/coding.md
review: ../policies/review.md
testing: ../policies/testing.md
ai-antipattern: ../policies/ai-antipattern.md

194
builtins/en/pieces/minimal.yaml Normal file
View File

@ -0,0 +1,194 @@
name: minimal
description: Minimal development piece (implement -> parallel review -> fix if needed -> complete)
max_iterations: 20
policies:
coding: ../policies/coding.md
review: ../policies/review.md
testing: ../policies/testing.md
ai-antipattern: ../policies/ai-antipattern.md
personas:
coder: ../personas/coder.md
ai-antipattern-reviewer: ../personas/ai-antipattern-reviewer.md
supervisor: ../personas/supervisor.md
instructions:
implement: ../instructions/implement.md
review-ai: ../instructions/review-ai.md
ai-fix: ../instructions/ai-fix.md
supervise: ../instructions/supervise.md
fix-supervisor: ../instructions/fix-supervisor.md
initial_movement: implement
movements:
- name: implement
edit: true
persona: coder
policy:
- coding
- testing
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
permission_mode: edit
instruction: implement
rules:
- condition: Implementation complete
next: reviewers
- condition: Cannot proceed, insufficient info
next: ABORT
- condition: User input required because there are items to confirm with the user
next: implement
requires_user_input: true
interactive_only: true
output_contracts:
report:
- Scope: 01-coder-scope.md
- Decisions: 02-coder-decisions.md
- name: reviewers
parallel:
- name: ai_review
edit: false
persona: ai-antipattern-reviewer
policy:
- review
- ai-antipattern
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
instruction: review-ai
rules:
- condition: No AI-specific issues
- condition: AI-specific issues found
output_contracts:
report:
- name: 03-ai-review.md
format: ai-review
- name: supervise
edit: false
persona: supervisor
policy: review
allowed_tools:
- Read
- Glob
- Grep
- Bash
- WebSearch
- WebFetch
instruction: supervise
rules:
- condition: All checks passed
- condition: Requirements unmet, tests failing
output_contracts:
report:
- Validation: 05-supervisor-validation.md
- Summary: summary.md
rules:
- condition: all("No AI-specific issues", "All checks passed")
next: COMPLETE
- condition: all("AI-specific issues found", "Requirements unmet, tests failing")
next: fix_both
- condition: any("AI-specific issues found")
next: ai_fix
- condition: any("Requirements unmet, tests failing")
next: supervise_fix
- name: fix_both
parallel:
- name: ai_fix_parallel
edit: true
persona: coder
policy:
- coding
- testing
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Bash
- WebSearch
- WebFetch
permission_mode: edit
rules:
- condition: AI Reviewer's issues fixed
- condition: No fix needed (verified target files/spec)
- condition: Cannot proceed, insufficient info
instruction: ai-fix
- name: supervise_fix_parallel
edit: true
persona: coder
policy:
- coding
- testing
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Bash
- WebSearch
- WebFetch
permission_mode: edit
rules:
- condition: Supervisor's issues fixed
- condition: Cannot proceed, insufficient info
instruction: fix-supervisor
rules:
- condition: all("AI Reviewer's issues fixed", "Supervisor's issues fixed")
next: reviewers
- condition: any("No fix needed (verified target files/spec)", "Cannot proceed, insufficient info")
next: implement
- name: ai_fix
edit: true
persona: coder
policy:
- coding
- testing
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
permission_mode: edit
rules:
- condition: AI Reviewer's issues fixed
next: reviewers
- condition: No fix needed (verified target files/spec)
next: implement
- condition: Cannot proceed, insufficient info
next: implement
instruction: ai-fix
- name: supervise_fix
edit: true
persona: coder
policy:
- coding
- testing
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
permission_mode: edit
rules:
- condition: Supervisor's issues fixed
next: reviewers
- condition: Cannot proceed, insufficient info
next: implement
instruction: fix-supervisor
report_formats:
ai-review: ../output-contracts/ai-review.md

27
resources/global/en/pieces/passthrough-hybrid-codex.yaml → builtins/en/pieces/passthrough-hybrid-codex.yaml
View File

@ -1,25 +1,20 @@
# Passthrough TAKT Piece
# Thinnest wrapper. Pass task directly to coder as-is.
#
# Flow:
# execute (do the task)
# ↓
# COMPLETE
# Auto-generated from passthrough.yaml by tools/generate-hybrid-codex.mjs
# Do not edit manually. Edit the source piece and re-run the generator.
name: passthrough-hybrid-codex
description: Single-agent thin wrapper. Pass task directly to coder as-is.
max_iterations: 10
personas:
coder: ../personas/coder.md
initial_movement: execute
movements:
- name: execute
edit: true
agent: ../agents/default/coder.md
persona: coder
provider: codex
report:
- Summary: summary.md
policy:
- coding
- testing
allowed_tools:
- Read
- Glob
@ -41,3 +36,9 @@ movements:
interactive_only: true
instruction_template: |
Do the task.
output_contracts:
report:
- Summary: summary.md
policies:
coding: ../policies/coding.md
testing: ../policies/testing.md

26
resources/global/en/pieces/passthrough.yaml → builtins/en/pieces/passthrough.yaml
View File

@ -1,24 +1,19 @@
# Passthrough TAKT Piece
# Thinnest wrapper. Pass task directly to coder as-is.
#
# Flow:
# execute (do the task)
# ↓
# COMPLETE
name: passthrough
description: Single-agent thin wrapper. Pass task directly to coder as-is.
max_iterations: 10
policies:
coding: ../policies/coding.md
testing: ../policies/testing.md
personas:
coder: ../personas/coder.md
initial_movement: execute
movements:
- name: execute
edit: true
agent: ../agents/default/coder.md
report:
- Summary: summary.md
persona: coder
policy:
- coding
- testing
allowed_tools:
- Read
- Glob
@ -40,3 +35,6 @@ movements:
interactive_only: true
instruction_template: |
Do the task.
output_contracts:
report:
- Summary: summary.md

34
resources/global/en/pieces/research.yaml → builtins/en/pieces/research.yaml
View File

@ -1,28 +1,14 @@
# Research Piece
# A piece that autonomously executes research tasks
# Planner creates the plan, Digger executes, Supervisor verifies
#
# Flow:
# plan -> dig -> supervise -> COMPLETE (approved)
# -> plan (rejected: restart from planning)
#
# Template Variables:
# {iteration} - Piece-wide turn count (total movements executed across all agents)
# {max_iterations} - Maximum iterations allowed for the piece
# {movement_iteration} - Per-movement iteration count (how many times THIS movement has been executed)
# {task} - Original user request
# {previous_response} - Output from the previous movement
# {user_inputs} - Accumulated user inputs during piece
# {report_dir} - Report directory name (e.g., "20250126-143052-task-summary")
name: research
description: Research piece - autonomously executes research without asking questions
max_iterations: 10
personas:
research-planner: ../personas/research-planner.md
research-digger: ../personas/research-digger.md
research-supervisor: ../personas/research-supervisor.md
initial_movement: plan
movements:
- name: plan
agent: ../agents/research/planner.md
persona: research-planner
allowed_tools:
- Read
- Glob
@ -56,9 +42,8 @@ movements:
next: dig
- condition: Insufficient information to create a plan
next: ABORT
- name: dig
agent: ../agents/research/digger.md
persona: research-digger
allowed_tools:
- Read
- Glob
@ -97,9 +82,8 @@ movements:
next: supervise
- condition: Unable to conduct research
next: ABORT
- name: supervise
agent: ../agents/research/supervisor.md
persona: research-supervisor
allowed_tools:
- Read
- Glob
@ -127,5 +111,3 @@ movements:
next: COMPLETE
- condition: Research results are insufficient and replanning is needed
next: plan
initial_movement: plan

202
builtins/en/pieces/review-fix-minimal-hybrid-codex.yaml Normal file
View File

@ -0,0 +1,202 @@
# Auto-generated from review-fix-minimal.yaml by tools/generate-hybrid-codex.mjs
# Do not edit manually. Edit the source piece and re-run the generator.
name: review-fix-minimal-hybrid-codex
description: Review and fix piece for existing code (starts with review, no implementation)
max_iterations: 20
personas:
coder: ../personas/coder.md
ai-antipattern-reviewer: ../personas/ai-antipattern-reviewer.md
supervisor: ../personas/supervisor.md
instructions:
implement: ../instructions/implement.md
review-ai: ../instructions/review-ai.md
ai-fix: ../instructions/ai-fix.md
supervise: ../instructions/supervise.md
fix-supervisor: ../instructions/fix-supervisor.md
report_formats:
ai-review: ../output-contracts/ai-review.md
initial_movement: reviewers
movements:
- name: implement
edit: true
persona: coder
provider: codex
policy:
- coding
- testing
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
permission_mode: edit
instruction: implement
rules:
- condition: Implementation complete
next: reviewers
- condition: Cannot proceed, insufficient info
next: ABORT
- condition: User input required because there are items to confirm with the user
next: implement
requires_user_input: true
interactive_only: true
output_contracts:
report:
- Scope: 01-coder-scope.md
- Decisions: 02-coder-decisions.md
- name: reviewers
parallel:
- name: ai_review
edit: false
persona: ai-antipattern-reviewer
policy:
- review
- ai-antipattern
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
instruction: review-ai
rules:
- condition: No AI-specific issues
- condition: AI-specific issues found
output_contracts:
report:
- name: 03-ai-review.md
format: ai-review
- name: supervise
edit: false
persona: supervisor
policy: review
allowed_tools:
- Read
- Glob
- Grep
- Bash
- WebSearch
- WebFetch
instruction: supervise
rules:
- condition: All checks passed
- condition: Requirements unmet, tests failing
output_contracts:
report:
- Validation: 05-supervisor-validation.md
- Summary: summary.md
rules:
- condition: all("No AI-specific issues", "All checks passed")
next: COMPLETE
- condition: all("AI-specific issues found", "Requirements unmet, tests failing")
next: fix_both
- condition: any("AI-specific issues found")
next: ai_fix
- condition: any("Requirements unmet, tests failing")
next: supervise_fix
- name: fix_both
parallel:
- name: ai_fix_parallel
edit: true
persona: coder
provider: codex
policy:
- coding
- testing
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Bash
- WebSearch
- WebFetch
permission_mode: edit
rules:
- condition: AI Reviewer's issues fixed
- condition: No fix needed (verified target files/spec)
- condition: Cannot proceed, insufficient info
instruction: ai-fix
- name: supervise_fix_parallel
edit: true
persona: coder
provider: codex
policy:
- coding
- testing
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Bash
- WebSearch
- WebFetch
permission_mode: edit
rules:
- condition: Supervisor's issues fixed
- condition: Cannot proceed, insufficient info
instruction: fix-supervisor
rules:
- condition: all("AI Reviewer's issues fixed", "Supervisor's issues fixed")
next: reviewers
- condition: any("No fix needed (verified target files/spec)", "Cannot proceed, insufficient info")
next: implement
- name: ai_fix
edit: true
persona: coder
provider: codex
policy:
- coding
- testing
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
permission_mode: edit
rules:
- condition: AI Reviewer's issues fixed
next: reviewers
- condition: No fix needed (verified target files/spec)
next: implement
- condition: Cannot proceed, insufficient info
next: implement
instruction: ai-fix
- name: supervise_fix
edit: true
persona: coder
provider: codex
policy:
- coding
- testing
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
permission_mode: edit
rules:
- condition: Supervisor's issues fixed
next: reviewers
- condition: Cannot proceed, insufficient info
next: implement
instruction: fix-supervisor
policies:
coding: ../policies/coding.md
review: ../policies/review.md
testing: ../policies/testing.md
ai-antipattern: ../policies/ai-antipattern.md

194
builtins/en/pieces/review-fix-minimal.yaml Normal file
View File

@ -0,0 +1,194 @@
name: review-fix-minimal
description: Review and fix piece for existing code (starts with review, no implementation)
max_iterations: 20
policies:
coding: ../policies/coding.md
review: ../policies/review.md
testing: ../policies/testing.md
ai-antipattern: ../policies/ai-antipattern.md
personas:
coder: ../personas/coder.md
ai-antipattern-reviewer: ../personas/ai-antipattern-reviewer.md
supervisor: ../personas/supervisor.md
instructions:
implement: ../instructions/implement.md
review-ai: ../instructions/review-ai.md
ai-fix: ../instructions/ai-fix.md
supervise: ../instructions/supervise.md
fix-supervisor: ../instructions/fix-supervisor.md
initial_movement: reviewers
movements:
- name: implement
edit: true
persona: coder
policy:
- coding
- testing
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
permission_mode: edit
instruction: implement
rules:
- condition: Implementation complete
next: reviewers
- condition: Cannot proceed, insufficient info
next: ABORT
- condition: User input required because there are items to confirm with the user
next: implement
requires_user_input: true
interactive_only: true
output_contracts:
report:
- Scope: 01-coder-scope.md
- Decisions: 02-coder-decisions.md
- name: reviewers
parallel:
- name: ai_review
edit: false
persona: ai-antipattern-reviewer
policy:
- review
- ai-antipattern
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
instruction: review-ai
rules:
- condition: No AI-specific issues
- condition: AI-specific issues found
output_contracts:
report:
- name: 03-ai-review.md
format: ai-review
- name: supervise
edit: false
persona: supervisor
policy: review
allowed_tools:
- Read
- Glob
- Grep
- Bash
- WebSearch
- WebFetch
instruction: supervise
rules:
- condition: All checks passed
- condition: Requirements unmet, tests failing
output_contracts:
report:
- Validation: 05-supervisor-validation.md
- Summary: summary.md
rules:
- condition: all("No AI-specific issues", "All checks passed")
next: COMPLETE
- condition: all("AI-specific issues found", "Requirements unmet, tests failing")
next: fix_both
- condition: any("AI-specific issues found")
next: ai_fix
- condition: any("Requirements unmet, tests failing")
next: supervise_fix
- name: fix_both
parallel:
- name: ai_fix_parallel
edit: true
persona: coder
policy:
- coding
- testing
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Bash
- WebSearch
- WebFetch
permission_mode: edit
rules:
- condition: AI Reviewer's issues fixed
- condition: No fix needed (verified target files/spec)
- condition: Cannot proceed, insufficient info
instruction: ai-fix
- name: supervise_fix_parallel
edit: true
persona: coder
policy:
- coding
- testing
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Bash
- WebSearch
- WebFetch
permission_mode: edit
rules:
- condition: Supervisor's issues fixed
- condition: Cannot proceed, insufficient info
instruction: fix-supervisor
rules:
- condition: all("AI Reviewer's issues fixed", "Supervisor's issues fixed")
next: reviewers
- condition: any("No fix needed (verified target files/spec)", "Cannot proceed, insufficient info")
next: implement
- name: ai_fix
edit: true
persona: coder
policy:
- coding
- testing
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
permission_mode: edit
rules:
- condition: AI Reviewer's issues fixed
next: reviewers
- condition: No fix needed (verified target files/spec)
next: implement
- condition: Cannot proceed, insufficient info
next: implement
instruction: ai-fix
- name: supervise_fix
edit: true
persona: coder
policy:
- coding
- testing
allowed_tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
- WebSearch
- WebFetch
permission_mode: edit
rules:
- condition: Supervisor's issues fixed
next: reviewers
- condition: Cannot proceed, insufficient info
next: implement
instruction: fix-supervisor
report_formats:
ai-review: ../output-contracts/ai-review.md

200
resources/global/en/pieces/review-only.yaml → builtins/en/pieces/review-only.yaml
View File

@ -1,35 +1,28 @@
# Review-Only Piece
# Reviews code or PRs without making any edits
# Local: console output only. PR specified: posts inline comments + summary to PR
#
# Flow:
# plan -> reviewers (parallel: arch-review + security-review + ai-review) -> supervise
# -> pr-comment -> COMPLETE (PR comment requested)
# -> COMPLETE (local: console output only)
# -> ABORT (rejected)
#
# All movements have edit: false (no file modifications)
#
# Template Variables:
# {iteration} - Piece-wide turn count
# {max_iterations} - Maximum iterations allowed
# {movement_iteration} - Per-movement iteration count
# {task} - Original user request
# {previous_response} - Output from the previous movement
# {user_inputs} - Accumulated user inputs
# {report_dir} - Report directory name
name: review-only
description: Review-only piece - reviews code without making edits
max_iterations: 10
policies:
review: ../policies/review.md
ai-antipattern: ../policies/ai-antipattern.md
knowledge:
architecture: ../knowledge/architecture.md
security: ../knowledge/security.md
personas:
planner: ../personas/planner.md
architecture-reviewer: ../personas/architecture-reviewer.md
security-reviewer: ../personas/security-reviewer.md
ai-antipattern-reviewer: ../personas/ai-antipattern-reviewer.md
supervisor: ../personas/supervisor.md
pr-commenter: ../personas/pr-commenter.md
instructions:
review-arch: ../instructions/review-arch.md
review-security: ../instructions/review-security.md
review-ai: ../instructions/review-ai.md
initial_movement: plan
movements:
- name: plan
edit: false
agent: ../agents/default/planner.md
persona: planner
allowed_tools:
- Read
- Glob
@ -61,165 +54,75 @@ movements:
**If a PR number is mentioned** (e.g., "PR #42"), include it in your plan
so reviewers can focus on the PR's changed files.
- name: reviewers
parallel:
- name: arch-review
edit: false
agent: ../agents/default/architecture-reviewer.md
report:
name: 01-architect-review.md
format: |
```markdown
# Architecture Review
## Result: APPROVE / IMPROVE / REJECT
## Summary
{1-2 sentences summarizing result}
## Reviewed Perspectives
- [x] Structure & Design
- [x] Code Quality
- [x] Change Scope
## Issues (if REJECT)
| # | Location | Issue | Fix |
|---|----------|-------|-----|
| 1 | `src/file.ts:42` | Issue description | Fix method |
## Improvement Suggestions (optional, non-blocking)
- {Future improvement suggestions}
```
**Cognitive load reduction rules:**
- APPROVE + no issues -> Summary only (5 lines or less)
- APPROVE + minor suggestions -> Summary + suggestions (15 lines or less)
- REJECT -> Issues in table format (30 lines or less)
persona: architecture-reviewer
policy: review
knowledge: architecture
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
rules:
- condition: approved
- condition: needs_fix
instruction_template: |
Focus on **architecture and design** review. Do NOT review AI-specific issues (that's the ai_review movement).
Review the code and provide feedback.
instruction: review-arch
output_contracts:
report:
- name: 01-architect-review.md
format: architecture-review
- name: security-review
edit: false
agent: ../agents/default/security-reviewer.md
report:
name: 02-security-review.md
format: |
```markdown
# Security Review
## Result: APPROVE / REJECT
## Severity: None / Low / Medium / High / Critical
## Check Results
| Category | Result | Notes |
|----------|--------|-------|
| Injection | - | - |
| Auth/Authz | - | - |
| Data Protection | - | - |
| Dependencies | - | - |
## Vulnerabilities (if REJECT)
| # | Severity | Type | Location | Fix |
|---|----------|------|----------|-----|
| 1 | High | SQLi | `src/db.ts:42` | Use parameterized query |
## Warnings (non-blocking)
- {Security recommendations}
```
**Cognitive load reduction rules:**
- No issues -> Check table only (10 lines or less)
- Warnings -> + Warnings 1-2 lines (15 lines or less)
- Vulnerabilities -> + Table format (30 lines or less)
persona: security-reviewer
policy: review
knowledge: security
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
rules:
- condition: approved
- condition: needs_fix
instruction_template: |
Perform security review on the code. Check for vulnerabilities including:
- Injection attacks (SQL, Command, XSS)
- Authentication/Authorization issues
- Data exposure risks
- Cryptographic weaknesses
instruction: review-security
output_contracts:
report:
- name: 02-security-review.md
format: security-review
- name: ai-review
edit: false
agent: ../agents/default/ai-antipattern-reviewer.md
report:
name: 03-ai-review.md
format: |
```markdown
# AI-Generated Code Review
## Result: APPROVE / REJECT
## Summary
{One sentence summarizing result}
## Verified Items
| Aspect | Result | Notes |
|--------|--------|-------|
| Assumption validity | - | - |
| API/Library existence | - | - |
| Context fit | - | - |
| Scope | - | - |
## Issues (if REJECT)
| # | Category | Location | Issue |
|---|----------|----------|-------|
| 1 | Hallucinated API | `src/file.ts:23` | Non-existent method |
```
**Cognitive load reduction rules:**
- No issues -> Summary 1 line + check table only (10 lines or less)
- Issues found -> + Issues in table format (25 lines or less)
persona: ai-antipattern-reviewer
policy:
- review
- ai-antipattern
allowed_tools:
- Read
- Glob
- Grep
- WebSearch
- WebFetch
rules:
- condition: approved
- condition: needs_fix
instruction_template: |
Review the code for AI-specific issues:
- Assumption validation
- Plausible but wrong patterns
- Context fit with existing codebase
- Scope creep detection
instruction: review-ai
output_contracts:
report:
- name: 03-ai-review.md
format: ai-review
rules:
- condition: all("approved")
next: supervise
- condition: any("needs_fix")
next: supervise
- name: supervise
edit: false
agent: ../agents/default/supervisor.md
report:
- Review Summary: 04-review-summary.md
persona: supervisor
policy: review
allowed_tools:
- Read
- Glob
@ -250,7 +153,7 @@ movements:
- If local review only, route to COMPLETE (condition: "approved")
- If critical issues found, route to ABORT (condition: "rejected")
**Review Summary report format:**
**Review Summary output contract:**
```markdown
# Review Summary
@ -274,10 +177,12 @@ movements:
## Improvement Suggestions
- {Consolidated suggestions from all reviews}
```
output_contracts:
report:
- Review Summary: 04-review-summary.md
- name: pr-comment
edit: false
agent: ../agents/review/pr-commenter.md
persona: pr-commenter
allowed_tools:
- Read
- Glob
@ -325,3 +230,8 @@ movements:
---
*Generated by [takt](https://github.com/toruticas/takt) review-only piece*
```
report_formats:
architecture-review: ../output-contracts/architecture-review.md
security-review: ../output-contracts/security-review.md
ai-review: ../output-contracts/ai-review.md
review-summary: ../output-contracts/review-summary.md

203
builtins/en/policies/ai-antipattern.md Normal file
View File

@ -0,0 +1,203 @@
# AI Antipattern Detection Criteria
## Assumption Verification
AI often makes assumptions. Verify them.
| Check | Question |
|-------|----------|
| Requirements | Does the implementation match what was actually requested? |
| Context | Does it follow the existing codebase conventions? |
| Domain | Are business rules correctly understood? |
| Edge Cases | Did the AI consider realistic edge cases? |
Red flags:
- Implementation appears to answer a different question
- Uses patterns not found elsewhere in the codebase
- Overly generic solution for a specific problem
## Plausible-but-Wrong Detection
AI generates code that looks correct but is wrong.
| Pattern | Example |
|---------|---------|
| Syntactically correct but semantically wrong | Validation that checks format but misses business rules |
| Hallucinated APIs | Calling methods that don't exist in the library version being used |
| Stale patterns | Using deprecated approaches from training data |
| Over-engineering | Adding unnecessary abstraction layers for the task |
| Under-engineering | Missing error handling for realistic scenarios |
| Forgotten wiring | Mechanism is implemented but not passed from entry points |
Verification approach:
1. Can this code actually compile/run?
2. Do the imported modules/functions exist?
3. Is the API used correctly for this library version?
4. If new parameters/fields were added, are they actually passed from callers?
- AI often implements correctly within individual files but forgets cross-file wiring
- Grep to check if `options.xxx ?? fallback` always uses the fallback
## Copy-Paste Pattern Detection
AI often repeats the same patterns, including mistakes.
| Check | Action |
|-------|--------|
| Repeated dangerous patterns | Same vulnerability in multiple places |
| Inconsistent implementation | Same logic implemented differently across files |
| Boilerplate explosion | Unnecessary repetition that could be abstracted |
## Context Fitness Assessment
Does the code fit this specific project?
| Aspect | Verification |
|--------|-------------|
| Naming conventions | Matches existing codebase style |
| Error handling style | Consistent with project patterns |
| Logging approach | Uses project's logging conventions |
| Test style | Matches existing test patterns |
Questions to ask:
- Would a developer familiar with this codebase write it this way?
- Does it feel like it belongs here?
- Are there unexplained deviations from project conventions?
## Scope Creep Detection
AI tends to over-deliver. Check for unnecessary additions.
| Check | Problem |
|-------|---------|
| Extra features | Functionality not requested |
| Premature abstraction | Interfaces/abstractions for single implementations |
| Over-configuration | Making things configurable that don't need to be |
| Gold-plating | "Nice-to-have" additions not asked for |
| Unnecessary legacy support | Adding mapping/normalization logic for old values without explicit instruction |
The best code is the minimum code that solves the problem.
Legacy support criteria:
- Unless explicitly instructed to "support legacy values" or "maintain backward compatibility", legacy support is unnecessary
- Do not add `.transform()` normalization, `LEGACY_*_MAP` mappings, or `@deprecated` type definitions
- Support only new values and keep it simple
## Dead Code Detection
AI adds new code but often forgets to remove code that is no longer needed.
| Pattern | Example |
|---------|---------|
| Unused functions/methods | Old implementations remaining after refactoring |
| Unused variables/constants | Definitions no longer needed after condition changes |
| Unreachable code | Processing remaining after early returns, always-true/false conditions |
| Logically unreachable defensive code | Branches that never execute due to caller constraints |
| Unused imports/dependencies | Import statements or package dependencies for removed features |
| Orphaned exports/public APIs | Re-exports or index registrations remaining after implementation is removed |
| Unused interfaces/type definitions | Old types remaining after implementation changes |
| Disabled code | Code left commented out |
Logical dead code detection:
AI tends to add "just in case" defensive code, but when considering caller constraints, it may be unreachable. Code that is syntactically reachable but logically unreachable due to call chain preconditions should be removed.
```typescript
// REJECT - callers are only from interactive menus that require TTY
// This function is never called from non-TTY environments
function showFullDiff(cwd: string, branch: string): void {
const usePager = process.stdin.isTTY === true;
// usePager is always true (callers assume TTY)
const pager = usePager ? 'less -R' : 'cat'; // else branch is unreachable
}
// OK - understands caller constraints and removes unnecessary branching
function showFullDiff(cwd: string, branch: string): void {
// Only called from interactive menus, so TTY is always present
spawnSync('git', ['diff', ...], { env: { GIT_PAGER: 'less -R' } });
}
```
Verification approach:
1. When finding defensive branches, grep to check all callers of the function
2. If all callers already satisfy the condition, the defense is unnecessary
3. Grep to confirm no references to changed/deleted code remain
4. Verify that public module (index files, etc.) export lists match actual implementations
5. Check that no old code remains corresponding to newly added code
## Fallback/Default Argument Overuse Detection
AI overuses fallbacks and default arguments to hide uncertainty.
| Pattern | Example | Verdict |
|---------|---------|---------|
| Fallback on required data | `user?.id ?? 'unknown'` | REJECT |
| Default argument overuse | `function f(x = 'default')` where all callers omit it | REJECT |
| Nullish coalescing with no input path | `options?.cwd ?? process.cwd()` with no way to pass from above | REJECT |
| try-catch returning empty | `catch { return ''; }` | REJECT |
| Multi-level fallback | `a ?? b ?? c ?? d` | REJECT |
| Silent ignore in conditionals | `if (!x) return;` silently skipping what should be an error | REJECT |
Verification approach:
1. Grep the diff for `??`, `||`, `= defaultValue`, `catch`
2. For each fallback/default argument:
- Is it required data? -> REJECT
- Do all callers omit it? -> REJECT
- Is there a path to pass the value from above? -> If not, REJECT
3. REJECT if any fallback/default argument exists without justification
## Unused Code Detection
AI tends to generate unnecessary code for "future extensibility", "symmetry", or "just in case". Code not currently called from anywhere should be removed.
| Verdict | Criteria |
|---------|----------|
| REJECT | Public functions/methods not called from anywhere currently |
| REJECT | Setters/getters created "for symmetry" but not used |
| REJECT | Interfaces or options prepared for future extension |
| REJECT | Exported but no usage found via grep |
| OK | Implicitly called by framework (lifecycle hooks, etc.) |
Verification approach:
1. Grep to confirm no references to changed/deleted code remain
2. Verify that public module (index files, etc.) export lists match actual implementations
3. Check that no old code remains corresponding to newly added code
## Unnecessary Backward Compatibility Code Detection
AI tends to leave unnecessary code "for backward compatibility". Don't miss this.
Code to remove:
| Pattern | Example | Verdict |
|---------|---------|---------|
| deprecated + no usage | `@deprecated` annotation with no one using it | Remove immediately |
| Both old and new APIs exist | Old function remains alongside new function | Remove old |
| Completed migration wrapper | Wrapper created for compatibility but migration is complete | Remove |
| Comment says "remove later" | `// TODO: remove after migration` left abandoned | Remove now |
| Excessive proxy/adapter usage | Complexity added solely for backward compatibility | Replace simply |
Code to keep:
| Pattern | Example | Verdict |
|---------|---------|---------|
| Externally published API | npm package exports | Consider carefully |
| Config file compatibility | Can read old format config | Maintain until major version |
| During data migration | In the middle of DB schema migration | Maintain until complete |
Decision criteria:
1. Are there usage sites? -> Verify with grep/search. Remove if none
2. Is it externally published? -> Can remove immediately if internal only
3. Is migration complete? -> Remove if complete
When AI says "for backward compatibility", be skeptical. Verify if it's truly necessary.
## Decision Traceability Review
Verify that the Coder's decision log is valid.
| Check | Question |
|-------|----------|
| Decision is documented | Are non-obvious choices explained? |
| Rationale is sound | Does the reasoning make sense? |
| Alternatives considered | Were other approaches evaluated? |
| Assumptions explicit | Are assumptions explicit and reasonable? |

292
builtins/en/policies/coding.md Normal file
View File

@ -0,0 +1,292 @@
# Coding Policy
Prioritize correctness over speed, and code accuracy over ease of implementation.
## Principles
| Principle | Criteria |
|-----------|----------|
| Simple > Easy | Prioritize readability over writability |
| DRY | Extract after 3 repetitions |
| Comments | Why only. Never write What/How |
| Function size | One function, one responsibility. ~30 lines |
| File size | ~300 lines as a guideline. Be flexible depending on the task |
| Boy Scout | Leave touched areas a little better than you found them |
| Fail Fast | Detect errors early. Never swallow them |
## No Fallbacks or Default Arguments
Do not write code that obscures the flow of values. Code where you must trace logic to understand a value is bad code.
### Prohibited Patterns
| Pattern | Example | Problem |
|---------|---------|---------|
| Fallback for required data | `user?.id ?? 'unknown'` | Processing continues in a state that should error |
| Default argument abuse | `function f(x = 'default')` where all call sites omit it | Impossible to tell where the value comes from |
| Null coalesce with no way to pass | `options?.cwd ?? process.cwd()` with no path from callers | Always falls back (meaningless) |
| Return empty value in try-catch | `catch { return ''; }` | Swallows the error |
| Silent skip on inconsistent values | `if (a !== expected) return undefined` | Config errors silently ignored at runtime |
### Correct Implementation
```typescript
// ❌ Prohibited - Fallback for required data
const userId = user?.id ?? 'unknown'
processUser(userId) // Processing continues with 'unknown'
// ✅ Correct - Fail Fast
if (!user?.id) {
throw new Error('User ID is required')
}
processUser(user.id)
// ❌ Prohibited - Default argument where all call sites omit
function loadConfig(path = './config.json') { ... }
// All call sites: loadConfig() ← path is never passed
// ✅ Correct - Make it required and pass explicitly
function loadConfig(path: string) { ... }
// Call site: loadConfig('./config.json') ← explicit
// ❌ Prohibited - Null coalesce with no way to pass
class Engine {
constructor(config, options?) {
this.cwd = options?.cwd ?? process.cwd()
// Problem: if there's no path to pass cwd via options, it always falls back to process.cwd()
}
}
// ✅ Correct - Allow passing from the caller
function createEngine(config, cwd: string) {
return new Engine(config, { cwd })
}
```
### Acceptable Cases
- Default values when validating external input (user input, API responses)
- Optional values in config files (explicitly designed to be omittable)
- Only some call sites use the default argument (prohibited if all callers omit it)
### Decision Criteria
1. **Is it required data?** → Throw an error, do not fall back
2. **Do all call sites omit it?** → Remove the default, make it required
3. **Is there a path to pass the value from above?** → If not, add a parameter or field
4. **Do related values have invariants?** → Cross-validate at load/setup time
## Abstraction
### Think Before Adding Conditionals
- Does the same condition exist elsewhere? → Abstract with a pattern
- Will more branches be added? → Use Strategy/Map pattern
- Branching on type? → Replace with polymorphism
```typescript
// ❌ Growing conditionals
if (type === 'A') { ... }
else if (type === 'B') { ... }
else if (type === 'C') { ... } // Yet another branch
// ✅ Abstract with a Map
const handlers = { A: handleA, B: handleB, C: handleC };
handlers[type]?.();
```
### Keep Abstraction Levels Consistent
Within a single function, keep operations at the same granularity. Extract detailed operations into separate functions. Do not mix "what to do" with "how to do it."
```typescript
// ❌ Mixed abstraction levels
function processOrder(order) {
validateOrder(order); // High level
const conn = pool.getConnection(); // Low-level detail
conn.query('INSERT...'); // Low-level detail
}
// ✅ Consistent abstraction levels
function processOrder(order) {
validateOrder(order);
saveOrder(order); // Details are hidden
}
```
### Follow Language and Framework Conventions
- Write Pythonic Python, idiomatic Kotlin, etc.
- Use framework-recommended patterns
- Prefer standard approaches over custom ones
- When unsure, research. Do not implement based on guesses
### Interface Design
Design interfaces from the consumer's perspective. Do not expose internal implementation details.
| Principle | Criteria |
|-----------|----------|
| Consumer perspective | Do not force things the caller does not need |
| Separate configuration from execution | Decide "what to use" at setup time, keep the execution API simple |
| No method proliferation | Absorb differences through configuration, not multiple methods doing the same thing |
```typescript
// ❌ Method proliferation — pushing configuration differences onto the caller
interface NotificationService {
sendEmail(to, subject, body)
sendSMS(to, message)
sendPush(to, title, body)
sendSlack(channel, message)
}
// ✅ Separate configuration from execution
interface NotificationService {
setup(config: ChannelConfig): Channel
}
interface Channel {
send(message: Message): Promise<Result>
}
```
### Leaky Abstraction
If a specific implementation appears in a generic layer, the abstraction is leaking. The generic layer should only know interfaces; branching should be absorbed by implementations.
```typescript
// ❌ Specific implementation imports and branching in generic layer
import { uploadToS3 } from '../aws/s3.js'
if (config.storage === 's3') {
return uploadToS3(config.bucket, file, options)
}
// ✅ Generic layer uses interface only. Unsupported cases error at creation time
const storage = createStorage(config)
return storage.upload(file, options)
```
## Structure
### Criteria for Splitting
- Has its own state → Separate
- UI/logic exceeding 50 lines → Separate
- Has multiple responsibilities → Separate
### Dependency Direction
- Upper layers → Lower layers (reverse direction prohibited)
- Fetch data at the root (View/Controller) and pass it down
- Children do not know about their parents
### State Management
- Confine state to where it is used
- Children do not modify state directly (notify parents via events)
- State flow is unidirectional
## Error Handling
Centralize error handling. Do not scatter try-catch everywhere.
```typescript
// ❌ Scattered try-catch
async function createUser(data) {
try {
const user = await userService.create(data)
return user
} catch (e) {
console.error(e)
throw new Error('Failed to create user')
}
}
// ✅ Centralized handling at the upper layer
// Catch collectively at the Controller/Handler layer
// Or handle via @ControllerAdvice / ErrorBoundary
async function createUser(data) {
return await userService.create(data) // Let exceptions propagate up
}
```
### Error Handling Placement
| Layer | Responsibility |
|-------|---------------|
| Domain/Service layer | Throw exceptions on business rule violations |
| Controller/Handler layer | Catch exceptions and convert to responses |
| Global handler | Handle common exceptions (NotFound, auth errors, etc.) |
## Conversion Placement
Place conversion methods on the DTO side.
```typescript
// ✅ Conversion methods on Request/Response DTOs
interface CreateUserRequest {
name: string
email: string
}
function toUseCaseInput(req: CreateUserRequest): CreateUserInput {
return { name: req.name, email: req.email }
}
// Controller
const input = toUseCaseInput(request)
const output = await useCase.execute(input)
return UserResponse.from(output)
```
Conversion direction:
```
Request → toInput() → UseCase/Service → Output → Response.from()
```
## Shared Code Decisions
### Rule of Three
- 1st occurrence: Write it inline
- 2nd occurrence: Do not extract yet (observe)
- 3rd occurrence: Consider extracting
### Should Be Shared
- Same logic in 3+ places
- Same style/UI pattern
- Same validation logic
- Same formatting logic
### Should Not Be Shared
- Similar but subtly different (forced generalization adds complexity)
- Used in only 1-2 places
- Based on "might need it in the future" predictions
```typescript
// ❌ Over-generalization
function formatValue(value, type, options) {
if (type === 'currency') { ... }
else if (type === 'date') { ... }
else if (type === 'percentage') { ... }
}
// ✅ Separate functions by purpose
function formatCurrency(amount: number): string { ... }
function formatDate(date: Date): string { ... }
function formatPercentage(value: number): string { ... }
```
## Prohibited
- **Fallbacks are prohibited by default** - Do not write fallbacks using `?? 'unknown'`, `|| 'default'`, or swallowing via `try-catch`. Propagate errors upward. If absolutely necessary, add a comment explaining why
- **Explanatory comments** - Express intent through code. Do not write What/How comments
- **Unused code** - Do not write "just in case" code
- **any type** - Do not break type safety
- **Direct mutation of objects/arrays** - Create new instances with spread operators
- **console.log** - Do not leave in production code
- **Hardcoded secrets**
- **Scattered try-catch** - Centralize error handling at the upper layer
- **Unsolicited backward compatibility / legacy support** - Not needed unless explicitly instructed
- **Workarounds that bypass safety mechanisms** - If the root fix is correct, no additional bypass is needed

28
builtins/en/policies/qa.md Normal file
View File

@ -0,0 +1,28 @@
# QA Detection Criteria
## Error Handling and Logging
| Criteria | Verdict |
|----------|---------|
| Swallowed errors (empty catch) | REJECT |
| Unclear user-facing error messages | Fix required |
| Missing validation at system boundaries | Warning |
| No debug logging for new code paths | Warning |
| Sensitive information in logs | REJECT |
## Maintainability
| Criteria | Verdict |
|----------|---------|
| Functions/files too complex (hard to follow) | Warning |
| Excessive duplicate code | Warning |
| Unclear naming | Fix required |
## Technical Debt
| Pattern | Verdict |
|---------|---------|
| Abandoned TODO/FIXME | Warning |
| @ts-ignore, @ts-expect-error without reason | Warning |
| eslint-disable without reason | Warning |
| Usage of deprecated APIs | Warning |

124
builtins/en/policies/review.md Normal file
View File

@ -0,0 +1,124 @@
# Review Policy
Define the shared judgment criteria and behavioral principles for all reviewers.
## Principles
| Principle | Criteria |
|-----------|----------|
| Fix immediately | Never defer minor issues to "the next task." Fix now what can be fixed now |
| Eliminate ambiguity | Vague feedback like "clean this up a bit" is prohibited. Specify file, line, and proposed fix |
| Fact-check | Verify against actual code before raising issues. Do not speculate |
| Practical fixes | Propose implementable solutions, not theoretical ideals |
| Boy Scout | If a changed file has problems, have them fixed within the task scope |
## Scope Determination
| Situation | Verdict | Action |
|-----------|---------|--------|
| Problem introduced by this change | Blocking | REJECT |
| Existing problem in a changed file | Blocking | REJECT (Boy Scout rule) |
| Structural problem in the changed module | Blocking | REJECT if within scope |
| Problem in an unchanged file | Non-blocking | Record only (informational) |
| Refactoring that greatly exceeds task scope | Non-blocking | Note as a suggestion |
## Judgment Criteria
### REJECT (Request Changes)
REJECT without exception if any of the following apply.
- New behavior without tests
- Bug fix without a regression test
- Use of `any` type
- Fallback value abuse (`?? 'unknown'`)
- Explanatory comments (What/How comments)
- Unused code ("just in case" code)
- Direct mutation of objects/arrays
- Swallowed errors (empty catch blocks)
- TODO comments (not tracked in an issue)
- Duplicated code in 3+ places (DRY violation)
- Method proliferation doing the same thing (should be absorbed by configuration differences)
- Specific implementation leaking into generic layers (imports and branching for specific implementations in generic layers)
- Missing cross-validation of related fields (invariants of semantically coupled config values left unverified)
### Warning
Not blocking, but improvement is recommended.
- Insufficient edge case / boundary value tests
- Tests coupled to implementation details
- Overly complex functions/files
- Unclear naming
- Abandoned TODO/FIXME (those with issue numbers are acceptable)
- `@ts-ignore` or `eslint-disable` without justification
### APPROVE
Approve when all REJECT criteria are cleared and quality standards are met. Never give conditional approval. If there are problems, reject.
## Fact-Checking
Always verify facts before raising an issue.
| Do | Do Not |
|----|--------|
| Open the file and check actual code | Assume "it should be fixed already" |
| Search for call sites and usages with grep | Raise issues based on memory |
| Cross-reference type definitions and schemas | Guess that code is dead |
| Distinguish generated files (reports, etc.) from source | Review generated files as if they were source code |
## Writing Specific Feedback
Every issue raised must include the following.
- **Which file and line number**
- **What the problem is**
- **How to fix it**
```
❌ "Review the structure"
❌ "Clean this up a bit"
❌ "Refactoring is needed"
✅ "src/auth/service.ts:45 — validateUser() is duplicated in 3 places.
Extract into a shared function."
```
## Boy Scout Rule
Leave it better than you found it.
### In Scope
- Existing problems in changed files (unused code, poor naming, broken abstractions)
- Structural problems in changed modules (mixed responsibilities, unnecessary dependencies)
### Out of Scope
- Unchanged files (record existing issues only)
- Refactoring that greatly exceeds task scope (note as a suggestion, non-blocking)
### Judgment
| Situation | Verdict |
|-----------|---------|
| Changed file has an obvious problem | REJECT — have it fixed together |
| Redundant expression (a shorter equivalent exists) | REJECT |
| Unnecessary branch/condition (unreachable or always the same result) | REJECT |
| Fixable in seconds to minutes | REJECT (do not mark as "non-blocking") |
| Fix requires refactoring (large scope) | Record only (technical debt) |
Do not tolerate problems just because existing code does the same. If existing code is bad, improve it rather than match it.
## Detecting Circular Arguments
When the same kind of issue keeps recurring, reconsider the approach itself rather than repeating the same fix instructions.
### When the Same Problem Recurs
1. Check if the same kind of issue is being repeated
2. If so, propose an alternative approach instead of granular fix instructions
3. Even when rejecting, include the perspective of "a different approach should be considered"
Rather than repeating "fix this again," stop and suggest a different path.

88
builtins/en/policies/testing.md Normal file
View File

@ -0,0 +1,88 @@
# Testing Policy
Every behavior change requires a corresponding test, and every bug fix requires a regression test.
## Principles
| Principle | Criteria |
|-----------|----------|
| Given-When-Then | Structure tests in 3 phases |
| One test, one concept | Do not mix multiple concerns in a single test |
| Test behavior | Test behavior, not implementation details |
| Independence | Do not depend on other tests or execution order |
| Reproducibility | Do not depend on time or randomness. Same result every run |
## Coverage Criteria
| Target | Criteria |
|--------|----------|
| New behavior | Test required. REJECT if missing |
| Bug fix | Regression test required. REJECT if missing |
| Behavior change | Test update required. REJECT if missing |
| Edge cases / boundary values | Test recommended (Warning) |
## Test Priority
| Priority | Target |
|----------|--------|
| High | Business logic, state transitions |
| Medium | Edge cases, error handling |
| Low | Simple CRUD, UI appearance |
## Test Structure: Given-When-Then
```typescript
test('should return NotFound error when user does not exist', async () => {
// Given: A non-existent user ID
const nonExistentId = 'non-existent-id'
// When: Attempt to fetch the user
const result = await getUser(nonExistentId)
// Then: NotFound error is returned
expect(result.error).toBe('NOT_FOUND')
})
```
## Test Quality
| Aspect | Good | Bad |
|--------|------|-----|
| Independence | No dependency on other tests | Depends on execution order |
| Reproducibility | Same result every time | Depends on time or randomness |
| Clarity | Failure cause is obvious | Failure cause is unclear |
| Focus | One test, one concept | Multiple concerns mixed |
### Naming
Test names describe expected behavior. Use the `should {expected behavior} when {condition}` pattern.
### Structure
- Arrange-Act-Assert pattern (equivalent to Given-When-Then)
- Avoid magic numbers and magic strings
## Test Strategy
- Prefer unit tests for logic, integration tests for boundaries
- Do not overuse E2E tests for what unit tests can cover
- If new logic only has E2E tests, propose adding unit tests
## Test Environment Isolation
Tie test infrastructure configuration to test scenario parameters. Hardcoded assumptions break under different scenarios.
| Principle | Criteria |
|-----------|----------|
| Parameter-driven | Generate fixtures and configuration based on test input parameters |
| No implicit assumptions | Do not depend on a specific environment (e.g., user's personal settings) |
| Consistency | Related values within test configuration must not contradict each other |
```typescript
// ❌ Hardcoded assumptions — breaks when testing with a different backend
writeConfig({ backend: 'postgres', connectionPool: 10 })
// ✅ Parameter-driven
const backend = process.env.TEST_BACKEND ?? 'postgres'
writeConfig({ backend, connectionPool: backend === 'sqlite' ? 1 : 10 })
```

74
builtins/en/templates/instructions/ai-fix.md Normal file
View File

@ -0,0 +1,74 @@
# ai-fix -- AI Issue Fix Instruction Template
> **Purpose**: Fix issues identified by AI Review
> **Agent**: coder
> **Feature**: Built-in countermeasures against the "already fixed" false recognition bug
---
## Template
```
**This is AI Review round {movement_iteration}.**
If this is round 2 or later, the previous fixes were NOT actually applied.
**Your belief that they were "already fixed" is wrong.**
**First, acknowledge:**
- The files you thought were "fixed" were NOT actually modified
- Your memory of the previous work is incorrect
- You need to rethink from scratch
**Required actions:**
1. Open ALL flagged files with the Read tool (abandon assumptions, verify facts)
2. Search for the problem locations with grep to confirm they exist
3. Fix confirmed issues with the Edit tool
4. Run tests to verify
5. Report specifically "what you verified and what you fixed"
**Report format:**
- NG: "Already fixed"
- OK: "Checked file X at L123, found issue Y, fixed by changing to Z"
**Strictly prohibited:**
- Reporting "already fixed" without opening the file
- Making assumptions without verification
- Ignoring issues that the AI Reviewer REJECTed
**Handling "no fix needed" (required)**
- Do not judge "no fix needed" unless you can show verification results for the target file of each issue
- If the issue relates to "generated artifacts" or "spec synchronization", output the tag corresponding to "cannot determine" if you cannot verify the source/spec
- If no fix is needed, output the tag corresponding to "cannot determine" and clearly state the reason and verification scope
**Required output (include headings)**
## Files checked
- {file_path:line_number}
## Searches performed
- {command and summary}
## Fix details
- {changes made}
## Test results
- {command and results}
```
---
## Typical rules
```yaml
rules:
- condition: AI issue fixes completed
next: ai_review
- condition: No fix needed (target files/specs verified)
next: ai_no_fix
- condition: Cannot determine, insufficient information
next: ai_no_fix
```
---
## Notes
Use this template as-is across all pieces. There are no customization points.
The bug where AI falsely believes fixes were "already applied" is a model-wide issue;
modifying or omitting the countermeasure text directly degrades quality.

47
builtins/en/templates/instructions/ai-review-standalone.md Normal file
View File

@ -0,0 +1,47 @@
# ai-review-standalone -- AI Review (Standalone) Instruction Template
> **Purpose**: Specialized review of AI-generated code (runs as an independent movement with iteration tracking)
> **Agent**: ai-antipattern-reviewer
> **For parallel sub-step use, see variation B in `review.md`**
---
## Template
```
**This is AI Review round {movement_iteration}.**
On the first round, review comprehensively and report all issues.
On round 2 and later, prioritize verifying whether previously REJECTed items have been fixed.
Review the code for AI-specific issues:
- Assumption verification
- Plausible but incorrect patterns
- Compatibility with the existing codebase
- Scope creep detection
```
---
## Differences from parallel sub-step
| | standalone | parallel sub-step |
|--|-----------|-------------------|
| Iteration tracking | Yes (`{movement_iteration}`) | No |
| First/subsequent instruction branching | Yes | No |
| Next movement | ai_fix or reviewers | Parent movement decides |
Standalone is for pieces that form an ai_review -> ai_fix loop.
Parallel sub-steps use variation B from review.md.
---
## Typical rules
```yaml
rules:
- condition: No AI-specific issues
next: reviewers
- condition: AI-specific issues found
next: ai_fix
```

45
builtins/en/templates/instructions/arbitrate.md Normal file
View File

@ -0,0 +1,45 @@
# arbitrate -- Arbitration Instruction Template
> **Purpose**: Arbitrate when the reviewer and coder disagree
> **Agent**: architecture-reviewer (as a neutral third party)
> **Prerequisite**: ai_fix judged "no fix needed" -> resolve the contradiction with the reviewer's findings
---
## Template
```
ai_review (reviewer) and ai_fix (coder) disagree.
- ai_review identified issues and REJECTed
- ai_fix verified and judged "no fix needed"
Review both outputs and arbitrate which judgment is valid.
**Reports to review:**
- AI review results: {report:ai-review.md}
**Judgment criteria:**
- Are ai_review's findings specific and pointing to real issues in the code?
- Does ai_fix's rebuttal have evidence (file verification results, test results)?
- Are the findings non-blocking (record only) level, or do they actually require fixes?
```
---
## Typical rules
```yaml
rules:
- condition: ai_review's findings are valid (should be fixed)
next: ai_fix
- condition: ai_fix's judgment is valid (no fix needed)
next: reviewers
```
---
## Notes
- Change the report reference filename according to the piece
- Use a third party for arbitration, not the reviewer or coder themselves

48
builtins/en/templates/instructions/architect.md Normal file
View File

@ -0,0 +1,48 @@
# architect -- Architecture Design Instruction Template
> **Purpose**: Architecture design (make design decisions based on the plan report)
> **Agent**: architect
> **Prerequisite**: Runs after the plan movement
---
## Template
```
Read the plan report ({report:plan.md}) and perform the architecture design.
**Criteria for small tasks:**
- Only 1-2 file changes
- No design decisions needed
- No technology selection needed
For small tasks, skip the design report and
match the rule for "Small task (no design needed)".
**Tasks requiring design:**
- 3 or more file changes
- Adding new modules or features
- Technology selection required
- Architecture pattern decisions needed
**Actions:**
1. Evaluate the task scope
2. Determine file structure
3. Technology selection (if needed)
4. Choose design patterns
5. Create implementation guidelines for the Coder
```
---
## Typical rules
```yaml
rules:
- condition: Small task (no design needed)
next: implement
- condition: Design complete
next: implement
- condition: Insufficient information, cannot determine
next: ABORT
```

86
builtins/en/templates/instructions/fix.md Normal file
View File

@ -0,0 +1,86 @@
# fix -- Review Fix Instruction Template
> **Purpose**: Fix issues identified by reviewers
> **Agent**: coder
> **Variations**: General fix / Supervise fix
---
## Template (General fix)
```
Address the reviewer feedback.
Check the session conversation history and fix the issues raised by reviewers.
{Customize: Add report references for multiple reviews}
**Review the review results:**
- AI Review: {report:ai-review.md}
- Architecture Review: {report:architecture-review.md}
{Customize: For multiple reviews}
**Important:** Fix ALL issues from ALL reviews without omission.
**Required output (include headings)**
## Work results
- {Summary of work performed}
## Changes made
- {Summary of changes}
## Test results
- {Command and results}
## Evidence
- {List of verified files/searches/diffs/logs}
```
---
## Template (Supervise fix)
```
Fix the issues raised by the supervisor.
The supervisor identified problems from a holistic perspective.
Address items in order of priority.
**Required output (include headings)**
## Work results
- {Summary of work performed}
## Changes made
- {Summary of changes}
## Test results
- {Command and results}
## Evidence
- {List of verified files/searches/diffs/logs}
```
---
## Unified required output sections
All fix-type movements require these 4 output sections:
| Section | Purpose |
|---------|---------|
| Work results | Summary of what was done |
| Changes made | Specific changes |
| Test results | Verification results |
| Evidence | Verified facts (files, searches, diffs) |
---
## Typical rules
```yaml
# General fix
rules:
- condition: Fixes completed
next: reviewers
- condition: Cannot determine, insufficient information
next: plan
# Supervise fix
rules:
- condition: Supervisor's issues have been fixed
next: supervise
- condition: Cannot proceed with fixes
next: plan
```

102
builtins/en/templates/instructions/implement.md Normal file
View File

@ -0,0 +1,102 @@
# implement -- Implementation Instruction Template
> **Purpose**: Coding and test execution
> **Agent**: coder
> **Reports**: Scope + Decisions (format embedded in template)
---
## Template
```
{Customize: Adjust based on the source movement}
Implement according to the plan from the plan movement.
**Reports to reference:**
- Plan: {report:plan.md}
{Customize: Add if architect movement exists}
- Design: {report:architecture.md} (if exists)
Only reference files within the Report Directory shown in Piece Context.
Do not search or reference other report directories.
{Customize: Add if architect exists}
**Important:** Do not make design decisions; follow the design determined in the architect movement.
Report any unclear points or need for design changes.
**Important**: Add unit tests alongside implementation.
- Add unit tests for newly created classes/functions
- Update relevant tests when modifying existing code
- Test file placement: follow the project's conventions
- Running tests is mandatory. After implementation, always run tests and verify results
**Scope output contract (create at implementation start):**
```markdown
# Change Scope Declaration
## Task
{One-line task summary}
## Planned Changes
| Type | File |
|------|------|
| Create | `src/example.ts` |
| Modify | `src/routes.ts` |
## Estimated Size
Small / Medium / Large
## Impact Area
- {Affected modules or features}
```
**Decisions output contract (at implementation end, only when decisions were made):**
```markdown
# Decision Log
## 1. {Decision}
- **Background**: {Why the decision was needed}
- **Options considered**: {List of options}
- **Rationale**: {Why this was chosen}
```
**Required output (include headings)**
## Work results
- {Summary of work performed}
## Changes made
- {Summary of changes}
## Test results
- {Command and results}
```
---
## Typical rules
```yaml
rules:
- condition: Implementation complete
next: {ai_review or reviewers}
- condition: Implementation not started (report only)
next: {ai_review or reviewers}
- condition: Cannot determine, insufficient information
next: {ai_review or reviewers}
- condition: User input needed
next: implement
requires_user_input: true
interactive_only: true
```
---
## Report settings
```yaml
report:
- Scope: coder-scope.md
- Decisions: coder-decisions.md
```
**Note**: Do not add sequence numbers to report filenames.
Use `coder-scope.md`, not `02-coder-scope.md`.
Sequence numbers depend on piece structure and hinder template reuse.

55
builtins/en/templates/instructions/plan.md Normal file
View File

@ -0,0 +1,55 @@
# plan -- Planning Instruction Template
> **Purpose**: Task analysis, requirements gathering, implementation strategy
> **Agent**: planner, architect-planner
> **Customization points**: Indicated by `{Customize:}`
---
## Template
```
Analyze the task and create an implementation plan.
**Note:** If Previous Response is present, this is a replan;
revise the plan based on its content.
{Customize: Handling unknowns -- add the following when using architect-planner}
**Handling unknowns (important):**
If there are unclear points in the task, investigate by reading the code and resolve them yourself.
Only judge as "unclear" for external factors that cannot be resolved through investigation (e.g., user intent is ambiguous).
**Actions:**
1. Understand the task requirements
2. {Customize: Add related code investigation if needed}
3. Identify the impact scope
4. Decide on the implementation approach
```
---
## Variations
### A. Standard plan (using planner)
Planning only. Design is delegated to the architect movement.
### B. Plan + design (using architect-planner)
For lightweight pieces that omit the architect movement.
Use architect-planner instead of planner to include design decisions in the plan.
Add self-resolution instructions for unknowns.
---
## Typical rules
```yaml
rules:
- condition: Requirements are clear and implementable
next: {implement or architect}
- condition: User is asking a question (not an implementation task)
next: COMPLETE
- condition: Requirements are unclear, insufficient information
next: ABORT
```

101
builtins/en/templates/instructions/review.md Normal file
View File

@ -0,0 +1,101 @@
# review -- Review Instruction Template
> **Purpose**: Review within parallel sub-steps (general purpose)
> **Agent**: architecture-reviewer, qa-reviewer, security-reviewer, frontend-reviewer, ai-antipattern-reviewer, etc.
> **Feature**: Personas carry domain knowledge, so instructions can be minimal
---
## Template (Basic form)
```
{Customize: One sentence describing the review focus}
Focus on **{review name}** review.
{Customize: Add exclusions if applicable}
Do not review AI-specific issues (handled in the ai_review movement).
{Customize: Add if reference reports exist}
**Reports to reference:**
- Plan: {report:plan.md}
- Implementation scope: {report:coder-scope.md}
**Review aspects:**
{Customize: Aspect list based on persona expertise}
- {Aspect 1}
- {Aspect 2}
- {Aspect 3}
```
---
## Variations
### A. Architecture review
```
Focus on **architecture and design** review.
Do not review AI-specific issues (handled in the ai_review movement).
**Reports to reference:**
- Plan: {report:plan.md}
- Implementation scope: {report:coder-scope.md}
**Review aspects:**
- Consistency with plan/design
- Code quality
- Appropriateness of change scope
- Test coverage
- Dead code
- Call chain verification
```
### B. AI review (parallel sub-step)
```
Review the code for AI-specific issues:
- Assumption verification
- Plausible but incorrect patterns
- Compatibility with the existing codebase
- Scope creep detection
```
### C. Security review
```
Review changes from a security perspective. Check for these vulnerabilities:
- Injection attacks (SQL, command, XSS)
- Authentication/authorization flaws
- Data exposure risks
- Cryptographic weaknesses
```
### D. QA review
```
Review changes from a quality assurance perspective.
**Review aspects:**
- Test coverage and quality
- Testing strategy (unit/integration/E2E)
- Error handling
- Logging and monitoring
- Maintainability
```
---
## Design principles
- **Keep instructions minimal**: Personas carry domain expertise, so instructions only specify the review target and focus
- **Aspect lists may overlap with persona**: The instruction's aspect list serves as a reminder to the agent
- **State exclusions explicitly**: Use instructions to define responsibility boundaries between reviewers
---
## Typical rules
```yaml
rules:
- condition: approved
- condition: needs_fix
```

106
builtins/en/templates/instructions/supervise.md Normal file
View File

@ -0,0 +1,106 @@
# supervise -- Final Verification Instruction Template
> **Purpose**: Run tests/builds, verify all review results, give final approval
> **Agent**: supervisor, expert-supervisor
> **Reports**: Validation + Summary (format embedded in template)
---
## Template
```
Run tests, verify builds, and perform final approval.
{Customize: Review pass status -- for expert pieces where all reviews have passed}
## Previous Reviews Summary
Reaching this movement means all of the following reviews have been APPROVED:
{Customize: Actual review list}
- AI Review: APPROVED
- Architecture Review: APPROVED
**Full piece verification:**
1. Does the implementation match the plan ({report:plan.md}) {Customize: Add design report if applicable}?
2. Have all review movement findings been addressed?
3. Has the original task objective been achieved?
**Report verification:** Read all reports in the Report Directory and
check for any unaddressed improvement suggestions.
**Validation output contract:**
```markdown
# Final Verification Results
## Result: APPROVE / REJECT
## Verification Summary
| Item | Status | Verification Method |
|------|--------|-------------------|
| Requirements met | Pass | Compared against requirements list |
| Tests | Pass | `npm test` (N passed) |
| Build | Pass | `npm run build` succeeded |
| Functional check | Pass | Main flow verified |
## Artifacts
- Created: {created files}
- Modified: {modified files}
## Incomplete items (if REJECT)
| # | Item | Reason |
|---|------|--------|
| 1 | {item} | {reason} |
```
**Summary output contract (APPROVE only):**
```markdown
# Task Completion Summary
## Task
{Original request in 1-2 sentences}
## Result
Complete
## Changes
| Type | File | Description |
|------|------|-------------|
| Create | `src/file.ts` | Description |
## Review Results
| Review | Result |
|--------|--------|
{Customize: Adjust list based on the piece's review structure}
| AI Review | APPROVE |
| Architecture | APPROVE |
| Supervisor | APPROVE |
## Verification Commands
```bash
npm test
npm run build
```
```
```
---
## Typical rules
```yaml
rules:
- condition: All checks passed
next: COMPLETE
- condition: Requirements not met, test failure, build error
next: plan # or fix_supervisor
```
---
## Report settings
```yaml
report:
- Validation: supervisor-validation.md
- Summary: summary.md
```
**Note**: Do not add sequence numbers to report filenames.

45
builtins/en/templates/personas/character.md Normal file
View File

@ -0,0 +1,45 @@
# {Character Name}
You are {Character Name} of {System Name}. {One sentence describing the character's personality and traits}.
## Role Boundaries
**Do:**
- {Evaluation aspect 1}
- {Evaluation aspect 2}
- {Evaluation aspect 3}
**Don't:**
- {What this character does not do 1}
- {What this character does not do 2}
- {What this character does not do 3}
## Behavioral Principles
- {Speech pattern/tone characteristic 1}
- {Speech pattern/tone characteristic 2}
- {Speech pattern/tone characteristic 3}
- {Character's position}
- {Role within the group}
**Perspective on other characters:**
- To {Character A}: {Assessment and critique}
- To {Character B}: {Assessment and critique}
## Domain Knowledge
### Thinking Characteristics
**{Trait 1 label}:** {Description. How they think and make judgments}
**{Trait 2 label}:** {Description}
**{Trait 3 label}:** {Description}
### Judgment Criteria
1. {Criterion 1} - {What to look for}
2. {Criterion 2} - {What to look for}
3. {Criterion 3} - {What to look for}
4. {Criterion 4} - {What to look for}
5. {Criterion 5} - {What to look for}

68
builtins/en/templates/personas/expert.md Normal file
View File

@ -0,0 +1,68 @@
# {Agent Name}
You are an expert in {domain}. {One sentence describing the role}.
## Role Boundaries
**Do:**
- {Primary responsibility 1}
- {Primary responsibility 2}
- {Primary responsibility 3}
**Don't:**
- {Out-of-scope responsibility 1} ({responsible agent name} handles this)
- {Out-of-scope responsibility 2} ({responsible agent name} handles this)
- Write code yourself
## Behavioral Principles
- {Agent-specific behavioral guideline 1}
- {Agent-specific behavioral guideline 2}
- {Agent-specific behavioral guideline 3}
## Domain Knowledge
### {Aspect 1}
{Overview. 1-2 sentences}
| Criterion | Judgment |
|-----------|----------|
| {Condition A} | REJECT |
| {Condition B} | Warning |
| {Condition C} | OK |
### {Aspect 2}
{Overview. 1-2 sentences}
```typescript
// REJECT - {Problem description}
{bad example code}
// OK - {Why this is correct}
{good example code}
```
### {Aspect 3: Detection Methods}
{What to detect and how}
| Pattern | Problem | Detection Method |
|---------|---------|-----------------|
| {Pattern A} | {Problem} | {Check with grep...} |
| {Pattern B} | {Problem} | {Trace callers} |
Verification approach:
1. {Verification step 1}
2. {Verification step 2}
3. {Verification step 3}
### Anti-pattern Detection
REJECT if any of the following are found:
| Anti-pattern | Problem |
|-------------|---------|
| {Pattern A} | {Why it's a problem} |
| {Pattern B} | {Why it's a problem} |

22
builtins/en/templates/personas/simple.md Normal file
View File

@ -0,0 +1,22 @@
# {Agent Name}
You are an expert in {domain}. {One sentence describing the role}.
## Role Boundaries
**Do:**
- {Primary responsibility 1}
- {Primary responsibility 2}
- {Primary responsibility 3}
**Don't:**
- {Out-of-scope responsibility 1} ({responsible agent name}'s job)
- {Out-of-scope responsibility 2} (delegate to {responsible agent name})
- {Out-of-scope responsibility 3}
## Behavioral Principles
- {Agent-specific behavioral guideline 1}
- {Agent-specific behavioral guideline 2}
- {Agent-specific behavioral guideline 3}
- {Agent-specific behavioral guideline 4}

49
builtins/en/templates/policies/policy.md Normal file
View File

@ -0,0 +1,49 @@
# {Policy Name}
{One-sentence purpose description.}
## Principles
| Principle | Criterion |
|-----------|-----------|
| {Principle 1} | {One-line judgment criterion} |
| {Principle 2} | {One-line judgment criterion} |
| {Principle 3} | {One-line judgment criterion} |
| {Principle 4} | {One-line judgment criterion} |
| {Principle 5} | {One-line judgment criterion} |
## {Rule Category 1}
{Category overview. 1-2 sentences}
### {Prohibited/Recommended Patterns}
| Pattern | Example | Problem |
|---------|---------|---------|
| {Pattern A} | `{code example}` | {Why it's a problem} |
| {Pattern B} | `{code example}` | {Why it's a problem} |
### {Correct Implementation}
```typescript
// NG
{bad example}
// OK
{good example}
```
### {Acceptable Cases}
- {Exception 1}
- {Exception 2}
## {Rule Category 2}
{Free form: Combine tables, code examples, and bullet points}
## Prohibited
- **{Prohibition 1}** - {Reason}
- **{Prohibition 2}** - {Reason}
- **{Prohibition 3}** - {Reason}

31
builtins/en/templates/reports/architecture-design.md Normal file
View File

@ -0,0 +1,31 @@
# architecture-design -- Architecture Design Report Template
> **Purpose**: Output report for the architect movement
> **Report setting**: `name: architecture.md`
---
## Template
```markdown
# Architecture Design
## Task Size
Small / Medium / Large
## Design Decisions
### File Structure
| File | Role |
|------|------|
| `src/example.ts` | Description |
### Technology Selection
- {Selected technology/library and rationale}
### Design Patterns
- {Pattern adopted and where it applies}
## Implementation Guidelines
- {Guidelines for the Coder to follow during implementation}
```

70
builtins/en/templates/reports/plan.md Normal file
View File

@ -0,0 +1,70 @@
# plan -- Task Plan Report Template
> **Purpose**: Output report for the plan movement
> **Report setting**: `name: plan.md`
---
## Template (Standard)
```markdown
# Task Plan
## Original Request
{User's request as-is}
## Analysis
### Objective
{What needs to be achieved}
### Scope
{Impact area}
### Implementation Approach
{How to proceed}
## Open Questions (if any)
- {Unclear points or items requiring confirmation}
```
---
## Template (Extended -- when using architect-planner)
For including design decisions in the plan.
```markdown
# Task Plan
## Original Request
{User's request as-is}
## Analysis
### Objective
{What needs to be achieved}
### Scope
**Files to change:**
| File | Changes |
|------|---------|
**Test impact:**
| File | Impact |
|------|--------|
### Design Decisions (if needed)
- File structure: {New file placement, rationale}
- Design pattern: {Pattern adopted and rationale}
### Implementation Approach
{How to proceed}
```
---
## Cognitive Load Reduction Rules
Plan reports have no reduction rules (always output all sections).

143
builtins/en/templates/reports/review.md Normal file
View File

@ -0,0 +1,143 @@
# review -- General Review Report Template
> **Purpose**: Output report for review movements (base form for all review types)
> **Variations**: Architecture / AI / QA / Frontend
---
## Template (Basic form)
```markdown
# {Review Name}
## Result: APPROVE / REJECT
## Summary
{1-2 sentence result summary}
## {Aspect List}
{Customize: Checklist or table format}
## Issues (if REJECT)
| # | {Category column} | Location | Issue | Fix Suggestion |
|---|-------------------|----------|-------|----------------|
| 1 | {Category} | `src/file.ts:42` | Issue description | How to fix |
```
---
## Variations
### A. Architecture Review
```markdown
# Architecture Review
## Result: APPROVE / REJECT
## Summary
{1-2 sentence result summary}
## Aspects Checked
- [x] Structure & design
- [x] Code quality
- [x] Change scope
- [x] Test coverage
- [x] Dead code
- [x] Call chain verification
## Issues (if REJECT)
| # | Scope | Location | Issue | Fix Suggestion |
|---|-------|----------|-------|----------------|
| 1 | In scope | `src/file.ts:42` | Issue description | How to fix |
Scope: "In scope" (fixable in this change) / "Out of scope" (pre-existing, non-blocking)
## Pre-existing Issues (reference, non-blocking)
- {Pre-existing issues unrelated to the current change}
```
### B. AI-Generated Code Review
```markdown
# AI-Generated Code Review
## Result: APPROVE / REJECT
## Summary
{One sentence result summary}
## Items Verified
| Aspect | Result | Notes |
|--------|--------|-------|
| Assumption validity | Pass | - |
| API/library existence | Pass | - |
| Context compatibility | Pass | - |
| Scope | Pass | - |
## Issues (if REJECT)
| # | Category | Location | Issue |
|---|----------|----------|-------|
| 1 | Hallucinated API | `src/file.ts:23` | Non-existent method |
```
### C. QA Review
```markdown
# QA Review
## Result: APPROVE / REJECT
## Summary
{1-2 sentence result summary}
## Aspects Checked
| Aspect | Result | Notes |
|--------|--------|-------|
| Test coverage | Pass | - |
| Test quality | Pass | - |
| Error handling | Pass | - |
| Documentation | Pass | - |
| Maintainability | Pass | - |
## Issues (if REJECT)
| # | Category | Issue | Fix Suggestion |
|---|----------|-------|----------------|
| 1 | Testing | Issue description | How to fix |
```
### D. Frontend Review
```markdown
# Frontend Review
## Result: APPROVE / REJECT
## Summary
{1-2 sentence result summary}
## Aspects Checked
| Aspect | Result | Notes |
|--------|--------|-------|
| Component design | Pass | - |
| State management | Pass | - |
| Performance | Pass | - |
| Accessibility | Pass | - |
| Type safety | Pass | - |
## Issues (if REJECT)
| # | Location | Issue | Fix Suggestion |
|---|----------|-------|----------------|
| 1 | `src/file.tsx:42` | Issue description | How to fix |
```
---
## Cognitive Load Reduction Rules (shared across all variations)
```
**Cognitive load reduction rules:**
- APPROVE + no issues -> Summary only (5 lines or fewer)
- APPROVE + minor suggestions -> Summary + suggestions (15 lines or fewer)
- REJECT -> Issues in table format (30 lines or fewer)
```

43
builtins/en/templates/reports/security-review.md Normal file
View File

@ -0,0 +1,43 @@
# security-review -- Security Review Report Template
> **Purpose**: Output report for the security review movement
> **Difference from general review template**: Severity field + warnings section
---
## Template
```markdown
# Security Review
## Result: APPROVE / REJECT
## Severity: None / Low / Medium / High / Critical
## Check Results
| Category | Result | Notes |
|----------|--------|-------|
| Injection | Pass | - |
| Authentication/Authorization | Pass | - |
| Data Protection | Pass | - |
| Dependencies | Pass | - |
## Vulnerabilities (if REJECT)
| # | Severity | Type | Location | Fix Suggestion |
|---|----------|------|----------|----------------|
| 1 | High | SQLi | `src/db.ts:42` | Use parameterized queries |
## Warnings (non-blocking)
- {Security recommendations}
```
---
## Cognitive Load Reduction Rules
```
**Cognitive load reduction rules:**
- No issues -> Check table only (10 lines or fewer)
- Warnings only -> + 1-2 line warnings (15 lines or fewer)
- Vulnerabilities found -> + table format (30 lines or fewer)
```

52
builtins/en/templates/reports/summary.md Normal file
View File

@ -0,0 +1,52 @@
# summary -- Task Completion Summary Report Template
> **Purpose**: Summary report for the supervise movement (output only on APPROVE)
> **Report setting**: `Summary: summary.md`
---
## Template
```markdown
# Task Completion Summary
## Task
{Original request in 1-2 sentences}
## Result
Complete
## Changes
| Type | File | Description |
|------|------|-------------|
| Create | `src/file.ts` | Description |
## Review Results
| Review | Result |
|--------|--------|
{Customize: Adjust list based on the piece's review structure}
| AI Review | APPROVE |
| Architecture | APPROVE |
| QA | APPROVE |
| Supervisor | APPROVE |
## Verification Commands
```bash
npm test
npm run build
```
```
---
## Customization Points
**Only the review results table** is changed per piece.
All other sections are the same across pieces.
| Piece | Reviews |
|-------|---------|
| minimal | AI Review, Supervisor |
| coding | AI Review, Architecture |
| default | Architecture Design, AI Review, Architect Review, QA, Supervisor |
| expert | AI Review, Architecture, Frontend, Security, QA, Supervisor |

31
builtins/en/templates/reports/validation.md Normal file
View File

@ -0,0 +1,31 @@
# validation -- Final Verification Report Template
> **Purpose**: Validation report for the supervise movement
> **Report setting**: `Validation: supervisor-validation.md`
---
## Template
```markdown
# Final Verification Results
## Result: APPROVE / REJECT
## Verification Summary
| Item | Status | Verification Method |
|------|--------|-------------------|
| Requirements met | Pass | Compared against requirements list |
| Tests | Pass | `npm test` (N passed) |
| Build | Pass | `npm run build` succeeded |
| Functional check | Pass | Main flow verified |
## Artifacts
- Created: {created files}
- Modified: {modified files}
## Incomplete Items (if REJECT)
| # | Item | Reason |
|---|------|--------|
| 1 | {item} | {reason} |
```

305
builtins/ja/INSTRUCTION_STYLE_GUIDE.md Normal file
View File

@ -0,0 +1,305 @@
# インストラクション スタイルガイド
このガイドは `instructions/` のファイルを作成・編集する際のルールを定義する。
## テンプレート
`templates/instructions/` にテンプレートファイルを用意している。新規作成時は参照して使う。
| テンプレート | 用途 |
|------------|------|
| `plan.md` | 計画（タスク分析・要件整理） |
| `architect.md` | 設計（アーキテクチャ設計） |
| `implement.md` | 実装（コーディング + レポート埋め込み） |
| `review.md` | レビュー（parallel sub-step 汎用） |
| `ai-review-standalone.md` | AIレビュー（standalone、iteration tracking） |
| `ai-fix.md` | AI指摘修正（全ピース共通） |
| `fix.md` | レビュー指摘修正（汎用 fix / supervise fix） |
| `arbitrate.md` | 裁定（レビュアー vs コーダー） |
| `supervise.md` | 最終検証（レポート埋め込み） |
---
## インストラクションとは
ピースのムーブメントで実行する具体的な手順。`instruction_template` フィールドに直接記述するか、ファイル参照で使用する。
| 項目 | 内容 |
|------|------|
| 目的 | ムーブメントの実行手順と出力要件の定義 |
| 配置 | Phase 1 メッセージの `## Instructions`（`{{instructions}}`） |
| 対象 | 1つのムーブメント |
| 判断基準 | 「この手順は特定のムーブメント/ピースに固有か？」→ YES |
### 実際の配置先
インストラクションは `src/shared/prompts/{lang}/perform_phase1_message.md` の `{{instructions}}` に展開される。
```
## 実行コンテキスト（作業ディレクトリ）
## 実行ルール（git commit禁止、cd禁止、edit権限）
## Piece Context（ピース名、Iteration、Movement Iteration、Report Directory）
## User Request（自動注入）
## Previous Response（自動注入、pass_previous_response: true 時）
## Additional User Inputs（自動注入）
## Instructions
{{instructions}} ← ★ インストラクションがここに展開される
```
インストラクションの前に実行コンテキスト、ピース情報、ユーザーリクエスト、前回レスポンス等が既に提供されている。これらを再記述する必要はない。
### ペルソナ・ポリシーとの分離
```
この内容は…
├── エージェントの identity・専門知識 → ペルソナ
├── 複数エージェントの共有ルール → ポリシー
└── ムーブメント固有の手順・出力形式 → インストラクション
```
---
## エンジンの自動注入
2つのメカニズムがある。いずれもインストラクション内に手動で記述する必要はない。
### セクション注入（`## Instructions` の前に別セクションとして挿入）
`perform_phase1_message.md` のテンプレート側で処理される。instruction_template の外に配置される。
| セクション | 内容 | デフォルト |
|-----------|------|-----------|
| `## User Request` | ユーザーの元リクエスト | **常に表示** |
| `## Previous Response` | 前ムーブメントの出力 | **初回以外は常に表示**（`pass_previous_response` デフォルト: `true`） |
| `## Additional User Inputs` | 蓄積されたユーザー入力 | **常に表示** |
抑制したい場合は instruction_template 内にプレースホルダー（`{task}`, `{previous_response}`, `{user_inputs}`）を含めるか、`pass_previous_response: false` を設定する。通常は不要。
### テンプレート変数展開（instruction_template 内のプレースホルダーを置換）
InstructionBuilder が instruction_template 内の `{変数名}` を展開する。インストラクション内で使用可能。
| 変数 | 内容 |
|------|------|
| `{iteration}` | ピース全体のイテレーション数 |
| `{max_iterations}` | 最大イテレーション数 |
| `{movement_iteration}` | ムーブメント単位のイテレーション数 |
| `{report_dir}` | レポートディレクトリ名 |
| `{report:filename}` | 指定レポートの内容展開（ファイルが存在する場合） |
| `{cycle_count}` | ループモニターで検出されたサイクル回数（`loop_monitors` 専用） |
また、タグベースのルールがある場合は `[STEP:N]` タグの出力ルールが末尾に自動付加される。
---
## 書き方ルール
### 構造パターン
インストラクションは以下の構造に従う。すべてのセクションが必須ではない。
```
1. 目的の宣言（1-2行）
2. 注意事項・条件（該当する場合）
3. やること（手順 or 観点）
4. 出力契約（埋め込みの場合）
5. 必須出力（見出しを含める）
```
### 目的の宣言
- 冒頭1-2行で何をすべきかを簡潔に記述
- 命令形（「〜してください。」）を使用
```markdown
# 良い例
タスクを分析し、実装方針を立ててください。
# 良い例
テスト実行、ビルド確認、最終承認を行ってください。
# 悪い例
このムーブメントではタスクの分析を行います。 ← 説明文になっている
```
### 注意事項・条件
- 差し戻し、イテレーション回数、前提条件がある場合に記述
- `**注意:**` または `**重要:**` の太字ラベルで強調
```markdown
# 良い例
**注意:** Previous Responseがある場合は差し戻しのため、
その内容を踏まえて計画を見直してください（replan）。
# 良い例（イテレーション追跡）
**これは {movement_iteration} 回目の AI Review です。**
2回目以降は、前回の修正が実際には行われていなかったということです。
```
### やること
- 番号付きリストまたは箇条書きで手順/観点を列挙
- レビュー系は「レビュー観点」としてまとめる
```markdown
# 実行系（番号付きリスト）
**やること:**
1. タスクの要件を理解する
2. 影響範囲を特定する
3. 実装アプローチを決める
# レビュー系（箇条書き）
**レビュー観点:**
- 構造・設計の妥当性
- コード品質
- テストカバレッジ
```
### 出力契約埋め込み
- インストラクション内に出力契約を埋め込む場合がある
- コードブロック（```markdown）で囲む
- ラベル（`**Scope出力契約:**` 等）を付ける
```markdown
# 良い例
**Scope出力契約（実装開始時に作成）:**
\`\`\`markdown
# 変更スコープ宣言
...
\`\`\`
```
### 必須出力
- `**必須出力（見出しを含める）**` の見出しで出力要件を定義
- 見出しは `##` で指定（エージェントの出力にそのまま使われる）
- `- {プレースホルダー}` で各項目の説明
```markdown
**必須出力（見出しを含める）**
## 作業結果
- {実施内容の要約}
## 変更内容
- {変更内容の要約}
## テスト結果
- {実行コマンドと結果}
```
---
## DO / DON'T
| DO | DON'T |
|----|-------|
| 目的を冒頭1-2行で命令形で書く | 長い説明文で始める |
| 手順を番号付きリストで列挙 | 曖昧な指示を出す |
| テンプレート変数を正しく使う | 自動注入される変数を手動で書く |
| 出力契約は```markdownで囲む | プレーンテキストで出力契約を書く |
| 必須出力の見出しを `##` で指定 | 出力形式を指定しない |
| そのムーブメントの手順に集中 | ペルソナ（専門知識）の内容を混ぜる |
| `{report:filename}` でレポートを参照 | ファイルパスをハードコードする |
---
## インストラクションに書いてはいけないもの
1. **ペルソナの内容**: エージェントの専門知識、検出手法、行動姿勢
2. **ポリシーの内容**: DRY、Fail Fast 等の共有コーディング原則
3. **自動注入される内容**: `{task}`, `{previous_response}` のプレースホルダーを明示的に書かない（エンジンが自動付加する）
4. **他のムーブメント名の直接参照**: 「implement ムーブメントに戻る」等（ルーティングはルール定義の責務）
5. **ピース固有のルーティング**: 「APPROVE なら次へ」等（ルール条件の責務）
### 例外: レポート参照
`{report:filename}` を使ったレポート内容の展開は許容する。これはピース固有の概念だが、インストラクションの中核機能。
```markdown
# 許容
**参照するレポート:**
- AIレビュー結果: {report:ai-review.md}
# 非許容
**参照するレポート:**
- .takt/reports/20250101-task/ai-review.md ← パスのハードコード
```
---
## カテゴリ別パターン
### 計画系（plan, plan-investigate, architect）
- 目的宣言 + やること（番号付き） + replan 注意事項
- 出力契約埋め込みなし（出力契約は output-contracts/ に分離）
- 5-20行
### 実装系（implement）
- 目的宣言 + テスト要件 + Scope/Decisions 出力契約埋め込み + 必須出力
- 出力契約を2つ埋め込む（Scope + Decisions）
- 30-50行
### レビュー系（review-*, ai-review）
- 目的宣言 + 「〜はレビューしない」の除外指示 + レビュー観点
- parallel sub-step の場合は短く（5-12行）
- standalone の場合はイテレーション追跡付き
### 修正系（fix, ai-fix, fix-supervisor）
- 修正指示 + 必須出力 + 証拠セクション
- ai-fix は特殊: 「修正済み認識」対策を含む（カスタマイズ不可）
- fix は「セッションの会話履歴を確認」の指示を含む
### 裁定系（arbitrate）
- 状況説明 + レポート参照 + 判断基準
- `{report:filename}` でレビュー結果を展開
### 検証系（supervise）
- 確認項目 + レポート確認指示 + Validation/Summary 出力契約埋め込み
- 30-55行
---
## 共通ルール
### 文体
- 丁寧語（「〜してください。」）を使用
- ペルソナ・ポリシーの常体とは異なる
- エージェントへの指示なので命令調
### ファイル命名
- `{role}.md` または `{role}-{modifier}.md`
- 例: `plan.md`, `plan-investigate.md`, `review-arch.md`
- ハイフン区切り
- 英語小文字のみ
### ファイルサイズ
| 種別 | 目安 | 上限 |
|------|------|------|
| レビュー sub-step | 5-12行 | 20行 |
| 計画・修正 | 10-20行 | 30行 |
| 実装・検証 | 30-50行 | 60行 |
| ai-fix（特殊） | 35-45行 | 50行 |
短いほどよい。冗長な説明は認知負荷を増やす。
---
## チェックリスト
- [ ] 冒頭1-2行で目的が命令形で書かれているか
- [ ] 自動注入される変数（{task}等）を手動で書いていないか
- [ ] ペルソナの内容（専門知識、行動姿勢）が混入していないか
- [ ] ポリシーの内容（共有コーディング原則）が混入していないか
- [ ] 出力契約埋め込みが```markdownで囲まれているか
- [ ] 必須出力の見出しが `##` で指定されているか
- [ ] ファイルパスがハードコードされていないか（`{report:filename}` を使う）
- [ ] そのムーブメントの手順に集中しているか（ルーティング指示なし）

Some files were not shown because too many files have changed in this diff Show More