@amrhas82/agentic-kit 1.5.0 → 1.7.0

package/packages/opencode/agent/orchestrator.md

@@ -1,6 +1,6 @@
 ---
 name: orchestrator
-description: Use this agent for workflow coordination, multi-agent task management, role switching guidance, or when unsure which specialist to consult. Master coordinator for the agentic Method framework that assesses needs, recommends agents/workflows, manages multi-agent sequences, presents capability overviews, and handles context switching between subagents.
+description: Workflow coordinator - analyzes intent, matches to patterns, invokes agents with minimal context. Asks before each step.
 mode: primary
 temperature: 0.5
 tools:
@@ -9,97 +9,134 @@ tools:
   bash: true
 ---
 
-You are the agentic Master Orchestrator, a unified interface to all agentic-Method capabilities. You coordinate workflows, manage multi-agent tasks, provide role-switching guidance, and help users navigate the agentic framework efficiently.
+You coordinate multi-agent workflows. Analyze user intent → match to pattern → ask approval → invoke agents with selective context only.
+
+# Core Rules
+
+1. **Read ~/.config/opencode/AGENTS.md first** - Get agent registry + 9 workflow patterns
+2. **Match intent to pattern** - 85% confidence or ask clarifying questions
+3. **Ask before each step** - Get approval, don't auto-advance
+4. **Selective context only** - Pass minimal necessary info to agents
+5. **Track state** - Current step, outputs, next decision point
+
+# Workflow Patterns (from ~/.config/opencode/AGENTS.md)
+
+1. Feature Discovery: "add feature" → research? → PRD? → tasks? → implement
+2. Product Definition: "new product" → product-manager → product-owner → architect
+3. Story Implementation: "implement story" → validate? → full-stack-dev → qa
+4. Architecture Decision: "use tech X?" → business-analyst → architect → product-manager
+5. UI Development: "build UI" → ux-expert → PRD? → dev → qa
+6. Bug Triage: "bug X" → full-stack-dev → severity? → fix/story
+7. Brownfield Discovery: "understand code" → context-initializer → analyst → architect?
+8. Quality Validation: "review PR" → qa-test-architect → PASS/FAIL → dev?
+9. Sprint Planning: "plan sprint" → product-manager → scrum-master → tasks
+
+# Intent → Agent Mapping
+
+| Intent Keywords | Invoke |
+|---|---|
+| research, competitive, discovery | business-analyst |
+| PRD, requirements, scope | 1-create-prd |
+| tasks, breakdown, backlog | 2-generate-tasks |
+| implement, build, code | full-stack-dev |
+| review, quality, test | qa-test-architect |
+| design, UI, wireframe | ux-expert |
+| story, acceptance criteria | product-owner |
+| strategy, features, roadmap | product-manager |
+| epic, sprint, agile | scrum-master |
+| architecture, design, tech | holistic-architect |
+| understand, document, brownfield | context-initializer, business-analyst |
+| systematic implementation | 3-process-task-list |
+
+# Context Injection Rules
+
+When invoking agents, pass ONLY:
+
+**business-analyst**: Feature description, user needs
+**1-create-prd**: Research output (if any), requirements
+**2-generate-tasks**: PRD only
+**full-stack-dev**: Specs, relevant files (not full history)
+**qa-test-architect**: Code diff, acceptance criteria, test requirements
+**ux-expert**: Feature description, design requirements
+**product-owner**: Feature idea, user story drafts
+**holistic-architect**: Requirements, constraints, tech context
+
+❌ **NEVER pass**: Full conversation, unrelated outputs, tangential discussions
+
+# Execution Flow
+
+```
+1. Read ~/.config/opencode/AGENTS.md (agent registry + patterns)
+2. Analyze user intent (keywords, artifacts, complexity)
+3. Match to workflow pattern (85% threshold)
+4. Present workflow: "I matched this to [pattern]. Steps: [list]. Proceed?"
+5. Execute with conditional asks at each step
+6. Between steps: summarize output, ask approval, inject selective context
+7. Track: current agent, outputs, next decision point
+```
+
+# Conditional Execution Example
+
+User: "Add user authentication"
+
+```
+Match: Feature Discovery Flow
+
+Ask: "Research auth approaches first?"
+├─ Yes → Invoke: business-analyst with "research auth approaches for [project]"
+│         Wait for output → Ask: "Create formal PRD?"
+│         ├─ Yes → Invoke: 1-create-prd with research output only
+│         └─ No → Done (return research)
+└─ No → Skip to PRD step
+```
 
-# Core Identity
+# Commands
 
-You serve as the master coordinator who:
-- Dynamically transforms into any specialized agent on demand
-- Loads resources only when explicitly needed (never pre-load)
-- Assesses user needs and recommends the best approach, agent, or workflow
-- Tracks current state and guides users to logical next steps
-- Makes your active persona and current task explicit at all times
-- Uses numbered lists for all choice presentations
-- Processes commands starting with * (asterisk) immediately
-- Always reminds users that commands require the * prefix
+User commands start with *:
 
-# Resource Loading Rules
+Core: *help, *status, *exit
+Agent: *agent [name] (transform into agent)
+Workflow: *workflow [name], *plan, *yolo (skip confirmations)
 
-- **Agents**: Load ONLY when transforming into that specific agent
-- **Templates/Tasks/Checklists**: Load ONLY when executing them
-- **Workflows**: Discover and load at runtime when needed
-- Always indicate when you're loading resources
-- Never dump entire knowledge base contents immediately
+If user forgets *, remind them.
 
-# Commands
+# Transformation
 
-All user commands must start with * (asterisk):
-**Core**: *help (display guide), *chat-mode (conversational), *status (show context), *exit (exit session), *kb-mode (Load full Agentic Kit knowledge base)
-**Agent & Task**: *agent [name] (transform into agent), *task [name] (run task), *checklist [name] (execute checklist)
-**Workflow**: *workflow [name] (start workflow), *workflow-guidance (selection help), *plan (create plan), *plan-status (show progress), *plan-update (update status)
-**Other**: *yolo (toggle confirmations), *party-mode (group chat simulation), *doc-out (output to /docs/orchestrator)
-
-# Transformation Protocol
-
-When users request agents, tasks, or workflows:
-1. Use 85% confidence threshold for fuzzy matching
-2. If below threshold, present numbered list of options
-3. When transforming:
-   - Announce transformation clearly
-   - Adopt complete persona, style, and principles
-   - Operate as that agent until *exit invoked
-   - Specialized persona's principles take precedence while embodied
-
-# Workflow Guidance
-
-When providing workflow guidance:
-1. Discover available workflows at runtime (never assume)
-2. Understand purpose, options, and decision points
-3. Ask clarifying questions based on workflow structure
-4. Guide users through selection when multiple options exist
-5. Suggest creating detailed plan before starting when appropriate
-6. Help choose right path for workflows with divergent paths
-7. Adapt questions to specific domain
-8. Only recommend workflows that exist in current bundle
-9. Start interactive session and list workflows with descriptions
-10. When *kb-mode is invoked, use kb-mode-interaction task; don't dump all KB content immediately, present topic areas and wait for user selection, provide focused contextual responses
-
-# Interaction Style
-
-- Be encouraging and supportive while technically precise
-- Make recommendations proactively when seeing opportunities
-- Ask clarifying questions before assumptions
-- Explain reasoning when suggesting agents or workflows
-- Track conversation context and reference when relevant
-- Be explicit about actions ("I'm now loading...", "Transforming into...")
-- Always provide numbered lists for easy selection
-
-# Dependencies
-
-Load only when needed:
-- **Agents** (../AGENTS.md): Load ONLY when transforming into that specific agent
-- **Data** (../resources/data.md): elicitation-methods, knowledge-base
-- **Tasks** (../resources/task-briefs.md): advanced-elicitation, create-doc
-- **Workflows** (../resources/workflows.yaml): greenfield-fullstack, greenfield-service, greenfield-ui, brownfield-fullstack, brownfield-service, brownfield-ui
+When *agent [name]:
+1. Fuzzy match (85% threshold)
+2. If ambiguous, show numbered options
+3. Announce: "Transforming into [agent]"
+4. Load agent file, adopt full persona
+5. Operate as that agent until *exit
 
 # Status Tracking
 
-When *status invoked, provide:
-1. Current active agent (if any)
-2. Current task or workflow in progress
-3. Completed and remaining steps
-4. Relevant context from conversation
-5. Suggested next actions
-
-# Operational Rules
-
-1. **Never Pre-load** - Discover and load resources only when explicitly needed
-2. **Command Prefix** - Remind users commands need * prefix if forgotten
-3. **Transformation Clarity** - Always announce when becoming different agent
-4. **Numbered Lists** - Use for all options to facilitate selection
-5. **Context Awareness** - Track and maintain awareness of user's goal and progress
-6. **Proactive Guidance** - Suggest next steps and relevant agents/workflows
-7. **Resource Efficiency** - Only load what's needed for immediate task
-8. **User Empowerment** - Help users understand agentic Method while executing work
-
-Your goal is to make sessions efficient and powerful while maintaining clarity and avoiding information overload.
+When *status:
+- Current agent (if transformed)
+- Workflow step (if in progress)
+- Completed steps
+- Next decision point
+- Suggested action
+
+# Agent Registry
+
+14 agents available (see ~/.config/opencode/AGENTS.md):
+orchestrator, 1-create-prd, 2-generate-tasks, 3-process-task-list, business-analyst, context-initializer, full-stack-dev, holistic-architect, master, product-manager, product-owner, qa-test-architect, scrum-master, ux-expert
+
+16 skills available (see ~/.config/opencode/AGENTS.md)
+
+# Resource Loading
+
+❌ **DON'T** pre-load agent definitions, workflows, tasks
+✅ **DO** load on-demand when explicitly needed
+✅ **DO** announce: "Loading [resource]..."
+
+# Key Principles
+
+- **Lazy loading**: Read files only when needed
+- **Minimal context**: Pass only what's essential
+- **Ask, don't assume**: Get approval before advancing
+- **Track state**: Always know where you are in workflow
+- **Be explicit**: Announce transformations, loading, decisions
+
+Your job: Route intelligently, ask before acting, inject context selectively, track state clearly.

package/packages/opencode/subagentic-manual.md

@@ -16,10 +16,10 @@ Install and invoke for your platform:
 
 | Platform | Installation | Invocation |
 |----------|--------------|-----------|
-| **Claude Code** | `cp -rv ai/subagents/claude/* ~/.claude/` | `@agent-name` or `As agent-name, ...` |
-| **OpenCode** | `cp -rv ai/subagents/opencode/* ~/.config/opencode/` | `@agent-name` or `As agent-name, ...` |
-| **Amp** | `cp -rv ai/subagents/ampcode/* ~/.config/amp/` | `As agent-name, ...` |
-| **Droid** | `cp -rv ai/subagents/droid/* ~/.factory/` + enable in `~/.factory/settings.json` | `invoke droid agent_name` |
+| **Claude Code** | `cp -rv ai/subagentic/claude/* ~/.claude/` | Automatic via orchestrator (or `@agent-name`, `As agent-name, ...`) |
+| **OpenCode** | `cp -rv ai/subagentic/opencode/* ~/.config/opencode/` | Automatic via orchestrator (or `@agent-name` or `As agent-name, ...` )|
+| **Amp** | `cp -rv ai/subagentic/ampcode/* ~/.config/amp/` | Automatic via orchestrator (or `As agent-name, ...` )|
+| **Droid** | `cp -rv ai/subagentic/droid/* ~/.factory/` + enable in `~/.factory/settings.json` | Automatic via orchestrator (or `invoke droid agent_name`) |
 
 ---
 
@@ -36,74 +36,78 @@ Install and invoke for your platform:
 ## 🤖 14 Subagents
 
 ### Workflow Phase Agents (3)
-| Agent | Purpose |
-|-------|---------|
-| **1-create-prd** | Create Product Requirement Documents with structured scope and requirements |
-| **2-generate-tasks** | Break PRDs into granular, actionable task lists |
-| **3-process-task-list** | Execute tasks iteratively with built-in review and progress tracking |
+| Agent | Purpose | Token Load* |
+|-------|---------|------------|
+| **1-create-prd** | Create Product Requirement Documents with structured scope and requirements | ~889 tokens |
+| **2-generate-tasks** | Break PRDs into granular, actionable task lists | ~1,029 tokens |
+| **3-process-task-list** | Execute tasks iteratively with built-in review and progress tracking | ~1,004 tokens |
 
 **Recommended Workflow:** PRD → Tasks → Process → Complete
 
 ### Specialist Agents (11)
-| Agent | Purpose |
-|-------|---------|
-| **ux-expert** | UI/UX design, wireframes, prototypes, front-end specifications |
-| **scrum-master** | User stories, epic management, agile process guidance |
-| **qa-test-architect** | Test architecture, quality gates, code review feedback |
-| **product-owner** | Backlog management, story refinement, acceptance criteria |
-| **product-manager** | PRDs, product strategy, feature prioritization, roadmaps |
-| **full-stack-dev** | Code implementation, debugging, refactoring |
-| **holistic-architect** | System design, architecture docs, API design, scalability |
-| **business-analyst** | Market research, competitive analysis, project discovery |
-| **orchestrator** | Workflow coordination, multi-agent task management |
-| **master** | Comprehensive expertise across all domains, universal executor |
-| **context-initializer** | Project context setup, documentation discovery and organization |
+| Agent | Purpose | Token Load*    |
+|-------|---------|----------------|
+| **ux-expert** | UI/UX design, wireframes, prototypes, front-end specifications | ~1,113 tokens  |
+| **scrum-master** | User stories, epic management, agile process guidance | ~927 tokens    |
+| **qa-test-architect** | Test architecture, quality gates, code review feedback | ~1,351 tokens  |
+| **product-owner** | Backlog management, story refinement, acceptance criteria | ~1,299 tokens  |
+| **product-manager** | PRDs, product strategy, feature prioritization, roadmaps | ~1,243 tokens  |
+| **full-stack-dev** | Code implementation, debugging, refactoring | ~1,025 tokens  |
+| **holistic-architect** | System design, architecture docs, API design, scalability | ~1,427 tokens  |
+| **business-analyst** | Market research, competitive analysis, project discovery | ~1,295 tokens  |
+| **orchestrator** | Workflow coordination, multi-agent task management, automatic routing | ~902 tokens    |
+| **master** | Comprehensive expertise across all domains, universal executor | ~1,073 tokens  |
+| **context-initializer** | Project context setup, documentation discovery, creates CLAUDE.md with agent system | ~1,614 tokens |
+
+**\*Progressive Disclosure:** Token loads shown are **full agent sizes when invoked**. Your base conversation only loads lightweight stubs (~50-90 tokens each, ~967 tokens total for all 14 agents). Full agent content loads only when you invoke that specific agent via `Task` tool. Check with `/context` command to see actual current usage.
 
 ---
 
 ## 🛠 22 Reusable Skills
 
 ### Development & Testing (7)
-| Skill | Purpose |
-|-------|---------|
-| **test-driven-development** | Write tests first, red-green-refactor cycle ensures tests verify behavior |
-| **testing-anti-patterns** | Avoid mock testing, test-only code, and mindless mocking |
-| **code-review** | Structured code review workflow before merging |
-| **systematic-debugging** | Four-phase debugging: investigate → analyze → hypothesize → implement |
-| **root-cause-tracing** | Trace bugs backward through call stack to find original trigger |
-| **condition-based-waiting** | Replace timeouts with polling to eliminate flaky tests |
-| **verification-before-completion** | Verify claims with evidence before marking tasks complete |
+| Skill | Purpose | Token Load* |
+|-------|---------|------------|
+| **test-driven-development** | Write tests first, red-green-refactor cycle ensures tests verify behavior | ~2,434 tokens |
+| **testing-anti-patterns** | Avoid mock testing, test-only code, and mindless mocking | ~2,101 tokens |
+| **code-review** | Structured code review workflow before merging | ~846 tokens |
+| **systematic-debugging** | Four-phase debugging: investigate → analyze → hypothesize → implement | ~163 tokens |
+| **root-cause-tracing** | Trace bugs backward through call stack to find original trigger | ~1,400 tokens |
+| **condition-based-waiting** | Replace timeouts with polling to eliminate flaky tests | ~937 tokens |
+| **verification-before-completion** | Verify claims with evidence before marking tasks complete | ~1,050 tokens |
 
 ### Design & Creativity (5)
-| Skill | Purpose |
-|-------|---------|
-| **algorithmic-art** | Create generative art using p5.js with seeded randomness |
-| **canvas-design** | Create visual art in PNG/PDF with design philosophy |
-| **artifacts-builder** | Build React/TypeScript/Tailwind/shadcn artifacts with Parcel bundling |
-| **theme-factory** | Apply 10 curated professional themes with color/font pairings |
-| **slack-gif-creator** | Create optimized animated GIFs for Slack |
+| Skill | Purpose | Token Load* |
+|-------|---------|------------|
+| **algorithmic-art** | Create generative art using p5.js with seeded randomness | ~4,942 tokens |
+| **canvas-design** | Create visual art in PNG/PDF with design philosophy | ~2,984 tokens |
+| **artifacts-builder** | Build React/TypeScript/Tailwind/shadcn artifacts with Parcel bundling | ~769 tokens |
+| **theme-factory** | Apply 10 curated professional themes with color/font pairings | ~781 tokens |
+| **slack-gif-creator** | Create optimized animated GIFs for Slack | ~4,285 tokens |
 
 ### Office & Document Processing (4)
-| Skill | Purpose |
-|-------|---------|
-| **pdf** | Extract/create PDFs, merge/split, handle forms and tables |
-| **docx** | Create/edit Word documents with tracked changes and comments |
-| **pptx** | Create/edit PowerPoint with design-first approach and HTML conversion |
-| **xlsx** | Create/edit spreadsheets with formulas, formatting, and data analysis |
+| Skill | Purpose | Token Load* |
+|-------|---------|------------|
+| **pdf** | Extract/create PDFs, merge/split, handle forms and tables | ~2,359 tokens |
+| **docx** | Create/edit Word documents with tracked changes and comments | ~2,537 tokens |
+| **pptx** | Create/edit PowerPoint with design-first approach and HTML conversion | ~6,387 tokens |
+| **xlsx** | Create/edit spreadsheets with formulas, formatting, and data analysis | ~2,658 tokens |
 
 ### Strategy & Communication (4)
-| Skill | Purpose |
-|-------|---------|
-| **brainstorming** | Collaborative design through questioning and exploration |
-| **internal-comms** | Write internal communications with company-approved formats |
-| **brand-guidelines** | Apply Anthropic's official brand colors and typography |
-| **mcp-builder** | Create MCP servers for LLM-service integration |
+| Skill | Purpose | Token Load* |
+|-------|---------|------------|
+| **brainstorming** | Collaborative design through questioning and exploration | ~640 tokens |
+| **internal-comms** | Write internal communications with company-approved formats | ~377 tokens |
+| **brand-guidelines** | Apply Anthropic's official brand colors and typography | ~558 tokens |
+| **mcp-builder** | Create MCP servers for LLM-service integration | ~3,388 tokens |
 
 ### Specialized (2)
-| Skill | Purpose |
-|-------|---------|
-| **webapp-testing** | Test local web apps with Playwright – verify, debug, screenshot |
-| **skill-creator** | Create custom skills extending Claude's capabilities |
+| Skill | Purpose | Token Load* |
+|-------|---------|------------|
+| **webapp-testing** | Test local web apps with Playwright – verify, debug, screenshot | ~978 tokens |
+| **skill-creator** | Create custom skills extending Claude's capabilities | ~2,886 tokens |
+
+**\*Progressive Disclosure:** Token loads shown are **full skill sizes when activated**. Skills load on-demand via the `Skill` tool when you invoke them (e.g., `/pdf`, `/brainstorming`). Until activated, skills consume minimal tokens as slash command metadata (~3.1k tokens total for all 22 skills). Use `/context` to monitor actual usage.
 
 ---
 
@@ -146,10 +150,21 @@ Pre-built workflows for common development patterns (available in all kits):
 
 ## 🎯 How to Use This Package
 
+### Claude Code (Orchestrator-First Pattern)
+1. **Install** – `cp -rv ai/subagentic/claude/* ~/.claude/`
+2. **Make requests naturally** – "Add authentication feature", "Review this code", "Plan next sprint"
+3. **Orchestrator routes automatically** – Matches intent to optimal workflow, asks conditional questions
+4. **Bypass when needed** – `@agent-name` or `As agent-name, ...` for direct agent access
+5. **9 workflow patterns** – Pre-defined sequences in CLAUDE.md (Feature Discovery, Architecture Decision, etc.)
+
+**Key files:**
+- `~/.claude/CLAUDE.md` – Agent system with orchestrator-first routing and 9 workflows
+- `~/.claude/agents/` – 14 specialist agents (orchestrator, 1-create-prd, full-stack-dev, qa, etc.)
+- Project `CLAUDE.md` – Auto-created by context-initializer with agent system reminder
+
+### Other Platforms
 1. **Clone and Install** – Copy files to your CLI's config directory
 2. **Start with Workflow** – Use 1-create-prd → 2-generate-tasks → 3-process-task-list
 3. **Add Specialists** – Invoke agents by name for specific domain expertise
 4. **Leverage Skills** – Use skills within agents for specialized capabilities
 5. **Reuse Tasks** – Apply pre-built task templates for common patterns
-
-**Across all four platforms:** Claude Code, OpenCode, Amp, Droid

package/packages/subagentic-manual.md

@@ -16,10 +16,10 @@ Install and invoke for your platform:
 
 | Platform | Installation | Invocation |
 |----------|--------------|-----------|
-| **Claude Code** | `cp -rv ai/subagents/claude/* ~/.claude/` | `@agent-name` or `As agent-name, ...` |
-| **OpenCode** | `cp -rv ai/subagents/opencode/* ~/.config/opencode/` | `@agent-name` or `As agent-name, ...` |
-| **Amp** | `cp -rv ai/subagents/ampcode/* ~/.config/amp/` | `As agent-name, ...` |
-| **Droid** | `cp -rv ai/subagents/droid/* ~/.factory/` + enable in `~/.factory/settings.json` | `invoke droid agent_name` |
+| **Claude Code** | `cp -rv ai/subagentic/claude/* ~/.claude/` | Automatic via orchestrator (or `@agent-name`, `As agent-name, ...`) |
+| **OpenCode** | `cp -rv ai/subagentic/opencode/* ~/.config/opencode/` | Automatic via orchestrator (or `@agent-name` or `As agent-name, ...` )|
+| **Amp** | `cp -rv ai/subagentic/ampcode/* ~/.config/amp/` | Automatic via orchestrator (or `As agent-name, ...` )|
+| **Droid** | `cp -rv ai/subagentic/droid/* ~/.factory/` + enable in `~/.factory/settings.json` | Automatic via orchestrator (or `invoke droid agent_name`) |
 
 ---
 
@@ -36,74 +36,78 @@ Install and invoke for your platform:
 ## 🤖 14 Subagents
 
 ### Workflow Phase Agents (3)
-| Agent | Purpose |
-|-------|---------|
-| **1-create-prd** | Create Product Requirement Documents with structured scope and requirements |
-| **2-generate-tasks** | Break PRDs into granular, actionable task lists |
-| **3-process-task-list** | Execute tasks iteratively with built-in review and progress tracking |
+| Agent | Purpose | Token Load* |
+|-------|---------|------------|
+| **1-create-prd** | Create Product Requirement Documents with structured scope and requirements | ~889 tokens |
+| **2-generate-tasks** | Break PRDs into granular, actionable task lists | ~1,029 tokens |
+| **3-process-task-list** | Execute tasks iteratively with built-in review and progress tracking | ~1,004 tokens |
 
 **Recommended Workflow:** PRD → Tasks → Process → Complete
 
 ### Specialist Agents (11)
-| Agent | Purpose |
-|-------|---------|
-| **ux-expert** | UI/UX design, wireframes, prototypes, front-end specifications |
-| **scrum-master** | User stories, epic management, agile process guidance |
-| **qa-test-architect** | Test architecture, quality gates, code review feedback |
-| **product-owner** | Backlog management, story refinement, acceptance criteria |
-| **product-manager** | PRDs, product strategy, feature prioritization, roadmaps |
-| **full-stack-dev** | Code implementation, debugging, refactoring |
-| **holistic-architect** | System design, architecture docs, API design, scalability |
-| **business-analyst** | Market research, competitive analysis, project discovery |
-| **orchestrator** | Workflow coordination, multi-agent task management |
-| **master** | Comprehensive expertise across all domains, universal executor |
-| **context-initializer** | Project context setup, documentation discovery and organization |
+| Agent | Purpose | Token Load*    |
+|-------|---------|----------------|
+| **ux-expert** | UI/UX design, wireframes, prototypes, front-end specifications | ~1,113 tokens  |
+| **scrum-master** | User stories, epic management, agile process guidance | ~927 tokens    |
+| **qa-test-architect** | Test architecture, quality gates, code review feedback | ~1,351 tokens  |
+| **product-owner** | Backlog management, story refinement, acceptance criteria | ~1,299 tokens  |
+| **product-manager** | PRDs, product strategy, feature prioritization, roadmaps | ~1,243 tokens  |
+| **full-stack-dev** | Code implementation, debugging, refactoring | ~1,025 tokens  |
+| **holistic-architect** | System design, architecture docs, API design, scalability | ~1,427 tokens  |
+| **business-analyst** | Market research, competitive analysis, project discovery | ~1,295 tokens  |
+| **orchestrator** | Workflow coordination, multi-agent task management, automatic routing | ~902 tokens    |
+| **master** | Comprehensive expertise across all domains, universal executor | ~1,073 tokens  |
+| **context-initializer** | Project context setup, documentation discovery, creates CLAUDE.md with agent system | ~1,614 tokens |
+
+**\*Progressive Disclosure:** Token loads shown are **full agent sizes when invoked**. Your base conversation only loads lightweight stubs (~50-90 tokens each, ~967 tokens total for all 14 agents). Full agent content loads only when you invoke that specific agent via `Task` tool. Check with `/context` command to see actual current usage.
 
 ---
 
 ## 🛠 22 Reusable Skills
 
 ### Development & Testing (7)
-| Skill | Purpose |
-|-------|---------|
-| **test-driven-development** | Write tests first, red-green-refactor cycle ensures tests verify behavior |
-| **testing-anti-patterns** | Avoid mock testing, test-only code, and mindless mocking |
-| **code-review** | Structured code review workflow before merging |
-| **systematic-debugging** | Four-phase debugging: investigate → analyze → hypothesize → implement |
-| **root-cause-tracing** | Trace bugs backward through call stack to find original trigger |
-| **condition-based-waiting** | Replace timeouts with polling to eliminate flaky tests |
-| **verification-before-completion** | Verify claims with evidence before marking tasks complete |
+| Skill | Purpose | Token Load* |
+|-------|---------|------------|
+| **test-driven-development** | Write tests first, red-green-refactor cycle ensures tests verify behavior | ~2,434 tokens |
+| **testing-anti-patterns** | Avoid mock testing, test-only code, and mindless mocking | ~2,101 tokens |
+| **code-review** | Structured code review workflow before merging | ~846 tokens |
+| **systematic-debugging** | Four-phase debugging: investigate → analyze → hypothesize → implement | ~163 tokens |
+| **root-cause-tracing** | Trace bugs backward through call stack to find original trigger | ~1,400 tokens |
+| **condition-based-waiting** | Replace timeouts with polling to eliminate flaky tests | ~937 tokens |
+| **verification-before-completion** | Verify claims with evidence before marking tasks complete | ~1,050 tokens |
 
 ### Design & Creativity (5)
-| Skill | Purpose |
-|-------|---------|
-| **algorithmic-art** | Create generative art using p5.js with seeded randomness |
-| **canvas-design** | Create visual art in PNG/PDF with design philosophy |
-| **artifacts-builder** | Build React/TypeScript/Tailwind/shadcn artifacts with Parcel bundling |
-| **theme-factory** | Apply 10 curated professional themes with color/font pairings |
-| **slack-gif-creator** | Create optimized animated GIFs for Slack |
+| Skill | Purpose | Token Load* |
+|-------|---------|------------|
+| **algorithmic-art** | Create generative art using p5.js with seeded randomness | ~4,942 tokens |
+| **canvas-design** | Create visual art in PNG/PDF with design philosophy | ~2,984 tokens |
+| **artifacts-builder** | Build React/TypeScript/Tailwind/shadcn artifacts with Parcel bundling | ~769 tokens |
+| **theme-factory** | Apply 10 curated professional themes with color/font pairings | ~781 tokens |
+| **slack-gif-creator** | Create optimized animated GIFs for Slack | ~4,285 tokens |
 
 ### Office & Document Processing (4)
-| Skill | Purpose |
-|-------|---------|
-| **pdf** | Extract/create PDFs, merge/split, handle forms and tables |
-| **docx** | Create/edit Word documents with tracked changes and comments |
-| **pptx** | Create/edit PowerPoint with design-first approach and HTML conversion |
-| **xlsx** | Create/edit spreadsheets with formulas, formatting, and data analysis |
+| Skill | Purpose | Token Load* |
+|-------|---------|------------|
+| **pdf** | Extract/create PDFs, merge/split, handle forms and tables | ~2,359 tokens |
+| **docx** | Create/edit Word documents with tracked changes and comments | ~2,537 tokens |
+| **pptx** | Create/edit PowerPoint with design-first approach and HTML conversion | ~6,387 tokens |
+| **xlsx** | Create/edit spreadsheets with formulas, formatting, and data analysis | ~2,658 tokens |
 
 ### Strategy & Communication (4)
-| Skill | Purpose |
-|-------|---------|
-| **brainstorming** | Collaborative design through questioning and exploration |
-| **internal-comms** | Write internal communications with company-approved formats |
-| **brand-guidelines** | Apply Anthropic's official brand colors and typography |
-| **mcp-builder** | Create MCP servers for LLM-service integration |
+| Skill | Purpose | Token Load* |
+|-------|---------|------------|
+| **brainstorming** | Collaborative design through questioning and exploration | ~640 tokens |
+| **internal-comms** | Write internal communications with company-approved formats | ~377 tokens |
+| **brand-guidelines** | Apply Anthropic's official brand colors and typography | ~558 tokens |
+| **mcp-builder** | Create MCP servers for LLM-service integration | ~3,388 tokens |
 
 ### Specialized (2)
-| Skill | Purpose |
-|-------|---------|
-| **webapp-testing** | Test local web apps with Playwright – verify, debug, screenshot |
-| **skill-creator** | Create custom skills extending Claude's capabilities |
+| Skill | Purpose | Token Load* |
+|-------|---------|------------|
+| **webapp-testing** | Test local web apps with Playwright – verify, debug, screenshot | ~978 tokens |
+| **skill-creator** | Create custom skills extending Claude's capabilities | ~2,886 tokens |
+
+**\*Progressive Disclosure:** Token loads shown are **full skill sizes when activated**. Skills load on-demand via the `Skill` tool when you invoke them (e.g., `/pdf`, `/brainstorming`). Until activated, skills consume minimal tokens as slash command metadata (~3.1k tokens total for all 22 skills). Use `/context` to monitor actual usage.
 
 ---
 
@@ -146,10 +150,21 @@ Pre-built workflows for common development patterns (available in all kits):
 
 ## 🎯 How to Use This Package
 
+### Claude Code (Orchestrator-First Pattern)
+1. **Install** – `cp -rv ai/subagentic/claude/* ~/.claude/`
+2. **Make requests naturally** – "Add authentication feature", "Review this code", "Plan next sprint"
+3. **Orchestrator routes automatically** – Matches intent to optimal workflow, asks conditional questions
+4. **Bypass when needed** – `@agent-name` or `As agent-name, ...` for direct agent access
+5. **9 workflow patterns** – Pre-defined sequences in CLAUDE.md (Feature Discovery, Architecture Decision, etc.)
+
+**Key files:**
+- `~/.claude/CLAUDE.md` – Agent system with orchestrator-first routing and 9 workflows
+- `~/.claude/agents/` – 14 specialist agents (orchestrator, 1-create-prd, full-stack-dev, qa, etc.)
+- Project `CLAUDE.md` – Auto-created by context-initializer with agent system reminder
+
+### Other Platforms
 1. **Clone and Install** – Copy files to your CLI's config directory
 2. **Start with Workflow** – Use 1-create-prd → 2-generate-tasks → 3-process-task-list
 3. **Add Specialists** – Invoke agents by name for specific domain expertise
 4. **Leverage Skills** – Use skills within agents for specialized capabilities
 5. **Reuse Tasks** – Apply pre-built task templates for common patterns
-
-**Across all four platforms:** Claude Code, OpenCode, Amp, Droid