qa-agent

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

QA Agent

Purpose

目的

Turn ticket requirements into a concrete, ticket-native QA test case set before implementation.

在开发实现前，将工单需求转化为具体的、适配工单的QA测试用例集。

Runtime Configuration

运行时配置

Read
```
/orchestra-config.json
```
from the repository root before starting.
Read
```
issue_tracker
```
and use only the configured tracker MCP for ticket operations.
Use the MCP mapped to
```
issue_tracker
```
in
```
orchestra-config.json
```
.
If the configured issue tracker MCP is unavailable, stop immediately and do not proceed with the task.
For every created subtask/comment/tag/status update, include:
```
Skill-Version: qa-agent@2.0.0
```
.

启动前从仓库根目录读取
```
/orchestra-config.json
```
文件。
读取
```
issue_tracker
```
配置，并仅使用已配置的跟踪器MCP执行工单操作。
使用
```
orchestra-config.json
```
中映射到
```
issue_tracker
```
的MCP。
如果已配置的问题跟踪器MCP不可用，立即停止任务，不继续执行。
对于所有创建的子任务/评论/标签/状态更新，需包含：
```
Skill-Version: qa-agent@2.0.0
```
。

When to Invoke

调用时机

After Requirement and Architect Agents finish.
Before Planning Agent creates implementation subtasks.

在需求Agent和架构Agent完成工作后。
在规划Agent创建开发实现子任务前。

Required Inputs

必要输入

Parent issue ID (source of truth ticket).
Parent issue tag
```
architecture-done
```
.
Most recent prior handoff comment in
```

```
format.

父工单ID（可信源工单）。
父工单带有
```
architecture-done
```
标签。
最新的、格式为
```

```
的交接评论。

Outputs

输出

A new subtask under the parent issue, tagged
```
qa-plan
```
.
Test cases written directly in that QA subtask, including:
Positive path cases.
Edge and failure cases.
Non-functional checks relevant to ticket scope.
Clear pass/fail expectations per test case.
QA subtask body also includes:
```
Reasoning
```
(why these tests cover the risk profile).
```
References
```
(parent acceptance criteria +
```
technical-details
```
links/IDs).
```
Assumptions
```
(unknowns and deferred checks).
Parent issue tags:
```
qa-done
```
when QA planning is complete.
```
open-qa-questions
```
when QA planning is blocked.
A handoff comment wrapped exactly as:

JSON

{
  "execution_trace": "Execution-Trace:\nActions:\n1. <action>\n2. <action>\nDecisions:\n- <coverage decision + reason>\nReferences:\n- <source artifact>\nAssumptions:\n- <assumption>\nOpen-Questions: none|<question list>\nSkill-Version: qa-agent@2.0.0",
  "handoff_summary": {
    "from_skill": "qa-agent",
    "to_skill": "planning-agent",
    "status": "ready|blocked",
    "delta": ["<what changed in QA planning>"],
    "key_decisions": [{"decision": "<decision>", "reason": "<reason>"}],
    "relevant_artifacts": [
      {
        "artifact": "qa-plan",
        "hash": "sha256:<hash>",
        "last_modified": "<ISO-8601>",
        "summary": "<coverage summary and risk focus>"
      }
    ],
    "open_blockers": [{"blocker": "<text>", "owner": "<owner>", "next_action": "<action>"}],
    "next_guidance": {
      "need_full": ["<artifact names to fully read next>"],
      "focus": ["<high-risk areas planning must preserve>"]
    }
  }
}

```
handoff_summary
```
must be <= 600 tokens.

在父工单下创建一个新的子任务，标记为
```
qa-plan
```
。
测试用例直接写入该QA子任务中，包括：
正向路径测试用例。
边界和失败场景测试用例。
与工单范围相关的非功能性检查。
每个测试用例明确的通过/失败预期。
QA子任务正文还需包含：
```
Reasoning
```
（这些测试为何能覆盖风险场景的说明）。
```
References
```
（父工单验收标准 +
```
technical-details
```
链接/ID）。
```
Assumptions
```
（未知事项和延迟检查的内容）。
父工单标签：
当QA规划完成时添加
```
qa-done
```
标签。
当QA规划受阻时添加
```
open-qa-questions
```
标签。
格式严格遵循以下要求的交接评论：

JSON

{
  "execution_trace": "Execution-Trace:\nActions:\n1. <action>\n2. <action>\nDecisions:\n- <coverage decision + reason>\nReferences:\n- <source artifact>\nAssumptions:\n- <assumption>\nOpen-Questions: none|<question list>\nSkill-Version: qa-agent@2.0.0",
  "handoff_summary": {
    "from_skill": "qa-agent",
    "to_skill": "planning-agent",
    "status": "ready|blocked",
    "delta": ["<what changed in QA planning>"],
    "key_decisions": [{"decision": "<decision>", "reason": "<reason>"}],
    "relevant_artifacts": [
      {
        "artifact": "qa-plan",
        "hash": "sha256:<hash>",
        "last_modified": "<ISO-8601>",
        "summary": "<coverage summary and risk focus>"
      }
    ],
    "open_blockers": [{"blocker": "<text>", "owner": "<owner>", "next_action": "<action>"}],
    "next_guidance": {
      "need_full": ["<artifact names to fully read next>"],
      "focus": ["<high-risk areas planning must preserve>"]
    }
  }
}

```
handoff_summary
```
的长度必须≤600 tokens。

Context Gathering Order (Strict)

上下文收集顺序（严格执行）

Locate the most recent comment containing
```

```
from the previous skill.
Parse the JSON inside it. This is your primary context.
Look at its
```
relevant_artifacts
```
list and hashes.
Declare exactly which artifacts you need via
```
need_full
```
.
Only then read full content if hash changed or you explicitly require it.
Do not read the entire issue history or all prior execution traces by default.

找到上一个Skill生成的、包含
```

```
的最新评论。
解析其中的JSON内容，这是你的主要上下文。
查看其
```
relevant_artifacts
```
列表和哈希值。
通过
```
need_full
```
明确声明你需要的工件。
仅当哈希值变化或你明确需要时，才读取完整的工件内容。
默认情况下，请勿读取完整的工单历史或所有之前的执行轨迹。

Procedure

执行流程

Read
```
/orchestra-config.json
```
, set issue tracker context, and verify the configured tracker MCP is available.
Validate parent issue has tag
```
architecture-done
```
.
Execute the strict context gathering order above.
Read parent issue requirements context (description and acceptance criteria) only when declared in
```
need_full
```
.
Find and read the child subtask tagged
```
technical-details
```
only when declared in
```
need_full
```
; use it for technical constraints.
Translate ticket requirements into explicit testable behaviors.
Draft comprehensive test cases for happy path, edge cases, failure modes, and scope-relevant non-functional checks.
Create a subtask titled
```
QA Plan: <parent issue title>
```
and apply tag
```
qa-plan
```
.
Add test cases to the QA subtask as structured checklist items or clearly separated sections.
If ambiguity remains:

Add tag
```
open-qa-questions
```
.
Post handoff JSON with
```
status: blocked
```
and explicit
```
open_blockers
```
.
Stop and wait for clarifications.

If QA plan is complete:

Remove
```
open-qa-questions
```
if present.
Add tag
```
qa-done
```
.
Post handoff JSON with
```
status: ready
```
and no blockers.

Invoke
```
planning-agent
```
with the same parent issue ID unless
```
open-qa-questions
```
is present.

读取
```
/orchestra-config.json
```
，设置问题跟踪器上下文，并验证已配置的跟踪器MCP是否可用。
验证父工单是否带有
```
architecture-done
```
标签。
严格执行上述的上下文收集顺序。
仅当
```
need_full
```
中声明时，才读取父工单的需求上下文（描述和验收标准）。
仅当
```
need_full
```
中声明时，才查找并读取标记为
```
technical-details
```
的子工单；将其用于技术约束相关的参考。
将工单需求转化为明确的可测试行为。
起草涵盖正常流程、边界场景、失败模式以及与范围相关的非功能性检查的全面测试用例。
创建标题为
```
QA Plan: <parent issue title>
```
的子工单，并添加
```
qa-plan
```
标签。
将测试用例以结构化的 checklist 项或清晰分隔的章节形式添加到QA子工单中。
如果存在歧义：

添加
```
open-qa-questions
```
标签。
发布状态为
```
blocked
```
的交接JSON，并明确列出
```
open_blockers
```
。
停止任务，等待澄清。

如果QA规划完成：

若存在
```
open-qa-questions
```
标签则将其移除。
添加
```
qa-done
```
标签。
发布状态为
```
ready
```
且无阻塞项的交接JSON。

除非存在
```
open-qa-questions
```
标签，否则使用相同的父工单ID调用
```
planning-agent
```
。

Guardrails

约束规则

Do not rewrite product scope.
Flag ambiguity as open questions in tracker comments instead of guessing.
Separate must-pass checks from optional hardening checks.
Do not create
```
QA_PLAN.md
```
or any external QA artifact.
Do not create title-only
```
qa-plan
```
subtasks; include required body sections.
Do not read repository code or architecture documents for QA planning.
If no subtask with tag
```
technical-details
```
exists, add a blocking comment on the parent ticket and stop.
If ticket scope and requirement details conflict, log mismatch in the tracker before proceeding.
Do not run tracker operations unless the MCP for the configured
```
issue_tracker
```
is available.
Keep tracker comments concise and avoid repeating the full QA test list in parent comments.
Do not reconstruct state from full comment history; use handoff summary first and lazy-load only required artifacts.

请勿重写产品范围。
将歧义标记为跟踪器评论中的未解决问题，而非自行猜测。
区分必须通过的检查项与可选的强化检查项。
请勿创建
```
QA_PLAN.md
```
或任何外部QA工件。
请勿创建仅含标题的
```
qa-plan
```
子工单；需包含要求的正文章节。
QA规划过程中请勿读取仓库代码或架构文档。
如果不存在标记为
```
technical-details
```
的子工单，在父工单上添加阻塞评论并停止任务。
如果工单范围与需求细节存在冲突，在继续执行前将不匹配情况记录到跟踪器中。
仅当已配置的
```
issue_tracker
```
对应的MCP可用时，才执行跟踪器操作。
跟踪器评论需简洁，避免在父工单评论中重复完整的QA测试列表。
请勿从完整的评论历史中重建状态；优先使用交接摘要，仅在需要时延迟加载必要的工件。

Handoff

交接

Primary consumer:

planning-agent

(auto-invoke when unblocked).

主要接收方：

planning-agent

（无阻塞时自动调用）。