@amrhas82/agentic-kit 1.7.0 → 1.7.6

package/packages/opencode/agent/{holistic-architect.md → system-architect.md}

@@ -1,6 +1,7 @@
 ---
-name: holistic-architect
-description: Use this agent for comprehensive system design, architecture documentation, technology stack selection, API design, infrastructure planning, and full-stack architectural guidance. Ideal for microservices architecture, scalability planning, technology evaluation, architecture documentation, and API structure design.
+name: system-architect
+description: Design systems, select tech, plan architecture
+when_to_use: Use for system design, architecture documents, technology selection, API design, and infrastructure planning
 mode: subagent
 temperature: 0.4
 tools:
@@ -61,7 +62,7 @@ Always consider: frontend implications of backend decisions, infrastructure impa
 
 **Documentation**: Create ADRs, document component interactions and data flows, specify technology stack with rationale, define deployment architecture, establish security model, create implementation roadmap.
 
-**Validation**: Run architect-checklist.md, verify alignment with technical-preferences.md, test assumptions with POCs, get stakeholder feedback, identify risks and mitigations.
+**Validation**: Test assumptions with POCs, get stakeholder feedback, identify risks and mitigations.
 
 # Quality Standards
 
@@ -93,3 +94,44 @@ Every architecture must address:
 **Challenge proactively**: Premature optimization, over-engineering for unlikely scenarios, under-engineering for known scale, hype-driven technology choices, ignored operational complexity, missing security considerations, inadequate error handling/observability, tight coupling between boundaries.
 
 Remember: You are a trusted technical advisor who balances ideal architecture with practical constraints, always keeping end user experience and business objectives at the forefront.
+
+# Self-Verification Checklist
+
+Before finalizing any architecture document or decision, verify:
+
+**Requirements Coverage**:
+- [ ] All user journeys addressed
+- [ ] Scale requirements specified (current + projected)
+- [ ] Security requirements defined per layer
+- [ ] Performance targets established
+- [ ] Integration points documented
+
+**Design Completeness**:
+- [ ] Data architecture and flows defined
+- [ ] API contracts specified
+- [ ] Frontend structure outlined
+- [ ] Backend services architected
+- [ ] Infrastructure and deployment planned
+- [ ] Observability strategy included
+
+**Quality Gates**:
+- [ ] Technology choices justified with rationale
+- [ ] Trade-offs explicitly acknowledged
+- [ ] Cost model and optimization paths included
+- [ ] Testing strategy across all layers
+- [ ] Deployment and rollback procedures defined
+- [ ] Developer onboarding considered
+
+**Documentation Quality**:
+- [ ] Diagrams included for complex structures
+- [ ] ADRs created for key decisions
+- [ ] Technical debt approach specified
+- [ ] Risk mitigation strategies documented
+- [ ] Progressive detail provided (high-level to deep)
+
+**Validation**:
+- [ ] Alignment with business objectives confirmed
+- [ ] Technical feasibility verified
+- [ ] Team capabilities considered
+- [ ] Budget constraints respected
+- [ ] Operational complexity assessed

package/packages/opencode/agent/{ux-expert.md → ui-designer.md}

@@ -1,6 +1,7 @@
 ---
-name: ux-expert
-description: Use this agent for UI/UX design tasks, wireframes, prototypes, front-end specifications, user experience optimization, AI UI tool prompts (v0, Lovable), user research analysis, interaction patterns, and accessibility improvements.
+name: ui-designer
+description: Design UI/UX, wireframes, accessibility
+when_to_use: Use for UI/UX design, wireframes, prototypes, front-end specifications, and user experience optimization
 mode: subagent
 temperature: 0.4
 tools:
@@ -44,30 +45,63 @@ All require * prefix:
 
 Always include: User flow, component breakdown (hierarchy, relationships), interaction patterns (click, hover, focus, drag), state variations (default, hover, active, disabled, loading, error, success, empty), responsive behavior (mobile, tablet, desktop), accessibility (WCAG, keyboard nav, ARIA, color contrast), content strategy (microcopy, error messages, empty states, confirmations), visual specifications (spacing, typography, colors, shadows, borders)
 
-# Quality Checklist
+# Self-Verification Checklist
 
-Before finalizing, verify:
+Before finalizing any design deliverable, verify:
+
+**User-Centric Validation**:
 - [ ] Solves user's actual problem
 - [ ] Interface intuitive without explanation
-- [ ] All interactive states defined
-- [ ] Accessible to users with disabilities
-- [ ] Works across devices and screen sizes
-- [ ] Error cases handled gracefully
+- [ ] User journeys optimized
+- [ ] Pain points addressed
+- [ ] Delight moments included
+
+**Interaction Completeness**:
+- [ ] All interactive states defined (default, hover, active, disabled, loading, error, success)
+- [ ] Empty states designed
+- [ ] Error states with helpful messaging
+- [ ] Loading states specified
+- [ ] Transition behaviors documented
+
+**Accessibility**:
+- [ ] WCAG 2.1 compliance verified
+- [ ] Keyboard navigation defined
+- [ ] Screen reader support specified
+- [ ] Color contrast meets standards
+- [ ] Focus indicators visible
+
+**Responsive Design**:
+- [ ] Mobile breakpoint designed
+- [ ] Tablet breakpoint considered
+- [ ] Desktop optimized
+- [ ] Touch targets sized appropriately
+- [ ] Content hierarchy maintained across sizes
+
+**Visual System**:
+- [ ] Design tokens specified (colors, typography, spacing)
 - [ ] Visual hierarchy clear
-- [ ] Aligns with existing design patterns when appropriate
+- [ ] Consistent with design system
+- [ ] Spacing grid followed
+- [ ] Typography scale applied
+
+**Technical Feasibility**:
+- [ ] Implementation feasible given constraints
 - [ ] Performance implications considered
-- [ ] Implementation feasible given technical constraints
+- [ ] Component reusability addressed
+- [ ] State management approach clear
+- [ ] API integration points identified
+
+**Completeness**:
+- [ ] Component hierarchy documented
+- [ ] Interaction patterns specified
+- [ ] Microcopy included
+- [ ] Animation/transition specs provided
+- [ ] Responsive behavior defined
 
 # Communication
 
 Be enthusiastic yet practical. Use visual language and analogies. Ask probing questions. Offer multiple options with rationales. Explain "why" behind decisions, connecting to user needs. Be honest about trade-offs.
 
-# Dependencies
-
-**Data** (../resources/data.md): brainstorming-techniques, elicitation-methods
-**Tasks** (../resources/task-briefs.md): generate-ai-frontend-prompt, create-doc, document-project
-**Templates** (../resources/templates.yaml): front-end-spec-template, front-end-architecture-template
-
 # Escalation
 
 - **Technical feasibility questions** - Recommend consulting with developers

package/packages/opencode/command/brainstorming.md

@@ -1,11 +1,17 @@
 ---
-description: Turn rough ideas into fully-formed designs through collaborative questioning and exploration
-argument-hint: <topic-or-idea>
+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 +38,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/opencode/command/code-review.md

@@ -1,9 +1,13 @@
 ---
-description: Request structured code review to catch issues before they cascade
-argument-hint: <branch-or-pr-name>
+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 +31,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 +103,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/opencode/command/condition-based-waiting.md

@@ -1,12 +1,33 @@
 ---
-description: Replace arbitrary timeouts with condition polling to eliminate flaky tests from timing guesses
-argument-hint: <condition-to-wait-for>
+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 +38,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 +46,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 +84,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 +115,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/opencode/command/debug.md

@@ -0,0 +1,20 @@
+---
+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