fix: align plan templates and dependency guidance

packages/opencode-hive/skills/writing-plans/SKILL.md

@@ -13,9 +13,9 @@ Assume they are a skilled developer, but know almost nothing about our toolset o
 
 **Announce at start:** "I'm using the writing-plans skill to create the implementation plan."
 
-**Context:** This should be run in a dedicated worktree (created by brainstorming skill).
+**Context:** Planning is read-only. Use `hive_feature_create` + `hive_plan_write` and avoid worktrees during planning.
 
-**Save plans to:** `docs/plans/YYYY-MM-DD-<feature-name>.md`
+**Save plans to:** `hive_plan_write` (writes to `.hive/features/<feature>/plan.md`)
 
 ## Bite-Sized Task Granularity
 
@@ -26,66 +26,92 @@ Assume they are a skilled developer, but know almost nothing about our toolset o
 - "Run the tests and make sure they pass" - step
 - "Commit" - step
 
-## Plan Document Header
+## Plan Structure
 
-**Every plan MUST start with this header:**
+**Every plan MUST follow this structure:**
 
-```markdown
-# [Feature Name] Implementation Plan
+````markdown
+# [Feature Name]
 
-> **For Claude:** REQUIRED SUB-SKILL: Use hive_skill:executing-plans to implement this plan task-by-task.
+## Discovery
 
-**Goal:** [One sentence describing what this builds]
+### Original Request
+- "{User's exact words}"
 
-**Architecture:** [2-3 sentences about approach]
+### Interview Summary
+- {Point}: {Decision}
 
-**Tech Stack:** [Key technologies/libraries]
+### Research Findings
+- `{file:lines}`: {Finding}
 
 ---
-```
 
-## Task Structure
+## Non-Goals (What we're NOT building)
+- {Explicit exclusion}
 
-```markdown
-### Task N: [Component Name]
+---
 
-**Files:**
-- Create: `exact/path/to/file.py`
-- Modify: `exact/path/to/existing.py:123-145`
-- Test: `tests/exact/path/to/test.py`
+## Tasks
 
-**Step 1: Write the failing test**
+### 1. Task Name
 
-```python
-def test_specific_behavior():
-    result = function(input)
-    assert result == expected
-```
+Use the Task Structure template below for every task.
+````
 
-**Step 2: Run test to verify it fails**
 
-Run: `pytest tests/path/test.py::test_name -v`
-Expected: FAIL with "function not defined"
+## Task Structure
 
-**Step 3: Write minimal implementation**
+The **Depends on** annotation declares task execution order:
+- **Depends on**: none — No dependencies; can run immediately or in parallel
+- **Depends on**: 1 — Depends on task 1
+- **Depends on**: 1, 3 — Depends on tasks 1 and 3
 
-```python
-def function(input):
-    return expected
-```
+Always include **Depends on** for each task. Use `none` to enable parallel starts.
 
-**Step 4: Run test to verify it passes**
+````markdown
+### N. Task Name
 
-Run: `pytest tests/path/test.py::test_name -v`
-Expected: PASS
+**Depends on**: none
 
-**Step 5: Commit**
+**Files:**
+- Create: `exact/path/to/file.py`
+- Modify: `exact/path/to/existing.py:123-145`
+- Test: `tests/exact/path/to/test.py`
 
-```bash
-git add tests/path/test.py src/path/file.py
-git commit -m "feat: add specific feature"
-```
-```
+**What to do**:
+- Step 1: Write the failing test
+  ```python
+  def test_specific_behavior():
+      result = function(input)
+      assert result == expected
+  ```
+- Step 2: Run test to verify it fails
+  - Run: `pytest tests/path/test.py::test_name -v`
+  - Expected: FAIL with "function not defined"
+- Step 3: Write minimal implementation
+  ```python
+  def function(input):
+      return expected
+  ```
+- Step 4: Run test to verify it passes
+  - Run: `pytest tests/path/test.py::test_name -v`
+  - Expected: PASS
+- Step 5: Commit
+  ```bash
+  git add tests/path/test.py src/path/file.py
+  git commit -m "feat: add specific feature"
+  ```
+
+**Must NOT do**:
+- {Task guardrail}
+
+**References**:
+- `{file:lines}` — {Why this reference matters}
+
+**Verify**:
+- [ ] Run: `{command}` → {expected}
+- [ ] {Additional acceptance criteria}
+````
 
 ## Remember
 - Exact file paths always
@@ -96,18 +122,17 @@ git commit -m "feat: add specific feature"
 
 ## Execution Handoff
 
-After saving the plan, offer execution choice:
-
-**"Plan complete and saved to `docs/plans/<filename>.md`. Two execution options:**
+After saving the plan, ask whether to consult Hygienic (Consultant/Reviewer/Debugger) before offering execution choice.
 
-**1. Subagent-Driven (this session)** - I dispatch fresh subagent per task, review between tasks, fast iteration
+Plan complete and saved to `.hive/features/<feature>/plan.md`.
 
-**2. Parallel Session (separate)** - Open new session with executing-plans, batch execution with checkpoints
+Two execution options:
+1. Subagent-Driven (this session) - I dispatch fresh subagent per task, review between tasks, fast iteration
+2. Parallel Session (separate) - Open new session with executing-plans, batch execution with checkpoints
 
-**Which approach?"**
+Which approach?
 
 **If Subagent-Driven chosen:**
-- **REQUIRED SUB-SKILL:** Use hive_skill:subagent-driven-development
 - Stay in this session
 - Fresh subagent per task + code review
 

packages/opencode-hive/src/agents/architect.ts

@@ -66,7 +66,14 @@ hive_plan_write({ content: "..." })
 Plan MUST include:
 - ## Discovery (Original Request, Interview Summary, Research)
 - ## Non-Goals (Explicit exclusions)
-- ## Tasks (### N. Title with What/Must NOT/References/Verify)
+- ## Tasks (### N. Title with Depends on/Files/What/Must NOT/References/Verify)
+  - Files must list Create/Modify/Test with exact paths and line ranges where applicable
+  - References must use file:line format
+  - Verify must include exact command + expected output
+
+Each task MUST declare dependencies with **Depends on**:
+- **Depends on**: none for no dependencies / parallel starts
+- **Depends on**: 1, 3 for explicit task-number dependencies
 
 ## Iron Laws
 

packages/opencode-hive/src/agents/hive.ts

@@ -109,14 +109,23 @@ hive_feature_create({ name: "feature-name" })
 hive_plan_write({ content: "..." })
 \`\`\`
 
-Plan includes: Discovery, Non-Goals, Tasks (with What/Must NOT/Verify)
+Plan includes: Discovery (Original Request, Interview Summary, Research Findings), Non-Goals, Tasks (### N. Title with Depends on/Files/What/Must NOT/References/Verify)
+- Files must list Create/Modify/Test with exact paths and line ranges where applicable
+- References must use file:line format
+- Verify must include exact command + expected output
+
+Each task MUST declare dependencies with **Depends on**:
+- **Depends on**: none for no dependencies / parallel starts
+- **Depends on**: 1, 3 for explicit task-number dependencies
 
 ### After Plan Written
 
-Ask user: "Plan complete. Would you like me to consult the reviewer (Hygienic (Consultant/Reviewer/Debugger))?"
+Ask user via \`question()\`: "Plan complete. Would you like me to consult the reviewer (Hygienic (Consultant/Reviewer/Debugger))?"
 
 If yes → \`task({ subagent_type: "hygienic", prompt: "Review plan..." })\`
 
+After review decision, offer execution choice (subagent-driven vs parallel session) consistent with writing-plans.
+
 ### Planning Iron Laws
 
 - Research BEFORE asking (use \`hive_skill("parallel-exploration")\` for multi-domain research)

packages/opencode-hive/src/agents/swarm.ts

@@ -28,6 +28,8 @@ Use \`hive_status()\` to see **runnable** tasks (dependencies satisfied) and **b
 - When 2+ tasks are runnable: ask operator via \`question()\` before parallelizing
 - Record execution decisions with \`hive_context_write({ name: "execution-decisions", ... })\`
 
+If tasks are missing **Depends on** metadata, ask the planner to revise the plan before executing.
+
 ### Standard Checks
 
 1. Is there a specialized agent that matches?

packages/opencode-hive/src/skills/registry.generated.ts

@@ -63,6 +63,6 @@ export const BUILTIN_SKILLS: SkillDefinition[] = [
   {
     name: "writing-plans",
     description: "Use when you have a spec or requirements for a multi-step task, before touching code",
-    template: "# Writing Plans\n\n## Overview\n\nWrite comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.\n\nAssume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.\n\n**Announce at start:** \"I'm using the writing-plans skill to create the implementation plan.\"\n\n**Context:** This should be run in a dedicated worktree (created by brainstorming skill).\n\n**Save plans to:** `docs/plans/YYYY-MM-DD-<feature-name>.md`\n\n## Bite-Sized Task Granularity\n\n**Each step is one action (2-5 minutes):**\n- \"Write the failing test\" - step\n- \"Run it to make sure it fails\" - step\n- \"Implement the minimal code to make the test pass\" - step\n- \"Run the tests and make sure they pass\" - step\n- \"Commit\" - step\n\n## Plan Document Header\n\n**Every plan MUST start with this header:**\n\n```markdown\n# [Feature Name] Implementation Plan\n\n> **For Claude:** REQUIRED SUB-SKILL: Use hive_skill:executing-plans to implement this plan task-by-task.\n\n**Goal:** [One sentence describing what this builds]\n\n**Architecture:** [2-3 sentences about approach]\n\n**Tech Stack:** [Key technologies/libraries]\n\n---\n```\n\n## Task Structure\n\n```markdown\n### Task N: [Component Name]\n\n**Files:**\n- Create: `exact/path/to/file.py`\n- Modify: `exact/path/to/existing.py:123-145`\n- Test: `tests/exact/path/to/test.py`\n\n**Step 1: Write the failing test**\n\n```python\ndef test_specific_behavior():\n    result = function(input)\n    assert result == expected\n```\n\n**Step 2: Run test to verify it fails**\n\nRun: `pytest tests/path/test.py::test_name -v`\nExpected: FAIL with \"function not defined\"\n\n**Step 3: Write minimal implementation**\n\n```python\ndef function(input):\n    return expected\n```\n\n**Step 4: Run test to verify it passes**\n\nRun: `pytest tests/path/test.py::test_name -v`\nExpected: PASS\n\n**Step 5: Commit**\n\n```bash\ngit add tests/path/test.py src/path/file.py\ngit commit -m \"feat: add specific feature\"\n```\n```\n\n## Remember\n- Exact file paths always\n- Complete code in plan (not \"add validation\")\n- Exact commands with expected output\n- Reference relevant skills with @ syntax\n- DRY, YAGNI, TDD, frequent commits\n\n## Execution Handoff\n\nAfter saving the plan, offer execution choice:\n\n**\"Plan complete and saved to `docs/plans/<filename>.md`. Two execution options:**\n\n**1. Subagent-Driven (this session)** - I dispatch fresh subagent per task, review between tasks, fast iteration\n\n**2. Parallel Session (separate)** - Open new session with executing-plans, batch execution with checkpoints\n\n**Which approach?\"**\n\n**If Subagent-Driven chosen:**\n- **REQUIRED SUB-SKILL:** Use hive_skill:subagent-driven-development\n- Stay in this session\n- Fresh subagent per task + code review\n\n**If Parallel Session chosen:**\n- Guide them to open new session in worktree\n- **REQUIRED SUB-SKILL:** New session uses hive_skill:executing-plans",
+    template: "# Writing Plans\n\n## Overview\n\nWrite comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.\n\nAssume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.\n\n**Announce at start:** \"I'm using the writing-plans skill to create the implementation plan.\"\n\n**Context:** Planning is read-only. Use `hive_feature_create` + `hive_plan_write` and avoid worktrees during planning.\n\n**Save plans to:** `hive_plan_write` (writes to `.hive/features/<feature>/plan.md`)\n\n## Bite-Sized Task Granularity\n\n**Each step is one action (2-5 minutes):**\n- \"Write the failing test\" - step\n- \"Run it to make sure it fails\" - step\n- \"Implement the minimal code to make the test pass\" - step\n- \"Run the tests and make sure they pass\" - step\n- \"Commit\" - step\n\n## Plan Structure\n\n**Every plan MUST follow this structure:**\n\n````markdown\n# [Feature Name]\n\n## Discovery\n\n### Original Request\n- \"{User's exact words}\"\n\n### Interview Summary\n- {Point}: {Decision}\n\n### Research Findings\n- `{file:lines}`: {Finding}\n\n---\n\n## Non-Goals (What we're NOT building)\n- {Explicit exclusion}\n\n---\n\n## Tasks\n\n### 1. Task Name\n\nUse the Task Structure template below for every task.\n````\n\n\n## Task Structure\n\nThe **Depends on** annotation declares task execution order:\n- **Depends on**: none — No dependencies; can run immediately or in parallel\n- **Depends on**: 1 — Depends on task 1\n- **Depends on**: 1, 3 — Depends on tasks 1 and 3\n\nAlways include **Depends on** for each task. Use `none` to enable parallel starts.\n\n````markdown\n### N. Task Name\n\n**Depends on**: none\n\n**Files:**\n- Create: `exact/path/to/file.py`\n- Modify: `exact/path/to/existing.py:123-145`\n- Test: `tests/exact/path/to/test.py`\n\n**What to do**:\n- Step 1: Write the failing test\n  ```python\n  def test_specific_behavior():\n      result = function(input)\n      assert result == expected\n  ```\n- Step 2: Run test to verify it fails\n  - Run: `pytest tests/path/test.py::test_name -v`\n  - Expected: FAIL with \"function not defined\"\n- Step 3: Write minimal implementation\n  ```python\n  def function(input):\n      return expected\n  ```\n- Step 4: Run test to verify it passes\n  - Run: `pytest tests/path/test.py::test_name -v`\n  - Expected: PASS\n- Step 5: Commit\n  ```bash\n  git add tests/path/test.py src/path/file.py\n  git commit -m \"feat: add specific feature\"\n  ```\n\n**Must NOT do**:\n- {Task guardrail}\n\n**References**:\n- `{file:lines}` — {Why this reference matters}\n\n**Verify**:\n- [ ] Run: `{command}` → {expected}\n- [ ] {Additional acceptance criteria}\n````\n\n## Remember\n- Exact file paths always\n- Complete code in plan (not \"add validation\")\n- Exact commands with expected output\n- Reference relevant skills with @ syntax\n- DRY, YAGNI, TDD, frequent commits\n\n## Execution Handoff\n\nAfter saving the plan, ask whether to consult Hygienic (Consultant/Reviewer/Debugger) before offering execution choice.\n\nPlan complete and saved to `.hive/features/<feature>/plan.md`.\n\nTwo execution options:\n1. Subagent-Driven (this session) - I dispatch fresh subagent per task, review between tasks, fast iteration\n2. Parallel Session (separate) - Open new session with executing-plans, batch execution with checkpoints\n\nWhich approach?\n\n**If Subagent-Driven chosen:**\n- Stay in this session\n- Fresh subagent per task + code review\n\n**If Parallel Session chosen:**\n- Guide them to open new session in worktree\n- **REQUIRED SUB-SKILL:** New session uses hive_skill:executing-plans",
   }
 ];