# XBOCTuK Flow

Local-first task management for solo developers and small teams — a VS Code
extension.

Tasks are plain Markdown files with YAML frontmatter (extension `.xflow.md`). No
cloud, no server: git-friendly, editable in any editor.

[Русская версия](README_ru.md)

## Features

- **Sidebar** — Project / Global → status → tasks
- **Dashboard** — task list + description (filters, scope, sort, group)
- **Kanban** — status columns, drag-and-drop, create-in-column
- **Commands** — create / open / change status / delete
- **In-editor** — frontmatter lint + status/priority Quick Pick (decorations)
- **Two stores** — project folder (workspace) and global folder (shared on the
  machine)

### Statuses

`backlog` · `todo` · `in-progress` · `done` · `cancelled`

On the Kanban board, `backlog` and `cancelled` are hidden by default (use **Show
hidden**).

### Priorities

`critical` · `high` · `medium` · `low`

## Requirements

- VS Code **^1.96.0**
- Node.js 20+ (for development)

## Development install

```bash
npm install
npm run build
```

1. Open the extension folder in VS Code
2. Press **F5** — Extension Development Host
3. In the Host window, open a workspace where you want tasks

The extension is **not** on the Marketplace yet — use dev host or a local
`.vsix` (below).

### Local `.vsix` (optional)

```bash
npm run build
npx @vscode/vsce package
```

Install: Extensions → `...` → Install from VSIX.

## Settings

Settings → **XBOCTuK Flow** (or `settings.json`). Defaults live in
`package.json` (`contributes.configuration`).

| Setting                   | Description                                         | Default  |
| ------------------------- | --------------------------------------------------- | -------- |
| `xboctukFlow.projectPath` | Project tasks folder **relative** to workspace root | `.xflow` |
| `xboctukFlow.globalPath`  | **Absolute** path to global tasks (empty = off)     | `""`     |

Task files always use the extension **`.xflow.md`**.

Example:

```json
{
  "xboctukFlow.projectPath": ".xflow",
  "xboctukFlow.globalPath": "C:\\Users\\You\\Documents\\xboctuk-flow"
}
```

## Commands

Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`):

| Command                                   | Action                                           |
| ----------------------------------------- | ------------------------------------------------ |
| **XBOCTuK Flow: Create Task**             | Create a task (scope pick if both paths are set) |
| **XBOCTuK Flow: Open Task**               | Open the task file in the editor                 |
| **XBOCTuK Flow: Change Status**           | Change status                                    |
| **XBOCTuK Flow: Edit Status (in file)**   | Frontmatter status via Quick Pick                |
| **XBOCTuK Flow: Edit Priority (in file)** | Frontmatter priority via Quick Pick              |
| **XBOCTuK Flow: Delete Task**             | Delete task                                      |
| **XBOCTuK Flow: Open Dashboard**          | Dashboard (list + body)                          |
| **XBOCTuK Flow: Open in Dashboard**       | Dashboard with the selected task                 |
| **XBOCTuK Flow: Open Kanban**             | Kanban board                                     |

Sidebar: title buttons (create / dashboard / kanban) and item actions (open /
edit / status / delete).

Status bar: **Tasks** → Dashboard.

## Task file format

```markdown
---
id: "550e8400-e29b-41d4-a716-446655440000"
title: "Fix login bug"
status: todo
priority: high
tags: [bug, frontend]
assignee: ""
created: 2026-07-12T10:00:00.000Z
updated: 2026-07-12T10:00:00.000Z
---

Task description in markdown…
```

One file per task (`*.xflow.md`). File name is derived from the title (slug).
`title` max length: 80 characters.

## Dashboard

- Search title/body; status/priority chips; group none/status/priority
- Scope: All / Project / Global
- Sort by **created**: Oldest first (default) / Newest first
- View-only detail; **Edit** opens the task file in the editor
- `+ Task` — create

## Kanban

- Columns by status; drag-and-drop updates status
- Scope filter; Show hidden (backlog/cancelled)
- `+` on a column — create with that status

## Development

```bash
npm run build       # bundle extension → out/extension.js (Vite)
npm run watch       # watch build
npm run test        # Vitest (watch)
npm run test:run    # Vitest single run
npm run check       # tsc app + tests
npm run lint        # ESLint
npm run format      # Prettier
```

### Architecture (short)

- **use-cases** (`src/commands/`) — no vscode; `Result` / `ResultAsync`
  (neverthrow)
- **ports** + storage adapters (`FsTaskRepository`, `NodeFileSystem`,
  `VscodeConfigProvider`)
- **UI** (`src/ui/`, `src/views/`) — thin vscode adapters, WebView hosts
- **settings defaults** — from `package.json`; code reads them via
  `src/config.ts`

Plan details: [`docs/PLAN.md`](docs/PLAN.md).  
Small backlog: [`todo.md`](todo.md).  
Russian README: [`README_ru.md`](README_ru.md).

## License

MIT (see `package.json`).