From a596827ca31c15dfc201d759b0e8adbd63873224 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=99=B3=E6=AC=A3=E6=80=A1?= Date: Fri, 12 Jun 2026 16:54:05 +0800 Subject: [PATCH 1/2] docs: add senior-sa and senior-sd to research phase orchestration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - senior-sa and senior-sd existed in .claude/agents/ but were never referenced by agent-team or team-lead, so they were unreachable in the SDD pipeline - SAAgent analyzes business flow from spec.md scenarios; SDAgent designs class/sequence diagrams — scopes annotated to avoid overlap with ArchitectAgent and APIDesignAgent - diagrams are returned as Mermaid text and embedded into plan.md by team-lead during synthesis, keeping research agents read-only and preserving the single-writer pattern Co-Authored-By: Claude Opus 4.7 --- .claude/agents/team-lead.md | 6 ++++-- .claude/commands/agent-team.md | 11 ++++++++++- 2 files changed, 14 insertions(+), 3 deletions(-) diff --git a/.claude/agents/team-lead.md b/.claude/agents/team-lead.md index 6c277a5..70e7de4 100644 --- a/.claude/agents/team-lead.md +++ b/.claude/agents/team-lead.md @@ -21,7 +21,7 @@ You are the Team Lead orchestrator for Label Suite with deep experience coordina ## Core Responsibilities -1. **Synthesize** findings from research agents before writing `plan.md` +1. **Synthesize** findings from research agents before writing `plan.md` — including embedding senior-sa's business flow chart and senior-sd's class/sequence diagrams (Mermaid) into the corresponding `plan.md` sections 2. **Sequence** tasks — API contract must be locked before dispatching senior-backend or senior-frontend 3. **Sequence** DB migrations — senior-dba runs only after senior-backend models are confirmed 4. **Sequence** tests — senior-qa writes failing tests before implementation starts; re-validates after implementation completes @@ -150,9 +150,11 @@ If gate fails: ``` Research Phase (read-only, parallel): - senior-architect · senior-dba · senior-api-designer · + senior-architect · senior-sa · senior-sd · senior-dba · senior-api-designer · senior-backend · senior-frontend · senior-uiux · senior-i18n [nlp-research-advisor] ← for annotation / NLP task features + senior-sa returns a business flow chart, senior-sd returns class/sequence diagrams — + both as Mermaid text in findings; team-lead embeds them into plan.md during synthesis → Synthesize → ⚠️ User confirms research findings → /speckit.plan → ⚠️ User reviews plan.md → /speckit.checklist → /speckit.tasks → /speckit.analyze → fix every analyze finding and rerun /speckit.analyze until clear diff --git a/.claude/commands/agent-team.md b/.claude/commands/agent-team.md index 8bec946..103032a 100644 --- a/.claude/commands/agent-team.md +++ b/.claude/commands/agent-team.md @@ -29,6 +29,8 @@ Add to `~/.claude/settings.json`: [Optional: Research Agents] — spawn before /speckit.plan for complex features ├──→ [ArchitectAgent] overall structure, cross-cutting integration points, naming conventions + ├──→ [SAAgent] business flow analysis → Mermaid flowchart ← from spec.md scenarios, not codebase + ├──→ [SDAgent] UML class / sequence diagrams (Mermaid) ← new feature design, not existing code ├──→ [DBResearchAgent] existing DB schema, migration strategy ├──→ [APIDesignAgent] existing API contracts, REST naming consistency ← no overlap with Architect ├──→ [BackendResearchAgent] service boundaries in backend/app/services/ ← no overlap with APIDesign @@ -96,6 +98,8 @@ Run /pr-flow | Teammate | Agent Type | Responsible For | |---|---|---| | ArchitectAgent | `senior-architect` | Overall structure, cross-cutting integration points, naming conventions | +| SAAgent | `senior-sa` | Business flow analysis from `spec.md` user scenarios → Mermaid flowchart, embedded in `plan.md` | +| SDAgent | `senior-sd` | UML class / sequence diagrams (Mermaid) for the planned feature, embedded in `plan.md` | | DBResearchAgent | `senior-dba` | Review DB schema, identify migration strategy | | APIDesignAgent | `senior-api-designer` | Existing API contracts, REST naming, OpenAPI conflicts | | BackendResearchAgent | `senior-backend` | Service boundaries in `backend/app/services/` | @@ -143,6 +147,10 @@ Run /pr-flow Before writing the plan for [feature], spawn a read-only research team: - ArchitectAgent (senior-architect): scan overall codebase structure, cross-cutting integration points, naming conventions, and architectural conflicts (do NOT duplicate backend-specific API review) +- SAAgent (senior-sa): analyze business processes from spec.md user scenarios and produce a Mermaid + flowchart of the end-to-end business flow (scope: spec scenarios, not codebase structure) +- SDAgent (senior-sd): design Mermaid class and sequence diagrams for the planned feature's components + and interactions (scope: new feature design, not existing API contracts — that is APIDesignAgent's scope) - DBResearchAgent (senior-dba): review existing DB schema and propose migration strategy - APIDesignAgent (senior-api-designer): review existing API contracts, REST naming consistency, and OpenAPI spec for conflicts with the planned feature @@ -153,7 +161,8 @@ Before writing the plan for [feature], spawn a read-only research team: - I18nAgent (senior-i18n): identify UI strings needing zh-TW/en translation - NLPAdvisorAgent (nlp-research-advisor): for annotation or NLP task features, review annotation schema, IAA metrics, and Demo Paper framing -All agents are read-only — no file edits. Synthesize findings for plan.md. +All agents are read-only — no file edits. SAAgent and SDAgent return diagrams as Mermaid text in their +findings; Team Lead embeds them into plan.md during synthesis. Synthesize all findings for plan.md. ``` ### Implementation Team From 48117a56cb9b506f85732717947f7cfb01247019 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=99=B3=E6=AC=A3=E6=80=A1?= Date: Fri, 12 Jun 2026 17:08:04 +0800 Subject: [PATCH 2/2] docs: route SA/SD diagrams through /speckit.plan template fill (gemini review) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - review found a sequencing error: plan.md is created by /speckit.plan from plan-template, so "embed during synthesis" referenced a file that does not exist yet - corrected flow: SA/SD Mermaid diagrams are synthesized findings that feed into /speckit.plan and land in the template's existing diagram sections — no post-plan embedding pass needed --- .claude/agents/team-lead.md | 5 +++-- .claude/commands/agent-team.md | 3 ++- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/.claude/agents/team-lead.md b/.claude/agents/team-lead.md index 70e7de4..2b3aaec 100644 --- a/.claude/agents/team-lead.md +++ b/.claude/agents/team-lead.md @@ -21,7 +21,7 @@ You are the Team Lead orchestrator for Label Suite with deep experience coordina ## Core Responsibilities -1. **Synthesize** findings from research agents before writing `plan.md` — including embedding senior-sa's business flow chart and senior-sd's class/sequence diagrams (Mermaid) into the corresponding `plan.md` sections +1. **Synthesize** findings from research agents before writing `plan.md` — including senior-sa's business flow chart and senior-sd's class/sequence diagrams (Mermaid), which feed into `/speckit.plan` and land in the corresponding `plan.md` diagram sections when the template is filled 2. **Sequence** tasks — API contract must be locked before dispatching senior-backend or senior-frontend 3. **Sequence** DB migrations — senior-dba runs only after senior-backend models are confirmed 4. **Sequence** tests — senior-qa writes failing tests before implementation starts; re-validates after implementation completes @@ -154,7 +154,8 @@ Research Phase (read-only, parallel): senior-backend · senior-frontend · senior-uiux · senior-i18n [nlp-research-advisor] ← for annotation / NLP task features senior-sa returns a business flow chart, senior-sd returns class/sequence diagrams — - both as Mermaid text in findings; team-lead embeds them into plan.md during synthesis + both as Mermaid text in findings; the diagrams feed into /speckit.plan and are written + into plan.md's diagram sections when the template is filled (plan.md does not exist earlier) → Synthesize → ⚠️ User confirms research findings → /speckit.plan → ⚠️ User reviews plan.md → /speckit.checklist → /speckit.tasks → /speckit.analyze → fix every analyze finding and rerun /speckit.analyze until clear diff --git a/.claude/commands/agent-team.md b/.claude/commands/agent-team.md index 103032a..f8dbe73 100644 --- a/.claude/commands/agent-team.md +++ b/.claude/commands/agent-team.md @@ -162,7 +162,8 @@ Before writing the plan for [feature], spawn a read-only research team: - NLPAdvisorAgent (nlp-research-advisor): for annotation or NLP task features, review annotation schema, IAA metrics, and Demo Paper framing All agents are read-only — no file edits. SAAgent and SDAgent return diagrams as Mermaid text in their -findings; Team Lead embeds them into plan.md during synthesis. Synthesize all findings for plan.md. +findings; the diagrams feed into /speckit.plan and are written into plan.md's diagram sections when the +template is filled (plan.md does not exist before /speckit.plan runs). Synthesize all findings for plan.md. ``` ### Implementation Team