ac-teams 0.0.10 → 0.0.11

package/README.md

@@ -14,6 +14,8 @@ Restart Pi after installation. Use Pi's `/trust` command to save approval for ea
 
 ## Use it
 
+Use `team_task` for substantial solo work as well as team deliverables. Agents receive guidance to plan multi-step work, start tasks before working, and complete them after verification. Simple tasks need no list.
+
 Your Pi session is the root; its child agents are members. Ask Pi to delegate a bounded assignment, for example:
 
 > Launch a member to review src/parser.ts without editing, and have it send findings back to me.
@@ -21,7 +23,7 @@ Your Pi session is the root; its child agents are members. Ask Pi to delegate a
 | Tool | Purpose |
 | --- | --- |
 | `team_agent` | Launch, inspect, stop, and resume members; manage limits and worktrees |
-| `team_task` | Track shared work, ownership, and dependencies |
+| `team_task` | Plan solo or team work, create tasks in batches, and track ownership and dependencies |
 | `team_message` | Send notifications and read or search team history |
 
 `/teams` or `/teams panel` opens Tasks, Teammates, and Activity. `/teams teammate <name-or-id>` opens a teammate directly; subcommands and teammate names autocomplete. Use the task graph or list, send feedback, and open a member's full live Pi session.

package/docs/usage.md

@@ -1,6 +1,6 @@
 # Use ac-teams
 
-ac-teams provides three tools with lightweight guidance for tracking delegated work. Your Pi session is a main session; the agents it launches are members. The first main session opens coordination state on the first team request. See [main sessions](#main-sessions-share-one-team) for adding more.
+ac-teams provides three tools for planning and tracking solo and delegated work. Your Pi session is a main session; the agents it launches are members. The first main session opens coordination state on the first team request. See [main sessions](#main-sessions-share-one-team) for adding more.
 
 | Tool | Actions | Main rule |
 | --- | --- | --- |
@@ -55,10 +55,11 @@ The task summary sits above the input editor; the agent selector sits below the
 
 1. In-progress work
 2. Ready prerequisites blocking other tasks, with the most dependents first
-3. Blocked work, marked `⊘` with prerequisite numbers such as `blocked by #3`
-4. Recently completed work, newest first
+3. Other ready work
+4. Blocked work, marked `⊘` with prerequisite numbers such as `blocked by #3`
+5. Recently completed work, newest first
 
-Ordinary ready tasks remain in `/teams`; the summary is not the full task list. Completion time determines recent order for newly completed tasks. Older completed tasks without timestamps fall back to task-number order.
+The summary shows at most five tasks; `/teams` retains the full list. Completion time determines recent order for newly completed tasks. Older completed tasks without timestamps fall back to task-number order.
 
 ac-teams leaves your existing footer intact and publishes a compact summary under the `ac-teams` extension-status key. Custom footers must support extension statuses to show it. In Zentui, use `/zentui extensions` to choose a placement for `ac-teams` if statuses are hidden by default. Agent navigation remains available in its own row even when the footer hides statuses.
 
@@ -66,6 +67,22 @@ Use `/teams config` to toggle **Task summary** and **Agent selector** independen
 
 Hiding a display does not stop agents, change tasks, or disable `/teams`. With the agent selector hidden, ordinary editor Down behavior returns. These global display preferences do not change the team's resource ceilings.
 
+## Plan solo and team work
+
+The tool guidance asks agents to use `team_task` for substantial work with three or more steps, explicit task lists, and coordinated deliverables, including solo research, design, implementation, and verification. Single trivial tasks and conversation need no list. This is guidance, not automatic task creation or enforcement.
+
+Create independent tasks in one call:
+
+```json
+{"action":"create","tasks":[{"title":"Review parser behavior","description":"Acceptance: identify malformed-input failures with reproduction steps."},{"title":"Review display ordering","description":"Acceptance: compare implementation and display tests, and report mismatches."}]}
+```
+
+A batch creates 1–100 tasks atomically: invalid input leaves no tasks created. Use either `tasks` or top-level task fields, not both. Existing single-task creation remains supported. A title is enough for a simple task; description defaults to title and label defaults to its first three words, capped at 60 characters. Supply explicit acceptance criteria for substantial or delegated work. Dependencies must reference existing task UUIDs, so create prerequisites before dependent tasks.
+
+Start a task before working and complete it immediately after checking the result. One agent normally works on one task at a time; teammates can work in parallel. Never complete partial work or work with unresolved failures.
+
+Task list and mutation responses give the model compact summaries, including UUIDs, revisions, owners, and dependencies. `read` returns full descriptions and acceptance criteria. Expanded tool responses retain full records for people to inspect.
+
 ## Give members bounded assignments
 
 Before delegating a deliverable, create or reuse a shared task and include its ID in the member's brief. Track independently owned outcomes, not every agent, tool call, or procedural step. For example:
@@ -101,11 +118,11 @@ Children can delegate through the same coordinator, subject to depth and capacit
 
 ## Track progress separately from ownership
 
-Task owners claim and start their work, then complete it after checking acceptance criteria or report blockers. Claiming reserves a task; starting also requires its dependencies to be done.
+Start ready work directly; `start` claims an unowned task and begins it atomically. Use `claim` only to reserve work in advance. Complete work after checking acceptance criteria or report blockers. Starting requires every dependency to be done.
 
 Each task has a stable team-local `number` and a 1–3-word `label` (at most 60 characters). The graph and list show `#3 Parser review`; details retain the full title, description, and UUID.
 
-Numbers follow creation order. Editing, filtering, or reopening tasks never changes their numbers. A concise title can supply an omitted label; longer titles need an explicit label.
+Numbers follow creation order. Editing, filtering, or reopening tasks never changes their numbers. An omitted label is derived from the title's first three words, capped at 60 characters. An explicit label must satisfy the same limits.
 
 Interim and final goals are ordinary tasks. Use dependencies for real prerequisites, not to make the diagram connected. Independent tasks remain disconnected until they genuinely contribute to a dependent task.
 
@@ -120,12 +137,12 @@ Use the returned task ID with these actions:
 | Action | Effect |
 | --- | --- |
 | `claim` | Reserve an unowned to-do task, even if blocked. Progress stays `todo`. |
-| `start` | The owner moves `todo` to `in_progress`, only when every dependency is `done`. |
+| `start` | Claim unowned work and move `todo` to `in_progress` atomically, only when every dependency is `done`. An existing owner must be the caller. |
 | `complete` | The owner moves `in_progress` to `done`, with `acceptance: true`. Ownership remains. |
 | `release` | Clear ownership. In-progress work returns to `todo`; done work stays `done`. |
 | `reopen` | Explicitly move `done` to `todo`, retaining any owner. Refuse if a dependent is in progress or done. |
 
-Only the owner can start, complete, or release its work. An ancestor may explicitly release a stopped or interrupted descendant's ownership. The owner or root can reopen an owned task; any member can reopen an unowned one. Done tasks cannot be claimed until reopened.
+Starting never steals another owner's work. Only the owner can complete or release its work. An ancestor may explicitly release a stopped or interrupted descendant's ownership. The owner or root can reopen an owned task; any member can reopen an unowned one. Done tasks cannot be claimed until reopened.
 
 Include `dependencies` on creation or `edit`. Any member can edit unowned to-do work; only the owner can edit reserved to-do work. In-progress and done tasks cannot be edited. The coordinator rejects unknown dependencies and cycles. An optional `revision` rejects stale mutations.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ac-teams",
-  "version": "0.0.10",
+  "version": "0.0.11",
   "description": "Small, persistent teams for Pi",
   "type": "module",
   "license": "MIT",

package/src/index.ts

@@ -274,7 +274,7 @@ export default function teams(pi: ExtensionAPI) {
   });
   function output(data: unknown) { return { content: [{ type: "text" as const, text: JSON.stringify(data) }], details: data }; }
   const guidance = "Team launches use real long-lived Pi sessions. Idle members count against the shared ceiling. Use stable member/task IDs; query status and history instead of acknowledging notifications. Limits cover only ac-teams, not other launchers or shell commands.";
-  const taskTrackingGuidance = "Before delegating a deliverable through team_agent, create or reuse a team_task and include its ID in the member's brief. Track independently owned outcomes, not tool calls or procedural steps; do not create one task per teammate by default. Skip tasks for quick lookups, clarification, and brief second opinions unless results need coordination or follow-up. Task owners claim and start their work, then complete it after checking acceptance criteria or report blockers.";
+  const taskTrackingGuidance = "Before delegating a deliverable through team_agent, create or reuse a team_task and include its ID in the member's brief. Use one shared task list for your own work and delegated work; do not create one task per teammate by default. Quick lookups and brief second opinions need no separate task unless their results need coordination or follow-up.";
   pi.registerTool({
     name: "team_agent", label: "Team agent", description: "Launch/resume Pi members, list/status, stop owned subtrees, change root limits, and explicitly clean stopped worktrees. Create or reuse team_task entries for delegated deliverables; quick lookups need no task unless results need coordination or follow-up.",
     promptGuidelines: [guidance, taskTrackingGuidance, "Delegation needs the user's authorization. Give each new member a unique descriptive name (one or two lowercase words, hyphenated if two), plus a bounded brief. Names remain stable on resume. Avoid concurrent writers in the same cwd. Worktrees are opt-in."],
@@ -283,11 +283,24 @@ export default function teams(pi: ExtensionAPI) {
     async execute(_id, args, _signal, _update, ctx) { return output(await handle("agent", args, ctx)); },
   });
   pi.registerTool({
-    name: "team_task", label: "Team task", description: "Track delegated deliverables, not every agent or action. Create or reuse tasks before delegation; quick lookups need no task unless results need coordination or follow-up. Manage shared tasks: create/list/read/edit, claim a reservation, start work, complete, release ownership, or explicitly reopen. Progress is todo/in_progress/done; blockedBy is derived from unfinished dependencies. Mutations support revision checks.",
-    promptGuidelines: [taskTrackingGuidance, taskRequestGuidance, "Give every task a concise 1–3-word label, alongside its full title and acceptance criteria. Stable team-local numbers are assigned automatically; use UUIDs for API references. Interim and final goals are ordinary tasks. Add dependencies only for real prerequisites, never merely to connect the diagram.", "Claim reserves a to-do task even if blocked; start requires ownership and all dependencies done. Complete requires in-progress work and acceptance=true after checking the criteria. Release clears ownership, returns in-progress work to todo, and leaves done work done. Reopen is explicit and cannot invalidate active or done dependents."],
+    name: "team_task", label: "Team task", description: "Plan and track multi-step solo and team work in one shared list. Create one task or a batch with tasks:[{title,...}], list compact summaries, read full details, edit, claim a reservation, start, complete, release, or reopen. Start atomically claims unowned ready work. Progress is todo/in_progress/done; blockedBy is derived from unfinished dependencies. Mutations support revision checks.",
+    promptSnippet: "Plan and track multi-step work, alone or with teammates",
+    promptGuidelines: [
+      "Use team_task before substantial work with 3+ steps, when the user gives an explicit task list, or when coordinating deliverables. This includes your own research, design, implementation, and verification; no teammate is required. Skip single trivial tasks, conversation, and tool-by-tool bookkeeping.",
+      "Create the initial plan in one team_task call with tasks:[{title,description},...]. Titles are required; labels and descriptions default from titles. Include acceptance criteria for substantial or delegated work. Dependencies must reference existing task UUIDs; create prerequisites before dependent tasks. Reuse relevant existing tasks rather than duplicating them.",
+      "Call team_task start BEFORE beginning a task; it claims unowned ready work atomically. Use claim only to reserve work in advance, including blocked work. Complete each task IMMEDIATELY after checking its result with acceptance=true; never complete partial work or work with unresolved failures. Report blockers. Each agent should normally work on one task at a time; teammates can work in parallel.",
+      taskTrackingGuidance, taskRequestGuidance,
+      "team_task list returns compact summaries; read a task for its full description and acceptance criteria. Use returned UUIDs for API references and stable task numbers/names when reporting to people. Add dependencies only for real prerequisites, never merely to connect the diagram.",
+      "team_task start refuses another owner's task or unfinished dependencies. Complete requires ownership, in-progress work, and acceptance=true. Release clears ownership, returns in-progress work to todo, and leaves done work done. Reopen is explicit and cannot invalidate active or done dependents.",
+    ],
     parameters: TaskSchema,
     ...teamToolRenderers("team_task"),
-    async execute(_id, args, _signal, _update, ctx) { return output(await handle("task", args, ctx)); },
+    async execute(_id, args, _signal, _update, ctx) {
+      const data = await handle("task", args, ctx) as TaskView | { tasks: TaskView[]; total: number };
+      const compact = (task: TaskView) => ({ id: task.id, number: task.number, label: task.label, title: task.title, status: task.status, owner: task.owner, revision: task.revision, dependencies: task.dependencies, blockedBy: task.blockedBy });
+      const content = args.action === "read" ? data : "tasks" in data ? { tasks: data.tasks.map(compact), total: data.total } : compact(data);
+      return { content: [{ type: "text" as const, text: JSON.stringify(content) }], details: data };
+    },
   });
   pi.registerTool({
     name: "team_message", label: "Team message", description: "Send a persistent direct/team message or read cursor-paged history. Send returns a receipt; history and search return full messages. New messages queue a compact follow-up notification for each recipient.",

package/src/render.ts

@@ -57,7 +57,7 @@ function toolSummary(data: unknown, theme: Theme): string {
   if (data && typeof data === "object") {
     const value = data as Record<string, unknown>;
     if (Array.isArray(value.members)) return preview(value.members, `${value.members.length} members`, theme);
-    if (Array.isArray(value.tasks)) return preview(value.tasks, `${value.tasks.length} of ${value.total} tasks`, theme);
+    if (Array.isArray(value.tasks)) return preview(value.tasks, value.total === undefined ? `${value.tasks.length} tasks` : `${value.tasks.length} of ${value.total} tasks`, theme);
     const label = value.title ?? value.name ?? value.brief ?? value.text ?? value.query ?? value.id;
     const status = value.status === undefined ? "" : inline(value.status);
     const color = status === "done" ? "success"

package/src/schemas.ts

@@ -21,14 +21,18 @@ export const AgentSchema = Type.Object({
     }, { additionalProperties: false, description: "Omit to keep the requester's network access. Children can only narrow it. The model provider stays reachable." })),
   }, { additionalProperties: false, description: "Launch only: OS-enforced directory access (Docker container). Paths are absolute or cwd-relative directories; write implies read and permits changing those live files; everything else on the host is hidden, and outbound access goes through a proxy that reaches only public addresses. Omit to inherit the requesting member's access; an unsandboxed requester then launches an unsandboxed member. Children can only narrow access. Launch fails if enforcement is unavailable; check team_agent list/limits sandbox first." })),
 }, { additionalProperties: false });
+const taskFields = {
+  title: Type.Optional(Type.String({ minLength: 1, maxLength: 500 })),
+  label: Type.Optional(Type.String({ minLength: 1, maxLength: taskLabelMaxLength, pattern: taskLabelPattern.source, description: "Optional 1–3-word label. Derived from title when omitted." })),
+  description: Type.Optional(Type.String({ maxLength: 16000, description: "Details and acceptance criteria. Defaults to title; include explicit criteria for substantial or delegated work." })),
+  dependencies: Type.Optional(Type.Array(id, { maxItems: 100, uniqueItems: true })),
+};
 export const TaskSchema = Type.Object({
   revision: Type.Optional(Type.Integer({ minimum: 1 })), acceptance: Type.Optional(Type.Boolean()),
   offset: Type.Optional(Type.Integer({ minimum: 0 })), limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
   action: Type.Union(["create", "list", "read", "edit", "claim", "start", "release", "complete", "reopen"].map(v => Type.Literal(v))),
-  id: Type.Optional(id), title: Type.Optional(Type.String({ minLength: 1, maxLength: 500 })),
-  label: Type.Optional(Type.String({ minLength: 1, maxLength: taskLabelMaxLength, pattern: taskLabelPattern.source, description: "A concise 1–3-word task label. Defaults to title only when title satisfies this limit." })),
-  description: Type.Optional(Type.String({ maxLength: 16000 })),
-  dependencies: Type.Optional(Type.Array(id, { maxItems: 100, uniqueItems: true })),
+  id: Type.Optional(id), ...taskFields,
+  tasks: Type.Optional(Type.Array(Type.Object({ ...taskFields, title: Type.String({ minLength: 1, maxLength: 500 }) }, { additionalProperties: false }), { minItems: 1, maxItems: 100, description: "Create several tasks atomically. Use instead of top-level task fields. Dependencies must refer to existing task IDs, not items in this batch." })),
 }, { additionalProperties: false });
 export const MessageSchema = Type.Object({
   action: Type.Union(["send", "history", "search"].map(v => Type.Literal(v))),

package/src/store.ts

@@ -53,6 +53,10 @@ function taskView(state: TeamState, task: Task): TaskView {
   return structuredClone({ ...task, blockedBy: task.dependencies.filter(id => state.tasks[id]?.status !== "done") });
 }
 
+function taskLabel(title: string): string {
+  return stripVTControlCharacters(title).replace(/[\x00-\x1f\x7f-\x9f]/g, " ").trim().split(/\s+/).slice(0, 3).join(" ").slice(0, taskLabelMaxLength).trim();
+}
+
 function migrate(state: unknown): boolean {
   if (!object(state) || ![1, 2, 3].includes(state.version as number)) return false;
   if (state.version !== 3) migrateTasks(state);
@@ -78,7 +82,7 @@ function migrateTasks(state: Record<string, unknown>): void {
       else task.status = "done";
     }
     task.number = ++number;
-    task.label = stripVTControlCharacters(task.title).replace(/[\x00-\x1f\x7f-\x9f]/g, " ").trim().split(/\s+/).slice(0, 3).join(" ").slice(0, taskLabelMaxLength).trim() || "Task";
+    task.label = taskLabel(task.title) || "Task";
   }
 }
 
@@ -273,6 +277,7 @@ export class Store {
 
   task(actor: string, args: TaskArgs): TaskView | { tasks: TaskView[]; total: number } {
     requireValue(!this.closed && Object.hasOwn(this.state.members, actor), "Unknown actor or closed store");
+    requireValue(args.tasks === undefined || args.action === "create", "tasks is only valid for create");
     if (args.action === "list") {
       const tasks = Object.values(this.state.tasks);
       const offset = args.offset ?? 0, limit = args.limit ?? 100;
@@ -285,13 +290,24 @@ export class Store {
     }
     return this.update(state => {
       if (args.action === "create") {
-        requireValue(text(args.title, 500) && text(args.description), "Task requires a title (max 500) and description (max 16000)");
-        const label = args.label ?? args.title;
-        requireValue(text(label, taskLabelMaxLength) && taskLabelPattern.test(label), "Task requires a 1–3-word label (max 60 characters); a concise title can serve as the label");
-        const number = Object.values(state.tasks).reduce((max, task) => Math.max(max, task.number), 0) + 1;
-        const task: Task = { id: randomUUID(), number, label, revision: 1, creator: actor, title: args.title, description: args.description, dependencies: args.dependencies === undefined ? [] : structuredClone(args.dependencies), status: "todo" };
-        state.tasks[task.id] = task;
-        return taskView(state, task);
+        requireValue(args.tasks === undefined || (Array.isArray(args.tasks) && args.tasks.length > 0 && args.tasks.length <= 100), "Batch create requires 1-100 tasks");
+        requireValue(args.tasks === undefined || [args.title, args.label, args.description, args.dependencies].every(value => value === undefined), "Use tasks or top-level task fields, not both");
+        const inputs = args.tasks ?? [args];
+        let number = Object.values(state.tasks).reduce((max, task) => Math.max(max, task.number), 0);
+        const existing = new Set(Object.keys(state.tasks));
+        const created = inputs.map(input => {
+          requireValue(object(input) && text(input.title, 500), "Task requires a title (max 500)");
+          const description = input.description === undefined ? input.title : input.description;
+          requireValue(text(description), "Task requires a description (max 16000)");
+          const label = input.label === undefined ? taskLabel(input.title) : input.label;
+          requireValue(text(label, taskLabelMaxLength) && taskLabelPattern.test(label), "Task requires a 1–3-word label (max 60 characters)");
+          const dependencies = input.dependencies === undefined ? [] : structuredClone(input.dependencies);
+          requireValue(Array.isArray(dependencies) && dependencies.length <= 100 && dependencies.every(dep => existing.has(dep)), "Dependencies must refer to existing tasks");
+          const task: Task = { id: randomUUID(), number: ++number, label, revision: 1, creator: actor, title: input.title, description, dependencies, status: "todo" };
+          state.tasks[task.id] = task;
+          return taskView(state, task);
+        });
+        return args.tasks === undefined ? created[0] : { tasks: created, total: created.length };
       }
       requireValue(args.id && Object.hasOwn(state.tasks, args.id), "Unknown task");
       const task = state.tasks[args.id];
@@ -308,10 +324,11 @@ export class Store {
         requireValue(!task.owner, `Task is already owned by ${task.owner}`);
         task.owner = actor;
       } else if (args.action === "start") {
-        requireValue(task.owner === actor, "Only the owner can start this task; claim it first");
+        requireValue(!task.owner || task.owner === actor, "Only the owner can start this task");
         requireValue(task.status === "todo", "Only to-do tasks can be started");
         const blocked = taskView(state, task).blockedBy;
         requireValue(blocked.length === 0, `Task is blocked by unfinished dependencies: ${blocked.join(", ")}`);
+        task.owner = actor;
         task.status = "in_progress";
       } else if (args.action === "complete") {
         requireValue(task.owner === actor, "Only the owner can complete this task");

package/src/task-summary.ts

@@ -9,8 +9,8 @@ export function summaryTasks(tasks: TaskView[]): TaskView[] {
     if (task.status !== "done") for (const id of task.blockedBy) dependents.set(id, (dependents.get(id) ?? 0) + 1);
   }
   const rank = (task: TaskView) => task.status === "in_progress" ? 0
-    : task.status === "done" ? 3 : task.blockedBy.length ? 2 : dependents.has(task.id) ? 1 : 4;
-  return tasks.filter(task => rank(task) < 4).sort((a, b) => rank(a) - rank(b)
+    : task.status === "done" ? 4 : task.blockedBy.length ? 3 : dependents.has(task.id) ? 1 : 2;
+  return [...tasks].sort((a, b) => rank(a) - rank(b)
     || (a.status === "done" && b.status === "done" ? (b.completedAt ?? -1) - (a.completedAt ?? -1) || b.number - a.number
       : (dependents.get(b.id) ?? 0) - (dependents.get(a.id) ?? 0) || a.number - b.number)).slice(0, 5);
 }

package/src/types.ts

@@ -97,7 +97,14 @@ export interface TeamState {
   tasks: Record<string, Task>;
   messages: Message[];
 }
+export interface TaskInput {
+  title: string;
+  label?: string;
+  description?: string;
+  dependencies?: string[];
+}
 export interface TaskArgs {
+  tasks?: TaskInput[];
   action: "create" | "list" | "read" | "edit" | "claim" | "start" | "release" | "complete" | "reopen";
   revision?: number;
   acceptance?: boolean;