Add a dedicated Specs navigation section

CHANGELOG.md

@@ -25,6 +25,10 @@ See `CONTRIBUTING.md` for full conventions.
 - 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
+
+- A dedicated Specs section in the documentation navigation, with feature and migration template links, authoring guidance, AI capability specs, and spec amendment guidance.
+
 ### Changed
 
 - Work item creation now computes the complete required label/tag set, creates missing GitHub labels before issue creation, verifies stored metadata, and reports recoverable partial batches instead of silently continuing. Kickoff and specification agents have the minimum tools needed to apply and repair this metadata.

docs/astro.config.mjs

@@ -86,13 +86,20 @@ items: [
 { label: 'Philosophy & Approach', slug: 'delivery-guardrails' },
 { label: 'Impact Classification', slug: 'concepts/impact-classification', badge: { text: 'Core', variant: 'tip' } },
 { label: 'Comprehension Checkpoints', slug: 'concepts/comprehension-checkpoints', badge: { text: 'Core', variant: 'tip' } },
-{ label: 'Spec Amendment', slug: 'concepts/spec-amendment', badge: { text: 'Core', variant: 'tip' } },
-{ label: 'AI Capability Specs', slug: 'concepts/ai-capability-specs' },
 { label: 'Implementation Rules', slug: 'guardrails/implementation' },
 { label: 'Team Coordination', slug: 'guardrails/team-coordination' },
 ],
 },
 {
+label: 'Specs',
+collapsed: true,
+items: [
+{ label: 'Overview', slug: 'specs' },
+{ label: 'AI Capability Specs', slug: 'concepts/ai-capability-specs' },
+{ label: 'Spec Amendment', slug: 'concepts/spec-amendment', badge: { text: 'Core', variant: 'tip' } },
+],
+},
+{
 label: 'Architecture',
 collapsed: true,
 items: [

docs/src/content/docs/specs/index.mdx

@@ -0,0 +1,42 @@
+---
+title: Specifications
+description: Feature and migration specs, their templates, and how they guide implementation.
+banner:
+  content: |
+    This project is under active development and subject to breaking changes. See the <a href="/devsquad-copilot/changelog/">changelog</a> for release notes.
+---
+
+Specifications describe the behavior a project needs and how to verify it. This section brings together the spec workflow, templates, and guidance for maintaining specs during implementation.
+
+## Choose a Spec Type
+
+| Type | Use when | Consumer repository location |
+|------|----------|------------------------------|
+| Feature | Adding or changing functionality and user behavior | `docs/features/<name>/spec.md` |
+| Migration | Moving a system while preserving required behavior, data, and operational guarantees | `docs/migrations/<name>/spec.md` |
+
+Run `/devsquad.specify` with the intended behavior or migration goal. Keep technical implementation choices in `plan.md` and ADRs.
+
+## Templates
+
+`devsquad.init` installs these templates into the consumer repository. The framework maintains their sources in the plugin:
+
+- [Feature spec template](https://github.com/microsoft/devsquad-copilot/blob/main/.github/plugins/devsquad/hooks/templates/docs/features/TEMPLATE.md)
+- [Migration spec template](https://github.com/microsoft/devsquad-copilot/blob/main/.github/plugins/devsquad/hooks/templates/docs/migrations/TEMPLATE.md)
+
+These are authoring templates, not completed product specifications. Specs created for your project remain in your repository.
+
+## Write and Maintain a Spec
+
+1. Describe the user journey, scope, and observable behavior using plain language.
+2. Define measurable requirements and conformance cases covering success, failure, and edge conditions.
+3. Add a focused diagram when it clarifies a flow, state change, conceptual relationship, or system boundary. Follow the `diagram-design` skill and keep business-facing diagrams technology-independent.
+4. Follow the installed template's required fields, then create the technical plan and decompose the approved scope into work items.
+5. When implementation reveals a mismatch, amend the affected section through `devsquad.refine` and preserve unrelated requirements and existing references.
+
+## Related Guidance
+
+- [Build a Feature](../guides/feature-walkthrough/) for an end-to-end example of the delivery workflow
+- [AI Capability Specs](../concepts/ai-capability-specs/) for features that embed AI behavior
+- [Spec Amendment](../concepts/spec-amendment/) for controlled changes to an existing spec
+- [Lifecycle Agents](../agents/lifecycle/#devsquadspecify-) for the specification agent