@qelos/aidev 0.7.0 → 0.7.2

package/README.md

@@ -1,755 +1,755 @@
-# @qelos/aidev
-
-[![npm version](https://img.shields.io/npm/v/%40qelos%2Faidev.svg?style=flat-square)](https://www.npmjs.com/package/@qelos/aidev)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](./LICENSE)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg?style=flat-square)](https://nodejs.org)
-
-**aidev** turns your tasks into merged code — automatically.
-
-It polls your task manager (ClickUp, Jira, Linear, Monday.com, Notion, Trello, or local markdown files), checks whether tasks are clear, runs Claude, Cursor, or Windsurf to implement them, pushes a branch, and moves the task to review. All without touching your keyboard.
-
-```
-Task  →  AI implements  →  git push  →  "in review"  →  AI resolves code review comments
-```
-
----
-
-## Table of Contents
-
-- [How it works](#how-it-works)
-- [Quick start](#quick-start)
-- [Commands](#commands)
-- [Concurrency lock](#concurrency-lock)
-- [Configuration](#configuration)
-- [AI agents](#ai-agents)
-- [Code review resolution](#code-review-resolution)
-- [Auto-merge accepted PRs](#auto-merge-accepted-prs)
-- [Dev notes mode](#dev-notes-mode)
-- [Local tasks file (`aidev.tasks.json`)](#local-tasks-file-aidevtasksjson)
-- [Scheduling](#scheduling)
-- [Hooks](#hooks)
-- [Logging](#logging)
-- [Providers](#providers)
-- [Contributing](#contributing)
-
----
-
-## How it works
-
-1. **Fetch** — pulls all tasks tagged with your configured tag from your task provider
-2. **Filter** — skips done/cancelled tasks and tasks that already have a branch
-3. **Clarify** — in `smart` mode, asks the AI if the task description is clear enough; if not, posts a question as a comment (prefixed with `[aidev]`) and marks the task `pending`
-4. **Wait** — pending tasks are re-checked on the next run; if a human replied or the trigger word is found, implementation proceeds with the conversation as context
-5. **Implement** — checks out a fresh branch (or reuses an existing one), runs your configured AI agent(s), falls back to the next agent if one fails
-6. **Ship** — commits all changes, pushes the branch, posts a comment with the branch name and a PR link, moves the task to your "in review" status
-7. **Review** — checks tasks already in review for unresolved PR code review comments; if found, runs an AI agent to fix code or reply to discussion threads
-
----
-
-## Quick start
-
-```bash
-npm install -g @qelos/aidev
-```
-
-Navigate to your project and run the interactive setup:
-
-```bash
-cd my-project
-aidev init
-```
-
-The wizard will ask for your task provider credentials, git settings, and preferred AI agents.
-
-> **Note:** `aidev init` currently supports **ClickUp, Jira, Linear, Local, and Monday.com**. For **Notion** and **Trello**, create `.env.aidev` manually using `.env.aidev.example` as a template (see [Configuration](#configuration)).
->
-> For ClickUp, API keys can be left blank if they are already set as environment variables in your shell. For Jira, Linear, and Monday.com, the wizard requires credentials to be entered directly — to use shell env vars instead, edit `.env.aidev` after init and remove the values you want read from your environment.
-
-Once configured:
-
-```bash
-aidev run
-```
-
----
-
-## Commands
-
-| Command | Description |
-|---|---|
-| `aidev init` | Interactive setup — creates `.env.aidev` |
-| `aidev run` | Process open + pending tasks, then check review tasks for unresolved PR comments |
-| `aidev run open` | Only open (non-pending) tasks |
-| `aidev run pending` | Only pending tasks — check for human replies |
-| `aidev run accepted` | Auto-merge PRs for tasks in review with the accepted tag |
-| `aidev run tasks` | Publish all entries in `aidev.tasks.json` and exit (no AI run) |
-| `aidev tasks add` | Add a new entry to `aidev.tasks.json` (interactive) |
-| `aidev tasks ls` | List entries currently queued in `aidev.tasks.json` |
-| `aidev tasks update [id]` | Edit a queued entry (interactive if `id` omitted) |
-| `aidev tasks remove [id]` | Delete a queued entry (interactive if `id` omitted) |
-| `aidev tasks push` | Same as `aidev run tasks` — publish all queued entries and exit |
-| `aidev stop` | Stop any running aidev process in the current directory |
-| `aidev schedule set` | Interactive cron picker for this directory |
-| `aidev schedule set "<expr>"` | Set a specific cron expression |
-| `aidev schedule set "<expr>" -e <path>` | Set a schedule that uses a custom env file when it fires |
-| `aidev schedule get` | Show the current schedule for this directory |
-| `aidev help` | Show command and config reference |
-
-### Global flags
-
-| Flag | Description |
-|---|---|
-| `-e, --env <path>` | Load config from a custom env file instead of `.env.aidev` |
-| `-V, --version` | Print version |
-
-**Examples**
-
-```bash
-# Use a shared env file for a staging environment
-aidev --env /shared/.env.staging run
-
-# Only process tasks that are waiting for a reply
-aidev run pending
-
-# Schedule to run every 30 minutes
-aidev schedule set "*/30 * * * *"
-```
-
----
-
-## Concurrency lock
-
-`aidev run` writes a PID lock file (`.aidev.lock`) in the current directory when it starts and removes it when it finishes. If a second invocation detects a live process already holding the lock, it logs a warning and exits immediately — preventing two agents from committing to the same branch at the same time.
-
-```
-$ aidev run
-[aidev] aidev is already running in this directory (PID 12345). Use "aidev stop" to terminate it.
-```
-
-Use `aidev stop` to send `SIGTERM` to the running process and clean up the lock file:
-
-```bash
-aidev stop
-```
-
-Stale lock files (left behind by a crash) are detected automatically — the next `aidev run` will overwrite them if the stored PID is no longer alive.
-
----
-
-## Configuration
-
-Run `aidev init` for an interactive setup, or create `.env.aidev` manually using `.env.aidev.example` as a template.
-
-### Global env file (`AIDEV_ENV_EXTEND`)
-
-If you work across multiple projects, you can keep shared settings (API keys, agent list, etc.) in a single global file and reference it from each project's `.env.aidev`:
-
-```bash
-# ~/.aidev.global
-CLICKUP_API_KEY=pk_...
-CLICKUP_TEAM_ID=123456
-AGENTS=claude,cursor
-```
-
-```bash
-# my-project/.env.aidev  — project-specific values override the global ones
-AIDEV_ENV_EXTEND=~/.aidev.global
-CLICKUP_TAG=my-project
-```
-
-**Priority order (highest → lowest):**
-
-1. Shell environment variables (e.g. set in `~/.zshrc`) — never overwritten
-2. Local `.env.aidev` values
-3. `AIDEV_ENV_EXTEND` file values (global base)
-
-`AIDEV_ENV_EXTEND` can be set in two ways:
-
-- **Per-project** — add `AIDEV_ENV_EXTEND=/path/to/file` inside `.env.aidev`
-- **Shell-wide** — `export AIDEV_ENV_EXTEND=~/.aidev.global` in `~/.zshrc` (applies to every project automatically)
-
-`aidev init` will ask for this path and pre-fill it if the variable is already in your shell environment.
-
-### ClickUp
-
-| Variable | Default | Description |
-|---|---|---|
-| `CLICKUP_API_KEY` | — | Personal API token — can be set as a shell env var |
-| `CLICKUP_TEAM_ID` | — | Workspace / team ID — can be set as a shell env var |
-| `CLICKUP_TAG` | — | Tasks with this tag will be picked up (set to `*` to match all tasks) |
-| `CLICKUP_PENDING_STATUS` | `pending` | Status name for "waiting for reply" |
-| `CLICKUP_IN_REVIEW_STATUS` | `review` | Status set after implementation |
-| `ASSIGNEE_TAG` | — | Only process tasks assigned to this user (optional) |
-| `THINKING_TAG` | — | Tasks with this tag are analyzed and broken into sub-tasks before execution (optional) |
-| `NON_CODE_TAG` | — | Tasks with this tag run without git branching (optional) |
-| `NON_CODE_CLICKUP_TEAM_ID` | same as `CLICKUP_TEAM_ID` | Different workspace for non-code tasks (optional) |
-
-> **Tip:** For ClickUp, API keys and tokens are intentionally omitted from `.env.aidev` if you leave them blank during `aidev init` — they will be read from your shell environment instead. For Jira, Linear, and Monday.com, the wizard requires these values; to use shell env vars, remove the entries from `.env.aidev` after init.
-
-> **Wildcard tag (`*`):** Set `CLICKUP_TAG=*` (or `JIRA_LABEL=*` / `LINEAR_LABEL=*` / `TRELLO_LABEL=*`) to match **all** tasks regardless of tags/labels. This is useful when the AI dev has its own dedicated user in the task provider and every task assigned to it should be processed.
-
-### Jira
-
-| Variable | Default | Description |
-|---|---|---|
-| `JIRA_BASE_URL` | — | Jira instance URL (e.g. `https://mycompany.atlassian.net`) |
-| `JIRA_EMAIL` | — | Email for Jira authentication |
-| `JIRA_API_TOKEN` | — | API token — generate from [Atlassian account settings](https://id.atlassian.com/manage-profile/security/api-tokens) |
-| `JIRA_PROJECT` | — | Project key (e.g. `PROJ`) |
-| `JIRA_LABEL` | — | Issues with this label will be picked up (set to `*` to match all issues) |
-| `JIRA_PENDING_STATUS` | `To Do` | Status name for "waiting for reply" |
-| `JIRA_IN_REVIEW_STATUS` | `In Review` | Status set after implementation |
-| `NON_CODE_JIRA_PROJECT` | same as `JIRA_PROJECT` | Different project for non-code tasks (optional) |
-
-### Linear
-
-Linear calls them "labels" — the same concept as `CLICKUP_TAG` / `JIRA_LABEL`. Tasks created via `aidev.tasks.json` with `tags` are mapped to Linear labels on the configured team, and missing labels are created automatically. Default status names align with Linear's standard workflow (`Backlog`, `Todo`, `In Progress`, `In Review`, `Done`); if your team renamed those states (e.g. `Triage` instead of `Backlog`), aidev also falls back to matching by Linear's underlying state type.
-
-| Variable | Default | Description |
-|---|---|---|
-| `LINEAR_API_KEY` | — | Personal API key from Linear Settings → API |
-| `LINEAR_TEAM_ID` | — | Team UUID from your workspace |
-| `LINEAR_LABEL` | — | Issues with this label will be picked up (set to `*` to match all issues) |
-| `LINEAR_PENDING_STATUS` | `Backlog` | Status name for "waiting for reply" |
-| `LINEAR_IN_REVIEW_STATUS` | `In Review` | Status set after implementation |
-| `NON_CODE_LINEAR_TEAM_ID` | same as `LINEAR_TEAM_ID` | Different team for non-code tasks (optional) |
-
-### Monday.com
-
-| Variable | Default | Description |
-|---|---|---|
-| `MONDAY_API_TOKEN` | — | API token from monday.com Developer settings |
-| `MONDAY_BOARD_ID` | — | Board ID (from the board URL) |
-| `MONDAY_STATUS_COLUMN_ID` | `status` | Column ID for the status field |
-| `MONDAY_GROUP_ID` | — | Group ID to filter items (optional) |
-
-### Notion
-
-| Variable | Default | Description |
-|---|---|---|
-| `NOTION_API_KEY` | — | Integration token from Notion → Settings → My integrations |
-| `NOTION_DATABASE_ID` | — | Database ID from the database URL (32-char hex) |
-| `NOTION_STATUS_PROPERTY` | `Status` | Name of the status property in the database |
-| `NOTION_PENDING_STATUS` | `pending` | Status value for "waiting for reply" |
-| `NOTION_IN_REVIEW_STATUS` | `review` | Status value set after implementation |
-
-### Trello
-
-| Variable | Default | Description |
-|---|---|---|
-| `TRELLO_API_KEY` | — | Developer API key from [trello.com/power-ups/admin](https://trello.com/power-ups/admin) |
-| `TRELLO_TOKEN` | — | Auth token generated via Trello's token flow |
-| `TRELLO_BOARD_ID` | — | Board ID from the board URL |
-| `TRELLO_LABEL` | — | Label name on cards to pick up (set to `*` to match all cards assigned to the token user) |
-| `TRELLO_OPEN_LIST` | `To Do` | List name for open/new cards |
-| `TRELLO_PENDING_LIST` | `Blocked` | List name for "waiting for reply" |
-| `TRELLO_IN_PROGRESS_LIST` | `Doing` | List name for cards being worked on |
-| `TRELLO_IN_REVIEW_LIST` | `In Review` | List name for completed cards awaiting review |
-| `TRELLO_OPEN_STATUS` | `open` | Semantic status mapped to the open list |
-| `TRELLO_PENDING_STATUS` | `pending` | Semantic status mapped to the pending list |
-| `TRELLO_IN_REVIEW_STATUS` | `review` | Semantic status mapped to the review list |
-
-### Git & GitHub
-
-| Variable | Default | Description |
-|---|---|---|
-| `GIT_REMOTE` | auto-detected | Remote name — detected via `git remote get-url origin` if unset |
-| `GITHUB_BASE_BRANCH` | `main` | Base branch; new task branches are cut from here |
-| `GITHUB_REPO` | — | `owner/repo` — used to generate PR links in comments |
-
-### Behaviour
-
-| Variable | Default | Description |
-|---|---|---|
-| `AIDEV_ENV_EXTEND` | — | Path to a global env file loaded as the base for this project (see above) |
-| `AGENTS` | `claude,cursor` | Comma-separated list of agents in priority order |
-| `DEV_NOTES_MODE` | `smart` | When to ask for clarification (`smart` or `always`) |
-| `AIDEV_TRIGGER_WORD` | `aidev-continue` | Comment containing this word re-triggers a skipped task |
-| `AIDEV_COMMENT_PREFIX` | `[aidev]` | Custom prefix for all aidev comments posted to task providers |
-| `AIDEV_HOOKS_PATH` | — | Path to a `.ts` or `.js` module that exports hook functions (see [Hooks](#hooks)) |
-| `ACCEPTED_TAG` | `accepted` | Tasks in review with this tag are auto-merged (see [Auto-merge accepted PRs](#auto-merge-accepted-prs)) |
-| `DONE_STATUS` | auto-detected | Status to set after auto-merging an accepted PR. When unset, aidev picks the first match of `done`, `closed`, `finish`, `success`, `prod` from the board's statuses |
-| `PR_SIGNATURE` | `Automated PR by aidev.` | Custom signature line appended to the PR body |
-| `AIDEV_AUTO_COMPRESS` | `true` | Auto-compress older comments when the prompt grows large. Set to `false` / `0` / `no` to opt out |
-| `AIDEV_COMPRESS_THRESHOLD` | `12000` | Char-length threshold that triggers compression |
-
----
-
-## Hooks
-
-Set `AIDEV_HOOKS_PATH` in `.env.aidev` to a path relative to the project directory or an absolute path. `aidev init` writes `.aidev/aidev.hooks.ts` and sets `AIDEV_HOOKS_PATH=.aidev/aidev.hooks.ts` by default.
-
-The module should export an object (or `export default`) whose properties are optional async functions. Only known hook names are used; anything else is ignored. If a hook throws, the current operation stops (for example the whole run after `beforeRun`, or conflict resolution after `beforeResolveConflicts`). If a hook returns an object, it replaces the context for that step (for example append to `context.prompt` in `beforeEachTask` and return the updated context).
-
-**Hook names**
-
-| Hook | When | Context notes |
-|---|---|---|
-| `beforeRun` / `afterRun` | Start / end of `aidev run` | `afterRun` includes `processed` and `skipped` counts |
-| `beforeEachTask` / `afterEachTask` | Around each code task implementation | `prompt`, `branchName`, `task`; `afterEachTask` has `success` |
-| `beforeResolveConflicts` / `afterResolveConflicts` | Merge conflict resolution with AI | `conflictFiles`, `prompt`; `afterResolveConflicts` has `resolved` |
-| `beforeNonCodeTask` / `afterNonCodeTask` | Non-code tasks | `afterNonCodeTask` includes agent `output` |
-| `beforeThinkingTask` / `afterThinkingTask` | Thinking-tag tasks (subtask plan) | `beforeThinkingTask` may adjust `subtasks` before steps run |
-| `beforeReviewTask` / `afterReviewTask` | Review tasks with unresolved PR comments | `threads`, `prompt`, `branchName`; `afterReviewTask` has `success`, `resolvedCount` |
-
-**Second argument: `vm`**
-
-Each hook receives `(context, vm)`. The `vm` object exposes:
-
-- `runAI(prompt)` — runs the first available configured AI agent
-- `postComment(taskId, text)`, `updateStatus(taskId, status)`, `getComments(taskId)` — same family of operations as the task provider
-- `log.info` / `log.warn` / `log.error` — prefixed hook logging
-
-**TypeScript hooks**
-
-`.ts` hook files are loaded at runtime via [jiti](https://www.npmjs.com/package/jiti) — no TypeScript compiler or toolchain needed. Just write a plain `.ts` file with the hook functions and aidev handles the rest.
-
----
-
-## AI agents
-
-aidev supports multiple AI agents with automatic fallback. The first available agent in the list is used; if it fails, the next one is tried with the previous agent's output as additional context.
-
-**Supported agents**
-
-| Agent | Requires |
-|---|---|
-| `antigravity` | Google **Antigravity** CLI (`agy` or `antigravity`) in PATH — see [Antigravity](https://antigravity.google/download) |
-| `claude` | [Claude CLI](https://github.com/anthropics/claude-code) installed and authenticated |
-| `cursor` | Cursor **Agent CLI** (`agent`) in PATH — see [Windows](#windows-cursor-agent-cli) below |
-| `windsurf` | [Windsurf](https://windsurf.com) installed with CLI available in PATH |
-
-### Windows: Cursor Agent CLI
-
-On Windows, the Cursor IDE (`cursor.exe`) is separate from the headless Agent CLI. The runner uses the `agent` binary. Install it in PowerShell:
-
-```powershell
-irm 'https://cursor.com/install?win32=true' | iex
-```
-
-Then ensure `agent` is on your PATH and run `agent --version` to confirm. Without this, the Cursor runner will report as unavailable.
-
-**Configure agent order in `.env.aidev`:**
-
-```bash
-# Claude first, fall back to Cursor
-AGENTS=claude,cursor
-
-# Cursor only
-AGENTS=cursor
-
-# Cursor first (useful when working locally with a monitor)
-AGENTS=cursor,claude
-
-# Claude first, then Windsurf, then Cursor
-AGENTS=claude,windsurf,cursor
-
-# Antigravity first, then Claude
-AGENTS=antigravity,claude
-
-# Windsurf only
-AGENTS=windsurf
-```
-
----
-
-## Trigger word & re-processing
-
-aidev prefixes every comment it posts with `[aidev]` (configurable via `AIDEV_COMMENT_PREFIX`). This lets it distinguish its own comments from human replies when deciding whether to re-process a task.
-
-A task is normally skipped when:
-- A remote branch already exists for it, **or**
-- It is `pending` and no human has replied yet
-
-To force aidev to pick the task up again, post a comment containing the **trigger word** (default: `aidev-continue`). aidev will reuse the existing branch and continue implementation from where it left off.
-
-```bash
-# Customise the trigger word in .env.aidev
-AIDEV_TRIGGER_WORD=please-retry
-```
-
-The trigger word match is case-insensitive, so `aidev-continue`, `AIDEV-CONTINUE`, and `Aidev-Continue` all work.
-
-For pending tasks, a regular human reply (any comment without the configured prefix) also triggers re-processing — the trigger word is an additional explicit mechanism.
-
-```bash
-# Customise the comment prefix in .env.aidev
-AIDEV_COMMENT_PREFIX=[mybot]
-```
-
----
-
-## Auto-compress
-
-For long-running tasks with many comments, the combined prompt (description + conversation history + review threads) can grow past the AI agent's effective context window. When the assembled context exceeds `AIDEV_COMPRESS_THRESHOLD` characters (default `12000`), aidev summarises the older comments via the configured AI agent and keeps only the **latest comment verbatim** — so the agent always sees the user's most recent intent without ambiguity.
-
-Compressed summaries are cached under `.aidev/sessions/<taskId>.json` and reused across runs; new comments invalidate the cache and trigger a re-summarisation of the delta. The directory is added to `.gitignore` automatically.
-
-This is **on by default**. To opt out:
-
-```bash
-# In .env.aidev
-AIDEV_AUTO_COMPRESS=false
-
-# Or raise the threshold instead of disabling
-AIDEV_COMPRESS_THRESHOLD=24000
-```
-
----
-
-## Non-code tasks
-
-Tasks tagged with `NON_CODE_TAG` are executed **without git branching** — no checkout, commit, push, or PR creation. The AI agent runs the task directly in the current working directory.
-
-This is useful for:
-- Research or investigation tasks
-- Documentation updates that don't go through PR review
-- Running scripts or commands
-- Any task where you want the AI to act without creating a branch
-
-```bash
-# In .env.aidev
-NON_CODE_TAG=non-code
-
-# Optionally use a different ClickUp team for non-code tasks
-NON_CODE_CLICKUP_TEAM_ID=987654
-
-# Or a different Jira project
-NON_CODE_JIRA_PROJECT=OPS
-```
-
-Non-code tasks follow the same lifecycle as regular tasks (clarification → implementation → review), except the implementation step skips all git operations. After completion, the task status is moved to your configured "in review" status.
-
-If `NON_CODE_TAG` is not configured, non-code task processing is disabled entirely.
-
----
-
-## Code review resolution
-
-When `aidev run` executes, it also checks tasks in **review** status for unresolved PR code review comments. If any actionable threads are found, an AI agent is run to address them — either by fixing the code or replying to discussion comments.
-
-**How it works:**
-
-1. Fetches all tasks in your configured "in review" status
-2. For each task, finds the associated PR by branch name (via `gh` CLI)
-3. Fetches unresolved review threads from the PR
-4. Filters out threads where the last comment is from aidev itself (to avoid re-processing)
-5. Runs an AI agent to address the remaining threads — code fixes are committed and pushed, discussion replies are posted directly on the thread
-6. Resolved threads are marked as resolved on GitHub
-
-This runs automatically as part of every `aidev run` (after processing open/pending tasks). No additional configuration is needed beyond having `gh` CLI installed and authenticated.
-
-> **Prerequisites:** The [GitHub CLI](https://cli.github.com/) must be installed and authenticated (`gh auth login`). If `gh` is not available, review task processing is silently skipped.
-
----
-
-## Auto-merge accepted PRs
-
-When a task has been reviewed and is ready to merge, tag it with `accepted` (the default — override via `ACCEPTED_TAG`). On the next run, aidev will automatically merge the PR via the GitHub CLI (`gh`), update the task status, and sync your local main branch.
-
-This feature works out of the box whenever the `gh` CLI is installed and authenticated.
-
-```bash
-# In .env.aidev (both optional)
-# ACCEPTED_TAG=accepted   # the tag aidev looks for on review tasks (default: accepted)
-# DONE_STATUS=done        # status to apply after merge — auto-detected when omitted
-```
-
-**How it works:**
-
-1. Finds all tasks in your "in review" status that have the accepted tag (`accepted` by default)
-2. For each task: merges the PR with squash and deletes the remote branch (`gh pr merge --squash --delete-branch`)
-3. Updates the task status to `DONE_STATUS`. When unset, aidev probes the board for one of `done`, `closed`, `finish`, `success`, `prod` and uses the first match
-4. Checks out the base branch and pulls the latest changes
-
-**Run it manually:**
-
-```bash
-aidev run accepted
-```
-
-**Automatic mode:** Whenever `gh` is available, accepted PRs are also auto-merged at the end of every `aidev run`.
-
-> **Prerequisites:** The [GitHub CLI](https://cli.github.com/) must be installed and authenticated (`gh auth login`). `aidev init` will prompt you for these settings if it detects `gh` on your PATH.
-
----
-
-## Dev notes mode
-
-Controls when aidev asks the task provider for clarification before implementing.
-
-| Mode | Behaviour |
-|---|---|
-| `smart` | Asks the AI whether the task description is clear enough. Only posts a clarification question if it's ambiguous. |
-| `always` | Always posts "any dev notes?" before implementing every task. |
-
-When a question is posted, the task is moved to the configured pending status (e.g. `CLICKUP_PENDING_STATUS`, `JIRA_PENDING_STATUS`, etc.). On the next run, aidev checks whether a human has replied and, if so, includes the reply as context for the AI.
-
----
-
-## Local tasks file (`aidev.tasks.json`)
-
-`aidev.tasks.json` is an **outbound queue** — a JSON file that sits at the root of your project and holds task templates that aidev will publish to your configured provider (ClickUp, Jira, Linear, etc.). It is the opposite direction from the [Local provider](#local-provider): the local provider **stores** tasks on disk, while `aidev.tasks.json` **pushes** tasks to a remote provider.
-
-Typical uses:
-
-- **Recurring tasks** — with a `cron` expression, an entry publishes a fresh task on every matching tick (daily standup reminders, weekly reviews, monthly housekeeping).
-- **Staged work** — queue a batch of tasks in a commit so they appear in the provider together when `aidev` next runs.
-- **AI-authored tasks** — another AI agent or script can append entries to the file; `aidev` will pick them up and create real tickets.
-
-The file is added to `.gitignore` by `aidev init` — each developer or automation environment maintains their own queue.
-
-### File format
-
-`aidev.tasks.json` is a JSON array of task entries. Each entry has the shape:
-
-```ts
-interface LocalTask {
-  id: string;              // UUID — generated automatically by "aidev tasks add"
-  title: string;           // required — task title on the remote provider
-  description: string;     // task body / description
-  type: 'code' | 'non-code'; // routes to the non-code provider when set to 'non-code'
-  priority?: number;       // 1=urgent, 2=high, 3=normal, 4=low
-  assignee?: string;       // currently informational (reserved for future use)
-  dueDate?: string;        // ISO date, e.g. "2026-05-01"
-  tags?: string[];         // extra tags appended to the provider-configured tag
-  listId?: string;         // override provider list / project ID for this task only
-  cron?: string;           // 5-field cron — if set, the task is re-published on every tick
-  lastPushedAt?: number;   // epoch ms of the last successful push (managed by aidev for cron entries)
-}
-```
-
-**Example** (`aidev.tasks.json`):
-
-```json
-[
-  {
-    "id": "7f3a9c2d-5b1e-4a6f-9d8c-1e2f3a4b5c6d",
-    "title": "Daily standup notes",
-    "description": "Post yesterday / today / blockers to the team channel.",
-    "type": "non-code",
-    "priority": 3,
-    "tags": ["standup"],
-    "cron": "0 9 * * 1-5"
-  },
-  {
-    "id": "2b8e1f7a-4c9d-4e5a-8b6c-9f1e2d3c4b5a",
-    "title": "Upgrade dependencies",
-    "description": "Run `npm outdated`, bump minor/patch versions, verify tests pass.",
-    "type": "code",
-    "priority": 2,
-    "tags": ["maintenance"]
-  }
-]
-```
-
-### Lifecycle
-
-1. **Every `aidev run`** (regardless of filter) begins by reading `aidev.tasks.json` and attempting to publish each entry via the configured provider's `createTask` API.
-2. **One-shot entries** (no `cron` field) are **removed from the file** after a successful push — they become a real ticket and won't be duplicated on the next run.
-3. **Cron entries** remain in the file. `lastPushedAt` is updated on each successful push; on the next run, aidev checks whether the cron has fired at least once since `lastPushedAt` before republishing. A fresh entry with a cron fires on the first run that matches.
-4. **Failures** are logged and the entry is kept — the next run retries.
-
-### Routing
-
-- `type: 'code'` → published with the code tag (`CLICKUP_TAG` / `JIRA_LABEL` / `LINEAR_LABEL`, etc.) to the primary provider.
-- `type: 'non-code'` → published with `NON_CODE_TAG` to the non-code provider (a separate team / project if `NON_CODE_CLICKUP_TEAM_ID`, `NON_CODE_JIRA_PROJECT`, or `NON_CODE_LINEAR_TEAM_ID` is configured, otherwise the primary).
-- Per-task `tags` are appended to the resolved default tag.
-- Per-task `listId` overrides the provider-default list / project for that single task.
-
-### Managing entries
-
-Use the built-in commands rather than hand-editing JSON (although hand-editing is fine — the file is plain JSON):
-
-```bash
-aidev tasks add              # interactive prompt: title, description, type, priority, due date, tags, list, cron
-aidev tasks ls               # table of queued entries
-aidev tasks update [id]      # edit an entry by table ID (interactive picker if no id)
-aidev tasks remove [id]      # delete an entry by table ID (interactive picker if no id)
-aidev tasks push             # publish everything now (same as "aidev run tasks") — useful for dry-running or in scripts
-```
-
-`aidev tasks push` and `aidev run tasks` do the same thing: they only process `aidev.tasks.json` and exit without pulling tasks from the provider or invoking the AI. This is useful when you want to decouple queue publishing from the main AI loop — for example, running `aidev tasks push` from a separate cron entry or CI job.
-
----
-
-## Scheduling
-
-aidev can run on a cron schedule, one entry per project directory.
-
-```bash
-# Interactive picker
-aidev schedule set
-
-# Or pass an expression directly
-aidev schedule set "*/15 * * * *"
-
-# Run a schedule against a custom env file (so the scheduled run uses
-# that config — useful when several env files live alongside one repo)
-aidev schedule set "*/15 * * * *" -e /path/to/custom/.env.aidev
-
-# Check what's scheduled for the current directory
-aidev schedule get
-```
-
-The `-e <path>` option is baked into the scheduled entry itself (the cron
-line on Linux, the LaunchAgent plist on macOS, or the Task Scheduler `/tr`
-command on Windows), so each run will pick up the right env file without
-relying on the shell environment at firing time.
-
-**Preset options (interactive picker)**
-
-| Option | Expression |
-|---|---|
-| Every 15 minutes | `*/15 * * * *` |
-| Every 30 minutes | `*/30 * * * *` |
-| Every hour | `0 * * * *` |
-| Every 5 hours | `0 */5 * * *` |
-| Every day at 8am | `0 8 * * *` |
-
-Each directory gets its own cron entry identified by a `# aidev-cwd:/path` marker — running `schedule set` again replaces the existing entry rather than adding a duplicate.
-
-### macOS: Full Disk Access required
-
-On macOS (Ventura and later), cron jobs are silently blocked unless `/usr/sbin/cron` has Full Disk Access:
-
-1. Open **System Settings → Privacy & Security → Full Disk Access**
-2. Click **+** and add `/usr/sbin/cron`
-3. Re-run `aidev schedule set` to apply your schedule
-
-Without this, cron will appear to be configured but jobs will never fire.
-
----
-
-## Logging
-
-Every run appends to `aidev.log` in your project directory:
-
-```
-────────────────────────────────────────────────────────────
-2026-03-06T08:00:00.000Z [run] started
-────────────────────────────────────────────────────────────
-2026-03-06T08:00:00.120Z [info] Fetching tasks (filter: all)...
-2026-03-06T08:00:01.340Z [task] [abc123] "Fix login flow" (status: open)
-2026-03-06T08:00:12.780Z [info] Running claude...
-2026-03-06T08:00:45.210Z [success] Task implemented: branch abc123/fix-login-flow pushed
-2026-03-06T08:00:45.890Z [success] Done. Processed: 1, Skipped: 3
-```
-
-ANSI colour codes are stripped so the file stays readable in any editor or `tail -f`. `aidev.log` is added to `.gitignore` automatically by `aidev init`.
-
-To write the log somewhere else, set `AIDEV_LOG_PATH` to an absolute, relative, or `~/`-prefixed path that includes the **file name** (not just the folder). Relative paths are resolved against the project cwd and missing parent directories are created on first write.
-
-```bash
-AIDEV_LOG_PATH=logs/aidev.log         # → <cwd>/logs/aidev.log
-AIDEV_LOG_PATH=/var/log/aidev.log     # absolute
-AIDEV_LOG_PATH=~/aidev/run.log        # under your home directory
-```
-
----
-
-## Providers
-
-| Provider | Status | `aidev init` support |
-|---|---|---|
-| ClickUp | ✅ Implemented | ✅ Interactive wizard |
-| Jira | ✅ Implemented | ✅ Interactive wizard |
-| Linear | ✅ Implemented | ✅ Interactive wizard |
-| Monday.com | ✅ Implemented | ✅ Interactive wizard |
-| Local | ✅ Implemented | ✅ Interactive wizard |
-| Notion | ✅ Implemented | Manual `.env.aidev` config |
-| Trello | ✅ Implemented | Manual `.env.aidev` config |
-
-> **Notion & Trello:** These providers are fully functional but not yet included in the `aidev init` wizard. To use them, set `PROVIDER=notion` or `PROVIDER=trello` in `.env.aidev` and fill in the required variables from the [Configuration](#configuration) section above.
-
-The `TaskProvider` interface makes it straightforward to add new providers. See [CONTRIBUTING.md](./CONTRIBUTING.md).
-
-### Local provider
-
-Set `PROVIDER=local` in `.env.aidev` to manage tasks entirely via local markdown files — no external API needed.
-
-```bash
-aidev init   # choose "local" when prompted for provider
-```
-
-Tasks live in `.aidev/tasks/` under status folders:
-
-```
-.aidev/tasks/
-  open/          # new tasks ready for implementation
-  pending/       # waiting for human reply
-  progress/      # currently being implemented
-  review/        # implementation complete, awaiting review
-  done/          # finished
-```
-
-**Task file format** (e.g. `.aidev/tasks/open/a1b2c3d4-fix-login-bug.md`):
-
-```markdown
----
-title: Fix login page bug
-priority: 2
-assignee: david
-estimated: 2h
-tags: frontend, auth
-created: 2026-03-12T10:00:00.000Z
----
-
-The login form should redirect users to the dashboard after successful authentication.
-```
-
-The filename must start with a short ID (hex characters) followed by a dash and a slug. The YAML frontmatter carries task metadata; everything after `---` is the task description.
-
-#### Code vs non-code tasks
-
-By default, local tasks are treated as **code tasks** — aidev creates a git branch, runs the AI agent, commits, pushes, and opens a PR.
-
-To mark a task as **non-code** (research, docs, investigation — no git branching), add `type: non-code` to the frontmatter:
-
-```markdown
----
-title: Compare OAuth2 providers
-type: non-code
-tags: research
----
-
-Evaluate Auth0, Clerk, and Supabase Auth. Write a recommendation.
-```
-
-Non-code tasks follow the same lifecycle but skip all git operations. The AI response is posted as a session comment instead of a PR.
-
-**Session file** (comments) — `.aidev/tasks/open/a1b2c3d4-fix-login-bug.session.md`:
-
-```markdown
-<!-- aidev session log — append your comments below using "## your-name" as header -->
-
----
-
-## aidev — 2026-03-12T10:05:00.000Z
-
-[aidev] Starting implementation on branch `a1b2c3d4/fix-login-bug`
-
----
-
-## david — 2026-03-12T10:10:00.000Z
-
-Please use the new auth API endpoint for this.
-```
-
-To add a comment, append a `---` separator followed by a `## your-name` header and your message. aidev parses these entries automatically and uses them as conversation context, just like ClickUp/Jira comments.
-
-Downloaded task attachments are stored in `.aidev/assets/<task-id>/`, and `aidev init` adds `.aidev/assets/` to `.gitignore` automatically.
-
----
-
-## Contributing
-
-Contributions are welcome — new providers, new AI runners, bug fixes, and docs improvements.
-
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full guide.
-
----
-
-## License
-
-[MIT](./LICENSE)
+# @qelos/aidev
+
+[![npm version](https://img.shields.io/npm/v/%40qelos%2Faidev.svg?style=flat-square)](https://www.npmjs.com/package/@qelos/aidev)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](./LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg?style=flat-square)](https://nodejs.org)
+
+**aidev** turns your tasks into merged code — automatically.
+
+It polls your task manager (ClickUp, Jira, Linear, Monday.com, Notion, Trello, or local markdown files), checks whether tasks are clear, runs Claude, Cursor, or Windsurf to implement them, pushes a branch, and moves the task to review. All without touching your keyboard.
+
+```
+Task  →  AI implements  →  git push  →  "in review"  →  AI resolves code review comments
+```
+
+---
+
+## Table of Contents
+
+- [How it works](#how-it-works)
+- [Quick start](#quick-start)
+- [Commands](#commands)
+- [Concurrency lock](#concurrency-lock)
+- [Configuration](#configuration)
+- [AI agents](#ai-agents)
+- [Code review resolution](#code-review-resolution)
+- [Auto-merge accepted PRs](#auto-merge-accepted-prs)
+- [Dev notes mode](#dev-notes-mode)
+- [Local tasks file (`aidev.tasks.json`)](#local-tasks-file-aidevtasksjson)
+- [Scheduling](#scheduling)
+- [Hooks](#hooks)
+- [Logging](#logging)
+- [Providers](#providers)
+- [Contributing](#contributing)
+
+---
+
+## How it works
+
+1. **Fetch** — pulls all tasks tagged with your configured tag from your task provider
+2. **Filter** — skips done/cancelled tasks and tasks that already have a branch
+3. **Clarify** — in `smart` mode, asks the AI if the task description is clear enough; if not, posts a question as a comment (prefixed with `[aidev]`) and marks the task `pending`
+4. **Wait** — pending tasks are re-checked on the next run; if a human replied or the trigger word is found, implementation proceeds with the conversation as context
+5. **Implement** — checks out a fresh branch (or reuses an existing one), runs your configured AI agent(s), falls back to the next agent if one fails
+6. **Ship** — commits all changes, pushes the branch, posts a comment with the branch name and a PR link, moves the task to your "in review" status
+7. **Review** — checks tasks already in review for unresolved PR code review comments; if found, runs an AI agent to fix code or reply to discussion threads
+
+---
+
+## Quick start
+
+```bash
+npm install -g @qelos/aidev
+```
+
+Navigate to your project and run the interactive setup:
+
+```bash
+cd my-project
+aidev init
+```
+
+The wizard will ask for your task provider credentials, git settings, and preferred AI agents.
+
+> **Note:** `aidev init` currently supports **ClickUp, Jira, Linear, Local, Monday.com, and Trello**. For **Notion**, create `.env.aidev` manually using `.env.aidev.example` as a template (see [Configuration](#configuration)).
+>
+> For ClickUp, API keys can be left blank if they are already set as environment variables in your shell. For Jira, Linear, Monday.com, and Trello, the wizard requires credentials to be entered directly — to use shell env vars instead, edit `.env.aidev` after init and remove the values you want read from your environment.
+
+Once configured:
+
+```bash
+aidev run
+```
+
+---
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `aidev init` | Interactive setup — creates `.env.aidev` |
+| `aidev run` | Process open + pending tasks, then check review tasks for unresolved PR comments |
+| `aidev run open` | Only open (non-pending) tasks |
+| `aidev run pending` | Only pending tasks — check for human replies |
+| `aidev run accepted` | Auto-merge PRs for tasks in review with the accepted tag |
+| `aidev run tasks` | Publish all entries in `aidev.tasks.json` and exit (no AI run) |
+| `aidev tasks add` | Add a new entry to `aidev.tasks.json` (interactive) |
+| `aidev tasks ls` | List entries currently queued in `aidev.tasks.json` |
+| `aidev tasks update [id]` | Edit a queued entry (interactive if `id` omitted) |
+| `aidev tasks remove [id]` | Delete a queued entry (interactive if `id` omitted) |
+| `aidev tasks push` | Same as `aidev run tasks` — publish all queued entries and exit |
+| `aidev stop` | Stop any running aidev process in the current directory |
+| `aidev schedule set` | Interactive cron picker for this directory |
+| `aidev schedule set "<expr>"` | Set a specific cron expression |
+| `aidev schedule set "<expr>" -e <path>` | Set a schedule that uses a custom env file when it fires |
+| `aidev schedule get` | Show the current schedule for this directory |
+| `aidev help` | Show command and config reference |
+
+### Global flags
+
+| Flag | Description |
+|---|---|
+| `-e, --env <path>` | Load config from a custom env file instead of `.env.aidev` |
+| `-V, --version` | Print version |
+
+**Examples**
+
+```bash
+# Use a shared env file for a staging environment
+aidev --env /shared/.env.staging run
+
+# Only process tasks that are waiting for a reply
+aidev run pending
+
+# Schedule to run every 30 minutes
+aidev schedule set "*/30 * * * *"
+```
+
+---
+
+## Concurrency lock
+
+`aidev run` writes a PID lock file (`.aidev.lock`) in the current directory when it starts and removes it when it finishes. If a second invocation detects a live process already holding the lock, it logs a warning and exits immediately — preventing two agents from committing to the same branch at the same time.
+
+```
+$ aidev run
+[aidev] aidev is already running in this directory (PID 12345). Use "aidev stop" to terminate it.
+```
+
+Use `aidev stop` to send `SIGTERM` to the running process and clean up the lock file:
+
+```bash
+aidev stop
+```
+
+Stale lock files (left behind by a crash) are detected automatically — the next `aidev run` will overwrite them if the stored PID is no longer alive.
+
+---
+
+## Configuration
+
+Run `aidev init` for an interactive setup, or create `.env.aidev` manually using `.env.aidev.example` as a template.
+
+### Global env file (`AIDEV_ENV_EXTEND`)
+
+If you work across multiple projects, you can keep shared settings (API keys, agent list, etc.) in a single global file and reference it from each project's `.env.aidev`:
+
+```bash
+# ~/.aidev.global
+CLICKUP_API_KEY=pk_...
+CLICKUP_TEAM_ID=123456
+AGENTS=claude,cursor
+```
+
+```bash
+# my-project/.env.aidev  — project-specific values override the global ones
+AIDEV_ENV_EXTEND=~/.aidev.global
+CLICKUP_TAG=my-project
+```
+
+**Priority order (highest → lowest):**
+
+1. Shell environment variables (e.g. set in `~/.zshrc`) — never overwritten
+2. Local `.env.aidev` values
+3. `AIDEV_ENV_EXTEND` file values (global base)
+
+`AIDEV_ENV_EXTEND` can be set in two ways:
+
+- **Per-project** — add `AIDEV_ENV_EXTEND=/path/to/file` inside `.env.aidev`
+- **Shell-wide** — `export AIDEV_ENV_EXTEND=~/.aidev.global` in `~/.zshrc` (applies to every project automatically)
+
+`aidev init` will ask for this path and pre-fill it if the variable is already in your shell environment.
+
+### ClickUp
+
+| Variable | Default | Description |
+|---|---|---|
+| `CLICKUP_API_KEY` | — | Personal API token — can be set as a shell env var |
+| `CLICKUP_TEAM_ID` | — | Workspace / team ID — can be set as a shell env var |
+| `CLICKUP_TAG` | — | Tasks with this tag will be picked up (set to `*` to match all tasks) |
+| `CLICKUP_PENDING_STATUS` | `pending` | Status name for "waiting for reply" |
+| `CLICKUP_IN_REVIEW_STATUS` | `review` | Status set after implementation |
+| `ASSIGNEE_TAG` | — | Only process tasks assigned to this user (optional) |
+| `THINKING_TAG` | — | Tasks with this tag are analyzed and broken into sub-tasks before execution (optional) |
+| `NON_CODE_TAG` | — | Tasks with this tag run without git branching (optional) |
+| `NON_CODE_CLICKUP_TEAM_ID` | same as `CLICKUP_TEAM_ID` | Different workspace for non-code tasks (optional) |
+
+> **Tip:** For ClickUp, API keys and tokens are intentionally omitted from `.env.aidev` if you leave them blank during `aidev init` — they will be read from your shell environment instead. For Jira, Linear, and Monday.com, the wizard requires these values; to use shell env vars, remove the entries from `.env.aidev` after init.
+
+> **Wildcard tag (`*`):** Set `CLICKUP_TAG=*` (or `JIRA_LABEL=*` / `LINEAR_LABEL=*` / `TRELLO_LABEL=*`) to match **all** tasks regardless of tags/labels. This is useful when the AI dev has its own dedicated user in the task provider and every task assigned to it should be processed.
+
+### Jira
+
+| Variable | Default | Description |
+|---|---|---|
+| `JIRA_BASE_URL` | — | Jira instance URL (e.g. `https://mycompany.atlassian.net`) |
+| `JIRA_EMAIL` | — | Email for Jira authentication |
+| `JIRA_API_TOKEN` | — | API token — generate from [Atlassian account settings](https://id.atlassian.com/manage-profile/security/api-tokens) |
+| `JIRA_PROJECT` | — | Project key (e.g. `PROJ`) |
+| `JIRA_LABEL` | — | Issues with this label will be picked up (set to `*` to match all issues) |
+| `JIRA_PENDING_STATUS` | `To Do` | Status name for "waiting for reply" |
+| `JIRA_IN_REVIEW_STATUS` | `In Review` | Status set after implementation |
+| `NON_CODE_JIRA_PROJECT` | same as `JIRA_PROJECT` | Different project for non-code tasks (optional) |
+
+### Linear
+
+Linear calls them "labels" — the same concept as `CLICKUP_TAG` / `JIRA_LABEL`. Tasks created via `aidev.tasks.json` with `tags` are mapped to Linear labels on the configured team, and missing labels are created automatically. Default status names align with Linear's standard workflow (`Backlog`, `Todo`, `In Progress`, `In Review`, `Done`); if your team renamed those states (e.g. `Triage` instead of `Backlog`), aidev also falls back to matching by Linear's underlying state type.
+
+| Variable | Default | Description |
+|---|---|---|
+| `LINEAR_API_KEY` | — | Personal API key from Linear Settings → API |
+| `LINEAR_TEAM_ID` | — | Team UUID from your workspace |
+| `LINEAR_LABEL` | — | Issues with this label will be picked up (set to `*` to match all issues) |
+| `LINEAR_PENDING_STATUS` | `Backlog` | Status name for "waiting for reply" |
+| `LINEAR_IN_REVIEW_STATUS` | `In Review` | Status set after implementation |
+| `NON_CODE_LINEAR_TEAM_ID` | same as `LINEAR_TEAM_ID` | Different team for non-code tasks (optional) |
+
+### Monday.com
+
+| Variable | Default | Description |
+|---|---|---|
+| `MONDAY_API_TOKEN` | — | API token from monday.com Developer settings |
+| `MONDAY_BOARD_ID` | — | Board ID (from the board URL) |
+| `MONDAY_STATUS_COLUMN_ID` | `status` | Column ID for the status field |
+| `MONDAY_GROUP_ID` | — | Group ID to filter items (optional) |
+
+### Notion
+
+| Variable | Default | Description |
+|---|---|---|
+| `NOTION_API_KEY` | — | Integration token from Notion → Settings → My integrations |
+| `NOTION_DATABASE_ID` | — | Database ID from the database URL (32-char hex) |
+| `NOTION_STATUS_PROPERTY` | `Status` | Name of the status property in the database |
+| `NOTION_PENDING_STATUS` | `pending` | Status value for "waiting for reply" |
+| `NOTION_IN_REVIEW_STATUS` | `review` | Status value set after implementation |
+
+### Trello
+
+| Variable | Default | Description |
+|---|---|---|
+| `TRELLO_API_KEY` | — | Developer API key from [trello.com/power-ups/admin](https://trello.com/power-ups/admin) |
+| `TRELLO_TOKEN` | — | Auth token generated via Trello's token flow |
+| `TRELLO_BOARD_ID` | — | Board ID from the board URL |
+| `TRELLO_LABEL` | — | Label name on cards to pick up (set to `*` to match all cards assigned to the token user) |
+| `TRELLO_OPEN_LIST` | `To Do` | List name for open/new cards |
+| `TRELLO_PENDING_LIST` | `Blocked` | List name for "waiting for reply" |
+| `TRELLO_IN_PROGRESS_LIST` | `Doing` | List name for cards being worked on |
+| `TRELLO_IN_REVIEW_LIST` | `In Review` | List name for completed cards awaiting review |
+| `TRELLO_OPEN_STATUS` | `open` | Semantic status mapped to the open list |
+| `TRELLO_PENDING_STATUS` | `pending` | Semantic status mapped to the pending list |
+| `TRELLO_IN_REVIEW_STATUS` | `review` | Semantic status mapped to the review list |
+
+### Git & GitHub
+
+| Variable | Default | Description |
+|---|---|---|
+| `GIT_REMOTE` | auto-detected | Remote name — detected via `git remote get-url origin` if unset |
+| `GITHUB_BASE_BRANCH` | `main` | Base branch; new task branches are cut from here |
+| `GITHUB_REPO` | — | `owner/repo` — used to generate PR links in comments |
+
+### Behaviour
+
+| Variable | Default | Description |
+|---|---|---|
+| `AIDEV_ENV_EXTEND` | — | Path to a global env file loaded as the base for this project (see above) |
+| `AGENTS` | `claude,cursor` | Comma-separated list of agents in priority order |
+| `DEV_NOTES_MODE` | `smart` | When to ask for clarification (`smart` or `always`) |
+| `AIDEV_TRIGGER_WORD` | `aidev-continue` | Comment containing this word re-triggers a skipped task |
+| `AIDEV_COMMENT_PREFIX` | `[aidev]` | Custom prefix for all aidev comments posted to task providers |
+| `AIDEV_HOOKS_PATH` | — | Path to a `.ts` or `.js` module that exports hook functions (see [Hooks](#hooks)) |
+| `ACCEPTED_TAG` | `accepted` | Tasks in review with this tag are auto-merged (see [Auto-merge accepted PRs](#auto-merge-accepted-prs)) |
+| `DONE_STATUS` | auto-detected | Status to set after auto-merging an accepted PR. When unset, aidev picks the first match of `done`, `closed`, `finish`, `success`, `prod` from the board's statuses |
+| `PR_SIGNATURE` | `Automated PR by aidev.` | Custom signature line appended to the PR body |
+| `AIDEV_AUTO_COMPRESS` | `true` | Auto-compress older comments when the prompt grows large. Set to `false` / `0` / `no` to opt out |
+| `AIDEV_COMPRESS_THRESHOLD` | `12000` | Char-length threshold that triggers compression |
+
+---
+
+## Hooks
+
+Set `AIDEV_HOOKS_PATH` in `.env.aidev` to a path relative to the project directory or an absolute path. `aidev init` writes `.aidev/aidev.hooks.ts` and sets `AIDEV_HOOKS_PATH=.aidev/aidev.hooks.ts` by default.
+
+The module should export an object (or `export default`) whose properties are optional async functions. Only known hook names are used; anything else is ignored. If a hook throws, the current operation stops (for example the whole run after `beforeRun`, or conflict resolution after `beforeResolveConflicts`). If a hook returns an object, it replaces the context for that step (for example append to `context.prompt` in `beforeEachTask` and return the updated context).
+
+**Hook names**
+
+| Hook | When | Context notes |
+|---|---|---|
+| `beforeRun` / `afterRun` | Start / end of `aidev run` | `afterRun` includes `processed` and `skipped` counts |
+| `beforeEachTask` / `afterEachTask` | Around each code task implementation | `prompt`, `branchName`, `task`; `afterEachTask` has `success` |
+| `beforeResolveConflicts` / `afterResolveConflicts` | Merge conflict resolution with AI | `conflictFiles`, `prompt`; `afterResolveConflicts` has `resolved` |
+| `beforeNonCodeTask` / `afterNonCodeTask` | Non-code tasks | `afterNonCodeTask` includes agent `output` |
+| `beforeThinkingTask` / `afterThinkingTask` | Thinking-tag tasks (subtask plan) | `beforeThinkingTask` may adjust `subtasks` before steps run |
+| `beforeReviewTask` / `afterReviewTask` | Review tasks with unresolved PR comments | `threads`, `prompt`, `branchName`; `afterReviewTask` has `success`, `resolvedCount` |
+
+**Second argument: `vm`**
+
+Each hook receives `(context, vm)`. The `vm` object exposes:
+
+- `runAI(prompt)` — runs the first available configured AI agent
+- `postComment(taskId, text)`, `updateStatus(taskId, status)`, `getComments(taskId)` — same family of operations as the task provider
+- `log.info` / `log.warn` / `log.error` — prefixed hook logging
+
+**TypeScript hooks**
+
+`.ts` hook files are loaded at runtime via [jiti](https://www.npmjs.com/package/jiti) — no TypeScript compiler or toolchain needed. Just write a plain `.ts` file with the hook functions and aidev handles the rest.
+
+---
+
+## AI agents
+
+aidev supports multiple AI agents with automatic fallback. The first available agent in the list is used; if it fails, the next one is tried with the previous agent's output as additional context.
+
+**Supported agents**
+
+| Agent | Requires |
+|---|---|
+| `antigravity` | Google **Antigravity** CLI (`agy` or `antigravity`) in PATH — see [Antigravity](https://antigravity.google/download) |
+| `claude` | [Claude CLI](https://github.com/anthropics/claude-code) installed and authenticated |
+| `cursor` | Cursor **Agent CLI** (`agent`) in PATH — see [Windows](#windows-cursor-agent-cli) below |
+| `windsurf` | [Windsurf](https://windsurf.com) installed with CLI available in PATH |
+
+### Windows: Cursor Agent CLI
+
+On Windows, the Cursor IDE (`cursor.exe`) is separate from the headless Agent CLI. The runner uses the `agent` binary. Install it in PowerShell:
+
+```powershell
+irm 'https://cursor.com/install?win32=true' | iex
+```
+
+Then ensure `agent` is on your PATH and run `agent --version` to confirm. Without this, the Cursor runner will report as unavailable.
+
+**Configure agent order in `.env.aidev`:**
+
+```bash
+# Claude first, fall back to Cursor
+AGENTS=claude,cursor
+
+# Cursor only
+AGENTS=cursor
+
+# Cursor first (useful when working locally with a monitor)
+AGENTS=cursor,claude
+
+# Claude first, then Windsurf, then Cursor
+AGENTS=claude,windsurf,cursor
+
+# Antigravity first, then Claude
+AGENTS=antigravity,claude
+
+# Windsurf only
+AGENTS=windsurf
+```
+
+---
+
+## Trigger word & re-processing
+
+aidev prefixes every comment it posts with `[aidev]` (configurable via `AIDEV_COMMENT_PREFIX`). This lets it distinguish its own comments from human replies when deciding whether to re-process a task.
+
+A task is normally skipped when:
+- A remote branch already exists for it, **or**
+- It is `pending` and no human has replied yet
+
+To force aidev to pick the task up again, post a comment containing the **trigger word** (default: `aidev-continue`). aidev will reuse the existing branch and continue implementation from where it left off.
+
+```bash
+# Customise the trigger word in .env.aidev
+AIDEV_TRIGGER_WORD=please-retry
+```
+
+The trigger word match is case-insensitive, so `aidev-continue`, `AIDEV-CONTINUE`, and `Aidev-Continue` all work.
+
+For pending tasks, a regular human reply (any comment without the configured prefix) also triggers re-processing — the trigger word is an additional explicit mechanism.
+
+```bash
+# Customise the comment prefix in .env.aidev
+AIDEV_COMMENT_PREFIX=[mybot]
+```
+
+---
+
+## Auto-compress
+
+For long-running tasks with many comments, the combined prompt (description + conversation history + review threads) can grow past the AI agent's effective context window. When the assembled context exceeds `AIDEV_COMPRESS_THRESHOLD` characters (default `12000`), aidev summarises the older comments via the configured AI agent and keeps only the **latest comment verbatim** — so the agent always sees the user's most recent intent without ambiguity.
+
+Compressed summaries are cached under `.aidev/sessions/<taskId>.json` and reused across runs; new comments invalidate the cache and trigger a re-summarisation of the delta. The directory is added to `.gitignore` automatically.
+
+This is **on by default**. To opt out:
+
+```bash
+# In .env.aidev
+AIDEV_AUTO_COMPRESS=false
+
+# Or raise the threshold instead of disabling
+AIDEV_COMPRESS_THRESHOLD=24000
+```
+
+---
+
+## Non-code tasks
+
+Tasks tagged with `NON_CODE_TAG` are executed **without git branching** — no checkout, commit, push, or PR creation. The AI agent runs the task directly in the current working directory.
+
+This is useful for:
+- Research or investigation tasks
+- Documentation updates that don't go through PR review
+- Running scripts or commands
+- Any task where you want the AI to act without creating a branch
+
+```bash
+# In .env.aidev
+NON_CODE_TAG=non-code
+
+# Optionally use a different ClickUp team for non-code tasks
+NON_CODE_CLICKUP_TEAM_ID=987654
+
+# Or a different Jira project
+NON_CODE_JIRA_PROJECT=OPS
+```
+
+Non-code tasks follow the same lifecycle as regular tasks (clarification → implementation → review), except the implementation step skips all git operations. After completion, the task status is moved to your configured "in review" status.
+
+If `NON_CODE_TAG` is not configured, non-code task processing is disabled entirely.
+
+---
+
+## Code review resolution
+
+When `aidev run` executes, it also checks tasks in **review** status for unresolved PR code review comments. If any actionable threads are found, an AI agent is run to address them — either by fixing the code or replying to discussion comments.
+
+**How it works:**
+
+1. Fetches all tasks in your configured "in review" status
+2. For each task, finds the associated PR by branch name (via `gh` CLI)
+3. Fetches unresolved review threads from the PR
+4. Filters out threads where the last comment is from aidev itself (to avoid re-processing)
+5. Runs an AI agent to address the remaining threads — code fixes are committed and pushed, discussion replies are posted directly on the thread
+6. Resolved threads are marked as resolved on GitHub
+
+This runs automatically as part of every `aidev run` (after processing open/pending tasks). No additional configuration is needed beyond having `gh` CLI installed and authenticated.
+
+> **Prerequisites:** The [GitHub CLI](https://cli.github.com/) must be installed and authenticated (`gh auth login`). If `gh` is not available, review task processing is silently skipped.
+
+---
+
+## Auto-merge accepted PRs
+
+When a task has been reviewed and is ready to merge, tag it with `accepted` (the default — override via `ACCEPTED_TAG`). On the next run, aidev will automatically merge the PR via the GitHub CLI (`gh`), update the task status, and sync your local main branch.
+
+This feature works out of the box whenever the `gh` CLI is installed and authenticated.
+
+```bash
+# In .env.aidev (both optional)
+# ACCEPTED_TAG=accepted   # the tag aidev looks for on review tasks (default: accepted)
+# DONE_STATUS=done        # status to apply after merge — auto-detected when omitted
+```
+
+**How it works:**
+
+1. Finds all tasks in your "in review" status that have the accepted tag (`accepted` by default)
+2. For each task: merges the PR with squash and deletes the remote branch (`gh pr merge --squash --delete-branch`)
+3. Updates the task status to `DONE_STATUS`. When unset, aidev probes the board for one of `done`, `closed`, `finish`, `success`, `prod` and uses the first match
+4. Checks out the base branch and pulls the latest changes
+
+**Run it manually:**
+
+```bash
+aidev run accepted
+```
+
+**Automatic mode:** Whenever `gh` is available, accepted PRs are also auto-merged at the end of every `aidev run`.
+
+> **Prerequisites:** The [GitHub CLI](https://cli.github.com/) must be installed and authenticated (`gh auth login`). `aidev init` will prompt you for these settings if it detects `gh` on your PATH.
+
+---
+
+## Dev notes mode
+
+Controls when aidev asks the task provider for clarification before implementing.
+
+| Mode | Behaviour |
+|---|---|
+| `smart` | Asks the AI whether the task description is clear enough. Only posts a clarification question if it's ambiguous. |
+| `always` | Always posts "any dev notes?" before implementing every task. |
+
+When a question is posted, the task is moved to the configured pending status (e.g. `CLICKUP_PENDING_STATUS`, `JIRA_PENDING_STATUS`, etc.). On the next run, aidev checks whether a human has replied and, if so, includes the reply as context for the AI.
+
+---
+
+## Local tasks file (`aidev.tasks.json`)
+
+`aidev.tasks.json` is an **outbound queue** — a JSON file that sits at the root of your project and holds task templates that aidev will publish to your configured provider (ClickUp, Jira, Linear, etc.). It is the opposite direction from the [Local provider](#local-provider): the local provider **stores** tasks on disk, while `aidev.tasks.json` **pushes** tasks to a remote provider.
+
+Typical uses:
+
+- **Recurring tasks** — with a `cron` expression, an entry publishes a fresh task on every matching tick (daily standup reminders, weekly reviews, monthly housekeeping).
+- **Staged work** — queue a batch of tasks in a commit so they appear in the provider together when `aidev` next runs.
+- **AI-authored tasks** — another AI agent or script can append entries to the file; `aidev` will pick them up and create real tickets.
+
+The file is added to `.gitignore` by `aidev init` — each developer or automation environment maintains their own queue.
+
+### File format
+
+`aidev.tasks.json` is a JSON array of task entries. Each entry has the shape:
+
+```ts
+interface LocalTask {
+  id: string;              // UUID — generated automatically by "aidev tasks add"
+  title: string;           // required — task title on the remote provider
+  description: string;     // task body / description
+  type: 'code' | 'non-code'; // routes to the non-code provider when set to 'non-code'
+  priority?: number;       // 1=urgent, 2=high, 3=normal, 4=low
+  assignee?: string;       // currently informational (reserved for future use)
+  dueDate?: string;        // ISO date, e.g. "2026-05-01"
+  tags?: string[];         // extra tags appended to the provider-configured tag
+  listId?: string;         // override provider list / project ID for this task only
+  cron?: string;           // 5-field cron — if set, the task is re-published on every tick
+  lastPushedAt?: number;   // epoch ms of the last successful push (managed by aidev for cron entries)
+}
+```
+
+**Example** (`aidev.tasks.json`):
+
+```json
+[
+  {
+    "id": "7f3a9c2d-5b1e-4a6f-9d8c-1e2f3a4b5c6d",
+    "title": "Daily standup notes",
+    "description": "Post yesterday / today / blockers to the team channel.",
+    "type": "non-code",
+    "priority": 3,
+    "tags": ["standup"],
+    "cron": "0 9 * * 1-5"
+  },
+  {
+    "id": "2b8e1f7a-4c9d-4e5a-8b6c-9f1e2d3c4b5a",
+    "title": "Upgrade dependencies",
+    "description": "Run `npm outdated`, bump minor/patch versions, verify tests pass.",
+    "type": "code",
+    "priority": 2,
+    "tags": ["maintenance"]
+  }
+]
+```
+
+### Lifecycle
+
+1. **Every `aidev run`** (regardless of filter) begins by reading `aidev.tasks.json` and attempting to publish each entry via the configured provider's `createTask` API.
+2. **One-shot entries** (no `cron` field) are **removed from the file** after a successful push — they become a real ticket and won't be duplicated on the next run.
+3. **Cron entries** remain in the file. `lastPushedAt` is updated on each successful push; on the next run, aidev checks whether the cron has fired at least once since `lastPushedAt` before republishing. A fresh entry with a cron fires on the first run that matches.
+4. **Failures** are logged and the entry is kept — the next run retries.
+
+### Routing
+
+- `type: 'code'` → published with the code tag (`CLICKUP_TAG` / `JIRA_LABEL` / `LINEAR_LABEL`, etc.) to the primary provider.
+- `type: 'non-code'` → published with `NON_CODE_TAG` to the non-code provider (a separate team / project if `NON_CODE_CLICKUP_TEAM_ID`, `NON_CODE_JIRA_PROJECT`, or `NON_CODE_LINEAR_TEAM_ID` is configured, otherwise the primary).
+- Per-task `tags` are appended to the resolved default tag.
+- Per-task `listId` overrides the provider-default list / project for that single task.
+
+### Managing entries
+
+Use the built-in commands rather than hand-editing JSON (although hand-editing is fine — the file is plain JSON):
+
+```bash
+aidev tasks add              # interactive prompt: title, description, type, priority, due date, tags, list, cron
+aidev tasks ls               # table of queued entries
+aidev tasks update [id]      # edit an entry by table ID (interactive picker if no id)
+aidev tasks remove [id]      # delete an entry by table ID (interactive picker if no id)
+aidev tasks push             # publish everything now (same as "aidev run tasks") — useful for dry-running or in scripts
+```
+
+`aidev tasks push` and `aidev run tasks` do the same thing: they only process `aidev.tasks.json` and exit without pulling tasks from the provider or invoking the AI. This is useful when you want to decouple queue publishing from the main AI loop — for example, running `aidev tasks push` from a separate cron entry or CI job.
+
+---
+
+## Scheduling
+
+aidev can run on a cron schedule, one entry per project directory.
+
+```bash
+# Interactive picker
+aidev schedule set
+
+# Or pass an expression directly
+aidev schedule set "*/15 * * * *"
+
+# Run a schedule against a custom env file (so the scheduled run uses
+# that config — useful when several env files live alongside one repo)
+aidev schedule set "*/15 * * * *" -e /path/to/custom/.env.aidev
+
+# Check what's scheduled for the current directory
+aidev schedule get
+```
+
+The `-e <path>` option is baked into the scheduled entry itself (the cron
+line on Linux, the LaunchAgent plist on macOS, or the Task Scheduler `/tr`
+command on Windows), so each run will pick up the right env file without
+relying on the shell environment at firing time.
+
+**Preset options (interactive picker)**
+
+| Option | Expression |
+|---|---|
+| Every 15 minutes | `*/15 * * * *` |
+| Every 30 minutes | `*/30 * * * *` |
+| Every hour | `0 * * * *` |
+| Every 5 hours | `0 */5 * * *` |
+| Every day at 8am | `0 8 * * *` |
+
+Each directory gets its own cron entry identified by a `# aidev-cwd:/path` marker — running `schedule set` again replaces the existing entry rather than adding a duplicate.
+
+### macOS: Full Disk Access required
+
+On macOS (Ventura and later), cron jobs are silently blocked unless `/usr/sbin/cron` has Full Disk Access:
+
+1. Open **System Settings → Privacy & Security → Full Disk Access**
+2. Click **+** and add `/usr/sbin/cron`
+3. Re-run `aidev schedule set` to apply your schedule
+
+Without this, cron will appear to be configured but jobs will never fire.
+
+---
+
+## Logging
+
+Every run appends to `aidev.log` in your project directory:
+
+```
+────────────────────────────────────────────────────────────
+2026-03-06T08:00:00.000Z [run] started
+────────────────────────────────────────────────────────────
+2026-03-06T08:00:00.120Z [info] Fetching tasks (filter: all)...
+2026-03-06T08:00:01.340Z [task] [abc123] "Fix login flow" (status: open)
+2026-03-06T08:00:12.780Z [info] Running claude...
+2026-03-06T08:00:45.210Z [success] Task implemented: branch abc123/fix-login-flow pushed
+2026-03-06T08:00:45.890Z [success] Done. Processed: 1, Skipped: 3
+```
+
+ANSI colour codes are stripped so the file stays readable in any editor or `tail -f`. `aidev.log` is added to `.gitignore` automatically by `aidev init`.
+
+To write the log somewhere else, set `AIDEV_LOG_PATH` to an absolute, relative, or `~/`-prefixed path that includes the **file name** (not just the folder). Relative paths are resolved against the project cwd and missing parent directories are created on first write.
+
+```bash
+AIDEV_LOG_PATH=logs/aidev.log         # → <cwd>/logs/aidev.log
+AIDEV_LOG_PATH=/var/log/aidev.log     # absolute
+AIDEV_LOG_PATH=~/aidev/run.log        # under your home directory
+```
+
+---
+
+## Providers
+
+| Provider | Status | `aidev init` support |
+|---|---|---|
+| ClickUp | ✅ Implemented | ✅ Interactive wizard |
+| Jira | ✅ Implemented | ✅ Interactive wizard |
+| Linear | ✅ Implemented | ✅ Interactive wizard |
+| Monday.com | ✅ Implemented | ✅ Interactive wizard |
+| Local | ✅ Implemented | ✅ Interactive wizard |
+| Notion | ✅ Implemented | Manual `.env.aidev` config |
+| Trello | ✅ Implemented | ✅ Interactive wizard |
+
+> **Notion:** This provider is fully functional but not yet included in the `aidev init` wizard. To use it, set `PROVIDER=notion` in `.env.aidev` and fill in the required variables from the [Configuration](#configuration) section above.
+
+The `TaskProvider` interface makes it straightforward to add new providers. See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+### Local provider
+
+Set `PROVIDER=local` in `.env.aidev` to manage tasks entirely via local markdown files — no external API needed.
+
+```bash
+aidev init   # choose "local" when prompted for provider
+```
+
+Tasks live in `.aidev/tasks/` under status folders:
+
+```
+.aidev/tasks/
+  open/          # new tasks ready for implementation
+  pending/       # waiting for human reply
+  progress/      # currently being implemented
+  review/        # implementation complete, awaiting review
+  done/          # finished
+```
+
+**Task file format** (e.g. `.aidev/tasks/open/a1b2c3d4-fix-login-bug.md`):
+
+```markdown
+---
+title: Fix login page bug
+priority: 2
+assignee: david
+estimated: 2h
+tags: frontend, auth
+created: 2026-03-12T10:00:00.000Z
+---
+
+The login form should redirect users to the dashboard after successful authentication.
+```
+
+The filename must start with a short ID (hex characters) followed by a dash and a slug. The YAML frontmatter carries task metadata; everything after `---` is the task description.
+
+#### Code vs non-code tasks
+
+By default, local tasks are treated as **code tasks** — aidev creates a git branch, runs the AI agent, commits, pushes, and opens a PR.
+
+To mark a task as **non-code** (research, docs, investigation — no git branching), add `type: non-code` to the frontmatter:
+
+```markdown
+---
+title: Compare OAuth2 providers
+type: non-code
+tags: research
+---
+
+Evaluate Auth0, Clerk, and Supabase Auth. Write a recommendation.
+```
+
+Non-code tasks follow the same lifecycle but skip all git operations. The AI response is posted as a session comment instead of a PR.
+
+**Session file** (comments) — `.aidev/tasks/open/a1b2c3d4-fix-login-bug.session.md`:
+
+```markdown
+<!-- aidev session log — append your comments below using "## your-name" as header -->
+
+---
+
+## aidev — 2026-03-12T10:05:00.000Z
+
+[aidev] Starting implementation on branch `a1b2c3d4/fix-login-bug`
+
+---
+
+## david — 2026-03-12T10:10:00.000Z
+
+Please use the new auth API endpoint for this.
+```
+
+To add a comment, append a `---` separator followed by a `## your-name` header and your message. aidev parses these entries automatically and uses them as conversation context, just like ClickUp/Jira comments.
+
+Downloaded task attachments are stored in `.aidev/assets/<task-id>/`, and `aidev init` adds `.aidev/assets/` to `.gitignore` automatically.
+
+---
+
+## Contributing
+
+Contributions are welcome — new providers, new AI runners, bug fixes, and docs improvements.
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full guide.
+
+---
+
+## License
+
+[MIT](./LICENSE)