anvil-dev-framework 0.1.6

package/docs/anvil-init.md

@@ -0,0 +1,255 @@
+# Anvil Init Command
+
+> Initialize Anvil Development Framework in any project directory.
+
+## Quick Start
+
+```bash
+# Initialize current directory with defaults
+anvil init
+
+# Initialize with all features
+anvil init --template nextjs --with-hooks --with-linear
+
+# Preview what would happen (dry run)
+anvil init --dry-run
+```
+
+## Installation
+
+### Adding Anvil to PATH
+
+Add this to your shell configuration (`~/.zshrc` or `~/.bashrc`):
+
+```bash
+export PATH="$HOME/Projects/anvil-dev-framework/scripts:$PATH"
+
+# Create alias for convenience
+alias anvil="init-project.sh"
+```
+
+Then reload your shell:
+```bash
+source ~/.zshrc  # or source ~/.bashrc
+```
+
+### Direct Script Usage
+
+Alternatively, run the script directly:
+
+```bash
+bash /path/to/anvil-dev-framework/scripts/init-project.sh [options]
+```
+
+## Command Reference
+
+```
+anvil init [directory] [options]
+```
+
+### Arguments
+
+| Argument | Description | Default |
+|----------|-------------|---------|
+| `directory` | Target directory to initialize | Current directory |
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--template <type>` | Use a project template: `generic`, `nextjs`, `python`, `saas` |
+| `--with-hooks` | Create symlinks to framework hooks and commands |
+| `--with-linear` | Enable Linear integration (prompts for setup) |
+| `--force` | Overwrite existing files (creates backups first) |
+| `--dry-run` | Show what would be done without making changes |
+| `--help` | Display help message |
+
+## Templates
+
+### Generic (Default)
+
+Basic template suitable for any project type.
+
+```bash
+anvil init --template generic
+```
+
+### Next.js
+
+Pre-configured for Next.js + TypeScript + Supabase + Tailwind CSS projects.
+
+```bash
+anvil init --template nextjs
+```
+
+### Python
+
+Pre-configured for Python + FastAPI + SQLAlchemy projects.
+
+```bash
+anvil init --template python
+```
+
+### SaaS
+
+Full SaaS application template (Next.js based).
+
+```bash
+anvil init --template saas
+```
+
+## Directory Structure
+
+After initialization, your project will have:
+
+```
+your-project/
+├── .claude/
+│   ├── CLAUDE.md           # Project-specific AI instructions
+│   ├── constitution.md     # Project principles
+│   ├── product.md          # Product definition
+│   ├── linear.yaml         # Linear team configuration
+│   ├── commands/           # Skill commands (copied or symlinked)
+│   ├── examples/           # Code convention examples
+│   ├── handoffs/           # Session continuity documents
+│   ├── hooks/              # Hook scripts (with --with-hooks)
+│   ├── lib/                # Library modules (with --with-hooks)
+│   └── specs/
+│       ├── current/        # Active specifications
+│       └── archive/        # Completed specifications
+├── .coderabbit.yaml        # CodeRabbit configuration
+├── .pre-commit-config.yaml # Pre-commit hooks
+└── .semgrep/
+    └── rules/              # Semgrep rules
+```
+
+## Examples
+
+### Basic Initialization
+
+Initialize current directory with defaults:
+
+```bash
+cd my-project
+anvil init
+```
+
+### New Project Setup
+
+Create and initialize a new directory:
+
+```bash
+mkdir my-app && cd my-app
+git init
+anvil init --template nextjs
+```
+
+### Full Setup with All Features
+
+```bash
+anvil init --template saas --with-hooks --with-linear
+```
+
+This will:
+1. Copy SaaS template files
+2. Create symlinks to framework hooks and commands
+3. Prompt you to run `/linear-setup` for Linear integration
+
+### Preview Changes (Dry Run)
+
+```bash
+anvil init --template python --with-hooks --dry-run
+```
+
+Output shows what would be created without making changes.
+
+### Force Overwrite with Backup
+
+```bash
+anvil init --force
+```
+
+Existing files are backed up to `.claude/.backup/<timestamp>/` before overwriting.
+
+## The --with-hooks Option
+
+The `--with-hooks` flag creates symlinks from your project to the central Anvil framework:
+
+### Symlinked Directories
+
+| Project Path | Links To |
+|--------------|----------|
+| `.claude/hooks/` | `global/hooks/` |
+| `.claude/commands/` | `global/commands/` |
+| `.claude/lib/` | `global/lib/` |
+
+### Benefits
+
+1. **Automatic Updates**: Changes to global hooks apply to all projects
+2. **Consistency**: Same commands available everywhere
+3. **Reduced Duplication**: No need to copy files to each project
+
+### When to Use
+
+- **With Hooks**: When you want the latest framework features
+- **Without Hooks**: When you need isolated, project-specific commands
+
+## The --with-linear Option
+
+Enables Linear integration for issue tracking:
+
+```bash
+anvil init --with-linear
+```
+
+After initialization, run `/linear-setup` in Claude Code to:
+1. Select your Linear team
+2. Configure team key mapping
+3. Enable workflow commands
+
+## Post-Initialization
+
+After running `anvil init`:
+
+1. **Edit `.claude/CLAUDE.md`**: Add project-specific details
+2. **Review `.claude/constitution.md`**: Adjust principles for your project
+3. **Fill out `.claude/product.md`**: Define your product
+4. **Run `/linear-setup`**: If you used `--with-linear`
+
+Then start using Anvil:
+
+```bash
+# Open Claude Code
+claude
+
+# Run orientation
+/orient
+```
+
+## Troubleshooting
+
+### Permission Denied
+
+Ensure the script is executable:
+```bash
+chmod +x /path/to/anvil-dev-framework/scripts/init-project.sh
+```
+
+### Pre-commit Not Found
+
+Install pre-commit if missing:
+```bash
+pip install pre-commit
+# or
+brew install pre-commit
+```
+
+### Symlinks Not Working on Windows
+
+Windows requires administrator privileges for symlinks. Consider using Git Bash with elevated permissions or WSL.
+
+## See Also
+
+- [Installation Guide](./INSTALLATION.md) - Complete Anvil setup
+- [Session Workflow](./session-workflow.md) - How to use Anvil in sessions
+- [Command Reference](./command-reference.md) - All available commands

package/docs/anvil-state.md

@@ -0,0 +1,210 @@
+# Anvil Session State System
+
+The Anvil session state system tracks workflow context across sessions using a local JSON file (`.claude/anvil-state.json`). This enables the statusline to display current phase, active issues, and other context without requiring API calls.
+
+## Overview
+
+The state file persists:
+- **Workflow phase** (orient, explore, spec, plan, tasks, implement, verify, handoff)
+- **Active spec/plan IDs** for current work
+- **Active Linear issue key** being worked on
+- **Last command executed** and timestamp
+- **Cached git information** with TTL for performance
+
+## State File Location
+
+```
+.claude/anvil-state.json
+```
+
+**Important**: Add this file to your `.gitignore` — it contains session-specific state that shouldn't be committed.
+
+## State File Schema
+
+```json
+{
+  "version": "1.0",
+  "session": {
+    "phase": "implement",
+    "activeSpec": "SPEC-ANV-22",
+    "activePlan": "PLAN-ANV-22",
+    "activeIssue": "ANV-42",
+    "lastCommand": "/plan",
+    "lastCommandAt": "2025-12-26T14:30:00Z"
+  },
+  "cache": {
+    "git": {
+      "branch": "feature/ANV-42",
+      "dirty": false,
+      "cachedAt": "2025-12-26T14:30:00Z",
+      "ttlSeconds": 5
+    }
+  },
+  "meta": {
+    "createdAt": "2025-12-26T14:00:00Z",
+    "updatedAt": "2025-12-26T14:30:00Z"
+  }
+}
+```
+
+## Using the State Library
+
+### Sourcing the Library
+
+```bash
+source "path/to/global/lib/anvil-state.sh"
+```
+
+### Basic Operations
+
+```bash
+# Initialize state file (creates if missing)
+anvil_state_init
+
+# Set workflow phase
+anvil_state_set_phase "implement"
+
+# Set active spec/plan/issue
+anvil_state_set_spec "SPEC-ANV-22"
+anvil_state_set_plan "PLAN-ANV-22"
+anvil_state_set_issue "ANV-42"
+
+# Record command execution
+anvil_state_set_command "/plan"
+
+# Get a specific field
+phase=$(anvil_state_get "session.phase")
+issue=$(anvil_state_get "session.activeIssue")
+
+# Update multiple fields at once
+anvil_state_update "implement" "SPEC-001" "PLAN-001" "ANV-42" "/tasks"
+```
+
+### Git Cache
+
+The library caches git information to avoid repeated git calls:
+
+```bash
+# Get branch (uses cache if valid, otherwise fetches fresh)
+branch=$(anvil_git_branch)
+
+# Force cache update
+anvil_git_cache_update
+
+# Check if cache is still valid
+if anvil_git_cache_valid; then
+    echo "Cache is fresh"
+fi
+```
+
+Default TTL is 5 seconds, configurable via `ANVIL_GIT_CACHE_TTL` environment variable.
+
+### Session Management
+
+```bash
+# Clear session state (useful for /orient reset)
+anvil_state_clear_session
+
+# Debug: print current state
+anvil_state_debug
+
+# Check if state file exists and is valid JSON
+if anvil_state_valid; then
+    echo "State is valid"
+fi
+
+# Repair corrupted state file
+anvil_state_repair
+```
+
+## Function Reference
+
+### Core Functions
+
+| Function | Description |
+|----------|-------------|
+| `anvil_check_jq` | Verify jq is installed, show install instructions if not |
+| `anvil_state_path` | Get state file path, create directory if needed |
+| `anvil_state_init` | Initialize state file with defaults |
+| `anvil_state_read` | Read entire state as JSON |
+| `anvil_state_get <field>` | Get specific field (dot notation) |
+| `anvil_state_set <field> <value>` | Set specific field |
+| `anvil_state_update <phase> <spec> <plan> <issue> <cmd>` | Update multiple fields |
+
+### Convenience Setters
+
+| Function | Description |
+|----------|-------------|
+| `anvil_state_set_phase <phase>` | Set workflow phase |
+| `anvil_state_set_spec <spec_id>` | Set active spec ID |
+| `anvil_state_set_plan <plan_id>` | Set active plan ID |
+| `anvil_state_set_issue <issue_key>` | Set active issue key |
+| `anvil_state_set_command <command>` | Record command with timestamp |
+| `anvil_state_clear_session` | Clear all session fields |
+
+### Git Cache Functions
+
+| Function | Description |
+|----------|-------------|
+| `anvil_git_branch` | Get branch (cached) |
+| `anvil_git_cache_update [branch]` | Update git cache |
+| `anvil_git_cache_valid` | Check if cache is within TTL |
+
+### Utility Functions
+
+| Function | Description |
+|----------|-------------|
+| `anvil_state_debug` | Pretty-print current state |
+| `anvil_state_valid` | Check if state file exists and is valid JSON |
+| `anvil_state_repair` | Backup corrupt file and recreate fresh |
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ANVIL_STATE_FILE` | `.claude/anvil-state.json` | State file path |
+| `ANVIL_GIT_CACHE_TTL` | `5` | Git cache TTL in seconds |
+| `ANVIL_STATE_VERSION` | `1.0` | State schema version |
+
+## Dependencies
+
+- **jq**: Required for JSON parsing
+  - macOS: `brew install jq`
+  - Ubuntu: `sudo apt-get install jq`
+  - Fedora: `sudo dnf install jq`
+
+## Integration with Commands
+
+Anvil workflow commands update the state file automatically:
+
+| Command | Phase Set | Additional State |
+|---------|-----------|------------------|
+| `/orient` | `orient` | Clears activeSpec, activePlan |
+| `/explore` | `explore` | — |
+| `/spec` | `spec` | Sets activeSpec |
+| `/plan` | `plan` | Sets activePlan |
+| `/tasks` | `tasks` | — |
+| `/evidence` | `verify` | — |
+| `/handoff` | `handoff` | — |
+
+## Troubleshooting
+
+### State file not updating
+1. Check jq is installed: `which jq`
+2. Check file permissions on `.claude/` directory
+3. Run `anvil_state_debug` to see current state
+
+### Corrupted state file
+```bash
+source global/lib/anvil-state.sh
+anvil_state_repair
+```
+
+### Performance issues
+- Increase `ANVIL_GIT_CACHE_TTL` if git operations are slow
+- State operations should complete in <10ms
+
+## Related Documentation
+
+- [SPEC-ANV-22: Statusline & Session State System](/.claude/specs/current/SPEC-ANV-22-statusline-session-state.md)
+- [Statusline Configuration](./statusline.md) (coming soon)