@amrhas82/agentic-kit 1.1.0 → 1.2.0

package/packages/opencode/agents/scrum-master.md

@@ -0,0 +1,64 @@
+---
+name: scrum-master
+description: Use this agent to create detailed user stories, manage epics, conduct retrospectives, or receive agile process guidance. Specializes in preparing crystal-clear, actionable stories for development handoff, epic decomposition, course correction, and story validation. Does NOT implement stories or modify code.
+model: inherit
+color: teal
+---
+
+You are a Technical Scrum Master and Story Preparation Specialist. Your singular focus is creating crystal-clear, actionable user stories that AI development agents can implement without confusion or ambiguity.
+
+**Core Identity:**
+- You are task-oriented, efficient, and precise
+- Your expertise lies in preparing detailed developer handoffs
+- You specialize in translating requirements into stories that "dumb AI agents" can execute flawlessly
+- You are the bridge between product vision and implementation clarity
+
+**Absolute Rules:**
+1. You are NEVER allowed to implement stories or modify code yourself
+2. You MUST rigorously follow the `create-next-story` procedure when generating user stories
+3. All story information MUST come from the PRD (Product Requirements Document) and Architecture documentation
+4. Your purpose is story preparation and agile guidance only
+
+**Available Commands** (all require * prefix, e.g., *help):
+- *help: Display a numbered list of all available commands for user selection
+- *correct-course: Execute the task defined in correct-course.md to realign work with PRD and architecture
+- *draft: Execute the task defined in create-next-story.md to generate the next detailed user story
+- *story-checklist: Execute the task defined in execute-checklist.md using story-draft-checklist.md to validate story quality
+- *exit: Provide a professional Scrum Master farewell and exit this persona
+
+**Required Dependencies:**
+You rely on these files in the agentic-kit resources:
+- Checklists (../resources/checklists.md):
+  - story-draft-checklist
+- Tasks (../resources/task-briefs.md):
+  - correct-course
+  - create-next-story
+  - execute-checklist
+- Templates (../resources/templates.yaml):
+  - story-template
+
+**Story Creation Principles:**
+1. Every story must be traceable to specific PRD requirements
+2. Stories must include sufficient context for autonomous AI implementation
+3. Acceptance criteria must be unambiguous and testable
+4. Technical guidance must reference architectural decisions and patterns
+5. Stories must anticipate edge cases and provide clear handling guidance
+
+**Operational Approach:**
+- When drafting stories, extract all relevant context from PRD and architecture docs
+- Ensure stories are self-contained with all necessary information
+- Use the story template consistently for standardization
+- Run quality checks via the story checklist before considering a story complete
+- If requirements are unclear or conflicting, flag issues rather than making assumptions
+- Guide users through agile ceremonies and processes when requested
+
+**Quality Standards:**
+- Stories must pass all items in story-draft-checklist.md
+- Acceptance criteria must be specific, measurable, and complete
+- Technical context must be sufficient for implementation without additional research
+- Dependencies and blockers must be explicitly identified
+
+**When Users Request Implementation:**
+If a user asks you to implement code or modify files, politely but firmly redirect: "As a Scrum Master, I prepare stories for implementation but don't code myself. I can create a detailed story that a development agent can execute. Would you like me to draft that story?"
+
+**Your Mantra:** Every story you create should be so clear that an AI agent with no prior context can implement it correctly on the first try.

package/packages/opencode/agents/ux-expert.md

@@ -0,0 +1,74 @@
+---
+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.
+model: inherit
+color: magenta
+---
+
+You are a UX Expert, an elite User Experience Designer and UI Specialist with deep expertise in creating intuitive, delightful interfaces. You embody an empathetic, creative, detail-oriented approach with unwavering obsession for user needs and data-informed decision-making.
+
+# Core Identity
+
+You specialize in UX design, interaction design, visual design, accessibility, and AI-powered UI generation. You excel at translating user needs into beautiful, functional designs and crafting effective prompts for AI UI generation tools like v0 and Lovable.
+
+# Guiding Principles
+
+1. **User-Centric Above All** - Every design decision must serve user needs
+2. **Simplicity Through Iteration** - Start simple, refine based on feedback
+3. **Delight in the Details** - Thoughtful micro-interactions create memorable experiences
+4. **Design for Real Scenarios** - Consider edge cases, error states, loading states, empty states, accessibility
+5. **Collaborate, Don't Dictate** - Best solutions emerge from cross-functional work
+
+# Commands
+
+All require * prefix:
+
+- **\*help** - Show numbered list of commands
+- **\*create-front-end-spec** - Create comprehensive front-end specification
+- **\*generate-ui-prompt** - Generate effective AI UI generation prompt
+- **\*exit** - Say goodbye and exit persona
+
+# Workflow Approach
+
+**Design Tasks**: Understand context (users, goals, constraints, metrics) → Research first (needs, pain points, patterns) → Define structure (IA, flows) → Design iteratively (low-fi to high-fi, gather feedback) → Specify completely (interactions, states, responsive, accessibility) → Validate against principles
+
+**Front-End Specs** (*create-front-end-spec): Component hierarchy, interaction behaviors, responsive breakpoints, accessibility (ARIA, keyboard nav, screen readers), state management (loading, error, empty, success), visual tokens (colors, typography, spacing), animations/transitions
+
+**AI UI Prompts** (*generate-ui-prompt): Component purpose and user context, visual style and design system, interaction behaviors and states, accessibility requirements, responsive expectations, technical constraints/framework preferences
+
+# Design Deliverables
+
+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
+
+Before finalizing, verify:
+- [ ] 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
+- [ ] Visual hierarchy clear
+- [ ] Aligns with existing design patterns when appropriate
+- [ ] Performance implications considered
+- [ ] Implementation feasible given technical constraints
+
+# 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
+- **Business requirement conflicts** - Suggest stakeholder discussion
+- **User research gaps** - Propose user testing or research activities
+- **Scope concerns** - Clearly outline what can be achieved now vs. later
+
+You are proactive, detail-oriented, and relentlessly focused on creating experiences that users love. Every interaction should reflect your commitment to user-centric design excellence.

package/packages/opencode/hooks/register-agents.js

@@ -0,0 +1,128 @@
+/**
+ * register-agents.js
+ * Auto-discovery mechanism that scans agent/ directory (Opencode uses singular 'agent')
+ * Extracts metadata from agent files
+ * Registers all agents in context.agentRegistry
+ * Enables auto-invocation for CLI-based workflows
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Parse agent metadata from markdown file
+ * Looks for frontmatter and specific headers
+ */
+function parseAgentMetadata(filePath) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+
+  const agent = {
+    id: path.basename(filePath, '.md'),
+    name: '',
+    description: '',
+    role: '',
+    capabilities: [],
+    filePath: filePath,
+    tool: 'opencode'
+  };
+
+  // Extract title/name from first heading
+  const titleMatch = content.match(/^#\s+(.+)$/m);
+  if (titleMatch) {
+    agent.name = titleMatch[1].trim();
+  }
+
+  // Extract description from first paragraph after title
+  const descMatch = content.match(/^#\s+.+\n\n(.+?)(?:\n\n|##)/s);
+  if (descMatch) {
+    agent.description = descMatch[1].trim();
+  }
+
+  // Extract role section if it exists
+  const roleMatch = content.match(/##\s+Role\n\n(.+?)(?=\n##)/s);
+  if (roleMatch) {
+    agent.role = roleMatch[1].trim();
+  }
+
+  // Extract capabilities from section if it exists
+  const capsMatch = content.match(/##\s+Capabilities\n\n([\s\S]+?)(?=\n##|$)/);
+  if (capsMatch) {
+    const capsText = capsMatch[1];
+    agent.capabilities = capsText
+      .split('\n')
+      .filter(line => line.trim().startsWith('-'))
+      .map(line => line.replace(/^-\s+/, '').trim());
+  }
+
+  return agent;
+}
+
+/**
+ * Scan agents/ directory and register all agents
+ * Opencode uses same structure as Claude for installer compatibility
+ */
+function registerAgents(agentsDir) {
+  const registry = {};
+
+  try {
+    if (!fs.existsSync(agentsDir)) {
+      console.warn(`Agents directory not found: ${agentsDir}`);
+      return registry;
+    }
+
+    const files = fs.readdirSync(agentsDir);
+    const mdFiles = files.filter(f => f.endsWith('.md'));
+
+    mdFiles.forEach(file => {
+      try {
+        const filePath = path.join(agentsDir, file);
+        const metadata = parseAgentMetadata(filePath);
+        registry[metadata.id] = metadata;
+        console.log(`[Opencode] Registered agent: ${metadata.id} - ${metadata.name}`);
+      } catch (error) {
+        console.error(`Failed to register agent ${file}:`, error.message);
+      }
+    });
+
+  } catch (error) {
+    console.error(`Failed to scan agent directory: ${error.message}`);
+  }
+
+  return registry;
+}
+
+/**
+ * Auto-invocation handler for CLI workflows
+ * Matches user commands to available agents and invokes them
+ * Optimized for terminal-based interactions
+ */
+function createAutoInvocationHandler(registry) {
+  return function invokeAgent(agentId, context) {
+    const agent = registry[agentId];
+
+    if (!agent) {
+      throw new Error(`Agent not found: ${agentId}`);
+    }
+
+    // Agent would be invoked here with appropriate context
+    // CLI-optimized: minimal output, command-line friendly
+    return {
+      agentId: agent.id,
+      name: agent.name,
+      description: agent.description,
+      role: agent.role,
+      capabilities: agent.capabilities,
+      context: context,
+      optimization: 'cli-codegen'
+    };
+  };
+}
+
+/**
+ * Module exports
+ */
+module.exports = {
+  parseAgentMetadata,
+  registerAgents,
+  createAutoInvocationHandler
+};

package/packages/opencode/hooks/session-start.js

@@ -0,0 +1,168 @@
+/**
+ * session-start.js
+ *
+ * This hook runs at the start of every Opencode session.
+ * It ensures all skills defined in the active variant are loaded and available.
+ *
+ * Purpose:
+ * - Load variant-specific skills automatically (same structure as Claude for installer compatibility)
+ * - Register agents for auto-invocation
+ * - Initialize any session-specific resources
+ * - Provide CLI-friendly session startup feedback
+ * - Optimize for terminal-based workflows
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Load and activate skills for the current variant
+ * Opencode uses same structure as Claude for installer compatibility
+ */
+function loadSkills(skillsDir, skillsList) {
+  const loadedSkills = [];
+
+  if (!skillsList || skillsList.length === 0) {
+    console.log('ℹ️  No skills to load for this variant');
+    return loadedSkills;
+  }
+
+  skillsList.forEach(skill => {
+    try {
+      const skillPath = path.join(skillsDir, skill.path);
+
+      if (fs.existsSync(skillPath)) {
+        loadedSkills.push({
+          id: skill.id,
+          name: skill.name,
+          path: skill.path,
+          status: 'loaded'
+        });
+        console.log(`✅ Loaded skill: ${skill.name}`);
+      } else {
+        console.warn(`⚠️  Skill not found: ${skill.name} at ${skillPath}`);
+      }
+    } catch (error) {
+      console.error(`❌ Failed to load skill ${skill.name}:`, error.message);
+    }
+  });
+
+  return loadedSkills;
+}
+
+/**
+ * Initialize agents for the session
+ * Opencode uses same structure as Claude for installer compatibility
+ */
+function initializeAgents(agentsDir, agentsList) {
+  const activeAgents = [];
+
+  agentsList.forEach(agent => {
+    try {
+      const agentPath = path.join(agentsDir, agent.path);
+
+      if (fs.existsSync(agentPath)) {
+        activeAgents.push({
+          id: agent.id,
+          name: agent.name,
+          status: 'ready'
+        });
+      }
+    } catch (error) {
+      console.error(`❌ Failed to initialize agent ${agent.name}:`, error.message);
+    }
+  });
+
+  return activeAgents;
+}
+
+/**
+ * Display CLI-optimized session start banner
+ */
+function displayBanner(variant, agentCount, skillCount) {
+  const variantColors = {
+    lite: '\x1b[32m',      // Green
+    standard: '\x1b[34m',   // Blue
+    pro: '\x1b[35m'        // Magenta
+  };
+
+  const color = variantColors[variant] || '\x1b[36m'; // Default cyan
+  const reset = '\x1b[0m';
+  const bold = '\x1b[1m';
+
+  console.log(`
+${bold}${color}╔═══════════════════════════════════════════════╗${reset}
+${bold}${color}║      Opencode - ${variant.charAt(0).toUpperCase() + variant.slice(1)} Variant${' '.repeat(Math.max(0, 20 - variant.length))}║${reset}
+${bold}${color}║      CLI-Optimized AI Code Generation        ║${reset}
+${bold}${color}╚═══════════════════════════════════════════════╝${reset}
+
+✨ Session started successfully!
+
+📊 Active Components:
+   • Agents: ${agentCount}
+   • Skills: ${skillCount}
+
+💡 Quick Start (CLI Mode):
+   • Invoke agents: ${color}@Master:${reset} help
+   • List skills: ${color}opencode list${reset}
+   • Execute skill: ${color}opencode <skill> <args>${reset}
+
+🚀 Optimization: ${bold}${color}cli-codegen${reset}
+   Terminal-first workflows, command-line integration
+
+${bold}Ready for CLI-based development!${reset}
+`);
+}
+
+/**
+ * Main session start handler
+ */
+function onSessionStart(context) {
+  try {
+    // Get variant from context or default to standard
+    const variant = context.variant || 'standard';
+    const manifest = context.manifest || {};
+
+    const agentsList = manifest.agents || [];
+    const skillsList = manifest.skills || [];
+
+    // Load skills (same structure as Claude for installer compatibility)
+    const loadedSkills = loadSkills(context.skillsPath || './skills', skillsList);
+
+    // Initialize agents (same structure as Claude for installer compatibility)
+    const activeAgents = initializeAgents(context.agentsPath || './agents', agentsList);
+
+    // Display CLI-optimized banner
+    displayBanner(variant, activeAgents.length, loadedSkills.length);
+
+    // Return session context with CLI optimization metadata
+    return {
+      variant,
+      agents: activeAgents,
+      skills: loadedSkills,
+      timestamp: new Date().toISOString(),
+      status: 'ready',
+      optimization: 'cli-codegen',
+      tool: 'opencode'
+    };
+
+  } catch (error) {
+    console.error('❌ Session start failed:', error.message);
+    console.log('⚠️  Plugin may not function correctly. Please restart or reinstall.');
+
+    return {
+      status: 'error',
+      error: error.message
+    };
+  }
+}
+
+/**
+ * Module exports
+ */
+module.exports = {
+  onSessionStart,
+  loadSkills,
+  initializeAgents,
+  displayBanner
+};

package/packages/opencode/opencode.jsonc

@@ -0,0 +1,225 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "agent": {
+      "1-create-prd": {
+      "prompt": "{file:./agent/1-create-prd.md}",
+      "mode": "all",
+      "tools": {
+        "write": true,
+        "edit": true,
+        "bash": true
+      },
+      "description": "1. Define Scope: use to clearly outlining what needs to be built with a Product Requirement Document (PRD)"
+    },
+        "2-generate-tasks": {
+      "prompt": "{file:./agent/2-generate-tasks.md}",
+      "mode": "all",
+      "tools": {
+        "write": true,
+        "edit": true,
+        "bash": true
+      },
+      "description": "2. Detailed Planning: use to break down the PRD into a granular, actionable task list"
+    },
+        "3-process-task-list": {
+      "prompt": "{file:./agent/3-process-task-list.md}",
+      "mode": "all",
+      "tools": {
+        "write": true,
+        "edit": true,
+        "bash": true
+      },
+      "description": "3. Iterative Implementation: use to guide the AI to tackle one task at a time, allowing you to review and approve each change"
+    },   
+    "ux-expert": {
+      "prompt": "{file:./agent/ux-expert.md}",
+      "mode": "all",
+      "tools": {
+        "write": true,
+        "edit": true,
+        "bash": true
+      },
+      "description": "Use for UI/UX design, wireframes, prototypes, front-end specifications, and user experience optimization"
+    },
+    "scrum-master": {
+      "prompt": "{file:./agent/scrum-master.md}",
+      "mode": "all",
+      "tools": {
+        "write": true,
+        "edit": true,
+        "bash": true
+      },
+      "description": "Use for story creation, epic management, retrospectives in party-mode, and agile process guidance"
+    },
+    "qa-test-architecht": {
+      "prompt": "{file:./agent/qa-test-architect.md}",
+      "mode": "all",
+      "tools": {
+        "write": true,
+        "edit": true,
+        "bash": true
+      },
+      "description": "Use for comprehensive test architecture review, quality gate decisions, and code improvement. Provides thorough analysis including requirements traceability, risk assessment, and test strategy. Advisory only - teams choose their quality bar."
+    },
+    "product-owner": {
+      "prompt": "{file:./agent/product-owner.md}",
+      "mode": "all",
+      "tools": {
+        "write": true,
+        "edit": true,
+        "bash": true
+      },
+      "description": "Use for backlog management, story refinement, acceptance criteria, sprint planning, and prioritization decisions"
+    },
+    "product-manager": {
+      "prompt": "{file:./agent/product-manager.md}",
+      "mode": "all",
+      "tools": {
+        "write": true,
+        "edit": true,
+        "bash": true
+      },
+      "description": "Use for creating PRDs, product strategy, feature prioritization, roadmap planning, and stakeholder communication"
+    },
+    "full-stack-dev": {
+      "prompt": "{file:./agent/full-stack-dev.md}",
+      "mode": "all",
+      "tools": {
+        "write": true,
+        "edit": true,
+        "bash": true
+      },
+      "description": "'Use for code implementation, debugging, refactoring, and development best practices'"
+    },
+    "orchestrator": {
+      "prompt": "{file:./agent/orchestrator.md}",
+      "mode": "primary",
+      "tools": {
+        "write": true,
+        "edit": true,
+        "bash": true
+      },
+      "description": "Use for workflow coordination, multi-agent tasks, role switching guidance, and when unsure which specialist to consult"
+    },
+    "master": {
+      "prompt": "{file:./agent/master.md}",
+      "mode": "all",
+      "tools": {
+        "write": true,
+        "edit": true,
+        "bash": true
+      },
+      "description": "Use when you need comprehensive expertise across all domains, running 1 off tasks that do not require a persona, or just wanting to use the same agent for many things."
+    },
+    "holistic-architect": {
+      "prompt": "{file:./agent/holistic-architect.md}",
+      "mode": "all",
+      "tools": {
+        "write": true,
+        "edit": true,
+        "bash": true
+      },
+      "description": "Use for system design, architecture documents, technology selection, API design, and infrastructure planning"
+    },
+    "business-analyst": {
+      "prompt": "{file:./agent/business-analyst.md}",
+      "mode": "all",
+      "tools": {
+        "write": true,
+        "edit": true,
+        "bash": true
+      },
+      "description": "Use for market research, brainstorming, competitive analysis, creating project briefs, initial project discovery, and documenting existing projects (brownfield)"
+    }
+  },
+  "command": {
+    "xlsx": {
+      "template": "{file:./xlsx.md}",
+      "description": "Create, edit, and analyze spreadsheets with formulas, formatting, data analysis, and visualization"
+    },
+    "webapp-testing": {
+      "template": "{file:./webapp-testing.md}",
+      "description": "Test local web applications using Playwright - verify functionality, debug UI, capture screenshots"
+    },
+    "systematic-debugging": {
+      "template": "{file:./systematic-debugging.md}",
+      "description": "Systematic four-phase debugging framework - investigate root cause before any fixes"
+    },
+    "slack-gif-creator": {
+      "template": "{file:./slack-gif-creator.md}",
+      "description": "Create animated GIFs optimized for Slack with size validation and composable animation primitives"
+    },
+    "verification-before-completion": {
+      "template": "{file:./verification-before-completion.md}",
+      "description": "Verify work meets requirements before marking complete - prevents incomplete deliverables"
+    },
+    "skill-creator": {
+      "template": "{file:./skill-creator.md}",
+      "description": "Create reusable skills with proper structure, validation, and documentation"
+    },
+    "test-driven-development": {
+      "template": "{file:./test-driven-development.md}",
+      "description": "Write test first, watch it fail, write minimal code to pass - ensures tests actually verify behavior"
+    },
+    "testing-anti-patterns": {
+      "template": "{file:./testing-anti-patterns.md}",
+      "description": "Identify and avoid common testing anti-patterns that create fragile, useless tests"
+    },
+    "theme-factory": {
+      "template": "{file:./theme-factory.md}",
+      "description": "Generate consistent themes with proper color systems, typography, and spacing"
+    },
+    "root-cause-tracing": {
+      "template": "{file:./root-cause-tracing.md}",
+      "description": "Trace issues to their root cause using systematic investigation techniques"
+    },
+    "internal-comms": {
+      "template": "{file:./internal-comms.md}",
+      "description": "Structure internal communications for clarity, actionability, and team alignment"
+    },
+    "pdf": {
+      "template": "{file:./pdf.md}",
+      "description": "Create, edit, and analyze PDF documents with proper formatting and structure"
+    },
+    "mcp-builder": {
+      "template": "{file:./mcp-builder.md}",
+      "description": "Build Model Context Protocol servers with proper tool definitions and error handling"
+    },
+    "condition-based-waiting": {
+      "template": "{file:./condition-based-waiting.md}",
+      "description": "Implement robust waiting mechanisms based on conditions rather than fixed delays"
+    },
+    "pptx": {
+      "template": "{file:./pptx.md}",
+      "description": "Create professional PowerPoint presentations with proper structure and design"
+    },
+    "docx": {
+      "template": "{file:./docx.md}",
+      "description": "Create and edit Word documents with proper formatting and structure"
+    },
+    "brand-guidelines": {
+      "template": "{file:./brand-guidelines.md}",
+      "description": "Establish comprehensive brand guidelines with visual identity and usage rules"
+    },
+    "brainstorming": {
+      "template": "{file:./brainstorming.md}",
+      "description": "Facilitate structured brainstorming sessions with proven techniques and frameworks"
+    },
+    "canvas-design": {
+      "template": "{file:./canvas-design.md}",
+      "description": "Design visual canvases for business models, user journeys, and strategic planning"
+    },
+    "artifacts-builder": {
+      "template": "{file:./artifacts-builder.md}",
+      "description": "Build structured artifacts with proper validation, formatting, and documentation"
+    },
+    "algorithmic-art": {
+      "template": "{file:./algorithmic-art.md}",
+      "description": "Generate algorithmic art with mathematical patterns and aesthetic principles"
+    },
+    "code-review": {
+      "template": "{file:./code-review.md}",
+      "description": "Conduct thorough code reviews with focus on quality, security, and maintainability"
+    }
+  }
+}