From e19656f30864d6acf8bcbf7f76f3f6981a4be5ef Mon Sep 17 00:00:00 2001 From: neil_tsai Date: Thu, 7 May 2026 18:06:03 +0800 Subject: [PATCH 01/13] =?UTF-8?q?feat:=20=E6=96=B0=E5=A2=9E=20implementati?= =?UTF-8?q?on-orchestrator=20v1=EF=BC=88=E5=BE=85=E5=AF=A6=E9=A9=97?= =?UTF-8?q?=E8=AA=BF=E6=95=B4=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../implementation-orchestrator/SKILL.md | 393 ++++++++++++++++++ 1 file changed, 393 insertions(+) create mode 100644 .agents/skills/implementation-orchestrator/SKILL.md diff --git a/.agents/skills/implementation-orchestrator/SKILL.md b/.agents/skills/implementation-orchestrator/SKILL.md new file mode 100644 index 0000000..7df9714 --- /dev/null +++ b/.agents/skills/implementation-orchestrator/SKILL.md @@ -0,0 +1,393 @@ +--- +name: implementation-orchestrator +description: orchestrate engineering implementation work from context collection and implementation planning through human review gates, task decomposition, execution brief generation, QA verification, and final delivery artifacts. use when the user asks to plan or coordinate a software implementation task, convert a Jira/GitHub/MR request into an executable plan, split complex engineering work into low-coupling subtasks, prepare prompts for coding agents, verify implementation completeness, or generate final MR descriptions and Jira comments as end-of-work artifacts. +--- + +# Implementation Orchestrator + +## Overview + +Use this skill to turn an engineering implementation request into a controlled, reviewable, and deliverable workflow. Prioritize high-quality context, explicit human review gates, low-coupling task decomposition, execution-ready briefs, and QA verification before producing final MR or Jira artifacts. + +This skill is responsible for planning and coordinating engineering implementation workflows. When multiple coding agents or executors are available, produce low-coupling execution briefs that can be delegated independently. When only a single assistant or executor is available, follow the same workflow sequentially and verify each step before moving on. + +## Core Principles + +* Treat MR descriptions and Jira comments as final byproducts, not as the main workflow. +* Do not start implementation before producing a context pack and an implementation plan. +* Keep human review gates explicit. Non-trivial tasks should pause for user confirmation after context collection, after the initial implementation plan, and after QA verification. +* Prefer fewer, clearer artifacts over many loosely related notes. +* Keep task decomposition low-coupling. Each subtask should have explicit inputs, expected outputs, ownership boundaries, and validation criteria. +* Update the implementation plan whenever new information invalidates earlier assumptions. +* Make uncertainty visible. Track open questions, assumptions, and risks separately. +* For complex work, define QA criteria before execution begins, not only after implementation ends. + +## Workflow + +### 1. Intake + +Collect the task objective and all available source material. + +Look for: + +* User request or Jira issue summary +* Business or product intent +* Current behavior and expected behavior +* Relevant repositories, branches, files, logs, docs, tickets, existing MRs, or screenshots +* Known constraints, deadlines, compatibility requirements, rollout expectations, and testing expectations +* User preferences regarding models, tools, or execution style + +If important context is missing but the workflow can still continue, record the gap as an open question instead of immediately blocking the workflow. + +### 2. Context Pack + +The first primary artifact is `context.md`. + +Default structure: + +```markdown +# Context Pack + +## Objective +[What this task is trying to achieve] + +## Background +[Relevant product, technical, or ticket background] + +## Current State +[Current implementation or behavior; include relevant files/modules/docs when available] + +## Desired State +[Expected outcome or behavior] + +## Relevant Sources +- [Source/file/doc/ticket]: [Why it matters] + +## Constraints +- [Technical/product/process constraints] + +## Assumptions +- [Current reasonable assumptions and rationale] + +## Open Questions +- [Question, impact if unresolved, suggested default behavior] + +## Initial Risks +- [Risk and possible mitigation] +``` + +Human review gate: for non-trivial work, ask the user to confirm or revise the context pack before finalizing the implementation plan. + +### 3. Implementation Plan Draft + +Once the context pack is sufficiently clear, produce `implementation-plan.md`. + +Default structure: + +```markdown +# Implementation Plan + +## Goal +[Concise implementation goal] + +## Non-goals +[Explicitly out-of-scope areas] + +## Proposed Approach +[Primary approach and rationale] + +## Alternatives Considered +- [Alternative]: [Reason not selected] + +## Impacted Areas +- [Module/service/file/API/data/test/docs] + +## Step-by-step Plan +1. [Action] +2. [Action] +3. [Action] + +## Data / API / Contract Changes +[If applicable] + +## Rollout / Migration Plan +[If applicable] + +## Testing Strategy +- Unit: +- Integration: +- E2E/manual: +- Regression: + +## QA Criteria +- [Conditions required for completion] + +## Risks and Mitigations +- [Risk]: [Mitigation] + +## Open Questions +- [Question and suggested default] + +## Plan Version Log +- v1: Initial draft +``` + +Human review gate: ask the user to approve, reject, or revise the implementation plan before generating execution briefs. + +### 4. Complexity Routing + +Classify task complexity after the implementation plan draft. + +Use this rubric: + +| Complexity | Indicators | Execution Route | +| ---------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | +| Low | Single module or narrow scoped change; no schema/API contract changes; limited test surface; low rollback risk | Single executor brief with focused QA checklist | +| Medium | Crosses 2-3 modules; requires test updates; impacts configuration, shared utilities, or API behavior | Split into a small number of sequenced subtasks with dependency notes | +| High | Cross-service/system changes; schema or migration work; security/performance risk; uncertain requirements; broad regression surface | Decompose into low-coupling workstreams, generate multiple execution briefs, require QA consolidation | + +If the classification is uncertain, choose the higher complexity route and explain why. + +### 5. Task Breakdown + +For medium or high complexity work, produce `task-breakdown.md`. + +Default structure: + +```markdown +# Task Breakdown + +## Complexity Classification +[Low / Medium / High and rationale] + +## Workstreams + +### Workstream 1: [Name] +**Purpose:** [Why this workstream exists] +**Inputs:** [Required context/files/contracts] +**Expected Outputs:** [Concrete deliverables] +**Dependencies:** [None or specific dependencies] +**Boundaries:** [What this workstream must not modify] +**Validation:** [How to verify completion] + +### Workstream 2: [Name] +... + +## Integration Sequence +1. [Merge/integration order] + +## Coordination Risks +- [Risk and mitigation] +``` + +Split workstreams by responsibility boundary, dependency boundary, or validation boundary instead of arbitrary file count. + +### 6. Execution Briefs + +Produce `execution-briefs.md` for executor models, coding agents, or human engineers. + +Low complexity work should generate one brief. Medium or high complexity work should generate one brief per workstream. + +Each brief should contain: + +```markdown +# Execution Brief: [Name] + +## Role +You are responsible only for the scoped task below. Do not expand scope without explicit approval. + +## Context +[Condensed context required for this executor] + +## Task +[Specific implementation task] + +## Files / Areas to Inspect +- [File/module/path] + +## Required Changes +- [Concrete required changes] + +## Boundaries +- Do not modify [out-of-scope area] +- Preserve [behavior/API/compatibility] + +## Validation +- [Tests/checks to execute] + +## Expected Output +- [Code changes, notes, test results, unresolved issues] + +## Handoff Notes +[What the executor must report back] +``` + +Execution briefs should avoid unrelated context. Keep them executable and tightly scoped. + +### 7. QA Verification + +Produce `qa-checklist.md` before or alongside execution, then update it after implementation evidence is available. + +Low complexity tasks may be verified by the same assistant after implementation. High complexity tasks should include a dedicated QA consolidation step. + +Default structure: + +```markdown +# QA Checklist + +## Acceptance Criteria +- [Acceptance criterion] + +## Implementation Verification +- [ ] Required files/modules changed as planned +- [ ] No out-of-scope changes introduced +- [ ] Edge cases handled +- [ ] Error states handled +- [ ] Backward compatibility considered + +## Test Verification +- [ ] Unit tests added/updated +- [ ] Integration tests added/updated where needed +- [ ] Existing relevant tests pass +- [ ] Manual checks documented where automated tests are unavailable + +## Risk Review +- [ ] Security/privacy impact reviewed +- [ ] Performance impact reviewed +- [ ] Migration/rollback path reviewed where applicable + +## Evidence +- Commands run: +- Test results: +- Screenshots/logs/links: + +## QA Decision +[Pass / Pass with follow-ups / Blocked] + +## Remaining Follow-ups +- [Follow-up item] +``` + +### 8. Final Verification + +After execution and QA evidence are available, produce `final-verification.md`. + +Default structure: + +```markdown +# Final Verification + +## Summary +[What was completed] + +## Plan Deviations +[Differences from the approved plan and why] + +## Verification Evidence +- [Test/check/evidence] + +## Known Limitations +- [Known limitations, if any] + +## Follow-up Tasks +- [Follow-up tasks, optionally with owners] + +## Ready for Delivery +[Yes / No, with rationale] +``` + +Human review gate: for tasks with meaningful scope or risk, ask the user to confirm the final verification before producing polished MR/Jira artifacts. + +### 9. Final Delivery Artifacts + +Only after final verification should the following byproducts be generated. + +#### `mr-description.md` + +```markdown +# Summary +- [Summary of changes] + +# Implementation Notes +- [Important technical decisions] + +# Testing +- [Executed tests/checks] + +# Risk / Impact +- [Risk level and impacted areas] + +# Related Jira +- [Ticket link/key if available] + +# Follow-ups +- [Follow-up items if any] +``` + +#### `jira-comment.md` + +```markdown +Completed: +- [Completed items] + +Verification: +- [Tests/checks performed] + +Impact Scope: +- [Affected modules/behaviors] + +Risks / Notes: +- [Known risks or none] + +Follow-ups: +- [Items requiring follow-up] +``` + +Jira comments should stay concise and status-oriented. Do not paste the full implementation plan into Jira unless explicitly requested. + +## Plan Update Rules + +When new information appears: + +1. Identify which artifact is affected. +2. Update the plan version log. +3. Explain what changed and why. +4. Preserve earlier decisions only if they are still valid. +5. Regenerate dependent artifacts when necessary. + +Use this plan version pattern: + +```markdown +## Plan Version Log +- v1: Initial draft based on [context] +- v2: Updated after user confirmation to [change] +- v3: Updated after implementation discovery: [change] +``` + +## Human Review Gate Prompts + +Use direct review prompts such as: + +```text +Please confirm whether this context pack is correct, especially the Objective, Desired State, Constraints, and Open Questions. Once confirmed, I will generate the implementation plan. +``` + +```text +Please confirm whether this implementation plan can be used as the execution baseline. Once approved, I will perform complexity routing and generate execution briefs and a QA checklist. +``` + +```text +Please confirm the final verification results. Once confirmed, I will generate the MR description and Jira comment. +``` + +## Quality Bar + +Before considering orchestration complete, verify that: + +* The context pack explains why the task exists and what success means. +* The implementation plan is specific enough to execute. +* Complexity routing has clear justification. +* Workstreams are low-coupling when decomposition is used. +* Execution briefs are tightly scoped and include validation instructions. +* The QA checklist maps back to acceptance criteria. +* Final MR/Jira artifacts are derived from verified facts, not assumptions. From 3186955de2cfa1e083618795b5ac090cf90655fa Mon Sep 17 00:00:00 2001 From: cdcd72 Date: Thu, 7 May 2026 22:53:18 +0800 Subject: [PATCH 02/13] =?UTF-8?q?feat(implementation-orchestrator):=20?= =?UTF-8?q?=E6=9B=B4=E6=96=B0=E6=8A=80=E8=83=BD=E6=96=87=E6=AA=94=E4=BB=A5?= =?UTF-8?q?=E5=A2=9E=E5=BC=B7=E5=AF=A6=E6=96=BD=E8=A8=88=E5=8A=83=E7=9A=84?= =?UTF-8?q?=E6=B8=85=E6=99=B0=E5=BA=A6=E5=92=8C=E5=8F=AF=E5=9F=B7=E8=A1=8C?= =?UTF-8?q?=E6=80=A7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../implementation-orchestrator/SKILL.md | 280 +++++++++++++++--- 1 file changed, 243 insertions(+), 37 deletions(-) diff --git a/.agents/skills/implementation-orchestrator/SKILL.md b/.agents/skills/implementation-orchestrator/SKILL.md index 7df9714..d128ebe 100644 --- a/.agents/skills/implementation-orchestrator/SKILL.md +++ b/.agents/skills/implementation-orchestrator/SKILL.md @@ -7,20 +7,30 @@ description: orchestrate engineering implementation work from context collection ## Overview -Use this skill to turn an engineering implementation request into a controlled, reviewable, and deliverable workflow. Prioritize high-quality context, explicit human review gates, low-coupling task decomposition, execution-ready briefs, and QA verification before producing final MR or Jira artifacts. +Use this skill to turn user-provided engineering context into a controlled, reviewable implementation plan. Prioritize understanding the available context, defining a feasible plan, decomposing the work into low-coupling implementation tasks, and preparing execution-ready briefs for coding agents or human executors. -This skill is responsible for planning and coordinating engineering implementation workflows. When multiple coding agents or executors are available, produce low-coupling execution briefs that can be delegated independently. When only a single assistant or executor is available, follow the same workflow sequentially and verify each step before moving on. +This skill owns the planning and coordination flow. It may produce execution briefs for delegated implementation work, but delegation applies to implementation workstreams, not to the skill's orchestration responsibilities. After the delegated implementation tasks are reported as complete, use this skill to consolidate the results, verify them against the approved plan and QA criteria, and then produce final MR/Jira artifacts when needed. ## Core Principles -* Treat MR descriptions and Jira comments as final byproducts, not as the main workflow. -* Do not start implementation before producing a context pack and an implementation plan. -* Keep human review gates explicit. Non-trivial tasks should pause for user confirmation after context collection, after the initial implementation plan, and after QA verification. -* Prefer fewer, clearer artifacts over many loosely related notes. -* Keep task decomposition low-coupling. Each subtask should have explicit inputs, expected outputs, ownership boundaries, and validation criteria. -* Update the implementation plan whenever new information invalidates earlier assumptions. -* Make uncertainty visible. Track open questions, assumptions, and risks separately. -* For complex work, define QA criteria before execution begins, not only after implementation ends. +- Treat the implementation plan as the primary output of the planning phase. +- Treat MR descriptions and Jira comments as final byproducts, not as the main workflow. +- Do not generate execution briefs before producing a context pack and an implementation plan. +- Keep human review gates explicit. Non-trivial tasks should pause for user confirmation after context collection, after the initial implementation plan, and after QA verification. +- Prefer fewer, clearer artifacts over many loosely related notes. +- Keep delegated implementation tasks low-coupling. Each task should have explicit inputs, expected outputs, ownership boundaries, and validation criteria. +- Delegate implementation work only after the plan has been reviewed or is sufficiently clear to execute. +- For low-complexity tasks, the assistant may execute implementation directly only when it has direct access to the required codebase, editing tools, and validation commands. +- For medium or high complexity tasks, or when direct implementation access is unavailable, stop after producing execution briefs and wait for the user, human executor, or coding agent to provide implementation results. +- Enter the verification phase only after implementation tasks have been reported as complete or implementation evidence is available. +- Update the implementation plan whenever new information invalidates earlier assumptions. +- Make uncertainty visible. Track open questions, assumptions, and risks separately. + +## Output Language Rule + +Generate workflow artifacts in the user's requested language. If no output language is specified, use the language of the user's task description. Keep artifact filenames such as `context.md`, `implementation-plan.md`, `task-breakdown.md`, `execution-briefs.md`, `qa-checklist.md`, and `final-verification.md` in English unless the user explicitly requests localized filenames. + +Prefer keeping technical section headings in English for consistency across coding agents and review artifacts, while writing the section content in the selected output language. If the user asks for fully localized documents, localize both headings and content. ## Workflow @@ -30,14 +40,14 @@ Collect the task objective and all available source material. Look for: -* User request or Jira issue summary -* Business or product intent -* Current behavior and expected behavior -* Relevant repositories, branches, files, logs, docs, tickets, existing MRs, or screenshots -* Known constraints, deadlines, compatibility requirements, rollout expectations, and testing expectations -* User preferences regarding models, tools, or execution style +- User request or Jira issue summary +- Business or product intent +- Current behavior and expected behavior +- Relevant repositories, branches, files, logs, docs, tickets, existing MRs, or screenshots +- Known constraints, deadlines, compatibility requirements, rollout expectations, and testing expectations +- User preferences regarding models, tools, or execution style -If important context is missing but the workflow can still continue, record the gap as an open question instead of immediately blocking the workflow. +If the core objective and expected outcome are clear enough to draft a plan, but some non-blocking details are missing, record those gaps as open questions with suggested defaults instead of blocking the workflow. If the objective, expected outcome, or success criteria are unclear, ask the user for clarification before planning. ### 2. Context Pack @@ -49,30 +59,39 @@ Default structure: # Context Pack ## Objective + [What this task is trying to achieve] ## Background + [Relevant product, technical, or ticket background] ## Current State + [Current implementation or behavior; include relevant files/modules/docs when available] ## Desired State + [Expected outcome or behavior] ## Relevant Sources + - [Source/file/doc/ticket]: [Why it matters] ## Constraints + - [Technical/product/process constraints] ## Assumptions + - [Current reasonable assumptions and rationale] ## Open Questions + - [Question, impact if unresolved, suggested default behavior] ## Initial Risks + - [Risk and possible mitigation] ``` @@ -88,65 +107,208 @@ Default structure: # Implementation Plan ## Goal + [Concise implementation goal] ## Non-goals + [Explicitly out-of-scope areas] ## Proposed Approach + [Primary approach and rationale] ## Alternatives Considered + - [Alternative]: [Reason not selected] ## Impacted Areas + - [Module/service/file/API/data/test/docs] ## Step-by-step Plan + 1. [Action] 2. [Action] 3. [Action] ## Data / API / Contract Changes + [If applicable] ## Rollout / Migration Plan + [If applicable] ## Testing Strategy + - Unit: - Integration: - E2E/manual: - Regression: ## QA Criteria + - [Conditions required for completion] ## Risks and Mitigations + - [Risk]: [Mitigation] ## Open Questions + - [Question and suggested default] ## Plan Version Log + - v1: Initial draft ``` Human review gate: ask the user to approve, reject, or revise the implementation plan before generating execution briefs. -### 4. Complexity Routing +### 4. Complexity Assessment and Routing + +After the implementation plan draft is created, assess the task complexity before deciding how to execute it. This step is not only a Low / Medium / High label. It is an execution strategy assessment based on four dimensions: + +```text +Overall Complexity Profile = +Implementation Complexity ++ Coordination Complexity ++ Verification Complexity ++ Requirement Volatility +``` + +Evaluate each dimension separately, then use the resulting profile to decide task decomposition, execution parallelism, verification depth, and human review frequency. + +#### 4.1 Implementation Complexity + +Assess how difficult the actual implementation is. + +Consider: + +- Architecture complexity +- Algorithm or data-flow complexity +- Migration or compatibility requirements +- Performance sensitivity +- Security or privacy sensitivity +- Unfamiliar technologies or fragile legacy code + +Default levels: + +| Level | Indicators | +| ------ | ----------------------------------------------------------------------------------------------------------------- | +| Low | Narrow scoped change, small refactor, simple UI or CRUD adjustment, no contract change | +| Medium | Cross-module business logic, shared utilities, cache/config behavior, moderate compatibility concerns | +| High | Distributed systems, concurrency, event ordering, migration, security-sensitive flows, performance-critical paths | + +#### 4.2 Coordination Complexity + +Assess how difficult it is to coordinate implementation across people, agents, modules, or workstreams. + +Consider: + +- Number of workstreams +- Dependency graph complexity +- Merge conflict risk +- Ownership boundaries +- Shared contracts or APIs +- Integration sequencing + +Default levels: + +| Level | Indicators | +| ------ | ---------------------------------------------------------------------------------------- | +| Low | A single executor can complete the work with minimal coordination | +| Medium | 2-3 workstreams with clear dependencies and manageable integration risk | +| High | Cross-team, cross-service, schema/API coordination, or high parallel implementation risk | + +#### 4.3 Verification Complexity + +Assess how difficult it is to prove the implementation is correct after completion. + +Consider: + +- Regression surface +- Integration or E2E test requirements +- Manual QA burden +- Async or timing-sensitive behavior +- Observability or logging requirements +- Rollback validation +- Production-only failure modes + +Default levels: + +| Level | Indicators | +| ------ | --------------------------------------------------------------------------------------------------------------------------- | +| Low | Unit tests or simple manual checks can verify the change | +| Medium | Integration tests, E2E tests, or coordinated manual QA are needed | +| High | Distributed async behavior, race conditions, production-only risks, broad regression surface, or hard-to-reproduce behavior | + +#### 4.4 Requirement Volatility + +Assess how stable the requirement is. + +Consider: + +- Clarity of objective and expected outcome +- Stability of acceptance criteria +- Unresolved product, UX, or technical decisions +- Exploratory nature of the work +- Likelihood that implementation discoveries will change the plan + +Default levels: -Classify task complexity after the implementation plan draft. +| Level | Indicators | +| ------ | --------------------------------------------------------------------------------------------------- | +| Low | Objective, desired state, and acceptance criteria are clear and stable | +| Medium | Some details are unresolved but suggested defaults are reasonable | +| High | The work is exploratory, acceptance criteria are unclear, or product/technical direction may change | -Use this rubric: +#### 4.5 Complexity Profile Output -| Complexity | Indicators | Execution Route | -| ---------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | -| Low | Single module or narrow scoped change; no schema/API contract changes; limited test surface; low rollback risk | Single executor brief with focused QA checklist | -| Medium | Crosses 2-3 modules; requires test updates; impacts configuration, shared utilities, or API behavior | Split into a small number of sequenced subtasks with dependency notes | -| High | Cross-service/system changes; schema or migration work; security/performance risk; uncertain requirements; broad regression surface | Decompose into low-coupling workstreams, generate multiple execution briefs, require QA consolidation | +Always include the complexity profile and recommended execution strategy in `implementation-plan.md`. -If the classification is uncertain, choose the higher complexity route and explain why. +If `task-breakdown.md` is generated, repeat the approved complexity profile at the beginning of the document as a short reference so the decomposition remains traceable to the routing decision. + +Use this structure: + +```yaml +Complexity Profile: + implementation_complexity: Low | Medium | High + coordination_complexity: Low | Medium | High + verification_complexity: Low | Medium | High + requirement_volatility: Low | Medium | High + +Rationale: + implementation_complexity: [Reason] + coordination_complexity: [Reason] + verification_complexity: [Reason] + requirement_volatility: [Reason] +``` + +#### 4.6 Routing Rules + +Use the profile to decide the execution strategy. + +```yaml +Recommended Execution Strategy: + planning_mode: direct | iterative + task_decomposition: none | light | aggressive + execution_parallelism: none | limited | parallelizable + verification_mode: focused | consolidated | rigorous + human_review_frequency: normal | increased | high +``` + +Apply these routing rules: + +- If all dimensions are Low, use direct planning, no task breakdown, one execution brief, and focused QA. +- If Implementation Complexity is Medium or High, make the implementation plan more explicit before producing execution briefs. +- If Coordination Complexity is Medium or High, create `task-breakdown.md` and define dependencies, boundaries, and integration sequence. +- If Verification Complexity is Medium or High, define QA criteria early and require stronger implementation evidence before final verification. +- If Requirement Volatility is Medium or High, use iterative planning, narrower workstreams, and more frequent human review gates. +- If any dimension is High, explain why the workflow is being made heavier and what risk it reduces. + +Do not use complexity assessment as bureaucracy. Use it to choose the minimum orchestration required to execute safely. ### 5. Task Breakdown @@ -158,11 +320,13 @@ Default structure: # Task Breakdown ## Complexity Classification + [Low / Medium / High and rationale] ## Workstreams ### Workstream 1: [Name] + **Purpose:** [Why this workstream exists] **Inputs:** [Required context/files/contracts] **Expected Outputs:** [Concrete deliverables] @@ -171,12 +335,15 @@ Default structure: **Validation:** [How to verify completion] ### Workstream 2: [Name] + ... ## Integration Sequence + 1. [Merge/integration order] ## Coordination Risks + - [Risk and mitigation] ``` @@ -184,9 +351,11 @@ Split workstreams by responsibility boundary, dependency boundary, or validation ### 6. Execution Briefs -Produce `execution-briefs.md` for executor models, coding agents, or human engineers. +Produce `execution-briefs.md` for coding agents or human executors after the implementation plan has been reviewed or is sufficiently clear to execute. + +Low complexity work should generate one brief. Medium or high complexity work should generate one brief per workstream. These briefs are intended for delegated implementation work; they do not delegate the orchestration flow itself. -Low complexity work should generate one brief. Medium or high complexity work should generate one brief per workstream. +For low-complexity tasks, if the current assistant has direct access to the codebase, editing tools, and validation commands required to safely complete the work, it may execute the task directly using the approved plan and then report implementation evidence. Otherwise, stop after producing execution briefs and wait for completion evidence from the user, human executor, or coding agent before entering QA verification. Each brief should contain: @@ -194,31 +363,40 @@ Each brief should contain: # Execution Brief: [Name] ## Role + You are responsible only for the scoped task below. Do not expand scope without explicit approval. ## Context + [Condensed context required for this executor] ## Task + [Specific implementation task] ## Files / Areas to Inspect + - [File/module/path] ## Required Changes + - [Concrete required changes] ## Boundaries + - Do not modify [out-of-scope area] - Preserve [behavior/API/compatibility] ## Validation + - [Tests/checks to execute] ## Expected Output + - [Code changes, notes, test results, unresolved issues] ## Handoff Notes + [What the executor must report back] ``` @@ -226,9 +404,11 @@ Execution briefs should avoid unrelated context. Keep them executable and tightl ### 7. QA Verification -Produce `qa-checklist.md` before or alongside execution, then update it after implementation evidence is available. +Define `qa-checklist.md` during planning so the execution briefs have clear validation expectations. Do not enter the active verification phase until implementation tasks have been reported as complete or implementation evidence is available. -Low complexity tasks may be verified by the same assistant after implementation. High complexity tasks should include a dedicated QA consolidation step. +Acceptable implementation evidence includes code diffs, commits, MR links, test results, logs, screenshots, implementation summaries, or coding agent handoff notes. + +Low complexity tasks may be verified by the same assistant after implementation. Medium or high complexity tasks should include a QA consolidation step that compares all completed workstreams against the approved plan, task breakdown, and QA criteria. Default structure: @@ -236,9 +416,11 @@ Default structure: # QA Checklist ## Acceptance Criteria + - [Acceptance criterion] ## Implementation Verification + - [ ] Required files/modules changed as planned - [ ] No out-of-scope changes introduced - [ ] Edge cases handled @@ -246,25 +428,30 @@ Default structure: - [ ] Backward compatibility considered ## Test Verification + - [ ] Unit tests added/updated - [ ] Integration tests added/updated where needed - [ ] Existing relevant tests pass - [ ] Manual checks documented where automated tests are unavailable ## Risk Review + - [ ] Security/privacy impact reviewed - [ ] Performance impact reviewed - [ ] Migration/rollback path reviewed where applicable ## Evidence + - Commands run: - Test results: - Screenshots/logs/links: ## QA Decision + [Pass / Pass with follow-ups / Blocked] ## Remaining Follow-ups + - [Follow-up item] ``` @@ -278,21 +465,27 @@ Default structure: # Final Verification ## Summary + [What was completed] ## Plan Deviations + [Differences from the approved plan and why] ## Verification Evidence + - [Test/check/evidence] ## Known Limitations + - [Known limitations, if any] ## Follow-up Tasks + - [Follow-up tasks, optionally with owners] ## Ready for Delivery + [Yes / No, with rationale] ``` @@ -306,21 +499,27 @@ Only after final verification should the following byproducts be generated. ```markdown # Summary + - [Summary of changes] # Implementation Notes + - [Important technical decisions] # Testing + - [Executed tests/checks] # Risk / Impact + - [Risk level and impacted areas] # Related Jira + - [Ticket link/key if available] # Follow-ups + - [Follow-up items if any] ``` @@ -328,18 +527,23 @@ Only after final verification should the following byproducts be generated. ```markdown Completed: + - [Completed items] Verification: + - [Tests/checks performed] Impact Scope: + - [Affected modules/behaviors] Risks / Notes: + - [Known risks or none] Follow-ups: + - [Items requiring follow-up] ``` @@ -359,6 +563,7 @@ Use this plan version pattern: ```markdown ## Plan Version Log + - v1: Initial draft based on [context] - v2: Updated after user confirmation to [change] - v3: Updated after implementation discovery: [change] @@ -384,10 +589,11 @@ Please confirm the final verification results. Once confirmed, I will generate t Before considering orchestration complete, verify that: -* The context pack explains why the task exists and what success means. -* The implementation plan is specific enough to execute. -* Complexity routing has clear justification. -* Workstreams are low-coupling when decomposition is used. -* Execution briefs are tightly scoped and include validation instructions. -* The QA checklist maps back to acceptance criteria. -* Final MR/Jira artifacts are derived from verified facts, not assumptions. +- The context pack explains why the task exists and what success means. +- The implementation plan is specific enough to execute. +- Complexity routing has clear justification. +- Delegated workstreams are low-coupling when decomposition is used. +- Execution briefs are tightly scoped and include validation instructions. +- Verification occurs after implementation completion evidence is available. +- The QA checklist maps back to acceptance criteria. +- Final MR/Jira artifacts are derived from verified facts, not assumptions. From a0abf928a354d06e0737d5799cf940599182975a Mon Sep 17 00:00:00 2001 From: cdcd72 Date: Thu, 7 May 2026 23:29:26 +0800 Subject: [PATCH 03/13] =?UTF-8?q?fix(implementation-orchestrator):=20?= =?UTF-8?q?=E6=9B=B4=E6=96=B0=E6=8A=80=E8=83=BD=E6=96=87=E6=AA=94=E4=BB=A5?= =?UTF-8?q?=E5=8F=8D=E6=98=A0=E6=9B=B4=E6=BA=96=E7=A2=BA=E7=9A=84=E5=AF=A6?= =?UTF-8?q?=E6=96=BD=E8=A8=88=E5=8A=83=E6=8F=8F=E8=BF=B0=E5=92=8C=E4=BA=A4?= =?UTF-8?q?=E4=BB=98=E7=94=A2=E7=89=A9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../implementation-orchestrator/SKILL.md | 28 +++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/.agents/skills/implementation-orchestrator/SKILL.md b/.agents/skills/implementation-orchestrator/SKILL.md index d128ebe..ec48fce 100644 --- a/.agents/skills/implementation-orchestrator/SKILL.md +++ b/.agents/skills/implementation-orchestrator/SKILL.md @@ -1,6 +1,6 @@ --- name: implementation-orchestrator -description: orchestrate engineering implementation work from context collection and implementation planning through human review gates, task decomposition, execution brief generation, QA verification, and final delivery artifacts. use when the user asks to plan or coordinate a software implementation task, convert a Jira/GitHub/MR request into an executable plan, split complex engineering work into low-coupling subtasks, prepare prompts for coding agents, verify implementation completeness, or generate final MR descriptions and Jira comments as end-of-work artifacts. +description: orchestrate engineering implementation planning from user-provided context into reviewable plans, complexity assessment, task breakdowns, execution briefs for coding agents, QA verification, and final delivery artifacts. use when the user wants to turn a software task, tracked issue, review request, bug report, feature request, refactor, or technical change into an implementation plan; split implementation work into delegated coding-agent tasks; or validate completed implementation work before delivery. --- # Implementation Orchestrator @@ -9,12 +9,12 @@ description: orchestrate engineering implementation work from context collection Use this skill to turn user-provided engineering context into a controlled, reviewable implementation plan. Prioritize understanding the available context, defining a feasible plan, decomposing the work into low-coupling implementation tasks, and preparing execution-ready briefs for coding agents or human executors. -This skill owns the planning and coordination flow. It may produce execution briefs for delegated implementation work, but delegation applies to implementation workstreams, not to the skill's orchestration responsibilities. After the delegated implementation tasks are reported as complete, use this skill to consolidate the results, verify them against the approved plan and QA criteria, and then produce final MR/Jira artifacts when needed. +This skill owns the planning and coordination flow. It may produce execution briefs for delegated implementation work, but delegation applies to implementation workstreams, not to the skill's orchestration responsibilities. After the delegated implementation tasks are reported as complete, use this skill to consolidate the results, verify them against the approved plan and QA criteria, and then produce final delivery artifacts when needed. ## Core Principles - Treat the implementation plan as the primary output of the planning phase. -- Treat MR descriptions and Jira comments as final byproducts, not as the main workflow. +- Treat delivery summaries and status-update comments as final byproducts, not as the main workflow. - Do not generate execution briefs before producing a context pack and an implementation plan. - Keep human review gates explicit. Non-trivial tasks should pause for user confirmation after context collection, after the initial implementation plan, and after QA verification. - Prefer fewer, clearer artifacts over many loosely related notes. @@ -40,10 +40,10 @@ Collect the task objective and all available source material. Look for: -- User request or Jira issue summary +- User request, issue, ticket, or task summary - Business or product intent - Current behavior and expected behavior -- Relevant repositories, branches, files, logs, docs, tickets, existing MRs, or screenshots +- Relevant repositories, branches, files, logs, docs, tickets, existing review requests, or screenshots - Known constraints, deadlines, compatibility requirements, rollout expectations, and testing expectations - User preferences regarding models, tools, or execution style @@ -406,7 +406,7 @@ Execution briefs should avoid unrelated context. Keep them executable and tightl Define `qa-checklist.md` during planning so the execution briefs have clear validation expectations. Do not enter the active verification phase until implementation tasks have been reported as complete or implementation evidence is available. -Acceptable implementation evidence includes code diffs, commits, MR links, test results, logs, screenshots, implementation summaries, or coding agent handoff notes. +Acceptable implementation evidence includes code diffs, commits, review links, test results, logs, screenshots, implementation summaries, or coding agent handoff notes. Low complexity tasks may be verified by the same assistant after implementation. Medium or high complexity tasks should include a QA consolidation step that compares all completed workstreams against the approved plan, task breakdown, and QA criteria. @@ -489,13 +489,13 @@ Default structure: [Yes / No, with rationale] ``` -Human review gate: for tasks with meaningful scope or risk, ask the user to confirm the final verification before producing polished MR/Jira artifacts. +Human review gate: for tasks with meaningful scope or risk, ask the user to confirm the final verification before producing polished delivery artifacts. ### 9. Final Delivery Artifacts Only after final verification should the following byproducts be generated. -#### `mr-description.md` +#### `delivery-summary.md` ```markdown # Summary @@ -514,16 +514,16 @@ Only after final verification should the following byproducts be generated. - [Risk level and impacted areas] -# Related Jira +# Related Issue / Ticket -- [Ticket link/key if available] +- [Ticket, issue, or work item link/key if available] # Follow-ups - [Follow-up items if any] ``` -#### `jira-comment.md` +#### `status-update.md` ```markdown Completed: @@ -547,7 +547,7 @@ Follow-ups: - [Items requiring follow-up] ``` -Jira comments should stay concise and status-oriented. Do not paste the full implementation plan into Jira unless explicitly requested. +Status-update comments should stay concise and status-oriented. Do not paste the full implementation plan into the target tracking system unless explicitly requested. ## Plan Update Rules @@ -582,7 +582,7 @@ Please confirm whether this implementation plan can be used as the execution bas ``` ```text -Please confirm the final verification results. Once confirmed, I will generate the MR description and Jira comment. +Please confirm the final verification results. Once confirmed, I will generate the delivery summary and status-update comment. ``` ## Quality Bar @@ -596,4 +596,4 @@ Before considering orchestration complete, verify that: - Execution briefs are tightly scoped and include validation instructions. - Verification occurs after implementation completion evidence is available. - The QA checklist maps back to acceptance criteria. -- Final MR/Jira artifacts are derived from verified facts, not assumptions. +- Final delivery artifacts are derived from verified facts, not assumptions. From 01f31cae053f3ed6b1e8fb364de8108d3bcea01d Mon Sep 17 00:00:00 2001 From: cdcd72 Date: Thu, 7 May 2026 23:46:30 +0800 Subject: [PATCH 04/13] =?UTF-8?q?fix(implementation-orchestrator):=20?= =?UTF-8?q?=E4=BF=AE=E6=AD=A3=E6=8A=80=E8=83=BD=E6=96=87=E6=AA=94=E4=B8=AD?= =?UTF-8?q?=E7=9A=84=E6=8F=8F=E8=BF=B0=E6=A0=BC=E5=BC=8F=E4=BB=A5=E5=A2=9E?= =?UTF-8?q?=E5=BC=B7=E5=8F=AF=E8=AE=80=E6=80=A7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agents/skills/implementation-orchestrator/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/skills/implementation-orchestrator/SKILL.md b/.agents/skills/implementation-orchestrator/SKILL.md index ec48fce..913176f 100644 --- a/.agents/skills/implementation-orchestrator/SKILL.md +++ b/.agents/skills/implementation-orchestrator/SKILL.md @@ -1,6 +1,6 @@ --- name: implementation-orchestrator -description: orchestrate engineering implementation planning from user-provided context into reviewable plans, complexity assessment, task breakdowns, execution briefs for coding agents, QA verification, and final delivery artifacts. use when the user wants to turn a software task, tracked issue, review request, bug report, feature request, refactor, or technical change into an implementation plan; split implementation work into delegated coding-agent tasks; or validate completed implementation work before delivery. +description: Orchestrate engineering implementation planning from user-provided context into reviewable plans, complexity assessment, task breakdowns, execution briefs for coding agents, QA verification, and final delivery artifacts. use when the user wants to turn a software task, tracked issue, review request, bug report, feature request, refactor, or technical change into an implementation plan; split implementation work into delegated coding-agent tasks; or validate completed implementation work before delivery. --- # Implementation Orchestrator From 3fdcd7ce15db4e040d6df3a014fcdcb58290d55a Mon Sep 17 00:00:00 2001 From: cdcd72 Date: Fri, 8 May 2026 00:07:03 +0800 Subject: [PATCH 05/13] =?UTF-8?q?fix(implementation-orchestrator):=20?= =?UTF-8?q?=E6=9B=B4=E6=96=B0=E8=A4=87=E9=9B=9C=E5=BA=A6=E8=A9=95=E4=BC=B0?= =?UTF-8?q?=E6=8F=8F=E8=BF=B0=E4=BB=A5=E5=A2=9E=E5=BC=B7=E6=B8=85=E6=99=B0?= =?UTF-8?q?=E5=BA=A6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../implementation-orchestrator/SKILL.md | 34 ++++++++++--------- 1 file changed, 18 insertions(+), 16 deletions(-) diff --git a/.agents/skills/implementation-orchestrator/SKILL.md b/.agents/skills/implementation-orchestrator/SKILL.md index 913176f..2956714 100644 --- a/.agents/skills/implementation-orchestrator/SKILL.md +++ b/.agents/skills/implementation-orchestrator/SKILL.md @@ -171,11 +171,11 @@ Human review gate: ask the user to approve, reject, or revise the implementation After the implementation plan draft is created, assess the task complexity before deciding how to execute it. This step is not only a Low / Medium / High label. It is an execution strategy assessment based on four dimensions: ```text -Overall Complexity Profile = -Implementation Complexity -+ Coordination Complexity -+ Verification Complexity -+ Requirement Volatility +Overall Complexity Profile consists of: +- Implementation Complexity +- Coordination Complexity +- Verification Complexity +- Requirement Volatility ``` Evaluate each dimension separately, then use the resulting profile to decide task decomposition, execution parallelism, verification depth, and human review frequency. @@ -274,16 +274,18 @@ Use this structure: ```yaml Complexity Profile: - implementation_complexity: Low | Medium | High - coordination_complexity: Low | Medium | High - verification_complexity: Low | Medium | High - requirement_volatility: Low | Medium | High - -Rationale: - implementation_complexity: [Reason] - coordination_complexity: [Reason] - verification_complexity: [Reason] - requirement_volatility: [Reason] + implementation_complexity: + level: Low | Medium | High + rationale: [Reason] + coordination_complexity: + level: Low | Medium | High + rationale: [Reason] + verification_complexity: + level: Low | Medium | High + rationale: [Reason] + requirement_volatility: + level: Low | Medium | High + rationale: [Reason] ``` #### 4.6 Routing Rules @@ -404,7 +406,7 @@ Execution briefs should avoid unrelated context. Keep them executable and tightl ### 7. QA Verification -Define `qa-checklist.md` during planning so the execution briefs have clear validation expectations. Do not enter the active verification phase until implementation tasks have been reported as complete or implementation evidence is available. +Define `qa-checklist.md` during planning based on the QA Criteria in the implementation plan, ensuring execution briefs have clear validation expectations. Do not enter the active verification phase until implementation tasks have been reported as complete or implementation evidence is available. Acceptable implementation evidence includes code diffs, commits, review links, test results, logs, screenshots, implementation summaries, or coding agent handoff notes. From f6c759a6e77a20d9d19a8ac8605a5bbd71fc7348 Mon Sep 17 00:00:00 2001 From: cdcd72 Date: Mon, 18 May 2026 22:24:30 +0800 Subject: [PATCH 06/13] =?UTF-8?q?=E6=9B=B4=E6=96=B0=E6=8F=90=E4=BA=A4?= =?UTF-8?q?=E8=A8=8A=E6=81=AF=E6=A0=BC=E5=BC=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 123.txt | 1 + 1 file changed, 1 insertion(+) create mode 100644 123.txt diff --git a/123.txt b/123.txt new file mode 100644 index 0000000..d800886 --- /dev/null +++ b/123.txt @@ -0,0 +1 @@ +123 \ No newline at end of file From d4e2922f51f710fe437f3c558275674e69673871 Mon Sep 17 00:00:00 2001 From: cdcd72 Date: Mon, 18 May 2026 22:25:23 +0800 Subject: [PATCH 07/13] =?UTF-8?q?Revert=20"=E6=9B=B4=E6=96=B0=E6=8F=90?= =?UTF-8?q?=E4=BA=A4=E8=A8=8A=E6=81=AF=E6=A0=BC=E5=BC=8F"?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This reverts commit f6c759a6e77a20d9d19a8ac8605a5bbd71fc7348. --- 123.txt | 1 - 1 file changed, 1 deletion(-) delete mode 100644 123.txt diff --git a/123.txt b/123.txt deleted file mode 100644 index d800886..0000000 --- a/123.txt +++ /dev/null @@ -1 +0,0 @@ -123 \ No newline at end of file From 0686f5e4a904cf060a6841d70c05b6d4dd0e64d0 Mon Sep 17 00:00:00 2001 From: Neil Date: Mon, 18 May 2026 22:32:28 +0800 Subject: [PATCH 08/13] Modify Overview section in SKILL.md Updated the Overview section to include '1' for clarity. --- .agents/skills/implementation-orchestrator/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/skills/implementation-orchestrator/SKILL.md b/.agents/skills/implementation-orchestrator/SKILL.md index 2956714..0811ce3 100644 --- a/.agents/skills/implementation-orchestrator/SKILL.md +++ b/.agents/skills/implementation-orchestrator/SKILL.md @@ -5,7 +5,7 @@ description: Orchestrate engineering implementation planning from user-provided # Implementation Orchestrator -## Overview +## Overview 1 Use this skill to turn user-provided engineering context into a controlled, reviewable implementation plan. Prioritize understanding the available context, defining a feasible plan, decomposing the work into low-coupling implementation tasks, and preparing execution-ready briefs for coding agents or human executors. From 7c62f918667dc1ae4a0024197f80e5feb96be825 Mon Sep 17 00:00:00 2001 From: cdcd72 Date: Mon, 18 May 2026 22:37:28 +0800 Subject: [PATCH 09/13] Revert "Modify Overview section in SKILL.md" This reverts commit 0686f5e4a904cf060a6841d70c05b6d4dd0e64d0. --- .agents/skills/implementation-orchestrator/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/skills/implementation-orchestrator/SKILL.md b/.agents/skills/implementation-orchestrator/SKILL.md index 0811ce3..2956714 100644 --- a/.agents/skills/implementation-orchestrator/SKILL.md +++ b/.agents/skills/implementation-orchestrator/SKILL.md @@ -5,7 +5,7 @@ description: Orchestrate engineering implementation planning from user-provided # Implementation Orchestrator -## Overview 1 +## Overview Use this skill to turn user-provided engineering context into a controlled, reviewable implementation plan. Prioritize understanding the available context, defining a feasible plan, decomposing the work into low-coupling implementation tasks, and preparing execution-ready briefs for coding agents or human executors. From 42ae386aa58dcf79d28ad68d29bda491430b2f05 Mon Sep 17 00:00:00 2001 From: neil_tsai Date: Fri, 29 May 2026 10:40:31 +0800 Subject: [PATCH 10/13] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E4=BA=A4?= =?UTF-8?q?=E4=BB=98=E6=91=98=E8=A6=81=E5=92=8C=E7=8B=80=E6=85=8B=E6=9B=B4?= =?UTF-8?q?=E6=96=B0=E7=9A=84=E6=8F=8F=E8=BF=B0=E4=BB=A5=E5=A2=9E=E5=BC=B7?= =?UTF-8?q?=E6=B8=85=E6=99=B0=E5=BA=A6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agents/skills/implementation-orchestrator/SKILL.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/.agents/skills/implementation-orchestrator/SKILL.md b/.agents/skills/implementation-orchestrator/SKILL.md index 2956714..9209f97 100644 --- a/.agents/skills/implementation-orchestrator/SKILL.md +++ b/.agents/skills/implementation-orchestrator/SKILL.md @@ -497,6 +497,10 @@ Human review gate: for tasks with meaningful scope or risk, ask the user to conf Only after final verification should the following byproducts be generated. +`delivery-summary.md` is intended to be pasted into a merge request / pull request description. It should be review-oriented and include enough technical context for code reviewers. + +`status-update.md` is intended to be pasted as a Jira / ticket comment. It should be concise, status-oriented, and readable by non-implementation stakeholders. + #### `delivery-summary.md` ```markdown @@ -549,7 +553,7 @@ Follow-ups: - [Items requiring follow-up] ``` -Status-update comments should stay concise and status-oriented. Do not paste the full implementation plan into the target tracking system unless explicitly requested. +Status-update comments should stay concise and status-oriented for Jira / ticket comments. Do not paste the full implementation plan into the target tracking system unless explicitly requested. ## Plan Update Rules From e369e62ff4ffdbb7e40539d6429e6b410850f6ac Mon Sep 17 00:00:00 2001 From: neil_tsai Date: Fri, 29 May 2026 11:05:23 +0800 Subject: [PATCH 11/13] =?UTF-8?q?docs:=20=E5=A2=9E=E5=8A=A0=E4=BA=BA?= =?UTF-8?q?=E9=A1=9E=E5=AF=A9=E6=9F=A5=E9=96=80=E6=AA=BB=E6=94=BF=E7=AD=96?= =?UTF-8?q?=E4=BB=A5=E5=BC=B7=E5=8C=96=E5=B7=A5=E4=BD=9C=E6=B5=81=E7=A8=8B?= =?UTF-8?q?=E6=8E=A7=E5=88=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../implementation-orchestrator/SKILL.md | 75 +++++++++++++++---- 1 file changed, 60 insertions(+), 15 deletions(-) diff --git a/.agents/skills/implementation-orchestrator/SKILL.md b/.agents/skills/implementation-orchestrator/SKILL.md index 9209f97..3772a5e 100644 --- a/.agents/skills/implementation-orchestrator/SKILL.md +++ b/.agents/skills/implementation-orchestrator/SKILL.md @@ -19,13 +19,46 @@ This skill owns the planning and coordination flow. It may produce execution bri - Keep human review gates explicit. Non-trivial tasks should pause for user confirmation after context collection, after the initial implementation plan, and after QA verification. - Prefer fewer, clearer artifacts over many loosely related notes. - Keep delegated implementation tasks low-coupling. Each task should have explicit inputs, expected outputs, ownership boundaries, and validation criteria. -- Delegate implementation work only after the plan has been reviewed or is sufficiently clear to execute. +- Delegate implementation work only after the implementation plan has been explicitly approved, unless the user explicitly asks to skip review gates. - For low-complexity tasks, the assistant may execute implementation directly only when it has direct access to the required codebase, editing tools, and validation commands. - For medium or high complexity tasks, or when direct implementation access is unavailable, stop after producing execution briefs and wait for the user, human executor, or coding agent to provide implementation results. - Enter the verification phase only after implementation tasks have been reported as complete or implementation evidence is available. - Update the implementation plan whenever new information invalidates earlier assumptions. - Make uncertainty visible. Track open questions, assumptions, and risks separately. +## Human Review Gate Policy + +Human review gates are mandatory workflow boundaries. + +When a phase includes a required stop, stop after producing the artifact for that phase and ask the user for explicit confirmation before continuing. + +Do not generate artifacts from later phases in the same response unless the user explicitly asks to skip review gates or requests an end-to-end draft without pauses. + +Acceptable confirmations include: + +- approved +- confirmed +- looks good +- continue +- proceed +- go ahead + +If confirmation is missing, do not continue to the next phase. + +Use direct review prompts such as: + +```text +Please confirm whether this context pack is correct, especially the Objective, Desired State, Constraints, and Open Questions. Once confirmed, I will generate the implementation plan. +``` + +```text +Please confirm whether this implementation plan can be used as the execution baseline. Once approved, I will generate the next required artifacts. +``` + +```text +Please confirm the final verification result. After confirmation, I can generate optional delivery artifacts if needed. +``` + ## Output Language Rule Generate workflow artifacts in the user's requested language. If no output language is specified, use the language of the user's task description. Keep artifact filenames such as `context.md`, `implementation-plan.md`, `task-breakdown.md`, `execution-briefs.md`, `qa-checklist.md`, and `final-verification.md` in English unless the user explicitly requests localized filenames. @@ -95,7 +128,7 @@ Default structure: - [Risk and possible mitigation] ``` -Human review gate: for non-trivial work, ask the user to confirm or revise the context pack before finalizing the implementation plan. +Required stop: after producing `context.md`, ask the user to confirm or revise it. Do not produce `implementation-plan.md` until the user explicitly confirms, unless the user has explicitly asked to skip review gates. ### 3. Implementation Plan Draft @@ -164,7 +197,7 @@ Default structure: - v1: Initial draft ``` -Human review gate: ask the user to approve, reject, or revise the implementation plan before generating execution briefs. +Required stop: after producing `implementation-plan.md`, ask the user to approve, reject, or revise it. Do not produce `task-breakdown.md`, `execution-briefs.md`, or `qa-checklist.md` until the user explicitly confirms, unless the user has explicitly asked to skip review gates. ### 4. Complexity Assessment and Routing @@ -491,18 +524,27 @@ Default structure: [Yes / No, with rationale] ``` -Human review gate: for tasks with meaningful scope or risk, ask the user to confirm the final verification before producing polished delivery artifacts. +Required stop: after producing `final-verification.md`, ask the user to confirm the verification result. Do not produce optional delivery artifacts until the user explicitly requests them. + +After confirmation, ask whether the user wants optional delivery artifacts generated: + +- `delivery-summary.md` +- `status-update.md` +- both +- none; end the workflow -### 9. Final Delivery Artifacts +### 9. Optional Delivery Artifacts -Only after final verification should the following byproducts be generated. +Final delivery artifacts are optional communication byproducts. Generate them only when the user requests delivery-ready materials, or when the user explicitly chooses them after final verification. -`delivery-summary.md` is intended to be pasted into a merge request / pull request description. It should be review-oriented and include enough technical context for code reviewers. +These artifacts are not required for orchestration completion. The workflow may end after `final-verification.md` if no delivery communication is needed. -`status-update.md` is intended to be pasted as a Jira / ticket comment. It should be concise, status-oriented, and readable by non-implementation stakeholders. +Only generate these artifacts from verified facts in `final-verification.md` and available QA evidence. Do not introduce new assumptions. #### `delivery-summary.md` +Intended to be pasted into a merge request / pull request description. It should be review-oriented and include enough technical context for code reviewers. + ```markdown # Summary @@ -531,6 +573,8 @@ Only after final verification should the following byproducts be generated. #### `status-update.md` +Intended to be pasted as a Jira / ticket comment. It should be concise, status-oriented, and readable by non-implementation stakeholders. + ```markdown Completed: @@ -557,12 +601,12 @@ Status-update comments should stay concise and status-oriented for Jira / ticket ## Plan Update Rules -When new information appears: +When new information invalidates earlier assumptions or changes the execution path: 1. Identify which artifact is affected. -2. Update the plan version log. -3. Explain what changed and why. -4. Preserve earlier decisions only if they are still valid. +2. Update the relevant artifact instead of silently continuing with stale assumptions. +3. Add or update the plan version log when `implementation-plan.md` changes. +4. Explain what changed and why. 5. Regenerate dependent artifacts when necessary. Use this plan version pattern: @@ -571,7 +615,7 @@ Use this plan version pattern: ## Plan Version Log - v1: Initial draft based on [context] -- v2: Updated after user confirmation to [change] +- v2: Updated after user confirmation: [change] - v3: Updated after implementation discovery: [change] ``` @@ -600,6 +644,7 @@ Before considering orchestration complete, verify that: - Complexity routing has clear justification. - Delegated workstreams are low-coupling when decomposition is used. - Execution briefs are tightly scoped and include validation instructions. -- Verification occurs after implementation completion evidence is available. +- Verification occurs only after implementation evidence is available. - The QA checklist maps back to acceptance criteria. -- Final delivery artifacts are derived from verified facts, not assumptions. +- `final-verification.md` clearly states whether the work is ready for delivery. +- Optional delivery artifacts are generated only from verified facts, not assumptions. From 6ca017568b28b9c3644284c5cfadd1766e3db8a5 Mon Sep 17 00:00:00 2001 From: neil_tsai Date: Fri, 29 May 2026 12:19:15 +0800 Subject: [PATCH 12/13] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E5=AF=A6?= =?UTF-8?q?=E6=96=BD=E5=8D=94=E8=AA=BF=E5=99=A8=E7=9A=84=E6=8F=8F=E8=BF=B0?= =?UTF-8?q?=E4=BB=A5=E5=A2=9E=E5=BC=B7=E6=B8=85=E6=99=B0=E5=BA=A6=E5=92=8C?= =?UTF-8?q?=E5=8F=AF=E8=AE=80=E6=80=A7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../implementation-orchestrator/SKILL.md | 349 +++++++----------- 1 file changed, 128 insertions(+), 221 deletions(-) diff --git a/.agents/skills/implementation-orchestrator/SKILL.md b/.agents/skills/implementation-orchestrator/SKILL.md index 3772a5e..89d9041 100644 --- a/.agents/skills/implementation-orchestrator/SKILL.md +++ b/.agents/skills/implementation-orchestrator/SKILL.md @@ -1,38 +1,39 @@ --- name: implementation-orchestrator -description: Orchestrate engineering implementation planning from user-provided context into reviewable plans, complexity assessment, task breakdowns, execution briefs for coding agents, QA verification, and final delivery artifacts. use when the user wants to turn a software task, tracked issue, review request, bug report, feature request, refactor, or technical change into an implementation plan; split implementation work into delegated coding-agent tasks; or validate completed implementation work before delivery. +description: Turn engineering work into a reviewed execution baseline with a context pack, implementation plan, complexity routing, optional workstream breakdowns, execution briefs for coding agents or human executors, QA verification, and optional delivery updates. Use when the user wants to turn a bug, feature, refactor, review request, or technical task into an implementation plan, coordinate work across coding agents or human executors, or verify completed implementation against the approved plan. --- # Implementation Orchestrator -## Overview +Use this skill to convert engineering context into a controlled implementation workflow. The skill owns planning, routing, QA consolidation, and final verification. It may create execution briefs for coding agents or human executors, but it does not delegate its orchestration responsibilities. -Use this skill to turn user-provided engineering context into a controlled, reviewable implementation plan. Prioritize understanding the available context, defining a feasible plan, decomposing the work into low-coupling implementation tasks, and preparing execution-ready briefs for coding agents or human executors. +## At a Glance -This skill owns the planning and coordination flow. It may produce execution briefs for delegated implementation work, but delegation applies to implementation workstreams, not to the skill's orchestration responsibilities. After the delegated implementation tasks are reported as complete, use this skill to consolidate the results, verify them against the approved plan and QA criteria, and then produce final delivery artifacts when needed. +1. Gather context and produce `context.md`. +2. Stop for confirmation unless the user explicitly asks to skip review gates. +3. Produce `implementation-plan.md`, including complexity routing. +4. Stop for plan approval unless the user explicitly asks to skip review gates. +5. Always produce `execution-briefs.md` after plan approval, using `task-breakdown.md` when decomposition is required. +6. Implement directly or delegate according to the approved routing and execution briefs. +7. Verify completed work with `qa-checklist.md` and `final-verification.md`. +8. Ask whether optional delivery artifacts are needed. -## Core Principles +## Operating Rules -- Treat the implementation plan as the primary output of the planning phase. -- Treat delivery summaries and status-update comments as final byproducts, not as the main workflow. -- Do not generate execution briefs before producing a context pack and an implementation plan. -- Keep human review gates explicit. Non-trivial tasks should pause for user confirmation after context collection, after the initial implementation plan, and after QA verification. -- Prefer fewer, clearer artifacts over many loosely related notes. -- Keep delegated implementation tasks low-coupling. Each task should have explicit inputs, expected outputs, ownership boundaries, and validation criteria. -- Delegate implementation work only after the implementation plan has been explicitly approved, unless the user explicitly asks to skip review gates. -- For low-complexity tasks, the assistant may execute implementation directly only when it has direct access to the required codebase, editing tools, and validation commands. -- For medium or high complexity tasks, or when direct implementation access is unavailable, stop after producing execution briefs and wait for the user, human executor, or coding agent to provide implementation results. -- Enter the verification phase only after implementation tasks have been reported as complete or implementation evidence is available. -- Update the implementation plan whenever new information invalidates earlier assumptions. -- Make uncertainty visible. Track open questions, assumptions, and risks separately. +- Treat `implementation-plan.md` as the execution baseline. +- Treat the complexity profile and recommended execution strategy as part of `implementation-plan.md`, not as a later-phase artifact. +- Keep human review gates explicit unless the user clearly asks to skip them. +- Prefer the lightest workflow that safely covers implementation risk, coordination risk, and verification risk. +- Always create `execution-briefs.md` after plan approval. +- Create `task-breakdown.md` only when routing calls for decomposition, and use it as the source for workstream-level execution briefs. +- Do not enter active verification until implementation evidence is available. +- Treat `delivery-summary.md` and `status-update.md` as optional byproducts, not mandatory workflow outputs. +- Update the plan when new information invalidates earlier assumptions, and regenerate dependent artifacts when needed. +- Keep uncertainty visible through assumptions, open questions, risks, and plan deviations. -## Human Review Gate Policy +## Review Gates -Human review gates are mandatory workflow boundaries. - -When a phase includes a required stop, stop after producing the artifact for that phase and ask the user for explicit confirmation before continuing. - -Do not generate artifacts from later phases in the same response unless the user explicitly asks to skip review gates or requests an end-to-end draft without pauses. +Human review gates are mandatory workflow boundaries unless the user explicitly asks to skip them or requests an end-to-end draft without pauses. Acceptable confirmations include: @@ -43,44 +44,46 @@ Acceptable confirmations include: - proceed - go ahead -If confirmation is missing, do not continue to the next phase. +If confirmation is missing, stop at the current gate. -Use direct review prompts such as: +Use these prompts when pausing: ```text Please confirm whether this context pack is correct, especially the Objective, Desired State, Constraints, and Open Questions. Once confirmed, I will generate the implementation plan. ``` ```text -Please confirm whether this implementation plan can be used as the execution baseline. Once approved, I will generate the next required artifacts. +Please confirm whether this implementation plan can be used as the execution baseline. Once approved, I will generate the execution artifacts required by the approved routing. ``` ```text -Please confirm the final verification result. After confirmation, I can generate optional delivery artifacts if needed. +Please confirm the final verification result. Once confirmed, I will ask whether you want optional delivery artifacts. ``` -## Output Language Rule +## Output Language -Generate workflow artifacts in the user's requested language. If no output language is specified, use the language of the user's task description. Keep artifact filenames such as `context.md`, `implementation-plan.md`, `task-breakdown.md`, `execution-briefs.md`, `qa-checklist.md`, and `final-verification.md` in English unless the user explicitly requests localized filenames. +Generate workflow artifacts in the user's requested language. If no output language is specified, use the language of the user's task description. -Prefer keeping technical section headings in English for consistency across coding agents and review artifacts, while writing the section content in the selected output language. If the user asks for fully localized documents, localize both headings and content. +Keep artifact filenames such as `context.md`, `implementation-plan.md`, `task-breakdown.md`, `execution-briefs.md`, `qa-checklist.md`, and `final-verification.md` in English unless the user explicitly requests localized filenames. + +Prefer keeping technical section headings in English for consistency across coding agents and review artifacts. If the user asks for fully localized documents, localize both headings and content. ## Workflow ### 1. Intake -Collect the task objective and all available source material. +Collect enough context to define the objective, desired outcome, and success criteria. Look for: -- User request, issue, ticket, or task summary -- Business or product intent -- Current behavior and expected behavior -- Relevant repositories, branches, files, logs, docs, tickets, existing review requests, or screenshots -- Known constraints, deadlines, compatibility requirements, rollout expectations, and testing expectations -- User preferences regarding models, tools, or execution style +- user request, issue, ticket, or task summary +- business or product intent +- current behavior and expected behavior +- relevant repositories, branches, files, logs, docs, tickets, review requests, or screenshots +- known constraints, deadlines, compatibility requirements, rollout expectations, and testing expectations +- user preferences about tools, models, or execution style -If the core objective and expected outcome are clear enough to draft a plan, but some non-blocking details are missing, record those gaps as open questions with suggested defaults instead of blocking the workflow. If the objective, expected outcome, or success criteria are unclear, ask the user for clarification before planning. +If the objective and desired outcome are mostly clear, capture non-blocking gaps as open questions with suggested defaults. If the objective, expected outcome, or success criteria remain unclear, ask for clarification before planning. ### 2. Context Pack @@ -128,12 +131,14 @@ Default structure: - [Risk and possible mitigation] ``` -Required stop: after producing `context.md`, ask the user to confirm or revise it. Do not produce `implementation-plan.md` until the user explicitly confirms, unless the user has explicitly asked to skip review gates. +Required stop: after producing `context.md`, ask the user to confirm or revise it. Do not produce `implementation-plan.md` until the user explicitly confirms, unless the user explicitly asks to skip review gates. -### 3. Implementation Plan Draft +### 3. Implementation Plan Once the context pack is sufficiently clear, produce `implementation-plan.md`. +This artifact must include both the plan itself and the complexity routing that determines how execution should proceed. + Default structure: ```markdown @@ -192,171 +197,83 @@ Default structure: - [Question and suggested default] -## Plan Version Log - -- v1: Initial draft -``` +## Complexity Profile -Required stop: after producing `implementation-plan.md`, ask the user to approve, reject, or revise it. Do not produce `task-breakdown.md`, `execution-briefs.md`, or `qa-checklist.md` until the user explicitly confirms, unless the user has explicitly asked to skip review gates. +Complexity Profile: +implementation_complexity: +level: Low | Medium | High +rationale: [Reason] +coordination_complexity: +level: Low | Medium | High +rationale: [Reason] +verification_complexity: +level: Low | Medium | High +rationale: [Reason] +requirement_volatility: +level: Low | Medium | High +rationale: [Reason] + +## Recommended Execution Strategy -### 4. Complexity Assessment and Routing +Recommended Execution Strategy: +planning_mode: direct | iterative +task_decomposition: none | light | aggressive +execution_mode: direct | delegated +execution_parallelism: none | limited | parallelizable +verification_mode: focused | consolidated | rigorous +human_review_frequency: normal | increased | high -After the implementation plan draft is created, assess the task complexity before deciding how to execute it. This step is not only a Low / Medium / High label. It is an execution strategy assessment based on four dimensions: +## Plan Version Log -```text -Overall Complexity Profile consists of: -- Implementation Complexity -- Coordination Complexity -- Verification Complexity -- Requirement Volatility +- v1: Initial draft ``` -Evaluate each dimension separately, then use the resulting profile to decide task decomposition, execution parallelism, verification depth, and human review frequency. - -#### 4.1 Implementation Complexity - -Assess how difficult the actual implementation is. - -Consider: - -- Architecture complexity -- Algorithm or data-flow complexity -- Migration or compatibility requirements -- Performance sensitivity -- Security or privacy sensitivity -- Unfamiliar technologies or fragile legacy code - -Default levels: - -| Level | Indicators | -| ------ | ----------------------------------------------------------------------------------------------------------------- | -| Low | Narrow scoped change, small refactor, simple UI or CRUD adjustment, no contract change | -| Medium | Cross-module business logic, shared utilities, cache/config behavior, moderate compatibility concerns | -| High | Distributed systems, concurrency, event ordering, migration, security-sensitive flows, performance-critical paths | - -#### 4.2 Coordination Complexity - -Assess how difficult it is to coordinate implementation across people, agents, modules, or workstreams. - -Consider: - -- Number of workstreams -- Dependency graph complexity -- Merge conflict risk -- Ownership boundaries -- Shared contracts or APIs -- Integration sequencing - -Default levels: - -| Level | Indicators | -| ------ | ---------------------------------------------------------------------------------------- | -| Low | A single executor can complete the work with minimal coordination | -| Medium | 2-3 workstreams with clear dependencies and manageable integration risk | -| High | Cross-team, cross-service, schema/API coordination, or high parallel implementation risk | - -#### 4.3 Verification Complexity - -Assess how difficult it is to prove the implementation is correct after completion. - -Consider: - -- Regression surface -- Integration or E2E test requirements -- Manual QA burden -- Async or timing-sensitive behavior -- Observability or logging requirements -- Rollback validation -- Production-only failure modes +Required stop: after producing `implementation-plan.md`, ask the user to approve, reject, or revise it. Do not produce `task-breakdown.md`, `execution-briefs.md`, or `qa-checklist.md` until the user explicitly confirms, unless the user explicitly asks to skip review gates. -Default levels: +### 4. Complexity Routing Guidance -| Level | Indicators | -| ------ | --------------------------------------------------------------------------------------------------------------------------- | -| Low | Unit tests or simple manual checks can verify the change | -| Medium | Integration tests, E2E tests, or coordinated manual QA are needed | -| High | Distributed async behavior, race conditions, production-only risks, broad regression surface, or hard-to-reproduce behavior | +Assess four dimensions and include the result in `implementation-plan.md`. -#### 4.4 Requirement Volatility +#### Implementation Complexity -Assess how stable the requirement is. +Use Low for narrow, low-risk changes with limited compatibility impact. Use Medium for cross-module logic, shared utilities, or moderate compatibility concerns. Use High for migrations, distributed behavior, concurrency, security-sensitive flows, or performance-critical paths. -Consider: +#### Coordination Complexity -- Clarity of objective and expected outcome -- Stability of acceptance criteria -- Unresolved product, UX, or technical decisions -- Exploratory nature of the work -- Likelihood that implementation discoveries will change the plan +Use Low when a single executor can complete the work. Use Medium for 2-3 coordinated workstreams with manageable dependencies. Use High for cross-team, cross-service, or shared-contract changes with meaningful integration sequencing risk. -Default levels: +#### Verification Complexity -| Level | Indicators | -| ------ | --------------------------------------------------------------------------------------------------- | -| Low | Objective, desired state, and acceptance criteria are clear and stable | -| Medium | Some details are unresolved but suggested defaults are reasonable | -| High | The work is exploratory, acceptance criteria are unclear, or product/technical direction may change | +Use Low when unit tests or simple manual checks can verify the change. Use Medium when integration tests, E2E coverage, or coordinated manual QA are needed. Use High when the regression surface is broad, timing-sensitive, production-sensitive, or difficult to reproduce locally. -#### 4.5 Complexity Profile Output +#### Requirement Volatility -Always include the complexity profile and recommended execution strategy in `implementation-plan.md`. - -If `task-breakdown.md` is generated, repeat the approved complexity profile at the beginning of the document as a short reference so the decomposition remains traceable to the routing decision. - -Use this structure: - -```yaml -Complexity Profile: - implementation_complexity: - level: Low | Medium | High - rationale: [Reason] - coordination_complexity: - level: Low | Medium | High - rationale: [Reason] - verification_complexity: - level: Low | Medium | High - rationale: [Reason] - requirement_volatility: - level: Low | Medium | High - rationale: [Reason] -``` - -#### 4.6 Routing Rules - -Use the profile to decide the execution strategy. - -```yaml -Recommended Execution Strategy: - planning_mode: direct | iterative - task_decomposition: none | light | aggressive - execution_parallelism: none | limited | parallelizable - verification_mode: focused | consolidated | rigorous - human_review_frequency: normal | increased | high -``` +Use Low when the objective and acceptance criteria are stable. Use Medium when some details remain unresolved but reasonable defaults exist. Use High when the work is exploratory or likely to change based on implementation discovery. Apply these routing rules: -- If all dimensions are Low, use direct planning, no task breakdown, one execution brief, and focused QA. -- If Implementation Complexity is Medium or High, make the implementation plan more explicit before producing execution briefs. -- If Coordination Complexity is Medium or High, create `task-breakdown.md` and define dependencies, boundaries, and integration sequence. -- If Verification Complexity is Medium or High, define QA criteria early and require stronger implementation evidence before final verification. -- If Requirement Volatility is Medium or High, use iterative planning, narrower workstreams, and more frequent human review gates. -- If any dimension is High, explain why the workflow is being made heavier and what risk it reduces. - -Do not use complexity assessment as bureaucracy. Use it to choose the minimum orchestration required to execute safely. +- If all dimensions are Low, prefer direct planning, no task breakdown, direct or single-threaded execution, and focused QA. +- If `implementation_complexity` is Medium or High, make the implementation steps and acceptance criteria more explicit before execution. +- If `coordination_complexity` is Medium or High, create `task-breakdown.md` and define dependencies, boundaries, and integration sequence before writing workstream-level execution briefs. +- If `coordination_complexity` is Low, skip `task-breakdown.md` and derive a single execution brief directly from `implementation-plan.md`. +- If `verification_complexity` is Medium or High, strengthen QA criteria early and require stronger implementation evidence before final verification. +- If `requirement_volatility` is Medium or High, use iterative planning and more frequent review gates. +- If any dimension is High, explain why the heavier workflow is necessary and what risk it reduces. ### 5. Task Breakdown -For medium or high complexity work, produce `task-breakdown.md`. +Produce `task-breakdown.md` when the approved routing calls for decomposition, especially when coordination complexity is Medium or High. + +This artifact is optional, but when it exists it becomes the source document for workstream-level execution briefs. Default structure: ```markdown # Task Breakdown -## Complexity Classification +## Complexity Profile Reference -[Low / Medium / High and rationale] +[Short restatement of the approved complexity profile] ## Workstreams @@ -382,15 +299,19 @@ Default structure: - [Risk and mitigation] ``` -Split workstreams by responsibility boundary, dependency boundary, or validation boundary instead of arbitrary file count. +Split workstreams by responsibility boundary, dependency boundary, or validation boundary rather than by file count alone. ### 6. Execution Briefs -Produce `execution-briefs.md` for coding agents or human executors after the implementation plan has been reviewed or is sufficiently clear to execute. +Always produce `execution-briefs.md` after the implementation plan is approved. -Low complexity work should generate one brief. Medium or high complexity work should generate one brief per workstream. These briefs are intended for delegated implementation work; they do not delegate the orchestration flow itself. +If `task-breakdown.md` is not needed, create a single execution brief derived directly from `implementation-plan.md`. -For low-complexity tasks, if the current assistant has direct access to the codebase, editing tools, and validation commands required to safely complete the work, it may execute the task directly using the approved plan and then report implementation evidence. Otherwise, stop after producing execution briefs and wait for completion evidence from the user, human executor, or coding agent before entering QA verification. +If `task-breakdown.md` exists, create one execution brief per workstream and keep each brief aligned with the approved dependencies, boundaries, and validation steps. + +If the approved routing supports `execution_mode: direct`, the brief may be addressed to the active agent and used to guide direct implementation. + +If the approved routing supports `execution_mode: delegated`, address the brief or briefs to the coding agents or human executors responsible for each scoped task. Each brief should contain: @@ -435,15 +356,15 @@ You are responsible only for the scoped task below. Do not expand scope without [What the executor must report back] ``` -Execution briefs should avoid unrelated context. Keep them executable and tightly scoped. +Execution briefs should avoid unrelated context, remain tightly scoped, and map cleanly back to either the implementation plan or the task breakdown. -### 7. QA Verification +### 7. QA Checklist -Define `qa-checklist.md` during planning based on the QA Criteria in the implementation plan, ensuring execution briefs have clear validation expectations. Do not enter the active verification phase until implementation tasks have been reported as complete or implementation evidence is available. +This artifact defines the verification requirements and evidence expectations for implementation and final verification. It is not the verification result itself. -Acceptable implementation evidence includes code diffs, commits, review links, test results, logs, screenshots, implementation summaries, or coding agent handoff notes. +Produce `qa-checklist.md` after plan approval, based on the approved QA criteria and routing. Use it to define what evidence is required before final verification. -Low complexity tasks may be verified by the same assistant after implementation. Medium or high complexity tasks should include a QA consolidation step that compares all completed workstreams against the approved plan, task breakdown, and QA criteria. +Acceptable implementation evidence includes code diffs, commits, review links, test results, logs, screenshots, implementation summaries, or coding agent handoff notes. Default structure: @@ -490,9 +411,11 @@ Default structure: - [Follow-up item] ``` +Do not enter active verification until implementation evidence is available. + ### 8. Final Verification -After execution and QA evidence are available, produce `final-verification.md`. +After implementation and QA evidence are available, produce `final-verification.md`. Default structure: @@ -524,9 +447,9 @@ Default structure: [Yes / No, with rationale] ``` -Required stop: after producing `final-verification.md`, ask the user to confirm the verification result. Do not produce optional delivery artifacts until the user explicitly requests them. +Required stop: after producing `final-verification.md`, ask the user to confirm the verification result. Do not generate delivery artifacts until the user explicitly chooses them. -After confirmation, ask whether the user wants optional delivery artifacts generated: +After confirmation, ask whether the user wants: - `delivery-summary.md` - `status-update.md` @@ -535,15 +458,15 @@ After confirmation, ask whether the user wants optional delivery artifacts gener ### 9. Optional Delivery Artifacts -Final delivery artifacts are optional communication byproducts. Generate them only when the user requests delivery-ready materials, or when the user explicitly chooses them after final verification. +Final delivery artifacts are optional communication byproducts. Generate them only when the user explicitly requests them after final verification, or when the user asked for delivery-ready materials earlier and the verification result is confirmed. These artifacts are not required for orchestration completion. The workflow may end after `final-verification.md` if no delivery communication is needed. -Only generate these artifacts from verified facts in `final-verification.md` and available QA evidence. Do not introduce new assumptions. +Generate them only from verified facts in `final-verification.md` and available QA evidence. Do not introduce new assumptions. #### `delivery-summary.md` -Intended to be pasted into a merge request / pull request description. It should be review-oriented and include enough technical context for code reviewers. +Use this for merge request or pull request descriptions. ```markdown # Summary @@ -573,7 +496,7 @@ Intended to be pasted into a merge request / pull request description. It should #### `status-update.md` -Intended to be pasted as a Jira / ticket comment. It should be concise, status-oriented, and readable by non-implementation stakeholders. +Use this for issue tracker or ticket comments. ```markdown Completed: @@ -597,19 +520,19 @@ Follow-ups: - [Items requiring follow-up] ``` -Status-update comments should stay concise and status-oriented for Jira / ticket comments. Do not paste the full implementation plan into the target tracking system unless explicitly requested. +Keep status updates concise and status-oriented. Do not paste the full implementation plan unless explicitly requested. ## Plan Update Rules When new information invalidates earlier assumptions or changes the execution path: 1. Identify which artifact is affected. -2. Update the relevant artifact instead of silently continuing with stale assumptions. -3. Add or update the plan version log when `implementation-plan.md` changes. +2. Update that artifact instead of silently continuing with stale assumptions. +3. Add or update the version log when `implementation-plan.md` changes. 4. Explain what changed and why. 5. Regenerate dependent artifacts when necessary. -Use this plan version pattern: +Use this pattern: ```markdown ## Plan Version Log @@ -619,32 +542,16 @@ Use this plan version pattern: - v3: Updated after implementation discovery: [change] ``` -## Human Review Gate Prompts - -Use direct review prompts such as: - -```text -Please confirm whether this context pack is correct, especially the Objective, Desired State, Constraints, and Open Questions. Once confirmed, I will generate the implementation plan. -``` - -```text -Please confirm whether this implementation plan can be used as the execution baseline. Once approved, I will perform complexity routing and generate execution briefs and a QA checklist. -``` - -```text -Please confirm the final verification results. Once confirmed, I will generate the delivery summary and status-update comment. -``` - ## Quality Bar Before considering orchestration complete, verify that: -- The context pack explains why the task exists and what success means. -- The implementation plan is specific enough to execute. -- Complexity routing has clear justification. -- Delegated workstreams are low-coupling when decomposition is used. -- Execution briefs are tightly scoped and include validation instructions. -- Verification occurs only after implementation evidence is available. -- The QA checklist maps back to acceptance criteria. -- `final-verification.md` clearly states whether the work is ready for delivery. -- Optional delivery artifacts are generated only from verified facts, not assumptions. +- the context pack explains why the task exists and what success means +- the implementation plan is specific enough to execute +- the complexity profile and routing are justified and consistent with the approved plan +- delegated workstreams are low-coupling when decomposition is used +- execution briefs are always produced, are tightly scoped, and include validation instructions +- verification occurs only after implementation evidence is available +- the QA checklist maps back to acceptance criteria +- `final-verification.md` clearly states whether the work is ready for delivery +- optional delivery artifacts are generated only from verified facts, not assumptions From 24dd77b09a4427fdc6f02a1932e1dd81b21ccef5 Mon Sep 17 00:00:00 2001 From: neil_tsai Date: Fri, 29 May 2026 15:45:15 +0800 Subject: [PATCH 13/13] =?UTF-8?q?docs:=20=E8=AA=BF=E6=95=B4=20Complexity?= =?UTF-8?q?=20Profile=20=E5=92=8C=20Recommended=20Execution=20Strategy=20?= =?UTF-8?q?=E7=9A=84=E6=A0=BC=E5=BC=8F=E7=82=BA=20YAML=EF=BC=8C=E4=BB=A5?= =?UTF-8?q?=E6=8F=90=E5=8D=87=E5=8F=AF=E8=AE=80=E6=80=A7=E5=92=8C=E7=B5=90?= =?UTF-8?q?=E6=A7=8B=E5=8C=96=E8=A1=A8=E9=81=94=E3=80=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../implementation-orchestrator/SKILL.md | 44 ++++++++++--------- 1 file changed, 24 insertions(+), 20 deletions(-) diff --git a/.agents/skills/implementation-orchestrator/SKILL.md b/.agents/skills/implementation-orchestrator/SKILL.md index 89d9041..dc5497c 100644 --- a/.agents/skills/implementation-orchestrator/SKILL.md +++ b/.agents/skills/implementation-orchestrator/SKILL.md @@ -141,7 +141,7 @@ This artifact must include both the plan itself and the complexity routing that Default structure: -```markdown +````markdown # Implementation Plan ## Goal @@ -199,34 +199,38 @@ Default structure: ## Complexity Profile +```yaml Complexity Profile: -implementation_complexity: -level: Low | Medium | High -rationale: [Reason] -coordination_complexity: -level: Low | Medium | High -rationale: [Reason] -verification_complexity: -level: Low | Medium | High -rationale: [Reason] -requirement_volatility: -level: Low | Medium | High -rationale: [Reason] + implementation_complexity: + level: Low | Medium | High + rationale: [Reason] + coordination_complexity: + level: Low | Medium | High + rationale: [Reason] + verification_complexity: + level: Low | Medium | High + rationale: [Reason] + requirement_volatility: + level: Low | Medium | High + rationale: [Reason] +``` ## Recommended Execution Strategy +```yaml Recommended Execution Strategy: -planning_mode: direct | iterative -task_decomposition: none | light | aggressive -execution_mode: direct | delegated -execution_parallelism: none | limited | parallelizable -verification_mode: focused | consolidated | rigorous -human_review_frequency: normal | increased | high + planning_mode: direct | iterative + task_decomposition: none | light | aggressive + execution_mode: direct | delegated + execution_parallelism: none | limited | parallelizable + verification_mode: focused | consolidated | rigorous + human_review_frequency: normal | increased | high +``` ## Plan Version Log - v1: Initial draft -``` +```` Required stop: after producing `implementation-plan.md`, ask the user to approve, reject, or revise it. Do not produce `task-breakdown.md`, `execution-briefs.md`, or `qa-checklist.md` until the user explicitly confirms, unless the user explicitly asks to skip review gates.