Skip to main content

SpecifyX Development Workflow

This guide covers the complete specification-driven development workflow using SpecifyX. If you haven't installed SpecifyX yet, start with the Installation Guide.

Overview​

SpecifyX follows a structured six-phase development process with quality gates:

  1. Specify - Define what to build
  2. Clarify - Resolve ambiguities and missing details
  3. Plan - Design how to build it
  4. Tasks - Break down into executable tasks
  5. Analyze - Validate consistency before implementation
  6. Implement - Execute tasks with guidance or automation

Phase 1: Specification​

The specification phase focuses on defining what you want to build, not how to build it.

Creating Specifications​

Use the /specify command with your AI assistant to describe what you want to build:

/specify Build a user authentication system that allows users to register, login, and manage their profiles. The system should support email/password authentication, password reset functionality, and basic profile management.

Focus on the what and why, not the technical implementation details.

Specification Structure​

Each specification includes:

  • User Stories - Who, what, and why
  • Functional Requirements - What the system should do
  • Acceptance Criteria - How to know when it's done
  • Success Metrics - Measurable outcomes

Best Practices​

  • Focus on outcomes, not implementation details
  • Be specific about user needs and business value
  • Include edge cases and error scenarios
  • Define success criteria clearly

Phase 2: Clarification​

The clarification phase resolves ambiguities and missing details before moving to technical planning.

Interactive Specification Refinement​

Use the /clarify command to identify and resolve ambiguities:

specifyx run check-prerequisites --json --paths-only

This will:

  • Analyze your specification for ambiguous requirements
  • Ask up to 5 targeted clarification questions
  • Update the spec file with your answers
  • Ensure all requirements are testable and unambiguous

Clarification Areas​

The clarification process covers:

  • Functional scope - Clear boundaries and out-of-scope declarations
  • Data model - Entity relationships and validation rules
  • User experience - Critical user journeys and error states
  • Non-functional requirements - Performance, security, scalability targets
  • Edge cases - Error handling and failure scenarios

Best Practices​

  • Answer all clarification questions before proceeding to planning
  • Be specific about measurable criteria
  • Define edge cases explicitly
  • Clarify terminology to avoid confusion

Phase 3: Planning​

The planning phase translates specifications into technical implementation plans.

Generating Implementation Plans​

Use the /plan command to provide your tech stack and architecture choices:

/plan The application will use Python with FastAPI for the backend API, SQLite for the database, and React for the frontend. Implement JWT tokens for authentication, bcrypt for password hashing, and include email verification for new accounts.

This generates:

  • Technical architecture decisions
  • Technology stack choices
  • Implementation roadmap
  • Risk assessment

Plan Components​

  • Architecture Overview - High-level system design
  • Technology Stack - Tools, frameworks, and libraries
  • Data Models - Database schemas and data flow
  • API Design - Endpoints and interfaces
  • Security Considerations - Authentication, authorization, data protection

Phase 4: Task Generation​

The task phase breaks down the implementation plan into actionable development tasks.

Creating Tasks​

Use the /tasks command to break down the implementation plan:

/tasks Break down the implementation into actionable development tasks with clear deliverables, dependencies, and testing requirements.

This creates:

  • Detailed task breakdown
  • Dependencies and priorities
  • Implementation steps
  • Testing requirements

Task Organization​

Tasks are organized by:

  • Priority - Critical path items first
  • Dependencies - Prerequisites and blockers
  • Complexity - Effort estimation
  • Testing - Validation requirements

Phase 5: Quality Analysis​

The analysis phase validates consistency and quality across all artifacts before implementation begins.

Cross-Artifact Analysis​

Use the /analyze command to validate your specifications, plans, and tasks:

specifyx run check-prerequisites --json --require-tasks --include-tasks

This performs:

  • Consistency checking across spec.md, plan.md, and tasks.md
  • Coverage analysis ensuring all requirements have corresponding tasks
  • Constitution compliance validation against project principles
  • Ambiguity detection flagging unclear or underspecified items
  • Duplication identification finding redundant requirements

Quality Gates​

The analysis validates:

  • Requirements coverage - Every requirement maps to implementation tasks
  • Constitutional alignment - All plans follow project principles
  • Terminology consistency - Same concepts use consistent naming
  • Dependency validation - Task ordering respects dependencies
  • Completeness - No missing critical components

Remediation​

Before proceeding to implementation:

  • Resolve CRITICAL issues - Fix constitution violations and coverage gaps
  • Address HIGH priority - Clear ambiguities and conflicts
  • Document decisions - Update specs/plans based on analysis findings

Phase 6: Implementation​

The implementation phase executes the validated tasks using either automated tools or human-friendly guidance.

Implementation Approaches​

Choose your implementation style:

Automated Implementation (/implement)​

/implement Execute the task list automatically using AI-driven development

Use when:

  • Tasks are well-defined and specific
  • Working on standard patterns and structures
  • Want rapid prototyping or scaffolding
  • Have comprehensive test coverage

Guided Implementation (/guide)​

/guide Provide structured instructions for manual execution of tasks

Use when:

  • Tasks require human judgment or creativity
  • Working with complex business logic
  • Need to understand implementation details
  • Prefer step-by-step manual control

Implementation Best Practices​

  • Follow TDD cycle - Tests first, then implementation
  • Execute tasks in order - Respect dependencies and priorities
  • Validate continuously - Run tests after each task completion
  • Update documentation - Keep plans and specs current with changes
  • Constitutional compliance - Ensure all implementations follow project principles

Quality Assurance​

During implementation:

  • Run tests frequently - Validate each completed task
  • Review against specs - Ensure implementation matches requirements
  • Performance validation - Meet non-functional requirements
  • Security review - Validate security requirements are met

AI Assistant Integration​

SpecifyX generates AI-specific commands for your preferred assistant:

Available Commands​

  • /specify - Create detailed specifications
  • /clarify - Resolve ambiguities in specifications
  • /plan - Generate technical implementation plans
  • /tasks - Break down into actionable tasks
  • /analyze - Validate consistency across artifacts
  • /implement - Execute tasks automatically with AI
  • /guide - Generate human-friendly implementation instructions

Workflow Integration​

  1. Specification Review - Use AI to refine and validate specs
  2. Plan Validation - Have AI audit technical decisions
  3. Task Refinement - Use AI to break down complex tasks
  4. Implementation - Leverage AI for code generation

Project Structure​

A typical SpecifyX project structure:

my-project/
├── .specify/               # SpecifyX configuration
│   ├── config.toml        # Project settings
│   ├── scripts/           # Python utility scripts
│   ├── templates/         # Jinja2 templates
│   └── memory/            # Project constitution
├── .claude/               # AI assistant integration
│   └── commands/          # Custom commands
├── specs/                 # Feature specifications
│   └── 001-feature-name/
│       ├── spec.md        # Feature specification
│       ├── plan.md        # Implementation plan
│       └── tasks.md       # Task breakdown
└── README.md             # Project documentation

Branch Naming Patterns​

SpecifyX supports various branch naming conventions:

  • feature/{feature-name}, {hotfix}/{bug-id} - Standard feature branches
  • 001-feature-name - Numbered features
  • feature/{spec-id}-{feature-name} - Numbered features with spec id
  • Custom patterns - Configure in .specify/config.toml

Template System​

SpecifyX uses Jinja2 templates for consistent project artifacts:

Template Categories​

  • Specification Templates - Standard spec formats
  • Plan Templates - Technical design templates
  • Task Templates - Development task formats
  • Script Templates - Python utility scripts

Customization​

Templates can be customized for:

  • Organization-specific formats
  • Technology stack preferences
  • Documentation standards
  • Workflow requirements

Best Practices​

Specification Phase​

  • Start with user needs, not technical solutions
  • Include acceptance criteria for every requirement
  • Consider edge cases and error scenarios
  • Validate with stakeholders before proceeding

Planning Phase​

  • Choose appropriate technology stacks
  • Consider scalability and maintainability
  • Plan for testing and deployment
  • Document architectural decisions

Task Phase​

  • Break down into manageable chunks
  • Define clear deliverables
  • Include testing requirements
  • Estimate effort and dependencies

Troubleshooting​

Common Issues​

  • Vague Specifications - Add more detail and examples
  • Over-Engineering - Focus on MVP and iterate, try to keep specs focused to get better results
  • Missing Dependencies - Review task dependencies carefully
  • Unclear Acceptance Criteria - Define measurable outcomes

Getting Help​

  • Run specifyx check to validate your setup
  • Review generated templates for guidance
  • Use AI assistants for clarification

Next Steps​