From 5a802e4fd267bc507bace2502f0d40658e6be671 Mon Sep 17 00:00:00 2001 From: Bhaskoro Muthohar Date: Mon, 13 Apr 2026 02:56:20 +0700 Subject: [PATCH] feat: add flow diagram directive to phase researcher agent (#2139) (#2147) Architecture diagrams generated by gsd-phase-researcher now enforce data-flow style (conceptual components with arrows) instead of file-listing style. The directive is language-agnostic and applies to all project types. Changes: - agents/gsd-phase-researcher.md: add System Architecture Diagram subsection in Architecture Patterns output template - get-shit-done/templates/research.md: add matching directive in both architecture_patterns template sections - tests/phase-researcher-flow-diagram.test.cjs: 8 tests validating directive presence, content, and ordering in agent and template Closes #2139 --- CHANGELOG.md | 1 + agents/gsd-phase-researcher.md | 14 +++ get-shit-done/templates/research.md | 28 +++++ tests/phase-researcher-flow-diagram.test.cjs | 104 +++++++++++++++++++ 4 files changed, 147 insertions(+) create mode 100644 tests/phase-researcher-flow-diagram.test.cjs diff --git a/CHANGELOG.md b/CHANGELOG.md index de5761189..a45e93241 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,7 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ### Added - **`@gsd-build/sdk` — Phase 1 typed query foundation** — Registry-based `gsd-sdk query` command, classified errors (`GSDQueryError`), and unit-tested handlers under `sdk/src/query/` (state, roadmap, phase lifecycle, init, config, validation, and related domains). Implements incremental SDK-first migration scope approved in #2083; builds on validated work from #2007 / `feat/sdk-foundation` without migrating workflows or removing `gsd-tools.cjs` in this phase. +- **Flow diagram directive for phase researcher** — `gsd-phase-researcher` now enforces data-flow architecture diagrams instead of file-listing diagrams. Language-agnostic directive added to agent prompt and research template. (#2139) ## [1.35.0] - 2026-04-10 diff --git a/agents/gsd-phase-researcher.md b/agents/gsd-phase-researcher.md index 05d5c07eb..b47c2fed5 100644 --- a/agents/gsd-phase-researcher.md +++ b/agents/gsd-phase-researcher.md @@ -312,6 +312,20 @@ Document the verified version and publish date. Training data versions may be mo ## Architecture Patterns +### System Architecture Diagram + +Architecture diagrams MUST show data flow through conceptual components, not file listings. + +Requirements: +- Show entry points (how data/requests enter the system) +- Show processing stages (what transformations happen, in what order) +- Show decision points and branching paths +- Show external dependencies and service boundaries +- Use arrows to indicate data flow direction +- A reader should be able to trace the primary use case from input to output by following the arrows + +File-to-implementation mapping belongs in the Component Responsibilities table, not in the diagram. + ### Recommended Project Structure \`\`\` src/ diff --git a/get-shit-done/templates/research.md b/get-shit-done/templates/research.md index eb2429240..30ef09269 100644 --- a/get-shit-done/templates/research.md +++ b/get-shit-done/templates/research.md @@ -94,6 +94,20 @@ yarn add [packages] ## Architecture Patterns +### System Architecture Diagram + +Architecture diagrams MUST show data flow through conceptual components, not file listings. + +Requirements: +- Show entry points (how data/requests enter the system) +- Show processing stages (what transformations happen, in what order) +- Show decision points and branching paths +- Show external dependencies and service boundaries +- Use arrows to indicate data flow direction +- A reader should be able to trace the primary use case from input to output by following the arrows + +File-to-implementation mapping belongs in the Component Responsibilities table, not in the diagram. + ### Recommended Project Structure ``` src/ @@ -312,6 +326,20 @@ npm install three @react-three/fiber @react-three/drei @react-three/rapier zusta ## Architecture Patterns +### System Architecture Diagram + +Architecture diagrams MUST show data flow through conceptual components, not file listings. + +Requirements: +- Show entry points (how data/requests enter the system) +- Show processing stages (what transformations happen, in what order) +- Show decision points and branching paths +- Show external dependencies and service boundaries +- Use arrows to indicate data flow direction +- A reader should be able to trace the primary use case from input to output by following the arrows + +File-to-implementation mapping belongs in the Component Responsibilities table, not in the diagram. + ### Recommended Project Structure ``` src/ diff --git a/tests/phase-researcher-flow-diagram.test.cjs b/tests/phase-researcher-flow-diagram.test.cjs new file mode 100644 index 000000000..79334ce7d --- /dev/null +++ b/tests/phase-researcher-flow-diagram.test.cjs @@ -0,0 +1,104 @@ +/** + * Phase Researcher Flow Diagram Tests (#2139) + * + * Validates that gsd-phase-researcher enforces data-flow architecture + * diagrams instead of file-listing diagrams. Also validates that the + * research template includes the matching directive. + */ + +const { test, describe } = require('node:test'); +const assert = require('node:assert/strict'); +const fs = require('fs'); +const path = require('path'); + +const AGENTS_DIR = path.join(__dirname, '..', 'agents'); +const TEMPLATES_DIR = path.join(__dirname, '..', 'get-shit-done', 'templates'); + +// ─── Phase Researcher: System Architecture Diagram Directive ───────────────── + +describe('phase-researcher: System Architecture Diagram directive', () => { + const researcherPath = path.join(AGENTS_DIR, 'gsd-phase-researcher.md'); + const content = fs.readFileSync(researcherPath, 'utf-8'); + + test('contains System Architecture Diagram section', () => { + assert.ok( + content.includes('### System Architecture Diagram'), + 'gsd-phase-researcher.md must contain "### System Architecture Diagram"' + ); + }); + + test('requires data flow through conceptual components', () => { + assert.ok( + content.includes('data flow through conceptual components'), + 'Directive must require "data flow through conceptual components"' + ); + }); + + test('explicitly prohibits file listings in diagrams', () => { + assert.ok( + content.includes('not file listings'), + 'Directive must explicitly state "not file listings"' + ); + }); + + test('includes key requirements for flow diagrams', () => { + const requirements = [ + 'entry points', + 'processing stages', + 'decision points', + 'external dependencies', + 'arrows', + ]; + + for (const req of requirements) { + assert.ok( + content.toLowerCase().includes(req), + `Directive must mention "${req}"` + ); + } + }); + + test('directs file-to-implementation mapping to Component Responsibilities table', () => { + assert.ok( + content.includes('Component Responsibilities table'), + 'Directive must redirect file mapping to Component Responsibilities table' + ); + }); + + test('diagram section comes before Recommended Project Structure', () => { + const diagramPos = content.indexOf('### System Architecture Diagram'); + const structurePos = content.indexOf('### Recommended Project Structure'); + + assert.ok(diagramPos !== -1, 'System Architecture Diagram section must exist'); + assert.ok(structurePos !== -1, 'Recommended Project Structure section must exist'); + assert.ok( + diagramPos < structurePos, + 'System Architecture Diagram must come before Recommended Project Structure' + ); + }); +}); + +// ─── Research Template: System Architecture Diagram Section ─────────────────── + +describe('research template: System Architecture Diagram section', () => { + const templatePath = path.join(TEMPLATES_DIR, 'research.md'); + const content = fs.readFileSync(templatePath, 'utf-8'); + + test('contains System Architecture Diagram section', () => { + assert.ok( + content.includes('### System Architecture Diagram'), + 'Research template must contain "### System Architecture Diagram"' + ); + }); + + test('includes flow diagram requirements', () => { + assert.ok( + content.includes('data flow through conceptual components'), + 'Research template must include flow diagram directive' + ); + assert.ok( + content.includes('not file listings'), + 'Research template must prohibit file listings in diagrams' + ); + }); +});