devflow-kit 3.1.0 → 3.3.0

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

@@ -1,6 +1,6 @@
 ---
 name: rust
-description: This skill should be used when the user works with Rust files (.rs), asks about "ownership", "borrowing", "lifetimes", "Result/Option", "traits", or discusses memory safety and type-driven design. Provides patterns for ownership, error handling, type system usage, and safe concurrency.
+description: This skill should be used when the user works with Rust files (.rs), asks about "ownership", "borrowing", "lifetimes", "traits", or discusses memory safety.
 user-invocable: false
 allowed-tools: Read, Grep, Glob
 activation:

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

@@ -1,6 +1,6 @@
 ---
 name: security
-description: This skill should be used when reviewing code for injection flaws, auth bypasses, or hardcoded secrets.
+description: This skill should be used when reviewing code for injection, auth or secrets flaws.
 user-invocable: false
 allowed-tools: Read, Grep, Glob
 ---

package/src/assets/skills/software-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: software-design
-description: This skill should be used when the user asks to "handle errors", "inject dependencies", "return Result", "make it immutable", "compose with pipes", or implements business logic, error handling, or service composition. Provides Result type patterns, dependency injection, immutability by default, pipe composition, and structured logging for robust application architecture.
+description: This skill should be used when the user asks to "handle errors", "inject dependencies", "return Result", "make it immutable", or implements business logic or error handling.
 user-invocable: false
 allowed-tools: Read, Grep, Glob, AskUserQuestion
 ---

package/src/assets/skills/test-driven-development/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: test-driven-development
-description: This skill should be used when implementing new features, fixing bugs, or writing new code. Enforces RED-GREEN-REFACTOR.
+description: This skill should be used when implementing features or fixing bugs. Enforces RED-GREEN-REFACTOR.
 user-invocable: false
 allowed-tools: Read, Grep, Glob
 activation:
@@ -34,6 +34,8 @@ Enforce the RED-GREEN-REFACTOR cycle for all implementation work. Tests define t
 
 ## The Cycle
 
+**Affected tests**: the tests that cover the changed files, selected by the runner's related-test option (Jest's `--findRelatedTests`, Vitest's `related`) or, where the runner has none, the package or path that owns them. Every "run the tests" step below means the affected tests; the full suite belongs to Validate.
+
 ### Step 1: RED — Write a Failing Test
 
 Write a test that describes the behavior you want. Run it. Watch it fail. The failure message IS your specification.
@@ -56,19 +58,18 @@ Don't write code "you'll need later." Write code the test demands NOW.
 Don't optimize. Don't refactor. Don't clean up. Just pass the test.
 ```
 
-**Checkpoint:** All tests pass. If any test fails, fix it before moving on.
+**Checkpoint:** All affected tests pass. If any test fails, fix it before moving on.
 
 ### Step 3: REFACTOR — Improve Without Changing Behavior
 
-Now clean up. Extract helpers, rename variables, simplify logic. Tests stay green throughout.
+Now clean up: extract helpers, rename, simplify, apply DRY. Tests stay green throughout.
 
 ```
-Run tests after every refactoring step.
+Run the affected tests after every refactoring step.
 If a test breaks during refactor, undo immediately — you changed behavior.
-Apply DRY, extract patterns, improve readability.
 ```
 
-**Checkpoint:** All tests still pass. Code is clean. Repeat from Step 1 for next behavior.
+**Checkpoint:** All affected tests still pass. Code is clean. Repeat from Step 1 for next behavior.
 
 ---
 
@@ -79,7 +80,7 @@ After each RED-GREEN-REFACTOR cycle, ALL must hold:
 - [ ] Test existed BEFORE production code (not concurrent, not after)
 - [ ] Test failed for the RIGHT reason (expected behavior absent, not syntax/import error)
 - [ ] Production code is minimal — no speculative additions beyond what the test demands
-- [ ] ALL tests pass, not just the new one
+- [ ] ALL affected tests pass, not just the new one
 - [ ] Refactoring happened in Step 3 (or code is already clean — state explicitly)
 - [ ] No untested production code remains
 
@@ -96,11 +97,10 @@ These are the excuses developers use to skip TDD. Recognize and reject them.
 | "I'll write tests after" | Need to see the shape first | Tests ARE the shape — they define the interface before implementation exists | Write the test first |
 | "Too simple to test" | It's just a getter/setter | Getters break, defaults change, edge cases hide in "simple" code | Write it — takes 30 seconds |
 | "I'll refactor later" | Just get it working now | "Later" never comes; technical debt compounds silently | Refactor now in Step 3 |
-| "Test is too hard to write" | Setup is complex, mocking is painful | Hard-to-test code = bad design; the test is telling you the interface is wrong | Simplify the interface first |
-| "Need to see the whole picture" | Can't test what I haven't designed yet | TDD IS design; each test reveals the next piece of the interface | Let the test guide the design |
+| "Test is too hard to write" or "the test setup is too complex" | Mocking is painful | Hard-to-test code = bad design, and complex setup = too much coupling; the test is telling you the interface is wrong | Simplify the interface first |
+| "Need to see the whole picture" or "the architecture first" | Can't test what I haven't designed or structured yet | TDD IS design; each test reveals the next piece of the interface, and tests DEFINE the architecture | Let the tests drive the design and structure |
 | "Tests slow me down" | Faster to just write the code | Faster until the first regression; TDD is faster for anything > 50 lines | Trust the cycle |
 | "Framework is hard to set up" | Setup is complex | One-time cost vs recurring regression cost; untested code compounds debt | Set up the framework first — that IS the work |
-| "Need the architecture first" | Can't test without structure | Tests DEFINE the architecture; they reveal what interfaces are needed | Let tests drive the structure |
 | "This is infrastructure, not logic" | Plumbing doesn't need tests | Infrastructure carries data; broken plumbing floods everything downstream | Test the contract, not the internals |
 | "Deadline is tight, no time for tests" | Ship now, test later | Untested code ships bugs; fixing bugs under deadline is slower than TDD | TDD is faster under pressure, not slower |
 
@@ -108,13 +108,11 @@ See `references/rationalization-prevention.md` for extended examples with code.
 
 ### Red Flags — STOP Immediately
 
-The rationalization table above catches excuses you make *before starting*. These red flags catch you *mid-work* — thoughts that signal you are about to skip a step.
+The table above catches excuses *before starting*. These catch you *mid-work*: thoughts that signal you are about to skip a step.
 
 | Thought | Correction |
 |---------|------------|
 | "Let me write the implementation first, tests after" | Delete the code. Write the test. Watch it fail. Then rewrite. |
-| "I need to see the shape before I can test" | The test IS the shape. It defines the interface before implementation. |
-| "The test setup is too complex for this" | Complex setup = too much coupling. Simplify the design first. |
 | "I'll just spike this and add tests later" | Unless the user said "spike" — you're rationalizing, not prototyping. |
 | "Let me get it working, then lock it with tests" | Those tests verify your implementation, not the requirement. Backwards. |
 | "I know this works, I've written it before" | Past code passed past tests. This code needs its own failing test. |
@@ -122,20 +120,11 @@ The rationalization table above catches excuses you make *before starting*. Thes
 
 ### Test-First vs Code-First
 
-**Code-first** (wrong):
-1. Write `parseConfig()` — split lines, filter comments, build map
-2. Write test: `parseConfig("key=val")` passes
-3. Ship. Undiscovered: empty input, malformed lines, multi-value keys, whitespace
-> Test mirrors implementation. Edge cases stay hidden until production.
+**Code-first** (wrong): write `parseConfig()`, then a test that mirrors it (`parseConfig("key=val")` passes). Empty input, malformed lines, multi-value keys and whitespace stay hidden until production.
 
-**Test-first** (correct):
-1. Test: "ignores comment lines" — `parseConfig("# comment\nkey=val")` → `{key: val}`
-2. Test: "handles empty input" — `parseConfig("")` → empty result
-3. Test: "rejects malformed lines" — `parseConfig("no-equals")` → error
-4. Implement `parseConfig()` to satisfy all three
-> Tests define the contract. Implementation forced to handle edges from the start.
+**Test-first** (correct): "ignores comment lines", then "handles empty input", then "rejects malformed lines", each failing first and each driving the next slice of `parseConfig()`, so it handles the edges from the start.
 
-The difference: code-first tests verify what you *happened to build*. Test-first tests specify what *should exist*.
+Code-first tests verify what you *happened to build*. Test-first tests specify what *should exist*.
 
 ### When Stuck
 
@@ -151,14 +140,7 @@ The difference: code-first tests verify what you *happened to build*. Test-first
 
 ## Process Enforcement
 
-When implementing any feature under ambient IMPLEMENT:
-
-1. **Identify the first behavior** — What is the simplest thing this feature must do?
-2. **Write the test** — Describe that behavior as a failing test
-3. **Run the test** — Confirm it fails (RED)
-4. **Write minimum code** — Just enough to pass (GREEN)
-5. **Refactor** — Clean up while tests stay green (REFACTOR)
-6. **Repeat** — Next behavior, next test, next cycle
+When implementing any feature under ambient IMPLEMENT, start from the simplest thing it must do, take that one behavior through RED, GREEN and REFACTOR, then repeat for the next behavior.
 
 ### File Organization
 

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

@@ -1,6 +1,6 @@
 ---
 name: testing
-description: This skill should be used when the user asks to "write tests", "fix failing tests", "improve test coverage", "add integration tests", "debug a flaky test", or reviews test quality. Provides behavior-focused testing patterns, coverage analysis, and detection of brittle test anti-patterns like implementation coupling and non-deterministic assertions.
+description: This skill should be used when the user asks to "write tests", "fix failing tests", "improve test coverage" or "debug a flaky test", or reviews test quality.
 user-invocable: false
 allowed-tools: Read, Grep, Glob, AskUserQuestion
 activation:

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

@@ -1,6 +1,6 @@
 ---
 name: typescript
-description: This skill should be used when the user works with TypeScript files (.ts/.tsx), asks about "generics", "type guards", "utility types", "strict typing", "discriminated unions", or discusses type safety and inference. Provides patterns for Result types, exhaustive checks, branded types, and type-safe API contracts.
+description: This skill should be used when the user works with TypeScript files (.ts/.tsx), asks about "generics", "type guards", "utility types", "discriminated unions", or discusses type safety.
 user-invocable: false
 allowed-tools: Read, Grep, Glob
 activation:

package/src/assets/skills/ui-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ui-design
-description: This skill should be used when the user asks to "design a component", "pick colors", "improve typography", "fix spacing", "choose a layout", or discusses visual design, CSS, styling decisions, or responsive interfaces. Provides patterns for typography scales, color systems, spacing, and production-grade UI design.
+description: This skill should be used when the user asks to "design a component", "pick colors", "improve typography", "fix spacing", or discusses visual design and CSS.
 user-invocable: false
 allowed-tools: Read, Grep, Glob
 activation:

package/src/assets/skills/worktree-support/SKILL.md

@@ -7,8 +7,6 @@ allowed-tools: Bash, Read
 
 # Worktree Support
 
-Canonical patterns for worktree-aware agents and multi-worktree discovery in commands.
-
 ## Iron Law
 
 > **WORKTREE_PATH IS A PREFIX, NOT A FLAG**
@@ -16,8 +14,6 @@ Canonical patterns for worktree-aware agents and multi-worktree discovery in com
 > When WORKTREE_PATH is provided, it changes how you resolve ALL paths — git commands,
 > file reads, .devflow/docs/ paths. It's not a toggle; it's a coordinate system shift.
 
----
-
 ## Agent Path Resolution
 
 When `WORKTREE_PATH` is provided to an agent:
@@ -31,46 +27,6 @@ When `WORKTREE_PATH` is provided to an agent:
 
 If `WORKTREE_PATH` is omitted, behavior is unchanged (use cwd). This is the common case.
 
----
-
-## Worktree Discovery Algorithm (Commands)
-
-For commands that auto-discover worktrees (`/code-review`, `/resolve`):
-
-### Step 1: List Worktrees
-
-Run `git worktree list --porcelain`
-
-### Step 2: Parse Each Entry
-
-Extract: `worktree {path}`, `HEAD {sha}`, `branch refs/heads/{name}`
-
-### Step 3: Filter
-
-Exclude:
-- **Bare worktrees** (no branch)
-- **Detached HEAD** (no named branch; roots and detached HEAD: `references/roots.md`)
-- **Protected branches**: `main`, `master`, `develop`, `integration`, `trunk`, `release/*`, `staging`, `production`
-- **Mid-rebase or mid-merge**: check `git -C {path} status` for "rebase in progress" or "merging"
-
-### Step 4: Check for Work
-
-Each worktree must have commits ahead of base branch. Skip those that are clean/up-to-date.
-
-### Step 5: Deduplicate
-
-If two worktrees are on the same branch, use only the first worktree's path.
-
-### Step 6: Sort
-
-Sort by last commit date (most recent first).
-
-### Step 7: Return
-
-Return list of reviewable worktrees with path, branch, HEAD SHA.
-
----
-
 ## Protected Branches (Canonical List)
 
 `main`, `master`, `develop`, `integration`, `trunk`, `release/*`, `staging`, `production`
@@ -78,15 +34,7 @@ Return list of reviewable worktrees with path, branch, HEAD SHA.
 All components (agents, commands, skills) must use this exact list when checking for protected branches.
 The HUD mirrors this list in `TRUNK_BRANCHES`/`TRUNK_BRANCH_PREFIXES`/`isTrunkBranch()` in `src/core/git.ts` — update both together.
 
----
-
-## Multi-Worktree Mode
+## Extended References
 
-| Condition | Behavior |
-|-----------|----------|
-| 0 reviewable worktrees | Error: no reviewable branches found |
-| 1 worktree (common case) | Single-worktree flow, zero behavior change |
-| 2+ worktrees | Report count, process worktrees **sequentially** (one at a time) |
-| 5+ worktrees | Report count and proceed — user manages their worktree count |
-| `--path` flag provided | Use only that worktree, skip discovery |
-| Same branch in 2 worktrees | Deduplicate — review once using first worktree's path |
+- `references/discovery.md` — the 7-step discovery algorithm and multi-worktree mode
+- `references/roots.md` — project data roots and detached HEAD

package/src/assets/skills/worktree-support/references/discovery.md

@@ -0,0 +1,48 @@
+# Worktree Discovery
+
+How commands that auto-discover worktrees (`/code-review`, `/resolve`) find them, and how the count found sets the flow. The protected-branch list lives only in the skill's `## Protected Branches (Canonical List)`; this file points to it and copies none of it.
+
+## Algorithm
+
+### Step 1: List Worktrees
+
+Run `git worktree list --porcelain`
+
+### Step 2: Parse Each Entry
+
+Extract: `worktree {path}`, `HEAD {sha}`, `branch refs/heads/{name}`
+
+### Step 3: Filter
+
+Exclude:
+- **Bare worktrees** (no branch)
+- **Detached HEAD** (no named branch; roots and detached HEAD: `roots.md`)
+- **Protected branches**: every branch in the skill's `## Protected Branches (Canonical List)`
+- **Mid-rebase or mid-merge**: check `git -C {path} status` for "rebase in progress" or "merging"
+
+### Step 4: Check for Work
+
+Each worktree must have commits ahead of base branch. Skip those that are clean/up-to-date.
+
+### Step 5: Deduplicate
+
+If two worktrees are on the same branch, use only the first worktree's path.
+
+### Step 6: Sort
+
+Sort by last commit date (most recent first).
+
+### Step 7: Return
+
+Return list of reviewable worktrees with path, branch, HEAD SHA.
+
+## Multi-Worktree Mode
+
+| Condition | Behavior |
+|-----------|----------|
+| 0 reviewable worktrees | Error: no reviewable branches found |
+| 1 worktree (common case) | Single-worktree flow, zero behavior change |
+| 2+ worktrees | Report count, process worktrees **sequentially** (one at a time) |
+| 5+ worktrees | Report count and proceed — user manages their worktree count |
+| `--path` flag provided | Use only that worktree, skip discovery |
+| Same branch in 2 worktrees | Deduplicate — review once using first worktree's path |

package/src/assets/skills/worktree-support/references/roots.md

@@ -1,6 +1,6 @@
 # Project Roots and Detached HEAD
 
-Where devflow keeps per-project data across checkouts, and what it does on a detached HEAD. Companion to the worktree discovery algorithm in `SKILL.md`.
+Where devflow keeps per-project data across checkouts, and what it does on a detached HEAD. Companion to the worktree discovery algorithm in `discovery.md`.
 
 ## Which Root Holds What
 
@@ -24,6 +24,6 @@ A detached HEAD is a commit checked out without a branch (`git checkout <sha>`,
 | Surface | Behaviour |
 |---------|-----------|
 | Knowledge commit | Skipped: a commit there becomes unreachable once HEAD moves. The Knowledge agent reports `KB_COMMIT: skipped (detached HEAD) — uncommitted: <paths>`, and the calling workflow names those paths to the user |
-| Worktree discovery | Excluded from auto-review (discovery Step 3 in `SKILL.md`): there is no branch to review, compare or push |
+| Worktree discovery | Excluded from auto-review (discovery Step 3 in `discovery.md`): there is no branch to review, compare or push |
 | Memory bootstrap | The first compaction bootstraps `WORKING-MEMORY.md` stamped `branch: (detached)`, keyed on the HEAD commit; an unborn branch has no commit and still skips |
 | Memory header | Renders `detached @ <short-sha>` instead of `on unknown` |