AGINEAR

# AGINEAR Markdown-native project management. `todo.md` and `roadmap.md` are the single source of truth. CLI, Web GUI, and MCP server — all powered by a lossless markdown engine. ## Quick Start ```bash npx aginear init # Creates todo.md, roadmap.md, .devplan/config.json npx aginear list # View tasks npx aginear serve # Launch web GUI at http://localhost:4040 ``` ## Setup Requires Node.js >= 18. ```bash cd your-repo npx aginear init ``` This creates: ``` your-repo/ ├── todo.md # Your tasks (editable by hand or via CLI/GUI) ├── roadmap.md # Your milestones ├── .devplan/ │ └── config.json # Per-repo configuration └── .gitignore # .devplan/ entry appended automatically ``` Both markdown files are yours to edit directly — AGINEAR preserves every byte of formatting you add (blank lines, prose, comments). ### Install Globally (optional) ```bash npm install -g aginear ``` --- ## Markdown Format ### todo.md ```markdown # My Project ## Backlog - [ ] Set up database @aditya #backend !high ^2025-06-01 - [ ] Write API docs #docs ## In Progress - [ ] Build auth flow @aditya #backend !critical - [x] Design token schema - [ ] Implement JWT validation - [ ] Add RS256 support - [ ] Write auth middleware Notes about the auth flow. ## Done - [x] Initialize repo ``` **Sections** are `##` headings — they become Kanban columns in the GUI. **Tasks** are `- [ ]` (incomplete) or `- [x]` (complete) list items. **Subtasks** are indented 2 spaces under their parent. Up to 3 levels deep. **Notes** are indented plain text under a task (not a list item). **Inline metadata** can appear anywhere in the task title: | Token | Meaning | Example | |---|---|---| | `@name` | Assignee | `@aditya` | | `#tag` | Tag (multiple allowed) | `#backend #api` | | `!priority` | Priority | `!critical`, `!high`, `!medium`, `!low` | | `^YYYY-MM-DD` | Due date | `^2025-06-01` | ### roadmap.md ```markdown # Product Roadmap ## MVP Launch status: in-progress progress: 60% Core features for initial release. - [x] User authentication - [x] Basic CRUD - [ ] Payment integration ## V2 Features status: planned - [ ] Analytics dashboard - [ ] Export to CSV ``` **Milestones** are `##` headings. **Metadata** are `key: value` lines directly under the heading: - `status:` — `planned`, `in-progress`, `completed`, `blocked` - `progress:` — `0%` to `100%` **Description** is any prose text between the metadata and the task items. --- ## CLI Reference ### Task Management ```bash # List all tasks aginear list aginear list --section "In Progress" aginear list --tag backend aginear list --assignee aditya # Add a task aginear add "Implement search" aginear add "Build dashboard" --section "In Progress" --assign aditya --priority high --tag frontend --tag ui --due 2025-06-01 # Mark complete / uncomplete aginear done "search" # Fuzzy matches title aginear done 3 # By displayed list number aginear done 0e0023 # By ID prefix (shown in list output) # Move between sections aginear move "search" --to "In Progress" # Edit properties aginear edit "search" --title "New title" --assign bob --priority medium --due 2025-07-01 # Remove aginear remove "search" ``` ### Task Identification All commands that take a `<query>` argument resolve tasks with this strategy: 1. **Numeric** — matches by position in the displayed list (`aginear done 3`) 2. **6-8 hex chars** — matches by task ID prefix (`aginear done 0e0023`) 3. **Otherwise** — case-insensitive substring match on task titles (`aginear done "auth flow"`) If multiple tasks match, you'll see a disambiguation list. ### Roadmap Management ```bash # View roadmap aginear roadmap # Add milestone aginear roadmap add "V3 Features" --status planned # Update milestone aginear roadmap update "MVP" --status completed --progress 100 ``` ### Web GUI ```bash aginear serve # http://localhost:4040 aginear serve --port 8080 # Custom port ``` Features: - Kanban board with drag-and-drop between columns - Click any task to edit title, assignee, priority, tags, due date - Toggle task completion via checkbox - Roadmap timeline view with progress bars and status badges - Live updates via WebSocket when files change on disk ### Initialize ```bash aginear init ``` Creates `todo.md`, `roadmap.md`, and `.devplan/config.json` with defaults. Skips any file that already exists. Appends `.devplan/` to `.gitignore`. --- ## MCP Server AGINEAR includes an MCP server so AI coding agents (Claude Desktop, Cursor, Claude Code, etc.) can read and modify your project tasks. ### Setup for Claude Desktop Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`): ```json { "mcpServers": { "aginear": { "command": "npx", "args": ["aginear", "mcp"], "cwd": "/absolute/path/to/your/repo" } } } ``` ### Setup for Cursor Add to `.cursor/mcp.json` in your project: ```json { "mcpServers": { "aginear": { "command": "npx", "args": ["aginear", "mcp", "--cwd", "."] } } } ``` ### Setup for Claude Code Add to `.claude/settings.json` in your project: ```json { "mcpServers": { "aginear": { "command": "npx", "args": ["aginear", "mcp", "--cwd", "."] } } } ``` ### Available Tools | Tool | Description | Input | |---|---|---| | `get_todos` | Get all tasks, optionally filtered | `{ section?, tag?, assignee?, priority? }` | | `add_task` | Add a new task | `{ title, section?, assignee?, tags?, priority?, due? }` | | `update_task` | Update an existing task | `{ search, updates: { title?, assignee?, priority?, tags?, due?, completed? } }` | | `move_task` | Move task to a different section | `{ search, to_section }` | | `complete_task` | Mark a task as complete | `{ search }` | | `remove_task` | Remove a task | `{ search }` | | `get_roadmap` | Get the full roadmap | `{}` | | `update_milestone` | Update milestone status/progress | `{ search, status?, progress? }` | The `search` parameter matches by ID prefix or case-insensitive title substring. --- ## Configuration `.devplan/config.json` is optional. AGINEAR uses sensible defaults if it's missing. ```json { "files": { "todo": "./todo.md", "roadmap": "./roadmap.md" }, "gui": { "port": 4040 }, "columns": ["Backlog", "In Progress", "Review", "Done"], "tags": {} } ``` | Key | Default | Description | |---|---|---| | `files.todo` | `./todo.md` | Path to the todo file (relative to config dir) | | `files.roadmap` | `./roadmap.md` | Path to the roadmap file (relative to config dir) | | `gui.port` | `4040` | Port for the web GUI | | `columns` | `["Backlog", "In Progress", "Review", "Done"]` | Kanban column names | | `tags` | `{}` | Tag name to hex color mapping | Config is resolved by walking up from `cwd` looking for `.devplan/config.json` (like `.git`). File paths in the config are resolved relative to the directory containing `.devplan/`. --- ## REST API When running `aginear serve`, these endpoints are available: ### Todos | Method | Endpoint | Body | Description | |---|---|---|---| | `GET` | `/api/todos` | -- | Full todo document as JSON | | `POST` | `/api/todos/tasks` | `{ title, section?, assignee?, tags?, priority?, due? }` | Add task | | `PATCH` | `/api/todos/tasks/:id` | `{ title?, assignee?, tags?, priority?, dueDate?, completed? }` | Update task | | `DELETE` | `/api/todos/tasks/:id` | -- | Remove task | | `POST` | `/api/todos/tasks/:id/move` | `{ section, position? }` | Move task | | `POST` | `/api/todos/tasks/:id/complete` | -- | Toggle completion | ### Roadmap | Method | Endpoint | Body | Description | |---|---|---|---| | `GET` | `/api/roadmap` | -- | Full roadmap document as JSON | | `PATCH` | `/api/roadmap/milestones/:id` | `{ status?, progress? }` | Update milestone | ### WebSocket Connect to `ws://localhost:4040` (same port). The server broadcasts these messages when files change on disk: ```json { "type": "todos_updated", "data": { "title": "...", "sections": [...] } } { "type": "roadmap_updated", "data": { "title": "...", "milestones": [...] } } ``` --- ## Development ```bash git clone https://github.com/Legorobotdude/AGINEAR.git cd AGINEAR pnpm install pnpm -r build pnpm -r test # 89 tests across core + mcp ``` ### Project Structure ``` packages/ core/ # Shared CST parser, mutator, serializer (lossless round-tripping) cli/ # CLI commands (commander + chalk) mcp/ # MCP server (@modelcontextprotocol/sdk, stdio transport) web/ # Express server + React SPA (Vite + Tailwind + @dnd-kit) ``` ### Publishing a New Version 1. Bump the version in two places: - `publish-package.json` — the `"version"` field (this is what npm sees) - `packages/cli/src/index.ts` — the `.version()` call in Commander (this is what `aginear --version` prints) 2. Build, pack, and verify: ```bash pnpm run publish:build pnpm run publish:pack # creates aginear-<version>.tgz in repo root ``` 3. Publish: ```bash cd dist && npm publish --access public ``` The `publish:build` script does the following: - Builds all workspace packages (`pnpm -r build`) - Bundles `cli`, `mcp`, and `server` entry points into `dist/` via tsup, inlining `@devplan/*` workspace deps while keeping third-party deps external - Copies the web client assets, `publish-package.json`, README, and LICENSE into `dist/` - Prepends the Node shebang to `dist/cli.js` ### Key Design Decisions - **No markdown AST library** -- Custom line-by-line CST parser that preserves every byte. `serialize(parse(input)) === input`. - **No state outside markdown files** -- The `.md` files are the database. Config is for preferences only. - **Tiny install** -- Everything bundles into ~94 KB (gzipped) via tsup/Vite with third-party deps installed by npm. ## License MIT