Feature/GitHub issue agent workflow

docs/plans/2026-03-21-github-issue-template-design.md

@@ -0,0 +1,164 @@
+# GitHub Issue Template Workflow Design
+
+## 背景
+当前仓库已经具备以下零散能力：
+- GitHub / GHE webhook 接入与 payload 归一化
+- task / template / trigger / worker 基础执行链路
+- `安全加密agent`、`des_encrypt`、`github_issue_feedback` 的雏形
+- Git 分支推送与 PR 创建能力
+
+但这些能力还没有收敛成一套可稳定执行的 “GitHub issue -> distribution agent -> worker agent -> 回帖 issue” 闭环。现状的主要问题是：
+- 模板、触发器、agent、skill 的协议不一致
+- `github_issue_number` 只在 mock 流程中稳定回填，真实 webhook 未闭环
+- `issue distribution agent` 还未成为统一入口
+- 当前 `安全加密agent` 依赖脚本和 prompt 零散拼装，缺少内置模板约束
+
+## 真实样本
+2026-03-21 通过 GHE API 拉取 `china/starbucks-asg-api#13` 的内容如下：
+- 标题：`安全加密`
+- 正文：`安全加密agent，对本项目的phone字段进行安全加密`
+- URL：`https://scm.starbucks.com/china/starbucks-asg-api/issues/13`
+
+该 issue 是本次首个真实验收样本，目标路由结果应为：
+- 命中 `github issue template`
+- 统一进入 `issue distribution agent`
+- 识别为安全加密类需求
+- 分发给 `安全加密agent`
+- worker 完成代码提交、推送分支、回帖 task URL 与分支名
+
+## 方案选择
+本次采用 “单模板入口 + 固定两阶段链路” 方案。
+
+### 方案说明
+1. 新增一个统一模板 `github_issue_template`
+2. 模板内固定两个阶段：
+   - `dispatch_issue` -> `issue distribution agent`
+   - `process_security_issue` -> `安全加密agent`
+3. 所有命中该模板的 GitHub issue 都先进入 distribution stage
+4. distribution stage 必须输出结构化分发结果
+5. 当前版本只支持一个 worker agent：`安全加密agent`
+6. 当 distribution 识别结果不是安全加密时，先产出明确的“不支持/待扩展”说明，不动态增删 stage
+
+### 采用该方案的原因
+- 与用户要求一致：统一进入 distribution agent
+- 能复用当前引擎，不需要先改动态编排核心
+- 便于未来增加更多 worker agent 时扩展 dispatch 协议
+- 风险可控，适合以 issue #13 为真实样本先落地
+
+## 目标能力
+### 1. 统一入口模板
+新增内置模板 `github_issue_template`，作为 GitHub issue 自动任务的标准入口。
+
+### 2. 两类 Agent 角色
+- `issue distribution agent`
+- `安全加密agent`
+
+### 3. 分发输出协议
+`issue distribution agent` 必须输出结构化结果，至少包含：
+- `selected_agent_role`
+- `intent`
+- `issue_number`
+- `issue_url`
+- `repo_full_name`
+- `task_title`
+- `work_summary`
+- `acceptance_criteria`
+- `dispatch_reason`
+
+### 4. worker 执行闭环
+`安全加密agent` 必须严格按对应 skill 执行：
+- 基于 `des_encrypt` skill 修改代码
+- 推送远端分支
+- 通过 `github_issue_feedback` skill 回帖 issue
+
+### 5. 任务可追踪性
+task 需要稳定保留 GitHub issue 关联信息，至少确保：
+- `github_issue_number`
+- issue URL / repo 信息进入 task 描述或 stage prompt
+- task 完成后可拼出 `http://127.0.0.1:3000/tasks/<task_id>` 形式的任务地址
+
+## 关键设计
+### 1. 模板定义
+`github_issue_template` 使用标准 `StageDefinition` 字段：
+- `name`: `dispatch_issue`
+- `agent_role`: `issue distribution agent`
+- `order`: `0`
+- `instruction`: 强调读取 GitHub issue 上下文并输出结构化分发结果
+
+- `name`: `process_security_issue`
+- `agent_role`: `安全加密agent`
+- `order`: `1`
+- `instruction`: 强调读取 dispatch 输出，仅处理安全加密任务，并回帖 issue
+
+### 2. Trigger 规则
+GitHub webhook 命中 `github_issue_template` 后：
+- 统一创建 task
+- 标题使用 issue 标题渲染
+- 描述中保留 issue URL、repo、作者、正文
+- 真实 webhook 路径与 mock webhook 路径都要写入 `github_issue_number`
+
+### 3. Distribution 行为
+`issue distribution agent` 的职责是识别 issue 意图，不直接改代码。当前支持规则：
+- 命中 “安全加密 / encryption / phone 字段加密” 等意图 -> `安全加密agent`
+- 其他意图 -> 输出 unsupported 说明，供后续扩 worker agent 时接入
+
+### 4. Worker 行为
+`安全加密agent` 的职责是执行，不重新决定路由。它接收的上下文应包含：
+- 原始 issue 标题、正文、URL、编号
+- repo 信息
+- distribution 产出的结构化工作单
+- 当前 task_id 与 task_url
+
+执行完成后必须回帖：
+- Git 分支名
+- Silicon Agent task URL
+
+### 5. Skill 目录与权限
+当前 worker 的技能分布在两个位置：
+- 仓库根目录 `skills/des_encrypt/SKILL.md`
+- 平台共享技能 `platform/skills/shared/github_issue_feedback/SKILL.md`
+
+因此需要让角色配置与 skill dir 白名单对齐，确保：
+- `issue distribution agent` 能加载 dispatch skill
+- `安全加密agent` 能同时加载 `des_encrypt` 与 `github_issue_feedback`
+
+### 6. 非目标
+本轮不做以下内容：
+- 不引入动态 stage 增删
+- 不实现多个 worker agent 的真正分流执行
+- 不要求 issue 回帖后自动关单
+- 不在本轮内重构整套 worker 架构
+
+## 失败处理
+- 若 distribution 无法识别意图，task 保持失败或输出明确阻塞原因，不允许假成功
+- 若 worker 未推送成功，不允许回帖成功态
+- 若代码已推送但回帖失败，task 应能从错误日志定位到 comment API 失败原因
+
+## 测试策略
+### 1. 单元 / 服务层
+- 内置模板 seed 正确创建
+- 内置 agent seed 正确创建
+- 真实 webhook 创建 task 时能保存 `github_issue_number`
+- task 描述中包含 issue 关键上下文
+
+### 2. mock webhook
+- 构造 GitHub issue payload，命中 `github_issue_template`
+- 验证创建出的 task stage 顺序与 agent_role 正确
+
+### 3. 真实 issue 样本
+- 使用 GHE API 拉取 `china/starbucks-asg-api#13`
+- 以真实 title/body 验证 distribution 识别结果应为 `安全加密agent`
+
+### 4. 闭环验证
+若当前环境具备仓库访问和推送条件，则继续验证：
+- task 被创建
+- worker 进入安全加密 stage
+- 分支被记录
+- issue 评论包含 task URL 和 branch
+
+## 交付结果
+本次设计通过后，实施阶段需要至少交付：
+- 一套稳定的 `github_issue_template`
+- 一套稳定的 distribution / security worker 协议
+- 一条可用的 GitHub issue 自动触发链路
+- 针对 issue #13 的验证与修复结果

docs/plans/2026-03-21-github-issue-template-workflow.md

@@ -0,0 +1,223 @@
+# GitHub Issue Template Workflow Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Build a stable `github_issue_template` workflow that routes every matched GitHub issue through `issue distribution agent`, dispatches security-encryption issues to `安全加密agent`, and posts branch plus Silicon task URL back to the originating issue.
+
+**Architecture:** Reuse the existing webhook -> trigger -> task -> worker pipeline, but formalize it with one built-in template, seeded agent roles, a fixed two-stage definition, and stable GitHub issue metadata propagation. Keep the first version intentionally static: distribution always runs first, while the security worker remains the only execution agent.
+
+**Tech Stack:** FastAPI, SQLAlchemy async ORM, Pydantic, existing worker engine, pytest, GitHub Enterprise REST API
+
+---
+
+### Task 1: Lock the spec and plan files into the repo
+
+**Files:**
+- Create: `docs/plans/2026-03-21-github-issue-template-design.md`
+- Create: `docs/plans/2026-03-21-github-issue-template-workflow.md`
+- Create: `platform/docs/specs/feature-009-GitHubIssue任务分发工作流/01_requirements.md`
+- Create: `platform/docs/specs/feature-009-GitHubIssue任务分发工作流/02_interface.md`
+- Create: `platform/docs/specs/feature-009-GitHubIssue任务分发工作流/03_implementation.md`
+
+**Step 1: Verify the new spec files exist**
+
+Run: `find docs/plans platform/docs/specs/feature-009-GitHubIssue任务分发工作流 -maxdepth 2 -type f | sort`
+Expected: all 5 files are listed
+
+**Step 2: Commit the documentation checkpoint**
+
+Run: `git add docs/plans/2026-03-21-github-issue-template-design.md docs/plans/2026-03-21-github-issue-template-workflow.md platform/docs/specs/feature-009-GitHubIssue任务分发工作流/01_requirements.md platform/docs/specs/feature-009-GitHubIssue任务分发工作流/02_interface.md platform/docs/specs/feature-009-GitHubIssue任务分发工作流/03_implementation.md && git commit -m "docs: define github issue template workflow"`
+Expected: commit created
+
+### Task 2: Write failing tests for built-in template and seeded agent definitions
+
+**Files:**
+- Modify: `platform/tests/test_template_service.py`
+- Modify: `platform/tests/test_agents_api.py`
+- Modify: `platform/tests/test_agents.py`
+- Modify: `platform/app/services/template_service.py`
+- Modify: `platform/app/services/seed_service.py`
+
+**Step 1: Write the failing template seed test**
+
+Add a test asserting a built-in template named `github_issue_template` exists and has exactly two ordered stages:
+- `dispatch_issue` / `issue distribution agent`
+- `process_security_issue` / `安全加密agent`
+
+**Step 2: Run the focused test to verify it fails**
+
+Run: `cd platform && pytest tests/test_template_service.py -k github_issue_template -v`
+Expected: FAIL because template is not seeded yet
+
+**Step 3: Write the failing agent seed test**
+
+Add tests asserting the seeded agent catalog contains:
+- `issue distribution agent`
+- `安全加密agent`
+
+And verify their configs include the skill directories and prompt append needed for dispatch / feedback behavior.
+
+**Step 4: Run the focused agent tests to verify they fail**
+
+Run: `cd platform && pytest tests/test_agents.py tests/test_agents_api.py -k "issue distribution agent or 安全加密agent" -v`
+Expected: FAIL because the roles are not seeded consistently yet
+
+**Step 5: Implement the minimal seed changes**
+
+Update the built-in template seed and the built-in agent seed path so the two new roles and the new template are created deterministically.
+
+**Step 6: Re-run the focused tests**
+
+Run: `cd platform && pytest tests/test_template_service.py tests/test_agents.py tests/test_agents_api.py -k "github_issue_template or issue distribution agent or 安全加密agent" -v`
+Expected: PASS
+
+**Step 7: Commit**
+
+Run: `git add platform/app/services/template_service.py platform/app/services/seed_service.py platform/tests/test_template_service.py platform/tests/test_agents.py platform/tests/test_agents_api.py && git commit -m "feat: seed github issue template agents"`
+
+### Task 3: Write failing tests for GitHub issue metadata propagation
+
+**Files:**
+- Modify: `platform/tests/test_webhook_project.py`
+- Modify: `platform/tests/test_mock_webhook.py`
+- Modify: `platform/tests/test_trigger_complex.py`
+- Modify: `platform/tests/test_task_service.py`
+- Modify: `platform/app/api/webhooks/github.py`
+- Modify: `platform/app/services/trigger_service.py`
+- Modify: `platform/app/services/task_service.py`
+- Modify: `platform/app/schemas/task.py`
+
+**Step 1: Write the failing project-webhook test**
+
+Add a test asserting a real GitHub issue webhook:
+- creates a task
+- stores `github_issue_number`
+- preserves issue URL and repo context inside task description or structured prompt input
+
+**Step 2: Write the failing mock-webhook regression test**
+
+Add a test asserting the same metadata is preserved when using `/mock-webhook`.
+
+**Step 3: Run the focused webhook tests to verify they fail**
+
+Run: `cd platform && pytest tests/test_webhook_project.py tests/test_mock_webhook.py -k "issue and github_issue_number" -v`
+Expected: FAIL because real webhook flow does not persist all issue metadata yet
+
+**Step 4: Implement the minimal metadata propagation**
+
+Update webhook normalization and trigger task creation so `issue_number`, `issue_url`, `repo_full_name`, and issue body flow into task creation consistently.
+
+**Step 5: Re-run the focused tests**
+
+Run: `cd platform && pytest tests/test_webhook_project.py tests/test_mock_webhook.py tests/test_task_service.py -k "github_issue_number or issue_url or repo_full_name" -v`
+Expected: PASS
+
+**Step 6: Commit**
+
+Run: `git add platform/app/api/webhooks/github.py platform/app/services/trigger_service.py platform/app/services/task_service.py platform/app/schemas/task.py platform/tests/test_webhook_project.py platform/tests/test_mock_webhook.py platform/tests/test_trigger_complex.py platform/tests/test_task_service.py && git commit -m "fix: propagate github issue metadata into tasks"`
+
+### Task 4: Write failing tests for dispatch and worker prompt contracts
+
+**Files:**
+- Modify: `platform/tests/test_prompts.py`
+- Modify: `platform/tests/test_worker.py`
+- Modify: `platform/app/worker/prompts.py`
+- Modify: `platform/app/worker/agents.py`
+
+**Step 1: Write the failing prompt contract test for distribution**
+
+Assert that the `dispatch_issue` stage instruction and `issue distribution agent` system prompt require structured dispatch output with `selected_agent_role`, `issue_number`, `repo_full_name`, `work_summary`, and `acceptance_criteria`.
+
+**Step 2: Write the failing prompt contract test for security worker**
+
+Assert that `process_security_issue` and `安全加密agent` require:
+- strict execution by skill
+- git branch push
+- GitHub issue feedback with branch and task URL
+
+**Step 3: Write the failing skill directory / tool exposure test**
+
+Assert that:
+- distribution agent can load shared dispatch skills
+- security worker can load both shared feedback skills and the repository-level `des_encrypt`
+- security worker has the tool permissions needed for code change and git execution
+
+**Step 4: Run the focused tests to verify they fail**
+
+Run: `cd platform && pytest tests/test_prompts.py tests/test_worker.py tests/test_agents.py -k "dispatch_issue or process_security_issue or 安全加密agent" -v`
+Expected: FAIL because current prompts and role configuration are incomplete
+
+**Step 5: Implement the minimal prompt and role updates**
+
+Update role prompts, stage instructions, and role skill/tool configuration so the contracts become explicit and testable.
+
+**Step 6: Re-run the focused tests**
+
+Run: `cd platform && pytest tests/test_prompts.py tests/test_worker.py tests/test_agents.py -k "dispatch_issue or process_security_issue or 安全加密agent" -v`
+Expected: PASS
+
+**Step 7: Commit**
+
+Run: `git add platform/app/worker/prompts.py platform/app/worker/agents.py platform/tests/test_prompts.py platform/tests/test_worker.py platform/tests/test_agents.py && git commit -m "feat: formalize github issue dispatch contracts"`
+
+### Task 5: Validate the real issue #13 classification path
+
+**Files:**
+- Modify: `platform/tests/test_integration_service.py`
+- Create: `platform/tests/test_github_issue_template_real_sample.py`
+
+**Step 1: Write a sample-backed test using issue #13 facts**
+
+Use the known issue facts:
+- repo `china/starbucks-asg-api`
+- issue number `13`
+- title `安全加密`
+- body `安全加密agent，对本项目的phone字段进行安全加密`
+
+Assert the dispatch stage contract would select `安全加密agent`.
+
+**Step 2: Run the focused test to verify the behavior**
+
+Run: `cd platform && pytest tests/test_github_issue_template_real_sample.py -v`
+Expected: PASS once prompt and metadata contracts are in place
+
+**Step 3: Commit**
+
+Run: `git add platform/tests/test_github_issue_template_real_sample.py platform/tests/test_integration_service.py && git commit -m "test: cover github issue template real sample"`
+
+### Task 6: End-to-end verification in the local environment
+
+**Files:**
+- Modify only if verification exposes a defect in existing implementation
+
+**Step 1: Run the main targeted backend suite**
+
+Run: `cd platform && pytest tests/test_template_service.py tests/test_mock_webhook.py tests/test_webhook_project.py tests/test_prompts.py tests/test_worker.py tests/test_agents.py tests/test_github_issue_template_real_sample.py -v`
+Expected: PASS
+
+**Step 2: Start or restart the local services if needed**
+
+Run: `./skills/start-project-services/scripts/start_services.sh`
+Expected: frontend and backend healthy
+
+**Step 3: Trigger a local mock GitHub issue for the new template**
+
+Run the project mock-webhook endpoint with a payload matching issue #13 semantics.
+Expected: task created with the two expected stages and the correct GitHub metadata
+
+**Step 4: If credentials and remote repo permissions are valid, run the real issue workflow**
+
+Expected:
+- `issue distribution agent` runs first
+- `安全加密agent` receives the dispatch context
+- branch name is recorded on the task
+- issue comment contains branch + task URL
+
+**Step 5: If any verification fails, fix with the same TDD loop before closing**
+
+Run: focused failing pytest target
+Expected: PASS after the fix
+
+**Step 6: Final commit**
+
+Run: `git add <touched files> && git commit -m "feat: complete github issue template workflow"`