feinai 0.5.5 → 0.5.7

package/README.md

@@ -165,7 +165,7 @@ tasks   — atomic work units with blocked_by, quality_gates, worktree
 events  — append-only audit log: {parent_process}:{pid}:{user}
 ```
 
-Every mutation is logged. Every agent is identified. Override identity with `$FEINA_USER`.
+Every mutation is logged. Every agent is identified. Override identity with `$FEINAI_USER`.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "feinai",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "description": "Task & spec manager for AI agents — parallel worktrees, live dashboard, SDD skills",
   "type": "module",
   "bin": {

package/skills/feinai-dispatch/SKILL.md

@@ -7,45 +7,102 @@ description: Use when tasks exist in feinai for a spec and need to be executed.
 
 Execute the pending tasks of a SPEC. One responsibility: dispatch subagents in worktrees, integrate their output, handle failures.
 
-## Preconditions
+## Preconditions — environment check
 
-Before anything else, verify the environment:
+Run this first:
 
 ```bash
 feinai --version 2>&1
 feinai git status 2>&1
 ```
 
-**If `feinai: command not found` or `opengit: command not found`:**
+---
+
+### Failure: `feinai: command not found`
+
+feinai is not installed. Tell the user:
+
+> feinai is not installed. Install with:
+> ```bash
+> bun install -g feinai
+> ```
+> Full setup guide: https://www.npmjs.com/package/feinai
+
+**Offer to run it.** Do not proceed until `feinai --version` returns a version number.
+
+---
+
+### Failure: `feinai` found but `opengit: command not found`
+
+opengit ships with feinai — if it's missing, the install is incomplete. Tell the user:
+
+> opengit is missing. Reinstall feinai:
+> ```bash
+> bun remove -g feinai && bun install -g feinai
+> ```
+
+**Offer to run it.**
+
+---
 
-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.
+### Failure: `feinai --version` works but `feinai status` fails with command not found in a different shell
 
-Tell the user:
+PATH issue in non-interactive SSH session. `~/.bun/bin` is not loaded. Tell the user:
 
-> `feinai` (or `opengit`) is not on PATH in this shell context. This happens in non-interactive SSH sessions where `~/.bun/bin` is not loaded.
+> feinai is installed but not on PATH in this shell context (common in non-interactive SSH sessions).
 >
-> Fix with a one-time symlink (requires sudo/root):
+> Fix with a one-time symlink (requires root):
 > ```bash
 > sudo ln -sf ~/.bun/bin/feinai /usr/local/bin/feinai
 > sudo ln -sf ~/.bun/bin/opengit /usr/local/bin/opengit
 > sudo ln -sf ~/.bun/bin/bun /usr/local/bin/bun
 > ```
-> Or if root access is available via a different user (e.g. `do-hermes`):
+> Or via root SSH if available:
 > ```bash
-> 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"
+> ssh root@<host> "ln -sf /home/<user>/.bun/bin/feinai /usr/local/bin/feinai && ln -sf /home/<user>/.bun/bin/opengit /usr/local/bin/opengit && ln -sf /home/<user>/.bun/bin/bun /usr/local/bin/bun"
 > ```
->
-> Want me to run this fix now?
 
-**Do not proceed until `feinai --version` returns a version number.**
+**Offer to run it.** Full docs: https://www.npmjs.com/package/feinai
+
+---
+
+### Failure: `feinai status` exits with code 2 (`no .tasca/tasca.db found`)
+
+feinai is installed but no DB in this project. Ask the user:
+
+> No feinai DB found in this directory. Run `feinai init` to create one?
+
+**Offer to run `feinai init`.**
+
+---
+
+### Failure: skills not activating in Claude Code
+
+If Claude Code doesn't recognize `feinai-dispatch` or other skills after install:
+
+> Run this to activate the skills:
+> ```bash
+> mkdir -p ~/.claude/skills
+> SKILLS=~/.bun/install/global/node_modules/feinai/skills
+> for skill in feinai-sdd feinai-write-spec feinai-write-tasks feinai-dispatch feinai-implement; do
+>   ln -sf "$SKILLS/$skill" ~/.claude/skills/$skill
+> done
+> ```
+> Then restart Claude Code.
+
+**Offer to run it.**
+
+---
 
-Then verify:
+**Do not proceed to dispatch until all checks pass:**
 
-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)
+1. `feinai --version` returns a version number
+2. `feinai git status` runs without error
+3. `feinai status` exits 0 (DB found)
+4. The SPEC has pending tasks: `feinai list --spec SPEC-NNN --pending --json` returns non-empty
+5. Current working directory is a clean git repo
 
-If any fails: stop and report. Do not improvise.
+If any fails: stop, diagnose, offer the fix above.
 
 ## Input
 

package/skills/feinai-sdd/SKILL.md

@@ -3,7 +3,7 @@ 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 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
@@ -20,7 +20,7 @@ just change *where the artifacts get stored*.
 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).
+   the current working directory; feinai 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
@@ -41,10 +41,20 @@ Before any spec / plan / task write, run:
 feinai status 2>/dev/null
 ```
 
-- Exit code 0: tasca is active in this project → use this skill.
+- Exit code 0: feinai 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.
+- Command not found: feinai is not installed or not on PATH. Tell the user:
+
+  > `feinai` is not found. Install it with:
+  > ```bash
+  > bun install -g feinai
+  > ```
+  > Full documentation and setup guide: https://www.npmjs.com/package/feinai
+  >
+  > If already installed but not found in this shell context (non-interactive SSH), see the PATH setup section in the docs above.
+
+  Stop and wait for the user to confirm it's fixed before continuing.
 
 ---
 
@@ -86,7 +96,7 @@ FEINAI_EOF
 
 ### What replaces what
 
-| Superpowers step | tasca equivalent |
+| Superpowers step | feinai 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) |
@@ -159,7 +169,7 @@ 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
+guarantee from using feinai: each subagent's context contains exactly the task
 it's executing, nothing else.
 
 ---
@@ -238,7 +248,7 @@ 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
+If feinai 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`.
 
@@ -252,9 +262,9 @@ subagents that both `show` then act will collide. Always `feinai take`.
 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
+### ✅ Do set `FEINAI_USER` for explicit subagent identity
 
-When dispatching a subagent, pass `FEINA_USER=subagent-N` in its environment
+When dispatching a subagent, pass `FEINAI_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.
 
@@ -284,8 +294,8 @@ field will read `bun:<pid>:<user>` for everyone.
 
 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.
+own the process. feinai only changes the storage of the artifacts they produce.
 
-If you start brainstorming and discover the project has no tasca DB, fall back
+If you start brainstorming and discover the project has no feinai DB, fall back
 to the normal superpowers behavior (markdown files). Do not silently switch
 storage strategy mid-project.

package/src/cli.ts

@@ -48,7 +48,7 @@ import {
   type OutputFormat,
 } from "./format";
 
-const VERSION = "0.5.5";
+const VERSION = "0.5.7";
 
 interface ParsedArgs {
   positional: string[];
@@ -126,7 +126,7 @@ function detectFormat(args: ParsedArgs): OutputFormat {
  * Build a stable identifier for whoever is invoking feina.
  *
  * Priority:
- *   1. $FEINA_USER env var (explicit override — used by agents to identify themselves)
+ *   1. $FEINAI_USER env var (explicit override — used by agents to identify themselves)
  *   2. parent process name (on Linux via /proc/$PPID/comm) → "{parent_name}:{ppid}:{user}"
  *   3. fallback: "{user}@{hostname}"
  *
@@ -134,7 +134,7 @@ function detectFormat(args: ParsedArgs): OutputFormat {
  * from "bash:9999:m" in the events audit log without manual configuration.
  */
 function getCurrentUser(): string {
-  const override = process.env.FEINA_USER;
+  const override = process.env.FEINAI_USER;
   if (override) return override;
 
   const username = process.env.USER ?? userInfo().username ?? "unknown";
@@ -259,7 +259,7 @@ GLOBAL FLAGS:
   --version                         Show version
 
 ENV:
-  FEINA_USER                        Override owner/actor identity used in audit log
+  FEINAI_USER                        Override owner/actor identity used in audit log
 
 \x1b[34m\x1b[1m── Agent Integration ──────────────────────────────────────────────\x1b[0m
   \x1b[36mTeach your AI agents to use \x1b[1mfeina\x1b[0m\x1b[36m as their single source of truth for\x1b[0m