Spec: Finder Phase Wayfinder Skill Workflow

User Input

lets jump into spec plan impl and onwards with $delivery-phase. no need to persist this to backlog. lets convert directly to spec this grilling. whenever writing skills please use $writing-great-skills

for latest docs-ingest-phase note that there will already be an existing finder-phase doc page in wiki as im writing it now with theory

Context

Harness needs a workflow entrypoint above requirements and delivery for loose work that is too large for one agent session and still wrapped in fog. The closed grill established a backlog-native model: the project/backlog root is the living map, finder-phase is the Harness phase wrapper, wayfinder remains a lean primitive, and write-backlog owns tracker materialization. This spec defines the shared skill package and distribution behavior needed for generated agents and local Harness agents to use that model consistently.

Affected roles:

• Repository agents deciding how to route vague, oversized work.
• Planning agents shaping fog into grilling, research, prototype, epic, or story work.
• Maintainers distributing shared Devpunks skills through the CLI baseline.

Non-Goals

• Do not create provider backlog tickets during this delivery.
• Do not migrate existing epic or story backlog items.
• Do not make wiki pages the living wayfinder map.
• Do not absorb wayfinder into write-backlog.
• Do not duplicate provider payload rules in finder-phase.
• Do not overwrite or redesign the concurrent finder-phase theory page under project public docs.
• Do not remediate known dp check scaffold drift unless it directly blocks this change.

Acceptance Criteria

• A model-invoked finder-phase shared skill exists and is distributed through Harness skill mirrors.
• A lean wayfinder primitive shared skill exists and is distributed through Harness skill mirrors.
• finder-phase routes loose, oversized, foggy work before requirements-phase and treats the backlog root as the living map.
• finder-phase/SKILL.md stays lean: trigger, core loop, route-selection steps, completion criteria, and reference pointers only.
• finder-phase references use progressive disclosure and noun-named files for Harness-specific depth.
• finder-phase completion produces an updated backlog frontier plus a concise handoff.
• wayfinder owns route selection and can classify next work as fog, grilling, research, prototype, epic, or story without owning provider payloads.
• write-backlog documents the canonical kind taxonomy: fog, grilling, research, prototype, epic, and story.
• Every supported kind is documented as a first-class provider backlog item that is visible, assignable, searchable, linkable, and closeable.
• write-backlog documents provider materialization for Linear, GitHub Projects V2, monday.com, and Azure DevOps using provider-native single-value kind storage where available.
• fog is root-level only, not delivery-eligible, not a SPEC.md anchor, and not an execution container.
• Concrete grilling, research, prototype, epic, and story items live under a module or milestone; stories remain children of epics.
• grilling, research, and prototype closure guidance requires an accepted decision note with answer, direction, artifacts, and created or updated implementation items.
• The planning default pack includes finder-phase and wayfinder.
• Catalog entries make both new skills baseline-visible when the shared skill bundle is synced.
• Root workflow-routing guidance can reference finder-phase for loose, oversized, foggy work before requirements-phase.
• Focused validation proves source skill content, Harness mirrors, catalog/pack wiring, and no whitespace regressions.

Constraints

• Reusable skill edits start in /Users/stefan/Desktop/repos/wearedevpunks-skills.
• Harness mirrors under apps/cli/skills/* and .agents/skills/* are generated or synced copies, not the source of truth.
• writing-great-skills governs all new and changed skill text.
• finder-phase links to write-backlog for backlog materialization instead of repeating provider details.
• Wiki/grill artifacts are evidence; backlog provider state is the intended live operating surface.
• The implementation must preserve existing epic and story delivery semantics.

Technical Notes

• Existing planning pack wiring lives in apps/cli/src/data/catalog/skills.ts and apps/cli/src/data/catalog/packs.ts.
• Shared skills live under /Users/stefan/Desktop/repos/wearedevpunks-skills/skills; current planning skills are under skills/agnostic/planning, and phase wrappers are under skills/phases.
• Existing write-backlog source owns SKILL.md, REFERENCE.md, EXAMPLES.md, assets/concepts/backlog-model.md, assets/concepts/story-shape.md, and provider payload references.
• bun run sync:skills in Harness updates apps/cli/skills from the shared skills repo; active .agents/skills mirrors may need explicit alignment for changed local phase skills.

Decision Log