easy-spec

Easy Spec - Claude Code Plugin & Marketplace

A simplified toolkit for generating research, specifications, plans, and tasks for feature development workflows.

📦 Installation

Option 1: Install from this marketplace

# Add this marketplace
/plugin marketplace add dzianis/easy-spec

# Install the easy-spec plugin
/plugin install easy-spec@dzianis/easy-spec

Option 2: Install directly

# Install the plugin directly from GitHub
/plugin install https://github.com/dzianis/easy-spec

🚀 Available Commands

This directory contains custom slash commands for automating common workflows.

Available Commands

/research - Generate Research Document

Automatically generates a research.md file by investigating existing patterns and technical approaches in the codebase.

Purpose: Find and document existing implementations, analyze options, and provide implementation guidance based on verified code patterns.

Usage:

# Basic usage
/research ai_tasks/another-big-project/ml-automation/new-feature/

# With problem statement
/research ai_tasks/another-big-project/ml-automation/s3-downloads/ Investigate concurrent S3 download patterns

# With project focus
/research ai_tasks/pipeline/icon-processing/ Focus on pipeline landmark icons patterns

What it does:

1. Reads the user's problem statement
2. Uses docs/templates/research_template.md as structure guidance
3. Searches for existing patterns in relevant projects:
   • pipeline (pipeline)
   • qa-tool (QA tools)
   • another-big-project-frontend
   • data-pipeline-exports
   • map-pipeline
4. Documents findings with actual file paths and code
5. Analyzes options with decision matrix
6. Provides implementation guidance
7. Outputs research.md in the feature folder

Requirements:

• Template file must exist at docs/templates/research_template.md

Key Principles:

• ✅ Reference actual code with full file paths
• ✅ Include verified findings (not assumptions)
• ✅ Show laconic code examples from existing implementations
• ✅ Provide decision rationale with trade-offs
• ❌ Don't invent solutions without checking existing code

Example Output:

## Existing Patterns

### Reference Implementation

**Location**: `/Users/dzianissheka/projects/dev/work/pipeline/src/service/s3-download.ts`
**Project**: pipeline
**Pattern**: Concurrent S3 downloads with parallel-transform

\`\`\`typescript
// Actual code from the project
const downloader = new S3Downloader({ concurrency: 10 });
await downloader.downloadFiles(urls, outputDir);
\`\`\`

## Decision Matrix

| Approach | Pros | Cons | Recommendation |
|----------|------|------|----------------|
| ThreadPoolExecutor | Python stdlib | Limited to I/O | ✅ Recommended |
| asyncio | Non-blocking | More complex | Consider if needed |

---

/spec - Generate Functional Requirements Specification

Automatically generates a spec.md file from research documents, focusing on functional requirements (WHAT users need, not HOW to implement).

Purpose: Convert research findings into clear, testable functional requirements for business stakeholders and developers.

Usage:

# Basic usage
/spec ai_tasks/another-big-project/ml-automation/feature-snapshotter/

# With custom instructions
/spec ai_tasks/data-pipeline/etl-process/ Focus on data validation and error recovery requirements

What it does:

1. Reads research documents from the feature folder (research.md, *research*.md)
2. Uses docs/templates/spec_template.md as the structure template
3. Extracts key information:
   • Problem statement and solution approach
   • User needs and scenarios
   • Input/output data requirements
   • Business logic and data transformations
4. Generates numbered functional requirements (FR-001, FR-002, ...)
5. Creates acceptance scenarios in Given-When-Then format
6. Identifies edge cases and error scenarios
7. Outputs spec.md in the feature folder

Requirements:

• Feature folder should contain research documents
• Template file must exist at docs/templates/spec_template.md

Key Principles:

• ✅ Focus on WHAT users need (functional requirements)
• ❌ Avoid HOW to implement (no tech stack, code, architecture)
• 👥 Written for business stakeholders, not just developers
• 📝 Use laconic, testable language

Example Output:

## Functional Requirements

### Input Data
- **FR-001**: System MUST accept GeoJSON files in RFC 7946 format
- **FR-002**: System MUST support Point, LineString, Polygon geometries

### Output Data
- **FR-010**: System MUST generate PNG images with configurable dimensions
- **FR-011**: System MUST name output files matching input basename

### Business Logic
- **FR-020**: System MUST calculate bounding box from all coordinates
- **FR-021**: System MUST calculate optimal zoom level to fit features

---

/plan - Generate Technical Implementation Plan