anvil-dev-framework 0.1.6

package/docs/local-issues.md

@@ -0,0 +1,677 @@
+# Local Issue Tracking
+
+> File-based issue tracking for projects without Linear integration.
+
+---
+
+## Overview
+
+The Anvil Framework includes a complete local issue tracking system that works without any external dependencies. This allows you to use all Anvil workflow commands (`/orient`, `/ready`, `/sprint`, `/tasks`) even if you don't use Linear.
+
+**Key Features:**
+- File-based JSON storage in `~/.anvil/issues/`
+- Full CLI for creating, updating, and managing issues
+- Same workflow patterns as Linear integration
+- Agent assignment for multi-agent coordination
+- Priority and status management
+- Statistics and ready-work calculation
+
+---
+
+## Quick Start
+
+### Create Your First Issue
+
+```bash
+# Create a simple issue
+anvil-issue create --title "Implement user authentication"
+
+# Create with priority and labels
+anvil-issue create --title "Fix login bug" --priority high --labels "bug,auth"
+
+# Create a sub-issue
+anvil-issue create --title "Phase 1: Database setup" --parent LOCAL-001
+```
+
+### View Issues
+
+```bash
+# List all issues
+anvil-issue list
+
+# Filter by status
+anvil-issue list --status todo
+anvil-issue list --status in-progress
+
+# Show issue details
+anvil-issue show LOCAL-001
+
+# Show ready work (prioritized)
+anvil-issue ready
+```
+
+### Update Issues
+
+```bash
+# Change status
+anvil-issue move LOCAL-001 --to in-progress
+anvil-issue move LOCAL-001 --to done
+
+# Update details
+anvil-issue update LOCAL-001 --title "New title" --priority urgent
+
+# Assign to agent
+anvil-issue assign LOCAL-001 --agent swift-falcon-a3f2
+```
+
+---
+
+## CLI Reference
+
+### Commands Overview
+
+| Command | Description |
+|---------|-------------|
+| `list` | List issues (optionally filtered by status) |
+| `create` | Create a new issue |
+| `show` | Show issue details |
+| `update` | Update an existing issue |
+| `move` | Change issue status |
+| `assign` | Assign issue to an agent |
+| `stats` | Show issue statistics |
+| `ready` | Show issues ready to work on |
+| `delete` | Delete an issue |
+
+### list
+
+List issues with optional filtering.
+
+```bash
+anvil-issue list [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--status`, `-s` | Filter by status (backlog, todo, in-progress, in-review, done, cancelled) |
+| `--limit`, `-n` | Maximum issues to show (default: 50) |
+
+**Examples:**
+```bash
+anvil-issue list
+anvil-issue list --status todo
+anvil-issue list --status in-progress --limit 10
+```
+
+### create
+
+Create a new issue.
+
+```bash
+anvil-issue create --title "TITLE" [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--title`, `-t` | Issue title (required) |
+| `--description`, `-d` | Issue description |
+| `--priority`, `-p` | Priority: urgent/p0, high/p1, medium/p2, low/p3, none/p4 |
+| `--labels`, `-l` | Comma-separated labels |
+| `--parent` | Parent issue identifier (creates sub-issue) |
+
+**Examples:**
+```bash
+anvil-issue create --title "Add dark mode"
+anvil-issue create --title "Critical bug" --priority urgent --labels "bug,critical"
+anvil-issue create --title "Phase 1: Setup" --parent LOCAL-001
+```
+
+### show
+
+Show detailed issue information.
+
+```bash
+anvil-issue show IDENTIFIER
+```
+
+**Example:**
+```bash
+anvil-issue show LOCAL-001
+```
+
+**Output:**
+```
+LOCAL-001: Implement user authentication
+--------------------------------------------------
+Status:    In Progress
+Priority:  P1 (High)
+
+Description:
+Add OAuth2 authentication with Google and GitHub providers.
+
+Labels: feature, auth
+Assigned: swift-falcon-a3f2
+Parent: LOCAL-000
+
+Created:  2026-01-04 09:30
+Updated:  2026-01-04 10:15
+```
+
+### update
+
+Update an existing issue.
+
+```bash
+anvil-issue update IDENTIFIER [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--title`, `-t` | New title |
+| `--description`, `-d` | New description |
+| `--priority`, `-p` | New priority |
+| `--labels`, `-l` | New labels (comma-separated) |
+
+**Example:**
+```bash
+anvil-issue update LOCAL-001 --title "Updated title" --priority high
+```
+
+### move
+
+Change issue status.
+
+```bash
+anvil-issue move IDENTIFIER --to STATUS
+```
+
+| Status | Description |
+|--------|-------------|
+| `backlog` | Not yet prioritized |
+| `todo` | Ready to start |
+| `in-progress` | Currently being worked on |
+| `in-review` | PR created, awaiting review |
+| `done` | Completed |
+| `cancelled` | No longer needed |
+
+**Examples:**
+```bash
+anvil-issue move LOCAL-001 --to in-progress
+anvil-issue move LOCAL-001 --to done
+```
+
+### assign
+
+Assign or unassign an agent.
+
+```bash
+anvil-issue assign IDENTIFIER [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--agent`, `-a` | Agent ID to assign |
+| `--unassign`, `-u` | Remove assignment |
+
+**Examples:**
+```bash
+anvil-issue assign LOCAL-001 --agent swift-falcon-a3f2
+anvil-issue assign LOCAL-001 --unassign
+```
+
+### stats
+
+Show issue statistics.
+
+```bash
+anvil-issue stats
+```
+
+**Output:**
+```
+=== Issue Statistics ===
+
+Total Issues: 15
+Assigned:     3
+Unassigned:   12
+
+--- By Status ---
+  Backlog         5
+  Todo            4
+  In Progress     2
+  In Review       1
+  Done            3
+
+--- By Priority ---
+  P0              1
+  P1              3
+  P2              8
+  P3              3
+```
+
+### ready
+
+Show issues ready to work on, sorted by priority.
+
+```bash
+anvil-issue ready [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--limit`, `-n` | Maximum issues (default: 10) |
+
+**Example:**
+```bash
+anvil-issue ready --limit 5
+```
+
+### delete
+
+Delete an issue.
+
+```bash
+anvil-issue delete IDENTIFIER [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--hard` | Permanently delete (default: soft delete/cancel) |
+
+**Examples:**
+```bash
+anvil-issue delete LOCAL-001           # Marks as cancelled
+anvil-issue delete LOCAL-001 --hard    # Permanently removes
+```
+
+---
+
+## Status Workflow
+
+Issues follow a standard workflow:
+
+```
+┌─────────┐
+│ Backlog │  Not yet prioritized
+└────┬────┘
+     │
+┌────▼────┐
+│  Todo   │  Ready to start
+└────┬────┘
+     │
+┌────▼─────────┐
+│ In Progress  │  Being worked on
+└────┬─────────┘
+     │
+┌────▼────────┐
+│  In Review  │  PR awaiting review
+└────┬────────┘
+     │
+┌────▼────┐
+│  Done   │  Completed
+└─────────┘
+```
+
+Use `anvil-issue move` to transition between states.
+
+---
+
+## Priority Levels
+
+| Priority | Code | Description |
+|----------|------|-------------|
+| Urgent | P0 | Drop everything, fix now |
+| High | P1 | Next up after current task |
+| Medium | P2 | This sprint (default) |
+| Low | P3 | Backlog |
+| None | P4 | No priority set |
+
+The `ready` command sorts by priority (P0 first) then by age (oldest first).
+
+---
+
+## Storage Structure
+
+Issues are stored in `~/.anvil/issues/`:
+
+```
+~/.anvil/issues/
+└── index.json     # All issues with metadata
+```
+
+The index file contains:
+- Version marker
+- Identifier prefix (default: "LOCAL")
+- Next ID counter
+- All issues as JSON objects
+
+**Example index.json:**
+```json
+{
+  "version": "1.0",
+  "prefix": "LOCAL",
+  "next_id": 5,
+  "issues": {
+    "LOCAL-001": {
+      "id": "uuid-here",
+      "title": "Implement auth",
+      "status": "in_progress",
+      "priority": 1,
+      "labels": ["feature"],
+      "assigned_agent": "swift-falcon",
+      "created_at": "2026-01-04T09:30:00Z",
+      "updated_at": "2026-01-04T10:15:00Z"
+    }
+  }
+}
+```
+
+---
+
+## Integration with Anvil Commands
+
+### /orient
+
+When no Linear configuration exists (`.claude/linear.yaml`), `/orient` automatically uses the local provider:
+
+```markdown
+## Session Orientation
+
+**Issue Provider**: local
+
+**Ready Work** (top 5):
+1. LOCAL-001: Fix auth bug (P0)
+2. LOCAL-003: Add logging (P1)
+...
+```
+
+### /ready
+
+Calculates ready work from local issues:
+
+```bash
+/ready
+```
+
+Shows issues in Todo status, sorted by priority and age.
+
+### /sprint
+
+Works identically with local issues, showing state summary and suggesting focus items.
+
+### /tasks
+
+When creating tasks from a plan, issues are created locally:
+
+```bash
+/tasks
+# Creates LOCAL-XXX issues for each phase
+```
+
+### /discover
+
+Files discovered work as local issues:
+
+```bash
+/discover "Found missing error handling"
+# Creates LOCAL-XXX with 'discovered' label
+```
+
+---
+
+## Multi-Agent Coordination
+
+### Agent Assignment
+
+Assign issues to prevent conflicts:
+
+```bash
+# Agent claims an issue
+anvil-issue assign LOCAL-001 --agent swift-falcon-a3f2
+
+# View agent's issues
+anvil-issue list | grep "swift-falcon"
+```
+
+### HUD Integration
+
+The HUD Kanban panel displays local issues:
+
+```bash
+uv run global/tools/anvil-hud.py
+```
+
+The Kanban shows:
+- TODO column: Issues in `todo` status
+- IN PROGRESS: Issues in `in_progress` or `in_review`
+- DONE: Completed issues
+
+---
+
+## Provider Detection
+
+Anvil automatically detects which provider to use:
+
+1. **If `.claude/linear.yaml` exists** → Uses Linear
+2. **Otherwise** → Uses local JSON storage
+
+You can check the active provider:
+
+```python
+from issue_provider import get_provider_name
+
+provider = get_provider_name()
+# Returns "linear:ANV" or "local"
+```
+
+---
+
+## Python API
+
+For programmatic access:
+
+```python
+from local_provider import LocalJsonProvider
+from issue_models import Issue, IssueStatus, Priority
+
+# Initialize provider
+provider = LocalJsonProvider()
+
+# Create issue
+issue = provider.create_issue(
+    title="New feature",
+    description="Details here",
+    priority=Priority.HIGH,
+    labels=["feature"]
+)
+
+# List issues
+todos = provider.list_issues(status=IssueStatus.TODO)
+
+# Update issue
+provider.update_issue(
+    identifier="LOCAL-001",
+    status=IssueStatus.IN_PROGRESS
+)
+
+# Assign to agent
+provider.assign_to_agent("LOCAL-001", "agent-id")
+
+# Get ready work
+ready = provider.get_ready_issues()
+
+# Get statistics
+stats = provider.get_statistics()
+```
+
+### Issue Model
+
+```python
+@dataclass
+class Issue:
+    id: str                    # Internal UUID
+    identifier: str            # Human-readable (LOCAL-001)
+    title: str
+    description: str = ""
+    status: IssueStatus = IssueStatus.TODO
+    priority: Priority = Priority.MEDIUM
+    parent_id: Optional[str] = None
+    labels: list[str] = []
+    assigned_agent: Optional[str] = None
+    created_at: datetime
+    updated_at: datetime
+    completed_at: Optional[datetime] = None
+    estimate: Optional[str] = None
+    provider: str = "local"
+```
+
+### Status Enum
+
+```python
+class IssueStatus(Enum):
+    BACKLOG = "backlog"
+    TODO = "todo"
+    IN_PROGRESS = "in_progress"
+    IN_REVIEW = "in_review"
+    DONE = "done"
+    CANCELLED = "cancelled"
+```
+
+### Priority Enum
+
+```python
+class Priority(Enum):
+    URGENT = 0   # P0
+    HIGH = 1     # P1
+    MEDIUM = 2   # P2
+    LOW = 3      # P3
+    NONE = 4     # P4
+```
+
+---
+
+## Migration
+
+### From Linear to Local
+
+Export from Linear and import locally:
+
+```python
+# In Python
+from linear_provider import LinearProvider
+from local_provider import LocalJsonProvider
+
+linear = LinearProvider(team_key="ANV", team_id="uuid")
+local = LocalJsonProvider()
+
+# Export from Linear
+issues = linear.list_issues(limit=100)
+
+# Import to local
+local.import_issues(issues)
+```
+
+### From Local to Linear
+
+Export as JSON for manual import:
+
+```python
+from local_provider import LocalJsonProvider
+import json
+
+provider = LocalJsonProvider()
+issues = provider.export_issues()
+
+with open("issues-export.json", "w") as f:
+    json.dump(issues, f, indent=2)
+```
+
+---
+
+## Best Practices
+
+### Issue Titles
+
+- Start with verb: "Add", "Fix", "Update", "Remove"
+- Be specific: "Fix login timeout" not "Fix bug"
+- Include scope: "Add dark mode to settings page"
+
+### Using Labels
+
+Common labels:
+- `bug` - Something broken
+- `feature` - New functionality
+- `chore` - Maintenance task
+- `discovered` - Found during other work
+- `blocked` - Cannot proceed
+
+### Sub-Issues
+
+For large features, create sub-issues:
+
+```bash
+# Parent issue
+anvil-issue create --title "User Authentication" --priority high
+
+# Sub-issues
+anvil-issue create --title "Phase 1: Database schema" --parent LOCAL-001
+anvil-issue create --title "Phase 2: API endpoints" --parent LOCAL-001
+anvil-issue create --title "Phase 3: UI components" --parent LOCAL-001
+```
+
+### Regular Cleanup
+
+Periodically clean up completed issues:
+
+```bash
+# View statistics
+anvil-issue stats
+
+# Delete old completed issues
+anvil-issue delete LOCAL-XXX --hard
+```
+
+---
+
+## Troubleshooting
+
+### "Issue not found"
+
+Check the identifier is correct (case-insensitive):
+
+```bash
+anvil-issue show local-001  # Works
+anvil-issue show LOCAL-001  # Works
+```
+
+### Storage Issues
+
+If the index file is corrupted:
+
+```bash
+# Backup and recreate
+mv ~/.anvil/issues/index.json ~/.anvil/issues/index.json.bak
+
+# Provider will create fresh index on next operation
+anvil-issue list
+```
+
+### Provider Not Detected
+
+Ensure you're in a project directory:
+
+```bash
+cd /path/to/your/project
+anvil-issue list
+```
+
+---
+
+## Related Documentation
+
+- [Command Reference](command-reference.md) - All Anvil commands
+- [Session Workflow](session-workflow.md) - Daily workflow patterns
+- [Multi-Agent Protocol](../docs/multi-agent-protocol.md) - Agent coordination
+
+---
+
+*For Linear integration setup, see [/linear-setup](command-reference.md#linear-setup).*