feinai 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [0.5.0] - 2026-06-10
+
+### Added
+- `tasca git <cmd>` — safe git wrapper subcommand. Passes through to `opengit`, enforcing a worktree-only whitelist (blocks branch, merge, rebase, checkout, etc.)
+- `opengit` shipped as a binary alongside `tasca` — `bun install -g tasca` now installs both
+- `tasca unblock <TASK-ID> --dep <TASK-ID>` — remove a specific dependency from a task
+- `tasca edit --clear-blocked-by` — clear all dependencies from a task
+- Live Agents Monitor: working directory, repo name, and `.tasca` path shown per agent card
+- Live Agents Monitor: presence indicator — gray dot when idle, green dot with ripple animation when agents are active
+- Live Agents Monitor: elapsed time and spec ID per card
+- `tasca init` now auto-adds `.tasca/` to `.gitignore` if in a git repo
+- Skills: `tasca-implement` — claim one pending task, implement in isolated worktree, run quality gates, push to main
+
+### Changed
+- Dashboard is now English-only — removed i18n/language selector
+- `tasca-implement` SKILL.md updated to use `tasca git` instead of `opengit` directly
+- `package.json`: added `repository`, `homepage`, `bugs` fields
+
+### Skills included
+`tasca-sdd` · `tasca-write-spec` · `tasca-write-tasks` · `tasca-dispatch` · `tasca-implement`
+
+---
+
+## [0.4.0] - 2026-06-08
+
+Initial public release. Core CLI with specs, plans, tasks, HTTP dashboard, and SDD skills.
+
+### Features
+- `tasca init / status / list / add / show / take / done / fail / block / release / reopen / edit`
+- `tasca spec` — spec lifecycle (add, start, done, archive, set-content, edit)
+- `tasca plan` — plan revisions per spec
+- `tasca server` — HTTP dashboard + REST API + SSE live updates
+- Live Agents Monitor — real-time view of in-progress tasks with worktree state
+- Atomic `take` — SQL-level concurrency safety for parallel agents
+- Append-only events audit log
+- Skills: `tasca-sdd`, `tasca-write-spec`, `tasca-write-tasks`, `tasca-dispatch`

package/README.md

@@ -0,0 +1,230 @@
+# tasca — run agents in parallel. know exactly what each one is doing.
+
+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.
+
+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.
+
+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.
+
+```bash
+tasca take TASK-121-A
+# → {id, subject, description, workplan, packages, quality_gates, worktree, ...}
+# One call. Everything the agent needs to start.
+```
+
+## Why tasca
+
+- **Atomic commands** — `take` returns the full task payload (subject + description + workplan + quality gates) in a single response.
+- **Concurrency-safe** — `take` is an atomic SQL UPDATE; two agents can't claim the same task.
+- **Queryable** — filter by status, owner, spec without parsing markdown.
+- **Auditable** — every operation is logged in an append-only events table.
+- **Local-first** — SQLite file at `.tasca/tasks.db`, no server, no cloud.
+
+## Status
+
+Alpha. Built for use in real SDD workflows; API may change before 1.0.
+
+## Install
+
+Requires [Bun](https://bun.sh) 1.3+.
+
+```bash
+# From source (recommended during alpha)
+git clone https://github.com/mvisca/tasca
+cd tasca
+bun install
+bun link  # registers `tasca` as global command
+```
+
+### Activate the Claude Code skills
+
+`tasca` ships four Claude Code skills that replace the markdown-file SDD workflow end to end. Link them into your global skills directory:
+
+```bash
+mkdir -p ~/.claude/skills
+ln -sfn "$(pwd)/skills/tasca-sdd"        ~/.claude/skills/tasca-sdd
+ln -sfn "$(pwd)/skills/tasca-write-spec" ~/.claude/skills/tasca-write-spec
+ln -sfn "$(pwd)/skills/tasca-write-tasks" ~/.claude/skills/tasca-write-tasks
+ln -sfn "$(pwd)/skills/tasca-dispatch"   ~/.claude/skills/tasca-dispatch
+```
+
+Skills activate automatically in projects that have `.tasca/tasca.db`.
+
+Future install paths (post-alpha):
+- `npm install -g tasca` (with Bun installed)
+- Pre-compiled binaries from GitHub Releases (with checksums)
+- Claude Code marketplace plugin (bundles CLI + skills)
+
+## Quick start
+
+```bash
+# 1. Initialize a tasca DB in your project
+cd my-project
+tasca init
+# → Creates .tasca/tasca.db
+
+# 2. Register a spec with its markdown content (typically done by brainstorming skill)
+tasca spec add SPEC-001 "User authentication" \
+  --file specs/001-auth/spec.md
+# OR via stdin:
+cat specs/001-auth/spec.md | tasca spec add SPEC-001 "User authentication" --stdin
+
+# 3. Register the implementation plan (typically done by writing-plans skill)
+cat plan.md | tasca plan add SPEC-001 --stdin
+
+# 4. Add tasks (typically done by writing-plans skill)
+tasca add TASK-001-A "Create auth schema" \
+  --spec SPEC-001 \
+  --desc "Define Drizzle schema for users table..." \
+  --package "@app/auth" \
+  --gate "pnpm typecheck" \
+  --gate "pnpm test -- --run"
+
+# 5. Agent takes the task (atomic — returns full task JSON in single call)
+tasca take TASK-001-A
+# Owner is auto-detected as "{parent_process}:{pid}:{username}"
+# Override via $TASCA_USER env var
+
+# 6. Agent marks done
+tasca done TASK-001-A --result "typecheck ✓ test ✓"
+
+# 7. Export content when needed
+tasca spec content SPEC-001 > /tmp/spec.md
+tasca plan show SPEC-001 > /tmp/plan.md
+```
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `tasca init` | Create `.tasca/tasks.db` in cwd |
+| `tasca status` | Summary: pending / in_progress / completed counts |
+| `tasca list [filters]` | List tasks with optional filters |
+| `tasca add ID "subject"` | Create a new task |
+| `tasca show ID` | Show full task detail |
+| `tasca take ID` | Atomically claim a pending task |
+| `tasca done ID --result "..."` | Mark task completed |
+| `tasca fail ID --error "..."` | Mark task failed |
+| `tasca block ID --by BLOCKER` | Add a dependency |
+| `tasca spec add ID "title"` | Register a spec |
+| `tasca spec list` | List all specs |
+| `tasca spec show ID` | Spec details |
+| `tasca spec start ID` | Mark spec as in progress |
+| `tasca spec done ID --pr N` | Mark spec as completed |
+| `tasca server [--port N]` | Start HTTP dashboard + REST API |
+
+Run `tasca --help` for full flag reference.
+
+## Dashboard & API
+
+```bash
+tasca server                  # starts on http://127.0.0.1:8272 (TASC on phone keypad)
+tasca server --port 8080      # custom port
+```
+
+The dashboard is a single self-contained HTML page (no external assets, ships
+inside the compiled binary). Features:
+
+- **Real-time updates via SSE** — no polling; dashboard reacts instantly to CLI mutations from any process
+- **Markdown rendering** — spec content, plans, descriptions all render properly
+- **Action buttons** — take / done / fail tasks and start / done specs directly from the UI
+- **Create from UI** — new spec / new task forms with markdown editor
+- **Full-text search** — searches across specs (title + content) and tasks (subject + description)
+- **Live indicator** — green pulse = SSE connected, red = disconnected
+
+### REST API
+
+#### Read endpoints
+
+| Method | Path | Returns |
+|---|---|---|
+| GET | `/api/status` | Stats: counts per status |
+| GET | `/api/specs` | Specs with task summary and latest plan version |
+| GET | `/api/specs/:id` | Spec + tasks + plans + latest plan content |
+| GET | `/api/specs/:id/content` | Raw markdown of the spec |
+| GET | `/api/specs/:id/plan` | Raw markdown of the latest plan |
+| GET | `/api/tasks?status=&spec=&owner=` | Filtered task list |
+| GET | `/api/tasks/:id` | Single task |
+| GET | `/api/events?limit=N` | Recent audit log entries |
+| GET | `/api/search?q=...` | Search specs and tasks |
+| GET | `/api/events/stream` | SSE stream of new events as they happen |
+
+#### Mutation endpoints (since v0.4)
+
+| Method | Path | Body |
+|---|---|---|
+| POST | `/api/specs` | `{id, title, content?}` |
+| POST | `/api/specs/:id/start` | `{}` |
+| POST | `/api/specs/:id/done` | `{pr?, merged_date?}` |
+| POST | `/api/specs/:id/content` | `{content}` (replace) |
+| POST | `/api/specs/:id/plans` | `{content}` (new version) |
+| POST | `/api/tasks` | `{id, subject, description?, spec_id?, packages?, quality_gates?, blocked_by?}` |
+| POST | `/api/tasks/:id/take` | `{owner?}` (atomic; rejects if not pending) |
+| POST | `/api/tasks/:id/done` | `{result}` |
+| POST | `/api/tasks/:id/fail` | `{error}` |
+| POST | `/api/tasks/:id/block` | `{by}` |
+
+Set the `X-Tasca-Actor` header to identify yourself in the audit log
+(e.g. `X-Tasca-Actor: dashboard`, `X-Tasca-Actor: ci-bot`). If unset, the
+server infers actor from the User-Agent.
+
+### Security notes
+
+The server binds to `127.0.0.1` by default — no external access. There is no
+authentication built in; the model assumes the local machine is trusted (same
+as a dev server). If you bind to `0.0.0.0`, put it behind a reverse proxy with
+auth.
+
+## Output formats
+
+```bash
+tasca list                # auto: color if TTY, plain otherwise
+tasca list --plain        # explicit plain (no ANSI codes)
+tasca list --json         # JSON for agents and scripts
+```
+
+## Claude Code skills
+
+`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.
+
+| Skill | When Claude uses it | What it does |
+|---|---|---|
+| `tasca-sdd` | Always, when `.tasca/tasca.db` exists | Master skill — teaches Claude the tasca workflow; activates the others |
+| `tasca-write-spec` | Designing a new feature | Writes spec + implementation plan directly into tasca (`tasca spec add` + `tasca plan add`) |
+| `tasca-write-tasks` | After spec + plan exist | Decomposes the plan into atomic tasks with file-level parallelism analysis and `blocked_by` dependencies |
+| `tasca-dispatch` | Executing a spec | Dispatches subagents into git worktrees; each agent calls `tasca take`, works in isolation, reports via `tasca done` |
+
+The skills are drop-in: in projects without tasca, Claude falls back to the regular superpowers markdown flow.
+
+## Architecture
+
+```
+~/.tasca/                          (future) global config
+<project>/.tasca/tasca.db          local SQLite, auto-discovered like .git
+
+Tables:
+  specs  (id, numero, title, status, content TEXT, pr, merged_date, ...)
+  plans  (id, spec_id FK, content TEXT, version, created_at)
+         indexed on spec_id for fast lookup; unique(spec_id, version)
+  tasks  (id, spec_id, subject, description, status, owner,
+          blocked_by, packages, quality_gates, result, error, ...)
+  events (append-only audit log of every operation, with actor)
+```
+
+`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.
+
+### Why the content lives in the DB
+
+`tasca` stores the actual markdown of specs and plans inside SQLite, not as paths to external files. This means:
+- `tasca` is the single source of truth — no risk of broken paths or moved files
+- Plans can have multiple versions tracked (revisions during refinement)
+- Export to markdown is trivial: `tasca spec content SPEC-X > spec.md`
+- An agent calling `tasca spec content SPEC-X` gets the same bytes the human gets, deterministically
+
+### Audit log
+
+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.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "feinai",
+  "version": "0.5.0",
+  "description": "Task & spec manager for AI agents — parallel worktrees, live dashboard, SDD skills",
+  "type": "module",
+  "bin": {
+    "feinai": "./src/cli.ts",
+    "opengit": "./src/opengit.sh"
+  },
+  "scripts": {
+    "dev": "bun src/cli.ts",
+    "test": "bun test",
+    "build": "bun build src/cli.ts --compile --outfile dist/feina",
+    "build:linux-x64": "bun build src/cli.ts --compile --target=bun-linux-x64 --outfile dist/feina-linux-x64",
+    "build:linux-arm64": "bun build src/cli.ts --compile --target=bun-linux-arm64 --outfile dist/feina-linux-arm64",
+    "build:darwin-x64": "bun build src/cli.ts --compile --target=bun-darwin-x64 --outfile dist/feina-darwin-x64",
+    "build:darwin-arm64": "bun build src/cli.ts --compile --target=bun-darwin-arm64 --outfile dist/feina-darwin-arm64",
+    "build:all": "bun run build:linux-x64 && bun run build:linux-arm64 && bun run build:darwin-x64 && bun run build:darwin-arm64"
+  },
+  "keywords": [
+    "task-manager",
+    "sdd",
+    "claude-code",
+    "ai-agents",
+    "sqlite",
+    "cli",
+    "feina"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mvisca/feina.git"
+  },
+  "homepage": "https://github.com/mvisca/feina#readme",
+  "bugs": {
+    "url": "https://github.com/mvisca/feina/issues"
+  },
+  "engines": {
+    "bun": ">=1.3.0",
+    "node": ">=22.5.0"
+  },
+  "optionalDependencies": {
+    "better-sqlite3": ">=9.0.0"
+  },
+  "files": [
+    "src/*.ts",
+    "src/*.html",
+    "src/*.sh",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "skills/"
+  ],
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}

package/skills/feinai-dispatch/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: feinai-dispatch
+description: Use when tasks exist in feinai for a spec and need to be executed. Dispatches subagents to claim and complete tasks, enforces worktree isolation, handles parallelism (sequential or parallel based on user choice), and resolves merge conflicts and failures by blocking the loop until repair completes. Replaces `subagent-driven-development` from superpowers when feinai is active.
+---
+
+# feinai-dispatch
+
+Execute the pending tasks of a SPEC. One responsibility: dispatch subagents in worktrees, integrate their output, handle failures.
+
+## Preconditions
+
+1. `feinai status` succeeds
+2. The SPEC has pending tasks: `feinai list --spec SPEC-NNN --pending --json` returns non-empty
+3. The current working directory is a clean git repo (no uncommitted changes blocking worktree creation)
+
+If any fails: stop and report. Do not improvise.
+
+## Input
+
+User invokes with a SPEC-ID. If missing, ask: *"Which SPEC-ID? (e.g. SPEC-121-B)"*.
+
+---
+
+## Phase 0 — Detect orphans
+
+Before doing anything, check for orphaned tasks:
+
+```bash
+feinai list --spec SPEC-NNN --json | jq '.[] | select(.status == "in_progress")'
+```
+
+Any `in_progress` task is a previous run that didn't complete. For each:
+
+1. Check if its `worktree` path still exists on disk
+2. Check if the worktree has uncommitted work
+3. Report to the user and ask: *"Task TASK-X is in_progress at <worktree>. Resume, release, or fail?"*
+
+Do not proceed to Phase 1 until all orphans are resolved.
+
+---
+
+## Phase 1 — Choose execution mode
+
+Read the task graph:
+
+```bash
+feinai list --spec SPEC-NNN --pending --json
+```
+
+Analyze `blocked_by` to find tasks ready to run (no unresolved blockers).
+
+If multiple tasks are ready simultaneously, ask the user:
+
+> Found N tasks ready: TASK-A, TASK-B, TASK-C.
+> Run **in parallel** (faster, harder to debug) or **sequentially** (safer, slower)?
+
+Do NOT decide for the user. The choice is intentional — fallos críticos
+en cadena son una preocupación real del usuario. Respect their answer.
+
+---
+
+## Phase 2 — The dispatch loop
+
+For each iteration:
+
+### Step A — Pick the next task(s)
+
+- **Sequential mode:** one task whose blockers are all `completed`
+- **Parallel mode:** all ready tasks (max as recommended by the plan)
+
+### Step B — Create worktrees
+
+For each task to dispatch:
+
+```bash
+git worktree add .claude/worktrees/TASK-X-id <branch>
+```
+
+Branch naming: `feature/TASK-X-id-slug` derived from the subject.
+
+### Step C — Register the worktree in feinai
+
+```bash
+feinai take TASK-X --json   # atomic claim, sin worktree aún
+feinai task edit TASK-X --worktree .claude/worktrees/TASK-X-id
+```
+
+Order matters: take first (atomic reservation), then edit to record the worktree path.
+
+### Step D — Dispatch the subagent
+
+Spawn a subagent with this prompt template:
+
+> Your task is TASK-X. You are operating in the worktree at <path>.
+> Do not switch branches. Do not edit files outside the worktree.
+>
+> The task is already claimed for you. Begin with:
+> ```
+> feinai show TASK-X --json
+> ```
+> The JSON returns the task description, packages, quality_gates, and spec_context
+> (the full spec + plan_content). Use only that payload — do not read external files
+> unless the description tells you to.
+>
+> Implement the task. Run the quality gates. If they pass:
+> ```
+> feinai done TASK-X --result "<gates summary>"
+> ```
+>
+> If gates fail and you cannot resolve, or if you hit a merge conflict on merge-back:
+> ```
+> feinai fail TASK-X --error "<short reason>"
+> ```
+> and stop. Do not try to recover or improvise.
+
+**Parallel mode:** dispatch all subagents in one batch (one tool call with multiple subagent invocations).
+
+### Step E — Wait for results
+
+Each subagent returns `done` or `fail`. The tasca DB is the source of truth — re-query it:
+
+```bash
+feinai show TASK-X --json
+```
+
+### Step F — Integrate (per completed task)
+
+For each `completed` task:
+
+1. Run the quality gates **again** in the worktree as a final check
+2. Merge worktree branch into the working branch
+3. Remove the worktree: `git worktree remove .claude/worktrees/TASK-X-id`
+4. Clear the worktree field: `feinai task edit TASK-X --worktree ""`
+
+If the merge has conflicts → treat as a failure. Go to Phase 3.
+
+---
+
+## Phase 3 — Failure handling (blocking)
+
+When a task fails OR a merge conflict appears:
+
+**Stop the loop.** No new tasks dispatch until repair is complete.
+
+### Repair sequence
+
+1. **Attempt your own fix** — read the worktree, the error, the failed task description. If it's a clear typo or trivial issue, fix it inline.
+2. **If stuck → advisor()** — call the advisor with full context. Wait for the response.
+3. **If still stuck → ask the user** — present:
+   - What failed
+   - What you tried
+   - The advisor's suggestion (if available)
+   - Ask: *"How to proceed? (a) I'll try the suggested fix, (b) escalate to a stronger model, (c) you take over"*
+
+### After repair
+
+- If you resolved it: `feinai task edit TASK-X --worktree ...` (if path changed), then `feinai release TASK-X` so it returns to pending, OR `feinai done` if you finished it yourself
+- If user took over: stop. Tell them to relaunch dispatch with: `/feinai-dispatch SPEC-NNN`
+
+**Never silently retry.** Always make the failure visible.
+
+---
+
+## Phase 4 — Completion
+
+When `feinai list --spec SPEC-NNN --pending --json` returns empty:
+
+1. Verify no `in_progress` left:
+   ```bash
+   feinai list --spec SPEC-NNN --json | jq '.[] | select(.status != "completed")'
+   ```
+   Should be empty.
+2. Run project-wide quality gates (from the plan)
+3. Report to the user:
+   > SPEC-NNN complete. All N tasks done. Quality gates pass.
+   > Mark spec done with: `feinai spec done SPEC-NNN --pr <num> --merged <date>` (when you merge to main).
+
+---
+
+## Rules
+
+### Worktree rules (non-negotiable)
+
+- ✅ Each task gets its own worktree under `.claude/worktrees/`
+- ✅ Subagent never switches branches, never works outside its worktree
+- ✅ Worktree path is recorded in feinai (`worktree` field) immediately after `take`
+- ❌ Never run `git checkout` on the main working tree during dispatch
+- ❌ Never delete a worktree without first marking the task done/failed/released
+
+### Parallelism rules
+
+- The "same file = sequential" decision was already made in `feinai-write-tasks` via `blocked_by`. Trust it.
+- Do NOT second-guess. If `blocked_by` says A→B→C, run them sequentially even in "parallel mode."
+- "Parallel mode" only means: tasks with no inter-dependencies dispatch concurrently.
+
+### Failure rules
+
+- One failure = stop the world. Block the loop. Repair before continuing.
+- Failed tasks keep their `worktree` field (we changed this intentionally) — so you can inspect them.
+- Never auto-retry. Repair → release → next loop iteration will re-pick.
+
+### Subagent autonomy boundary
+
+- Subagents read only their task payload (via `feinai take` / `feinai show`)
+- Subagents may not call other skills (they have no context)
+- Subagents may not dispatch other subagents
+- All decision-making about scope, parallelism, and failure handling stays in the dispatcher
+
+---
+
+## What NOT to do
+
+- ❌ Skip Phase 0 (orphan detection) — you'll dispatch into half-broken state
+- ❌ Dispatch without creating a worktree first
+- ❌ Decide parallel vs sequential without asking the user
+- ❌ Continue the loop while a task is failed
+- ❌ Read every task description yourself — let the subagent do it via `feinai take`
+- ❌ Modify tasks during dispatch — that's `feinai-write-tasks`' job; if specs need changing, stop and tell the user
+
+---
+
+## Quick reference
+
+| Need | Command |
+|---|---|
+| Find ready tasks | `feinai list --spec SPEC-N --pending --json` |
+| Find orphans | `feinai list --spec SPEC-N --json \| jq '.[] \| select(.status=="in_progress")'` |
+| Claim a task | `feinai take TASK-X` |
+| Record worktree | `feinai task edit TASK-X --worktree <path>` |
+| Mark done | `feinai done TASK-X --result "..."` |
+| Mark failed (keeps worktree) | `feinai fail TASK-X --error "..."` |
+| Release for retry | `feinai release TASK-X` |
+| Verify all done | `feinai list --spec SPEC-N --json` |