<div align="center">

# OpenTask

**The Memory Layer for AI Agents.**  
A lightweight, persistent task management system that lives in your repository.

> 🚧 **Current Status**: OpenTask CLI is fully supported and stable. The Model Context Protocol (MCP) server integration is currently **under active development** and has not been fully debugged. Please use the CLI for task management for now.

</div>

---

## 📦 Installation & Setup

### 1. Install from Source
Since this package is currently in development:

```bash
# Clone the repository
git clone https://github.com/yourusername/opentask.git
cd opentask

# Install dependencies and build
npm install
npm run build

# Link globally (makes 'opentask' command available)
npm link
```

### 2. Auto-Integrate
Run this command in your target project root to automatically configure your AI tools:

```bash
# Ensure .cursor directory exists if you use Cursor (optional but recommended)
mkdir -p .cursor

# Run installer
opentask install
```

This magic command will:
- **OpenCode**: Inject the "No-Ticket-No-Code" system prompt, configured to use the CLI.
- **Cursor**: Create `.cursor/rules/opentask.mdc` to force the AI to use the task system.

---

## ✨ Why OpenTask?

AI coding assistants (Cursor, Claude, Aider) often suffer from "amnesia". They forget what they were doing between sessions.

**OpenTask** upgrades your workflow from ephemeral "chat messages" to persistent **"Project Memory"**.

1.  **Stateful Task Management**: Track `pending`, `in_progress`, `blocked`, and `completed` states across sessions.
2.  **Repo-Native**: Tasks are stored in `.opentask/tasks/` as JSON files. They are version-controlled with your code.
3.  **Agent-Ready (MCP)**: *[Under Development]* Includes a **Model Context Protocol (MCP)** server, allowing AI agents to read, create, and update tasks autonomously.

---

## 🚀 Workflow

### 1. The Manager (Human)

Use OpenTask to plan work for your AI agents.

```bash
# Initialize project
npx opentask init

# Create tasks for your agent
npx opentask create "Implement Auth" "Login and Signup forms" --priority high
npx opentask create "Setup DB" "Initialize Prisma schema"

# View the board
npx opentask list
```

### 2. The Worker (AI Agent) _(Coming Soon)_

When you connect OpenTask as an MCP Server to your AI (e.g., in Claude Desktop or Cursor), the AI can:

1.  **Read the plan**: `list_tasks(status='pending')`
2.  **Pick a task**: `update_task(id='...', status='in_progress', assignee='claude')`
3.  **Mark complete**: `update_task(id='...', status='completed')`

This means you can close your editor, come back tomorrow, and the AI knows exactly where it left off.

---

## 🛠 CLI Usage

### Create a Task

```bash
# Simple task
npx opentask create "Fix Bug" "Fix login error"

# Rich task with details and criteria
npx opentask create "Refactor API" "Migrate to tRPC" \
  --details "This involves updating the backend router and frontend client." \
  --criteria "All tests pass" "Type safety ensured"

# Specify explicit project root (useful for monorepos)
npx opentask create "Sub-package Task" "..." --root ./packages/ui
```

### List Tasks

```bash
# List all
npx opentask list

# Filter by status
npx opentask list --status pending

# Show dependency tree
npx opentask list --tree
```

### Update Task

```bash
# Start working
npx opentask update <ID> --status in_progress

# Complete
npx opentask update <ID> --status completed

# Add dependency
npx opentask update <ID> --add-dep <DEPENDENCY_ID>
```

### Show Details

```bash
# View full task details including description and criteria
npx opentask show <ID>
```

### Archiving

```bash
# Archive completed tasks to keep the active list clean
# (Moves tasks to .opentask/archive/)
npx opentask archive

# Archive tasks older than 7 days
npx opentask archive --days 7

# Restore a task from archive
npx opentask unarchive <ID>
```

---

## 📂 Project Structure

OpenTask creates a lightweight `.opentask` registry in your project root.

```text
my-project/
├── .opentask/
│   └── tasks/
│       ├── 8a2f9c.json  # Metadata: "Implement Auth"
│       └── b4d1e2.json  # Metadata: "Setup DB"
└── package.json
```

## 📝 Task Definition Schema

A task is simply a JSON file with metadata and context.

```typescript
interface TaskDefinition {
  metadata: {
    id: string;
    status: 'pending' | 'in_progress' | 'blocked' | 'completed';
    priority: 'low' | 'medium' | 'high';
    dependencies: string[];
    assignee?: string;
  };
  
  name: string;
  description: string;
  
  // Context for the AI
  details?: string;
  acceptance_criteria?: string[];

  // Context for the AI
  context?: {
    files?: string[]; // Related files
    notes?: string;   // Extra context
  };
}
```

## 📄 License

Apache-2.0