@web42/stask 0.1.7 → 0.2.1

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

@@ -0,0 +1,115 @@
+---
+name: stask-lead
+description: Lead agent workflow — orchestrates the 6-phase spec process, 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.
+
+## Multi-Project Awareness
+
+stask supports multiple projects. Each project lives in a repo with a `.stask/` folder.
+
+- **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.
+
+When heartbeat returns tasks with a `project` field, include `--project <name>` in all subsequent stask commands for that task.
+
+## The 6-Phase Process
+
+You follow a strict 6-phase process. Never skip a phase.
+
+### Phase 1: Requirements & Analysis (With Yan Only)
+- Receive Yan's request, identify ambiguities, resolve all unknowns before technical work
+- Run Requirements Clarification + Analysis modes from `technical-spec-design` skill
+
+### Phase 2: Technical Exploration (With Team)
+- Spawn Gilfoyle, Dinesh, and Jared as subagents to produce technical deliverables
+- Use structured prompts with Context, What To Do, and Required Deliverables sections
+- Wait for all to return before consolidating
+
+### Phase 3: Design & Architecture (Consolidation)
+- Run Design + Architecture modes from `technical-spec-design` skill
+- Consolidate team findings into the final spec with all required sections
+- 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 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`
+- When all subtasks Done → auto-transitions to Testing
+
+### Phase 6: QA → Review → Done
+- Jared tests against ACs
+- If QA FAIL: transition back to In-Progress, create fix subtasks, re-delegate
+- If QA PASS: create PR, transition to "Ready for Human Review"
+- If Yan merges: transition to Done
+
+## Commands You Use
+
+| 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 |
+
+> **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`
+
+### 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.
+- **Spec before code.** No implementation starts without an approved spec.
+- **Ambiguity first.** Resolve unknowns with Yan before delegating to the team.

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/bin/stask.mjs

@@ -23,7 +23,30 @@
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import { loadEnv, CONFIG } from '../lib/env.mjs';
+
+// ─── Extract --project flag before module loading ─────────────────
+// Must happen before env.mjs is imported since it resolves project root at import time.
+{
+  const idx = process.argv.indexOf('--project');
+  if (idx !== -1 && idx + 1 < process.argv.length) {
+    process.env.STASK_PROJECT = process.argv[idx + 1];
+    // Remove --project <name> from argv so commands don't see it
+    process.argv.splice(idx, 2);
+  }
+}
+
+// Commands that don't need a project context (work with global registry only)
+const NO_PROJECT_COMMANDS = new Set(['init', 'projects', 'heartbeat-all']);
+
+const _cmd = process.argv[2];
+if (NO_PROJECT_COMMANDS.has(_cmd)) {
+  // Skip project resolution — these commands handle it themselves
+  const mod = await import(`../commands/${_cmd}.mjs`);
+  await mod.run(process.argv.slice(3));
+  process.exit(0);
+}
+
+const { loadEnv, CONFIG } = await import('../lib/env.mjs');
 
 // Auto-load env before anything else
 loadEnv();
@@ -44,7 +67,6 @@ function ensureSyncDaemon() {
 }
 
 // Don't auto-start for sync-daemon commands (avoid recursion) or read-only queries
-const _cmd = process.argv[2];
 if (_cmd && _cmd !== 'sync-daemon' && _cmd !== '--help' && _cmd !== '-h') {
   ensureSyncDaemon();
 }
@@ -68,6 +90,8 @@ const COMMANDS = {
   'assign':         () => import('../commands/assign.mjs'),
   'sync':           () => import('../commands/sync.mjs'),
   'sync-daemon':    () => import('../commands/sync-daemon.mjs'),
+  // Multi-project commands (also handled as NO_PROJECT_COMMANDS above for init/projects/heartbeat-all)
+  'heartbeat-all':  () => import('../commands/heartbeat-all.mjs'),
 };
 
 const SUBTASK_COMMANDS = {
@@ -148,6 +172,14 @@ Read-only commands:
 Sync commands:
   sync                          Run one bidirectional sync cycle
   sync-daemon start|stop|status Manage background sync daemon
+
+Multi-project commands:
+  init <name> --repo <path>     Create a new stask project
+  projects [show <name>]        List/show registered projects
+  heartbeat-all <agent-name>    Get pending work across all projects
+
+Global flags:
+  --project <name>              Target a specific project (otherwise auto-detected from cwd)
 `);
 }
 

package/commands/heartbeat-all.mjs

@@ -0,0 +1,87 @@
+/**
+ * stask heartbeat-all — Get pending work for an agent across ALL projects.
+ *
+ * Usage: stask heartbeat-all <agent-name>
+ *
+ * Iterates over all registered projects, checks if the agent is configured
+ * in each project, and runs heartbeat per project. Returns combined JSON.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { execFileSync } from 'child_process';
+import { fileURLToPath } from 'url';
+import { loadProjectsRegistry } from '../lib/resolve-home.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const STASK_BIN = path.resolve(__dirname, '../bin/stask.mjs');
+
+export async function run(args) {
+  const agentName = args[0];
+
+  if (!agentName) {
+    console.error('Usage: stask heartbeat-all <agent-name>');
+    process.exit(1);
+  }
+
+  const registry = loadProjectsRegistry();
+  const projects = Object.entries(registry.projects || {});
+
+  if (projects.length === 0) {
+    console.log(JSON.stringify({ agent: agentName, pendingTasks: [], projects: [] }, null, 2));
+    return;
+  }
+
+  const allPendingTasks = [];
+  const projectResults = [];
+
+  for (const [projectName, projectInfo] of projects) {
+    const configPath = path.join(projectInfo.repoPath, '.stask', 'config.json');
+
+    // Skip projects without config
+    if (!fs.existsSync(configPath)) continue;
+
+    // Check if agent is in this project's config
+    try {
+      const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+      const agentConfig = config.agents?.[agentName.toLowerCase()];
+      if (!agentConfig) continue;
+
+      // Run heartbeat for this project via subprocess
+      const result = execFileSync(
+        process.execPath,
+        [STASK_BIN, 'heartbeat', agentName, '--project', projectName],
+        { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
+      );
+
+      const heartbeat = JSON.parse(result);
+
+      // Tag each pending task with the project name
+      for (const task of heartbeat.pendingTasks || []) {
+        task.project = projectName;
+        // Inject --project into prompt so agent uses it in subsequent commands
+        if (task.prompt) {
+          task.prompt = task.prompt.replace(
+            /\bstask\b(?!\s+--project)/g,
+            `stask --project ${projectName}`
+          );
+        }
+        allPendingTasks.push(task);
+      }
+
+      projectResults.push({ project: projectName, role: agentConfig.role, taskCount: (heartbeat.pendingTasks || []).length });
+    } catch (err) {
+      // Log to stderr but don't fail — other projects may still work
+      console.error(`WARNING: heartbeat failed for project "${projectName}": ${err.message}`);
+      projectResults.push({ project: projectName, error: err.message });
+    }
+  }
+
+  const result = {
+    agent: agentName,
+    pendingTasks: allPendingTasks,
+    projects: projectResults,
+  };
+
+  console.log(JSON.stringify(result, null, 2));
+}

package/commands/init.mjs

@@ -0,0 +1,148 @@
+/**
+ * stask init — Create a new stask project.
+ *
+ * Usage: stask init <project-name> --repo <path> [--worktrees <path>] [--specs <path>]
+ *
+ * Creates .stask/ in the target repo with scaffolded config.json and .gitignore.
+ * Registers the project in ~/.stask/projects.json.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { loadProjectsRegistry, saveProjectsRegistry, GLOBAL_STASK_DIR } from '../lib/resolve-home.mjs';
+
+function parseArgs(args) {
+  const name = args[0];
+  if (!name || name.startsWith('--')) {
+    return null;
+  }
+  const opts = { name };
+  for (let i = 1; i < args.length; i += 2) {
+    const flag = args[i];
+    const val = args[i + 1];
+    if (!val) break;
+    if (flag === '--repo') opts.repo = val;
+    else if (flag === '--worktrees') opts.worktrees = val;
+    else if (flag === '--specs') opts.specs = val;
+  }
+  return opts;
+}
+
+const CONFIG_TEMPLATE = (name, specsDir, worktreeBaseDir) => ({
+  project: name,
+  specsDir,
+  projectRepoPath: '.',
+  worktreeBaseDir,
+  staleSessionMinutes: 30,
+  syncIntervalSeconds: 60,
+  maxQaRetries: 3,
+
+  human: {
+    name: 'YourName',
+    slackUserId: 'UXXXXXXXXXX',
+    githubUsername: 'your-github-username',
+  },
+
+  agents: {
+    'lead-agent':  { role: 'lead',   slackUserId: 'UXXXXXXXXXX' },
+    'worker-1':    { role: 'worker', slackUserId: 'UXXXXXXXXXX' },
+    'worker-2':    { role: 'worker', slackUserId: 'UXXXXXXXXXX' },
+    'qa-agent':    { role: 'qa',     slackUserId: 'UXXXXXXXXXX' },
+  },
+
+  slack: {
+    listId: 'YOUR_SLACK_LIST_ID',
+    columns: {
+      name: 'ColXXXXXXXXX',
+      task_id: 'ColXXXXXXXXX',
+      status: 'ColXXXXXXXXX',
+      assignee: 'ColXX',
+      spec: 'ColXXXXXXXXX',
+      type: 'ColXXXXXXXXX',
+      worktree: 'ColXXXXXXXXX',
+      pr: 'ColXXXXXXXXX',
+      qa_report_1: 'ColXXXXXXXXX',
+      qa_report_2: 'ColXXXXXXXXX',
+      qa_report_3: 'ColXXXXXXXXX',
+      completed: 'ColXX',
+      spec_approved: 'ColXXXXXXXXX',
+      pr_status: 'ColXXXXXXXXX',
+    },
+    statusOptions: {
+      'To-Do': 'OptXXXXXXXXX',
+      'In-Progress': 'OptXXXXXXXXX',
+      'Testing': 'OptXXXXXXXXX',
+      'Ready for Human Review': 'OptXXXXXXXXX',
+      'Blocked': 'OptXXXXXXXXX',
+      'Done': 'OptXXXXXXXXX',
+    },
+    typeOptions: {
+      Feature: 'OptXXXXXXXXX',
+      Bug: 'OptXXXXXXXXX',
+      Improvement: 'OptXXXXXXXXX',
+      Research: 'OptXXXXXXXXX',
+    },
+  },
+});
+
+const GITIGNORE_CONTENT = `# stask runtime data (do not commit)
+tracker.db
+tracker.db-wal
+tracker.db-shm
+FILE_REGISTRY.json
+logs/
+pr-status/
+`;
+
+export async function run(args) {
+  const opts = parseArgs(args);
+  if (!opts || !opts.repo) {
+    console.error('Usage: stask init <project-name> --repo <path> [--worktrees <path>] [--specs <path>]');
+    process.exit(1);
+  }
+
+  const repoPath = path.resolve(opts.repo);
+  if (!fs.existsSync(repoPath)) {
+    console.error(`ERROR: Repo path does not exist: ${repoPath}`);
+    process.exit(1);
+  }
+
+  const staskDir = path.join(repoPath, '.stask');
+  if (fs.existsSync(path.join(staskDir, 'config.json'))) {
+    console.error(`ERROR: Project already initialized at ${staskDir}`);
+    console.error('Delete .stask/config.json first if you want to re-initialize.');
+    process.exit(1);
+  }
+
+  const specsDir = opts.specs || './specs';
+  const worktreeBaseDir = opts.worktrees || path.join(GLOBAL_STASK_DIR, 'worktrees', opts.name);
+
+  // Create .stask/ directory
+  fs.mkdirSync(staskDir, { recursive: true });
+
+  // Write config.json
+  const config = CONFIG_TEMPLATE(opts.name, specsDir, worktreeBaseDir);
+  fs.writeFileSync(
+    path.join(staskDir, 'config.json'),
+    JSON.stringify(config, null, 2) + '\n'
+  );
+
+  // Write .gitignore
+  fs.writeFileSync(path.join(staskDir, '.gitignore'), GITIGNORE_CONTENT);
+
+  // Register in global projects.json
+  const registry = loadProjectsRegistry();
+  registry.projects = registry.projects || {};
+  registry.projects[opts.name] = { repoPath };
+  saveProjectsRegistry(registry);
+
+  console.log(`Project "${opts.name}" initialized.`);
+  console.log('');
+  console.log(`  Config:   ${path.join(staskDir, 'config.json')}`);
+  console.log(`  Registry: ${path.join(GLOBAL_STASK_DIR, 'projects.json')}`);
+  console.log('');
+  console.log('Next steps:');
+  console.log('  1. Edit .stask/config.json — fill in agents, Slack list/column IDs, human info');
+  console.log('  2. Set SLACK_TOKEN env var or add to ~/.stask/config.json');
+  console.log(`  3. Run: cd ${repoPath} && stask list`);
+}

package/commands/projects.mjs

@@ -0,0 +1,103 @@
+/**
+ * stask projects — List and show registered stask projects.
+ *
+ * Usage:
+ *   stask projects              List all registered projects
+ *   stask projects show <name>  Show project details + task count
+ */
+
+import fs from 'fs';
+import path from 'path';
+import Database from 'better-sqlite3';
+import { loadProjectsRegistry } from '../lib/resolve-home.mjs';
+
+export async function run(args) {
+  const subCmd = args[0];
+
+  if (subCmd === 'show') {
+    return showProject(args[1]);
+  }
+
+  return listProjects();
+}
+
+function listProjects() {
+  const registry = loadProjectsRegistry();
+  const entries = Object.entries(registry.projects || {});
+
+  if (entries.length === 0) {
+    console.log('No projects registered.');
+    console.log('');
+    console.log('Create one with: stask init <name> --repo <path>');
+    return;
+  }
+
+  const maxName = Math.max(...entries.map(([n]) => n.length));
+  console.log('Registered projects:');
+  console.log('');
+  for (const [name, info] of entries) {
+    const staskDir = path.join(info.repoPath, '.stask');
+    const hasConfig = fs.existsSync(path.join(staskDir, 'config.json'));
+    const status = hasConfig ? '' : ' (missing .stask/config.json)';
+    console.log(`  ${name.padEnd(maxName + 2)}${info.repoPath}${status}`);
+  }
+}
+
+function showProject(name) {
+  if (!name) {
+    console.error('Usage: stask projects show <name>');
+    process.exit(1);
+  }
+
+  const registry = loadProjectsRegistry();
+  const project = registry.projects?.[name];
+  if (!project) {
+    console.error(`ERROR: Unknown project "${name}".`);
+    console.error('');
+    console.error('Run `stask projects` to see all registered projects.');
+    process.exit(1);
+  }
+
+  const staskDir = path.join(project.repoPath, '.stask');
+  const configPath = path.join(staskDir, 'config.json');
+
+  console.log(`Project: ${name}`);
+  console.log(`Repo:    ${project.repoPath}`);
+  console.log(`Data:    ${staskDir}`);
+
+  if (!fs.existsSync(configPath)) {
+    console.log('Status:  NOT CONFIGURED (missing .stask/config.json)');
+    return;
+  }
+
+  try {
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+
+    // Show agents
+    const agents = Object.entries(config.agents || {});
+    if (agents.length > 0) {
+      console.log('');
+      console.log('Agents:');
+      for (const [agentName, info] of agents) {
+        console.log(`  ${agentName.padEnd(16)}${info.role}`);
+      }
+    }
+
+    // Show task count if DB exists
+    const dbPath = path.join(staskDir, 'tracker.db');
+    if (fs.existsSync(dbPath)) {
+      try {
+        const db = new Database(dbPath, { readonly: true });
+        const total = db.prepare('SELECT COUNT(*) as c FROM tasks WHERE parent_id IS NULL').get().c;
+        const active = db.prepare("SELECT COUNT(*) as c FROM tasks WHERE parent_id IS NULL AND status != 'Done'").get().c;
+        db.close();
+        console.log('');
+        console.log(`Tasks:   ${active} active, ${total} total`);
+      } catch {
+        // DB might not have tables yet
+      }
+    }
+  } catch {
+    console.log('Status:  CONFIG ERROR (could not parse config.json)');
+  }
+}

package/config.example.json

@@ -1,7 +1,8 @@
 {
-  "specsDir": "/path/to/your/specs",
-  "projectRepoPath": "/path/to/your/git/repo",
-  "worktreeBaseDir": "/path/to/worktrees",
+  "project": "your-project-name",
+  "specsDir": "./specs",
+  "projectRepoPath": ".",
+  "worktreeBaseDir": "~/.stask/worktrees/your-project-name",
   "staleSessionMinutes": 30,
   "syncIntervalSeconds": 60,
   "maxQaRetries": 3,

package/lib/env.mjs

@@ -1,23 +1,30 @@
 /**
- * env.mjs — Loads config.json from ~/.stask/, auto-loads .env,
- * resolves global paths, and imports bundled libs.
+ * env.mjs — Loads project config.json, resolves secrets via layered
+ * token resolution, and imports bundled libs.
  *
- * Global data dir: ~/.stask/ (override with STASK_HOME env var)
- * Contains: config.json, .env, tracker.db, FILE_REGISTRY.json, logs/, pr-status/
+ * Project root resolution:
+ *   1. --project <name> → ~/.stask/projects.json registry lookup
+ *   2. Walk up from cwd looking for .stask/config.json
+ *   3. Helpful error if no project found
+ *
+ * Token resolution (SLACK_TOKEN):
+ *   1. SLACK_TOKEN env var
+ *   2. ~/.stask/config.json → projects.<name>.slackToken
+ *   3. ~/.stask/config.json → slackToken (global default)
  */
 
 import fs from 'fs';
 import path from 'path';
-import os from 'os';
 import { fileURLToPath } from 'url';
+import { resolveProjectRoot, resolveProjectName, resolveSlackToken } from './resolve-home.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
-// ─── STASK_HOME — global data directory ───────────────────────────
+// ─── STASK_HOME — resolved project .stask/ directory ──────────────
 
-export const STASK_HOME = process.env.STASK_HOME || path.join(os.homedir(), '.stask');
+export const STASK_HOME = resolveProjectRoot();
 
-// ─── Load config.json from STASK_HOME ─────────────────────────────
+// ─── Load config.json from project .stask/ ────────────────────────
 
 let _config = null;
 
@@ -27,7 +34,7 @@ export function loadConfig() {
   const configPath = path.join(STASK_HOME, 'config.json');
   if (!fs.existsSync(configPath)) {
     console.error(`ERROR: Config not found at ${configPath}`);
-    console.error(`Run: mkdir -p ~/.stask && cp config.example.json ~/.stask/config.json`);
+    console.error(`Run: stask init <project-name> --repo <path>`);
     process.exit(1);
   }
 
@@ -38,11 +45,10 @@ export function loadConfig() {
 
   _config = {
     ...raw,
-    // Resolved absolute paths — all runtime data lives in STASK_HOME
+    // Resolved absolute paths — runtime data lives in .stask/
     staskRoot,
     staskHome: STASK_HOME,
     dbPath: path.join(STASK_HOME, 'tracker.db'),
-    envFile: path.join(STASK_HOME, '.env'),
     registryPath: path.join(STASK_HOME, 'FILE_REGISTRY.json'),
     // Backward compat: expose specsDir as workspace too
     workspace: raw.specsDir,
@@ -50,33 +56,22 @@ export function loadConfig() {
   return _config;
 }
 
-// ─── Auto-load .env into process.env ───────────────────────────────
+// ─── Load secrets (Slack token) via layered resolution ─────────────
 
 let _envLoaded = false;
 
 export function loadEnv() {
   if (_envLoaded) return;
   const config = loadConfig();
-  try {
-    const lines = fs.readFileSync(config.envFile, 'utf-8').split('\n');
-    for (const line of lines) {
-      const match = line.match(/^([^#=]+)=(.*)$/);
-      if (match) {
-        const key = match[1].trim();
-        const val = match[2].trim();
-        if (!process.env[key]) process.env[key] = val;
-      }
-    }
-  } catch (err) {
-    console.error(`WARNING: Could not load env file ${config.envFile}: ${err.message}`);
-  }
-  _envLoaded = true;
+  const projectName = resolveProjectName();
 
-  // Override listId from env if config says FROM_ENV
-  if (config.slack?.listId === 'FROM_ENV' && process.env.LIST_ID) {
-    config.slack.listId = process.env.LIST_ID;
+  // Resolve Slack token via layered precedence
+  const slackToken = resolveSlackToken(projectName);
+  if (slackToken && !process.env.SLACK_TOKEN) {
+    process.env.SLACK_TOKEN = slackToken;
   }
 
+  _envLoaded = true;
 }
 
 // ─── Local lib imports (all bundled in stask/lib/) ─────────────────

package/lib/resolve-home.mjs

@@ -0,0 +1,185 @@
+/**
+ * resolve-home.mjs — Resolves the stask project root directory.
+ *
+ * Resolution order:
+ *   1. --project <name> or STASK_PROJECT env var → look up ~/.stask/projects.json
+ *   2. Walk up from cwd looking for .stask/config.json (like git finds .git/)
+ *   3. No project found → helpful error listing registered projects, exit(1)
+ *
+ * This module has ZERO dependencies on env.mjs or tracker-db.mjs to avoid circular imports.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+const GLOBAL_STASK_DIR = path.join(os.homedir(), '.stask');
+const REGISTRY_PATH = path.join(GLOBAL_STASK_DIR, 'projects.json');
+const CENTRAL_CONFIG_PATH = path.join(GLOBAL_STASK_DIR, 'config.json');
+
+// ─── Projects registry ───────────────────────────────────────────
+
+export function loadProjectsRegistry() {
+  try {
+    return JSON.parse(fs.readFileSync(REGISTRY_PATH, 'utf-8'));
+  } catch {
+    return { projects: {} };
+  }
+}
+
+export function saveProjectsRegistry(registry) {
+  fs.mkdirSync(GLOBAL_STASK_DIR, { recursive: true });
+  fs.writeFileSync(REGISTRY_PATH, JSON.stringify(registry, null, 2) + '\n');
+}
+
+// ─── Central config (secrets) ─────────────────────────────────────
+
+export function loadCentralConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(CENTRAL_CONFIG_PATH, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+// ─── Resolve SLACK_TOKEN ──────────────────────────────────────────
+
+/**
+ * Resolve Slack token with layered precedence:
+ *   1. SLACK_TOKEN env var
+ *   2. Central config → projects.<name>.slackToken
+ *   3. Central config → slackToken (global default)
+ */
+export function resolveSlackToken(projectName) {
+  if (process.env.SLACK_TOKEN) return process.env.SLACK_TOKEN;
+
+  const central = loadCentralConfig();
+  if (projectName && central.projects?.[projectName]?.slackToken) {
+    return central.projects[projectName].slackToken;
+  }
+  if (central.slackToken) return central.slackToken;
+
+  return null;
+}
+
+// ─── Project name from argv ───────────────────────────────────────
+
+export function extractProjectFlag(argv) {
+  const idx = argv.indexOf('--project');
+  if (idx !== -1 && idx + 1 < argv.length) {
+    return argv[idx + 1];
+  }
+  return process.env.STASK_PROJECT || null;
+}
+
+// ─── Walk up to find .stask/ ──────────────────────────────────────
+
+function findStaskDir(startDir) {
+  let dir = path.resolve(startDir);
+  const root = path.parse(dir).root;
+  while (dir !== root) {
+    const candidate = path.join(dir, '.stask', 'config.json');
+    if (fs.existsSync(candidate)) {
+      return path.join(dir, '.stask');
+    }
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+// ─── Format registered projects for error messages ────────────────
+
+function formatProjectList(registry) {
+  const entries = Object.entries(registry.projects || {});
+  if (entries.length === 0) return '  (none registered)';
+  const maxName = Math.max(...entries.map(([n]) => n.length));
+  return entries
+    .map(([name, info]) => `  ${name.padEnd(maxName + 2)}${info.repoPath}`)
+    .join('\n');
+}
+
+// ─── Main resolver ────────────────────────────────────────────────
+
+let _resolved = null;
+
+/**
+ * Resolve the stask project root (.stask/ directory).
+ * Returns an absolute path to the .stask/ folder.
+ * Exits with helpful error if no project is found.
+ */
+export function resolveProjectRoot() {
+  if (_resolved) return _resolved;
+
+  const projectName = extractProjectFlag(process.argv);
+
+  // 1. Explicit --project flag or STASK_PROJECT env var
+  if (projectName) {
+    const registry = loadProjectsRegistry();
+    const project = registry.projects?.[projectName];
+    if (!project) {
+      console.error(`ERROR: Unknown project "${projectName}".`);
+      console.error('');
+      console.error('Registered projects:');
+      console.error(formatProjectList(registry));
+      console.error('');
+      console.error('Run `stask projects` to see all projects.');
+      process.exit(1);
+    }
+    const staskDir = path.join(project.repoPath, '.stask');
+    if (!fs.existsSync(path.join(staskDir, 'config.json'))) {
+      console.error(`ERROR: Project "${projectName}" is registered but .stask/config.json is missing at ${staskDir}.`);
+      console.error('');
+      console.error(`Run \`stask init ${projectName} --repo ${project.repoPath}\` to re-scaffold.`);
+      process.exit(1);
+    }
+    _resolved = staskDir;
+    return _resolved;
+  }
+
+  // 2. Walk up from cwd
+  const found = findStaskDir(process.cwd());
+  if (found) {
+    _resolved = found;
+    return _resolved;
+  }
+
+  // 3. No project found — helpful error
+  const registry = loadProjectsRegistry();
+  console.error('ERROR: No stask project found.');
+  console.error('');
+  console.error('No .stask/ folder found in the current directory or any parent.');
+  console.error('');
+
+  const entries = Object.entries(registry.projects || {});
+  if (entries.length > 0) {
+    console.error('Your registered projects:');
+    console.error(formatProjectList(registry));
+    console.error('');
+    console.error('To work on a project:');
+    console.error(`  cd ${entries[0][1].repoPath}${' '.repeat(6)}# auto-detects .stask/`);
+    console.error(`  stask --project ${entries[0][0]} <command>  # explicit project selection`);
+  } else {
+    console.error('No projects registered yet.');
+  }
+  console.error('');
+  console.error('To create a new project:');
+  console.error('  stask init <name> --repo <path>');
+  console.error('');
+  console.error('Run `stask projects` to see all projects.');
+  process.exit(1);
+}
+
+/**
+ * Get the project name from the resolved .stask/config.json.
+ */
+export function resolveProjectName() {
+  const staskDir = resolveProjectRoot();
+  try {
+    const config = JSON.parse(fs.readFileSync(path.join(staskDir, 'config.json'), 'utf-8'));
+    return config.project || path.basename(path.dirname(staskDir));
+  } catch {
+    return path.basename(path.dirname(staskDir));
+  }
+}
+
+export { GLOBAL_STASK_DIR };

package/lib/tracker-db.mjs

@@ -11,14 +11,14 @@ import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 
-// Resolve paths from STASK_HOME directly to avoid circular deps with env.mjs
-import os from 'os';
+// Resolve paths via resolve-home.mjs (no circular dep with env.mjs)
+import { resolveProjectRoot } from './resolve-home.mjs';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const STASK_HOME = process.env.STASK_HOME || path.join(os.homedir(), '.stask');
+const STASK_HOME = resolveProjectRoot();
 const STASK_ROOT = path.resolve(__dirname, '..');  // Package install dir
 const _configRaw = JSON.parse(fs.readFileSync(path.join(STASK_HOME, 'config.json'), 'utf-8'));
 const WORKSPACE_DIR = _configRaw.specsDir;
-const TASKS_DIR = STASK_HOME;  // Runtime data lives in ~/.stask/
+const TASKS_DIR = STASK_HOME;  // Runtime data lives in .stask/
 const DB_PATH = path.join(STASK_HOME, 'tracker.db');
 
 // ─── Schema ─────────────────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@web42/stask",
-  "version": "0.1.7",
+  "version": "0.2.1",
   "description": "SQLite-backed task lifecycle CLI with Slack sync for AI agent teams",
   "type": "module",
   "bin": {
@@ -11,6 +11,7 @@
     "lib/",
     "commands/",
     "skills/",
+    ".agents/",
     "config.example.json"
   ],
   "scripts": {

package/skills/stask-lead.md

@@ -1,88 +0,0 @@
----
-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 |
-|---------|------|
-| `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 `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: `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: `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):
-     - `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):
-     - 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 `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
-
-- **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.
-- **Post every action to the task thread.** The thread is how the team stays informed.