harvest

name	harvest
description	Decomposes a reviewed implementation plan into backlog feature/task/subtask hierarchy
argument-hint	plan=docs/exec-plans/{YYYY-MM-DD}-{slug}-plan.md
input	{"properties":{"plan":{"type":"string","description":"Path to the reviewed implementation plan"},"dry_run":{"type":"boolean","description":"When true, output the planned structure without creating entries"}},"required":["plan"]}

Harvest Skill

The harvest skill turns a reviewed implementation plan into backlog feature, task, and subtask items. It is the reusable decomposition step invoked by the stage agent.

This skill does not perform planning or review. It assumes the incoming plan has already been reviewed or otherwise approved for decomposition.

Agent-Intercom Communication

When the agent-intercom capability pack is installed, call ping at session start. If reachable, broadcast at every step. If unreachable, warn the operator that visibility is degraded and continue locally.

Event	Level	Message prefix
Session start	info	[HARVEST] Starting: plan={input.plan}
Plan accepted	info	[HARVEST] Using reviewed plan: {plan_path}
Docline gate passed	info	[HARVEST] Docline gate passed: {plan_path}
Docline gate HALT	error	[HARVEST] Docline gate HALT: {violation_count} violation(s) in {plan_path}
Structure parsed	info	[HARVEST] Parsed implementation units: {unit_count}
Dry run	info	[HARVEST] Dry run: {feature_count} features, {task_count} tasks, {subtask_count} subtasks
Feature created	info	[HARVEST] Created feature: {feature_id} — {title}
Task created	info	[HARVEST] Created task: {task_id} — {title}
Dependency wired	info	[HARVEST] Dependency: {item_id} blocked by {depends_on}
Complete	success	[HARVEST] Complete: {feature_count} features, {task_count} tasks, {subtask_count} subtasks

Inputs

• ${input:plan}: (Required) Path to the reviewed implementation plan.
• ${input:dry_run:false}: (Optional, defaults to false) Preview the planned hierarchy without creating entries.

Workflow

Phase 1: Validate the reviewed plan

1. Read ${input:plan} in full.
2. Confirm the file exists and represents an implementation plan.
3. Confirm the plan has already cleared the review gate or is explicitly marked ready for harvesting.
4. Broadcast the accepted plan path.
5. Halt if the plan is missing, unreadable, or clearly not ready for backlog creation. Recommend running plan-review first when the review state is unclear.

Phase 1.5: Docline frontmatter gate (pre-decomposition)

Before any parsing, backlog mutation, or enclosing Stage harvest commit, gate the incoming plan against the docline frontmatter contract. This is the shift-left guard that prevents an invalid Stage-authored plan from riding into a downstream Ship feature PR and failing the CI "Docline frontmatter gate" (make docs-lint). It exists because of the 075-S root cause: a harvest commit carried a plan with doc_type: exec-plan and no top-level title/source into PR #164, failing the gate with 3 violations and blocking the PR.

1. Run the docline linter (authoring profile) against ${input:plan} via the same entrypoint CI uses. make docs-lint runs the repo-wide gate (go run ./cmd/backlogit docs lint, no arguments); to scope the check to the incoming plan, call the same source entrypoint directly: go run ./cmd/backlogit docs lint --path ${input:plan}. Use the source entrypoint, not a possibly-stale installed backlogit binary, so the gate cannot pass locally while CI fails.
2. If the linter reports valid with 0 violations, broadcast the pass and proceed to Phase 2.
3. On any violation, HALT decomposition. Do not parse the plan, create any backlog item, or allow the enclosing Stage harvest commit. Report the violations and direct the author to fix the plan frontmatter (or run backlogit docs migrate diff-first, then --apply --yes --path ${input:plan}) and re-run this gate. Cite the 075-S root cause so the reason is legible.

Both docline gates sit upstream of every path by which a plan reaches a commit: the impl-plan skill's mandatory self-lint runs at authoring time, and this Phase 1.5 gate runs before decomposition (and therefore before the enclosing Stage harvest commit). The harvest skill itself creates backlog items and does not commit; the commit is the enclosing Stage step, which this gate precedes.

Phase 2: Parse the plan structure

Extract the planning data needed for decomposition:

1. Root feature title from frontmatter and top-level headings.
2. Problem frame, requirements trace, decisions, and standards check for the root feature description.
3. Task candidates from each implementation unit.
4. Subtask candidates from file lists, acceptance criteria, verification steps, and test surfaces inside each implementation unit.
5. Dependency edges from the plan's dependency graph.

Use repository search tools to validate file references or symbols when the plan mentions existing code locations that need confirmation.

Phase 3: Build the hierarchy model

Map the plan into the backlog hierarchy:

• one feature representing the whole reviewed plan
• one task per implementation unit
• one or more subtasks per file group, verification slice, or explicit execution step inside the unit

Before creating anything, apply backlog shaping rules:

1. Keep tasks small enough to fit a focused implementation session (the 2-hour rule).
2. Keep each task within a single skill domain.
3. Require a verifiable exit state for every task and subtask.
4. Preserve plan references so downstream execution can trace work back to the plan.

Parent-first ordering (NON-NEGOTIABLE): Tasks require a parent_id referencing an existing feature. The root feature MUST be created before any tasks are created. If the harvest context does not include an existing parent feature for task-kind work items, create or identify one before proceeding. Omitting parent_id for task-kind artifacts violates the required parent-child hierarchy (P-003 decomposition integrity) and may be blocked by the configured backlog registry or policy gates.

When the backlogit capability pack is installed and the registry advertises features.shipments: true, the parent feature MUST be added to the shipment before its child tasks during shipment assembly. This ordering is enforced downstream by the Ship agent — flag it explicitly in the harvest report so Ship can assemble the shipment correctly.

Phase 4: Execute or preview

If ${input:dry_run} is true:

1. Produce the proposed feature, task, subtask, and dependency structure.
2. Broadcast the dry-run counts.
3. Do not call backlog mutation tools.

If ${input:dry_run} is false:

1. Query the backlog first to avoid duplicate root features. Use backlogit_list_items or backlogit_search_items to check for existing items with matching titles.
2. Create the root feature via backlogit_create_item or backlogit add.
3. Create one task per implementation unit under that feature.
4. Create granular subtasks under each task.
5. Wire dependencies when the backlog tool supports dependency operations (check the backlog registry for availability).
6. Broadcast each created feature, task, and dependency edge as it is written.

Phase 5: Verify and report

1. Confirm the created hierarchy through backlog read operations.
2. Report the created IDs, counts, and dependency summary.
3. Return the ready backlog as the output of the planning pipeline.
4. Recommend handing the resulting backlog to the build-and-ship workflow for harness, build, review, CI, and pull request execution.

Guardrails

• Do not modify the plan file.
• Do not decompose or commit a plan that fails backlogit docs lint (the Phase 1.5 docline frontmatter gate). HALT and require a fix first.
• Do not skip duplicate checks.
• Do not create shipment artifacts from this skill. Shipment assembly happens downstream in Stage (Step 5.5) or Ship (fallback path).
• Keep descriptions self-contained enough for the next executor to act without reopening the plan for basic context.

Model Routing

This skill operates at Tier 2 (Standard) — backlog decomposition is structured and deterministic.