@amrhas82/agentic-kit 1.5.0 → 1.7.5

package/packages/droid/commands/brainstorming.md

@@ -1,11 +1,18 @@
 ---
-description: Turn rough ideas into fully-formed designs through collaborative questioning and exploration
-argument-hint: <topic-or-idea>
+id: brainstorming
+name: brainstorming
+description: Use when creating or developing, before writing code or implementation plans - refines rough ideas into fully-formed designs through collaborative questioning, alternative exploration, and incremental validation. Don't use during clear 'mechanical' processes
+usage: /brainstorming <session-type> <topic>
+auto_trigger: false
 ---
 
+# Brainstorming Ideas Into Designs
+
+## Overview
+
 Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
 
-Start by understanding the current project context, then ask questions one at a time to refine the idea: $ARGUMENTS. Once you understand what you're building, present the design in small sections (200-300 words), checking after each section whether it looks right so far.
+Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design in small sections (200-300 words), checking after each section whether it looks right so far.
 
 ## The Process
 
@@ -32,11 +39,12 @@ Start by understanding the current project context, then ask questions one at a
 
 **Documentation:**
 - Write the validated design to `docs/plans/YYYY-MM-DD-<topic>-design.md`
+- Use elements-of-style:writing-clearly-and-concisely skill if available
 - Commit the design document to git
 
 **Implementation (if continuing):**
 - Ask: "Ready to set up for implementation?"
-- Use git worktrees to create isolated workspace
+- Create isolated workspace (use git worktrees if needed)
 - Create detailed implementation plan
 
 ## Key Principles

package/packages/droid/commands/code-review.md

@@ -1,9 +1,14 @@
 ---
-description: Request structured code review to catch issues before they cascade
-argument-hint: <branch-or-pr-name>
+id: code-review
+name: code-review
+description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements - reviews implementation against plan or requirements before proceeding
+usage: /code-review <review-scope> <focus-areas>
+auto_trigger: false
 ---
 
-Dispatch structured code review to catch issues before they cascade.
+# Requesting Code Review
+
+Review code thoroughly to catch issues before they cascade.
 
 **Core principle:** Review early, review often.
 
@@ -27,42 +32,51 @@ BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
 HEAD_SHA=$(git rev-parse HEAD)
 ```
 
-**2. Review scope:** $ARGUMENTS
-
-**3. Key areas to focus on:**
-
-**Summary & Purpose:**
-- What changed and why it matters
-- Is the implementation aligned with the requirements
-
-**Correctness & Quality:**
-- Logic errors and edge cases
-- Test coverage and test quality
-- Code readability and maintainability
+**2. Conduct code review:**
 
-**Risks & Concerns:**
-- Security implications
-- Performance bottlenecks
-- Breaking changes or migration issues
-- Dependency risks
+Review implementation against requirements and plan
 
-**Architecture & Design:**
-- Code organization and structure
-- Separation of concerns
-- Reusability and extensibility
-- API design consistency
+**Placeholders:**
+- `{WHAT_WAS_IMPLEMENTED}` - What you just built
+- `{PLAN_OR_REQUIREMENTS}` - What it should do
+- `{BASE_SHA}` - Starting commit
+- `{HEAD_SHA}` - Ending commit
+- `{DESCRIPTION}` - Brief summary
 
-**Follow-up Actions:**
-- Concrete TODOs with owners
-- Priority levels (Critical/Important/Minor)
-- Testing requirements
-
-## Act on feedback:
+**3. Act on feedback:**
 - Fix Critical issues immediately
 - Fix Important issues before proceeding
 - Note Minor issues for later
 - Push back if reviewer is wrong (with reasoning)
 
+## Example
+
+```
+[Just completed Task 2: Add verification function]
+
+You: Let me request code review before proceeding.
+
+BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
+HEAD_SHA=$(git rev-parse HEAD)
+
+[Conduct code review]
+  WHAT_WAS_IMPLEMENTED: Verification and repair functions for conversation index
+  PLAN_OR_REQUIREMENTS: Task 2 from docs/plans/deployment-plan.md
+  BASE_SHA: a7981ec
+  HEAD_SHA: 3df7661
+  DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
+
+[Subagent returns]:
+  Strengths: Clean architecture, real tests
+  Issues:
+    Important: Missing progress indicators
+    Minor: Magic number (100) for reporting interval
+  Assessment: Ready to proceed
+
+You: [Fix progress indicators]
+[Continue to Task 3]
+```
+
 ## Integration with Workflows
 
 **Subagent-Driven Development:**
@@ -90,3 +104,5 @@ HEAD_SHA=$(git rev-parse HEAD)
 - Push back with technical reasoning
 - Show code/tests that prove it works
 - Request clarification
+
+See template at: requesting-code-review/code-reviewer.md

package/packages/droid/commands/condition-based-waiting.md

@@ -1,12 +1,34 @@
 ---
-description: Replace arbitrary timeouts with condition polling to eliminate flaky tests from timing guesses
-argument-hint: <condition-to-wait-for>
+id: condition-based-waiting
+name: condition-based-waiting
+description: Use when tests have race conditions, timing dependencies, or inconsistent pass/fail behavior - replaces arbitrary timeouts with condition polling to wait for actual state changes, eliminating flaky tests from timing guesses
+usage: /condition-based-waiting <condition-type> <timeout-specs>
+auto_trigger: false
 ---
 
+# Condition-Based Waiting
+
+## Overview
+
+Flaky tests often guess at timing with arbitrary delays. This creates race conditions where tests pass on fast machines but fail under load or in CI.
+
 **Core principle:** Wait for the actual condition you care about, not a guess about how long it takes.
 
 ## When to Use
 
+```dot
+digraph when_to_use {
+    "Test uses setTimeout/sleep?" [shape=diamond];
+    "Testing timing behavior?" [shape=diamond];
+    "Document WHY timeout needed" [shape=box];
+    "Use condition-based waiting" [shape=box];
+
+    "Test uses setTimeout/sleep?" -> "Testing timing behavior?" [label="yes"];
+    "Testing timing behavior?" -> "Document WHY timeout needed" [label="yes"];
+    "Testing timing behavior?" -> "Use condition-based waiting" [label="no"];
+}
+```
+
 **Use when:**
 - Tests have arbitrary delays (`setTimeout`, `sleep`, `time.sleep()`)
 - Tests are flaky (pass sometimes, fail under load)
@@ -17,9 +39,7 @@ argument-hint: <condition-to-wait-for>
 - Testing actual timing behavior (debounce, throttle intervals)
 - Always document WHY if using arbitrary timeout
 
-## Quick Patterns
-
-Replace timing guesses with condition polling:
+## Core Pattern
 
 ```typescript
 // ❌ BEFORE: Guessing at timing
@@ -27,21 +47,25 @@ await new Promise(r => setTimeout(r, 50));
 const result = getResult();
 expect(result).toBeDefined();
 
-// ✅ AFTER: Waiting for condition  
+// ✅ AFTER: Waiting for condition
 await waitFor(() => getResult() !== undefined);
 const result = getResult();
 expect(result).toBeDefined();
 ```
 
-**Common scenarios:**
-- Wait for event: `waitFor(() => events.find(e => e.type === 'DONE'))`
-- Wait for state: `waitFor(() => machine.state === 'ready')`
-- Wait for count: `waitFor(() => items.length >= 5)`
-- Wait for file: `waitFor(() => fs.existsSync(path))`
-- Complex condition: `waitFor(() => obj.ready && obj.value > 10)`
+## Quick Patterns
+
+| Scenario | Pattern |
+|----------|---------|
+| Wait for event | `waitFor(() => events.find(e => e.type === 'DONE'))` |
+| Wait for state | `waitFor(() => machine.state === 'ready')` |
+| Wait for count | `waitFor(() => items.length >= 5)` |
+| Wait for file | `waitFor(() => fs.existsSync(path))` |
+| Complex condition | `waitFor(() => obj.ready && obj.value > 10)` |
 
 ## Implementation
 
+Generic polling function:
 ```typescript
 async function waitFor<T>(
   condition: () => T | undefined | null | false,
@@ -61,31 +85,11 @@ async function waitFor<T>(
     await new Promise(r => setTimeout(r, 10)); // Poll every 10ms
   }
 }
-
-// Domain-specific helpers
-async function waitForEvent(eventManager: any, eventType: string) {
-  return waitFor(() => 
-    eventManager.events.find((e: any) => e.type === eventType),
-    `event ${eventType}`
-  );
-}
-
-async function waitForEventCount(eventManager: any, eventType: string, count: number) {
-  return waitFor(() => 
-    eventManager.events.filter((e: any) => e.type === eventType).length >= count,
-    `${count} events of type ${eventType}`
-  );
-}
-
-async function waitForEventMatch(eventManager: any, eventType: string, matcher: any) {
-  return waitFor(() => 
-    eventManager.events.find((e: any) => e.type === eventType && matcher(e)),
-    `event ${eventType} matching criteria`
-  );
-}
 ```
 
-## Common Mistakes to Avoid
+See @example.ts for complete implementation with domain-specific helpers (`waitForEvent`, `waitForEventCount`, `waitForEventMatch`) from actual debugging session.
+
+## Common Mistakes
 
 **❌ Polling too fast:** `setTimeout(check, 1)` - wastes CPU
 **✅ Fix:** Poll every 10ms
@@ -112,22 +116,8 @@ await new Promise(r => setTimeout(r, 200));   // Then: wait for timed behavior
 
 ## Real-World Impact
 
-**Benefits:**
-- Fixed 15 flaky tests across multiple files
+From debugging session (2025-10-03):
+- Fixed 15 flaky tests across 3 files
 - Pass rate: 60% → 100%
-- Execution time: 40% faster  
+- Execution time: 40% faster
 - No more race conditions
-
-## Usage Examples
-
-**Wait for async operation:**
-`/condition-based-waiting "database connection established"`
-
-**Wait for UI state:**
-`/condition-based-waiting "login button enabled"`
-
-**Wait for file changes:**
-`/condition-based-waiting "build output file created"`
-
-**Complex condition:**
-`/condition-based-waiting "user authenticated AND profile loaded"`

package/packages/droid/commands/debug.md

@@ -0,0 +1,21 @@
+---
+id: debug
+name: debug
+description: Debug issue [issue]
+usage: /debug <issue-description>
+argument-hint: [description of the problem]
+---
+Debug: $ARGUMENTS
+
+## Process
+1. Clarify: What's expected vs actual behavior?
+2. Reproduce: What triggers the issue?
+3. Isolate: Which component/function is responsible?
+4. Trace: Follow the data flow
+5. Fix: Implement and verify the solution
+
+## Output
+- Root cause
+- Affected code paths
+- Fix with explanation
+- Prevention strategy