diff --git a/resources/global/en/instructions/ai-fix.md b/resources/global/en/instructions/ai-fix.md new file mode 100644 index 0000000..5a21970 --- /dev/null +++ b/resources/global/en/instructions/ai-fix.md @@ -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} diff --git a/resources/global/en/instructions/ai-review.md b/resources/global/en/instructions/ai-review.md new file mode 100644 index 0000000..0a485ff --- /dev/null +++ b/resources/global/en/instructions/ai-review.md @@ -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 diff --git a/resources/global/en/instructions/arbitrate.md b/resources/global/en/instructions/arbitrate.md new file mode 100644 index 0000000..a1486d9 --- /dev/null +++ b/resources/global/en/instructions/arbitrate.md @@ -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 diff --git a/resources/global/en/instructions/architect.md b/resources/global/en/instructions/architect.md new file mode 100644 index 0000000..c34640c --- /dev/null +++ b/resources/global/en/instructions/architect.md @@ -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 diff --git a/resources/global/en/instructions/fix-supervisor.md b/resources/global/en/instructions/fix-supervisor.md new file mode 100644 index 0000000..3797ebd --- /dev/null +++ b/resources/global/en/instructions/fix-supervisor.md @@ -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} diff --git a/resources/global/en/instructions/fix.md b/resources/global/en/instructions/fix.md new file mode 100644 index 0000000..74ef769 --- /dev/null +++ b/resources/global/en/instructions/fix.md @@ -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} diff --git a/resources/global/en/instructions/implement.md b/resources/global/en/instructions/implement.md new file mode 100644 index 0000000..f0b77f1 --- /dev/null +++ b/resources/global/en/instructions/implement.md @@ -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 report format (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 report format (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} diff --git a/resources/global/en/instructions/plan-investigate.md b/resources/global/en/instructions/plan-investigate.md new file mode 100644 index 0000000..3ae97c8 --- /dev/null +++ b/resources/global/en/instructions/plan-investigate.md @@ -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 diff --git a/resources/global/en/instructions/plan.md b/resources/global/en/instructions/plan.md new file mode 100644 index 0000000..9916bb1 --- /dev/null +++ b/resources/global/en/instructions/plan.md @@ -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 diff --git a/resources/global/en/instructions/review-ai.md b/resources/global/en/instructions/review-ai.md new file mode 100644 index 0000000..43b86f6 --- /dev/null +++ b/resources/global/en/instructions/review-ai.md @@ -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 diff --git a/resources/global/en/instructions/review-arch.md b/resources/global/en/instructions/review-arch.md new file mode 100644 index 0000000..d345896 --- /dev/null +++ b/resources/global/en/instructions/review-arch.md @@ -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 diff --git a/resources/global/en/instructions/review-cqrs-es.md b/resources/global/en/instructions/review-cqrs-es.md new file mode 100644 index 0000000..ce16f07 --- /dev/null +++ b/resources/global/en/instructions/review-cqrs-es.md @@ -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. diff --git a/resources/global/en/instructions/review-frontend.md b/resources/global/en/instructions/review-frontend.md new file mode 100644 index 0000000..9e4b591 --- /dev/null +++ b/resources/global/en/instructions/review-frontend.md @@ -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. diff --git a/resources/global/en/instructions/review-qa.md b/resources/global/en/instructions/review-qa.md new file mode 100644 index 0000000..d50442a --- /dev/null +++ b/resources/global/en/instructions/review-qa.md @@ -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 diff --git a/resources/global/en/instructions/review-security.md b/resources/global/en/instructions/review-security.md new file mode 100644 index 0000000..609cd1a --- /dev/null +++ b/resources/global/en/instructions/review-security.md @@ -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 diff --git a/resources/global/en/instructions/supervise.md b/resources/global/en/instructions/supervise.md new file mode 100644 index 0000000..68b9d74 --- /dev/null +++ b/resources/global/en/instructions/supervise.md @@ -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 report format:** +```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 report format (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 +``` +``` diff --git a/resources/global/en/pieces/coding.yaml b/resources/global/en/pieces/coding.yaml index 78383ea..2941174 100644 --- a/resources/global/en/pieces/coding.yaml +++ b/resources/global/en/pieces/coding.yaml @@ -43,6 +43,18 @@ personas: 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: ../report-formats/plan.md + ai-review: ../report-formats/ai-review.md + architecture-review: ../report-formats/architecture-review.md + initial_movement: plan movements: @@ -51,35 +63,7 @@ movements: persona: architect-planner 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} - ``` + format: plan allowed_tools: - Read - Glob @@ -94,20 +78,7 @@ movements: 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 + instruction: plan - name: implement edit: true @@ -140,60 +111,7 @@ movements: 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} + instruction: implement - name: reviewers parallel: @@ -203,32 +121,7 @@ movements: stance: review 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) + format: ai-review allowed_tools: - Read - Glob @@ -238,16 +131,7 @@ movements: 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) + instruction: ai-review - name: arch-review edit: false @@ -255,37 +139,7 @@ movements: stance: review 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) + format: architecture-review allowed_tools: - Read - Glob @@ -295,21 +149,7 @@ movements: 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 + instruction: review-arch rules: - condition: all("No AI-specific issues", "approved") @@ -338,30 +178,4 @@ movements: 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} + instruction: fix diff --git a/resources/global/en/pieces/default.yaml b/resources/global/en/pieces/default.yaml index ce65a42..ec2d547 100644 --- a/resources/global/en/pieces/default.yaml +++ b/resources/global/en/pieces/default.yaml @@ -1,38 +1,55 @@ # Default TAKT Piece # Plan -> Architect -> Implement -> AI Review -> Reviewers (parallel: Architect + QA) -> Supervisor Approval # -# Boilerplate sections (Piece Context, User Request, Previous Response, -# Additional User Inputs, Instructions heading) are auto-injected by buildInstruction(). -# Only movement-specific content belongs in instruction_template. -# -# Template Variables (available in instruction_template): -# {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) -# {previous_response} - Output from the previous movement (only when pass_previous_response: true) -# {report_dir} - Report directory name (e.g., "20250126-143052-task-summary") -# -# Movement-level Fields: -# report: - Report file(s) for the movement (auto-injected as Report File/Files in Piece Context) -# Single: report: 00-plan.md -# Multiple: report: -# - Scope: 01-coder-scope.md -# - Decisions: 02-coder-decisions.md +# 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: default description: Standard development piece with planning and specialized reviews max_iterations: 30 +stances: + coding: ../stances/coding.md + review: ../stances/review.md + testing: ../stances/testing.md + personas: planner: ../personas/planner.md - architect: ../personas/architect-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: ../report-formats/plan.md + architecture-design: ../report-formats/architecture-design.md + ai-review: ../report-formats/ai-review.md + architecture-review: ../report-formats/architecture-review.md + qa-review: ../report-formats/qa-review.md + validation: ../report-formats/validation.md + summary: ../report-formats/summary.md + initial_movement: plan loop_monitors: @@ -65,27 +82,7 @@ movements: persona: planner report: name: 00-plan.md - format: | - ```markdown - # Task Plan - - ## Original Request - {User's request as-is} - - ## Analysis Results - - ### Objective - {What needs to be achieved} - - ### Scope - {Impact scope} - - ### Implementation Approach - {How to proceed} - - ## Clarifications Needed (if any) - - {Unclear points or items requiring confirmation} - ``` + format: plan allowed_tools: - Read - Glob @@ -104,45 +101,14 @@ movements: Clarifications needed: - {Question 1} - {Question 2} - instruction_template: | - Analyze the task and create an implementation plan. - - **Note:** If returned from implement movement (Previous Response exists), - review and revise the plan based on that feedback (replan). - - **Tasks (for implementation tasks):** - 1. Understand the requirements - 2. Identify impact scope - 3. Decide implementation approach + instruction: plan - name: architect edit: false - persona: architect + persona: architect-planner report: name: 01-architecture.md - format: | - ```markdown - # Architecture Design - - ## Task Size - Small / Medium / Large - - ## Design Decisions - - ### File Structure - | File | Role | - |------|------| - | `src/example.ts` | Summary | - - ### Technology Selection - - {Selected technologies/libraries and reasoning} - - ### Design Patterns - - {Patterns to adopt and where to apply} - - ## Implementation Guidelines - - {Guidelines for Coder to follow during implementation} - ``` + format: architecture-design allowed_tools: - Read - Glob @@ -156,32 +122,14 @@ movements: next: implement - condition: Insufficient info, cannot proceed next: ABORT - instruction_template: | - Read the plan report ({report:00-plan.md}) and perform architecture design. - - **Small task criteria:** - - Only 1-2 files to modify - - No design decisions needed - - No technology selection needed - - For small tasks, skip the design report and use the "Small task (no design needed)" rule. - - **Tasks requiring design:** - - 3+ files to modify - - Adding new modules/features - - Technology selection needed - - Architecture pattern decisions needed - - **Tasks:** - 1. Evaluate task size - 2. Decide file structure - 3. Select technology (if needed) - 4. Choose design patterns - 5. Create implementation guidelines for Coder + instruction: architect - name: implement edit: true persona: coder + stance: + - coding + - testing session: refresh report: - Scope: 02-coder-scope.md @@ -207,89 +155,15 @@ movements: next: implement requires_user_input: true interactive_only: true - instruction_template: | - Follow the plan from the plan movement and the design from the architect movement. - - **Reports to reference:** - - Plan: {report:00-plan.md} - - Design: {report:01-architecture.md} (if exists) - - Use only the Report Directory files shown in Piece Context. Do not search or open reports outside that directory. - - **Important:** Do not make design decisions; follow the design determined in the architect movement. - Report if you encounter unclear points or need design changes. - - **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 (on completion, only if decisions were made):** - ```markdown - # Decision Log - - ## 1. {Decision Content} - - **Background**: {Why the decision was needed} - - **Options Considered**: {List of options} - - **Reason**: {Why this option was chosen} - ``` - - **Required output (include headings)** - ## Work done - - {summary of work performed} - ## Changes made - - {summary of code changes} - ## Test results - - {command and outcome} - - **No-implementation handling (required)** + instruction: implement - name: ai_review edit: false persona: ai-antipattern-reviewer + stance: review report: name: 04-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) + format: ai-review allowed_tools: - Read - Glob @@ -301,21 +175,14 @@ movements: next: reviewers - condition: AI-specific issues found next: ai_fix - instruction_template: | - **This is AI Review iteration {movement_iteration}.** - - For the 1st iteration, review thoroughly and report all issues at once. - For iteration 2+, prioritize verifying that previously REJECTed items have been fixed. - - Review the code for AI-specific issues: - - Assumption validation - - Plausible but wrong patterns - - Context fit with existing codebase - - Scope creep detection + instruction: ai-review - name: ai_fix edit: true persona: coder + stance: + - coding + - testing session: refresh allowed_tools: - Read @@ -334,51 +201,12 @@ movements: next: ai_no_fix - condition: Cannot proceed, insufficient info next: ai_no_fix - instruction_template: | - **This is AI Review iteration {movement_iteration}.** - - If this is iteration 2 or later, it means your previous fixes were not actually applied. - **Your belief that you "already fixed it" is wrong.** - - **First, acknowledge:** - - Files you thought were "fixed" are actually not fixed - - Your understanding of previous work is incorrect - - You need to start from zero - - **Required actions:** - 1. Open all flagged files with Read tool (drop assumptions, verify facts) - 2. Search for problem code with grep to confirm it exists - 3. Fix confirmed problems with Edit tool - 4. Run tests to verify (`./gradlew :backend:test` etc.) - 5. Report specifically "what you checked and what you fixed" - - **Report format:** - - ❌ "Already fixed" - - ✅ "Checked file X at L123, found problem Y, fixed to Z" - - **Absolutely prohibited:** - - Reporting "fixed" without opening files - - **Handling "no fix needed" (required)** - - Do not claim "no fix needed" unless you can show the checked target file(s) for each AI Review issue - - If an issue involves generated code or spec sync, and you cannot verify the source spec, output the tag for "Unable to proceed with fixes" - - When "no fix needed", output the tag for "Unable to proceed with fixes" and include the reason + checked scope - - **Required output (include headings)** - ## Files checked - - {path:line} - ## Searches run - - {command and summary} - ## Fixes applied - - {what changed} - ## Test results - - {command and outcome} - - Judging based on assumptions - - Leaving problems that AI Reviewer REJECTED + instruction: ai-fix - name: ai_no_fix edit: false persona: architecture-reviewer + stance: review allowed_tools: - Read - Glob @@ -388,57 +216,17 @@ movements: next: ai_fix - condition: ai_fix's judgment is valid (no fix needed) next: reviewers - instruction_template: | - ai_review (reviewer) and ai_fix (coder) disagree. - - - ai_review found issues and REJECTed - - ai_fix verified and determined "no fix needed" - - Review both outputs and arbitrate which judgment is correct. - - **Reports to reference:** - - AI Review results: {report:04-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, test results)? - - Are the findings non-blocking (record-only) or do they require actual fixes? + instruction: arbitrate - name: reviewers parallel: - name: arch-review edit: false persona: architecture-reviewer + stance: review report: name: 05-architect-review.md - format: | - ```markdown - # Architecture Review - - ## Result: APPROVE / REJECT - - ## Summary - {1-2 sentences summarizing result} - - ## Reviewed Perspectives - - [x] Structure & Design - - [x] Code Quality - - [x] Change Scope - - ## Issues (if REJECT) - | # | Scope | Location | Issue | Fix | - |---|-------|----------|-------|-----| - | 1 | In-scope | `src/file.ts:42` | Issue description | Fix method | - - 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 or less) - - REJECT -> Issues in table format (30 lines or less) + format: architecture-review allowed_tools: - Read - Glob @@ -448,52 +236,15 @@ movements: rules: - condition: approved - condition: needs_fix - instruction_template: | - **Verify that the implementation follows the design from the architect movement.** - Do NOT review AI-specific issues (that's the ai_review movement). - - **Reports to reference:** - - Design: {report:01-architecture.md} (if exists) - - Implementation scope: {report:02-coder-scope.md} - - **Review perspectives:** - - Design consistency (does it follow the file structure and patterns defined by architect?) - - Code quality - - Change scope appropriateness - - Test coverage - - Dead code - - Call chain verification - - **Note:** For small tasks that skipped the architect movement, review design validity as usual. + instruction: review-arch - name: qa-review edit: false persona: qa-reviewer + stance: review report: name: 06-qa-review.md - format: | - ```markdown - # QA Review - - ## Result: APPROVE / REJECT - - ## Summary - {1-2 sentences summarizing result} - - ## Reviewed Perspectives - | Perspective | Result | Notes | - |-------------|--------|-------| - | Test Coverage | ✅ | - | - | Test Quality | ✅ | - | - | Error Handling | ✅ | - | - | Documentation | ✅ | - | - | Maintainability | ✅ | - | - - ## Issues (if REJECT) - | # | Category | Issue | Fix | - |---|----------|-------|-----| - | 1 | Testing | Issue description | Fix method | - ``` + format: qa-review allowed_tools: - Read - Glob @@ -503,15 +254,7 @@ movements: rules: - condition: approved - condition: needs_fix - instruction_template: | - Review the changes from the quality assurance perspective. - - **Review Criteria:** - - Test coverage and quality - - Test strategy (unit/integration/E2E) - - Error handling - - Logging and monitoring - - Maintainability + instruction: review-qa rules: - condition: all("approved") next: supervise @@ -521,6 +264,9 @@ movements: - name: fix edit: true persona: coder + stance: + - coding + - testing allowed_tools: - Read - Glob @@ -536,25 +282,12 @@ movements: next: reviewers - condition: Cannot proceed, insufficient info next: plan - instruction_template: | - Address the feedback from the reviewers. - The "Original User Request" is reference information, not the latest instruction. - Review the session conversation history and fix the issues raised by the reviewers. - - - **Required output (include headings)** - ## Work done - - {summary of work performed} - ## Changes made - - {summary of code changes} - ## Test results - - {command and outcome} - ## Evidence - - {key files/grep/diff/log evidence you verified} + instruction: fix - name: supervise edit: false persona: supervisor + stance: review report: - Validation: 07-supervisor-validation.md - Summary: summary.md @@ -570,68 +303,4 @@ movements: next: COMPLETE - condition: Requirements unmet, tests failing, build errors next: plan - instruction_template: | - Run tests, verify the build, and perform final approval. - - **Piece Overall Review:** - 1. Does the implementation match the plan ({report:00-plan.md}) and design ({report:01-architecture.md}, if exists)? - 2. Were all review movement issues addressed? - 3. Was the original task objective achieved? - - **Review Reports:** Read all reports in Report Directory and - check for any unaddressed improvement suggestions. - - **Validation report format:** - ```markdown - # Final Validation Results - - ## Result: APPROVE / REJECT - - ## Validation Summary - | Item | Status | Verification Method | - |------|--------|---------------------| - | Requirements met | ✅ | Matched against requirements list | - | Tests | ✅ | `npm test` (N passed) | - | Build | ✅ | `npm run build` succeeded | - | Functional check | ✅ | Main flows verified | - - ## Deliverables - - Created: {Created files} - - Modified: {Modified files} - - ## Incomplete Items (if REJECT) - | # | Item | Reason | - |---|------|--------| - | 1 | {Item} | {Reason} | - ``` - - **Summary report format (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 | - - ## Review Results - | Review | Result | - |--------|--------| - | Architecture Design | ✅ Complete | - | AI Review | ✅ APPROVE | - | Architect Review | ✅ APPROVE | - | QA | ✅ APPROVE | - | Supervisor | ✅ APPROVE | - - ## Verification Commands - ```bash - npm test - npm run build - ``` - ``` + instruction: supervise diff --git a/resources/global/en/pieces/expert.yaml b/resources/global/en/pieces/expert.yaml index e7a1652..fed3e2e 100644 --- a/resources/global/en/pieces/expert.yaml +++ b/resources/global/en/pieces/expert.yaml @@ -9,26 +9,14 @@ # └─ qa-review # any("needs_fix") → fix → reviewers # -# AI review runs immediately after implementation to catch AI-specific issues early, -# before expert reviews begin. -# -# Boilerplate sections (Piece Context, User Request, Previous Response, -# Additional User Inputs, Instructions heading) are auto-injected by buildInstruction(). -# Only movement-specific content belongs in instruction_template. -# -# Template Variables (available in instruction_template): -# {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) -# {previous_response} - Output from the previous movement (only when pass_previous_response: true) -# {report_dir} - Report directory name (e.g., "20250126-143052-task-summary") -# -# Movement-level Fields: -# report: - Report file(s) for the movement (auto-injected as Report File/Files in Piece Context) -# Single: report: 00-plan.md -# Multiple: report: -# - Scope: 01-coder-scope.md -# - Decisions: 02-coder-decisions.md +# 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: expert description: Architecture, Frontend, Security, QA Expert Review @@ -50,6 +38,30 @@ personas: 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: ../report-formats/plan.md + ai-review: ../report-formats/ai-review.md + architecture-review: ../report-formats/architecture-review.md + frontend-review: ../report-formats/frontend-review.md + security-review: ../report-formats/security-review.md + qa-review: ../report-formats/qa-review.md + validation: ../report-formats/validation.md + summary: ../report-formats/summary.md + initial_movement: plan movements: @@ -61,27 +73,7 @@ movements: persona: planner report: name: 00-plan.md - format: | - ```markdown - # Task Plan - - ## Original Request - {User's request as-is} - - ## Analysis Results - - ### Objective - {What needs to be achieved} - - ### Scope - {Impact scope} - - ### Implementation Approach - {How to proceed} - - ## Clarifications Needed (if any) - - {Unclear points or items requiring confirmation} - ``` + format: plan allowed_tools: - Read - Glob @@ -89,16 +81,7 @@ movements: - Bash - WebSearch - WebFetch - instruction_template: | - Analyze the task and create an implementation plan. - - **Note:** If returned from implement movement (Previous Response exists), - review and revise the plan based on that feedback (replan). - - **Tasks:** - 1. Understand the requirements - 2. Identify impact scope - 3. Decide implementation approach + instruction: plan rules: - condition: Task analysis and planning is complete next: implement @@ -127,48 +110,7 @@ movements: - Bash - WebSearch - WebFetch - instruction_template: | - Follow the plan from the plan movement and implement. - Refer to the plan report ({report:00-plan.md}) and proceed with implementation. - Use only the Report Directory files shown in Piece Context. Do not search or open reports outside that directory. - - **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 (on completion, only if decisions were made):** - ```markdown - # Decision Log - - ## 1. {Decision Content} - - **Background**: {Why the decision was needed} - - **Options Considered**: {List of options} - - **Reason**: {Why this option was chosen} - ``` - - **Required output (include headings)** - ## Work done - - {summary of work performed} - ## Changes made - - {summary of code changes} - ## Test results - - {command and outcome} + instruction: implement rules: - condition: Implementation is complete next: ai_review @@ -190,49 +132,14 @@ movements: stance: review 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) + format: ai-review allowed_tools: - Read - Glob - Grep - WebSearch - WebFetch - instruction_template: | - **This is AI Review iteration {movement_iteration}.** - - For the 1st iteration, review thoroughly and report all issues at once. - For iteration 2+, prioritize verifying that previously REJECTed items have been fixed. - - Review the code for AI-specific issues: - - Assumption validation - - Plausible but wrong patterns - - Context fit with existing codebase - - Scope creep detection + instruction: ai-review rules: - condition: No AI-specific issues found next: reviewers @@ -255,50 +162,7 @@ movements: - Bash - WebSearch - WebFetch - instruction_template: | - **This is AI Review iteration {movement_iteration}.** - - If this is iteration 2 or later, it means your previous fixes were not actually applied. - **Your belief that you "already fixed it" is wrong.** - - **First, acknowledge:** - - Files you thought were "fixed" are actually not fixed - - Your understanding of previous work is incorrect - - You need to start from zero - - **Required actions:** - 1. Open all flagged files with Read tool (drop assumptions, verify facts) - 2. Search for problem code with grep to confirm it exists - 3. Fix confirmed problems with Edit tool - 4. Run tests to verify (`./gradlew :backend:test` etc.) - 5. Report specifically "what you checked and what you fixed" - - **Report format:** - - ❌ "Already fixed" - - ✅ "Checked file X at L123, found problem Y, fixed to Z" - - **Absolutely prohibited:** - - Reporting "fixed" without opening files - - Judging based on assumptions - - Leaving problems that AI Reviewer REJECTED - - Removing scope creep - - **Handling "no fix needed" (required)** - - Do not claim "no fix needed" unless you can show the checked target file(s) for each AI Review issue - - If an issue involves generated code or spec sync, and you cannot verify the source spec, output the tag for "Unable to proceed with fixes" - - When "no fix needed", output the tag for "Unable to proceed with fixes" and include the reason + checked scope - - **Required output (include headings)** - ## Files checked - - {path:line} - ## Searches run - - {command and summary} - ## Fixes applied - - {what changed} - ## Test results - - {command and outcome} - - **No-implementation handling (required)** + instruction: ai-fix rules: - condition: AI Reviewer's issues have been fixed next: ai_review @@ -320,21 +184,7 @@ movements: next: ai_fix - condition: ai_fix's judgment is valid (no fix needed) next: reviewers - instruction_template: | - ai_review (reviewer) and ai_fix (coder) disagree. - - - ai_review found issues and REJECTed - - ai_fix verified and determined "no fix needed" - - Review both outputs and arbitrate which judgment is correct. - - **Reports to reference:** - - AI Review results: {report:03-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, test results)? - - Are the findings non-blocking (record-only) or do they require actual fixes? + instruction: arbitrate # =========================================== # Movement 3: Expert Reviews (Parallel) @@ -347,37 +197,7 @@ movements: stance: review report: name: 04-architect-review.md - format: | - ```markdown - # Architecture Review - - ## Result: APPROVE / REJECT - - ## Summary - {1-2 sentences summarizing result} - - ## 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 | - |---|-------|----------|-------|-----| - | 1 | In-scope | `src/file.ts:42` | Issue description | Fix method | - - 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 or less) - - REJECT -> Issues in table format (30 lines or less) + format: architecture-review allowed_tools: - Read - Glob @@ -388,16 +208,7 @@ movements: 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 Criteria:** - - Structure/design validity - - Code quality - - Change scope appropriateness - - Test coverage - - Dead code - - Call chain verification + instruction: review-arch - name: frontend-review edit: false @@ -405,29 +216,7 @@ movements: stance: review report: name: 05-frontend-review.md - format: | - ```markdown - # Frontend Review - - ## Result: APPROVE / REJECT - - ## Summary - {1-2 sentences summarizing result} - - ## Reviewed Perspectives - | Perspective | Result | Notes | - |-------------|--------|-------| - | Component Design | ✅ | - | - | State Management | ✅ | - | - | Performance | ✅ | - | - | Accessibility | ✅ | - | - | Type Safety | ✅ | - | - - ## Issues (if REJECT) - | # | Location | Issue | Fix | - |---|----------|-------|-----| - | 1 | `src/file.tsx:42` | Issue description | Fix method | - ``` + format: frontend-review allowed_tools: - Read - Glob @@ -438,19 +227,7 @@ movements: rules: - condition: approved - condition: needs_fix - instruction_template: | - Review the changes from the frontend development perspective. - - **Review Criteria:** - - Component design (separation of concerns, granularity) - - State management (local/global decisions) - - Performance (re-rendering, memoization) - - Accessibility (keyboard support, ARIA) - - Data fetching patterns - - TypeScript type safety - - **Note**: If this project does not include frontend code, - approve and proceed to the next movement. + instruction: review-frontend - name: security-review edit: false @@ -458,35 +235,7 @@ movements: stance: review report: name: 06-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) + format: security-review allowed_tools: - Read - Glob @@ -497,12 +246,7 @@ movements: rules: - condition: approved - condition: needs_fix - instruction_template: | - Perform security review on the changes. Check for vulnerabilities including: - - Injection attacks (SQL, Command, XSS) - - Authentication/Authorization issues - - Data exposure risks - - Cryptographic weaknesses + instruction: review-security - name: qa-review edit: false @@ -510,29 +254,7 @@ movements: stance: review report: name: 07-qa-review.md - format: | - ```markdown - # QA Review - - ## Result: APPROVE / REJECT - - ## Summary - {1-2 sentences summarizing result} - - ## Reviewed Perspectives - | Perspective | Result | Notes | - |-------------|--------|-------| - | Test Coverage | ✅ | - | - | Test Quality | ✅ | - | - | Error Handling | ✅ | - | - | Documentation | ✅ | - | - | Maintainability | ✅ | - | - - ## Issues (if REJECT) - | # | Category | Issue | Fix | - |---|----------|-------|-----| - | 1 | Testing | Issue description | Fix method | - ``` + format: qa-review allowed_tools: - Read - Glob @@ -543,16 +265,7 @@ movements: rules: - condition: approved - condition: needs_fix - instruction_template: | - Review the changes from the quality assurance perspective. - - **Review Criteria:** - - Test coverage and quality - - Test strategy (unit/integration/E2E) - - Documentation (in-code and external) - - Error handling - - Logging and monitoring - - Maintainability + instruction: review-qa rules: - condition: all("approved") next: supervise @@ -580,21 +293,7 @@ movements: next: reviewers - condition: Cannot proceed, insufficient info next: plan - instruction_template: | - Address the feedback from the reviewers. - The "Original User Request" is reference information, not the latest instruction. - Review the session conversation history and fix the issues raised by the reviewers. - - - **Required output (include headings)** - ## Work done - - {summary of work performed} - ## Changes made - - {summary of code changes} - ## Test results - - {command and outcome} - ## Evidence - - {key files/grep/diff/log evidence you verified} + instruction: fix # =========================================== # Movement 4: Supervision @@ -612,80 +311,7 @@ movements: - Grep - WebSearch - WebFetch - instruction_template: | - ## Previous Reviews Summary - Reaching this movement means all the following reviews have been APPROVED: - - Architecture Review: APPROVED - - Frontend Review: APPROVED - - AI Review: APPROVED - - Security Review: APPROVED - - QA Review: APPROVED - - Run tests, verify the build, and perform final approval. - - **Piece Overall Review:** - 1. Does the implementation match the plan ({report:00-plan.md})? - 2. Were all review movement issues addressed? - 3. Was the original task objective achieved? - - **Review Reports:** Read all reports in Report Directory and - check for any unaddressed improvement suggestions. - - **Validation report format:** - ```markdown - # Final Validation Results - - ## Result: APPROVE / REJECT - - ## Validation Summary - | Item | Status | Verification Method | - |------|--------|---------------------| - | Requirements met | ✅ | Matched against requirements list | - | Tests | ✅ | `npm test` (N passed) | - | Build | ✅ | `npm run build` succeeded | - | Functional check | ✅ | Main flows verified | - - ## Deliverables - - Created: {Created files} - - Modified: {Modified files} - - ## Incomplete Items (if REJECT) - | # | Item | Reason | - |---|------|--------| - | 1 | {Item} | {Reason} | - ``` - - **Summary report format (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 | - - ## Review Results - | Review | Result | - |--------|--------| - | Architecture | ✅ APPROVE | - | Frontend | ✅ APPROVE | - | AI Review | ✅ APPROVE | - | Security | ✅ APPROVE | - | QA | ✅ APPROVE | - | Supervisor | ✅ APPROVE | - - ## Verification Commands - ```bash - npm test - npm run build - ``` - ``` + instruction: supervise rules: - condition: All validations pass and ready to merge next: COMPLETE @@ -707,22 +333,7 @@ movements: - Bash - WebSearch - WebFetch - instruction_template: | - Fix the issues pointed out by the supervisor. - - The supervisor has identified issues from a big-picture perspective. - Address items in priority order. - - - **Required output (include headings)** - ## Work done - - {summary of work performed} - ## Changes made - - {summary of code changes} - ## Test results - - {command and outcome} - ## Evidence - - {key files/grep/diff/log evidence you verified} + instruction: fix-supervisor rules: - condition: Supervisor's issues have been fixed next: supervise diff --git a/resources/global/en/pieces/minimal.yaml b/resources/global/en/pieces/minimal.yaml index 3a8d008..29c8d84 100644 --- a/resources/global/en/pieces/minimal.yaml +++ b/resources/global/en/pieces/minimal.yaml @@ -16,17 +16,35 @@ description: Minimal development piece (implement -> parallel review -> fix if n max_iterations: 20 +stances: + coding: ../stances/coding.md + review: ../stances/review.md + testing: ../stances/testing.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 + +report_formats: + ai-review: ../report-formats/ai-review.md + initial_movement: implement movements: - name: implement edit: true persona: coder + stance: + - coding + - testing report: - Scope: 01-coder-scope.md - Decisions: 02-coder-decisions.md @@ -40,48 +58,7 @@ movements: - WebSearch - WebFetch permission_mode: edit - instruction_template: | - Implement the task. - Use only the Report Directory files shown in Piece Context. Do not search or open reports outside that directory. - - **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 (on completion, only if decisions were made):** - ```markdown - # Decision Log - - ## 1. {Decision Content} - - **Background**: {Why the decision was needed} - - **Options Considered**: {List of options} - - **Reason**: {Why this option was chosen} - ``` - - **Required output (include headings)** - ## Work done - - {summary of work performed} - ## Changes made - - {summary of code changes} - ## Test results - - {command and outcome} - + instruction: implement rules: - condition: Implementation complete next: reviewers @@ -97,34 +74,10 @@ movements: - name: ai_review edit: false persona: ai-antipattern-reviewer + stance: review 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) + format: ai-review allowed_tools: - Read - Glob @@ -132,12 +85,7 @@ movements: - WebSearch - WebFetch - 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 rules: - condition: No AI-specific issues - condition: AI-specific issues found @@ -145,6 +93,7 @@ movements: - name: supervise edit: false persona: supervisor + stance: review report: - Validation: 05-supervisor-validation.md - Summary: summary.md @@ -156,68 +105,7 @@ movements: - Bash - WebSearch - WebFetch - instruction_template: | - Run tests, verify the build, and perform final approval. - - **Piece Overall Review:** - 1. Does the implementation meet the original request? - 2. Were AI Review issues addressed? - 3. Was the original task objective achieved? - - **Review Reports:** Read all reports in Report Directory and - check for any unaddressed improvement suggestions. - - **Validation report format:** - ```markdown - # Final Validation Results - - ## Result: APPROVE / REJECT - - ## Validation Summary - | Item | Status | Verification Method | - |------|--------|---------------------| - | Requirements met | ✅ | Matched against requirements list | - | Tests | ✅ | `npm test` (N passed) | - | Build | ✅ | `npm run build` succeeded | - | Functional check | ✅ | Main flows verified | - - ## Deliverables - - Created: {Created files} - - Modified: {Modified files} - - ## Incomplete Items (if REJECT) - | # | Item | Reason | - |---|------|--------| - | 1 | {Item} | {Reason} | - ``` - - **Summary report format (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 | - - ## Review Results - | Review | Result | - |--------|--------| - | AI Review | ✅ APPROVE | - | Supervisor | ✅ APPROVE | - - ## Verification Commands - ```bash - npm test - npm run build - ``` - ``` + instruction: supervise rules: - condition: All checks passed - condition: Requirements unmet, tests failing @@ -237,6 +125,9 @@ movements: - name: ai_fix_parallel edit: true persona: coder + stance: + - coding + - testing allowed_tools: - Read - Glob @@ -251,51 +142,14 @@ movements: - condition: AI Reviewer's issues fixed - condition: No fix needed (verified target files/spec) - condition: Cannot proceed, insufficient info - instruction_template: | - **This is AI Review iteration {movement_iteration}.** - - If this is iteration 2 or later, it means your previous fixes were not actually applied. - **Your belief that you "already fixed it" is wrong.** - - **First, acknowledge:** - - Files you thought were "fixed" are actually not fixed - - Your understanding of previous work is incorrect - - You need to start from zero - - **Required actions:** - 1. Open all flagged files with Read tool (drop assumptions, verify facts) - 2. Search for problem code with grep to confirm it exists - 3. Fix confirmed problems with Edit tool - 4. Run tests to verify (e.g., `npm test`, `./gradlew test`) - 5. Report specifically "what you checked and what you fixed" - - **Report format:** - - ❌ "Already fixed" - - ✅ "Checked file X at L123, found problem Y, fixed to Z" - - **Absolutely prohibited:** - - Reporting "fixed" without opening files - - Judging based on assumptions - - Leaving problems that AI Reviewer REJECTED - - **Handling "no fix needed" (required)** - - Do not claim "no fix needed" unless you can show the checked target file(s) for each AI Review issue - - If an issue involves generated code or spec sync, and you cannot verify the source spec, output the tag for "Cannot proceed, insufficient info" - - When "no fix needed", output the tag for "Cannot proceed, insufficient info" and include the reason + checked scope - - **Required output (include headings)** - ## Files checked - - {path:line} - ## Searches run - - {command and summary} - ## Fixes applied - - {what changed} - ## Test results - - {command and outcome} + instruction: ai-fix - name: supervise_fix_parallel edit: true persona: coder + stance: + - coding + - testing allowed_tools: - Read - Glob @@ -309,21 +163,7 @@ movements: rules: - condition: Supervisor's issues fixed - condition: Cannot proceed, insufficient info - instruction_template: | - Fix the issues pointed out by the supervisor. - - The supervisor has identified issues from a big-picture perspective. - Address items in priority order. - - **Required output (include headings)** - ## Work done - - {summary of work performed} - ## Changes made - - {summary of code changes} - ## Test results - - {command and outcome} - ## Evidence - - {key files/grep/diff/log evidence you verified} + instruction: fix-supervisor rules: - condition: all("AI Reviewer's issues fixed", "Supervisor's issues fixed") @@ -334,6 +174,9 @@ movements: - name: ai_fix edit: true persona: coder + stance: + - coding + - testing allowed_tools: - Read - Glob @@ -351,51 +194,14 @@ movements: next: implement - condition: Cannot proceed, insufficient info next: implement - instruction_template: | - **This is AI Review iteration {movement_iteration}.** - - If this is iteration 2 or later, it means your previous fixes were not actually applied. - **Your belief that you "already fixed it" is wrong.** - - **First, acknowledge:** - - Files you thought were "fixed" are actually not fixed - - Your understanding of previous work is incorrect - - You need to start from zero - - **Required actions:** - 1. Open all flagged files with Read tool (drop assumptions, verify facts) - 2. Search for problem code with grep to confirm it exists - 3. Fix confirmed problems with Edit tool - 4. Run tests to verify (e.g., `npm test`, `./gradlew test`) - 5. Report specifically "what you checked and what you fixed" - - **Report format:** - - ❌ "Already fixed" - - ✅ "Checked file X at L123, found problem Y, fixed to Z" - - **Absolutely prohibited:** - - Reporting "fixed" without opening files - - Judging based on assumptions - - Leaving problems that AI Reviewer REJECTED - - **Handling "no fix needed" (required)** - - Do not claim "no fix needed" unless you can show the checked target file(s) for each AI Review issue - - If an issue involves generated code or spec sync, and you cannot verify the source spec, output the tag for "Cannot proceed, insufficient info" - - When "no fix needed", output the tag for "Cannot proceed, insufficient info" and include the reason + checked scope - - **Required output (include headings)** - ## Files checked - - {path:line} - ## Searches run - - {command and summary} - ## Fixes applied - - {what changed} - ## Test results - - {command and outcome} + instruction: ai-fix - name: supervise_fix edit: true persona: coder + stance: + - coding + - testing allowed_tools: - Read - Glob @@ -411,18 +217,4 @@ movements: next: reviewers - condition: Cannot proceed, insufficient info next: implement - instruction_template: | - Fix the issues pointed out by the supervisor. - - The supervisor has identified issues from a big-picture perspective. - Address items in priority order. - - **Required output (include headings)** - ## Work done - - {summary of work performed} - ## Changes made - - {summary of code changes} - ## Test results - - {command and outcome} - ## Evidence - - {key files/grep/diff/log evidence you verified} + instruction: fix-supervisor diff --git a/resources/global/en/pieces/review-only.yaml b/resources/global/en/pieces/review-only.yaml index d7312f9..785a8ac 100644 --- a/resources/global/en/pieces/review-only.yaml +++ b/resources/global/en/pieces/review-only.yaml @@ -35,6 +35,17 @@ personas: 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 + +report_formats: + architecture-review: ../report-formats/architecture-review.md + security-review: ../report-formats/security-review.md + ai-review: ../report-formats/ai-review.md + review-summary: ../report-formats/review-summary.md + initial_movement: plan movements: @@ -81,33 +92,7 @@ movements: stance: review 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) + format: architecture-review allowed_tools: - Read - Glob @@ -118,10 +103,7 @@ movements: 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 - name: security-review edit: false @@ -129,35 +111,7 @@ movements: stance: review 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) + format: security-review allowed_tools: - Read - Glob @@ -168,12 +122,7 @@ movements: 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 - name: ai-review edit: false @@ -181,32 +130,7 @@ movements: stance: review 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) + format: ai-review allowed_tools: - Read - Glob @@ -217,12 +141,7 @@ movements: 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 rules: - condition: all("approved") next: supervise diff --git a/resources/global/en/report-formats/ai-review.md b/resources/global/en/report-formats/ai-review.md new file mode 100644 index 0000000..0591515 --- /dev/null +++ b/resources/global/en/report-formats/ai-review.md @@ -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) diff --git a/resources/global/en/report-formats/architecture-design.md b/resources/global/en/report-formats/architecture-design.md new file mode 100644 index 0000000..44f30f0 --- /dev/null +++ b/resources/global/en/report-formats/architecture-design.md @@ -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} +``` diff --git a/resources/global/en/report-formats/architecture-review.md b/resources/global/en/report-formats/architecture-review.md new file mode 100644 index 0000000..2525bf2 --- /dev/null +++ b/resources/global/en/report-formats/architecture-review.md @@ -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) diff --git a/resources/global/en/report-formats/coder-decisions.md b/resources/global/en/report-formats/coder-decisions.md new file mode 100644 index 0000000..7f3b3e8 --- /dev/null +++ b/resources/global/en/report-formats/coder-decisions.md @@ -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} +``` diff --git a/resources/global/en/report-formats/coder-scope.md b/resources/global/en/report-formats/coder-scope.md new file mode 100644 index 0000000..2eb9635 --- /dev/null +++ b/resources/global/en/report-formats/coder-scope.md @@ -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} +``` diff --git a/resources/global/en/report-formats/cqrs-es-review.md b/resources/global/en/report-formats/cqrs-es-review.md new file mode 100644 index 0000000..ce79821 --- /dev/null +++ b/resources/global/en/report-formats/cqrs-es-review.md @@ -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} +``` diff --git a/resources/global/en/report-formats/frontend-review.md b/resources/global/en/report-formats/frontend-review.md new file mode 100644 index 0000000..eed15f1 --- /dev/null +++ b/resources/global/en/report-formats/frontend-review.md @@ -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 | +``` diff --git a/resources/global/en/report-formats/plan.md b/resources/global/en/report-formats/plan.md new file mode 100644 index 0000000..eaf4348 --- /dev/null +++ b/resources/global/en/report-formats/plan.md @@ -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} +``` diff --git a/resources/global/en/report-formats/qa-review.md b/resources/global/en/report-formats/qa-review.md new file mode 100644 index 0000000..170b254 --- /dev/null +++ b/resources/global/en/report-formats/qa-review.md @@ -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 | +``` diff --git a/resources/global/en/report-formats/review-summary.md b/resources/global/en/report-formats/review-summary.md new file mode 100644 index 0000000..bf354de --- /dev/null +++ b/resources/global/en/report-formats/review-summary.md @@ -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} +``` diff --git a/resources/global/en/report-formats/security-review.md b/resources/global/en/report-formats/security-review.md new file mode 100644 index 0000000..7f24c6d --- /dev/null +++ b/resources/global/en/report-formats/security-review.md @@ -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) diff --git a/resources/global/en/report-formats/summary.md b/resources/global/en/report-formats/summary.md new file mode 100644 index 0000000..6fbd682 --- /dev/null +++ b/resources/global/en/report-formats/summary.md @@ -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 +``` +``` diff --git a/resources/global/en/report-formats/validation.md b/resources/global/en/report-formats/validation.md new file mode 100644 index 0000000..a55ebec --- /dev/null +++ b/resources/global/en/report-formats/validation.md @@ -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} | +``` diff --git a/resources/global/en/stances/coding.md b/resources/global/en/stances/coding.md new file mode 100644 index 0000000..ae13ca0 --- /dev/null +++ b/resources/global/en/stances/coding.md @@ -0,0 +1,292 @@ +# Coding Stance + +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 +} +``` + +### 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 diff --git a/resources/global/en/stances/review.md b/resources/global/en/stances/review.md new file mode 100644 index 0000000..136974e --- /dev/null +++ b/resources/global/en/stances/review.md @@ -0,0 +1,124 @@ +# Review Stance + +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. diff --git a/resources/global/en/stances/testing.md b/resources/global/en/stances/testing.md new file mode 100644 index 0000000..475b1bd --- /dev/null +++ b/resources/global/en/stances/testing.md @@ -0,0 +1,88 @@ +# Testing Stance + +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 }) +``` diff --git a/resources/global/en/templates/instructions/ai-fix.md b/resources/global/en/templates/instructions/ai-fix.md new file mode 100644 index 0000000..802f99b --- /dev/null +++ b/resources/global/en/templates/instructions/ai-fix.md @@ -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. diff --git a/resources/global/en/templates/instructions/ai-review-standalone.md b/resources/global/en/templates/instructions/ai-review-standalone.md new file mode 100644 index 0000000..72fd428 --- /dev/null +++ b/resources/global/en/templates/instructions/ai-review-standalone.md @@ -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 +``` diff --git a/resources/global/en/templates/instructions/arbitrate.md b/resources/global/en/templates/instructions/arbitrate.md new file mode 100644 index 0000000..d38a3f8 --- /dev/null +++ b/resources/global/en/templates/instructions/arbitrate.md @@ -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 diff --git a/resources/global/en/templates/instructions/architect.md b/resources/global/en/templates/instructions/architect.md new file mode 100644 index 0000000..968c325 --- /dev/null +++ b/resources/global/en/templates/instructions/architect.md @@ -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 +``` diff --git a/resources/global/en/templates/instructions/fix.md b/resources/global/en/templates/instructions/fix.md new file mode 100644 index 0000000..4643b48 --- /dev/null +++ b/resources/global/en/templates/instructions/fix.md @@ -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 +``` diff --git a/resources/global/en/templates/instructions/implement.md b/resources/global/en/templates/instructions/implement.md new file mode 100644 index 0000000..ad9dea9 --- /dev/null +++ b/resources/global/en/templates/instructions/implement.md @@ -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 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 Area +- {Affected modules or features} +``` + +**Decisions report format (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. diff --git a/resources/global/en/templates/instructions/plan.md b/resources/global/en/templates/instructions/plan.md new file mode 100644 index 0000000..d12a431 --- /dev/null +++ b/resources/global/en/templates/instructions/plan.md @@ -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 +``` diff --git a/resources/global/en/templates/instructions/review.md b/resources/global/en/templates/instructions/review.md new file mode 100644 index 0000000..b22469f --- /dev/null +++ b/resources/global/en/templates/instructions/review.md @@ -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 +``` diff --git a/resources/global/en/templates/instructions/supervise.md b/resources/global/en/templates/instructions/supervise.md new file mode 100644 index 0000000..aae7853 --- /dev/null +++ b/resources/global/en/templates/instructions/supervise.md @@ -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 report format:** +```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 report format (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. diff --git a/resources/global/en/templates/personas/character.md b/resources/global/en/templates/personas/character.md new file mode 100644 index 0000000..cfb9dbb --- /dev/null +++ b/resources/global/en/templates/personas/character.md @@ -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 Stance + +- {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} diff --git a/resources/global/en/templates/personas/expert.md b/resources/global/en/templates/personas/expert.md new file mode 100644 index 0000000..2d74aa3 --- /dev/null +++ b/resources/global/en/templates/personas/expert.md @@ -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 Stance + +- {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} | diff --git a/resources/global/en/templates/personas/simple.md b/resources/global/en/templates/personas/simple.md new file mode 100644 index 0000000..d2b8698 --- /dev/null +++ b/resources/global/en/templates/personas/simple.md @@ -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 Stance + +- {Agent-specific behavioral guideline 1} +- {Agent-specific behavioral guideline 2} +- {Agent-specific behavioral guideline 3} +- {Agent-specific behavioral guideline 4} diff --git a/resources/global/en/templates/reports/architecture-design.md b/resources/global/en/templates/reports/architecture-design.md new file mode 100644 index 0000000..f1b4312 --- /dev/null +++ b/resources/global/en/templates/reports/architecture-design.md @@ -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} +``` diff --git a/resources/global/en/templates/reports/plan.md b/resources/global/en/templates/reports/plan.md new file mode 100644 index 0000000..f61b72d --- /dev/null +++ b/resources/global/en/templates/reports/plan.md @@ -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). diff --git a/resources/global/en/templates/reports/review.md b/resources/global/en/templates/reports/review.md new file mode 100644 index 0000000..2caf037 --- /dev/null +++ b/resources/global/en/templates/reports/review.md @@ -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) +``` diff --git a/resources/global/en/templates/reports/security-review.md b/resources/global/en/templates/reports/security-review.md new file mode 100644 index 0000000..90674a3 --- /dev/null +++ b/resources/global/en/templates/reports/security-review.md @@ -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) +``` diff --git a/resources/global/en/templates/reports/summary.md b/resources/global/en/templates/reports/summary.md new file mode 100644 index 0000000..c146171 --- /dev/null +++ b/resources/global/en/templates/reports/summary.md @@ -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 | diff --git a/resources/global/en/templates/reports/validation.md b/resources/global/en/templates/reports/validation.md new file mode 100644 index 0000000..39d5b4b --- /dev/null +++ b/resources/global/en/templates/reports/validation.md @@ -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} | +``` diff --git a/resources/global/en/templates/stances/stance.md b/resources/global/en/templates/stances/stance.md new file mode 100644 index 0000000..4e0005c --- /dev/null +++ b/resources/global/en/templates/stances/stance.md @@ -0,0 +1,49 @@ +# {Stance 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} diff --git a/src/__tests__/interactive.test.ts b/src/__tests__/interactive.test.ts index 4ed8401..efe2c44 100644 --- a/src/__tests__/interactive.test.ts +++ b/src/__tests__/interactive.test.ts @@ -240,10 +240,27 @@ describe('interactiveMode', () => { // When await interactiveMode('/project'); - // Then: each call receives only the current user input (session maintains context) + // Then: each call receives user input with stance injected (session maintains context) const mockProvider = mockGetProvider.mock.results[0]!.value as { _call: ReturnType }; - expect(mockProvider._call.mock.calls[0]?.[0]).toBe('first msg'); - expect(mockProvider._call.mock.calls[1]?.[0]).toBe('second msg'); + expect(mockProvider._call.mock.calls[0]?.[0]).toContain('first msg'); + expect(mockProvider._call.mock.calls[1]?.[0]).toContain('second msg'); + }); + + it('should inject stance into user messages', async () => { + // Given + setupInputSequence(['test message', '/cancel']); + setupMockProvider(['response']); + + // When + await interactiveMode('/project'); + + // Then: the prompt should contain stance section + const mockProvider = mockGetProvider.mock.results[0]!.value as { _call: ReturnType }; + const prompt = mockProvider._call.mock.calls[0]?.[0] as string; + expect(prompt).toContain('## Stance'); + expect(prompt).toContain('Interactive Mode Stance'); + expect(prompt).toContain('Stance Reminder'); + expect(prompt).toContain('test message'); }); it('should process initialInput as first message before entering loop', async () => { @@ -254,10 +271,12 @@ describe('interactiveMode', () => { // When const result = await interactiveMode('/project', 'a'); - // Then: AI should have been called with initialInput + // Then: AI should have been called with initialInput (with stance injected) const mockProvider = mockGetProvider.mock.results[0]!.value as { _call: ReturnType }; expect(mockProvider._call).toHaveBeenCalledTimes(2); - expect(mockProvider._call.mock.calls[0]?.[0]).toBe('a'); + const firstPrompt = mockProvider._call.mock.calls[0]?.[0] as string; + expect(firstPrompt).toContain('## Stance'); + expect(firstPrompt).toContain('a'); // /go should work because initialInput already started conversation expect(result.action).toBe('execute'); @@ -272,11 +291,13 @@ describe('interactiveMode', () => { // When const result = await interactiveMode('/project', 'a'); - // Then: each call receives only its own input (session handles history) + // Then: each call receives only its own input with stance (session handles history) const mockProvider = mockGetProvider.mock.results[0]!.value as { _call: ReturnType }; expect(mockProvider._call).toHaveBeenCalledTimes(3); - expect(mockProvider._call.mock.calls[0]?.[0]).toBe('a'); - expect(mockProvider._call.mock.calls[1]?.[0]).toBe('fix the login page'); + const firstPrompt = mockProvider._call.mock.calls[0]?.[0] as string; + const secondPrompt = mockProvider._call.mock.calls[1]?.[0] as string; + expect(firstPrompt).toContain('a'); + expect(secondPrompt).toContain('fix the login page'); // Task still contains all history for downstream use expect(result.action).toBe('execute'); diff --git a/src/__tests__/prompts.test.ts b/src/__tests__/prompts.test.ts index 7fa0578..6a058f6 100644 --- a/src/__tests__/prompts.test.ts +++ b/src/__tests__/prompts.test.ts @@ -17,12 +17,22 @@ describe('loadTemplate', () => { it('loads an English interactive template', () => { const result = loadTemplate('score_interactive_system_prompt', 'en'); - expect(result).toContain('You are a task planning assistant'); + expect(result).toContain('Interactive Mode Assistant'); + }); + + it('loads an English interactive stance template', () => { + const result = loadTemplate('score_interactive_stance', 'en'); + expect(result).toContain('Interactive Mode Stance'); }); it('loads a Japanese template', () => { const result = loadTemplate('score_interactive_system_prompt', 'ja'); - expect(result).toContain('あなたはTAKT'); + expect(result).toContain('対話モードアシスタント'); + }); + + it('loads a Japanese interactive stance template', () => { + const result = loadTemplate('score_interactive_stance', 'ja'); + expect(result).toContain('対話モードスタンス'); }); it('loads score_slug_system_prompt with explicit lang', () => { @@ -117,6 +127,7 @@ describe('renderTemplate', () => { describe('template file existence', () => { const allTemplates = [ 'score_interactive_system_prompt', + 'score_interactive_stance', 'score_summary_system_prompt', 'score_slug_system_prompt', 'perform_phase1_message', @@ -154,12 +165,26 @@ describe('caching', () => { }); describe('template content integrity', () => { - it('score_interactive_system_prompt contains core instructions', () => { + it('score_interactive_system_prompt contains persona definition', () => { const en = loadTemplate('score_interactive_system_prompt', 'en'); - expect(en).toContain('task planning assistant'); + expect(en).toContain('Interactive Mode Assistant'); + expect(en).toContain('Role Boundaries'); const ja = loadTemplate('score_interactive_system_prompt', 'ja'); - expect(ja).toContain('あなたはTAKT'); + expect(ja).toContain('対話モードアシスタント'); + expect(ja).toContain('役割の境界'); + }); + + it('score_interactive_stance contains behavioral guidelines', () => { + const en = loadTemplate('score_interactive_stance', 'en'); + expect(en).toContain('Interactive Mode Stance'); + expect(en).toContain('Principles'); + expect(en).toContain('Strict Requirements'); + + const ja = loadTemplate('score_interactive_stance', 'ja'); + expect(ja).toContain('対話モードスタンス'); + expect(ja).toContain('原則'); + expect(ja).toContain('厳守事項'); }); it('score_slug_system_prompt contains format specification', () => { diff --git a/src/features/interactive/interactive.ts b/src/features/interactive/interactive.ts index b0e7190..e78c9e8 100644 --- a/src/features/interactive/interactive.ts +++ b/src/features/interactive/interactive.ts @@ -92,9 +92,11 @@ function resolveLanguage(lang?: Language): 'en' | 'ja' { function getInteractivePrompts(lang: 'en' | 'ja', pieceContext?: PieceContext) { const systemPrompt = loadTemplate('score_interactive_system_prompt', lang, {}); + const stanceContent = loadTemplate('score_interactive_stance', lang, {}); return { systemPrompt, + stanceContent, lang, pieceContext, conversationLabel: getLabel('interactive.conversationLabel', lang), @@ -344,12 +346,27 @@ export async function interactiveMode( } } + /** + * Inject stance into user message for AI call. + * Follows the same pattern as piece execution (perform_phase1_message.md). + */ + function injectStance(userMessage: string): string { + const stanceIntro = lang === 'ja' + ? '以下のスタンスは行動規範です。必ず遵守してください。' + : 'The following stance defines behavioral guidelines. Please follow them.'; + const reminderLabel = lang === 'ja' + ? '上記の Stance セクションで定義されたスタンス規範を遵守してください。' + : 'Please follow the stance guidelines defined in the Stance section above.'; + return `## Stance\n${stanceIntro}\n\n${prompts.stanceContent}\n\n---\n\n${userMessage}\n\n---\n**Stance Reminder:** ${reminderLabel}`; + } + // Process initial input if provided (e.g. from `takt a`) if (initialInput) { history.push({ role: 'user', content: initialInput }); log.debug('Processing initial input', { initialInput, sessionId }); - const result = await callAIWithRetry(initialInput, prompts.systemPrompt); + const promptWithStance = injectStance(initialInput); + const result = await callAIWithRetry(promptWithStance, prompts.systemPrompt); if (result) { if (!result.success) { error(result.content); @@ -440,7 +457,8 @@ export async function interactiveMode( log.debug('Sending to AI', { messageCount: history.length, sessionId }); process.stdin.pause(); - const result = await callAIWithRetry(trimmed, prompts.systemPrompt); + const promptWithStance = injectStance(trimmed); + const result = await callAIWithRetry(promptWithStance, prompts.systemPrompt); if (result) { if (!result.success) { error(result.content); diff --git a/src/shared/prompts/en/score_interactive_stance.md b/src/shared/prompts/en/score_interactive_stance.md new file mode 100644 index 0000000..80a4634 --- /dev/null +++ b/src/shared/prompts/en/score_interactive_stance.md @@ -0,0 +1,51 @@ + +# Interactive Mode Stance + +Focus on creating task instructions for the piece. Do not execute tasks or investigate unnecessarily. + +## Principles + +| Principle | Standard | +|-----------|----------| +| Focus on instruction creation | Task execution is always the piece's job | +| Restrain investigation | Do not investigate unless explicitly requested | +| Concise responses | Key points only. Avoid verbose explanations | + +## Understanding User Intent + +The user is NOT asking YOU to do the work, but asking you to create task instructions for the PIECE. + +| User Statement | Correct Interpretation | +|---------------|----------------------| +| "Review this code" | Create instructions for the piece to review | +| "Implement feature X" | Create instructions for the piece to implement | +| "Fix this bug" | Create instructions for the piece to fix | + +## Investigation Guidelines + +### When Investigation IS Appropriate (Rare) + +Only when the user explicitly asks YOU to investigate: +- "Read the README to understand the project structure" +- "Read file X to see what it does" +- "What does this project do?" + +### When Investigation is NOT Appropriate (Most Cases) + +When the user is describing a task for the piece: +- "Review the changes" → Create instructions without investigating +- "Fix the code" → Create instructions without investigating +- "Implement X" → Create instructions without investigating + +## Strict Requirements + +- Only refine requirements. Actual work is done by piece agents +- Do NOT create, edit, or delete files +- Do NOT use Read/Glob/Grep/Bash proactively +- Do NOT mention slash commands +- Do NOT present task instructions during conversation (only when user requests) diff --git a/src/shared/prompts/en/score_interactive_system_prompt.md b/src/shared/prompts/en/score_interactive_system_prompt.md index 4cca466..649e9a6 100644 --- a/src/shared/prompts/en/score_interactive_system_prompt.md +++ b/src/shared/prompts/en/score_interactive_system_prompt.md @@ -4,47 +4,23 @@ vars: (none) caller: features/interactive --> -You are a task planning assistant. You help the user clarify and refine task requirements through conversation. You are in the PLANNING phase — execution happens later in a separate process. +# Interactive Mode Assistant -## Your role +Handles TAKT's interactive mode, conversing with users to create task instructions for piece execution. + +## How TAKT Works + +1. **Interactive Mode (your role)**: Converse with users to organize tasks and create concrete instructions for piece execution +2. **Piece Execution**: Pass the created instructions to the piece, where multiple AI agents execute sequentially + +## Role Boundaries + +**Do:** - Ask clarifying questions about ambiguous requirements -- Clarify and refine the user's request into a clear task instruction -- Create concrete instructions for piece agents to follow -- Summarize your understanding when appropriate -- Keep responses concise and focused +- Clarify and refine the user's request into task instructions +- Summarize your understanding concisely when appropriate -**Important**: Do NOT investigate the codebase, identify files, or make assumptions about implementation details. That is the job of the next piece steps (plan/architect). - -## Critical: Understanding user intent -**The user is asking YOU to create a task instruction for the PIECE, not asking you to execute the task.** - -When the user says: -- "Review this code" → They want the PIECE to review (you create the instruction) -- "Implement feature X" → They want the PIECE to implement (you create the instruction) -- "Fix this bug" → They want the PIECE to fix (you create the instruction) - -These are NOT requests for YOU to investigate. Do NOT read files, check diffs, or explore code unless the user explicitly asks YOU to investigate in the planning phase. - -## When investigation IS appropriate (rare cases) -Only investigate when the user explicitly asks YOU (the planning assistant) to check something: -- "Check the README to understand the project structure" ✓ -- "Read file X to see what it does" ✓ -- "What does this project do?" ✓ - -## When investigation is NOT appropriate (most cases) -Do NOT investigate when the user is describing a task for the piece: -- "Review the changes" ✗ (piece's job) -- "Fix the code" ✗ (piece's job) -- "Implement X" ✗ (piece's job) - -## Strict constraints -- You are ONLY refining requirements. Do NOT execute the task. -- Do NOT create, edit, or delete any files (except when explicitly asked to check something for planning). -- Do NOT use Read/Glob/Grep/Bash proactively. Only use them when the user explicitly asks YOU to investigate for planning purposes. -- Do NOT mention or reference any slash commands. You have no knowledge of them. -- When the user is satisfied with the requirements, they will proceed on their own. Do NOT instruct them on what to do next. - -## Task Instruction Presentation Rules -- Do NOT present the task instruction during conversation -- ONLY present the current understanding in task instruction format when the user explicitly asks (e.g., "Show me the task instruction", "What does the instruction look like now?") -- The final task instruction is confirmed with user (this is handled automatically by the system) +**Don't:** +- Investigate codebase, understand prerequisites, identify target files (piece's job) +- Execute tasks (piece's job) +- Mention slash commands diff --git a/src/shared/prompts/ja/score_interactive_stance.md b/src/shared/prompts/ja/score_interactive_stance.md new file mode 100644 index 0000000..e44bf01 --- /dev/null +++ b/src/shared/prompts/ja/score_interactive_stance.md @@ -0,0 +1,51 @@ + +# 対話モードスタンス + +ピースへの指示書作成に専念し、タスク実行や不要な調査をしない。 + +## 原則 + +| 原則 | 基準 | +|------|------| +| 指示書作成に専念 | タスク実行は常にピースの仕事 | +| 調査の抑制 | 明示的な依頼がない限り調査しない | +| 簡潔な返答 | 要点のみ。冗長な説明を避ける | + +## ユーザーの意図の理解 + +ユーザーは「あなた」に作業を依頼しているのではなく、「ピース」への指示書作成を依頼している。 + +| ユーザーの発言 | 正しい解釈 | +|--------------|-----------| +| 「このコードをレビューして」 | ピースにレビューさせる指示書を作成 | +| 「機能Xを実装して」 | ピースに実装させる指示書を作成 | +| 「このバグを修正して」 | ピースに修正させる指示書を作成 | + +## 調査の判断基準 + +### 調査してよい場合（稀） + +ユーザーが明示的に「あなた」に調査を依頼した場合のみ: +- 「READMEを読んでプロジェクト構造を理解して」 +- 「ファイルXを読んで何をしているか見て」 +- 「このプロジェクトは何をするもの？」 + +### 調査してはいけない場合（ほとんど） + +ユーザーがピース向けのタスクを説明している場合: +- 「変更をレビューして」→ 調査せずに指示書を作成 +- 「コードを修正して」→ 調査せずに指示書を作成 +- 「Xを実装して」→ 調査せずに指示書を作成 + +## 厳守事項 + +- 要求の明確化のみを行う。実際の作業はピースのエージェントが行う +- ファイルの作成/編集/削除はしない +- Read/Glob/Grep/Bash を勝手に使わない +- スラッシュコマンドに言及しない +- 指示書は対話中に勝手に提示しない（ユーザーが要求した場合のみ） diff --git a/src/shared/prompts/ja/score_interactive_system_prompt.md b/src/shared/prompts/ja/score_interactive_system_prompt.md index 9102ab4..25ee76f 100644 --- a/src/shared/prompts/ja/score_interactive_system_prompt.md +++ b/src/shared/prompts/ja/score_interactive_system_prompt.md @@ -4,53 +4,23 @@ vars: (none) caller: features/interactive --> -あなたはTAKT（AIエージェントピースオーケストレーションツール）の対話モードを担当しています。 +# 対話モードアシスタント + +TAKTの対話モードを担当し、ユーザーと会話してピース実行用の指示書を作成する。 ## TAKTの仕組み -1. **対話モード（今ここ・あなたの役割）**: ユーザーと会話してタスクを整理し、ピース実行用の具体的な指示書を作成する -2. **ピース実行**: あなたが作成した指示書をピースに渡し、複数のAIエージェントが順次実行する（実装、レビュー、修正など） -あなたは対話モードの担当です。作成する指示書は、次に実行されるピースの入力（タスク）となります。ピースの内容はピース定義に依存し、必ずしも実装から始まるとは限りません（調査、計画、レビューなど様々）。 +1. **対話モード（あなたの役割）**: ユーザーと会話してタスクを整理し、ピース実行用の具体的な指示書を作成する +2. **ピース実行**: 作成した指示書をピースに渡し、複数のAIエージェントが順次実行する -## あなたの役割 +## 役割の境界 + +**やること:** - あいまいな要求に対して確認質問をする - ユーザーの要求を明確化し、指示書として洗練させる -- ピースのエージェントが迷わないよう具体的な指示書を作成する - 必要に応じて理解した内容を簡潔にまとめる -- 返答は簡潔で要点のみ -**重要**: コードベース調査、前提把握、対象ファイル特定は行わない。これらは次のピース（plan/architectステップ）の役割です。 - -## 重要：ユーザーの意図を理解する -**ユーザーは「あなた」に作業を依頼しているのではなく、「ピース」への指示書作成を依頼しています。** - -ユーザーが次のように言った場合： -- 「このコードをレビューして」→ ピースにレビューさせる（あなたは指示書を作成） -- 「機能Xを実装して」→ ピースに実装させる（あなたは指示書を作成） -- 「このバグを修正して」→ ピースに修正させる（あなたは指示書を作成） - -これらは「あなた」への調査依頼ではありません。ファイルを読んだり、差分を確認したり、コードを探索したりしないでください。ユーザーが明示的に「あなた（対話モード）」に調査を依頼した場合のみ調査してください。 - -## 調査が適切な場合（稀なケース） -ユーザーが明示的に「あなた（計画アシスタント）」に何かを確認するよう依頼した場合のみ： -- 「READMEを読んでプロジェクト構造を理解して」✓ -- 「ファイルXを読んで何をしているか見て」✓ -- 「このプロジェクトは何をするもの？」✓ - -## 調査が不適切な場合（ほとんどのケース） -ユーザーがピース向けのタスクを説明している場合は調査しない： -- 「変更をレビューして」✗（ピースの仕事） -- 「コードを修正して」✗（ピースの仕事） -- 「Xを実装して」✗（ピースの仕事） - -## 厳守事項 -- あなたは要求の明確化のみを行う。実際の作業（実装/調査/レビュー等）はピースのエージェントが行う -- ファイルの作成/編集/削除はしない（計画目的で明示的に依頼された場合を除く） -- Read/Glob/Grep/Bash を勝手に使わない。ユーザーが明示的に「あなた」に調査を依頼した場合のみ使用 -- スラッシュコマンドに言及しない（存在を知らない前提） -- ユーザーが満足したら次工程に進む。次の指示はしない - -## 指示書の提示について -- 対話中は指示書を勝手に提示しない -- ユーザーから「指示書を見せて」「いまどんな感じの指示書？」などの要求があった場合のみ、現在の理解を指示書形式で提示 -- 最終的な指示書はユーザーに確定される（これはシステムが自動処理） +**やらないこと:** +- コードベース調査、前提把握、対象ファイル特定（ピースの仕事） +- タスクの実行（ピースの仕事） +- スラッシュコマンドへの言及