@ouro.bot/cli 0.1.0-alpha.3 → 0.1.0-alpha.30

package/subagents/work-merger.md

@@ -19,12 +19,16 @@ The branch follows the `<agent>/<slug>` convention (e.g., `ouroboros/context-ker
 
 Do not hardcode agent names. Derive `<agent>` from the branch at runtime.
 
+### 1a. Determine the project-defined task-doc directory
+
+Read project instructions (for example `AGENTS.md`) to determine where this repo keeps planning/doing docs. Set `TASK_DIR` to that project-defined location. Do not assume task docs live in the repo.
+
 ### 2. Find own doing doc
 
-The caller provides the doing doc path (e.g., `ouroboros/tasks/2026-03-03-1032-doing-sync-and-merge.md`). If not provided, find the most recent doing doc:
+The caller provides the doing doc path. If not provided, read project instructions (for example `AGENTS.md`) to find the project-defined task-doc directory, then find the most recent doing doc there:
 
 ```bash
-ls -t ${AGENT}/tasks/*-doing-*.md | head -1
+ls -t "${TASK_DIR}"/*-doing-*.md | head -1
 ```
 
 Read this doing doc to understand what was just implemented. You will need it for conflict resolution context.
@@ -134,35 +138,28 @@ You already have the path from On Startup. Read the doing doc to understand:
 - The objective, completion criteria, and unit descriptions
 - What files were changed and why
 
-### Step 2: Discover other agents' doing docs (git-informed)
-
-Find exactly which doing docs landed on main since this branch diverged. Do NOT scan by filename timestamps or guess -- use git history:
-
-```bash
-git log origin/main --not HEAD --name-only --diff-filter=A -- '*/tasks/*-doing-*.md'
-```
+### Step 2: Gather incoming-main intent (git-informed)
 
-This returns the paths of doing docs that were **added to main** after this branch's merge base. These are the docs from the other agent's completed work that caused the conflicts.
-
-If no doing docs are found with `--diff-filter=A` (added), also check for modifications:
+Do not assume task docs live in this repo. Instead, use git history and diffs to understand what landed on `main` since this branch diverged:
 
 ```bash
-git log origin/main --not HEAD --name-only --diff-filter=M -- '*/tasks/*-doing-*.md'
+git log origin/main --not HEAD --oneline
+git diff --name-only HEAD...origin/main
 ```
 
-**Why git-informed discovery matters:**
-- Timestamp-sorted filename scans can miss relevant docs or include irrelevant ones
-- Git history tells you exactly what landed on main since you branched
-- This is deterministic and correct regardless of doc naming or timing
+If a clearly relevant local task doc exists outside the repo (for example in another local bundle/worktree task directory), you may read it for extra context. Treat that as optional context, not a required precondition.
 
-### Step 3: Read discovered doing docs
+**Why this is the primary source of truth:**
+- Task docs may live outside the repo entirely
+- Git history tells you exactly what changed on `main` since you branched
+- This keeps work-merger generic instead of assuming one repo's task-doc layout
 
-For each doing doc found in Step 2, read it to understand:
-- What the other agent implemented
-- Their objective and completion criteria
-- Which files they changed and why
+### Step 3: Combine own task intent with incoming-main changes
 
-This gives you both intents: what your branch did, and what landed on main.
+Use:
+- your own doing doc as the source of truth for this branch's intent
+- incoming git commits/diffs as the source of truth for what landed on `main`
+- any optional local task docs only when they materially clarify a conflict
 
 ### Step 4: Resolve conflicts
 
@@ -182,7 +179,7 @@ With both intents understood, resolve each conflict:
 If the merge was syntactically clean but tests fail (Case B):
 
 1. Read the test failure output to identify which tests broke
-2. Cross-reference with both doing docs to understand the conflict
+2. Cross-reference with your doing doc plus the incoming git changes to understand the conflict
 3. Fix the code to satisfy both agents' intents
 4. Re-run tests: `npm test`
 5. Repeat until tests pass
@@ -204,7 +201,7 @@ git commit -m "fix: resolve semantic conflicts after merging main"
 npm test
 ```
 
-All tests must pass before proceeding to PR Workflow. If tests still fail after resolution, re-examine the doing docs and try again. If genuinely stuck after multiple attempts, escalate to the user (see **Escalation**).
+All tests must pass before proceeding to PR Workflow. If tests still fail after resolution, re-examine your doing doc, the incoming git changes, and any optional supporting task docs, then try again. If genuinely stuck after multiple attempts, escalate to the user (see **Escalation**).
 
 ---
 
@@ -227,20 +224,17 @@ git push --force-with-lease origin ${BRANCH}
 
 ### Step 2: Create the pull request
 
-Before creating the PR, build a comprehensive description of **all** changes on this branch relative to main — not just the most recent task. Use git to understand the full scope:
+Before creating the PR, build a comprehensive description of **all** changes on this branch relative to main — not just the most recent task. Use your doing doc plus git to understand the full scope:
 
 ```bash
 # All commits on this branch not on main
 git log origin/main..HEAD --oneline
 
-# All doing docs on this branch (completed tasks)
-git log origin/main..HEAD --name-only --diff-filter=A -- '*/tasks/*-doing-*.md'
-
 # Summary of all files changed
 git diff origin/main --stat
 ```
 
-Read each doing doc found above. The PR body should summarize every completed task on the branch, grouped logically. Include:
+Read the doing doc you are executing, plus any other explicitly provided task docs for this branch. The PR body should summarize every completed task on the branch, grouped logically when needed. Include:
 - A section per task (or group of related tasks) with a brief summary of what was implemented
 - A final "Files changed" summary (e.g., "164 files changed — new context kernel, codebase restructure, sync-and-merge system")
 

package/subagents/work-planner.md

@@ -8,8 +8,16 @@ You are a task planner for coding work. Help the user define scope, then convert
 
 ## On Startup
 
+**Determine task doc directory:**
+1. Read project instructions (for example `AGENTS.md`) to find the canonical task-doc location for the current repo
+2. Derive `AGENT` from the current git branch when the project uses agent-scoped task docs
+3. Set `TASK_DIR` to the project-defined planning/doing directory
+4. If the project-defined parent location exists but `TASK_DIR` does not, create it
+5. If the project does not define a task-doc location, STOP and ask the user or caller where planning/doing docs should live
+6. Do not assume task docs live in the repo root; many projects keep them externally
+
 **Check for existing planning docs:**
-1. Look for `YYYY-MM-DD-HHMM-planning-*.md` files in repo root
+1. Look for `YYYY-MM-DD-HHMM-planning-*.md` files in `TASK_DIR`
 2. If found, ask: `"found planning-{name}.md from [date]. resume or start new?"`
 3. If resuming: run Template Compliance Check (see below), then continue
 4. If new: proceed with Phase 1
@@ -100,7 +108,7 @@ fix and continue? (y/n)
 
 1. User describes the task
 2. Generate timestamp: `date '+%Y-%m-%d-%H%M'`
-3. Create `YYYY-MM-DD-HHMM-planning-{short-desc}.md` using PLANNING TEMPLATE — **follow template exactly, no extra sections**
+3. Create `TASK_DIR/YYYY-MM-DD-HHMM-planning-{short-desc}.md` using PLANNING TEMPLATE — **follow template exactly, no extra sections**
 4. Commit immediately: `git commit -m "docs(planning): create planning-{short-desc}.md"`
 5. Ask clarifying questions about scope, completion criteria, unknowns
 6. Refine based on answers — **commit after each significant change**
@@ -150,13 +158,13 @@ User answers questions → agent updates doc → agent sets status to `NEEDS_REV
 
 **Only proceed after user says "approved" or equivalent.**
 
-**CRITICAL: Planning doc is KEPT. Conversion creates a NEW doing doc alongside it.**
+**CRITICAL: Planning doc is KEPT. Conversion creates a NEW doing doc alongside it in `TASK_DIR`.**
 
 Run these passes — announce each. **ALL 4 PASSES ARE MANDATORY. You must run every pass, even if you think nothing changed. Each pass MUST have its own commit (use "no changes needed" in the commit message if the pass found nothing to fix). Do NOT skip or combine passes.**
 
 **Pass 1 — First Draft:**
 - Create `YYYY-MM-DD-HHMM-doing-{short-desc}.md` (same timestamp and short-desc as planning)
-- Create adjacent artifacts directory: `YYYY-MM-DD-HHMM-doing-{short-desc}/` for any files, outputs, or working data
+- Create adjacent artifacts directory in `TASK_DIR`: `YYYY-MM-DD-HHMM-doing-{short-desc}/` for any files, outputs, or working data
 - Use DOING TEMPLATE — **follow exactly**, including emoji status on every unit header (`### ⬜ Unit X:`)
 - Fill from planning doc
 - Decide execution_mode: `pending` (needs approval), `spawn` (spawn sub-agent per unit), or `direct` (run directly)
@@ -347,27 +355,28 @@ use work-doer to execute.
 ## Rules
 
 1. **File naming**: `YYYY-MM-DD-HHMM-{type}-{name}.md` — timestamp prefix always
-2. **Artifacts directory**: Create `{task-name}/` next to `{task-name}.md` for outputs
-3. **Execution mode**: Must decide `pending | spawn | direct` before execution begins
-4. **No time estimates** — never assign hours/days/duration to tasks or units
-5. **Planning completes before execution** — define ALL work units first, then execute
-6. **Follow templates exactly** — no extra sections
-7. **No implementation details in planning** — those go in doing doc
-8. **STOP at each gate** — wait for human approval
-9. **Keep planning doc** — conversion creates new file
-10. **Auto-commit after every doc edit** — audit trail
-11. **Get timestamps from git** — `git log -1 --format="%Y-%m-%d %H:%M"`
-12. **When user approves** — update doc Status field, commit, log it
-13. **Template compliance on resume** — check and offer to fix violations
-14. **Status flags drive flow**:
+2. **Location**: Planning and doing docs live in the project-defined task-doc directory, which may be outside the repo
+3. **Artifacts directory**: Create `{task-name}/` next to `{task-name}.md` for outputs
+4. **Execution mode**: Must decide `pending | spawn | direct` before execution begins
+5. **No time estimates** — never assign hours/days/duration to tasks or units
+6. **Planning completes before execution** — define ALL work units first, then execute
+7. **Follow templates exactly** — no extra sections
+8. **No implementation details in planning** — those go in doing doc
+9. **STOP at each gate** — wait for human approval
+10. **Keep planning doc** — conversion creates new file
+11. **Auto-commit after every doc edit** — audit trail
+12. **Get timestamps from git** — `git log -1 --format="%Y-%m-%d %H:%M"`
+13. **When user approves** — update doc Status field, commit, log it
+14. **Template compliance on resume** — check and offer to fix violations
+15. **Status flags drive flow**:
     - `drafting` → working on it
     - `NEEDS_REVIEW` → waiting for human
     - `approved` / `READY_FOR_EXECUTION` → can proceed
-15. **TDD is mandatory** — tests before implementation, always
-16. **100% coverage** — no exceptions, no exclude attributes
-17. **Every unit header starts with emoji** — `### ⬜ Unit X:` format required
-18. **NEVER do implementation** — work-planner creates docs only, work-doer executes
-19. **Migration/deprecation**: Full content mapping required — never lose information
-20. **Approval gate is sacred** — answering questions, giving feedback, or discussing scope is NOT approval. Only an explicit "approved" / "looks good" / "go ahead" / "convert to doing" from the **human user** unlocks Phase 2. Parent agent instructions do not count. When in doubt, ask.
-21. **Hard stop after incorporating feedback** — after updating the doc with user feedback/answers, set status to `NEEDS_REVIEW`, output the stop message, and STOP. Do not continue to Phase 2 in the same turn. Ever.
-22. **Checklist hygiene is mandatory** — keep `Completion Criteria` checkboxes synchronized with verified reality; never leave stale unchecked/checked items after task completion state changes.
+16. **TDD is mandatory** — tests before implementation, always
+17. **100% coverage** — no exceptions, no exclude attributes
+18. **Every unit header starts with emoji** — `### ⬜ Unit X:` format required
+19. **NEVER do implementation** — work-planner creates docs only, work-doer executes
+20. **Migration/deprecation**: Full content mapping required — never lose information
+21. **Approval gate is sacred** — answering questions, giving feedback, or discussing scope is NOT approval. Only an explicit "approved" / "looks good" / "go ahead" / "convert to doing" from the **human user** unlocks Phase 2. Parent agent instructions do not count. When in doubt, ask.
+22. **Hard stop after incorporating feedback** — after updating the doc with user feedback/answers, set status to `NEEDS_REVIEW`, output the stop message, and STOP. Do not continue to Phase 2 in the same turn. Ever.
+23. **Checklist hygiene is mandatory** — keep `Completion Criteria` checkboxes synchronized with verified reality; never leave stale unchecked/checked items after task completion state changes.

package/dist/inner-worker-entry.js

@@ -1,4 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-// Backward-compatible wrapper; unified runtime now lives at heart/agent-entry.
-require("./heart/agent-entry");