@drafthq/draft 2.7.0

package/core/templates/tech-stack.md

@@ -0,0 +1,169 @@
+---
+project: "{PROJECT_NAME}"
+module: "root"
+generated_by: "draft:init"
+generated_at: "{ISO_TIMESTAMP}"
+---
+
+# Tech Stack
+
+| Field | Value |
+|-------|-------|
+| **Branch** | `{LOCAL_BRANCH}` → `{REMOTE/BRANCH}` |
+| **Commit** | `{SHORT_SHA}` — {COMMIT_MESSAGE} |
+| **Generated** | {ISO_TIMESTAMP} |
+| **Synced To** | `{FULL_SHA}` |
+
+---
+
+## Languages
+
+| Language | Version | Purpose |
+|----------|---------|---------|
+| [Primary] | [Version] | Main application code |
+| [Secondary] | [Version] | [Scripts/tooling/etc] |
+
+---
+
+## Frameworks & Libraries
+
+### Core
+| Name | Version | Purpose |
+|------|---------|---------|
+| [Framework] | [Version] | [Purpose] |
+| [Library] | [Version] | [Purpose] |
+
+### Development
+| Name | Version | Purpose |
+|------|---------|---------|
+| [Tool] | [Version] | [Purpose] |
+
+---
+
+## Database
+
+| Type | Technology | Purpose |
+|------|------------|---------|
+| Primary | [DB Name] | Main data storage |
+| Cache | [Cache Name] | [If applicable] |
+| Search | [Search Engine] | [If applicable] |
+
+---
+
+## Testing
+
+| Level | Framework | Coverage Target |
+|-------|-----------|-----------------|
+| Unit | [Framework] | [80%+] |
+| Integration | [Framework] | [Key flows] |
+| E2E | [Framework] | [Critical paths] |
+
+---
+
+## Build & Deploy
+
+### Build
+- **Tool**: [Webpack/Vite/esbuild/etc]
+- **Output**: [dist/build/etc]
+
+### CI/CD
+- **Platform**: [GitHub Actions/CircleCI/etc]
+- **Triggers**: [on push, PR, etc]
+
+### Deployment
+- **Target**: [Vercel/AWS/GCP/etc]
+- **Environments**: [dev, staging, prod]
+
+---
+
+## Code Patterns
+
+### Architecture
+- **Pattern**: [Clean Architecture/MVC/Hexagonal/etc]
+- **Rationale**: [Why this pattern]
+
+### State Management
+- **Approach**: [Redux/Zustand/Context/etc]
+- **Rationale**: [Why this approach]
+
+### Error Handling
+- **Strategy**: [Centralized/per-module/etc]
+- **Logging**: [Tool/service]
+
+### API Design
+- **Style**: [REST/GraphQL/gRPC]
+- **Conventions**: [Naming, versioning]
+
+---
+
+## Component Overview
+
+```mermaid
+graph TD
+    subgraph Frontend["Frontend"]
+        UI["UI Framework"]
+        State["State Management"]
+    end
+    subgraph Backend["Backend"]
+        API["API Layer"]
+        BL["Business Logic"]
+        DAL["Data Access"]
+    end
+    subgraph Infrastructure["Infrastructure"]
+        DB[(Database)]
+        Cache[(Cache)]
+        Queue["Message Queue"]
+    end
+    UI --> State
+    State --> API
+    API --> BL
+    BL --> DAL
+    DAL --> DB
+    DAL --> Cache
+    BL --> Queue
+```
+
+> Replace with actual components and their relationships from the codebase. For detailed architecture analysis see `draft/.ai-context.md`.
+
+---
+
+## External Services
+
+| Service | Purpose | Credentials Location |
+|---------|---------|---------------------|
+| [Service 1] | [Purpose] | [.env / secrets manager] |
+| [Service 2] | [Purpose] | [.env / secrets manager] |
+
+---
+
+## Code Style
+
+### Linting
+- **Tool**: [ESLint/Prettier/etc]
+- **Config**: [.eslintrc / prettier.config.js]
+
+### Formatting
+- **Indentation**: [2 spaces / 4 spaces / tabs]
+- **Line Length**: [80 / 100 / 120]
+- **Quotes**: [single / double]
+
+### Naming Conventions
+- **Files**: [kebab-case / camelCase / PascalCase]
+- **Functions**: [camelCase]
+- **Classes**: [PascalCase]
+- **Constants**: [SCREAMING_SNAKE_CASE]
+
+---
+
+## Accepted Patterns
+
+<!-- Intentional design decisions that may appear unusual but are correct -->
+<!-- bughunt, deep-review, and review commands will honor these exceptions -->
+
+| Pattern | Location | Rationale |
+|---------|----------|-----------|
+| [e.g., Empty catch blocks] | [src/resilient-loader.ts] | [Intentional silent failure for optional plugins] |
+| [e.g., Circular import] | [moduleA ↔ moduleB] | [Lazy resolution pattern, not a bug] |
+| [e.g., `any` type usage] | [src/legacy-adapter.ts] | [Bridging untyped legacy API] |
+
+> Add patterns here that static analysis might flag but are intentional. Include enough context for reviewers to understand the decision.

package/core/templates/track-architecture.md

@@ -0,0 +1,311 @@
+---
+project: "{PROJECT_NAME}"
+module: "root"
+track_id: "{TRACK_ID}"
+generated_by: "draft:decompose"
+generated_at: "{ISO_TIMESTAMP}"
+git:
+  branch: "{LOCAL_BRANCH}"
+  remote: "{REMOTE/BRANCH}"
+  commit: "{FULL_SHA}"
+  commit_short: "{SHORT_SHA}"
+  commit_date: "{COMMIT_DATE}"
+  commit_message: "{COMMIT_MESSAGE}"
+  dirty: false
+synced_to_commit: "{FULL_SHA}"
+---
+
+# Track Architecture: {TRACK_TITLE}
+
+> Track-scoped HLD/LLD for a single feature, bug fix, or refactor.
+> Source of truth for implementation — `/draft:implement` consumes this to guide build order, contracts, and story generation.
+> For project-wide architecture, see `draft/architecture.md`.
+
+| Field | Value |
+|-------|-------|
+| **Track ID** | `{TRACK_ID}` |
+| **Spec** | `./spec.md` |
+| **Plan** | `./plan.md` |
+| **Branch** | `{LOCAL_BRANCH}` → `{REMOTE/BRANCH}` |
+| **Commit** | `{SHORT_SHA}` — {COMMIT_MESSAGE} |
+| **Generated** | {ISO_TIMESTAMP} |
+| **LLD Included** | {true | false} |
+
+---
+
+## Table of Contents
+
+1. [Overview](#1-overview)
+2. [Module Breakdown](#2-module-breakdown)
+3. [High-Level Design (HLD)](#3-high-level-design-hld)
+   - 3.1 Component Diagram
+   - 3.2 Data Flow
+   - 3.3 Sequence Diagrams (Critical Flows)
+   - 3.4 State Machine(s)
+4. [Dependency Analysis](#4-dependency-analysis)
+5. [Implementation Order](#5-implementation-order)
+6. [Low-Level Design (LLD)](#6-low-level-design-lld)
+   - 6.1 Per-Module API Contracts
+   - 6.2 Data Models & Schemas
+   - 6.3 Error Handling & Retry Semantics
+   - 6.4 Algorithm Pseudocode (where non-trivial)
+7. [Notes & Decisions](#7-notes--decisions)
+
+---
+
+## 1. Overview
+
+**What this track delivers:** {one paragraph from spec.md — the feature, bug fix, or refactor being scoped}
+
+**Inputs:** {what triggers or feeds into this feature}
+**Outputs:** {what this feature produces — data, side effects, API responses}
+**Constraints:** {latency, throughput, compatibility, security — anything from spec.md Non-Functional Requirements}
+
+**Integration points:** {which existing modules from `draft/.ai-context.md` this track touches}
+
+---
+
+## 2. Module Breakdown
+
+### Modules Introduced or Modified
+
+For each module in scope, fill out one block:
+
+#### Module: `{module-name}`
+
+- **Status:** `[ ] New` | `[ ] Modified` | `[x] Existing (unchanged)`
+- **Responsibility:** {one sentence — what this module owns}
+- **Files:** `{path/to/file1}`, `{path/to/file2}`
+- **API Surface:** {public functions, classes, or interfaces — names only, contracts in §6.1}
+- **Dependencies:** {other modules this imports from}
+- **Complexity:** `Low` | `Medium` | `High`
+- **Story placeholder:** _populated by `/draft:implement`_
+
+{Repeat for each module.}
+
+---
+
+## 3. High-Level Design (HLD)
+
+### 3.1 Component Diagram
+
+Shows modules in scope + the external collaborators they talk to.
+
+```mermaid
+flowchart TD
+    subgraph Track["Track: {TRACK_ID}"]
+        M1["{module-1}"]
+        M2["{module-2}"]
+        M3["{module-3}"]
+    end
+    subgraph Existing["Existing System"]
+        E1["{existing-module-A}"]
+        E2["{existing-module-B}"]
+    end
+    subgraph External["External"]
+        X1["{DB / queue / API}"]
+    end
+
+    M1 --> M2
+    M2 --> M3
+    M1 --> E1
+    M3 --> X1
+```
+
+> Draw one node per module in scope. Include existing modules only when this track calls into them. Label edges with the transport (HTTP, RPC, queue, direct call) when non-obvious.
+
+### 3.2 Data Flow
+
+End-to-end flow of data through the track's modules.
+
+```mermaid
+flowchart LR
+    In["{input — request / event}"] --> V["{validation}"]
+    V --> L["{business logic}"]
+    L --> P["{persistence}"]
+    P --> Out["{output — response / emitted event}"]
+```
+
+> Replace with the actual transforms. If the track has distinct read and write paths, draw them separately.
+
+### 3.3 Sequence Diagrams — Critical Flows
+
+One sequence per acceptance criterion that involves more than a single module call. Skip for trivial single-module tracks.
+
+#### Flow: {name — e.g., "Happy path: user submits X"}
+
+```mermaid
+sequenceDiagram
+    participant U as {Caller}
+    participant A as {module-1}
+    participant B as {module-2}
+    participant D as {DB / external}
+
+    U->>A: {request payload}
+    A->>B: {internal call}
+    B->>D: {query / write}
+    D-->>B: {result}
+    B-->>A: {response}
+    A-->>U: {final response}
+
+    Note over A,B: {invariant / gate — e.g., "tx must be open here"}
+```
+
+#### Flow: {error path — e.g., "Dependency timeout"}
+
+```mermaid
+sequenceDiagram
+    participant U as {Caller}
+    participant A as {module-1}
+    participant D as {External}
+
+    U->>A: {request}
+    A->>D: {call with timeout={N}ms}
+    D--xA: {timeout}
+    A->>A: {fallback / circuit breaker}
+    A-->>U: {degraded response or error}
+```
+
+### 3.4 State Machine(s)
+
+Include only if the track introduces or modifies stateful entities. Omit otherwise.
+
+```mermaid
+stateDiagram-v2
+    [*] --> Pending
+    Pending --> Processing: start
+    Processing --> Complete: success
+    Processing --> Failed: error
+    Failed --> Pending: retry (max {N})
+    Failed --> DeadLetter: retries exhausted
+    Complete --> [*]
+```
+
+---
+
+## 4. Dependency Analysis
+
+### ASCII Dependency Graph
+
+```
+[module-1] ──> [module-2]
+    │              │
+    └──> [module-3] <──┘
+```
+
+### Dependency Table
+
+| Module | Depends On | Depended By | Cycle? |
+|--------|------------|-------------|--------|
+| `{mod}` | `{list}` | `{list}` | no |
+
+### Cycle Mitigation
+
+_If any cycles detected, describe how they are broken (shared interface extraction, dependency inversion, etc.). Otherwise: "No cycles detected."_
+
+---
+
+## 5. Implementation Order
+
+Topological sort — leaves first.
+
+1. `{module-A}` (no internal deps) — foundational
+2. `{module-B}` (depends on: A)
+3. `{module-C}` (depends on: A, B)
+
+**Parallel opportunities:** {which modules can be built concurrently}
+
+---
+
+## 6. Low-Level Design (LLD)
+
+> Present when `--lld` flag was passed to `/draft:decompose` OR any module in §2 has `Complexity: High`. Otherwise this section reads: _"LLD not generated. Run `/draft:decompose --lld` to expand."_
+
+### 6.1 Per-Module API Contracts
+
+For each module in §2 marked `New` or `Modified`:
+
+#### `{module-name}` — Public API
+
+| Function / Method | Signature | Params | Returns | Errors / Exceptions |
+|-------------------|-----------|--------|---------|---------------------|
+| `{name}` | `{lang-appropriate signature}` | `{param: type — constraint}` | `{type — shape}` | `{error types / codes}` |
+
+**Preconditions:** {what must be true before call — caller responsibilities}
+**Postconditions:** {what is guaranteed after successful call}
+**Invariants:** {properties preserved across calls — thread safety, idempotency, ordering}
+
+{Repeat per module.}
+
+### 6.2 Data Models & Schemas
+
+Concrete shapes for every new or modified entity this track introduces.
+
+#### `{ModelName}`
+
+```{language}
+{actual type definition — struct, class, interface, proto message, TypedDict, etc.}
+```
+
+| Field | Type | Nullable | Default | Validation / Constraint |
+|-------|------|----------|---------|-------------------------|
+| `{field}` | `{type}` | yes/no | `{default or —}` | `{rule}` |
+
+**Storage:** {where persisted — table, collection, key prefix}
+**Indexes / Keys:** {primary key, unique constraints, indexed fields}
+**Migration:** {if this is a schema change — migration path and rollback}
+
+{Repeat per model.}
+
+### 6.3 Error Handling & Retry Semantics
+
+Per-operation policy. One row per operation that has non-trivial error handling.
+
+| Operation | Error Class | Classification | Retry? | Backoff | Max Attempts | Fallback |
+|-----------|-------------|----------------|--------|---------|--------------|----------|
+| `{op}` | `{ErrorType}` | transient / permanent / timeout | yes/no | `{policy}` | `{N}` | `{behavior}` |
+
+**Propagation model:** {how errors surface — Result type, exceptions, error codes}
+**Circuit breaker:** {thresholds, half-open policy, reset} — omit if N/A
+**Idempotency:** {which operations are idempotent and how — dedup key, tx id}
+
+### 6.4 Algorithm Pseudocode
+
+Include only for non-trivial logic. Skip for straightforward CRUD.
+
+#### {Algorithm name}
+
+**Inputs:** `{...}`
+**Outputs:** `{...}`
+**Complexity:** `O({...})` time, `O({...})` space
+
+```
+{numbered or indented pseudocode — language-agnostic}
+1. validate inputs
+2. ...
+3. return result
+```
+
+**Edge cases handled:**
+- {case 1 — what happens}
+- {case 2 — what happens}
+
+---
+
+## 7. Notes & Decisions
+
+### Architecture Decisions
+
+- {decision 1 — rationale, alternatives considered}
+- {decision 2 — rationale, alternatives considered}
+
+### Open Questions
+
+- {question tracked during decomposition — to resolve before or during implementation}
+
+### Links
+
+- Spec: `./spec.md`
+- Plan: `./plan.md`
+- Related ADRs: `{paths if any, created via /draft:adr}`
+- Project architecture: `draft/.ai-context.md` → `draft/architecture.md`

package/core/templates/workflow.md

@@ -0,0 +1,187 @@
+---
+project: "{PROJECT_NAME}"
+module: "root"
+generated_by: "draft:init"
+generated_at: "{ISO_TIMESTAMP}"
+git:
+  branch: "{LOCAL_BRANCH}"
+  remote: "{REMOTE/BRANCH}"
+  commit: "{FULL_SHA}"
+  commit_short: "{SHORT_SHA}"
+  commit_date: "{COMMIT_DATE}"
+  commit_message: "{COMMIT_MESSAGE}"
+  dirty: false
+synced_to_commit: "{FULL_SHA}"
+---
+
+# Development Workflow
+
+| Field | Value |
+|-------|-------|
+| **Branch** | `{LOCAL_BRANCH}` → `{REMOTE/BRANCH}` |
+| **Commit** | `{SHORT_SHA}` — {COMMIT_MESSAGE} |
+| **Generated** | {ISO_TIMESTAMP} |
+| **Synced To** | `{FULL_SHA}` |
+
+---
+
+## Test-Driven Development
+
+**Mode:** [strict | flexible | none]
+
+**Coverage Target:**
+```yaml
+coverage_target: 95  # Minimum coverage percentage (default: 95%)
+```
+
+### Strict TDD
+
+**Iron Law:** No production code without a failing test first.
+
+The Cycle:
+1. **RED** - Write failing test, run it, VERIFY it FAILS
+2. **GREEN** - Write minimum code, run test, VERIFY it PASSES
+3. **REFACTOR** - Clean up, keep tests green throughout
+
+**Red Flags - Delete and Restart if:**
+- Code written before test exists
+- Test passes immediately (testing wrong thing or wrong code)
+- "Just this once" rationalization
+- "This is too simple to test"
+- Running test mentally instead of actually
+
+**Checklist:**
+- [ ] Test written and committed BEFORE implementation
+- [ ] Test fails with expected failure (not syntax error)
+- [ ] Minimum code to pass (no extra features)
+- [ ] Refactor preserves green state
+
+### Flexible TDD
+- [ ] Tests required but can be written after implementation
+- [ ] All code must have tests before marking complete
+- [ ] Refactoring encouraged
+
+### No TDD
+- [ ] Tests optional
+- [ ] Manual verification acceptable
+
+---
+
+## Commit Strategy
+
+**Format:** `type(scope): description`
+
+### Types
+| Type | Use For |
+|------|---------|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `docs` | Documentation only |
+| `style` | Formatting, whitespace |
+| `refactor` | Code restructure without behavior change |
+| `test` | Adding or fixing tests |
+| `chore` | Build, tooling, dependencies |
+
+### Scope
+- Use track ID for Draft work: `feat(add-auth): ...`
+- Use component name otherwise: `fix(api): ...`
+
+### Commit Frequency
+- [ ] After each task completion
+- [ ] At phase boundaries
+- [ ] End of session
+
+---
+
+## Code Review
+
+### Self-Review Checklist
+- [ ] Code follows project style guide
+- [ ] Tests pass locally
+- [ ] No console.log or debug statements
+- [ ] Error handling complete
+- [ ] Edge cases considered
+
+### Before Marking Task Complete
+- [ ] Run linter
+- [ ] Run tests
+- [ ] Review diff
+
+---
+
+## Phase Verification
+
+At the end of each phase:
+
+1. **Run full test suite**
+2. **Manual smoke test** if applicable
+3. **Review against phase goals** in plan.md
+4. **Document any issues** found
+
+Do not proceed to next phase until verification passes.
+
+---
+
+## Review Settings
+
+### Auto-Review
+- [ ] Auto-review at track completion
+
+When enabled, runs `/draft:review track <id>` automatically when `/draft:implement` completes a track.
+
+### Blocking Behavior
+- [ ] Block on review failures
+
+When enabled, halt track completion if critical (✗) issues found. Requires fixes before marking complete.
+
+When disabled (default), review failures produce warnings only. Issues documented in `draft/tracks/<id>/review-report.md`.
+
+### Review Scope (Stage 1 Automation)
+- [x] Architecture conformance
+- [x] Dead code detection
+- [x] Dependency cycle detection
+- [x] Security scan
+- [x] Performance anti-patterns
+
+Uncheck categories to skip during validation phase of review. All enabled by default.
+
+> **How to configure:** Edit the checkboxes above directly in this file. Change `[x]` to `[ ]` to disable a category. The `/draft:review` command reads these settings before running.
+
+---
+
+## Session Management
+
+### Starting a Session
+1. Run `/draft:status` to see current state
+2. Read active track's spec.md and plan.md
+3. Find current task (marked `[~]` or first `[ ]`)
+
+### Ending a Session
+1. Commit any pending changes
+2. Update plan.md with progress
+3. Add notes for next session if mid-task
+
+### Context Handoff
+If task exceeds 5 iterations:
+1. Document current state in plan.md
+2. Note any discoveries or blockers
+3. Suggest resumption approach
+
+---
+
+## Toolchain
+
+### VCS
+- [x] git + GitHub Pull Requests
+
+### MCP Auto-Connect (optional)
+- [ ] Jira MCP — for ticket linking via `/draft:jira` (preview / create / review)
+- [ ] Confluence MCP — for design-doc and runbook lookups
+
+> **How to configure:** Check the MCP boxes above to enable optional integrations. See `core/shared/vcs-commands.md` for git command conventions used across skills.
+
+---
+
+## Guardrails
+
+> **See `draft/guardrails.md`** — Hard guardrails, learned conventions, and learned anti-patterns are managed in the dedicated guardrails file. Run `/draft:learn` to discover patterns and update guardrails.