@hivehub/rulebook 5.4.1 → 5.5.1

package/templates/core/RULEBOOK.md

@@ -1,1947 +1,1947 @@
-<!-- RULEBOOK:START -->
-# Rulebook Task Management
-
-**CRITICAL**: Use Rulebook's built-in task management system for spec-driven development of new features and breaking changes.
-
-## When to Use
-
-Create tasks for:
-- ✅ New features/capabilities
-- ✅ Breaking changes
-- ✅ Architecture changes
-- ✅ Performance/security work
-
-Skip for:
-- ❌ Bug fixes (restore intended behavior)
-- ❌ Typos, formatting, comments
-- ❌ Dependency updates (non-breaking)
-
-## Persistent Memory Integration
-
-**IMPORTANT**: Task management is tightly integrated with persistent memory system for cross-session context:
-
-### Task Completion and Memory
-When a task is marked as completed:
-1. **Auto-save to memory** (if enabled): Key learnings, patterns, gotchas from task specs are captured
-2. **Search past tasks**: Before creating similar tasks, search memory for past implementations:
-   ```bash
-   rulebook memory search "authentication" --type feature
-   ```
-3. **Update implementation faster**: Reference past solutions documented in memory
-
-### Memory during Task Development
-As you work on a task:
-- **Save discoveries**: Use `rulebook memory save` to capture patterns and gotchas
-- **Reference past context**: Search memory for related implementations
-- **Document decisions**: Save architectural choices for future developers
-
-## ⚠️ CRITICAL: Task Creation is MANDATORY Before Implementation
-
-**ABSOLUTE RULE**: You MUST create a task BEFORE implementing ANY feature.
-
-### Why This Matters
-
-**Without task registration:**
-- ❌ Tasks can be lost in context
-- ❌ No tracking of implementation progress
-- ❌ No record of what was done and why
-- ❌ Difficult to resume work after context loss
-- ❌ No validation of completion criteria
-
-**With task registration:**
-- ✅ All features are tracked and documented
-- ✅ Progress is visible and measurable
-- ✅ Implementation history is preserved
-- ✅ Easy to resume work from any point
-- ✅ Clear completion criteria
-
-### MANDATORY Workflow
-
-**NEVER start implementation without creating a task first:**
-
-```bash
-# ❌ WRONG: Starting implementation directly
-# ... writing code without task ...
-
-# ✅ CORRECT: Create task first
-rulebook task create <task-id>
-# Write proposal.md
-# Write tasks.md
-# Write spec deltas
-rulebook task validate <task-id>
-# NOW you can start implementation
-```
-
-### Task Creation Before Any Feature Request
-
-**When a feature is requested:**
-
-1. **STOP** - Do not start coding
-2. **Create task** - `rulebook task create <task-id>`
-3. **Plan** - Write proposal.md and tasks.md
-4. **Spec** - Write spec deltas
-5. **Validate** - `rulebook task validate <task-id>`
-6. **THEN** - Start implementation
-
-**Example:**
-```
-User: "Add user authentication feature"
-
-❌ WRONG: Start coding immediately
-✅ CORRECT:
-  1. rulebook task create add-user-authentication
-  2. Write proposal.md explaining why and what
-  3. Write tasks.md with implementation checklist
-  4. Write specs/core/spec.md with requirements
-  5. rulebook task validate add-user-authentication
-  6. NOW start implementing
-```
-
-## CRITICAL: Task Creation Workflow
-
-**MANDATORY STEPS** - Follow in this exact order:
-
-### Step 1: Check Context7 MCP (MANDATORY)
-
-**BEFORE creating ANY task, you MUST:**
-
-1. **Query Context7 for OpenSpec documentation** (Rulebook uses OpenSpec-compatible format):
-   ```
-   @Context7 /fission-ai/openspec task creation format spec structure
-   ```
-
-2. **Review official format requirements**:
-   - Spec delta file format
-   - Requirement structure
-   - Scenario formatting
-   - Delta headers (ADDED/MODIFIED/REMOVED/RENAMED)
-
-3. **Verify format requirements**:
-   - Scenario MUST use `#### Scenario:` (4 hashtags, NOT 3, NOT bullets)
-   - Requirements MUST use `### Requirement: [Name]`
-   - MUST include SHALL/MUST statement after requirement name
-   - MUST include at least one scenario per requirement
-   - Purpose section MUST have minimum 20 characters
-
-**Why This Matters:**
-Most AI assistants create tasks with incorrect formats (wrong scenario headers, missing SHALL statements, incomplete deltas). Context7 provides the official format documentation that prevents validation failures.
-
-### Step 2: Explore Current State
-
-```bash
-# List existing tasks
-rulebook task list
-
-# List active changes
-rulebook task list --active
-
-# View task details
-rulebook task show <task-id>
-```
-
-### Step 3: Choose Task ID
-
-- Use **verb-led** kebab-case: `add-auth`, `update-api`, `remove-feature`, `refactor-module`
-- Must be unique (check existing tasks)
-- Descriptive and focused (one capability per task)
-
-### Step 4: Create Task Structure
-
-```bash
-# Create new task
-rulebook task create <task-id>
-
-# This creates:
-# /.rulebook/tasks/<task-id>/
-#   ├── proposal.md       # Why and what changes
-#   ├── tasks.md          # Implementation checklist
-#   ├── design.md         # Technical decisions (optional)
-#   └── specs/
-#       └── <module>/
-#           └── spec.md   # Delta showing additions/modifications
-```
-
-### Step 5: Write Proposal
-
-**File**: `/.rulebook/tasks/<task-id>/proposal.md`
-
-```markdown
-# Proposal: Task Name
-
-## Why
-Minimum 20 characters explaining why this change is needed.
-Provide context, motivation, and business/technical rationale.
-
-## What Changes
-Detailed description of what will change:
-- Specific components affected
-- New features or capabilities
-- Breaking changes (if any)
-- Migration path (if applicable)
-
-## Impact
-- Affected specs: list spec names
-- Affected code: list files/modules
-- Breaking change: YES/NO
-- User benefit: describe benefits
-```
-
-### Step 6: Write Tasks Checklist
-
-**File**: `/.rulebook/tasks/<task-id>/tasks.md`
-
-```markdown
-## 1. Implementation Phase
-- [ ] 1.1 First task item
-- [ ] 1.2 Second task item
-
-## 2. Testing Phase
-- [ ] 2.1 Write unit tests
-- [ ] 2.2 Write integration tests
-
-## 3. Documentation Phase
-- [ ] 3.1 Update README
-- [ ] 3.2 Update CHANGELOG
-```
-
-**⚠️ CRITICAL: Sequential Execution Rule**
-
-When implementing tasks from `tasks.md`, you MUST execute items **in the exact order listed**:
-
-1. Find the FIRST unchecked item (`- [ ]`) — implement THAT one
-2. Mark it `[x]` when done
-3. Move to the NEXT unchecked item
-4. **NEVER** skip ahead, reorder, or cherry-pick tasks
-5. **NEVER** start a later phase before the current phase is 100% complete
-
-**The task list is an ORDER, not a MENU.** The human defined the sequence deliberately. Follow it.
-
-### Step 7: Write Spec Delta
-
-**File**: `/.rulebook/tasks/<task-id>/specs/<module>/spec.md`
-
-**CRITICAL FORMAT REQUIREMENTS:**
-
-```markdown
-# Specification Name
-
-## ADDED Requirements
-
-### Requirement: Feature Name
-The system SHALL/MUST do something specific and testable.
-Every requirement needs SHALL or MUST keyword.
-
-#### Scenario: Scenario Name
-Given some precondition
-When an action occurs
-Then an expected outcome happens
-
-## MODIFIED Requirements
-
-### Requirement: Existing Feature
-The system SHALL/MUST do something modified.
-
-#### Scenario: Modified scenario
-Given updated precondition
-When action occurs
-Then new expected outcome
-
-## REMOVED Requirements
-
-### Requirement: Deprecated Feature
-[Description of what is being removed]
-
-## RENAMED Requirements
-- FROM: `### Requirement: Old Name`
-- TO: `### Requirement: New Name`
-```
-
-**Format Rules:**
-- ✅ Purpose section: Minimum 20 characters
-- ✅ Requirements: Must contain SHALL or MUST
-- ✅ Scenarios: Use `#### Scenario:` (4 hashtags)
-- ✅ Scenarios: Use Given/When/Then structure
-- ✅ Deltas: Use ADDED/MODIFIED/REMOVED/RENAMED headers
-- ❌ NEVER use 3 hashtags for scenarios
-- ❌ NEVER use bullet points for scenarios
-- ❌ NEVER omit SHALL/MUST from requirements
-
-### Step 8: Validate Task
-
-```bash
-# Validate task format
-rulebook task validate <task-id>
-
-# Validate with strict mode (recommended)
-rulebook task validate <task-id> --strict
-
-# Validate all tasks
-rulebook task validate --all
-```
-
-**Validation checks:**
-- Purpose section length (≥20 chars)
-- Requirement keywords (SHALL/MUST)
-- Scenario format (4 hashtags)
-- Given/When/Then structure
-- Delta headers format
-
-### Step 9: Update Task Status
-
-```bash
-# Mark task as in progress
-rulebook task update <task-id> --status in-progress
-
-# Update task progress
-rulebook task update <task-id> --progress 50
-
-# Mark task as completed
-rulebook task update <task-id> --status completed
-```
-
-### Step 10: Archive Completed Task
-
-```bash
-# Archive completed task
-rulebook task archive <task-id>
-
-# Archive without prompts
-rulebook task archive <task-id> --yes
-```
-
-**Archive process:**
-1. Validates task format
-2. Checks task completion status
-3. Applies spec deltas to main specifications
-4. Moves task to `/.rulebook/tasks/archive/YYYY-MM-DD-<task-id>/`
-5. Updates related specifications
-
-## 🚨 MANDATORY: Deferred Items → Tasks Rule
-
-**ABSOLUTE RULE — NO EXCEPTIONS**: Whenever a task is archived with items marked as "Deferred" or "Phase X+", you MUST immediately create Rulebook tasks for those deferred items **before archiving**.
-
-### The Deferred Items Protocol
-
-```
-❌ WRONG — defer without creating task:
-1. Archive task with "- [ ] D1. feature X — deferred Phase 4"
-   → Feature X is now forgotten forever
-
-✅ CORRECT — defer with tracking:
-1. Add "- [ ] D1. feature X — deferred Phase 4" to tasks.md
-2. Call rulebook_task_create("phase4-feature-x")
-3. Write tasks.md for the new task with full context
-4. THEN call rulebook_task_archive
-```
-
-### tasks.md Format for Archived Tasks
-
-```markdown
-## 1. Implemented Feature
-
-- [x] 1.1 Thing that was done
-- [x] 1.2 Another thing done
-
-## Deferred to Phase N (reason: dependency not ready)
-
-- [ ] D1. Feature X — deferred (reason)   ← task phase4-feature-x MUST exist
-- [ ] D2. Feature Y — deferred (reason)   ← task phaseN-feature-y MUST exist
-```
-
-### Archive Checklist (ALL must be done before `rulebook_task_archive`)
-
-```
-□ 1. tasks.md uses - [x] for implemented, - [ ] for deferred
-□ 2. Each deferred item has a "Phase N" target
-□ 3. A rulebook task exists for EVERY deferred item or group
-□ 4. The new deferred tasks have tasks.md with full context
-□ 5. THEN call rulebook_task_archive
-```
-
-## Task Format Examples
-
-### Correct Format ✅
-
-```markdown
-# Auth Specification
-
-## ADDED Requirements
-
-### Requirement: Two-Factor Authentication
-The system MUST require a second factor during login for enhanced security.
-
-#### Scenario: OTP required
-Given a user submits valid credentials
-When authentication starts
-Then an OTP challenge is required
-
-#### Scenario: OTP verification
-Given a user receives an OTP code
-When they submit the correct OTP
-Then they are authenticated successfully
-```
-
-### Incorrect Format ❌
-
-```markdown
-# Auth Specification
-
-## Requirements
-
-### Requirement: Two-Factor Authentication
-The system requires a second factor.  # ❌ Missing SHALL/MUST
-
-#### Scenario: OTP required  # ❌ Only 3 hashtags
-- WHEN user submits credentials  # ❌ Using bullets instead of Given/When/Then
-- THEN OTP challenge is required
-```
-
-## Common Pitfalls & How to Avoid Them
-
-### Top 5 Mistakes AI Assistants Make
-
-1. **Wrong Scenario Headers**
-   - ❌ `### Scenario:` (3 hashtags)
-   - ✅ `#### Scenario:` (4 hashtags)
-
-2. **Missing SHALL/MUST Keywords**
-   - ❌ "The system provides authentication"
-   - ✅ "The system SHALL provide authentication"
-
-3. **Using Bullets for Scenarios**
-   - ❌ `- WHEN user does X THEN Y happens`
-   - ✅ `Given X\nWhen Y\nThen Z`
-
-4. **Incomplete Purpose Section**
-   - ❌ "Auth system" (too short)
-   - ✅ "Authentication system for secure user access with JWT tokens and session management" (≥20 chars)
-
-5. **Wrong Delta Headers**
-   - ❌ `## New Requirements` or `## Changes`
-   - ✅ `## ADDED Requirements`, `## MODIFIED Requirements`, etc.
-
-## Integration with AGENT_AUTOMATION
-
-**CRITICAL**: After implementing a task, follow AGENT_AUTOMATION workflow:
-
-1. Run quality checks (lint, test, type-check, build)
-2. Update task status in `tasks.md`
-3. Update documentation (ROADMAP, CHANGELOG, specs)
-4. Commit with conventional commit format
-5. Archive task when complete
-
-## ⚠️ CRITICAL: Git Hooks Will Block Commits with Problems
-
-**ABSOLUTE RULE**: Pre-commit and pre-push hooks will **BLOCK** any commit attempt if there are:
-- ❌ Lint errors or warnings
-- ❌ Test failures
-- ❌ Type check errors
-- ❌ Formatting issues
-- ❌ Coverage below thresholds
-
-### Why This Matters
-
-**DO NOT attempt to commit code with problems:**
-- ❌ `git commit` will **FAIL** if lint has errors
-- ❌ `git commit` will **FAIL** if tests are failing
-- ❌ `git push` will **FAIL** if pre-push checks fail
-- ❌ You will waste time trying to commit broken code
-- ❌ The hooks will reject your commit automatically
-
-**ALWAYS fix problems BEFORE attempting to commit:**
-- ✅ Run `npm run lint` and fix ALL errors/warnings first
-- ✅ Run `npm test` and ensure ALL tests pass
-- ✅ Run `npm run type-check` and fix ALL type errors
-- ✅ Run `npm run format` if formatting is required
-- ✅ Run `npm test -- --coverage` and ensure coverage thresholds are met
-- ✅ **ONLY THEN** attempt `git commit`
-
-### Mandatory Pre-Commit Workflow
-
-**BEFORE every commit, you MUST:**
-
-```bash
-# 1. Fix lint errors FIRST (highest priority)
-npm run lint
-# Fix ALL errors and warnings
-# If lint fails, commit will be blocked
-
-# 2. Fix test failures SECOND
-npm test
-# Fix ALL failing tests
-# If tests fail, commit will be blocked
-
-# 3. Fix type errors THIRD
-npm run type-check
-# Fix ALL type errors
-# If type check fails, commit will be blocked
-
-# 4. Fix formatting (if required)
-npm run format
-# Apply formatting fixes
-
-# 5. Verify coverage (if required by hooks)
-npm test -- --coverage
-# Ensure coverage thresholds are met
-
-# 6. ONLY AFTER all checks pass, attempt commit
-git add .
-git commit -m "feat: your commit message"
-# This will now succeed because all checks passed
-```
-
-### What Happens If You Try to Commit with Problems
-
-**Example of blocked commit:**
-
-```bash
-$ git commit -m "feat: add new feature"
-
-🔍 Running TypeScript/JavaScript pre-commit checks...
-  → Type checking...
-  → Linting...
-
-/mnt/f/project/src/feature.ts
-   42:19  error  Unexpected any. Specify a different type  @typescript-eslint/no-explicit-any
-
-✖ 1 problem (1 error, 0 warnings)
-
-❌ Commit blocked: Lint errors found
-```
-
-**You MUST fix the error before committing:**
-
-```bash
-# Fix the lint error
-# ... edit code to fix the issue ...
-
-# Run lint again to verify
-npm run lint
-# ✅ All checks pass
-
-# NOW commit will succeed
-git commit -m "feat: add new feature"
-# ✅ Commit successful
-```
-
-### ⚠️ CRITICAL: NEVER Use --no-verify to Bypass Hooks
-
-**ABSOLUTE PROHIBITION**: You MUST NEVER use `--no-verify` or `--no-gpg-sign` flags to bypass git hooks.
-
-**FORBIDDEN COMMANDS:**
-- ❌ `git commit --no-verify` - **NEVER USE THIS**
-- ❌ `git commit -n` - **NEVER USE THIS** (short form of --no-verify)
-- ❌ `git push --no-verify` - **NEVER USE THIS**
-- ❌ Any flag that skips pre-commit or pre-push hooks
-
-### Why This Is Prohibited
-
-**Using `--no-verify` defeats the entire purpose of quality gates:**
-- ❌ Allows broken code to be committed
-- ❌ Bypasses all quality checks (lint, test, type-check)
-- ❌ Introduces technical debt and bugs
-- ❌ Violates project quality standards
-- ❌ Can break the build for other developers
-- ❌ Makes code review harder (reviewers see broken code)
-
-**The hooks exist for a reason:**
-- ✅ They protect code quality
-- ✅ They prevent bugs from entering the codebase
-- ✅ They ensure consistency across the project
-- ✅ They catch errors before they reach production
-
-### What to Do Instead
-
-**If you're tempted to use `--no-verify`, it means:**
-1. **You have problems that need fixing** - Fix them first
-2. **You're trying to commit too early** - Complete the work properly
-3. **You're rushing** - Slow down and do it right
-
-**Correct approach:**
-
-```bash
-# ❌ WRONG: Trying to bypass hooks
-git commit --no-verify -m "feat: add feature"
-# This is FORBIDDEN - never do this
-
-# ✅ CORRECT: Fix problems first, then commit
-npm run lint
-# Fix all errors...
-
-npm test
-# Fix all failing tests...
-
-npm run type-check
-# Fix all type errors...
-
-# NOW commit (hooks will pass)
-git commit -m "feat: add feature"
-# ✅ Commit successful - all checks passed
-```
-
-### Summary
-
-**CRITICAL RULES:**
-- ⚠️ **NEVER** attempt to commit code with lint errors - hooks will block it
-- ⚠️ **NEVER** attempt to commit code with test failures - hooks will block it
-- ⚠️ **NEVER** attempt to commit code with type errors - hooks will block it
-- ⚠️ **NEVER** use `--no-verify` or any flag to bypass hooks - **ABSOLUTELY FORBIDDEN**
-- ⚠️ **ALWAYS** fix ALL problems BEFORE attempting to commit
-- ⚠️ **ALWAYS** run quality checks manually before `git commit`
-- ⚠️ **ALWAYS** ensure all checks pass before committing
-
-**The hooks are there to protect code quality - they will NOT let broken code through. Always resolve problems first, then commit. Bypassing hooks is strictly prohibited and defeats the purpose of quality gates.**
-
-## MANDATORY: Task List Updates During Implementation
-
-**CRITICAL RULE**: You MUST update the task list (`tasks.md`) immediately after completing and testing each implementation step.
-
-### When to Update Task List
-
-**ALWAYS update `tasks.md` when:**
-- ✅ You complete a task item (mark as `[x]`)
-- ✅ You finish implementing a feature and it's tested
-- ✅ You complete a test suite
-- ✅ You finish documentation updates
-- ✅ You verify the implementation works correctly
-
-**NEVER commit without updating `tasks.md` if you've made progress on a task.**
-
-### How to Update Task List
-
-1. **After Implementation**:
-   ```markdown
-   ## 1. Implementation Phase
-   - [x] 1.1 Create task manager module  # ✅ Mark as done
-   - [x] 1.2 Add validation logic        # ✅ Mark as done
-   - [ ] 1.3 Add archive functionality   # Still pending
-   ```
-
-2. **After Testing**:
-   ```markdown
-   ## 2. Testing Phase
-   - [x] 2.1 Write unit tests            # ✅ Tests written and passing
-   - [x] 2.2 Write integration tests     # ✅ Tests written and passing
-   - [ ] 2.3 Add E2E tests                # Still pending
-   ```
-
-3. **After Documentation**:
-   ```markdown
-   ## 3. Documentation Phase
-   - [x] 3.1 Update README                # ✅ Updated
-   - [x] 3.2 Update CHANGELOG             # ✅ Updated
-   - [ ] 3.3 Update API docs              # Still pending
-   ```
-
-### Workflow: Implement → Test → Verify Coverage → Update Tasks → Commit → Next Task
-
-**MANDATORY SEQUENCE** for every implementation:
-
-```bash
-# 1. Implement the feature
-# ... write code ...
-
-# 2. Test the implementation
-npm test
-npm run lint
-npm run type-check
-
-# 3. Verify test coverage (CRITICAL)
-npm test -- --coverage
-# Check coverage thresholds are met
-# Fix any coverage gaps before proceeding
-
-# 4. Update tasks.md IMMEDIATELY after successful tests and coverage check
-# Mark completed items as [x] in tasks.md
-# Update task status if needed
-
-# 5. Verify task status is updated before moving to next task
-rulebook task show <task-id>
-# Confirm status reflects current progress
-
-# 6. Commit locally (BACKUP - do this frequently)
-git add .
-git commit -m "feat: implement task manager validation
-
-- Complete task 1.2: Add validation logic
-- All tests passing
-- Coverage verified: 95%
-- Updated tasks.md"
-
-# 7. Keep remote repository updated (if configured)
-# Check if remote is configured
-git remote -v
-
-# If remote exists, push regularly
-git push origin <branch-name>
-
-# If no remote configured, see setup instructions below
-
-# 8. Only then proceed to next task
-# Follow priority order (most critical first)
-```
-
-## ⚠️ CRITICAL: Frequent Local Commits for Backup
-
-**ABSOLUTE RULE**: Commit locally frequently, even if just for backup purposes.
-
-### Why Frequent Commits Matter
-
-**Without frequent commits:**
-- ❌ Risk of losing work if system crashes
-- ❌ No recovery point if something goes wrong
-- ❌ Difficult to revert to previous working state
-- ❌ Lost context if session is interrupted
-
-**With frequent commits:**
-- ✅ Work is backed up locally
-- ✅ Easy to recover from mistakes
-- ✅ Can revert to any previous state
-- ✅ Progress is preserved
-
-### When to Commit Locally
-
-**Commit locally whenever you:**
-- ✅ Complete a task item (even if not fully tested)
-- ✅ Finish implementing a feature (before full testing)
-- ✅ Fix a bug or issue
-- ✅ Update documentation
-- ✅ Make significant progress
-- ✅ Feel the need for a backup point
-- ✅ Are about to try something risky
-- ✅ Are switching to a different task
-
-**Commit frequency:**
-- **Minimum**: After completing each task item
-- **Recommended**: Every 15-30 minutes of active work
-- **Maximum**: As often as you feel necessary for safety
-
-### Local Commit Workflow
-
-```bash
-# Quick local commit (backup)
-git add .
-git commit -m "wip: progress on task 1.2
-
-- Implemented validation logic
-- Still testing
-- Backup commit"
-
-# Or more descriptive
-git add .
-git commit -m "feat: add validation logic (WIP)
-
-- Task 1.2 in progress
-- Core validation implemented
-- Tests pending
-- Backup before continuing"
-```
-
-### Commit Message Format for Backup Commits
-
-**For work-in-progress commits:**
-```bash
-git commit -m "wip: <brief description>
-
-- What was done
-- Current status
-- Next steps"
-```
-
-**For completed task items:**
-```bash
-git commit -m "feat: <feature description>
-
-- Complete task X.Y: <task name>
-- All tests passing
-- Coverage verified
-- Updated tasks.md"
-```
-
-## ⚠️ CRITICAL: Keep Remote Repository Updated
-
-**MANDATORY**: Keep your remote repository synchronized with local work.
-
-### Check Remote Configuration
-
-**First, check if remote is configured:**
-```bash
-git remote -v
-```
-
-**If you see output like:**
-```
-origin  https://github.com/user/repo.git (fetch)
-origin  https://github.com/user/repo.git (push)
-```
-✅ Remote is configured - proceed to push regularly
-
-**If you see no output or error:**
-❌ No remote configured - see setup instructions below
-
-### Push to Remote Regularly
-
-**After local commits, push to remote:**
-```bash
-# Push current branch
-git push origin <branch-name>
-
-# Or push current branch (if tracking is set)
-git push
-
-# Push with tags
-git push --tags
-```
-
-**Recommended push frequency:**
-- **Minimum**: After completing a task
-- **Recommended**: After every 2-3 local commits
-- **Maximum**: After every local commit (if working solo)
-
-### Remote Repository Setup
-
-**If no remote repository is configured:**
-
-#### Option 1: GitHub (Recommended)
-
-1. **Create repository on GitHub:**
-   - Go to https://github.com/new
-   - Create a new repository
-   - **DO NOT** initialize with README, .gitignore, or license (if you already have local repo)
-
-2. **Add remote and push:**
-   ```bash
-   # Add remote (replace with your repository URL)
-   git remote add origin https://github.com/username/repo-name.git
-   
-   # Or using SSH
-   git remote add origin git@github.com:username/repo-name.git
-   
-   # Push to remote
-   git push -u origin main
-   # Or 'master' if that's your default branch
-   ```
-
-3. **Verify:**
-   ```bash
-   git remote -v
-   git push
-   ```
-
-**GitHub Setup Guide:**
-- **Official Guide**: https://docs.github.com/en/get-started/quickstart/create-a-repo
-- **Adding Remote**: https://docs.github.com/en/get-started/getting-started-with-git/managing-remote-repositories
-
-#### Option 2: GitLab
-
-1. **Create repository on GitLab:**
-   - Go to https://gitlab.com/projects/new
-   - Create a new project
-   - **DO NOT** initialize with README (if you already have local repo)
-
-2. **Add remote and push:**
-   ```bash
-   git remote add origin https://gitlab.com/username/repo-name.git
-   git push -u origin main
-   ```
-
-**GitLab Setup Guide:**
-- **Official Guide**: https://docs.gitlab.com/ee/gitlab-basics/create-project.html
-
-#### Option 3: Bitbucket
-
-1. **Create repository on Bitbucket:**
-   - Go to https://bitbucket.org/repo/create
-   - Create a new repository
-
-2. **Add remote and push:**
-   ```bash
-   git remote add origin https://bitbucket.org/username/repo-name.git
-   git push -u origin main
-   ```
-
-**Bitbucket Setup Guide:**
-- **Official Guide**: https://support.atlassian.com/bitbucket-cloud/docs/create-a-git-repository/
-
-#### Option 4: Self-Hosted Git Server
-
-**If using self-hosted Git server:**
-```bash
-# Add remote
-git remote add origin <your-git-server-url>
-
-# Push
-git push -u origin main
-```
-
-### Verify Remote is Working
-
-**After setting up remote:**
-```bash
-# Check remote configuration
-git remote -v
-
-# Test push
-git push origin main
-
-# If successful, you'll see:
-# "Enumerating objects: X, done."
-# "Writing objects: 100% (X/X), done."
-```
-
-### Troubleshooting Remote Issues
-
-**Error: "remote origin already exists"**
-```bash
-# Remove existing remote
-git remote remove origin
-
-# Add new remote
-git remote add origin <new-url>
-```
-
-**Error: "authentication failed"**
-- Check your credentials
-- Use SSH keys for better security
-- See: https://docs.github.com/en/authentication/connecting-to-github-with-ssh
-
-**Error: "repository not found"**
-- Verify repository URL is correct
-- Check you have access to the repository
-- Ensure repository exists on remote server
-
-### Best Practices for Remote Sync
-
-**DO's ✅:**
-- ✅ Push to remote after completing tasks
-- ✅ Push before switching branches
-- ✅ Push before trying risky changes
-- ✅ Push at end of work session
-- ✅ Use descriptive commit messages
-- ✅ Keep commits atomic (one logical change per commit)
-
-**DON'Ts ❌:**
-- ❌ Don't push broken code (test first)
-- ❌ Don't push sensitive information (API keys, passwords)
-- ❌ Don't force push to shared branches
-- ❌ Don't skip pushing for extended periods
-- ❌ Don't commit without meaningful messages
-
-### Automated Backup Reminder
-
-**Set up reminders to push regularly:**
-```bash
-# Add to your shell profile (.bashrc, .zshrc, etc.)
-alias git-backup='git add . && git commit -m "backup: $(date +%Y-%m-%d\ %H:%M:%S)" && git push'
-
-# Use: git-backup (quick backup and push)
-```
-
-### Summary: Backup and Remote Sync Workflow
-
-**Complete workflow:**
-1. **Work locally** - Make changes
-2. **Test changes** - Ensure they work
-3. **Commit locally** - `git commit` (backup)
-4. **Update tasks.md** - Mark progress
-5. **Push to remote** - `git push` (if remote configured)
-6. **Continue work** - Next task
-
-**If no remote:**
-1. **Set up remote** - Follow instructions above
-2. **Push initial code** - `git push -u origin main`
-3. **Continue regular pushes** - After each commit or task
-
-### Priority Order: Most Critical First
-
-**ALWAYS follow this priority order when continuing implementation:**
-
-1. **Tests** (HIGHEST PRIORITY)
-   - Write tests for the feature
-   - Ensure all tests pass
-   - Verify test coverage meets thresholds
-
-2. **Coverage Verification** (CRITICAL)
-   - Run coverage check: `npm test -- --coverage`
-   - Fix any coverage gaps
-   - Ensure coverage thresholds are met
-
-3. **Update Task Status** (MANDATORY)
-   - Mark completed items as `[x]` in `tasks.md`
-   - Update task status if needed
-   - Document what was completed
-
-4. **Next Task** (Only after above steps)
-   - Move to next most critical task
-   - Follow same sequence
-
-**Example Priority Order:**
-
-```markdown
-## Priority Order (Most Critical First)
-
-### 1. Testing (CRITICAL - Do First)
-- [ ] 1.1 Write unit tests for core functionality
-- [ ] 1.2 Write integration tests
-- [ ] 1.3 Verify test coverage ≥ 95%
-
-### 2. Coverage Verification (CRITICAL - Do Second)
-- [ ] 2.1 Run coverage check
-- [ ] 2.2 Fix coverage gaps
-- [ ] 2.3 Verify thresholds met
-
-### 3. Task Status Update (MANDATORY - Do Third)
-- [ ] 3.1 Update tasks.md with completed items
-- [ ] 3.2 Update task status
-- [ ] 3.3 Document completion
-
-### 4. Next Implementation (Only After Above)
-- [ ] 4.1 Move to next critical task
-- [ ] 4.2 Follow same sequence
-```
-
-### Never Skip Steps
-
-**CRITICAL RULES:**
-- ❌ NEVER proceed to next task without updating current task status
-- ❌ NEVER skip test coverage verification
-- ❌ NEVER mark tasks complete without tests passing
-- ❌ NEVER implement without creating task first
-- ✅ ALWAYS update task status before moving to next task
-- ✅ ALWAYS verify coverage before marking task complete
-- ✅ ALWAYS follow priority order (most critical first)
-
-### Task Status Tracking
-
-**Track progress in `tasks.md`:**
-
-```markdown
-## Progress Summary
-- Total tasks: 15
-- Completed: 8
-- In progress: 2
-- Pending: 5
-- Blocked: 0
-
-## Current Status
-- ✅ Implementation Phase: 80% complete (4/5 tasks)
-- ⏳ Testing Phase: 50% complete (2/4 tasks)
-- ⏸️ Documentation Phase: 0% complete (0/3 tasks)
-```
-
-### Validation Before Committing
-
-**BEFORE every commit, verify:**
-- [ ] All completed tasks are marked as `[x]` in `tasks.md`
-- [ ] Task status reflects current progress
-- [ ] No tasks are marked complete without implementation
-- [ ] All tests pass for completed tasks
-- [ ] Test coverage meets thresholds (run `npm test -- --coverage`)
-- [ ] Task status updated before moving to next task
-- [ ] Documentation is updated for completed features
-
-### Task Status Update Before Next Task
-
-**CRITICAL RULE**: You MUST update task status in `tasks.md` BEFORE moving to the next task.
-
-**Why:**
-- Prevents loss of progress tracking
-- Ensures context is preserved
-- Makes it easy to resume work
-- Provides clear progress visibility
-
-**Workflow:**
-```bash
-# 1. Complete current task item
-# ... implementation ...
-
-# 2. Test and verify coverage
-npm test
-npm test -- --coverage
-
-# 3. Update tasks.md IMMEDIATELY
-# Mark as [x] and add status comment
-
-# 4. Verify update
-rulebook task show <task-id>
-# Confirm status is updated
-
-# 5. ONLY THEN proceed to next task
-# Follow priority order (most critical first)
-```
-
-**Example:**
-```markdown
-## 1. Implementation Phase
-- [x] 1.1 Create task manager module <!-- tested, coverage: 95% -->
-- [x] 1.2 Add validation logic <!-- tested, coverage: 92%, status: complete -->
-- [ ] 1.3 Add archive functionality <!-- next: will start after status update -->
-```
-
-## Task Archiving Workflow
-
-**CRITICAL**: Archive tasks ONLY after full completion and validation.
-
-### When to Archive
-
-**Archive a task when:**
-- ✅ All items in `tasks.md` are marked as `[x]`
-- ✅ All tests pass (unit, integration, E2E)
-- ✅ Code review is complete (if applicable)
-- ✅ Documentation is updated (README, CHANGELOG, specs)
-- ✅ Task format is validated (`rulebook task validate <task-id>`)
-- ✅ Spec deltas have been applied to main specifications
-
-**NEVER archive a task that is:**
-- ❌ Partially complete
-- ❌ Missing tests
-- ❌ Failing validation
-- ❌ Missing documentation
-
-### Archive Process
-
-**Step-by-step archive workflow:**
-
-```bash
-# 1. Verify all tasks are complete
-rulebook task show <task-id>
-# Check that all items in tasks.md are [x]
-
-# 2. Run all quality checks
-npm test
-npm run lint
-npm run type-check
-npm run build
-
-# 3. Validate task format
-rulebook task validate <task-id>
-
-# 4. Update final documentation
-# - Update CHANGELOG.md
-# - Update README.md if needed
-# - Update any affected documentation
-
-# 5. Archive the task
-rulebook task archive <task-id>
-
-# 6. Verify archive
-rulebook task list --archived
-# Task should appear in archived list
-```
-
-### Post-Archive Actions
-
-**After archiving, ensure:**
-- ✅ Spec deltas are applied to main specifications
-- ✅ CHANGELOG.md is updated with the change
-- ✅ Any breaking changes are documented
-- ✅ Migration guides are created (if needed)
-- ✅ Related tasks are unblocked (if any)
-
-### Archive Location
-
-**Archived tasks are moved to:**
-```
-/.rulebook/tasks/archive/YYYY-MM-DD-<task-id>/
-```
-
-**Structure:**
-```
-/.rulebook/tasks/archive/2025-11-13-add-auth/
-├── proposal.md
-├── tasks.md          # All items marked [x]
-├── design.md
-└── specs/
-    └── core/
-        └── spec.md
-```
-
-## Task Creation Best Practices
-
-### Task ID Naming
-
-**Use verb-led kebab-case:**
-- ✅ `add-user-authentication`
-- ✅ `refactor-task-manager`
-- ✅ `update-api-validation`
-- ✅ `remove-legacy-code`
-- ❌ `user-auth` (not descriptive)
-- ❌ `task_manager` (use kebab-case)
-- ❌ `new-feature` (too generic)
-
-### Task Scope
-
-**One capability per task:**
-- ✅ Good: `add-email-notifications`
-- ❌ Bad: `add-email-notifications-and-sms-and-push` (too broad)
-
-**Break large tasks into smaller ones:**
-- ✅ `add-email-notifications`
-- ✅ `add-sms-notifications`
-- ✅ `add-push-notifications`
-
-### Task Checklist Structure
-
-**Organize tasks by phase:**
-
-```markdown
-## 1. Planning & Design
-- [ ] 1.1 Research existing solutions
-- [ ] 1.2 Design architecture
-- [ ] 1.3 Create technical spec
-
-## 2. Implementation
-- [ ] 2.1 Create core module
-- [ ] 2.2 Add validation logic
-- [ ] 2.3 Integrate with existing system
-
-## 3. Testing
-- [ ] 3.1 Write unit tests
-- [ ] 3.2 Write integration tests
-- [ ] 3.3 Test edge cases
-
-## 4. Documentation
-- [ ] 4.1 Update README
-- [ ] 4.2 Update CHANGELOG
-- [ ] 4.3 Add code comments
-
-## 5. Cleanup
-- [ ] 5.1 Remove debug code
-- [ ] 5.2 Remove unused imports
-- [ ] 5.3 Final code review
-```
-
-## Continuous Task Updates
-
-**CRITICAL**: Update `tasks.md` continuously, not just at the end.
-
-### Real-Time Updates
-
-**Update as you work:**
-1. **Start task**: Mark as `[ ]` (if not already)
-2. **Begin implementation**: Add comment `<!-- in progress -->`
-3. **Complete implementation**: Mark as `[x]`
-4. **Test passes**: Add comment `<!-- tested -->`
-5. **Ready for review**: Add comment `<!-- ready for review -->`
-
-**Example:**
-```markdown
-## 1. Implementation
-- [x] 1.1 Create task manager module <!-- tested -->
-- [x] 1.2 Add validation logic <!-- tested, ready for review -->
-- [ ] 1.3 Add archive functionality <!-- in progress -->
-```
-
-### Progress Tracking
-
-**Add progress indicators:**
-```markdown
-## Progress: 60% (9/15 tasks complete)
-
-## 1. Implementation Phase: 100% ✅
-- [x] 1.1 Task 1
-- [x] 1.2 Task 2
-- [x] 1.3 Task 3
-
-## 2. Testing Phase: 50% ⏳
-- [x] 2.1 Unit tests
-- [x] 2.2 Integration tests
-- [ ] 2.3 E2E tests
-
-## 3. Documentation Phase: 0% ⏸️
-- [ ] 3.1 README
-- [ ] 3.2 CHANGELOG
-- [ ] 3.3 API docs
-```
-
-## Task Validation Before Archive
-
-**MANDATORY checks before archiving:**
-
-```bash
-# 1. Format validation
-rulebook task validate <task-id>
-# Must pass all format checks
-
-# 2. Completion check
-# All items in tasks.md must be [x]
-
-# 3. Test coverage
-npm test -- --coverage
-# Must meet coverage thresholds
-
-# 4. Code quality
-npm run lint
-npm run type-check
-# Must pass all checks
-
-# 5. Build verification
-npm run build
-# Must build successfully
-```
-
-## Summary: Task Lifecycle
-
-**Complete task lifecycle:**
-
-1. **Create** (MANDATORY FIRST STEP): `rulebook task create <task-id>`
-   - ⚠️ NEVER start implementation without creating task first
-   - ⚠️ Tasks without registration can be lost in context
-
-2. **Plan**: Write proposal.md and tasks.md
-   - Define why, what, and how
-   - Create implementation checklist
-
-3. **Design**: Write design.md (if needed)
-   - Technical decisions
-   - Architecture choices
-
-4. **Spec**: Write spec deltas in specs/
-   - OpenSpec-compatible format
-   - Requirements with SHALL/MUST
-
-5. **Validate**: `rulebook task validate <task-id>`
-   - Format validation
-   - Structure verification
-
-6. **Implement**: Write code, following priority order
-   - Most critical tasks first
-   - Update tasks.md as you go
-
-7. **Test** (HIGHEST PRIORITY): Write tests, verify coverage
-   - All tests must pass
-   - Coverage must meet thresholds
-   - Mark tested items in tasks.md
-
-8. **Update Status** (MANDATORY): Update task status before next task
-   - Mark completed items as `[x]`
-   - Update status in tasks.md
-   - Verify status update
-
-9. **Document**: Update docs, mark in tasks.md
-   - README, CHANGELOG, specs
-
-10. **Validate**: Final validation before archive
-    - All checks pass
-    - Coverage verified
-
-11. **Archive**: `rulebook task archive <task-id>`
-    - Move to archive
-    - Apply spec deltas
-
-**CRITICAL REMINDERS:**
-- ⚠️ **ALWAYS create task BEFORE implementation** - without registration, tasks can be lost
-- ⚠️ **ALWAYS follow priority order** - most critical first (tests, coverage, status update)
-- ⚠️ **ALWAYS update task status before next task** - prevents context loss
-- ⚠️ **ALWAYS verify coverage** - run `npm test -- --coverage` before marking complete
-- ⚠️ **ALWAYS commit locally frequently** - even for backup, prevents work loss
-- ⚠️ **ALWAYS keep remote repository updated** - push regularly if remote is configured
-- ⚠️ **ALWAYS update `tasks.md` at EVERY step**, not just at the end!
-
-## Best Practices
-
-### DO's ✅
-
-- **ALWAYS** create task BEFORE implementing any feature
-- **ALWAYS** check Context7 MCP before creating tasks
-- **ALWAYS** validate task format before committing
-- **ALWAYS** use SHALL/MUST in requirements
-- **ALWAYS** use 4 hashtags for scenarios
-- **ALWAYS** use Given/When/Then structure
-- **ALWAYS** follow priority order (most critical first)
-- **ALWAYS** write tests first (highest priority)
-- **ALWAYS** verify test coverage before marking complete
-- **ALWAYS** commit locally frequently (even for backup)
-- **ALWAYS** keep remote repository updated (push regularly)
-- **ALWAYS** update task status before moving to next task
-- **ALWAYS** update task status during implementation
-- **ALWAYS** archive completed tasks
-- **ALWAYS** document breaking changes in proposal
-
-### DON'Ts ❌
-
-- **NEVER** start implementation without creating task first
-- **NEVER** skip task registration (tasks can be lost in context)
-- **NEVER** proceed to next task without updating current task status
-- **NEVER** skip test coverage verification
-- **NEVER** mark tasks complete without tests passing
-- **NEVER** skip local commits (commit frequently for backup)
-- **NEVER** let remote repository get out of sync (push regularly)
-- **NEVER** commit sensitive information (API keys, passwords)
-- **NEVER** force push to shared branches
-- **NEVER** create tasks without checking Context7 format
-- **NEVER** use 3 hashtags for scenarios
-- **NEVER** omit SHALL/MUST from requirements
-- **NEVER** use bullet points for scenarios
-- **NEVER** skip validation
-- **NEVER** leave tasks unarchived after completion
-- **NEVER** mix formats (stick to OpenSpec-compatible format)
-- **NEVER** ignore priority order (always do most critical first)
-
-## CLI Commands Reference
-
-### Task Management Commands
-
-#### `rulebook task create <task-id>`
-
-Create a new Rulebook task with OpenSpec-compatible format.
-
-**Usage:**
-```bash
-rulebook task create add-user-authentication
-```
-
-**What it does:**
-- Creates `/.rulebook/tasks/<task-id>/` directory
-- Generates `proposal.md` template
-- Generates `tasks.md` template
-- Creates `specs/` directory for spec deltas
-
-**Requirements:**
-- Task ID must be unique (verb-led kebab-case)
-- Context7 MCP must be available (for format validation)
-
-**Example:**
-```bash
-$ rulebook task create add-email-notifications
-✅ Task add-email-notifications created successfully
-Location: .rulebook/tasks/add-email-notifications/
-
-⚠️  Remember to:
-  1. Check Context7 MCP for OpenSpec format requirements
-  2. Fill in proposal.md (minimum 20 characters in "Why" section)
-  3. Add tasks to tasks.md
-  4. Create spec deltas in specs/*/spec.md
-  5. Validate with: rulebook task validate add-email-notifications
-```
-
-**Error Handling:**
-- `Task <task-id> already exists`: Choose a different task ID or archive existing task
-
----
-
-#### `rulebook task list [--archived]`
-
-List all Rulebook tasks (active and optionally archived).
-
-**Usage:**
-```bash
-# List active tasks only
-rulebook task list
-
-# List including archived tasks
-rulebook task list --archived
-```
-
-**Output:**
-- Active tasks with status (pending, in-progress, completed, blocked)
-- Archived tasks with archive date (if --archived flag is used)
-
-**Example:**
-```bash
-$ rulebook task list
-
-📋 Rulebook Tasks
-
-Active Tasks:
-  pending      add-user-authentication - Add user authentication feature
-  in-progress  refactor-api-validation - Refactor API validation logic
-  completed    update-documentation - Update project documentation
-
-$ rulebook task list --archived
-
-📋 Rulebook Tasks
-
-Active Tasks:
-  pending      add-user-authentication - Add user authentication feature
-
-Archived Tasks:
-  archived     2025-01-15-add-email-notifications - Add email notifications (2025-01-15)
-```
-
-**Task Status Values:**
-- `pending`: Task not started
-- `in-progress`: Task being worked on
-- `completed`: Task finished (ready for archive)
-- `blocked`: Task blocked by dependency
-
----
-
-#### `rulebook task show <task-id>`
-
-Show detailed information about a specific task.
-
-**Usage:**
-```bash
-rulebook task show add-user-authentication
-```
-
-**Output:**
-- Task ID and title
-- Status (pending, in-progress, completed, blocked)
-- Created and updated dates
-- Archive date (if archived)
-- Proposal summary (first 500 characters)
-- Spec files list
-
-**Example:**
-```bash
-$ rulebook task show add-user-authentication
-
-📋 Task: add-user-authentication
-
-Title: add-user-authentication
-Status: pending
-Created: 2025-01-15T10:30:00.000Z
-Updated: 2025-01-15T10:30:00.000Z
-
-Proposal:
-# Proposal: Add User Authentication
-
-## Why
-We need to implement secure user authentication to protect user accounts and enable personalized features. This will include JWT token-based authentication with refresh tokens and password hashing using bcrypt...
-
-Specs:
-  core/spec.md (1234 chars)
-```
-
-**Error Handling:**
-- `Task <task-id> not found`: Verify task ID exists with `rulebook task list`
-
----
-
-#### `rulebook task validate <task-id>`
-
-Validate task format against OpenSpec-compatible requirements.
-
-**Usage:**
-```bash
-rulebook task validate add-user-authentication
-```
-
-**Validation Checks:**
-- Purpose section length (≥20 characters)
-- Requirement keywords (SHALL/MUST)
-- Scenario format (4 hashtags, not 3)
-- Given/When/Then structure
-- Delta headers format (ADDED/MODIFIED/REMOVED/RENAMED)
-
-**Example:**
-```bash
-$ rulebook task validate add-user-authentication
-✅ Task add-user-authentication is valid
-
-⚠️  Warnings:
-  - Scenario in core/spec.md should use Given/When/Then structure
-```
-
-**Error Example:**
-```bash
-$ rulebook task validate invalid-task
-❌ Task invalid-task validation failed
-
-Errors:
-  - Scenarios in core/spec.md must use 4 hashtags (####), not 3 (###)
-  - Requirement in core/spec.md missing SHALL or MUST keyword: ### Requirement: Auth
-  - Purpose section (## Why) must have at least 20 characters
-```
-
-**Error Handling:**
-- Fix all errors before proceeding
-- Warnings are informational but don't block archiving
-
----
-
-#### `rulebook task archive <task-id> [--skip-validation]`
-
-Archive a completed task and apply spec deltas to main specifications.
-
-**Usage:**
-```bash
-# Archive with validation (recommended)
-rulebook task archive add-user-authentication
-
-# Archive without validation (use with caution)
-rulebook task archive add-user-authentication --skip-validation
-```
-
-**Archive Process:**
-1. Validates task format (unless `--skip-validation` is used)
-2. Checks task completion status
-3. Applies spec deltas to main specifications
-4. Moves task to `/.rulebook/tasks/archive/YYYY-MM-DD-<task-id>/`
-5. Updates related specifications
-
-**Example:**
-```bash
-$ rulebook task archive add-user-authentication
-✅ Task add-user-authentication archived successfully
-```
-
-**Error Handling:**
-- `Task validation failed`: Fix validation errors before archiving
-- `Task <task-id> not found`: Verify task ID exists
-- `Archive <archive-name> already exists`: Archive with that date already exists
-
-**Important:**
-- Only archive tasks that are fully completed
-- All items in `tasks.md` should be marked as `[x]`
-- All tests should pass
-- Documentation should be updated
-
----
-
-### Core Rulebook Commands
-
-#### `rulebook init [--minimal] [--light] [--yes]`
-
-Initialize Rulebook for current project.
-
-**Usage:**
-```bash
-# Interactive mode
-rulebook init
-
-# Minimal setup (essentials only)
-rulebook init --minimal
-
-# Light mode (no quality enforcement)
-rulebook init --light
-
-# Skip prompts, use defaults
-rulebook init --yes
-```
-
-**What it does:**
-- Detects languages, frameworks, and MCP modules
-- Generates AGENTS.md with AI assistant rules
-- Creates `/rulebook/` directory with templates
-- Creates/updates `.gitignore` automatically
-- Optionally installs Git hooks
-- Generates Cursor commands (if Cursor is selected IDE)
-
----
-
-#### `rulebook update [--yes] [--minimal] [--light]`
-
-Update AGENTS.md and .rulebook to latest version.
-
-**Usage:**
-```bash
-# Interactive mode
-rulebook update
-
-# Skip confirmation
-rulebook update --yes
-
-# Minimal mode
-rulebook update --minimal
-
-# Light mode
-rulebook update --light
-```
-
-**What it does:**
-- Migrates OpenSpec tasks to Rulebook format (if OpenSpec exists)
-- Migrates OpenSpec archives to Rulebook format
-- Removes OpenSpec commands from `.cursor/commands/`
-- Updates AGENTS.md with latest templates
-- Merges templates while preserving customizations
-- Updates Cursor commands (if Cursor is selected IDE)
-
----
-
-#### `rulebook validate`
-
-Validate project structure against Rulebook standards.
-
-**Usage:**
-```bash
-rulebook validate
-```
-
-**Validation Checks:**
-- AGENTS.md presence and format
-- Rulebook directory structure
-- Documentation structure
-- Tests directory
-- Score calculation (0-100)
-
----
-
-#### `rulebook health`
-
-Check project health score.
-
-**Usage:**
-```bash
-rulebook health
-```
-
-**Categories Scored:**
-- Quality (linting, formatting, code quality)
-- Testing (test coverage, test quality)
-- Security (vulnerabilities, secrets)
-- Documentation (README, docs/, comments)
-
-**Score Range:** 0-100
-
----
-
-#### `rulebook workflows`
-
-Generate GitHub Actions workflows for detected languages.
-
-**Usage:**
-```bash
-rulebook workflows
-```
-
-**What it does:**
-- Creates `.github/workflows/` directory
-- Generates language-specific workflows (test, lint, publish)
-- Adds codespell workflow for spelling checks
-
----
-
-#### `rulebook check-deps`
-
-Check for outdated and vulnerable dependencies.
-
-**Usage:**
-```bash
-rulebook check-deps
-```
-
-**Supported Package Managers:**
-- npm (package.json)
-- Cargo (Cargo.toml)
-- pip (requirements.txt, pyproject.toml)
-- Go modules (go.mod)
-
----
-
-#### `rulebook check-coverage [-t <threshold>]`
-
-Check test coverage against threshold.
-
-**Usage:**
-```bash
-# Default threshold (95%)
-rulebook check-coverage
-
-# Custom threshold
-rulebook check-coverage -t 80
-```
-
----
-
-#### `rulebook generate-docs [--yes]`
-
-Generate documentation structure and standard files.
-
-**Usage:**
-```bash
-# Interactive mode
-rulebook generate-docs
-
-# Skip prompts
-rulebook generate-docs --yes
-```
-
----
-
-#### `rulebook version <major|minor|patch>`
-
-Bump project version (semantic versioning).
-
-**Usage:**
-```bash
-rulebook version major  # 1.0.0 -> 2.0.0
-rulebook version minor  # 1.0.0 -> 1.1.0
-rulebook version patch  # 1.0.0 -> 1.0.1
-```
-
----
-
-#### `rulebook changelog [-v <version>]`
-
-Generate changelog from git commits.
-
-**Usage:**
-```bash
-# Auto-detect version
-rulebook changelog
-
-# Specify version
-rulebook changelog -v 1.0.0
-```
-
----
-
-#### `rulebook fix`
-
-Auto-fix common project issues.
-
-**Usage:**
-```bash
-rulebook fix
-```
-
----
-
-### Advanced Commands (Beta)
-
-#### `rulebook watcher`
-
-Start modern full-screen console watcher for task progress.
-
-**Usage:**
-```bash
-rulebook watcher
-```
-
-**Features:**
-- Live task progress tracking
-- Activity log with timestamps
-- System status monitoring
-- Auto-refresh every 2 seconds
-
----
-
-#### `rulebook agent [--dry-run] [--tool <name>] [--iterations <n>] [--watch]`
-
-Start autonomous agent for managing AI CLI workflows.
-
-**Usage:**
-```bash
-# Dry run (simulate without changes)
-rulebook agent --dry-run
-
-# Specify CLI tool
-rulebook agent --tool cursor-agent
-
-# Set max iterations
-rulebook agent --iterations 10
-
-# Enable watcher mode
-rulebook agent --watch
-```
-
----
-
-#### `rulebook config [--show] [--set <key=value>] [--feature <name> --enable|--disable]`
-
-Manage Rulebook configuration.
-
-**Usage:**
-```bash
-# Show current config
-rulebook config --show
-
-# Set config value
-rulebook config --set rulebookDir=custom-rulebook
-
-# Enable feature
-rulebook config --feature watcher --enable
-
-# Disable feature
-rulebook config --feature agent --disable
-```
-
-## Migration from OpenSpec
-
-If your project previously used OpenSpec:
-
-1. **Automatic Migration**: Run `rulebook update` to automatically migrate OpenSpec tasks to Rulebook format
-2. **Manual Migration**: Tasks in `/openspec/changes/` will be moved to `/.rulebook/tasks/`
-3. **Format Compatibility**: Rulebook uses OpenSpec-compatible format, so existing tasks remain valid
-
-## Context7 MCP Requirement
-
-**CRITICAL**: Context7 MCP is REQUIRED for task creation.
-
-**Why**: 
-- Ensures correct format by fetching official OpenSpec documentation
-- Prevents common format errors made by AI assistants
-- Provides up-to-date format requirements
-
-**If Context7 MCP is not available:**
-- Task creation will fail with clear error message
-- You must configure Context7 MCP before creating tasks
-- See `/rulebook/CONTEXT7.md` for setup instructions
-
-## Troubleshooting
-
-### Validation Errors
-
-**Error**: "Requirement must contain SHALL or MUST keyword"
-- **Fix**: Add SHALL or MUST to requirement text
-- **Example**: Change "The system provides authentication" to "The system SHALL provide authentication"
-
-**Error**: "Scenario must use 4 hashtags"
-- **Fix**: Change `### Scenario:` to `#### Scenario:` (at start of line)
-- **Note**: Validation only checks headers at start of line, not in text content
-
-**Error**: "Purpose section too short"
-- **Fix**: Expand "Why" section in proposal.md to at least 20 characters
-- **Example**: "Auth system" → "Authentication system for secure user access with JWT tokens and session management"
-
-**Error**: "Scenario must use Given/When/Then structure"
-- **Fix**: Replace bullet points with Given/When/Then format
-- **Example**: 
-  ```markdown
-  #### Scenario: User login
-  Given a user has valid credentials
-  When they submit the login form
-  Then they are authenticated successfully
-  ```
-
-### Task Creation Errors
-
-**Error**: "Context7 MCP not available"
-- **Fix**: Configure Context7 MCP in your MCP configuration file
-- **See**: `/rulebook/CONTEXT7.md` for setup instructions
-
-**Error**: "Task ID already exists"
-- **Fix**: Choose a different task ID or archive existing task
-- **Check**: Use `rulebook task list` to see existing tasks
-
-### Task Archive Errors
-
-**Error**: "Task validation failed"
-- **Fix**: Run `rulebook task validate <task-id>` to see all errors
-- **Fix**: Address all validation errors before archiving
-- **Option**: Use `--skip-validation` flag only if you're certain the task is valid
-
-**Error**: "Archive <archive-name> already exists"
-- **Fix**: Archive with that date already exists
-- **Check**: Use `rulebook task list --archived` to see archived tasks
-
-### Command Errors
-
-**Error**: "Task <task-id> not found"
-- **Fix**: Verify task ID exists with `rulebook task list`
-- **Check**: Ensure you're in the correct project directory
-
-**Error**: "No tasks found"
-- **Fix**: Create a task first with `rulebook task create <task-id>`
-- **Check**: Verify `/.rulebook/tasks/` directory exists
-
-### Migration Errors
-
-**Error**: "Failed to migrate task"
-- **Fix**: Check error message for specific issue
-- **Check**: Verify OpenSpec task structure is correct
-- **Fix**: Manually migrate if automatic migration fails
-
-**Error**: "Failed to read OpenSpec changes directory"
-- **Fix**: Verify `/openspec/changes/` directory exists
-- **Check**: Ensure you have read permissions
-
-## Examples
-
-See `/.rulebook/tasks/` directory for examples of correctly formatted tasks.
-
-<!-- RULEBOOK:END -->
-
+<!-- RULEBOOK:START -->
+# Rulebook Task Management
+
+**CRITICAL**: Use Rulebook's built-in task management system for spec-driven development of new features and breaking changes.
+
+## When to Use
+
+Create tasks for:
+- ✅ New features/capabilities
+- ✅ Breaking changes
+- ✅ Architecture changes
+- ✅ Performance/security work
+
+Skip for:
+- ❌ Bug fixes (restore intended behavior)
+- ❌ Typos, formatting, comments
+- ❌ Dependency updates (non-breaking)
+
+## Persistent Memory Integration
+
+**IMPORTANT**: Task management is tightly integrated with persistent memory system for cross-session context:
+
+### Task Completion and Memory
+When a task is marked as completed:
+1. **Auto-save to memory** (if enabled): Key learnings, patterns, gotchas from task specs are captured
+2. **Search past tasks**: Before creating similar tasks, search memory for past implementations:
+   ```bash
+   rulebook memory search "authentication" --type feature
+   ```
+3. **Update implementation faster**: Reference past solutions documented in memory
+
+### Memory during Task Development
+As you work on a task:
+- **Save discoveries**: Use `rulebook memory save` to capture patterns and gotchas
+- **Reference past context**: Search memory for related implementations
+- **Document decisions**: Save architectural choices for future developers
+
+## ⚠️ CRITICAL: Task Creation is MANDATORY Before Implementation
+
+**ABSOLUTE RULE**: You MUST create a task BEFORE implementing ANY feature.
+
+### Why This Matters
+
+**Without task registration:**
+- ❌ Tasks can be lost in context
+- ❌ No tracking of implementation progress
+- ❌ No record of what was done and why
+- ❌ Difficult to resume work after context loss
+- ❌ No validation of completion criteria
+
+**With task registration:**
+- ✅ All features are tracked and documented
+- ✅ Progress is visible and measurable
+- ✅ Implementation history is preserved
+- ✅ Easy to resume work from any point
+- ✅ Clear completion criteria
+
+### MANDATORY Workflow
+
+**NEVER start implementation without creating a task first:**
+
+```bash
+# ❌ WRONG: Starting implementation directly
+# ... writing code without task ...
+
+# ✅ CORRECT: Create task first
+rulebook task create <task-id>
+# Write proposal.md
+# Write tasks.md
+# Write spec deltas
+rulebook task validate <task-id>
+# NOW you can start implementation
+```
+
+### Task Creation Before Any Feature Request
+
+**When a feature is requested:**
+
+1. **STOP** - Do not start coding
+2. **Create task** - `rulebook task create <task-id>`
+3. **Plan** - Write proposal.md and tasks.md
+4. **Spec** - Write spec deltas
+5. **Validate** - `rulebook task validate <task-id>`
+6. **THEN** - Start implementation
+
+**Example:**
+```
+User: "Add user authentication feature"
+
+❌ WRONG: Start coding immediately
+✅ CORRECT:
+  1. rulebook task create add-user-authentication
+  2. Write proposal.md explaining why and what
+  3. Write tasks.md with implementation checklist
+  4. Write specs/core/spec.md with requirements
+  5. rulebook task validate add-user-authentication
+  6. NOW start implementing
+```
+
+## CRITICAL: Task Creation Workflow
+
+**MANDATORY STEPS** - Follow in this exact order:
+
+### Step 1: Check Context7 MCP (MANDATORY)
+
+**BEFORE creating ANY task, you MUST:**
+
+1. **Query Context7 for OpenSpec documentation** (Rulebook uses OpenSpec-compatible format):
+   ```
+   @Context7 /fission-ai/openspec task creation format spec structure
+   ```
+
+2. **Review official format requirements**:
+   - Spec delta file format
+   - Requirement structure
+   - Scenario formatting
+   - Delta headers (ADDED/MODIFIED/REMOVED/RENAMED)
+
+3. **Verify format requirements**:
+   - Scenario MUST use `#### Scenario:` (4 hashtags, NOT 3, NOT bullets)
+   - Requirements MUST use `### Requirement: [Name]`
+   - MUST include SHALL/MUST statement after requirement name
+   - MUST include at least one scenario per requirement
+   - Purpose section MUST have minimum 20 characters
+
+**Why This Matters:**
+Most AI assistants create tasks with incorrect formats (wrong scenario headers, missing SHALL statements, incomplete deltas). Context7 provides the official format documentation that prevents validation failures.
+
+### Step 2: Explore Current State
+
+```bash
+# List existing tasks
+rulebook task list
+
+# List active changes
+rulebook task list --active
+
+# View task details
+rulebook task show <task-id>
+```
+
+### Step 3: Choose Task ID
+
+- Use **verb-led** kebab-case: `add-auth`, `update-api`, `remove-feature`, `refactor-module`
+- Must be unique (check existing tasks)
+- Descriptive and focused (one capability per task)
+
+### Step 4: Create Task Structure
+
+```bash
+# Create new task
+rulebook task create <task-id>
+
+# This creates:
+# /.rulebook/tasks/<task-id>/
+#   ├── proposal.md       # Why and what changes
+#   ├── tasks.md          # Implementation checklist
+#   ├── design.md         # Technical decisions (optional)
+#   └── specs/
+#       └── <module>/
+#           └── spec.md   # Delta showing additions/modifications
+```
+
+### Step 5: Write Proposal
+
+**File**: `/.rulebook/tasks/<task-id>/proposal.md`
+
+```markdown
+# Proposal: Task Name
+
+## Why
+Minimum 20 characters explaining why this change is needed.
+Provide context, motivation, and business/technical rationale.
+
+## What Changes
+Detailed description of what will change:
+- Specific components affected
+- New features or capabilities
+- Breaking changes (if any)
+- Migration path (if applicable)
+
+## Impact
+- Affected specs: list spec names
+- Affected code: list files/modules
+- Breaking change: YES/NO
+- User benefit: describe benefits
+```
+
+### Step 6: Write Tasks Checklist
+
+**File**: `/.rulebook/tasks/<task-id>/tasks.md`
+
+```markdown
+## 1. Implementation Phase
+- [ ] 1.1 First task item
+- [ ] 1.2 Second task item
+
+## 2. Testing Phase
+- [ ] 2.1 Write unit tests
+- [ ] 2.2 Write integration tests
+
+## 3. Documentation Phase
+- [ ] 3.1 Update README
+- [ ] 3.2 Update CHANGELOG
+```
+
+**⚠️ CRITICAL: Sequential Execution Rule**
+
+When implementing tasks from `tasks.md`, you MUST execute items **in the exact order listed**:
+
+1. Find the FIRST unchecked item (`- [ ]`) — implement THAT one
+2. Mark it `[x]` when done
+3. Move to the NEXT unchecked item
+4. **NEVER** skip ahead, reorder, or cherry-pick tasks
+5. **NEVER** start a later phase before the current phase is 100% complete
+
+**The task list is an ORDER, not a MENU.** The human defined the sequence deliberately. Follow it.
+
+### Step 7: Write Spec Delta
+
+**File**: `/.rulebook/tasks/<task-id>/specs/<module>/spec.md`
+
+**CRITICAL FORMAT REQUIREMENTS:**
+
+```markdown
+# Specification Name
+
+## ADDED Requirements
+
+### Requirement: Feature Name
+The system SHALL/MUST do something specific and testable.
+Every requirement needs SHALL or MUST keyword.
+
+#### Scenario: Scenario Name
+Given some precondition
+When an action occurs
+Then an expected outcome happens
+
+## MODIFIED Requirements
+
+### Requirement: Existing Feature
+The system SHALL/MUST do something modified.
+
+#### Scenario: Modified scenario
+Given updated precondition
+When action occurs
+Then new expected outcome
+
+## REMOVED Requirements
+
+### Requirement: Deprecated Feature
+[Description of what is being removed]
+
+## RENAMED Requirements
+- FROM: `### Requirement: Old Name`
+- TO: `### Requirement: New Name`
+```
+
+**Format Rules:**
+- ✅ Purpose section: Minimum 20 characters
+- ✅ Requirements: Must contain SHALL or MUST
+- ✅ Scenarios: Use `#### Scenario:` (4 hashtags)
+- ✅ Scenarios: Use Given/When/Then structure
+- ✅ Deltas: Use ADDED/MODIFIED/REMOVED/RENAMED headers
+- ❌ NEVER use 3 hashtags for scenarios
+- ❌ NEVER use bullet points for scenarios
+- ❌ NEVER omit SHALL/MUST from requirements
+
+### Step 8: Validate Task
+
+```bash
+# Validate task format
+rulebook task validate <task-id>
+
+# Validate with strict mode (recommended)
+rulebook task validate <task-id> --strict
+
+# Validate all tasks
+rulebook task validate --all
+```
+
+**Validation checks:**
+- Purpose section length (≥20 chars)
+- Requirement keywords (SHALL/MUST)
+- Scenario format (4 hashtags)
+- Given/When/Then structure
+- Delta headers format
+
+### Step 9: Update Task Status
+
+```bash
+# Mark task as in progress
+rulebook task update <task-id> --status in-progress
+
+# Update task progress
+rulebook task update <task-id> --progress 50
+
+# Mark task as completed
+rulebook task update <task-id> --status completed
+```
+
+### Step 10: Archive Completed Task
+
+```bash
+# Archive completed task
+rulebook task archive <task-id>
+
+# Archive without prompts
+rulebook task archive <task-id> --yes
+```
+
+**Archive process:**
+1. Validates task format
+2. Checks task completion status
+3. Applies spec deltas to main specifications
+4. Moves task to `/.rulebook/tasks/archive/YYYY-MM-DD-<task-id>/`
+5. Updates related specifications
+
+## 🚨 MANDATORY: Deferred Items → Tasks Rule
+
+**ABSOLUTE RULE — NO EXCEPTIONS**: Whenever a task is archived with items marked as "Deferred" or "Phase X+", you MUST immediately create Rulebook tasks for those deferred items **before archiving**.
+
+### The Deferred Items Protocol
+
+```
+❌ WRONG — defer without creating task:
+1. Archive task with "- [ ] D1. feature X — deferred Phase 4"
+   → Feature X is now forgotten forever
+
+✅ CORRECT — defer with tracking:
+1. Add "- [ ] D1. feature X — deferred Phase 4" to tasks.md
+2. Call rulebook_task_create("phase4-feature-x")
+3. Write tasks.md for the new task with full context
+4. THEN call rulebook_task_archive
+```
+
+### tasks.md Format for Archived Tasks
+
+```markdown
+## 1. Implemented Feature
+
+- [x] 1.1 Thing that was done
+- [x] 1.2 Another thing done
+
+## Deferred to Phase N (reason: dependency not ready)
+
+- [ ] D1. Feature X — deferred (reason)   ← task phase4-feature-x MUST exist
+- [ ] D2. Feature Y — deferred (reason)   ← task phaseN-feature-y MUST exist
+```
+
+### Archive Checklist (ALL must be done before `rulebook_task_archive`)
+
+```
+□ 1. tasks.md uses - [x] for implemented, - [ ] for deferred
+□ 2. Each deferred item has a "Phase N" target
+□ 3. A rulebook task exists for EVERY deferred item or group
+□ 4. The new deferred tasks have tasks.md with full context
+□ 5. THEN call rulebook_task_archive
+```
+
+## Task Format Examples
+
+### Correct Format ✅
+
+```markdown
+# Auth Specification
+
+## ADDED Requirements
+
+### Requirement: Two-Factor Authentication
+The system MUST require a second factor during login for enhanced security.
+
+#### Scenario: OTP required
+Given a user submits valid credentials
+When authentication starts
+Then an OTP challenge is required
+
+#### Scenario: OTP verification
+Given a user receives an OTP code
+When they submit the correct OTP
+Then they are authenticated successfully
+```
+
+### Incorrect Format ❌
+
+```markdown
+# Auth Specification
+
+## Requirements
+
+### Requirement: Two-Factor Authentication
+The system requires a second factor.  # ❌ Missing SHALL/MUST
+
+#### Scenario: OTP required  # ❌ Only 3 hashtags
+- WHEN user submits credentials  # ❌ Using bullets instead of Given/When/Then
+- THEN OTP challenge is required
+```
+
+## Common Pitfalls & How to Avoid Them
+
+### Top 5 Mistakes AI Assistants Make
+
+1. **Wrong Scenario Headers**
+   - ❌ `### Scenario:` (3 hashtags)
+   - ✅ `#### Scenario:` (4 hashtags)
+
+2. **Missing SHALL/MUST Keywords**
+   - ❌ "The system provides authentication"
+   - ✅ "The system SHALL provide authentication"
+
+3. **Using Bullets for Scenarios**
+   - ❌ `- WHEN user does X THEN Y happens`
+   - ✅ `Given X\nWhen Y\nThen Z`
+
+4. **Incomplete Purpose Section**
+   - ❌ "Auth system" (too short)
+   - ✅ "Authentication system for secure user access with JWT tokens and session management" (≥20 chars)
+
+5. **Wrong Delta Headers**
+   - ❌ `## New Requirements` or `## Changes`
+   - ✅ `## ADDED Requirements`, `## MODIFIED Requirements`, etc.
+
+## Integration with AGENT_AUTOMATION
+
+**CRITICAL**: After implementing a task, follow AGENT_AUTOMATION workflow:
+
+1. Run quality checks (lint, test, type-check, build)
+2. Update task status in `tasks.md`
+3. Update documentation (ROADMAP, CHANGELOG, specs)
+4. Commit with conventional commit format
+5. Archive task when complete
+
+## ⚠️ CRITICAL: Git Hooks Will Block Commits with Problems
+
+**ABSOLUTE RULE**: Pre-commit and pre-push hooks will **BLOCK** any commit attempt if there are:
+- ❌ Lint errors or warnings
+- ❌ Test failures
+- ❌ Type check errors
+- ❌ Formatting issues
+- ❌ Coverage below thresholds
+
+### Why This Matters
+
+**DO NOT attempt to commit code with problems:**
+- ❌ `git commit` will **FAIL** if lint has errors
+- ❌ `git commit` will **FAIL** if tests are failing
+- ❌ `git push` will **FAIL** if pre-push checks fail
+- ❌ You will waste time trying to commit broken code
+- ❌ The hooks will reject your commit automatically
+
+**ALWAYS fix problems BEFORE attempting to commit:**
+- ✅ Run `npm run lint` and fix ALL errors/warnings first
+- ✅ Run `npm test` and ensure ALL tests pass
+- ✅ Run `npm run type-check` and fix ALL type errors
+- ✅ Run `npm run format` if formatting is required
+- ✅ Run `npm test -- --coverage` and ensure coverage thresholds are met
+- ✅ **ONLY THEN** attempt `git commit`
+
+### Mandatory Pre-Commit Workflow
+
+**BEFORE every commit, you MUST:**
+
+```bash
+# 1. Fix lint errors FIRST (highest priority)
+npm run lint
+# Fix ALL errors and warnings
+# If lint fails, commit will be blocked
+
+# 2. Fix test failures SECOND
+npm test
+# Fix ALL failing tests
+# If tests fail, commit will be blocked
+
+# 3. Fix type errors THIRD
+npm run type-check
+# Fix ALL type errors
+# If type check fails, commit will be blocked
+
+# 4. Fix formatting (if required)
+npm run format
+# Apply formatting fixes
+
+# 5. Verify coverage (if required by hooks)
+npm test -- --coverage
+# Ensure coverage thresholds are met
+
+# 6. ONLY AFTER all checks pass, attempt commit
+git add .
+git commit -m "feat: your commit message"
+# This will now succeed because all checks passed
+```
+
+### What Happens If You Try to Commit with Problems
+
+**Example of blocked commit:**
+
+```bash
+$ git commit -m "feat: add new feature"
+
+🔍 Running TypeScript/JavaScript pre-commit checks...
+  → Type checking...
+  → Linting...
+
+/mnt/f/project/src/feature.ts
+   42:19  error  Unexpected any. Specify a different type  @typescript-eslint/no-explicit-any
+
+✖ 1 problem (1 error, 0 warnings)
+
+❌ Commit blocked: Lint errors found
+```
+
+**You MUST fix the error before committing:**
+
+```bash
+# Fix the lint error
+# ... edit code to fix the issue ...
+
+# Run lint again to verify
+npm run lint
+# ✅ All checks pass
+
+# NOW commit will succeed
+git commit -m "feat: add new feature"
+# ✅ Commit successful
+```
+
+### ⚠️ CRITICAL: NEVER Use --no-verify to Bypass Hooks
+
+**ABSOLUTE PROHIBITION**: You MUST NEVER use `--no-verify` or `--no-gpg-sign` flags to bypass git hooks.
+
+**FORBIDDEN COMMANDS:**
+- ❌ `git commit --no-verify` - **NEVER USE THIS**
+- ❌ `git commit -n` - **NEVER USE THIS** (short form of --no-verify)
+- ❌ `git push --no-verify` - **NEVER USE THIS**
+- ❌ Any flag that skips pre-commit or pre-push hooks
+
+### Why This Is Prohibited
+
+**Using `--no-verify` defeats the entire purpose of quality gates:**
+- ❌ Allows broken code to be committed
+- ❌ Bypasses all quality checks (lint, test, type-check)
+- ❌ Introduces technical debt and bugs
+- ❌ Violates project quality standards
+- ❌ Can break the build for other developers
+- ❌ Makes code review harder (reviewers see broken code)
+
+**The hooks exist for a reason:**
+- ✅ They protect code quality
+- ✅ They prevent bugs from entering the codebase
+- ✅ They ensure consistency across the project
+- ✅ They catch errors before they reach production
+
+### What to Do Instead
+
+**If you're tempted to use `--no-verify`, it means:**
+1. **You have problems that need fixing** - Fix them first
+2. **You're trying to commit too early** - Complete the work properly
+3. **You're rushing** - Slow down and do it right
+
+**Correct approach:**
+
+```bash
+# ❌ WRONG: Trying to bypass hooks
+git commit --no-verify -m "feat: add feature"
+# This is FORBIDDEN - never do this
+
+# ✅ CORRECT: Fix problems first, then commit
+npm run lint
+# Fix all errors...
+
+npm test
+# Fix all failing tests...
+
+npm run type-check
+# Fix all type errors...
+
+# NOW commit (hooks will pass)
+git commit -m "feat: add feature"
+# ✅ Commit successful - all checks passed
+```
+
+### Summary
+
+**CRITICAL RULES:**
+- ⚠️ **NEVER** attempt to commit code with lint errors - hooks will block it
+- ⚠️ **NEVER** attempt to commit code with test failures - hooks will block it
+- ⚠️ **NEVER** attempt to commit code with type errors - hooks will block it
+- ⚠️ **NEVER** use `--no-verify` or any flag to bypass hooks - **ABSOLUTELY FORBIDDEN**
+- ⚠️ **ALWAYS** fix ALL problems BEFORE attempting to commit
+- ⚠️ **ALWAYS** run quality checks manually before `git commit`
+- ⚠️ **ALWAYS** ensure all checks pass before committing
+
+**The hooks are there to protect code quality - they will NOT let broken code through. Always resolve problems first, then commit. Bypassing hooks is strictly prohibited and defeats the purpose of quality gates.**
+
+## MANDATORY: Task List Updates During Implementation
+
+**CRITICAL RULE**: You MUST update the task list (`tasks.md`) immediately after completing and testing each implementation step.
+
+### When to Update Task List
+
+**ALWAYS update `tasks.md` when:**
+- ✅ You complete a task item (mark as `[x]`)
+- ✅ You finish implementing a feature and it's tested
+- ✅ You complete a test suite
+- ✅ You finish documentation updates
+- ✅ You verify the implementation works correctly
+
+**NEVER commit without updating `tasks.md` if you've made progress on a task.**
+
+### How to Update Task List
+
+1. **After Implementation**:
+   ```markdown
+   ## 1. Implementation Phase
+   - [x] 1.1 Create task manager module  # ✅ Mark as done
+   - [x] 1.2 Add validation logic        # ✅ Mark as done
+   - [ ] 1.3 Add archive functionality   # Still pending
+   ```
+
+2. **After Testing**:
+   ```markdown
+   ## 2. Testing Phase
+   - [x] 2.1 Write unit tests            # ✅ Tests written and passing
+   - [x] 2.2 Write integration tests     # ✅ Tests written and passing
+   - [ ] 2.3 Add E2E tests                # Still pending
+   ```
+
+3. **After Documentation**:
+   ```markdown
+   ## 3. Documentation Phase
+   - [x] 3.1 Update README                # ✅ Updated
+   - [x] 3.2 Update CHANGELOG             # ✅ Updated
+   - [ ] 3.3 Update API docs              # Still pending
+   ```
+
+### Workflow: Implement → Test → Verify Coverage → Update Tasks → Commit → Next Task
+
+**MANDATORY SEQUENCE** for every implementation:
+
+```bash
+# 1. Implement the feature
+# ... write code ...
+
+# 2. Test the implementation
+npm test
+npm run lint
+npm run type-check
+
+# 3. Verify test coverage (CRITICAL)
+npm test -- --coverage
+# Check coverage thresholds are met
+# Fix any coverage gaps before proceeding
+
+# 4. Update tasks.md IMMEDIATELY after successful tests and coverage check
+# Mark completed items as [x] in tasks.md
+# Update task status if needed
+
+# 5. Verify task status is updated before moving to next task
+rulebook task show <task-id>
+# Confirm status reflects current progress
+
+# 6. Commit locally (BACKUP - do this frequently)
+git add .
+git commit -m "feat: implement task manager validation
+
+- Complete task 1.2: Add validation logic
+- All tests passing
+- Coverage verified: 95%
+- Updated tasks.md"
+
+# 7. Keep remote repository updated (if configured)
+# Check if remote is configured
+git remote -v
+
+# If remote exists, push regularly
+git push origin <branch-name>
+
+# If no remote configured, see setup instructions below
+
+# 8. Only then proceed to next task
+# Follow priority order (most critical first)
+```
+
+## ⚠️ CRITICAL: Frequent Local Commits for Backup
+
+**ABSOLUTE RULE**: Commit locally frequently, even if just for backup purposes.
+
+### Why Frequent Commits Matter
+
+**Without frequent commits:**
+- ❌ Risk of losing work if system crashes
+- ❌ No recovery point if something goes wrong
+- ❌ Difficult to revert to previous working state
+- ❌ Lost context if session is interrupted
+
+**With frequent commits:**
+- ✅ Work is backed up locally
+- ✅ Easy to recover from mistakes
+- ✅ Can revert to any previous state
+- ✅ Progress is preserved
+
+### When to Commit Locally
+
+**Commit locally whenever you:**
+- ✅ Complete a task item (even if not fully tested)
+- ✅ Finish implementing a feature (before full testing)
+- ✅ Fix a bug or issue
+- ✅ Update documentation
+- ✅ Make significant progress
+- ✅ Feel the need for a backup point
+- ✅ Are about to try something risky
+- ✅ Are switching to a different task
+
+**Commit frequency:**
+- **Minimum**: After completing each task item
+- **Recommended**: Every 15-30 minutes of active work
+- **Maximum**: As often as you feel necessary for safety
+
+### Local Commit Workflow
+
+```bash
+# Quick local commit (backup)
+git add .
+git commit -m "wip: progress on task 1.2
+
+- Implemented validation logic
+- Still testing
+- Backup commit"
+
+# Or more descriptive
+git add .
+git commit -m "feat: add validation logic (WIP)
+
+- Task 1.2 in progress
+- Core validation implemented
+- Tests pending
+- Backup before continuing"
+```
+
+### Commit Message Format for Backup Commits
+
+**For work-in-progress commits:**
+```bash
+git commit -m "wip: <brief description>
+
+- What was done
+- Current status
+- Next steps"
+```
+
+**For completed task items:**
+```bash
+git commit -m "feat: <feature description>
+
+- Complete task X.Y: <task name>
+- All tests passing
+- Coverage verified
+- Updated tasks.md"
+```
+
+## ⚠️ CRITICAL: Keep Remote Repository Updated
+
+**MANDATORY**: Keep your remote repository synchronized with local work.
+
+### Check Remote Configuration
+
+**First, check if remote is configured:**
+```bash
+git remote -v
+```
+
+**If you see output like:**
+```
+origin  https://github.com/user/repo.git (fetch)
+origin  https://github.com/user/repo.git (push)
+```
+✅ Remote is configured - proceed to push regularly
+
+**If you see no output or error:**
+❌ No remote configured - see setup instructions below
+
+### Push to Remote Regularly
+
+**After local commits, push to remote:**
+```bash
+# Push current branch
+git push origin <branch-name>
+
+# Or push current branch (if tracking is set)
+git push
+
+# Push with tags
+git push --tags
+```
+
+**Recommended push frequency:**
+- **Minimum**: After completing a task
+- **Recommended**: After every 2-3 local commits
+- **Maximum**: After every local commit (if working solo)
+
+### Remote Repository Setup
+
+**If no remote repository is configured:**
+
+#### Option 1: GitHub (Recommended)
+
+1. **Create repository on GitHub:**
+   - Go to https://github.com/new
+   - Create a new repository
+   - **DO NOT** initialize with README, .gitignore, or license (if you already have local repo)
+
+2. **Add remote and push:**
+   ```bash
+   # Add remote (replace with your repository URL)
+   git remote add origin https://github.com/username/repo-name.git
+   
+   # Or using SSH
+   git remote add origin git@github.com:username/repo-name.git
+   
+   # Push to remote
+   git push -u origin main
+   # Or 'master' if that's your default branch
+   ```
+
+3. **Verify:**
+   ```bash
+   git remote -v
+   git push
+   ```
+
+**GitHub Setup Guide:**
+- **Official Guide**: https://docs.github.com/en/get-started/quickstart/create-a-repo
+- **Adding Remote**: https://docs.github.com/en/get-started/getting-started-with-git/managing-remote-repositories
+
+#### Option 2: GitLab
+
+1. **Create repository on GitLab:**
+   - Go to https://gitlab.com/projects/new
+   - Create a new project
+   - **DO NOT** initialize with README (if you already have local repo)
+
+2. **Add remote and push:**
+   ```bash
+   git remote add origin https://gitlab.com/username/repo-name.git
+   git push -u origin main
+   ```
+
+**GitLab Setup Guide:**
+- **Official Guide**: https://docs.gitlab.com/ee/gitlab-basics/create-project.html
+
+#### Option 3: Bitbucket
+
+1. **Create repository on Bitbucket:**
+   - Go to https://bitbucket.org/repo/create
+   - Create a new repository
+
+2. **Add remote and push:**
+   ```bash
+   git remote add origin https://bitbucket.org/username/repo-name.git
+   git push -u origin main
+   ```
+
+**Bitbucket Setup Guide:**
+- **Official Guide**: https://support.atlassian.com/bitbucket-cloud/docs/create-a-git-repository/
+
+#### Option 4: Self-Hosted Git Server
+
+**If using self-hosted Git server:**
+```bash
+# Add remote
+git remote add origin <your-git-server-url>
+
+# Push
+git push -u origin main
+```
+
+### Verify Remote is Working
+
+**After setting up remote:**
+```bash
+# Check remote configuration
+git remote -v
+
+# Test push
+git push origin main
+
+# If successful, you'll see:
+# "Enumerating objects: X, done."
+# "Writing objects: 100% (X/X), done."
+```
+
+### Troubleshooting Remote Issues
+
+**Error: "remote origin already exists"**
+```bash
+# Remove existing remote
+git remote remove origin
+
+# Add new remote
+git remote add origin <new-url>
+```
+
+**Error: "authentication failed"**
+- Check your credentials
+- Use SSH keys for better security
+- See: https://docs.github.com/en/authentication/connecting-to-github-with-ssh
+
+**Error: "repository not found"**
+- Verify repository URL is correct
+- Check you have access to the repository
+- Ensure repository exists on remote server
+
+### Best Practices for Remote Sync
+
+**DO's ✅:**
+- ✅ Push to remote after completing tasks
+- ✅ Push before switching branches
+- ✅ Push before trying risky changes
+- ✅ Push at end of work session
+- ✅ Use descriptive commit messages
+- ✅ Keep commits atomic (one logical change per commit)
+
+**DON'Ts ❌:**
+- ❌ Don't push broken code (test first)
+- ❌ Don't push sensitive information (API keys, passwords)
+- ❌ Don't force push to shared branches
+- ❌ Don't skip pushing for extended periods
+- ❌ Don't commit without meaningful messages
+
+### Automated Backup Reminder
+
+**Set up reminders to push regularly:**
+```bash
+# Add to your shell profile (.bashrc, .zshrc, etc.)
+alias git-backup='git add . && git commit -m "backup: $(date +%Y-%m-%d\ %H:%M:%S)" && git push'
+
+# Use: git-backup (quick backup and push)
+```
+
+### Summary: Backup and Remote Sync Workflow
+
+**Complete workflow:**
+1. **Work locally** - Make changes
+2. **Test changes** - Ensure they work
+3. **Commit locally** - `git commit` (backup)
+4. **Update tasks.md** - Mark progress
+5. **Push to remote** - `git push` (if remote configured)
+6. **Continue work** - Next task
+
+**If no remote:**
+1. **Set up remote** - Follow instructions above
+2. **Push initial code** - `git push -u origin main`
+3. **Continue regular pushes** - After each commit or task
+
+### Priority Order: Most Critical First
+
+**ALWAYS follow this priority order when continuing implementation:**
+
+1. **Tests** (HIGHEST PRIORITY)
+   - Write tests for the feature
+   - Ensure all tests pass
+   - Verify test coverage meets thresholds
+
+2. **Coverage Verification** (CRITICAL)
+   - Run coverage check: `npm test -- --coverage`
+   - Fix any coverage gaps
+   - Ensure coverage thresholds are met
+
+3. **Update Task Status** (MANDATORY)
+   - Mark completed items as `[x]` in `tasks.md`
+   - Update task status if needed
+   - Document what was completed
+
+4. **Next Task** (Only after above steps)
+   - Move to next most critical task
+   - Follow same sequence
+
+**Example Priority Order:**
+
+```markdown
+## Priority Order (Most Critical First)
+
+### 1. Testing (CRITICAL - Do First)
+- [ ] 1.1 Write unit tests for core functionality
+- [ ] 1.2 Write integration tests
+- [ ] 1.3 Verify test coverage ≥ 95%
+
+### 2. Coverage Verification (CRITICAL - Do Second)
+- [ ] 2.1 Run coverage check
+- [ ] 2.2 Fix coverage gaps
+- [ ] 2.3 Verify thresholds met
+
+### 3. Task Status Update (MANDATORY - Do Third)
+- [ ] 3.1 Update tasks.md with completed items
+- [ ] 3.2 Update task status
+- [ ] 3.3 Document completion
+
+### 4. Next Implementation (Only After Above)
+- [ ] 4.1 Move to next critical task
+- [ ] 4.2 Follow same sequence
+```
+
+### Never Skip Steps
+
+**CRITICAL RULES:**
+- ❌ NEVER proceed to next task without updating current task status
+- ❌ NEVER skip test coverage verification
+- ❌ NEVER mark tasks complete without tests passing
+- ❌ NEVER implement without creating task first
+- ✅ ALWAYS update task status before moving to next task
+- ✅ ALWAYS verify coverage before marking task complete
+- ✅ ALWAYS follow priority order (most critical first)
+
+### Task Status Tracking
+
+**Track progress in `tasks.md`:**
+
+```markdown
+## Progress Summary
+- Total tasks: 15
+- Completed: 8
+- In progress: 2
+- Pending: 5
+- Blocked: 0
+
+## Current Status
+- ✅ Implementation Phase: 80% complete (4/5 tasks)
+- ⏳ Testing Phase: 50% complete (2/4 tasks)
+- ⏸️ Documentation Phase: 0% complete (0/3 tasks)
+```
+
+### Validation Before Committing
+
+**BEFORE every commit, verify:**
+- [ ] All completed tasks are marked as `[x]` in `tasks.md`
+- [ ] Task status reflects current progress
+- [ ] No tasks are marked complete without implementation
+- [ ] All tests pass for completed tasks
+- [ ] Test coverage meets thresholds (run `npm test -- --coverage`)
+- [ ] Task status updated before moving to next task
+- [ ] Documentation is updated for completed features
+
+### Task Status Update Before Next Task
+
+**CRITICAL RULE**: You MUST update task status in `tasks.md` BEFORE moving to the next task.
+
+**Why:**
+- Prevents loss of progress tracking
+- Ensures context is preserved
+- Makes it easy to resume work
+- Provides clear progress visibility
+
+**Workflow:**
+```bash
+# 1. Complete current task item
+# ... implementation ...
+
+# 2. Test and verify coverage
+npm test
+npm test -- --coverage
+
+# 3. Update tasks.md IMMEDIATELY
+# Mark as [x] and add status comment
+
+# 4. Verify update
+rulebook task show <task-id>
+# Confirm status is updated
+
+# 5. ONLY THEN proceed to next task
+# Follow priority order (most critical first)
+```
+
+**Example:**
+```markdown
+## 1. Implementation Phase
+- [x] 1.1 Create task manager module <!-- tested, coverage: 95% -->
+- [x] 1.2 Add validation logic <!-- tested, coverage: 92%, status: complete -->
+- [ ] 1.3 Add archive functionality <!-- next: will start after status update -->
+```
+
+## Task Archiving Workflow
+
+**CRITICAL**: Archive tasks ONLY after full completion and validation.
+
+### When to Archive
+
+**Archive a task when:**
+- ✅ All items in `tasks.md` are marked as `[x]`
+- ✅ All tests pass (unit, integration, E2E)
+- ✅ Code review is complete (if applicable)
+- ✅ Documentation is updated (README, CHANGELOG, specs)
+- ✅ Task format is validated (`rulebook task validate <task-id>`)
+- ✅ Spec deltas have been applied to main specifications
+
+**NEVER archive a task that is:**
+- ❌ Partially complete
+- ❌ Missing tests
+- ❌ Failing validation
+- ❌ Missing documentation
+
+### Archive Process
+
+**Step-by-step archive workflow:**
+
+```bash
+# 1. Verify all tasks are complete
+rulebook task show <task-id>
+# Check that all items in tasks.md are [x]
+
+# 2. Run all quality checks
+npm test
+npm run lint
+npm run type-check
+npm run build
+
+# 3. Validate task format
+rulebook task validate <task-id>
+
+# 4. Update final documentation
+# - Update CHANGELOG.md
+# - Update README.md if needed
+# - Update any affected documentation
+
+# 5. Archive the task
+rulebook task archive <task-id>
+
+# 6. Verify archive
+rulebook task list --archived
+# Task should appear in archived list
+```
+
+### Post-Archive Actions
+
+**After archiving, ensure:**
+- ✅ Spec deltas are applied to main specifications
+- ✅ CHANGELOG.md is updated with the change
+- ✅ Any breaking changes are documented
+- ✅ Migration guides are created (if needed)
+- ✅ Related tasks are unblocked (if any)
+
+### Archive Location
+
+**Archived tasks are moved to:**
+```
+/.rulebook/tasks/archive/YYYY-MM-DD-<task-id>/
+```
+
+**Structure:**
+```
+/.rulebook/tasks/archive/2025-11-13-add-auth/
+├── proposal.md
+├── tasks.md          # All items marked [x]
+├── design.md
+└── specs/
+    └── core/
+        └── spec.md
+```
+
+## Task Creation Best Practices
+
+### Task ID Naming
+
+**Use verb-led kebab-case:**
+- ✅ `add-user-authentication`
+- ✅ `refactor-task-manager`
+- ✅ `update-api-validation`
+- ✅ `remove-legacy-code`
+- ❌ `user-auth` (not descriptive)
+- ❌ `task_manager` (use kebab-case)
+- ❌ `new-feature` (too generic)
+
+### Task Scope
+
+**One capability per task:**
+- ✅ Good: `add-email-notifications`
+- ❌ Bad: `add-email-notifications-and-sms-and-push` (too broad)
+
+**Break large tasks into smaller ones:**
+- ✅ `add-email-notifications`
+- ✅ `add-sms-notifications`
+- ✅ `add-push-notifications`
+
+### Task Checklist Structure
+
+**Organize tasks by phase:**
+
+```markdown
+## 1. Planning & Design
+- [ ] 1.1 Research existing solutions
+- [ ] 1.2 Design architecture
+- [ ] 1.3 Create technical spec
+
+## 2. Implementation
+- [ ] 2.1 Create core module
+- [ ] 2.2 Add validation logic
+- [ ] 2.3 Integrate with existing system
+
+## 3. Testing
+- [ ] 3.1 Write unit tests
+- [ ] 3.2 Write integration tests
+- [ ] 3.3 Test edge cases
+
+## 4. Documentation
+- [ ] 4.1 Update README
+- [ ] 4.2 Update CHANGELOG
+- [ ] 4.3 Add code comments
+
+## 5. Cleanup
+- [ ] 5.1 Remove debug code
+- [ ] 5.2 Remove unused imports
+- [ ] 5.3 Final code review
+```
+
+## Continuous Task Updates
+
+**CRITICAL**: Update `tasks.md` continuously, not just at the end.
+
+### Real-Time Updates
+
+**Update as you work:**
+1. **Start task**: Mark as `[ ]` (if not already)
+2. **Begin implementation**: Add comment `<!-- in progress -->`
+3. **Complete implementation**: Mark as `[x]`
+4. **Test passes**: Add comment `<!-- tested -->`
+5. **Ready for review**: Add comment `<!-- ready for review -->`
+
+**Example:**
+```markdown
+## 1. Implementation
+- [x] 1.1 Create task manager module <!-- tested -->
+- [x] 1.2 Add validation logic <!-- tested, ready for review -->
+- [ ] 1.3 Add archive functionality <!-- in progress -->
+```
+
+### Progress Tracking
+
+**Add progress indicators:**
+```markdown
+## Progress: 60% (9/15 tasks complete)
+
+## 1. Implementation Phase: 100% ✅
+- [x] 1.1 Task 1
+- [x] 1.2 Task 2
+- [x] 1.3 Task 3
+
+## 2. Testing Phase: 50% ⏳
+- [x] 2.1 Unit tests
+- [x] 2.2 Integration tests
+- [ ] 2.3 E2E tests
+
+## 3. Documentation Phase: 0% ⏸️
+- [ ] 3.1 README
+- [ ] 3.2 CHANGELOG
+- [ ] 3.3 API docs
+```
+
+## Task Validation Before Archive
+
+**MANDATORY checks before archiving:**
+
+```bash
+# 1. Format validation
+rulebook task validate <task-id>
+# Must pass all format checks
+
+# 2. Completion check
+# All items in tasks.md must be [x]
+
+# 3. Test coverage
+npm test -- --coverage
+# Must meet coverage thresholds
+
+# 4. Code quality
+npm run lint
+npm run type-check
+# Must pass all checks
+
+# 5. Build verification
+npm run build
+# Must build successfully
+```
+
+## Summary: Task Lifecycle
+
+**Complete task lifecycle:**
+
+1. **Create** (MANDATORY FIRST STEP): `rulebook task create <task-id>`
+   - ⚠️ NEVER start implementation without creating task first
+   - ⚠️ Tasks without registration can be lost in context
+
+2. **Plan**: Write proposal.md and tasks.md
+   - Define why, what, and how
+   - Create implementation checklist
+
+3. **Design**: Write design.md (if needed)
+   - Technical decisions
+   - Architecture choices
+
+4. **Spec**: Write spec deltas in specs/
+   - OpenSpec-compatible format
+   - Requirements with SHALL/MUST
+
+5. **Validate**: `rulebook task validate <task-id>`
+   - Format validation
+   - Structure verification
+
+6. **Implement**: Write code, following priority order
+   - Most critical tasks first
+   - Update tasks.md as you go
+
+7. **Test** (HIGHEST PRIORITY): Write tests, verify coverage
+   - All tests must pass
+   - Coverage must meet thresholds
+   - Mark tested items in tasks.md
+
+8. **Update Status** (MANDATORY): Update task status before next task
+   - Mark completed items as `[x]`
+   - Update status in tasks.md
+   - Verify status update
+
+9. **Document**: Update docs, mark in tasks.md
+   - README, CHANGELOG, specs
+
+10. **Validate**: Final validation before archive
+    - All checks pass
+    - Coverage verified
+
+11. **Archive**: `rulebook task archive <task-id>`
+    - Move to archive
+    - Apply spec deltas
+
+**CRITICAL REMINDERS:**
+- ⚠️ **ALWAYS create task BEFORE implementation** - without registration, tasks can be lost
+- ⚠️ **ALWAYS follow priority order** - most critical first (tests, coverage, status update)
+- ⚠️ **ALWAYS update task status before next task** - prevents context loss
+- ⚠️ **ALWAYS verify coverage** - run `npm test -- --coverage` before marking complete
+- ⚠️ **ALWAYS commit locally frequently** - even for backup, prevents work loss
+- ⚠️ **ALWAYS keep remote repository updated** - push regularly if remote is configured
+- ⚠️ **ALWAYS update `tasks.md` at EVERY step**, not just at the end!
+
+## Best Practices
+
+### DO's ✅
+
+- **ALWAYS** create task BEFORE implementing any feature
+- **ALWAYS** check Context7 MCP before creating tasks
+- **ALWAYS** validate task format before committing
+- **ALWAYS** use SHALL/MUST in requirements
+- **ALWAYS** use 4 hashtags for scenarios
+- **ALWAYS** use Given/When/Then structure
+- **ALWAYS** follow priority order (most critical first)
+- **ALWAYS** write tests first (highest priority)
+- **ALWAYS** verify test coverage before marking complete
+- **ALWAYS** commit locally frequently (even for backup)
+- **ALWAYS** keep remote repository updated (push regularly)
+- **ALWAYS** update task status before moving to next task
+- **ALWAYS** update task status during implementation
+- **ALWAYS** archive completed tasks
+- **ALWAYS** document breaking changes in proposal
+
+### DON'Ts ❌
+
+- **NEVER** start implementation without creating task first
+- **NEVER** skip task registration (tasks can be lost in context)
+- **NEVER** proceed to next task without updating current task status
+- **NEVER** skip test coverage verification
+- **NEVER** mark tasks complete without tests passing
+- **NEVER** skip local commits (commit frequently for backup)
+- **NEVER** let remote repository get out of sync (push regularly)
+- **NEVER** commit sensitive information (API keys, passwords)
+- **NEVER** force push to shared branches
+- **NEVER** create tasks without checking Context7 format
+- **NEVER** use 3 hashtags for scenarios
+- **NEVER** omit SHALL/MUST from requirements
+- **NEVER** use bullet points for scenarios
+- **NEVER** skip validation
+- **NEVER** leave tasks unarchived after completion
+- **NEVER** mix formats (stick to OpenSpec-compatible format)
+- **NEVER** ignore priority order (always do most critical first)
+
+## CLI Commands Reference
+
+### Task Management Commands
+
+#### `rulebook task create <task-id>`
+
+Create a new Rulebook task with OpenSpec-compatible format.
+
+**Usage:**
+```bash
+rulebook task create add-user-authentication
+```
+
+**What it does:**
+- Creates `/.rulebook/tasks/<task-id>/` directory
+- Generates `proposal.md` template
+- Generates `tasks.md` template
+- Creates `specs/` directory for spec deltas
+
+**Requirements:**
+- Task ID must be unique (verb-led kebab-case)
+- Context7 MCP must be available (for format validation)
+
+**Example:**
+```bash
+$ rulebook task create add-email-notifications
+✅ Task add-email-notifications created successfully
+Location: .rulebook/tasks/add-email-notifications/
+
+⚠️  Remember to:
+  1. Check Context7 MCP for OpenSpec format requirements
+  2. Fill in proposal.md (minimum 20 characters in "Why" section)
+  3. Add tasks to tasks.md
+  4. Create spec deltas in specs/*/spec.md
+  5. Validate with: rulebook task validate add-email-notifications
+```
+
+**Error Handling:**
+- `Task <task-id> already exists`: Choose a different task ID or archive existing task
+
+---
+
+#### `rulebook task list [--archived]`
+
+List all Rulebook tasks (active and optionally archived).
+
+**Usage:**
+```bash
+# List active tasks only
+rulebook task list
+
+# List including archived tasks
+rulebook task list --archived
+```
+
+**Output:**
+- Active tasks with status (pending, in-progress, completed, blocked)
+- Archived tasks with archive date (if --archived flag is used)
+
+**Example:**
+```bash
+$ rulebook task list
+
+📋 Rulebook Tasks
+
+Active Tasks:
+  pending      add-user-authentication - Add user authentication feature
+  in-progress  refactor-api-validation - Refactor API validation logic
+  completed    update-documentation - Update project documentation
+
+$ rulebook task list --archived
+
+📋 Rulebook Tasks
+
+Active Tasks:
+  pending      add-user-authentication - Add user authentication feature
+
+Archived Tasks:
+  archived     2025-01-15-add-email-notifications - Add email notifications (2025-01-15)
+```
+
+**Task Status Values:**
+- `pending`: Task not started
+- `in-progress`: Task being worked on
+- `completed`: Task finished (ready for archive)
+- `blocked`: Task blocked by dependency
+
+---
+
+#### `rulebook task show <task-id>`
+
+Show detailed information about a specific task.
+
+**Usage:**
+```bash
+rulebook task show add-user-authentication
+```
+
+**Output:**
+- Task ID and title
+- Status (pending, in-progress, completed, blocked)
+- Created and updated dates
+- Archive date (if archived)
+- Proposal summary (first 500 characters)
+- Spec files list
+
+**Example:**
+```bash
+$ rulebook task show add-user-authentication
+
+📋 Task: add-user-authentication
+
+Title: add-user-authentication
+Status: pending
+Created: 2025-01-15T10:30:00.000Z
+Updated: 2025-01-15T10:30:00.000Z
+
+Proposal:
+# Proposal: Add User Authentication
+
+## Why
+We need to implement secure user authentication to protect user accounts and enable personalized features. This will include JWT token-based authentication with refresh tokens and password hashing using bcrypt...
+
+Specs:
+  core/spec.md (1234 chars)
+```
+
+**Error Handling:**
+- `Task <task-id> not found`: Verify task ID exists with `rulebook task list`
+
+---
+
+#### `rulebook task validate <task-id>`
+
+Validate task format against OpenSpec-compatible requirements.
+
+**Usage:**
+```bash
+rulebook task validate add-user-authentication
+```
+
+**Validation Checks:**
+- Purpose section length (≥20 characters)
+- Requirement keywords (SHALL/MUST)
+- Scenario format (4 hashtags, not 3)
+- Given/When/Then structure
+- Delta headers format (ADDED/MODIFIED/REMOVED/RENAMED)
+
+**Example:**
+```bash
+$ rulebook task validate add-user-authentication
+✅ Task add-user-authentication is valid
+
+⚠️  Warnings:
+  - Scenario in core/spec.md should use Given/When/Then structure
+```
+
+**Error Example:**
+```bash
+$ rulebook task validate invalid-task
+❌ Task invalid-task validation failed
+
+Errors:
+  - Scenarios in core/spec.md must use 4 hashtags (####), not 3 (###)
+  - Requirement in core/spec.md missing SHALL or MUST keyword: ### Requirement: Auth
+  - Purpose section (## Why) must have at least 20 characters
+```
+
+**Error Handling:**
+- Fix all errors before proceeding
+- Warnings are informational but don't block archiving
+
+---
+
+#### `rulebook task archive <task-id> [--skip-validation]`
+
+Archive a completed task and apply spec deltas to main specifications.
+
+**Usage:**
+```bash
+# Archive with validation (recommended)
+rulebook task archive add-user-authentication
+
+# Archive without validation (use with caution)
+rulebook task archive add-user-authentication --skip-validation
+```
+
+**Archive Process:**
+1. Validates task format (unless `--skip-validation` is used)
+2. Checks task completion status
+3. Applies spec deltas to main specifications
+4. Moves task to `/.rulebook/tasks/archive/YYYY-MM-DD-<task-id>/`
+5. Updates related specifications
+
+**Example:**
+```bash
+$ rulebook task archive add-user-authentication
+✅ Task add-user-authentication archived successfully
+```
+
+**Error Handling:**
+- `Task validation failed`: Fix validation errors before archiving
+- `Task <task-id> not found`: Verify task ID exists
+- `Archive <archive-name> already exists`: Archive with that date already exists
+
+**Important:**
+- Only archive tasks that are fully completed
+- All items in `tasks.md` should be marked as `[x]`
+- All tests should pass
+- Documentation should be updated
+
+---
+
+### Core Rulebook Commands
+
+#### `rulebook init [--minimal] [--light] [--yes]`
+
+Initialize Rulebook for current project.
+
+**Usage:**
+```bash
+# Interactive mode
+rulebook init
+
+# Minimal setup (essentials only)
+rulebook init --minimal
+
+# Light mode (no quality enforcement)
+rulebook init --light
+
+# Skip prompts, use defaults
+rulebook init --yes
+```
+
+**What it does:**
+- Detects languages, frameworks, and MCP modules
+- Generates AGENTS.md with AI assistant rules
+- Creates `/rulebook/` directory with templates
+- Creates/updates `.gitignore` automatically
+- Optionally installs Git hooks
+- Generates Cursor commands (if Cursor is selected IDE)
+
+---
+
+#### `rulebook update [--yes] [--minimal] [--light]`
+
+Update AGENTS.md and .rulebook to latest version.
+
+**Usage:**
+```bash
+# Interactive mode
+rulebook update
+
+# Skip confirmation
+rulebook update --yes
+
+# Minimal mode
+rulebook update --minimal
+
+# Light mode
+rulebook update --light
+```
+
+**What it does:**
+- Migrates OpenSpec tasks to Rulebook format (if OpenSpec exists)
+- Migrates OpenSpec archives to Rulebook format
+- Removes OpenSpec commands from `.cursor/commands/`
+- Updates AGENTS.md with latest templates
+- Merges templates while preserving customizations
+- Updates Cursor commands (if Cursor is selected IDE)
+
+---
+
+#### `rulebook validate`
+
+Validate project structure against Rulebook standards.
+
+**Usage:**
+```bash
+rulebook validate
+```
+
+**Validation Checks:**
+- AGENTS.md presence and format
+- Rulebook directory structure
+- Documentation structure
+- Tests directory
+- Score calculation (0-100)
+
+---
+
+#### `rulebook health`
+
+Check project health score.
+
+**Usage:**
+```bash
+rulebook health
+```
+
+**Categories Scored:**
+- Quality (linting, formatting, code quality)
+- Testing (test coverage, test quality)
+- Security (vulnerabilities, secrets)
+- Documentation (README, docs/, comments)
+
+**Score Range:** 0-100
+
+---
+
+#### `rulebook workflows`
+
+Generate GitHub Actions workflows for detected languages.
+
+**Usage:**
+```bash
+rulebook workflows
+```
+
+**What it does:**
+- Creates `.github/workflows/` directory
+- Generates language-specific workflows (test, lint, publish)
+- Adds codespell workflow for spelling checks
+
+---
+
+#### `rulebook check-deps`
+
+Check for outdated and vulnerable dependencies.
+
+**Usage:**
+```bash
+rulebook check-deps
+```
+
+**Supported Package Managers:**
+- npm (package.json)
+- Cargo (Cargo.toml)
+- pip (requirements.txt, pyproject.toml)
+- Go modules (go.mod)
+
+---
+
+#### `rulebook check-coverage [-t <threshold>]`
+
+Check test coverage against threshold.
+
+**Usage:**
+```bash
+# Default threshold (95%)
+rulebook check-coverage
+
+# Custom threshold
+rulebook check-coverage -t 80
+```
+
+---
+
+#### `rulebook generate-docs [--yes]`
+
+Generate documentation structure and standard files.
+
+**Usage:**
+```bash
+# Interactive mode
+rulebook generate-docs
+
+# Skip prompts
+rulebook generate-docs --yes
+```
+
+---
+
+#### `rulebook version <major|minor|patch>`
+
+Bump project version (semantic versioning).
+
+**Usage:**
+```bash
+rulebook version major  # 1.0.0 -> 2.0.0
+rulebook version minor  # 1.0.0 -> 1.1.0
+rulebook version patch  # 1.0.0 -> 1.0.1
+```
+
+---
+
+#### `rulebook changelog [-v <version>]`
+
+Generate changelog from git commits.
+
+**Usage:**
+```bash
+# Auto-detect version
+rulebook changelog
+
+# Specify version
+rulebook changelog -v 1.0.0
+```
+
+---
+
+#### `rulebook fix`
+
+Auto-fix common project issues.
+
+**Usage:**
+```bash
+rulebook fix
+```
+
+---
+
+### Advanced Commands (Beta)
+
+#### `rulebook watcher`
+
+Start modern full-screen console watcher for task progress.
+
+**Usage:**
+```bash
+rulebook watcher
+```
+
+**Features:**
+- Live task progress tracking
+- Activity log with timestamps
+- System status monitoring
+- Auto-refresh every 2 seconds
+
+---
+
+#### `rulebook agent [--dry-run] [--tool <name>] [--iterations <n>] [--watch]`
+
+Start autonomous agent for managing AI CLI workflows.
+
+**Usage:**
+```bash
+# Dry run (simulate without changes)
+rulebook agent --dry-run
+
+# Specify CLI tool
+rulebook agent --tool cursor-agent
+
+# Set max iterations
+rulebook agent --iterations 10
+
+# Enable watcher mode
+rulebook agent --watch
+```
+
+---
+
+#### `rulebook config [--show] [--set <key=value>] [--feature <name> --enable|--disable]`
+
+Manage Rulebook configuration.
+
+**Usage:**
+```bash
+# Show current config
+rulebook config --show
+
+# Set config value
+rulebook config --set rulebookDir=custom-rulebook
+
+# Enable feature
+rulebook config --feature watcher --enable
+
+# Disable feature
+rulebook config --feature agent --disable
+```
+
+## Migration from OpenSpec
+
+If your project previously used OpenSpec:
+
+1. **Automatic Migration**: Run `rulebook update` to automatically migrate OpenSpec tasks to Rulebook format
+2. **Manual Migration**: Tasks in `/openspec/changes/` will be moved to `/.rulebook/tasks/`
+3. **Format Compatibility**: Rulebook uses OpenSpec-compatible format, so existing tasks remain valid
+
+## Context7 MCP Requirement
+
+**CRITICAL**: Context7 MCP is REQUIRED for task creation.
+
+**Why**: 
+- Ensures correct format by fetching official OpenSpec documentation
+- Prevents common format errors made by AI assistants
+- Provides up-to-date format requirements
+
+**If Context7 MCP is not available:**
+- Task creation will fail with clear error message
+- You must configure Context7 MCP before creating tasks
+- See `/rulebook/CONTEXT7.md` for setup instructions
+
+## Troubleshooting
+
+### Validation Errors
+
+**Error**: "Requirement must contain SHALL or MUST keyword"
+- **Fix**: Add SHALL or MUST to requirement text
+- **Example**: Change "The system provides authentication" to "The system SHALL provide authentication"
+
+**Error**: "Scenario must use 4 hashtags"
+- **Fix**: Change `### Scenario:` to `#### Scenario:` (at start of line)
+- **Note**: Validation only checks headers at start of line, not in text content
+
+**Error**: "Purpose section too short"
+- **Fix**: Expand "Why" section in proposal.md to at least 20 characters
+- **Example**: "Auth system" → "Authentication system for secure user access with JWT tokens and session management"
+
+**Error**: "Scenario must use Given/When/Then structure"
+- **Fix**: Replace bullet points with Given/When/Then format
+- **Example**: 
+  ```markdown
+  #### Scenario: User login
+  Given a user has valid credentials
+  When they submit the login form
+  Then they are authenticated successfully
+  ```
+
+### Task Creation Errors
+
+**Error**: "Context7 MCP not available"
+- **Fix**: Configure Context7 MCP in your MCP configuration file
+- **See**: `/rulebook/CONTEXT7.md` for setup instructions
+
+**Error**: "Task ID already exists"
+- **Fix**: Choose a different task ID or archive existing task
+- **Check**: Use `rulebook task list` to see existing tasks
+
+### Task Archive Errors
+
+**Error**: "Task validation failed"
+- **Fix**: Run `rulebook task validate <task-id>` to see all errors
+- **Fix**: Address all validation errors before archiving
+- **Option**: Use `--skip-validation` flag only if you're certain the task is valid
+
+**Error**: "Archive <archive-name> already exists"
+- **Fix**: Archive with that date already exists
+- **Check**: Use `rulebook task list --archived` to see archived tasks
+
+### Command Errors
+
+**Error**: "Task <task-id> not found"
+- **Fix**: Verify task ID exists with `rulebook task list`
+- **Check**: Ensure you're in the correct project directory
+
+**Error**: "No tasks found"
+- **Fix**: Create a task first with `rulebook task create <task-id>`
+- **Check**: Verify `/.rulebook/tasks/` directory exists
+
+### Migration Errors
+
+**Error**: "Failed to migrate task"
+- **Fix**: Check error message for specific issue
+- **Check**: Verify OpenSpec task structure is correct
+- **Fix**: Manually migrate if automatic migration fails
+
+**Error**: "Failed to read OpenSpec changes directory"
+- **Fix**: Verify `/openspec/changes/` directory exists
+- **Check**: Ensure you have read permissions
+
+## Examples
+
+See `/.rulebook/tasks/` directory for examples of correctly formatted tasks.
+
+<!-- RULEBOOK:END -->
+