dino-spec

Spec-driven development workflow for Claude Code with dinosaur-themed phases

       __
      (_ \
  .-^^^  /
 /       /
<__|-|__|

dino-spec is a CLI tool that brings structured, specification-driven development to Claude Code. It guides you through a dinosaur-themed workflow: from discovering requirements to hunting down implementation tasks.

Why dino-spec?

When working with AI coding assistants, projects often suffer from:

• Context loss - AI forgets what you're building mid-conversation
• Scope creep - Features expand without clear boundaries
• Unstructured iteration - No clear progression from idea to implementation
• Lost specifications - Requirements scattered across conversations

dino-spec solves these problems by:

• Persisting specifications in .dino/ files that survive context resets
• Enforcing a structured workflow with clear phase transitions
• Breaking work into small, trackable tasks (max 8-10 per phase)
• Integrating directly with Claude Code via slash commands

Who is this for?

• Developers using Claude Code who want structured AI-assisted development
• Teams who need reproducible specification workflows
• Solo developers building complex features incrementally
• Anyone tired of re-explaining context to AI assistants

Installation

From npm (recommended)

npm install -g dino-spec

From GitHub

git clone https://github.com/xullul/dino-spec.git
cd dino-spec
pnpm install
pnpm build
npm link

Quick Start

# Initialize in your project
cd your-project
dino init

# Open Claude Code and run:
# /dino.discover add user authentication

The Dinosaur Workflow

Each phase builds on the previous, ensuring nothing is lost:

discover → scout → sniff → nest → hatch → hunt → aging → fossil → [extinct]

Optional: /dino.next suggests follow-up features based on completed work.

CLI Commands

These commands work without AI - saving tokens and providing instant feedback:

dino init              # Initialize dino-spec in your project
dino status [spec]     # Show current spec progress
dino list              # List all specifications
dino view              # Interactive dashboard
dino active [spec]     # Show or set active specification
dino archive <spec>    # Archive completed specification
dino museum [spec]     # View museum records (extinct specs summary)
dino update            # Update configuration files

# Skill management
dino skill list        # List installed skills
dino skill create      # Create custom skill
dino skill install     # Install from registry
dino skill remove      # Remove a skill

# API Provider management
dino provider list     # List configured providers
dino provider add      # Add a new provider (Z.AI, etc.)
dino provider remove   # Remove a provider
dino provider show     # Show provider details
dino provider setup    # Install shell functions
dino provider -h       # Show provider help

Project Structure

After dino init, your project will have:

your-project/
├── .claude/
│   ├── commands/              # Slash commands for Claude Code (12 total)
│   │   ├── dino.discover.md
│   │   ├── dino.scout.md
│   │   ├── dino.sniff.md
│   │   ├── dino.nest.md
│   │   ├── dino.hatch.md
│   │   ├── dino.hunt.md
│   │   ├── dino.aging.md
│   │   ├── dino.fossil.md
│   │   ├── dino.extinct.md
│   │   └── ...
│   ├── skills/dino-workflow/
│   │   └── SKILL.md           # Workflow skill definition
│   └── rules/dino/
│       └── workflow.md        # Workflow rules
└── .dino/
    ├── active.json            # Current active specification
    ├── dna.md                 # Project conventions
    ├── specs/                 # Active specifications
    ├── archive/               # Completed specifications
    └── museum/                # Minimal records of extinct specs

Specification Files

Each specification contains:

.dino/specs/{spec-id}/
├── spec.md      # Requirements and success criteria
├── research.md  # Technical research from scout phase
├── plan.md      # Implementation plan from nest phase
├── tasks.md     # Phased task checklist with requirement mapping
└── tests.md     # Test cases with business logic verification (aging phase)

Key Features

Context Preservation

All state is stored in files. When context resets, Claude Code reads .dino/active.json and resumes from where you left off.

Plan Mode Integration

Complex phases (/dino.nest, /dino.hatch) automatically trigger Claude Code's Plan Mode for careful deliberation.

Task Tracking

Tasks use a simple checkbox format with requirement mapping and progress bars:

- [ ] T001 Implement user model | REQ-1
- [ ] T002 [P] Add validation (parallelizable) | REQ-1, REQ-2
- [x] T003 Create database schema (completed) | REQ-3

The | REQ-N suffix maps tasks to requirements, ensuring every requirement is covered.

Skill System

Extend functionality with custom skills:

dino skill create my-linter
# Edit .claude/skills/my-linter/SKILL.md

API Provider Management

Use alternative API providers (like Z.AI) with Claude Code without affecting your default Anthropic subscription:

# Add Z.AI provider (with optional model mapping for GLM models)
dino provider add zai \
  --url https://api.z.ai/api/anthropic \
  --key YOUR_API_KEY \
  --sonnet GLM-4.7 \
  --haiku GLM-4.5-Air \
  --opus GLM-4.7

# Install shell functions for quick switching
dino provider setup

# Reload PowerShell profile
. $PROFILE

Important: Use https://api.z.ai/api/anthropic (Anthropic-compatible endpoint), NOT https://api.z.ai/api/coding/paas/v4/ (direct GLM endpoint). Claude Code requires the Anthropic-compatible API format.

After setup, use these commands in any terminal:

Minimax 2.1 Provider

Minimax 2.1 requires additional environment variables. Use the dedicated options:

# Add Minimax provider (International users)
dino provider add minimax \
  --url https://api.minimax.io/anthropic \
  --key YOUR_MINIMAX_API_KEY \
  --model MiniMax-M2.1 \
  --small-fast-model MiniMax-M2.1 \
  --sonnet MiniMax-M2.1 \
  --haiku MiniMax-M2.1 \
  --opus MiniMax-M2.1 \
  --disable-nonessential-traffic

# For China users, use:
# --url https://api.minimaxi.com/anthropic

# Install shell functions
dino provider setup

# Reload PowerShell profile
. $PROFILE

After setup:

Note: Get your Minimax API key from the Minimax Developer Platform. See official documentation for details.

Provider configurations are stored in ~/.dino/providers.json for cross-computer portability.

Example Workflow

# 1. Initialize
dino init

# 2. In Claude Code, start a specification
/dino.discover add dark mode toggle to settings

# 3. Claude creates spec.md with requirements

# 4. Research the codebase
/dino.scout

# 5. Sniff out any ambiguities
/dino.sniff

# 6. Create implementation plan (enters Plan Mode)
/dino.nest

# 7. Break into tasks with requirement mapping
/dino.hatch

# 8. Implement with progress tracking
/dino.hunt

# 9. Verify with tests
/dino.aging

# 10. Archive when complete
/dino.fossil

# 11. (Optional) Clean up archive, keep museum record
/dino.extinct

# Check progress anytime
dino status
dino view
dino museum   # View extinct specs history

Configuration

Project DNA

Edit .dino/dna.md to define project conventions:

# Project DNA

## Tech Stack
- Framework: React
- Language: TypeScript
- Testing: Vitest

## Conventions
- Use functional components
- Prefer composition over inheritance

Requirements

• Node.js >= 20.0.0
• Claude Code CLI

Contributing

Contributions welcome! Please read the contribution guidelines before submitting PRs.

License

MIT

Acknowledgments

Inspired by spec-kit and OpenSpec - combining structured workflows with token-efficient CLI tools.

Built for developers who believe AI coding should be structured, reproducible, and context-aware.