arkweb-architect

ArkWeb Architect - Subagent Orchestration Process

Environment Variables

The main Session determines the following variable values before Phase 1 begins, and all subsequent Phases reference these variables:

Variable	Meaning	Value Rules	Example
SKILL_HOME	Read-only resource path (skill definitions, templates, reference materials, existing analyses)	Default = main Session's current working directory (cwd). That is, the root path of the skill definition	—
WORK_HOME	Output path (design documents, analysis reports, generated code)	Default = SKILL_HOME. The user may specify the target code repository (cross-repository scenario)	—
DOCS_REPO	Design document repository path (location where outputs are stored)	Automatically discovered at startup; if not found, ask the user: search by priority → use the first one found → if none found, via AskUserQuestion require the user to directly input the path	—
docs_dir	Feature output directory	{DOCS_REPO}/docs/features/{feature-name}/	—
analysis_dir	Code analysis cache directory	{DOCS_REPO}/analysis/	—
references_dir	Reference materials	{DOCS_REPO}/references/	—

Value logic:

1. When the main Session starts,SKILL_HOME = current working directory (cwd)
2. If the user specifies another working directory, then WORK_HOME = user-specified path; otherwise WORK_HOME = SKILL_HOME
3. DOCS_REPO Check at startup (try in order of priority, stop at the first one that satisfies the conditions):
   • {SKILL_HOME} itself (check whether it contains the docs/features/ and analysis/ subdirectories)
   • {SKILL_HOME}/{DOCS_REPO_DIR}(check whether that directory exists and contains the docs/ and analysis/ subdirectories)
   • From SKILL_HOME search upward level by level for a directory containing the docs/features/ and analysis/ subdirectories
   • If none of the above are found → use AskUserQuestion to ask the user: "No design document repository found (must contain docs/features/ and analysis/ directories), please enter the full path"
4. When the main Session spawns a subagent, it replaces the above variables with actual absolute paths and injects them into the task description
5. The task received by the subagent does not contain variable names, only actual path values

Important: All path references in this SKILL.md use the above variables. This is to enable different models/environments to understand the meaning of the paths unambiguously. During actual execution, the main Session performs the variable substitution.

Core Principles

Main Session = coordinator + decision-maker, does not do the actual work.

Each skill is an independent subagent with its own context and output. Subagents pass data through the file system (reading and writing a shared workspace) and do not communicate directly.

proposal.md is the core requirements document. The template output (spec.md) is extracted and generated from proposal.md. The review target is always proposal.md.

Architecture Overview

┌──────────────────────────────────────────────────────────────────────────────────────────────┐
│                         🧠 主 Session（协调者）                                                │
│                                                                                              │
│  ┌───────┐ ┌───────┐ ┌───────┐                                                                  │
│  │决策 1 │ │决策 2 │ │决策 3 │                                                                  │
│  │选方案?│ │评审?  │ │审代码?│                                                                  │
│  └───┬───┘ └───┬───┘ └───┬───┘                                                                  │
│      └─────────┴─────────┘                                                                      │
│  ┌──────────────────────────────────────────────────────────────────────────────────────┐  │
│  │                    Subagent 调度器                                                   │  │
│  │         spawn / yield / collect / steer / kill                                       │  │
│  └──────────────────────────────────────────────────────────────────────────────────────┘  │
└──────────┬──────────┬──────────┬──────────┬──────────┬──────────┬──────────┬────────────────┘
           │          │          │          │          │          │          │
     ┌──────────────────────────────────────────────────────────┐
     │ 专家团（10 专家并行，由主 Session 直接调度）              │
     │ ⚡🎬🔌🔐🎨🖼️✨🌐⚙️🛡️                              │
     │ → 按相关度权重筛选（🟢核心/🟡关联/⚪旁听）              │
     └──────────────────────────────────────────────────────────┘
     ┌──────────────────────────────────────────────────────────┐
     │Sub-1 brainstorm（接收专家意见，输出方案）[Phase 2]          │
     │ → 读取专家团讨论纪要 → 融入方案 → 输出 brainstorm       │
     └──────────────────────────────────────────────────────────┘
     ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
     │Sub-2    │ │Sub-3    │ │Sub-4    │ │Sub-7    │ │Sub-8    │
     │code     │ │design   │ │spec     │ │code     │ │committer│
     │analysis │ │doc      │ │review   │ │gen      │ │review   │
     └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘
     ┌─────────┐
     │Sub-9    │
     │gitcode  │
     │pr       │
     │(Phase 9)│
     └─────────┘
     ┌─────────┐
     │Sub-10   │
     │spec-gen │
     │(Phase 6)│
     └─────────┘

     ┌──────────────────────────────────────────────────────────┐
     │ 主 Session 直接生成（不通过 subagent）                    │
     │ → proposal.md (Phase 1 需求录入 + Phase 1.5 澄清 + Phase 3 基线) │
     └──────────────────────────────────────────────────────────┘

Subagent List

ID	Skill	Responsibility	Input	Output
Sub-1	arkweb-brainstorm	Requirements decomposition and solution design	User requirements + constraints	brainstorm.md
Sub-2	arkweb-code-analysis	Code repository analysis	Technical keywords	analysis.md
Sub-3	arkweb-design-doc	Design document generation	Confirm solution + code index + out-of-scope items	requirement.md + design.md
Sub-4	arkweb-spec-review	Document review (including Checklist inspection)	Design document + code index	review.md
Sub-7	arkweb-code-gen	Code generation (Spec-driven)	Design document + spec.md + code index	Implementation code + tests
Sub-8	arkweb-committer-review	Committer code review	Design document + generated code	review-report.md
Sub-9	gitcode-pr	GitCode commit	Document + code + commit message	Issue + PR
Sub-10	arkweb-spec-gen	Unified Spec + execution plan generation	proposal + requirement + design + review + analysis	spec.md + task.md

Note: proposal.md (Phase 1 requirement entry + Phase 1.5 clarification record + Phase 3 requirement baseline) is generated directly bythe main Session. spec.md + task.md (Phase 6) are generated by Sub-10 (spec-gen).

v5 changes: Sub-4 merged the functionality of the original Sub-4.5 (checklist-review); during review, both the technical review and the Checklist compliance inspection are completed at the same time. Sub-5 (spec-extract) and Sub-6 (create-spec) have been removed, and spec.md is now generated by Sub-10 (spec-gen) in Phase 6.

Expert team Subagent (directly scheduled by the main Session)

In Step 2.2 of Phase 2, the main Session directly spawns domain expert subagents, collects their opinions, and passes them to brainstorm:

ID	Skill	Role	Trigger condition
Exp-1	arkweb-expert-performance	⚡ Performance expert	Automatically triggered by brainstorm
Exp-2	arkweb-expert-multimedia	🎬 Multimedia expert	Automatically triggered by brainstorm
Exp-3	arkweb-expert-peripheral	🔌 Peripheral service expert (sensors/battery/wake lock/vibration/screen)	Automatically triggered by brainstorm
Exp-4	arkweb-expert-interaction-security	🔐 Interaction security expert	Automatically triggered by brainstorm
Exp-5	arkweb-expert-rendering	🎨 Rendering engine expert	Automatically triggered by brainstorm
Exp-6	arkweb-expert-compositing	🖼️ Rendering composition expert	Automatically triggered by brainstorm
Exp-7	arkweb-expert-interaction-motion	✨ Interaction expert (scroll/zoom/menu/selection/drag/upload/focus/fill/AI-ification)	Automatically triggered by brainstorm
Exp-8	arkweb-expert-network	🌐 Network loading expert	Automatically triggered by brainstorm
Exp-9	arkweb-expert-js-engine	⚙️ JS engine expert	Automatically triggered by brainstorm
Exp-10	arkweb-expert-stability	🛡️ Stability and DFX expert	Automatically triggered by brainstorm

Note: the expert team subagents are directly scheduled by the main Session in Phase 2, and are not spawned inside Sub-1 (brainstorm). After collecting expert opinions, the main Session summarizes them into the "Expert Team Discussion Minutes" as input for brainstorm.

Complete process

Phase numbering convention

Phase 1-9 = natural number order — each phase corresponds to an independent step, with continuous numbering and no skipped numbers.

Number	Phase	Type	Required/Optional	Description
1	proposal (requirement entry + baseline)	Independent	Required	Phase 1 enters the original requirements, Phase 3 appends the requirement baseline, one file
1.5	Requirement clarification (multi-round dialogue)	Independent	Required	Ask the user questions round by round to clarify the hypotheses to be verified, scope, subsystem impacts, etc. Only after all clarifications are complete can Phase 2 be entered.
2	Requirements Analysis	Independent	Required	Knowledge base retrieval + expert panel + brainstorm + code-analysis, triggering Decision 1
3	design (design document)	Independent	Required	Produce requirement.md + design.md
4	Design Document	Independent	Required	Produce the complete design document
5	spec-review	Independent	Required	Complete technical review + Checklist in one go, triggering Decision 2
6	spec (unified specification document)	Independent	Required	Sub-10 generates spec.md (4-in-1) + task.md, input for code-gen
7	Code Generation	Independent	Required	Spec-driven code generation, triggering Decision 3
8	Committer Review	Independent	Required	Produce review report
9	Submit PR	Independent	Required	Produce Issue + PR

Phase 1: Initialization and Requirements Entry

主 Session:
  1. 接收用户需求
  2. 提取关键信息：
     - 需求描述
     - 目标设备（默认：全覆盖）
     - OHOS 版本（默认：全部）
  3. 确定工作目录：
     - docs_dir = {docs_dir}{feature-name}/
     - analysis_dir = {analysis_dir}
     - date = YYYY-MM-DD
     - feature = {从需求中提取的简短英文标识（kebab-case）}
  4. 创建需求目录：
     - mkdir -p {docs_dir}
  5. 生成文件名模板：
     - proposal: {docs_dir}/proposal.md
     - brainstorm: {docs_dir}/{date}-{feature}-brainstorm.md
     - requirement: {docs_dir}/{date}-{feature}-requirement.md
     - design: {docs_dir}/{date}-{feature}-design.md
     - review: {docs_dir}/{date}-{feature}-review.md
     - spec: {docs_dir}/spec.md
     - analysis: {analysis_dir}/{date}-{feature}-analysis.md
     - committer-review: {docs_dir}/{date}-{feature}-committer-review.md

proposal (requirements entry + baseline) ⭐ Required

Before brainstorm, record the original context of the requirement to ensure a complete traceability chain. Use the proposal.md template format.

主 Session:
  1. 从用户需求中提取：
     - 来源（MSDP / 内部 / 竞品 / 社区 Issue）
     - 提出人/团队
     - 原始问题描述
     - 用户痛点
     - 竞品/背景证据
     - 初始范围（可能包含 / 明确不包含）
     - 初始假设（待验证的技术假设）
     - 预计流程级别：L0（小改动）/ L1（标准 Feature）/ L2（跨子系统）/ L3（大型 Feature）
     - 判断依据：涉及仓数量、API 级别、是否需要跨团队
     - 目标发行版本：记录版本号或 TBD
     - 版本是否已承诺：是/否/待确认
  3. 保存为 proposal.md

[Mandatory] Before generating proposal.md, you must first read the template file {DOCS_REPO}/assets/templates/proposal.md, and fill in the content strictly according to the template's section structure, Chinese section headings, and table format. Do not change it to an English structure or English headings on your own.

Template Reference：{DOCS_REPO}/assets/templates/proposal.md

• Basic information table (requirement ID / source / priority / status)
• Target release version table (version / basis for judgment / committed or not / subsequent source of truth)
• Original problem description
• User/developer pain point table
• Expected results list
• Background and evidence table (competitive analysis link, code analysis link)
• Initial scope (possibly included / explicitly excluded)
• Initial assumptions table (assumption / type / verification method / status)

Phase 1.5: Requirements Clarification (multi-round dialogue) ⭐ Required · Mandatory decision point

After the first chapter of proposal.md is generated, you must enter the requirements clarification stage. Skipping is not allowed.

Clarification is a round-by-round dialogue, not a one-time form-filling. The main Session must proactively ask the user questions and wait for the user's reply before continuing.

主 Session:
  1. 从 proposal.md 第一章提取所有"待澄清/待验证"项：
     - 初始假设表中的「待验证」条目
     - 初始范围中的模糊描述
     - 用户痛点中需要确认的细节
     - 目标设备/OHOS 版本的默认值是否正确
     - 初始分级判断是否有依据不足的项
     - 复杂度判断是否需要更多信息
  2. 将待澄清项整理为编号问题清单（Q-1, Q-2, ...），每项包含：
     - 具体问题
     - 为什么需要澄清（对后续设计的影响）
  3. 向用户展示问题清单，**逐条或分批提问**
  4. 记录用户回答到 proposal.md 第二章「澄清记录」：
     - 更新「待澄清问题」表的状态（待澄清 → 已确认/已排除/待定）
     - 追加「讨论记录」
     - 更新「功能范围确认」「子系统影响」「API 变更评估」等表
     - 更新「初始假设」表的状态（待验证 → 已验证/已否定/需补充信息）
  5. 每轮澄清后检查：是否产生了新的待澄清项？
     - 是 → 继续下一轮澄清
     - 否 → 检查进入设计条件

Conditions for completing clarification (all must be met before entering Phase 2):

• The status of all questions to be clarified is not "to be clarified" (confirmed/excluded/pending but known to the user)
• All initial assumptions have conclusions (verified/refuted/user accepts the risk)
• Functional scope is fully confirmed
• Subsystem impacts have been initially identified
• There is a clear judgment on the complexity level (or a "pending" reason confirmed by the user)

Clarification principles:

• Do not guess: If uncertain, you must ask; do not use "default", "speculation", or "high probability" to replace user confirmation
• Not overloaded: Limit each round of questioning to 3-5 core questions, avoiding listing all questions at once
• Prioritized: First clarify the questions that directly affect solution selection, then clarify details
• Traceable: The conclusions of each round of clarification are recorded in Chapter 2 of proposal.md, without losing information
• Interruptible: The user can add new information at any time, and the main Session returns to the clarification stage to update the record

Note: The "Chapter 2: Clarification Record" in the proposal.md template already includes a complete record structure (pending clarification question table, discussion record, functional scope confirmation, subsystem impact, API change assessment, compatibility requirements, dependencies and risks, etc.). The main Session can simply fill in each item according to the template structure.

Phase 2: Requirements Analysis — knowledge base retrieval + expert team + brainstorm + code-analysis

Phase 2 is divided into five steps:

Step 2.0: Knowledge base retrieval (executed by the main Session)

[Mandatory] Before spawning any subagent, the main Session must first perform knowledge base retrieval and produce a "knowledge base evidence package".

Fallback strategy (try level by level in order of priority, see _shared/KB_RULES.md）：

Priority	Data source	Execution method
🥇 First choice	oh-chromium-knowledge	GitCode API read index.json → search/by_feature.json → routing_table.json
🥇 First choice	oh-ai-full-design	GitCode API read index.json → search/by_keyword.json → subsystems/ → components/
🥈 Second choice	DeepWiki MCP	read_wiki_structure → read_wiki_contents → ask_question
🥉 Last resort	Local documents	grep search {DOCS_REPO}/analysis/*.md and {DOCS_REPO}/references/*.md
🏅 Final	Clone repository	git clone --depth=1 to {DOCS_REPO}/tmp/ then search

The two 🥇 knowledge bases are used complementarily: oh-chromium-knowledge focuses on Chromium kernel implementation, and oh-ai-full-design focuses on the HarmonyOS component system. For Chromium code paths, prioritize the former; for subsystems/components/APIs, prioritize the latter. oh-ai-full-design is a private repository; skip it when you do not have permission.

Execution steps:

1. Extract requirement keywords from proposal.md in Phase 1
2. 🥇 Read skills/oh-chromium-knowledge/SKILL.md to obtain the knowledge base read protocol
3. 🥇 Follow index.json → search/by_feature.json → routing_table.json process to retrieve and match requirement keywords
4. 🥇 Read the oh-ai-full-design knowledge base, and retrieve according to index.json → search/by_keyword.json → subsystems/ → components/ process (skip if you do not have permission)
5. Record hit results (related repositories, modules, code paths, architecture documents, subsystems/components/APIs)
6. 🥈 For requirement keywords not covered by 🥇, use DeepWiki MCP for supplementary retrieval
7. 🥉 For details not covered by either 🥇 or 🥈, search local documents
8. 🏅 If there are still uncovered items, clone repositories as needed
9. Summarize as a "knowledge base evidence package" in the following format:

## 知识库证据包

### 🥇 oh-chromium-knowledge
- 匹配的功能类型: {type}（来自 search/by_feature.json）
- 相关代码路径: {paths}（来自 routing_table.json）
- 架构约束: {summary}（来自 architecture.md）
- 未覆盖项: {items}

### 🥇 oh-ai-full-design
- 匹配的子系统/部件: {subsystem/component}
- 相关 API: {apis}
- SystemCapability: {syscap}
- 未覆盖项: {items}（或：无权限，已跳过）

### 🥈 DeepWiki 补充
- 仓库: {repo} → 搜索 "{keyword}" → {发现摘要}
- 未覆盖项: {items}

### 🥉 本地文档补充
- 文档: {path} → {发现摘要}
- 未覆盖项: {items}

### 🏅 克隆仓库（如有）
- 仓库: {repo} → 搜索 "{keyword}" → {发现摘要}

1. [Mandatory persistence] Write the complete evidence package (including all original retrieval content) to {DOCS_REPO}/tmp/arkweb_kb_evidence_{YYYYMMDD_HHmmss}_{feature}.md. See _shared/KB_RULES.md Section 11 "Evidence Package Persistence".

• The file must contain each data source'soriginal retrieval results(complete JSON, text, code snippets); saving only summaries is not allowed
• First Write to {DOCS_REPO}/tmp/, then inject the evidence package content into the subagent
• If subsequent phases need to reuse the evidence package, preferentially read the existing file from {DOCS_REPO}/tmp/ Read existing file

This evidence package will be injected into the task descriptions of all subsequent subagents (expert panel, code-analysis, brainstorm). At the same time, the evidence package file path will also be passed to the subagents, so that subagents can recover from the file when context is lost.

Step 2.1: Expert panel relevance weight determination

Before spawning, the main Session first determines the relevance level of each expert:

Weight rules:

1. Core expert(weight 3x): domain experts directly related to the requirement, whose opinions have the highest priority during aggregation
2. Related expert(weight 2x): domain experts indirectly related to the requirement, whose opinions have reference value
3. Observer expert(weight 1x): domain experts basically unrelated to the requirement, who only supplement from a general perspective

Determination method:

• 🟢 Core expert: the main functionality of the requirement directly belongs to this expert's domain → spawn directly
• 🟡 Related expert: the requirement may indirectly affect this expert's domain → spawn directly
• ⚪ Observer expert: the requirement is basically unrelated to this expert's domain → skip if more than 5 (save resources)

Discussion control:

• The opinion length of core experts should account for 40%+ of the total opinions
• The opinion length of related experts should account for 30%
• Observer experts only need to briefly state their position (1-2 points), not exceeding 30%

Step 2.2: Parallel — expert panel discussion + code-analysis

The main Session simultaneously spawns the following subagents:

Expert panel (one subagent per expert)

sessions_spawn(
    task="""
    你是 ArkWeb 领域的{角色名}专家。请分析以下需求，从你的专业角度给出意见。

    1. 读取你的 skill 文件：{skill_path}
    2. 按 skill 定义的输出格式给出意见

    ## 用户需求
    {user_requirement}

    ## 约束条件
    - 目标设备：{device_scope}
    - OHOS 版本：{ohos_versions}

    ## 知识库证据包（主 Session 已检索完成）

    以下是通过知识库降级策略检索到的证据，你必须在意见中引用相关证据。

    {kb_evidence_package}

    **证据包持久化文件（上下文丢失时可从此文件恢复）**：
    {DOCS_REPO}/tmp/arkweb_kb_evidence_{timestamp}_{feature}.md

    直接输出你的专家意见，不需要保存文件。
    """,
    mode="run",
    label="expert-{expert_id}"
)

Expert spawn list:

#	Expert ID	Role	Skill path
1	arkweb-expert-performance	⚡ Performance expert	.skills/arkweb-experts/arkweb-expert-performance/SKILL.md
2	arkweb-expert-multimedia	🎬 Multimedia expert	.skills/arkweb-experts/arkweb-expert-multimedia/SKILL.md
3	arkweb-expert-peripheral	🔌 Peripheral service expert	.skills/arkweb-experts/arkweb-expert-peripheral/SKILL.md
4	arkweb-expert-interaction-security	🔐 Interaction security expert	.skills/arkweb-experts/arkweb-expert-interaction-security/SKILL.md
5	arkweb-expert-rendering	🎨 Rendering engine expert	.skills/arkweb-experts/arkweb-expert-rendering/SKILL.md
6	arkweb-expert-compositing	🖼️ Rendering compositing expert	.skills/arkweb-experts/arkweb-expert-compositing/SKILL.md
7	arkweb-expert-interaction-motion	✨ Interaction expert (scrolling/zooming/menus/selection/dragging/uploading/focus/filling/AI-ification)	.skills/arkweb-experts/arkweb-expert-interaction-motion/SKILL.md
8	arkweb-expert-network	🌐 Network loading expert	.skills/arkweb-experts/arkweb-expert-network/SKILL.md
9	arkweb-expert-js-engine	⚙️ JS engine expert	.skills/arkweb-experts/arkweb-expert-js-engine/SKILL.md
10	arkweb-expert-stability	🛡️ Stability and DFX expert	.skills/arkweb-experts/arkweb-expert-stability/SKILL.md

According to the relevance determination in Step 1.0, skip observer experts (if more than 5).

Sub-2: code-analysis (unchanged)

sessions_spawn(
    task="""
    你是 ArkWeb 代码分析师。请执行以下任务：

    1. 读取 skill 文件：.skills/arkweb-code-analysis/SKILL.md
    2. 按 SKILL.md 的流程执行代码分析

    ## 需求关键词
    {tech_keywords_from_requirement}

    ## 分析范围
    - ace_engine: Web 组件相关代码
    - web_webview: NWeb API 相关代码
    - chromium_src: 内核相关代码（如涉及）

    ## 数据源（按优先级使用）

    降级策略及认证方式详见 `_shared/KB_RULES.md`。

    ### 🥈 DeepWiki 在线索引
    - OpenHarmony ACE Engine: https://deepwiki.com/openharmony/arkui_ace_engine
    - OpenHarmony WebWebView: https://deepwiki.com/openharmony/web_webview
    - Chromium: https://deepwiki.com/niclas-ahden/chromium-source-code

    ### 🥉 本地分析文档（复用）
    - {analysis_dir}arkweb-ace-engine-analysis.md
    - {analysis_dir}web-webview-analysis.md
    - {analysis_dir}chromium-arkweb-analysis.md

    ## 知识库证据包（主 Session 已检索完成）

    以下是通过知识库降级策略检索到的证据，在分析中引用相关证据。

    {kb_evidence_package}

    **证据包持久化文件（上下文丢失时可从此文件恢复）**：
    {DOCS_REPO}/tmp/arkweb_kb_evidence_{timestamp}_{feature}.md

    ## 输出
    将分析结果保存到：
    {analysis_dir}{date}-{feature}-analysis.md

    文档必须包含：
    - 相关文件清单（路径 + 职责）
    - 关键类和接口签名
    - 现有代码中与本需求相关的逻辑
    - 对设计方案的技术可行性评估

    完成后回复文档路径和关键发现摘要。
    """,
    mode="run",
    label="code-analysis"
)

The main Session waits for all experts + code-analysis subagents to complete:

sessions_yield()  # 等待 subagent 结果推送

Step 2.3: Collect expert opinions

Wait for all expert subagents to complete, and the main Session aggregates them into the "Expert Panel Discussion Summary":

1. Categorize and organize: classify expert opinions as "adopt/reference/temporarily not considered"
2. Extract consensus: issues jointly focused on by multiple experts
3. Identify conflicts: differences of opinion among different experts
4. Weight annotation: annotate each expert opinion with a weight level (🟢/🟡/⚪)

Summary format:

## 🧠 专家团讨论纪要

### 共识（3+专家一致）
- {共识1}

### 高价值建议（2专家提出）
- {建议1}

### 分歧与权衡
- {分歧1}：{专家A} 认为... vs {专家B} 认为... → 结论：{总架构师裁定}

### 领域特定关切
- ⚡ 性能：{关键点}
- 🎬 多媒体：{关键点}
- ...

### 对方案的影响
- 采纳的专家意见将如何影响方案设计

Step 2.4: brainstorm

spawn the brainstorm subagent, with the expert panel discussion summary directly included in the task description:

sessions_spawn(
    task="""
    你是 ArkWeb 需求分析师。请执行以下任务：

    1. 读取 skill 文件：.skills/arkweb-brainstorm/SKILL.md
    2. 按 SKILL.md 的流程执行需求拆解（**跳过专家团讨论步骤**，因为已在 Phase 2 完成）

    ## 用户需求
    {user_requirement}

    ## 约束
    - 目标设备：{device_scope}
    - OHOS 版本：{ohos_versions}

    ## 参考资料（按需读取）
    - 架构参考：{references_dir}arkweb-architecture.md
    - 兼容性检查：{WORK_HOME}/docs/api-compatibility-check-arkweb.md
    - 代码分析报告：{analysis_dir}{date}-{feature}-analysis.md

    ## 知识库证据包（主 Session 已检索完成）

    以下是通过知识库降级策略检索到的证据，你必须在方案设计中引用相关证据，并在文档末尾输出「知识证据清单」。

    {kb_evidence_package}

    **证据包持久化文件（上下文丢失时可从此文件恢复）**：
    {DOCS_REPO}/tmp/arkweb_kb_evidence_{timestamp}_{feature}.md

    ## 专家团讨论纪要（已由主 Session 收集完成）

    以下是领域专家的意见汇总，你必须在方案设计中标注采纳了哪些专家建议。

    {expert_opinions_summary}

    ## 输出
    将完整的 brainstorm 文档保存到：
    {docs_dir}{feature-name}/{date}-{feature}-brainstorm.md

    文档必须包含：
    - 需求理解（问题现象 + 根因分析）
    - 2-3 个可选方案（含对比矩阵）
    - 推荐方案及理由
    - 交互场景补充分析（如拖拽/滚动等）
    - 专家团讨论纪要（含各专家意见、权重标注及采纳情况）
    - 知识证据清单（引用知识库证据包中的条目）

    完成后回复文档路径和方案摘要。
    """,
    mode="run",
    label="brainstorm"
)

The main Session waits for the brainstorm subagent to complete:

sessions_yield()  # 等待 Sub-1 结果推送

🔀 Decision 1: Confirm the plan (expert panel opinions already included)

主 Session:
  1. 读取 Sub-1 输出的 brainstorm.md（内含专家团讨论纪要）
  2. 读取 Sub-2 输出的 analysis.md（关键发现）
  3. 将方案摘要 + 专家团关键建议 + 代码分析发现呈现给用户
  4. 等待用户选择：
     a) 确认方案 X → 进入 Phase 3（需求基线）
     b) 修改方案 → 重新 spawn Sub-1（附修改意见 + 专家纪要）
     c) 需要更多信息 → 补充后重新启动 Phase 2

Phase 3: Requirements Baseline (append to proposal.md) ⭐ Required · Core document

After the plan is confirmed, generate a stable requirements baseline document. This is thecore requirements document— all subsequent processes (review, code generation, spec extraction) are based on this document.

主 Session:
  1. 从以下输入提取需求基线：
     - proposal.md 第一章（原始痛点 + 背景）
     - brainstorm.md（确认方案 + 专家意见）
     - analysis.md（技术可行性）
  2. 追加 proposal.md 第二章和第三章：
     - 问题陈述（痛点 + 根因）
     - 目标和成功指标表
     - 用户故事表（Story ID / 故事 / 优先级）
     - 验收标准表（AC编号 / 描述 / 类型 / 关联Story）
     - 不做范围清单
     - 关键假设与验证结果
  3. 保存为 {docs_dir}/proposal.md

File path: docs/features/{feature-name}/proposal.md

[Mandatory] Before appending the proposal.md baseline section, you must first read the template file {DOCS_REPO}/assets/templates/proposal.md, and fill it in strictly according to the template's section structure and Chinese section titles. Do not change it to an English structure or English titles on your own.

Template reference：{DOCS_REPO}/assets/templates/proposal.md

• Basic information table (Requirements ID / Related original requirements / Baseline version / Confirmer)
• Problem statement (one paragraph summarizing the pain point + root cause + competitor gap)
• Goals and success metrics table (Goal / Metric / Verification method)
• User story table
• Acceptance criteria table (including normal/exception/compatibility counterexamples)
• Out-of-scope list
• Initial assumptions table (Assumption / Type / Verification method / Owner / Status)

Non-applicable items confirmation

The main Session presents the user with the various dimensions involved in the requirements, so the user can confirm item by item which ones are not applicable:

Standard confirmation checklist

#	Dimension	Option	Description
1	Target device	Full coverage / Specified devices	Phone/Tablet/PC/2in1/Smart screen/Watch/Car head unit/IoT
2	OHOS version	All / Specified version	API Level range
3	Performance metrics	Applicable / Not applicable	Whether there are explicit performance baseline requirements
4	Security and privacy	Applicable / Not applicable	Sandbox/Permissions/Data security
5	Accessibility	Applicable / Not applicable	Large font/Screen reader/Elder-friendly
6	Globalization	Applicable / Not applicable	Multilingual/Mirrored layout
7	1+8 device differences	Applicable / Not applicable	Whether a difference table needs to be filled in per device
8	Compatibility	Applicable / Not applicable	Impact on existing APIs
9	DFX (crash/ANR/logs)	Applicable / Not applicable	Stability-related design
10	Power consumption	Applicable / Not applicable	Battery/Heat impact

After user confirmation, mark the "not applicable" dimensions as N/A and pass them to Sub-3 (design-doc); the corresponding sections in the design document only need to be filled in as "not applicable".

Phase 4: Design document

spawn Sub-3：

sessions_spawn(
    task="""
    你是 ArkWeb 设计文档撰写者。请执行以下任务：

    1. 读取 skill 文件：.skills/arkweb-design-doc/SKILL.md
    2. 按 SKILL.md 的流程生成两个设计文档

    ## 确认的方案（来自决策 1）
    {confirmed_plan_details}

    ## 不涉及项确认
    以下维度已确认为"不涉及"，对应章节只需填写"不涉及"即可：
    {na_dimensions_list}

    ## 需求基线（读取此文件）
    docs/features/{feature-name}/proposal.md

    ## 代码分析结果（读取此文件）
    {analysis_dir}{date}-{feature}-analysis.md

    ## 参考资料（按需读取）
    - 架构参考：{references_dir}arkweb-architecture.md
    - ACE Engine 索引：{analysis_dir}arkweb-ace-engine-analysis.md
    - 兼容性检查：{WORK_HOME}/docs/api-compatibility-check-arkweb.md
    - brainstorm 文档：{docs_dir}{feature-name}/{date}-{feature}-brainstorm.md

    ## 知识库证据包（主 Session 已在 Phase 2 检索完成）

    以下是通过知识库降级策略检索到的证据，在设计文档中引用相关证据。

    {kb_evidence_package}

    **证据包持久化文件（上下文丢失时可从此文件恢复）**：
    {DOCS_REPO}/tmp/arkweb_kb_evidence_{timestamp}_{feature}.md

    ## 输出
    【强制】生成文档前，必须先读取以下模板文件，严格按模板的章节结构、中文章节标题、表格格式填充内容：
    1. `{DOCS_REPO}/assets/templates/requirement.md`
    2. `{DOCS_REPO}/assets/templates/design.md`
    不得自行改为英文结构或英文标题。

    按设计文档 skill 的产出规范，生成两个文档：
    1. requirement.md：需求基线评审文档
    2. design.md：架构设计文档

    保存到：docs/features/{feature-name}/

    requirement.md 必须包含：
    - 需求描述（功能范围 + 典型场景 + 验收标准）
    - 功能设计（ASCII 架构图 + 类图 + 时序图）
    - 接口设计（参数表 + 示例代码）
    - 设备矩阵（1+8 设备差异表）
    - DFX 六维度分析
    - 性能功耗设计
    - 安全隐私设计

    design.md 必须包含：
    - 设计元数据
    - 涉及仓和模块
    - 关键设计决策（ADR）
    - 设计骨架（架构图 + 骨架 Spec 拆分）
    - 风险和开放问题

    注意：不涉及项对应章节填写"不涉及"即可，无需展开。

    完成后回复两个文档的路径和结构摘要。
    """,
    mode="run",
    label="design-doc"
)

Phase 5: Document review ⭐ Required

Merge the original Phase 3 (technical review) and Phase 3.5 (Checklist compliance inspection) into a single review. Sub-4 simultaneously performs the technical review and the 14-item Checklist inspection, producing a unified review.md.

spawn Sub-4：

sessions_spawn(
    task="""
    你是 ArkWeb 文档评审专家。请执行以下任务：

    1. 读取 skill 文件：.skills/arkweb-spec-review/SKILL.md
    2. 按 SKILL.md 的流程评审设计文档

    ## 待评审文档
    - requirement.md：{DOCS_REPO}/docs/features/{feature-name}/{date}-{feature}-requirement.md
    - design.md：{DOCS_REPO}/docs/features/{feature-name}/{date}-{feature}-design.md

    ## 代码分析结果（用于交叉验证）
    {analysis_dir}{date}-{feature}-analysis.md

    ## 参考资料（按需读取）
    - ACE Engine 索引：{analysis_dir}arkweb-ace-engine-analysis.md
    - WebWebView 分析：{analysis_dir}web-webview-analysis.md

    ## 评审维度

    ### Part A: 技术评审（原 Phase 3）
    1. 完整性检查（10 项）
    2. 一致性检查（6 项）
    3. 技术可行性检查（5 项）
    4. DFX 完整性（6 项）
    5. 文档规范（4 项）

    ### Part B: Checklist 规范性检视（原 Phase 3.5）
    按 14 条 Checklist 规则验证功能设计说明书的符合性，以资深软件设计质量分析师视角检视。

    ## 输出
    将评审报告保存到：
    {docs_dir}{feature-name}/{date}-{feature}-review.md

    报告必须包含：
    - 评审结果：通过 / 需修改 / 不通过
    - Part A 问题清单（🔴必须修改 / 🟡建议修改 / 🟢优秀实践）
    - Part B Checklist 检视结果（🔴必须修改 / 🟡建议修改 / ✅通过）
    - 统计数据（总检查项 / 通过 / 问题数）

    完成后回复文档路径和评审结果摘要。
    """,
    mode="run",
    label="spec-review"
)

🔀 Decision 2: Review decision (mandatory quality gate)

主 Session:
  1. 读取 Sub-4 输出的 review.md
  2. 将评审结果呈现给用户：
     - Part A：🔴 必须修改项 + 🟡 建议修改项 + 🟢 优秀实践
     - Part B：Checklist 检视结果
     - 统计数据（总检查项 / 通过 / 问题数）
  3. 根据结果决定：

     ┌─ 有 🔴 必须修改项 ──────────────────────────────────────────────────┐
     │ a) 强制修复：必须修复所有 🔴 项后才能继续。                          │
     │    → 回到 Phase 4 修改设计文档（附评审报告 + 修复清单）           │
     │    → 修复后必须重新 spawn Sub-4 复审                           │
     │    → 复审仍有 🔴 → 继续修复，直到所有 🔴 清零                      │
     │    → 此路径不允许跳过                                          │
     ├──────────────────────────────────────────────────────────────────┤
     │ b) 回到需求/方案阶段（Phase 1 或 Phase 2）：                         │
     │    如果 🔴 问题不是文档层面的，而是涉及需求理解或方案设计：          │
     │                                                                   │
     │    → 回到 Phase 1（需求基线）：                                   │
     │      - 需求理解偏差、用户故事不完整、验收标准缺失                  │
     │      - 目标发行版本/优先级/范围定义错误                            │
     │      → 保留 brainstorm 和 code-analysis 结果（不需要重做）          │
     │      → 仅追加/修改 proposal.md 的需求基线部分                    │
     │                                                                   │
     │    → 回到 Phase 2（方案设计）：                                   │
     │      - 方案选型错误、架构设计不合理、接口设计有问题                  │
     │      - 多个方案都有严重缺陷，需要重新设计                          │
     │      → 保留 proposal.md 和 code-analysis 结果                   │
     │      → 重新 brainstorm 时附上：上次方案的问题 + 评审报告          │
     │                                                                   │
     │    → 判断依据（定性为主，数量为辅）：                             │
     │      - 问题性质 > 问题数量（一个关键架构 🔴 > 十个文档格式 🔴）     │
     │      - 🔴 涉及需求/方案/架构/接口 → 回到 Phase 1 或 2               │
     │      - 🔴 仅涉及文档格式/遗漏/描述 → Phase 4 修复即可              │
     │    → 回到 Phase 1 或 2 时，保留已有分析结果和评审记录               │
     ├──────────────────────────────────────────────────────────────────┤
     │ c) 仅 🟡 建议修改项 ───────────────────────────────────────────────┤
     │    → 询问用户：                                                  │
     │      1) 修改后继续 → 回到 Phase 4 修改 → 可选复审                │
     │      2) 接受现状继续 → 进入 Phase 6（记录为「有条件通过」）         │
     │      3) 回到需求/方案 → 回到 Phase 1 或 Phase 2（理由记录）         │
     ├──────────────────────────────────────────────────────────────────┤
     │ d) 全部通过（无 🔴，🟡 可选） ────────────────────────────────────┤
     │    → 进入 Phase 6                                                │
     │    → 如果有 🟡 未处理项，记录到 spec.md 的「已知限制」章节        │
     └──────────────────────────────────────────────────────────────────┘

Basis for the review decision

When the review result is "Needs Revision", the main Session must determine the fix path:

🔴 Issue Characteristics	Suggested Path	Reason
Requirement misunderstanding / missing user stories	Return to Phase 1	The requirement baseline is problematic; the brainstorm foundation is incorrect
Incomplete acceptance criteria / incorrect scope definition	Return to Phase 1	The Phase 3 requirement baseline needs correction
Incorrect solution selection / unreasonable architecture	Return to Phase 2	Document-level fixes cannot solve the root problem
Interface design contradicts requirements	Return to Phase 1	Both the requirement baseline and the solution need to be realigned
Document format / missing sections / unclear description	Phase 4 fix	Does not involve requirement/solution changes
Example code / parameter table incomplete	Phase 4 fix	Just supplement it
Insufficient DFX / compatibility analysis	Phase 4 fix	Just supplement the analysis

Review record traceability

Review records are carried by the review.md of Sub-4 (spec-review); proposal.md is not modified additionally.

After each review decision, append a review decision record to review.md:

## 评审决策记录

### 评审 1（Phase 5）
- 日期：YYYY-MM-DD
- 评审结果：需修改（🔴 3 项 / 🟡 5 项 / 🟢 12 项）
- 决策：Phase 4 修复（文档层面问题，不涉及方案变更）
- 🔴 修改项：[简要列出]

### 评审 2（Phase 5 复审）
- 日期：YYYY-MM-DD
- 评审结果：有条件通过（🟡 2 项未处理）
- 决策：进入 Phase 6
- 🟡 未处理项：[简要列出，记录到 spec.md 已知限制章节]

Note: review.md is the output of Sub-4; simply append the review record to the end of review.md, no need to create a new file. If the decision is "Return to Phase 1 or Phase 2", append a brief record in proposal.md explaining the reason for the rollback and the date.

Fix loop: Issues found in review can return to Phase 1 (requirement baseline), Phase 2 (solution design), or Phase 4 (design document). After modification, Phase 5 review must be run again. It is not allowed to skip 🔴 must-fix items and go directly to Phase 6.

Skip prevention mechanism: When Sub-4 returns 🔴 must-fix items, the main Session must clearly present the fix plan and wait for user confirmation. Do not provide an "ignore and continue" option.

Phase 6: Unified Spec Generation⭐ Required

After the review passes, spawn Sub-10 to generate the unified spec.md and task.md. spec.md is a 4-in-1 structured specification document and serves as the only Spec input for Sub-7 (code-gen). task.md is the execution plan for AC→Task traceability.

spawn Sub-10：

sessions_spawn(
    task="""
    你是 ArkWeb Spec 生成工程师。请执行以下任务：

    1. 读取 skill 文件：.skills/arkweb-spec-gen/SKILL.md
    2. 按 SKILL.md 的流程生成统一 Spec 和执行计划

    ## 输入文档（全部读取）
    - proposal.md：{DOCS_REPO}/docs/features/{feature-name}/proposal.md
    - requirement.md：{DOCS_REPO}/docs/features/{feature-name}/{date}-{feature}-requirement.md
    - design.md：{DOCS_REPO}/docs/features/{feature-name}/{date}-{feature}-design.md
    - review.md：{DOCS_REPO}/docs/features/{feature-name}/{date}-{feature}-review.md
    - analysis.md：{DOCS_REPO}/analysis/{date}-{feature}-analysis.md

    ## 评审遗留项
    如果 review.md 中有 🟡 未处理项，记录到 spec.md 的「已知限制」章节。

    ## 输出
    【强制】生成文档前，必须先读取以下模板文件，严格按模板的章节结构、中文章节标题填充内容：
    1. `{DOCS_REPO}/assets/templates/spec.md`
    2. `{DOCS_REPO}/assets/templates/task.md`
    不得自行改为英文结构或英文标题。

    1. spec.md（4 合 1：架构设计 / 接口规格 / 特性规格 / 任务规格）
       保存到：docs/features/{feature-name}/spec.md
    2. task.md（AC→Task 追溯 + Task 详情 + 停止条件）
       保存到：docs/features/{feature-name}/task.md

    完成后回复两个文档的路径和结构摘要。
    """,
    mode="run",
    label="spec-gen"
)

The main Session waits for Sub-10 to complete:

sessions_yield()

Phase 7: Code Generation (Spec-driven)

spawn Sub-7：

sessions_spawn(
    task="""
    你是 ArkWeb 代码生成工程师。请执行以下任务：

    1. 读取 skill 文件：.skills/arkweb-code-gen/SKILL.md
    2. 按 SKILL.md 的流程生成实现代码

    ## 设计文档（读取这些文件）
    - requirement.md：{DOCS_REPO}/docs/features/{feature-name}/{date}-{feature}-requirement.md
    - design.md：{DOCS_REPO}/docs/features/{feature-name}/{date}-{feature}-design.md

    ## 统一 Spec（读取此文件）
    {docs_dir}{feature-name}/spec.md

    **重要：代码生成时优先依据 spec.md 中的结构化定义，设计文档作为上下文补充。接口签名、参数约束、行为场景必须与 Spec 一致。**

    ## 代码分析结果（读取此文件）
    {analysis_dir}{date}-{feature}-analysis.md

    ## 目标仓库
    - 路径：{SKILL_HOME}/
    - 分支：feat/{feature-name}

    ## 生成范围
    - 核心实现代码（.cpp / .h / .ts / .ets 等）
    - 单元测试代码
    - BUILD.gn 修改（如需要）

    ## 输出
    1. 生成计划（文件清单）
    2. 实现代码文件
    3. 单元测试
    4. 自验证报告

    完成后回复生成摘要和验证结果。
    """,
    mode="run",
    label="code-gen"
)

The main Session waits for Sub-7 to complete:

sessions_yield()

🔀 Decision 3: Code Review

主 Session:
  1. 读取 Sub-7 输出的验证报告
  2. 将生成摘要 + 验证结果呈现给用户
  3. 等待用户审查：
     a) 通过 → 进入 Phase 8（Committer 检视）
     b) 要求修改 → 重新 spawn Sub-7（附修改意见）
     c) 需要查看具体代码 → 展示关键文件内容

Phase 8: Committer Review

After code generation, spawn Sub-8 to review code quality from the Committer perspective.

Sub-8: committer-review

sessions_spawn(
    task="""
    你是 ArkWeb 项目的 Committer。请对以下代码进行检视。

    1. 读取 skill 文件：.skills/arkweb-committer-review/SKILL.md
    2. 按 SKILL.md 的流程执行 Committer 检视

    ## 设计文档（读取这些文件）
    - requirement.md：{DOCS_REPO}/docs/features/{feature-name}/{date}-{feature}-requirement.md
    - design.md：{DOCS_REPO}/docs/features/{feature-name}/{date}-{feature}-design.md

    ## 生成代码目录
    {WORK_HOME}/implementation/{feature-name}/

    ## 代码分析结果（读取此文件）
    {analysis_dir}{date}-{feature}-analysis.md

    ## 输出
    将检视报告保存到：
    {docs_dir}{feature-name}/{date}-{feature}-committer-review.md

    完成后回复文档路径和检视结果摘要。
    """,
    mode="run",
    label="committer-review"
)

主 Session:
  1. 读取 Sub-8 输出的检视报告
  2. 呈现检视结果（问题清单 + 严重程度）
  3. 等待用户决定：
     a) 通过 → 进入 Phase 9（提交 PR）
     b) 要求修复 → 重新 spawn Sub-7（附检视报告）

Phase 9: Submit PR

Multi-repository PR coordination rules (mandatory compliance):

The code for this project is distributed across 3 repositories. When submitting PRs, the following rules must be followed:

1. Issue grouping: repositories at the same level share one Issue; different levels use separate Issues

   • Engine layer (chromium_src) → separate Issue, created in openharmony-tpc/chromium_src
   • Framework layer (web_webview + arkui_ace_engine) → share one Issue, created in openharmony/web_webview

2. PR direction: Must fork from the upstream original repository; self-merging within the fork is prohibited

   • {FORK_OWNER}/xxx:feat/xxx → openharmony(-tpc)/xxx:{base_branch}
   • The base branch of chromium_src is 132_trunk, while other repositories are master

3. PR template: Before creating a PR, you must first read the target repository's PULL_REQUEST_TEMPLATE.md(path see gitcode-pr skill), fill in the body according to the template format; custom formats are prohibited

4. Cross-references: Each PR's body must include the linked Issue link and the PR links of the other two repositories

5. Submission process: First create all Issues → read all templates → create all PRs → cross-reference each other

spawn Sub-9：

sessions_spawn(
    task="""
    你是 GitCode PR 提交助手。请执行以下任务：

    1. 读取 skill 文件：.skills/gitcode-pr/SKILL.md
    2. 按 SKILL.md 的流程执行提交流程

    ## 待提交文件
    {all_document_files_and_code_files}

    ## 提交信息
    - Issue 标题：feat: {feature-name} — {description}
    - Commit message: feat: {description}\n\n- {change_1}\n- {change_2}
    - PR body: 方案概述 + 评审记录 + Closes #{issue_number}
    - 分支名：docs/{feature-name}

    ## 仓库配置
    - 仓库：{owner}/{docs_repo}
    - 本地路径：{SKILL_HOME}/
    - Token：从环境变量读取（优先 `GITCODE_TOKEN`，回退 `GITLAB_TOKEN`）

    ## 输出
    1. Issue URL
    2. PR URL
    3. 提交状态

    完成后回复提交结果。
    """,
    mode="run",
    label="gitcode-pr"
)

主 Session:
  1. 读取 Sub-9 的提交结果
  2. 将 PR 信息呈现给用户
  3. 等待用户确认：
     a) 合并 → 执行合并 API
     b) 修改 → 重新 spawn Sub-9
     c) 拒绝 → 结束
  4. 合并完成 → ✅ 输出最终摘要

---

Decision point summary

#	Decision	Timing	Optional actions	Default behavior
1	Confirm the plan	Phase 2 (Sub-1 + Sub-2 completed)	Choose plan / modify / supplement information	Wait for user
2	Review decision	Phase 5 (Sub-4 completed, including technical review + Checklist)	🔴Mandatory fix / return to requirements (Phase 1) / return to plan (Phase 2) / 🟡Optional fix / conditional pass	🔴Cannot be skipped, 🟡ask the user
3	Code review	Phase 7 (Sub-7 completed)	Pass / request changes / view code	Wait for user

Decision points reduced from 9 to 3. The original decision points are streamlined to 3: plan confirmation (after Phase 2), review results (after Phase 5), code review (after Phase 7). The Spec review decision point is removed (spec is machine-consumed and does not require manual review). Committer inspection and PR submission are handled as in-process steps. Decision 2 adds a "return to requirements/plan design" path and an anti-skip mechanism.

---

Data flow

主 Session 直接生成（不通过 subagent）:
  Phase 1:   proposal.md 第一章（原始需求录入）
  Phase 1.5: proposal.md 第二章（澄清记录，多轮对话填充）
  Phase 3:   proposal.md 第三章（需求基线，追加到同一文件）
  Phase 2 Step 2.0: 知识库检索 → 产出「知识库证据包」（注入到后续所有 subagent）
  Phase 2 Step 2.0: 知识库证据包持久化 → Write 到 {DOCS_REPO}/tmp/arkweb_kb_evidence_{timestamp}_{feature}.md
  Phase 6:   spec.md（统一规格文档，4 合 1：架构设计/接口规格/特性规格/任务规格）

专家团（主 Session 直接调度，并行 spawn，接收知识库证据包）
  → 按相关度权重筛选专家（🟢核心/🟡关联/⚪旁听，旁听超 5 个跳过）
  → 各专家输出意见 → 主 Session 收集汇总
  → 生成「专家团讨论纪要」（含权重标注 + 共识/分歧/采纳情况）

Sub-1 (brainstorm)
  ← 输入: 专家团讨论纪要 + 用户需求 + 约束 + code-analysis 路径 + 知识库证据包
  → 读取专家纪要，将采纳的意见融入方案设计
  → 写入: docs/features/{feature-name}/{date}-{feature}-brainstorm.md（含专家讨论纪要 + 权重标注）
  → 主 Session 读取 → 呈现给用户 → 决策 1

Sub-2 (code-analysis)
  → 数据源：oh-chromium-knowledge + oh-ai-full-design（🥇）→ DeepWiki MCP（🥈）→ 本地文档（🥉）→ 克隆仓库（🏅）
  → 写入: analysis/{date}-{feature}-analysis.md
  → Sub-3 读取（作为参考资料）
  → Sub-4 读取（作为交叉验证）

Sub-3 (design-doc)
  → 读取: proposal.md + brainstorm.md + analysis.md + 不涉及项确认 + 参考资料
  → 写入: docs/features/{feature-name}/{date}-{feature}-requirement.md + {date}-{feature}-design.md
  → Sub-4 读取（作为评审对象）
  → Sub-7 读取（作为代码生成的依据）
  → Sub-8 读取（作为 Committer 检视的依据）

Sub-4 (spec-review) — v5 合并了原 Sub-4.5 的 Checklist 检视
  → 读取: requirement.md + design.md + analysis.md
  → 写入: docs/features/{feature-name}/{date}-{feature}-review.md
  → 主 Session 读取 → 呈现给用户 → 决策 2

Sub-10 (spec-gen)
  ← 读取: proposal.md + requirement.md + design.md + analysis.md + review.md
  → 写入: docs/features/{feature-name}/spec.md（统一规格文档，4 合 1）+ task.md
  → Sub-7 读取（作为代码生成的主要依据）

Sub-7 (code-gen)
  → 读取: requirement.md + design.md + spec.md + analysis.md
  → 写入: 实现代码 + 单元测试 + BUILD.gn
  → 主 Session 读取验证报告 → 呈现给用户 → 决策 3

Sub-8 (committer-review)
  → 读取: requirement.md + design.md + analysis.md + 生成代码
  → 写入: docs/features/{feature-name}/{date}-{feature}-committer-review.md

Sub-9 (gitcode-pr)
  → 读取: 所有文档文件 + 所有代码文件
  → 写入: GitCode Issue + PR

完整文档产出链路（核心）:
  proposal.md(Ch1) → [Phase 1.5 澄清] → proposal.md(Ch2) → brainstorm.md → requirement.md + design.md → review.md
  → spec.md → 实现代码 → committer-review.md → Issue + PR
  proposal.md(Ch3 需求基线) 在决策 1 后追加

---

⚠️ Problem prevention rules

When executing the process, the following rules must be followed:

Rule 1: Requirement clarification cannot be skipped

• After Phase 1 generates Chapter 1 of proposal.md,mustenter Phase 1.5 requirement clarification
• It is not allowed to use "default values", "speculation", or "high probability" in place of user confirmation
• Each round of clarification should be limited to 3-5 core questions, and all conclusions should be recorded in Chapter 2 of proposal.md
• Only after all clarification completion conditions are met can Phase 2 be entered

Rule 2: Subagent task descriptions must specify file paths

• In the subagent task, explicitly state "save to path X"; do not write vague descriptions like "save the document"
• If multiple files are to be generated, list the full path of each file in the task

Rule 3: Check git diff before commit

• Before git commit, run git diff --stat to confirm the scope of changes
• Check whether any unexpected files were modified or deleted

---

Mode switching

Condition	Mode
sessions_spawn Available + complex requirements	Mode A(Subagent orchestration)
sessions_spawn unavailable	Mode B (main session serially calls skill)
User requests serial execution	Mode B

In Mode B, the main session reads each SKILL.md in sequence and executes according to the workflow; after each skill completes, decisions are made within the current session.

---

Reference Resources

Documents	Paths
ACE Engine Analysis	analysis/arkweb-ace-engine-analysis.md
WebWebView Analysis	analysis/web-webview-analysis.md
Architecture Reference	references/arkweb-architecture.md
Compatibility Check	docs/api-compatibility-check-arkweb.md
Device Matrix	references/device-matrix.md
Competitive Analysis	references/competitor-analysis.md

Quick Entry

User Intent	Launched Subagent
"Help me analyze this requirement"	Expert team + Sub-1 brainstorm + Sub-2 code-analysis (parallel → collect → brainstorm)
"Generate design document"	Sub-3 design-doc
"Review this document"	Sub-4 spec-review (including Checklist review)
"Generate code"	Sub-7 code-gen
"Committer review"	Sub-8 committer-review
"Analyze xxx repository"	Sub-2 code-analysis
"Submit to GitCode"	Sub-9 gitcode-pr
"Full workflow"	Expert team + 8 subagents + 3 decision points