devflow-kit 1.8.3 → 2.0.1

package/src/assets/skills/documentation/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: documentation
+description: This skill should be used when reviewing for documentation drift, missing API docs, or stale comments.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+---
+
+# Documentation Patterns
+
+Domain expertise for documentation quality and alignment. Use alongside `devflow:review-methodology` for complete documentation reviews.
+
+## Iron Law
+
+> **DOCUMENTATION MUST MATCH REALITY**
+>
+> Outdated documentation is worse than no documentation. It actively misleads. Every code
+> change that affects behavior requires a documentation check. Comments that explain "what"
+> instead of "why" are noise. The best documentation is code that doesn't need documentation.
+
+---
+
+## Documentation Categories
+
+### 1. Code Documentation Issues
+
+| Issue | Problem | Fix |
+|-------|---------|-----|
+| Missing docstrings | Complex functions without explanation | Add JSDoc with params, returns, throws |
+| Outdated comments | Comments that contradict code | Update or remove |
+| "What" comments | `// Loop through users` | Explain "why" instead |
+| Magic algorithms | Complex logic without explanation | Document algorithm and rationale |
+| Transition residue | "We no longer do X" notes, in-file changelogs, or refs to removed code/sections | Remove — git holds the history |
+
+**Brief Example - Missing vs. Complete:**
+```typescript
+// BAD: No documentation on complex function
+export function calculateProratedAmount(plan: Plan, startDate: Date, endDate: Date): number;
+
+// GOOD: Purpose, params, returns, edge cases documented
+/**
+ * Calculates prorated billing amount when switching plans mid-cycle.
+ * @param plan - The new plan to prorate to
+ * @returns Prorated amount in cents (can be negative for downgrades)
+ */
+export function calculateProratedAmount(plan: Plan, startDate: Date, endDate: Date): number;
+```
+
+### 2. API Documentation Issues
+
+| Issue | Problem | Fix |
+|-------|---------|-----|
+| Missing params | Callers don't know valid values | Document all params with types and constraints |
+| Missing returns | Return shape unknown | Describe return structure and units |
+| Missing errors | Callers don't know what to catch | List all thrown error types |
+
+**Brief Example - Incomplete vs. Complete:**
+```typescript
+// BAD: No params, no errors documented
+/** Creates a subscription. */
+async function createSubscription(userId: string, planId: string): Promise<Subscription>;
+
+// GOOD: Full contract documented
+/**
+ * @param userId - User's unique identifier
+ * @param planId - Plan ID from /plans endpoint
+ * @throws {UserNotFoundError} If userId doesn't exist
+ * @throws {PlanNotFoundError} If planId doesn't exist
+ */
+async function createSubscription(userId: string, planId: string): Promise<Subscription>;
+```
+
+### 3. Alignment Issues
+
+| Issue | Problem | Fix |
+|-------|---------|-----|
+| Code-comment drift | Comment says 3 retries, code does 5 | Update comment or use constant |
+| Stale README | Examples use removed functions | Keep README in sync with code |
+| Missing changelog | Breaking changes undocumented | Document all notable changes |
+
+**Brief Example - Drift vs. Aligned:**
+```typescript
+// BAD: Comment doesn't match code
+// Retries up to 3 times
+for (let i = 0; i < 5; i++) { /* ... */ }
+
+// GOOD: Use constant to keep aligned
+const MAX_RETRIES = 5;
+for (let i = 0; i < MAX_RETRIES; i++) { /* ... */ }
+```
+
+---
+
+## Extended References
+
+For extended examples and detection commands:
+
+- **[references/violations.md](references/violations.md)** - Extended violation examples with explanations
+- **[references/patterns.md](references/patterns.md)** - Complete correct pattern examples
+- **[references/detection.md](references/detection.md)** - Bash commands for finding issues
+
+---
+
+## Severity Guidelines
+
+| Severity | Description | Examples |
+|----------|-------------|----------|
+| **CRITICAL** | Actively misleading | Comments contradict code; API docs with wrong types; README with broken steps; Changelog missing breaking changes |
+| **HIGH** | Significant gaps | Public APIs undocumented; Complex algorithms unexplained; Errors not documented; Migration guides missing |
+| **MEDIUM** | Moderate issues | Some params undocumented; Examples could be clearer; "What" comments instead of "why" |
+| **LOW** | Minor improvements | Could add more examples; Formatting inconsistencies; Typos |
+
+---
+
+## Documentation Checklist
+
+Before approving changes:
+
+- [ ] All public APIs have JSDoc/docstrings
+- [ ] Parameters and return values documented
+- [ ] Error conditions documented
+- [ ] Complex algorithms explained
+- [ ] Comments explain "why", not "what"
+- [ ] README reflects current state
+- [ ] CHANGELOG updated for notable changes
+- [ ] No TODO comments for completed work
+- [ ] Examples work with current API

package/src/assets/skills/feature-knowledge/SKILL.md

@@ -0,0 +1,341 @@
+---
+name: feature-knowledge
+description: Structures codebase exploration into a feature knowledge base
+user-invocable: false
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Write
+---
+
+# Feature Knowledge Base Creation
+
+## Iron Law
+
+> **Capture the institutional knowledge that lives in developers' heads — the things
+> obvious to them but invisible to newcomers.**
+>
+> A feature knowledge entry exists to save the NEXT agent from rediscovering patterns that span multiple files,
+> modules, or layers. If it's obvious from a single file read, don't capture it.
+
+---
+
+## The Four Phases
+
+Follow these four phases in order. Do not skip ahead.
+
+### Phase 1: Scan
+
+Map the landscape. Get a high-level understanding before going deep.
+
+- Use `Glob` to discover directory structure and file organization
+- Identify language(s), framework(s), and major dependencies
+- Locate key entry points, configuration files, and existing documentation
+- Note how the code is organized — monorepo, modules, layers, etc.
+
+**Goal**: Answer "Where does the code related to this area live, and how is it structured?"
+
+### Phase 2: Extract
+
+Go deep. Read the actual code and pull out the real patterns.
+
+- Read key files using `Read`
+- Use `Grep` to find recurring patterns across the codebase
+- Trace data flow: how does information move through the system?
+- Identify naming conventions, structural patterns, error handling approaches
+- Look for implicit rules — things the team clearly follows but never wrote down
+- Pay attention to what's consistent (conventions) vs. what varies (knowledge gaps)
+- Look at how similar things are implemented — find ALL instances and see what they share
+
+**For complex domains, go further:**
+- Map core entities and their relationships
+- Identify decision points — where does business logic branch?
+- Extract implicit knowledge — what's obvious to current developers but invisible to newcomers?
+- Document state transitions, business rules, and edge case handling
+
+**Self-check before moving on:**
+- "Am I understanding the full scope of what's being requested?"
+- "What connections am I seeing that weren't obvious initially?"
+- "Are there patterns I'm missing because I'm too focused on one area?"
+
+### Phase 3: Distill
+
+Organize and validate findings. Raw observations become structured knowledge.
+
+**Choose a knowledge category:**
+
+| The knowledge is about... | Category | Language Style |
+|---|---|---|
+| How the overall system is designed | `architecture` | Descriptive — explains what systems are and why they exist |
+| Patterns followed across the whole project | `conventions` | Prescriptive — "Do this," "Avoid that" |
+| How a specific type of component works | `component-patterns` | Prescriptive — enforces conventions |
+| A specific business domain or module | `domain-knowledge` | Descriptive — builds mental models |
+| Hard-won lessons from incidents or edge cases | `lessons-learned` | Narrative — tells the story of discovery |
+
+**Validate each finding:**
+- Is this specific to THIS codebase, or generic advice? (only keep specific)
+- Does this reflect what the code actually does NOW, or is it speculative? (only keep current)
+- Would a developer actually use this to build something? (only keep actionable)
+- Is this obvious from reading one file, or does it require cross-cutting knowledge? (prefer cross-cutting)
+
+### Phase 4: Forge
+
+Write the knowledge file. Follow the output format exactly.
+
+---
+
+## Output Format
+
+### KNOWLEDGE.md Structure
+
+```markdown
+---
+feature: {slug}
+name: {human-readable name}
+description: "Use when [specific scenarios]. Keywords: [relevant terms]."
+category: [architecture | conventions | component-patterns | domain-knowledge | lessons-learned]
+directories: [{dir prefixes}]
+created: {ISO date}
+updated: {ISO date}
+---
+
+# {Feature Area Name}
+
+## Overview
+[1-2 paragraphs: what this knowledge covers and why it matters for this codebase]
+
+## [Main Sections — vary by category, see Category Templates below]
+
+## Anti-Patterns
+[What to avoid and why — with explanation of consequences]
+
+## Gotchas
+[Non-obvious behaviors, edge cases, things that break silently]
+
+## Key Files
+[Most important files with one-line descriptions]
+
+## Related
+[Links to ADR/PF entries, other feature knowledge entries, key source files]
+```
+
+### Category Templates
+
+Use the matching template as your main sections. Anti-Patterns, Gotchas, Key Files, and Related are shared across all categories.
+
+**Architecture:**
+- System Context (purpose, role in larger system, external dependencies)
+- Component Architecture (major building blocks, data stores, APIs)
+- Component Interactions (how pieces communicate, data flow)
+- Integration Patterns (how this connects to external systems)
+- Constraints (security boundaries, performance considerations, scaling limits)
+
+**Conventions:**
+- Code Organization Principles (principle with rationale)
+- Standard Patterns (pattern with annotated code example)
+- Error Handling Standards (approach with code example)
+
+**Component Patterns:**
+- Core Responsibilities (what this component should/should NOT do)
+- Standard Structure (complete annotated code example)
+- Dependency Patterns (how dependencies are managed)
+- Error Handling (component-specific error patterns)
+- Integration Guidelines (how to interact with other component types)
+
+**Domain Knowledge:**
+- Business Context (purpose, business value, compliance constraints)
+- Core Business Rules (rules with examples and edge cases)
+- State Transitions (workflow states and triggers)
+- Technical Implementation Patterns (code patterns specific to this domain)
+- Error Handling and Recovery (domain-specific failure modes)
+
+**Lessons Learned:**
+- Per lesson: Incident Context → Root Cause → Impact → Code showing problem and solution → Prevention Strategy
+
+### Description Field Rules
+
+The `description` field is how this feature knowledge entry gets discovered. It must:
+- Start with "Use when"
+- Name specific scenarios where this knowledge applies
+- Include keywords a developer would search for
+
+Good: `"Use when adding a new vendor integration, implementing API clients, or connecting to external services. Keywords: integration, vendor, API client, webhook."`
+Bad: `"Integration stuff"`
+
+### Cross-References
+
+Knowledge files must not exist in isolation. The **Related** section must link to:
+- Other feature knowledge entries that cover related topics
+- ADR/PF entries from DECISIONS_CONTEXT (if provided)
+- Key source files referenced in the knowledge
+
+References should be bidirectional — when creating a new feature knowledge entry that relates to an existing one, note the connection.
+
+---
+
+## Rules for Code Examples
+
+Every code example must have three parts:
+1. **Description before**: what it demonstrates and why
+2. **Inline comments**: explaining the important lines
+3. **Takeaways after**: key points
+
+Before including an example, verify it adds **significant unique value** beyond what descriptive text alone provides. If the pattern can be fully explained in a sentence, skip the code block. Only show codebase-specific patterns — never generic language features.
+
+Never include bare code snippets without context.
+
+---
+
+## What to Avoid
+
+- **Generic advice**: "Use dependency injection" without showing how THIS project does it
+- **Speculation**: "We might want to add caching later" — only document what exists
+- **Bare examples**: Code without explanation of what it shows and why it matters
+- **Low-value examples**: Code that restates generic language features. If it doesn't show something unique to THIS project, cut it.
+- **Everything-bagel files**: Covering too many topics in one file — stay focused
+- **Obvious things**: If reading one file makes it clear, it doesn't need a feature knowledge entry
+- **Testing knowledge**: Don't include test patterns unless explicitly requested
+- **Isolated knowledge islands**: Every feature knowledge entry must reference related files and source code
+
+| Red Flag | What It Indicates |
+|----------|-------------------|
+| "Always follow best practices" | Generic, not codebase-specific |
+| No code examples at all | Insufficient actionable guidance |
+| Examples without inline comments | Missing required context |
+| "In the future, we might..." | Speculative — remove it |
+| 500+ lines in a single file | Should be split into focused files |
+| No cross-references in Related | Isolated knowledge island |
+
+---
+
+## Quality Self-Checks
+
+Run through this before writing. If any check fails, go back and fix it.
+
+**Content:**
+- [ ] Knowledge provides codebase-specific insights (not generic guidance)
+- [ ] All content reflects current patterns (no speculation)
+- [ ] Business context and domain constraints captured where relevant
+- [ ] Every claim is verifiable in actual code
+
+**Examples:**
+- [ ] Every code example has description before, inline comments, and takeaways after
+- [ ] Each example adds significant unique value beyond descriptive text alone
+- [ ] Anti-patterns documented with explanation of consequences
+
+**Structure:**
+- [ ] Category is correct and main sections follow the matching template
+- [ ] Description field starts with "Use when" and includes keywords
+- [ ] File stays under 500 lines (split if necessary)
+
+**Connections:**
+- [ ] Cross-references to related feature knowledge entries and ADR/PF entries in Related section
+- [ ] No isolated knowledge islands — file connects to the broader knowledge network
+- [ ] Key source files listed in Key Files section
+
+---
+
+## Index Registration
+
+After writing KNOWLEDGE.md, update the index cache directly:
+
+**File**: `{worktree}/.devflow/features/index.md`
+**Operation**: Read-modify-write — replace the existing line for this slug if present, or append.
+
+**Line format**:
+```
+- **{slug}** — {areas} — {Use-when description}
+```
+
+Where:
+- `{slug}` matches the `feature:` frontmatter field
+- `{areas}` is a comma-separated summary of the `directories:` frontmatter field
+- `{Use-when description}` is the `description:` frontmatter field value (the full "Use when..." sentence)
+
+If `index.md` does not exist, create it with just this line. If the file already has an entry for this slug, replace that line in-place. This is the discoverable cache read by `knowledge_load()` — the KNOWLEDGE.md frontmatter is always authoritative.
+
+---
+
+## Worked Example
+
+This is what a complete, well-structured feature knowledge entry looks like. Use it as a reference for quality and format.
+
+````markdown
+---
+feature: integrations
+name: Third-Party Integrations
+description: "Use when adding a new vendor integration, implementing API clients, or connecting to external services. Keywords: integration, vendor, API client, webhook, spawn, config."
+category: component-patterns
+directories: [src/lib/]
+created: 2026-04-30
+updated: 2026-04-30
+---
+
+# Third-Party Integrations
+
+## Overview
+
+This project integrates with external systems in three ways: spawning CLI processes, fetching files from remote registries, and writing to directories that AI editors watch. Each integration lives in its own module under `src/lib/` and is wired into a command in `src/commands/`. All external constants are centralized in `src/lib/config.ts`.
+
+The key cross-cutting pattern is the separation between lib modules (which integrate) and commands (which orchestrate). Violating this creates coupling that breaks the error handling model.
+
+## Core Responsibilities
+
+- Lib modules: integrate with external systems, export async functions, throw on failure
+- Commands: orchestrate lib modules, catch errors, route to UI via `showError()`
+- Config: centralize all external constants, expose env var overrides
+
+## Standard Structure
+
+Every integration follows the same file organization. This example shows the pattern that all three existing integrations (Claude CLI, GitHub, AI editors) follow:
+
+```
+src/lib/
+  claude.ts          # Claude Code CLI (spawn + stream JSON)
+  skill-installer.ts # GitHub (git clone, sparse checkout)
+  deploy.ts          # AI editors (.claude/, .cursor/ dirs)
+  config.ts          # All constants for the above
+```
+
+A new integration means a new file here. The module exports async functions, imports from `config.ts`, and never imports from `src/ui/` or `src/commands/`.
+
+### Config Centralization
+
+URLs, subpaths, install directories — these change together. One file to update when an upstream moves:
+
+All constants use `SCREAMING_SNAKE_CASE` with a descriptive prefix. If a value can be overridden by the user, expose an env var with a sensible default.
+
+## Anti-Patterns
+
+- **Putting fetch logic in a command file** — breaks the lib/command separation and makes the integration untestable in isolation.
+- **Hardcoding URLs in lib modules** — always use `config.ts`. Scattered strings become stale and hard to find.
+- **Calling `showError()` from a lib module** — lib modules throw; commands catch and display.
+
+## Gotchas
+
+- `spawn` requires the binary on PATH. If integrating a tool that may not be globally installed, detect `ENOENT` and provide an install URL.
+- Temp files use `Date.now()`. If two processes run simultaneously, add a random suffix to avoid collisions.
+
+## Key Files
+
+- `src/lib/config.ts` — add constants here before writing integration code
+- `src/lib/claude.ts` — reference implementation for spawn-and-stream pattern
+- `src/lib/skill-installer.ts` — reference implementation for fetch-from-remote pattern
+
+## Related
+
+- ADR-003: Lib/command separation principle
+- PF-001: Config drift when constants are scattered
+````
+
+---
+
+## Scope and Limitations
+
+Only document what you can verify in the codebase. When you encounter:
+- Knowledge outside the provided codebase
+- External systems without accessible documentation
+- Information that requires context you don't have
+
+Acknowledge the limitation clearly and focus on what IS extractable. Never fill gaps with generic knowledge or speculation.

package/src/assets/skills/gap-analysis/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: gap-analysis
+description: This skill should be used when analyzing design documents, specifications, or plans for completeness gaps, architectural issues, security concerns, and performance implications. Provides focus-specific detection patterns for the Design agent.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+---
+
+# Gap Analysis
+
+Domain expertise for detecting gaps in design documents, specifications, and plans before implementation begins.
+
+## Iron Law
+
+> **GAPS IN DESIGN BECOME BUGS IN PRODUCTION**
+>
+> Every undefined error state, vague requirement, and missing integration point is a bug
+> waiting to be written. Catch gaps in the plan so the implementation reflects reality,
+> not assumption. Evidence-required: every gap must cite specific text from the artifact.
+
+---
+
+## Focus Areas
+
+### 1. Completeness
+
+Detect missing pieces that will block or break implementation.
+
+**Detection patterns:**
+- Missing acceptance criteria — requirements without testable success conditions
+- Undefined error states — happy path described, failure paths absent
+- Vague requirements — "fast", "secure", "user-friendly" without measurable thresholds
+- Ambiguous user journeys — "user submits form" without specifying what happens next
+- Missing rollback specification — no recovery path if operation partially fails
+- Unspecified data constraints — fields mentioned without type, size, or validation rules
+
+**Evidence trigger:** Any requirement phrase that cannot be directly translated into a test case.
+
+### 2. Architecture
+
+Detect design decisions that conflict with existing patterns or create structural problems.
+
+**Detection patterns:**
+- Implied patterns violating existing conventions — new module structure that contradicts codebase layout
+- Missing integration points — feature touches shared state but integration method unspecified
+- Layering issues — business logic pushed to wrong layer (e.g., validation in presentation layer)
+- Undeclared dependencies — feature needs data/service not mentioned in scope
+- Missing schema changes — new data structure implied but migration not mentioned
+- Shared resource contention — multiple features/requests accessing same resource without concurrency plan
+
+**Evidence trigger:** Any design element that references an existing system component without specifying the integration contract.
+
+### 3. Security
+
+Detect authentication, authorization, and data protection gaps.
+
+**Detection patterns:**
+- Auth gaps — feature creates new endpoints or data access without specifying auth requirements
+- Input validation missing — user-provided data consumed without specifying sanitization
+- Secret handling — credentials, tokens, or keys mentioned without specifying storage/transmission
+- OWASP implications — mass assignment, IDOR, SSRF risks implied by the design
+- Privilege escalation paths — role or permission changes without specifying boundary checks
+- Audit trail missing — sensitive operations without logging or change tracking
+
+**Evidence trigger:** Any data flow that crosses a trust boundary without specifying the security control.
+
+### 4. Performance
+
+Detect design decisions that will cause performance problems at scale.
+
+**Detection patterns:**
+- N+1 patterns implied — loop-based data fetching without batch operation specified
+- Missing caching strategy — repeated expensive operations (DB queries, API calls) without cache layer
+- Concurrency concerns — shared mutable state accessed without locking or isolation strategy
+- Query patterns — filtering/sorting on unindexed fields implied by the feature
+- Unbounded result sets — list operations without pagination or size limits
+- Synchronous blocking — long-running operations blocking request threads without async design
+
+**Evidence trigger:** Any data access pattern that scales linearly with user count or data volume without a mitigation strategy.
+
+### 5. Consistency (multi-issue only)
+
+Detect contradictions and duplications across multiple issue specifications.
+
+**Detection patterns:**
+- Cross-issue contradictions — Issue A says feature X works one way, Issue B implies another
+- Duplicate requirements — same functionality specified in multiple issues without coordination
+- Conflicting scope — one issue's in-scope is another issue's out-of-scope
+- Naming conflicts — same entity called different names across issues
+- Interface mismatches — Issue A produces output that Issue B consumes, but shapes differ
+
+**Evidence trigger:** Any requirement in one issue that cannot coexist with a requirement in another issue.
+
+### 6. Dependencies (multi-issue only)
+
+Detect ordering constraints and shared resource conflicts across issues.
+
+**Detection patterns:**
+- Inter-issue ordering — Issue B depends on data/schema/interface created by Issue A
+- Shared resources — multiple issues modify the same file, table, or API without coordination
+- Breaking change propagation — one issue changes a contract that other issues assume stable
+- Circular dependencies — two issues each require the other to be implemented first
+- Implicit sequencing — implementation order not specified but technically required
+
+**Evidence trigger:** Any issue that references state, contracts, or resources that may be in flux due to another issue in the batch.
+
+### 7. Compliance (when compliance skill installed)
+
+Detect regulatory gaps that security doesn't cover. Active frameworks = the `references/{id}.md` files present in the installed skill. Load `devflow:compliance` before analyzing.
+
+**Detection patterns:**
+- Missing audit trails on regulated mutations — writes to financial records, PHI, PCI-scoped data without durable logging
+- PII flows without retention/erasure specification — data collected but deletion/expiry policy absent
+- Missing encryption requirements — regulated data at rest or in transit without specified encryption control
+- Sensitive data in observability — PII or credentials leaking into logs, traces, or metrics
+- IaC exposure — infrastructure definitions without required security controls (open ports, unencrypted storage, missing IAM boundaries)
+- Self-approval flows — change requires segregation of duties (SOX/SOC 2 CC8.1) but single-actor path exists in the design
+
+**Explicit scope note:** Do NOT duplicate §3 Security's checks (secrets, injection, authZ). Compliance focus is on regulatory control requirements — retention periods, erasure rights, audit completeness, and segregation of duties — not general application security.
+
+**Evidence trigger:** Any regulated-data flow or infrastructure element in the design that does not specify a required control (retention policy, encryption spec, audit log destination, approval workflow).
+
+---
+
+## Extended References
+
+| Reference | Content |
+|-----------|---------|
+| `references/check-layers.md` | Detailed detection checklists per focus area |
+
+## Severity Guidelines
+
+| Level | Criteria | Examples |
+|-------|----------|----------|
+| **CRITICAL** | Gap that will cause data loss, security breach, or system failure | Missing auth on sensitive endpoint, undefined error recovery for financial transaction |
+| **HIGH** | Gap that will cause incorrect behavior or significant technical debt | Missing pagination on unbounded list, undefined race condition in concurrent update |
+| **MEDIUM** | Gap that will require rework if unaddressed | Vague acceptance criteria, missing caching strategy for frequently-read data |
+| **LOW** | Gap that is an improvement opportunity | Naming inconsistency, minor UX ambiguity with obvious resolution |
+
+## Confidence Calibration
+
+- **Report at 80%+**: Gap is clearly present, evidence directly cited
+- **Suggest at 60-79%**: Plausible gap, depends on context not visible in artifact
+- **Drop below 60%**: Speculation without textual evidence
+
+Output format per gap:
+```
+**[FOCUS] Gap: {title}** — Severity: {CRITICAL/HIGH/MEDIUM/LOW} | Confidence: {n}%
+Evidence: "{quoted text from artifact}"
+Issue: {what is missing or contradictory}
+Resolution: {concrete action to address the gap}
+```