feinai 0.5.0

package/skills/feinai-implement/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: feinai-implement
+description: Use when a feinai task needs to be executed. Claims one pending task from tasca, implements it in an isolated worktree, runs quality gates, and pushes to main. Designed to be dispatched by feinai-dispatch or run standalone for a single task.
+---
+
+# feinai-implement
+
+Claim one pending task from tasca, implement it in an isolated worktree, run quality gates, push to main.
+
+## Preconditions
+
+1. `feinai status` succeeds and there is at least one pending task
+2. Current working directory is a clean git repo
+3. `feinai git status` works (feinai git is bundled with tasca — no separate setup needed)
+
+If any fails: stop and report. Do not improvise.
+
+---
+
+## AL ARRANCAR
+
+1. `feinai list --pending --json` — encontrá la primera tarea disponible (sin blockers pendientes)
+2. Si no hay ninguna → respondé "No hay tareas pendientes" y pará
+3. `feinai take <TASK-ID> --owner implement-agent` — tomala atómicamente
+4. Si la tarea tiene `spec_id` → `feinai spec content <SPEC-ID>` para contexto
+5. Si la tarea tiene `blocked_by` con tareas no completadas → soltá con `feinai release <TASK-ID>` y pará
+
+Leé `AGENTS.md` del proyecto para arquitectura y convenciones del proyecto específico.
+
+---
+
+## Ejecutar la tarea
+
+**Paso 1 — Worktree aislado:**
+```bash
+feinai git worktree add .worktrees/<TASK-ID> origin/main
+cd .worktrees/<TASK-ID>
+```
+
+**Paso 2 — Setup del worktree:**
+Instalá dependencias si el proyecto las requiere. Consultá `AGENTS.md` del proyecto para el comando exacto.
+
+**Paso 3 — Leer antes de escribir:**
+- La descripción completa de la tarea (`feinai show <TASK-ID>`)
+- Los archivos que vas a tocar — léelos antes de editarlos
+- Si hay un **Workplan** en la descripción → ejecutá esos pasos en ese orden exacto
+
+**Paso 4 — Implementar:**
+Exactamente lo que dice la tarea. Ni más ni menos.
+- No toques archivos fuera del scope de la tarea
+- Si un archivo "a crear" ya existe → extendelo en lugar de sobrescribirlo si ya tiene contenido válido
+
+**Paso 5 — Commit:**
+Un commit por tarea. Conventional commits:
+```
+feat(scope): descripción concisa
+```
+Tipos: `feat`, `fix`, `refactor`, `test`, `chore`.
+
+**Paso 6 — Quality gates:**
+Corré los gates definidos en la tarea (`quality_gates`). Si la tarea no los especifica, consultá `AGENTS.md` del proyecto para los gates por defecto.
+
+**Paso 7 — Cerrar:**
+
+Gates pasan:
+```bash
+# Desde el worktree:
+feinai git push origin HEAD:main
+
+# Desde la raíz del repo:
+feinai git worktree remove .worktrees/<TASK-ID>
+feinai git complete
+
+feinai done <TASK-ID> --result "gates ✓"
+```
+
+Gates fallan → seguí "Si algo falla".
+
+**Done = 3 hechos observables:**
+1. Quality gates pasan sin errores
+2. Los archivos de la tarea existen con contenido correcto
+3. Commit limpio en `main` y tarea en estado `completed` en tasca
+
+---
+
+## Si algo falla
+
+Gates fallan, push falla, o error en cualquier paso:
+
+1. **No limpies el worktree**
+2. Push a rama backup:
+   ```bash
+   feinai git push origin HEAD:backup/<TASK-ID>
+   ```
+3. Marcá la tarea como fallida:
+   ```bash
+   feinai fail <TASK-ID> --error "<comando exacto + output relevante>"
+   ```
+4. Dejá el worktree intacto para recuperación manual
+
+---
+
+## Git — `feinai git` exclusivamente
+
+`git` y `gh` están bloqueados. Usá `feinai git` para todo — es opengit bundleado con tasca.
+
+**Permitido:**
+- `feinai git worktree add/list/lock/unlock`
+- `feinai git add`, `commit`, `push`, `status`, `diff`, `log`, `show`
+- `feinai git complete` — sincroniza main local tras push (solo desde raíz del repo)
+
+**Prohibido:**
+- `feinai git branch`, `checkout`, `switch` — nunca cambiar branches
+- `feinai git merge`, `rebase`, `reset`, `cherry-pick`
+- `feinai git fetch`, `pull`, `remote`, `clone`
+- `feinai git stash`, `tag`
+- `feinai git worktree remove` — solo tras push exitoso
+
+Si `feinai git` falla → **STOP**. No reintentes, no uses `git`. Reportá al usuario.
+
+---
+
+## Reglas absolutas
+
+**No modifiques:**
+- `AGENTS.md`, `CLAUDE.md`
+- Archivos de configuración de CI/CD, infra, o secretos (`.env`, `.env.*`)
+- La DB de tasca directamente
+
+**Código:**
+- Sin `any` sin comentario justificado en la misma línea
+- Si un test falla: corregí el test O la implementación. Nunca silencies, skipees, ni agregues workarounds para que el gate "pase"
+- Si no es obvio cuál es la causa → **STOP**, reportá al usuario con el comando exacto y el output completo

package/skills/feinai-sdd/SKILL.md

@@ -0,0 +1,291 @@
+---
+name: feinai-sdd
+description: Use when working in spec-driven development (SDD) workflows that involve brainstorming, writing-plans, or subagent-driven-development AND the project has a `.tasca/tasca.db` file. Replaces creating markdown files in `docs/superpowers/specs/` and `docs/superpowers/plans/` with atomic `feinai` CLI calls, keeping state queryable, race-free, and audit-logged. Also use when the user asks to create a spec, add a task, claim work, or mark progress, in a project that uses tasca.
+---
+
+# Tasca SDD integration
+
+`feinai` is a CLI + local SQLite database for managing specs, plans, and tasks in
+SDD workflows. When a project has `.tasca/tasca.db`, you should write to that
+database instead of producing markdown files under `docs/superpowers/`.
+
+This skill extends superpowers — it does not replace it. You still follow the
+SDD process (brainstorming → writing-plans → subagent-driven-development); you
+just change *where the artifacts get stored*.
+
+---
+
+## When to use this skill
+
+Invoke when **all** of the following are true:
+
+1. The project has a `.tasca/tasca.db` file (walk up the directory tree from
+   the current working directory; tasca uses the same discovery pattern as git).
+   Check with: `feinai status` (exit code 0 = tasca is set up).
+2. You are about to:
+   - Write a spec via the `brainstorming` skill, OR
+   - Write a plan via the `writing-plans` skill, OR
+   - Execute tasks via `subagent-driven-development` or `executing-plans`, OR
+   - The user explicitly mentions creating/claiming/marking tasks or specs.
+
+If `.tasca/tasca.db` does not exist, skip this skill — let superpowers do its
+normal markdown-based flow.
+
+---
+
+## Detection (do this first)
+
+Before any spec / plan / task write, run:
+
+```bash
+feinai status 2>/dev/null
+```
+
+- Exit code 0: tasca is active in this project → use this skill.
+- Exit code 2: `No .tasca/tasca.db found` → fall back to vanilla superpowers
+  (or ask the user `feinai init` if it seems intended).
+- Command not found: tasca is not installed. Tell the user and stop.
+
+---
+
+## Phase 1 — Brainstorming → `feinai spec add`
+
+When `brainstorming` would write to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`,
+instead create a spec entry in feinai with the same content.
+
+**Spec ID convention:** `SPEC-NNN` where `NNN` is the next free integer.
+Find the next number with:
+
+```bash
+feinai spec list --json | jq -r '.[].numero' | sort -n | tail -1
+```
+
+(or just inspect the list — the next number is `max + 1`.)
+
+### Pattern — create the spec
+
+Use stdin for the markdown content to avoid quoting issues:
+
+```bash
+feinai spec add SPEC-042 "Short title" --stdin <<'FEINAI_EOF'
+# SPEC-042: Short title
+
+## Goal
+One sentence describing what this builds.
+
+## Architecture
+2-3 sentences about approach.
+
+## Components
+- ...
+
+## Tests
+- ...
+FEINAI_EOF
+```
+
+### What replaces what
+
+| Superpowers step | tasca equivalent |
+|---|---|
+| `Write(docs/superpowers/specs/YYYY-MM-DD-X-design.md, ...)` | `feinai spec add SPEC-NNN "title" --stdin <<<` content |
+| Spec self-review (re-read the markdown) | `feinai spec content SPEC-NNN` (returns the markdown) |
+| User reviews written spec | Same — but they can also use `feinai server` and open the dashboard |
+| Refining the spec | `feinai spec set-content SPEC-NNN --stdin <<<` updated content |
+
+---
+
+## Phase 2 — Writing-plans → `feinai plan add` + `feinai add`
+
+When `writing-plans` would write a plan file with checkbox tasks, do **two**
+things in feinai:
+
+1. **Store the plan markdown** for the human/agent reference.
+2. **Create individual tasks** as structured rows so subagents can claim them.
+
+### Pattern — store the plan
+
+```bash
+feinai plan add SPEC-042 --stdin <<'FEINAI_EOF'
+# Implementation plan for SPEC-042
+
+## Architecture
+...
+
+## Task breakdown
+- TASK-042-A: schema (touches packages/auth)
+- TASK-042-B: routes (depends on A)
+- TASK-042-C: tests (depends on A, B)
+FEINAI_EOF
+```
+
+Plans are versioned automatically; `feinai plan add` always creates a new
+version (`v1`, `v2`, ...). Use this when refining a plan after review.
+
+### Pattern — create each task
+
+For every numbered task in the plan, create a row. Pass the task's workplan
+markdown as `--desc`:
+
+```bash
+feinai add TASK-042-A "Create auth schema" \
+  --spec SPEC-042 \
+  --desc "Define Drizzle schema for users table with email, password_hash, refresh_token columns. See specs/042-auth for column types." \
+  --package "@app/auth" \
+  --gate "pnpm --filter @app/auth typecheck" \
+  --gate "pnpm --filter @app/auth test -- --run"
+
+feinai add TASK-042-B "Add auth routes" \
+  --spec SPEC-042 \
+  --desc "POST /auth/login, POST /auth/refresh, POST /auth/logout. Validate via TypeBox." \
+  --package "@app/auth" \
+  --gate "pnpm --filter @app/auth typecheck" \
+  --gate "pnpm --filter @app/auth test -- --run" \
+  --blocked-by TASK-042-A
+
+feinai add TASK-042-C "Integration tests" \
+  --spec SPEC-042 \
+  --desc "End-to-end flow: register → login → refresh → logout." \
+  --package "@app/auth" \
+  --gate "pnpm --filter @app/auth test -- --run" \
+  --blocked-by TASK-042-A \
+  --blocked-by TASK-042-B
+```
+
+### Why each task lives in feinai instead of a checkbox in markdown
+
+A subagent claiming `TASK-042-A` calls `feinai take TASK-042-A` and gets, in a
+single response, the full payload: `description` (workplan), `quality_gates`,
+`packages`, `blocked_by`. **The subagent never has to read the plan markdown.**
+
+This is the single biggest token saving and the strongest correctness
+guarantee from using tasca: each subagent's context contains exactly the task
+it's executing, nothing else.
+
+---
+
+## Phase 3 — Subagent-driven-development → `feinai take` + `feinai done`
+
+When dispatching subagents, instruct each one to:
+
+1. Call `feinai take TASK-XXX` to atomically claim the task.
+2. Use the returned JSON for everything it needs:
+   - `description` — workplan
+   - `packages` — what to touch
+   - `quality_gates` — what to verify
+   - `spec_id` — context if needed (`feinai spec content SPEC-XXX`)
+3. Run the gates and write the code.
+4. Call `feinai done TASK-XXX --result "typecheck ✓ lint ✓ test ✓"` (or
+   `feinai fail TASK-XXX --error "..."` if gates fail).
+
+### Subagent prompt template
+
+When you dispatch a subagent for a task, include this in its prompt:
+
+> Your task is `TASK-XXX`. Begin by running `feinai take TASK-XXX`. The command
+> returns a JSON object with the full task description, packages to touch, and
+> quality gates to run. Use only that payload — do not read the plan markdown.
+>
+> When you finish the implementation and the quality gates pass, run
+> `feinai done TASK-XXX --result "<gates summary>"`. If the gates fail and you
+> cannot resolve, run `feinai fail TASK-XXX --error "<short reason>"` and stop.
+>
+> You are operating in a worktree at `<path>`. Do not switch branches.
+
+### Choosing the next task
+
+To find the next task that is **pending** and has no unresolved blockers:
+
+```bash
+feinai list --pending --json
+```
+
+In JSON output, filter for tasks whose `blocked_by` array is empty or whose
+blockers are all `completed`. Then `feinai take <id>`.
+
+Atomic `take` means: if you and another agent both call `feinai take TASK-X` at
+the same time, exactly one of you gets the task and the other gets an error.
+You can dispatch parallel subagents safely.
+
+### Marking the spec done
+
+When all tasks for a spec are `completed`, mark the spec done:
+
+```bash
+feinai spec done SPEC-042 --pr 123 --merged 2026-06-05
+```
+
+---
+
+## Visibility for the human
+
+The user can watch progress live by running `feinai server` in another terminal
+and opening `http://127.0.0.1:8272` in a browser. The dashboard streams events
+via SSE, so they see takes / dones / fails as they happen.
+
+If you anticipate the user will want to monitor a long-running multi-task
+workflow, suggest this once at the start of the session.
+
+---
+
+## Common pitfalls
+
+### ❌ Don't read the plan markdown to find tasks
+
+If you've created tasks via `feinai add`, **never** re-read the plan to figure
+out what to do next. Use `feinai list --pending --json`. The plan is the
+human-readable rationale; the tasks are the executable state.
+
+### ❌ Don't create `docs/superpowers/specs/*.md` files
+
+If tasca is active, those files become a source of drift. The spec lives in
+the database. If you need to publish the spec elsewhere (PR description, wiki,
+etc.), export it on demand: `feinai spec content SPEC-X > /tmp/spec.md`.
+
+### ❌ Don't skip `feinai take` and just read the task
+
+`feinai show TASK-X` is read-only and does **not** claim the task. Two
+subagents that both `show` then act will collide. Always `feinai take`.
+
+### ❌ Don't try to write to the SQLite file directly
+
+The CLI handles concurrency, audit logging, and validation. Direct SQL
+mutations bypass the events table and leave the audit log incomplete.
+
+### ✅ Do set `FEINA_USER` for explicit subagent identity
+
+When dispatching a subagent, pass `FEINA_USER=subagent-N` in its environment
+so the audit log distinguishes which subagent did what. Otherwise the actor
+field will read `bun:<pid>:<user>` for everyone.
+
+---
+
+## Quick reference
+
+| Need | Command |
+|---|---|
+| Is tasca set up here? | `feinai status` |
+| Next pending task | `feinai list --pending --json` |
+| Claim a task atomically | `feinai take TASK-X` |
+| Read a spec | `feinai spec content SPEC-X` |
+| Read the latest plan | `feinai plan show SPEC-X` |
+| Create spec from stdin | `feinai spec add SPEC-X "title" --stdin <<<` markdown |
+| Update spec content | `feinai spec set-content SPEC-X --stdin <<<` markdown |
+| Add a plan version | `feinai plan add SPEC-X --stdin <<<` markdown |
+| Create task | `feinai add TASK-X "subject" --spec SPEC-X --desc "..." --gate "..." --package "..." [--blocked-by TASK-Y]` |
+| Mark task done | `feinai done TASK-X --result "..."` |
+| Mark task failed | `feinai fail TASK-X --error "..."` |
+| Mark spec done | `feinai spec done SPEC-X --pr N --merged DATE` |
+| Live dashboard | `feinai server` then open `http://127.0.0.1:8272` |
+
+---
+
+## Relationship to superpowers skills
+
+This skill is **additive**. The superpowers skills (`brainstorming`,
+`writing-plans`, `subagent-driven-development`, etc.) still run; they still
+own the process. tasca only changes the storage of the artifacts they produce.
+
+If you start brainstorming and discover the project has no tasca DB, fall back
+to the normal superpowers behavior (markdown files). Do not silently switch
+storage strategy mid-project.

package/skills/feinai-write-spec/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: feinai-write-spec
+description: Use when the user wants to design a new feature, refactor, or change in a project that has `.tasca/tasca.db`. Writes a complete spec + plan into tasca in a single session. Replaces `brainstorming` + `writing-plans` from superpowers when feinai is active. Reads project context (CLAUDE.md, ARCHITECTURE.md, README.md), asks clarifying questions only when context has gaps, and produces spec+plan atomically with one `feinai spec add` + one `feinai plan add`.
+---
+
+# feinai-write-spec
+
+Write a spec + plan for a feature in one session. Output goes to tasca, not markdown files.
+
+## Preconditions
+
+Run `feinai status` (exit 0 = tasca is active). If not active, stop and ask the
+user if they want `feinai init` or to fall back to vanilla superpowers.
+
+## The flow — three entry modes
+
+Decide which entry mode applies BEFORE doing anything else. Ask the user only if ambiguous.
+
+### Mode A — User has a clear idea
+"Add X feature to do Y." → proceed to **Phase 2** directly.
+
+### Mode B — User has no idea yet
+"What should we build next?" → propose 2–4 candidate features derived from
+BACKLOG.md, recent commits, or the project's stated goals. User picks one.
+→ proceed to **Phase 2**.
+
+### Mode C — User gives a tiny idea
+"Add a search bar." → BEFORE expanding, ask: *"Quick scope check: do you want this
+as a minimal change (just the input + endpoint call) or shall I think wider
+(filters, debounce, empty states, mobile UX)?"* User picks. → proceed to **Phase 2**.
+
+---
+
+## Phase 1 — Load project context
+
+Read **in this order, stop early if enough**:
+
+1. `CLAUDE.md` (root) — already in your context normally
+2. `.claude/ARCHITECTURE.md` or `ARCHITECTURE.md` (root)
+3. `README.md`
+4. `decisions/` directory (just file names, read only if a name matches the topic)
+
+If none exist or context is **insufficient or contradictory** for the spec at hand:
+
+- **Ask the user** with a short, targeted questionnaire (3–6 questions max)
+- Do not invent or assume. Do not guess architecture.
+- If you have permission, offer to write/update `ARCHITECTURE.md` after the spec is done — but **only ask permission once**, not per file.
+
+Keep this phase tight — every read costs tokens. Stop as soon as you can write the spec accurately.
+
+---
+
+## Phase 2 — Draft and write the spec
+
+**Spec answers: what and why.** Not how.
+
+Required sections:
+- **Goal** — one sentence
+- **Problem / motivation** — why this exists
+- **Scope** — what's in, what's out
+- **Contracts** — API shapes, data model changes, UI invariants (whichever apply)
+- **Tests required** — the behavioral cases that must pass
+
+**Pick the next SPEC ID:**
+```bash
+feinai spec list --json | jq -r '.[].id' | grep -oE 'SPEC-[0-9]+' | sort -V | tail -1
+# next = max + 1, or follow project convention if user gave one
+```
+
+**Write it atomically:**
+```bash
+feinai spec add SPEC-NNN "Short title" --stdin <<'FEINAI_EOF'
+# SPEC-NNN: Short title
+
+## Goal
+...
+
+## Problem
+...
+
+## Scope
+- In: ...
+- Out: ...
+
+## Contracts
+...
+
+## Tests required
+- ...
+FEINAI_EOF
+```
+
+---
+
+## Phase 3 — Draft and write the plan
+
+**Plan answers: how.** Architecture decisions, file map, dependencies.
+
+Required sections:
+- **Architecture overview** — 2–4 sentences
+- **Files to touch** — explicit list
+- **Task breakdown preview** — high-level (the actual tasks are written by `feinai-write-tasks`)
+- **Quality gates** — the commands that prove correctness
+
+**Write the plan:**
+```bash
+feinai plan add SPEC-NNN --stdin <<'FEINAI_EOF'
+# Plan v1 — SPEC-NNN: Title
+
+## Architecture overview
+...
+
+## Files to touch
+- packages/X/...
+- packages/Y/...
+
+## Task breakdown preview
+- TASK-NNN-A: <what>
+- TASK-NNN-B: <what> (blocked by A)
+- ...
+
+## Quality gates
+pnpm --filter @X typecheck
+pnpm --filter @X test -- --run
+FEINAI_EOF
+```
+
+---
+
+## Phase 4 — Hand off
+
+Tell the user:
+> Spec + plan written: SPEC-NNN. View with `feinai spec show SPEC-NNN --full`.
+> Next step: run `/feinai-write-tasks SPEC-NNN` to break it down into executable tasks.
+
+Do NOT create tasks here. That's `feinai-write-tasks`. One responsibility per skill.
+
+---
+
+## Key questions to ask (during, only if needed)
+
+These come up mid-session. Ask them inline, one at a time, brief:
+
+- Ambiguity in scope: *"Do we include X in this spec or punt to a follow-up?"*
+- Missing architecture decision: *"This needs a choice between A and B. Default is A unless you say otherwise."*
+- Architecture gap: *"ARCHITECTURE.md doesn't cover X. Want me to add a note after the spec is done?"*
+
+**Do not batch questions.** Ask one, get answer, move on. Most specs need 0–2 questions.
+
+---
+
+## What NOT to do
+
+- ❌ Write `docs/superpowers/specs/*.md` files — spec lives in feinai
+- ❌ Create tasks in this skill — that's `feinai-write-tasks`
+- ❌ Invent architecture if `ARCHITECTURE.md` is silent — ask the user
+- ❌ Write spec content that is actually a plan (HOW). Keep them separated.
+- ❌ Ask the user to confirm before writing — write the spec, then they review with `feinai spec show`
+
+---
+
+## Subagent isolation
+
+If you delegate the spec drafting to a subagent (e.g. for parallel research),
+the subagent must NOT use this skill — it has no context. Hand it concrete
+findings and let it return text; you write to tasca yourself.
+
+---
+
+## Quick reference
+
+| Need | Command |
+|---|---|
+| Next free SPEC ID | `feinai spec list --json \| jq -r '.[].id'` |
+| Write spec | `feinai spec add SPEC-N "title" --stdin <<<` content |
+| Update spec content | `feinai spec set-content SPEC-N --stdin <<<` content |
+| Write plan | `feinai plan add SPEC-N --stdin <<<` content |
+| Show spec+plan together | `feinai spec show SPEC-N --full` |