dino-spec 0.11.0 → 5.0.0

package/README.md

@@ -1,6 +1,6 @@
 # dino-spec
 
-> Spec-driven development workflow for Claude Code with dinosaur-themed phases
+> Automatic context engineering for Claude Code
 
 ```
        __
@@ -10,30 +10,101 @@
 <__|-|__|
 ```
 
-**dino-spec** is a CLI tool that brings structured, specification-driven development to [Claude Code](https://claude.ai/code). It guides you through a dinosaur-themed workflow: from discovering requirements to hunting down implementation tasks.
+**dino-spec** is a CLI tool that brings structured, context-aware development to [Claude Code](https://claude.ai/code). It automatically maintains session state through hooks, ensuring Claude always has the context it needs.
 
 ## 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
+- **State blindness** - No awareness of test/build/lint status
 - **Unstructured iteration** - No clear progression from idea to implementation
-- **Lost specifications** - Requirements scattered across conversations
 
-**dino-spec** solves these problems by:
+**dino-spec v5.0.0** solves these with:
 
-- 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
+- **Progressive task delegation** - Automatic delegation to specialized agents with context handoffs
+- **Progressive context loading** - Minimal initial tokens, load context on-demand via MCP resources
+- **Automatic context** via Claude Code hooks that maintain session state
+- **Skill-based workflow** with phases from discovery to completion
+- **Session intelligence** that tracks focus, blockers, and progress
 
-## Who is this for?
+## What's New in v5.0.0
 
-- **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
+### Progressive Task Delegation
+
+Automatically delegate complex tasks to specialized agents while preserving context:
+
+```
+User: "Implement caching for the API"
+         ↓
+┌────────────────────────────────────────────────┐
+│  @dino-analyst → @dino-architect → @dino-implementer  │
+│     (explore)      (design)         (implement)       │
+└────────────────────────────────────────────────┘
+```
+
+Each agent creates **checkpoints** with their discoveries, which get passed to the next agent via **handoffs**. No re-reading the entire codebase!
+
+#### MCP Tools for Task Management
+
+| Tool | Purpose |
+|------|---------|
+| `dino_task_create` | Create a task in the registry |
+| `dino_task_breakdown` | Split task into subtasks with roles |
+| `dino_checkpoint_create` | Save findings for handoff |
+| `dino_task_delegate` | Delegate to specialized agent |
+| `dino_task_status` | View task tree and progress |
+
+#### New Resources
+
+| Resource | Description |
+|----------|-------------|
+| `@dino://tasks` | Current task tree and progress |
+| `@dino://handoff` | Active handoff context |
+
+### Specialized Agents
+
+| Agent | Role | Purpose |
+|-------|------|---------|
+| `@dino-analyst` | Explorer | Read-only codebase research |
+| `@dino-architect` | Planner | Design and planning (Opus) |
+| `@dino-implementer` | Implementer | Full implementation |
+| `@dino-tester` | Tester | Test writing and execution |
+| `@dino-reviewer` | Reviewer | Code review and QA |
+
+### Auto-Delegation Detection
+
+The `user-prompt-submit` hook detects complex prompts and suggests delegation:
+
+```
+[dino] Multi-step task detected. Suggested delegation: explorer -> planner -> implementer
+```
+
+## Previous: v4.0.0 Features
+
+### Progressive Context Loading
+
+Reduce initial context by ~59% with the new `--minimal` mode:
+
+```bash
+dino init --minimal
+```
+
+Instead of loading everything upfront, context is loaded on-demand:
+
+| Resource | Description | Access |
+|----------|-------------|--------|
+| `@dino://session` | Current session state | On-demand |
+| `@dino://structure` | Project architecture | On-demand |
+| `@dino://patterns` | Coding conventions | On-demand |
+| `@dino://commands` | Build/test/lint commands | On-demand |
+| `@dino://skills` | Available workflow skills | On-demand |
+
+### Smart Hooks
+
+- **Context Router**: Session-start only outputs critical alerts (failing tests, blockers)
+- **Intent Detection**: User prompts trigger relevant resource suggestions
+- **Session Compaction**: Automatically archives old session data
 
 ## Installation
 
@@ -56,63 +127,65 @@ npm link
 ## Quick Start
 
 ```bash
-# Initialize in your project
+# Initialize in your project (standard mode)
 cd your-project
 dino init
 
-# Open Claude Code and run:
-# /dino.discover add user authentication
+# Or use minimal mode for progressive context loading
+dino init --minimal
+
+# Check current session state
+dino status
+
+# Open Claude Code and use workflow skills:
+# /dino.discover, /dino.scout, /dino.hunt, etc.
 ```
 
-## The Dinosaur Workflow
+## The Workflow
 
-Each phase builds on the previous, ensuring nothing is lost:
+Each phase builds on the previous, with automatic session tracking:
 
 ```
-discover → scout → sniff → nest → hatch → hunt → aging → fossil → [extinct]
+discover → scout → sniff → nest → hatch → hunt → aging → fossil
 ```
 
-| Phase        | Command          | Purpose                                        |
-| ------------ | ---------------- | ---------------------------------------------- |
-| **Discover** | `/dino.discover` | Capture requirements and create specification  |
-| **Scout**    | `/dino.scout`    | Research codebase and technical options        |
-| **Sniff**    | `/dino.sniff`    | Sniff out ambiguities with targeted questions  | (optional) |
-| **Nest**     | `/dino.nest`     | Create implementation plan (Plan Mode)         |
-| **Hatch**    | `/dino.hatch`    | Break plan into tasks with requirement mapping |
-| **Hunt**     | `/dino.hunt`     | Implement tasks with progress tracking         |
-| **Aging**    | `/dino.aging`    | Create and run tests to verify business logic  | (optional) |
-| **Fossil**   | `/dino.fossil`   | Archive completed specification                |
-| **Extinct**  | `/dino.extinct`  | Permanently remove archive, keep museum record | (optional) |
+| Phase        | Skill            | Purpose                                      |
+| ------------ | ---------------- | -------------------------------------------- |
+| **Discover** | `/dino.discover` | Capture requirements from user prompts       |
+| **Scout**    | `/dino.scout`    | Research codebase and explore options        |
+| **Sniff**    | `/dino.sniff`    | Clarify ambiguities with targeted questions  |
+| **Nest**     | `/dino.nest`     | Plan implementation (uses Plan Mode)         |
+| **Hatch**    | `/dino.hatch`    | Break plan into actionable todos             |
+| **Hunt**     | `/dino.hunt`     | Execute implementation with tracking         |
+| **Aging**    | `/dino.aging`    | Verify with tests                            |
+| **Fossil**   | `/dino.fossil`   | Archive and commit completed work            |
 
-Optional: `/dino.next` suggests follow-up features based on completed work.
+Utility skills: `/dino.status`, `/dino.focus`, `/dino.next`
 
 ## CLI Commands
 
-These commands work **without AI** - saving tokens and providing instant feedback:
-
 ```bash
-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
+# Initialize
+dino init                  # Standard initialization
+dino init --minimal        # Minimal mode for progressive loading
+dino init --force          # Reinitialize, overwriting existing
+
+# Status and refresh
+dino status                # Show current session state
+dino refresh               # Re-analyze codebase and update context
+dino refresh --minimal     # Switch to minimal mode
+
+# Session management
+dino session read          # Display session state
+dino session update        # Update session (blockers, focus, etc.)
+
+# Hooks
+dino hooks setup           # Install Claude Code hooks
+dino hooks status          # Show hook configuration
+dino hooks list            # List all available hooks
+dino hooks enable <id>     # Enable a specific hook
+dino hooks disable <id>    # Disable a specific hook
+dino hooks remove          # Remove all hooks
 ```
 
 ## Project Structure
@@ -121,194 +194,111 @@ After `dino init`, your project will have:
 
 ```
 your-project/
+├── CLAUDE.md                    # Project context (auto-updated)
 ├── .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
+│   ├── skills/dino/             # Workflow skills
+│   │   ├── discover.md          # Discovery phase
+│   │   ├── scout.md             # Research phase
+│   │   ├── sniff.md             # Clarification phase
+│   │   ├── nest.md              # Planning phase
+│   │   ├── hatch.md             # Breakdown phase
+│   │   ├── hunt.md              # Implementation phase
+│   │   ├── aging.md             # Verification phase
+│   │   ├── fossil.md            # Completion phase
+│   │   ├── status.md            # Status utility
+│   │   ├── focus.md             # Focus utility
+│   │   └── next.md              # Next steps utility
+│   ├── rules/dino/              # Workflow rules
+│   └── agents/                  # Specialized agents
 └── .dino/
-    ├── active.json            # Current active specification
-    ├── dna.md                 # Project conventions
-    ├── specs/                 # Active specifications
-    ├── archive/               # Completed specifications
-    └── museum/                # Minimal records of extinct specs
+    ├── session.md               # Session state (focus, blockers, signals)
+    ├── structure.json           # Cached codebase analysis
+    ├── patterns.json            # Coding patterns (@dino://patterns)
+    ├── commands.json            # Commands (@dino://commands)
+    ├── config.json              # Configuration
+    ├── archive/                 # Session history archive
+    ├── tasks/                   # Task registry (v5.0.0)
+    ├── checkpoints/             # Agent checkpoints (v5.0.0)
+    └── handoff/                 # Agent handoffs (v5.0.0)
 ```
 
-## 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.
+## Session State
 
-### 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:
+The `.dino/session.md` file tracks:
 
 ```markdown
-- [ ] 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:
-
-```bash
-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:
+# Session State
 
-```bash
-# 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.
+## Focus
+**src/core/** (high confidence, directory-cluster)
 
-After setup, use these commands in any terminal:
+## Test Status
+**Status:** passing
+**Counts:** 121 passed, 0 failed, 0 skipped
 
-| Command | Description |
-|---------|-------------|
-| `claude-zai` | Launch Claude Code with Z.AI |
-| `claude-anthropic` | Reset to default Anthropic |
+## Build Status
+**Status:** passing
 
-#### Minimax 2.1 Provider
+## Blockers
+- Waiting for API response format decision
 
-Minimax 2.1 requires additional environment variables. Use the dedicated options:
-
-```bash
-# 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
+## Progress
+- 2024-01-15 10:30: tests-fixed - All tests passing
+- 2024-01-15 10:15: build-fixed - Build errors resolved
 ```
 
-After setup:
-
-| Command | Description |
-|---------|-------------|
-| `claude-minimax` | Launch Claude Code with Minimax 2.1 |
-| `claude-anthropic` | Reset to default Anthropic |
-
-> **Note:** Get your Minimax API key from the [Minimax Developer Platform](https://platform.minimax.io/user-center/basic-information/interface-key). See [official documentation](https://platform.minimax.io/docs/coding-plan/claude-code) for details.
-
-Provider configurations are stored in `~/.dino/providers.json` for cross-computer portability.
-
-## Example Workflow
+Hooks automatically update this state based on your actions.
 
-```bash
-# 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
+## Hooks System (v4.0.0)
 
-# 5. Sniff out any ambiguities
-/dino.sniff
+Dino-spec integrates with Claude Code's hooks:
 
-# 6. Create implementation plan (enters Plan Mode)
-/dino.nest
+| Hook | Purpose |
+|------|---------|
+| `SessionStart` | Output critical alerts only (context router) |
+| `SessionEnd` | Clean up on exit |
+| `PostEdit` | Track file changes with classification |
+| `PostTest` | Update test status |
+| `PostBuild` | Update build status |
+| `PostLint` | Update lint status |
+| `PreCompact` | Archive and compact session state |
+| `UserPromptSubmit` | Intent detection with resource suggestions |
+| `SubagentStart/Stop` | Track agent activity |
 
-# 7. Break into tasks with requirement mapping
-/dino.hatch
+The v4.0.0 hooks are optimized for minimal output:
+- **Session-start**: Only alerts on failures/blockers (silence when green)
+- **User-prompt-submit**: Suggests relevant `@dino://` resources based on intent
 
-# 8. Implement with progress tracking
-/dino.hunt
+## MCP Resources
 
-# 9. Verify with tests
-/dino.aging
+Access context on-demand using @ mentions in Claude Code:
 
-# 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
+```
+@dino://session    # Current focus, blockers, test status
+@dino://structure  # Project architecture and directories
+@dino://patterns   # Coding conventions and patterns
+@dino://commands   # Build, test, lint commands
+@dino://skills     # Available workflow skills
+@dino://history    # Recent file edit history
+@dino://tasks      # Task registry and progress (v5.0.0)
+@dino://handoff    # Active handoff context (v5.0.0)
 ```
 
-## Configuration
-
-### Project DNA
-
-Edit `.dino/dna.md` to define project conventions:
+## Minimal vs Standard Mode
 
-```markdown
-# Project DNA
+| Aspect | Standard | Minimal |
+|--------|----------|---------|
+| CLAUDE.md size | ~300 tokens | ~100 tokens |
+| Initial context | Full sections | Quick reference |
+| Architecture | Embedded | `@dino://structure` |
+| Patterns | Embedded | `@dino://patterns` |
+| Commands | Embedded | `@dino://commands` |
+| Best for | Quick reference | Large codebases |
 
-## Tech Stack
-- Framework: React
-- Language: TypeScript
-- Testing: Vitest
-
-## Conventions
-- Use functional components
-- Prefer composition over inheritance
+Switch between modes:
+```bash
+dino refresh --minimal  # Switch to minimal
+dino refresh --full     # Switch to standard
 ```
 
 ## Requirements
@@ -316,18 +306,10 @@ Edit `.dino/dna.md` to define project conventions:
 - 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](https://github.com/spec-kit/spec-kit) and [OpenSpec](https://github.com/openspec/openspec) - combining structured workflows with token-efficient CLI tools.
-
 ---
 
 Built for developers who believe AI coding should be structured, reproducible, and context-aware.

package/dist/agents/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Custom Agents System - v3.0.0
+ *
+ * Creates specialized agents in .claude/agents/
+ * Each agent has specific capabilities and tool restrictions.
+ */
+/**
+ * Agent definition
+ */
+export interface AgentDefinition {
+    name: string;
+    filename: string;
+    description: string;
+    role: string;
+    frontmatter: AgentFrontmatter;
+    content: string;
+}
+/**
+ * Agent frontmatter options
+ */
+interface AgentFrontmatter {
+    description: string;
+    model?: 'sonnet' | 'haiku' | 'opus';
+    permissionMode?: 'permissive' | 'default';
+    allowedTools?: string[];
+    disallowedTools?: string[];
+}
+/**
+ * Get all agent definitions
+ */
+export declare function getAllAgentDefinitions(): AgentDefinition[];
+/**
+ * Result of agents creation
+ */
+export interface AgentsCreateResult {
+    created: string[];
+    updated: string[];
+    skipped: string[];
+    agentsDir: string;
+}
+/**
+ * Create .claude/agents/ with all agent files
+ */
+export declare function createAgents(projectDir: string, options?: {
+    force?: boolean;
+}): Promise<AgentsCreateResult>;
+/**
+ * Get agents directory path
+ */
+export declare function getAgentsDir(projectDir: string): string;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/agents/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,gBAAgB,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,UAAU,gBAAgB;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;IACpC,cAAc,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;IAC1C,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAmSD;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,eAAe,EAAE,CAE1D;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAChC,OAAO,CAAC,kBAAkB,CAAC,CAqC7B;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEvD"}