Shark Task Manager

A task management system built with Go and SQLite, featuring both an HTTP API and a powerful CLI tool for AI-driven development workflows.

Key Features

Hierarchical Task Organization: Organize work into Epics → Features → Tasks with auto-generated keys
Dual Key Format: Support for both numeric (E04, T-E04-F01-001) and human-readable slugged keys (E04-user-management, T-E04-F01-001-implement-auth)
Flexible Command Syntax: Positional arguments for cleaner commands (shark feature create E07 "Title")
Case-Insensitive Keys: Use any case (E07, e07, E07-F01, e07-f01) - all work identically
User-Friendly Error Messages: Clear error messages with context, examples, and suggestions
AI-Driven Workflows: Built-in support for multiple agent types with dependency-aware task selection
Flexible Organization: Organize with custom file paths (--file flag) for complete control over project structure
Auto-Detect Project Root: Run shark commands from any subdirectory - automatically finds database and config
Progress Tracking: Automatic progress calculation from task completion to features and epics
Audit Trail: Complete history of all status changes with timestamps and agent tracking
Dependency Management: Express task dependencies and get warnings about blocking work
JSON Output: Machine-readable JSON output for all commands (with --json flag)

Prerequisites

Go 1.23.4 or later
SQLite3

Shark CLI - AI Agent Task Management

The shark CLI is designed for AI agents to manage epics, features, and tasks programmatically. It provides atomic operations, dependency management, and progress tracking.

Quick Start for AI Agents

# 1. Initialize infrastructure (first time only)
shark init --non-interactive

# 2. Query available work
shark epic list --json
shark task list --status=todo --agent=backend --json

# 3. Advance task to next workflow status (short format, recommended)
shark task next-status E04-F06-001
# Case insensitive
shark task next-status e04-f06-001
# OR traditional format (still supported)
shark task next-status T-E04-F06-001
# OR using human-readable slugged key
shark task next-status E04-F06-001-implement-user-authentication

# 4. Advance again to next status
shark task next-status E04-F06-001

# 5. Continue advancing through workflow
shark task next-status E04-F06-001

Core Workflows for AI Agents

1. Project Initialization

Set up Shark CLI infrastructure (run once per project):

# Non-interactive mode for automation
shark init --non-interactive

This creates:

SQLite database (shark-tasks.db) with schema
Folder structure (docs/plan/)
Configuration file (.sharkconfig.json)
Templates (shark-templates/) - epic.md, feature.md, task.md

2. Discovering Available Work

List all epics with progress:

shark epic list --json
shark epic list --status=active --json

Get epic details with all features:

# Using numeric key (case insensitive)
shark epic get E04 --json
shark epic get e04 --json

# OR using human-readable slugged key
shark epic get E04-user-management --json
shark epic get e04-user-management --json

List features in an epic:

# Using positional argument (recommended, shorter syntax)
shark feature list E04
shark feature list e04  # Case insensitive
shark feature list E04 --json
shark feature list E04 --status=active --json

# Using flag syntax (still supported, backward compatible)
shark feature list --epic=E04 --json
shark feature list --epic=E04 --status=active --json

# Works with slugged epic keys too
shark feature list E04-user-management --json

Get feature details with all tasks:

# Using numeric key (case insensitive)
shark feature get E04-F06 --json
shark feature get e04-f06 --json

# OR using slugged key
shark feature get E04-F06-authentication --json
shark feature get e04-f06-authentication --json

3. Querying Tasks

List all tasks:

shark task list --json

Filter by status:

shark task list --status=todo --json
shark task list --status=in_progress --json
shark task list --status=ready_for_review --json
shark task list --status=completed --json
shark task list --status=blocked --json

Filter by epic or agent:

# Using positional arguments (recommended, shorter syntax)
shark task list E04                    # Filter by epic
shark task list e04                    # Case insensitive
shark task list E04 F01                # Filter by epic and feature
shark task list E04-F01                # Alternative combined format
shark task list e04-f01                # Case insensitive combined format

# Using flag syntax (still supported, backward compatible)
shark task list --epic=E04 --json
shark task list --epic=E04 --feature=F01 --json

# Filter by agent type
shark task list --agent=backend --json              # Standard agent type
shark task list --agent=architect --json            # Custom agent type
shark task list --agent=business-analyst --json     # Custom agent type
shark task list --epic=E04 --agent=backend --status=todo --json

Get task details:

# Short format (recommended)
shark task get E04-F06-001 --json
shark task get e04-f06-001 --json  # Case insensitive

# Traditional format (still supported)
shark task get T-E04-F06-001 --json

Returns task metadata, dependencies, and dependency status.

4. Creating Tasks

Positional syntax (recommended):

# 3-argument format: epic, feature, title
shark task create E04 F06 "Implement task validation" \
  --agent=backend \
  --priority=3 \
  --description="Add validation logic for task creation" \
  --depends-on="E04-F06-001,E04-F06-002"

# 2-argument format: combined epic-feature, title
shark task create E04-F06 "Implement task validation" \
  --agent=backend \
  --priority=3

# Case insensitive
shark task create e04 f06 "Implement task validation" --agent=backend

# With custom agent type (for multi-agent workflows)
shark task create E04 F06 "Design system architecture" --agent=architect --priority=2
shark task create E04 F06 "Elaborate user requirements" --agent=business-analyst --priority=4
shark task create E04 F06 "Create test strategy" --agent=qa --priority=3

Flag syntax (legacy, still supported):

shark task create \
  --epic=E04 \
  --feature=F06 \
  --title="Implement task validation" \
  --agent=backend \
  --priority=3 \
  --description="Add validation logic for task creation" \
  --depends-on="E04-F06-001,E04-F06-002"

Parameters:

Epic and feature keys (required, via positional args or --epic/--feature flags)
Title (required, via positional arg or --title flag)
--agent: Agent type (any non-empty string; recommended: frontend, backend, api, testing, devops, general, or custom types like architect, business-analyst, qa)
--priority: Priority 1-10 (default: 5, where 1 = highest)
--description: Detailed task description
--depends-on: Comma-separated list of dependency task keys (short format: E04-F06-001)

The CLI automatically:

Generates unique task key (e.g., T-E04-F06-003)
Creates markdown file at docs/plan/epic/feature/task-key.md
Sets initial status to todo
Validates epic and feature exist

About Agent Types:

Shark supports flexible agent type assignment for diverse team structures and multi-agent workflows:

Standard agent types (frontend, backend, api, testing, devops, general) have role-specific templates
Custom agent types (architect, business-analyst, qa, tech-lead, product-manager, ux-designer, etc.) use the general template
Any non-empty string is supported as an agent type
Custom types enable multi-agent orchestration: each agent can query their work with shark task list --agent=<type> --status=todo --json

5. Task Lifecycle Management

Standard workflow:

# 1. Advance task to next workflow status
# Short format (recommended)
shark status advance E04-F06-001 --json
# Case insensitive
shark status advance e04-f06-001 --json
# Traditional format (still supported)
shark status advance T-E04-F06-001 --json

# 2. Continue advancing through the workflow
shark status advance E04-F06-001 --json

# 3. Advance again to reach completion
shark status advance E04-F06-001 --json

State Transitions:

Command	Description	Notes
`shark status advance <key>`	Advance to next workflow status	Determined by workflow profile
`shark task next-status <key>`	Advance to next workflow status	Equivalent to `status advance`
`shark status set <key> <status>`	Set status directly	Use when skipping steps or correcting state
`shark status set <key> blocked --reason="..."`	Block task	Cannot proceed, needs resolution

Handling blocked tasks:

# Block a task with reason
shark status set E04-F06-001 blocked --reason="Waiting for API design approval" --json

# List all blocked tasks
shark task list --blocked --json

# Unblock by advancing to next status
shark status advance E04-F06-001 --json

Handling review feedback:

# Set back to in-progress for rework
shark status set E04-F06-001 in_progress --reason="Need to add error handling" --json

# Fix issues and advance to review status again
shark status advance E04-F06-001 --json

Important: Status is managed exclusively in the database and is NOT from files. This ensures atomic status transitions and audit trails.

7. Progress Tracking

Epic progress:

shark epic list --json
shark epic get E04 --json

Returns calculated progress percentage based on completed tasks across all features.

Feature progress:

shark feature list --epic=E04 --json
shark feature get E04-F06 --json

Returns:

Progress percentage
Task count
Status breakdown (todo/in_progress/completed/blocked)

AI Agent Best Practices

Always use --json flag for machine-readable output
Check dependencies before starting tasks via shark task list --status=todo --json
Use atomic operations - each command is a single transaction
Handle blocked tasks - use shark status set <key> blocked --reason="..." with reasons
Track work with agent identifier - use --agent flag for audit trail
Use priority effectively - 1=highest, 10=lowest for task ordering
Check exit codes - Non-zero indicates errors (1=not found, 2=db error, 3=invalid state)


### JSON Output Format

All commands support `--json` for structured output:

```json
{
  "key": "T-E04-F06-001",
  "title": "Implement key generation",
  "status": "todo",
  "priority": 3,
  "agent_type": "backend",
  "depends_on": ["T-E04-F05-001"],
  "dependency_status": {
    "T-E04-F05-001": "completed"
  },
  "file_path": "docs/plan/E04-task-mgmt-cli-core/E04-F06-task-creation/T-E04-F06-001.md"
}

Documentation

User Guides

Initialization Guide - Set up Shark CLI
Troubleshooting - Common issues and solutions

Reference

Complete Documentation Index - Find all documentation
CLI Documentation - Complete command reference
Migration Guide - Upgrading from older versions (custom_folder_path deprecation)
Epic & Feature Query Guide - Query epics and features with progress
Quick Reference - Fast command lookup
Examples - Real-world usage scenarios
Make

Project Structure

.
├── cmd/
│   └── server/          # Application entry point
│       └── main.go
├── internal/
│   ├── db/              # Database initialization and setup
│   ├── handlers/        # HTTP request handlers
│   └── models/          # Data models
├── migrations/          # Database migrations
├── Makefile            # Development commands
└── README.md

Getting Started

Install Dependencies

make install

Build the Application

make build

Run the Application

make run

The server will start on http://localhost:8080

Development Mode (Hot Reload)

For development with automatic reloading on file changes:

make dev

This will install air if not already installed and run the application with hot reload enabled.

Available Make Commands

CLI Tools

make shark - Build the Shark CLI tool
make install-shark - Install Shark CLI to ~/go/bin

Application

make help - Show all available commands
make install - Install project dependencies
make build - Build the application binary
make run - Build and run the application
make dev - Run in development mode with hot reload

Testing

make demo - Run interactive demo with sample data ⭐
make test-db - Run database integration tests
make test - Run all tests
make test-coverage - Run tests with coverage report

Code Quality

make fmt - Format code using gofmt
make vet - Run go vet for code analysis
make lint - Run golangci-lint (installs if needed)
make clean - Remove build artifacts and databases

Testing

Interactive Demo

See the database in action with sample data:

make demo

This creates an epic, feature, and tasks, then demonstrates:

CRUD operations
Progress calculations
Query filtering
Status updates with history tracking

Integration Tests

Run comprehensive database tests:

make test-db

Tests include:

Epic/Feature/Task CRUD operations
Atomic status updates
Progress calculations
Cascade deletes
All constraints and validations

See TESTING.md for detailed testing guide.

Installation

Shark CLI is available for macOS, Linux, and Windows through multiple installation methods.

Quick Install

Linux/macOS (Manual):

curl -fsSL https://github.com/jwwelbor/shark-task-manager/releases/latest/download/shark_$(uname -s)_$(uname -m).tar.gz -o shark.tar.gz
tar -xzf shark.tar.gz
sudo mv shark /usr/local/bin/

Verify Installation:

shark --version

Detailed Installation Instructions

macOS

Option 1: Homebrew (Recommended)

Add the Shark tap:
```
brew tap jwwelbor/shark
```
Install Shark:
```
brew install shark
```
Verify installation:
```
shark --version
```

Option 2: Manual Installation

Download the latest release for your architecture:
- Intel Macs: shark_*_darwin_amd64.tar.gz
- Apple Silicon (M1/M2/M3): shark_*_darwin_arm64.tar.gz

Extract and install:

tar -xzf shark_*.tar.gz
sudo mv shark /usr/local/bin/

Verify installation:
```
shark --version
```

Linux

Option 1: Manual Installation (All Distributions)

Download the latest release for your architecture:
- AMD64/x86_64: shark_*_linux_amd64.tar.gz
- ARM64/aarch64: shark_*_linux_arm64.tar.gz

Download and verify checksums (recommended):

# Download binary and checksums
wget https://github.com/jwwelbor/shark-task-manager/releases/latest/download/shark_*_linux_amd64.tar.gz
wget https://github.com/jwwelbor/shark-task-manager/releases/latest/download/checksums.txt

# Verify integrity
sha256sum -c checksums.txt --ignore-missing

Extract and install:

tar -xzf shark_*.tar.gz
sudo mv shark /usr/local/bin/

Verify installation:
```
shark --version
```

Option 2: From Source

Install Go 1.23 or later

Clone and build:

git clone https://github.com/jwwelbor/shark-task-manager.git
cd shark-task-manager
make install-shark

Manual Installation

Download shark_*_windows_amd64.zip from the latest release

Download checksums.txt and verify (PowerShell):

# Calculate hash
$actual = (Get-FileHash shark_*_windows_amd64.zip -Algorithm SHA256).Hash.ToLower()

# Extract expected hash
$expected = (Get-Content checksums.txt | Select-String "windows_amd64").ToString().Split()[0]

# Verify
if ($actual -eq $expected) {
    Write-Host "✅ Checksum verified successfully"
} else {
    Write-Host "❌ Checksum verification FAILED"
    exit 1
}

Extract the ZIP file
Add the directory to your PATH or move shark.exe to a directory already in PATH
Verify installation:
```
shark --version
```

Security: Verifying Downloads

All releases include SHA256 checksums in checksums.txt. Always verify downloads before installation:

Linux/macOS:

sha256sum -c checksums.txt --ignore-missing

Windows PowerShell:

$actual = (Get-FileHash shark.zip -Algorithm SHA256).Hash.ToLower()
$expected = (Get-Content checksums.txt | Select-String "windows").ToString().Split()[0]
if ($actual -eq $expected) { Write-Host "✅ Verified" }

Development

Database

The application uses SQLite for data persistence with a complete schema:

Tables:

epics - Top-level project organization units
features - Mid-level components within epics
tasks - Atomic work units within features
task_history - Audit trail of task status changes

Features:

Foreign key constraints with CASCADE DELETE
Auto-update triggers for timestamps
10+ indexes for query performance
WAL mode for better concurrency
Comprehensive validation at application layer

The database file (shark-tasks.db) is automatically created on first run. Turso cloud sqlite db is also supported.

See internal/db/README.md for detailed schema documentation.

Code Formatting

Before committing, format your code:

make fmt
make vet

Testing

Run the test suite:

make test

Generate coverage report:

make test-coverage

CI/CD Pipeline

The project uses GitHub Actions for continuous integration and automated releases.

Continuous Integration (Every Push)

The CI workflow (.github/workflows/ci.yml) runs automatically on every push and pull request:

Tests: Full test suite with coverage reporting
Build: Verifies builds succeed on Linux, macOS, and Windows
Lint: Code quality checks with golangci-lint

All checks must pass before merging to main.

Release Pipeline (Tagged Versions Only)

Releases are triggered by pushing a version tag matching v* (e.g., v1.0.0, v0.2.0-beta):

# Create a signed tag
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

The release workflow (.github/workflows/release.yml) automatically:

Runs all tests as a quality gate
Builds multi-platform binaries using GoReleaser
Creates a GitHub release with all assets
Publishes to Homebrew (macOS)
Publishes to Scoop (Windows)

Only push v-tags to publish releases. Don't use tags for testing.

Release Testing

Post-release testing (.github/workflows/release-test.yml) can be triggered manually or runs automatically after a release:

Tests manual downloads
Validates Homebrew installation (macOS)
Validates Scoop installation (Windows)
Performance benchmarking

Environment Setup

Go is installed in ~/go/bin. Make sure your PATH includes this directory:

export PATH=$PATH:$HOME/go/bin

This is automatically added to your ~/.bashrc and ~/.profile.

License

See LICENSE file for details.

Name	collaboration
Description	Behavioral workflows and collaboration patterns for code review, agent coordination, and branch management. Use this skill when coordinating multi-agent work, managing code review processes, completing feature branches, or resolving productive disagreements between valid approaches.

collaboration

SKILL.md

Shark Task Manager

Key Features

Prerequisites

Shark CLI - AI Agent Task Management

Quick Start for AI Agents

Core Workflows for AI Agents

1. Project Initialization

2. Discovering Available Work

3. Querying Tasks

4. Creating Tasks

5. Task Lifecycle Management

7. Progress Tracking

AI Agent Best Practices

Documentation

User Guides

Reference

Project Structure

Getting Started

Install Dependencies

Build the Application

Run the Application

Development Mode (Hot Reload)

Available Make Commands

CLI Tools

Application

Testing

Code Quality

Testing

Interactive Demo

Integration Tests

Installation

Quick Install

Detailed Installation Instructions

macOS

Linux

Security: Verifying Downloads

Development

Database

Code Formatting

Testing

CI/CD Pipeline

Continuous Integration (Every Push)

Release Pipeline (Tagged Versions Only)

Release Testing

Environment Setup

License