| name | amplihack-expert |
| description | Comprehensive knowledge of amplihack framework architecture, patterns, and usage |
| version | 2.0.0 |
| author | amplihack team |
| tags | ["amplihack","framework","architecture","workflows","agents","commands"] |
| triggers | {"keywords":["amplihack","dev-orchestrator","smart-orchestrator","/dev","workstream","recipe runner","workflow","DEFAULT_WORKFLOW","/.claude/","agent system","specialized agent","command system","hook system","continuous work","skill system","extensibility"],"patterns":["How does amplihack.*work","What is.*amplihack","amplihack.*(architecture|structure|design)","How do I.*amplihack","What.*agents.*available","How.*orchestrat","When.*use.*dev|When.*use.*/dev"],"file_paths":["~/.amplihack/",".claude/agents/",".claude/commands/",".claude/workflow/",".claude/skills/"]} |
| token_budget | {"skill_md":800,"reference_md":1200,"examples_md":600,"total":2600} |
| disclosure_strategy | {"quick_answer":"SKILL.md only","architecture_question":"SKILL.md + reference.md","how_to_question":"SKILL.md + examples.md","comprehensive":"All three files"} |
| references | ["reference.md: Comprehensive architecture details","examples.md: Real-world usage scenarios","@~/.amplihack/.claude/context/PHILOSOPHY.md: Core principles","@~/.amplihack/.claude/workflow/DEFAULT_WORKFLOW.md: Main workflow"] |
amplihack Expert Knowledge
What is amplihack?
Engineering system for coding CLIs (Claude, Copilot, Amplifier): 5 mechanisms, 23-step workflow, 30+ agents, 80+ skills. Core entry point: /dev <task> — unified task orchestrator with auto-classification, parallel workstream detection, and goal-seeking execution loop.
Quick Reference
Top Commands
| Command | Purpose | Use When |
|---|
| /dev | Orchestrate | Any non-trivial task |
| /analyze | Review | Check compliance |
| /fix | Fix errors | Common error patterns |
| /amplihack:ddd:* | Doc-driven dev | 10+ file features |
| /multitask | Parallel tasks | Sprint/batch work |
Top Agents
| Agent | Role |
|---|
| architect | Design |
| builder | Code |
| reviewer | Quality |
| tester | Tests |
Workflows
| Name | Steps |
|---|
| DEFAULT_WORKFLOW | 23 |
| INVESTIGATION | 6 |
| FIX | 3 |
Navigation Guide
Quick: SKILL.md | Architecture: reference.md | How-To: examples.md | Deep: all
Core Concepts
5 Mechanisms: Workflow (process), Command (entry), Skill (auto), Agent (delegate), Hook (runtime)
Composition: Commands → Workflows → Agents → Skills
Execution: /dev orchestrates — classifies task, detects parallel workstreams, executes via smart-orchestrator recipe, goal-seeking loop (3 rounds max)
Entry point: /dev <task> → dev-orchestrator skill → smart-orchestrator recipe → default-workflow recipe
dev-orchestrator Architecture
Entry point: /dev <task> or any non-trivial prompt
Routing:
- Q&A →
amplihack:core:analyzer responds directly
- Operations → bash (simple) or
amplihack:core:builder (complex)
- Development/Investigation → smart-orchestrator recipe (full orchestration)
Execution flow:
- Classify task (architect agent → JSON decomposition)
- Detect workstreams (1 = single session, 2-5 = parallel via multitask)
- Register session in tree (depth/capacity enforcement)
- Execute rounds (up to 3, goal-seeking reflection loop)
- Summarize results with PR links and GOAL_STATUS
Session tree: Prevents infinite recursion
AMPLIHACK_MAX_DEPTH=3 (default) — increase to 5 for deep orchestrationAMPLIHACK_MAX_SESSIONS=10 (default) — max concurrent sessions per tree
Status signals:
GOAL_STATUS: ACHIEVED — all criteria metGOAL_STATUS: PARTIAL -- [gaps] — another round will runGOAL_STATUS: NOT_ACHIEVED -- [reason] — final failure status
Related Docs
- reference.md: Architecture (5 mechanisms, 5 layers, hooks)
- examples.md: Scenarios (5+ real examples)
- @~/.amplihack/.claude/context/PHILOSOPHY.md: Core principles
- @~/.amplihack/.claude/workflow/DEFAULT_WORKFLOW.md: 23 steps
- @~/.amplihack/.claude/agents/amplihack/: All agents
- @~/.amplihack/.claude/commands/amplihack/: All commands
- @~/.amplihack/.claude/tools/amplihack/hooks/: Hook system
- amplifier-bundle/recipes/smart-orchestrator.yaml: Core orchestration recipe
- Native recursion guard via
AMPLIHACK_MAX_DEPTH env var
amplihack orch helper: Native Rust JSON extraction (source: crates/amplihack-cli/src/commands/orch.rs)
Known Failure Points
Rate-limit resilience
When an upstream API (Copilot, Anthropic) returns a rate-limit error during an
agent step, the recipe runner treats it as a hard failure by default. Non-critical
steps such as step-06c-documentation-refinement set continue_on_error: true
so that documentation polish does not abort the entire recipe. For critical steps,
the agent runtime retries with exponential back-off (configured by the SDK adapter).
If a rate-limit error aborts your workflow, check which step failed — if it is a
polish/review step, adding continue_on_error: true is the recommended fix.
