docs: organize usage guides under How to

README.ja.md

@@ -48,7 +48,7 @@ cd my-project
 
 この例では **GitHub Copilotのデフォルトのスキルモード** を使用しています。他の対応エージェントを使う場合は、`copilot` をお使いのエージェントの[連携キー](https://github.github.io/spec-kit/integrations/index.html)に置き換えてください。
 
-すでにコードがありますか？[既存プロジェクト向けガイド](https://github.github.io/spec-kit/guides/existing-projects.html)を参照してください。バージョン固定でのインストール、その他のインストーラー、CI、トラブルシューティングについては[インストールガイド](https://github.github.io/spec-kit/installation.html)を、既存のインストールを更新する場合は[アップグレードガイド](https://github.github.io/spec-kit/upgrade.html)を参照してください。
+すでにコードがありますか？[既存プロジェクト向けガイド](https://github.github.io/spec-kit/how-to/existing-projects.html)を参照してください。バージョン固定でのインストール、その他のインストーラー、CI、トラブルシューティングについては[インストールガイド](https://github.github.io/spec-kit/installation.html)を、既存のインストールを更新する場合は[アップグレードガイド](https://github.github.io/spec-kit/upgrade.html)を参照してください。
 
 ここから**プロジェクトディレクトリでコーディングエージェントを起動し**、下記のいずれかのプロセスを選んでください。各 `/speckit-*` **スキルはエージェントのチャット内で**、1つずつ呼び出し、結果を確認してから次に進んでください。これらはターミナルコマンドではなく、エージェントのスキルです。エージェントやモードによっては、[異なる呼び出し方](https://github.github.io/spec-kit/integrations/cli.html#command-invocation)を使う場合があります。
 
@@ -141,7 +141,7 @@ specify extension add assess
 
 **拡張機能**は新しい機能を追加し、**プリセット**は既存の挙動を調整し、**ワークフロー**は手順を自動化し、**バンドル**はロールベースのセットアップをパッケージ化します。単発のテンプレート変更にはプロジェクトローカルなオーバーライドを使用してください。
 
-[カスタマイズガイド](https://github.github.io/spec-kit/guides/customization.html) ·
+[カスタマイズガイド](https://github.github.io/spec-kit/how-to/customization.html) ·
 [コミュニティの拡張機能・プリセット・バンドル・ウォークスルー](https://github.github.io/spec-kit/community/overview.html)
 
 <a id="-specify-cli-リファレンス"></a>
@@ -156,7 +156,7 @@ specify extension add assess
 ## ドキュメント
 
 - [CLIリファレンス](https://github.github.io/spec-kit/reference/overview.html) と [プロセスコマンド](https://github.github.io/spec-kit/reference/agentic-sdd.html#command-overview)
-- [SDDの理念](https://github.github.io/spec-kit/concepts/sdd.html)、[完全な方法論](./spec-driven.md)、[既存の仕様の進化](https://github.github.io/spec-kit/guides/evolving-specs.html)
+- [SDDの理念](https://github.github.io/spec-kit/how-to/sdd.html)、[完全な方法論](./spec-driven.md)、[既存の仕様の進化](https://github.github.io/spec-kit/how-to/evolving-specs.html)
 - [プロジェクトの歴史](https://github.github.io/spec-kit/history.html)
 - [Spec KitはSpec Kit自身をどう使っているか](./CONTRIBUTING.md#does-spec-kit-use-spec-kit)
 

README.ko.md

@@ -53,7 +53,7 @@ cd my-project
 예시는 **GitHub Copilot의 기본 스킬 모드**를 기준으로 합니다. 지원되는 다른 에이전트를 쓰려면
 `copilot`을 해당 에이전트의 [통합 키](https://github.github.io/spec-kit/integrations/index.html)로 바꾸세요.
 
-이미 코드가 있나요? [기존 프로젝트 가이드](https://github.github.io/spec-kit/guides/existing-projects.html)를 따르세요.
+이미 코드가 있나요? [기존 프로젝트 가이드](https://github.github.io/spec-kit/how-to/existing-projects.html)를 따르세요.
 특정 버전 고정, 다른 설치 방법, CI, 문제 해결은
 [설치](https://github.github.io/spec-kit/installation.html) 문서를 참고하세요.
 기존 설치를 업데이트하려면 [업그레이드](https://github.github.io/spec-kit/upgrade.html) 문서를 참고하세요.
@@ -161,7 +161,7 @@ specify extension add assess
 **확장**은 기능을 추가하고, **프리셋**은 기존 동작을 조정하며, **워크플로**는 단계를 자동화하고,
 **번들**은 역할별 구성을 하나로 묶습니다. 일회성 템플릿 변경에는 프로젝트 로컬 오버라이드를 사용하세요.
 
-[커스터마이즈 가이드](https://github.github.io/spec-kit/guides/customization.html) ·
+[커스터마이즈 가이드](https://github.github.io/spec-kit/how-to/customization.html) ·
 [커뮤니티 확장, 프리셋, 번들, 실습 가이드](https://github.github.io/spec-kit/community/overview.html)
 
 <a id="-specify-cli-reference"></a>
@@ -175,7 +175,7 @@ specify extension add assess
 ## 문서
 
 - [CLI 레퍼런스](https://github.github.io/spec-kit/reference/overview.html)와 [프로세스 명령어](https://github.github.io/spec-kit/reference/agentic-sdd.html#command-overview)
-- [SDD 철학](https://github.github.io/spec-kit/concepts/sdd.html), [전체 방법론](./spec-driven.md), [기존 스펙 발전시키기](https://github.github.io/spec-kit/guides/evolving-specs.html)
+- [SDD 철학](https://github.github.io/spec-kit/how-to/sdd.html), [전체 방법론](./spec-driven.md), [기존 스펙 발전시키기](https://github.github.io/spec-kit/how-to/evolving-specs.html)
 - [프로젝트 연혁](https://github.github.io/spec-kit/history.html)
 - [Spec Kit이 Spec Kit을 쓰는 방법](./CONTRIBUTING.md#does-spec-kit-use-spec-kit)
 

README.md

@@ -48,7 +48,7 @@ Spec Kit combines ready-to-use processes with composable mechanisms:
 | Run extension commands before or after Spec Kit commands | [Extension hook](https://github.github.io/spec-kit/extensions/api.html#hook-configuration) |
 | Adapt templates, commands, terminology, or methodology | [Preset](https://github.github.io/spec-kit/presets/overview.html) |
 | Enforce organizational or regulatory standards | [Preset](https://github.github.io/spec-kit/presets/overview.html) |
-| Override a template for one project | [Project-local override](https://github.github.io/spec-kit/guides/customization.html#project-local-overrides-and-resolution) |
+| Override a template for one project | [Project-local override](https://github.github.io/spec-kit/how-to/customization.html#project-local-overrides-and-resolution) |
 | Automate prompts, commands, gates, and shell tasks | [Workflow](https://github.github.io/spec-kit/workflows/overview.html) |
 | Modify an installed workflow without forking it | [Workflow overlay](https://github.github.io/spec-kit/workflows/overlays.html) |
 | Add reusable executable behavior to workflows | [Workflow step](https://github.github.io/spec-kit/workflows/developing.html#custom-step-packages) |
@@ -90,7 +90,7 @@ agent in the project directory, then choose a process below.
 For other setups:
 
 - [Installation](https://github.github.io/spec-kit/installation.html) for pinned releases, other installers, CI, and troubleshooting.
-- [Existing projects](https://github.github.io/spec-kit/guides/existing-projects.html) to start with code you already have.
+- [Existing projects](https://github.github.io/spec-kit/how-to/existing-projects.html) to start with code you already have.
 - [Other agents](https://github.github.io/spec-kit/integrations/index.html) for integration keys and [invocation syntax](https://github.github.io/spec-kit/integrations/cli.html#command-invocation).
 - [Upgrade](https://github.github.io/spec-kit/upgrade.html) to update an existing installation.
 
@@ -213,7 +213,7 @@ Combine the [capabilities above](#capabilities) to match your goal:
 Start with the smallest change that meets your needs; you do not have to replace
 the whole process.
 
-[Customization guide](https://github.github.io/spec-kit/guides/customization.html) ·
+[Customization guide](https://github.github.io/spec-kit/how-to/customization.html) ·
 [Community components and walkthroughs](https://github.github.io/spec-kit/community/overview.html)
 
 <a id="-specify-cli-reference"></a>
@@ -227,7 +227,8 @@ the whole process.
 ## Documentation
 
 - [CLI reference](https://github.github.io/spec-kit/reference/overview.html) and [process commands](https://github.github.io/spec-kit/reference/agentic-sdd.html#command-overview)
-- [SDD philosophy](https://github.github.io/spec-kit/concepts/sdd.html), [full methodology](./spec-driven.md), and [evolving existing specs](https://github.github.io/spec-kit/guides/evolving-specs.html)
+- [How-to guides](https://github.github.io/spec-kit/how-to/index.html) for applying Spec Kit to your project work
+- [SDD philosophy](https://github.github.io/spec-kit/how-to/sdd.html), [full methodology](./spec-driven.md), and [evolving existing specs](https://github.github.io/spec-kit/how-to/evolving-specs.html)
 - [Project history](https://github.github.io/spec-kit/history.html)
 - [How Spec Kit uses Spec Kit](./CONTRIBUTING.md#does-spec-kit-use-spec-kit)
 

README.zh-CN.md

@@ -57,7 +57,7 @@ CLI 只需安装一次，项目只需初始化一次；以下三种流程共用
 如需使用其他助手，将 `copilot` 替换为对应的
 [集成标识](https://github.github.io/spec-kit/integrations/index.html)。
 
-已有代码？请参阅[现有项目指南](https://github.github.io/spec-kit/guides/existing-projects.html)。
+已有代码？请参阅[现有项目指南](https://github.github.io/spec-kit/how-to/existing-projects.html)。
 锁定版本、其他安装方式、CI 与故障排查见[安装指南](https://github.github.io/spec-kit/installation.html)；
 更新已安装的 CLI 和项目文件见[升级指南](https://github.github.io/spec-kit/upgrade.html)。
 
@@ -160,7 +160,7 @@ specify extension add assess
 **扩展**新增能力，**预设**调整现有行为，**工作流**自动执行步骤，**捆绑包**打包面向角色的配置。
 单个项目的一次性模板调整可使用项目本地覆盖；流程或术语的本地化可使用预设。
 
-[定制指南](https://github.github.io/spec-kit/guides/customization.html) ·
+[定制指南](https://github.github.io/spec-kit/how-to/customization.html) ·
 [社区扩展、预设、捆绑包与实战演练](https://github.github.io/spec-kit/community/overview.html)
 
 <a id="-specify-cli-参考"></a>
@@ -176,7 +176,7 @@ specify extension add assess
 以下链接指向英文指南。工具升级与功能规范演进是两件事：升级时更新工具文件，需求变化时更新 `specs/` 制品。
 
 - [CLI 参考](https://github.github.io/spec-kit/reference/overview.html)与[流程命令](https://github.github.io/spec-kit/reference/agentic-sdd.html#command-overview)
-- [SDD 理念](https://github.github.io/spec-kit/concepts/sdd.html)、[完整方法论](./spec-driven.md)与[现有规范演进](https://github.github.io/spec-kit/guides/evolving-specs.html)
+- [SDD 理念](https://github.github.io/spec-kit/how-to/sdd.html)、[完整方法论](./spec-driven.md)与[现有规范演进](https://github.github.io/spec-kit/how-to/evolving-specs.html)
 - [项目历史](https://github.github.io/spec-kit/history.html)
 - [Spec Kit 如何使用 Spec Kit](./CONTRIBUTING.md#does-spec-kit-use-spec-kit)
 

docs/README.md

@@ -31,7 +31,16 @@ To build the documentation locally:
 - `guides/agentic-sdlc.md` - How Spec Kit applies agentic and conventional SDLC practices to itself
 - `guides/bugfix.md` - Bug-fixing walkthrough
 - `guides/assessment.md` - Idea assessment walkthrough
-- `guides/customization.md` - Choosing and combining customization building blocks
+- `how-to/index.md` - How-to guide directory
+- `how-to/sdd.md` - Understanding Spec-Driven Development
+- `how-to/existing-projects.md` - Adopting Spec Kit in an existing project
+- `how-to/monorepo.md` - Working in a monorepo
+- `how-to/contract-driven-development.md` - Defining and evolving component contracts
+- `how-to/complex-features.md` - Implementing complex features in bounded runs
+- `how-to/spec-of-specs.md` - Breaking large features into smaller specifications
+- `how-to/spec-persistence.md` - Choosing a specification persistence model
+- `how-to/evolving-specs.md` - Maintaining specifications after delivery
+- `how-to/customization.md` - Adapting Spec Kit to your process
 - `reference/catalogs.md` - Catalog discovery, trust, private sources, and precedence
 - `extensions/overview.md` - Extension user guide
 - `extensions/cli.md` - Extension management CLI reference

docs/bundles/overview.md

@@ -95,4 +95,4 @@ were already installed are not rolled back after a later failure.
 - [Publishing bundles](publishing.md)
 - [Community bundles](../community/bundles.md)
 - [Community walkthroughs](../community/walkthroughs.md)
-- [Choosing customization building blocks](../guides/customization.md)
+- [Choosing customization building blocks](../how-to/customization.md)

docs/community/overview.md

@@ -54,4 +54,4 @@ To publish your own work, follow the
 the [Presets Publishing Guide](../presets/publishing.md),
 the [Bundle Publishing Guide](../bundles/publishing.md), or the
 [Community Workflow Step Types guide](workflow-steps.md). For help choosing a
-component type, see [Customize Spec Kit](../guides/customization.md).
+component type, see [Adapt Spec Kit to your process](../how-to/customization.md).

docs/docfx.json

@@ -7,9 +7,9 @@
           "toc.yml",
           "community/*.md",
           "bundles/*.md",
-          "concepts/*.md",
           "extensions/*.md",
           "guides/*.md",
+          "how-to/*.md",
           "integrations/*.md",
           "presets/*.md",
           "workflows/*.md",

docs/extensions/overview.md

@@ -755,4 +755,4 @@ artifact resolution priority.
 - [Developing extensions](developing.md)
 - [Extension API reference](api.md)
 - [Publishing extensions](publishing.md)
-- [Spec persistence models](../concepts/spec-persistence.md)
+- [Spec persistence models](../how-to/spec-persistence.md)

docs/guides/agentic-sdlc.md

@@ -233,7 +233,7 @@ each combining an extension with a resumable *Spec Kit workflow* and a human
 review gate. It also ships the
 [`lean` preset](https://github.com/github/spec-kit/tree/main/presets/lean)
 to demonstrate an alternative way of shaping core SDD guidance. These are
-Spec Kit's own [extensions, presets, workflows, and bundles](customization.md),
+Spec Kit's own [extensions, presets, workflows, and bundles](../how-to/customization.md),
 not the repository's GitHub Actions workflows.
 
 ★ Beyond core feature delivery, agentic community-submission workflows for

docs/guides/assessment.md

@@ -12,7 +12,7 @@ The bundled, opt-in **assess** extension provides five stages:
 
 [Install Spec Kit and initialize a project](../installation.md). An empty project
 is enough, or you can use an
-[existing repository](existing-projects.md) when the idea relates to its code.
+[existing repository](../how-to/existing-projects.md) when the idea relates to its code.
 In a terminal at the initialized project root, install the extension:
 
 ```bash

docs/guides/bugfix.md

@@ -12,7 +12,7 @@ The bundled, opt-in **bug** extension separates the work into
 
 First [install Spec Kit](../installation.md) and initialize the repository that
 contains the bug. If it already contains code, follow
-[Adopting Spec Kit in an Existing Project](existing-projects.md).
+[Adopting Spec Kit in an Existing Project](../how-to/existing-projects.md).
 
 In a terminal at the initialized project root, install the extension:
 

docs/concepts/complex-features.md → docs/how-to/complex-features.md

@@ -1,4 +1,4 @@
-# Handling Complex Features
+# How to implement complex features in bounded runs
 
 Large or complex features often run smoothly through `/speckit.specify`,
 `/speckit.plan`, and `/speckit.tasks`, then degrade during implementation. In

docs/guides/contract-driven-development.md → docs/how-to/contract-driven-development.md

@@ -1,4 +1,4 @@
-# Contract-Driven Development
+# How to define and evolve contracts between components
 
 When a component exposes an interface to an external consumer, define the
 contract that consumer can rely on. **Contract-driven development** means

docs/guides/customization.md → docs/how-to/customization.md

@@ -1,4 +1,4 @@
-# Customize Spec Kit
+# How to adapt Spec Kit to your way of working
 
 The three first-party processes are starting points, not limits. Keep the
 built-in SDD process, add bug fixing or assessment, adapt a process to your
@@ -45,7 +45,7 @@ specify extension add <extension-name>
 
 Examples include Jira integration, post-implementation code review, V-Model test
 traceability, and project health diagnostics. The bundled
-[bug](bugfix.md) and [assess](assessment.md) extensions are first-party examples.
+[bug](../guides/bugfix.md) and [assess](../guides/assessment.md) extensions are first-party examples.
 Browse [community extensions](../community/extensions.md), or use the
 [extension CLI reference](../extensions/cli.md) for management and the
 [extension user guide](../extensions/overview.md#configuration) for configuration.

docs/guides/evolving-specs.md → docs/how-to/evolving-specs.md

@@ -1,4 +1,4 @@
-# Evolving Specs in Existing Projects
+# How to maintain specifications after delivery
 
 If the repository has not been initialized with Spec Kit yet, start with
 [Adopting Spec Kit in an Existing Project](existing-projects.md). This page
@@ -18,7 +18,7 @@ feature artifacts are maintained when requirements or implementation insights
 change an existing project. None is required or the default.
 
 For the conceptual model definitions, see
-[Spec Persistence Models](../concepts/spec-persistence.md).
+[Spec Persistence Models](spec-persistence.md).
 
 ## Shared Feature Delivery Loop
 

docs/guides/existing-projects.md → docs/how-to/existing-projects.md

@@ -1,4 +1,4 @@
-# Adopting Spec Kit in an Existing Project
+# How to adopt Spec Kit in an existing project
 
 You do not need to recreate an existing system from specifications before using
 Spec Kit. Initialize the repository in place, capture the rules that matter,
@@ -35,8 +35,8 @@ specifications for existing behavior.
 
 The remaining steps illustrate adopting **SDD** for a bounded feature. If your
 first task is a repair, you can instead follow the
-[bug-fixing quickstart](bugfix.md) after initialization; to evaluate a proposal,
-use the [idea assessment quickstart](assessment.md). Neither process requires
+[bug-fixing quickstart](../guides/bugfix.md) after initialization; to evaluate a proposal,
+use the [idea assessment quickstart](../guides/assessment.md). Neither process requires
 completing the SDD steps below first.
 
 Run `/speckit.constitution` with principles that are already true for the
@@ -100,7 +100,7 @@ artifacts:
 - Allow discoveries to flow back from code, tasks, or plans, then reconcile the
   full artifact set.
 
-The [Spec Persistence Models](../concepts/spec-persistence.md) page compares
+The [Spec Persistence Models](spec-persistence.md) page compares
 these choices. The [Evolving Specs guide](evolving-specs.md) provides the
 maintenance loop for each model.