Encourage focused diagrams in feature specs

.github/instructions/specs.instructions.md

@@ -8,6 +8,7 @@ When editing feature specs, follow these rules:
 
 - Focus on **WHAT** users need and **WHY**, never on HOW to implement.
 - Written for business stakeholders, not developers.
+- When a visual clarifies a user flow, state transition, conceptual data relationship, or system boundary, consult `diagram-design` and include a focused diagram near the relevant text. Prefer Mermaid for simple diagrams. Keep business specs technology-independent, omit diagrams that add no clarity, and use the platform-appropriate rendering format.
 - Every user story must be prioritized (P1, P2, P3) and independently testable.
 - The spec must describe a vertical slice (tracer bullet) that (1) has at least one conformance case that runs end-to-end, not a unit-level check; (2) can be demoed, called, or observed by someone outside the implementing team without referring to a future spec; (3) touches every layer the feature requires (data, logic, and surface). Each slice cuts through all integration layers, not a horizontal slice of one layer. Sizing is handled by `complexity-analysis` during decomposition, not in the spec — if a slice is too large to estimate, decomposition will flag it.
 - Resist specifying P2/P3 in detail until P1 is implemented and reviewed. Write a short placeholder for later priorities (intent + assumptions) and expand when the slice becomes current.

.github/plugins/devsquad/agents/devsquad.specify.agent.md

@@ -34,6 +34,7 @@ Without `[CONDUCTOR]` → normal interactive flow.
 ## Style Guide
 
 - Skill `documentation-style` (text formatting)
+- Skill `diagram-design` (focused diagrams that clarify behavior or conceptual relationships without prescribing implementation)
 - Skill `reasoning` (reasoning log and handoff envelope)
 - Skill `work-item-creation` (if creating feature on the board)
 - Skill `domain-glossary` (validate spec terms against glossary, if glossary exists)
@@ -196,6 +197,7 @@ Given this feature description, do the following:
          No limit on DEFERRED markers. Unlike NEEDS CLARIFICATION, DEFERRED items do not block sprint readiness.
     4. Fill in User Scenarios and Tests section
        If no clear user flow: ERROR "Unable to determine user scenarios"
+       When flows, state changes, conceptual entity relationships, or system boundaries are easier to understand visually, consult `diagram-design` and add a focused diagram beside the relevant section. Prefer Mermaid for simple diagrams and apply the platform rendering rules. Keep the diagram at the business level without technology choices or internal implementation details. Omit it when prose or a small table is clearer.
     5. Generate Functional Requirements
        Each requirement must be testable
        Use reasonable defaults for unspecified details (document assumptions in the Assumptions section)

.github/plugins/devsquad/hooks/templates/.github/instructions/specs.instructions.md

@@ -8,6 +8,7 @@ When editing feature specs, follow these rules:
 
 - Focus on **WHAT** users need and **WHY**, never on HOW to implement.
 - Written for business stakeholders, not developers.
+- When a visual clarifies a user flow, state transition, conceptual data relationship, or system boundary, consult `diagram-design` and include a focused diagram near the relevant text. Prefer Mermaid for simple diagrams. Keep business specs technology-independent, omit diagrams that add no clarity, and use the platform-appropriate rendering format.
 - Every user story must be prioritized (P1, P2, P3) and independently testable.
 - The spec must describe a vertical slice (tracer bullet) that (1) has at least one conformance case that runs end-to-end, not a unit-level check; (2) can be demoed, called, or observed by someone outside the implementing team without referring to a future spec; (3) touches every layer the feature requires (data, logic, and surface). Each slice cuts through all integration layers, not a horizontal slice of one layer. Sizing is handled by `complexity-analysis` during decomposition, not in the spec — if a slice is too large to estimate, decomposition will flag it.
 - Every functional requirement must be testable and unambiguous. Vague terms like "fast", "easy", "intuitive" must be quantified.

.github/plugins/devsquad/hooks/templates/docs/features/TEMPLATE.md

@@ -112,6 +112,14 @@ For features whose Change type is not "new surface", recovery semantics belong i
 
 ## User Scenarios & Tests *(required)*
 
+<!--
+  Include a focused diagram near the relevant text when it clarifies a user flow,
+  state change, conceptual entity relationship, or system boundary. Consult the
+  diagram-design skill for notation and platform rendering. Prefer Mermaid for
+  simple diagrams, keep the view technology-independent, and omit visuals that
+  repeat the text without improving understanding. Do not add an empty diagram section.
+-->
+
 <!--
   IMPORTANT: User stories must be PRIORITIZED as user journeys ordered by importance.
   Each user story/journey must be INDEPENDENTLY TESTABLE - meaning that if you implement only ONE of them,

CHANGELOG.md

@@ -18,6 +18,8 @@ See `CONTRIBUTING.md` for full conventions.
 
 ### Template changes (consumer action required)
 
+- Documentation style guidance now recommends plain vocabulary for non-native English speakers, and feature-spec guidance recommends focused diagrams only when they improve understanding. Precise technical terms and existing authored content remain intact.
+- **Consumer action:** Update the plugin and apply the new style and spec guidance to existing instruction files, or preview `sdd-init.sh update-all --dry-run` and review planned overwrites before refreshing managed templates.
 - Documentation style guidance now favors descriptive names and links over invented identifiers in newly written or rewritten text. Preserve existing references, native board IDs, ADR numbers, technical identifiers, and IDs still required by artifact-specific templates and verification rules. No automatic cleanup of existing documents is required.
 - **Consumer action:** Update the DevSquad plugin and apply the naming guidance to existing `.github/copilot-instructions.md` and `.github/instructions/documentation-style.instructions.md`, or preview `sdd-init.sh update-all --dry-run` and review all planned overwrites before applying `sdd-init.sh update-all`.
 - Documentation style instructions and the `documentation-style` skill now explicitly forbid introducing the em-dash character (Unicode U+2014) in newly written or rewritten Markdown and discourage semicolons in prose. Recast sentences for natural flow while preserving their meaning, without mechanically replacing punctuation with abrupt sentence breaks. Semicolons required by code, technical syntax, or verbatim quotations remain allowed. Preserve existing text outside the requested scope. Existing documents do not require a cleanup.

docs/src/content/docs/agents/lifecycle.mdx

@@ -110,6 +110,7 @@ Key characteristics:
 - Written for business stakeholders, not developers
 - Conformance table with minimum 3 cases (happy path, error, edge case)
 - Supports both feature specs and migration specs (v0.5.0+)
+- Uses `diagram-design` for focused diagrams when they clarify user flows, state changes, conceptual relationships, or system boundaries
 
 ---