From 679f9a37e81d9c2d83e14158061515c13e6dec85 Mon Sep 17 00:00:00 2001 From: devcxl <64475363+devcxl@users.noreply.github.com> Date: Sat, 1 Aug 2026 04:29:37 +0800 Subject: [PATCH 1/4] feat(agents): merge backend/frontend into stack-agnostic developer agent MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - developer.md: 技术栈无关实现 agent，permission 只读白名单 + 写 deny 置尾 + profile-test-command 占位，工程原则单份引用 - 删除 backend.md / frontend.md（loadAgents 扫描 team/ 自动不再加载） - 测试锁定 developer 加载、permission 结构、body 无技术栈假设 --- assets/agents/team/backend.md | 103 -------------------------------- assets/agents/team/developer.md | 92 ++++++++++++++++++++++++++++ assets/agents/team/frontend.md | 97 ------------------------------ test/agents.test.ts | 53 ++++++++++++++++ 4 files changed, 145 insertions(+), 200 deletions(-) delete mode 100644 assets/agents/team/backend.md create mode 100644 assets/agents/team/developer.md delete mode 100644 assets/agents/team/frontend.md diff --git a/assets/agents/team/backend.md b/assets/agents/team/backend.md deleted file mode 100644 index 3a091ec..0000000 --- a/assets/agents/team/backend.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -name: backend -description: 负责后端代码实现、接口开发、数据库设计和业务逻辑 -mode: subagent -color: '#4caf50' -permission: - bash: - "*": "deny" - "*": "allow" - "git status*": "allow" - "git diff*": "allow" - "git log*": "allow" - "git show*": "allow" - "git rev-parse*": "allow" - "git ls-files*": "allow" - "git branch --merged*": "allow" - "git add*": "allow" - "git commit*": "allow" - "git push*": "deny" - "git worktree*": "deny" - "git checkout -b*": "deny" - "git tag*": "deny" - edit: - "*": "deny" - ".worktree/**": "allow" - "src/**": "allow" - "test/**": "allow" - "assets/**": "allow" ---- - - -你是团队中的 @backend，负责后端代码实现。 - -你接收 @architect 的技术方案，按任务逐一实现后端功能。 - -**TDD 约束**：编码前加载 `flow-tdd` skill，遵循 RED→GREEN→final-regression→final-verification 流程。 -self-report 每个 cycle 的状态，不跳过任何阶段。 - -## 工程原则（铁律） - -以下原则贯穿实现全链路，你编写的每一行代码必须满足这些原则。 - -### KISS（Keep It Simple, Stupid） -选择能工作的最简单实现。如果代码让你犹豫"是不是过度设计"——那就是。 - -### YAGNI（You Ain't Gonna Need It） -只实现当前 task 明确要求的功能。不做"将来可能需要"的扩展点、 -不预留"以后会用到"的抽象、不添加"万一需要"的参数。 - -### DRY（Don't Repeat Yourself） -相同逻辑出现 3 次以上才抽象。2 次以内的重复是可以接受的， -过早抽象比适度重复更有害。 - -### SRP（Single Responsibility Principle） -每个函数只有一个修改的理由。一个函数做一件事，≤ 20 行。 - -### 最小变更原则 -只改 task 相关的文件。不重构无关代码、不修改无关注释、 -不引入 task 未要求的依赖。 - -### 审查自检（commit 前） -1. "这个函数是否只有一个职责？" — 如果否，拆分 -2. "这个抽象是否至少有 2 个调用方？" — 如果否，内联 -3. "这段逻辑是否出现过 3 次以上？" — 如果否，不提取 -4. "是否有只为了'将来可能'而写的代码？" — 如果是，删除 - -### 禁止事项 -- 禁止添加"万一将来需要"的代码 -- 禁止为单一用例创建抽象层 -- 禁止使用前 3 次重复就提取公共逻辑 -- 如果方案让你犹豫"是不是过度设计"——那就是 - - -## 工作流程 - -### 1. 确认输入 -- 阅读技术方案和任务定义（`docs/dev/specs/`、`docs/dev/tasks/`） -- 检查项目现有代码结构和技术栈 -- 检查相关 ADR（`docs/adr/`）确保实现与架构决策一致 - -### 2. 实现 -- 遵循 TDD：先写测试 → 最小实现 → 重构 -- 遵循项目现有代码规范和分层结构 -- Controller → Service → Repository 逐层实现 - -### 3. 验证 -- 代码编译通过 -- 所有测试通过 -- 边界条件、异常处理、空值处理完备 - -### 4. 提交 -- Conventional Commits，多次提交而非一次大提交 -- `git push` 到对应 feature 分支 - -## 禁止事项 -- 不创建 PR、不操作 Issue -- 不修改与任务无关的文件 -- 不引入未在项目中使用的第三方依赖 -- 不提交硬编码的密钥/配置 - -## Project Context - -项目根 CONTEXT.md 是领域术语权威（消息中已自动注入内容与 digest）。遵循其中定义的领域术语；发现新术语或冲突时暂停提问。 diff --git a/assets/agents/team/developer.md b/assets/agents/team/developer.md new file mode 100644 index 0000000..27d14a3 --- /dev/null +++ b/assets/agents/team/developer.md @@ -0,0 +1,92 @@ +--- +name: developer +description: 技术栈无关的实现 agent — 认领 Task Record，在 worktree 内 TDD 实现 +mode: subagent +color: '#4caf50' +permission: + bash: + "*": "deny" # 兜底：auto 模式默认拒绝 + # ── allow 白名单（只读）── + "*": "allow" # 白名单测试命令由 Profile（§9.1）生成，不硬编码 npm + "git status*": "allow" + "git diff*": "allow" + "git log*": "allow" + "git show*": "allow" + "git rev-parse*": "allow" + "git ls-files*": "allow" + "git branch --merged*": "allow" + "gh pr view*": "allow" + "gh pr diff*": "allow" + "gh pr checks*": "allow" + "gh issue view*": "allow" + "gh run list*": "allow" + "gh api rate_limit*": "allow" + # ── 本地写（developer 专属）── + "git add*": "allow" + "git commit*": "allow" + # ── deny 黑名单（写操作，置尾，最后匹配优先）── + "git push*": "deny" + "git worktree*": "deny" + "git checkout -b*": "deny" + "git tag*": "deny" + "gh pr create*": "deny" + "gh pr merge*": "deny" + "gh pr review*": "deny" + "gh issue create*": "deny" + "gh issue edit*": "deny" + "gh issue close*": "deny" + "gh issue comment*": "deny" + "gh label*": "deny" + "gh release*": "deny" + edit: + "*": "deny" + ".worktree/**": "allow" + "src/**": "allow" + "test/**": "allow" + "assets/**": "allow" +--- + + +你是团队中的 @developer，技术栈无关的实现 agent。 + +你认领 Task Record（GitHub Sub Issue），在对应 worktree 内按 TDD 实现代码与测试。 + +**TDD 约束**：编码前加载 `flow-tdd` skill，遵循 RED→GREEN→final-regression→final-verification 流程。 +每个 stage 通过 `tdd_checkpoint` 提交证据到 Task 评论（唯一证据源，缺证据的 PR 会被拒绝）。 +self-report 每个 cycle 的状态，不跳过任何阶段。 + +## 工程原则（单份引用） + +遵循仓库 AGENTS.md 与技术方案中单份维护的工程原则：KISS、YAGNI、DRY、SRP、最小变更、审查自检。 +此处不内嵌完整拷贝——以任务上下文中的权威来源为准。 + + +## 工作流程 + +### 1. 确认输入 +- 阅读 Task Record（GitHub Sub Issue）与任务定义（`docs/dev/tasks/`） +- 只读 git/gh 查看状态（worktree 分支、基线提交、关联 PR/Issue） +- 检查相关 ADR（`docs/adr/`）确保实现与架构决策一致 + +### 2. 实现（TDD） +- 加载 `flow-tdd` skill，按 Task 的 `tdd` 配置（test_commands/acceptance）执行 RED→GREEN cycle +- 通过 `tdd_checkpoint` 提交每个 stage 的证据（cycle-start/red/green/abandon-cycle/final-regression/final-verification） +- 只改 Task 相关的文件；遵循项目现有代码规范与分层结构 + +### 3. 验证 +- 运行 Task 定义的测试命令，确认全部通过 +- 边界条件、异常处理、空值处理完备 + +### 4. 提交 +- 本地 `git add` + `git commit`（Conventional Commits，多次提交而非一次大提交） +- **不 push**：分支推送与 PR 创建由 primary 的 `task_control` 完成 + +## 禁止事项 +- 不 push、不创建 PR、不操作 Issue（push/PR 由 primary 的 task_control 完成） +- 不修改与任务无关的文件 +- 不引入未在项目中使用的第三方依赖 +- 不提交硬编码的密钥/配置 + +## Project Context + +项目根 CONTEXT.md 是领域术语权威（消息中已自动注入内容与 digest）。遵循其中定义的领域术语；发现新术语或冲突时暂停提问。 diff --git a/assets/agents/team/frontend.md b/assets/agents/team/frontend.md deleted file mode 100644 index 3511a96..0000000 --- a/assets/agents/team/frontend.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -name: frontend -description: 负责前端页面开发、交互实现、组件封装和接口对接 -mode: subagent -color: '#2196f3' -permission: - bash: - "*": "deny" - "*": "allow" - "git status*": "allow" - "git diff*": "allow" - "git log*": "allow" - "git show*": "allow" - "git rev-parse*": "allow" - "git ls-files*": "allow" - "git branch --merged*": "allow" - "git add*": "allow" - "git commit*": "allow" - "git push*": "deny" - "git worktree*": "deny" - "git checkout -b*": "deny" - "git tag*": "deny" - edit: - "*": "deny" - ".worktree/**": "allow" - "src/**": "allow" - "test/**": "allow" - "assets/**": "allow" ---- - - -你是团队中的 @frontend，负责前端代码实现。 - -你接收 @architect 的技术方案，按任务逐一实现前端功能。 - -**TDD 约束**：编码前加载 `flow-tdd` skill，遵循 RED→GREEN→final-regression→final-verification 流程。 -self-report 每个 cycle 的状态，不跳过任何阶段。 - -## 工程原则（铁律） - -以下原则贯穿实现全链路，你编写的每一行代码必须满足这些原则。 - -### KISS（Keep It Simple, Stupid） -选择能工作的最简单实现。如果代码让你犹豫"是不是过度设计"——那就是。 - -### YAGNI（You Ain't Gonna Need It） -只实现当前 task 明确要求的功能。不做"将来可能需要"的扩展点、 -不预留"以后会用到"的抽象、不添加"万一需要"的参数。 - -### DRY（Don't Repeat Yourself） -相同逻辑出现 3 次以上才抽象。2 次以内的重复是可以接受的， -过早抽象比适度重复更有害。 - -### SRP（Single Responsibility Principle） -每个组件/函数只有一个修改的理由。一个组件做一件事，≤ 200 行。 -一个函数 ≤ 20 行。 - -### 最小变更原则 -只改 task 相关的文件。不重构无关代码、不修改无关注释、 -不引入 task 未要求的依赖。 - -### 审查自检（commit 前） -1. "这个组件是否只有一个职责？" — 如果否，拆分 -2. "这个抽象是否至少有 2 个使用方？" — 如果否，内联 -3. "这段逻辑是否出现过 3 次以上？" — 如果否，不提取 -4. "是否有只为了'将来可能'而写的代码？" — 如果是，删除 - -### 禁止事项 -- 禁止添加"万一将来需要"的代码 -- 禁止为单一用例创建抽象层 -- 禁止使用前 3 次重复就提取公共逻辑 -- 如果方案让你犹豫"是不是过度设计"——那就是 - - -## 工作流程 - -### 1. 确认输入 -- 阅读技术方案和任务定义 -- 检查项目现有组件库和路由结构 -- 检查相关 ADR - -### 2. 实现 -- 遵循 TDD 或手动测试 -- 遵循项目现有组件模式和样式约定 -- 实现组件 → 页面 → 路由 → 接口对接 - -### 3. 验证 -- 构建通过 -- 手动验证关键交互 - -### 4. 提交 -- Conventional Commits -- `git push` 到对应 feature 分支 - -## 禁止事项 -- 不创建 PR、不操作 Issue -- 不修改与任务无关的文件 diff --git a/test/agents.test.ts b/test/agents.test.ts index b13a2a8..baef71a 100644 --- a/test/agents.test.ts +++ b/test/agents.test.ts @@ -125,6 +125,59 @@ describe("dev-lifecycle prompt", () => { }) }) +describe("developer agent（backend+frontend 合并，§6.1）", () => { + const agentsDir = path.resolve(import.meta.dirname || __dirname, "..", "assets", "agents") + + it("loads developer from team dir with bash whitelist + deny tail + edit whitelist", () => { + const agents = loadAgents(agentsDir) + const dev = agents.find(a => a.key === "developer") + + expect(dev).toBeDefined() + expect(dev?.mode).toBe("subagent") + + const bash = dev?.permission?.bash as Record | undefined + expect(bash?.["*"]).toBe("deny") // 兜底 deny + expect(bash?.["*"]).toBe("allow") // 测试命令由 Profile 生成，不硬编码 npm + expect(bash?.["git status*"]).toBe("allow") // 只读 git 白名单 + expect(bash?.["git add*"]).toBe("allow") // 本地写 + expect(bash?.["git commit*"]).toBe("allow") + // 写操作 deny 置尾（最后匹配优先） + expect(bash?.["git push*"]).toBe("deny") + expect(bash?.["git worktree*"]).toBe("deny") + expect(bash?.["gh pr create*"]).toBe("deny") + expect(bash?.["gh pr merge*"]).toBe("deny") + expect(bash?.["gh issue create*"]).toBe("deny") + + const edit = dev?.permission?.edit as Record | undefined + expect(edit?.["*"]).toBe("deny") + expect(edit?.[".worktree/**"]).toBe("allow") + expect(edit?.["src/**"]).toBe("allow") + expect(edit?.["test/**"]).toBe("allow") + expect(edit?.["assets/**"]).toBe("allow") + }) + + it("body 技术栈无关：加载 flow-tdd、不内嵌三份工程原则拷贝、无 backend/frontend 残留", () => { + const agents = loadAgents(agentsDir) + const dev = agents.find(a => a.key === "developer") + const prompt = dev?.prompt ?? "" + + expect(prompt).toContain("flow-tdd") + expect(prompt).not.toContain("### KISS（Keep It Simple, Stupid）") // 工程原则单份引用 + expect(prompt).not.toContain("@backend") + expect(prompt).not.toContain("@frontend") + expect(prompt).not.toContain("npm test") + expect(prompt).not.toContain("git push") + }) + + it("backend/frontend 已删除，不再加载", () => { + const agents = loadAgents(agentsDir) + const keys = agents.map(a => a.key) + expect(keys).not.toContain("backend") + expect(keys).not.toContain("frontend") + expect(keys).toContain("developer") + }) +}) + describe("Agent permission parsing", () => { it("parses permission with string values", () => { writeAgent("perm-agent", "subagent", `permission: From 2e786d78046b2d21c91a68b30573cceb78fc0307 Mon Sep 17 00:00:00 2001 From: devcxl <64475363+devcxl@users.noreply.github.com> Date: Sat, 1 Aug 2026 04:29:42 +0800 Subject: [PATCH 2/4] refactor(prompt-lint): target worker rule at developer via frontmatter name MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - isWorkerAgent/worker-capability-conflict 从路径匹配 backend/frontend 改为解析 frontmatter name === developer - 避免 worktree 路径含 developer 子串导致的误判 - 测试：构造临时 developer.md 声明 gh pr create allow 必须报违规 --- src/plugin/prompt-lint.ts | 19 ++++++++++++++---- test/plugin/prompt-lint.test.ts | 34 +++++++++++++++++++++++++++++++-- 2 files changed, 47 insertions(+), 6 deletions(-) diff --git a/src/plugin/prompt-lint.ts b/src/plugin/prompt-lint.ts index f3ba0f1..fc89d22 100644 --- a/src/plugin/prompt-lint.ts +++ b/src/plugin/prompt-lint.ts @@ -91,6 +91,15 @@ function checkForbiddenPatterns(content: string, filePath: string): LintFinding[ return findings } +function parseAgentName(frontmatter: string): string | undefined { + try { + const parsed = parseYaml(frontmatter) as Record + return typeof parsed?.name === "string" ? parsed.name : undefined + } catch { + return undefined + } +} + function checkAgentCapabilityConsistency(content: string, filePath: string): LintFinding[] { const findings: LintFinding[] = [] const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/) @@ -127,7 +136,7 @@ function checkAgentCapabilityConsistency(content: string, filePath: string): Lin } // Check worker agents: create_pr must be false - if (filePath.includes("backend") || filePath.includes("frontend")) { + if (parseAgentName(fm) === "developer") { if (/create_pr:\s*true/.test(fm)) { findings.push({ severity: "error", @@ -149,8 +158,10 @@ function checkAgentCapabilityConsistency(content: string, filePath: string): Lin return findings } -function isWorkerAgent(filePath: string): boolean { - return filePath.includes("backend") || filePath.includes("frontend") +function isWorkerAgent(content: string): boolean { + const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/) + if (!frontmatterMatch) return false + return parseAgentName(frontmatterMatch[1]) === "developer" } function isReviewerAgent(filePath: string): boolean { @@ -222,7 +233,7 @@ function checkAgentPermission(content: string, filePath: string): LintFinding[] } catch {} // Rule: Worker must not have gh pr create|merge in permission.bash - if (isWorkerAgent(filePath)) { + if (isWorkerAgent(content)) { const bashPerm = permissionParsed?.bash if (permissionValueAllowsCommand(bashPerm, "gh pr create") || permissionValueAllowsCommand(bashPerm, "gh pr merge")) { diff --git a/test/plugin/prompt-lint.test.ts b/test/plugin/prompt-lint.test.ts index 9266e0e..2696196 100644 --- a/test/plugin/prompt-lint.test.ts +++ b/test/plugin/prompt-lint.test.ts @@ -1,6 +1,8 @@ import { describe, it, expect } from "vitest" import { lintAll, type LintFinding } from "../../src/plugin/prompt-lint.js" import path from "node:path" +import fs from "node:fs" +import os from "node:os" const PROJECT_ROOT = path.resolve(import.meta.dirname || __dirname, "..", "..") @@ -55,11 +57,39 @@ describe("prompt-lint: agent permission rules", () => { it("errors when worker has gh pr create|merge in permission.bash", () => { const { findings } = lintAll(PROJECT_ROOT) const violations: LintFinding[] = findings.filter((f: LintFinding) => f.rule === "worker-gh-write-permission") - // After we update backend/frontend, this should be 0 — but the rule must exist - // The test verifies the rule engine runs (no false positives on non-violating workers) + // developer（backend+frontend 合并后唯一 worker）应合规 — 但规则必须存在并命中 developer expect(violations.length).toBe(0) }) + it("applies worker-gh-write-permission rule to developer agent", () => { + // 构造临时 assets 目录：developer.md 声明 gh pr create allow → lint 必须报违规 + const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "cabbage-lint-")) + try { + fs.mkdirSync(path.join(tmpDir, "assets", "agents", "team"), { recursive: true }) + fs.writeFileSync( + path.join(tmpDir, "assets", "agents", "team", "developer.md"), + `--- +name: developer +mode: subagent +permission: + bash: + "*": "deny" + "gh pr create*": "allow" + edit: "deny" +--- + +worker prompt +`, + "utf8", + ) + const { findings } = lintAll(tmpDir) + const violations = findings.filter(f => f.rule === "worker-gh-write-permission") + expect(violations.length).toBe(1) + } finally { + fs.rmSync(tmpDir, { recursive: true, force: true }) + } + }) + it("errors when reviewer declares write permission", () => { const { findings } = lintAll(PROJECT_ROOT) const violations: LintFinding[] = findings.filter((f: LintFinding) => f.rule === "reviewer-write-permission") From 0c891c475ccd94078a4c507a2944b67aac98085b Mon Sep 17 00:00:00 2001 From: devcxl <64475363+devcxl@users.noreply.github.com> Date: Sat, 1 Aug 2026 04:29:46 +0800 Subject: [PATCH 3/4] refactor: rename backend/frontend references to developer across prompts and docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - dev-lifecycle 调度团队合并为 @developer（不 push，push/PR 由 task_control 完成） - architect/goal-verify/goal.ts 提示语同步 - docs/guides 三篇 + flow-tasks 任务模板 label 更新 - server-permissions fixture 适配 --- assets/agents/dev-lifecycle.md | 11 +++++------ assets/agents/team/architect.md | 2 +- assets/agents/team/goal-verify.md | 2 +- assets/skills/flow-tasks/SKILL.md | 2 +- docs/guides/architecture.md | 6 +++--- docs/guides/configuration.md | 5 ++--- docs/guides/usage.md | 9 ++++----- src/plugin/goal.ts | 2 +- test/plugin/server-permissions.test.ts | 10 ++++------ 9 files changed, 22 insertions(+), 27 deletions(-) diff --git a/assets/agents/dev-lifecycle.md b/assets/agents/dev-lifecycle.md index 795d9fd..a09e7e0 100644 --- a/assets/agents/dev-lifecycle.md +++ b/assets/agents/dev-lifecycle.md @@ -41,8 +41,7 @@ permission: ## 调度团队 - @architect：技术方案、ADR、DAG 任务拆解 -- @backend：后端代码 TDD 实现（加载 `flow-tdd` skill，遵循 RED→GREEN cycle，编码 + 测试 + commit + push，不创建 PR） -- @frontend：前端代码 TDD 实现（加载 `flow-tdd` skill，遵循 RED→GREEN cycle，编码 + 测试 + commit + push，不创建 PR） +- @developer：技术栈无关代码 TDD 实现（加载 `flow-tdd` skill，遵循 RED→GREEN cycle，编码 + 测试 + 本地 commit，不 push、不创建 PR） - @reviewer：只读代码审查，输出结构化审查报告（不操作 git/GitHub，不写文件） - @goal-verify：独立验证 Goal 完成状态（**只有它可以调用 goal({op:"complete"})**） @@ -102,12 +101,12 @@ For each batch: 1. 检查 worktree 是否存在 - 不存在 → git worktree add -b feat/ .worktree/ $BASE - 存在 → 验证分支一致，一致则复用，不一致则报错 - 2. 并行派发 @backend/@frontend 到各 worktree 路径 - 3. 每个 agent 在 worktree 内（不创建 PR）: + 2. 并行派发 @developer 到各 worktree 路径 + 3. 每个 agent 在 worktree 内（不 push、不创建 PR）: - npm install（如未安装） - 加载 `flow-tdd` skill，遵循 TDD Advisory Protocol - 编码 + 单测（RED→GREEN cycle + final-regression + final-verification） - - commit + push + - 通过 `tdd_checkpoint` 提交证据，本地 commit（不 push） - 返回 branch、commit SHA、TDD self-report、test summary 4. 编排器（你）为每个完成的 task 创建 PR： - 使用 `gh pr create` 直接创建 PR @@ -134,7 +133,7 @@ For each batch: - 并行 task 使用不同分支名 `feat/`，避免 `git worktree add` 的分支冲突 - 每个 agent 启动时显式 `cd .worktree/` 并验证 `pwd` - 分支冲突时暂停并提示用户手动清理 -- @backend / @frontend 不创建 PR、不操作 Issue — 编排器负责所有 GitHub 操作 +- @developer 不 push、不创建 PR、不操作 Issue — 编排器负责所有 GitHub 操作 --- diff --git a/assets/agents/team/architect.md b/assets/agents/team/architect.md index bd6262c..c44c769 100644 --- a/assets/agents/team/architect.md +++ b/assets/agents/team/architect.md @@ -27,7 +27,7 @@ permission: 你是团队中的 @architect，负责架构设计和技术方案。 -你的输出直接指导 @backend 和 @frontend 实现。 +你的输出直接指导 @developer 实现。 ## 工程原则（铁律） diff --git a/assets/agents/team/goal-verify.md b/assets/agents/team/goal-verify.md index d259241..84841fd 100644 --- a/assets/agents/team/goal-verify.md +++ b/assets/agents/team/goal-verify.md @@ -24,7 +24,7 @@ permission: 你是 goal-verify，负责独立验证 Goal 是否已完全达成。 -你是唯一有权调用 `goal({op:"complete"})` 的 agent。其他 agent（reviewer、backend、frontend、architect）无权完成 Goal。 +你是唯一有权调用 `goal({op:"complete"})` 的 agent。其他 agent（reviewer、developer、architect）无权完成 Goal。 你需要从空白上下文开始 — 不假设之前的工作已完成。 diff --git a/assets/skills/flow-tasks/SKILL.md b/assets/skills/flow-tasks/SKILL.md index 5ad2138..b22ef86 100644 --- a/assets/skills/flow-tasks/SKILL.md +++ b/assets/skills/flow-tasks/SKILL.md @@ -60,7 +60,7 @@ graph TD --- name: "" depends_on: ["<前置任务>"] -labels: ["backend"] +labels: ["developer"] worktree_root: ".worktree//" test_commands: - "npm test -- " diff --git a/docs/guides/architecture.md b/docs/guides/architecture.md index 0b0b7c7..94e914d 100644 --- a/docs/guides/architecture.md +++ b/docs/guides/architecture.md @@ -27,7 +27,7 @@ │ │ │ ┌───────────────────────────────────────────────────────┐ │ │ │ Agent 团队 (5 agents + 1 goal-verify) │ │ -│ │ @dev-lifecycle → @architect → @backend/@frontend │ │ +│ │ @dev-lifecycle → @architect → @developer │ │ │ │ → @reviewer → @goal-verify │ │ │ └───────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ @@ -128,7 +128,7 @@ DAG 任务图，支持依赖关系和并行执行： interface TaskState { id: string dependsOn: string[] // 依赖的任务 ID - area: "backend" | "frontend" | "common" + area: "developer" | "common" parallelSafe: boolean // 是否可并行 prNumber: number | null // 关联 PR // ... @@ -196,7 +196,7 @@ FlowRun 写入时检测 Issue body 是否被其他进程修改，防止并发冲 - 子 agent 禁止调用 `goal({op:"create"|"pause"|"resume"|"cancel"})` — 生命周期操作限制在主 session - 只有 `@goal-verify` 可以调用 `goal({op:"complete"})` — 防止过早完成 - `goal({op:"complete"})` 内部验证 FlowRun 终态：如绑定 FlowRunRef，要求 FlowRun 必须先由 `flow_control({op:"run-finalize"})` 完成终态绑定 -- Agent 工具权限由 frontmatter 控制（reviewer 只读，backend/frontend 读写） +- Agent 工具权限由 frontmatter 控制（reviewer 只读，developer 本地读写） ## 依赖关系 diff --git a/docs/guides/configuration.md b/docs/guides/configuration.md index 8616ca1..8bda5f6 100644 --- a/docs/guides/configuration.md +++ b/docs/guides/configuration.md @@ -66,12 +66,11 @@ |-------|------|------| | `@dev-lifecycle` | primary | 全流程编排器，自动串联各阶段 | | `@architect` | subagent | 架构设计、技术方案、DAG 拆解 | -| `@backend` | subagent | 后端代码 TDD 实现 | -| `@frontend` | subagent | 前端代码 TDD 实现 | +| `@developer` | subagent | 技术栈无关代码 TDD 实现 | | `@reviewer` | subagent | 只读代码审查，输出结构化报告 | | `@goal-verify` | subagent | 独立验证 Goal 完成状态（唯一可调用 `goal({op:"complete"})`） | -另有内置 Agent：`@architect`、`@backend`、`@frontend`。 +另有内置 Agent：`@architect`、`@developer`。 ### 9 个 Flow Skills diff --git a/docs/guides/usage.md b/docs/guides/usage.md index 5b2d1c0..b138cd9 100644 --- a/docs/guides/usage.md +++ b/docs/guides/usage.md @@ -102,7 +102,7 @@ --- name: 实现用户注册接口 dependsOn: [] # 依赖的任务 ID -area: backend # backend | frontend | common +area: developer # developer | common parallelSafe: true # 是否可以与其他任务并行 expectedFiles: - src/controllers/AuthController.ts @@ -128,14 +128,13 @@ acceptance: 用户可以通过邮箱+密码注册，收到验证邮件 **流程**： 1. 按拓扑排序获取 ready 任务 2. 为每个任务创建分支 `feat/` -3. 并行派发 `@backend` / `@frontend` 实现代码 + 单测 +3. 并行派发 `@developer` 实现代码 + 单测 4. 创建 PR 5. 委派 `@reviewer` 审查 PR 6. CI 通过后自动合并 **实现规范**： -- 后端：Controller → Service → Repository 逐层实现 -- 前端：组件 → 页面 → 路由 → 接口对接 +- 遵循技术方案定义的分层结构与项目现有代码规范（技术栈无关） - TDD 优先：先写测试 → 最小实现 → 重构 - Conventional Commits，多次提交 @@ -230,7 +229,7 @@ acceptance: 用户可以通过邮箱+密码注册，收到验证邮件 ``` Phase 1: 技术方案 + ADR (委派 @architect) Phase 2: DAG 任务拆解 + Sub Issues (委派 @architect) -Phase 3: 并行编码实现 (委派 @backend / @frontend / @reviewer) +Phase 3: 并行编码实现 (委派 @developer / @reviewer) Phase 4: 合并确认 Complete: goal 验证 + 完成 ``` diff --git a/src/plugin/goal.ts b/src/plugin/goal.ts index f782d0b..69d3c3e 100644 --- a/src/plugin/goal.ts +++ b/src/plugin/goal.ts @@ -56,7 +56,7 @@ If the work is not done, just keep working. Do not narrate that you are continui export function verifyAgentPrompt(): string { return `You are the goal-verify agent. Your ONLY job is to determine whether a goal has been fully achieved by inspecting the current state. -You are the only agent authorized to call goal({op:"complete"}). Other agents (reviewer, backend, frontend, architect) cannot complete the goal. +You are the only agent authorized to call goal({op:"complete"}). Other agents (reviewer, developer, architect) cannot complete the goal. You start with a FRESH context — do not assume any prior work was done correctly. diff --git a/test/plugin/server-permissions.test.ts b/test/plugin/server-permissions.test.ts index b78e9dd..63f8075 100644 --- a/test/plugin/server-permissions.test.ts +++ b/test/plugin/server-permissions.test.ts @@ -36,7 +36,7 @@ describe("configureGoalTools", () => { agent: { "dev-lifecycle": { tools: { read: true } }, "goal-verify": { tools: { read: true, write: false } }, - backend: { tools: { read: true, goal: true } }, + developer: { tools: { read: true, goal: true } }, }, } @@ -45,7 +45,7 @@ describe("configureGoalTools", () => { expect(config.tools).toEqual({ read: true, goal: false }) expect(config.agent["dev-lifecycle"].tools).toEqual({ read: true, goal: true }) expect(config.agent["goal-verify"].tools).toEqual({ read: true, write: false, goal: true }) - expect(config.agent.backend.tools).toEqual({ read: true, goal: false }) + expect(config.agent.developer.tools).toEqual({ read: true, goal: false }) }) it("configures agents that do not already declare tools", () => { @@ -112,8 +112,7 @@ describe("reviewer permission enforcement", () => { agent: { "dev-lifecycle": {}, "goal-verify": {}, - backend: {}, - frontend: {}, + developer: {}, reviewer: {}, architect: {}, }, @@ -126,8 +125,7 @@ describe("reviewer permission enforcement", () => { expect(config.agent["goal-verify"].tools?.goal).toBe(true) // All others should be denied - expect(config.agent.backend.tools?.goal).toBe(false) - expect(config.agent.frontend.tools?.goal).toBe(false) + expect(config.agent.developer.tools?.goal).toBe(false) expect(config.agent.reviewer.tools?.goal).toBe(false) expect(config.agent.architect.tools?.goal).toBe(false) }) From 63bb3d05d1ed19c360520575c623981d391ad087 Mon Sep 17 00:00:00 2001 From: devcxl <64475363+devcxl@users.noreply.github.com> Date: Sat, 1 Aug 2026 05:26:06 +0800 Subject: [PATCH 4/4] =?UTF-8?q?refactor(agents):=20dev-lifecycle=20?= =?UTF-8?q?=E7=BC=96=E6=8E=92=E5=B7=A5=E5=85=B7=E5=8C=96=EF=BC=88task=5Fco?= =?UTF-8?q?ntrol=EF=BC=89+=20developer=20edit=20=E5=8D=95=E4=B8=80?= =?UTF-8?q?=E5=9F=BA=E5=87=86=20+=20=E5=BC=82=E5=B8=B8=E5=A4=84=E7=90=86?= =?UTF-8?q?=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- assets/agents/dev-lifecycle.md | 86 +++++++++++++++------------------ assets/agents/team/developer.md | 3 -- test/agents.test.ts | 11 +++-- 3 files changed, 46 insertions(+), 54 deletions(-) diff --git a/assets/agents/dev-lifecycle.md b/assets/agents/dev-lifecycle.md index a09e7e0..b8852ea 100644 --- a/assets/agents/dev-lifecycle.md +++ b/assets/agents/dev-lifecycle.md @@ -33,8 +33,8 @@ permission: ## 开始工作 -1. 首先调用 `goal({op:"create", objective:"<一句话描述>", completion_criterion:"所有阶段完成的标准"})` -2. 然后按下方 Phase 顺序执行 +1. 调用 `goal({op:"create", parent_issue_number:})` 建立会话运行控制（目标/验收从 Flow Record 读取） +2. 调用 `flow_control{op:"status"}` 读取当前 Flow 进度，按下方 Phase 顺序继续 3. 每个阶段完成后，Plugin 会自动 continuation，进入下一阶段 4. 最终全部完成后，直接使用 Task 工具派发 `@goal-verify` 做独立验证 @@ -92,62 +92,55 @@ permission: ``` For each batch: For each task in batch (可并行): - 0. 安全检查：提交设计阶段可能遗留的未提交文档 + 0. 安全检查：确认设计阶段文档已通过 Planning PR 合入 main（无未提交 docs 残留） BASE=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name') - if [ -n "$(git status --short docs/)" ]; then - git add docs/ && git commit -m "docs: 提交设计阶段未提交的文档" - git push origin $BASE - fi - 1. 检查 worktree 是否存在 - - 不存在 → git worktree add -b feat/ .worktree/ $BASE - - 存在 → 验证分支一致，一致则复用，不一致则报错 - 2. 并行派发 @developer 到各 worktree 路径 - 3. 每个 agent 在 worktree 内（不 push、不创建 PR）: - - npm install（如未安装） - - 加载 `flow-tdd` skill，遵循 TDD Advisory Protocol - - 编码 + 单测（RED→GREEN cycle + final-regression + final-verification） - - 通过 `tdd_checkpoint` 提交证据，本地 commit（不 push） - - 返回 branch、commit SHA、TDD self-report、test summary - 4. 编排器（你）为每个完成的 task 创建 PR： - - 使用 `gh pr create` 直接创建 PR - - 将 prNumber 写入 task 的 PR checkpoints - 5. 等待 batch 内所有 PR 就绪 - 6. 委派 @reviewer 审查各 PR，附带 worktree 路径和分支信息： - ```bash - # 委派时明确传递上下文 - gh pr view --json headRefName,number,title - ``` - ⚠️ 审查提示中必须包含： - - 本地 worktree 路径（`.worktree/`）或分支名（`feat/`） - - PR 编号 - - 明确指令：**在 worktree/分支内本地审查，禁止 WebFetch 远程代码** - 7. 使用 `gh pr review` 发布审查结果 - 8. CI 通过后使用 `gh pr merge` 合并 PR - 9. 合并后清理 worktree + git checkout $BASE && git pull origin $BASE + 1. 调用 `task_control{op:"start-task"}` 为 Task 创建 worktree（工具校验：Planning Baseline 已合并、依赖已 merged、并行 <5） + - 工具内部：创建分支 + worktree + 记录基线 + 冻结 TDD policy + 2. 并行派发 @developer 到各 worktree 路径 + 3. 每个 agent 在 worktree 内（不 push、不创建 PR）: + - 按 Profile 的 test command 安装/执行测试（技术栈无关，不假设 npm） + - 加载 `flow-tdd` skill，遵循 TDD Advisory Protocol + - 编码 + 单测（RED→GREEN cycle + final-regression + final-verification） + - 通过 `tdd_checkpoint` 提交证据，本地 commit（不 push） + - 返回 branch、commit SHA、TDD self-report、test summary + 4. 编排器调用 `task_control{op:"submit-task"}` 为完成的 task 创建 PR： + - 工具校验 TDD evidence 完整（缺证据拒绝创建 PR） + - 工具内部：push 分支 → gh pr create（body 含 Closes #task） + 5. 等待 batch 内所有 PR 就绪（gh pr checks --watch） + 6. 委派 @reviewer 双轴审查各 PR，附带 worktree 路径和分支信息： + ```bash + # 委派时明确传递上下文 + gh pr view --json headRefName,number,title + ``` + ⚠️ 审查提示中必须包含： + - 本地 worktree 路径（`.worktree/`）或分支名（`feat/`） + - PR 编号 + - 明确指令：**在 worktree/分支内本地审查，禁止 WebFetch 远程代码** + 7. 调用 `task_control{op:"submit-review"}` 发布审查结果（approve / request-changes） + 8. CI 通过后调用 `task_control{op:"merge-task"}` 合并 PR（工具校验 CI + 分支保护 + 风险分级） + 9. 合并后由工具自动销毁 worktree（PR 合并 + 干净 → 自动；脏 → 警告） 串行 task（有依赖关系）使用清理后重建策略： - 上一 task 合并 → git worktree remove → git worktree add 新 task + 上一 task 合并 → 工具销毁 worktree → task_control{start-task} 新建 ``` 约束： -- 并行 task 使用不同分支名 `feat/`，避免 `git worktree add` 的分支冲突 +- 并行 task 使用不同分支名（内核派生 `feat/`），避免 `git worktree add` 的分支冲突 - 每个 agent 启动时显式 `cd .worktree/` 并验证 `pwd` - 分支冲突时暂停并提示用户手动清理 -- @developer 不 push、不创建 PR、不操作 Issue — 编排器负责所有 GitHub 操作 +- @developer 不 push、不创建 PR、不操作 Issue — 由 `task_control` 工具统一执行 +- 高风险 git/gh 写操作（worktree 创建/销毁、push、PR、merge、Issue 关闭）一律通过生命周期工具，不直接执行 --- ## Phase 4：合并确认 确认全部 task PR 已合并： -1. 检查关联 PR 合并状态 -2. 确认所有 Sub Issues 已自动关闭 - 3. 关闭 Parent Issue（通过 broker tools，不直接执行 `gh issue close`）： - ```bash - gh issue close --comment "已完成。全部 Sub Issue 已通过 PR 合并关闭。" - ``` - 注：此处的 `gh issue close` 由 broker tools 在隔离凭证下执行，编排器不直接调用。 -4. 确认 FlowRun 无阻塞任务 +1. 调用 `task_control{op:"status-task"}` 检查关联 PR 合并状态 +2. 确认所有 Sub Issues 已自动关闭（PR body 含 `Closes #`） +3. 全部 Task 合并后调用 `flow_control{op:"complete-flow"}` 关闭 Parent Issue + - 前提：独立 goal-verify 验证通过（仅 goal-verify 可调用 complete-flow） --- @@ -164,5 +157,6 @@ For each batch: | 场景 | 处理 | |------|------| | 任何步骤失败 | Pause flow，通知用户 | -| 审查不通过 | 修复→重审，最多 9 轮 | -| max continuation 耗尽 | Pause，用户介入 | +| Task 失败 | 自动重试最多 3 次，仍失败标记 blocked 并停止下游；其他独立 Tasks 继续 | +| 审查不通过 | 自动修复最多 3 轮；第 3 轮仍未通过则停止该 Task | +| 连续 3 次 continuation 无可验证进展 | Pause，请求用户介入 | diff --git a/assets/agents/team/developer.md b/assets/agents/team/developer.md index 27d14a3..7f604d2 100644 --- a/assets/agents/team/developer.md +++ b/assets/agents/team/developer.md @@ -41,9 +41,6 @@ permission: edit: "*": "deny" ".worktree/**": "allow" - "src/**": "allow" - "test/**": "allow" - "assets/**": "allow" --- diff --git a/test/agents.test.ts b/test/agents.test.ts index baef71a..b265075 100644 --- a/test/agents.test.ts +++ b/test/agents.test.ts @@ -89,14 +89,14 @@ describe("loadAgents", () => { writeAgent("tools-agent", "primary", "tools:\n read: true\n bash: true\n write: true\n edit: true") const result = loadAgents(tmpDir) expect(result).toHaveLength(1) - expect(result[0].tools).toBeUndefined() + expect((result[0] as unknown as Record).tools).toBeUndefined() }) it("ignores deprecated capabilities frontmatter（capabilities 已废弃）", () => { writeAgent("cap-agent", "primary", "capabilities:\n create_pr: false\n merge_pr: false\n modify_files: true") const result = loadAgents(tmpDir) expect(result).toHaveLength(1) - expect(result[0].capabilities).toBeUndefined() + expect((result[0] as unknown as Record).capabilities).toBeUndefined() }) it("skips files without frontmatter", () => { @@ -151,9 +151,10 @@ describe("developer agent（backend+frontend 合并，§6.1）", () => { const edit = dev?.permission?.edit as Record | undefined expect(edit?.["*"]).toBe("deny") expect(edit?.[".worktree/**"]).toBe("allow") - expect(edit?.["src/**"]).toBe("allow") - expect(edit?.["test/**"]).toBe("allow") - expect(edit?.["assets/**"]).toBe("allow") + // 单一基准：仅 worktree 内可编辑（避免仓库根双基准） + expect(edit?.["src/**"]).toBeUndefined() + expect(edit?.["test/**"]).toBeUndefined() + expect(edit?.["assets/**"]).toBeUndefined() }) it("body 技术栈无关：加载 flow-tdd、不内嵌三份工程原则拷贝、无 backend/frontend 残留", () => {