devflow-kit 0.9.0 → 1.1.0

package/shared/skills/agent-teams/references/communication.md

@@ -0,0 +1,122 @@
+# Communication Protocols
+
+## Message Types
+
+### Direct Message (one-to-one)
+
+Use when challenging a specific teammate's finding:
+
+```
+To [Security Reviewer]:
+"Your finding about SQL injection at api/users.ts:42 - I disagree.
+The parameterized query at line 45 handles this. Check the query builder
+pattern used throughout this codebase."
+```
+
+### Broadcast (one-to-all)
+
+Use when sharing findings that affect all teammates:
+
+```
+Broadcast:
+"I found that the auth middleware is bypassed for /api/internal/* routes.
+This affects security, architecture, and testing perspectives."
+```
+
+---
+
+## Debate Protocol
+
+### Round Structure
+
+```
+Round 1: Initial findings (each teammate shares top findings)
+Round 2: Challenge round (teammates dispute or validate)
+Round 3: Resolution (update, withdraw, or escalate)
+```
+
+**Cap: 2 challenge exchanges per topic.** If unresolved, escalate to lead.
+
+### Challenge Format
+
+When challenging another teammate:
+
+```
+CHALLENGE to [Teammate]:
+- Finding: [what they claimed]
+- Evidence against: [your counter-evidence with file:line references]
+- Suggested resolution: [what you think is correct]
+```
+
+### Concession Format
+
+When accepting a challenge:
+
+```
+UPDATED based on [Teammate]'s challenge:
+- Original: [what I originally claimed]
+- Revised: [updated finding incorporating their evidence]
+```
+
+### Escalation Format
+
+When debate is unresolved after 2 exchanges:
+
+```
+ESCALATION to Lead:
+- Topic: [what we disagree about]
+- Position A: [first perspective with evidence]
+- Position B: [second perspective with evidence]
+- Recommendation: [which has stronger evidence, or "genuinely split"]
+```
+
+---
+
+## Lead Coordination Messages
+
+### Initiating Debate
+
+```
+Lead broadcast:
+"All teammates: Share your top 3-5 findings. After sharing, challenge
+any finding you disagree with. Provide evidence (file:line references).
+You have 2 exchange rounds to resolve disagreements."
+```
+
+### Ending Debate
+
+```
+Lead broadcast:
+"Debate round complete. Submit final findings with confidence levels:
+- HIGH: Unanimous or unchallenged with evidence
+- MEDIUM: Majority agreed, dissent noted
+- LOW: Split opinion, both perspectives included"
+```
+
+### Requesting Clarification
+
+```
+Lead to [Teammate]:
+"Your finding about X contradicts [Other Teammate]'s finding about Y.
+Can you address their evidence at [file:line]?"
+```
+
+---
+
+## Output Aggregation
+
+### Consensus Report Structure
+
+```markdown
+## Confirmed Findings (HIGH confidence)
+[Findings all teammates agreed on or that survived challenge]
+
+## Majority Findings (MEDIUM confidence)
+[Findings most agreed on, with dissenting view noted]
+
+## Split Findings (LOW confidence)
+[Genuinely contested findings with both perspectives and evidence]
+
+## Withdrawn Findings
+[Findings that were disproved during debate]
+```

package/shared/skills/agent-teams/references/team-patterns.md

@@ -0,0 +1,217 @@
+# Team Patterns by Workflow
+
+## Task-Based Coordination
+
+All team workflows should use the shared task list for structured progress tracking:
+
+```
+1. Lead creates team
+2. Lead creates tasks (TaskCreate) for each teammate's work unit
+3. Lead spawns teammates, assigning tasks via TaskUpdate(owner)
+4. Teammates work, mark tasks completed via TaskUpdate(status: completed)
+5. Lead checks TaskList before proceeding to next phase
+6. Lead shuts down teammates, calls TeamDelete
+```
+
+**Example task creation for a review team:**
+
+```
+TaskCreate: "Security review of auth module" → assigned to Security Reviewer
+TaskCreate: "Architecture review of auth module" → assigned to Architecture Reviewer
+TaskCreate: "Performance review of auth module" → assigned to Performance Reviewer
+```
+
+---
+
+## Review Team
+
+### Standard Review (4 perspectives)
+
+```
+Lead spawns:
+├── Security reviewer    → vulnerabilities, injection, auth, crypto
+├── Architecture reviewer → SOLID, coupling, layering, modularity
+├── Performance reviewer  → queries, algorithms, caching, I/O
+└── Quality reviewer      → complexity, tests, consistency, naming
+```
+
+### Extended Review (add conditionally)
+
+```
+Additional teammates based on changed files:
+├── TypeScript reviewer  → type safety, generics (if .ts/.tsx changed)
+├── React reviewer       → hooks, state, rendering (if .tsx/.jsx changed)
+├── Database reviewer    → schema, queries, migrations (if DB files changed)
+└── Dependencies reviewer → CVEs, versions, licenses (if package files changed)
+```
+
+### Review Debate Flow
+
+```
+1. Each reviewer analyzes independently
+2. Lead broadcasts: "Share top 3 findings and challenge others"
+3. Security challenges architecture: "This coupling creates attack surface"
+4. Architecture challenges performance: "Your caching suggestion breaks separation"
+5. Quality validates: "Tests don't cover the security concern raised"
+6. Lead collects consensus after max 2 exchange rounds
+```
+
+---
+
+## Implementation Team
+
+### Exploration Team (4 perspectives)
+
+```
+Lead spawns:
+├── Architecture explorer  → existing patterns, module structure
+├── Integration explorer   → entry points, services, config
+├── Reusable code explorer → utilities, helpers, shared logic
+└── Edge case explorer     → error conditions, boundaries, race conditions
+```
+
+### Planning Team (3 perspectives)
+
+```
+Lead spawns:
+├── Implementation planner → step-by-step coding approach
+├── Testing planner        → test strategy and coverage plan
+└── Risk planner           → potential issues, rollback strategy
+```
+
+### Implementation Debate
+
+```
+1. Explorers share findings
+2. Architecture challenges edge cases: "This boundary isn't handled"
+3. Integration challenges reusable code: "That helper doesn't cover our case"
+4. Lead synthesizes consensus exploration
+
+5. Planners propose approaches
+6. Testing challenges implementation: "This approach is untestable"
+7. Risk challenges both: "Rollback is impossible with this migration"
+8. Lead synthesizes consensus plan
+```
+
+---
+
+## Specification Team
+
+### Requirements Exploration Team (4 perspectives)
+
+```
+Lead spawns:
+├── User Perspective Explorer  → target users, goals, pain points, user journeys
+├── Similar Features Explorer  → comparable features, scope patterns, precedents
+├── Constraints Explorer       → dependencies, business rules, security, performance
+└── Failure Mode Explorer      → error states, edge cases, validation needs
+```
+
+### Requirements Debate Flow
+
+```
+1. Each explorer shares findings from their perspective
+2. Constraints challenges user perspective: "This requirement conflicts with X constraint"
+3. Failure modes challenges similar features: "That pattern failed in Y scenario"
+4. Similar features validates user perspective: "This UX pattern works well in Z"
+5. Lead collects consensus after max 2 exchange rounds
+```
+
+### Scope Planning Team (3 perspectives)
+
+```
+Lead spawns:
+├── User Stories Planner       → actors, actions, outcomes ("As X, I want Y, so that Z")
+├── Scope Boundaries Planner   → v1 MVP, v2 deferred, out of scope, dependencies
+└── Acceptance Criteria Planner → success/failure/edge case criteria (testable)
+```
+
+### Scope Debate Flow
+
+```
+1. Each planner presents their analysis
+2. Scope challenges user stories: "This story is too broad for v1"
+3. Acceptance challenges scope: "These boundaries leave this edge case uncovered"
+4. User stories challenges acceptance: "This criterion is untestable"
+5. Lead collects consensus after max 2 exchange rounds
+```
+
+**Note**: Specification teams complement (not replace) the 3 mandatory clarification gates. User still drives all decisions via Gate 0, Gate 1, and Gate 2.
+
+---
+
+## Resolution Team
+
+### Cross-Validation Resolution Team
+
+```
+Lead spawns resolvers based on batches:
+├── Resolver A → Batch 1 issues (file-a cluster)
+├── Resolver B → Batch 2 issues (file-b cluster)
+└── Resolver C → Batch 3 issues (file-c cluster)
+```
+
+### Resolution Debate Flow
+
+```
+1. Each resolver independently validates + fixes their batch
+2. Lead broadcasts: "Review each other's fixes for cross-batch conflicts"
+3. Resolver A: "My fix in file-a.ts changes the interface that Resolver B depends on"
+4. Resolver B: "Confirmed — my fix in file-b.ts imports from that interface"
+5. Resolvers coordinate the fix or escalate conflict to lead
+6. Lead collects consensus after max 2 exchange rounds
+```
+
+### When Cross-Validation Adds Value
+
+- Fixes touch shared interfaces or types
+- Resolvers modify files that import from each other
+- Batch fixes could introduce conflicting patterns
+- Large resolution sets (>5 issues across multiple files)
+
+### When to Skip Cross-Validation
+
+- All fixes are in completely independent files
+- Only 1-2 batches with no shared dependencies
+- Fixes are trivial (typos, formatting, naming)
+
+---
+
+## Debug Team
+
+### Hypothesis Investigation (3-5 hypotheses)
+
+```
+Lead spawns (one per hypothesis):
+├── Hypothesis A investigator → state management / race condition
+├── Hypothesis B investigator → configuration / environment
+├── Hypothesis C investigator → edge case / input validation
+└── Hypothesis D investigator → dependency / version issue
+```
+
+### Debug Debate Flow
+
+```
+1. Each investigator gathers evidence for their hypothesis
+2. Lead broadcasts: "Present evidence. Disprove each other."
+3. Investigator A: "Found race condition at file:line"
+4. Investigator B: "My config theory is disproved by A's evidence"
+5. Investigator C: "A's race condition doesn't explain the timing"
+6. Converge on surviving hypothesis with strongest evidence
+```
+
+---
+
+## Team Size Guidelines
+
+| Scenario | Min | Max | Rationale |
+|----------|-----|-----|-----------|
+| Quick review | 2 | 3 | Focused, low cost |
+| Full review | 4 | 5 | Core perspectives |
+| Exploration | 3 | 4 | Diminishing returns beyond 4 |
+| Planning | 2 | 3 | Too many cooks |
+| Specification (explore) | 3 | 4 | Requirements need diverse perspectives |
+| Specification (scope) | 2 | 3 | Scope planning benefits from focus |
+| Resolution | 2 | 4 | One per independent batch |
+| Debugging | 3 | 5 | One per viable hypothesis |
+| Parallel coding | 2 | 3 | Merge complexity grows fast |

package/shared/skills/ambient-router/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: ambient-router
+description: >-
+  Classify user intent and response depth for ambient mode. Auto-loads relevant
+  skills without explicit command invocation. Used by /ambient command and
+  always-on UserPromptSubmit hook.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+---
+
+# Ambient Router
+
+Classify user intent and auto-load relevant skills. Zero overhead for simple requests, skill injection for substantive work, workflow nudges for complex tasks.
+
+## Iron Law
+
+> **PROPORTIONAL RESPONSE**
+>
+> Match effort to intent. Never apply heavyweight processes to lightweight requests.
+> A chat question gets zero overhead. A 3-file feature gets 2-3 skills. A system
+> refactor gets a nudge toward `/implement`. Misclassification in either direction
+> is a failure.
+
+---
+
+## Step 1: Classify Intent
+
+Determine what the user is trying to do from their prompt.
+
+| Intent | Signal Words / Patterns | Examples |
+|--------|------------------------|---------|
+| **BUILD** | "add", "create", "implement", "build", "write", "make" | "add a login form", "create an API endpoint" |
+| **DEBUG** | "fix", "bug", "broken", "failing", "error", "why does" | "fix the auth error", "why is this test failing" |
+| **REVIEW** | "check", "look at", "review", "is this ok", "any issues" | "check this function", "any issues with this?" |
+| **PLAN** | "how should", "design", "architecture", "approach", "strategy" | "how should I structure auth?", "what's the approach for caching?" |
+| **EXPLORE** | "what is", "where is", "find", "show me", "explain", "how does" | "where is the config?", "explain this function" |
+| **CHAT** | greetings, meta-questions, confirmations, short responses | "thanks", "yes", "what can you do?" |
+
+**Ambiguous prompts:** Default to the lowest-overhead classification. "Update the README" → BUILD/STANDARD. Git operations like "commit this" → QUICK.
+
+## Step 2: Classify Depth
+
+Determine how much enforcement the prompt warrants.
+
+| Depth | Criteria | Action |
+|-------|----------|--------|
+| **QUICK** | CHAT intent. EXPLORE with no analytical depth ("where is X?"). Git/devops operations (commit, push, merge, branch, pr, deploy, reinstall). Single-word continuations. | Respond normally. Zero overhead. Do not state classification. |
+| **STANDARD** | BUILD/DEBUG/REVIEW/PLAN intent (any word count). EXPLORE with analytical depth ("analyze our X", "discuss how Y works"). | Read and apply 2-3 relevant skills from the selection matrix below. State classification briefly. |
+| **ESCALATE** | Multi-file architectural change, system-wide scope, > 5 files. Detailed implementation plan (100+ words with plan structure). | Respond at best effort + recommend: "This looks like it would benefit from `/implement` for full lifecycle management." |
+
+## Step 3: Select Skills (STANDARD depth only)
+
+Based on classified intent, read the following skills to inform your response.
+
+| Intent | Primary Skills | Secondary (if file type matches) |
+|--------|---------------|----------------------------------|
+| **BUILD** | test-driven-development, implementation-patterns | typescript (.ts), react (.tsx/.jsx), frontend-design (CSS/UI), input-validation (forms/API), security-patterns (auth/crypto) |
+| **DEBUG** | test-patterns, core-patterns | git-safety (if git operations involved) |
+| **REVIEW** | self-review, core-patterns | test-patterns |
+| **PLAN** | implementation-patterns | core-patterns |
+
+**Excluded from ambient** (review-command-only): review-methodology, complexity-patterns, consistency-patterns, database-patterns, dependencies-patterns, documentation-patterns, regression-patterns, architecture-patterns, accessibility.
+
+See `references/skill-catalog.md` for the full skill-to-intent mapping with file pattern triggers.
+
+## Step 4: Apply
+
+- **QUICK:** Respond directly. No preamble, no classification statement.
+- **STANDARD:** State classification briefly: `Ambient: BUILD/STANDARD. Loading: test-driven-development, implementation-patterns.` Then read the selected skills and apply their patterns to your response. For BUILD intent, enforce RED-GREEN-REFACTOR from test-driven-development.
+- **ESCALATE:** Respond with your best effort, then append: `> This task spans multiple files/systems. Consider \`/implement\` for full lifecycle (exploration → planning → implementation → review).`
+
+---
+
+## Transparency Rules
+
+1. **QUICK → silent.** No classification output.
+2. **STANDARD → brief statement.** One line: intent, depth, skills loaded.
+3. **ESCALATE → recommendation.** Best-effort response + workflow nudge.
+4. **Never lie about classification.** If uncertain, say so.
+5. **Never over-classify.** When in doubt, go one tier lower.
+
+## Edge Cases
+
+| Case | Handling |
+|------|----------|
+| Mixed intent ("fix this bug and add a test") | Use the higher-overhead intent (BUILD > DEBUG) |
+| Continuation of previous conversation | Inherit previous classification unless prompt clearly shifts |
+| User explicitly requests no enforcement | Respect immediately — classify as QUICK |
+| Prompt references specific DevFlow command | Skip ambient — the command has its own orchestration |

package/shared/skills/ambient-router/references/skill-catalog.md

@@ -0,0 +1,64 @@
+# Ambient Router — Skill Catalog
+
+Full mapping of DevFlow skills to ambient intents and file-type triggers. The ambient-router SKILL.md references this for detailed selection logic.
+
+## Skills Available for Ambient Loading
+
+These skills may be loaded during STANDARD-depth ambient routing.
+
+### BUILD Intent
+
+| Skill | When to Load | File Patterns |
+|-------|-------------|---------------|
+| test-driven-development | Always for BUILD | `*.ts`, `*.tsx`, `*.js`, `*.jsx`, `*.py` |
+| implementation-patterns | Always for BUILD | Any code file |
+| typescript | TypeScript files in scope | `*.ts`, `*.tsx` |
+| react | React components in scope | `*.tsx`, `*.jsx` |
+| frontend-design | UI/styling work | `*.css`, `*.scss`, `*.tsx` with styling keywords |
+| input-validation | Forms, APIs, user input | Files with form/input/validation keywords |
+| security-patterns | Auth, crypto, secrets | Files with auth/token/crypto/password keywords |
+
+### DEBUG Intent
+
+| Skill | When to Load | File Patterns |
+|-------|-------------|---------------|
+| test-patterns | Always for DEBUG | Any test-related context |
+| core-patterns | Always for DEBUG | Any code file |
+| git-safety | Git operations involved | User mentions git, rebase, merge, etc. |
+
+### REVIEW Intent
+
+| Skill | When to Load | File Patterns |
+|-------|-------------|---------------|
+| self-review | Always for REVIEW | Any code file |
+| core-patterns | Always for REVIEW | Any code file |
+| test-patterns | Test files in scope | `*.test.*`, `*.spec.*` |
+
+### PLAN Intent
+
+| Skill | When to Load | File Patterns |
+|-------|-------------|---------------|
+| implementation-patterns | Always for PLAN | Any planning context |
+| core-patterns | Architectural planning | System design discussions |
+
+## Skills Excluded from Ambient
+
+These skills are loaded only by explicit DevFlow commands (primarily `/code-review`):
+
+- review-methodology — Full review process (6-step, 3-category classification)
+- complexity-patterns — Cyclomatic complexity, deep nesting analysis
+- consistency-patterns — Naming convention, pattern deviation detection
+- database-patterns — Index analysis, query optimization, migration safety
+- dependencies-patterns — CVE detection, license audit, outdated packages
+- documentation-patterns — Doc drift, stale comments, missing API docs
+- regression-patterns — Lost functionality, broken exports, behavioral changes
+- architecture-patterns — SOLID analysis, coupling detection, layering issues
+- accessibility — WCAG compliance, ARIA roles, keyboard navigation
+- performance-patterns — N+1 queries, memory leaks, caching opportunities
+
+## Selection Limits
+
+- **Maximum 3 skills** per ambient response (primary + up to 2 secondary)
+- **Primary skills** are always loaded for the classified intent
+- **Secondary skills** are loaded only when file patterns match conversation context
+- If more than 3 skills seem relevant, this is an ESCALATE signal

package/shared/skills/architecture-patterns/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: architecture-patterns
+description: Architecture analysis patterns for code review. Detects SOLID violations, tight coupling, layering issues, and dependency direction problems. Loaded by Reviewer agent when focus=architecture.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+---
+
+# Architecture Patterns
+
+Domain expertise for software architecture and design pattern analysis. Use alongside `review-methodology` for complete architecture reviews.
+
+## Iron Law
+
+> **SEPARATION OF CONCERNS IS NON-NEGOTIABLE**
+>
+> Every module has one reason to change. Every layer has clear boundaries. Every dependency
+> points in one direction. Violations compound into unmaintainable systems.
+
+---
+
+## Architecture Categories
+
+### 1. SOLID Violations
+
+**Single Responsibility (SRP)**: One class, one reason to change.
+```typescript
+// VIOLATION: Handles HTTP, validation, DB, email
+class UserController {
+  async createUser(req, res) {
+    if (!req.body.email.includes('@')) throw new Error('Invalid');
+    const user = await db.users.create(req.body);
+    await sendEmail(user.email, 'Welcome!');
+    res.json(user);
+  }
+}
+// CORRECT: Separate concerns via injected services
+```
+
+**Open/Closed (OCP)**: Extend without modifying.
+```typescript
+// VIOLATION: Adding type = modifying
+if (type === 'regular') return amount * 0.1;
+if (type === 'premium') return amount * 0.2;
+
+// CORRECT: Strategy pattern
+interface DiscountStrategy { calculate(amount: number): number; }
+```
+
+**Liskov Substitution (LSP)**: Subtypes must be substitutable.
+```typescript
+// VIOLATION: Subclass breaks contract
+class Square extends Rectangle { setWidth(w) { this.width = this.height = w; } }
+
+// CORRECT: Use composition/proper abstraction
+interface Shape { area(): number; }
+```
+
+**Interface Segregation (ISP)**: No forced unused implementations.
+```typescript
+// VIOLATION: Robot forced to implement eat()
+interface Worker { work(); eat(); sleep(); }
+
+// CORRECT: Segregated interfaces
+interface Workable { work(): void; }
+```
+
+**Dependency Inversion (DIP)**: Depend on abstractions.
+```typescript
+// VIOLATION: Concrete dependency
+class OrderService { private db = new PostgresDatabase(); }
+
+// CORRECT: Inject interface
+class OrderService { constructor(private repo: OrderRepository) {} }
+```
+
+### 2. Coupling Issues
+
+**Tight Coupling**: Direct instantiation creates coupling.
+```typescript
+// VIOLATION
+class ReportGenerator {
+  generate() { new DatabaseService().query('SELECT...'); }
+}
+// CORRECT: Inject dependencies via constructor
+```
+
+**Circular Dependencies**: A imports B, B imports A. Extract shared concern or use events.
+
+**Feature Envy**: Method uses another class's data excessively. Move behavior to data owner.
+
+### 3. Layering Violations
+
+**Skipping Layers**: Controller directly accessing database.
+```typescript
+// VIOLATION: Controller -> DB (skips service)
+const user = await db.query('SELECT...', [req.params.id]);
+
+// CORRECT: Controller -> Service -> Repository
+const user = await this.userService.findById(req.params.id);
+```
+
+**Leaky Abstractions**: Infrastructure details in domain.
+```typescript
+// VIOLATION: Domain exposes MongoDB internals
+interface User { id: string; _mongoId: ObjectId; __v: number; }
+
+// CORRECT: Clean domain, map in repository
+interface User { id: string; name: string; }
+```
+
+**Wrong Direction**: Domain must not import infrastructure. Infrastructure implements domain interfaces.
+
+### 4. Modularity Issues
+
+**God Class**: Class does everything. Split into bounded contexts.
+
+**Inappropriate Intimacy**: Class knows internals of another. Use "tell, don't ask."
+
+---
+
+## Extended References
+
+For detailed examples and detection patterns:
+
+- `references/solid.md` - Extended SOLID violation examples with full fixes
+- `references/coupling.md` - Circular dependencies, feature envy, tight coupling
+- `references/layering.md` - Layer skipping, leaky abstractions, wrong direction
+- `references/detection.md` - Grep patterns and bash commands for automated detection
+
+---
+
+## Severity Guidelines
+
+| Severity | Examples |
+|----------|----------|
+| **CRITICAL** | Circular dependencies, domain depends on infrastructure, god classes 1000+ lines |
+| **HIGH** | SOLID violations in core logic, tight coupling between services, leaky abstractions |
+| **MEDIUM** | Dependencies not injected, minor layering violations, missing interfaces |
+| **LOW** | Naming issues, minor organization, missing architecture docs |
+
+---
+
+## Architecture Principles Reference
+
+| Principle | Violation Sign | Fix Pattern |
+|-----------|----------------|-------------|
+| SRP | Multiple reasons to change | Extract classes |
+| OCP | Modifying to add features | Strategy/plugin pattern |
+| LSP | Subclass throws "not supported" | Composition over inheritance |
+| ISP | Unused interface methods | Split interfaces |
+| DIP | `new ConcreteClass()` in business | Inject via constructor |
+| DRY | Copy-paste code blocks | Extract to shared module |
+| YAGNI | Premature abstractions | Remove until needed |