Skip to content

Commit 853a144

Browse files
author
Dominikus Nold
committed
feat: add watch mode and complete documentation reorganization (v0.5.0)
- Add watch mode for continuous synchronization (sync spec-kit and sync repository) - Implement real-time file system monitoring with configurable interval - Add comprehensive E2E test suite for watch mode (20+ tests) - Complete documentation reorganization (all 3 phases): - Phase 1: Core reorganization (streamlined README, persona-based docs/README) - Phase 2: Content creation (first-steps.md, workflows.md, troubleshooting.md, quick-examples.md) - Phase 3: Content enhancement (architecture.md, commands.md, polish all docs) - Add plan sync --shared and plan compare --code-vs-plan convenience aliases - Fix watch mode path validation and error handling - Update all version artifacts to 0.5.0 - Add comprehensive CHANGELOG entry for 0.5.0 Closes: Watch mode implementation (Phase 6 & 7) Closes: Documentation reorganization (all phases)
1 parent 3206c60 commit 853a144

35 files changed

+3343
-417
lines changed

‎CHANGELOG.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,110 @@ All notable changes to this project will be documented in this file.
99

1010
---
1111

12+
## [0.5.0] - 2025-11-09
13+
14+
### Added (0.5.0)
15+
16+
- **Watch Mode for Continuous Synchronization**
17+
- Added `--watch` flag to `sync spec-kit` and `sync repository` commands
18+
- Real-time file system monitoring with configurable interval (default: 5 seconds)
19+
- Automatic change detection for Spec-Kit artifacts, SpecFact plans, and repository code
20+
- Debouncing to prevent rapid file change events (500ms debounce interval)
21+
- Graceful shutdown with Ctrl+C support
22+
- Resource-efficient implementation with minimal CPU/memory usage
23+
- Comprehensive E2E test suite with 20+ tests covering all watch mode scenarios
24+
25+
- **Enhanced Sync Commands**
26+
- `sync spec-kit` now supports watch mode for continuous bidirectional sync
27+
- `sync repository` now supports watch mode for continuous code-to-plan sync
28+
- Automatic change type detection (Spec-Kit, SpecFact, or code changes)
29+
- Improved error handling with path validation and graceful degradation
30+
31+
- **Documentation Reorganization**
32+
- Complete reorganization of user-facing documentation for improved clarity
33+
- Created persona-based navigation hub in `docs/README.md`
34+
- New guides: `getting-started/first-steps.md`, `guides/workflows.md`, `guides/troubleshooting.md`
35+
- New examples: `examples/quick-examples.md`
36+
- Moved technical content to dedicated `technical/` directory
37+
- Enhanced `reference/architecture.md` and `reference/commands.md` with quick reference sections
38+
- Streamlined root `README.md` to focus on value proposition and quick start
39+
- All documentation verified for consistency, links, and markdown linting
40+
41+
- **Plan Management Enhancements**
42+
- Added `plan sync --shared` convenience wrapper for team collaboration
43+
- Added `plan compare --code-vs-plan` convenience alias for drift detection
44+
- Improved active plan selection and management
45+
- Enhanced plan comparison with better deviation reporting
46+
47+
### Changed (0.5.0)
48+
49+
- **Sync Command Improvements**
50+
- Enhanced `sync spec-kit` with better bidirectional sync handling
51+
- Improved `sync repository` with better code change tracking
52+
- Better error messages and validation for repository paths
53+
- Improved handling of temporary directory cleanup during watch mode
54+
55+
- **Documentation Structure**
56+
- Moved `guides/mode-detection.md` → `reference/modes.md` (technical reference)
57+
- Moved `guides/feature-key-normalization.md` → `reference/feature-keys.md` (technical reference)
58+
- Moved `reference/testing.md` → `technical/testing.md` (contributor concern)
59+
- Updated all cross-references and links throughout documentation
60+
- Improved organization with clear separation between user guides and technical reference
61+
62+
- **Command Reference Enhancements**
63+
- Added quick reference section to `reference/commands.md`
64+
- Grouped commands by workflow (Import & Analysis, Plan Management, Enforcement, etc.)
65+
- Added related documentation links to all reference pages
66+
- Improved examples and usage patterns
67+
68+
- **Architecture Documentation**
69+
- Added quick overview section to `reference/architecture.md` for non-technical users
70+
- Enhanced with related documentation links
71+
- Improved organization and readability
72+
73+
### Fixed (0.5.0)
74+
75+
- **Watch Mode Path Validation**
76+
- Fixed repository path validation in watch mode callbacks
77+
- Added proper path resolution and validation before watcher initialization
78+
- Improved handling of temporary directory cleanup during watch mode execution
79+
- Added graceful error handling for non-existent directories
80+
81+
- **Documentation Consistency**
82+
- Fixed outdated path references (`contracts/plans/` → `.specfact/plans/`)
83+
- Updated all default paths to match current directory structure
84+
- Verified all cross-references and links
85+
- Fixed markdown linting errors
86+
87+
- **Test Suite Improvements**
88+
- Added `@pytest.mark.slow` marker for slow tests
89+
- Added `@pytest.mark.timeout` for watch mode tests
90+
- Improved test reliability and error handling
91+
- Enhanced E2E test coverage for watch mode scenarios
92+
93+
### Documentation (0.5.0)
94+
95+
- **Complete Documentation Reorganization**
96+
- Phase 1: Core reorganization (streamlined README, persona-based docs/README, moved technical content)
97+
- Phase 2: Content creation (first-steps.md, workflows.md, troubleshooting.md, quick-examples.md)
98+
- Phase 3: Content enhancement (architecture.md, commands.md, polish all docs)
99+
- All phases completed with full verification and consistency checks
100+
101+
- **New Documentation Files**
102+
- `docs/getting-started/first-steps.md` - Step-by-step first commands
103+
- `docs/guides/workflows.md` - Common daily workflows
104+
- `docs/guides/troubleshooting.md` - Common issues and solutions
105+
- `docs/examples/quick-examples.md` - Quick code snippets
106+
- `docs/technical/README.md` - Technical deep dives overview
107+
108+
- **Enhanced Documentation**
109+
- Added "dogfooding" term explanation in examples
110+
- Improved cross-references and navigation
111+
- Better organization for different user personas
112+
- Clearer separation between user guides and technical reference
113+
114+
---
115+
12116
## [0.4.2] - 2025-11-06
13117

14118
### Fixed (0.4.2)

‎README.md‎

Lines changed: 3 additions & 124 deletions
Original file line numberDiff line numberDiff line change
@@ -66,134 +66,13 @@ We ran SpecFact CLI **on itself** to prove it works:
6666

6767
---
6868

69-
## What Can You Do?
70-
71-
### 1. 🔄 Import from GitHub Spec-Kit
72-
73-
Already using Spec-Kit? **Level up to automated enforcement** in one command:
74-
75-
```bash
76-
specfact import from-spec-kit --repo ./spec-kit-project --write
77-
```
78-
79-
**Result**: Your Spec-Kit artifacts become production-ready contracts with automated quality gates.
80-
81-
### 2. 🔍 Analyze Your Existing Code
82-
83-
Turn brownfield code into a clean spec:
84-
85-
```bash
86-
specfact import from-code --repo . --name my-project
87-
```
88-
89-
**Result**: Auto-generated plan showing what your code actually does
90-
91-
### 3. 📋 Plan New Features
92-
93-
Start with a spec, not with code:
94-
95-
```bash
96-
specfact plan init --interactive
97-
specfact plan add-feature --key FEATURE-001 --title "User Login"
98-
```
99-
100-
**Result**: Clear acceptance criteria before writing any code
101-
102-
### 4. 🛡️ Enforce Quality
103-
104-
Set rules that actually block bad code:
105-
106-
```bash
107-
specfact enforce stage --preset balanced
108-
```
109-
110-
**Modes:**
111-
112-
- `minimal` - Just observe, never block
113-
- `balanced` - Block critical bugs, warn on others
114-
- `strict` - Block everything suspicious
115-
116-
### 5. ✅ Validate Everything
117-
118-
One command to check it all:
119-
120-
```bash
121-
specfact repro
122-
```
123-
124-
**Checks:** Contracts, types, async patterns, state machines
125-
126-
---
127-
12869
## Documentation
12970

130-
For complete documentation, see **[docs/README.md](docs/README.md)**.
131-
132-
**Quick Links:**
133-
134-
- 📖 **[Getting Started](docs/getting-started/README.md)** - Installation and first steps
135-
- 🎯 **[The Journey: From Spec-Kit to SpecFact](docs/guides/speckit-journey.md)** - Level up from interactive authoring to automated enforcement
136-
- 📋 **[Command Reference](docs/reference/commands.md)** - All commands with examples
137-
- 🤖 **[IDE Integration](docs/guides/ide-integration.md)** - Set up slash commands in your IDE
138-
- 💡 **[Use Cases](docs/guides/use-cases.md)** - Real-world scenarios
139-
140-
---
141-
142-
## Installation Options
143-
144-
### 1. uvx (Easiest)
145-
146-
No installation needed:
147-
148-
```bash
149-
uvx --from specfact-cli specfact plan init
150-
```
151-
152-
### 2. pip
153-
154-
Install globally:
155-
156-
```bash
157-
pip install specfact-cli
158-
specfact --help
159-
```
160-
161-
### 3. Docker
162-
163-
Run in a container:
164-
165-
```bash
166-
docker run ghcr.io/nold-ai/specfact-cli:latest --help
167-
```
168-
169-
---
170-
171-
## Project Documentation
172-
173-
### 📚 Online Documentation
174-
175-
**GitHub Pages**: Full documentation is available at `https://nold-ai.github.io/specfact-cli/`
176-
177-
The documentation includes:
178-
179-
- Getting Started guides
180-
- Complete command reference
181-
- IDE integration setup
182-
- Use cases and examples
183-
- Architecture overview
184-
- Testing procedures
185-
186-
**Note**: The GitHub Pages workflow is configured and will automatically deploy when changes are pushed to the `main` branch. Enable GitHub Pages in your repository settings to activate the site.
187-
188-
### 📖 Local Documentation
71+
**New to SpecFact?** Start with the [Getting Started Guide](docs/getting-started/README.md)
18972

190-
All documentation is in the [`docs/`](docs/) directory:
73+
**Using Spec-Kit?** See [The Journey: From Spec-Kit to SpecFact](docs/guides/speckit-journey.md)
19174

192-
- **[Documentation Index](docs/README.md)** - Complete documentation overview
193-
- **[Getting Started](docs/getting-started/installation.md)** - Installation and setup
194-
- **[Command Reference](docs/reference/commands.md)** - All available commands
195-
- **[IDE Integration](docs/guides/ide-integration.md)** - Set up slash commands
196-
- **[Use Cases](docs/guides/use-cases.md)** - Real-world scenarios
75+
**Need help?** Browse the [Documentation Hub](docs/README.md)
19776

19877
---
19978

0 commit comments

Comments
 (0)