@web42/stask 0.1.5

package/lib/worktree-cleanup.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/**
+ * worktree-cleanup.mjs — Remove a git worktree after task completion.
+ *
+ * Usage: node worktree-cleanup.mjs <task-id> [--force]
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+import { findTask, updateTask, addLogEntry, parseWorktreeValue } from './tracker-db.mjs';
+import { CONFIG } from './env.mjs';
+
+const REPO_PATH = CONFIG.projectRepoPath;
+
+const taskId = process.argv[2];
+const forceFlag = process.argv.includes('--force');
+
+if (!taskId) {
+  console.error('Usage: node worktree-cleanup.mjs <task-id> [--force]');
+  process.exit(1);
+}
+
+const task = findTask(taskId);
+
+if (!task) {
+  console.error(`ERROR: Task ${taskId} not found`);
+  process.exit(1);
+}
+
+const wt = parseWorktreeValue(task['Worktree']);
+if (!wt) {
+  console.log(`No worktree set for ${taskId}. Nothing to clean up.`);
+  process.exit(0);
+}
+
+const { branch, path: wtPath } = wt;
+
+// Check for uncommitted changes
+if (fs.existsSync(wtPath)) {
+  try {
+    const status = execSync('git status --porcelain', { cwd: wtPath, encoding: 'utf-8' }).trim();
+    if (status && !forceFlag) {
+      console.error(`ERROR: Worktree at ${wtPath} has uncommitted changes:`);
+      console.error(status);
+      console.error('Use --force to remove anyway.');
+      process.exit(1);
+    }
+  } catch {}
+}
+
+// Remove worktree
+if (fs.existsSync(wtPath)) {
+  try {
+    execSync(`git worktree remove "${wtPath}" ${forceFlag ? '--force' : ''}`, { cwd: REPO_PATH, stdio: 'pipe' });
+    console.log(`Removed worktree: ${wtPath}`);
+  } catch (err) {
+    try {
+      fs.rmSync(wtPath, { recursive: true, force: true });
+      console.log(`Removed worktree directory manually: ${wtPath}`);
+      execSync('git worktree prune', { cwd: REPO_PATH, stdio: 'pipe' });
+    } catch (rmErr) {
+      console.error(`ERROR: Could not remove worktree directory: ${rmErr.message}`);
+    }
+  }
+} else {
+  try { execSync('git worktree prune', { cwd: REPO_PATH, stdio: 'pipe' }); } catch {}
+}
+
+// Delete local branch
+try {
+  execSync(`git branch -d "${branch}"`, { cwd: REPO_PATH, stdio: 'pipe' });
+  console.log(`Deleted local branch: ${branch}`);
+} catch {
+  if (forceFlag) {
+    try {
+      execSync(`git branch -D "${branch}"`, { cwd: REPO_PATH, stdio: 'pipe' });
+      console.log(`Force-deleted local branch: ${branch}`);
+    } catch (err) {
+      console.error(`WARNING: Could not delete branch ${branch}: ${err.message}`);
+    }
+  } else {
+    console.log(`Branch ${branch} not deleted (has unmerged changes). Use --force to delete.`);
+  }
+}
+
+// Update DB
+updateTask(taskId, { worktree: null });
+addLogEntry(taskId, `${taskId} "${task['Task Name']}": Worktree cleaned up. Branch: ${branch}.`);
+
+console.log(`${taskId}: Worktree cleaned up | Branch: ${branch}`);

package/lib/worktree-create.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * worktree-create.mjs — Create a git worktree for a parent task.
+ *
+ * Usage: node worktree-create.mjs <task-id>
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+import {
+  findTask, updateTask, addLogEntry, formatWorktreeValue,
+} from './tracker-db.mjs';
+import { slugifyTaskName, branchPrefixForType } from './validate.mjs';
+import { CONFIG } from './env.mjs';
+
+const REPO_PATH = CONFIG.projectRepoPath;
+const WORKTREE_BASE = CONFIG.worktreeBaseDir;
+
+const taskId = process.argv[2];
+
+if (!taskId) {
+  console.error('Usage: node worktree-create.mjs <task-id>');
+  process.exit(1);
+}
+
+const task = findTask(taskId);
+
+if (!task) {
+  console.error(`ERROR: Task ${taskId} not found`);
+  process.exit(1);
+}
+
+if (task['Parent'] !== 'None') {
+  console.error(`ERROR: ${taskId} is a subtask. Worktrees are only created for parent tasks.`);
+  process.exit(1);
+}
+
+if (task['Worktree'] !== 'None') {
+  console.log(`Worktree already exists for ${taskId}: ${task['Worktree']}. Skipping.`);
+  process.exit(0);
+}
+
+// ─── Derive branch name and path ────────────────────────────────────
+
+const slug = slugifyTaskName(task['Task Name']);
+const prefix = branchPrefixForType(task['Type']);
+let branchName = `${prefix}/${slug}`;
+
+if (!fs.existsSync(WORKTREE_BASE)) {
+  fs.mkdirSync(WORKTREE_BASE, { recursive: true });
+}
+
+const worktreePath = path.join(WORKTREE_BASE, slug);
+
+// Check for branch name collision
+try {
+  const existing = execSync(`git branch --list "${branchName}"`, { cwd: REPO_PATH, encoding: 'utf-8' }).trim();
+  if (existing) {
+    try {
+      const worktrees = execSync('git worktree list --porcelain', { cwd: REPO_PATH, encoding: 'utf-8' });
+      if (worktrees.includes(branchName)) {
+        console.log(`Branch ${branchName} already has a worktree. Reusing.`);
+        const lines = worktrees.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+          if (lines[i].includes(`branch refs/heads/${branchName}`)) {
+            const wtPath = lines[i - 2]?.replace('worktree ', '') || worktreePath;
+            const wtValue = formatWorktreeValue(branchName, wtPath);
+            updateTask(taskId, { worktree: wtValue });
+            addLogEntry(taskId, `${taskId}: Reusing existing worktree for branch ${branchName}.`);
+                        console.log(`${taskId}: Worktree reused | Branch: ${branchName} | Path: ${wtPath}`);
+            process.exit(0);
+          }
+        }
+      }
+    } catch {}
+    branchName = `${prefix}/${slug}-${taskId.toLowerCase()}`;
+    console.log(`Branch name collision. Using: ${branchName}`);
+  }
+} catch {}
+
+// ─── Create worktree ────────────────────────────────────────────────
+
+if (fs.existsSync(worktreePath)) {
+  try {
+    execSync(`git worktree remove "${worktreePath}" --force`, { cwd: REPO_PATH, stdio: 'pipe' });
+  } catch {
+    fs.rmSync(worktreePath, { recursive: true, force: true });
+  }
+}
+
+try {
+  let baseBranch = 'dev';
+  try {
+    execSync('git rev-parse --verify dev', { cwd: REPO_PATH, stdio: 'pipe' });
+  } catch {
+    try {
+      execSync('git rev-parse --verify main', { cwd: REPO_PATH, stdio: 'pipe' });
+      baseBranch = 'main';
+    } catch {
+      console.error('ERROR: Neither dev nor main branch found.');
+      process.exit(1);
+    }
+  }
+
+  try {
+    execSync(`git fetch origin ${baseBranch}`, { cwd: REPO_PATH, stdio: 'pipe' });
+  } catch {
+    console.error(`WARNING: Could not fetch origin/${baseBranch}.`);
+  }
+
+  execSync(`git worktree add "${worktreePath}" -b "${branchName}" ${baseBranch}`, {
+    cwd: REPO_PATH, stdio: 'pipe',
+  });
+  console.log(`Based on: ${baseBranch}`);
+} catch (err) {
+  console.error(`ERROR: Failed to create worktree: ${err.message}`);
+  process.exit(1);
+}
+
+// ─── Update DB ──────────────────────────────────────────────────────
+
+const wtValue = formatWorktreeValue(branchName, worktreePath);
+updateTask(taskId, { worktree: wtValue });
+addLogEntry(taskId, `${taskId} "${task['Task Name']}": Worktree created. Branch: ${branchName}, Path: ${worktreePath}.`);
+
+console.log(`${taskId}: Worktree created | Branch: ${branchName} | Path: ${worktreePath}`);

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@web42/stask",
+  "version": "0.1.5",
+  "description": "SQLite-backed task lifecycle CLI with Slack sync for AI agent teams",
+  "type": "module",
+  "bin": {
+    "stask": "./bin/stask.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "commands/",
+    "skills/",
+    "config.example.json"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "keywords": [
+    "cli",
+    "task",
+    "slack",
+    "sqlite",
+    "ai-agents",
+    "lifecycle"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "better-sqlite3": "^12.8.0"
+  }
+}

package/skills/stask-general.md

@@ -0,0 +1,113 @@
+---
+name: stask-general
+description: Task lifecycle framework — spec-first workflow, Slack sync, status transitions, worktree isolation, and PR-based review. SQLite is the single source of truth. All operations go through the `stask` CLI.
+---
+
+# stask — Task Lifecycle Framework
+
+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.
+
+## Core Rules
+
+1. **No task exists without a spec uploaded to Slack.** Every task must have a Spec value: `specs/<name>.md (F0XXXXXXXXX)`.
+2. **SQLite is the single source of truth.** Never edit `tracker.db` directly — use `stask` commands only.
+3. **Every parent task gets its own worktree.** The guard system creates it automatically on In-Progress.
+4. **PR merge = Done.** The Human merges on GitHub, the system auto-completes the task.
+5. **DB + Slack are transactional.** If Slack sync fails, the DB rolls back.
+
+## Roles
+
+| Role | Responsibility |
+|------|---------------|
+| **Human** | Approves specs (via Slack checkbox), reviews PRs on GitHub, merges |
+| **Lead** | Creates subtasks, delegates, coordinates fixes |
+| **Worker(s)** | Implements subtasks in worktrees, marks them done |
+| **QA** | Tests against acceptance criteria, submits pass/fail verdict |
+
+## Task Lifecycle
+
+```
+Lead writes spec -> uploads to Slack -> creates task (assigned to Human)
+    -> Human approves spec -> assigned to Lead
+    -> Lead creates subtasks -> delegates to Workers
+    -> Lead transitions to In-Progress -> worktree created automatically (guard)
+    -> Workers work in the task worktree (feature branch)
+    -> All subtasks Done -> auto Testing (guard: worktree clean + pushed)
+    -> QA submits verdict:
+        PASS -> Ready for Human Review -> draft PR created (guard)
+            -> Human reviews on GitHub, leaves comments
+            -> Human merges PR -> task auto-completes to Done
+        FAIL (1st/2nd) -> back to In-Progress (Lead re-delegates)
+        FAIL (3rd) -> Blocked -> escalated to Human
+```
+
+## Guards
+
+Guards run automatically before transitions. Checks run first (read-only); if all pass, setup guards run (side effects).
+
+| Transition | Guard | Type | What it does |
+|---|---|---|---|
+| -> In-Progress | `require_approved` | check | Task must not be assigned to Human |
+| -> In-Progress | `setup_worktree` | setup | Creates git worktree + feature branch |
+| -> Testing | `all_subtasks_done` | check | Every subtask must be Done |
+| -> Testing | `worktree_clean` | check | No uncommitted changes in worktree |
+| -> Testing | `worktree_pushed` | check | No unpushed commits |
+| -> Ready for Human Review | `worktree_clean` | check | No uncommitted changes |
+| -> Ready for Human Review | `worktree_pushed` | check | No unpushed commits |
+| -> Ready for Human Review | `require_pr` | check | PR must exist |
+
+## Status Definitions
+
+| Status | Meaning | Assigned To |
+|--------|---------|-------------|
+| To-Do (Human) | Spec written, awaiting approval | Human |
+| To-Do (Lead) | Spec approved, Lead creating subtasks | Lead |
+| In-Progress | Workers building subtasks in worktree | Parent: Lead, Subtasks: Workers |
+| Testing | QA testing with evidence | QA |
+| Ready for Human Review | QA PASSED, awaiting final sign-off + PR review | Human |
+| Done | PR merged, shipped | -- |
+| Blocked | Halted — escalated to Human | Human |
+
+## CLI Reference
+
+### Mutation commands (DB + Slack transaction)
+
+| Command | Purpose |
+|---------|---------|
+| `stask create --spec <path> --name "..." [--type Feature\|Bug\|Task]` | Create task (auto-uploads spec to Slack) |
+| `stask approve <task-id>` | Human approves spec (reassigns to Lead) |
+| `stask transition <task-id> <status>` | Transition status (guards enforce prerequisites) |
+| `stask subtask create --parent <id> --name "..." --assign <agent>` | Create subtask under parent |
+| `stask subtask done <subtask-id>` | Worker marks subtask Done (auto-cascades parent) |
+| `stask qa <task-id> --report <path> --verdict PASS\|FAIL` | Submit QA verdict with report |
+| `stask assign <task-id> <name>` | Reassign a task |
+| `stask spec-update <task-id> --spec <path>` | Re-upload edited spec |
+
+### Read-only commands
+
+| Command | Purpose |
+|---------|---------|
+| `stask list [--status X] [--assignee Y] [--json]` | List tasks (filterable) |
+| `stask show <task-id> [--log]` | Show task details + subtasks + audit log |
+| `stask log [<task-id>] [--limit N]` | View audit log |
+| `stask heartbeat <agent-name>` | Returns pending work for an agent (JSON) |
+| `stask pr-status <task-id>` | Poll PR for comments/merge status |
+| `stask session claim\|release\|status <task-id>` | Manage session locks |
+
+### Sync commands
+
+| Command | Purpose |
+|---------|---------|
+| `stask sync` | Run one bidirectional sync cycle |
+| `stask sync-daemon start\|stop\|status` | Manage background sync daemon |
+
+## Rules for All Agents
+
+1. **Never edit tracker.db directly.** Use `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.
+5. **PR merge = Done.** Never manually transition to Done.
+6. **All PR comments go through the Human.** External comments need explicit triage.
+7. **Workers mark their own subtasks Done** via `stask subtask done <id>`.
+8. **Reference specs by Slack file ID** (e.g., `F0XXXXXXXXX`), never by local path.

package/skills/stask-lead.md

@@ -0,0 +1,72 @@
+---
+name: stask-lead
+description: Lead agent workflow — creates subtasks, delegates work, triages PR feedback, coordinates the full task lifecycle from spec approval to PR merge.
+---
+
+# Lead Agent Workflow
+
+You are the **Lead**. You own each task from spec approval through PR merge. You never write code directly — you delegate to Workers and coordinate the lifecycle.
+
+## Your Responsibilities
+
+1. **Read the spec** when a task is approved and assigned to you
+2. **Create subtasks** breaking the spec into implementable units
+3. **Delegate** each subtask to a Worker agent
+4. **Transition to In-Progress** (auto-creates worktree)
+5. **Triage QA failures** — review reports, create fix subtasks, re-delegate
+6. **Create the PR** after QA passes — write a rich description with summary, changes, QA results
+7. **Triage PR feedback** — decide if code change or cosmetic fix
+8. **Transition to Done** when the Human merges the PR
+
+## Commands You Use
+
+| Command | When |
+|---------|------|
+| `stask heartbeat <your-name>` | Check what work you have pending |
+| `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 |
+
+## 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`
+
+### 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"`
+
+### 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>`
+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`
+     - Create fix subtasks, delegate to Workers
+     - After fixes: QA re-tests, you update PR, transition back to RHR
+   - **Cosmetic fix** (PR description, naming):
+     - Fix directly on GitHub. No state change needed.
+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`
+
+## Key Rules
+
+- **Never write code yourself.** Delegate to Workers via subtasks.
+- **Never skip QA.** Even for small fixes, the QA cycle must complete.
+- **The PR is your responsibility.** Write a description that helps the Human review quickly.
+- **External PR comments** (not from Human): Send Human a Slack DM. Do NOT act on them.
+- **Old Done subtasks stay Done** when cycling back to In-Progress. Only create NEW fix subtasks.

package/skills/stask-qa.md

@@ -0,0 +1,99 @@
+---
+name: stask-qa
+description: QA agent workflow — tests tasks against acceptance criteria, takes evidence screenshots, writes reports, and submits PASS/FAIL verdicts.
+---
+
+# QA Agent Workflow
+
+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.
+
+## Your Responsibilities
+
+1. **Check for work** using heartbeat
+2. **Read the spec** — focus on acceptance criteria
+3. **Test in the worktree** — run the dev server, test every AC
+4. **Collect evidence** — screenshots, test output, console logs
+5. **Write a QA report** — structured markdown with pass/fail per criterion
+6. **Submit your verdict** — PASS or FAIL with the report
+
+## Commands You Use
+
+| Command | When |
+|---------|------|
+| `stask heartbeat <your-name>` | Check what tasks need testing |
+| `stask show <task-id>` | View task details and spec |
+| `stask qa <task-id> --report <path> --verdict PASS\|FAIL` | Submit your verdict |
+
+## When You Receive Work
+
+### Task in Testing (assigned to you)
+
+The heartbeat will tell you:
+- The task ID and name
+- The worktree path
+- The spec file ID with acceptance criteria
+
+**Steps:**
+1. `cd` to the worktree path
+2. Read the spec — identify every acceptance criterion (AC)
+3. Start the dev server or test environment
+4. Test each AC systematically
+5. Take screenshots as evidence for each AC
+6. Write your QA report (see format below)
+7. Submit: `stask qa T-XXX --report <path> --verdict PASS` or `FAIL`
+
+## QA Report Format
+
+```markdown
+# QA Report: T-XXX — Task Name
+
+## Environment
+- Branch: feature/xxx
+- Worktree: /path/to/worktree
+- Date: YYYY-MM-DD
+
+## Acceptance Criteria Results
+
+### AC 1: [Description from spec]
+- **Result:** PASS / FAIL
+- **Evidence:** [Screenshot path or description]
+- **Notes:** [Any observations]
+
+### AC 2: [Description from spec]
+- **Result:** PASS / FAIL
+- **Evidence:** [Screenshot path or description]
+- **Notes:** [Any observations]
+
+## Summary
+- Total ACs: X
+- Passed: X
+- Failed: X
+
+## Verdict: PASS / FAIL
+
+## Additional Notes
+[Any bugs found, edge cases, suggestions]
+```
+
+## Key Rules
+
+- **Test every acceptance criterion.** Don't skip any, even obvious ones.
+- **Take screenshots.** Evidence is required for the Human's review.
+- **Be specific in failure reports.** The Lead needs to know exactly what failed and how to reproduce it.
+- **Don't fix bugs yourself.** Report them. The Lead will delegate fixes to Workers.
+- **3 failures = escalation.** After 3 consecutive FAIL verdicts, the task gets Blocked and escalated to the Human.
+
+## QA Retry Slots
+
+- 1st attempt: `qa_report_1`
+- 2nd attempt (after 1st fail + fixes): `qa_report_2`
+- 3rd attempt (after 2nd fail + fixes): `qa_report_3`
+- 3rd fail: Task goes to Blocked, escalated to Human
+
+## On Re-test (After Fixes)
+
+When testing a task that previously failed:
+1. Focus on the previously failed ACs first
+2. Still verify all other ACs haven't regressed
+3. Reference the previous report in your new one
+4. Note what was fixed and what changed

package/skills/stask-worker.md

@@ -0,0 +1,61 @@
+---
+name: stask-worker
+description: Worker agent workflow — implements subtasks in git worktrees, commits, pushes, and marks subtasks done. Workers write all the code.
+---
+
+# Worker Agent Workflow
+
+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.
+
+## Your Responsibilities
+
+1. **Check for work** using heartbeat
+2. **Read the spec** to understand what you're building
+3. **Work in the task worktree** (never the main repo checkout)
+4. **Implement** the subtask according to the spec
+5. **Commit and push** your changes
+6. **Mark your subtask done** when implementation is complete
+
+## Commands You Use
+
+| Command | When |
+|---------|------|
+| `stask heartbeat <your-name>` | Check what subtasks are assigned to you |
+| `stask show <task-id>` | View task/subtask details and spec |
+| `stask subtask done <subtask-id>` | Mark your subtask as Done |
+| `stask session claim <task-id>` | Claim a session lock (prevents conflicts) |
+| `stask session release <task-id>` | Release your session lock |
+
+## When You Receive Work
+
+### Subtask Assigned (In-Progress, assigned to you)
+
+The heartbeat will tell you:
+- The subtask ID and name
+- The parent task's worktree path and branch
+- The spec file ID
+
+**Steps:**
+1. `cd` to the worktree path from the heartbeat
+2. Read the spec to understand the full context and your specific subtask
+3. Implement the changes
+4. Test your changes locally
+5. `git add` + `git commit` with a clear message
+6. `git push` to the remote branch
+7. `stask subtask done <your-subtask-id>`
+
+## Key Rules
+
+- **Always work in the worktree.** The path is in the heartbeat output. Never work in the main repo.
+- **Commit AND push before marking done.** The Testing guards check for both uncommitted changes and unpushed commits. If you don't push, the task will get stuck.
+- **One branch per task.** All Workers on the same parent task share one worktree and one branch. Coordinate with other Workers if needed.
+- **Don't transition the parent task.** The system auto-transitions to Testing when all subtasks are Done.
+- **Mark only YOUR subtask done.** Use `stask subtask done <your-id>`, not anyone else's.
+- **If you're blocked**, tell the Lead. Don't try to work around issues.
+
+## Common Mistakes
+
+1. **Forgetting to push** — `git commit` is not enough. You must `git push`.
+2. **Working in main checkout** — Always verify you're in the worktree directory.
+3. **Marking done too early** — Only mark done when your implementation is complete and pushed.
+4. **Not reading the spec** — The spec has acceptance criteria. Read them before coding.