Skip to content

Commit efdff31

Browse files
mnriemmnriem
authored
docs: revamp landing page with four-pillar card layout (#2531)
Rewrite docs/index.md from a philosophy essay into a landing page organized around four pillars: Spec-driven by default, Use any coding agent, Make it your own, and Integrate into your organization. - Add hero section with GitHub Spec Kit branding and CTA buttons - Add 2x2 pillar card grid with GitHub Primer color accents - Add community stats section (96K stars, 200+ contributors, etc.) - Add navigation cards and footer install CTA - Move SDD philosophy content to docs/concepts/sdd.md - Add custom DocFX template overlay with card CSS and dark mode - Set landing layout for index.md via fileMetadata - Update toc.yml and docfx.json for new concepts section
1 parent 372b22a commit efdff31

5 files changed

Lines changed: 451 additions & 43 deletions

File tree

‎docs/concepts/sdd.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# What is Spec-Driven Development?
2+
3+
Spec-Driven Development **flips the script** on traditional software development. For decades, code has been king — specifications were just scaffolding we built and discarded once the "real work" of coding began. Spec-Driven Development changes this: **specifications become executable**, directly generating working implementations rather than just guiding them.
4+
5+
## Core Philosophy
6+
7+
Spec-Driven Development is a structured process that emphasizes:
8+
9+
- **Intent-driven development** where specifications define the "*what*" before the "*how*"
10+
- **Rich specification creation** using guardrails and organizational principles
11+
- **Multi-step refinement** rather than one-shot code generation from prompts
12+
- **Heavy reliance** on advanced AI model capabilities for specification interpretation
13+
14+
## Development Phases
15+
16+
| Phase | Focus | Key Activities |
17+
|-------|-------|----------------|
18+
| **0-to-1 Development** ("Greenfield") | Generate from scratch | <ul><li>Start with high-level requirements</li><li>Generate specifications</li><li>Plan implementation steps</li><li>Build production-ready applications</li></ul> |
19+
| **Creative Exploration** | Parallel implementations | <ul><li>Explore diverse solutions</li><li>Support multiple technology stacks & architectures</li><li>Experiment with UX patterns</li></ul> |
20+
| **Iterative Enhancement** ("Brownfield") | Brownfield modernization | <ul><li>Add features iteratively</li><li>Modernize legacy systems</li><li>Adapt processes</li></ul> |
21+
22+
## Experimental Goals
23+
24+
Our research and experimentation focus on:
25+
26+
### Technology Independence
27+
28+
- Create applications using diverse technology stacks
29+
- Validate the hypothesis that Spec-Driven Development is a process not tied to specific technologies, programming languages, or frameworks
30+
31+
### Enterprise Constraints
32+
33+
- Demonstrate mission-critical application development
34+
- Incorporate organizational constraints (cloud providers, tech stacks, engineering practices)
35+
- Support enterprise design systems and compliance requirements
36+
37+
### User-Centric Development
38+
39+
- Build applications for different user cohorts and preferences
40+
- Support various development approaches (from vibe-coding to AI-native development)
41+
42+
### Creative & Iterative Processes
43+
44+
- Validate the concept of parallel implementation exploration
45+
- Provide robust iterative feature development workflows
46+
- Extend processes to handle upgrades and modernization tasks

‎docs/docfx.json‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
"*.md",
77
"toc.yml",
88
"community/*.md",
9+
"concepts/*.md",
910
"reference/*.md",
1011
"install/*.md"
1112
]
@@ -50,7 +51,8 @@
5051
"fileMetadataFiles": [],
5152
"template": [
5253
"default",
53-
"modern"
54+
"modern",
55+
"template"
5456
],
5557
"postProcessors": [],
5658
"markdownEngineName": "markdig",
@@ -68,6 +70,11 @@
6870
"repo": "https://github.com/github/spec-kit",
6971
"branch": "main"
7072
}
73+
},
74+
"fileMetadata": {
75+
"_layout": {
76+
"index.md": "landing"
77+
}
7178
}
7279
}
7380
}

‎docs/index.md‎

Lines changed: 127 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,67 +1,152 @@
1-
# Spec Kit
1+
<div class="landing-hero">
22

3-
*Build high-quality software faster.*
3+
# GitHub Spec Kit
44

5-
**An effort to allow organizations to focus on product scenarios rather than writing undifferentiated code with the help of Spec-Driven Development.**
5+
**Define what to build before building it — with any AI coding agent.**
66

7-
## What is Spec-Driven Development?
7+
Spec Kit is a toolkit for [Spec-Driven Development](concepts/sdd.md) (SDD), a methodology that puts specifications at the center of AI-assisted software development. Instead of jumping straight to code, you describe *what* to build, refine it through structured phases, and let your AI coding agent implement it.
88

9-
Spec-Driven Development **flips the script** on traditional software development. For decades, code has been king — specifications were just scaffolding we built and discarded once the "real work" of coding began. Spec-Driven Development changes this: **specifications become executable**, directly generating working implementations rather than just guiding them.
9+
<a href="installation.md" class="btn btn-primary btn-lg">Install Spec Kit</a>&nbsp;
10+
<a href="quickstart.md" class="btn btn-outline-primary btn-lg">Quick Start</a>
1011

11-
## Getting Started
12+
</div>
1213

13-
- [Installation Guide](installation.md)
14-
- [Quick Start Guide](quickstart.md)
15-
- [Upgrade Guide](upgrade.md)
16-
- [Local Development](local-development.md)
14+
---
1715

18-
## Core Philosophy
16+
<div class="pillar-grid">
1917

20-
Spec-Driven Development is a structured process that emphasizes:
18+
<div class="pillar-card">
2119

22-
- **Intent-driven development** where specifications define the "*what*" before the "*how*"
23-
- **Rich specification creation** using guardrails and organizational principles
24-
- **Multi-step refinement** rather than one-shot code generation from prompts
25-
- **Heavy reliance** on advanced AI model capabilities for specification interpretation
20+
### Spec-driven by default
2621

27-
## Development Phases
22+
The core SDD process ships ready to use: **Spec → Plan → Tasks → Implement**.
2823

29-
| Phase | Focus | Key Activities |
30-
|-------|-------|----------------|
31-
| **0-to-1 Development** ("Greenfield") | Generate from scratch | <ul><li>Start with high-level requirements</li><li>Generate specifications</li><li>Plan implementation steps</li><li>Build production-ready applications</li></ul> |
32-
| **Creative Exploration** | Parallel implementations | <ul><li>Explore diverse solutions</li><li>Support multiple technology stacks & architectures</li><li>Experiment with UX patterns</li></ul> |
33-
| **Iterative Enhancement** ("Brownfield") | Brownfield modernization | <ul><li>Add features iteratively</li><li>Modernize legacy systems</li><li>Adapt processes</li></ul> |
24+
Define what to build before building it. Rich templates, quality checklists, and cross-artifact analysis come out of the box. Each phase produces a Markdown artifact that feeds the next — giving your AI coding agent structured context instead of ad-hoc prompts.
3425

35-
## Experimental Goals
26+
<a href="quickstart.md" class="pillar-link">Walk through the workflow →</a>
3627

37-
Our research and experimentation focus on:
28+
</div>
3829

39-
### Technology Independence
30+
<div class="pillar-card">
4031

41-
- Create applications using diverse technology stacks
42-
- Validate the hypothesis that Spec-Driven Development is a process not tied to specific technologies, programming languages, or frameworks
32+
### Use any coding agent
4333

44-
### Enterprise Constraints
34+
<span class="pillar-stat">30 integrations</span> — Copilot, Gemini, Codex, Windsurf, Claude, Forge, Kiro, and more. Switch freely between agents with a single command. No lock-in.
4535

46-
- Demonstrate mission-critical application development
47-
- Incorporate organizational constraints (cloud providers, tech stacks, engineering practices)
48-
- Support enterprise design systems and compliance requirements
36+
Run `specify init` with your agent of choice and Spec Kit sets up the right command files, context rules, and directory structures automatically. If your agent isn't listed, the `generic` integration is an escape hatch for any tool.
4937

50-
### User-Centric Development
38+
<a href="reference/integrations.md" class="pillar-link">See all integrations →</a>
5139

52-
- Build applications for different user cohorts and preferences
53-
- Support various development approaches (from vibe-coding to AI-native development)
40+
</div>
5441

55-
### Creative & Iterative Processes
42+
<div class="pillar-card">
5643

57-
- Validate the concept of parallel implementation exploration
58-
- Provide robust iterative feature development workflows
59-
- Extend processes to handle upgrades and modernization tasks
44+
### Make it your own
6045

61-
## Contributing
46+
<span class="pillar-stat">91 community extensions</span> (50+ authors), <span class="pillar-stat">18 presets</span>, and growing — including entirely different SDD processes:
6247

63-
Please see our [Contributing Guide](https://github.com/github/spec-kit/blob/main/CONTRIBUTING.md) for information on how to contribute to this project.
48+
- **AIDE** — 7-step AI-driven engineering lifecycle
49+
- **Canon** — baseline-driven workflows (spec-first, code-first, spec-drift)
50+
- **Product Forge** — product-management-oriented SDD
51+
- **FX→.NET** — end-to-end .NET Framework migration across 7 phases
52+
- **MAQA** — multi-agent orchestration with quality assurance gates
6453

65-
## Support
54+
Tune the core process with presets, extend it with extensions, orchestrate it with workflows, or replace it entirely. Build and publish your own.
6655

67-
For support, please check our [Support Guide](https://github.com/github/spec-kit/blob/main/SUPPORT.md) or open an issue on GitHub.
56+
<a href="community/presets.md" class="pillar-link">Browse community presets →</a>
57+
58+
</div>
59+
60+
<div class="pillar-card">
61+
62+
### Integrate into your organization
63+
64+
Works offline, behind firewalls, and on **Windows, macOS, and Linux**. Host your own extension and preset catalogs so your organization controls what gets installed.
65+
66+
Community extensions like CI Guard and Architecture Guard add compliance gates and governance that fit the way your team already works.
67+
68+
<a href="installation.md" class="pillar-link">Installation guide →</a>&nbsp;&nbsp;
69+
<a href="reference/extensions.md" class="pillar-link">Extensions reference →</a>
70+
71+
</div>
72+
73+
</div>
74+
75+
---
76+
77+
<div class="community-section">
78+
79+
## Built by the community
80+
81+
**200+ contributors** power the Spec Kit ecosystem — from core integrations to entirely new development processes. Anyone can create and publish an extension, preset, or workflow.
82+
83+
<div class="stats-grid">
84+
<div class="stat-item">
85+
<span class="stat-number">96K+</span>
86+
<span class="stat-label">GitHub stars</span>
87+
</div>
88+
<div class="stat-item">
89+
<span class="stat-number">200+</span>
90+
<span class="stat-label">Contributors</span>
91+
</div>
92+
<div class="stat-item">
93+
<span class="stat-number">30</span>
94+
<span class="stat-label">Integrations</span>
95+
</div>
96+
<div class="stat-item">
97+
<span class="stat-number">91</span>
98+
<span class="stat-label">Extensions</span>
99+
</div>
100+
<div class="stat-item">
101+
<span class="stat-number">18</span>
102+
<span class="stat-label">Presets</span>
103+
</div>
104+
<div class="stat-item">
105+
<span class="stat-number">4</span>
106+
<span class="stat-label">Friends projects</span>
107+
</div>
108+
</div>
109+
110+
<a href="community/presets.md">Presets</a> · <a href="community/walkthroughs.md">Walkthroughs</a> · <a href="community/friends.md">Friends</a>
111+
112+
</div>
113+
114+
---
115+
116+
## Explore the docs
117+
118+
<div class="nav-cards">
119+
<a href="quickstart.md" class="nav-card">
120+
<strong>Getting Started</strong>
121+
<span>Install, configure, and run your first SDD workflow</span>
122+
</a>
123+
<a href="reference/overview.md" class="nav-card">
124+
<strong>Reference</strong>
125+
<span>Core commands, integrations, extensions, presets, and workflows</span>
126+
</a>
127+
<a href="community/presets.md" class="nav-card">
128+
<strong>Community</strong>
129+
<span>Presets, walkthroughs, and friend projects</span>
130+
</a>
131+
<a href="local-development.md" class="nav-card">
132+
<strong>Development</strong>
133+
<span>Contribute to Spec Kit</span>
134+
</a>
135+
<a href="concepts/sdd.md" class="nav-card">
136+
<strong>What is SDD?</strong>
137+
<span>The philosophy behind Spec-Driven Development</span>
138+
</a>
139+
</div>
140+
141+
---
142+
143+
<div class="footer-cta">
144+
145+
```bash
146+
uvx --from git+https://github.com/github/spec-kit.git
147+
specify init my-project --integration copilot
148+
```
149+
150+
Ready to start? Follow the [Quick Start Guide](quickstart.md).
151+
152+
</div>

0 commit comments

Comments
 (0)