@eddacraft/anvil-aps 0.1.0

package/docs/APS-Planning-Spec-v0.1.md

@@ -0,0 +1,362 @@
+# APS Planning Spec v0.1
+
+> **Anvil Planning Spec (APS)** — A Markdown-based format for LLM-readable
+> planning documents.
+
+## Overview
+
+The Anvil Planning Spec (APS) defines a structured Markdown format for planning
+documents that are:
+
+- **Human-readable** — Plain Markdown, familiar conventions
+- **LLM-friendly** — Structured with clear headings and key-value fields
+- **Graph-aware** — Supports modular plans with dependencies
+- **Execution-ready** — Bridges from planning to task execution
+
+### Design Goals
+
+1. **Single source of truth** — Planning docs are canonical, not derived
+2. **Separation of concerns** — Planning (source) vs Execution (derived state)
+3. **Validation-first** — Clear rules, early feedback
+4. **Scoped context** — LLMs see only what they need
+
+### Non-Goals
+
+See [APS-NonGoals.md](./APS-NonGoals.md) for explicit non-goals.
+
+---
+
+## Document Types
+
+APS supports two document types:
+
+1. **Leaf Spec** — Contains tasks for a single module or feature
+2. **Index File** — Organises multiple leaf specs into a plan graph
+
+### Single-File Plans
+
+For simple plans, a single leaf spec is sufficient:
+
+```markdown
+# Feature: User Authentication
+
+**Scope:** AUTH **Owner:** @alice **Priority:** high
+
+## Tasks
+
+### AUTH-001: Implement login endpoint
+
+...
+```
+
+### Multi-File Plans
+
+For complex plans, use an index file + leaf specs:
+
+```
+docs/planning/
+  system.aps.md           # Index file
+  modules/
+    auth.aps.md           # Leaf spec
+    payments.aps.md       # Leaf spec
+```
+
+---
+
+## Index File Structure
+
+Index files organise leaf specs and define module metadata.
+
+### Required Sections
+
+#### `# [Plan Title]` (H1)
+
+The plan title (H1 heading). Only one H1 per file.
+
+#### `## Modules` (H2)
+
+Lists modules with metadata. Each module is an H3 heading.
+
+**Example:**
+
+```markdown
+## Modules
+
+### auth
+
+- **Path:** [./modules/auth.aps.md](./modules/auth.aps.md)
+- **Scope:** AUTH
+- **Owner:** @alice
+- **Priority:** high
+- **Tags:** security, core
+- **Dependencies:** (none)
+
+### payments
+
+- **Path:** [./modules/payments.aps.md](./modules/payments.aps.md)
+- **Scope:** PAY
+- **Owner:** @bob
+- **Priority:** medium
+- **Tags:** billing, stripe
+- **Dependencies:** auth
+```
+
+### Module Metadata Fields
+
+| Field             | Required | Format                       | Purpose                 |
+| ----------------- | -------- | ---------------------------- | ----------------------- |
+| **Path:**         | Yes      | Markdown link                | Link to leaf spec file  |
+| **Scope:**        | No       | Uppercase prefix (e.g. AUTH) | Namespace for task IDs  |
+| **Owner:**        | No       | @username                    | Person/team responsible |
+| **Priority:**     | No       | `low`, `medium`, `high`      | Priority level          |
+| **Tags:**         | No       | Comma-separated list         | Labels for filtering    |
+| **Dependencies:** | No       | Comma-separated module IDs   | Modules this depends on |
+
+### Optional Sections
+
+- **`## Overview`** — High-level description
+- **`## Open Questions`** — Unresolved questions
+- **`## Decisions`** — Architectural decisions with dates
+
+---
+
+## Leaf Spec Structure
+
+Leaf specs contain tasks for a single module or feature.
+
+### Required Sections
+
+#### `# [Module Title]` (H1)
+
+The module title (H1 heading). Only one H1 per file.
+
+#### Module Metadata Line
+
+Immediately after the H1, include scope/owner/priority:
+
+```markdown
+# Authentication Module
+
+**Scope:** AUTH **Owner:** @alice **Priority:** high
+```
+
+#### `## Tasks` (H2)
+
+Contains task definitions. Each task is an H3 heading.
+
+### Task Structure
+
+Each task follows this format:
+
+```markdown
+### AUTH-001: Implement login endpoint
+
+**Intent:** Create POST /auth/login endpoint that validates credentials and
+returns JWT **Expected Outcome:** Working login endpoint with tests
+**Confidence:** high **Scopes:** AUTH **Tags:** security, api **Dependencies:**
+DB-001 **Inputs:**
+
+- User credentials (email, password)
+- Database connection
+
+**Status:** open
+```
+
+### Task Fields
+
+| Field                 | Required | Format                   | Purpose                               |
+| --------------------- | -------- | ------------------------ | ------------------------------------- |
+| **Intent:**           | Yes      | Single sentence          | What the task aims to achieve         |
+| **Expected Outcome:** | No       | Text                     | Success criteria                      |
+| **Confidence:**       | No       | `low`, `medium`, `high`  | Certainty about approach              |
+| **Scopes:**           | No       | Comma-separated prefixes | What can be changed (LLM constraints) |
+| **Tags:**             | No       | Comma-separated labels   | For filtering and search              |
+| **Dependencies:**     | No       | Comma-separated task IDs | Tasks that must complete first        |
+| **Inputs:**           | No       | Bulleted list            | Required inputs or context            |
+| **Status:**           | No       | See status values below  | Current execution state               |
+
+### Task Status Values
+
+| Status      | Meaning                                 |
+| ----------- | --------------------------------------- |
+| `open`      | Not started (default)                   |
+| `locked`    | Being worked on (via `anvil plan lock`) |
+| `completed` | Finished successfully                   |
+| `cancelled` | Abandoned or no longer needed           |
+
+**Note:** Status is managed externally in `.anvil/state.json`, not in the
+planning doc.
+
+### Task ID Format
+
+Task IDs must follow the format: `<SCOPE>-<NUMBER>`
+
+**Examples:**
+
+- `AUTH-001` ✓
+- `PAY-042` ✓
+- `auth-001` ✗ (lowercase scope)
+- `AUTH001` ✗ (missing hyphen)
+
+Task IDs must be unique across the entire plan graph.
+
+### Optional Sections
+
+- **`## Dependencies`** — Module-level dependencies
+- **`## Notes`** — Additional context
+
+---
+
+## Conventions
+
+See [APS-Conventions.md](./APS-Conventions.md) for detailed conventions on:
+
+- File naming (`.aps.md` extension)
+- Link rules (relative paths, in-repo only)
+- ID uniqueness (error on duplicates)
+- Heading hierarchy
+- Root file discovery
+
+---
+
+## Scopes vs Tags
+
+**Scopes** and **Tags** serve different purposes:
+
+### Scopes (Hard Boundaries)
+
+Scopes define **what code/files can be changed** during task execution. They
+constrain the LLM's operating context.
+
+**Example:**
+
+```markdown
+**Scopes:** AUTH, DB
+```
+
+This means the LLM can only modify files in the `AUTH` and `DB` scopes.
+
+### Tags (Soft Labels)
+
+Tags are labels for **filtering and search**. They don't constrain behaviour.
+
+**Example:**
+
+```markdown
+**Tags:** security, high-risk, needs-review
+```
+
+This helps filter tasks but doesn't restrict what can be changed.
+
+---
+
+## Validation Rules
+
+APS documents must pass validation before execution:
+
+### Errors (Blocking)
+
+- Missing required sections (`## Modules`, `## Tasks`)
+- Missing required fields (`Path:` in modules, `Intent:` in tasks)
+- Invalid task ID format
+- Duplicate task IDs across plan graph
+- Broken links
+- Circular module dependencies
+
+### Warnings (Non-blocking)
+
+- Missing Confidence field
+- Scope mismatch (task scope not in parent module scope)
+- Orphan leaf specs (not referenced from index)
+
+See Phase 6 implementation for full validation rules.
+
+---
+
+## Example: Simple Feature Plan
+
+```markdown
+# Feature: User Authentication
+
+**Scope:** AUTH **Owner:** @alice **Priority:** high
+
+> Implement basic username/password authentication.
+
+## Tasks
+
+### AUTH-001: Create user model
+
+**Intent:** Define User model with email, password hash, created_at **Expected
+Outcome:** User model with validation and tests **Confidence:** high **Scopes:**
+AUTH, DB **Tags:** models, database
+
+### AUTH-002: Implement login endpoint
+
+**Intent:** Create POST /auth/login that validates credentials **Expected
+Outcome:** Working endpoint with JWT generation **Confidence:** high **Scopes:**
+AUTH **Tags:** api, security **Dependencies:** AUTH-001
+
+## Notes
+
+- Consider OAuth in future iteration
+```
+
+---
+
+## Example: Multi-Module Plan
+
+**Index file:** `docs/planning/system.aps.md`
+
+```markdown
+# System: E-commerce Platform
+
+## Overview
+
+Build core e-commerce functionality.
+
+## Modules
+
+### auth
+
+- **Path:** [./modules/auth.aps.md](./modules/auth.aps.md)
+- **Scope:** AUTH
+- **Owner:** @alice
+- **Priority:** high
+- **Tags:** security, core
+
+### payments
+
+- **Path:** [./modules/payments.aps.md](./modules/payments.aps.md)
+- **Scope:** PAY
+- **Owner:** @bob
+- **Priority:** medium
+- **Tags:** billing, stripe
+- **Dependencies:** auth
+```
+
+**Leaf file:** `docs/planning/modules/auth.aps.md`
+
+```markdown
+# Authentication Module
+
+**Scope:** AUTH **Owner:** @alice **Priority:** high
+
+## Tasks
+
+### AUTH-001: Implement login
+
+**Intent:** Create login endpoint **Confidence:** high **Scopes:** AUTH
+```
+
+---
+
+## Integration with Anvil
+
+See [APS-Anvil-Integration.md](./APS-Anvil-Integration.md) for how planning docs
+become execution plans.
+
+---
+
+## Version History
+
+- **v0.1** (2025-12-17) — Initial specification

package/examples/README.md

@@ -0,0 +1,170 @@
+# APS Examples
+
+This directory contains example planning documents demonstrating different APS
+patterns and use cases.
+
+## Examples Overview
+
+### 1. Feature Plan: User Authentication
+
+**File:** `feature-auth.aps.md`
+
+**Type:** Single-file plan
+
+**Demonstrates:**
+
+- Simple, self-contained feature plan
+- Sequential task dependencies
+- Clear task structure with Intent, Expected Outcome, Confidence
+- Multi-scope tasks (AUTH + DB, AUTH + API)
+- Module-level dependencies section
+- Deferred work documented in Notes
+
+**Use this as a template for:** Small to medium features with clear scope
+
+---
+
+### 2. System Plan: E-commerce Platform MVP
+
+**Files:** `system-ecommerce/APS.md` + `modules/*.aps.md`
+
+**Type:** Multi-file plan (index + 4 leaf specs)
+
+**Demonstrates:**
+
+- Large system broken into modules
+- Index file with module metadata (Scope, Owner, Priority, Tags, Dependencies)
+- Module dependency graph (auth → products → cart → payments)
+- Open Questions section in index
+- Decisions section with dates
+- Different confidence levels across tasks
+- Cross-module dependencies between tasks
+
+**Modules:**
+
+- `auth.aps.md` — Authentication (3 tasks, high confidence)
+- `products.aps.md` — Product catalog (5 tasks, mixed confidence)
+- `cart.aps.md` — Shopping cart (5 tasks, medium confidence with open questions)
+- `payments.aps.md` — Stripe payments (6 tasks, includes low confidence task)
+
+**Use this as a template for:** Large systems with multiple modules and team
+ownership
+
+---
+
+### 3. Refactor Plan: API Error Handling
+
+**File:** `refactor-error-handling.aps.md`
+
+**Type:** Single-file plan
+
+**Demonstrates:**
+
+- Refactoring with uncertainty (low/medium/high confidence mix)
+- Multi-scope tasks across many modules (API, AUTH, PROD, CART, PAY, INFRA,
+  DOCS)
+- Research/audit tasks (API-001 with low confidence)
+- Design tasks before implementation
+- Multiple parallel refactor tasks (API-005 through API-008)
+- Open questions documenting unknowns
+- Notes about rollout strategy and considerations
+
+**Confidence distribution:**
+
+- Low: 3 tasks (audit, monitoring integration, unknowns)
+- Medium: 4 tasks (design, implementation with dependencies on external systems)
+- High: 4 tasks (clear implementation with established patterns)
+
+**Use this as a template for:** Technical debt, refactoring, infrastructure work
+with unknowns
+
+---
+
+## Key Patterns Demonstrated
+
+### Task Structure
+
+All examples show proper task formatting:
+
+```markdown
+### SCOPE-001: Task title
+
+**Intent:** What the task achieves **Expected Outcome:** Success criteria
+**Confidence:** low|medium|high **Scopes:** SCOPE1, SCOPE2 **Tags:** tag1, tag2
+**Dependencies:** SCOPE-XXX **Inputs:**
+
+- Required input 1
+```
+
+### Confidence Levels
+
+- **High:** Well-understood, clear path (most tasks in feature-auth)
+- **Medium:** Generally clear with some unknowns (cart pricing, payment
+  webhooks)
+- **Low:** Uncertain approach, needs exploration (error audit, monitoring
+  integration)
+
+### Multi-Scope Tasks
+
+Tasks that touch multiple areas use comma-separated scopes:
+
+```markdown
+**Scopes:** AUTH, DB, API
+```
+
+### Dependencies
+
+- **Module dependencies:** In index file under each module
+- **Task dependencies:** In task metadata with IDs
+
+### Deferred Work
+
+All examples document out-of-scope items in Notes:
+
+- "OAuth integration deferred"
+- "Image upload deferred to separate module"
+- "Refunds deferred to phase 2"
+
+---
+
+## Using These Examples
+
+### As Learning Material
+
+1. Read `feature-auth.aps.md` first for basic structure
+2. Explore `system-ecommerce/` for multi-module plans
+3. Study `refactor-error-handling.aps.md` for uncertainty handling
+
+### As Templates
+
+1. Copy the example closest to your use case
+2. Replace scope prefixes with your own
+3. Update tasks to match your requirements
+4. Adjust confidence based on your knowledge
+
+### For Validation Testing
+
+These examples can be used to test the APS validator:
+
+- All should pass structural validation
+- All should have valid task ID formats
+- All should have resolvable links (in system-ecommerce)
+
+---
+
+## File Naming Conventions
+
+- **Single-file plans:** `[type]-[name].aps.md` (e.g., `feature-auth.aps.md`)
+- **Multi-file plans:** `[name]/APS.md` as index, `modules/*.aps.md` as leaf
+  specs
+
+---
+
+## Next Steps
+
+After exploring these examples:
+
+1. Read the [APS Planning Spec](../docs/APS-Planning-Spec-v0.1.md) for full
+   format details
+2. Check [APS Conventions](../docs/APS-Conventions.md) for detailed rules
+3. Use the template generator: `pnpm generate-templates`

package/examples/feature-auth.aps.md

@@ -0,0 +1,87 @@
+# Feature: User Authentication
+
+**Scope:** AUTH **Owner:** @alice **Priority:** high
+
+> Implement basic username/password authentication with JWT tokens for the
+> e-commerce platform.
+
+## Tasks
+
+### AUTH-001: Create user database model
+
+**Intent:** Define User model with email, password hash, and timestamps
+**Expected Outcome:** User model with validation, migrations, and unit tests
+**Confidence:** high **Scopes:** AUTH, DB **Tags:** database, models, security
+**Inputs:**
+
+- Database connection configuration
+- Password hashing library (bcrypt)
+
+### AUTH-002: Implement password hashing service
+
+**Intent:** Create service for secure password hashing and verification using
+bcrypt **Expected Outcome:** Service with hash() and verify() methods, tested
+with edge cases **Confidence:** high **Scopes:** AUTH **Tags:** security,
+services **Dependencies:** AUTH-001
+
+### AUTH-003: Create registration endpoint
+
+**Intent:** Implement POST /auth/register endpoint that validates input and
+creates user accounts **Expected Outcome:** Working endpoint that returns 201
+with user data (excluding password) **Confidence:** high **Scopes:** AUTH, API
+**Tags:** api, endpoints **Dependencies:** AUTH-001, AUTH-002 **Inputs:**
+
+- Email validation rules
+- Password strength requirements (min 8 chars, 1 uppercase, 1 number, 1 special)
+
+### AUTH-004: Implement JWT token generation
+
+**Intent:** Create service for generating and signing JWT tokens with user
+claims **Expected Outcome:** Service that generates tokens with configurable
+expiry (default 24h) **Confidence:** high **Scopes:** AUTH **Tags:** security,
+jwt, tokens **Inputs:**
+
+- JWT secret from environment variables
+- Token expiry configuration
+
+### AUTH-005: Create login endpoint
+
+**Intent:** Implement POST /auth/login that validates credentials and returns
+JWT token **Expected Outcome:** Working endpoint that returns 200 with token on
+success, 401 on failure **Confidence:** high **Scopes:** AUTH, API **Tags:**
+api, endpoints, security **Dependencies:** AUTH-001, AUTH-002, AUTH-004
+
+### AUTH-006: Add authentication middleware
+
+**Intent:** Create Express middleware that validates JWT tokens and attaches
+user to request **Expected Outcome:** Middleware that protects routes, returns
+401 for invalid/missing tokens **Confidence:** high **Scopes:** AUTH, API
+**Tags:** middleware, security **Dependencies:** AUTH-004
+
+### AUTH-007: Implement logout endpoint
+
+**Intent:** Create POST /auth/logout endpoint that invalidates current token
+**Expected Outcome:** Endpoint that adds token to blacklist and returns 200
+**Confidence:** medium **Scopes:** AUTH, CACHE **Tags:** api, endpoints
+**Dependencies:** AUTH-006 **Inputs:**
+
+- Redis connection for token blacklist
+
+### AUTH-008: Add integration tests
+
+**Intent:** Create end-to-end tests covering full authentication flow **Expected
+Outcome:** Test suite covering register → login → authenticated request → logout
+**Confidence:** high **Scopes:** AUTH, API **Tags:** testing, integration
+**Dependencies:** AUTH-003, AUTH-005, AUTH-007
+
+## Dependencies
+
+- Database connection and migrations system (assumed existing)
+- Redis for token blacklist (AUTH-007)
+
+## Notes
+
+- Consider OAuth integration in future iteration (Google, GitHub)
+- Email verification not in scope for this iteration
+- Password reset flow deferred to separate feature plan
+- Rate limiting should be added to login/register endpoints (separate task)