@amrhas82/agentic-kit 1.7.0 → 1.7.5

package/packages/droid/AGENTS.md

@@ -1,525 +1,55 @@
-# Global Droid Agents
+# Global Droid CLI
 
-This file provides guidance and memory for your coding CLI.
+Droid is a lightweight CLI tool that provides workflow automation commands.
 
-# MANDATORY: Orchestrator-First Routing Pattern
+## Droid Subagents (Reference)
 
-**System Instruction for Droid**:
-When processing ANY user request, invoke the `orchestrator` agent FIRST unless:
-- User explicitly mentions a specific agent: `@agent-id` or `As agent-id, ...`
-- User invokes a command: `/command-name`
-- User gives a direct command: `npm test`, `git status`, file operations, etc.
+These subagents are available when using Claude Code CLI. Droid can reference them but doesn't implement them directly.
 
-**Why orchestrator first?**
-- Analyzes user intent and matches to optimal workflow
-- Asks clarifying questions for conditional workflow steps (e.g., "Research first?")
-- Coordinates multi-agent sequences with minimal context passing
-- Ensures systematic approach to complex tasks
+### Subagents (14 total)
 
-**Orchestrator reads this registry** to match requests to specialists and invoke via Task tool with selective context injection.
-
-# Droid CLI subagents and Tasks (Droid)
-
-Droid reads AGENTS.md when other subagents want to invoke other subagents, tasks, or resources
-
-## How To Use With Droid
-
-Activate agents by mentioning their ID in your prompts:
-- `"As full-stack-dev, implement the login feature"`
-- `"invoke droid qa-test-architect"`
-
-- Copy/paste `droid` subfolders in this project to ~/.factory and Droid will read and access agents from ~/.factory/droids and tasks from ~/.factory/resources/tasks-brief.md,
-- You can access agents using "@ux-expert", or you can reference a role naturally, e.g., "As ux-expert, implement ..." or use commands defined in your tasks.
-
-Note
-- Orchestrators/master run as mode: primary; other agents as mode: subagents.
-- All agents have enbaled tools: write, edit, bash.
-
-## Agents
-
-### Directory
-
-| Title | ID | When To Use |
+| ID | Title | When To Use |
 |---|---|---|
-| 1-Create PRD | 1-create-prd | 1. Define Scope: use to clearly outlining what needs to be built with a Product Requirement Document (PRD) |
-| 2-Generate Tasks | 2-generate-tasks | 2. Detailed Planning: use to break down the PRD into a granular, actionable task list |
-| 3-Process Task List | 3-process-task-list | 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 | ux-expert | Use for UI/UX design, wireframes, prototypes, front-end specifications, and user experience optimization |
-| Scrum Master | scrum-master | Use for story creation, epic management, retrospectives in party-mode, and agile process guidance |
-| Test Architect & Quality Advisor | qa-test-architect | 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 | product-owner | Use for backlog management, story refinement, acceptance criteria, sprint planning, and prioritization decisions |
-| Product Manager | product-manager | Use for creating PRDs, product strategy, feature prioritization, roadmap planning, and stakeholder communication |
-| Full Stack Developer | full-stack-dev | Use for code implementation, debugging, refactoring, and development best practices |
-| Master Orchestrator | orchestrator | Use for workflow coordination, multi-agent tasks, role switching guidance, and when unsure which specialist to consult |
-| Master Task Executor | master | 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. |
-| Architect | holistic-architect | Use for system design, architecture documents, technology selection, API design, and infrastructure planning |
-| Business Analyst | business-analyst | Use for market research, brainstorming, competitive analysis, creating project briefs, initial project discovery, and documenting existing projects (brownfield) |
-| Context Initializer | context-initializer | Use to initialize Droid context for new/existing projects, discover and organize documentation, create AGENTS.md and KNOWLEDGE_BASE.md for optimal token-efficient memory |
-
-## Common Workflow Patterns
-
-The orchestrator uses these patterns to match user intent to multi-agent workflows. Each step is **conditional** - orchestrator asks user approval before advancing.
-
-### 1. Feature Discovery Flow (Most Common)
-**User Intent**: "I need to add [feature]", "Build [new functionality]"
-**Workflow**:
-```
-orchestrator analyzes → asks: "Research competitive approaches first?"
-  ├─ Yes → business-analyst (research) → ask: "Create formal PRD?"
-  │   ├─ Yes → 1-create-prd → ask: "Generate implementation tasks?"
-  │   │   ├─ Yes → 2-generate-tasks → ask: "Start systematic implementation?"
-  │   │   │   ├─ Yes → 3-process-task-list
-  │   │   │   └─ No → Done (user has task list for review)
-  │   │   └─ No → Done (user has PRD for review)
-  │   └─ No → Done (user has research for review)
-  └─ No → 1-create-prd → (same conditional tree from PRD onward)
-```
-
-### 2. Product Definition Flow
-**User Intent**: "We're considering a new product/initiative", "Strategic product planning"
-**Workflow**:
-```
-orchestrator → ask: "Follow product definition workflow?"
-└─ Yes → product-manager (strategy, vision) → ask: "Define user stories?"
-    └─ Yes → product-owner (backlog, stories) → ask: "Technical feasibility assessment?"
-        └─ Yes → holistic-architect (platform decisions, technical design)
-```
-
-### 3. Story Implementation Flow
-**User Intent**: "Implement [existing story]", "Build [defined feature with acceptance criteria]"
-**Workflow**:
-```
-orchestrator → ask: "Validate story readiness first?"
-├─ Yes → product-owner (validate acceptance criteria) → full-stack-dev → qa-test-architect
-└─ No → full-stack-dev (implement) → qa-test-architect (quality gate)
-```
-
-### 4. Architecture Decision Flow
-**User Intent**: "Should we use [tech A] or [tech B]?", "How should we architect [system]?"
-**Workflow**:
-```
-orchestrator → business-analyst (gather constraints, requirements)
-            → holistic-architect (options analysis, tradeoffs)
-            → ask: "Need product alignment?"
-            └─ Yes → product-manager (strategic alignment, decision rationale)
-```
-
-### 5. UI Development Flow
-**User Intent**: "Build [UI component]", "Design and implement [interface]"
-**Workflow**:
-```
-orchestrator → ux-expert (wireframes, design system)
-            → ask: "Complex enough to need PRD?"
-            ├─ Yes → 1-create-prd → full-stack-dev → qa-test-architect
-            └─ No → full-stack-dev (implement) → qa-test-architect (validate)
-```
-
-### 6. Bug Triage Flow
-**User Intent**: "Bug: [description]", "Fix [broken behavior]"
-**Workflow**:
-```
-orchestrator → full-stack-dev (investigate root cause)
-            → ask: "Severity level?"
-            ├─ Critical → full-stack-dev (immediate fix) → qa-test-architect (verify)
-            └─ Non-critical → 1-create-prd (bug story) → backlog (for sprint planning)
-```
-
-### 7. Brownfield Discovery Flow
-**User Intent**: "Help me understand this codebase", "Document existing system"
-**Workflow**:
-```
-orchestrator → context-initializer (build knowledge base, discover patterns)
-            → business-analyst (document current state, stakeholders)
-            → ask: "Assess technical debt and modernization opportunities?"
-            └─ Yes → holistic-architect (technical assessment, recommendations)
-```
-
-### 8. Quality Validation Flow
-**User Intent**: "Review this PR", "Check code quality before merge"
-**Workflow**:
-```
-orchestrator → qa-test-architect (comprehensive review)
-            → [Decision gate]
-            ├─ PASS → Done (ready to merge)
-            ├─ CONCERNS → Present issues → user decides next step
-            └─ FAIL → full-stack-dev (apply fixes) → qa-test-architect (re-validate)
-```
-
-### 9. Sprint Planning Flow
-**User Intent**: "Plan next sprint", "Prepare sprint backlog"
-**Workflow**:
-```
-orchestrator → product-manager (prioritize features for sprint)
-            → scrum-master (break into user stories)
-            → product-owner (add acceptance criteria)
-            → 2-generate-tasks (create sprint backlog with tasks)
-```
-
-### Selective Context Injection
-
-When orchestrator invokes specialists, it passes **minimal necessary context**:
-
-**✓ Include**:
-- Direct user requirements for the specific task
-- Outputs from immediate workflow dependencies only
-- Relevant domain-specific files/data
-
-**✗ Exclude**:
-- Full conversation history
-- Unrelated workflow step outputs
-- Tangential project context
-
-**Example**: When invoking `qa-test-architect`:
-- ✓ Include: code diff, test requirements, acceptance criteria
-- ✗ Exclude: PRD creation discussions, UI wireframes, database schema decisions
-
-### 1-Create PRD (id: 1-create-prd) 
-Source: [./droids/ux-expert.md](./droids/1-create-prd.md)
-
-- When to use: Define Scope: use to clearly outlining what needs to be built with a Product Requirement Document (PRD)  optimization
-- How to activate: Mention "create prd, ..." to get role-aligned behavior
-- Full definition: open the source file above (content not embedded)
-
-### 2-Generate Tasks (id: 2-generate-tasks) 
-Source: [./droids/ux-expert.md](./droids/2-generate-tasks.md)
-
-- When to use: 2. Detailed Planning: use to break down the PRD into a granular, actionable task list
-- How to activate: Mention "generate tasks, ..." to get role-aligned behavior
-- Full definition: open the source file above (content not embedded)
-
-### 3-Process Task List (id: 3-process-task-list)
-Source: [./droids/ux-expert.md](./droids/3-process-task-list.md)
-
-- When to use: 3. Iterative Implementation: use to guide the AI to tackle one task at a time, allowing you to review and approve each change
-- How to activate: Mention "process task list, ..." to get role-aligned behavior
-- Full definition: open the source file above (content not embedded)
-
-### UX Expert (id: ux-expert)
-Source: [./droids/ux-expert.md](./droids/ux-expert.md)
-
-- When to use: Use for UI/UX design, wireframes, prototypes, front-end specifications, and user experience optimization
-- How to activate: Mention "As ux-expert, ..." to get role-aligned behavior
-- Full definition: open the source file above (content not embedded)
-
-### Scrum Master (id: scrum-master)
-Source: [./droids/scrum-master.md](./droids/scrum-master.md)
-
-- When to use: Use for story creation, epic management, retrospectives in party-mode, and agile process guidance
-- How to activate: Mention "As scrum-master, ..." to get role-aligned behavior
-- Full definition: open the source file above (content not embedded)
-
-### Test Architect & Quality Advisor (id: qa-test-architect)
-Source: [./droids/qa-test-architect.md](./droids/qa-test-architect.md)
-
-- When to use: 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.
-- How to activate: Mention "As qa, ..." to get role-aligned behavior
-- Full definition: open the source file above (content not embedded)
-
-### Product Owner (id: product-owner)
-Source: [./droids/product-owner.md](./droids/product-owner.md)
-
-- When to use: Use for backlog management, story refinement, acceptance criteria, sprint planning, and prioritization decisions
-- How to activate: Mention "As product-owner, ..." to get role-aligned behavior
-- Full definition: open the source file above (content not embedded)
-
-### Product Manager (id: product-manager)
-Source: [./droids/product-manager.md](./droids/product-manager.md)
-
-- When to use: Use for creating PRDs, product strategy, feature prioritization, roadmap planning, and stakeholder communication
-- How to activate: Mention "As product-manager, ..." to get role-aligned behavior
-- Full definition: open the source file above (content not embedded)
-
-### Full Stack Developer (id: full-stack-dev)
-Source: [./droids/full-stack-dev.md](./droids/full-stack-dev.md)
-
-- When to use: Use for code implementation, debugging, refactoring, and development best practices
-- How to activate: Mention "As full-stack-dev, ..." to get role-aligned behavior
-- Full definition: open the source file above (content not embedded)
-
-### Master Orchestrator (id: orchestrator)
-Source: [./droids/orchestrator.md](./droids/orchestrator.md)
-
-- When to use: Use for workflow coordination, multi-agent tasks, role switching guidance, and when unsure which specialist to consult
-- How to activate: Mention "As orchestrator, ..." to get role-aligned behavior
-- Full definition: open the source file above (content not embedded)
-
-### Master Task Executor (id: master)
-Source: [./droids/master.md](./droids/master.md)
-
-- When to use: 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.
-- How to activate: Mention "As master, ..." to get role-aligned behavior
-- Full definition: open the source file above (content not embedded)
-
-### Architect (id: holistic-architect)
-Source: [./droids/holistic-architect.md](./droids/holistic-architect.md)
-
-- When to use: Use for system design, architecture documents, technology selection, API design, and infrastructure planning
-- How to activate: Mention "As architect, ..." to get role-aligned behavior
-- Full definition: open the source file above (content not embedded)
-
-### Context Initializer (id: context-initializer)
-Source: [./droids/context-initializer.md](./droids/context-initializer.md)
-
-- When to use: Use to initialize Droid context for new/existing projects, discover and organize documentation, create AGENTS.md and KNOWLEDGE_BASE.md for optimal token-efficient memory
-- How to activate: Mention "@context-initializer" or "As context-initializer, ..." to get role-aligned behavior
-- Full definition: open the source file above (content not embedded)
-
-### Business Analyst (id: business-analyst)
-Source: [./droids/business-analyst.md](./droids/business-analyst.md)
-
-- When to use: Use for market research, brainstorming, competitive analysis, creating project briefs, initial project discovery, and documenting existing projects (brownfield)
-- How to activate: Mention "As analyst, ..." to get role-aligned behavior
-- Full definition: open the source file above (content not embedded)
-
-## Tasks
-
-These are reusable task briefs; use the paths to open them as needed.
-
-### Task: validate-next-story
-Source: [./resources/task-briefs.md#validate-next-story](./resources/task-briefs.md#validate-next-story)
-- How to use: Reference the task in your prompt or execute via your configured commands.
-- Full brief: open the source file above (content not embedded)
-
-### Task: trace-requirements
-Source: [./resources/task-briefs.md#trace-requirements](./resources/task-briefs.md#trace-requirements)
-- How to use: Reference the task in your prompt or execute via your configured commands.
-- Full brief: open the source file above (content not embedded)
-
-### Task: test-design
-Source: [./resources/task-briefs.md#test-design](./resources/task-briefs.md#test-design)
-- How to use: Reference the task in your prompt or execute via your configured commands.
-- Full brief: open the source file above (content not embedded)
-
-### Task: shard-doc
-Source: [./resources/task-briefs.md#shard-doc](./resources/task-briefs.md#shard-doc)
-- How to use: Reference the task in your prompt or execute via your configured commands.
-- Full brief: open the source file above (content not embedded)
-
-### Task: risk-profile
-Source: [./resources/task-briefs.md#risk-profile](./resources/task-briefs.md#risk-profile)
-- How to use: Reference the task in your prompt or execute via your configured commands.
-- Full brief: open the source file above (content not embedded)
-
-### Task: review-story
-Source: [./resources/task-briefs.md#review-story](./resources/task-briefs.md#review-story)
-- How to use: Reference the task in your prompt or execute via your configured commands.
-- Full brief: open the source file above (content not embedded)
-
-### Task: qa-test-architect-gate
-Source: [./resources/task-briefs.md#qa-gate](./resources/task-briefs.md#qa-gate)
-- How to use: Reference the task in your prompt or execute via your configured commands.
-- Full brief: open the source file above (content not embedded)
-
-### Task: nfr-assess
-Source: [./resources/task-briefs.md#nfr-assess](./resources/task-briefs.md#nfr-assess)
-- How to use: Reference the task in your prompt or execute via your configured commands.
-- Full brief: open the source file above (content not embedded)
-
-### Task: index-docs
-Source: [./resources/task-briefs.md#index-docs](./resources/task-briefs.md#index-docs)
-- How to use: Reference the task in your prompt or execute via your configured commands.
-- Full brief: open the source file above (content not embedded)
-
-### Task: generate-ai-frontend-prompt
-Source: [./resources/task-briefs.md#generate-ai-frontend-prompt](./resources/task-briefs.md#generate-ai-frontend-prompt)
-- How to use: Reference the task in your prompt or execute via your configured commands.
-- Full brief: open the source file above (content not embedded)
-
-### Task: facilitate-brainstorming-session
-Source: [./resources/task-briefs.md#facilitate-brainstorming-session](./resources/task-briefs.md#facilitate-brainstorming-session)
-- How to use: Reference the task in your prompt or execute via your configured commands.
-- Full brief: open the source file above (content not embedded)
-
-### Task: execute-checklist
-Source: [./resources/task-briefs.md#execute-checklist](./resources/task-briefs.md#execute-checklist)
-- How to use: Reference the task in your prompt or execute via your configured commands.
-- Full brief: open the source file above (content not embedded)
-
-### Task: document-project
-Source: [./resources/task-briefs.md#document-project](./resources/task-briefs.md#document-project)
-- How to use: Reference the task in your prompt or execute via your configured commands.
-- Full brief: open the source file above (content not embedded)
-
-### Task: create-next-story
-Source: [./resources/task-briefs.md#create-next-story](./resources/task-briefs.md#create-next-story)
-- How to use: Reference the task in your prompt or execute via your configured commands.
-- Full brief: open the source file above (content not embedded)
-
-### Task: create-doc
-Source: [./resources/task-briefs.md#create-doc](./resources/task-briefs.md#create-doc)
-- How to use: Reference the task in your prompt or execute via your configured commands.
-- Full brief: open the source file above (content not embedded)
-
-### Task: create-deep-research-prompt
-Source: [./resources/task-briefs.md#create-deep-research-prompt](./resources/task-briefs.md#create-deep-research-prompt)
-- How to use: Reference the task in your prompt or execute via your configured commands.
-- Full brief: open the source file above (content not embedded)
-
-### Task: create-brownfield-story
-Source: [./resources/task-briefs.md#create-brownfield-story](./resources/task-briefs.md#create-brownfield-story)
-- How to use: Reference the task in your prompt or execute via your configured commands.
-- Full brief: open the source file above (content not embedded)
-
-### Task: correct-course
-Source: [./resources/task-briefs.md#correct-course](./resources/task-briefs.md#correct-course)
-- How to use: Reference the task in your prompt or execute via your configured commands.
-- Full brief: open the source file above (content not embedded)
-
-### Task: brownfield-create-story
-Source: [./resources/task-briefs.md#brownfield-create-story](./resources/task-briefs.md#brownfield-create-story)
-- How to use: Reference the task in your prompt or execute via your configured commands.
-- Full brief: open the source file above (content not embedded)
-
-### Task: brownfield-create-epic
-Source: [./resources/task-briefs.md#brownfield-create-epic](./resources/task-briefs.md#brownfield-create-epic)
-- How to use: Reference the task in your prompt or execute via your configured commands.
-- Full brief: open the source file above (content not embedded)
-
-### Task: apply-qa-fixes
-Source: [./resources/task-briefs.md#apply-qa-fixes](./resources/task-briefs.md#apply-qa-fixes)
-- How to use: Reference the task in your prompt or execute via your configured commands.
-- Full brief: open the source file above (content not embedded)
-
-### Task: advanced-elicitation
-Source: [./resources/task-briefs.md#advanced-elicitation](./resources/task-briefs.md#advanced-elicitation)
-- How to use: Reference the task in your prompt or execute via your configured commands.
-- Full brief: open the source file above (content not embedded)
-
-## Commands
-
-These are slash commands available in the TUI. Use /command-name to execute.
-
-### Command: xlsx
-Source: [./commands/xlsx.md](./commands/xlsx.md)
-- Description: Create, edit, and analyze spreadsheets with formulas, formatting, data analysis, and visualization
-- Usage: `/xlsx <operation> <spreadsheet-file>`
-- Full definition: open the source file above (content not embedded)
-
-### Command: webapp-testing
-Source: [./commands/webapp-testing.md](./commands/webapp-testing.md)
-- Description: Test local web applications using Playwright - verify functionality, debug UI, capture screenshots
-- Usage: `/webapp-testing <webapp-url-or-local-server>`
-- Full definition: open the source file above (content not embedded)
-
-### Command: systematic-debugging
-Source: [./commands/systematic-debugging.md](./commands/systematic-debugging.md)
-- Description: Systematic four-phase debugging framework - investigate root cause before any fixes
-- Usage: `/systematic-debugging <bug-or-error-description>`
-- Full definition: open the source file above (content not embedded)
-
-### Command: slack-gif-creator
-Source: [./commands/slack-gif-creator.md](./commands/slack-gif-creator.md)
-- Description: Create animated GIFs optimized for Slack with size validation and composable animation primitives
-- Usage: `/slack-gif-creator <gif-type> <animation-concept>`
-- Full definition: open the source file above (content not embedded)
-
-### Command: verification-before-completion
-Source: [./commands/verification-before-completion.md](./commands/verification-before-completion.md)
-- Description: Verify work meets requirements before marking complete - prevents incomplete deliverables
-- Usage: `/verification-before-completion <work-to-verify>`
-- Full definition: open the source file above (content not embedded)
-
-### Command: skill-creator
-Source: [./commands/skill-creator.md](./commands/command/skill-creator.md)
-- Description: Create reusable skills with proper structure, validation, and documentation
-- Usage: `/skill-creator <skill-type> <skill-description>`
-- Full definition: open the source file above (content not embedded)
-
-### Command: test-driven-development
-Source: [./commands/test-driven-development.md](./commands/test-driven-development.md)
-- Description: Write test first, watch it fail, write minimal code to pass - ensures tests actually verify behavior
-- Usage: `/test-driven-development <feature-or-behavior-to-test>`
-- Full definition: open the source file above (content not embedded)
-
-### Command: testing-anti-patterns
-Source: [./commands/testing-anti-patterns.md](./commands/testing-anti-patterns.md)
-- Description: Identify and avoid common testing anti-patterns that create fragile, useless tests
-- Usage: `/testing-anti-patterns <testing-scenario>`
-- Full definition: open the source file above (content not embedded)
-
-### Command: theme-factory
-Source: [./commands/theme-factory.md](./commands/theme-factory.md)
-- Description: Generate consistent themes with proper color systems, typography, and spacing
-- Usage: `/theme-factory <theme-type> <design-requirements>`
-- Full definition: open the source file above (content not embedded)
-
-### Command: root-cause-tracing
-Source: [./commands/root-cause-tracing.md](./commands/root-cause-tracing.md)
-- Description: Trace issues to their root cause using systematic investigation techniques
-- Usage: `/root-cause-tracing <issue-description>`
-- Full definition: open the source file above (content not embedded)
-
-### Command: internal-comms
-Source: [./commands/internal-comms.md](./commands/internal-comms.md)
-- Description: Structure internal communications for clarity, actionability, and team alignment
-- Usage: `/internal-comms <communication-type> <audience>`
-- Full definition: open the source file above (content not embedded)
-
-### Command: pdf
-Source: [./commands/pdf.md](./commands/pdf.md)
-- Description: Create, edit, and analyze PDF documents with proper formatting and structure
-- Usage: `/pdf <operation> <pdf-file>`
-- Full definition: open the source file above (content not embedded)
-
-### Command: mcp-builder
-Source: [./commands/mcp-builder.md](./commands/mcp-builder.md)
-- Description: Build Model Context Protocol servers with proper tool definitions and error handling
-- Usage: `/mcp-builder <server-type> <specifications>`
-- Full definition: open the source file above (content not embedded)
-
-### Command: condition-based-waiting
-Source: [./commands/condition-based-waiting.md](./commands/condition-based-waiting.md)
-- Description: Implement robust waiting mechanisms based on conditions rather than fixed delays
-- Usage: `/condition-based-waiting <condition-type> <timeout-specs>`
-- Full definition: open the source file above (content not embedded)
-
-### Command: pptx
-Source: [./commands/pptx.md](./commands/pptx.md)
-- Description: Create professional PowerPoint presentations with proper structure and design
-- Usage: `/pptx <presentation-type> <content-outline>`
-- Full definition: open the source file above (content not embedded)
-
-### Command: docx
-Source: [./commands/docx.md](./commands/docx.md)
-- Description: Create and edit Word documents with proper formatting and structure
-- Usage: `/docx <operation> <document-specs>`
-- Full definition: open the source file above (content not embedded)
-
-### Command: brand-guidelines
-Source: [./commands/brand-guidelines.md](./commands/brand-guidelines.md)
-- Description: Establish comprehensive brand guidelines with visual identity and usage rules
-- Usage: `/brand-guidelines <brand-type> <requirements>`
-- Full definition: open the source file above (content not embedded)
-
-### Command: brainstorming
-Source: [./commands/brainstorming.md](./commands/brainstorming.md)
-- Description: Facilitate structured brainstorming sessions with proven techniques and frameworks
-- Usage: `/brainstorming <session-type> <topic>`
-- Full definition: open the source file above (content not embedded)
-
-### Command: canvas-design
-Source: [./commands/canvas-design.md](./commands/canvas-design.md)
-- Description: Design visual canvases for business models, user journeys, and strategic planning
-- Usage: `/canvas-design <canvas-type> <design-goals>`
-- Full definition: open the source file above (content not embedded)
-
-### Command: artifacts-builder
-Source: [./commands/artifacts-builder.md](./commands/artifacts-builder.md)
-- Description: Build structured artifacts with proper validation, formatting, and documentation
-- Usage: `/artifacts-builder <artifact-type> <specifications>`
-- Full definition: open the source file above (content not embedded)
-
-### Command: algorithmic-art
-Source: [./commands/algorithmic-art.md](./commands/algorithmic-art.md)
-- Description: Generate algorithmic art with mathematical patterns and aesthetic principles
-- Usage: `/algorithmic-art <art-type> <pattern-specs>`
-- Full definition: open the source file above (content not embedded)
-
-### Command: code-review
-Source: [./commands/code-review.md](./commands/code-review.md)
-- Description: Conduct thorough code reviews with focus on quality, security, and maintainability
-- Usage: `/code-review <review-scope> <focus-areas>`
-- Full definition: open the source file above (content not embedded)
-
-
-
+| 1-create-prd | 1-Create PRD | Define Scope - use to clearly outline what needs to be built with a Product Requirement Document (PRD) |
+| 2-generate-tasks | 2-Generate Tasks | Detailed Planning - use to break down the PRD into a granular, actionable task list |
+| 3-process-task-list | 3-Process Task List | Iterative Implementation - use to guide the AI to tackle one task at a time, allowing you to review and approve each change |
+| backlog-manager | Product Owner | Use for backlog management, story refinement, acceptance criteria, sprint planning, and prioritization decisions |
+| code-developer | Full Stack Developer | Use for code implementation, debugging, refactoring, and development best practices |
+| context-builder | Context Initializer | Use to initialize Claude Code context for new/existing projects, discover and organize documentation, create CLAUDE.md and KNOWLEDGE_BASE.md for optimal token-efficient memory |
+| feature-planner | Product Manager | Use for creating PRDs, product strategy, feature prioritization, roadmap planning, and stakeholder communication |
+| market-researcher | Business Analyst | Use for market research, brainstorming, competitive analysis, creating project briefs, initial project discovery, and documenting existing projects (brownfield) |
+| master | Master Task Executor | 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 |
+| orchestrator | Master Orchestrator | Use for workflow coordination, multi-agent tasks, role switching guidance, and when unsure which specialist to consult |
+| quality-assurance | Test Architect & Quality Advisor | 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 |
+| story-writer | Scrum Master | Use for story creation, epic management, retrospectives in party-mode, and agile process guidance |
+| system-architect | Architect | Use for system design, architecture documents, technology selection, API design, and infrastructure planning |
+| ui-designer | UX Expert | Use for UI/UX design, wireframes, prototypes, front-end specifications, and user experience optimization |
+
+## Droid Commands (20 total)
+
+| ID | Description | Usage | Auto |
+|---|---|---|---|
+| brainstorming | Refines rough ideas into fully-formed designs through collaborative questioning | /brainstorming <session-type> <topic> | false |
+| code-review | Reviews implementation against plan or requirements before proceeding | /code-review <review-scope> <focus-areas> | false |
+| condition-based-waiting | Replaces arbitrary timeouts with condition polling to wait for actual state changes | /condition-based-waiting <condition-type> <timeout-specs> | false |
+| debug | Debug an issue systematically using structured investigation techniques | /debug <issue-description> | - |
+| docs-builder | Create comprehensive project documentation with structured /docs hierarchy | /docs-builder | false |
+| explain | Explain code for someone new to the codebase | /explain <code-section> | - |
+| git-commit | Analyze changes and create intelligent git commits | /git-commit | - |
+| optimize | Analyze and optimize performance issues | /optimize <target-area> | - |
+| refactor | Refactor code while maintaining behavior and tests | /refactor <code-section> | - |
+| review | Comprehensive code review including quality, tests, and architecture | /review | - |
+| root-cause-tracing | Systematically traces bugs backward through call stack to identify source | /root-cause-tracing <issue-description> | false |
+| security | Security vulnerability scan and analysis | /security | - |
+| ship | Pre-deployment verification checklist | /ship | - |
+| skill-creator | Guide for creating effective skills and extending Claude capabilities | /skill-creator <skill-type> <skill-description> | false |
+| subagent-spawning | Provides TDD-aware templates for spawning fresh subagents | Used by 3-process-task-list and other agents | true |
+| systematic-debugging | Four-phase debugging framework - investigate root cause before any fixes | /systematic-debugging <bug-or-error-description> | false |
+| test-driven-development | Write test first, watch it fail, write minimal code to pass | /test-driven-development <feature-or-behavior-to-test> | true |
+| test-generate | Generate comprehensive test suites for existing code | /test-generate <code-section> | - |
+| testing-anti-patterns | Prevents testing mock behavior and production pollution with test-only methods | /testing-anti-patterns <testing-scenario> | true |
+| verification-before-completion | Requires running verification commands before making any success claims | /verification-before-completion <work-to-verify> | true |
+
+All resources are auto-discovered from frontmatter in their respective directories:
+- **Agents**: `./droids/*.md`
+- **Commands**: `./commands/*.md`

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