@web42/stask 0.2.1 → 0.2.2

package/.agents/skills/stask-general/SKILL.md

@@ -7,6 +7,26 @@ description: Task lifecycle framework — spec-first workflow, Slack sync, statu
 
 SQLite-backed task lifecycle management with Slack sync. Every operation goes through the `stask` CLI — the database enforces all lifecycle rules via triggers and constraints, and every mutation syncs to Slack atomically.
 
+## Multi-Project Support
+
+stask supports multiple projects. Each project lives in a repo with a `.stask/` folder at its root (like `.git/`).
+
+- **Auto-detection:** stask walks up from cwd to find `.stask/config.json`. If you're in a project repo or its worktree, it auto-detects.
+- **Explicit selection:** Use `--project <name>` flag on any command to target a specific project.
+- **Project registry:** `npx @web42/stask projects` lists all registered projects.
+- **Cross-project heartbeat:** `npx @web42/stask heartbeat-all <agent>` returns pending work across all projects.
+- **New project:** `npx @web42/stask init <name> --repo <path>` scaffolds a new project.
+- **Secrets:** `SLACK_TOKEN` comes from env var or `~/.stask/config.json` (no `.env` files).
+
+### Multi-project commands
+
+| Command | Purpose |
+|---------|---------|
+| `npx @web42/stask init <name> --repo <path>` | Create a new stask project |
+| `npx @web42/stask projects [show <name>]` | List/show registered projects |
+| `npx @web42/stask heartbeat-all <agent-name>` | Get pending work across all projects |
+| `--project <name>` | Global flag — target a specific project |
+
 ## Core Rules
 
 1. **No task exists without a spec uploaded to Slack.** Every task must have a Spec value: `specs/<name>.md (F0XXXXXXXXX)`.
@@ -103,7 +123,7 @@ Guards run automatically before transitions. Checks run first (read-only); if al
 
 ## Thread Communication
 
-Every task has a dedicated Slack thread linked to its list item. The thread reference (`channelId` + `threadTs`) is stored in the DB and included in `stask show` and `heartbeat` output.
+Every task has a dedicated Slack thread linked to its list item. The thread reference (`channelId` + `threadTs`) is stored in the DB and included in `npx @web42/stask show` and `heartbeat` output.
 
 **All agents MUST post updates to the task thread at every step.** Use the Slack API `chat.postMessage` with the thread's `channel` and `thread_ts` to post replies. The thread is the single place for all task communication.
 
@@ -137,7 +157,7 @@ Use the `SLACK_TOKEN` from the environment for authorization.
 
 ## Rules for All Agents
 
-1. **Never edit tracker.db directly.** Use `stask` commands only.
+1. **Never edit tracker.db directly.** Use `npx @web42/stask` commands only.
 2. **Every task needs a spec.** No exceptions.
 3. **Work in the task worktree.** Never in the main repo checkout.
 4. **Commit and push before marking done.** Guards will block Testing if you don't.

package/.agents/skills/stask-lead/SKILL.md

@@ -13,8 +13,8 @@ stask supports multiple projects. Each project lives in a repo with a `.stask/`
 
 - **Auto-detection:** If you're inside a project repo (or its worktree), stask auto-detects the project.
 - **Explicit selection:** Use `--project <name>` when working outside the repo or across projects.
-- **Discover projects:** Run `stask projects` to list all registered projects.
-- **Cross-project heartbeat:** Run `stask heartbeat-all <your-name>` to see pending work across all projects.
+- **Discover projects:** Run `npx @web42/stask projects` to list all registered projects.
+- **Cross-project heartbeat:** Run `npx @web42/stask heartbeat-all <your-name>` to see pending work across all projects.
 
 When heartbeat returns tasks with a `project` field, include `--project <name>` in all subsequent stask commands for that task.
 
@@ -37,14 +37,14 @@ You follow a strict 6-phase process. Never skip a phase.
 - Save to `../shared/specs/<task-name>.md`
 
 ### Phase 4: Approval & Delegation
-- Create task via `stask create` (uploads spec to Slack, creates in tracker.db)
-- Wait for Yan to check `spec_approved` or run `stask approve`
+- Create task via `npx @web42/stask create` (uploads spec to Slack, creates in tracker.db)
+- Wait for Yan to check `spec_approved` or run `npx @web42/stask approve`
 - Create subtasks using the breakdowns from Phase 2
 - Transition to In-Progress (auto-creates worktree + branch)
 
 ### Phase 5: Implementation (Spawn Workers)
 - Spawn workers with Implementation Prompts referencing their spec section
-- Monitor via `stask heartbeat richard`
+- Monitor via `npx @web42/stask heartbeat richard`
 - When all subtasks Done → auto-transitions to Testing
 
 ### Phase 6: QA → Review → Done
@@ -57,44 +57,44 @@ You follow a strict 6-phase process. Never skip a phase.
 
 | Command | When |
 |---------|------|
-| `stask heartbeat <your-name>` | Check what work you have pending |
-| `stask heartbeat-all <your-name>` | Check work across ALL projects |
-| `stask show <task-id>` | View task details, subtasks, and status |
-| `stask subtask create --parent <id> --name "..." --assign <worker>` | Break work into subtasks |
-| `stask transition <task-id> In-Progress` | Start work (auto-creates worktree) |
-| `stask transition <task-id> "Ready for Human Review"` | After QA pass + PR created |
-| `stask transition <task-id> Done` | After Human merges the PR |
-| `stask pr-status <task-id>` | Check PR comments and merge status |
-| `stask assign <task-id> <name>` | Reassign a task |
-| `stask create --spec <path> --name "..." --type Feature` | Create new task with spec |
-| `stask spec-update <task-id> --spec <path>` | Update spec after Yan feedback |
-| `stask projects` | List all registered projects |
+| `npx @web42/stask heartbeat <your-name>` | Check what work you have pending |
+| `npx @web42/stask heartbeat-all <your-name>` | Check work across ALL projects |
+| `npx @web42/stask show <task-id>` | View task details, subtasks, and status |
+| `npx @web42/stask subtask create --parent <id> --name "..." --assign <worker>` | Break work into subtasks |
+| `npx @web42/stask transition <task-id> In-Progress` | Start work (auto-creates worktree) |
+| `npx @web42/stask transition <task-id> "Ready for Human Review"` | After QA pass + PR created |
+| `npx @web42/stask transition <task-id> Done` | After Human merges the PR |
+| `npx @web42/stask pr-status <task-id>` | Check PR comments and merge status |
+| `npx @web42/stask assign <task-id> <name>` | Reassign a task |
+| `npx @web42/stask create --spec <path> --name "..." --type Feature` | Create new task with spec |
+| `npx @web42/stask spec-update <task-id> --spec <path>` | Update spec after Yan feedback |
+| `npx @web42/stask projects` | List all registered projects |
 
 > **Tip:** Add `--project <name>` to any command when working outside the project repo or across multiple projects.
 
 ## When You Receive Work
 
 ### Spec Approved (To-Do, assigned to you)
-1. Read the spec (use the Slack file ID from `stask show`)
-2. Create subtasks: `stask subtask create --parent T-XXX --name "..." --assign <worker>`
-3. Transition: `stask transition T-XXX In-Progress`
+1. Read the spec (use the Slack file ID from `npx @web42/stask show`)
+2. Create subtasks: `npx @web42/stask subtask create --parent T-XXX --name "..." --assign <worker>`
+3. Transition: `npx @web42/stask transition T-XXX In-Progress`
 
 ### QA Passed (Testing, reassigned to you)
 1. Read the spec, QA report, git log, and diff
 2. Create a draft PR: `gh pr create --draft` in the worktree
 3. Write a rich PR description (summary, changes, QA results, screenshots)
-4. Transition: `stask transition T-XXX "Ready for Human Review"`
+4. Transition: `npx @web42/stask transition T-XXX "Ready for Human Review"`
 
 ### QA Failed (In-Progress, reassigned to you)
 1. Review the QA report — identify what failed
-2. Create NEW fix subtasks: `stask subtask create --parent T-XXX --name "Fix: ..." --assign <worker>`
+2. Create NEW fix subtasks: `npx @web42/stask subtask create --parent T-XXX --name "Fix: ..." --assign <worker>`
 3. Workers fix in the same worktree (same branch, same PR)
 4. When fix subtasks are Done, auto-transitions back to Testing
 
 ### PR Feedback (Ready for Human Review, detected by heartbeat)
 1. Read the feedback and judge:
    - **Code change needed** (bug, wrong behavior, missing feature):
-     - `stask transition T-XXX In-Progress`
+     - `npx @web42/stask transition T-XXX In-Progress`
      - Create fix subtasks, delegate to Workers
      - After fixes: QA re-tests, you update PR, transition back to RHR
    - **Cosmetic fix** (PR description, naming):
@@ -102,7 +102,7 @@ You follow a strict 6-phase process. Never skip a phase.
 2. The PR stays open. The branch stays the same. All prior data is preserved.
 
 ### PR Merged (detected by heartbeat)
-- Run `stask transition T-XXX Done`
+- Run `npx @web42/stask transition T-XXX Done`
 
 ## Key Rules
 

package/.agents/skills/stask-qa/SKILL.md

@@ -7,6 +7,10 @@ description: QA agent workflow — tests tasks against acceptance criteria, take
 
 You are **QA**. You test completed work against the spec's acceptance criteria. You produce evidence (screenshots, test output) and submit a verdict. Your reports are the basis for the Human's review.
 
+## Multi-Project Awareness
+
+stask supports multiple projects. If you're inside a project repo, stask auto-detects it. Otherwise use `--project <name>` on any command. Run `npx @web42/stask heartbeat-all <your-name>` to see work across all projects.
+
 ## Your Responsibilities
 
 1. **Check for work** using heartbeat

package/.agents/skills/stask-worker/SKILL.md

@@ -7,6 +7,10 @@ description: Worker agent workflow — implements subtasks in git worktrees, com
 
 You are a **Worker**. You implement subtasks assigned to you by the Lead. You write code in the task's git worktree, commit, push, and mark your subtask done.
 
+## Multi-Project Awareness
+
+stask supports multiple projects. If you're inside a project repo or its worktree, stask auto-detects it. Otherwise use `--project <name>` on any command. Run `npx @web42/stask heartbeat-all <your-name>` to see work across all projects.
+
 ## Your Responsibilities
 
 1. **Check for work** using heartbeat

package/bin/stask.mjs

@@ -23,6 +23,32 @@
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { execFileSync } from 'child_process';
+
+// ─── Auto-rebuild better-sqlite3 if compiled for wrong Node version ─
+{
+  try {
+    const mod = await import('better-sqlite3');
+    // Trigger actual load by constructing a DB (import alone may not load the native binding)
+    new mod.default(':memory:').close();
+  } catch (err) {
+    if (err.code === 'ERR_DLOPEN_FAILED') {
+      const __dir = path.dirname(fileURLToPath(import.meta.url));
+      console.error('Native module mismatch — rebuilding better-sqlite3...');
+      execFileSync('npm', ['rebuild', 'better-sqlite3'], {
+        cwd: path.resolve(__dir, '..'),
+        stdio: ['pipe', 'inherit', 'inherit'],
+      });
+      // Re-exec ourselves — can't reload native modules in same process
+      const result = execFileSync(process.execPath, process.argv.slice(1), {
+        stdio: 'inherit',
+        env: process.env,
+      });
+      process.exit(0);
+    }
+    throw err;
+  }
+}
 
 // ─── Extract --project flag before module loading ─────────────────
 // Must happen before env.mjs is imported since it resolves project root at import time.

package/lib/resolve-home.mjs

@@ -110,6 +110,12 @@ let _resolved = null;
 export function resolveProjectRoot() {
   if (_resolved) return _resolved;
 
+  // 0. STASK_HOME env var — direct override for CI, Docker, or explicit configuration
+  if (process.env.STASK_HOME) {
+    _resolved = process.env.STASK_HOME;
+    return _resolved;
+  }
+
   const projectName = extractProjectFlag(process.argv);
 
   // 1. Explicit --project flag or STASK_PROJECT env var

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@web42/stask",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "SQLite-backed task lifecycle CLI with Slack sync for AI agent teams",
   "type": "module",
   "bin": {
@@ -15,7 +15,9 @@
     "config.example.json"
   ],
   "scripts": {
-    "test": "node --test test/*.test.mjs"
+    "test": "STASK_HOME=test/fixtures/.stask node --test test/*.test.mjs",
+    "test:e2e": "node --test test/multi-project.test.mjs",
+    "test:unit": "STASK_HOME=test/fixtures/.stask node --test test/cascade.test.mjs test/lifecycle.test.mjs test/roles.test.mjs test/session.test.mjs test/slack-row.test.mjs test/transitions.test.mjs test/tx.test.mjs"
   },
   "keywords": [
     "cli",