pmp-gywd 3.3.0

package/docs/GETTING-STARTED.md

@@ -0,0 +1,262 @@
+# Getting Started with GYWD
+
+> From zero to your first AI-assisted feature in 10 minutes.
+
+## Prerequisites
+
+- **Node.js 18+** installed
+- **Claude Code CLI** installed and authenticated
+- A project to work on (or an idea for one)
+
+## Installation
+
+### Quick Install
+
+```bash
+npx pmp-gywd
+```
+
+Choose:
+- **Global** — Available in all projects (recommended)
+- **Local** — This project only
+
+### Verify Installation
+
+Open Claude Code and run:
+
+```bash
+/gywd:help
+```
+
+You should see 40 commands listed. If commands don't appear, restart Claude Code.
+
+---
+
+## Choose Your Path
+
+| Your Situation | Start Here |
+|----------------|------------|
+| New idea, starting fresh | [Path A: New Project](#path-a-new-project) |
+| Existing codebase | [Path B: Existing Codebase](#path-b-existing-codebase) |
+
+---
+
+## Path A: New Project
+
+**Time:** ~5 minutes
+
+You have an idea and want to build it from scratch.
+
+### Step 1: Define Your Project
+
+```bash
+/gywd:new-project
+```
+
+GYWD will ask you about:
+- What problem you're solving
+- Who the users are
+- Core features needed
+- Technical preferences (language, framework)
+
+**Example answers:**
+```
+Problem: "I want to track my daily habits"
+Users: "Just me, for personal use"
+Features: "Add habits, mark complete, see streaks"
+Tech: "Node.js CLI app"
+```
+
+After answering, GYWD creates:
+- `.planning/PROJECT.md` — Your vision documented
+- `.planning/STATE.md` — Session memory
+- Developer profile (learns your patterns over time)
+
+### Step 2: Create Your Roadmap
+
+```bash
+/gywd:create-roadmap
+```
+
+GYWD breaks your idea into phases. For example:
+
+```
+Phase 1: Core data model
+Phase 2: CLI interface
+Phase 3: Streak tracking
+Phase 4: Notifications
+```
+
+Creates `.planning/ROADMAP.md` with the full plan.
+
+### Step 3: Plan Your First Phase
+
+```bash
+/gywd:plan-phase 1
+```
+
+Creates a detailed task plan in `.planning/phases/01-*/01-01-PLAN.md`.
+
+Review the plan — it shows exactly what will be built.
+
+### Step 4: Execute!
+
+```bash
+/gywd:execute-plan
+```
+
+GYWD builds your first phase with AI assistance:
+- Writes code based on your decisions
+- Tracks every choice made
+- Creates summary when done
+
+### Step 5: Continue Tomorrow
+
+```bash
+/gywd:progress
+```
+
+See where you left off and what's next. GYWD routes you to the right command.
+
+```bash
+/gywd:resume-work
+```
+
+Restore full context from your previous session.
+
+---
+
+## Path B: Existing Codebase
+
+**Time:** ~5 minutes
+
+You have code and want GYWD to understand it.
+
+### Step 1: Analyze Your Codebase
+
+```bash
+/gywd:bootstrap
+```
+
+GYWD scans your code and creates:
+
+| File | Contents |
+|------|----------|
+| `.planning/codebase/STACK.md` | Technologies used |
+| `.planning/codebase/ARCHITECTURE.md` | Design patterns |
+| `.planning/codebase/CONVENTIONS.md` | Coding standards |
+| `.planning/codebase/TESTING.md` | Test approach |
+| `.planning/core/decisions.json` | Decision graph from git |
+
+### Step 2: Understand Existing Code
+
+Trace any file to its original decisions:
+
+```bash
+/gywd:why src/auth/login.ts
+```
+
+Output:
+```
+DEC-015: JWT authentication [88% confidence]
+
+Rationale: Stateless auth for API scalability
+Alternatives rejected: Sessions (state management overhead)
+Source: Commit a3f2c1 "Add JWT auth layer"
+```
+
+See how a feature evolved:
+
+```bash
+/gywd:history "authentication"
+```
+
+### Step 3: Add a New Feature
+
+Define what you're adding (GYWD respects existing architecture):
+
+```bash
+/gywd:new-project
+```
+
+Then plan and execute:
+
+```bash
+/gywd:create-roadmap
+/gywd:plan-phase 1
+/gywd:execute-plan
+```
+
+GYWD ensures new code is consistent with existing patterns.
+
+### Step 4: Daily Workflow
+
+```bash
+/gywd:progress      # Start of day — see what's next
+/gywd:pause-work    # Before stopping — save context
+/gywd:resume-work   # Pick up where you left off
+```
+
+---
+
+## Quick Command Reference
+
+| When You Want To... | Run |
+|---------------------|-----|
+| Start a new project | `/gywd:new-project` |
+| Analyze existing code | `/gywd:bootstrap` |
+| See project status | `/gywd:progress` |
+| Plan next phase | `/gywd:plan-phase` |
+| Build the plan | `/gywd:execute-plan` |
+| Understand why code exists | `/gywd:why <file>` |
+| Get AI review | `/gywd:challenge` |
+| Save work in progress | `/gywd:pause-work` |
+| Resume previous session | `/gywd:resume-work` |
+
+---
+
+## What's Next?
+
+**Explore more commands:**
+```bash
+/gywd:help
+```
+
+**Get adversarial review of your plans:**
+```bash
+/gywd:challenge .planning/phases/01-*/01-01-PLAN.md
+```
+
+**Pre-load context before working:**
+```bash
+/gywd:anticipate --for "user authentication"
+```
+
+**View your learned preferences:**
+```bash
+/gywd:profile
+```
+
+**See complete workflow examples:**
+- [Workflow Examples](EXAMPLES.md) — End-to-end scenarios
+
+---
+
+## Troubleshooting
+
+**Commands not appearing?**
+- Restart Claude Code
+- Verify files in `~/.claude/commands/gywd/`
+
+**Nothing happening when commands run?**
+- Check `.planning/` directory exists
+- Run `/gywd:init` if missing
+
+**Lost context mid-session?**
+- Run `/gywd:resume-work`
+
+---
+
+*See also: [Commands](COMMANDS.md) | [Examples](EXAMPLES.md) | [README](../README.md)*
+
+*Need help? [Open an issue](https://github.com/cyberbloke9/pmp-gywd/issues)*

package/docs/README.md

@@ -0,0 +1,55 @@
+# GYWD Documentation
+
+> Complete documentation for the Get Your Work Done framework.
+
+## Quick Links
+
+| Document | Description |
+|----------|-------------|
+| [Getting Started](GETTING-STARTED.md) | Installation and first steps |
+| [Commands](COMMANDS.md) | All 40 commands with usage |
+| [Examples](EXAMPLES.md) | End-to-end workflow examples |
+| [Contributing](CONTRIBUTING.md) | Development and contribution guide |
+| [Releasing](RELEASING.md) | Maintainer release guide |
+
+## For New Users
+
+**Recommended reading order:**
+
+1. **[Getting Started](GETTING-STARTED.md)** — Install GYWD and run your first commands
+2. **[Examples](EXAMPLES.md)** — See complete workflows in action
+3. **[Commands](COMMANDS.md)** — Reference when you need specific command details
+
+## For Contributors
+
+1. **[Contributing](CONTRIBUTING.md)** — Development setup and guidelines
+2. **[Commands](COMMANDS.md)** — Understand the command structure
+3. **[Releasing](RELEASING.md)** — How to create releases (maintainers)
+
+## Quick Start
+
+```bash
+# Install
+npx pmp-gywd
+
+# Verify
+/gywd:help
+
+# Start a new project
+/gywd:new-project
+
+# Or analyze existing code
+/gywd:bootstrap
+```
+
+## Main README
+
+See the [main README](../README.md) for:
+- Feature overview
+- Architecture diagrams
+- Project structure
+- Troubleshooting
+
+---
+
+*GYWD v3.3 — 40 commands · 557 tests · Zero runtime deps*

package/docs/RELEASING.md

@@ -0,0 +1,159 @@
+# Releasing GYWD
+
+> Guide for maintainers on creating new releases.
+
+## Release Checklist
+
+Before creating a release:
+
+- [ ] All tests pass: `npm test`
+- [ ] Linting passes: `npm run lint`
+- [ ] Validations pass: `npm run validate:all`
+- [ ] CHANGELOG.md updated with new version
+- [ ] package.json version bumped
+- [ ] All changes committed and pushed
+
+## Quick Release
+
+```bash
+# 1. Ensure everything passes
+npm run release
+
+# 2. Create and push tag
+git tag v3.3.0
+git push origin v3.3.0
+```
+
+The GitHub Actions release workflow handles the rest automatically.
+
+## Detailed Process
+
+### 1. Prepare the Release
+
+```bash
+# Run all checks
+npm run release
+
+# This runs: lint + validate:all + test
+```
+
+### 2. Update Version
+
+Edit `package.json`:
+```json
+{
+  "version": "X.Y.Z"
+}
+```
+
+Update `CHANGELOG.md` with the new version section.
+
+### 3. Commit Changes
+
+```bash
+git add package.json CHANGELOG.md
+git commit -m "chore: bump version to vX.Y.Z"
+git push
+```
+
+### 4. Create Tag
+
+```bash
+# Create annotated tag
+git tag -a vX.Y.Z -m "Release vX.Y.Z"
+
+# Push tag to trigger release
+git push origin vX.Y.Z
+```
+
+### 5. Automated Pipeline
+
+When you push a tag starting with `v`, GitHub Actions:
+
+1. **Runs tests** — Ensures code passes before publish
+2. **Publishes to npm** — Uses `NPM_TOKEN` secret
+3. **Creates GitHub Release** — With auto-generated changelog
+
+## GitHub Actions Workflows
+
+### CI Pipeline (`.github/workflows/ci.yml`)
+
+Runs on every push and PR:
+- Multi-platform tests (Ubuntu, macOS, Windows)
+- Multi-Node version tests (16, 18, 20, 22)
+- ESLint
+- Schema/command validation
+- Security audit
+
+### Release Pipeline (`.github/workflows/release.yml`)
+
+Runs on tag push (`v*`):
+- Pre-release tests
+- npm publish
+- GitHub Release creation
+
+## Required Secrets
+
+| Secret | Purpose |
+|--------|---------|
+| `NPM_TOKEN` | npm authentication for publish |
+| `GITHUB_TOKEN` | Auto-provided for GitHub releases |
+| `CODECOV_TOKEN` | Optional: coverage reporting |
+
+## Versioning
+
+GYWD follows [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** (X.0.0): Breaking changes
+- **MINOR** (0.X.0): New features, backwards compatible
+- **PATCH** (0.0.X): Bug fixes, backwards compatible
+
+## Troubleshooting
+
+### npm publish fails
+
+1. Check `NPM_TOKEN` secret is set in repository settings
+2. Verify token has publish permissions
+3. Check package name isn't taken
+
+### Tests fail in CI but pass locally
+
+1. Check Node version matches CI matrix
+2. Look for platform-specific issues (Windows paths)
+3. Ensure no local-only dependencies
+
+### Tag already exists
+
+```bash
+# Delete local tag
+git tag -d vX.Y.Z
+
+# Delete remote tag
+git push origin :refs/tags/vX.Y.Z
+
+# Recreate tag
+git tag vX.Y.Z
+git push origin vX.Y.Z
+```
+
+### GitHub Release not created
+
+1. Check `contents: write` permission in workflow
+2. Verify `GITHUB_TOKEN` is available
+3. Check workflow logs for errors
+
+## Manual npm Publish
+
+If automation fails, publish manually:
+
+```bash
+# Login to npm
+npm login
+
+# Publish
+npm publish
+```
+
+---
+
+*See also: [Contributing](CONTRIBUTING.md) | [Commands](COMMANDS.md)*