@4-r-c-4-n-4/todo 0.1.2 → 0.1.3

package/BIBLE.md

@@ -21,11 +21,24 @@ todo close <id>
 ### Feature build (parent + children)
 A parent ticket tracks the feature. Children track subtasks. All children share the parent's branch.
 
-```
+```bash
 todo new "Add OAuth2 login" --type feature
 todo new "Add /auth/callback route" --type chore --parent <feature-id>
 todo new "Store session tokens" --type chore --parent <feature-id>
-todo work <child-id>   # checks out todo/<feature-id> branch
+todo new "Write integration tests" --type chore --parent <feature-id>
+
+# First child creates the shared branch
+todo work <child-1-id>
+
+# Subsequent children — use todo next (preferred)
+while next=$(todo next <feature-id> 2>/dev/null); do
+  # implement $next ...
+  git add -A && git commit -m "todo:$next — ..."
+  todo close $next --note "..."
+  git add .todo/ && git commit -m "todo:$next — close"
+done
+
+todo close <feature-id> --note "All subtasks done."
 ```
 
 Children resolve on the parent branch. Close all children before closing the parent.
@@ -71,7 +84,7 @@ Children resolve on the parent branch. Close all children before closing the par
 
 ## The Branch Workflow
 
-Step by step:
+### Standalone ticket
 
 ```bash
 # 1. Start work — creates branch todo/<id>, transitions ticket to active
@@ -97,7 +110,35 @@ git merge --no-ff todo/<id>
 git branch -d todo/<id>
 ```
 
-For child tickets: `todo work <child-id>` checks out the parent's branch, not a new one.
+### Feature build (shared branch)
+
+All children share `todo/<parent-id>`. The first `todo work` creates the branch; subsequent children must not trigger a redundant checkout.
+
+```bash
+# First child — creates todo/<parent-id>
+todo work <child-1-id>
+git add -A && git commit -m "todo:<child-1-id> — ..."
+todo close <child-1-id> --note "..."
+git add .todo/ && git commit -m "todo:<child-1-id> — close"
+
+# Remaining children — todo next handles activation cleanly
+while next=$(todo next <parent-id> 2>/dev/null); do
+  # implement ...
+  git add -A && git commit -m "todo:$next — ..."
+  todo close $next --note "..."
+  git add .todo/ && git commit -m "todo:$next — close"
+done
+
+# Close parent
+todo close <parent-id> --note "All children done."
+git add .todo/ && git commit -m "todo:<parent-id> — close"
+git checkout main && git merge --no-ff todo/<parent-id>
+git branch -d todo/<parent-id>
+```
+
+`todo next <parent-id>` finds the first open child (in creation order), activates it on the current branch without any git checkout, prints its ID to stdout and a summary to stderr. Exits 1 when all children are done — that's what stops the `while` loop.
+
+If you need manual control instead of a loop, use `todo work --skip-branch <child-id>` to activate a child without a redundant checkout. Do NOT use plain `todo work` for subsequent children on a shared branch — it performs a no-op checkout and prints confusing resume output.
 
 ---
 
@@ -138,6 +179,7 @@ Examples:
 todo:a1b2c3d4 — fix null pointer in auth handler
 todo:a1b2c3d4 — close
 todo:e5f6a7b8 — add /auth/callback route
+todo:e8e874e9 — plan: 4 subtasks
 ```
 
 The `<id>` is the full 8-char ticket ID. Always include it. This ties commits to tickets and enables commit-based dedup and linking.
@@ -156,6 +198,10 @@ The `<id>` is the full 8-char ticket ID. Always include it. This ties commits to
 
 5. **Not committing parent ticket after adding children** — Parent `relationships.children` is updated when you create a child. Commit `.todo/` after creating children.
 
+6. **Using plain `todo work` for subsequent children on a shared branch** — After the first child creates `todo/<parent-id>`, calling `todo work <child-N>` again does a redundant checkout and prints misleading "Resumed branch" output. Use `todo next <parent-id>` (preferred) or `todo work --skip-branch <child-N>` instead.
+
+7. **Using `--no-branch` instead of `--skip-branch`** — Commander.js treats `--no-X` as negating the `--X <value>` option. `--no-branch` silently overrides `--branch <name>` rather than setting a new flag. The correct flag is `--skip-branch`.
+
 ---
 
 ## CLI Quick Reference
@@ -179,6 +225,10 @@ todo close <id>                        Shorthand: transition to done
   --commit --test --note --checkout
 todo work <id>                         Start/resume work on a ticket
   --branch --actor
+  --skip-branch                        Activate on current branch, no git ops (orchestrator mode)
+todo next <parent-id>                  Activate next open child on current branch
+                                       stdout: ticket ID  stderr: summary  exit 1: all done
+  --actor
 todo analyze <id>                      Add analysis entry
   --type blame|hypothesis|evidence|conclusion (required)
   --content <text> (required)
@@ -193,15 +243,15 @@ todo scan                              Scan source tree for TODO/FIXME comments
 todo dedup                             Find duplicate tickets
   --strategy fingerprint|file-line|semantic
   --apply
-todo export <id>                       Export ticket as JSON/markdown
-  --format json|markdown
+todo export                            Export tickets as JSON
+  --state --type
 ```
 
 ---
 
 ## Skill Interface
 
-Agents operate via four named skills. Each maps to a phase of the lifecycle.
+Agents operate via five named skills. Each maps to a phase of the lifecycle.
 
 **todo-capture** — Create a ticket from any signal (log, test failure, comment, agent observation). Use `todo new` with `--source` and `--pipe` as appropriate. Always commit the result.
 
@@ -209,4 +259,6 @@ Agents operate via four named skills. Each maps to a phase of the lifecycle.
 
 **todo-analyze** — Build up the understanding of a bug or requirement. Use `todo analyze` with sequenced entries: hypothesis → evidence → conclusion. Reference supporting indices. Commit when done.
 
-**todo-implement** — Run `todo work` to branch, implement, commit with the `todo:<id>` prefix, then `todo close`. Always commit `.todo/` after close.
+**todo-plan** — Decompose a feature or spec into a parent ticket with ordered children. Use `todo new --parent` to wire children. Commit the full structure before handing off. Children are worked sequentially on the parent's branch via `todo next`.
+
+**todo-implement** — Run `todo work` to branch, implement, commit with the `todo:<id>` prefix, then `todo close`. Use `todo next` to advance through children on a shared branch. Always commit `.todo/` after close.

package/README.md

@@ -1,2 +1,4 @@
 # todo
 Making working on work work
+
+https://www.npmjs.com/package/@4-r-c-4-n-4/todo

package/dist/cli.js

@@ -10,6 +10,7 @@ const export_js_1 = require("./commands/export.js");
 const init_js_1 = require("./commands/init.js");
 const link_js_1 = require("./commands/link.js");
 const list_js_1 = require("./commands/list.js");
+const next_js_1 = require("./commands/next.js");
 const new_js_1 = require("./commands/new.js");
 const scan_js_1 = require("./commands/scan.js");
 const show_js_1 = require("./commands/show.js");
@@ -29,6 +30,7 @@ program
 (0, transition_js_1.registerTransition)(program);
 (0, close_js_1.registerClose)(program);
 (0, work_js_1.registerWork)(program);
+(0, next_js_1.registerNext)(program);
 (0, analyze_js_1.registerAnalyze)(program);
 (0, link_js_1.registerLink)(program);
 (0, scan_js_1.registerScan)(program);

package/dist/commands/next.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerNext(program: Command): void;

package/dist/commands/next.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerNext = registerNext;
+const context_js_1 = require("../context.js");
+const errors_js_1 = require("../errors.js");
+const git_js_1 = require("../git.js");
+const state_js_1 = require("../state.js");
+const ticket_js_1 = require("../ticket.js");
+function registerNext(program) {
+    program
+        .command("next <parent-id>")
+        .description("Activate the next open child of a parent ticket on the current branch (orchestrator mode)")
+        .option("--actor <name>", "override actor (also reads TODO_ACTOR env)")
+        .action((parentId, opts) => {
+        const ctx = (0, context_js_1.getContext)(true);
+        const { repoRoot } = ctx;
+        try {
+            // Resolve actor
+            let actor;
+            if (opts.actor) {
+                actor = opts.actor;
+            }
+            else if (process.env["TODO_ACTOR"]) {
+                actor = process.env["TODO_ACTOR"];
+            }
+            else {
+                try {
+                    actor = (0, git_js_1.getGitUserName)(repoRoot);
+                }
+                catch {
+                    actor = "unknown";
+                }
+            }
+            // Load the parent ticket to get the children list (ordered by creation)
+            const parent = (0, ticket_js_1.readTicket)(repoRoot, parentId);
+            const children = parent.relationships?.children ?? [];
+            if (children.length === 0) {
+                console.error(`Error: ticket ${parent.id} has no children.`);
+                process.exit(1);
+            }
+            // Find the first child that is not in a terminal state
+            const openTickets = (0, ticket_js_1.listTickets)(repoRoot, "open");
+            const openIds = new Set(openTickets.map((t) => t.id));
+            const nextId = children.find((id) => openIds.has(id));
+            if (!nextId) {
+                console.error(`All children of ${parent.id} are done. Close the parent with: todo close ${parent.id}`);
+                process.exit(1);
+            }
+            // Activate the child on the current branch (--skip-branch semantics)
+            const ticket = (0, ticket_js_1.readTicket)(repoRoot, nextId);
+            const currentBranch = (0, git_js_1.getCurrentBranch)(repoRoot);
+            const defaultBranch = (0, git_js_1.getDefaultBranch)(repoRoot);
+            if (ticket.state !== "active") {
+                const now = new Date().toISOString();
+                let updated;
+                try {
+                    updated = (0, state_js_1.applyTransition)(ticket, "active", { actor }, repoRoot);
+                }
+                catch (err) {
+                    console.error(`Error: ${err.message}`);
+                    process.exit(1);
+                }
+                updated.work = {
+                    branch: currentBranch,
+                    base_branch: defaultBranch,
+                    started_at: now,
+                    started_by: actor,
+                };
+                updated.updated_at = now;
+                (0, ticket_js_1.writeTicket)(repoRoot, updated);
+            }
+            // Print the ticket ID on stdout — scriptable (while next=$(todo next <parent>))
+            process.stdout.write(`${nextId}\n`);
+            // Print summary on stderr so it doesn't pollute the captured value
+            process.stderr.write(`Activated ${nextId}: ${ticket.summary}\n`);
+        }
+        catch (err) {
+            (0, errors_js_1.handleError)(err);
+        }
+    });
+}

package/dist/commands/work.js

@@ -11,6 +11,7 @@ function registerWork(program) {
         .command("work <id>")
         .description("Start or resume work on a ticket")
         .option("--branch <name>", "override branch name")
+        .option("--skip-branch", "activate ticket without any git branch operations (orchestrator mode)")
         .option("--actor <name>", "override actor (also reads TODO_ACTOR env)")
         .action((id, opts) => {
         const ctx = (0, context_js_1.getContext)(true);
@@ -50,7 +51,31 @@ function registerWork(program) {
                 }
             }
             const defaultBranch = (0, git_js_1.getDefaultBranch)(repoRoot);
-            if ((0, git_js_1.branchExists)(branch, repoRoot)) {
+            if (opts.skipBranch) {
+                // --no-branch: orchestrator mode — activate on current branch without any git ops
+                const currentBranch = (0, git_js_1.getCurrentBranch)(repoRoot);
+                if (ticket.state !== "active") {
+                    const now = new Date().toISOString();
+                    let updated;
+                    try {
+                        updated = (0, state_js_1.applyTransition)(ticket, "active", { actor }, repoRoot);
+                    }
+                    catch (err) {
+                        console.error(`Error: ${err.message}`);
+                        process.exit(1);
+                    }
+                    updated.work = {
+                        branch: currentBranch,
+                        base_branch: defaultBranch,
+                        started_at: now,
+                        started_by: actor,
+                    };
+                    updated.updated_at = now;
+                    (0, ticket_js_1.writeTicket)(repoRoot, updated);
+                }
+                console.log(`Activated ticket ${ticket.id} on current branch ${currentBranch}.`);
+            }
+            else if ((0, git_js_1.branchExists)(branch, repoRoot)) {
                 // Resume
                 (0, git_js_1.checkoutBranch)(branch, repoRoot);
                 // Ensure ticket is active

package/dist/git.js

@@ -29,7 +29,11 @@ class GitError extends Error {
 exports.GitError = GitError;
 function exec(args, cwd) {
     try {
-        return (0, node_child_process_1.execFileSync)("git", args, { encoding: "utf8", cwd }).trim();
+        return (0, node_child_process_1.execFileSync)("git", args, {
+            encoding: "utf8",
+            cwd,
+            stdio: ["pipe", "pipe", "pipe"],
+        }).trim();
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@4-r-c-4-n-4/todo",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Git-native work tracking for coding agents",
   "main": "dist/cli.js",
   "bin": {
     "todo": "./dist/cli.js"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=20"
   },
   "files": [
     "dist/",