feinai 0.6.6 → 0.7.0

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 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.7.0] - 2026-06-22
+
+### Added
+- **Project-scoped server port tracking** (`server_state` table in `feinai.db`)
+  - `feinai status` now validates & repairs the server record before printing the exact project URL
+  - `feinai server` auto-increments from port 8272 when the default is busy
+  - `feinai server --down` targets the recorded pid/port for this project
+  - Graceful shutdown clears the server record from the DB
+- 6 unit tests for server-state DB operations
+
+### Changed
+- **Normalized language**: removed all "Claude Code" and provider-specific references across CLI, README, and skill files
+- `feinai-implement` skill fully translated from Spanish to English
+- `CLAUDE.md` references → `AGENTS.md`, `.claude/ARCHITECTURE.md` → `ARCHITECTURE.md`
+- `formatStatus` accepts optional `serverUrl` parameter
+
 ## [0.6.3] - 2026-06-11
 
 ### Fixed

package/README.md

@@ -109,28 +109,26 @@ Agents don't parse `QUEUE.md`. They talk to a small local coordination service i
 
 ---
 
-## Claude Code skills
+## Agent harness skills
 
-feinai ships five Claude Code skills covering the full development loop. They activate automatically when `.feinai/feinai.db` is present:
+feinai ships three skills covering the full development loop. They activate automatically when `.feinai/feinai.db` is present:
 
-| Skill               | Purpose                                                |
-|---------------------|--------------------------------------------------------|
-| `feinai-sdd`        | Teaches Claude the feinai workflow and concepts        |
-| `feinai-write-spec` | Writes spec + plan into feinai from a design thread    |
-| `feinai-write-tasks`| Decomposes a plan into atomic tasks with parallelism   |
-| `feinai-dispatch`   | Orchestrates subagents in isolated git worktrees       |
-| `feinai-implement`  | Claims and executes one task end‑to‑end                |
+| Skill               | Purpose                                                                          |
+|---------------------|----------------------------------------------------------------------------------|
+| `feinai-write-spec` | Full pipeline: spec + plan + tasks. With no argument runs the complete flow; with a SPEC-ID argument regenerates tasks only (use when iterating on an existing plan) |
+| `feinai-dispatch`   | Orchestrates subagents in isolated git worktrees                                 |
+| `feinai-implement`  | Claims and executes one task end‑to‑end                                          |
 
 Together they cover: design → spec → plan → tasks → parallel execution → merge.
 
-### Activating skills in Claude Code
+### Activating skills
 
 ```sh
-mkdir -p ~/.claude/skills
+mkdir -p <your-harness-skills-dir>
 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
+for skill in feinai-write-spec feinai-dispatch feinai-implement; do
+  ln -sf "$SKILLS/$skill" <your-harness-skills-dir>/$skill
 done
 ```
 
@@ -151,7 +149,7 @@ This installs:
 
 ### PATH setup (non‑interactive SSH)
 
-In interactive shells and for local agents (Claude Code, opencode) it should work out of the box.
+In interactive shells and for local coding agents it should work out of the box.
 
 For non‑interactive SSH sessions (e.g. `ssh host 'feinai status'`), you may need a one‑time setup:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "feinai",
-  "version": "0.6.6",
+  "version": "0.7.0",
   "description": "Task & spec manager for AI agents — parallel worktrees, live dashboard, SDD skills",
   "type": "module",
   "bin": {
@@ -21,7 +21,6 @@
   "keywords": [
     "task-manager",
     "sdd",
-    "claude-code",
     "ai-agents",
     "sqlite",
     "cli",

package/skills/feinai-dispatch/SKILL.md

@@ -76,19 +76,19 @@ feinai is installed but no DB in this project. Ask the user:
 
 ---
 
-### Failure: skills not activating in Claude Code
+### Failure: skills not activating in your agent harness
 
-If Claude Code doesn't recognize `feinai-dispatch` or other skills after install:
+If your agent harness doesn't recognize `feinai-dispatch` or other skills after install:
 
 > Run this to activate the skills:
 > ```bash
-> mkdir -p ~/.claude/skills
+> mkdir -p <your-harness-skills-dir>
 > 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
+>   ln -sf "$SKILLS/$skill" <your-harness-skills-dir>/$skill
 > done
 > ```
-> Then restart Claude Code.
+> Then restart your agent harness.
 
 **Offer to run it.**
 
@@ -162,7 +162,7 @@ For each iteration:
 For each task to dispatch:
 
 ```bash
-git worktree add .claude/worktrees/TASK-X-id <branch>
+git worktree add .worktrees/TASK-X-id <branch>
 ```
 
 Branch naming: `feature/TASK-X-id-slug` derived from the subject.
@@ -171,7 +171,7 @@ Branch naming: `feature/TASK-X-id-slug` derived from the subject.
 
 ```bash
 feinai take TASK-X --json   # atomic claim, sin worktree aún
-feinai task edit TASK-X --worktree .claude/worktrees/TASK-X-id
+feinai task edit TASK-X --worktree .worktrees/TASK-X-id
 ```
 
 Order matters: take first (atomic reservation), then edit to record the worktree path.
@@ -218,7 +218,7 @@ 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`
+3. Remove the worktree: `git worktree remove .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.
@@ -270,7 +270,7 @@ When `feinai list --spec SPEC-NNN --pending --json` returns empty:
 
 ### Worktree rules (non-negotiable)
 
-- ✅ Each task gets its own worktree under `.claude/worktrees/`
+- ✅ Each task gets its own worktree under `.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

package/skills/feinai-implement/SKILL.md

@@ -17,117 +17,117 @@ If any fails: stop and report. Do not improvise.
 
 ---
 
-## AL ARRANCAR
+## On startup
 
-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á
+1. `feinai list --pending --json` — find the first available task (no pending blockers)
+2. If none exists → respond "No pending tasks" and stop
+3. `feinai take <TASK-ID> --owner implement-agent` — claim it atomically
+4. If the task has `spec_id` → `feinai spec content <SPEC-ID>` for context
+5. If the task has `blocked_by` with uncompleted tasks → release with `feinai release <TASK-ID>` and stop
 
-Leé `AGENTS.md` del proyecto para arquitectura y convenciones del proyecto específico.
+Read `AGENTS.md` of the project for architecture and project-specific conventions.
 
 ---
 
-## Ejecutar la tarea
+## Execute the task
 
-**Paso 1 — Worktree aislado:**
+**Step 1 — Isolated worktree:**
 ```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.
+**Step 2 — Worktree setup:**
+Install dependencies if the project requires them. Check `AGENTS.md` of the project for the exact command.
 
-**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
+**Step 3 — Read before writing:**
+- The full task description (`feinai show <TASK-ID>`)
+- The files you will touch — read them before editing
+- If there is a **Workplan** in the description → follow those steps in exact order
 
-**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
+**Step 4 — Implement:**
+Exactly what the task says. No more, no less.
+- Do not touch files outside the task scope
+- If a file "to create" already exists → extend it instead of overwriting if it already contains valid content
 
-**Paso 5 — Commit:**
-Un commit por tarea. Conventional commits:
+**Step 5 — Commit:**
+One commit per task. Conventional commits:
 ```
-feat(scope): descripción concisa
+feat(scope): concise description
 ```
-Tipos: `feat`, `fix`, `refactor`, `test`, `chore`.
+Types: `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.
+**Step 6 — Quality gates:**
+Run the gates defined in the task (`quality_gates`). If the task does not specify them, check `AGENTS.md` of the project for default gates.
 
-**Paso 7 — Cerrar:**
+**Step 7 — Close:**
 
-Gates pasan:
+Gates pass:
 ```bash
-# Desde el worktree:
+# From the worktree:
 feinai git push origin HEAD:main
 
-# Desde la raíz del repo:
+# From the repo root:
 feinai git worktree remove .worktrees/<TASK-ID>
 feinai git complete
 
 feinai done <TASK-ID> --result "gates ✓"
 ```
 
-Gates fallan → seguí "Si algo falla".
+Gates fail → follow "If something fails".
 
-**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 feinai
+**Done = 3 observable facts:**
+1. Quality gates pass without errors
+2. The task files exist with correct content
+3. Clean commit on `main` and task status `completed` in feinai
 
 ---
 
-## Si algo falla
+## If something fails
 
-Gates fallan, push falla, o error en cualquier paso:
+Gates fail, push fails, or error at any step:
 
-1. **No limpies el worktree**
-2. Push a rama backup:
+1. **Do not clean the worktree**
+2. Push to a backup branch:
    ```bash
    feinai git push origin HEAD:backup/<TASK-ID>
    ```
-3. Marcá la tarea como fallida:
+3. Mark the task as failed:
    ```bash
-   feinai fail <TASK-ID> --error "<comando exacto + output relevante>"
+   feinai fail <TASK-ID> --error "<exact command + relevant output>"
    ```
-4. Dejá el worktree intacto para recuperación manual
+4. Leave the worktree intact for manual recovery
 
 ---
 
-## Git — `feinai git` exclusivamente
+## Git — `feinai git` exclusively
 
-`git` y `gh` están bloqueados. Usá `feinai git` para todo — es opengit bundleado con feinai.
+`git` and `gh` are blocked. Use `feinai git` for everything — it is opengit bundled with feinai.
 
-**Permitido:**
+**Allowed:**
 - `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)
+- `feinai git complete` — syncs local main after push (only from repo root)
 
-**Prohibido:**
-- `feinai git branch`, `checkout`, `switch` — nunca cambiar branches
+**Prohibited:**
+- `feinai git branch`, `checkout`, `switch` — never switch 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
+- `feinai git worktree remove` — only after successful push
 
-Si `feinai git` falla → **STOP**. No reintentes, no uses `git`. Reportá al usuario.
+If `feinai git` fails → **STOP**. Do not retry, do not use `git`. Report to the user.
 
 ---
 
-## Reglas absolutas
+## Absolute rules
 
-**No modifiques:**
+**Do not modify:**
 - `AGENTS.md`, `CLAUDE.md`
-- Archivos de configuración de CI/CD, infra, o secretos (`.env`, `.env.*`)
-- La DB de feinai directamente
+- CI/CD, infrastructure, or secret configuration files (`.env`, `.env.*`)
+- The feinai DB directly
 
-**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
+**Code:**
+- No `any` without a justified comment on the same line
+- If a test fails: fix either the test or the implementation. Never silence, skip, or add workarounds to make the gate "pass"
+- If the cause is not obvious → **STOP**, report to the user with the exact command and the full output

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

@@ -1,18 +1,31 @@
 ---
 name: feinai-write-spec
-description: Use when the user wants to design a new feature, refactor, or change in a project that has `.feinai/feinai.db`. Writes a complete spec + plan into feinai 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`.
+description: Use when the user wants to design a new feature, refactor, or change in a project that has `.feinai/feinai.db`. With no argument, runs the full pipeline (spec + plan + tasks). With a SPEC-ID argument, skips to task generation only (use when iterating on an existing plan). Replaces `brainstorming` + `writing-plans` + `feinai-write-tasks` from superpowers when feinai is active.
 ---
 
 # feinai-write-spec
 
-Write a spec + plan for a feature in one session. Output goes to feinai, not markdown files.
+Full pipeline: spec → plan → tasks. One skill, two entry points.
+
+## Entry point detection
+
+**Check the first argument before doing anything else.**
+
+- **No argument** → full pipeline (Phases 1–5)
+- **SPEC-ID given** (e.g. `SPEC-42`) → tasks only, jump to **Phase 4**
+
+Ask the user which mode only if ambiguous.
+
+---
 
 ## Preconditions
 
 Run `feinai status` (exit 0 = feinai 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
+---
+
+## Phase 1 — Decide entry mode (full pipeline only)
 
 Decide which entry mode applies BEFORE doing anything else. Ask the user only if ambiguous.
 
@@ -31,12 +44,12 @@ as a minimal change (just the input + endpoint call) or shall I think wider
 
 ---
 
-## Phase 1 — Load project context
+## Phase 2 — Load project context (full pipeline only)
 
 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)
+1. `AGENTS.md` (root) — already in your context normally
+2. `ARCHITECTURE.md` (root)
 3. `README.md`
 4. `decisions/` directory (just file names, read only if a name matches the topic)
 
@@ -50,9 +63,9 @@ Keep this phase tight — every read costs tokens. Stop as soon as you can write
 
 ---
 
-## Phase 2 — Draft and write the spec
+## Phase 3 — Draft and write the spec + plan (full pipeline only)
 
-**Spec answers: what and why.** Not how.
+### Spec (what and why — not how)
 
 Required sections:
 - **Goal** — one sentence
@@ -90,19 +103,14 @@ feinai spec add SPEC-NNN "Short title" --stdin <<'FEINAI_EOF'
 FEINAI_EOF
 ```
 
----
-
-## Phase 3 — Draft and write the plan
-
-**Plan answers: how.** Architecture decisions, file map, dependencies.
+### Plan (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`)
+- **Task breakdown preview** — high-level (the actual tasks come in Phase 4)
 - **Quality gates** — the commands that prove correctness
 
-**Write the plan:**
 ```bash
 feinai plan add SPEC-NNN --stdin <<'FEINAI_EOF'
 # Plan v1 — SPEC-NNN: Title
@@ -127,19 +135,112 @@ FEINAI_EOF
 
 ---
 
-## Phase 4 — Hand off
+## Phase 4 — Build the task graph
 
-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.
+*Entry point when SPEC-ID is given as argument.*
+
+### Step 1 — Load spec + plan
+
+```bash
+feinai spec show SPEC-NNN --full
+```
+
+Read both. Internalize:
+- The WHAT (spec)
+- The HOW (plan)
+- The "Files to touch" list
+- The "Task breakdown preview" — your starting point, not a contract
+
+### Step 2 — Analyze granularity and parallelism
+
+**A. Granularity** — one task = one logical change a single subagent can complete in one session.
+- Too big: "implement the entire auth system" → split by route
+- Too small: "add a single import" → merge into larger task
+- Sweet spot: ~50–300 lines, 1–3 files
+
+**B. Parallelism rule — no exceptions:**
+
+> **Tasks that touch the same file cannot run in parallel.**
+
+When a **shared file** needs changes (e.g. `router.ts`, `index.ts`, schema), extract it first:
+
+```
+TASK-NNN-0: edit shared file once
+   ↓ blocks
+TASK-NNN-1: feature A  ┐
+TASK-NNN-2: feature B  ├ parallel
+TASK-NNN-3: feature C  ┘
+```
 
-Do NOT create tasks here. That's `feinai-write-tasks`. One responsibility per skill.
+**C. Dependencies** — use `--blocked-by` for:
+- File-level conflicts (above)
+- Logical dependencies (B uses a type defined in A)
+
+### Step 3 — Embed TDD instructions
+
+Each implementation task description starts with:
+
+```
+## TDD baseline
+Write the tests first based on the "Tests required" section of SPEC-NNN.
+Run them — they must fail (the implementation doesn't exist yet).
+Implement until all tests pass. Then run the quality gates.
+```
+
+No separate "write tests" tasks. Test + implementation live together.
+
+**Exception:** if shared fixtures are needed across tasks, extract them into a tiny TASK-NNN-0 that others block on.
+
+### Step 4 — Write the tasks
+
+```bash
+feinai add TASK-NNN-X "subject" \
+  --spec SPEC-NNN \
+  --desc "$(cat <<'EOF'
+## TDD baseline
+Write the tests first based on the "Tests required" section of SPEC-NNN.
+Run them — they must fail. Implement until they pass.
+
+## Files to touch
+- packages/X/...
+- packages/Y/...
+
+## Implementation notes
+<concrete, copy-pasteable details. Cite line numbers if useful.>
+
+## Do not touch
+- <files explicitly out of scope>
+EOF
+)" \
+  --package "@scope/pkg" \
+  --gate "pnpm --filter @scope/pkg typecheck" \
+  --gate "pnpm --filter @scope/pkg test -- --run" \
+  --blocked-by TASK-NNN-Y    # repeatable if needed
+```
+
+**Task description = self-contained.** The subagent reads only the task (via `feinai take`) and gets spec+plan as `spec_context` automatically.
 
 ---
 
-## Key questions to ask (during, only if needed)
+## Phase 5 — Hand off
+
+Output a parallelism summary table:
+
+```
+TASK-NNN-0: shared file edit            (sequential)
+TASK-NNN-1: feature A                   (parallel with 2, 3) blocked-by 0
+TASK-NNN-2: feature B                   (parallel with 1, 3) blocked-by 0
+TASK-NNN-3: feature C                   (parallel with 1, 2) blocked-by 0
+TASK-NNN-4: integration tests           (sequential)         blocked-by 1, 2, 3
+```
+
+Tell the user:
+> Tasks written for SPEC-NNN. View with `feinai list --spec SPEC-NNN`.
+> Next step: run `/feinai-dispatch SPEC-NNN` to execute.
+
+---
 
-These come up mid-session. Ask them inline, one at a time, brief:
+## Key questions to ask (inline, only if needed)
 
 - 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."*
@@ -152,18 +253,19 @@ These come up mid-session. Ask them inline, one at a time, brief:
 ## 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`
+- ❌ Ask the user to confirm before writing — write spec/plan/tasks, then they review
+- ❌ Re-think architecture in Phase 4 — it's in the plan, follow it
+- ❌ Write tasks without a SPEC-ID — every task must have `--spec SPEC-NNN`
+- ❌ Skip the same-file analysis — it's the single biggest cause of merge conflicts
+- ❌ Hardcode worktree paths — `feinai-dispatch` assigns those at execution time
 
 ---
 
 ## 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 feinai yourself.
+If you delegate spec drafting to a subagent, the subagent must NOT use this skill. Hand it concrete findings and let it return text; you write to feinai yourself.
 
 ---
 
@@ -176,3 +278,6 @@ findings and let it return text; you write to feinai yourself.
 | 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` |
+| List tasks for spec | `feinai list --spec SPEC-N` |
+| Add task | `feinai add TASK-X "subject" --spec SPEC-N --desc "..." --gate "..." [--blocked-by TASK-Y]` |
+| Edit task | `feinai task edit TASK-X --desc "..." --gate "..."` |

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

@@ -1,6 +1,6 @@
 ---
 name: feinai-write-tasks
-description: Use when a spec + plan already exist in feinai (written by `feinai-write-spec` or manually) and need to be broken down into executable tasks. Decomposes the plan into atomic `feinai add` calls, analyzes file-level parallelism, and embeds TDD instructions. Output: a set of tasks with `blocked_by` dependencies ready for `feinai-dispatch` to execute.
+description: "Use when a spec + plan already exist in feinai (written by `feinai-write-spec` or manually) and need to be broken down into executable tasks. Decomposes the plan into atomic `feinai add` calls, analyzes file-level parallelism, and embeds TDD instructions. Output: a set of tasks with `blocked_by` dependencies ready for `feinai-dispatch` to execute."
 ---
 
 # feinai-write-tasks