Skip to content

Commit f39e59e

Browse files
djm81djm81
authored
docs: improve documentation structure with unified command chains and cross-linking (#80)
* docs: improve documentation structure with unified command chains and cross-linking (#79) Co-authored-by: Dominikus Nold <[email protected]> * docs: add integrations overview guide (optional task 6.4) - Create integrations-overview.md with comprehensive overview of all integrations - Add links from integration guides to integrations-overview.md - Add link to integrations-overview.md in docs/README.md - Complete optional task 6.4 from improve-documentation-structure change * docs: fix linting errors in integrations-overview.md - Fix MD036 warnings by converting emphasis to proper headings - Fix MD040 warning by adding language specifier to code block --------- Co-authored-by: Dominikus Nold <[email protected]>
1 parent 4ba12e0 commit f39e59e

16 files changed

+2516
-25
lines changed

‎.github/ISSUE_TEMPLATE/change_proposal.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
---
2+
name: Change Proposal
3+
about: Create a change proposal issue (typically synced from OpenSpec change proposals via `/specfact.sync-backlog`)
4+
title: "[Change] <Brief Description>"
5+
labels: enhancement, change-proposal
6+
assignees: ''
7+
8+
---
9+
10+
<!--
11+
This template matches the format used by `/specfact.sync-backlog` when creating GitHub issues from OpenSpec change proposals.
12+
When synced automatically, only the "Why" and "What Changes" sections are populated from the proposal.md file.
13+
Additional sections (Acceptance Criteria, Dependencies, etc.) can be added manually for tracking.
14+
-->
15+
16+
## Why
17+
18+
<!-- Rationale and business value for this change -->
19+
<!-- This section is populated from the `rationale` field in OpenSpec proposal.md -->
20+
<!-- Explain why this change is needed and what problem it solves -->
21+
22+
<!-- Example: -->
23+
<!-- This change addresses the need for unified command chain documentation. Currently, users must navigate 3-5 separate documents to understand a single workflow, which creates friction and reduces adoption. -->
24+
25+
## What Changes
26+
27+
<!-- Description of what will change -->
28+
<!-- This section is populated from the `description` or `what_changes` field in OpenSpec proposal.md -->
29+
<!-- Include high-level implementation approach, affected areas, and key decisions -->
30+
31+
<!-- Example: -->
32+
<!-- This change will create a unified `docs/guides/command-chains.md` reference documenting all 9 command chains (6 mature + 3 emerging) with: -->
33+
<!-- - Overview section explaining what command chains are -->
34+
<!-- - One section per chain with goal, command sequence, decision points, expected outcomes -->
35+
<!-- - Visual flow diagrams (mermaid) for each chain -->
36+
<!-- - "When to use" decision tree -->
37+
<!-- - Cross-references to detailed guides -->
38+
39+
## Acceptance Criteria
40+
41+
<!-- Define what "done" looks like -->
42+
<!-- Use checkboxes for tracking -->
43+
44+
- [ ] Criterion 1
45+
- [ ] Criterion 2
46+
- [ ] Criterion 3
47+
48+
<!-- Example: -->
49+
<!-- - [ ] All 9 command chains documented in unified reference -->
50+
<!-- - [ ] Each chain includes: goal, command sequence, decision points, expected outcomes, links to detailed guides -->
51+
<!-- - [ ] Visual flow diagrams (mermaid) created for each chain -->
52+
<!-- - [ ] "When to use" decision tree added -->
53+
<!-- - [ ] Cross-references added from docs/README.md and docs/reference/commands.md -->
54+
55+
## Dependencies
56+
57+
<!-- List any dependencies on other changes, features, or external factors -->
58+
59+
<!-- Example: -->
60+
<!-- - Depends on: #123 (Command reorganization) -->
61+
<!-- - Blocks: #456 (Common tasks index) -->
62+
63+
## Related Issues/PRs
64+
65+
<!-- Link to related issues or pull requests -->
66+
67+
<!-- Example: -->
68+
<!-- - Related to: #789 -->
69+
<!-- - Supersedes: #012 -->
70+
71+
## Additional Context
72+
73+
<!-- Add any other context, examples, or implementation notes -->
74+
<!-- This section is not auto-populated from OpenSpec proposals - add manually as needed -->
75+
76+
<!--
77+
Note: When this issue is created via `/specfact.sync-backlog`, the following happens automatically:
78+
- "Why" section populated from proposal.md rationale
79+
- "What Changes" section populated from proposal.md description/what_changes
80+
- OpenSpec change ID added to footer
81+
- Issue number and URL stored in proposal.md source_tracking section
82+
- Labels set based on proposal status
83+
-->
84+
85+
---
86+
*OpenSpec Change Proposal: `change-id-here`*
87+
88+
<!--
89+
The footer above is automatically added by `/specfact.sync-backlog`.
90+
Replace `change-id-here` with the actual change ID (e.g., `add-command-chains-reference`).
91+
For manually created issues, you can omit this footer or add it manually.
92+
-->

‎docs/README.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ SpecFact isn't just a technical tool—it's designed for **real-world agile/scru
4545

4646
**Bottom line:** Use Spec-Kit for documenting new features. Use OpenSpec for change tracking. Use SpecFact for modernizing legacy code safely and enabling team collaboration. Use all three together for the best of all worlds.
4747

48-
👉 **[See detailed comparison](guides/speckit-comparison.md)** | **[Journey from Spec-Kit](guides/speckit-journey.md)** | **[OpenSpec Journey](guides/openspec-journey.md)** 🆕 | **[Bridge Adapters](reference/commands.md#sync-bridge)**
48+
👉 **[See detailed comparison](guides/speckit-comparison.md)** | **[Journey from Spec-Kit](guides/speckit-journey.md)** | **[OpenSpec Journey](guides/openspec-journey.md)** 🆕 | **[Integrations Overview](guides/integrations-overview.md)** 🆕 | **[Bridge Adapters](reference/commands.md#sync-bridge)**
4949

5050
---
5151

@@ -133,10 +133,12 @@ specfact enforce sdd --bundle my-project
133133

134134
**Goal**: Use SpecFact effectively in your workflow
135135

136-
1. **[Command Reference](reference/commands.md)** - All commands with examples
137-
2. **[Use Cases](guides/use-cases.md)** - Real-world scenarios
138-
3. **[IDE Integration](guides/ide-integration.md)** - Set up slash commands
139-
4. **[CoPilot Mode](guides/copilot-mode.md)** - Enhanced prompts
136+
1. **[Command Chains Reference](guides/command-chains.md)** ⭐ **NEW** - Complete workflows and command sequences
137+
2. **[Common Tasks Index](guides/common-tasks.md)** ⭐ **NEW** - Quick "How do I X?" reference
138+
3. **[Command Reference](reference/commands.md)** - All commands with examples
139+
4. **[Use Cases](guides/use-cases.md)** - Real-world scenarios
140+
5. **[IDE Integration](guides/ide-integration.md)** - Set up slash commands
141+
6. **[CoPilot Mode](guides/copilot-mode.md)** - Enhanced prompts
140142

141143
**Time**: 30-60 minutes | **Result**: Master daily workflows
142144

‎docs/guides/ai-ide-workflow.md‎

Lines changed: 271 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,271 @@
1+
---
2+
layout: default
3+
title: AI IDE Workflow Guide
4+
permalink: /ai-ide-workflow/
5+
---
6+
7+
# AI IDE Workflow Guide
8+
9+
> **Complete guide to using SpecFact CLI with AI IDEs (Cursor, VS Code + Copilot, Claude Code, etc.)**
10+
11+
---
12+
13+
## Overview
14+
15+
SpecFact CLI integrates with AI-assisted IDEs through slash commands that enable a seamless workflow: **SpecFact finds gaps → AI IDE fixes them → SpecFact validates**. This guide explains the complete workflow from setup to validation.
16+
17+
**Key Benefits**:
18+
19+
- ✅ **You control the AI** - Use your preferred AI model
20+
- ✅ **SpecFact validates** - Ensure AI-generated code meets contracts
21+
- ✅ **No lock-in** - Works with any AI IDE
22+
- ✅ **CLI-first** - Works offline, no account required
23+
24+
---
25+
26+
## Setup Process
27+
28+
### Step 1: Initialize IDE Integration
29+
30+
Run the `init --ide` command in your repository:
31+
32+
```bash
33+
# Auto-detect IDE
34+
specfact init
35+
36+
# Or specify IDE explicitly
37+
specfact init --ide cursor
38+
specfact init --ide vscode
39+
specfact init --ide copilot
40+
41+
# Install required packages for contract enhancement
42+
specfact init --ide cursor --install-deps
43+
```
44+
45+
**What it does**:
46+
47+
1. Detects your IDE (or uses `--ide` flag)
48+
2. Copies prompt templates from `resources/prompts/` to IDE-specific location
49+
3. Creates/updates IDE settings if needed
50+
4. Makes slash commands available in your IDE
51+
5. Optionally installs required packages (`beartype`, `icontract`, `crosshair-tool`, `pytest`)
52+
53+
**Related**: [IDE Integration Guide](ide-integration.md) - Complete setup instructions
54+
55+
---
56+
57+
## Available Slash Commands
58+
59+
Once initialized, the following slash commands are available in your IDE:
60+
61+
### Core Workflow Commands
62+
63+
| Slash Command | Purpose | Equivalent CLI Command |
64+
|---------------|---------|------------------------|
65+
| `/specfact.01-import` | Import from codebase | `specfact import from-code` |
66+
| `/specfact.02-plan` | Plan management | `specfact plan init/add-feature/add-story` |
67+
| `/specfact.03-review` | Review plan | `specfact plan review` |
68+
| `/specfact.04-sdd` | Create SDD manifest | `specfact enforce sdd` |
69+
| `/specfact.05-enforce` | SDD enforcement | `specfact enforce sdd` |
70+
| `/specfact.06-sync` | Sync operations | `specfact sync bridge` |
71+
| `/specfact.07-contracts` | Contract management | `specfact generate contracts-prompt` |
72+
73+
### Advanced Commands
74+
75+
| Slash Command | Purpose | Equivalent CLI Command |
76+
|---------------|---------|------------------------|
77+
| `/specfact.compare` | Compare plans | `specfact plan compare` |
78+
| `/specfact.validate` | Validation suite | `specfact repro` |
79+
80+
**Related**: [IDE Integration - Available Slash Commands](ide-integration.md#available-slash-commands)
81+
82+
---
83+
84+
## Complete Workflow: Prompt Generation → AI IDE → Validation Loop
85+
86+
### Workflow Overview
87+
88+
```mermaid
89+
graph TD
90+
A[SpecFact Analysis] -->|Find Gaps| B[Generate Prompt]
91+
B -->|Copy to IDE| C[AI IDE]
92+
C -->|Generate Fix| D[Apply Changes]
93+
D -->|SpecFact Validate| E[Validation]
94+
E -->|Pass| F[Complete]
95+
E -->|Fail| B
96+
```
97+
98+
### Step-by-Step Workflow
99+
100+
#### 1. Run SpecFact Analysis
101+
102+
```bash
103+
# Import from codebase
104+
specfact import from-code --bundle my-project --repo .
105+
106+
# Run validation to find gaps
107+
specfact repro --verbose
108+
```
109+
110+
#### 2. Generate AI-Ready Prompt
111+
112+
```bash
113+
# Generate fix prompt for a specific gap
114+
specfact generate fix-prompt GAP-001 --bundle my-project
115+
116+
# Or generate contract prompt
117+
specfact generate contracts-prompt --bundle my-project --feature FEATURE-001
118+
119+
# Or generate test prompt
120+
specfact generate test-prompt src/auth/login.py --bundle my-project
121+
```
122+
123+
#### 3. Use AI IDE to Apply Fixes
124+
125+
**In Cursor / VS Code / Copilot**:
126+
127+
1. Open the generated prompt file
128+
2. Copy the prompt content
129+
3. Paste into AI IDE chat
130+
4. AI generates the fix
131+
5. Review and apply the changes
132+
133+
**Example**:
134+
135+
```bash
136+
# After generating prompt
137+
cat .specfact/prompts/fix-prompt-GAP-001.md
138+
139+
# Copy content to AI IDE chat
140+
# AI generates fix
141+
# Apply changes to code
142+
```
143+
144+
#### 4. Validate with SpecFact
145+
146+
```bash
147+
# Check contract coverage
148+
specfact contract coverage --bundle my-project
149+
150+
# Run validation
151+
specfact repro --verbose
152+
153+
# Enforce SDD compliance
154+
specfact enforce sdd --bundle my-project
155+
```
156+
157+
#### 5. Iterate if Needed
158+
159+
If validation fails, return to step 2 and generate a new prompt for the remaining issues.
160+
161+
---
162+
163+
## Integration with Command Chains
164+
165+
The AI IDE workflow integrates with several command chains:
166+
167+
### AI-Assisted Code Enhancement Chain
168+
169+
**Workflow**: `generate contracts-prompt` → [AI IDE] → `contracts-apply` → `contract coverage` → `repro`
170+
171+
**Related**: [AI-Assisted Code Enhancement Chain](command-chains.md#7-ai-assisted-code-enhancement-chain-emerging)
172+
173+
### Test Generation from Specifications Chain
174+
175+
**Workflow**: `generate test-prompt` → [AI IDE] → `spec generate-tests` → `pytest`
176+
177+
**Related**: [Test Generation from Specifications Chain](command-chains.md#8-test-generation-from-specifications-chain-emerging)
178+
179+
### Gap Discovery & Fixing Chain
180+
181+
**Workflow**: `repro --verbose` → `generate fix-prompt` → [AI IDE] → `enforce sdd`
182+
183+
**Related**: [Gap Discovery & Fixing Chain](command-chains.md#9-gap-discovery--fixing-chain-emerging)
184+
185+
---
186+
187+
## Example: Complete AI IDE Workflow
188+
189+
### Scenario: Add Contracts to Existing Code
190+
191+
```bash
192+
# 1. Analyze codebase
193+
specfact import from-code --bundle legacy-api --repo .
194+
195+
# 2. Find gaps
196+
specfact repro --verbose
197+
198+
# 3. Generate contract prompt
199+
specfact generate contracts-prompt --bundle legacy-api --feature FEATURE-001
200+
201+
# 4. [In AI IDE] Use slash command or paste prompt
202+
# /specfact.generate-contracts-prompt legacy-api FEATURE-001
203+
# AI generates contracts
204+
# Apply contracts to code
205+
206+
# 5. Validate
207+
specfact contract coverage --bundle legacy-api
208+
specfact repro --verbose
209+
specfact enforce sdd --bundle legacy-api
210+
```
211+
212+
---
213+
214+
## Supported IDEs
215+
216+
SpecFact CLI supports the following AI IDEs:
217+
218+
- ✅ **Cursor** - `.cursor/commands/`
219+
- ✅ **VS Code / GitHub Copilot** - `.github/prompts/` + `.vscode/settings.json`
220+
- ✅ **Claude Code** - `.claude/commands/`
221+
- ✅ **Gemini CLI** - `.gemini/commands/`
222+
- ✅ **Qwen Code** - `.qwen/commands/`
223+
- ✅ **opencode** - `.opencode/command/`
224+
- ✅ **Windsurf** - `.windsurf/workflows/`
225+
- ✅ **Kilo Code** - `.kilocode/workflows/`
226+
- ✅ **Auggie** - `.augment/commands/`
227+
- ✅ **Roo Code** - `.roo/commands/`
228+
- ✅ **CodeBuddy** - `.codebuddy/commands/`
229+
- ✅ **Amp** - `.agents/commands/`
230+
- ✅ **Amazon Q Developer** - `.amazonq/prompts/`
231+
232+
**Related**: [IDE Integration - Supported IDEs](ide-integration.md#supported-ides)
233+
234+
---
235+
236+
## Troubleshooting
237+
238+
### Slash Commands Not Showing
239+
240+
**Issue**: Slash commands don't appear in IDE
241+
242+
**Solution**:
243+
244+
```bash
245+
# Re-initialize with force
246+
specfact init --ide cursor --force
247+
```
248+
249+
**Related**: [IDE Integration - Troubleshooting](ide-integration.md#troubleshooting)
250+
251+
---
252+
253+
### AI-Generated Code Fails Validation
254+
255+
**Issue**: AI-generated code doesn't pass SpecFact validation
256+
257+
**Solution**:
258+
259+
1. Review validation errors
260+
2. Generate a new prompt with more specific requirements
261+
3. Re-run AI generation
262+
4. Validate again
263+
264+
---
265+
266+
## See Also
267+
268+
- [IDE Integration Guide](ide-integration.md) - Complete setup and configuration
269+
- [Command Chains Reference](command-chains.md) - Complete workflows
270+
- [Common Tasks Index](common-tasks.md) - Quick reference
271+
- [Generate Commands Reference](../reference/commands.md#generate---generate-artifacts) - Command documentation

0 commit comments

Comments
 (0)