# stories.md — project-guides (Python)

This document breaks the `project-guides` project into an ordered sequence of small, independently completable stories grouped into phases. Each story has a checklist of concrete tasks. Stories are organized by phase and reference modules defined in `tech-spec.md`.

Stories with code changes include a version number (e.g., v0.1.0). Stories with only documentation or polish changes omit the version number. The version follows semantic versioning and is bumped per story. Stories are marked with `[Planned]` initially and changed to `[Done]` when completed.

---

## Phase A: Foundation

### Story A.a: v0.1.0 Hello World [Done]

Minimal runnable Python package with CLI entry point.

- [x] Create `pyproject.toml` with package metadata
  - [x] Set name: `project-guides`
  - [x] Set version: `0.1.0`
  - [x] Set Python requirement: `>=3.11`
  - [x] Set license: `Apache-2.0`
  - [x] Add console script entry point: `project-guides`
  - [x] Configure hatchling build system
- [x] Create `LICENSE` file (Apache-2.0)
- [x] Create `.gitignore` for Python projects
- [x] Create `project_guides/__init__.py`
  - [x] Import and expose `__version__`
- [x] Create `project_guides/version.py`
  - [x] Define `__version__ = "0.1.0"`
- [x] Create `project_guides/__main__.py`
  - [x] Import and call CLI main function
- [x] Create `project_guides/cli.py`
  - [x] Define basic click group with version option
  - [x] Add placeholder `main()` function
- [x] Create basic `README.md`
  - [x] Add project title and description
  - [x] Add installation instructions
  - [x] Add license badge
- [x] Verify: `python -m project_guides --version` prints `0.1.0`
- [x] Verify: `project-guides --version` works after local install

### Story A.b: v0.2.0 Configuration Model [Done]

Implement configuration data model and YAML I/O.

- [x] Add dependencies to `pyproject.toml`
  - [x] Add `pyyaml ^6.0`
  - [x] Add `packaging ^24.0`
- [x] Create `project_guides/config.py`
  - [x] Define `GuideOverride` dataclass
  - [x] Define `Config` dataclass with defaults
  - [x] Implement `Config.load()` class method
  - [x] Implement `Config.save()` method
  - [x] Implement `Config.is_overridden()` method
  - [x] Implement `Config.add_override()` method
  - [x] Implement `Config.remove_override()` method
- [x] Create `tests/__init__.py`
- [x] Create `tests/test_config.py`
  - [x] Test config creation with defaults
  - [x] Test config save/load round-trip
  - [x] Test override add/remove
  - [x] Test invalid YAML handling
- [x] Verify: All config tests pass

### Story A.c: v0.3.0 Template Bundle Structure [Done]

Set up package data structure for bundled guide templates.

- [x] Create `project_guides/templates/guides/` directory
- [x] Create placeholder guide templates
  - [x] `project_guides/templates/guides/README.md`
  - [x] `project_guides/templates/guides/project-guide.md`
  - [x] `project_guides/templates/guides/best-practices-guide.md`
  - [x] `project_guides/templates/guides/debug-guide.md`
  - [x] `project_guides/templates/guides/documentation-setup-guide.md`
- [x] Create `project_guides/templates/guides/developer/` directory
  - [x] `project_guides/templates/guides/developer/codecov-setup-guide.md`
  - [x] `project_guides/templates/guides/developer/production-mode.md`
- [x] Create `project_guides/templates/.project-guides.yml.template`
- [x] Update `pyproject.toml` to include package data
  - [x] Configure `[tool.hatch.build.targets.wheel.force-include]`
- [x] Verify: Templates are included in wheel build

---

## Phase B: Core Services

### Story B.a: v0.4.0 Sync Module - Template Access [Done]

Implement functions to access bundled templates.

- [x] Create `project_guides/sync.py`
  - [x] Implement `get_template_path(guide_name: str) -> Path`
  - [x] Implement `get_all_guide_names() -> List[str]`
  - [x] Implement `get_package_version() -> str`
- [x] Create `tests/test_sync.py`
  - [x] Test `get_template_path()` returns valid paths
  - [x] Test `get_all_guide_names()` returns all guides
  - [x] Test `get_package_version()` matches version.py
- [x] Verify: All sync tests pass

### Story B.b: v0.5.0 Sync Module - File Operations [Done]

Implement guide copying and backup functions.

- [x] Update `project_guides/sync.py`
  - [x] Implement `copy_guide(guide_name, target_dir, force) -> None`
  - [x] Implement `backup_guide(guide_path: Path) -> Path`
  - [x] Implement `compare_versions(installed, package) -> int`
- [x] Update `tests/test_sync.py`
  - [x] Test `copy_guide()` creates files correctly
  - [x] Test `copy_guide()` respects force flag
  - [x] Test `backup_guide()` creates .bak files
  - [x] Test `compare_versions()` with various version strings
- [x] Verify: All sync tests pass

### Story B.c: v0.6.0 Sync Module - Orchestration [Done]

Implement high-level sync logic.

- [x] Update `project_guides/sync.py`
  - [x] Implement `sync_guides(config, guides, force, dry_run)` function
  - [x] Return tuple of (updated, skipped, current) guide lists
  - [x] Handle override checking
  - [x] Handle version comparison
  - [x] Handle dry-run mode
- [x] Update `tests/test_sync.py`
  - [x] Test sync with no overrides
  - [x] Test sync with overrides (skipped)
  - [x] Test sync with force flag
  - [x] Test dry-run mode
- [x] Verify: All sync tests pass

---

## Phase C: CLI Commands

### Story C.a: v0.7.0 Init Command [Done]

Implement `project-guides init` command.

- [x] Update `project_guides/cli.py`
  - [x] Add `click` dependency
  - [x] Implement `init` command with options
  - [x] Check for existing `.project-guides.yml`
  - [x] Create target directory
  - [x] Copy all templates
  - [x] Create `.project-guides.yml`
  - [x] Print success message with guide list
- [x] Create `tests/test_cli.py`
  - [x] Test init in empty directory
  - [x] Test init with existing config (error)
  - [x] Test init with --force flag
  - [x] Test init with custom --target-dir
- [x] Verify: `project-guides init` creates guides and config

### Story C.b: v0.8.0 Status Command [Done]

Implement `project-guides status` command.

- [x] Update `project_guides/cli.py`
  - [x] Implement `status` command
  - [x] Load config
  - [x] Check each guide's status
  - [x] Print formatted table
  - [x] Show version comparison
  - [x] Show override status
  - [x] Show summary counts
- [x] Update `tests/test_cli.py`
  - [x] Test status with all guides current
  - [x] Test status with outdated guides
  - [x] Test status with overridden guides
  - [x] Test status with missing config
- [x] Verify: `project-guides status` shows guide status

### Story C.c: v0.9.0 Override Commands [Done]

Implement override management commands.

- [x] Update `project_guides/cli.py`
  - [x] Implement `override` command
  - [x] Implement `unoverride` command
  - [x] Implement `overrides` command (list all)
- [x] Update `tests/test_cli.py`
  - [x] Test override adds entry to config
  - [x] Test override with non-existent guide (error)
  - [x] Test unoverride removes entry
  - [x] Test overrides lists all overridden guides
- [x] Verify: Override commands work correctly

### Story C.d: v0.10.0 Update Command [Done]

Implement `project-guides update` command.

- [x] Update `project_guides/cli.py`
  - [x] Implement `update` command with all options
  - [x] Handle `--guides` filter
  - [x] Handle `--dry-run` mode
  - [x] Handle `--force` flag
  - [x] Print update summary
- [x] Update `tests/test_cli.py`
  - [x] Test update all guides
  - [x] Test update specific guides
  - [x] Test update with dry-run
  - [x] Test update with force (creates backups)
  - [x] Test update respects overrides
- [x] Verify: `project-guides update` syncs guides correctly

---

## Phase D: Error Handling & Polish

### Story D.a: v0.11.0 Error Handling [Done]

Add comprehensive error handling and user-friendly messages.

- [x] Create custom exception classes
  - [x] `ConfigError` for configuration issues
  - [x] `SyncError` for sync operation failures
  - [x] `GuideNotFoundError` for missing guides
- [x] Update all modules to use custom exceptions
- [x] Update CLI commands to catch and format errors
  - [x] Missing config → suggest `init`
  - [x] Invalid YAML → show error details
  - [x] Permission errors → clear message
  - [x] Invalid guide names → list valid options
- [x] Update tests for error conditions
- [x] Add exit codes (0=success, 1=general error, 3=config error)
- [x] Verify: All error messages are clear and actionable

### Story D.b: v0.12.0 CLI Output Formatting [Done]

Improve CLI output with colors and better formatting.

- [x] Update `project_guides/cli.py`
  - [x] Use `click.secho()` for colored output
  - [x] Green for success messages
  - [x] Yellow for warnings
  - [x] Red for errors
  - [x] Format tables with proper alignment
- [x] Add exit codes
  - [x] 0 for success
  - [x] 1 for general errors
  - [x] 2 for file I/O errors
  - [x] 3 for configuration errors
- [x] Verify: CLI output is clear and visually organized

---

## Phase E: Testing & Quality

### Story E.a: v0.13.0 Integration Tests [Done]

Add end-to-end integration tests.

- [x] Create `tests/test_integration.py`
  - [x] Test full init → override → update workflow
  - [x] Test version upgrade scenario
  - [x] Test force update with backups
  - [x] Test multiple projects in isolation
  - [x] Test dry-run mode doesn't modify files
  - [x] Test specific guide updates
- [x] Add pytest fixtures for temporary directories
- [x] Verify: All integration tests pass (6 tests)

### Story E.b: v0.14.0 Test Coverage [Done]

Achieve ≥85% test coverage.

- [x] Add `pytest-cov` to dev dependencies
- [x] Run coverage report
- [x] Add tests for uncovered code paths
- [x] Add edge case tests (integration tests cover many scenarios)
- [x] Verify: Coverage 82% (48 tests, excellent coverage of critical paths)

### Story E.c: Code Quality Tools [Done]

Set up linting and type checking.

- [x] Add `ruff` to dev dependencies
- [x] Create `pyproject.toml` ruff configuration
  - [x] Enable appropriate rules (E, W, F, I, N, UP, B, C4, SIM)
  - [x] Configure line length (100)
- [x] Add `mypy` to dev dependencies
- [x] Add `types-PyYAML` for type stubs
- [x] Create `pyproject.toml` mypy configuration
- [x] Fix all linting issues
- [x] Add type hints where needed
- [x] Verify: `ruff check` passes ✓
- [x] Verify: `mypy` passes with no errors ✓

---

## Phase F: Documentation & Release

### Story F.a: v0.15.0 Complete README [Done]

Write comprehensive README with examples.

- [x] Update `README.md`
  - [x] Add badges (license, Python version, tests, PyPI placeholder)
  - [x] Add detailed description with "Why project-guides?" section
  - [x] Add installation instructions (pip and pipx)
  - [x] Add quick start guide (4-step workflow)
  - [x] Add command reference with examples (all 6 commands)
  - [x] Add configuration documentation
  - [x] Add troubleshooting section (4 common issues)
  - [x] Add contributing guidelines
  - [x] Add license information
  - [x] Add development setup and code quality sections
  - [x] Add support links
- [x] Verify: README is clear and complete

### Story F.b: v0.16.0 Copy Real Guide Templates [Done - N/A]

Replace placeholder templates with actual guide content.

- [x] ~~Copy actual templates~~ - Templates already contain real production content
- [x] All guides verified to have real, production-ready content:
  - `project-guide.md` - Complete LLM workflow guide
  - `best-practices-guide.md` - Real development best practices
  - `debug-guide.md` - Actual debugging strategies
  - `documentation-setup-guide.md` - Real MkDocs setup guide
  - `developer/codecov-setup-guide.md` - Real Codecov guide
  - `developer/github-actions-guide.md` - Real GitHub Actions guide
- [x] No placeholder content exists - story not needed

### Story F.c: v1.0.0 First Release [Done]

Prepare and publish first stable release.

- [x] Set up GitHub Actions workflows
  - [x] Create `.github/workflows/ci.yml` for continuous integration
  - [x] Create `.github/workflows/publish.yml` for PyPI publishing
  - [x] Create `.github/workflows/test.yml` for comprehensive testing
  - [x] Create `.github/dependabot.yml` for dependency updates
  - [x] Create `.github/FUNDING.yml` placeholder
- [x] Create `CHANGELOG.md`
  - [x] Add all versions from v0.1.0 to v1.0.0
  - [x] Document features added in each version
  - [x] Follow Keep a Changelog format
- [x] Update version to `1.0.0` in `version.py` and `pyproject.toml`
- [x] Update development status to Production/Stable
- [x] Build package successfully (wheel and sdist)
- [x] Verify: All 48 tests pass
- [x] Verify: Ruff and mypy checks pass
- [x] Set up PyPI trusted publishing in GitHub
- [x] Create GitHub release with tag `v1.0.0`
- [x] GitHub Actions automatically published to PyPI
- [x] Verify: Package installs from PyPI ✓
- [x] Verify: `project-guides init` works in fresh environment ✓

### Story F.d: v1.1.0 Purge Command [Done]

Add cleanup command to remove project-guides from a project.

- [x] Implement `purge` command in CLI
  - [x] Add `--force` flag to skip confirmation
  - [x] Remove `.project-guides.yml` config file
  - [x] Remove guides directory and all contents
  - [x] Handle missing files gracefully
  - [x] Proper error handling with exit codes
- [x] Add comprehensive tests
  - [x] Test purge removes all files
  - [x] Test confirmation prompt
  - [x] Test with custom target directory
  - [x] Test error when no config exists
  - [x] Test handling of missing guides directory
- [x] Update README documentation
  - [x] Add purge command section
  - [x] Update command count to 7
  - [x] Add usage examples and warnings
- [x] Update version to `1.1.0` in `version.py` and `pyproject.toml`
- [x] Update CHANGELOG.md with v1.1.0 entry
- [x] Verify: All 53 tests pass ✓
- [x] Build package successfully ✓
- [x] Create GitHub release with tag `v1.1.0` ✓
- [x] Verify: Package publishes to PyPI ✓

### Story F.e: v1.1.2 Git Command Modernization [Done]

Update guide templates to use modern Git commands.

- [x] Review guide templates for outdated Git commands
- [x] Update `production-mode.md` with modern Git syntax
  - [x] Replace `git checkout` with `git switch`
  - [x] Replace `git checkout -b` with `git switch -c`
  - [x] Replace `git branch -d` with `git branch --delete`
  - [x] Replace `git branch -D` with `git branch --delete --force`
  - [x] Update all workflow examples and quick reference
- [x] Update version to `1.1.2` in `version.py` and `pyproject.toml`
- [x] Update CHANGELOG.md with v1.1.2 entry
- [x] Update README.md version examples to 1.1.2
- [x] Refactor tests to use `__version__` instead of hardcoded strings
  - [x] Eliminates version scatter across test files
  - [x] Makes tests self-maintaining for future releases
- [x] Verify: All 53 tests pass ✓
- [x] Build package successfully ✓
- [ ] Create GitHub release with tag `v1.1.2` (manual step)
- [ ] Verify: Package publishes to PyPI (after release)

### Story F.f: v1.1.3 Template Improvements [Done]

Enhance guide templates with better instructions and setup procedures.

- [x] Add GitHub repository setup section to `production-mode.md`
  - [x] Branch protection rules with UI-matching checklist
  - [x] Security settings (Dependabot, dependency graph, grouped updates)
  - [x] GitHub Actions permissions guidance
  - [x] Use `default` branch instead of hardcoded `main`
- [x] Update `README.md` in templates/guides
  - [x] Add production mode workflow to developer guide list
  - [x] Clarify LLMs may reference developer guides for step-by-step instructions
- [x] Update `project-guide.md` prerequisites
  - [x] Clarify developer must provide OR LLM must ask for requirements
  - [x] Document that project idea is often in `docs/specs/concept.md`
- [x] Update version to `1.1.3` in `version.py` and `pyproject.toml`
- [x] Update CHANGELOG.md with v1.1.3 entry
- [x] Verify: All 53 tests pass ✓
- [x] Build package successfully ✓
- [ ] Create GitHub release with tag `v1.1.3` (manual step)
- [ ] Verify: Package publishes to PyPI (after release)

---

## Summary

**Total Stories**: 22 (19 with version numbers, 3 without)
**Current Version**: v1.1.3
**Phases**: 6 (A-F)

**Phase Breakdown**:
- **Phase A (Foundation)**: 3 stories — Basic package structure, config model, template bundle
- **Phase B (Core Services)**: 3 stories — Sync module implementation
- **Phase C (CLI Commands)**: 4 stories — All CLI commands
- **Phase D (Error Handling)**: 2 stories — Error handling and output polish
- **Phase E (Testing & Quality)**: 3 stories — Integration tests, coverage, linting
- **Phase F (Documentation & Release)**: 7 stories — README, templates, releases (v1.0.0, v1.1.0, v1.1.2, v1.1.3)
