devflow-kit 1.4.0 → 1.6.0

package/shared/skills/knowledge-persistence/references/examples.md

@@ -0,0 +1,44 @@
+# Knowledge Persistence Examples
+
+## Decision Entry Example
+
+```markdown
+## ADR-001: Use mkdir-based locks for concurrent session serialization
+
+- **Date**: 2026-03-03
+- **Status**: Accepted
+- **Context**: Multiple Claude Code sessions can run on the same project simultaneously (different terminals, SSH, etc.). Memory writes must serialize to prevent corruption.
+- **Decision**: Use `mkdir` as an atomic lock primitive. Lock directory at `.memory/.knowledge.lock`. 30-second timeout with 60-second stale recovery.
+- **Consequences**: Simple, cross-platform, no external dependencies. Cannot detect holder PID if lock is stale — relies on age-based recovery. Sufficient for low-contention writes.
+- **Source**: `/implement #99`
+```
+
+## Pitfall Entry Example
+
+```markdown
+## PF-001: Orphaned teams variants silently skipped
+
+- **Area**: plugins/devflow-*/commands/*-teams.md, src/cli/installer
+- **Issue**: The installer iterates base `.md` files and looks up matching `-teams.md` variants. A `-teams.md` file without a corresponding base `.md` is silently ignored during installation.
+- **Impact**: Teams variant appears committed but never installs. Users on `--teams` mode silently get no command.
+- **Resolution**: Always create the base `.md` file first. CI should validate that every `-teams.md` has a matching base file.
+- **Source**: `/code-review feat/agent-teams`
+```
+
+## Status Lifecycle (Decisions Only)
+
+Decisions support status transitions:
+- `Accepted` — current, in effect
+- `Superseded by ADR-NNN` — replaced by a newer decision
+- `Deprecated` — no longer relevant, kept for history
+
+Pitfalls have no status field — they remain until manually removed.
+
+## Deduplication Logic (Pitfalls Only)
+
+Before appending a new pitfall, check existing entries:
+1. Extract `Area` and `Issue` from the new entry
+2. Compare against all existing `PF-*` entries
+3. If both Area AND Issue match an existing entry (case-insensitive substring), skip
+
+This prevents recording the same gotcha from multiple review cycles.

package/shared/skills/plan-orchestration/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: plan-orchestration
+description: Agent orchestration for PLAN intent — codebase orientation, design exploration, gap validation
+user-invocable: false
+allowed-tools: Read, Grep, Glob, Bash, Task, AskUserQuestion
+---
+
+# Plan Orchestration
+
+Agent pipeline for PLAN intent in ambient ORCHESTRATED mode. Codebase orientation, targeted exploration, architecture design, and gap validation.
+
+This is a lightweight variant of the Plan phase in `/implement` for ambient ORCHESTRATED mode.
+
+## Iron Law
+
+> **PLANS WITHOUT CODEBASE GROUNDING ARE FANTASIES**
+>
+> Orient before architecting. Every design decision must reference existing patterns,
+> real file structures, and actual integration points. A plan that ignores the codebase
+> will fail on contact with implementation.
+
+---
+
+## Phase 1: Orient
+
+Spawn `Task(subagent_type="Skimmer")` to get codebase overview relevant to the planning question:
+
+- Existing patterns and conventions in the affected area
+- File structure and module boundaries
+- Test patterns and coverage approach
+- Related prior implementations (similar features, analogous patterns)
+
+## Phase 2: Explore
+
+Based on Skimmer findings, spawn 2-3 `Task(subagent_type="Explore")` agents **in a single message** (parallel execution):
+
+- **Integration explorer**: Examine integration points — APIs, shared types, module boundaries the plan must respect
+- **Pattern explorer**: Find existing implementations of similar features to follow as templates
+- **Constraint explorer**: Identify constraints — test infrastructure, build system, CI requirements, deployment concerns
+
+Adjust explorer focus based on the specific planning question.
+
+## Phase 3: Design
+
+Spawn `Task(subagent_type="Plan")` with combined Skimmer + Explore findings:
+
+- Design implementation approach with file-level specificity
+- Reference existing patterns discovered in Phase 1-2
+- Include: architecture decisions, file changes, new files needed, test strategy
+- Flag any areas where existing patterns conflict with the proposed approach
+
+## Phase 4: Validate
+
+Main session reviews the plan for:
+
+- **Gaps**: Missing files, unhandled edge cases, integration points not addressed
+- **Risks**: Areas where the plan deviates from existing patterns, potential regressions
+- **Ambiguities**: Design choices that need user input
+
+Present plan to user with identified risks. Use AskUserQuestion for any ambiguous design choices.
+
+## Output
+
+Structured plan ready to feed into IMPLEMENT/ORCHESTRATED if user proceeds:
+
+- Goal and scope
+- Architecture decisions with rationale
+- File-level change list (create/modify/delete)
+- Test strategy
+- Risks and mitigations
+- Open questions (if any)

package/shared/skills/search-first/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: search-first
+description: >-
+  This skill should be used when the user asks to "add a utility", "create a helper",
+  "implement parsing", "build a wrapper", or writes infrastructure/utility code that
+  may already exist as a well-maintained package. Enforces research before building.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+---
+
+# Search-First
+
+Research before building. Check if a battle-tested solution exists before writing custom utility code.
+
+## Iron Law
+
+> **RESEARCH BEFORE BUILDING**
+>
+> Never write custom utility code without first checking if a battle-tested solution
+> exists. The best code is code you don't write. A maintained package with thousands
+> of users will always beat a hand-rolled utility in reliability, edge cases, and
+> long-term maintenance.
+
+## When This Skill Activates
+
+**Triggers** — creating or modifying code that:
+- Parses, formats, or validates data (dates, URLs, emails, UUIDs, etc.)
+- Implements common algorithms (sorting, diffing, hashing, encoding)
+- Wraps HTTP clients, retries, rate limiting, caching
+- Handles file system operations beyond basic read/write
+- Implements CLI argument parsing, logging, or configuration
+- Creates test utilities (mocking, fixtures, assertions)
+
+**Does NOT trigger** for:
+- Domain-specific business logic unique to this project
+- Glue code connecting existing components
+- Trivial operations (< 5 lines, single-use)
+- Code that intentionally avoids external dependencies (e.g., zero-dep libraries)
+
+---
+
+## Research Process
+
+### Phase 1: Need Analysis
+
+Before searching, define what you actually need:
+
+```
+Need: {one-sentence description of the capability}
+Constraints: {runtime, bundle size, license, zero-dep requirement}
+Must-haves: {non-negotiable requirements}
+Nice-to-haves: {optional features}
+```
+
+### Phase 2: Search
+
+Delegate research to an Explore subagent to keep main session context clean.
+
+**Spawn an Explore agent** with this prompt template:
+
+```
+Task(subagent_type="Explore"):
+"Research existing solutions for: {need description}
+
+Search for:
+1. npm/PyPI/crates packages that solve this (check package.json/requirements.txt for ecosystem)
+2. Existing utilities in this codebase (grep for related function names)
+3. Framework built-ins that already handle this
+
+For each candidate, find:
+- Package name and weekly downloads (if applicable)
+- Last publish date and maintenance status
+- Bundle size / dependency count
+- API surface relevant to our need
+- License compatibility
+
+Return top 3 candidates with pros/cons, or confirm nothing suitable exists."
+```
+
+### Phase 3: Evaluate
+
+Score each candidate against evaluation criteria. See `references/evaluation-criteria.md` for the full matrix.
+
+Quick checklist:
+- [ ] Last published within 12 months
+- [ ] Weekly downloads > 1,000 (npm) or equivalent traction
+- [ ] No known vulnerabilities (check Snyk/npm audit)
+- [ ] API fits the use case without heavy wrapping
+- [ ] License compatible with project (MIT/Apache/BSD preferred)
+- [ ] Bundle size acceptable for the project context
+
+### Phase 4: Decide
+
+Choose one of four outcomes:
+
+| Decision | When | Action |
+|----------|------|--------|
+| **Adopt** | Exact match, well-maintained, good API | Install and use directly |
+| **Extend** | Partial match, needs thin wrapper | Install + write minimal adapter |
+| **Compose** | No single package fits, but 2-3 small ones combine well | Install multiple, write glue code |
+| **Build** | Nothing fits, or dependency cost exceeds value | Write custom, document why |
+
+**Document the decision** in a code comment at the usage site:
+
+```typescript
+// search-first: Adopted date-fns for date formatting (2M weekly downloads, 30KB)
+// search-first: Built custom — no package handles our specific wire format
+```
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Correct Approach |
+|-------------|-----------------|
+| Adding a dependency for 5 lines of trivial code | Build — dependency overhead exceeds value |
+| Choosing the most popular package without checking fit | Evaluate API fit, not just popularity |
+| Wrapping a package so heavily it obscures the original | If wrapping > 50% of original API, reconsider |
+| Skipping research because "I know how to build this" | Research anyway — maintenance cost matters more than initial build |
+| Installing a massive framework for one utility function | Look for focused, single-purpose packages |
+
+## Scope Limiter
+
+This skill concerns **utility and infrastructure code** only:
+- Data transformation, validation, formatting
+- Network operations, retries, caching
+- CLI tooling, logging, configuration
+- Test utilities and helpers
+
+It does NOT apply to **domain-specific business logic** where:
+- The logic encodes unique business rules
+- No generic solution could exist
+- The code is inherently project-specific

package/shared/skills/search-first/references/evaluation-criteria.md

@@ -0,0 +1,101 @@
+# Search-First — Evaluation Criteria
+
+Detailed package evaluation criteria and decision matrix for the 4-outcome model.
+
+## Evaluation Matrix
+
+Score each candidate on these axes (1-5 scale):
+
+| Criterion | Weight | 1 (Poor) | 3 (Acceptable) | 5 (Excellent) |
+|-----------|--------|-----------|-----------------|----------------|
+| **Maintenance** | High | No commits in 2+ years | Active, yearly releases | Regular releases, responsive maintainer |
+| **Adoption** | Medium | < 100 weekly downloads | 1K-10K weekly downloads | > 100K weekly downloads |
+| **API Fit** | High | Needs heavy wrapping | Partial fit, thin adapter needed | Direct use, clean API |
+| **Bundle Size** | Medium | > 500KB | 50-500KB | < 50KB |
+| **Security** | High | Known vulnerabilities | No known issues, few dependencies | Audited, zero/minimal dependencies |
+| **License** | Required | GPL/AGPL (restrictive) | LGPL (conditional) | MIT/Apache/BSD (permissive) |
+
+**Minimum thresholds**: License must be compatible. Security must be ≥ 3. All others are trade-offs.
+
+## Decision Matrix
+
+### Adopt (score ≥ 20/25, API Fit ≥ 4)
+
+The package directly solves the problem with minimal integration code.
+
+**Example**: Using `zod` for schema validation — exact fit, massive adoption, tiny bundle.
+
+```
+✅ Adopt: zod v3.22
+- Maintenance: 5 (monthly releases)
+- Adoption: 5 (4M weekly downloads)
+- API Fit: 5 (direct use for all validation)
+- Bundle Size: 4 (57KB)
+- Security: 5 (zero dependencies)
+- Total: 24/25
+```
+
+### Extend (score ≥ 15/25, API Fit ≥ 2)
+
+The package handles 60-80% of the need. Write a thin adapter for the rest.
+
+**Example**: Using `got` for HTTP but wrapping it with project-specific retry and auth logic.
+
+```
+✅ Extend: got v14
+- Maintenance: 4 (active)
+- Adoption: 5 (8M weekly downloads)
+- API Fit: 3 (need custom retry wrapper)
+- Bundle Size: 3 (150KB)
+- Security: 4 (minimal deps)
+- Total: 19/25
+Adapter: ~30 lines wrapping retry + auth headers
+```
+
+### Compose (no single package fits, but small packages combine)
+
+Two or three focused packages together solve the problem better than one large framework.
+
+**Example**: `ms` (time parsing) + `p-retry` (retry logic) + `quick-lru` (caching) instead of a monolithic HTTP client framework.
+
+**Rules for Compose**:
+- Maximum 3 packages in a composition
+- Each package must be focused (single responsibility)
+- Total combined bundle < what a monolithic alternative would cost
+- Glue code should be < 50 lines
+
+### Build (nothing fits, or dependency cost > value)
+
+Write custom code when:
+- No package scores ≥ 15/25
+- The code is < 50 lines and trivial
+- Zero-dependency constraint is explicit
+- The domain is too specific for generic packages
+
+**Required**: Document why Build was chosen:
+
+```typescript
+// search-first: Built custom — our wire format uses non-standard
+// ISO-8601 extensions that no date library handles correctly.
+// Evaluated: date-fns (no custom format support), luxon (500KB overhead),
+// dayjs (close but missing timezone edge case).
+```
+
+## Ecosystem-Specific Hints
+
+### Node.js / TypeScript
+- Check npm: `https://www.npmjs.com/package/{name}`
+- Bundle size: `https://bundlephobia.com/package/{name}`
+- Check if Node.js built-ins handle it (`node:crypto`, `node:url`, `node:path`)
+
+### Python
+- Check PyPI: `https://pypi.org/project/{name}`
+- Check if stdlib handles it (`urllib`, `json`, `pathlib`, `dataclasses`)
+
+### Rust
+- Check crates.io: `https://crates.io/crates/{name}`
+- Check if std handles it
+
+### Go
+- Check pkg.go.dev
+- Go standard library is extensive — check stdlib first

package/shared/skills/test-driven-development/SKILL.md

@@ -91,7 +91,7 @@ See `references/rationalization-prevention.md` for extended examples with code.
 
 ## Process Enforcement
 
-When implementing any feature under ambient BUILD/GUIDED:
+When implementing any feature under ambient IMPLEMENT/GUIDED or IMPLEMENT/ORCHESTRATED:
 
 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
@@ -130,7 +130,8 @@ When skipping TDD, never rationalize. State clearly: "Skipping TDD because: [spe
 
 ## Integration with Ambient Mode
 
-- **BUILD/GUIDED** → TDD enforced. Every new function/method gets test-first treatment.
-- **BUILD/QUICK** → TDD skipped (trivial single-file edit).
-- **BUILD/ELEVATE** → TDD mentioned in nudge toward `/implement`.
-- **DEBUG/GUIDED** → TDD applies to the fix: write a test that reproduces the bug first, then fix.
+- **IMPLEMENT/GUIDED** → TDD enforced in main session. Write the failing test before production code. Skill loaded directly.
+- **IMPLEMENT/ORCHESTRATED** → TDD enforced via Coder agent (skill in Coder frontmatter). Every implementation gets test-first treatment.
+- **IMPLEMENT/QUICK** → TDD skipped (trivial single-file edit).
+- **DEBUG/GUIDED** → TDD applies to the fix in main session: write a test that reproduces the bug first, then fix.
+- **DEBUG/ORCHESTRATED** → TDD applies to the fix: write a test that reproduces the bug first, then fix.

package/plugins/devflow-ambient/commands/ambient.md

@@ -1,110 +0,0 @@
----
-description: Ambient mode — classify intent and auto-load relevant skills for any prompt
----
-
-# Ambient Command
-
-Classify user intent and auto-load relevant skills. No agents spawned — enhances the main session only.
-
-## Usage
-
-```
-/ambient <prompt>           Classify and respond with skill enforcement
-/ambient                    Show usage
-```
-
-## Phases
-
-### Phase 1: Load Router
-
-Read the `ambient-router` skill:
-- `~/.claude/skills/ambient-router/SKILL.md`
-
-### Phase 2: Classify
-
-Apply the ambient-router classification to `$ARGUMENTS`:
-
-1. **Intent:** BUILD | DEBUG | REVIEW | PLAN | EXPLORE | CHAT
-2. **Depth:** QUICK | GUIDED | ELEVATE
-
-If no arguments provided, output:
-
-```
-## Ambient Mode
-
-Classify intent and auto-load relevant skills.
-
-Usage: /ambient <your prompt>
-
-Examples:
-  /ambient add a login form          → BUILD/GUIDED (loads TDD + implementation-patterns)
-  /ambient fix the auth error        → DEBUG/GUIDED (loads test-patterns + core-patterns)
-  /ambient where is the config?      → EXPLORE/QUICK (responds normally)
-  /ambient refactor the auth system  → BUILD/ELEVATE (suggests /implement)
-
-Always-on: devflow ambient --enable
-```
-
-Then stop.
-
-### Phase 3: State Classification
-
-- **QUICK:** Skip this phase entirely. Respond directly in Phase 4.
-- **GUIDED:** Output one line: `Ambient: {INTENT}/{DEPTH}. Loading: {skill1}, {skill2}.`
-- **ELEVATE:** Skip — recommendation happens in Phase 4.
-
-### Phase 4: Apply
-
-**QUICK:**
-Respond to the user's prompt normally. Zero skill loading. Zero overhead.
-
-**GUIDED:**
-Read the selected skills based on the ambient-router's skill selection matrix:
-
-| Intent | Primary Skills | Secondary (conditional) |
-|--------|---------------|------------------------|
-| BUILD | test-driven-development, implementation-patterns | typescript (.ts), react (.tsx), frontend-design (CSS/UI), input-validation (forms/API), security-patterns (auth/crypto) |
-| DEBUG | test-patterns, core-patterns | git-safety (if git ops) |
-| REVIEW | self-review, core-patterns | test-patterns |
-| PLAN | implementation-patterns | core-patterns |
-
-Read up to 3 skills from `~/.claude/skills/{name}/SKILL.md`. Apply their patterns and constraints when responding to the user's prompt.
-
-For BUILD intent: enforce RED-GREEN-REFACTOR from test-driven-development. Write failing tests before production code.
-
-**ELEVATE:**
-Respond to the user's prompt with your best effort, then append:
-
-> This task spans multiple files/systems. Consider `/implement` for full lifecycle management (exploration → planning → implementation → review).
-
-## Architecture
-
-```
-/ambient <prompt> (main session, no agents)
-│
-├─ Phase 1: Load ambient-router skill
-├─ Phase 2: Classify intent + depth
-├─ Phase 3: State classification (GUIDED only)
-└─ Phase 4: Apply
-   ├─ QUICK → respond directly
-   ├─ GUIDED → load 2-3 skills, apply patterns, respond
-   └─ ELEVATE → respond + workflow nudge
-```
-
-## Edge Cases
-
-| Case | Handling |
-|------|----------|
-| No arguments | Show usage and stop |
-| Single word ("help") | Classify — likely CHAT/QUICK |
-| Prompt references `/implement` etc. | Classify as normal — user chose /ambient intentionally |
-| Mixed intent ("fix and add test") | Use higher-overhead intent (BUILD > DEBUG) |
-| User says "no enforcement" | Respect immediately — treat as QUICK |
-
-## Principles
-
-1. **No agents** — Ambient enhances the main session, never spawns subagents
-2. **Proportional** — QUICK gets zero overhead, GUIDED gets 2-3 skills, ELEVATE gets a nudge
-3. **Transparent** — State classification for GUIDED/ELEVATE, silent for QUICK
-4. **Respectful** — Never over-classify; when in doubt, go one tier lower
-5. **TDD for BUILD** — GUIDED depth BUILD tasks enforce test-first workflow