@kontourai/flow-agents 0.1.1

package/skills/pickup-probe/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: "pickup-probe"
+description: "Builder Kit work-item/docs/provider-grounded Probe specialization used at the design-probe flow step before plan-work."
+---
+
+# Pickup Probe
+
+Probe selected backlog work before Builder Kit planning starts.
+
+## Contract
+
+`pickup-probe` is the Builder Kit pickup specialization of the `design-probe` flow step. It runs after `pull-work` selects work and before `plan-work` creates an execution plan.
+
+Direct `pull-work` and direct `plan-work` remain valid standalone primitives. This skill is required when the productized Builder Kit `build` flow has selected work, when a user asks to pick up work and continue into build/delivery, or when `deliver` needs to prove selected-work readiness before planning.
+
+This skill is modeled after Matt Pocock's `grill-with-docs`: challenge the selected work against the existing domain model, sharpen terminology, cross-check docs and code, ask one recommended question at a time, update durable glossary terms inline when they crystallize, and offer ADRs only for hard-to-reverse, surprising, trade-off decisions.
+
+## Required Inputs
+
+- Selected work item or coherent work item group.
+- Pull-work artifact with board snapshot, WIP assessment, selection rationale, scope, non-goals, pickup gate, and handoff.
+- Provider state, including WorkItemProvider and BoardProvider refs, issue status, labels, milestone/project fields, blockers, PR links, and source artifact refs when available.
+- WIP and conflict scan covering active sessions, open PRs, verification/review/CI remediation queues, expected shared files, and worktree or sandbox mode.
+- Existing acceptance criteria, done criteria, stop-short risks, and known non-goals.
+- Source issue and artifact refs, including issue URLs, source planning or idea artifacts, flow definition refs, and missing-source notes.
+- Repository reality: `CONTEXT.md` when present, relevant docs, ADRs, contracts, skills, schemas, fixtures, and code paths named by the selected work.
+- Domain documentation: root `CONTEXT.md`, `CONTEXT-MAP.md` when present, and relevant `docs/adr/` records. If no durable context file exists, create one lazily only when a resolved project-specific term needs a home.
+- Planned-base drift context: `planned_base_ref`, `planned_base_sha`, current target ref/SHA, `planning_scope_refs`, and a diff summary from the planned/pulled work SHA to current HEAD when available.
+
+If a required input is missing, first try to recover it from local artifacts and provider snapshots. Ask one alignment question only when the missing input creates a real decision gap that cannot be resolved from local evidence.
+
+If `planned_base_sha` is missing, record that as a `NOT_VERIFIED` drift baseline gap and use current target plus provider history as the best available baseline. Do not invent a planned SHA.
+
+For Builder Kit baseline freshness gaps where `planned_base_sha` is missing or inconclusive, record `resolution_hints` in the Builder Kit Probe record when that record shape is available. Use `gap_id: revision_freshness_not_verified`, `claim_id: planning.baseline.current`, and a reason code such as `missing_planned_base_sha`. The hint should name the blocked refs, the required evidence needed to resolve the gap, `resolve_at` pointing back to `pickup-probe`, and any explicit accepted fallback baseline that allows planning to continue.
+
+## Behavior
+
+Challenge the selected work against the repository before planning:
+
+- Fetch latest for the target ref when available, then compare the current target SHA to `planned_base_sha`. Record current target ref/SHA, planned base ref/SHA, `commits-since`, planned age, changed files reviewed, and changed-file intersections with `planning_scope_refs`.
+- Classify revision freshness as `fresh`, `drifted`, or `stale`. `fresh` may proceed through normal pickup gates. `drifted` prompts alignment and may proceed only when the Probe records accepted decisions or an explicit accepted gap. `stale` routes back to `idea-to-backlog` before implementation planning.
+- If `planned_base_sha` is missing, mark the freshness check `NOT_VERIFIED` and record the concrete fallback baseline, such as current target ref/SHA plus provider history. Treat that as an accepted gap only when the artifact names why planning may continue; do not invent a planned SHA. When using a Builder Kit Probe JSON record, include `resolution_hints` for `revision_freshness_not_verified` so the next planning attempt can see the accepted fallback baseline or route back to `pickup-probe` for missing evidence.
+- Research drift before asking questions: compare the selected work's `planned_base_sha` or pulled-work SHA to current HEAD before running the alignment interview. Inspect changed files, docs, ADRs, contracts, schemas, dependency state, and expected execution areas that overlap `planning_scope_refs` or likely modified files.
+- Classify the diff from planned base to current HEAD as `no_material_drift`, `scope_drift`, `dependency_drift`, `contract_drift`, or `conflict_risk`. Treat material drift as pickup Probe context and ask an alignment question before planning when it changes scope, acceptance criteria, dependency assumptions, terminology, contract expectations, or execution risk.
+- Compare the selected work to `CONTEXT.md`, docs, ADRs, contracts, existing skills, schemas, fixtures, and nearby code.
+- Verify that the acceptance criteria describe an executable outcome rather than only implementation tasks.
+- Sharpen fuzzy domain and workflow terms until the artifact names, scope, gate names, and next step mean one thing.
+- Surface contradictions between issue text, pull-work handoff, provider state, docs, ADRs, contracts, and code reality.
+- Challenge glossary conflicts immediately: if a user or issue uses a term differently than `CONTEXT.md`, ask which meaning is authoritative before planning.
+- Discuss concrete scenarios when boundaries are fuzzy, especially around ownership, provider state, workflow gates, and stop-short behavior.
+- Check whether the selected work is still ready after WIP, conflicts, blockers, dependency freshness, and expected modified files are considered.
+- Keep downstream issues and non-goals out of scope unless they are explicit contract consumers for the selected work.
+- Ask one question at a time when a decision is needed, include a recommended answer, and record the answer immediately.
+- Record unresolved questions as blockers unless the user or orchestrator explicitly accepts proceeding with the gap.
+- Update the active workflow artifact immediately when a decision crystallizes; do not rely on chat memory.
+
+For Builder Kit build-flow recovery, a missing or incomplete pickup Probe record routes `decision_gap` back to the `design-probe` step. For pickup/planning gaps, returning to `design-probe` means completing this pickup Probe record before retrying `plan-work`.
+
+## Output
+
+Record the pickup Probe result in the pull-work artifact, handoff artifact, or documented Builder Kit Probe record referenced by `state.json` or `handoff.json`. The record must include:
+
+- Probe status: `pass`, `needs_decision`, `blocked`, or `accepted_gap`.
+- Decisions made during the Probe, with source refs when relevant.
+- Unresolved questions, each with owner, impact, and whether it blocks planning.
+- Accepted gaps, including who accepted the gap and why planning may continue.
+- Drift research: planned base ref/SHA, current target ref/SHA, command or provider evidence used, changed files reviewed, drift classification, and whether the drift is material.
+- Builder Kit `resolution_hints` when available for baseline freshness `NOT_VERIFIED` gaps, including `planning.baseline.current`, required baseline evidence, and the accepted fallback baseline behavior.
+- Planning readiness: ready/not ready, required handoff target, and readiness evidence.
+- Expected modified files or file areas, including generated/runtime artifact expectations when relevant.
+- Conflict risks with active work, shared files, provider state, or downstream contract consumers.
+- Route reason and next action, such as `continue -> plan-work`, `decision_gap -> design-probe`, `blocked -> pull-work`, or `split_scope -> pull-work`.
+
+## Planning Gate
+
+Planning is ready only when:
+
+- Selected work and source refs are clear enough for `plan-work`.
+- Acceptance criteria and done criteria are present or explicit accepted gaps exist.
+- Planned-base drift research is recorded, or the missing baseline is explicitly marked `NOT_VERIFIED` with a best-available fallback.
+- Provider state and WIP/conflict scan have been checked or marked `NOT_VERIFIED` with a reason.
+- Scope, non-goals, expected modified files, and conflict risks are recorded.
+- Contradictions are resolved, blocked, or explicitly accepted as gaps.
+- The route reason and next action are recorded in an artifact that can be recovered without chat memory.
+
+If the gate fails, stop before `plan-work` and update the artifact with the blocker or decision gap.
+
+## Docs And ADR Policy
+
+`pickup-probe` may identify durable terminology and decision gaps, but it must keep documentation changes narrow:
+
+- Update `CONTEXT.md` inline only for glossary-style durable terminology decisions, using tight one- or two-sentence definitions and `_Avoid_` terms when useful. Keep implementation details out of `CONTEXT.md`.
+- If a `CONTEXT-MAP.md` exists, update the relevant context instead of assuming the root glossary owns the term.
+- Create a lazy context file only when a resolved term or workflow concept has no existing home.
+- Do not create context files for transient planning notes, open questions, or provider snapshots.
+- Propose or create ADRs sparingly, only when all three are true: the decision is hard to reverse, surprising without context, and the result of a real trade-off.
+- Prefer workflow artifacts for pickup decisions, unresolved questions, accepted gaps, and route reasons until the work is accepted.
+
+## Handoff To Plan Work
+
+When the Probe passes, hand off to `plan-work` with:
+
+- selected work item refs
+- pull-work artifact path
+- pickup Probe record path or section
+- provider state summary
+- planned-base drift summary and drift classification
+- accepted gaps
+- expected modified files
+- conflict risks
+- sandbox/worktree mode
+- route reason and next action
+
+`plan-work` must consume this record for Builder Kit build-flow planning. If the record is absent, contradictory, or lacks an accepted gap for a known decision gap, planning stops and routes back to `design-probe`.

package/skills/plan-work/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: "plan-work"
+description: "Code planning primitive — goal + directory to structured execution plan. Delegates to tool-planner. No resume, no ideation."
+---
+
+# Plan
+
+Goal + directory in, structured plan artifact out. Pure planning primitive.
+
+## Agents
+
+| Agent | Role |
+|---|---|
+| tool-planner | Codebase analysis, structured execution plan, writes plan artifact |
+
+## Orchestrator Rule
+
+You do not read source files. You delegate to tool-planner and read the artifact it produces.
+
+## Shared Contracts
+
+Follow:
+- `context/contracts/artifact-contract.md`
+- `context/contracts/planning-contract.md`
+- `context/contracts/sandbox-policy.md`
+
+This skill owns orchestration. The contracts own the required artifact shape, Definition Of Done, acceptance criteria, sandbox mode, evidence expectations, and stop-short risk rules.
+
+## Pre-Planning: Research
+
+Before delegating to tool-planner, check if the goal can be solved with existing tools or libraries:
+1. Search the current codebase for similar functionality
+2. If the goal involves adding new capabilities, invoke the search-first skill
+3. Pass research findings to tool-planner as additional context
+
+Skip this step if the goal is purely about modifying existing code (bug fixes, refactors).
+
+## Input
+
+The orchestrator (or user) provides:
+- **Goal**: what to build or change
+- **Directory**: working directory for the codebase
+- **Constraints**: from AGENTS.md, user preferences, conversation context
+- **Session file path** (optional): if part of a larger workflow, the orchestrator passes this
+
+Direct `plan-work` remains a standalone planning primitive. Do not require Builder Kit pickup Probe state for ordinary direct planning prompts unless the user is trying to pick up provider-backed backlog work or continue a productized build/delivery workflow.
+
+When `plan-work` is invoked from the Builder Kit `build` flow, from `deliver`, or from a pick-up-and-build request after `pull-work`, first read the recorded pickup Probe decisions, unresolved questions, accepted gaps, sandbox/worktree mode, expected modified files, and conflict risks from the pull-work or handoff artifact. If the handoff lacks required Probe decisions or explicitly accepted gaps, stop planning and route `decision_gap` back to `design-probe`; for pickup/planning gaps, that means returning to the pickup Probe before retrying planning.
+
+Only consume Builder Kit Probe `resolution_hints` in those Builder Kit build/deliver/pickup contexts. Direct primitive `plan-work` remains valid without Builder Kit-specific `resolution_hints`; do not require or synthesize them for ordinary planning requests.
+
+Required Builder Kit handoff fields before planning:
+
+- `probe_status` is `passed` or `accepted_gap`
+- `probe_artifact_ref` points to the pickup Probe record
+- selected item ids are present
+- grouping decision is `single-item`, `independent-items`, or `justified-bundle`
+- accepted gaps, expected modified files, conflict risks, route reason, and next action are recorded
+
+If the handoff came from stale broad continuation language after a previous merge, treat it as missing Probe evidence and route back to `design-probe` / `pickup-probe`. Do not infer permission to plan the next item from a previous continuation instruction.
+
+## Provider-Backed Baseline Preflight
+
+For provider-backed backlog work, `plan-work` consumes freshness context; it does not classify revision freshness itself. Before delegating to `tool-planner`, read the pull-work or pickup Probe artifact and carry forward:
+
+- `revision_freshness` from the upstream artifact
+- current target ref/SHA confirmed from the latest provider or repository state available to pull-work/pickup Probe
+- `planned_base_ref` and `planned_base_sha` when present
+- accepted gaps, including any accepted-gap baseline for missing historical `planned_base_sha`
+- Builder Kit Probe `resolution_hints` for `revision_freshness_not_verified` when the invocation came through Builder Kit build/deliver/pickup, especially hints for `planning.baseline.current`
+- changed scope intersections with `planning_scope_refs`, contracts, dependencies, expected files, or execution areas
+- dependency freshness and provider state, including blockers, PR links, board/project membership, and any `NOT_VERIFIED` checks
+
+If `revision_freshness` is `stale`, unresolved, missing without an accepted gap, or contradicted by dependency/provider state, stop planning. Route pickup/planning gaps back to `pickup-probe`; when `revision_freshness` is `stale`, route stale shaped work back to `idea-to-backlog` instead of handing the item to `tool-planner`.
+
+An explicit accepted-gap fallback baseline may allow planning to proceed, but it must name the fallback baseline used. Missing `planned_base_sha` is never fresh by itself. If baseline freshness is missing or `NOT_VERIFIED`, record the gap and stop planning unless it has been explicitly accepted as a fallback baseline naming the current target ref/SHA plus provider history or equivalent.
+
+For Builder Kit `resolution_hints` with `gap_id: revision_freshness_not_verified` and `claim_id: planning.baseline.current`, carry the accepted fallback baseline into the plan's baseline section exactly enough for execution and verification to recover it. If the missing baseline evidence does not include an explicit accepted fallback baseline, do not pass the item to `tool-planner`; route back to `pickup-probe` so the Probe can collect evidence or record the accepted gap.
+
+The `tool-planner` prompt context must include the latest-base confirmation and acceptance-criteria drift findings:
+
+- the current target ref/SHA that planning is based on
+- the source freshness state or accepted-gap baseline
+- each upstream AC id revalidated against drift
+- stale assumptions found during revalidation
+- any route-back decision already taken or still required
+
+## Workflow
+
+1. Create session file in `.flow-agents/<slug>/` if one wasn't provided:
+   - Filename: `<slug>--plan-work.md`
+   - `status: planning`, `type: plan-work`
+   - Create or update `state.json` with phase `planning`
+   - use `npm run workflow:sidecar -- ensure-session --source-request ... --summary ... --criterion ...` when the repository provides it; this also writes `.flow-agents/current.json`
+2. Delegate to `tool-planner`:
+   ```
+   Goal: <goal>
+   Directory: <working directory>
+   Constraints: <constraints>
+   todo_file: <session file path>
+   Workflow artifact root: <path from npm run workflow:sidecar -- current --format path>
+   Latest-base confirmation: <current target ref/SHA, revision_freshness, planned base or accepted-gap baseline>
+   AC drift findings: <per-AC revalidation, stale assumptions, route-back decisions>
+   Evidence expectations: preserve AC ids; require command/test evidence and structured source refs for implementation behavior; require provider/closure `Acceptance Evidence` tables when comments claim behavior
+   ```
+3. tool-planner explores the codebase and writes the plan to the artifact file:
+   - `<session-basename>-plan.md`
+   - `acceptance.json` with pending criteria from Definition Of Done
+   - `handoff.json` with the execution/user-approval next steps
+   - use `npm run workflow:sidecar -- init-plan <artifact> --source-request ... --summary ... --next-action ...` when the repository provides it
+   - every acceptance criterion should have a stable id, either in Markdown or mirrored in `acceptance.json`
+   - every implementation task/wave should list which acceptance criterion ids it supports
+   - acceptance criteria for behavior changes should name expected command/test proof and expected source evidence refs or permalink upgrade expectations
+   - `acceptance.json` evidence refs must be structured objects, not legacy strings
+   - if task-to-acceptance mapping is unclear, send the planner feedback before presenting the plan as ready
+4. Read the plan artifact
+5. Update session file: paste plan summary into `## Plan`, set `status: planned`
+6. Update `state.json` with `status: planned`, phase `planning`, and the next action
+7. Present the plan to the user
+8. If the user wants changes, re-delegate to tool-planner with feedback
+
+Never rely on conversational memory for the slug. Resolve the active artifact with `npm run workflow:sidecar -- current --format path` and pass that path to delegated agents.
+
+## Definition Of Done Contract
+
+Every plan artifact must include the `## Definition Of Done` defined in `context/contracts/planning-contract.md`, including `Stop-short risks` and `Durable docs target`. If the goal is exploratory or uncertain, the plan must still name what the user should be able to take away from the work. Do not let acceptance criteria stop at implementation tasks.
+
+Every non-trivial implementation plan must include traceability from requirements to acceptance criteria to execution tasks. At minimum, acceptance criteria need stable ids and each wave/task needs a `Supports:` line referencing those ids. Loose wave names without criterion references are not execution-ready.
+
+Every behavior-changing plan must also include evidence traceability expectations. The Definition Of Done should tell workers and verifiers which command/test evidence is expected and which source evidence refs should support claimed behavior. Source refs use the structured evidence ref object from `context/contracts/artifact-contract.md`; before publication they may be local file/line/excerpt refs, and provider-facing comments should upgrade them to immutable GitHub blob permalinks pinned to a commit SHA when available. Plans that expect provider, PR, issue, closure, or final acceptance comments must require an `Acceptance Evidence` table with columns `AC id`, `Status`, `Command/Test Evidence`, `Source Evidence / Permalinks`, and `Gaps`.
+
+Every plan artifact must also record `Sandbox mode` using `context/contracts/sandbox-policy.md`. If the needed mode is unclear, choose the smallest safe mode for the plan and list the escalation condition that would require a stronger boundary.
+
+## Structured Sidecars
+
+Follow `context/contracts/artifact-contract.md` and `context/contracts/planning-contract.md`.
+
+When `npm run workflow:sidecar --` exists, structured sidecars are not optional ceremony. Use the writer commands above, then validate the artifact directory when local validation is available. If the writer is unavailable or blocked, preserve the exact blocker in the Markdown artifact as a `NOT_VERIFIED` gap.
+
+Planning owns:
+
+- `state.json`: current phase/status and next action
+- `acceptance.json`: criteria from the Definition Of Done, initially `pending`
+- `handoff.json`: summary and execution/user-approval next steps
+
+If a target harness cannot write sidecars, record `NOT_VERIFIED` or an explicit gap in the session file instead of pretending the structured state exists.
+
+## Session File Format
+
+```markdown
+# <Goal one-liner>
+
+branch: <branch>
+worktree: <worktree>
+created: <date>
+status: planning | planned
+type: plan-work
+
+## Plan
+
+Structured plan from tool-planner (pasted from artifact).
+
+## Definition Of Done
+
+Copied from the plan artifact. This is the stop condition for delivery.
+```
+
+## Output
+
+- Session file in `.flow-agents/<slug>/` with status `planned`
+- Plan artifact: `<session-basename>-plan.md`
+- Structured sidecars: `state.json`, `acceptance.json`, and `handoff.json`
+- The plan artifact is the source of truth — tool-worker agents read it directly
+- Plan artifact follows `context/contracts/planning-contract.md`
+
+{context?}

package/skills/pull-work/SKILL.md

@@ -0,0 +1,309 @@
+---
+name: "pull-work"
+description: "Select ready GitHub issues from the executable backlog and prepare them for implementation. Use when choosing what to work on next, reviewing a kanban-style issue board, enforcing WIP limits, grouping issues, deciding worktree isolation, or handing selected work to plan-work."
+---
+
+# Pull Work
+
+Select ready backlog work and prepare a bounded execution handoff without implementing it.
+
+## Contract
+
+- Use `context/contracts/work-item-contract.md` as the source vocabulary for provider-backed work item shape, provider roles, and capability flags.
+- Read the configured backlog provider dynamically.
+- Select one issue or a coherent issue group.
+- Do not implement code.
+- Do not weaken scope to make execution easier.
+- Do not implement provider settings, provider configuration, or configured-provider discovery; this skill consumes configured provider state and helper outputs when available.
+- Do not reimplement Flow Definition validation or gate expectation semantics. When Flow Definition readiness is relevant, call Flow's validation surface (`flow validate-definition <path> [--json]` or `validateDefinitionWithDiagnostics`) and cite that result.
+- Do not pull unrelated ideas together just because they are nearby in the backlog.
+- Do not invoke `execute-plan`, `review-work`, `verify-work`, `evidence-gate`, or release skills.
+- Hand selected work to `plan-work` only after the pickup gate is satisfied and the user wants planning.
+- When the user wants to pick up work, enforce the full pull-work selection, WIP/shepherding, dependency, grouping, and worktree logic before any planning handoff.
+- Do not hand selected work to `plan-work` until a fresh pickup Probe record exists for the selected item or explicitly bundled group, unless the user is making a direct primitive-only `pull-work` request and explicitly wants the primitive to stop before planning.
+- Every pull-work artifact must correlate to selected backlog refs, shepherding refs for active PRs/sidecars/issues being finished before new work, or `backlog_gap=true` with a route to `idea-to-backlog`; direct audits with no new selection must record `shepherding_item_ids` or `backlog_gap`, not free-floating implementation scope.
+- A stale broad continuation instruction, such as "keep going", "pick up the next two", or "continue after merge", may allow queue inspection but must not bypass per-item pickup Probe evidence.
+
+## Inputs
+
+- Repository or working directory.
+- Optional labels, milestone, project board, assignee, or priority filter.
+- Optional WIP limit or current in-progress context.
+- Existing `.flow-agents/<slug>/` artifacts, PRs, and CI/review queues.
+
+## Artifact Contract
+
+Create or update `.flow-agents/<slug>/<slug>--pull-work.md` with:
+
+- `board_snapshot`: filters, issue list, labels, milestone/provider milestone state, project fields, state, blockers
+- `wip_assessment`: active work, reviews, verification, CI remediation, with personal WIP separated from global conflict context
+- `my_active_work`: local worktrees, dirty branches, open PRs by the current user, active sidecars, and in-flight review/verification/release work owned by the current user
+- `shepherding_candidates`: personal PRs, worktrees, or sidecars that should be reviewed, fixed, published, merged, abandoned, or cleaned before starting more work
+- `stale_worktrees`: worktrees with no open PR, no recent activity, merged/abandoned branches, or unclear ownership that need an explicit keep/remove decision
+- `open_prs_by_me`: open pull requests authored by the current user, including check/review state and whether they need shepherding
+- `global_conflicts`: open PRs, active work, or sidecars by others that overlap selected files, dependencies, release lanes, or provider state
+- `dependency_impacts`: blockers, blocked-by relationships, sequencing constraints, and work that should be prioritized because it unlocks or protects other work
+- `start_new_work_decision`: `proceed`, `shepherd_existing`, `cleanup_required`, `blocked`, or `needs_user`, with the reason and next action
+- `selection`: selected issue(s), rationale, priority, dependencies
+- `selected_item_ids`: provider or local backlog artifact refs selected for pickup, using neutral work item refs when available
+- `shepherding_item_ids`: active PR, sidecar, issue, worktree, or local backlog artifact refs being finished, reviewed, cleaned up, or unblocked before starting new work
+- `backlog_gap`: `true` only when no provider/local backlog item or shepherding item can anchor the artifact, with the gap reason
+- `backlog_gap_route`: route to `idea-to-backlog` or Builder Kit shape, including the prompt/context needed to create a local backlog artifact or provider-backed item
+- `selected_scope`: selected repository, work item refs, whether the selection is single-item, independent-items, or a justified Work Item Group, and the thinnest meaningful slice being handed to planning
+- `priority_rationale`: provider-neutral ranking reason, including delivery outcome, dependency unlocking, urgency, risk, size, readiness, and why higher-visible items were not selected
+- `dependencies`: known blockers, blocked-by items, dependency freshness, cross-repo sequencing constraints, and any dependency checks that are `NOT_VERIFIED`
+- `wip_conflict_notes`: personal WIP gate result, global WIP/conflict notes, file/provider-state/release-lane risks, and whether conflicts block, inform, or require isolation
+- `alignment_questions`: pickup Probe questions asked one at a time, recommended answer, user answer, unresolved question, or reason no question is needed
+- `grouping_check`: thinnest meaningful slice, bundle justification, dependency map, split/keep decision
+- `anchor`: objective, source artifacts, non-goals, done criteria
+- `work_scope`: allowed files/areas, risky areas, coordination notes
+- `worktree_decision`: yes/no, path/branch if known, rationale
+- `worktree_lifecycle`: path, branch, retain-until condition, cleanup owner, cleanup command, and whether cleanup is blocked by an open PR, review, CI, or user decision
+- `handoff`: recommended `plan-work` prompt and acceptance criteria
+- `pickup_gate`: pass/fail/block and reason
+- `pickup_probe`: for Builder Kit build flow only, the recorded Probe decisions, unresolved questions, accepted gaps, planning readiness, expected modified files, sandbox/worktree mode, and conflict risks that `plan-work` must consume
+- `builder_kit_handoff`: when Builder Kit build flow is active, machine-checkable fields `probe_status`, `probe_artifact_ref`, selected item ids, grouping decision, accepted gaps, route reason, and next action
+
+## Workflow
+
+### 1. Read Board State
+
+First inspect effective backlog provider settings when the repo provides them:
+
+```bash
+npm run effective-backlog-settings -- --repo-path . --json
+```
+
+If the command returns `status: configured`, use the returned `WorkItemProvider`, `BoardProvider`, filters, and WIP policy as the default board source. Preserve the provider source and settings path in the pull-work artifact. If it returns `status: ask_user` or the helper is unavailable, ask the user which backlog `WorkItemProvider` and `BoardProvider` to use before selecting work. Do not silently assume a repository, project, filters, labels, milestone, or WIP policy.
+
+Use `github-cli` / `gh` when available to inspect issues, labels, milestones, project fields, PR links, and blockers.
+
+Treat GitHub Issues as a `WorkItemProvider` and GitHub Projects as a `BoardProvider`, mapped through `context/contracts/work-item-contract.md`. Preserve provider-specific values in the artifact when useful, but use the contract's neutral fields for selection, grouping, and handoff.
+
+Classify issues:
+
+- ready
+- blocked
+- stale
+- in progress
+- related-only
+
+When local JSON from `gh issue list/view --json ...` is available, normalize it through the helper before selection:
+
+```bash
+npm run pull-work-provider -- \
+  --settings-json context/settings/backlog-provider-settings.json \
+  --issues-json /path/to/github-issues.json \
+  --resolved-ref kontourai/flow#2=closed
+```
+
+The helper preserves provider refs, project fields, blockers, PR links, and source artifact refs, then emits the work item contract fields plus readiness evidence. Use live provider state for final decisions; fixture output is only test evidence.
+
+Before classifying provider-backed work as ready for pickup, fetch the latest target ref when network access and provider credentials are available, then compare the current target SHA to the work item's `planned_base_sha`. Record the current target ref/SHA, planned base ref/SHA, `commits-since`, planned age, changed files since the planned base, and changed-file intersections with `planning_scope_refs` in the pull-work artifact or helper output.
+
+Classify revision freshness as:
+
+- `fresh`: the planned base matches the current target SHA, or the only newer commits/files are known not to affect the planning scope.
+- `drifted`: the target has moved, but changed files do not materially intersect `planning_scope_refs`; prompt alignment and record accepted decisions before planning may proceed.
+- `stale`: changed files intersect `planning_scope_refs`, contracts, dependencies, or expected execution areas enough that the issue may no longer describe the right slice; route back to `idea-to-backlog` instead of handing directly to `plan-work`.
+
+Missing `planned_base_sha` is not fresh. Record it as an explicit `NOT_VERIFIED` or accepted-gap baseline with the concrete fallback baseline used, such as current target ref/SHA plus provider history. Do not invent revision certainty for legacy work items.
+
+Return vague work to `idea-to-backlog` instead of inventing scope.
+
+### 2. Enforce WIP And Shepherding
+
+Before selecting new work, check whether review, verification, release, or CI remediation is congested. Separate the current user's active work from global conflict context.
+
+Personal WIP scan:
+
+- Inspect local worktrees and branches for dirty state, unpublished commits, merged branches, abandoned branches, and unclear ownership.
+- Inspect open PRs authored by the current user and record review/check state, requested changes, mergeability, and whether the PR needs shepherding.
+- Inspect active `.flow-agents/<slug>/` sidecars owned by the current user or current session, especially `planning`, `planned`, `in_progress`, `verifying`, `needs_decision`, `not_verified`, `failed`, and `blocked`.
+- Classify personal items into `my_active_work`, `shepherding_candidates`, `stale_worktrees`, and `open_prs_by_me`.
+
+Global conflict scan:
+
+- Inspect open PRs, active work, and known sidecars from other owners only for file overlap, dependency, sequencing, release-lane, provider-state, or artifact-contract risk.
+- Record those risks in `global_conflicts` and `dependency_impacts`; do not block just because other people have work in progress.
+
+Default policy:
+
+- Prefer finishing active work over starting new work.
+- Personal WIP may block new work when it exceeds the WIP policy, needs review/CI shepherding, has dirty worktrees, or has unresolved verification/release decisions.
+- Other people's WIP blocks only when it creates concrete file-scope conflict, dependency, sequencing, release, provider-state, or artifact-contract risk for the selected item.
+- Do not pull new implementation work when verification/evidence gates are overloaded.
+- Prefer shepherding an already-open personal PR over starting new implementation when the PR is near merge or needs only checks/review/fixes.
+- Return vague or stale issues to `idea-to-backlog`.
+- Do not select work that conflicts with another active TODO's `modified_files` unless isolation or sequencing is recorded.
+- Always record `start_new_work_decision` before selection handoff. If the decision is not `proceed`, stop with the shepherding, cleanup, blocker, or user-decision next action.
+
+### 3. Select Work
+
+Choose one issue or coherent group based on:
+
+- priority
+- milestone / delivery outcome alignment
+- dependency unlocking
+- risk
+- size
+- readiness
+- owner / agent availability
+- parallelism opportunity
+
+Prefer the smallest coherent unit that can reach evidence and release readiness without leaving dependent half-work.
+
+### Cross-Repo Ranking And Selection
+
+When the backlog spans related repositories or product areas, use provider-neutral cross-repo ranking before selection. Compare work items by normalized work item refs from `context/contracts/work-item-contract.md`, not by provider-specific board mechanics. Preserve provider-specific details as evidence, but do not mutate GitHub Projects, provider fields, or cross-repo provider state from this skill.
+
+Rank candidates by:
+
+- delivery outcome alignment, including milestone, release lane, dogfood target, or explicit user priority
+- dependency unlocking or protection across repositories
+- readiness, acceptance criteria quality, dependency freshness, and provider state
+- risk, size, reversibility, and ability to produce evidence without dependent half-work
+- personal WIP, global conflicts, release-lane conflicts, and file/provider-state overlap
+- owner or agent availability and whether the work is appropriate for the current sandbox/worktree mode
+
+The output must make the ranking decision reviewable. Record `selected_scope`, `priority_rationale`, `dependencies`, `wip_conflict_notes`, and `alignment_questions` even when the selection is a single issue. Include why visible alternatives were deferred when they outrank the selected item on one dimension but lose on readiness, dependency, WIP, or scope fit. If ranking cannot be completed from available provider context, ask one alignment question or record the unknown as a blocker or accepted gap before planning.
+
+Default to one thinnest meaningful slice. A Work Item Group selection requires explicit justification in `grouping_check` and `selected_scope`; do not group items merely because they share a milestone, label, repository family, or theme.
+
+For issue groups, require an explicit grouping check:
+
+- the group shares one user outcome and acceptance signal, or
+- one issue hard-blocks another and the dependency sequence is recorded, or
+- splitting would create unsafe or unusable partial delivery.
+
+If the relationship is only thematic, split the work and select the thinnest meaningful slice instead.
+
+### Selection Examples
+
+Use these compact examples as the expected artifact shape when selecting or rejecting cross-repo work:
+
+- **independent docs work**: `selected_scope`: single-item docs update in `kontourai/flow-agents`; `priority_rationale`: small, ready, improves workflow discoverability, and does not block runtime delivery; `dependencies`: none known; `wip_conflict_notes`: no personal WIP block and no global file overlap; `grouping_check`: single-item, no Work Item Group; `alignment_questions`: none needed because scope and docs target are explicit.
+- **Resource Contract audit work**: `selected_scope`: single-item audit of the Resource Contract guidance across the owning repo and referenced docs; `priority_rationale`: selected because it protects later implementation work and resolves contract drift before code changes; `dependencies`: requires current contract docs and provider refs to be fresh, with unknown external repo state recorded as `NOT_VERIFIED` if not checked; `wip_conflict_notes`: block if another active task edits the same contract, otherwise record as global context; `grouping_check`: do not bundle fixes unless the issue explicitly requires audit plus remediation; `alignment_questions`: ask whether to stop at audit evidence or include narrowly scoped doc fixes, with a recommended answer.
+- **dogfood-alpha implementation work**: `selected_scope`: single-item implementation slice in the dogfood-alpha milestone; `priority_rationale`: high delivery alignment and unlocks product dogfood evidence, but only selected if dependencies are closed or explicitly accepted; `dependencies`: list blocked-by issues, required artifacts, and pickup Probe freshness; `wip_conflict_notes`: require worktree isolation when implementation overlaps active files or release lanes; `grouping_check`: Work Item Group only when one item hard-blocks the implementation and the dependency sequence is part of the same acceptance signal; `alignment_questions`: ask the narrow scope question before `plan-work` if the issue could expand into provider adapters or runtime orchestration.
+- **blocked cross-product dependency**: `selected_scope`: no implementation selection; `priority_rationale`: defer because a higher-priority item in another product/repo is blocked by an unresolved dependency or missing provider state; `dependencies`: name the blocker, owner/repo when known, and freshness check; `wip_conflict_notes`: record any release-lane or provider-state conflict as the reason to stop; `grouping_check`: unsafe-group unless explicit dependency sequencing and shared acceptance justify a bundle; `alignment_questions`: ask whether to shepherd/unblock the dependency, return to shaping, or choose the next ready independent item.
+
+### 4. Anchor Check
+
+Before planning, restate:
+
+- selected issue links
+- objective
+- authoritative artifacts
+- milestone or delivery outcome, including whether it is a real provider milestone, a project field, a label, or intentionally unset
+- non-goals
+- current gate
+- allowed file/work scope
+- done criteria
+- expected verification/evidence/release gates
+
+### 5. Worktree Decision
+
+Use `context/contracts/sandbox-policy.md` for the broader execution boundary decision. `pull-work` owns the first `sandbox_mode` recommendation; `execute-plan` may upgrade it if risk increases.
+
+Strongly consider isolated worktrees, especially for:
+
+- parallel agent execution
+- risky refactors
+- prototype/MVP work
+- multiple agents in one repo
+- large dependency or migration changes
+
+Record:
+
+- sandbox_mode: `local-read-only`, `local-edit`, `worktree`, `container`, `cloud-sandbox`, or `privileged-integration`
+- worktree used: yes/no
+- path or branch when known
+- rationale
+- worktree lifecycle:
+  - `retain_until`: `pr_merged`, `branch_abandoned`, `user_override`, or a documented equivalent
+  - `cleanup_owner`: user, orchestrator, or named agent role
+  - `cleanup_command`: usually `git worktree remove <path>` after merge/abandonment and optional branch deletion when safe
+  - `cleanup_blocked_by`: open PR, pending review, pending CI, dirty files, unpublished commits, or user decision
+
+If not using a worktree, state why shared-workspace execution is acceptable.
+
+Publishing a branch must retain the worktree for review, CI, and follow-up fixes. Final acceptance, release cleanup, or explicit abandonment owns worktree removal. Do not copy files back into the main checkout by hand; Git is the merge surface.
+
+### 6. Handoff
+
+Then invoke or recommend `plan-work` only when the user wants execution planning to begin.
+
+### Builder Kit Pickup Probe Handoff
+
+Direct `pull-work` remains a standalone primitive: it may select work, write the pull-work artifact, and stop at a `plan-work` handoff without invoking the productized Builder Kit build flow.
+
+For productized pickup, selected work routes through the `design-probe` step as `pickup-probe` before planning. This applies to Builder Kit `build` flow and to "pick up work and build it" requests that intend to continue into delivery. Do not let `plan-work` proceed until the pull-work or plan handoff artifact records the pickup Probe outcome:
+
+- goal fit and scope
+- blockers and dependencies
+- dependency freshness
+- acceptance criteria quality
+- provider state
+- risk and stop-short risks
+- sandbox/worktree mode
+- expected modified files and conflict risks
+- planning readiness
+- decisions, unresolved questions, and any accepted gaps
+
+Record these machine-checkable handoff fields for every selected productized pickup item or bundle:
+
+- `probe_status`: `missing`, `required`, `in_progress`, `passed`, `accepted_gap`, or `blocked`
+- `probe_artifact_ref`: path to the pull-work section or Builder Kit Probe sidecar that contains the pickup Probe evidence
+- `selected_item_ids`: neutral work item refs from `context/contracts/work-item-contract.md`
+- `grouping_decision`: `single-item`, `independent-items`, `justified-bundle`, `unsafe-group`, or `empty-board`
+- `accepted_gaps`: known gaps explicitly accepted for this planning pass
+- `route_reason` and `next_action`
+
+Ask one alignment question at a time only when repo/provider context leaves a genuine decision gap. Include a recommended answer with that question. If the user accepts proceeding despite an unresolved question, record the unresolved question as an accepted gap in the handoff artifact before planning.
+
+For productized pickup handoff, route `decision_gap` back to `design-probe`; for pickup/planning gaps, that means returning to this pickup Probe record before retrying `plan-work`.
+
+If a direct `pull-work` invocation has enough primitive inputs but no productized build intent, stop after the handoff and report the expected next step. If the user then asks to continue into build or delivery, route to `design-probe` / `pickup-probe` before planning.
+
+If no ready backlog item exists, route to Builder Kit shape / `idea-to-backlog` instead of inventing implementation work.
+
+Direct pull-work audits that inspect WIP, PRs, sidecars, or board state without selecting new implementation work are valid only when the artifact records `shepherding_item_ids` for the active items being finished or `backlog_gap=true` plus `backlog_gap_route` to `idea-to-backlog`. They must stop at shepherding, cleanup, blocker, or shaping guidance and must not create free-floating implementation scope.
+
+## Pickup Gate
+
+Selected work is ready when:
+
+- `selected_item_ids` records the selected provider/local backlog item refs, or `shepherding_item_ids` records the active PR/sidecar/issue refs being finished before new work, or `backlog_gap=true` records the route to `idea-to-backlog`
+- issue scope is clear
+- acceptance criteria exist
+- dependencies are known
+- selected issue group has explicit bundle justification or is split to one thinnest meaningful slice
+- multi-item selection records independence or bundle justification and expected conflict risks
+- owner/agent path is clear
+- worktree decision is recorded
+- worktree lifecycle is recorded when a worktree is used
+- personal WIP/shepherding scan is recorded
+- global conflicts and dependency impacts are recorded
+- `start_new_work_decision` is `proceed` or an explicit accepted gap allows pickup to continue
+- no higher-priority blocked verification work should be finished first
+- conflict risk with active TODOs is recorded
+
+If the gate fails, update the artifact and stop with the blocker.
+
+After a merge, automatic continuation may inspect the queue and write a new pull-work artifact, but it cannot enter planning or execution for the next work item until a fresh pickup Probe record exists for that newly selected item or justified group.
+
+## Flow Validation Boundary
+
+Flow Agents may need to know whether a Flow Definition referenced by a work item is valid, but Flow owns those semantics. Use one of Flow's published validation surfaces instead of copying checks into this repo:
+
+```bash
+flow validate-definition <path> --json
+```
+
+or, from code that already depends on Flow:
+
+```js
+validateDefinitionWithDiagnostics(definition)
+```
+
+Record the command/API result in the pull-work artifact or evidence sidecar. If Flow is unavailable, mark that readiness subcheck `NOT_VERIFIED` or blocked; do not create a partial validator in Flow Agents.