hermes-spec Plugin Documentation

Overview

The hermes-spec plugin brings Spec-Driven Development (SDD) to Hermes Agent, inspired by Smart Ralph. It provides a structured workflow that guides you from idea to production through well-defined phases, each producing persistent artifacts.

Key Features

• 11 Specialized Tools covering the full SDD lifecycle
• Profile-Aware Delegation automatically routes work to the right Hermes profile
• Skill Integration leverages existing Hermes skills (plan, test-driven-development, etc.)
• Persistent Artifacts stored in .spec/ directory, version-controllable
• Progress Tracking with spec_status dashboard
• Workflow Presets for common scenarios (greenfield, feature, bugfix, etc.)
• Graceful Degradation works with or without Graphiti/Graphify
• Quality Gates enforce completion of each phase before proceeding

Installation

The plugin is automatically installed in all Hermes profiles. To verify:

# Check if plugin is loaded (after restarting Hermes)
spec_status

If you see "No .spec directory found", the plugin is loaded and ready.

Quick Start

# 1. Initialize a new spec project
spec_init --project_name "Task API" --goal "Build a REST API for task management"

# 2. Research phase
spec_research --focus "FastAPI best practices, async patterns"

# 3. Requirements
spec_requirements --format user_stories

# 4. Design
spec_design --include_diagrams true --arch_style monolith

# 5. Task breakdown
spec_tasks --time_unit hours --detail_level medium

# 6. Implementation (incremental)
spec_implement --work_incrementally true

# 7. Testing
spec_test --test_type both --coverage_threshold 80

# 8. Review
spec_review --focus all --fix_automatically true

# 9. Documentation
spec_docs --doc_type all --audience both

# 10. Check status
spec_status

Tool Reference

spec_init

Initialize a new spec-driven project.

Arguments:

• project_name (string, required): Human-readable project name
• goal (string, required): Brief description of project goal

Example:

spec_init --project_name "User Service" --goal "Microservice for user authentication and profiles"

spec_research

Perform research for the project. Delegates to researcher profile.

Arguments:

• focus (string, optional): Specific area to focus on
• use_graphiti (boolean, default: false): Query Graphiti for existing knowledge
• use_graphify (boolean, default: false): Run Graphify semantic search

spec_requirements

Generate requirements from research. Delegates to writer profile.

Arguments:

• format (enum: user_stories|use_cases|brief, default: user_stories): Output format

spec_design

Create technical design from requirements. Delegates to coder profile.

Arguments:

• include_diagrams (boolean, default: true): Include Mermaid diagrams
• arch_style (enum: microservices|monolith|layered|event-driven, optional): Preferred architecture

spec_tasks

Break down design into hierarchical tasks. Uses planning methodology.

Arguments:

• time_unit (enum: hours|days, default: hours): Estimation unit
• detail_level (enum: high|medium|low, default: medium): Granularity

spec_implement

Implement features following task list. Delegates to coder profile.

Arguments:

• start_from (string, optional): Task ID to start from (e.g., "T3")
• work_incrementally (boolean, default: false): Pause after each task

spec_test

Run tests with TDD methodology. Delegates to coder profile.

Arguments:

• test_type (enum: unit|integration|both|all, default: both): Test categories
• coverage_threshold (number, default: 80): Minimum coverage percentage

spec_review

Perform code review. Delegates to coder profile with requesting-code-review skill.

Arguments:

• focus (enum: security|style|performance|all, default: all): Review focus
• fix_automatically (boolean, default: false): Apply auto-fixes

spec_docs

Generate documentation. Delegates to writer profile.

Arguments:

• doc_type (enum: readme|api|changelog|all, default: all): Documentation types
• audience (enum: end_users|developers|both, default: both): Target audience

spec_status

Show workflow progress dashboard.

Arguments: None

spec_cleanup

Run code simplification and optionally remove .spec directory.

Arguments:

• remove_spec_dir (boolean, default: false): Delete .spec after cleanup
• level (enum: light|moderate|aggressive, default: moderate): Cleanup intensity

Workflows

Predefined workflows for common scenarios:

Workflow	Description	Use Case
greenfield	Full SDD for new projects	Starting from scratch
feature	Add feature to existing project	New feature development
bugfix	Bug fix with root cause analysis	Production bug fixes
refactor	Safe refactoring with verification	Technical debt reduction
migration	Technology/framework migration	Major version upgrades
release	Release preparation and execution	Version releases
documentation	Comprehensive documentation	Docs-only projects
api	API design and implementation	REST/GraphQL APIs

Running a Workflow

Workflows are YAML files in workflows/. Run each step sequentially:

# Example: greenfield workflow
spec_init --project_name "My Project" --goal "Build a blog platform"
spec_research --use_graphiti true --use_graphify true
spec_requirements --format user_stories
# ... continue through all steps

Or create a script to run them automatically.

Project Artifacts

All artifacts stored in .spec/ directory:

.spec/
├── metadata.json          # Project metadata
├── research.md            # Research findings
├── requirements.md        # User stories, acceptance criteria
├── design.md              # Technical architecture
├── tasks.md               # Hierarchical task breakdown
├── implementation.md      # Implementation notes
├── testing.md             # Test results
├── review.md              # Code review findings
├── documentation.md       # User-facing docs
└── changelog.md           # Version history (if generated)

Profile & Skill Mapping

Phase	Hermes Profile	Skills Used
Research	researcher	web_search, Graphiti, Graphify
Requirements	writer	—
Design	coder	plan
Tasks	coder	plan
Implementation	coder	—
Testing	coder	test-driven-development
Review	coder	requesting-code-review
Documentation	writer	—
Cleanup	coder	simplify-code

Graphiti & Graphify Integration

If installed, the plugin automatically uses them during research:

• Graphiti: Retrieves architecture decisions, past implementations, API knowledge
• Graphify: Semantic search over codebase for patterns and components

Enable with:

spec_research --use_graphiti true --use_graphify true

Quality Gates

The workflow enforces implicit quality gates:

1. Research must complete before requirements
2. Requirements must complete before design
3. Design must complete before tasks
4. Tasks must complete before implementation
5. Implementation should pass tests before review
6. Review should pass before documentation

Use spec_status to verify phase completion.

Extending the Plugin

Adding New Workflows

1. Create a YAML file in workflows/ following the schema
2. Reference existing tools with appropriate arguments
3. Document in this README

Adding New Tools

1. Add schema and handler to __init__.py
2. Register in register(ctx) function
3. Update plugin.yaml with new tool name
4. Restart Hermes

Custom Templates

Add templates to templates/ directory for:

• Spec file templates
• Diagram templates
• Documentation templates

Troubleshooting

"Plugin not found" / Tools not available

• Restart Hermes session (required for plugin discovery)
• Verify hermes-spec in plugins.enabled in config.yaml
• Verify spec in toolsets in config.yaml

"No .spec directory found"

• Run spec_init first to initialize the project

Delegate task fails

• Ensure target profile exists (coder, researcher, writer, etc.)
• Check Hermes logs for delegation errors

Graphiti/Graphify not working

• Tools are optional; plugin works without them
• Verify MCP servers are running if enabled

Examples

See examples/ directory for complete project walkthroughs:

• task-api/ - REST API example
• blog-platform/ - Full-stack example
• microservice-migration/ - Migration example

Contributing

1. Fork the plugin
2. Add features/workflows
3. Update documentation
4. Submit PR

License

MIT License - See LICENSE file