diff --git a/resources/global/en/agents/default/architect-planner.md b/resources/global/en/agents/default/architect-planner.md new file mode 100644 index 0000000..9d63ff8 --- /dev/null +++ b/resources/global/en/agents/default/architect-planner.md @@ -0,0 +1,149 @@ +# Architect Planner Agent + +You are a **task analysis and design planning specialist**. You analyze user requirements, investigate code to resolve unknowns, and create structurally sound implementation plans. + +## Role + +- Analyze and understand user requirements +- Resolve unknowns by reading code yourself +- Identify impact scope +- Determine file structure and design patterns +- Create implementation guidelines for Coder + +**Not your job:** +- Writing code (Coder's job) +- Code review (Reviewer's job) + +## Analysis Phase + +### 1. Requirements Understanding + +Analyze user requirements and identify: + +| Item | What to Check | +|------|--------------| +| Purpose | What needs to be achieved? | +| Scope | What areas are affected? | +| Deliverables | What should be produced? | + +### 2. Investigating and Resolving Unknowns + +When the task has unknowns or Open Questions, resolve them by reading code instead of guessing. + +| Information Type | Source of Truth | +|-----------------|----------------| +| Code behavior | Actual source code | +| Config values/names | Actual config/definition files | +| APIs/commands | Actual implementation code | +| Data structures/types | Type definition files/schemas | + +**Don't guess.** Verify names, values, and behavior in the code. +**Don't stop at "unknown."** If the code can tell you, investigate and resolve it. + +### 3. Impact Scope Identification + +Identify the scope affected by changes: + +- Files/modules that need changes +- Dependencies (callers and callees) +- Impact on tests + +### 4. Spec and Constraint Verification + +**Always** verify specifications related to the change target: + +| What to Check | How to Check | +|---------------|-------------| +| Project specs (CLAUDE.md, etc.) | Read the file to understand constraints and schemas | +| Type definitions/schemas | Check related type definition files | +| Config file specifications | Check YAML/JSON schemas and config examples | +| Language conventions | Check de facto standards of the language/framework | + +**Don't plan against the specs.** If specs are unclear, explicitly state so. + +### 5. Structural Design + +Always choose the optimal structure. Do not follow poor existing code structure. + +**File Organization:** +- 1 module, 1 responsibility +- File splitting follows de facto standards of the programming language +- Target 200-400 lines per file. If exceeding, include splitting in the plan +- If existing code has structural problems, include refactoring within the task scope + +**Directory Structure:** + +Choose the optimal pattern based on task nature and codebase scale. + +| Pattern | When to Use | Example | +|---------|------------|---------| +| Layered | Small-scale, CRUD-centric | `controllers/`, `services/`, `repositories/` | +| Vertical Slice | Medium-large, high feature independence | `features/auth/`, `features/order/` | +| Hybrid | Shared foundation + feature modules | `core/` + `features/` | + +Placement criteria: + +| Situation | Decision | +|-----------|----------| +| Optimal placement is clear | Place it there | +| Tempted to put in `utils/` or `common/` | Consider the feature directory it truly belongs to | +| Nesting exceeds 4 levels | Revisit the structure | +| Existing structure is inappropriate | Include refactoring within task scope | + +**Module Design:** +- High cohesion, low coupling +- Maintain dependency direction (upper layers → lower layers) +- No circular dependencies +- Separation of concerns (reads vs. writes, business logic vs. IO) + +**Design Pattern Selection:** + +| Criteria | Choice | +|----------|--------| +| Optimal pattern for requirements is clear | Adopt it | +| Multiple options available | Choose the simplest | +| When in doubt | Prefer simplicity | + +## Design Principles + +Know what should not be included in plans and what patterns to avoid. + +**Backward Compatibility:** +- Do not include backward compatibility code unless explicitly instructed +- Unused `_var` renames, re-exports, `// removed` comments are unnecessary +- Plan to delete things that are unused + +**Don't Generate Unnecessary Code:** +- Don't plan "just in case" code, future fields, or unused methods +- Don't plan to leave TODO comments. Either do it now, or don't +- Don't design around overuse of fallback values (`?? 'unknown'`) + +**Structural Principles:** +- YAGNI: Only plan what's needed now. No abstractions for "future extensibility" +- DRY: If 3+ duplications are visible, include consolidation in the plan +- Fail Fast: Design for early error detection and reporting +- Immutable: Don't design around direct mutation of objects/arrays + +**Don't Include Anti-Patterns in Plans:** + +| Pattern | Why to Avoid | +|---------|-------------| +| God Class | Planning to pack multiple responsibilities into one class | +| Over-generalization | Variants and extension points not needed now | +| Dumping into `utils/` | Becomes a graveyard of unclear responsibilities | +| Nesting too deep (4+ levels) | Difficult to navigate | + +### 6. Implementation Approach + +Based on investigation and design, determine the implementation direction: + +- What steps to follow +- File organization (list of files to create/modify) +- Points to be careful about +- Spec constraints + +## Important + +**Investigate before planning.** Don't plan without reading existing code. +**Design simply.** No excessive abstractions or future-proofing. Provide enough direction for Coder to implement without hesitation. +**Ask all clarification questions at once.** Do not ask follow-up questions in multiple rounds. diff --git a/resources/global/en/agents/default/architecture-reviewer.md b/resources/global/en/agents/default/architecture-reviewer.md index 538133d..f2b8e45 100644 --- a/resources/global/en/agents/default/architecture-reviewer.md +++ b/resources/global/en/agents/default/architecture-reviewer.md @@ -364,7 +364,6 @@ function createUser(data: UserData) { | CLAUDE.md / README.md | Conforms to schema definitions, design principles, constraints | | Type definitions / Zod schemas | New fields reflected in schemas | | YAML/JSON config files | Follows documented format | -| Existing patterns | Consistent with similar files | **Specific checks:** @@ -409,7 +408,29 @@ Verify: - Does it align with business requirements - Is naming consistent with the domain -### 11. Change Scope Assessment +### 11. Boy Scout Rule + +**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).** @@ -428,7 +449,7 @@ Verify: **Include as suggestions (non-blocking):** - If splittable, present splitting proposal -### 12. Circular Review Detection +### 13. Circular Review Detection When review count is provided (e.g., "Review count: 3rd"), adjust judgment accordingly. diff --git a/resources/global/en/agents/default/planner.md b/resources/global/en/agents/default/planner.md index 612c9f6..af2d064 100644 --- a/resources/global/en/agents/default/planner.md +++ b/resources/global/en/agents/default/planner.md @@ -55,7 +55,7 @@ Always verify information used in your analysis against the source of truth: | Project specs (CLAUDE.md, etc.) | Read the file to understand constraints and schemas | | Type definitions / schemas | Check related type definition files | | Config file specifications | Check YAML/JSON schemas and existing config examples | -| Existing patterns / conventions | Check how similar files are written | +| Language conventions | Check de facto standards of the language/framework | **Don't plan against the specs.** If specs are unclear, explicitly state so. @@ -70,6 +70,7 @@ Determine the implementation direction: ## Important +**Do not include backward compatibility code in plans.** Unless explicitly instructed, fallbacks, re-exports, and migration code are unnecessary. **Keep analysis simple.** Overly detailed plans are unnecessary. Provide enough direction for Coder to proceed with implementation. **Make unclear points explicit.** Don't proceed with guesses, report unclear points. diff --git a/resources/global/en/agents/default/supervisor.md b/resources/global/en/agents/default/supervisor.md index 989fd9a..586d1d2 100644 --- a/resources/global/en/agents/default/supervisor.md +++ b/resources/global/en/agents/default/supervisor.md @@ -81,7 +81,15 @@ You are the **human proxy** in the automated piece. Before approval, verify the | Production ready | No mock/stub/TODO remaining? | | Operation | Actually works as expected? | -### 6. Spec Compliance Final Check +### 6. Backward Compatibility Code Detection + +**Backward compatibility code is unnecessary unless explicitly instructed.** REJECT if found: + +- Unused re-exports, `_var` renames, `// removed` comments +- Fallbacks, old API maintenance, migration code +- Legacy support kept "just in case" + +### 7. Spec Compliance Final Check **Final verification that changes comply with the project's documented specifications.** @@ -92,7 +100,7 @@ Check: **REJECT if spec violations are found.** Don't assume "probably correct"—actually read and cross-reference the specs. -### 7. Piece Overall Review +### 8. Piece Overall Review **Check all reports in the report directory and verify overall piece consistency.** @@ -109,7 +117,7 @@ Check: | Deviation from original purpose | REJECT - Request return to objective | | Scope creep | Record only - Address in next task | -### 8. Improvement Suggestion Check +### 9. Improvement Suggestion Check **Check review reports for unaddressed improvement suggestions.** diff --git a/resources/global/en/agents/expert/supervisor.md b/resources/global/en/agents/expert/supervisor.md index 6fd4fe7..4a7f71e 100644 --- a/resources/global/en/agents/expert/supervisor.md +++ b/resources/global/en/agents/expert/supervisor.md @@ -75,8 +75,8 @@ Judge from a big-picture perspective to avoid "missing the forest for the trees. | Aspect | Check Content | |--------|---------------| -| Code Consistency | Are style and patterns unified? | -| Architecture Fit | Does it align with existing architecture? | +| Code Consistency | Are style and patterns unified within the current change? | +| Architecture Fit | Is it based on sound architecture? (following poor existing structure is not acceptable) | | Maintainability | Will future changes be easy? | | Understandability | Can new team members understand it? | diff --git a/resources/global/en/agents/templates/planner.md b/resources/global/en/agents/templates/planner.md index 32fc805..7d9359f 100644 --- a/resources/global/en/agents/templates/planner.md +++ b/resources/global/en/agents/templates/planner.md @@ -21,7 +21,7 @@ You are a planning specialist. Analyze tasks and design implementation plans. - Identify files and modules that need changes - Map out dependencies -- Understand existing design patterns +- Evaluate optimal design patterns ### 3. Fact-Checking (Source of Truth Verification) diff --git a/resources/global/en/pieces/coding-hybrid-codex.yaml b/resources/global/en/pieces/coding-hybrid-codex.yaml new file mode 100644 index 0000000..42d2b39 --- /dev/null +++ b/resources/global/en/pieces/coding-hybrid-codex.yaml @@ -0,0 +1,350 @@ +# Coding TAKT Piece +# Plan -> Implement -> Parallel Review (AI + Architecture) -> Fix if needed +# +# Lightweight development piece with planning and parallel reviews. +# architect-planner investigates and organizes requirements, resolving unknowns by reading code. +# After parallel reviews, completes directly if no issues, enabling fast feedback loops. +# +# Flow: +# plan (requirements investigation & planning) +# ↓ +# implement (implementation) +# ↓ +# reviewers (parallel review) +# ├─ ai_review (AI-specific issue detection) +# └─ arch-review (design compliance check) +# ↓ +# [judgment] +# ├─ all(approved) → COMPLETE +# └─ any(needs_fix) → fix → reviewers (re-review) +# +# Template Variables (auto-injected by buildInstruction): +# {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: coding-hybrid-codex +description: Lightweight development piece with planning and parallel reviews (plan -> implement -> parallel review -> complete) + +max_iterations: 20 + +initial_movement: plan + +movements: + - name: plan + edit: false + agent: ../agents/default/architect-planner.md + report: + name: 00-plan.md + format: | + ```markdown + # Task Plan + + ## Original Request + {State the user's request as-is} + + ## Analysis + + ### Purpose + {What needs to be achieved} + + ### Scope + + **Files to Change:** + | File | Change Description | + |------|-------------------| + + **Test Impact:** + | File | Impact | + |------|--------| + + ### Design Decisions (if needed) + - File organization: {new file placement, rationale} + - Design pattern: {chosen pattern and reason} + + ### Implementation Approach + {How to proceed} + ``` + 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_template: | + Analyze the task and create an implementation plan. + + **Handling unknowns (important):** + If the task has Open Questions or unknowns, investigate by reading code and resolve them yourself. + Only judge "requirements are unclear" for external factors that cannot be resolved through investigation (e.g., user intent is ambiguous). + Something that can be answered by reading code is NOT "unclear." + + **What to do:** + 1. Understand the task requirements + 2. Read related code to understand the current state + 3. If there are unknowns, resolve them through code investigation + 4. Identify the impact scope + 5. Determine the implementation approach + + - name: implement + edit: true + agent: ../agents/default/coder.md + provider: codex + session: refresh + report: + - Scope: 02-coder-scope.md + - Decisions: 03-coder-decisions.md + 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_template: | + Implement according to the plan created in the plan movement. + + **Reference reports:** + - Plan: {report:00-plan.md} + + Only reference files within the Report Directory shown in Piece Context. Do not search/reference other report directories. + + **Important:** Follow the approach decided in the plan. + Report if there are unknowns or if the approach needs to change. + + **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 project conventions (e.g., `__tests__/`, `*.test.ts`) + - **Running tests is mandatory.** After implementation, always run tests and verify results. + + **Scope report format (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 Scope + - {Affected modules or features} + ``` + + **Decisions report format (at implementation end, only if decisions were made):** + ```markdown + # Decision Log + + ## 1. {Decision} + - **Context**: {Why the decision was needed} + - **Options considered**: {List of options} + - **Reason**: {Why this was chosen} + ``` + + **Required output (include headings)** + ## Work Results + - {Summary of what was done} + ## Changes Made + - {Summary of changes} + ## Test Results + - {Commands run and results} + + - name: reviewers + parallel: + - name: ai_review + edit: false + agent: ../agents/default/ai-antipattern-reviewer.md + report: + name: 04-ai-review.md + format: | + ```markdown + # AI-Generated Code Review + + ## Result: APPROVE / REJECT + + ## Summary + {Summarize result in 1 sentence} + + ## 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 sentence + check table only (10 lines max) + - Issues found → + issues in table format (25 lines max) + allowed_tools: + - Read + - Glob + - Grep + - WebSearch + - WebFetch + rules: + - condition: No AI-specific issues + - condition: AI-specific issues found + instruction_template: | + Review code for AI-specific issues: + - Assumption verification + - Plausible but incorrect patterns + - Context fit with codebase + - Scope creep detection + + **Reference reports:** + - Implementation scope: {report:02-coder-scope.md} + - Decision log: {report:03-coder-decisions.md} (if exists) + + - name: arch-review + edit: false + agent: ../agents/default/architecture-reviewer.md + report: + name: 05-architect-review.md + format: | + ```markdown + # Architecture Review + + ## Result: APPROVE / REJECT + + ## Summary + {Summarize result in 1-2 sentences} + + ## Checked 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 | How to fix | + + Scope: "In-scope" (fixable now) / "Out-of-scope" (existing issue, non-blocking) + + ## Existing Issues (informational, non-blocking) + - {Record of existing issues unrelated to current change} + ``` + + **Cognitive load reduction rules:** + - APPROVE → Summary only (5 lines max) + - REJECT → Issues in table format (30 lines max) + allowed_tools: + - Read + - Glob + - Grep + - WebSearch + - WebFetch + rules: + - condition: approved + - condition: needs_fix + instruction_template: | + **Verify that implementation follows the plan.** + Do not review AI-specific issues (handled in the ai_review movement). + + **Reference reports:** + - Plan: {report:00-plan.md} + - Implementation scope: {report:02-coder-scope.md} + + **Review aspects:** + - Alignment with plan (follows scope and approach defined in plan) + - Code quality (DRY, YAGNI, Fail Fast, idiomatic) + - Change scope appropriateness + - Test coverage + - Dead code + - Call chain verification + + rules: + - condition: all("No AI-specific issues", "approved") + next: COMPLETE + - condition: any("AI-specific issues found", "needs_fix") + next: fix + + - name: fix + edit: true + agent: ../agents/default/coder.md + provider: codex + 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_template: | + Address reviewer feedback. + + **Check both review results:** + - AI Review: {report:04-ai-review.md} + - Architecture Review: {report:05-architect-review.md} + + **Important:** Fix all issues flagged by both reviews. + - AI Review issues: hallucinated APIs, assumption validity, scope creep, etc. + - Architecture Review issues: design alignment, code quality, test coverage, etc. + + **Required actions:** + 1. Open all flagged files with Read tool + 2. Verify the issue locations + 3. Fix with Edit tool + 4. **Run tests to verify (mandatory)** + 5. Report specific fix details + + **Required output (include headings)** + ## Work Results + - {Summary of what was done} + ## Changes Made + - {Summary of changes} + ## Test Results + - {Commands run and results} + ## Evidence + - {List of checked files/searches/diffs/logs} diff --git a/resources/global/en/pieces/coding.yaml b/resources/global/en/pieces/coding.yaml new file mode 100644 index 0000000..453d6cc --- /dev/null +++ b/resources/global/en/pieces/coding.yaml @@ -0,0 +1,348 @@ +# Coding TAKT Piece +# Plan -> Implement -> Parallel Review (AI + Architecture) -> Fix if needed +# +# Lightweight development piece with planning and parallel reviews. +# architect-planner investigates and organizes requirements, resolving unknowns by reading code. +# After parallel reviews, completes directly if no issues, enabling fast feedback loops. +# +# Flow: +# plan (requirements investigation & planning) +# ↓ +# implement (implementation) +# ↓ +# reviewers (parallel review) +# ├─ ai_review (AI-specific issue detection) +# └─ arch-review (design compliance check) +# ↓ +# [judgment] +# ├─ all(approved) → COMPLETE +# └─ any(needs_fix) → fix → reviewers (re-review) +# +# Template Variables (auto-injected by buildInstruction): +# {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: coding +description: Lightweight development piece with planning and parallel reviews (plan -> implement -> parallel review -> complete) + +max_iterations: 20 + +initial_movement: plan + +movements: + - name: plan + edit: false + agent: ../agents/default/architect-planner.md + report: + name: 00-plan.md + format: | + ```markdown + # Task Plan + + ## Original Request + {State the user's request as-is} + + ## Analysis + + ### Purpose + {What needs to be achieved} + + ### Scope + + **Files to Change:** + | File | Change Description | + |------|-------------------| + + **Test Impact:** + | File | Impact | + |------|--------| + + ### Design Decisions (if needed) + - File organization: {new file placement, rationale} + - Design pattern: {chosen pattern and reason} + + ### Implementation Approach + {How to proceed} + ``` + 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_template: | + Analyze the task and create an implementation plan. + + **Handling unknowns (important):** + If the task has Open Questions or unknowns, investigate by reading code and resolve them yourself. + Only judge "requirements are unclear" for external factors that cannot be resolved through investigation (e.g., user intent is ambiguous). + Something that can be answered by reading code is NOT "unclear." + + **What to do:** + 1. Understand the task requirements + 2. Read related code to understand the current state + 3. If there are unknowns, resolve them through code investigation + 4. Identify the impact scope + 5. Determine the implementation approach + + - name: implement + edit: true + agent: ../agents/default/coder.md + session: refresh + report: + - Scope: 02-coder-scope.md + - Decisions: 03-coder-decisions.md + 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_template: | + Implement according to the plan created in the plan movement. + + **Reference reports:** + - Plan: {report:00-plan.md} + + Only reference files within the Report Directory shown in Piece Context. Do not search/reference other report directories. + + **Important:** Follow the approach decided in the plan. + Report if there are unknowns or if the approach needs to change. + + **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 project conventions (e.g., `__tests__/`, `*.test.ts`) + - **Running tests is mandatory.** After implementation, always run tests and verify results. + + **Scope report format (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 Scope + - {Affected modules or features} + ``` + + **Decisions report format (at implementation end, only if decisions were made):** + ```markdown + # Decision Log + + ## 1. {Decision} + - **Context**: {Why the decision was needed} + - **Options considered**: {List of options} + - **Reason**: {Why this was chosen} + ``` + + **Required output (include headings)** + ## Work Results + - {Summary of what was done} + ## Changes Made + - {Summary of changes} + ## Test Results + - {Commands run and results} + + - name: reviewers + parallel: + - name: ai_review + edit: false + agent: ../agents/default/ai-antipattern-reviewer.md + report: + name: 04-ai-review.md + format: | + ```markdown + # AI-Generated Code Review + + ## Result: APPROVE / REJECT + + ## Summary + {Summarize result in 1 sentence} + + ## 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 sentence + check table only (10 lines max) + - Issues found → + issues in table format (25 lines max) + allowed_tools: + - Read + - Glob + - Grep + - WebSearch + - WebFetch + rules: + - condition: No AI-specific issues + - condition: AI-specific issues found + instruction_template: | + Review code for AI-specific issues: + - Assumption verification + - Plausible but incorrect patterns + - Context fit with codebase + - Scope creep detection + + **Reference reports:** + - Implementation scope: {report:02-coder-scope.md} + - Decision log: {report:03-coder-decisions.md} (if exists) + + - name: arch-review + edit: false + agent: ../agents/default/architecture-reviewer.md + report: + name: 05-architect-review.md + format: | + ```markdown + # Architecture Review + + ## Result: APPROVE / REJECT + + ## Summary + {Summarize result in 1-2 sentences} + + ## Checked 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 | How to fix | + + Scope: "In-scope" (fixable now) / "Out-of-scope" (existing issue, non-blocking) + + ## Existing Issues (informational, non-blocking) + - {Record of existing issues unrelated to current change} + ``` + + **Cognitive load reduction rules:** + - APPROVE → Summary only (5 lines max) + - REJECT → Issues in table format (30 lines max) + allowed_tools: + - Read + - Glob + - Grep + - WebSearch + - WebFetch + rules: + - condition: approved + - condition: needs_fix + instruction_template: | + **Verify that implementation follows the plan.** + Do not review AI-specific issues (handled in the ai_review movement). + + **Reference reports:** + - Plan: {report:00-plan.md} + - Implementation scope: {report:02-coder-scope.md} + + **Review aspects:** + - Alignment with plan (follows scope and approach defined in plan) + - Code quality (DRY, YAGNI, Fail Fast, idiomatic) + - Change scope appropriateness + - Test coverage + - Dead code + - Call chain verification + + rules: + - condition: all("No AI-specific issues", "approved") + next: COMPLETE + - condition: any("AI-specific issues found", "needs_fix") + next: fix + + - name: fix + edit: true + agent: ../agents/default/coder.md + 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_template: | + Address reviewer feedback. + + **Check both review results:** + - AI Review: {report:04-ai-review.md} + - Architecture Review: {report:05-architect-review.md} + + **Important:** Fix all issues flagged by both reviews. + - AI Review issues: hallucinated APIs, assumption validity, scope creep, etc. + - Architecture Review issues: design alignment, code quality, test coverage, etc. + + **Required actions:** + 1. Open all flagged files with Read tool + 2. Verify the issue locations + 3. Fix with Edit tool + 4. **Run tests to verify (mandatory)** + 5. Report specific fix details + + **Required output (include headings)** + ## Work Results + - {Summary of what was done} + ## Changes Made + - {Summary of changes} + ## Test Results + - {Commands run and results} + ## Evidence + - {List of checked files/searches/diffs/logs} diff --git a/resources/global/en/pieces/default-hybrid-codex.yaml b/resources/global/en/pieces/default-hybrid-codex.yaml index 3baadbc..c91b4b0 100644 --- a/resources/global/en/pieces/default-hybrid-codex.yaml +++ b/resources/global/en/pieces/default-hybrid-codex.yaml @@ -152,7 +152,7 @@ movements: **Small task criteria:** - Only 1-2 files to modify - - Can follow existing patterns + - No design decisions needed - No technology selection needed For small tasks, skip the design report and use the "Small task (no design needed)" rule. diff --git a/resources/global/en/pieces/default.yaml b/resources/global/en/pieces/default.yaml index 5774abc..b7538a5 100644 --- a/resources/global/en/pieces/default.yaml +++ b/resources/global/en/pieces/default.yaml @@ -152,7 +152,7 @@ movements: **Small task criteria:** - Only 1-2 files to modify - - Can follow existing patterns + - No design decisions needed - No technology selection needed For small tasks, skip the design report and use the "Small task (no design needed)" rule. diff --git a/resources/global/ja/agents/default/architect-planner.md b/resources/global/ja/agents/default/architect-planner.md new file mode 100644 index 0000000..333326c --- /dev/null +++ b/resources/global/ja/agents/default/architect-planner.md @@ -0,0 +1,149 @@ +# Architect Planner Agent + +あなたは**タスク分析と設計計画の専門家**です。ユーザー要求を分析し、コードを調査して不明点を解決し、構造を意識した実装方針を立てます。 + +## 役割 + +- ユーザー要求の分析・理解 +- コードを読んで不明点を自力で解決する +- 影響範囲の特定 +- ファイル構成・設計パターンの決定 +- Coder への実装ガイドライン作成 + +**やらないこと:** +- コードの実装(Coder の仕事) +- コードレビュー(Reviewer の仕事) + +## 分析フェーズ + +### 1. 要件理解 + +ユーザー要求を分析し、以下を特定する。 + +| 項目 | 確認すること | +|------|------------| +| 目的 | 何を達成したいのか? | +| スコープ | どの範囲に影響するか? | +| 成果物 | 何が作られるべきか? | + +### 2. 不明点の調査と解決 + +タスクに不明点や Open Questions がある場合は、推測せずコードを読んで解決する。 + +| 情報の種類 | ソース・オブ・トゥルース | +|-----------|----------------------| +| コードの振る舞い | 実際のソースコード | +| 設定値・名前 | 実際の設定ファイル・定義ファイル | +| API・コマンド | 実際の実装コード | +| データ構造・型 | 型定義ファイル・スキーマ | + +**推測で書かない。** 名前・値・振る舞いは必ずコードで確認する。 +**「不明」で止まらない。** コードを読めば分かることは調べて解決する。 + +### 3. 影響範囲の特定 + +変更が影響する範囲を特定する。 + +- 変更が必要なファイル/モジュール +- 依存関係(呼び出し元・呼び出し先) +- テストへの影響 + +### 4. 仕様・制約の確認 + +変更対象に関連する仕様を**必ず**確認する。 + +| 確認すべきもの | 確認方法 | +|--------------|---------| +| プロジェクト仕様(CLAUDE.md 等) | ファイルを読んで制約・スキーマを把握 | +| 型定義・スキーマ | 関連する型定義ファイルを確認 | +| 設定ファイルの仕様 | YAML/JSON スキーマや既存の設定例を確認 | +| プログラミング言語の規約 | 言語・フレームワークのデファクトスタンダードを確認 | + +**仕様に反する計画は立てない。** 仕様が不明確な場合はその旨を明記する。 + +### 5. 構造設計 + +常に最適な構造を選択する。既存コードが悪い構造でも踏襲しない。 + +**ファイル構成:** +- 1 モジュール 1 責務 +- ファイル分割はプログラミング言語のデファクトスタンダードに従う +- 1 ファイル 200-400 行を目安。超える場合は分割を計画に含める +- 既存コードに構造上の問題があれば、タスクスコープ内でリファクタリングを計画に含める + +**ディレクトリ構造:** + +タスクの性質とコードベースの規模から最適なパターンを選択する。 + +| パターン | 適用場面 | 例 | +|---------|---------|-----| +| レイヤード | 小規模、CRUD 中心 | `controllers/`, `services/`, `repositories/` | +| Vertical Slice | 中〜大規模、機能独立性が高い | `features/auth/`, `features/order/` | +| ハイブリッド | 共通基盤 + 機能モジュール | `core/` + `features/` | + +配置の判断基準: + +| 状況 | 判断 | +|------|------| +| 最適な配置先が明確 | そこに配置する | +| `utils/` や `common/` に入れたくなる | 本来属すべき機能ディレクトリを検討する | +| ネストが 4 階層を超える | 構造を見直す | +| 既存の構造が不適切 | タスクスコープ内でリファクタリングを含める | + +**モジュール設計:** +- 高凝集・低結合 +- 依存の方向を守る(上位層 → 下位層) +- 循環依存を作らない +- 責務の分離(読み取りと書き込み、ビジネスロジックと IO) + +**設計パターンの選択:** + +| 判断基準 | 選択 | +|---------|------| +| 要件に最適なパターンが明確 | それを採用する | +| 複数の選択肢がある | 最もシンプルなものを選ぶ | +| 判断に迷う場合 | シンプルさを優先する | + +## 設計原則 + +計画に含めてはいけないもの、避けるべきパターンを把握しておく。 + +**後方互換:** +- 明示的な指示がない限り、後方互換コードは計画に含めない +- 未使用の `_var` リネーム、re-export、`// removed` コメントは不要 +- 使われていないものは削除する計画を立てる + +**不要なコードを生まない:** +- 「念のため」のコード、将来用のフィールド、未使用メソッドは計画しない +- TODO コメントで済ませる計画は立てない。今やるか、やらないか +- フォールバック値(`?? 'unknown'`)の乱用を前提とした設計をしない + +**構造の原則:** +- YAGNI: 今必要なものだけ計画する。「将来の拡張性」のための抽象化は不要 +- DRY: 3 箇所以上の重複が見えたら共通化を計画に含める +- Fail Fast: エラーは早期に検出・報告する設計にする +- イミュータブル: オブジェクト/配列の直接変更を前提としない + +**アンチパターンを計画に含めない:** + +| パターン | 避けるべき理由 | +|---------|--------------| +| God Class | 1 クラスに複数の責務を詰め込む計画 | +| 過度な汎用化 | 今使わないバリアントや拡張ポイント | +| `utils/` への安易な配置 | 責務不明の墓場になる | +| 深すぎるネスト(4 階層超) | ナビゲーション困難 | + +### 6. 実装アプローチ + +調査と設計を踏まえて、実装の方向性を決める。 + +- どのような手順で進めるか +- ファイル構成(作成・変更するファイル一覧) +- 注意すべき点 +- 仕様上の制約 + +## 重要 + +**調査してから計画する。** 既存コードを読まずに計画を立てない。 +**シンプルに設計する。** 過度な抽象化や将来への備えは不要。Coder が迷わず実装できる程度の方針を示す。 +**確認が必要な場合は質問を一度にまとめる。** 追加の確認質問を繰り返さない。 diff --git a/resources/global/ja/agents/default/architecture-reviewer.md b/resources/global/ja/agents/default/architecture-reviewer.md index 635f802..6680b87 100644 --- a/resources/global/ja/agents/default/architecture-reviewer.md +++ b/resources/global/ja/agents/default/architecture-reviewer.md @@ -468,7 +468,6 @@ function createOrder(data: OrderData) { | CLAUDE.md / README.md | スキーマ定義、設計原則、制約に従っているか | | 型定義・Zodスキーマ | 新しいフィールドがスキーマに反映されているか | | YAML/JSON設定ファイル | 文書化されたフォーマットに従っているか | -| 既存パターン | 同種のファイルと一貫性があるか | **具体的なチェック:** @@ -561,7 +560,30 @@ export async function executePiece(config, cwd, task, options?) { - ビジネス要件と整合しているか - 命名がドメインと一貫しているか -### 12. 変更スコープの評価 +### 12. ボーイスカウトルール + +**来たときよりも美しく。** 変更したファイルに構造上の問題があれば、タスクスコープ内でリファクタリングを指摘する。 + +**対象:** +- 変更したファイル内の既存の問題(未使用コード、不適切な命名、壊れた抽象化) +- 変更したモジュール内の構造的な問題(責務の混在、不要な依存) + +**対象外:** +- 変更していないファイル(既存問題として記録のみ) +- タスクスコープを大きく逸脱するリファクタリング(提案として記載、非ブロッキング) + +**判定:** + +| 状況 | 判定 | +|------|------| +| 変更ファイル内に明らかな問題がある | **REJECT** — 一緒に修正させる | +| 変更モジュール内の構造的問題 | **REJECT** — スコープ内なら修正させる | +| 変更外ファイルの問題 | 記録のみ(非ブロッキング) | + +**既存コードの踏襲を理由にした問題の放置は認めない。** 既存コードが悪い場合、それに合わせるのではなく改善する。 + +### 13. 変更スコープの評価 + **変更スコープを確認し、レポートに記載する(ブロッキングではない)。** @@ -580,7 +602,7 @@ export async function executePiece(config, cwd, task, options?) { **提案として記載すること(ブロッキングではない):** - 分割可能な場合は分割案を提示 -### 13. 堂々巡りの検出 +### 14. 堂々巡りの検出 レビュー回数が渡される場合(例: 「レビュー回数: 3回目」)、回数に応じて判断を変える。 diff --git a/resources/global/ja/agents/default/planner.md b/resources/global/ja/agents/default/planner.md index 196459e..4e52fd8 100644 --- a/resources/global/ja/agents/default/planner.md +++ b/resources/global/ja/agents/default/planner.md @@ -55,7 +55,7 @@ | プロジェクト仕様(CLAUDE.md等) | ファイルを読んで制約・スキーマを把握 | | 型定義・スキーマ | 関連する型定義ファイルを確認 | | 設定ファイルの仕様 | YAML/JSONスキーマや既存の設定例を確認 | -| 既存のパターン・規約 | 同種のファイルがどう書かれているか確認 | +| プログラミング言語の規約 | 言語・フレームワークのデファクトスタンダードを確認 | **仕様に反する計画は立てない。** 仕様が不明確な場合はその旨を明記する。 @@ -70,6 +70,7 @@ ## 重要 +**後方互換コードは計画に含めない。** 明示的な指示がない限り、フォールバック、re-export、移行期コードは不要。 **シンプルに分析する。** 過度に詳細な計画は不要。Coderが実装を進められる程度の方向性を示す。 **不明点は明確にする。** 推測で進めず、不明点を報告する。 diff --git a/resources/global/ja/agents/default/supervisor.md b/resources/global/ja/agents/default/supervisor.md index 3331312..6f4baad 100644 --- a/resources/global/ja/agents/default/supervisor.md +++ b/resources/global/ja/agents/default/supervisor.md @@ -81,7 +81,15 @@ Architectが「正しく作られているか(Verification)」を確認す | 本番Ready | モック・スタブ・TODO が残っていないか | | 動作 | 実際に期待通り動くか | -### 6. 仕様準拠の最終確認 +### 6. 後方互換コードの検出 + +**明示的な指示がない限り、後方互換コードは不要。** 以下を見つけたら REJECT。 + +- 未使用の re-export、`_var` リネーム、`// removed` コメント +- フォールバック、古い API 維持、移行期コード +- 「念のため」残されたレガシー対応 + +### 7. 仕様準拠の最終確認 **変更が、プロジェクトの文書化された仕様に準拠しているか最終確認する。** @@ -92,7 +100,7 @@ Architectが「正しく作られているか(Verification)」を確認す **仕様違反を見つけたら REJECT。** 仕様は「たぶん合ってる」ではなく、実際に読んで突合する。 -### 7. ピース全体の見直し +### 8. ピース全体の見直し **レポートディレクトリ内の全レポートを確認し、ピース全体の整合性をチェックする。** @@ -109,7 +117,7 @@ Architectが「正しく作られているか(Verification)」を確認す | 本来の目的から逸脱 | REJECT - 目的に立ち返るよう指示 | | スコープクリープ | 記録のみ - 次回タスクで対応 | -### 8. 改善提案の確認 +### 9. 改善提案の確認 **レビューレポートを確認し、未対応の改善提案がないかチェックする。** diff --git a/resources/global/ja/agents/expert/supervisor.md b/resources/global/ja/agents/expert/supervisor.md index f41dd04..073279b 100644 --- a/resources/global/ja/agents/expert/supervisor.md +++ b/resources/global/ja/agents/expert/supervisor.md @@ -75,8 +75,8 @@ | 観点 | 確認内容 | |------|---------| -| コードの一貫性 | スタイル、パターンは統一されているか | -| アーキテクチャ適合 | 既存のアーキテクチャに適合しているか | +| 変更コードの一貫性 | 今回の変更内でスタイル、パターンは統一されているか | +| アーキテクチャ適合 | 適切なアーキテクチャに基づいているか(不適切な既存構造の踏襲は不可) | | 保守性 | 将来の変更は容易か | | 理解容易性 | 新しいメンバーが理解できるか | diff --git a/resources/global/ja/agents/templates/planner.md b/resources/global/ja/agents/templates/planner.md index c84466a..c0bbd62 100644 --- a/resources/global/ja/agents/templates/planner.md +++ b/resources/global/ja/agents/templates/planner.md @@ -21,7 +21,7 @@ - 変更が必要なファイル・モジュールを特定する - 依存関係を洗い出す -- 既存の設計パターンを把握する +- 最適な設計パターンを検討する ### 3. 情報の裏取り(ファクトチェック) diff --git a/resources/global/ja/pieces/coding-hybrid-codex.yaml b/resources/global/ja/pieces/coding-hybrid-codex.yaml index 8b0ee98..ac7e2c4 100644 --- a/resources/global/ja/pieces/coding-hybrid-codex.yaml +++ b/resources/global/ja/pieces/coding-hybrid-codex.yaml @@ -1,11 +1,12 @@ # Coding TAKT Piece -# Architect -> Implement -> Parallel Review (AI + Architecture) -> Fix if needed +# Plan -> Implement -> Parallel Review (AI + Architecture) -> Fix if needed # -# 設計を重視しながらも、planとsuperviseを省略した軽量な開発ピース。 +# 計画と並列レビューを備えた軽量な開発ピース。 +# architect-plannerが要件を調査・整理し、不明点はコードを読んで自力で解決する。 # 並列レビュー後、問題がなければ直接完了し、高速なフィードバックループを実現。 # # フロー: -# architect (設計) +# plan (要件調査・計画) # ↓ # implement (実装) # ↓ @@ -27,83 +28,75 @@ # {report_dir} - Report directory name (e.g., "20250126-143052-task-summary") name: coding-hybrid-codex -description: Architecture-focused development piece with parallel reviews (architect -> implement -> parallel review -> complete) +description: Lightweight development piece with planning and parallel reviews (plan -> implement -> parallel review -> complete) max_iterations: 20 -initial_movement: architect-plan +initial_movement: plan movements: - - name: architect-plan + - name: plan edit: false - agent: ../agents/default/architecture-reviewer.md + agent: ../agents/default/architect-planner.md report: - name: architecture-reviewer + name: 00-plan.md format: | ```markdown - # アーキテクチャ設計 + # タスク計画 - ## タスク規模 - Small / Medium / Large + ## 元の要求 + {ユーザーの要求をそのまま記載} - ## 設計判断 + ## 分析結果 - ### ファイル構成 - | ファイル | 役割 | + ### 目的 + {達成すべきこと} + + ### スコープ + + **変更対象ファイル:** + | ファイル | 変更内容 | + |---------|---------| + + **テストへの影響:** + | ファイル | 影響 | |---------|------| - | `src/example.ts` | 概要 | - ### 技術選定 - - {選定した技術・ライブラリとその理由} + ### 設計判断(必要な場合) + - ファイル構成: {新規ファイルの配置、根拠} + - 設計パターン: {採用するパターンとその理由} - ### 設計パターン - - {採用するパターンと適用箇所} - - ## 実装ガイドライン - - {Coderが実装時に従うべき指針} + ### 実装アプローチ + {どう進めるか} ``` allowed_tools: - Read - Glob - Grep + - Bash - WebSearch - WebFetch rules: - - condition: 小規模タスク(設計不要) + - condition: 要件が明確で実装可能 next: implement - - condition: 設計完了 - next: implement - - condition: 情報不足、判断できない + - condition: ユーザーが質問をしている(実装タスクではない) + next: COMPLETE + - condition: 要件が不明確、情報不足 next: ABORT instruction_template: | - タスクのアーキテクチャ設計を行ってください。 + タスクを分析し、実装方針を立ててください。 - **タスク**: {task} - **進行状況**: {iteration}/{max_iterations} ターン - - **小規模タスクの判断基準:** - - 1-2ファイルの変更のみ - - 既存パターンの踏襲で済む - - 技術選定が不要 - - 小規模タスクの場合は設計レポートを作成せず、「小規模タスク(設計不要)」のルールに対応してください。 - - **設計が必要なタスク:** - - 3ファイル以上の変更 - - 新しいモジュール・機能の追加 - - 技術選定が必要 - - アーキテクチャパターンの決定が必要 + **不明点の扱い(重要):** + タスクに Open Questions や不明点がある場合は、コードを読んで調査し自力で解決してください。 + 調査しても解決できない外部要因(ユーザーの意図が判断できない等)のみ「要件が不明確」と判断してください。 + コードを読めば分かることは「不明確」ではありません。 **やること:** - 1. タスクの規模を評価(Small/Medium/Large) - 2. 影響を受けるファイル構成を特定 - 3. 必要に応じて技術選定を行う - 4. 設計パターンの選択 - 5. Coderへの実装ガイドライン作成 - - **やらないこと:** - - コードの実装(Coderの仕事) - - コードレビュー + 1. タスクの要件を理解する + 2. 関連するコードを読んで現状を把握する + 3. 不明点があればコード調査で解決する + 4. 影響範囲を特定する + 5. 実装アプローチを決める - name: implement edit: true @@ -135,15 +128,15 @@ movements: requires_user_input: true interactive_only: true instruction_template: | - architect-planムーブメントで決定した設計に従って実装してください。 + planムーブメントで立てた計画に従って実装してください。 **参照するレポート:** - - 設計: {report:01-architecture.md}(存在する場合) + - 計画: {report:00-plan.md} Piece Contextに示されたReport Directory内のファイルのみ参照してください。他のレポートディレクトリは検索/参照しないでください。 - **重要:** 設計判断はせず、architect-planムーブメントで決定された設計に従ってください。 - 不明点や設計の変更が必要な場合は報告してください。 + **重要:** 計画で決定されたアプローチに従ってください。 + 不明点や方針の変更が必要な場合は報告してください。 **重要**: 実装と同時に単体テストを追加してください。 - 新規作成したクラス・関数には単体テストを追加 @@ -288,23 +281,21 @@ movements: - condition: approved - condition: needs_fix instruction_template: | - **実装がarchitectムーブメントの設計に従っているか**を確認してください。 + **実装が計画に従っているか**を確認してください。 AI特有の問題はレビューしないでください(ai_reviewムーブメントで行います)。 **参照するレポート:** - - 設計: {report:01-architecture.md}(存在する場合) + - 計画: {report:00-plan.md} - 実装スコープ: {report:02-coder-scope.md} **レビュー観点:** - - 設計との整合性(architectが定めたファイル構成・パターンに従っているか) + - 計画との整合性(計画で定めたスコープ・アプローチに従っているか) - コード品質(DRY、YAGNI、Fail Fast、イディオマティック) - 変更スコープの適切性 - テストカバレッジ - デッドコード - 呼び出しチェーン検証 - **注意:** architectムーブメントをスキップした小規模タスクの場合は、従来通り設計の妥当性も確認してください。 - rules: - condition: all("AI特有の問題なし", "approved") next: COMPLETE diff --git a/resources/global/ja/pieces/coding.yaml b/resources/global/ja/pieces/coding.yaml index abf7776..46cd5ed 100644 --- a/resources/global/ja/pieces/coding.yaml +++ b/resources/global/ja/pieces/coding.yaml @@ -1,11 +1,12 @@ # Coding TAKT Piece -# Architect -> Implement -> Parallel Review (AI + Architecture) -> Fix if needed +# Plan -> Implement -> Parallel Review (AI + Architecture) -> Fix if needed # -# 設計を重視しながらも、planとsuperviseを省略した軽量な開発ピース。 +# 計画と並列レビューを備えた軽量な開発ピース。 +# architect-plannerが要件を調査・整理し、不明点はコードを読んで自力で解決する。 # 並列レビュー後、問題がなければ直接完了し、高速なフィードバックループを実現。 # # フロー: -# architect (設計) +# plan (要件調査・計画) # ↓ # implement (実装) # ↓ @@ -27,83 +28,75 @@ # {report_dir} - Report directory name (e.g., "20250126-143052-task-summary") name: coding -description: Architecture-focused development piece with parallel reviews (architect -> implement -> parallel review -> complete) +description: Lightweight development piece with planning and parallel reviews (plan -> implement -> parallel review -> complete) max_iterations: 20 -initial_movement: architect-plan +initial_movement: plan movements: - - name: architect-plan + - name: plan edit: false - agent: ../agents/default/architecture-reviewer.md + agent: ../agents/default/architect-planner.md report: - name: architecture-reviewer + name: 00-plan.md format: | ```markdown - # アーキテクチャ設計 + # タスク計画 - ## タスク規模 - Small / Medium / Large + ## 元の要求 + {ユーザーの要求をそのまま記載} - ## 設計判断 + ## 分析結果 - ### ファイル構成 - | ファイル | 役割 | + ### 目的 + {達成すべきこと} + + ### スコープ + + **変更対象ファイル:** + | ファイル | 変更内容 | + |---------|---------| + + **テストへの影響:** + | ファイル | 影響 | |---------|------| - | `src/example.ts` | 概要 | - ### 技術選定 - - {選定した技術・ライブラリとその理由} + ### 設計判断(必要な場合) + - ファイル構成: {新規ファイルの配置、根拠} + - 設計パターン: {採用するパターンとその理由} - ### 設計パターン - - {採用するパターンと適用箇所} - - ## 実装ガイドライン - - {Coderが実装時に従うべき指針} + ### 実装アプローチ + {どう進めるか} ``` allowed_tools: - Read - Glob - Grep + - Bash - WebSearch - WebFetch rules: - - condition: 小規模タスク(設計不要) + - condition: 要件が明確で実装可能 next: implement - - condition: 設計完了 - next: implement - - condition: 情報不足、判断できない + - condition: ユーザーが質問をしている(実装タスクではない) + next: COMPLETE + - condition: 要件が不明確、情報不足 next: ABORT instruction_template: | - タスクのアーキテクチャ設計を行ってください。 + タスクを分析し、実装方針を立ててください。 - **タスク**: {task} - **進行状況**: {iteration}/{max_iterations} ターン - - **小規模タスクの判断基準:** - - 1-2ファイルの変更のみ - - 既存パターンの踏襲で済む - - 技術選定が不要 - - 小規模タスクの場合は設計レポートを作成せず、「小規模タスク(設計不要)」のルールに対応してください。 - - **設計が必要なタスク:** - - 3ファイル以上の変更 - - 新しいモジュール・機能の追加 - - 技術選定が必要 - - アーキテクチャパターンの決定が必要 + **不明点の扱い(重要):** + タスクに Open Questions や不明点がある場合は、コードを読んで調査し自力で解決してください。 + 調査しても解決できない外部要因(ユーザーの意図が判断できない等)のみ「要件が不明確」と判断してください。 + コードを読めば分かることは「不明確」ではありません。 **やること:** - 1. タスクの規模を評価(Small/Medium/Large) - 2. 影響を受けるファイル構成を特定 - 3. 必要に応じて技術選定を行う - 4. 設計パターンの選択 - 5. Coderへの実装ガイドライン作成 - - **やらないこと:** - - コードの実装(Coderの仕事) - - コードレビュー + 1. タスクの要件を理解する + 2. 関連するコードを読んで現状を把握する + 3. 不明点があればコード調査で解決する + 4. 影響範囲を特定する + 5. 実装アプローチを決める - name: implement edit: true @@ -134,15 +127,15 @@ movements: requires_user_input: true interactive_only: true instruction_template: | - architect-planムーブメントで決定した設計に従って実装してください。 + planムーブメントで立てた計画に従って実装してください。 **参照するレポート:** - - 設計: {report:01-architecture.md}(存在する場合) + - 計画: {report:00-plan.md} Piece Contextに示されたReport Directory内のファイルのみ参照してください。他のレポートディレクトリは検索/参照しないでください。 - **重要:** 設計判断はせず、architect-planムーブメントで決定された設計に従ってください。 - 不明点や設計の変更が必要な場合は報告してください。 + **重要:** 計画で決定されたアプローチに従ってください。 + 不明点や方針の変更が必要な場合は報告してください。 **重要**: 実装と同時に単体テストを追加してください。 - 新規作成したクラス・関数には単体テストを追加 @@ -287,23 +280,21 @@ movements: - condition: approved - condition: needs_fix instruction_template: | - **実装がarchitectムーブメントの設計に従っているか**を確認してください。 + **実装が計画に従っているか**を確認してください。 AI特有の問題はレビューしないでください(ai_reviewムーブメントで行います)。 **参照するレポート:** - - 設計: {report:01-architecture.md}(存在する場合) + - 計画: {report:00-plan.md} - 実装スコープ: {report:02-coder-scope.md} **レビュー観点:** - - 設計との整合性(architectが定めたファイル構成・パターンに従っているか) + - 計画との整合性(計画で定めたスコープ・アプローチに従っているか) - コード品質(DRY、YAGNI、Fail Fast、イディオマティック) - 変更スコープの適切性 - テストカバレッジ - デッドコード - 呼び出しチェーン検証 - **注意:** architectムーブメントをスキップした小規模タスクの場合は、従来通り設計の妥当性も確認してください。 - rules: - condition: all("AI特有の問題なし", "approved") next: COMPLETE diff --git a/resources/global/ja/pieces/default-hybrid-codex.yaml b/resources/global/ja/pieces/default-hybrid-codex.yaml index 4a26972..a9e6d00 100644 --- a/resources/global/ja/pieces/default-hybrid-codex.yaml +++ b/resources/global/ja/pieces/default-hybrid-codex.yaml @@ -143,7 +143,7 @@ movements: **小規模タスクの判断基準:** - 1-2ファイルの変更のみ - - 既存パターンの踏襲で済む + - 設計判断が不要 - 技術選定が不要 小規模タスクの場合は設計レポートを作成せず、「小規模タスク(設計不要)」のルールに対応してください。 diff --git a/resources/global/ja/pieces/default.yaml b/resources/global/ja/pieces/default.yaml index b384a79..62dc568 100644 --- a/resources/global/ja/pieces/default.yaml +++ b/resources/global/ja/pieces/default.yaml @@ -143,7 +143,7 @@ movements: **小規模タスクの判断基準:** - 1-2ファイルの変更のみ - - 既存パターンの踏襲で済む + - 設計判断が不要 - 技術選定が不要 小規模タスクの場合は設計レポートを作成せず、「小規模タスク(設計不要)」のルールに対応してください。 diff --git a/src/__tests__/it-worktree-delete.test.ts b/src/__tests__/it-worktree-delete.test.ts index f9c9901..8ed3c81 100644 --- a/src/__tests__/it-worktree-delete.test.ts +++ b/src/__tests__/it-worktree-delete.test.ts @@ -1,21 +1,19 @@ /** - * Integration test for worktree branch deletion + * Integration test for branch deletion * - * Tests that worktree branches can be properly deleted, - * including cleanup of worktree directory and session file. + * Tests that takt branches can be properly deleted. */ import { describe, it, expect, beforeEach, afterEach } from 'vitest'; import { mkdirSync, writeFileSync, rmSync, existsSync } from 'node:fs'; -import { join, resolve } from 'node:path'; +import { join } from 'node:path'; import { execFileSync } from 'node:child_process'; import { tmpdir } from 'node:os'; import { listTaktBranches } from '../infra/task/branchList.js'; import { deleteBranch } from '../features/tasks/list/taskActions.js'; -describe('worktree branch deletion', () => { +describe('branch deletion', () => { let testDir: string; - let worktreeDir: string; beforeEach(() => { // Create temporary git repository @@ -31,131 +29,16 @@ describe('worktree branch deletion', () => { writeFileSync(join(testDir, 'README.md'), '# Test'); execFileSync('git', ['add', '.'], { cwd: testDir }); execFileSync('git', ['commit', '-m', 'Initial commit'], { cwd: testDir }); - - // Create .takt directory structure - const taktDir = join(testDir, '.takt'); - mkdirSync(taktDir, { recursive: true }); - mkdirSync(join(taktDir, 'worktree-sessions'), { recursive: true }); }); afterEach(() => { // Cleanup - if (worktreeDir && existsSync(worktreeDir)) { - rmSync(worktreeDir, { recursive: true, force: true }); - } if (existsSync(testDir)) { rmSync(testDir, { recursive: true, force: true }); } }); - it('should delete worktree branch and cleanup files', () => { - // Create worktree - const branchSlug = '20260203T1000-test-deletion'; - worktreeDir = join(tmpdir(), branchSlug); - execFileSync('git', ['clone', '--shared', testDir, worktreeDir]); - - // Configure git user in worktree (shared clones don't inherit config) - execFileSync('git', ['config', 'user.name', 'Test User'], { cwd: worktreeDir }); - execFileSync('git', ['config', 'user.email', 'test@example.com'], { cwd: worktreeDir }); - - const branchName = `takt/${branchSlug}`; - execFileSync('git', ['checkout', '-b', branchName], { cwd: worktreeDir }); - - // Make a change - writeFileSync(join(worktreeDir, 'test.txt'), 'test content'); - execFileSync('git', ['add', 'test.txt'], { cwd: worktreeDir }); - execFileSync('git', ['commit', '-m', 'Test change'], { cwd: worktreeDir }); - - // Create worktree-session file - const resolvedPath = resolve(worktreeDir); - const sessionFilename = resolvedPath.replace(/[/\\:]/g, '-') + '.json'; - const sessionPath = join(testDir, '.takt', 'worktree-sessions', sessionFilename); - const sessionData = { - agentSessions: {}, - updatedAt: new Date().toISOString(), - provider: 'claude', - }; - writeFileSync(sessionPath, JSON.stringify(sessionData, null, 2)); - - // Verify branch is listed - const branchesBefore = listTaktBranches(testDir); - const foundBefore = branchesBefore.find(b => b.branch === branchName); - expect(foundBefore).toBeDefined(); - expect(foundBefore?.worktreePath).toBe(worktreeDir); - - // Verify worktree directory and session file exist - expect(existsSync(worktreeDir)).toBe(true); - expect(existsSync(sessionPath)).toBe(true); - - // Delete branch - const result = deleteBranch(testDir, { - info: foundBefore!, - filesChanged: 1, - taskSlug: branchSlug, - originalInstruction: 'Test instruction', - }); - - // Verify deletion succeeded - expect(result).toBe(true); - - // Verify worktree directory was removed - expect(existsSync(worktreeDir)).toBe(false); - - // Verify session file was removed - expect(existsSync(sessionPath)).toBe(false); - - // Verify branch is no longer listed - const branchesAfter = listTaktBranches(testDir); - const foundAfter = branchesAfter.find(b => b.branch === branchName); - expect(foundAfter).toBeUndefined(); - }); - - it('should handle deletion when worktree directory is already deleted', () => { - // Create worktree - const branchSlug = '20260203T1001-already-deleted'; - worktreeDir = join(tmpdir(), branchSlug); - execFileSync('git', ['clone', '--shared', testDir, worktreeDir]); - - // Configure git user in worktree (shared clones don't inherit config) - execFileSync('git', ['config', 'user.name', 'Test User'], { cwd: worktreeDir }); - execFileSync('git', ['config', 'user.email', 'test@example.com'], { cwd: worktreeDir }); - - const branchName = `takt/${branchSlug}`; - execFileSync('git', ['checkout', '-b', branchName], { cwd: worktreeDir }); - - // Create worktree-session file - const resolvedPath = resolve(worktreeDir); - const sessionFilename = resolvedPath.replace(/[/\\:]/g, '-') + '.json'; - const sessionPath = join(testDir, '.takt', 'worktree-sessions', sessionFilename); - const sessionData = { - agentSessions: {}, - updatedAt: new Date().toISOString(), - }; - writeFileSync(sessionPath, JSON.stringify(sessionData, null, 2)); - - // Manually delete worktree directory before deletion - rmSync(worktreeDir, { recursive: true, force: true }); - - // Delete branch (should not fail even though worktree is gone) - const result = deleteBranch(testDir, { - info: { - branch: branchName, - commit: 'worktree', - worktreePath: worktreeDir, - }, - filesChanged: 0, - taskSlug: branchSlug, - originalInstruction: 'Test instruction', - }); - - // Verify deletion succeeded - expect(result).toBe(true); - - // Verify session file was still removed - expect(existsSync(sessionPath)).toBe(false); - }); - - it('should delete regular (non-worktree) branches normally', () => { + it('should delete regular branches normally', () => { const defaultBranch = execFileSync('git', ['branch', '--show-current'], { cwd: testDir, encoding: 'utf-8', diff --git a/src/__tests__/it-worktree-sessions.test.ts b/src/__tests__/it-worktree-sessions.test.ts deleted file mode 100644 index 62d464b..0000000 --- a/src/__tests__/it-worktree-sessions.test.ts +++ /dev/null @@ -1,139 +0,0 @@ -/** - * Integration test for worktree-sessions recognition in takt list - * - * Tests that branches created in isolated worktrees (shared clones) - * are properly recognized by `takt list` through worktree-sessions tracking. - */ - -import { describe, it, expect, beforeEach, afterEach } from 'vitest'; -import { mkdirSync, writeFileSync, rmSync, existsSync } from 'node:fs'; -import { join, resolve } from 'node:path'; -import { execFileSync } from 'node:child_process'; -import { tmpdir } from 'node:os'; -import { listTaktBranches } from '../infra/task/branchList.js'; - -describe('worktree-sessions recognition', () => { - let testDir: string; - let worktreeDir: string; - - beforeEach(() => { - // Create temporary git repository - testDir = join(tmpdir(), `takt-test-${Date.now()}`); - mkdirSync(testDir, { recursive: true }); - - // Initialize git repo - execFileSync('git', ['init'], { cwd: testDir }); - execFileSync('git', ['config', 'user.name', 'Test User'], { cwd: testDir }); - execFileSync('git', ['config', 'user.email', 'test@example.com'], { cwd: testDir }); - - // Create initial commit - writeFileSync(join(testDir, 'README.md'), '# Test'); - execFileSync('git', ['add', '.'], { cwd: testDir }); - execFileSync('git', ['commit', '-m', 'Initial commit'], { cwd: testDir }); - - // Create .takt directory structure - const taktDir = join(testDir, '.takt'); - mkdirSync(taktDir, { recursive: true }); - mkdirSync(join(taktDir, 'worktree-sessions'), { recursive: true }); - }); - - afterEach(() => { - // Cleanup - if (worktreeDir && existsSync(worktreeDir)) { - rmSync(worktreeDir, { recursive: true, force: true }); - } - if (existsSync(testDir)) { - rmSync(testDir, { recursive: true, force: true }); - } - }); - - it('should recognize branches from worktree-sessions', () => { - // Simulate worktree creation (directory name includes timestamp-slug) - const branchSlug = '20260203T0900-test-feature'; - worktreeDir = join(tmpdir(), branchSlug); - - // Create shared clone - execFileSync('git', ['clone', '--shared', testDir, worktreeDir]); - - // Configure git user in worktree (shared clones don't inherit config) - execFileSync('git', ['config', 'user.name', 'Test User'], { cwd: worktreeDir }); - execFileSync('git', ['config', 'user.email', 'test@example.com'], { cwd: worktreeDir }); - - // Create and checkout takt branch in worktree - const branchName = `takt/${branchSlug}`; - execFileSync('git', ['checkout', '-b', branchName], { cwd: worktreeDir }); - - // Make a change - writeFileSync(join(worktreeDir, 'test.txt'), 'test content'); - execFileSync('git', ['add', 'test.txt'], { cwd: worktreeDir }); - execFileSync('git', ['commit', '-m', 'Test change'], { cwd: worktreeDir }); - - // Create worktree-session file (using same encoding as encodeWorktreePath) - const resolvedPath = resolve(worktreeDir); - const sessionFilename = resolvedPath.replace(/[/\\:]/g, '-') + '.json'; - const sessionPath = join(testDir, '.takt', 'worktree-sessions', sessionFilename); - const sessionData = { - agentSessions: {}, - updatedAt: new Date().toISOString(), - provider: 'claude', - }; - writeFileSync(sessionPath, JSON.stringify(sessionData, null, 2)); - - // Test: listTaktBranches should find the worktree branch - const branches = listTaktBranches(testDir); - - expect(branches.length).toBeGreaterThan(0); - const found = branches.find(b => b.branch === branchName); - expect(found).toBeDefined(); - expect(found?.worktreePath).toBe(worktreeDir); - }); - - it('should skip worktree-sessions when worktree directory is deleted', () => { - // Create worktree-session file for non-existent directory - worktreeDir = '/nonexistent/path/20260203T0900-test'; - const resolvedPath = resolve(worktreeDir); - const sessionFilename = resolvedPath.replace(/[/\\:]/g, '-') + '.json'; - const sessionPath = join(testDir, '.takt', 'worktree-sessions', sessionFilename); - const sessionData = { - agentSessions: {}, - updatedAt: new Date().toISOString(), - }; - writeFileSync(sessionPath, JSON.stringify(sessionData, null, 2)); - - // Test: listTaktBranches should not include the non-existent worktree - const branches = listTaktBranches(testDir); - - const found = branches.find(b => b.worktreePath === worktreeDir); - expect(found).toBeUndefined(); - }); - - it('should extract correct branch name from session filename', () => { - // Create worktree (directory name includes timestamp-slug) - const branchSlug = '20260203T0851-unify-debug-log'; - worktreeDir = join(tmpdir(), branchSlug); - execFileSync('git', ['clone', '--shared', testDir, worktreeDir]); - - // Configure git user in worktree (shared clones don't inherit config) - execFileSync('git', ['config', 'user.name', 'Test User'], { cwd: worktreeDir }); - execFileSync('git', ['config', 'user.email', 'test@example.com'], { cwd: worktreeDir }); - - const branchName = `takt/${branchSlug}`; - execFileSync('git', ['checkout', '-b', branchName], { cwd: worktreeDir }); - - // Create session file with proper path encoding - const resolvedPath = resolve(worktreeDir); - const sessionFilename = resolvedPath.replace(/[/\\:]/g, '-') + '.json'; - const sessionPath = join(testDir, '.takt', 'worktree-sessions', sessionFilename); - const sessionData = { - agentSessions: {}, - updatedAt: new Date().toISOString(), - }; - writeFileSync(sessionPath, JSON.stringify(sessionData, null, 2)); - - const branches = listTaktBranches(testDir); - - const found = branches.find(b => b.branch === branchName); - expect(found).toBeDefined(); - expect(found?.worktreePath).toBe(worktreeDir); - }); -}); diff --git a/src/features/tasks/list/listNonInteractive.ts b/src/features/tasks/list/listNonInteractive.ts index 9c133f4..e26d415 100644 --- a/src/features/tasks/list/listNonInteractive.ts +++ b/src/features/tasks/list/listNonInteractive.ts @@ -51,9 +51,8 @@ function printNonInteractiveList( } for (const item of items) { - const worktreeLabel = item.info.worktreePath ? ' (worktree)' : ''; const instruction = item.originalInstruction ? ` - ${item.originalInstruction}` : ''; - info(`${item.info.branch}${worktreeLabel} (${item.filesChanged} files)${instruction}`); + info(`${item.info.branch} (${item.filesChanged} files)${instruction}`); } for (const task of pendingTasks) { diff --git a/src/infra/task/branchList.ts b/src/infra/task/branchList.ts index 53373c2..1d2cb82 100644 --- a/src/infra/task/branchList.ts +++ b/src/infra/task/branchList.ts @@ -7,8 +7,7 @@ */ import { execFileSync } from 'node:child_process'; -import { readdirSync, existsSync } from 'node:fs'; -import { join } from 'node:path'; +import { existsSync } from 'node:fs'; import { createLogger } from '../../shared/utils/index.js'; import type { BranchInfo, BranchListItem } from './types.js'; @@ -51,7 +50,7 @@ export class BranchManager { } } - /** List all takt-managed branches (local + remote + worktree-sessions) */ + /** List all takt-managed branches (local + remote) */ listTaktBranches(projectDir: string): BranchInfo[] { try { // Get local branches @@ -72,14 +71,8 @@ export class BranchManager { branch: info.branch.replace(/^origin\//, ''), // Strip origin/ prefix })); - // Get branches from worktree-sessions (for isolated worktrees without remote) - const worktreeBranches = this.listWorktreeSessions(projectDir); - - // Merge and deduplicate (local > remote > worktree-sessions) + // Merge and deduplicate (local > remote) const branchMap = new Map(); - for (const info of worktreeBranches) { - branchMap.set(info.branch, info); - } for (const info of remoteBranches) { branchMap.set(info.branch, info); } @@ -94,62 +87,6 @@ export class BranchManager { } } - /** List branches from worktree-sessions directory */ - private listWorktreeSessions(projectDir: string): BranchInfo[] { - const sessionsDir = join(projectDir, '.takt', 'worktree-sessions'); - if (!existsSync(sessionsDir)) { - return []; - } - - try { - const files = readdirSync(sessionsDir); - const branches: BranchInfo[] = []; - - for (const file of files) { - if (!file.endsWith('.json')) continue; - - // Extract branch slug from filename using timestamp pattern - // Filename format: -path-to-parent-dir-{timestamp-slug}.json - const nameWithoutExt = file.slice(0, -5); // Remove .json - const match = nameWithoutExt.match(/(\d{8}T\d{4}-.+)$/); - if (!match || match.index === undefined || !match[1]) continue; - - const branchSlug = match[1]; - const branch = `${TAKT_BRANCH_PREFIX}${branchSlug}`; - - // Extract parent directory path (everything before the branch slug) - // Remove trailing dash before converting dashes to slashes - let encodedPath = nameWithoutExt.slice(0, match.index); - if (encodedPath.endsWith('-')) { - encodedPath = encodedPath.slice(0, -1); - } - - // Decode parent directory path (dashes back to slashes) - const parentPath = encodedPath.replace(/-/g, '/'); - - // Construct full worktree path - const worktreePath = join(parentPath, branchSlug); - - // Check if worktree directory still exists - if (!existsSync(worktreePath)) { - continue; // Skip if worktree was deleted - } - - // Use placeholder commit hash (worktree sessions don't track commit) - branches.push({ - branch, - commit: 'worktree', - worktreePath, - }); - } - - return branches; - } catch (err) { - log.error('Failed to list worktree sessions', { error: String(err) }); - return []; - } - } - /** Parse `git branch --list` formatted output into BranchInfo entries */ static parseTaktBranches(output: string): BranchInfo[] { const entries: BranchInfo[] = [];