executing-jira-task

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Executing Jira Task

执行Jira任务

Purpose

用途

Execute exactly ONE task from the task plan through a structured pipeline of specialist subagents. Each subagent handles a specific concern (planning, testing, refactoring, implementation, documentation, code quality, architecture, security, requirements verification), keeping the orchestrator's context clean for coordination and decision-making.

The pipeline ensures tasks are completed with proper planning, test coverage, clean code practices, sound architecture, verified security, and confirmed requirements before moving on.

通过专业子Agent组成的结构化流水线，仅执行任务计划中的一个任务。每个子Agent负责特定的模块（规划、测试、重构、实现、文档编写、代码质量、架构、安全、需求验证），让编排器的上下文保持清晰，便于协调和决策。

该流水线可确保任务在进入下一阶段前，完成合理规划、测试覆盖、整洁代码实践、合理架构设计、安全验证以及需求确认。

Platform Compatibility

平台兼容性

This skill works across multiple AI coding tools. Each platform uses a different syntax for dispatching subagents:

Platform	Dispatch syntax
Claude Code CLI	`agent <subagent-name> "<prompt>"` — native subagent via Agent tool
Cursor IDE	Place `.md` files in `.cursor/agents/` or `@` -mention the subagent
OpenCode CLI	Subagents invoked via Task tool or `@` -mention in messages

All three platforms support the Agent Skills open standard (SKILL.md format). The subagent files are self-contained markdown — each platform discovers and dispatches them using its own native mechanism.

For Claude Code, place subagent

.md

files in

.claude/agents/

(or reference them from the skill's

subagents/

directory). For Cursor, place them in

.cursor/agents/

(Cursor also reads from

.claude/agents/

for compatibility). For OpenCode, place them in

.opencode/agents/

or define them in

opencode.json

If your platform does not support native subagent dispatch, read the subagent file and execute its instructions directly, keeping the subagent's output contract intact so downstream steps can consume it.

本技能可在多个AI编码工具上运行，不同平台调用子Agent的语法不同：

平台	调用语法
Claude Code CLI	`agent <subagent-name> "<prompt>"` — 基于Agent工具的原生子Agent调用
Cursor IDE	将 `.md` 文件放入 `.cursor/agents/` 目录，或通过 `@` 提及子Agent
OpenCode CLI	通过任务工具调用子Agent，或在消息中通过 `@` 提及子Agent

以上三个平台都支持Agent技能开放标准（SKILL.md格式）。子Agent文件是自包含的markdown文件，各平台会通过自身原生机制发现并调用它们。

对于Claude Code，将子Agent的

.md

文件放入

.claude/agents/

目录（或从技能的

subagents/

目录引用）。对于Cursor，将文件放入

.cursor/agents/

目录（Cursor为了兼容也会读取

.claude/agents/

目录的内容）。对于OpenCode，将文件放入

.opencode/agents/

目录，或在

opencode.json

中定义。

如果你的平台不支持原生子Agent调用，可以直接读取子Agent文件并执行其指令，保留子Agent的输出约定，以便下游步骤可以正常消费输出内容。

Inputs

输入项

Input	Source	Required	Example
`TICKET_KEY`	User / `$ARGUMENTS`	Yes	`JNS-6065`
`TASK_NUMBER`	User / `$ARGUMENTS`	Yes	`3`

Both the ticket snapshot (

docs/<TICKET_KEY>.md

) and the task plan (

docs/<TICKET_KEY>-tasks.md

) must exist. If either is missing, tell the user which prerequisite skill to run.

输入项	来源	是否必填	示例
`TICKET_KEY`	用户 / `$ARGUMENTS`	是	`JNS-6065`
`TASK_NUMBER`	用户 / `$ARGUMENTS`	是	`3`

工单快照（

docs/<TICKET_KEY>.md

）和任务计划（

docs/<TICKET_KEY>-tasks.md

）都必须存在。如果任意文件缺失，告知用户需要先运行对应的前置技能。

Input contract (produced by upstream skills)

输入约定（由上游技能生成）

The task plan file

docs/<TICKET_KEY>-tasks.md

must contain these sections, built up across the preceding phases:

Required section / element	Produced by	Used in step	Why
`## Task <N>:` with all 8 subsections	planning-jira-tasks	Step 1 (load)	Source content for the execution brief
`## Dependency Graph`	planning-jira-tasks	Step 1 (pre-flight)	Validates dependencies are satisfied
`## Decisions Log`	clarifying-assumptions	Step 3 (brief)	Resolved decisions folded into execution context
Per-task `Questions to answer` resolved	clarifying-assumptions	Step 1 (pre-flight)	Pre-flight checks all questions are answered
`## Jira Subtasks` table with keys	creating-jira-subtasks	Step 13b (Jira)	Maps task number to Jira subtask key for status
`Jira Subtask: <KEY>` in each task section	creating-jira-subtasks	Step 13b (Jira)	Identifies which Jira issue to transition
`Status:` on previously completed tasks	executing-jira-task (self)	Step 1 (pre-flight)	Checks whether dependencies are marked complete

Pre-flight gate: If the

## Jira Subtasks

table is missing, subtasks were not created in Jira. Warn the user and ask whether to proceed without Jira integration or run the creating-jira-subtasks skill first. This is a warning, not a hard block — execution can proceed without Jira tracking.

任务计划文件

docs/<TICKET_KEY>-tasks.md

必须包含以下部分，由前面的阶段逐步生成：

所需章节/元素	生成方	使用步骤	用途
包含全部8个子章节的 `## 任务 <N>:`	planning-jira-tasks	步骤1（加载）	执行概要的源内容
`## 依赖图`	planning-jira-tasks	步骤1（预检）	验证依赖已满足
`## 决策日志`	clarifying-assumptions	步骤3（概要）	已解决的决策会纳入执行上下文
每个任务的 `待回答问题` 已解决	clarifying-assumptions	步骤1（预检）	预检确认所有问题都已回答
包含key的 `## Jira子任务` 表格	creating-jira-subtasks	步骤13b（Jira）	映射任务编号到Jira子任务key用于同步状态
每个任务章节中的 `Jira Subtask: <KEY>`	creating-jira-subtasks	步骤13b（Jira）	识别要流转状态的Jira工单
已完成任务的 `状态:` 标记	executing-jira-task（自身）	步骤1（预检）	检查依赖是否标记为已完成

预检关卡： 如果缺失

## Jira子任务

表格，说明还没有在Jira中创建子任务。警告用户并询问是无需Jira集成直接继续，还是先运行creating-jira-subtasks技能。这只是警告，不是强制阻塞——可以不使用Jira跟踪直接执行。

Subagent Registry

子Agent注册表

Subagent	Path	Purpose
`execution-prepper`	`./subagents/execution-prepper.md`	Pre-execution: validates task, sets up branch, transitions Jira to In Progress, assembles execution brief
`execution-planner`	`./subagents/execution-planner.md`	Analyzes the task, inspects the codebase, and produces an execution plan with skills
`test-strategist`	`./subagents/test-strategist.md`	Defines behaviour-driven tests based on business requirements, not implementation
`refactoring-advisor`	`./subagents/refactoring-advisor.md`	Evaluates whether existing code needs refactoring before or during task execution
`task-executor`	`./subagents/task-executor.md`	Performs the actual implementation work based on the execution brief — cautious by design
`documentation-writer`	`./subagents/documentation-writer.md`	Documents codebase changes, commits all work, and handles post-execution tracking (plan updates, Jira transitions)
`clean-code-reviewer`	`./subagents/clean-code-reviewer.md`	Reviews for Clean Code, SOLID principles; validates recency via context7
`architecture-reviewer`	`./subagents/architecture-reviewer.md`	Reviews for DDD and functional programming principles; validates recency via context7
`security-auditor`	`./subagents/security-auditor.md`	Audits for security vulnerabilities, credential leaks, and insecure patterns
`requirements-verifier`	`./subagents/requirements-verifier.md`	Pre-gate coverage check — confirms all requirements are met before quality gates run

Before delegating, read the subagent file to understand its contract (expected input format, output format, and rules). The path is relative to this skill's directory.

子Agent	路径	用途
`execution-prepper`	`./subagents/execution-prepper.md`	执行前准备：验证任务、创建分支、将Jira状态流转为进行中、组装执行概要
`execution-planner`	`./subagents/execution-planner.md`	分析任务、检视代码库、生成包含所需技能的执行计划
`test-strategist`	`./subagents/test-strategist.md`	基于业务需求定义行为驱动测试，而非基于实现细节
`refactoring-advisor`	`./subagents/refactoring-advisor.md`	评估任务执行前或执行过程中现有代码是否需要重构
`task-executor`	`./subagents/task-executor.md`	基于执行概要完成实际的实现工作，设计上偏向谨慎
`documentation-writer`	`./subagents/documentation-writer.md`	记录代码库变更、提交所有工作、处理执行后跟踪（计划更新、Jira状态流转）
`clean-code-reviewer`	`./subagents/clean-code-reviewer.md`	评审整洁代码、SOLID原则合规性；通过context7验证内容时效性
`architecture-reviewer`	`./subagents/architecture-reviewer.md`	评审DDD和函数式编程原则合规性；通过context7验证内容时效性
`security-auditor`	`./subagents/security-auditor.md`	审计安全漏洞、凭证泄露、不安全编码模式
`requirements-verifier`	`./subagents/requirements-verifier.md`	前置覆盖检查——在质量门禁运行前确认所有需求都已满足

在委派任务前，请先阅读子Agent文件了解其约定（预期输入格式、输出格式和规则）。路径是相对于本技能目录的相对路径。

Skill Dependencies

技能依赖

All subagents depend on external skills that must be installed before execution. These are validated by the orchestrator's

preflight-checker

before execution begins AND by each subagent at runtime (defense-in-depth).

If any skill is missing, the subagent will STOP immediately and report the missing skill to the orchestrator. The orchestrator will then prompt the user to install the skill and re-dispatch the subagent from the beginning. There is no fallback behavior — all skills are required.

Subagent	Depends on	Level	Install command
`execution-planner`	`/find-skills`	Required	`skills install vercel-labs/skills/find-skills`
`execution-planner`	`/writing-plans`	Required	`skills install obra/superpowers/writing-plans`
`test-strategist`	`/writing-plans`	Required	`skills install obra/superpowers/writing-plans`
`test-strategist`	`/test-driven-development`	Required	`skills install obra/superpowers/test-driven-development`
`test-strategist`	`/vitest`	Required	`skills install antfu/skills/vitest`
`refactoring-advisor`	`/writing-plans`	Required	`skills install obra/superpowers/writing-plans`
`task-executor`	`/executing-plans`	Required	`skills install obra/superpowers/executing-plans`
`documentation-writer`	`/commit-work`	Required	`skills install softaworks/agent-toolkit/commit-work`
`documentation-writer`	`/humanizer`	Required	`skills install blader/humanizer`
`clean-code-reviewer`	`/clean-code`	Required	`skills install sickn33/antigravity-awesome-skills/clean-code`
`architecture-reviewer`	`/architecture-patterns`	Required	`skills install wshobson/agents/architecture-patterns`
`security-auditor`	`/api-security-best-practices`	Required	`skills install sickn33/antigravity-awesome-skills/api-security-best-practices`
Quality gates (all 3)	`context7` MCP	Required	Connect context7 MCP in your IDE/CLI settings

所有子Agent都依赖外部技能，必须在执行前安装完成。编排器的

preflight-checker

会在执行开始前验证依赖，且每个子Agent在运行时也会再次验证（深度防御）。

如果缺失任意技能，子Agent会立即停止并向编排器报告缺失的技能。编排器会提示用户安装该技能，然后从头重新调用子Agent。没有降级行为——所有技能都是必填项。

子Agent	依赖技能	依赖级别	安装命令
`execution-planner`	`/find-skills`	必须	`skills install vercel-labs/skills/find-skills`
`execution-planner`	`/writing-plans`	必须	`skills install obra/superpowers/writing-plans`
`test-strategist`	`/writing-plans`	必须	`skills install obra/superpowers/writing-plans`
`test-strategist`	`/test-driven-development`	必须	`skills install obra/superpowers/test-driven-development`
`test-strategist`	`/vitest`	必须	`skills install antfu/skills/vitest`
`refactoring-advisor`	`/writing-plans`	必须	`skills install obra/superpowers/writing-plans`
`task-executor`	`/executing-plans`	必须	`skills install obra/superpowers/executing-plans`
`documentation-writer`	`/commit-work`	必须	`skills install softaworks/agent-toolkit/commit-work`
`documentation-writer`	`/humanizer`	必须	`skills install blader/humanizer`
`clean-code-reviewer`	`/clean-code`	必须	`skills install sickn33/antigravity-awesome-skills/clean-code`
`architecture-reviewer`	`/architecture-patterns`	必须	`skills install wshobson/agents/architecture-patterns`
`security-auditor`	`/api-security-best-practices`	必须	`skills install sickn33/antigravity-awesome-skills/api-security-best-practices`
全部3个质量门禁	`context7` MCP	必须	在你的IDE/CLI设置中连接context7 MCP

Output

输出

Implemented code / configuration changes for the specified task.
Tests covering business requirements.
Documentation for all changes.
Atomic commits for all changes (via /commit-work skill).
Updated task plan with execution status.
Jira subtask transitioned (if Jira MCP available and subtask keys present).

指定任务的已实现代码/配置变更
覆盖业务需求的测试
所有变更的文档
所有变更的原子提交（通过/commit-work技能实现）
带有执行状态的更新后任务计划
Jira子任务状态流转（如果Jira MCP可用且存在子任务key）

Output contract (consumed by orchestrator and self)

输出约定（供编排器和自身消费）

After this skill completes for a given task, the plan file must contain these updates:

Addition	Consumed by	Why
`Status: ✅ Complete (<date>)` on task	orchestrator, self	Orchestrator tracks progress; self checks deps
`Implementation summary:` on task	orchestrator	Progress file gets a concise summary
`Files changed:` list on task	orchestrator	Progress reporting
`## Jira Subtasks` table status updated to Done	orchestrator	Reflects current state

本技能完成指定任务的执行后，计划文件必须包含以下更新：

新增内容	消费方	用途
任务上的 `状态: ✅ 已完成（<日期>）`	编排器、本技能	编排器跟踪进度；本技能检查依赖
任务上的 `实现摘要:`	编排器	进度文件的精简摘要
任务上的 `变更文件:` 列表	编排器	进度上报
`## Jira子任务` 表格状态更新为已完成	编排器	同步当前状态

Quality Gate Architecture

质量门禁架构

Three subagents serve as mandatory quality gates. ALL THREE must return a PASS verdict for the task execution to be considered complete. The

requirements-verifier

runs before the gates (step 7) to confirm coverage is complete — the gates then review code that is known to address all requirements.

Gate	Concern	Runs after
`clean-code-reviewer`	Clean Code, SOLID, test quality, documentation	`requirements-verifier`
`architecture-reviewer`	DDD, functional programming, bounded contexts	`clean-code-reviewer`
`security-auditor`	Vulnerabilities, credential leaks, insecure patterns	`architecture-reviewer`

三个子Agent作为强制质量门禁，必须全部返回通过判定，才算任务执行完成。

requirements-verifier

会在门禁前运行（步骤7）确认需求覆盖完整——之后门禁才会评审已知满足所有需求的代码。

门禁	检查项	运行时机
`clean-code-reviewer`	整洁代码、SOLID、测试质量、文档	`requirements-verifier` 之后
`architecture-reviewer`	DDD、函数式编程、限界上下文	`clean-code-reviewer` 之后
`security-auditor`	漏洞、凭证泄露、不安全编码模式	`architecture-reviewer` 之后

On quality gate failure — targeted fix cycle

质量门禁未通过的处理——定向修复循环

If ANY gate returns a verdict other than PASS, the pipeline does NOT re-run from the beginning. Instead, a targeted fix cycle is triggered:

The failing gate's feedback (specific issues, file paths, and recommended fixes) is collected.
The
```
task-executor
```
subagent is re-dispatched with the original execution brief PLUS the gate feedback as additional context. The executor addresses only the issues raised by the failing gate — it does not redo the entire implementation.
The
```
documentation-writer
```
subagent is re-dispatched to commit the fixes as atomic commits.
The failing gate is re-run to verify the fixes.

If multiple gates fail in the same run, all gate feedback is collected and passed to the task-executor together, so all issues are addressed in one fix cycle. After the fixes are committed, ALL previously failing gates are re-run in their original order.

Fix cycle limit: Maximum 3 targeted fix cycles per task. If the quality gates still do not pass after 3 fix cycles, escalate to the user with the accumulated gate feedback and ask how to proceed.

A full pipeline re-run (from step 1) is reserved for cases where the gate feedback indicates a fundamental approach failure — not code quality issues. The orchestrator makes this judgment call when the fix cycle limit is exhausted.

The quality gates also enforce a commit discipline rule: if any gate detects uncommitted changes in the working tree, it MUST stop immediately and report this to the orchestrator. The orchestrator will then require the

documentation-writer

subagent to commit all pending changes before the gates can re-run. This ensures that reviewers always review committed, traceable code.

如果任意门禁返回非通过判定，流水线不会从头重新运行，而是触发定向修复循环：

收集未通过门禁的反馈（具体问题、文件路径、建议修复方案）
重新调用
```
task-executor
```
子Agent，传入原始执行概要加上门禁反馈作为额外上下文。执行器仅处理未通过门禁提出的问题，不会重做整个实现。
重新调用
```
documentation-writer
```
子Agent，将修复内容作为原子提交。
重新运行未通过的门禁验证修复效果。

如果同一次运行中多个门禁未通过，会收集所有门禁反馈一起传给task-executor，这样所有问题可以在一个修复循环中处理完成。修复提交后，所有之前未通过的门禁会按原顺序重新运行。

修复循环限制： 每个任务最多进行3次定向修复循环。如果3次循环后质量门禁仍未通过，将累计的门禁反馈上报给用户，询问后续处理方案。

仅当门禁反馈表明基础实现方案存在根本性错误时，才会从头重新运行整个流水线（从步骤1开始），代码质量问题不会触发全量重跑。修复循环次数耗尽后由编排器做出该判断。

质量门禁还会强制提交规范规则：如果任意门禁检测到工作区存在未提交的变更，必须立即停止并向编排器报告。编排器会要求

documentation-writer

子Agent先提交所有待处理变更，才能重新运行门禁。这确保评审的始终是已提交的、可追溯的代码。

Execution Steps

执行步骤

1. Dispatch: Execution Prepper

1. 调用：执行准备器

Read

./subagents/execution-prepper.md

and dispatch the execution-prepper subagent with:

```
TICKET_KEY
```
```
TASK_NUMBER
```
```
BRANCH_OVERRIDE
```
(if the orchestrator or user specified a branch name)

The execution-prepper handles four setup steps in one dispatch:

Validates the task — checks that the task exists, dependencies are marked complete, and all questions are resolved.
Ensures the working branch — checks current branch, creates or switches to the feature branch, stashes uncommitted changes if needed.
Transitions the Jira subtask to "In Progress" — if the subtask key and Jira MCP are available. Skips silently if not.
Assembles the execution brief — reads the task plan and Decisions Log, builds a self-contained brief, writes it to
```
docs/<TICKET_KEY>-task-<N>-brief.md
```
.

Collect its output as the

PREP_SUMMARY

If pre-flight FAIL: The subagent reports what needs resolution (unsatisfied dependencies or unresolved questions). Relay this to the user and stop — do not proceed to the execution pipeline.

If an existing ticket branch was found: The subagent notes this. Ask the user whether to reuse the existing branch or create a new task-level branch. If the user chooses to reuse, re-dispatch with the branch name as

BRANCH_OVERRIDE

If changes were stashed: Inform the user that uncommitted changes were stashed and will need to be popped later.

After the prep summary confirms PASS, proceed to step 2 using the brief file path from the summary.

读取

./subagents/execution-prepper.md

，调用execution-prepper子Agent，传入以下参数：

```
TICKET_KEY
```
```
TASK_NUMBER
```
```
BRANCH_OVERRIDE
```
（如果编排器或用户指定了分支名）

execution-prepper会在一次调用中完成四个准备步骤：

验证任务 —— 检查任务是否存在、依赖是否标记为已完成、所有问题是否已解决。
确保工作分支可用 —— 检查当前分支，创建或切换到功能分支，必要时暂存未提交的变更。
将Jira子任务流转为“进行中” —— 如果子任务key和Jira MCP可用，否则静默跳过。
组装执行概要 —— 读取任务计划和决策日志，构建自包含的执行概要，写入
```
docs/<TICKET_KEY>-task-<N>-brief.md
```
。

收集其输出作为

PREP_SUMMARY

。

如果预检失败： 子Agent会报告需要解决的问题（未满足的依赖或未解决的问题）。将问题转告用户并停止——不要继续执行流水线。

如果找到已有的工单分支： 子Agent会记录该情况。询问用户是复用现有分支还是创建新的任务级分支。如果用户选择复用，传入分支名作为

BRANCH_OVERRIDE

重新调用。

如果有变更被暂存： 告知用户未提交的变更已被暂存，之后需要手动弹出。

准备摘要确认通过后，使用摘要中的概要文件路径进入步骤2。

2. Dispatch: Execution Planner

2. 调用：执行规划器

Read

./subagents/execution-planner.md

and dispatch the execution-planner subagent with the execution brief path.

The execution-planner will:

Analyse the task and the relevant parts of the codebase.
Use the
```
/find-skills
```
skill to identify the best available skills for the task.
Produce a structured execution plan with recommended skills, approach, and file-level strategy.

Collect its output as the

EXECUTION_PLAN

. This plan feeds into all subsequent subagents.

读取

./subagents/execution-planner.md

，传入执行概要文件路径调用execution-planner子Agent。

execution-planner会完成以下工作：

分析任务和代码库的相关部分
使用
```
/find-skills
```
技能识别最适合该任务的可用技能
生成结构化的执行计划，包含推荐技能、实现方案、文件级策略

收集其输出作为

EXECUTION_PLAN

，该计划会输入到所有后续子Agent中。

3. Dispatch: Test Strategist

3. 调用：测试策略师

Read

./subagents/test-strategist.md

and dispatch the test-strategist subagent with the execution brief and the

EXECUTION_PLAN

The test strategist will:

Analyse the business requirements from the execution brief.
Define a list of behaviour-driven tests (not implementation-detail tests).
Produce a test specification that the task-executor will implement.

Collect its output as the

TEST_SPEC

读取

./subagents/test-strategist.md

，传入执行概要和

EXECUTION_PLAN

调用test-strategist子Agent。

test-strategist会完成以下工作：

分析执行概要中的业务需求
定义行为驱动测试列表（而非实现细节相关的测试）
生成测试规范，供task-executor实现

收集其输出作为

TEST_SPEC

。

4. Dispatch: Refactoring Advisor

4. 调用：重构顾问

Read

./subagents/refactoring-advisor.md

and dispatch the refactoring-advisor subagent with the execution brief,

EXECUTION_PLAN

, and

TEST_SPEC

The refactoring advisor will:

Evaluate whether existing code needs changes to accommodate the task cleanly.
Identify refactoring opportunities that prevent code rot.
Produce a refactoring recommendation (which may be "no refactoring needed").

Collect its output as the

REFACTORING_PLAN

读取

./subagents/refactoring-advisor.md

，传入执行概要、

EXECUTION_PLAN

和

TEST_SPEC

调用refactoring-advisor子Agent。

refactoring-advisor会完成以下工作：

评估现有代码是否需要变更才能适配当前任务
识别可避免代码腐化的重构机会
生成重构建议（可能是“无需重构”）

收集其输出作为

REFACTORING_PLAN

。

5. Dispatch: Task Executor

5. 调用：任务执行器

Read

./subagents/task-executor.md

and dispatch the task-executor subagent with the execution brief,

EXECUTION_PLAN

TEST_SPEC

, and

REFACTORING_PLAN

The task executor operates under a cautious execution model: it will STOP and report back to the orchestrator whenever it encounters ambiguity, unclear intent, uncertain architectural decisions, or any situation where the correct course of action is not explicitly documented in its inputs. The orchestrator must then resolve the ambiguity and re-dispatch the task-executor with updated guidance.

The task executor will:

Apply any recommended refactoring first.
Implement the task following the execution plan and recommended skills.
Write and run the tests from the test specification.
STOP and escalate if anything is unclear — it does NOT guess or assume.
Produce an execution report.

Collect its output as the

EXECUTION_REPORT

If the task-executor stops due to ambiguity:

Review the reported ambiguity.
Resolve it with the user if needed.
Update the execution brief with the resolution.
Re-dispatch the task-executor with the updated brief and the
```
PARTIAL_EXECUTION_REPORT
```
from the previous run.

Note: The task-executor does NOT write documentation — that is handled separately by the documentation-writer subagent.

读取

./subagents/task-executor.md

，传入执行概要、

EXECUTION_PLAN

、

TEST_SPEC

和

REFACTORING_PLAN

调用task-executor子Agent。

task-executor遵循谨慎执行模型：每当遇到歧义、意图不明确、不确定的架构决策，或任何正确处理方式未在输入中明确说明的场景时，都会停止并向编排器报告。编排器必须解决歧义后，传入更新后的指引重新调用task-executor。

task-executor会完成以下工作：

先应用所有推荐的重构
按照执行计划和推荐技能实现任务
编写并运行测试规范中的测试
遇到任何不明确的内容立即停止并上报——不会猜测或假设
生成执行报告

收集其输出作为

EXECUTION_REPORT

。

如果task-executor因歧义停止：

评审上报的歧义问题
必要时和用户一起解决问题
更新执行概要，记录解决方案
传入更新后的概要和上一次运行的
```
PARTIAL_EXECUTION_REPORT
```
，重新调用task-executor。

注意： task-executor不编写文档——该工作由documentation-writer子Agent单独处理。

6. Dispatch: Documentation Writer

6. 调用：文档编写师

Read

./subagents/documentation-writer.md

and dispatch the documentation-writer subagent with the

EXECUTION_REPORT

TICKET_KEY

, and

TASK_NUMBER

The documentation writer will:

Review all changes made by the task-executor.
Add or update code comments, docstrings, and inline documentation ONLY in files that the task-executor changed. It does NOT modify any other files.
Use the
```
/humanizer
```
skill to ensure all written text reads naturally.
Use the
```
/commit-work
```
skill to commit all changes (implementation, tests, and documentation) as atomic, logically scoped commits. It does NOT ask for user confirmation — it commits directly.
Update the task plan with completion status, implementation summary, and files changed.
Transition the Jira subtask to "Done" (if MCP available and subtask key present).
Update the
## Jira Subtasks
table status to "Done".
Produce a documentation report including commits, tracking updates, and any issues.

Collect its output as the

DOCUMENTATION_REPORT

读取

./subagents/documentation-writer.md

，传入

EXECUTION_REPORT

、

TICKET_KEY

和

TASK_NUMBER

调用documentation-writer子Agent。

documentation-writer会完成以下工作：

评审task-executor的所有变更
仅在task-executor修改过的文件中新增或更新代码注释、文档字符串、内联文档，不会修改其他任何文件
使用
```
/humanizer
```
技能确保所有文本自然可读
使用
```
/commit-work
```
技能将所有变更（实现、测试、文档）作为逻辑独立的原子提交，无需用户确认——直接提交
更新任务计划，添加完成状态、实现摘要、变更文件列表
将Jira子任务流转为“已完成”（如果MCP可用且存在子任务key）
更新
## Jira子任务
表格状态为“已完成”
生成文档报告，包含提交记录、跟踪更新、任何问题

收集其输出作为

DOCUMENTATION_REPORT

。

7. Dispatch: Requirements Verifier (pre-gate coverage check)

7. 调用：需求验证器（门禁前覆盖检查）

Read

./subagents/requirements-verifier.md

and dispatch the requirements-verifier subagent with the execution brief,

TEST_SPEC

EXECUTION_REPORT

, and

DOCUMENTATION_REPORT

The requirements verifier runs BEFORE the quality gates to catch coverage gaps early. This prevents the gates from reviewing code that is missing functionality — wasting a full gate cycle on incomplete work.

The requirements verifier will:

Cross-check every item in the Definition of Done against the actual changes.
Verify test coverage matches business requirements.
Confirm documentation is complete.
Produce a verification verdict: PASS or FAIL with specific gaps.

If the verdict is FAIL: Report the gaps to the user and ask whether to address the missing requirements before running the quality gates, or proceed with the gates on the current implementation. Do NOT automatically re-run the pipeline — let the user decide.

If the verdict is PASS: Proceed to the quality gates.

Collect its output as the

VERIFICATION_RESULT

. Pass it to the quality gates as additional context so they know whether requirements coverage is complete.

读取

./subagents/requirements-verifier.md

，传入执行概要、

TEST_SPEC

、

EXECUTION_REPORT

和

DOCUMENTATION_REPORT

调用requirements-verifier子Agent。

需求验证器在质量门禁前运行，尽早发现覆盖缺口，避免门禁评审功能缺失的代码——浪费门禁周期在未完成的工作上。

requirements-verifier会完成以下工作：

对照实际变更交叉检查完成定义中的每一项
验证测试覆盖匹配业务需求
确认文档完整
生成验证判定：通过，或带有具体缺口的不通过

如果判定为不通过： 将缺口报告给用户，询问是在运行质量门禁前先补全缺失的需求，还是基于当前实现继续运行门禁。不要自动重新运行流水线——让用户决定。

如果判定为通过： 进入质量门禁阶段。

收集其输出作为

VERIFICATION_RESULT

，将其作为额外上下文传给质量门禁，让门禁知晓需求覆盖是否完整。

8. Dispatch: Clean Code Reviewer (Quality Gate 1/3)

8. 调用：整洁代码评审员（质量门禁1/3）

Read

./subagents/clean-code-reviewer.md

and dispatch the clean-code-reviewer subagent with the execution brief,

TEST_SPEC

REFACTORING_PLAN

EXECUTION_REPORT

DOCUMENTATION_REPORT

, and

VERIFICATION_RESULT

Pre-gate check: The clean-code-reviewer will first check for uncommitted changes. If uncommitted changes exist, it stops and reports this — the orchestrator must ensure the documentation-writer commits all pending work before the review can proceed.

The clean code reviewer will:

Use the
```
/clean-code
```
skill as its primary review reference (required — subagent will stop if not available).
Review the full picture: task requirements, tests, refactoring decisions, implementation, and documentation.
Check for Clean Code and SOLID principles compliance.
Use the
```
context7
```
MCP to retrieve up-to-date documentation for libraries used in the project, ensuring recommendations reflect current best practices.
Produce a review verdict: PASS, PASS WITH SUGGESTIONS, or NEEDS FIXES.

If verdict is NEEDS FIXES: Collect the review feedback. Do NOT stop the gate cycle — continue to the architecture-reviewer and security-auditor so all issues are identified in one pass. After all three gates have run, trigger a targeted fix cycle (see Quality Gate Architecture above).

Collect the output as the

CODE_REVIEW

读取

./subagents/clean-code-reviewer.md

，传入执行概要、

TEST_SPEC

、

REFACTORING_PLAN

、

EXECUTION_REPORT

、

DOCUMENTATION_REPORT

和

VERIFICATION_RESULT

调用clean-code-reviewer子Agent。

门禁前置检查： clean-code-reviewer会首先检查是否存在未提交的变更。如果存在未提交的变更，会停止并报告——编排器必须确保documentation-writer先提交所有待处理工作，才能继续评审。

clean-code-reviewer会完成以下工作：

使用
```
/clean-code
```
技能作为主要评审参考（必填——如果不可用子Agent会停止）
评审全链路内容：任务需求、测试、重构决策、实现、文档
检查整洁代码和SOLID原则合规性
使用
```
context7
```
MCP获取项目所用库的最新文档，确保推荐符合当前最佳实践
生成评审判定：通过、有建议通过、需要修复

如果判定为需要修复： 收集评审反馈，不要停止门禁流程——继续运行architecture-reviewer和security-auditor，一次性识别所有问题。三个门禁全部运行完成后，触发定向修复循环（见上文质量门禁架构）。

收集输出作为

CODE_REVIEW

。

9. Dispatch: Architecture Reviewer (Quality Gate 2/3)

9. 调用：架构评审员（质量门禁2/3）

Read

./subagents/architecture-reviewer.md

and dispatch the architecture-reviewer subagent with the execution brief,

EXECUTION_PLAN

EXECUTION_REPORT

DOCUMENTATION_REPORT

VERIFICATION_RESULT

, and

CODE_REVIEW

Pre-gate check: The architecture-reviewer will first check for uncommitted changes. If uncommitted changes exist, it stops and reports this.

The architecture reviewer will:

Use the
```
/architecture-patterns
```
skill as its primary review reference (required — subagent will stop if not available).
Verify that changes follow domain-driven design principles: bounded contexts, aggregates, entities, value objects, domain events, and ubiquitous language.
Verify that changes follow functional programming principles: functional composition, immutability, pure functions, and declarative patterns.
Explicitly NOT enforce OOP patterns — the codebase should favor composition over inheritance, data transformations over stateful objects.
Use the
```
context7
```
MCP to retrieve up-to-date documentation for libraries used in the project.
Produce a review verdict: PASS, PASS WITH SUGGESTIONS, or NEEDS FIXES.

If verdict is NEEDS FIXES: Collect the review feedback. Continue to the security-auditor so all issues are identified in one pass.

Collect the output as the

ARCHITECTURE_REVIEW

读取

./subagents/architecture-reviewer.md

，传入执行概要、

EXECUTION_PLAN

、

EXECUTION_REPORT

、

DOCUMENTATION_REPORT

、

VERIFICATION_RESULT

和

CODE_REVIEW

调用architecture-reviewer子Agent。

门禁前置检查： architecture-reviewer会首先检查是否存在未提交的变更。如果存在未提交的变更，会停止并报告。

architecture-reviewer会完成以下工作：

使用
```
/architecture-patterns
```
技能作为主要评审参考（必填——如果不可用子Agent会停止）
验证变更符合领域驱动设计原则：限界上下文、聚合、实体、值对象、领域事件、通用语言
验证变更符合函数式编程原则：函数组合、不可变性、纯函数、声明式模式
明确不强制OOP模式——代码库应该优先选择组合而非继承，优先选择数据转换而非有状态对象
使用
```
context7
```
MCP获取项目所用库的最新文档
生成评审判定：通过、有建议通过、需要修复

如果判定为需要修复： 收集评审反馈，继续运行security-auditor，一次性识别所有问题。

收集输出作为

ARCHITECTURE_REVIEW

。

10. Dispatch: Security Auditor (Quality Gate 3/3)

10. 调用：安全审计员（质量门禁3/3）

Read

./subagents/security-auditor.md

and dispatch the security-auditor subagent with the execution brief,

EXECUTION_REPORT

DOCUMENTATION_REPORT

VERIFICATION_RESULT

CODE_REVIEW

, and

ARCHITECTURE_REVIEW

Pre-gate check: The security-auditor will first check for uncommitted changes. If uncommitted changes exist, it stops and reports this.

The security auditor will:

Use the
```
/api-security-best-practices
```
skill as its primary audit reference (required — subagent will stop if not available).
Audit all changes for security vulnerabilities (injection, XSS, CSRF, insecure deserialization, broken access control, etc.).
Check for credential leaks, hardcoded secrets, and sensitive information exposure in code, comments, logs, or error messages.
Verify secure coding patterns (input validation, output encoding, authentication/authorization checks, secure defaults).
Use the
```
context7
```
MCP to retrieve up-to-date security documentation for libraries used in the project.
Produce an audit verdict: PASS, PASS WITH ADVISORIES, or NEEDS FIXES.

If verdict is NEEDS FIXES: Collect the audit feedback.

读取

./subagents/security-auditor.md

，传入执行概要、

EXECUTION_REPORT

、

DOCUMENTATION_REPORT

、

VERIFICATION_RESULT

、

CODE_REVIEW

和

ARCHITECTURE_REVIEW

调用security-auditor子Agent。

门禁前置检查： security-auditor会首先检查是否存在未提交的变更。如果存在未提交的变更，会停止并报告。

security-auditor会完成以下工作：

使用
```
/api-security-best-practices
```
技能作为主要审计参考（必填——如果不可用子Agent会停止）
审计所有变更的安全漏洞（注入、XSS、CSRF、不安全反序列化、访问控制失效等）
检查代码、注释、日志、错误消息中的凭证泄露、硬编码密钥、敏感信息暴露问题
验证安全编码模式（输入验证、输出编码、认证/授权检查、安全默认值）
使用
```
context7
```
MCP获取项目所用库的最新安全文档
生成审计判定：通过、有警告通过、需要修复

如果判定为需要修复： 收集审计反馈。

10a. Targeted fix cycle (if any gate returned NEEDS FIXES)

10a. 定向修复循环（如果任意门禁返回需要修复）

After all three gates have run, check whether any returned NEEDS FIXES. If all three passed, skip to step 11.

If one or more gates returned NEEDS FIXES:

Collect all feedback. Merge the NEEDS FIXES feedback from every failing gate into a single consolidated fix brief. Include specific file paths, line numbers, and recommended fixes from each gate.
Re-dispatch the task-executor. Pass the original execution brief PLUS the consolidated fix brief as additional context. The executor addresses only the issues raised by the failing gates — it does not redo the entire implementation.
Re-dispatch the documentation-writer. Pass the fix execution report so the documentation-writer can commit the fixes as atomic commits.
Re-run only the previously failing gates. If only the security-auditor failed, only re-run the security-auditor. If clean-code-reviewer and architecture-reviewer both failed, re-run both (in their original order). Gates that already passed do not need to re-run.
Check results. If all re-run gates now pass, continue to step 11. If any still fail, repeat this fix cycle.

Fix cycle limit: Maximum 3 targeted fix cycles per task. If the quality gates still do not pass after 3 fix cycles, escalate to the user with the accumulated gate feedback and ask how to proceed. The user may choose to:

Accept the current state and move on.
Provide guidance for a different approach.
Request a full pipeline re-run from step 1 (reserved for fundamental approach failures, not code quality issues).

Collect the output as the

SECURITY_AUDIT

三个门禁全部运行完成后，检查是否有门禁返回需要修复。如果全部通过，跳过到步骤11。

如果有一个或多个门禁返回需要修复：

收集所有反馈。 将所有未通过门禁的需要修复反馈合并为统一的修复概要，包含每个门禁提出的具体文件路径、行号、建议修复方案。
重新调用task-executor。 传入原始执行概要加上合并后的修复概要作为额外上下文。执行器仅处理未通过门禁提出的问题，不会重做整个实现。
重新调用documentation-writer。 传入修复执行报告，让documentation-writer将修复内容作为原子提交。
仅重新运行之前未通过的门禁。 如果只有security-auditor未通过，仅重新运行security-auditor。如果clean-code-reviewer和architecture-reviewer都未通过，按原顺序重新运行这两个。已经通过的门禁不需要重新运行。
检查结果。 如果所有重新运行的门禁现在都通过，继续到步骤11。如果仍有未通过的，重复该修复循环。

修复循环限制： 每个任务最多进行3次定向修复循环。如果3次循环后质量门禁仍未通过，将累计的门禁反馈上报给用户，询问后续处理方案。用户可以选择：

接受当前状态继续
提供其他实现方案的指引
请求从步骤1开始全量重跑流水线（仅用于基础实现方案失败的情况，不用于代码质量问题）

收集输出作为

SECURITY_AUDIT

。

11. Clean up

11. 清理

Delete the temporary execution brief file:

bash

rm -f docs/<TICKET_KEY>-task-<N>-brief.md

Cleanup failure is non-critical — log a warning but do not block.

Note: Post-execution tracking (plan file updates, Jira subtask transitions, Jira Subtasks table updates) is handled by the

documentation-writer

subagent in step 6. Check the

DOCUMENTATION_REPORT

for the tracking status. If any tracking update failed, relay it to the user in the report below.

删除临时执行概要文件：

bash

rm -f docs/<TICKET_KEY>-task-<N>-brief.md

清理失败不影响流程——记录警告即可，不要阻塞执行。

注意： 执行后跟踪（计划文件更新、Jira子任务状态流转、Jira子任务表格更新）由步骤6中的

documentation-writer

子Agent处理。检查

DOCUMENTATION_REPORT

中的跟踪状态。如果有跟踪更新失败，在下方的报告中转告用户。

12. Report to user

12. 向用户报告

Task <N> complete: <Title>

Summary: <what was done in 2-3 sentences>

Pipeline results:
- Prep: <branch name, pre-flight PASS>
- Planning: <skills recommended, approach taken>
- Tests: <N tests defined, N passing>
- Refactoring: <what was refactored, or "none needed">
- Implementation: <files changed count>
- Documentation: <what was documented>
- Commits: <N atomic commits created>
- Tracking: <plan updated, Jira transitioned — from DOCUMENTATION_REPORT>
- Requirements verification: <PASS/FAIL> (pre-gate coverage check)
- Code review: <PASS/PASS WITH NOTES> (recency-validated via context7)
- Architecture review: <PASS/PASS WITH NOTES> (DDD + FP validated)
- Security audit: <PASS/PASS WITH ADVISORIES>

Commits:
- <short hash> — <commit message>
- <short hash> — <commit message>

Files changed:
- <list>

Jira subtask <KEY>: transitioned to Done.

⚠️ Remaining items (if any):
- <anything that could not be fully resolved>

Ready for the next task? Let me know which one to tackle.

任务 <N> 已完成：<标题>

摘要：<用2-3句话说明完成的工作>

流水线结果：
- 准备：<分支名，预检通过>
- 规划：<推荐的技能，采用的实现方案>
- 测试：<定义N个测试，N个通过>
- 重构：<重构的内容，或“无需重构”>
- 实现：<变更文件数量>
- 文档：<记录的内容>
- 提交：<创建N个原子提交>
- 跟踪：<计划已更新，Jira状态已流转——来自DOCUMENTATION_REPORT>
- 需求验证：<通过/不通过>（门禁前覆盖检查）
- 代码评审：<通过/有备注通过>（通过context7验证时效性）
- 架构评审：<通过/有备注通过>（DDD + FP验证通过）
- 安全审计：<通过/有警告通过>

提交记录：
- <短哈希> — <提交信息>
- <短哈希> — <提交信息>

变更文件：
- <列表>

Jira子任务 <KEY>：已流转为已完成。

⚠️ 剩余待处理项（如果有）：
- <未完全解决的内容>

准备好处理下一个任务了吗？告诉我要处理哪个任务即可。

Safety Rules

安全规则

One task at a time. Never auto-continue to the next task.
Scope discipline. Do not implement anything outside the task's scope, even if it seems like a quick win.
Fail loudly. If any subagent encounters ambiguity or a blocker, surface it to the user immediately rather than making assumptions.
Preserve the plan. The task plan is the source of truth. If execution reveals the plan needs changes, propose the change to the user — do not silently modify the plan.
Respect the pipeline order. Do not skip subagent steps or reorder them. Each step depends on the output of the previous one.
Limit retries. The task-executor gets at most 3 retry cycles for ambiguity escalations within a single pipeline run. The targeted fix cycle (triggered by quality gate failures) is limited to 3 iterations within this skill. Full pipeline re-runs are reserved for fundamental approach failures and require user approval.
Quality gates are non-negotiable. All three quality gates (clean-code, architecture, security) must pass. There is no override, no "good enough."

每次仅执行一个任务。 绝对不要自动继续执行下一个任务。
范围管控。 不要实现任何超出任务范围的内容，哪怕看起来是很容易实现的优化。
明确报错。 如果任意子Agent遇到歧义或阻塞，立即向用户反馈，不要自行假设。
保护计划完整性。 任务计划是唯一可信源。如果执行过程中发现计划需要变更，向用户提出变更建议——不要悄悄修改计划。
遵守流水线顺序。 不要跳过子Agent步骤或调整顺序，每个步骤都依赖前一步的输出。
限制重试次数。 单次流水线运行中，task-executor最多可以因歧义上报重试3次。质量门禁失败触发的定向修复循环在本技能中最多迭代3次。全量重跑流水线仅用于基础实现方案失败的场景，且需要用户批准。
质量门禁不可妥协。 三个质量门禁（整洁代码、架构、安全）必须全部通过，没有例外，没有“足够好”的情况。

Handling BLOCKED Verdicts (Missing Required Skills)

处理阻塞判定（缺失必填技能）

Every subagent checks for its required skills as its absolute first step (defense-in-depth). If a subagent returns a

BLOCKED — MISSING REQUIRED SKILL

verdict:

Do NOT proceed to the next pipeline step. The blocked subagent's output is required by downstream steps.
Present the missing skill(s) to the user with install commands from the subagent's report.
Wait for the user to confirm the skill(s) have been installed.
Re-dispatch the blocked subagent from the beginning. Do not attempt to resume from a partial state — the subagent performs no work before the skill check, so there is nothing to resume.

This applies to ANY subagent in the pipeline (steps 1–10). The orchestrator should present the install instructions clearly:

⚠️ Missing required skill — pipeline paused

The <subagent-name> subagent requires the following skill(s):

- `/<skill-name>` — <purpose>
  Install: `skills install <path>`

Please install the skill(s) and let me know when ready to continue.

After the user confirms installation, re-dispatch the same subagent with the same inputs it was originally given.

每个子Agent的第一步都会检查所需技能（深度防御）。如果子Agent返回

阻塞 — 缺失必填技能

判定：

不要继续执行下一个流水线步骤。下游步骤依赖被阻塞子Agent的输出。
向用户展示缺失的技能，附带子Agent报告中的安装命令。
等待用户确认技能已安装完成。
从头重新调用被阻塞的子Agent。 不要尝试从部分状态恢复——子Agent在技能检查前不会执行任何工作，所以没有可恢复的内容。

该规则适用于流水线中的任意子Agent（步骤1-10）。编排器应该清晰展示安装说明：

⚠️ 缺失必填技能 — 流水线已暂停

<subagent-name>子Agent需要以下技能：

- `/<skill-name>` — <用途>
  安装命令：`skills install <路径>`

请安装该技能，准备好后告诉我继续。

用户确认安装完成后，使用原始输入重新调用同一个子Agent。