@drafthq/draft 2.7.0

package/skills/testing-strategy/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: testing-strategy
+description: Design test strategies and test plans with coverage targets. Complements /draft:coverage which measures what this skill plans. Auto-loaded by /draft:implement before TDD.
+---
+
+# Testing Strategy
+
+You are designing a testing strategy and test plan for this project or track.
+
+## Red Flags — STOP if you're:
+
+- Writing a strategy without understanding the codebase
+- Setting unrealistic coverage targets (100% is rarely appropriate)
+- Focusing only on unit tests and ignoring integration/E2E
+- Ignoring existing test infrastructure and conventions
+- Not considering the testing pyramid for this project's architecture
+
+**A good testing strategy matches the architecture. Not every project needs the same pyramid.**
+
+---
+
+## Pre-Check
+
+### 0. Capture Git Context
+
+Before starting, capture the current git state:
+
+```bash
+git branch --show-current # Current branch name
+git rev-parse --short HEAD # Current commit hash
+```
+
+Store this for the report header. The strategy is scoped to this specific branch/commit.
+
+### 1. Verify Draft Context
+
+```bash
+ls draft/ 2>/dev/null
+```
+
+If `draft/` doesn't exist, this skill can still run standalone with reduced context.
+
+### 2. Load Draft Context (if available)
+
+Read and follow the base procedure in `core/shared/draft-context-loading.md`.
+
+## Step 1: Parse Arguments
+
+- `/draft:testing-strategy` — Project-wide strategy (default if no active track)
+- `/draft:testing-strategy track <id>` — Track-scoped strategy
+- `/draft:testing-strategy module <name>` — Module-scoped strategy
+
+## Step 2: Analyze Codebase
+
+1. **Identify component types:**
+   - APIs (REST, GraphQL, gRPC)
+   - Data pipelines (ETL, streaming)
+   - Frontend (React, Vue, etc.)
+   - Infrastructure (Terraform, K8s configs)
+   - Libraries/SDKs
+   - CLI tools
+
+2. **Discover existing tests:**
+   ```bash
+   find . -name "*test*" -o -name "*spec*" | head -50
+   ```
+   Identify: test frameworks, test directories, existing coverage config, test runners.
+
+3. **Assess current coverage:**
+   Check for existing coverage reports or configuration:
+   ```bash
+   ls coverage/ .nyc_output/ htmlcov/ .coverage 2>/dev/null
+   ```
+
+4. **Read project context:**
+   - `draft/tech-stack.md` — Test frameworks, testing conventions
+   - `draft/workflow.md` — TDD preferences (strict/flexible/none)
+   - `draft/.ai-context.md` — INVARIANTS section (critical paths), module boundaries, concurrency model
+   - `draft/guardrails.md` — Anti-patterns that need test coverage
+   - `draft/product.md` — Critical user flows that demand E2E tests
+
+## Step 3: Design Strategy
+
+### Testing Pyramid
+
+Tailor to the project architecture:
+
+```
+        ┌─────────┐
+        │ E2E │ Few, critical paths only
+        ├─────────┤
+        │ Integr. │ Service boundaries, DB, APIs
+        ├─────────┤
+        │ Unit │ Business logic, utilities
+        └─────────┘
+```
+
+Adjust the pyramid shape per architecture. A microservices backend may need a wider integration band. A UI-heavy app may need more E2E. A library may be almost entirely unit tests.
+
+### Per-Component Strategy
+
+| Component Type | Unit | Integration | E2E | Focus |
+|---------------|------|-------------|-----|-------|
+| API endpoints | Input validation, handlers | DB queries, auth | Critical flows | Contract testing |
+| Data pipelines | Transform logic | Source/sink connections | Full pipeline | Data integrity |
+| Frontend | Component rendering, hooks | API integration | User journeys | Visual regression |
+| Infrastructure | Config validation | Resource provisioning | Deployment | Drift detection |
+| Libraries | Public API surface | Cross-module | Consumer scenarios | Backward compat |
+| CLI tools | Argument parsing, logic | File I/O, system calls | Full workflows | Exit codes, output |
+
+### Coverage Targets
+
+Set realistic targets based on component criticality:
+- **Critical paths** (from .ai-context.md INVARIANTS): 95%+
+- **Business logic**: 85-90%
+- **Utilities/helpers**: 80%
+- **Infrastructure/config**: 70%
+- **Generated code**: Exclude from targets
+- **Vendor/third-party wrappers**: 60%
+
+### Test Quality Guidelines
+
+Coverage alone is insufficient. Include guidance on:
+- **Assertion density:** At least one meaningful assertion per test (not just "doesn't throw")
+- **Boundary testing:** Edge cases, empty inputs, max values, off-by-one
+- **Error paths:** Test failure modes, not just happy paths
+- **Isolation:** Unit tests must not depend on external services, filesystem, or network
+- **Determinism:** No time-dependent, order-dependent, or flaky tests
+- **Naming:** Test names describe the scenario and expected outcome
+
+## Step 4: Gap Analysis
+
+Compare current state to targets:
+1. Run test discovery to count existing tests per module
+2. Identify modules with zero test coverage
+3. Identify critical paths (from INVARIANTS) without integration tests
+4. Identify user flows (from product.md) without E2E coverage
+5. Identify anti-patterns (from guardrails.md) without regression tests
+6. Prioritize gaps by risk: high-risk untested > low-risk untested
+
+Present as a gap matrix:
+
+| Module | Current Tests | Target | Gap | Risk | Priority |
+|--------|--------------|--------|-----|------|----------|
+| ... | ... | ... | ... | ... | ... |
+
+## Step 5: Generate Test Plan
+
+Priority test cases to write, ordered by impact:
+
+1. Tests for critical invariants (from .ai-context.md)
+2. Tests for anti-patterns (from guardrails.md) — regression prevention
+3. Integration tests for service boundaries
+4. E2E tests for critical user flows (from product.md)
+5. Regression tests for known bugs
+6. Property-based tests for complex business logic (if framework supports it)
+7. Performance tests for latency-sensitive paths
+
+For each priority test, specify:
+- **What:** Description of the test scenario
+- **Why:** Which invariant, anti-pattern, or flow it protects
+- **How:** Test type (unit/integration/E2E), framework, key assertions
+- **Where:** File path where the test should live
+
+## Step 6: Save Output
+
+**MANDATORY: Include YAML frontmatter with git metadata.** Follow `core/shared/git-report-metadata.md`.
+
+Include the report header table immediately after frontmatter:
+
+```markdown
+| Field | Value |
+|-------|-------|
+| **Branch** | `{LOCAL_BRANCH}` → `{REMOTE/BRANCH}` |
+| **Commit** | `{SHORT_SHA}` — {COMMIT_MESSAGE} |
+| **Generated** | {ISO_TIMESTAMP} |
+| **Synced To** | `{FULL_SHA}` |
+```
+
+Save to:
+- Project-wide: `draft/testing-strategy.md`
+- Track-scoped: `draft/tracks/<id>/testing-strategy.md`
+
+## Cross-Skill Dispatch
+
+- **Auto-loaded by:** `/draft:implement` (before TDD cycle)
+- **Suggested by:** `/draft:decompose` (after module definition), `/draft:init` (after setup)
+- **Feeds into:** `/draft:coverage` (measurement against targets set here)
+- **References:** `/draft:bughunt` findings as regression test candidates
+
+## Error Handling
+
+**If no test infrastructure found:** Recommend test framework based on tech-stack.md, include setup steps needed before tests can be written
+**If no draft context:** Generate generic strategy, suggest running `/draft:init` for better results
+**If conflicting test patterns found:** Document both patterns, recommend consolidation as a tech-debt item

package/skills/tour/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: tour
+description: Interactive onboarding walkthrough for a new engineer. Use for "give me a tour", "onboard me", "walk me through the codebase".
+---
+
+# Draft Tour: Interactive Onboarding
+
+Provide an interactive codebase walk-through based on existing architecture and guardrail constraints.
+
+## Red Flags - STOP if you're:
+- Dumping the entire `architecture.md` into the chat window.
+- Giving answers to foundational pattern questions before prompting the developer to guess.
+- Explaining code the developer hasn't explicitly asked to view yet.
+
+---
+
+## Execution Constraints
+
+1. **Load Context:** Read `draft/architecture.md`, `draft/tech-stack.md`, and `draft/guardrails.md`.
+2. **Interactive Cadence:** Ask the developer if they are familiar with the tech stack constraints found in `draft/tech-stack.md`.
+3. **Module Introduction:** Instead of listing all modules, introduce the "Entry Point" module first.
+4. **Active Challenge:** After explaining a module's responsibility, challenge the developer: "Based on our *Context-Driven Development* rules, how do you think we handle data persistence here?" Wait for their answer before revealing the architecture strategy.
+   - If the answer is correct, confirm briefly and cite the supporting line in `architecture.md` / `guardrails.md`.
+   - If the answer is partially right, name what they got right, then ask a narrower follow-up (e.g., "Right that we cache reads — what's the invalidation trigger?") before revealing the rest.
+   - If the answer is wrong, do not just hand them the answer. Quote the specific guardrail or HLD section that contradicts it, then re-prompt with a hint scoped to that section.
+5. **Traceability:** Highlight `draft/.state/facts.json` showing how module constraints have evolved.
+6. **Track Lifecycle Walk:** Show the full feature lifecycle and who owns each gate:
+   - `/draft:new-track` → `spec.md` (requirements + classification + approvers) + `plan.md` (phases/tasks)
+   - `/draft:decompose` → `hld.md` (always, with graph-derived diagrams) + `lld.md` (when --lld or High-complexity module)
+   - **Approvers (HLD):** Technical Leads, Architecture Review Board, Cloud Operations (SaaS), QA Leads (on-prem), PM Leads
+   - **Approvers (LLD):** Team Leads, Technical Leads, Quality Assurance
+   - `/draft:implement` → TDD loop reading lld.md/hld.md for stub generation
+   - `/draft:upload` → blocks `git upload` for high/mission-critical tracks until HLD §Approvals signed
+   - `/draft:deploy-checklist` → blocks deploy until HLD §Checklist + LLD §Alerting Thresholds populated
+   - Walk a real example track from `draft/tracks/` if any exist; otherwise sketch a hypothetical low-criticality flow.
+7. **Completion:** Guide the developer to create their first test track using `/draft:new-track` so they understand the artifact loop end-to-end.
+
+---

package/skills/upload/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: upload
+description: Pre-upload gate for track handoff. Verifies review status, HLD approvals, deploy checklist, and validator chain before git upload or PR submission.
+---
+
+# Upload for Review
+
+Gate track completion before `git upload`, `git push`, or opening a PR for human review.
+
+## Red Flags — STOP if you're:
+
+See [shared red flags](../../core/shared/red-flags.md).
+
+Skill-specific:
+- Uploading without a passing `/draft:review` on the track
+- Skipping HLD §Approvals for `criticality ∈ {high, mission-critical}` tracks
+- Treating a deploy checklist with `status: BLOCKED` as passing
+- Pushing when validator tools report hygiene or citation drift
+
+**Upload is a gate, not a shortcut around review.**
+
+---
+
+## Step 1: Resolve Track
+
+1. Parse `track <id|name>` from arguments, or auto-detect the active `[~]` track from `draft/tracks.md`.
+2. Load `draft/tracks/<id>/spec.md`, `plan.md`, `metadata.json`, and `hld.md` when present.
+3. If no track resolves, error: "No track to upload. Specify `track <id>` or activate a track."
+
+---
+
+## Step 2: Pre-Upload Verification
+
+### 2.1 Review gate
+
+- Require `review-report-latest.md` on the track with verdict `PASS` or `PASS WITH NOTES`.
+- If missing or `FAIL`, stop and instruct: run `/draft:review track <id>` first.
+
+### 2.2 Deploy checklist (auto-invoke)
+
+Run `/draft:deploy-checklist track <id>` when no fresh passing checklist exists.
+
+### 2.5 Checklist status
+
+- Read `draft/tracks/<id>/deploy-checklist-latest.md` (or timestamped sibling).
+- If frontmatter contains `status: BLOCKED`, **stop** — checklist is not a passing gate.
+- Critical unchecked items block upload.
+
+### 2.3 Validator chain
+
+Run the WS-9 chain from [verification-gates.md](../../core/shared/verification-gates.md) against the track directory. Any non-zero exit aborts upload.
+
+```bash
+TRACK_DIR="draft/tracks/<id>"
+DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$HOME/.claude/plugins/draft}/scripts/tools"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$HOME/.cursor/plugins/local/draft/scripts/tools"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
+
+"$DRAFT_TOOLS/check-track-hygiene.sh" "$TRACK_DIR"
+"$DRAFT_TOOLS/verify-citations.sh" "$TRACK_DIR"
+"$DRAFT_TOOLS/verify-doc-anchors.sh" "$TRACK_DIR"
+"$DRAFT_TOOLS/diff-templates-vs-tracks.sh" "$TRACK_DIR"
+```
+
+---
+
+## Step 3: HLD / LLD Approval Gate
+
+### 3.1 HLD §Approvals (high-criticality)
+
+When `spec.md` frontmatter `classification.criticality` is `high` or `mission-critical`:
+
+- Every required row in `hld.md` §Approvals must have a populated **Date** column.
+- If HLD was edited after the latest signed Date, stop — re-circulate for sign-off.
+- For `low` / unset criticality, warn if approvers are placeholders but do not block.
+
+### 3.2 LLD presence
+
+When LLD was generated for the track, ensure Team Lead / QA approval rows are populated before upload (same Date rule as HLD).
+
+---
+
+## Step 4: Upload Execution
+
+After all gates pass:
+
+1. Confirm branch and commit range with the user.
+2. Run the project's upload command (`git upload`, `git push`, or `gh pr create` per `draft/workflow.md`).
+3. Capture the review URL or change ID.
+
+Update `draft/tracks/<id>/metadata.json`:
+
+```json
+{
+  "lastUploaded": "<ISO-8601>",
+  "uploadCount": <N+1>
+}
+```
+
+---
+
+## Step 5: Post-Upload
+
+- If Jira is linked, sync via [jira-sync.md](../../core/shared/jira-sync.md): comment "Code uploaded for review. {URL}".
+- If new public APIs lack docs, suggest `/draft:documentation api`.
+
+---
+
+## Cross-Skill Dispatch
+
+- **Auto-invokes:** `/draft:deploy-checklist`
+- **Requires:** `/draft:review` PASS (or PASS WITH NOTES)
+- **Suggested by:** `/draft:implement` (track completion), `/draft:documentation` (pre-upload API docs)
+
+## Graph Usage Report
+
+Emit the canonical footer from [graph-usage-report.md](../../core/shared/graph-usage-report.md) when graph queries were used during validation.