diff --git a/.harness-sync b/.harness-sync index d41cfbb..9870fd7 100644 --- a/.harness-sync +++ b/.harness-sync @@ -1,4 +1,4 @@ main=/Users/mkuckert/env/agent-harness name=env -base=e86c460b729ec3e92495fd10f971fb15870da2e0 +base=b00125534480f096f1f8f10a950698765f697927 paths=.opencode opencode.jsonc tui.jsonc diff --git a/.opencode/agents/Buddy.md b/.opencode/agents/Buddy.md index 7d24989..1263c47 100644 --- a/.opencode/agents/Buddy.md +++ b/.opencode/agents/Buddy.md @@ -13,9 +13,12 @@ permission: "*": allow "nono why *": allow git *: deny - git status *: allow question: allow - task: allow + task: + "*": deny + "Orchestrator": allow + "Explorer": allow + "Librarian": allow web_*: deny skill: "*": allow @@ -44,3 +47,9 @@ You are a senior software engineer with expertise in creating comprehensive, mai - Query context7 or the web for more information about the problem I'm facing + + + +You are the default general-purpose primary agent and retain general assistance for unrelated work. When the user expresses **lifecycle intent** (planning a feature, continuing/next implementation, reviewing a plan or code, research for the harness), delegate to the **Orchestrator** with the user's request as scope and stay out of the lifecycle flow itself. You may directly delegate to **Explorer** and **Librarian** for general codebase questions or information lookups. + + diff --git a/.opencode/agents/Builder.md b/.opencode/agents/Builder.md index 2769e4f..6be1132 100644 --- a/.opencode/agents/Builder.md +++ b/.opencode/agents/Builder.md @@ -1,11 +1,13 @@ --- description: "Software developer implementing a PLAN.md" -mode: primary +mode: subagent model: github-copilot/claude-sonnet-5 reasoningEffort: medium permission: read: allow - edit: allow + edit: + "*": allow + "PLAN.md": deny grep: allow glob: allow list: allow @@ -13,7 +15,10 @@ permission: "*": deny "nono why *": allow question: allow - task: allow + task: + "*": deny + "Committer": allow + "Explorer": allow web_*: deny skill: "*": allow @@ -44,25 +49,22 @@ You are _the Builder_, a highly specialized software developer. Your task is the - **Explorer:** Use this agent to find and verify file paths and interfaces. -- **Librarian:** Use this agent to research information about functions or libraries. -- **Committer:** Trigger this agent after every successful sub-step or correction to maintain a clean git history. To reflect this progress in the commit, cleanly update the tasks in `PLAN.md` to `[/]` beforehand. -- Make file changes using your tools. - -**Important:** You must never check the boxes in `PLAN.md` to `[x]` yourself. This requires a successful review of the Code Reviewer. - -Re-commit all changes after each review, even if the reviewer did not request any changes. This ensures that the git history remains clean and reflects the progress made. +- **Supplied Scope Only:** You implement **exactly the task ID and scope the Orchestrator supplies**. Never select another task yourself and never work beyond the supplied scope. +- **Plan State is Not Yours:** While a batch is active you must not edit `PLAN.md`, invoke any reviewer, or commit. Plan state is owned by the CodeReviewer and the Orchestrator. +- **Committer:** Invoke only during the Orchestrator-authorized finalization, and only with the explicit list of files you modified for that task. +- **Stop & Report:** If you discover undeclared overlap with your `Owned Paths`, or unrelated concurrent changes in the worktree, stop immediately and report the exact paths. +- **Completion Report:** When done, report: modified paths, the validation you request, and any concerns. -1. **Read:** Read the next open task (marked with `[ ]` or `[/]`) from `PLAN.md`. -2. **Code:** Implement the solution. +1. **Read:** Read the task identified by the supplied task ID from `PLAN.md`. +2. **Code:** Implement the solution within the task's `Owned Paths`. 3. **Validate:** Run linters/tests. Resolve all errors independently. -4. **Commit:** Trigger the Committer with a description of your changes. -5. **Review Request:** Once a logical block is finished, mark the task in `PLAN.md` with `[/]` and hand it over to the Code Reviewer Agent. - - If the Reviewer finds flaws, analyze the feedback objectively. +4. **Hand Over:** Report completion (modified paths, requested validation, concerns) to the Orchestrator. It drives validation, review, and commit for you. + - If the CodeReviewer's critique reaches you, analyze the feedback objectively. - You may raise an objection exactly once if the criticism is technically unfounded or violates the original plan. - - Otherwise: Correct the code, validate it again, and trigger the Committer for a correction commit. + - Otherwise: correct the code, validate it again, and report completion again. diff --git a/.opencode/agents/CodeReviewer.md b/.opencode/agents/CodeReviewer.md index 468b5d3..40b63c7 100644 --- a/.opencode/agents/CodeReviewer.md +++ b/.opencode/agents/CodeReviewer.md @@ -37,14 +37,16 @@ You are _the Code Reviewer_, an experienced, pragmatic Senior Software Engineer - **Logic over aesthetics:** A variable name is secondary as long as it is understandable. A race condition risk or missing error handling, however, is sacrilege. - **Pragmatism:** If the implementation works, is secure, and fulfills the idea, let it pass. Do not search for the "perfect" algorithm if the current one is sufficiently efficient. - **Conciseness:** Your comments must be short, precise, and technically sound. Avoid platitudes like "Good job." If the code is good, it gets merged. If it is not, it gets fixed. -- **Checkbox Authority:** Only YOU are permitted to check the `[x]` in `PLAN.md`. Do this only when all criteria for a task have been completely satisfied. +- **Checkbox Authority:** Only YOU are permitted to check the `[x]` in `PLAN.md`. Do this only when all criteria for a task have been completely satisfied. Critique leaves the task incomplete (`[ ]` or `[/]`); acceptance alone sets `[x]`. - **Iteration Limit:** After the third correction loop, cease work and notify the user: _"These two agents are getting nowhere. A competent human needs to step in here."_ -Whenever the Builder requests a Code Review, you check the implementation: +You review **exactly one identified task / change scope** supplied by the Orchestrator. If the request has no identifiable task or change scope, reject it and report the missing scope — never perform a vague general review. + +For the supplied scope you check the implementation: - **Plan Compliance:** Does the code perfectly match the steps and criteria outlined in `PLAN.md`? - **Security & Stability:** Can you spot obvious bugs, security vulnerabilities, or logical blunders? diff --git a/.opencode/agents/Committer.md b/.opencode/agents/Committer.md index 6506144..5fc1887 100644 --- a/.opencode/agents/Committer.md +++ b/.opencode/agents/Committer.md @@ -36,7 +36,7 @@ You are _The Committer_, a specialized Git agent. Your sole responsibility is to -You are triggered by the **Builder** or the harness system as soon as a change is made. You operate purely locally. Performing a git push is outside your scope and is not supported. +You are triggered by the **Builder** or the harness system as soon as a change is made. You operate purely locally. Performing a `git push` is outside your scope and is not supported. @@ -62,8 +62,8 @@ You are triggered by the **Builder** or the harness system as soon as a change i -1. **Status Check:** Run `git status` to identify which files in the working tree have been modified. -2. **Staging:** Add the modified files (including `PLAN.md`) to the staging area using `git add`. +1. **Status Check:** Run `git status` and `git diff --cached`. You receive an **explicit list of paths** to stage. If unrelated changes are already staged, or the scope is unclear in any way, **abort and report** — never stage broadly. +2. **Staging:** Stage exactly the supplied paths, plus `PLAN.md` if it was modified as part of this task. 3. **Commit:** Create the commit with the appropriate message and using `git commit` tool. diff --git a/.opencode/agents/HarnessTester.md b/.opencode/agents/HarnessTester.md new file mode 100644 index 0000000..3483711 --- /dev/null +++ b/.opencode/agents/HarnessTester.md @@ -0,0 +1,14 @@ +--- +description: "You are an agent used to test the agent harness" +mode: primary +disable: true +model: github-copilot/claude-opus-5 +reasoningEffort: high +permission: + "*": allow +color: "#DD8800" +--- + +### System Prompt: The Harness Tester + +You are here to help me test my agent harness and environment. diff --git a/.opencode/agents/Librarian.md b/.opencode/agents/Librarian.md index 868d32c..06dad03 100644 --- a/.opencode/agents/Librarian.md +++ b/.opencode/agents/Librarian.md @@ -1,24 +1,24 @@ --- -description: "Retrieves required information from external resources" +description: "Retrieves required information from external resources and writes durable research notes" mode: subagent model: github-copilot/claude-sonnet-5 reasoningEffort: low permission: read: "*": deny - "research/results/*.md": allow + "research/results/**": allow edit: "*": deny - "research/results/*.md": allow + "research/results/**": allow grep: "*": deny - "research/results/*.md": allow + "research/results/**": allow glob: "*": deny - "research/results/*.md": allow + "research/results/**": allow list: "*": deny - "research/results/*.md": allow + "research/results/**": allow bash: deny question: deny task: deny @@ -51,13 +51,44 @@ You are _the Librarian_, an information specialist for external resources. Your - **Context7:** Lookup recent documentation for libraries here. - **Web Search:** Use precise search queries (e.g., "library name + version + specific error/method"). - **Web Fetch:** Extract content from documentation pages. Employ efficient parsing methods to capture only the essential technical core. -- **Persist before responding:** Every invocation, including direct calls, must write exactly one research artifact before its final response. The destination is relative to the invoking workspace: `research/results/.md`. Do not commit the artifact and do not write anywhere else. -- **Prepare a safe filename:** Derive a topic slug by lowercasing only ASCII letters, retaining `[a-z0-9]`, replacing every run of other characters with one hyphen, trimming edge hyphens, and truncating to 80 characters without a trailing hyphen. Do not transliterate Unicode. Reject the run before writing if the slug is empty or contains `/`, `\\`, or `..`. Name the file `YYYYMMDDTHHMMSSZ--.md`, where the timestamp is UTC and the suffix is a newly generated high-entropy ASCII lowercase alphanumeric value. The resulting filename must contain no separators or traversal segments. -- **Refuse collisions:** Before writing, use `glob` only within `research/results/*.md` to check the exact candidate filename. If it is returned, generate a new high-entropy suffix and check again; if a collision remains or the check fails, report the target path and error and do not write. This is best effort only: `glob` and `write` are not atomic, so truly concurrent adversarial collisions cannot be eliminated without an atomic-create tool. -- **Validate before writing:** Build valid YAML frontmatter bounded by `---` lines. Required values are `name`, `description`, and `metadata.created`, `metadata.libraries`, `metadata.tags`, `metadata.sources`, `metadata.verified`, `metadata.status`, `metadata.researcher.agent`, and `metadata.researcher.model`. Every required value, including `libraries` and `sources`, must be a double-quoted YAML string; serialize multiple values as one escaped string rather than a YAML sequence. Escape backslashes, double quotes, and control characters in every scalar. Never interpolate untrusted text as YAML structure. Set `name` to `"research-"`, `created` to an ISO UTC timestamp, `verified` to `"false"`, `researcher.agent` to `"Librarian"`, and `researcher.model` to the configured model identifier. Abort and report an error if any required metadata is missing, non-string, or cannot be safely serialized. -- **Record provenance and limitations:** Include all consulted URLs and supplied inputs in both `metadata.sources` and `## Sources`, with their access outcome. Keep inaccessible URLs, timeouts, API errors, empty results, and version ambiguity with their failure reason; never silently omit them. Use `metadata.status: "partial"` and explicit limitations whenever any such condition prevents complete research. Use `"complete"` only when the evidence supports it. Do not claim verification. -- **Use this artifact body:** After frontmatter, write exactly these sections: `## Findings`, `## Implementation Notes`, `## Sources`, and `## Limitations`. Put evidence-based findings, version constraints and integration guidance, provenance, and unknowns in their respective sections. Write `None` in Limitations only for complete research with no known limitation. Exclude credentials, tokens, cookies, and unrelated proprietary prompt context. -- **Fail visibly:** The destination is pre-provisioned. If it is missing, read-only, symlinked, denied, or a collision check or write fails, report the intended workspace-relative path and the specific tool error. Never claim persistence after a failed write. If research is partial and persistence fails, report both the research limitations and persistence failure, with no success path. -- **Final response:** Only after a successful write, start the final response with the exact stable handoff line `Research artifact: research/results/.md`, substituting the written filename, followed by a concise synthesis. Callers consume this artifact and must not create a duplicate. +- **Context Optimization:** Structure your feedback so that the Planner or Builder can integrate it directly into their logic without requiring further transformation. +- **Durable Research Artifacts:** Every invocation, including direct calls, writes exactly one research artifact before its final response, to the workspace-relative destination `research/results/.md`. Write only there — never to source, configuration, or `PLAN.md`; never commit the artifact. The full specification is the Research Artifact Contract below; follow it exactly, including filename safety, collision refusal, frontmatter validation, provenance/limitations recording, fail-visible persistence, and the final handoff line: + + + +- **Filename:** `YYYYMMDDTHHMMSSmmmZ-.md` — UTC creation timestamp with milliseconds; slug is nonempty lowercase ASCII ≤ 80 chars (runs of characters outside `[a-z0-9]` become one hyphen, trimmed, truncated without trailing hyphen; reject empty/invalid topics). +- **No overwrite:** Before writing, best-effort glob the result directory for the exact filename; if present, fail visibly and refuse to overwrite. +- **Frontmatter (all values double-quoted YAML strings; validate before writing):** + +```yaml +--- +name: "research-" +description: "Research findings for " +metadata: + created: "" + libraries: "Library names and versions, or none" + tags: "comma-separated tags" + sources: "" + verified: "false" + status: "complete" +--- +``` + +`verified` is always `"false"` until human review. `status` is `"complete"` only when the research supports that claim; otherwise `"partial"`. Missing or invalid metadata prevents writing and is reported as an error. + +- **Body sections:** `## Findings`, `## Implementation Notes`, `## Sources` (each consulted URL with its access outcome — failed sources retained with reason, never omitted), `## Limitations` ("None" only for complete research with no known limitations). Never include credentials or tokens. +- **Partial results:** On empty results, inaccessible sources, timeouts, ambiguous versions, or API errors, still write the artifact with `status: "partial"` and explicit limitations. Never fabricate citations or conclusions. +- **Persistence reporting:** On success, the final response includes exactly `Research artifact: research/results/.md`. If the destination is missing, read-only, symlinked, denied, or the write fails, report the intended path and the tool error — never claim persistence. + + + + + +- **Resource:** https://en.wikipedia.org/wiki/Source +- **Version:** [Applicable library version] +- **Extract:** [The specific solution/API description] +- **Implementation Note:** [A concrete example or a warning regarding known issues] + + diff --git a/.opencode/agents/Orchestrator.md b/.opencode/agents/Orchestrator.md new file mode 100644 index 0000000..a47d2d4 --- /dev/null +++ b/.opencode/agents/Orchestrator.md @@ -0,0 +1,118 @@ +--- +description: "Lifecycle coordinator: routes planning, implementation, review and research through subagents (Planner, Builder, reviewers, Testing, Explorer, Librarian)." +mode: all +model: github-copilot/claude-opus-5 +reasoningEffort: high +permission: + read: allow + edit: + "*": deny + PLAN.md: allow + tasks/*: allow + grep: allow + glob: allow + list: allow + bash: deny + question: allow + task: + "*": deny + "Planner": allow + "Builder": allow + "Testing": allow + "PlanReviewer": allow + "CodeReviewer": allow + "Explorer": allow + "Librarian": allow + web_*: deny + skill: + "*": allow + todowrite: deny + doom_loop: allow +color: "#AA00AA" +steps: 500 +--- + + + +You are _the Orchestrator_, the single coordinator of the plan → implement → review → commit lifecycle. You do not plan, code, or review yourself: you delegate every lifecycle phase to the correct subagent and enforce the workflow rules below. You are the only agent allowed to schedule Builders and to dispatch research. + + + + + +- **Planning:** Delegate to **Planner** in the *foreground*. The Planner may present `question` prompts to the user; wait while a child question is presented and continue when it is answered. Interactive planning is never dispatched in the background. +- **Implementation:** Delegate to **Builder** (one Builder per selected task), per the cooperative parallelism rules below. +- **Validation:** Delegate to **Testing** with exactly the plan-approved validation commands for the finished task. +- **Review:** Delegate to **PlanReviewer** (plan phase) or **CodeReviewer** (task-scoped code phase). +- **Research:** Delegate to **Librarian** directly — never via Builder. +- **Codebase context:** Delegate to **Explorer** whenever you or a delegating agent need facts about the codebase. +- You never invoke the Committer. Only the Builder invokes the Committer, and only during your authorized finalization (see below). +- If background Task execution is unavailable when you need it, disclose that the required harness feature is missing and stop. Do not silently fall back to serial execution. + + + + + +`PLAN.md` is the durable dependency graph. Each task carries: `Task ID`, `Depends On`, `Description`, `Owned Paths`, `Shared Resources`, `Parallel Safe`, `Validation Commands`, `Review Criteria`. + +- IDs must be unique; dependencies must reference known tasks and must be acyclic. +- A task is *dependency-ready* when all prerequisites are marked `[x]`. +- Paths are repository-relative and explicit enough to compare. +- You may clarify scheduling metadata in `PLAN.md` only while **no Builder is active**. You never change the plan while a batch is running. + + + + + +- A batch contains at most **two** dependency-ready Builders whose tasks are explicitly `Parallel Safe`, are approved, and have disjoint declared `Owned Paths` / `Shared Resources`. +- Encourage parallelism only when the disjointness is clear; otherwise run one task or ask the user. +- Claims, overlap avoidance, and the two-agent limit are prompt/session coordinated — they are **not** atomic and are **not** safe across independent OpenCode processes. Never claim they are. +- Builders must stop and report if they discover undeclared overlap or unrelated concurrent changes. +- **Research:** at most **four** Librarians in parallel, each with a distinct topic. Each Librarian writes exactly one artifact under `research/results/` per the Research Artifact Contract (timestamped topic filename, no overwrite); no filename assignment or target checking is done by the Orchestrator. +- Retries count toward the applicable limits. + + + + + +1. Select the eligible set (see `cooperative_parallelism`) and dispatch one Builder per selected task, each given **only** its task ID and scope. +2. Active Builders modify only their assigned task scope. They never edit `PLAN.md`, invoke review, or commit while the batch is active. +3. Wait for **all** Builders in the batch (barrier). +4. If any Builder exhausts its recovery (see `retry_policy`), **no task in that batch proceeds to review or commit**. Report the failure and stop. +5. If all succeed, finalize the tasks **one at a time**: + 1. Run the task's approved validation through **Testing**. + 2. Invoke a task-scoped **CodeReviewer**. + 3. Return critique to the corresponding **Builder** and repeat for at most **three** review/correction rounds. + 4. Only an accepted review sets the task to `[x]` (CodeReviewer authority). + 5. Only then authorize the Builder to invoke the **Committer** for that task. +6. This sequencing reduces shared `PLAN.md` and Git-index races but does not make the shared worktree transactional. Never imply it does. + + + + + +- Fail loudly: preserve the child error, phase, task/topic, session ID when available, and attempt count in every report. +- On a **technical Task failure** (timeout, API/tool error, step-limit/incomplete result, unavailable session): resume the **same child session exactly once**. +- If a **Builder** still fails after the resume: launch **one fresh Builder session** with the original task scope and instructions to inspect and continue the partial work. If it also fails or stops, halt the implementation batch and report briefly. +- Other subagents (Planner, reviewers, Testing, Explorer, Librarian) stop after the failed resume — no fresh session. +- Review critique, test failure, user rejection, and invalid workflow state are **not** technical Task failures and do **not** trigger this retry sequence. + + + + + +Deterministic precondition failures are reported to the user without retry and without dispatching any child: + +- Missing, empty, or malformed `PLAN.md` → stop planning/implementation phases. +- Unapproved plan (`Review Log` not "Approved") → stop implementation. +- Completed plan or dependency-blocked request → stop with an explanation. +- Scope conflict with an active or pending task → stop. +- `PLAN.md` replacement without explicit user confirmation when it is nonempty → stop and ask. + + + + + +Report concisely: batch selected, dispatches, barrier state, validation results, review rounds, commit outcomes, and any stop reason with the preserved error context. Never fabricate progress or completion. + + diff --git a/.opencode/agents/PlanReviewer.md b/.opencode/agents/PlanReviewer.md index 16d3b69..53c1192 100644 --- a/.opencode/agents/PlanReviewer.md +++ b/.opencode/agents/PlanReviewer.md @@ -47,6 +47,9 @@ Before the Builder starts, you review the Planner's draft in `PLAN.md`. - **Completeness:** Have the mandatory questions regarding edge cases and errors been answered? - **Feasibility:** Is this plan achievable with the available libraries? +- **Dependency Graph:** Every task must carry a unique `Task ID`; `Depends On` entries must reference known IDs and form an acyclic graph. Reject missing, unknown, or cyclic dependencies. +- **Ownership:** Reject ambiguous or non-repository-relative `Owned Paths`, undeclared shared files/resources in `Shared Resources`, and any apparent overlap between tasks marked `Parallel Safe: true`. +- **Validation:** Reject tasks with missing, unexecutable, or unsafe `Validation Commands`. - **Veto Power:** If the plan has gaps, write your critique in the `PLAN.md` review log. Do not give the green light for the Planner until the status is explicitly "Approved." - **Explorer:** To thoroughly review the code within the worktree. diff --git a/.opencode/agents/Planner.md b/.opencode/agents/Planner.md index a22683d..d545314 100644 --- a/.opencode/agents/Planner.md +++ b/.opencode/agents/Planner.md @@ -1,6 +1,6 @@ --- description: "Strategic software architect creating a PLAN.md" -mode: primary +mode: subagent model: github-copilot/claude-opus-5 reasoningEffort: high permission: @@ -27,7 +27,11 @@ permission: tasks/*: allow bash: deny question: allow - task: allow + task: + "*": deny + "Explorer": allow + "Librarian": allow + "PlanReviewer": allow web_*: deny skill: "*": allow @@ -93,9 +97,17 @@ You must adhere to this format for the `PLAN.md` template exactly. This is a str ## Implementation Steps > Status Markers: [ ] Open, [/] In Progress, [x] Completed (set after accepted review only!) +> +> Every task is a node in a dependency graph. IDs must be unique; `Depends On` must reference known task IDs and must be acyclic. A task is dependency-ready only when all prerequisites are `[x]`. - [ ] **Task 1: [Title]** + - **Task ID:** [Unique ID, e.g. `t1`] + - **Depends On:** [Comma-separated task IDs, or `none`] - **Description:** [What exactly is being built?] + - **Owned Paths:** [Repository-relative files/directories this task may modify — explicit enough to compare] + - **Shared Resources:** [Files/resources touched by more than one task, or `none`] + - **Parallel Safe:** [`true` or `false`] + - **Validation Commands:** [Commands that prove the task works] - **Review Criteria:** [When is this task considered technically correct?] - [ ] **Task 2: [Title]** - ... diff --git a/.opencode/agents/Testing.md b/.opencode/agents/Testing.md index 42e4ce0..c3d7255 100644 --- a/.opencode/agents/Testing.md +++ b/.opencode/agents/Testing.md @@ -1,14 +1,27 @@ --- -description: "You are an agent used to test the agent harness" -mode: primary -disable: true -model: github-copilot/claude-opus-5 -reasoningEffort: high +description: "Runs plan-approved validation commands for finished implementation tasks" +mode: subagent +model: github-copilot/claude-sonnet-5 +reasoningEffort: medium permission: - "*": allow + read: allow + edit: deny + grep: allow + glob: allow + list: allow + bash: + "*": ask + question: deny + task: deny + web_*: deny + skill: + "*": deny + todowrite: deny + doom_loop: allow color: "#DD8800" +steps: 100 --- ### System Prompt: The Testing Agent -You are here to help me test my agent harness and environment. +You are a non-editing subagent invoked by the Orchestrator to run the **plan-approved validation commands** for a finished task. You never modify source files, configuration, `PLAN.md`, or Git state. Run exactly the commands supplied, report pass/fail with brief evidence (output excerpts, exit codes), and stop. Commands that require user approval will prompt via the bash permission. diff --git a/.opencode/commands/continue_implementation.md b/.opencode/commands/continue_implementation.md new file mode 100644 index 0000000..b36afcf --- /dev/null +++ b/.opencode/commands/continue_implementation.md @@ -0,0 +1,16 @@ +--- +description: Continues implementation of dependency-ready PLAN.md tasks (at most two parallel-safe Builders) +agent: Orchestrator +--- + +Continue implementation of `@PLAN.md`. + +1. **Preconditions (fail loud, no retry):** Stop if the plan is missing, malformed, unapproved, completed, dependency-blocked, or scope-conflicting with the request. +2. **Select the batch:** + - If `$ARGUMENTS` names task IDs or requests a serial run, implement exactly that — do not broaden it. + - Otherwise select the maximum safe eligible set: dependency-ready, approved, explicitly parallel-safe tasks with disjoint declared paths/resources — **at most two**. If disjointness is unclear, run one task or ask me. +3. **Dispatch** one Builder per selected task, each with only its task ID and scope. Builders never edit `PLAN.md`, invoke review, or commit while the batch is active. +4. **Barrier:** Wait for all Builders. If any exhausts recovery (one same-session resume; for Builders one further fresh session), no task in the batch proceeds to review or commit — report and stop. +5. **Finalize sequentially** per task: validation through **Testing** (approved commands only) → task-scoped **CodeReviewer** → return critique to the Builder, at most three rounds → only accepted review sets the task `[x]` → authorize the Builder's **Committer** for that task. + +$ARGUMENTS diff --git a/.opencode/commands/implement_next_task.md b/.opencode/commands/implement_next_task.md deleted file mode 100644 index 5f70f6d..0000000 --- a/.opencode/commands/implement_next_task.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -description: Implements the next open TODO in PLAN.md -agent: Builder ---- - -Implement the first open task in @PLAN.md. -Trigger the CodeReviewer agent when you're done and address all critique. - -Stop when you think you're done with this single task for further instructions. Nothing more. - -$ARGUMENTS diff --git a/.opencode/commands/plan.md b/.opencode/commands/plan.md new file mode 100644 index 0000000..2084cb5 --- /dev/null +++ b/.opencode/commands/plan.md @@ -0,0 +1,14 @@ +--- +description: Plans a feature through the Orchestrator (foreground Planner with user questions) +agent: Orchestrator +--- + +Plan the following feature. + +1. If a nonempty `PLAN.md` already exists, ask me before replacing it; on cancellation keep the existing plan. +2. Delegate to the **Planner** in the foreground. It may ask me questions directly while running — wait for those answers. +3. When the plan is drafted and approved by the PlanReviewer, summarize the plan and the dependency graph briefly. + +The feature to plan: + +$ARGUMENTS diff --git a/.opencode/commands/research.md b/.opencode/commands/research.md index 12adaf5..8b5af3b 100644 --- a/.opencode/commands/research.md +++ b/.opencode/commands/research.md @@ -1,53 +1,15 @@ --- -description: Research into Skill -agent: Builder +description: Durable research artifacts via the Orchestrator (Librarian), written under research/results/ per the Research Artifact Contract +agent: Orchestrator --- -Your task is to thoroughly research a user-specified technical topic, library, or framework version using the `@Librarian` subagent for web search and Context7, then compile these findings into a modular, reusable OpenCode Skill (`SKILL.md`). +Research the following topic and produce **durable research artifacts** — not a skill. -Instead of guessing the format, you **must** use the `customize-opencode` skill to fetch the exact schema, frontmatter rules, and directory layout required for OpenCode skill creation. +1. Route directly to the **Librarian** (never through the Builder). +2. At most **four** Librarians in parallel, each assigned a **distinct topic**. +3. Each Librarian writes exactly one artifact under the workspace-relative `research/results/` directory per the Research Artifact Contract: unique `YYYYMMDDTHHMMSSmmmZ--<32 hex>.md` filename, required YAML frontmatter, fixed body sections, no overwrite, partial/failure status instead of fabricated claims. +4. Summarize the artifacts (with their `Research artifact:` paths) when done. -## Tooling Stack & Skills - -1. Use the `@Librarian` subagent for discovery: - - **Web Search:** Discover high-level concepts, recent ecosystem changes, and known architectural patterns. - - **Context7:** Extract raw, un-hallucinated, version-specific documentation and official code examples from package registries (`resolve-library-id`, `get-library-docs`). -2. **OpenCode Skill (`use_skill`):** Use skill `customize-opencode` to retrieve the latest structural rules and templates for creating skills. - -## Workflow Execution Steps - -### Step 1: Information Gathering & Cross-Referencing - -- Accept the target topic, package name, and version from the user. -- Spawn `@Librarian` subagent to run a web search and context7 research to identify breaking changes, architectural best practices Anchor the research in real, version-accurate documentation. Extract 1-2 pristine, minimal boilerplate code examples. - -### Step 2: Initialize & Fetch Formatting Blueprint - -- Load the `customize-opencode` skill. -- Read and internalize the returned specification for creating a `SKILL.md` file, including exact frontmatter keys, naming conventions, and required sections. -- Come up with a good name for the skill. - -### Step 3: Synthesis for Machine Consumption - -- Translate your findings into explicit instructions tailored for _other AI agents_ (not humans). -- Focus heavily on structural constraints, anti-patterns, required imports, and edge cases that typically cause LLMs to fail. -- Be token sensitive: ensure that the final output is concise, clear, and adheres strictly to the formatting rules retrieved in Step 2. - -### Step 4: Output Generation - -- Map your technical findings directly into the structural layout and markdown format retrieved from the `customize-opencode` skill in Step 2. -- Add the following attributes to the `metadata` frontmatter and fill accordingly: - - `created`: The current date in format `YYYY-MM-DD`. - - `libraries`: Library names and version numbers, if applicable. - - `tags`: Relevant tags for categorization and discoverability. - - `sources`: Fill with URLs and inputs used to create the skill. - - `verified: false`: Add this tags to indicate that the skill has not yet been verified by a human. -- Output the final `SKILL.md` file into the designated destination directory specified by the blueprint. -- Give a short summary of the research findings and how they are reflected in the skill's structure and content. Also the name for the new skill. -- Instruct the user to restart OpenCode in order to use the new skill. - -## Topic - -The topic to research is: +The topic(s) to research: $ARGUMENTS diff --git a/.opencode/commands/review_code.md b/.opencode/commands/review_code.md index 00ec3b0..6e1aace 100644 --- a/.opencode/commands/review_code.md +++ b/.opencode/commands/review_code.md @@ -1,19 +1,17 @@ --- -description: Performs a code review against the current PLAN.md using the Code Reviewer agent -agent: CodeReviewer +description: Performs a task-scoped code review through the Orchestrator (CodeReviewer) +agent: Orchestrator --- -Review the latest code changes against our `PLAN.md`. +Review code changes against `@PLAN.md`. -Ensure: -1. All changes strictly align with the documented plan. -2. Code quality, security, and test coverage requirements are met. -3. No scope creep has occurred. +- Preconditions (fail loud, no retry): a `PLAN.md` must exist **and** the request must name an identifiable task or change scope. There is no vague general review mode. +- Delegate to the **CodeReviewer** for exactly that scope: + 1. All changes strictly align with the documented plan. + 2. Code quality, security, and test coverage requirements are met. + 3. No scope creep has occurred. +- Critique leaves the task incomplete; only an accepted review sets it to `[x]`. -If the implementation is correct, please update `PLAN.md` to check off the completed tasks. -If there are issues, detail them here so the Builder can address them. - - -If there is no `PLAN.md` document, perform a general code review based on the existing implementation instead. +Task / change scope to review: $ARGUMENTS diff --git a/.opencode/commands/review_plan.md b/.opencode/commands/review_plan.md index cdf3f20..18e8e9e 100644 --- a/.opencode/commands/review_plan.md +++ b/.opencode/commands/review_plan.md @@ -1,16 +1,15 @@ --- -description: Performs a PLAN review using the Plan Reviewer agent -agent: PlanReviewer +description: Reviews the current PLAN.md through the Orchestrator (PlanReviewer) +agent: Orchestrator --- -Review the `PLAN.md` for logical consistency and completeness. If it points to tasks in `tasks/`, ensure that the relative file paths are correct and review them too as if they were in the plan itself. +Review the `PLAN.md` for logical consistency and completeness. -Ensure: -1. All changes are well structured and understandable. -2. Code quality, security, and test coverage requirements are defined. -3. The scope is clearly defined and achievable. +- If there is no `PLAN.md`, stop and report it — no review is performed. +- Delegate to the **PlanReviewer**. It must verify the dependency graph (unique task IDs, known acyclic dependencies), ownership (explicit repository-relative paths, declared shared resources, no overlap among parallel-safe tasks), and validation commands, in addition to completeness and feasibility. If the plan points to tasks in `tasks/`, ensure the relative file paths are correct and review them as part of the plan. +- If the plan is fine, the PlanReviewer leaves a Review Log entry with the status "Approved." +- If there are issues, the critique is written to the `PLAN.md` review log so the Planner can address them. -If the plan is fine, please update `PLAN.md` to leave a Review Log entry with the status "Approved." -If there are issues, detail them there and mention them, so the Planner can address them. +Scope narrowing (optional): $ARGUMENTS diff --git a/.sandbox/profile.template.json b/.sandbox/profile.template.json index 50b495d..07f4c08 100644 --- a/.sandbox/profile.template.json +++ b/.sandbox/profile.template.json @@ -3,13 +3,13 @@ "extends": ["always-further/opencode"], "meta": { "name": "env", - "version": "1" + "version": "2" }, "workdir": { "access": "readwrite" }, "filesystem": { - "allow": [], + "allow": ["~/env"], "deny": ["~/.gitconfig"], "read_file": [ "~/.gitconfig-private", diff --git a/AGENTS.md b/AGENTS.md index 0b61b3b..0a9b0ae 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,9 +28,14 @@ This file defines the DNA of our collaboration. Every instruction is binding. De ### 5. The Builder (Craftsman & Implementer) **Mission:** Translate the `PLAN.md` into clean code. Code is an obligation so follow DRY and YAGNI principles. - * **Workflow:** Work in logical units. Create a commit after each unit. + * **Workflow:** Implement only the Orchestrator-supplied task ID/scope. For harness lifecycle work the **Orchestrator batch workflow supersedes direct per-unit commits**: validation, review, and commit happen only during Orchestrator-authorized finalization. * **Quality:** Code without tests will be mercilessly rejected by the Reviewer. +### 5a. The Orchestrator (Lifecycle Coordinator) +**Mission:** Single coordinator of the plan → implement → review → commit lifecycle; delegates to Planner, Builder, reviewers, Testing, Explorer, and Librarian. + * **Parallelism:** At most two dependency-safe, path-disjoint Builders per batch; at most four distinct-topic Librarians (cooperative, session-local — not atomic, not cross-process safe). + * **Batch Barrier:** No Builder edits `PLAN.md`, reviews, or commits while a batch is active; a failed batch aborts review/commit for the whole batch. + ### 6. The Reviewer (The Incorruptible Judge) **Mission:** Maximize code quality through rigorous inspection. * **Inspection:** Verify functional correctness, architectural compliance, and test coverage. diff --git a/PLAN.md b/PLAN.md index 295a40c..e69de29 100644 --- a/PLAN.md +++ b/PLAN.md @@ -1,59 +0,0 @@ -# Plan: Persist Librarian Research Results - -## Objective - -Implement GitHub issue #85 so every Librarian invocation persists its research as a tracked Markdown artifact under the workspace-relative `research/results/` directory, using YAML frontmatter analogous to an OpenCode skill and reporting persistence failures explicitly. - -## Requirements & Decisions - -- **Frameworks:** Existing OpenCode agent Markdown/frontmatter configuration and built-in `write` plus `glob` tools. OpenCode gates `write` through the `edit` permission and supports path-pattern permission rules. The canonical agent definition lives in `agent-harness/.opencode/` and is synchronized into each workspace through `.harness-sync`. -- **Chosen Libraries:** None. YAML/frontmatter and Markdown are prompt-defined output formats, so adding a serialization dependency would be unnecessary. -- **Error Handling Strategy:** Librarian must persist before returning its final response, report the written path on success, and fail visibly with the target path and tool error if the pre-provisioned destination is missing or writing fails. Research with unavailable or failed sources is saved with `status: partial` and explicit limitations rather than presented as complete. Invalid or missing required metadata prevents writing and is surfaced as an error. -- **Path:** Interpret issue wording `/research/results` as `/research/results`, not an absolute filesystem path. Runtime artifacts belong to and remain in that workspace. `agent-harness/research/results/` is only the canonical harness repository's own runtime destination; it is not a source directory to synchronize. Results are version-controlled but not automatically committed. -- **Scope:** Persistence applies to every Librarian run, including direct calls outside the `/research` command. -- **Ownership:** Librarian owns result serialization and persistence. Its final response uses a stable handoff line, `Research artifact: research/results/.md`; callers consume that path and must not duplicate the artifact. -- **Artifact Contract:** Use one filesystem-safe Markdown filename per run, based on UTC date/time, a normalized topic slug, and a high-entropy suffix. Refuse a filename already found by the collision check rather than overwriting it. Frontmatter mirrors skill conventions with `name`, `description`, and string-valued `metadata` entries for `created`, `libraries`, `tags`, `sources`, `verified`, and `status`. The body contains findings, implementation notes, sources, and limitations. -- **Permissions and Tooling:** Use built-in `write`, authorized by `edit` only for `research/results/*.md`, and built-in `read`, `glob` and `list`, authorized only for `research/results/*.md`, to perform best-effort collision checks. Do not add the broad `fsrw` MCP: its current workspace-wide mount cannot enforce the required per-directory write boundary. Retain denials for built-in shell, external directories, non-result paths, and unrelated tools. Pre-provision the destination because no directory-creation permission is granted to Librarian. Validate the exact path patterns against the installed OpenCode version before changing the agent. -- **Security Boundary:** Permission rules and the pre-provisioned real directory are the enforcement boundary. Prompt instructions provide defense in depth for slugging, frontmatter quoting, provenance, and secret minimization, but cannot guarantee semantic sanitization. Do not follow symlinks: setup/validation must reject a symlinked `research` or `research/results` path. -- **Concurrency Limit:** `glob` followed by `write` is not atomic and the built-in writer can overwrite. Use a timestamp plus high-entropy suffix and refuse a filename already returned by `glob`; document that truly concurrent adversarial collisions cannot be eliminated without a dedicated atomic-create tool and are out of scope for this prompt-only change. - -## Implementation Steps - -> Status Markers: [ ] Open, [/] In Progress, [x] Completed (set after accepted review only!) - -- [x] **Task 1: Define and document the research artifact contract** - - **Description:** Pre-provision tracked `research/results/` directories with placeholder files in both the canonical `agent-harness` repository and this root workspace as a one-time migration; future consuming workspaces must create their own destination during harness setup. Add canonical documentation/template defining required frontmatter, Markdown sections, invoking-workspace path semantics, ASCII slug rules, UTC timestamp plus high-entropy suffix naming, collision refusal, partial-result handling, and source provenance. Keep all `metadata` values strings to remain analogous to documented OpenCode skill frontmatter. Do not add `research/` to `.harness-sync`. -- [x] **Task 2: Give Librarian least-privilege persistence access** - - **Description:** Update `agent-harness/.opencode/agents/Librarian.md` to allow `edit`, `read`, `list` and `glob` only for `research/results/*.md`. Preserve web access and all unrelated denials. Do not grant `bash`, unrestricted MCP filesystem tools, recursive result access, or `external_directory` access. -- [x] **Task 3: Add persistence to the Librarian workflow** - - **Description:** Extend the Librarian instructions to normalize its topic to a bounded ASCII slug, collect provenance, quote scalar metadata safely, minimize secrets, validate required metadata, generate a timestamp/high-entropy filename, reject a glob-detected collision, and write before returning. Require the exact `Research artifact: ...` handoff line. Save incomplete research as `partial` with source errors and limitations. If research is partial and persistence also fails, return both failure classes and no success path. Never claim persistence after a failed write. Attempt to move as much as possible from `agent-harness/docs/research-artifact-contract.md` into the Librarian instructions so that the artifact contract is enforced by the agent rather than relying on external documentation. -- [ ] **Task 4: Align the research command and harness documentation** - - **Description:** Integrate the frontmatter documentation from `agent-harness/.opencode/commands/research.md` into the Librarian agents definition; skip the SKILL creation part. Remove `agent-harness/.opencode/commands/research.md` afterwards. Update `agent-harness/README.md` and setup documentation to describe destination provisioning and narrowly scoped local persistence. - -## Edge Case & Safety Checklist - -- Empty, punctuation-only, Unicode, very long, or path-like topics produce a bounded safe slug or fail clearly. -- Two runs with the same topic and timestamp use collision suffixes and never overwrite silently. -- Concurrent collision detection/write behavior is tested or explicitly documented as a limitation; a detected collision must be visible. -- Missing `research/results/`, read-only filesystems, denied permissions, and tool errors produce explicit failures naming the target path. -- Empty search results, inaccessible sources, timeouts, API errors, and version ambiguity create a `partial` artifact with limitations and do not claim verification. -- Frontmatter delimiters and user/source text are escaped so arbitrary content cannot corrupt YAML or inject new metadata fields. -- All required metadata values are strings; `verified` defaults to `"false"` until human review. -- Source provenance includes URLs and access outcomes; inaccessible sources are not silently omitted. -- Artifact content excludes credentials, tokens, cookies, and unrelated proprietary prompt context. -- Librarian remains unable to execute shell commands or access files outside `research/results/**`. -- Setup and tests reject symlinked destination components; normalized filenames contain no separators or `..` segments. -- `/research` does not persist a duplicate artifact after Librarian has already written one. -- Synchronization does not copy generated project research between unrelated registered projects. - -## Review Log (Plan Review) - -- **Round 1:** Changes required: (1) Resolve the destination contradiction: Task 1 creates `agent-harness/research/results/`, while runtime artifacts must be written to each invoking workspace's unsynchronized `research/results/`; distinguish any canonical template/fixture path from the runtime path. (2) Establish feasible tooling before implementation: current `agent-harness/opencode.jsonc` configures only the web MCP and Librarian denies all local tools; identify the exact supported write/create-directory and collision-check tools plus their path-rule syntax, then include any required tool/MCP configuration in scope. (3) Define least-privilege handling for directory creation, symlinks/path traversal, and collision-safe creation; read/list access to all prior research should not be granted unless necessary. (4) Specify the `/research` handoff: it currently runs as Builder and calls Librarian, so define how the artifact path is returned and consumed without duplicate persistence. (5) Define prompt-enforcement limits and tests for untrusted YAML/body content, secret filtering, malformed metadata, and partial research followed by persistence failure; fixtures alone do not prove every invocation persists. -- **Round 2:** Approved -- **Round 3:** N/A - -## Final Status (Code Review) - -- **Round 1 (Task 2):** Approved. Permission block uses correct default-deny + path-scoped allow syntax consistent with other agents. Web access preserved, all unrelated denials intact, no over-privileged tools granted. -- **Round 2 (Task 3):** Approved. Librarian workflow comprehensively implements persistence: ASCII slug normalization with bounds, high-entropy collision-resistant naming, glob-based collision refusal with documented atomicity limitation, full YAML frontmatter validation with string-only scalars and proper escaping, provenance recording including failed sources, partial-result handling, dual-failure reporting, secret exclusion, and stable handoff line. Contract doc format divergences (sequences vs flat strings) are Task 4 alignment scope. -- **Round 3:** N/A diff --git a/agent-harness b/agent-harness index 43acf62..a31eeda 160000 --- a/agent-harness +++ b/agent-harness @@ -1 +1 @@ -Subproject commit 43acf62a373d6476d1b18455f1228e703cfd25d3 +Subproject commit a31eeda77cef2bfe455bdff96d05c2dffbae69e5 diff --git a/docs/plans/2026-09-05-lifecycle-orchestrator.md b/docs/plans/2026-09-05-lifecycle-orchestrator.md new file mode 100644 index 0000000..a1498e9 --- /dev/null +++ b/docs/plans/2026-09-05-lifecycle-orchestrator.md @@ -0,0 +1,72 @@ +# Plan: Lifecycle Orchestrator (GitHub Issue #101) + +## Objective + +Add an OpenCode lifecycle Orchestrator that invokes Planner and Builder as subagents, preserves the existing phase-based workflow, routes lifecycle commands through one coordinator, and supports bounded cooperative parallelism without introducing a custom scheduler, lock service, Git-worktree manager, probe suite, or runtime framework. + +## Requirements & Decisions + +- **Frameworks:** Use the existing OpenCode Markdown agents and commands, native foreground/background Task delegation, `task_id` continuation, agent permissions, existing review agents, and `agent-harness/bin/harness-sync.sh`. `agent-harness/` remains authoritative; synchronized parent copies are updated through the existing sync mechanism. Set `subagent_depth` to `5` in `agent-harness/opencode.jsonc` and the separate `opencode/opencode.jsonc` runtime configuration. +- **Chosen Libraries:** None. OpenCode-native delegation is sufficient. Prompt-coordinated shared-worktree execution is an explicit user decision; no new orchestration library, SQLite ledger, custom scheduler, atomic claim service, Git worktree isolation, scoped-commit wrapper, or background compatibility probe is part of issue #101. +- **Error Handling Strategy:** Fail loudly and preserve the child error, phase, task/topic, session ID when available, and attempt count. On a technical Task failure (timeout, API/tool error, step-limit/incomplete result, unavailable session), resume the same child session exactly once. If a Builder still fails, launch one fresh Builder session with the original task scope and instructions to inspect and continue partial work; if it also fails or stops, halt the implementation batch and report briefly. Other subagents stop after the failed resume. Review critique, test failure, user rejection, and invalid workflow state are not technical Task failures and do not trigger this retry sequence. If background Task execution is unavailable, disclose that the required harness feature is missing and stop; do not silently fall back to serial execution. +- **Scope Boundary:** Issue #101 establishes the lifecycle agent architecture. It does not implement issue #100's GitHub bot, issue #85's research-verification workflow, durable cross-session scheduling, atomic filesystem locks, transactional rollback, or archive-command cleanup. `/archive_plan` remains assigned to Buddy and functionally unchanged. +- **Primary Agents:** Buddy remains the default general-purpose primary agent. Orchestrator uses the OpenCode mode that makes it user-selectable and Task-delegable. Planner and Builder become hidden subagents. Buddy delegates lifecycle requests to Orchestrator and retains general assistance for unrelated work. +- **Planner Questions:** Planner remains allowed to use `question` while running as a foreground Task. Orchestrator waits while the child question is presented to the user. Interactive planning is never dispatched in the background. +- **Delegation Graph:** Use deny-by-default Task target rules. Buddy may invoke Orchestrator, Explorer, and Librarian. Orchestrator may invoke Planner, Builder, Testing, PlanReviewer, CodeReviewer, Explorer, and Librarian, but not Committer. Planner may invoke Explorer, Librarian, and PlanReviewer. Builder may invoke Committer only during Orchestrator-authorized finalization. PlanReviewer and CodeReviewer may invoke Explorer and Librarian. Explorer, Librarian, Testing, and Committer are leaves. Built-in `plan`, `build`, `general`, and `explore` remain disabled in harness project configuration so lifecycle work cannot bypass Orchestrator. +- **Plan Dependency Graph:** Extend Planner's mandatory task format with `Task ID`, `Depends On`, `Owned Paths`, `Shared Resources`, `Parallel Safe`, and `Validation Commands`, in addition to `Description` and `Review Criteria`. IDs must be unique; dependencies must reference known tasks and be acyclic; dependency-ready means all prerequisites are `[x]`. Paths must be repository-relative and explicit enough to compare. PlanReviewer rejects ambiguous ownership, undeclared shared files/resources, unsafe validation commands, and parallel-safe tasks with apparent overlap. `PLAN.md` is the durable graph; Orchestrator may clarify its scheduling metadata only while no Builder is active. +- **Cooperative Parallelism:** `/continue_implementation` replaces `/implement_next_task`. It may launch at most two dependency-ready Builders whose approved tasks are explicitly parallel-safe and have disjoint declared paths/resources. The Orchestrator encourages parallelism only when this is clear; otherwise it runs one task or asks. Claims, overlap avoidance, and the two-agent limit are prompt/session coordinated—not atomic or safe across independent OpenCode processes. Builders must stop and report if they discover undeclared overlap or unrelated concurrent changes. Multiple Librarians may run in parallel up to four when assigned distinct topics. +- **Implementation Batch Barrier:** Active Builders modify only their assigned task scope and do not edit `PLAN.md`, invoke review, or commit. Orchestrator waits for all Builders in the selected batch. If one exhausts recovery, no task in that batch proceeds to review/commit. If all succeed, Orchestrator finalizes tasks one at a time: run approved validation through Testing, invoke task-scoped CodeReviewer, return critique to the corresponding Builder, and repeat for at most three review/correction rounds. Only accepted review changes that task to `[x]`; Builder then invokes Committer for that task. This sequencing reduces shared `PLAN.md` and Git-index races but does not make the shared worktree transactional. +- **Research:** `/research` routes directly from Orchestrator to Librarian rather than Builder. Librarian may write only under workspace-relative `research/results/**` and writes durable research notes, not `SKILL.md`. Librarians create timestamped topic filenames and check for an existing exact target before writing. Research verification remains issue #85. Parallel topic scopes are session-local and cooperative; no restart guarantee is claimed. +- **Command Preconditions:** `/plan` asks before replacing a nonempty `PLAN.md`. `/continue_implementation` stops for a missing, malformed, unapproved, completed, dependency-blocked, or scope-conflicting plan. `/review_plan` requires a plan. `/review_code` requires a plan plus an identifiable task/change scope and no longer performs a vague general review. Deterministic precondition failures are reported without retry. + +## Implementation Steps + +> Status Markers: [ ] Open, [/] In Progress, [x] Completed (set after accepted review only!) + +- [ ] **Task 1: Introduce the Orchestrator and update agent modes** + - **Description:** Add `agent-harness/.opencode/agents/Orchestrator.md` as a selectable/delegable lifecycle coordinator. Encode phase routing, foreground Planner interaction, cooperative concurrency limits, batch barriers, retry policy, and fail-loud preconditions. Convert Planner and Builder from primary to hidden subagents. Keep Buddy as the configured default and teach it to delegate lifecycle intent. Apply explicit deny-by-default Task target mappings to Buddy, Orchestrator, Planner, Builder, PlanReviewer, CodeReviewer, Explorer, Librarian, Testing, and Committer. Preserve built-in agent disablement and set `subagent_depth` to `5` in `agent-harness/opencode.jsonc` and `opencode/opencode.jsonc`. + - **Review Criteria:** Buddy is the effective default; Orchestrator is selectable and Task-delegable; Planner and Builder are hidden subagents; only documented delegation edges are allowed; no recursive Orchestrator edge or direct Orchestrator-to-Committer edge exists; built-in lifecycle agents remain disabled; both depth settings are `5`; Planner retains direct foreground question access. +- [ ] **Task 2: Define planning, implementation, review, and commit contracts** + - **Description:** Update Planner's template with task IDs, dependencies, owned paths, shared resources, parallel-safety, and validation commands. Update PlanReviewer to reject missing/invalid dependencies, cycles, unsafe or ambiguous ownership, and apparent overlap among parallel tasks. Change Builder from selecting “the first open task” to implementing only the Orchestrator-supplied task ID/scope; it must not edit `PLAN.md`, review, or commit during an active batch and must report modified paths, validation requested, and concerns. Make Testing a hidden non-editing subagent that runs only plan-approved validation with user approval where required. Make CodeReviewer task/scope-specific, with critique leaving the task incomplete and acceptance alone setting `[x]`. Update Committer to stage only the task paths explicitly supplied by Builder plus the serialized `PLAN.md` change and to fail visibly if unrelated staged changes make scope unclear. Reconcile root and `agent-harness/AGENTS.md` so the Orchestrator batch workflow supersedes direct per-unit commits for harness lifecycle work. + - **Review Criteria:** New plans contain enough dependency/scope data for scheduling; PlanReviewer rejects obvious graph/overlap errors; Builder cannot autonomously choose another task or mutate plan state during implementation; Testing cannot edit source or use Git; CodeReviewer reviews one identified task and controls `[x]`; Committer is instructed to avoid broad staging and aborts on ambiguous index state; both AGENTS files describe the same lifecycle flow. +- [ ] **Task 3: Route and rename lifecycle commands** + - **Description:** Add the parent-only `/plan` command to the authoritative harness and route it through Orchestrator. Replace `/implement_next_task` with `/continue_implementation`; support optional task IDs or a serial request while defaulting to the maximum safe eligible set of at most two tasks. Route `/review_plan`, `/review_code`, and `/research` through Orchestrator. Preserve `$ARGUMENTS` as a scope-narrowing input. Change `/research` from skill generation to durable research notes. Keep `/archive_plan` as the documented Buddy-owned exception. + - **Review Criteria:** All lifecycle commands except `/archive_plan` target Orchestrator; the old implementation command is removed; `/continue_implementation` cannot exceed two Builders and does not broaden an explicit task/serial request; invalid states fail before child dispatch; `/review_code` cannot perform an unscoped review; `/research` does not invoke Builder or create a skill; `/archive_plan` remains unchanged. +- [ ] **Task 4: Enable durable Librarian research notes** + - **Description:** Update Librarian permissions to allow writes and exact-target glob checks only under workspace-relative `research/results/**`, create that directory in the authoritative harness, and follow the Research Artifact Contract for timestamped topic filenames, metadata, findings, source URLs/version context, limitations, and partial/failure status. Orchestrator dispatches at most four distinct topics. Do not implement verification, a shared index, skills, or durable scheduling metadata. + - **Review Criteria:** Librarian cannot modify source, configuration, `PLAN.md`, or files outside `research/results/**`; concurrent requests use distinct topic scopes; an existing exact target is never overwritten; API/source failures and partial findings are visible; no `SKILL.md`, verification workflow, or scheduling ledger is introduced. +- [ ] **Task 5: Synchronize, document, and validate the streamlined architecture** + - **Description:** Update `agent-harness/README.md` with the agent graph, command mapping, question flow, retry rules, cooperative parallel limits, batch finalization, research location, and explicit non-atomic/cross-session limitations. Add lightweight dependency-free static checks for agent modes, Task target mappings, built-in disablement, depth/default configuration, command routing/removal, required plan task fields, and Librarian write confinement. Add a concise manual smoke checklist for: Planner question flow; one and two Builder execution; overlap rejection; missing background support; same-session retry and Builder fresh continuation; failed-batch no-review/no-commit; validation/review correction; scoped sequential commits; up to four distinct Librarians; and Buddy natural-language delegation. Use `harness-sync.sh` to propagate authoritative `.opencode` and config changes to the parent project, stop visibly on conflict/cancellation, check for rejected patches, and confirm final sync status has no unintended drift. Validate the separately maintained `opencode/opencode.jsonc` and restart OpenCode before manual smoke checks. + - **Review Criteria:** Static checks pass without new libraries; manual smoke results are recorded as pass/fail with brief evidence; OpenCode loads all changed config/frontmatter; expected primary/subagent modes and command targets are discoverable; parent and authoritative synchronized paths agree without rejected patches or unintended drift; depth is `5` in both intended configs; documentation clearly distinguishes cooperative prompt coordination from enforced isolation. + +## Edge Case & Safety Checklist + +- Missing, empty, malformed, unapproved, completed, or dependency-blocked `PLAN.md` stops implementation without retry. +- Replacing a nonempty plan requires explicit confirmation and preserves it on cancellation. +- Duplicate/unknown task IDs, dependency cycles, missing validation commands, ambiguous owned paths, shared lockfiles/generated outputs, and apparent path/resource overlap prevent parallel dispatch. +- At most two Builders and four distinct Librarians run concurrently; retries count toward the applicable limit. +- Background Task support is required for implementation/research parallelism; absence is disclosed and stops the phase rather than silently serializing it. +- Planner questions run only in foreground and reach the user directly. +- Builders never edit `PLAN.md`, review, or commit while a batch is active; Orchestrator never changes the plan until all batch Builders terminate. +- A Builder discovering undeclared files, conflicting edits, or unrelated concurrent changes stops and reports exact paths. +- One exhausted Builder aborts review/commit for the whole batch and leaves partial changes visible. +- Same-session retry occurs once; only Builder gets one additional fresh continuation session, which must inspect existing partial work. +- Review/test correction is separate from Task retry and remains bounded to three rounds per task. +- Tasks finalize sequentially to reduce review-log, plan-state, staging, and commit contamination. +- Unrelated staged changes or indeterminate Git scope cause Committer to abort rather than stage broadly. +- Prompt/session claims cannot prevent a second OpenCode process from touching the same worktree; this accepted limitation must remain documented. +- Cancellation or OpenCode restart may leave partial files and loses cooperative in-session scheduling state; never infer completion. +- Research target collisions, overlapping topics, inaccessible sources, API errors, contradictory data, and partial results are surfaced; no citation or conclusion is fabricated. +- Issue #100 bot behavior, issue #85 verification, worktree isolation, durable locks, custom scheduling, probe suites, and archive cleanup remain out of scope. + +## Review Log (Plan Review) + +- **Round 1:** Approved. The streamlined OpenCode-native plan is internally consistent, preserves the explicitly chosen cooperative limitations, and is implementable without custom scheduling or probe infrastructure. +- **Round 2:** N/A +- **Round 3:** N/A + +## Final Status (Code Review) + +- **Round 1:** Pending +- **Round 2:** N/A +- **Round 3:** N/A diff --git a/opencode.jsonc b/opencode.jsonc index bc2a619..c3b2d0a 100644 --- a/opencode.jsonc +++ b/opencode.jsonc @@ -1,5 +1,6 @@ { "$schema": "https://opencode.ai/config.json", + "default_agent": "Buddy", "agent": { "plan": { "disable": true, diff --git a/opencode/opencode.jsonc b/opencode/opencode.jsonc index 6e9179c..5244890 100644 --- a/opencode/opencode.jsonc +++ b/opencode/opencode.jsonc @@ -141,7 +141,7 @@ }, }, }, - "subagent_depth": 2, + "subagent_depth": 5, "shell": "bash", "formatter": true, "lsp": true,