186 lines
5.4 KiB
Markdown
186 lines
5.4 KiB
Markdown
# 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/tags/assignee actions
|
|
- **Project tags** — catalog in task folder `config.yml`
|
|
- **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.
|
|
|
|
### Project config (`config.yml` in the task folder)
|
|
|
|
Default layout:
|
|
|
|
```text
|
|
.xflow/
|
|
config.yml # project tags catalog
|
|
fix-login.xflow.md
|
|
```
|
|
|
|
```yaml
|
|
# .xflow/config.yml
|
|
tags:
|
|
- bug
|
|
- frontend
|
|
```
|
|
|
|
If `config.yml` exists, tags on a task that are **not** in the catalog show as
|
|
warnings. Hover `tags` → **Edit tags…** / **Add tag to project**.
|
|
|
|
## 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`).
|