@glrs-dev/cli 1.1.0 → 2.0.0

package/dist/vendor/harness-opencode/dist/skills/pilot-planning/SKILL.md

@@ -1,80 +0,0 @@
----
-name: pilot-planning
-description: Methodology for producing a pilot.yaml plan that the pilot-builder agent can execute unattended. Use when the pilot-planner agent receives a feature request — covers task decomposition, verify-command design, scope tightness, DAG shape, and self-review. Auto-loaded by the pilot-planner agent.
----
-
-# Pilot Planning Skill
-
-You are producing a `pilot.yaml` plan: a list of tasks the pilot-builder agent can execute one at a time, fully unattended. The cost of a bad plan is high — the builder will fail tasks confusingly, the cascade-fail will block downstream work, and the human pilot operator has to clean up worktrees and re-plan.
-
-A good plan trades a planning-session's worth of patient thought for hours of unsupervised builder time. Take the patient thought.
-
-## Workflow
-
-Apply these nine rules in order. Each rule has its own file in `rules/` for the full text:
-
-1. [`first-principles.md`](rules/first-principles.md) — Frame the task FROM the user's intent, not from a templated checklist. Ask "what does the user actually want done?" before "what files might change?"
-
-2. [`decomposition.md`](rules/decomposition.md) — Break the work into right-sized tasks (10-30 minutes of agent time, ≤3 attempts). Too big = unbounded work; too small = orchestration overhead drowns the value.
-
-3. [`verify-design.md`](rules/verify-design.md) — Each task's `verify:` commands must succeed iff the task is correctly done. No `echo done`. No `test -f file.ts`. Real assertions only.
-
-4. [`touches-scope.md`](rules/touches-scope.md) — `touches:` globs must be the tightest set that lets the task succeed. Default to "specific file paths"; `**` is a smell.
-
-5. [`dag-shape.md`](rules/dag-shape.md) — Tasks depend on each other only when there's a real semantic dependency (B reads what A produces). False dependencies make the run sequential when it could parallel; missing dependencies cause subtle race-on-state bugs.
-
-6. [`milestones.md`](rules/milestones.md) — Optional grouping. Use when several tasks share a "is this batch done?" check (e.g. integration tests after a chunk of unit-test work).
-
-7. [`self-review.md`](rules/self-review.md) — Before declaring the plan ready, run through a 7-question checklist. Find the holes yourself; the validator only catches schema errors. And before declaring "refuse", revisit the bundle-vs-split decision below.
-
-8. [`task-context.md`](rules/task-context.md) — Every non-trivial task carries a `context:` block. Thin plans fail because the builder works each task from scratch with no carry-over; rich context pre-loads what the builder needs to work confidently. Cover outcome, rationale, code pointers, acceptance.
-
-9. [`qa-expectations.md`](rules/qa-expectations.md) — Detect → propose → confirm per-surface verify patterns for UI, API, DB, integration, browser-based component, and CLI surfaces.
-
-## After applying the rules
-
-1. Save the YAML to the path returned by `bunx @glrs-dev/harness-plugin-opencode pilot plan-dir`.
-2. Remind the user the plan assumes their dev stack is already running (install, compose, migrate, seed). Plans no longer bootstrap their own environment.
-3. Run `bunx @glrs-dev/harness-plugin-opencode pilot validate <path>` and fix every error / warning.
-4. Hand off to the user with: `Plan saved to <path>. Next: bunx @glrs-dev/harness-plugin-opencode pilot build`.
-
-Do NOT summarize the plan in chat. The user can read the YAML.
-
-## When to bundle vs. split plans
-
-Multi-issue cross-cutting plans are a first-class pilot shape. When a user's scope spans 2–4 related issues, default to **one plan** covering all of them — as long as they share:
-
-- Same repo (or monorepo).
-- Same package manager / install command.
-- Same `docker-compose` (or equivalent local-infra) stack.
-- Same test runner and verify style.
-- Same migrations/seed pipeline.
-
-Bundling amortizes setup cost (install, compose up, migrate, seed — minutes each, paid once per pilot run) across all the work. Tasks from different issues typically form disconnected subtrees in the DAG — see [`dag-shape.md`](rules/dag-shape.md)'s "Disconnected" pattern. Task-level `cascadeFail` only blocks transitive dependents, so a failure in one subtree does NOT cascade into its siblings.
-
-**Split into separate pilot plans when:**
-
-- Issues live in different repositories.
-- Issues require fundamentally different setup environments.
-- Issues have fundamentally different acceptance shapes (e.g., automated typecheck vs. manual operator playbook).
-
-See [`decomposition.md`](rules/decomposition.md) "Plan sizing — count of tasks" for more.
-
-## When to refuse
-
-Refuse ONLY when the **work itself** is underspecified or ambiguous — no concrete acceptance criteria, no clear "done" condition. Examples that warrant refusal:
-
-- "Make the API better."
-- "Refactor auth."
-- "Clean up tech debt."
-
-These don't name specific behaviors the pilot-builder can verify. Ask the user to narrow the scope before planning.
-
-**Do NOT refuse for:**
-
-- Plan size (5–30 tasks is fine; even more is fine when the work is well-defined).
-- Multi-issue scope (2–4 related issues in one plan is first-class — see "When to bundle" above).
-- Disconnected-subtree DAG shape (tasks from different concerns don't need artificial edges).
-- Concerns about PR shape (that's a reviewer decision; the pilot run can produce one PR or several).
-
-When you do refuse: tell the user honestly and specifically what's missing. Suggest the regular `/plan` agent (markdown plans, human-driven execution) for ambiguous work that needs human iteration before it's pilotable. It is far better to refuse an unspecified request than to ship a plan full of `echo done` verifies — but narrow what "bad plan" means. Ambitious is not bad; ambiguous is bad.

package/dist/vendor/harness-opencode/dist/skills/pilot-planning/rules/dag-shape.md

@@ -1,47 +0,0 @@
-# Rule 5 — DAG shape
-
-**Tasks depend on each other only when there's a real semantic dependency.**
-
-The `depends_on` edges in the plan determine run order. False edges serialize work that could parallelize (v0.3); missing edges let a downstream task run against a state where its prerequisite hasn't committed yet.
-
-## What a real dependency looks like
-
-- **Reads code that the dep produces.** T2 imports a function T1 introduced.
-- **Reads schema that the dep modifies.** T2 calls an endpoint T1 added.
-- **Tests behavior the dep implements.** T2's verify runs a test T1's code makes pass.
-
-## What ISN'T a real dependency
-
-- "T1 should run first because it's foundational." If T2 doesn't use T1's output, the order doesn't matter for correctness — and forcing it costs you parallelism.
-- "Both touch `src/api/`." Touch overlap is a worktree-pool concern (v0.3), not a logical dependency. Capture it via `touches:` if at all.
-- "I want T1 to be done before I review T2." That's a human-review concern, not a pilot DAG concern. The pilot run completes; you review afterward.
-
-## Common shapes
-
-**Linear** — T1 → T2 → T3:
-
-Each task is the next layer. Use when each layer literally builds on the previous.
-
-**Diamond** — T1 fans out to T2, T3; both reconverge into T4:
-
-T1 = "introduce module skeleton"; T2, T3 = "fill in submodule X / Y" (parallelizable on disjoint scopes); T4 = "wire up everything and run integration tests".
-
-**Disconnected** — Two independent components in the same plan:
-
-`auth-1`, `auth-2` are one chain; `billing-1`, `billing-2` are another. Use when the plan covers multiple unrelated improvements.
-
-**Hub-and-spoke** — Many tasks all depend on T1 but not on each other:
-
-T1 = "add the typed client"; T2-Tn each = "use the typed client in module M". All Tn parallelize.
-
-## Cycle detection
-
-The validator catches cycles. If you accidentally write `T1 → T2 → T1`, validate will tell you. Most cycles arise from copy-paste in `depends_on` lists; check yours before saving.
-
-## Self-loops
-
-`T1: depends_on: [T1]` is a self-loop, also caught by validate. Always a typo.
-
-## "I want everything serial"
-
-Sometimes the right answer IS a fully linear DAG (e.g., a refactor where each step's diff would conflict with the next). Don't be afraid to chain everything if that's the truth — but don't pretend it's the truth when it isn't.

package/dist/vendor/harness-opencode/dist/skills/pilot-planning/rules/decomposition.md

@@ -1,63 +0,0 @@
-# Rule 2 — Decomposition
-
-**Right-sized tasks: 10-30 minutes of agent time, ≤3 attempts to pass verify.**
-
-A "right-sized" pilot task is one the pilot-builder can complete in a single session within the default `max_turns: 50` budget. Empirically, that's about 10-30 minutes of agent wall time and 1-3 attempts.
-
-## Sizing heuristics
-
-**Too big (split it):**
-
-- The verify command exercises >3 distinct code paths.
-- The task touches >5 files.
-- The prompt has >10 numbered steps.
-- The task says "and also" / "while you're at it" — a sign of conjoined work.
-
-**Too small (merge it):**
-
-- The task touches a single file with <30 lines added/changed.
-- The verify command would also pass before the task ran.
-- Splitting added a `depends_on` edge that just moves work around.
-
-## Splitting patterns
-
-- **Layer-by-layer**: schema → DB accessors → API → wiring. Each layer has its own tests; each is a task.
-- **Read → Write**: T1 = "add a function that returns the data", T2 = "add an endpoint that calls it". T2 depends on T1.
-- **Skeleton → Detail**: T1 = "introduce the module structure with stubs", T2-Tn = "fill in each stub with logic+tests". The stubs let downstream tasks parallelize.
-
-## Anti-patterns
-
-- **Refactor as one task.** "Refactor X" is a feature, not a task. Decompose into `extract Y`, `inline Z`, `rename W`, each with its own verify.
-- **Setup-only tasks.** "Install lodash" is not a pilot task — the next task can install it as part of its own scope. Avoid tasks that don't deliver an observable check.
-- **Cleanup-only tasks.** "Remove dead code". The verify is "tests still pass" — but tests passing was already the contract on the previous task. If there's nothing new to assert, this isn't a task.
-
-## When you can't decompose
-
-If the work genuinely doesn't decompose (e.g., a 200-line algorithm that has to land atomically), it might not be a fit for pilot. Tell the user; they may want to run it as a regular `/build` task instead.
-
-## Plan sizing — count of tasks
-
-Per-task size is covered above. Plan-level size (total task count) is a different dimension and has its own sweet spot: **roughly 5–30 tasks per `pilot.yaml`**. Outside this range:
-
-- **Fewer than 5 tasks:** usually means the work is a single change that doesn't benefit from the pilot harness. Consider `/plan` + `/build` instead.
-- **More than 30 tasks:** fine in principle, but at that size the plan probably spans enough distinct concerns that a human reviewer will want it split — not a pilot problem, a PR-shape problem.
-
-### Multi-issue cross-cutting plans are a first-class shape
-
-It is **normal and correct** for a single pilot plan to span 2–4 related issues (Linear tickets, GitHub issues) **when those issues share setup and verify infrastructure** — same repo, same package manager, same `docker-compose`, same test runner, same migrations. Reasons to bundle:
-
-- **Setup amortization.** `pnpm install`, `docker compose up`, `pnpm db:migrate`, seed scripts — each of these is minutes of wall time. Running them once per pilot session vs. once per Linear issue saves hours across a multi-issue push.
-- **Context reuse.** The builder learns the codebase through reading during early tasks; that context benefits every subsequent task in the run.
-- **Shared acceptance.** Cross-issue integration checks (a milestone-close verify that exercises all three issues' changes together) are natural in one plan, awkward across three runs.
-
-**Reference shape (not a red flag):** rule-engine cleanup + LISTEN/NOTIFY cache invalidation + read-only admin UI landed together in one plan of ~19 tasks across 4 milestones, covering 3 Linear issues. This is the shape pilot is built for.
-
-When bundling, the tasks from different issues typically form **disconnected subtrees** in the DAG (no real semantic dependency between them). That's fine — see [`dag-shape.md`](dag-shape.md)'s "Disconnected" pattern. Task-level `cascadeFail` only blocks transitive dependents, so a failure in one subtree doesn't cascade into the siblings.
-
-### When to split instead of bundle
-
-Split into separate pilot plans when:
-
-- The issues live in **different repositories**.
-- The issues require **fundamentally different setup environments** (e.g., one needs Postgres + Temporal, the other needs a headless browser grid — sharing setup is worse than paying the cost twice).
-- The issues have **fundamentally different acceptance criteria** (e.g., one is a TypeScript refactor verified via typecheck, the other is an infrastructure change verified via a manual operator playbook — no shared verify makes sense).

package/dist/vendor/harness-opencode/dist/skills/pilot-planning/rules/first-principles.md

@@ -1,29 +0,0 @@
-# Rule 1 — First-principles task framing
-
-**Frame from intent, not from a template.**
-
-Bad plans start with a checklist ("read AGENTS.md → write tests → write code → run tests"). Good plans start with the question: *what does the user actually want at the end of this?*
-
-## What to ask yourself
-
-1. **What is the working state at the end of the run?** A passing test suite that previously failed? A new endpoint serving real traffic? A refactor with zero behavior change? Different end-states demand different task shapes.
-
-2. **What can fail?** A task that "adds an import" can't really fail. A task that "implements pagination across three layers" can fail in a hundred ways. The latter needs decomposition.
-
-3. **What does the verify catch?** If you can't articulate the failure mode each verify command detects, the verify is decoration.
-
-4. **What is the smallest change that ships?** Pilot is good at small surgical work. If the user wants a wholesale rewrite, pilot is the wrong tool — say so.
-
-## Talk to the user — once
-
-Before you spend an hour reading code, take 2 minutes to ask the user 1-3 clarifying questions:
-
-- Scope (what's in / out of this plan?)
-- Success criteria (how do we know we're done?)
-- Constraints (deps to use, deps to avoid, tests to preserve)
-
-Do this BEFORE applying rules 2-7. The cheapest mistake to fix is the one you avoid by understanding intent up front.
-
-## Then read code
-
-Don't ask the user things you can answer by reading code. Don't ask "what test framework do you use?" — `package.json` says. Don't ask "where does auth live?" — `grep` it. Use the user's time only for things genuinely unknown to the codebase.

package/dist/vendor/harness-opencode/dist/skills/pilot-planning/rules/milestones.md

@@ -1,57 +0,0 @@
-# Rule 6 — Milestones (optional)
-
-**Use milestones to attach extra verify when a logical batch finishes.**
-
-Milestones are an optional grouping. They serve two purposes:
-
-1. **Status output** — `pilot status` groups tasks by milestone. Easier to read for big plans.
-2. **Milestone-level verify** — extra verify commands that run when the LAST task in the milestone completes.
-
-If neither of those is useful, don't add milestones. Plain task lists are simpler.
-
-## Schema
-
-```yaml
-milestones:
-  - name: M1
-    description: Foundation
-    verify:
-      - bun run integration-test:foundation
-  - name: M2
-    description: API layer
-    verify:
-      - bun run integration-test:api
-
-tasks:
-  - id: T1
-    title: schema
-    milestone: M1
-  - id: T2
-    title: db
-    milestone: M1
-  - id: T3
-    title: endpoint
-    milestone: M2
-```
-
-Each task has an optional `milestone:` label. The label must match a `milestones[].name` (the validator catches typos).
-
-## When milestone verify fires
-
-Milestone-level verify runs **after the last task in that milestone completes successfully**. "Last" = last in topological order among tasks with that label. If any task in the milestone fails or gets blocked, the milestone verify does NOT run (the cascade-fail will block downstream work anyway).
-
-## When to use them
-
-- **Multi-layer features** where you want an integration test after each layer (schema, API, UI).
-- **Long plans** (8+ tasks) where the user wants visible progress markers.
-- **Mixed-domain plans** where milestones group related work for status readability.
-
-## When NOT to use them
-
-- Simple plans (≤5 tasks). Just list the tasks; status output is fine without grouping.
-- Plans where every "milestone" has only one task. Use task verify instead.
-- Plans where the milestone verify is "the same as the last task's verify". Redundant.
-
-## Don't conflate milestone with dep
-
-Milestones are a presentation/verify-grouping concept; they do NOT change scheduling. If T3 needs T2 done before it can start, that's a `depends_on: [T2]`, not a `milestone:` label. The DAG and milestones are independent axes.

package/dist/vendor/harness-opencode/dist/skills/pilot-planning/rules/qa-expectations.md

@@ -1,120 +0,0 @@
-# Rule 10 — QA-expectations establishment
-
-**Detect → propose → confirm per-surface verify patterns.**
-
-A plan's verify commands are its contract with the builder. Generic verifies ("run tests") waste builder time; specific verifies ("run the API tests that exercise the files this task touches") catch real failures. This rule establishes concrete, per-surface QA expectations with the user before emitting the plan.
-
-## The six surfaces
-
-For each surface below, detect signals in the codebase, propose a canonical verify pattern, and confirm with the user.
-
-### UI — Browser-based user interface
-
-**Detection signals:**
-- `@playwright/test`, `cypress`, or `@vitest/browser` in `package.json` dependencies
-- `playwright.config.{ts,js}` or `cypress.config.*` present
-
-**Proposed verify pattern:**
-Playwright MCP invocation for visual/interaction assertions:
-```yaml
-verify:
-  - playwright test --project=chromium --grep "@task-specific-tag"
-```
-
-### API — HTTP endpoints
-
-**Detection signals:**
-- `openapi.yaml` / `openapi.json` present
-- `curl` or `httpie` usage in existing scripts
-- Postman collection files
-
-**Proposed verify pattern:**
-Direct HTTP assertion against a local port:
-```yaml
-verify:
-  - curl -fsS http://localhost:3000/health | jq '.status == "ok"'
-```
-
-### DB — Database schema and queries
-
-**Detection signals:**
-- `docker-compose` postgres service defined
-- `prisma`, `drizzle-kit`, `knex`, or `flyway` in dependencies
-- `test/db` or similar helper directory
-
-**Proposed verify pattern:**
-Postgres readiness + migration + assertion:
-```yaml
-verify:
-  - pg_isready -h localhost -p 5432
-  - pnpm prisma migrate deploy
-  - pnpm tsx scripts/verify-db.ts
-```
-
-### Integration — Cross-module workflows
-
-**Detection signals:**
-- `test/integration/**` directory exists
-- `e2e/**` directory exists
-- `*.integration.test.ts` files
-
-**Proposed verify pattern:**
-Integration test runner scoped to relevant paths:
-```yaml
-verify:
-  - pnpm test test/integration
-```
-
-### Browser-based component — Storybook stories
-
-**Detection signals:**
-- `storybook` or `@storybook/*` in dependencies
-- `*.stories.{ts,tsx}` files present
-
-**Proposed verify pattern:**
-Storybook test or Chromatic visual verification:
-```yaml
-verify:
-  - pnpm storybook test --stories "ComponentName"
-```
-
-### CLI — Command-line interface
-
-**Detection signals:**
-- `bin/*` directory with executables
-- `package.json` `bin:` entry defined
-
-**Proposed verify pattern:**
-Smoke test via help flag or scripted invocation:
-```yaml
-verify:
-  - pnpm my-cli --help
-  - pnpm tsx scripts/smoke-test-cli.ts
-```
-
-## Question-bundling rule
-
-**Two or more surfaces detected:** Bundle into a single structured `question` tool call with one checkbox group per surface.
-
-**One surface detected:** Still ask (confirmation, not interrogation), but use a single-field call.
-
-**Zero surfaces detected:** Skip the QA-expectation question entirely. Fall back to generic verifies:
-```yaml
-defaults:
-  verify_after_each:
-    - pnpm run typecheck
-    - pnpm test
-```
-
-## Emission
-
-Confirmed patterns become:
-
-1. **Per-task verify templates** — tasks targeting specific files use scoped verifies (e.g., `pnpm test test/api/users.test.ts` for a task touching `src/api/users.ts`)
-2. **defaults.verify_after_each** — global breakage catchers (typecheck, full test suite)
-
-The rule: per-task verify targets the specific files touched; defaults catches global breakage.
-
-## Cross-reference to verify-design.md
-
-This rule (10) is the per-surface tactical layer — it names the tools to detect and the patterns to propose. Rule 3 (verify-design.md) owns the principles: deterministic, assertive, would-have-failed-before. Every proposed command must satisfy both layers.

package/dist/vendor/harness-opencode/dist/skills/pilot-planning/rules/self-review.md

@@ -1,46 +0,0 @@
-# Rule 7 — Self-review
-
-**Before declaring the plan ready, run through this checklist.**
-
-The validator catches schema, DAG, and glob errors. It cannot catch "this verify is too weak" or "this scope is too loose". You can.
-
-## The 7 questions
-
-1. **Is each task right-sized?** Reread each task's prompt. Could the pilot-builder do it in ~20 minutes with the standard `max_turns: 50`? If a task feels like 2 hours of work, split it. If it feels like 2 minutes, merge it.
-
-2. **Does each verify command HAVE to fail before the task runs?** For each task, mentally checkout the pre-task state. Would the verify command fail there? If not, the verify isn't observing the task's effect — fix it.
-
-3. **Is each `touches:` glob the tightest fit?** For each task, list the files the agent will need to edit. Are they all matched? Are there ANY paths matched that the agent SHOULDN'T touch? If yes to either, refine.
-
-4. **Does the DAG match the actual dependencies?** For each `depends_on:` edge, ask: does the dependent task READ code the dep produces, or assume schema the dep modifies? If "no" to both, the edge is false. Drop it.
-
-5. **Are there missing edges?** Look at every pair of tasks that share files in their `touches:`. Do they need an order? If T2's verify exercises code T1 introduces, T2 depends on T1 — even if their `touches:` don't overlap.
-
-6. **Does the DAG concentrate too much value in one task?** Task-level `cascadeFail` only blocks transitive DEPENDENTS of the failed task — sibling subtrees in a disconnected DAG keep running. So plan size is not itself a risk. The real risk is a task everything else depends on: a schema migration that all downstream work reads, a core-type definition all imports reference, a shared config every consumer parses. If THAT task fails, the whole run stalls. Is there such a task in your plan? If yes, can it be simplified — smaller diff, tighter verify, higher success probability? Don't over-concentrate; a plan where 80% of tasks depend on T1 and T1 is complex is fragile by design.
-
-7. **Could you read this plan in 6 months and understand it?** Plan names + task titles + prompts should be a self-explanatory summary of the work. If the plan needs a verbal preamble to make sense, rewrite the prompts.
-
-## Run validate
-
-```
-bunx @glrs-dev/harness-plugin-opencode pilot validate <plan-path>
-```
-
-Fix every error AND warning. The "warnings" tier (e.g., glob conflicts between tasks) is also yours to action — either decide they're OK and document it, or restructure.
-
-## When the plan is ready
-
-When all seven questions are answered "yes" and `pilot validate` exits 0:
-
-- Save the plan.
-- Tell the user: `Plan saved to <path>. Next: bunx @glrs-dev/harness-plugin-opencode pilot build`.
-- Stop. Don't summarize. Don't editorialize. The user can read the YAML.
-
-## When the plan is NOT ready
-
-If you can't answer "yes" to any of the seven questions and you don't see a way to fix it within the planning session:
-
-- Tell the user honestly. "I can't produce a plan that I'd trust the unattended builder to execute, because <specific reason>."
-- Suggest the regular `/plan` agent (markdown plans, human-driven `/build`) or a manual decomposition.
-
-It is far better to refuse than to ship a bad plan.

package/dist/vendor/harness-opencode/dist/skills/pilot-planning/rules/task-context.md

@@ -1,47 +0,0 @@
-# Task context
-
-Every non-trivial task in a pilot plan carries a `context:` field — a markdown block that preloads the builder agent with the narrative it needs to work confidently without re-discovering the problem from scratch.
-
-The builder gets a fresh opencode session per task. No carry-over from the planning conversation. No memory of which files the planner inspected. Just: title, touches, verify, context (if present), and the prompt directive. If `context:` is empty, the builder starts from the directive alone — fine for a one-line task ("add a CHANGELOG entry for version 1.2.3"), but painful for anything else.
-
-## What belongs in context
-
-- **The user-facing outcome.** In one sentence, what changes from a user's perspective when this task lands? Why should anyone care it got done?
-- **The rationale / why this task exists.** What problem is this task solving? Why is it broken out as a separate task rather than rolled into a sibling? The planner had reasons; write them down.
-- **Code pointers.** The specific files / functions / types the builder should read BEFORE editing. Name them with paths the builder can `read` directly. E.g., "Start by reading `src/pilot/cli/build.ts:resolvePlanPath` (lines 350-370) — the three-step fallback lives there." Saves 3-10 minutes of the builder re-grepping the repo.
-- **Acceptance shorthand.** What "done" looks like from the human's view — a sentence or two that complements the machine-checkable `verify:` list. Verify says "tests pass"; context says "the user can now type `pilot build plan-name` without the full path."
-- **Gotchas / constraints.** Anything the builder would trip over that `prompt:` shouldn't carry as a directive. "The schema is `.strict()` — don't add unknown keys." "Downstream tools parse stdout; keep streaming logs on stderr."
-
-## What does NOT belong in context
-
-- **The directive itself.** "Add a function that …" is `prompt:` territory. Keep context for grounding, prompt for the imperative.
-- **Implementation plans.** Don't pre-decide how the builder should write the code. `touches:` constrains the scope; the builder picks the structure within it. If you find yourself writing "first add X, then update Y, then rename Z," either the task is too big (split it) or you're over-specifying (trust the builder).
-- **Copy-pasted architecture diagrams.** If it's longer than ~40 lines, it probably belongs in a doc file the builder can read via `touches`, not inline in the plan.
-- **Tutorials.** The builder already knows how to write TypeScript / run tests / use `edit`. Don't explain the fundamentals; link to the specific non-obvious convention in the repo (AGENTS.md, CLAUDE.md).
-
-## Length guidance
-
-- **Trivial task** (one-line prompt, ≤1 file, ≤10 LOC): `context:` optional; omit is fine.
-- **Standard task** (3-5 files, non-trivial logic): one paragraph minimum, 3-5 sentences covering outcome, rationale, and the 2-3 most relevant code pointers.
-- **Complex task** (many files, architectural change): several paragraphs, organized under headers (`### Outcome`, `### Rationale`, `### Code pointers`, `### Acceptance`). If you're writing more than ~60 lines of context, reconsider: is this really one task, or should it be split?
-
-## Relationship to other fields
-
-- **`prompt:`** is the directive. It says "do X." Keep it crisp — one to three short paragraphs max. If you're tempted to put narrative in `prompt:`, move it to `context:`.
-- **`verify:`** is the machine contract. Binary, scripted, precise.
-- **`touches:`** is the scope ceiling. Lists every file the builder is allowed to edit.
-- **`context:`** is the human narrative. Read by the builder once at kickoff; helps the builder understand WHICH files inside `touches:` to read first and WHAT the end user will perceive.
-
-The four work together: `context:` orients, `touches:` bounds, `prompt:` directs, `verify:` confirms.
-
-## Emission
-
-The kickoff prompt sent to the builder renders `context:` as a `## Context` section between the scope/verify block and the final `## Task` directive. Reading order: hard rules → allowed scope → verify commands → **context (grounding)** → task (act). The builder reads context right before the directive so the directive is the last, most salient framing when it starts making edits.
-
-Empty `context:` → no `## Context` section emitted. No penalty for omission on trivial tasks.
-
-## Anti-pattern: copying the user's original request
-
-Don't just paste the Linear ticket description or the user's chat message into `context:`. That defeats the point of planning — you're supposed to have DIGESTED the request into task-shaped outcomes, not forwarded it verbatim. If the context reads like the ticket, the planning didn't do its job.
-
-Good context is specific to *this task*, referencing *this task's* files, *this task's* verify commands, *this task's* narrow success criterion. Plan-wide or epic-wide context belongs at the plan level (the top-of-file `name:` and `branch_prefix:`), not duplicated into every task.

package/dist/vendor/harness-opencode/dist/skills/pilot-planning/rules/touches-scope.md

@@ -1,81 +0,0 @@
-# Rule 4 — `touches:` scope tightness
-
-**Globs must be the tightest set that lets the task succeed. `**` is a smell.**
-
-The `touches:` list is the agent's leash. After verify passes, the worker computes `git diff --name-only` against the worktree's pre-task SHA; any path NOT matched by `touches:` is a violation and the task fails.
-
-This catches:
-
-- Agents that "helpfully" reformat unrelated files.
-- Agents that modify a test in a far-away module to make verify pass.
-- Agents that drift into copilot-style imports of unrelated utils.
-
-Tight scopes also let v0.3's parallel scheduler safely run two tasks at once — if their touches don't intersect, they can't conflict.
-
-## Heuristics
-
-- **One module = one glob.** `src/api/**` and `test/api/**` for an API task. Not `src/**`.
-- **Exact files when you know them.** `src/auth/login.ts` is better than `src/auth/**` if the task is just "edit login.ts".
-- **Test files belong with their source files.** A task that adds source code almost always adds or edits a test. Both go in `touches:`.
-- **Lock files: rarely.** `package.json` / `bun.lock` / `Cargo.lock` should appear ONLY when the task explicitly says "add a dependency". Don't include them speculatively.
-- **Config files: rarely.** `tsconfig.json`, `.eslintrc`, `package.json` scripts — only if the task is about config.
-
-## When `**` IS reasonable
-
-- The task is a global rename / rewrite (across the whole repo).
-- The task is "fix every TODO in the codebase" — touches everything by intent.
-- The task explicitly says "this is a sweeping change".
-
-In these cases, `**` is fine; the AGENT'S diligence becomes the constraint instead of the touches enforcement.
-
-## What `touches: []` means
-
-An empty `touches` list means the task **must NOT edit any files**. Use this for:
-
-- Verify-only tasks (e.g., "confirm the existing tests still pass after a deps update was made by an upstream task").
-- Probing tasks (e.g., "run benchmarks and report results" — though pilot doesn't yet have a "report results" mechanism, so this is rare).
-
-If the verify commands would FAIL without edits, an empty `touches` is a STOP — the task is contradictory.
-
-## Common mistakes
-
-- **`touches: ["**/*.ts"]`** — too loose. Better: list the actual modules.
-- **Forgetting tests.** Source-only `touches:` makes the task fail when the agent (correctly) edits the test file.
-- **Forgetting docs.** If the task explicitly says "update README", README must be in `touches:`.
-- **Including the migrations dir for a non-migration task.** Tight scope.
-
-When in doubt, write the tightest possible scope first. If the task fails verify with "touches violation: src/X.ts", the worker shows you which file got touched — broaden then.
-
-## `tolerate:` — files allowed in the diff but outside the contract
-
-When a task's verify step runs a tool that writes files as a side-effect (codegen, build, snapshots), those files will appear in `git diff` even though the agent didn't author them. Add them to `tolerate:` so enforcement accepts them without counting them as part of the task's output.
-
-Two categories to watch for:
-
-**Built-in defaults (already tolerated — don't list these):**
-- `**/next-env.d.ts` — Next.js regenerates on every `next build`.
-- `**/.next/types/**`, `**/.next/dev/types/**` — Next.js app-router generated types.
-- `**/*.tsbuildinfo` — TypeScript project-reference build cache.
-- `**/__snapshots__/**`, `**/*.snap` — Jest / Vitest snapshot files rewritten by `-u`.
-
-**Project-specific (list in `tolerate:` per task):**
-- Prisma client output (e.g., `prisma/client/**` if `prisma generate` runs in verify).
-- GraphQL codegen output (`graphql/generated/**`, `*.graphql.d.ts`).
-- OpenAPI codegen output (`api-types/generated/**`).
-- Anywhere you have a build step that writes type declarations downstream of the agent's source edits.
-
-A good test: if the task's verify step runs `prisma generate`, `pnpm codegen`, `next build`, or similar, ask: "does that command write files anywhere?" If yes, those paths go in `tolerate:`.
-
-### Example
-
-```yaml
-- id: T-ADD-RULE-MODEL
-  touches:
-    - prisma/schema.prisma
-    - src/models/rule.ts
-  tolerate:
-    - prisma/client/**        # prisma generate output
-  verify:
-    - pnpm prisma generate
-    - pnpm --filter core test rule-model
-```