@web42/stask 0.1.6 → 0.1.8

package/README.md

@@ -13,7 +13,7 @@ stask enforces a spec-first workflow where tasks flow through defined statuses (
 ## Install
 
 ```bash
-npm install -g stask
+npm install -g @web42/stask
 ```
 
 ## Setup

package/commands/heartbeat.mjs

@@ -11,7 +11,7 @@ import path from 'path';
 import { execFileSync, execSync } from 'child_process';
 import { CONFIG, LIB_DIR, getWorkspaceLibs } from '../lib/env.mjs';
 import { withDb } from '../lib/tx.mjs';
-import { syncTaskToSlack } from '../lib/slack-row.mjs';
+import { syncTaskToSlack, getThreadRef } from '../lib/slack-row.mjs';
 import { isTaskClaimable } from '../lib/session-tracker.mjs';
 import { getLeadAgent } from '../lib/roles.mjs';
 
@@ -348,7 +348,9 @@ These are NOT from ${CONFIG.human.name}. Send a Slack DM to ${CONFIG.human.name}
       }
 
       if (action && prompt) {
-        pendingTasks.push({ taskId, taskName: task['Task Name'], status, parent: task['Parent'], specFileId, action, prompt });
+        const threadRef = getThreadRef(db, isSubtask ? task['Parent'] : taskId);
+        const thread = threadRef ? { channelId: threadRef.channelId, threadTs: threadRef.threadTs } : null;
+        pendingTasks.push({ taskId, taskName: task['Task Name'], status, parent: task['Parent'], specFileId, action, prompt, thread });
       }
     }
 

package/commands/show.mjs

@@ -5,6 +5,7 @@
  */
 
 import { withDb } from '../lib/tx.mjs';
+import { getThreadRef } from '../lib/slack-row.mjs';
 
 export async function run(argv) {
   const taskId = argv[0];
@@ -34,6 +35,11 @@ export async function run(argv) {
     if (task['QA Report 3'] !== 'None') console.log(`  QA Report 3: ${task['QA Report 3']}`);
     if (task['Blocker'] !== 'None') console.log(`  Blocker:     ${task['Blocker']}`);
 
+    const threadRef = getThreadRef(db, taskId);
+    if (threadRef) {
+      console.log(`  Thread:      ${threadRef.channelId}:${threadRef.threadTs}`);
+    }
+
     console.log(`  Created:     ${task['created_at']}`);
     console.log(`  Updated:     ${task['updated_at']}`);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@web42/stask",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "SQLite-backed task lifecycle CLI with Slack sync for AI agent teams",
   "type": "module",
   "bin": {

package/skills/{stask-general.md → stask-general/SKILL.md}

@@ -10,7 +10,7 @@ SQLite-backed task lifecycle management with Slack sync. Every operation goes th
 ## 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.
+2. **SQLite is the single source of truth.** Never edit `tracker.db` directly — use `npx @web42/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.
@@ -74,32 +74,66 @@ Guards run automatically before transitions. Checks run first (read-only); if al
 
 | 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 |
+| `npx @web42/stask create --spec <path> --name "..." [--type Feature\|Bug\|Task]` | Create task (auto-uploads spec to Slack) |
+| `npx @web42/stask approve <task-id>` | Human approves spec (reassigns to Lead) |
+| `npx @web42/stask transition <task-id> <status>` | Transition status (guards enforce prerequisites) |
+| `npx @web42/stask subtask create --parent <id> --name "..." --assign <agent>` | Create subtask under parent |
+| `npx @web42/stask subtask done <subtask-id>` | Worker marks subtask Done (auto-cascades parent) |
+| `npx @web42/stask qa <task-id> --report <path> --verdict PASS\|FAIL` | Submit QA verdict with report |
+| `npx @web42/stask assign <task-id> <name>` | Reassign a task |
+| `npx @web42/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 |
+| `npx @web42/stask list [--status X] [--assignee Y] [--json]` | List tasks (filterable) |
+| `npx @web42/stask show <task-id> [--log]` | Show task details + subtasks + audit log |
+| `npx @web42/stask log [<task-id>] [--limit N]` | View audit log |
+| `npx @web42/stask heartbeat <agent-name>` | Returns pending work for an agent (JSON) |
+| `npx @web42/stask pr-status <task-id>` | Poll PR for comments/merge status |
+| `npx @web42/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 |
+| `npx @web42/stask sync` | Run one bidirectional sync cycle |
+| `npx @web42/stask sync-daemon start\|stop\|status` | Manage background sync daemon |
+
+## 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.
+
+**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.
+
+### What to post
+
+- **Starting work** — "Starting work on T-XXX.2: Build login form"
+- **Progress updates** — "Implemented the auth middleware, moving to the UI components"
+- **Blockers or issues** — "Hit an issue: the API endpoint returns 500 on invalid tokens. Investigating."
+- **Errors or failures** — "Tests failing on login redirect. Stack trace: ..."
+- **Subtask completion** — "Subtask T-XXX.1 done. Pushed 3 commits to feature/xxx"
+- **QA results** — "QA PASS: all 5 acceptance criteria verified. Screenshots attached."
+- **Status transitions** — "Transitioning T-XXX to Testing"
+- **Questions** — "Question for @yan: should the invite expire after 7 days or 30 days?"
+
+### How to post
+
+The thread reference is in the heartbeat JSON as `thread.channelId` and `thread.threadTs`. Post using the Slack API:
+
+```
+POST https://slack.com/api/chat.postMessage
+{
+  "channel": "<thread.channelId>",
+  "thread_ts": "<thread.threadTs>",
+  "text": "<your update>"
+}
+```
+
+Use the `SLACK_TOKEN` from the environment for authorization.
+
+**Post even when things go wrong.** Failed builds, test errors, unexpected behavior — all of it goes in the thread. Silence is worse than bad news.
 
 ## Rules for All Agents
 
@@ -109,5 +143,6 @@ Guards run automatically before transitions. Checks run first (read-only); if al
 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>`.
+7. **Workers mark their own subtasks Done** via `npx @web42/stask subtask done <id>`.
 8. **Reference specs by Slack file ID** (e.g., `F0XXXXXXXXX`), never by local path.
+9. **Post every step to the task thread.** Every action, result, blocker, and question goes in the thread. No exceptions.

package/skills/{stask-lead.md → stask-lead/SKILL.md}

@@ -22,38 +22,38 @@ You are the **Lead**. You own each task from spec approval through PR merge. You
 
 | 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 |
+| `npx @web42/stask heartbeat <your-name>` | Check what work you have pending |
+| `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 |
 
 ## 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):
@@ -61,7 +61,22 @@ You are the **Lead**. You own each task from spec approval through PR merge. You
 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`
+
+## Thread Communication
+
+**Post to the task thread at every step.** The thread reference is in your heartbeat output (`thread.channelId` + `thread.threadTs`). Use `chat.postMessage` with `thread_ts` to reply.
+
+You must post when you:
+- Receive a task and start planning subtasks
+- Create each subtask (who it's assigned to, what it does)
+- Transition the task to any new status
+- Review a QA failure and plan fixes
+- Create the PR (include the PR link)
+- Address PR feedback
+- Encounter any blocker or unexpected issue
+
+Example: "Creating 3 subtasks for T-006: (1) Build invite API → Gilfoyle, (2) Build invite UI → Dinesh, (3) Add email notifications → Gilfoyle. Transitioning to In-Progress."
 
 ## Key Rules
 
@@ -70,3 +85,4 @@ You are the **Lead**. You own each task from spec approval through PR merge. You
 - **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.
+- **Post every action to the task thread.** The thread is how the team stays informed.

package/skills/{stask-qa.md → stask-qa/SKILL.md}

@@ -20,9 +20,9 @@ You are **QA**. You test completed work against the spec's acceptance criteria.
 
 | 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 |
+| `npx @web42/stask heartbeat <your-name>` | Check what tasks need testing |
+| `npx @web42/stask show <task-id>` | View task details and spec |
+| `npx @web42/stask qa <task-id> --report <path> --verdict PASS\|FAIL` | Submit your verdict |
 
 ## When You Receive Work
 
@@ -40,7 +40,7 @@ The heartbeat will tell you:
 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`
+7. Submit: `npx @web42/stask qa T-XXX --report <path> --verdict PASS` or `FAIL`
 
 ## QA Report Format
 
@@ -75,6 +75,24 @@ The heartbeat will tell you:
 [Any bugs found, edge cases, suggestions]
 ```
 
+## Thread Communication
+
+**Post to the task thread at every step.** The thread reference is in your heartbeat output (`thread.channelId` + `thread.threadTs`). Use `chat.postMessage` with `thread_ts` to reply.
+
+You must post when you:
+- Start testing a task
+- Begin testing each acceptance criterion
+- Find a passing AC — "AC 1 (login redirect): PASS"
+- Find a failing AC — "AC 3 (error message): FAIL — shows generic 500 instead of 'Invalid email'"
+- Encounter test environment issues
+- Submit your final verdict
+
+Example: "Starting QA for T-005. Reading spec and setting up test environment."
+Example: "AC 1 PASS: Health endpoint returns 200 with version field. AC 2 PASS: Response time < 100ms. AC 3 FAIL: Missing content-type header."
+Example: "QA FAIL submitted for T-005. 1 of 3 ACs failed. See report for details."
+
+**Post even when things go wrong.** Environment issues, build failures, unclear spec — post it all to the thread.
+
 ## Key Rules
 
 - **Test every acceptance criterion.** Don't skip any, even obvious ones.
@@ -82,6 +100,7 @@ The heartbeat will tell you:
 - **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.
+- **Post every step to the task thread.** Every AC result, every issue, every observation.
 
 ## QA Retry Slots
 

package/skills/{stask-worker.md → stask-worker/SKILL.md}

@@ -20,11 +20,11 @@ You are a **Worker**. You implement subtasks assigned to you by the Lead. You wr
 
 | 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 |
+| `npx @web42/stask heartbeat <your-name>` | Check what subtasks are assigned to you |
+| `npx @web42/stask show <task-id>` | View task/subtask details and spec |
+| `npx @web42/stask subtask done <subtask-id>` | Mark your subtask as Done |
+| `npx @web42/stask session claim <task-id>` | Claim a session lock (prevents conflicts) |
+| `npx @web42/stask session release <task-id>` | Release your session lock |
 
 ## When You Receive Work
 
@@ -42,7 +42,25 @@ The heartbeat will tell you:
 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>`
+7. `npx @web42/stask subtask done <your-subtask-id>`
+
+## Thread Communication
+
+**Post to the task thread at every step.** The thread reference is in your heartbeat output (`thread.channelId` + `thread.threadTs`). Use `chat.postMessage` with `thread_ts` to reply.
+
+You must post when you:
+- Start working on your subtask
+- Make meaningful progress (e.g., "Implemented the API route, moving to tests")
+- Hit any error, blocker, or unexpected behavior
+- Have a question for the Lead or Human
+- Finish and push your code
+- Mark your subtask as Done
+
+Example: "Starting T-005.1: Build CLI flags. Reading the spec now."
+Example: "Hit an issue — the config loader doesn't support nested objects. Working around it by flattening."
+Example: "T-005.1 done. Pushed 2 commits: added --serve flag and OpenClawAgentExecutor."
+
+**Post even when things go wrong.** If tests fail, if something breaks, if you're confused — post it. Silence is the worst outcome.
 
 ## Key Rules
 
@@ -50,8 +68,9 @@ The heartbeat will tell you:
 - **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.
+- **Mark only YOUR subtask done.** Use `npx @web42/stask subtask done <your-id>`, not anyone else's.
+- **If you're blocked**, tell the Lead in the thread. Don't try to work around issues.
+- **Post every step to the task thread.** No exceptions — every action, result, and question.
 
 ## Common Mistakes