diff --git a/packages/opencode-hive/skills/writing-plans/SKILL.md b/packages/opencode-hive/skills/writing-plans/SKILL.md index c1351f70..ddcfac4f 100644 --- a/packages/opencode-hive/skills/writing-plans/SKILL.md +++ b/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-.md` +**Save plans to:** `hive_plan_write` (writes to `.hive/features//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/.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//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 diff --git a/packages/opencode-hive/src/agents/architect.ts b/packages/opencode-hive/src/agents/architect.ts index 9dbd5f63..8ad44381 100644 --- a/packages/opencode-hive/src/agents/architect.ts +++ b/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 diff --git a/packages/opencode-hive/src/agents/hive.ts b/packages/opencode-hive/src/agents/hive.ts index 3f35c985..4820e52b 100644 --- a/packages/opencode-hive/src/agents/hive.ts +++ b/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) diff --git a/packages/opencode-hive/src/agents/swarm.ts b/packages/opencode-hive/src/agents/swarm.ts index 4c229f66..c948283a 100644 --- a/packages/opencode-hive/src/agents/swarm.ts +++ b/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? diff --git a/packages/opencode-hive/src/skills/registry.generated.ts b/packages/opencode-hive/src/skills/registry.generated.ts index 841c35e2..a41e0de2 100644 --- a/packages/opencode-hive/src/skills/registry.generated.ts +++ b/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-.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/.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//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//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", } ];