feinai 0.5.0 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +99 -161
  2. package/package.json +1 -1
  3. package/skills/feinai-dispatch/SKILL.md +32 -0
  4. package/src/cli.ts +1 -1
package/README.md CHANGED
@@ -1,230 +1,168 @@
1
- # tasca — run agents in parallel. know exactly what each one is doing.
1
+ # feinai — coordination layer for multi-agent teams
2
2
 
3
- Working with AI agents on complex features is powerful — until the coordination overhead swallows the productivity. I was using markdown files (`QUEUE.md`, `SPECS-QUEUE.md`, plan checklists) to track specs and tasks across sessions. The files grew without bound. Agents had to read the whole thing to extract a handful of lines. Context windows filled with stale state. Keeping files current after each task required discipline I didn't always have, and the more agents worked in parallel, the more likely a file was to be inconsistent.
3
+ Working with AI agents on complex features is powerful — until the coordination overhead swallows the productivity. **feinai** is a task & spec manager built for multi-agent workflows: specs, plans, tasks, worktree isolation, and a live orchestration dashboard.
4
4
 
5
- So I built **tasca**: a dual-interface tool (CLI + HTTP API) that serves both humans and agents. Agents claim tasks atomically, get exactly the context they need, and report results — all in single calls. Humans watch a live dashboard that shows which tasks exist, who's working on them, which files are being touched, and what the final outcome was. The underlying state lives in a local SQLite file and never leaves your machine.
6
-
7
- It ships with a set of skills — `tasca-sdd`, `tasca-write-spec`, `tasca-write-tasks`, `tasca-dispatch` — that replace the markdown-file side-effects of the SDD workflow with atomic CLI calls. The skills are drop-in replacements: if a project has `.tasca/tasca.db`, Claude uses tasca; otherwise it falls back to regular superpowers markdown flow.
5
+ Agents claim tasks atomically, get exactly the context they need, and report results — all in single CLI calls. Humans watch a live dashboard showing which tasks exist, who's working on them, which files are being touched, and what the outcome was. State lives in a local SQLite file and never leaves your machine.
8
6
 
9
7
  ```bash
10
- tasca take TASK-121-A
8
+ feinai take TASK-121-A
11
9
  # → {id, subject, description, workplan, packages, quality_gates, worktree, ...}
12
10
  # One call. Everything the agent needs to start.
13
11
  ```
14
12
 
15
- ## Why tasca
13
+ ## Install
16
14
 
17
- - **Atomic commands** — `take` returns the full task payload (subject + description + workplan + quality gates) in a single response.
18
- - **Concurrency-safe** — `take` is an atomic SQL UPDATE; two agents can't claim the same task.
19
- - **Queryable** — filter by status, owner, spec without parsing markdown.
20
- - **Auditable** — every operation is logged in an append-only events table.
21
- - **Local-first** — SQLite file at `.tasca/tasks.db`, no server, no cloud.
15
+ Requires [Bun](https://bun.sh) 1.3+.
22
16
 
23
- ## Status
17
+ ```bash
18
+ bun install -g feinai
19
+ ```
24
20
 
25
- Alpha. Built for use in real SDD workflows; API may change before 1.0.
21
+ This installs two binaries: `feinai` and `opengit` (safe git wrapper for parallel worktree workflows).
26
22
 
27
- ## Install
23
+ ### PATH setup
28
24
 
29
- Requires [Bun](https://bun.sh) 1.3+.
25
+ Bun installs global binaries to `~/.bun/bin`. This directory is added to PATH in interactive terminals automatically. No extra steps needed for:
26
+ - Interactive terminal sessions
27
+ - Local AI agents (Claude Code, opencode running locally)
28
+
29
+ **Non-interactive SSH sessions only** (e.g. `ssh host 'feinai status'`) require `~/.bun/bin` to be on PATH. Fix with a one-time symlink (requires sudo):
30
30
 
31
31
  ```bash
32
- # From source (recommended during alpha)
33
- git clone https://github.com/mvisca/tasca
34
- cd tasca
35
- bun install
36
- bun link # registers `tasca` as global command
32
+ sudo ln -sf ~/.bun/bin/feinai /usr/local/bin/feinai
33
+ sudo ln -sf ~/.bun/bin/opengit /usr/local/bin/opengit
34
+ sudo ln -sf ~/.bun/bin/bun /usr/local/bin/bun
37
35
  ```
38
36
 
39
- ### Activate the Claude Code skills
37
+ Or use a login shell: `ssh host 'bash -lc "feinai status"'`
40
38
 
41
- `tasca` ships four Claude Code skills that replace the markdown-file SDD workflow end to end. Link them into your global skills directory:
39
+ ### Activate Claude Code skills
42
40
 
43
41
  ```bash
44
42
  mkdir -p ~/.claude/skills
45
- ln -sfn "$(pwd)/skills/tasca-sdd" ~/.claude/skills/tasca-sdd
46
- ln -sfn "$(pwd)/skills/tasca-write-spec" ~/.claude/skills/tasca-write-spec
47
- ln -sfn "$(pwd)/skills/tasca-write-tasks" ~/.claude/skills/tasca-write-tasks
48
- ln -sfn "$(pwd)/skills/tasca-dispatch" ~/.claude/skills/tasca-dispatch
43
+ SKILLS="$(bun pm bin -g)/../lib/node_modules/feinai/skills"
44
+ for skill in feinai-sdd feinai-write-spec feinai-write-tasks feinai-dispatch feinai-implement; do
45
+ ln -sf "$SKILLS/$skill" ~/.claude/skills/$skill
46
+ done
49
47
  ```
50
48
 
51
49
  Skills activate automatically in projects that have `.tasca/tasca.db`.
52
50
 
53
- Future install paths (post-alpha):
54
- - `npm install -g tasca` (with Bun installed)
55
- - Pre-compiled binaries from GitHub Releases (with checksums)
56
- - Claude Code marketplace plugin (bundles CLI + skills)
57
-
58
51
  ## Quick start
59
52
 
60
53
  ```bash
61
- # 1. Initialize a tasca DB in your project
54
+ # 1. Initialize feinai in your project
62
55
  cd my-project
63
- tasca init
64
- # → Creates .tasca/tasca.db
56
+ feinai init
57
+ # → Creates .tasca/tasca.db (auto-added to .gitignore)
65
58
 
66
- # 2. Register a spec with its markdown content (typically done by brainstorming skill)
67
- tasca spec add SPEC-001 "User authentication" \
68
- --file specs/001-auth/spec.md
69
- # OR via stdin:
70
- cat specs/001-auth/spec.md | tasca spec add SPEC-001 "User authentication" --stdin
59
+ # 2. Add a spec
60
+ feinai spec add SPEC-001 "User authentication" --content "## Goal\nAdd JWT auth..."
71
61
 
72
- # 3. Register the implementation plan (typically done by writing-plans skill)
73
- cat plan.md | tasca plan add SPEC-001 --stdin
62
+ # 3. Add a plan
63
+ feinai plan add SPEC-001 --content "## Steps\n1. Schema\n2. Routes\n3. Tests"
74
64
 
75
- # 4. Add tasks (typically done by writing-plans skill)
76
- tasca add TASK-001-A "Create auth schema" \
65
+ # 4. Add tasks
66
+ feinai add TASK-001-A "Create auth schema" \
77
67
  --spec SPEC-001 \
78
- --desc "Define Drizzle schema for users table..." \
79
- --package "@app/auth" \
68
+ --desc "Define schema for users table..." \
80
69
  --gate "pnpm typecheck" \
81
70
  --gate "pnpm test -- --run"
82
71
 
83
- # 5. Agent takes the task (atomic — returns full task JSON in single call)
84
- tasca take TASK-001-A
85
- # Owner is auto-detected as "{parent_process}:{pid}:{username}"
86
- # Override via $TASCA_USER env var
72
+ # 5. Agent claims a task (atomic)
73
+ feinai take TASK-001-A
74
+ # Owner auto-detected as "{parent_process}:{pid}:{username}"
75
+ # Override via $FEINA_USER env var
87
76
 
88
77
  # 6. Agent marks done
89
- tasca done TASK-001-A --result "typecheck ✓ test ✓"
90
-
91
- # 7. Export content when needed
92
- tasca spec content SPEC-001 > /tmp/spec.md
93
- tasca plan show SPEC-001 > /tmp/plan.md
78
+ feinai done TASK-001-A --result "typecheck ✓ test ✓"
94
79
  ```
95
80
 
96
81
  ## Commands
97
82
 
98
83
  | Command | Purpose |
99
84
  |---|---|
100
- | `tasca init` | Create `.tasca/tasks.db` in cwd |
101
- | `tasca status` | Summary: pending / in_progress / completed counts |
102
- | `tasca list [filters]` | List tasks with optional filters |
103
- | `tasca add ID "subject"` | Create a new task |
104
- | `tasca show ID` | Show full task detail |
105
- | `tasca take ID` | Atomically claim a pending task |
106
- | `tasca done ID --result "..."` | Mark task completed |
107
- | `tasca fail ID --error "..."` | Mark task failed |
108
- | `tasca block ID --by BLOCKER` | Add a dependency |
109
- | `tasca spec add ID "title"` | Register a spec |
110
- | `tasca spec list` | List all specs |
111
- | `tasca spec show ID` | Spec details |
112
- | `tasca spec start ID` | Mark spec as in progress |
113
- | `tasca spec done ID --pr N` | Mark spec as completed |
114
- | `tasca server [--port N]` | Start HTTP dashboard + REST API |
115
-
116
- Run `tasca --help` for full flag reference.
117
-
118
- ## Dashboard & API
85
+ | `feinai init` | Create `.tasca/tasca.db` in cwd |
86
+ | `feinai status` | Summary: pending / in_progress / completed counts |
87
+ | `feinai list [filters]` | List tasks with optional filters |
88
+ | `feinai add ID "subject"` | Create a new task |
89
+ | `feinai show ID` | Show full task detail |
90
+ | `feinai take ID` | Atomically claim a pending task |
91
+ | `feinai done ID --result "..."` | Mark task completed |
92
+ | `feinai fail ID --error "..."` | Mark task failed |
93
+ | `feinai block ID --by BLOCKER` | Add a dependency |
94
+ | `feinai unblock ID --dep BLOCKER` | Remove a dependency |
95
+ | `feinai spec add ID "title"` | Register a spec |
96
+ | `feinai spec list` | List all specs |
97
+ | `feinai spec show ID` | Spec details |
98
+ | `feinai spec start ID` | Mark spec as in progress |
99
+ | `feinai spec done ID --pr N` | Mark spec as completed |
100
+ | `feinai git <cmd>` | Safe git wrapper (worktree-only whitelist) |
101
+ | `feinai server [--port N]` | Start HTTP dashboard + REST API |
102
+
103
+ Run `feinai --help` for full flag reference.
104
+
105
+ ## Dashboard
119
106
 
120
107
  ```bash
121
- tasca server # starts on http://127.0.0.1:8272 (TASC on phone keypad)
122
- tasca server --port 8080 # custom port
108
+ feinai server # http://127.0.0.1:8272
109
+ feinai server --port 9000 # custom port
110
+ feinai server -d # background daemon
123
111
  ```
124
112
 
125
- The dashboard is a single self-contained HTML page (no external assets, ships
126
- inside the compiled binary). Features:
127
-
128
- - **Real-time updates via SSE** — no polling; dashboard reacts instantly to CLI mutations from any process
129
- - **Markdown rendering** — spec content, plans, descriptions all render properly
130
- - **Action buttons** — take / done / fail tasks and start / done specs directly from the UI
131
- - **Create from UI** — new spec / new task forms with markdown editor
132
- - **Full-text search** — searches across specs (title + content) and tasks (subject + description)
133
- - **Live indicator** — green pulse = SSE connected, red = disconnected
134
-
135
- ### REST API
136
-
137
- #### Read endpoints
138
-
139
- | Method | Path | Returns |
140
- |---|---|---|
141
- | GET | `/api/status` | Stats: counts per status |
142
- | GET | `/api/specs` | Specs with task summary and latest plan version |
143
- | GET | `/api/specs/:id` | Spec + tasks + plans + latest plan content |
144
- | GET | `/api/specs/:id/content` | Raw markdown of the spec |
145
- | GET | `/api/specs/:id/plan` | Raw markdown of the latest plan |
146
- | GET | `/api/tasks?status=&spec=&owner=` | Filtered task list |
147
- | GET | `/api/tasks/:id` | Single task |
148
- | GET | `/api/events?limit=N` | Recent audit log entries |
149
- | GET | `/api/search?q=...` | Search specs and tasks |
150
- | GET | `/api/events/stream` | SSE stream of new events as they happen |
151
-
152
- #### Mutation endpoints (since v0.4)
153
-
154
- | Method | Path | Body |
155
- |---|---|---|
156
- | POST | `/api/specs` | `{id, title, content?}` |
157
- | POST | `/api/specs/:id/start` | `{}` |
158
- | POST | `/api/specs/:id/done` | `{pr?, merged_date?}` |
159
- | POST | `/api/specs/:id/content` | `{content}` (replace) |
160
- | POST | `/api/specs/:id/plans` | `{content}` (new version) |
161
- | POST | `/api/tasks` | `{id, subject, description?, spec_id?, packages?, quality_gates?, blocked_by?}` |
162
- | POST | `/api/tasks/:id/take` | `{owner?}` (atomic; rejects if not pending) |
163
- | POST | `/api/tasks/:id/done` | `{result}` |
164
- | POST | `/api/tasks/:id/fail` | `{error}` |
165
- | POST | `/api/tasks/:id/block` | `{by}` |
166
-
167
- Set the `X-Tasca-Actor` header to identify yourself in the audit log
168
- (e.g. `X-Tasca-Actor: dashboard`, `X-Tasca-Actor: ci-bot`). If unset, the
169
- server infers actor from the User-Agent.
170
-
171
- ### Security notes
172
-
173
- The server binds to `127.0.0.1` by default — no external access. There is no
174
- authentication built in; the model assumes the local machine is trusted (same
175
- as a dev server). If you bind to `0.0.0.0`, put it behind a reverse proxy with
176
- auth.
177
-
178
- ## Output formats
113
+ The dashboard is a self-contained HTML page (no external assets). Features:
114
+ - **Live Agents Monitor** — shows active agents, worktree path, repo, files being touched, elapsed time
115
+ - **Presence indicator** — green ripple when agents active, gray when idle
116
+ - **Real-time updates via SSE** — reacts instantly to CLI mutations
117
+ - **Action buttons** — take / done / fail tasks directly from UI
118
+ - **Full-text search** — across specs, plans, and tasks
119
+
120
+ ## `feinai git` — safe git wrapper
121
+
122
+ `feinai git` enforces a worktree-only workflow for parallel agent safety. It blocks operations that would interfere with other agents working in parallel:
179
123
 
180
124
  ```bash
181
- tasca list # auto: color if TTY, plain otherwise
182
- tasca list --plain # explicit plain (no ANSI codes)
183
- tasca list --json # JSON for agents and scripts
125
+ feinai git worktree add .worktrees/TASK-001 origin/main
126
+ feinai git add .
127
+ feinai git commit -m "feat: ..."
128
+ feinai git push origin HEAD:main
129
+ feinai git complete # sync main after push
184
130
  ```
185
131
 
186
- ## Claude Code skills
132
+ Blocked: `branch`, `checkout`, `merge`, `rebase`, `reset`, `fetch`, `pull`, `stash`, `clone`.
187
133
 
188
- `tasca` ships four skills that cover the full [Spec-Driven Development](https://github.com/anthropics/superpowers) cycle. They replace the markdown-file workflow entirely — no `docs/superpowers/` directory, no growing plan files, no token waste reading stale state.
134
+ `opengit` is also available as a standalone command (installed alongside `feinai`).
189
135
 
190
- | Skill | When Claude uses it | What it does |
191
- |---|---|---|
192
- | `tasca-sdd` | Always, when `.tasca/tasca.db` exists | Master skill — teaches Claude the tasca workflow; activates the others |
193
- | `tasca-write-spec` | Designing a new feature | Writes spec + implementation plan directly into tasca (`tasca spec add` + `tasca plan add`) |
194
- | `tasca-write-tasks` | After spec + plan exist | Decomposes the plan into atomic tasks with file-level parallelism analysis and `blocked_by` dependencies |
195
- | `tasca-dispatch` | Executing a spec | Dispatches subagents into git worktrees; each agent calls `tasca take`, works in isolation, reports via `tasca done` |
136
+ ## Claude Code skills
196
137
 
197
- The skills are drop-in: in projects without tasca, Claude falls back to the regular superpowers markdown flow.
138
+ feinai ships five skills covering the full Spec-Driven Development cycle:
139
+
140
+ | Skill | Purpose |
141
+ |---|---|
142
+ | `feinai-sdd` | Master skill — activates when `.tasca/tasca.db` exists |
143
+ | `feinai-write-spec` | Writes spec + plan into feinai |
144
+ | `feinai-write-tasks` | Decomposes plan into atomic tasks with parallelism analysis |
145
+ | `feinai-dispatch` | Orchestrates subagents in git worktrees |
146
+ | `feinai-implement` | Claims and executes one task in an isolated worktree |
198
147
 
199
148
  ## Architecture
200
149
 
201
150
  ```
202
- ~/.tasca/ (future) global config
203
- <project>/.tasca/tasca.db local SQLite, auto-discovered like .git
151
+ <project>/.tasca/tasca.db local SQLite, auto-discovered like .git
204
152
 
205
153
  Tables:
206
- specs (id, numero, title, status, content TEXT, pr, merged_date, ...)
207
- plans (id, spec_id FK, content TEXT, version, created_at)
208
- indexed on spec_id for fast lookup; unique(spec_id, version)
209
- tasks (id, spec_id, subject, description, status, owner,
210
- blocked_by, packages, quality_gates, result, error, ...)
211
- events (append-only audit log of every operation, with actor)
154
+ specs (id, title, status, content, plan versions...)
155
+ tasks (id, spec_id, subject, description, status, owner,
156
+ blocked_by, packages, quality_gates, worktree, result, error...)
157
+ events (append-only audit log — actor, operation, timestamp)
212
158
  ```
213
159
 
214
- `tasca` walks up the directory tree from `cwd` looking for `.tasca/tasca.db`, the same way git locates `.git`. This means you can run `tasca` commands from any subdirectory of your project.
215
-
216
- ### Why the content lives in the DB
217
-
218
- `tasca` stores the actual markdown of specs and plans inside SQLite, not as paths to external files. This means:
219
- - `tasca` is the single source of truth — no risk of broken paths or moved files
220
- - Plans can have multiple versions tracked (revisions during refinement)
221
- - Export to markdown is trivial: `tasca spec content SPEC-X > spec.md`
222
- - An agent calling `tasca spec content SPEC-X` gets the same bytes the human gets, deterministically
160
+ feinai walks up the directory tree from `cwd` looking for `.tasca/tasca.db`, the same way git locates `.git`.
223
161
 
224
162
  ### Audit log
225
163
 
226
- Every mutation records an event in the `events` table with an `actor` identifier of the form `{parent_process}:{pid}:{username}` (e.g., `claude:12345:m`, `opencode:67890:m`, `bash:99999:m`). Override with `$TASCA_USER` for explicit agent identity.
164
+ Every mutation records `{parent_process}:{pid}:{username}` (e.g. `claude:12345:m`, `opencode:67890:m`). Override with `$FEINA_USER`.
227
165
 
228
166
  ## License
229
167
 
230
- MIT
168
+ MIT — built with ❤️ in Barcelona. *Feina* means "work" in Catalan.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "feinai",
3
- "version": "0.5.0",
3
+ "version": "0.5.1",
4
4
  "description": "Task & spec manager for AI agents — parallel worktrees, live dashboard, SDD skills",
5
5
  "type": "module",
6
6
  "bin": {
package/skills/feinai-dispatch/SKILL.md CHANGED
@@ -9,6 +9,38 @@ Execute the pending tasks of a SPEC. One responsibility: dispatch subagents in w
9
9
 
10
10
  ## Preconditions
11
11
 
12
+ Before anything else, verify the environment:
13
+
14
+ ```bash
15
+ feinai --version 2>&1
16
+ feinai git status 2>&1
17
+ ```
18
+
19
+ **If `feinai: command not found` or `opengit: command not found`:**
20
+
21
+ This means `~/.bun/bin` is not on PATH in this shell context. This is a known issue with bun global installs in non-interactive sessions.
22
+
23
+ Tell the user:
24
+
25
+ > `feinai` (or `opengit`) is not on PATH in this shell context. This happens in non-interactive SSH sessions where `~/.bun/bin` is not loaded.
26
+ >
27
+ > Fix with a one-time symlink (requires sudo/root):
28
+ > ```bash
29
+ > sudo ln -sf ~/.bun/bin/feinai /usr/local/bin/feinai
30
+ > sudo ln -sf ~/.bun/bin/opengit /usr/local/bin/opengit
31
+ > sudo ln -sf ~/.bun/bin/bun /usr/local/bin/bun
32
+ > ```
33
+ > Or if root access is available via a different user (e.g. `do-hermes`):
34
+ > ```bash
35
+ > ssh do-hermes "ln -sf /home/martin/.bun/bin/feinai /usr/local/bin/feinai && ln -sf /home/martin/.bun/bin/opengit /usr/local/bin/opengit && ln -sf /home/martin/.bun/bin/bun /usr/local/bin/bun"
36
+ > ```
37
+ >
38
+ > Want me to run this fix now?
39
+
40
+ **Do not proceed until `feinai --version` returns a version number.**
41
+
42
+ Then verify:
43
+
12
44
  1. `feinai status` succeeds
13
45
  2. The SPEC has pending tasks: `feinai list --spec SPEC-NNN --pending --json` returns non-empty
14
46
  3. The current working directory is a clean git repo (no uncommitted changes blocking worktree creation)
package/src/cli.ts CHANGED
@@ -48,7 +48,7 @@ import {
48
48
  type OutputFormat,
49
49
  } from "./format";
50
50
 
51
- const VERSION = "0.5.0";
51
+ const VERSION = "0.5.1";
52
52
 
53
53
  interface ParsedArgs {
54
54
  positional: string[];