diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index b55a3c2..149f167 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -79,6 +79,9 @@ For code rules (values, style, tests, performance, git, PRs), follow `.github/do When editing or creating markdown documents: - No emojis or decorative Unicode (such as arrows, bullets, checkmarks, stars). +- Do not introduce the em-dash character (Unicode U+2014) in newly written or rewritten Markdown text. Rephrase the sentence instead. +- Avoid semicolons in newly written or rewritten prose. Recast the sentence naturally using a conjunction, a clearer sentence structure, or separate sentences when appropriate. Preserve the original meaning, and avoid turning connected ideas into a series of short, abrupt sentences. Keep semicolons required by code, technical syntax, or verbatim quotations. +- Preserve existing text outside the requested scope. Do not scan or rewrite documents solely to remove existing em dashes or semicolons. - No hyphens or dashes as separators between concepts. Rewrite the sentence. - No `#` in free text (Azure DevOps converts it to a work item link). - No contrastive framing ("not just X, it's Y", "goes beyond", "more than just"). Describe directly. diff --git a/.github/instructions/documentation-style.instructions.md b/.github/instructions/documentation-style.instructions.md index b90acf4..13fe192 100644 --- a/.github/instructions/documentation-style.instructions.md +++ b/.github/instructions/documentation-style.instructions.md @@ -8,6 +8,9 @@ When editing markdown documentation, follow these formatting rules: - Ensure there are no spelling errors. - Do not use emojis or decorative Unicode characters (such as →, •, ★, ✓, 🎯, ✅, ⚠️, ❌). +- Do not introduce the em-dash character (Unicode U+2014) in newly written or rewritten Markdown text. Rephrase the sentence instead. +- Avoid semicolons in newly written or rewritten prose. Recast the sentence naturally using a conjunction, a clearer sentence structure, or separate sentences when appropriate. Preserve the original meaning, and avoid turning connected ideas into a series of short, abrupt sentences. Keep semicolons required by code, technical syntax, or verbatim quotations. +- Preserve existing text outside the requested scope. Do not scan or rewrite documents solely to remove existing em dashes or semicolons. - Do not use hyphens or dashes as separators between concepts ("concept A - concept B"). Rewrite the sentence. - Do not use `#` in free text (Azure DevOps converts it to a work item link). Use "first", "third option", etc. - Do not use promotional language: "it's not just X, it's Y", "goes beyond...", "more than just...". Describe directly. diff --git a/.github/plugins/devsquad/hooks/templates/.github/copilot-instructions.md b/.github/plugins/devsquad/hooks/templates/.github/copilot-instructions.md index e0c688e..b751686 100644 --- a/.github/plugins/devsquad/hooks/templates/.github/copilot-instructions.md +++ b/.github/plugins/devsquad/hooks/templates/.github/copilot-instructions.md @@ -86,6 +86,9 @@ For code rules (values, style, tests, performance, git, PRs), follow `.github/do When editing or creating markdown documents: - No emojis or decorative Unicode (such as arrows, bullets, checkmarks, stars). +- Do not introduce the em-dash character (Unicode U+2014) in newly written or rewritten Markdown text. Rephrase the sentence instead. +- Avoid semicolons in newly written or rewritten prose. Recast the sentence naturally using a conjunction, a clearer sentence structure, or separate sentences when appropriate. Preserve the original meaning, and avoid turning connected ideas into a series of short, abrupt sentences. Keep semicolons required by code, technical syntax, or verbatim quotations. +- Preserve existing text outside the requested scope. Do not scan or rewrite documents solely to remove existing em dashes or semicolons. - No hyphens or dashes as separators between concepts. Rewrite the sentence. - No `#` in free text (Azure DevOps converts it to a work item link). - No contrastive framing ("not just X, it's Y", "goes beyond", "more than just"). Describe directly. diff --git a/.github/plugins/devsquad/hooks/templates/.github/instructions/documentation-style.instructions.md b/.github/plugins/devsquad/hooks/templates/.github/instructions/documentation-style.instructions.md index bb56120..4d55212 100644 --- a/.github/plugins/devsquad/hooks/templates/.github/instructions/documentation-style.instructions.md +++ b/.github/plugins/devsquad/hooks/templates/.github/instructions/documentation-style.instructions.md @@ -8,6 +8,9 @@ When editing markdown documentation, follow these formatting rules: - Ensure there are no spelling errors. - Do not use emojis or decorative Unicode characters (such as →, •, ★, ✓, 🎯, ✅, ⚠️, ❌). +- Do not introduce the em-dash character (Unicode U+2014) in newly written or rewritten Markdown text. Rephrase the sentence instead. +- Avoid semicolons in newly written or rewritten prose. Recast the sentence naturally using a conjunction, a clearer sentence structure, or separate sentences when appropriate. Preserve the original meaning, and avoid turning connected ideas into a series of short, abrupt sentences. Keep semicolons required by code, technical syntax, or verbatim quotations. +- Preserve existing text outside the requested scope. Do not scan or rewrite documents solely to remove existing em dashes or semicolons. - Do not use hyphens or dashes as separators between concepts ("concept A - concept B"). Rewrite the sentence. - Do not use `#` in free text (Azure DevOps converts it to a work item link). Use "first", "third option", etc. - Do not use promotional language: "it's not just X, it's Y", "goes beyond...", "more than just...". Describe directly. diff --git a/.github/plugins/devsquad/skills/documentation-style/SKILL.md b/.github/plugins/devsquad/skills/documentation-style/SKILL.md index 7b00c40..16ca8b8 100644 --- a/.github/plugins/devsquad/skills/documentation-style/SKILL.md +++ b/.github/plugins/devsquad/skills/documentation-style/SKILL.md @@ -10,6 +10,9 @@ This guide defines standards for all documentation generated in the project. ## Formatting - Ensure there are no spelling errors. Avoid emojis and decorative Unicode characters (such as →, •, ★, ✓, 🎯, ✅). +- Do not introduce the em-dash character (Unicode U+2014) in newly written or rewritten Markdown text. Rephrase the sentence instead. +- Avoid semicolons in newly written or rewritten prose. Recast the sentence naturally using a conjunction, a clearer sentence structure, or separate sentences when appropriate. Preserve the original meaning, and avoid turning connected ideas into a series of short, abrupt sentences. Keep semicolons required by code, technical syntax, or verbatim quotations. +- Preserve existing text outside the requested scope. Do not scan or rewrite documents solely to remove existing em dashes or semicolons. - Avoid hyphens or dashes as separators between concepts. Instead of "concept A - concept B", rewrite the sentence. - Prefer lists and tables over long paragraphs. - Keep documents concise: specs and ADRs should be 1-2 pages, not novels. diff --git a/CHANGELOG.md b/CHANGELOG.md index 48ede69..9e92029 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,11 @@ See `CONTRIBUTING.md` for full conventions. ## [Unreleased] +### Template changes (consumer action required) + +- 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. +- **Consumer action:** Update the DevSquad plugin for the skill change. Apply the same scoped rules to existing `.github/copilot-instructions.md` and `.github/instructions/documentation-style.instructions.md` files, or preview `sdd-init.sh update-all --dry-run` and review all planned overwrites before applying `sdd-init.sh update-all` to refresh managed files. + ### Added (Agent Intent Governance — selective Architecture of Intent adoption) Closes three structural gaps in the framework: framework agents had no explicit behavioral envelope (a reviewer reading `devsquad.implement.agent.md` could not determine in under a minute what the agent was authorized to do, must never do, or how it composes sub-agents); consumer specs describing AI capabilities had no canonical fragment for operational cost commitments; the failure-diagnosis surface had no taxonomy mapping a failure to the upstream artifact that owns the fix. Vocabulary and discipline drawn from "The Architecture of Intent" by Marcel Aldecoa (`https://marcelaldecoa.github.io/TheArchitectureOfIntent/`). The framework adopts the load-bearing principles and deliberately omits parts of the source vocabulary that add no behavior (see "AoI constructs considered and not adopted" in ADR 0014). diff --git a/docs/src/content/docs/skills/quality.mdx b/docs/src/content/docs/skills/quality.mdx index 556c28c..d91f2f7 100644 --- a/docs/src/content/docs/skills/quality.mdx +++ b/docs/src/content/docs/skills/quality.mdx @@ -115,11 +115,17 @@ Formatting and style rules for all markdown documentation generated in the proje |------|--------| | Spelling | No errors allowed | | Emojis | Prohibited, including decorative Unicode | -| Separators | No hyphens between concepts; rewrite the sentence | +| Em dashes | Rephrase sentences without introducing Unicode U+2014 in newly written or rewritten Markdown | +| Semicolons | Recast newly written or rewritten prose naturally using conjunctions, clearer structure, or separate sentences when appropriate | +| Separators | Rephrase sentences instead of separating concepts with hyphens | | Work item references | Never use `#` in free text (Azure DevOps auto-links) | | Structure | Lists and tables over long paragraphs | | Length | Specs and ADRs should be 1-2 pages | +Preserve meaning and natural flow rather than mechanically replacing semicolons with periods or splitting connected ideas into short, abrupt sentences. Keep semicolons required by code, technical syntax, or verbatim quotations. + +Preserve existing text outside the requested scope. Do not scan or rewrite documents solely to remove existing em dashes or semicolons. Ordinary hyphens in compound words, identifiers, Markdown lists, and tables remain allowed. + **Language rules:** | Avoid | Prefer | |-------|--------|