gsd-path-define

Before executing project helpers, read runtime selection and operating rules.

GSD Path Define Phase

Turn a project idea or approved roadmap entry into an approved intent artifact. Run this phase in the main conversation; never delegate its interview or confirmation.

Primary modes: standard (single milestone, below), program (a multi-milestone program — interview into .project/CHARTER.md), and milestone (derive one milestone's INTENT.md from the approved roadmap; no re-interview). Modifiers: brownfield when the track's research/evidence-codebase.md exists, and supplied-spec when the user hands in a PRD, issue, or design doc. Apply every matching modifier on top of the primary mode.

Routing instructions below are caller handoffs under the AGENTS.md handoff rule; never invoke an explicit-only sibling skill yourself.

Before interview work and again before approval, apply the AGENTS.md pending-answer rule with the bundled scripts/discussion_records.py; a follow-up owned by define is resolved in INTENT.md, or the phase blocks.

State ownership

If STATE.md exists, require pipeline_state.py validate --repo <absolute root> [--project-dir .project/next] to pass; otherwise return to $gsd-path for ownership checking. Legal existing-state entry is inspect/done (transition to define/active; milestone mode when ROADMAP.md exists), roadmap/done (transition to define/active, milestone mode), or define/active|blocked. When ROADMAP.md exists, a later milestone or lookahead track at define/active|blocked also requires both current-track inspection artifacts and a Log entry proving inspect/done for the same milestone after its latest activation; otherwise route to inspect. The sole later-phase exception is a blocked build entered through the build recovery contract. Follow its preparation and corrections procedure when the runtime returns mode corrections; keep the existing milestone identity and approval gate. Otherwise define/done or any later phase blocks rather than overwriting approved intent and leaving downstream artifacts stale. When an active router supplies the lookahead track root .project/next/, require its STATE.md to be a regular non-symlink file and evaluate this section against that track's state and paths; see Lookahead mode. If STATE.md is missing, run the bundled python3 <absolute-bundled-script> initialize --repo <absolute-root> --template <absolute-state-template> --require-git helper (scripts/detect_project.py) and follow its returned JSON verdict / route. This is the only no-state boundary; do not run classify first or classify from a directory listing or conversation. Handle route: setup-repository before the write gate: preserve the folder unchanged and return to $gsd-path for repository setup; no state was written. If the command exits nonzero, returns error, or returns wrote_state: false, report the error and block without routing or claiming STATE.md was written.

owned — continue under the existing-state rules above.
orphan — return to $gsd-path for orphaned-state recovery; existing evidence does not prove its pipeline version or phase and must not be reused or overwritten by inference.
brownfield — the helper writes STATE.md at inspect/active; route to $gsd-path-inspect from this returned verdict.
greenfield — require wrote_state: true, then continue with the helper's STATE.md at define/active. Do not create STATE.md yourself.

Enter from inspect/done or roadmap/done only with pipeline_state.py transition: pass the exact expected phase/status/branch/archive values, event definition started, and --set-phase define --set-status active (plus --project-dir .project/next for lookahead). This helper is the only ordinary STATE mutation; direct template writing is limited to the missing-state greenfield initialization above.

The router's verified new-GitHub-repository transaction is the sole greenfield exception: STATE.md already exists at define/active, branch is the approved gsd-path/M001 branch, and .project/REPOSITORY.md contains the fixed-format remote, remote-default SHA, clean default checkout, branch, and primary worktree. Verify that artifact and the current branch/worktree before interviewing. The required classifier returns owned before signal scanning, so the bootstrap README is not a brownfield signal. A missing or mismatched binding returns to $gsd-path; never infer it from STATE log prose or repair it inside define.

Coverage checklist

Obtain a confident answer in every area before finishing:

Problem — what hurts, for whom, and how badly.
Users — who uses this, how many, how technical, and what they use now.
Success — what observable result makes the first release complete.
Scope in — the smallest version that achieves that result.
Scope out — explicit vetoes that downstream phases must not include.
Constraints — stack, deadline, budget, code, integrations, compliance.
Risks — the assumptions and unknowns research must investigate.
Surfaces — what a person opens, sees, or types into to get the result: screens, commands, endpoints. Record them on INTENT.md Surfaces: (none only when nobody touches this work directly), and give every named surface at least one success criterion observable there. A criterion satisfied by a passing test alone does not cover a surface.

Program mode

When the user frames the work as a large multi-milestone program — or the interview reveals scope that cannot ship as one milestone — interview against the charter instead of the single-milestone checklist:

Vision — the program's end state and why it matters.
Full scope in — every capability area the program will deliver.
Vetoes — what no milestone may include.
Constraints — program-level stack, budget, deadline, integrations.
Program success criteria — observable when the last milestone ships.
Review panel — optional durable default (off | detected | named families). Use the configured future preference unless the user chooses otherwise (see Output contract). This value persists on CHARTER.md; later milestone INTENT files copy it and may override.

Read the local charter template, write the approval draft to .project/CHARTER.md including the configured or explicitly chosen Review panel: value, and run the same playback-approval loop as the standard Process. On approval, retain the reviewed Review panel: value on CHARTER.md, run pipeline_state.py transition with expected define/active, milestone/branch/archive all at their exact current values, event program charter approved, and --set-phase define --set-status done; require milestone to remain null. Report that research (program scope) is next. Research, decide, and the roadmap phase slice the program; per-milestone INTENT.md files come later, in milestone mode. Do not write INTENT.md in program mode.

Milestone mode

Legal entry: roadmap/done only for the first milestone after initial roadmap approval, or inspect/done when .project/ROADMAP.md exists. Recovery from define/active|blocked follows the current inspection-evidence requirement in State ownership. There is no re-interview of charter or roadmap scope:

Read the applicable track STATE.md, .project/CHARTER.md, and .project/ROADMAP.md. Select the entry whose slug matches STATE.milestone. Require exactly one match. In ordinary milestone mode, require that entry to be active; in lookahead mode, require it to be pending. A missing, duplicate, or wrong-status match blocks: record the failure in the applicable STATE.md and return to the router. When brownfield, also read the track's research/evidence-codebase.md and research/DOCS-AUDIT.md first.
Draft INTENT.md from the resolved entry: Summary from its Goal, Scope in/out and Success criteria from the entry, Constraints inherited from the charter, Risks and Open questions from the entry (tagged RESEARCH/NEEDS-USER), Lane: milestone, Surfaces: copied verbatim from the entry, and Review panel: copied from CHARTER.md (default the configured preference when CHARTER omits it). The confirmation may override the copied panel value; do not invent detected or a named list. When brownfield, fill ## Current state from the map, record doc-vs-code rulings as in Brownfield mode, and add protected existing behavior under Scope out. Write Ground truth paths from the track root: .project normally, or .project/next in Lookahead mode — never the building milestone's active research/ paths.
Present one confirmation, not an interview: playback the derivation (and brownfield ground truth when present), link the resolved absolute INTENT.md path, and ask approve or adjust. A requested change that contradicts the charter or the resolved roadmap entry is a scope change — this phase never edits the roadmap; surface it to the user for a $gsd-path-roadmap re-slice at the next milestone boundary.
On approval, finalize per the Output contract, setting milestone to the resolved entry's slug. The router continues with milestone-scoped research when the entry lists open questions, otherwise planning.

Lookahead mode

Entered only when an active router supplies the lookahead track root .project/next/ while the active STATE.md is build/active in program flow. Evaluate every state and artifact precondition in this contract against the track — .project/next/STATE.md is the state file and INTENT.md is .project/next/intent/INTENT.md — never against active-path artifacts. This is milestone mode run against the track, with two differences:

Read CHARTER.md and ROADMAP.md from their active .project/ paths, but resolve the milestone only from .project/next/STATE.md as described above; never use the building milestone's active entry and never create or modify any active-path artifact.
Never mark the lookahead milestone's roadmap entry active; the router does that at promotion.

All other milestone-mode rules apply unchanged. Brownfield evidence for this track is .project/next/research/evidence-codebase.md.

Supplied-spec mode

When the user supplies a document at entry — a PRD, issue, or design doc — read it fully before the first question and map it against the coverage checklist. Present what the document settles per checklist area for correction — stated, not asked, exactly like brownfield ground truth — then interview only the gaps and contradictions. Note the source document path in INTENT.md's Summary. A supplied spec composes with brownfield mode: ground truth first, then the spec, then delta questions only.

Brownfield mode

When the track's research/evidence-codebase.md exists (inspect already ran), read it and the matching research/DOCS-AUDIT.md before the first question. The rules change for every primary mode:

Established facts are not questions. Never ask what the stack is or what the code does — the map answers that. State it and let the user correct.
Standard and program interviews cover only deltas: what should change, what must not break, and — standard — the goal of THIS milestone against the code that already exists. Program interviews still use the charter checklist, but skip any area the map already settled.
Milestone mode still does not re-interview; it still collects the rulings below before confirmation.
Work through the mapper's ## Open questions for define and the audit's NEEDS-USER remediation rows — each doc-vs-code conflict gets a ruling (fix-doc, fix-code, or accept-drift) recorded verbatim in INTENT.md and appended to DOCS-AUDIT.md's ## User rulings table. fix-doc and fix-code rows receive planned: no; accept-drift receives planned: n/a (accept-drift). Never leave the durable alignment queue only in INTENT.md. Program mode records those rulings on CHARTER.md Constraints or Corrections and still writes the DOCS-AUDIT.md table.
Existing behavior the user wants preserved is recorded under Scope out as a veto ("do not break X"); accepted fix-code items become scope.
Fill INTENT.md's ## Current state from the codebase map so downstream phases inherit ground truth without re-scanning. Set Ground truth to the track's research/evidence-codebase.md and research/DOCS-AUDIT.md (.project/next/research/ in Lookahead mode). Omit that section for greenfield. Do not add it to CHARTER.md.

Process

Open in this order, then stop for the reply:
- Brownfield (any primary): present the one-screen ground truth from inspect before any question.
- Standard, no brownfield: ask for a one-paragraph idea if missing.
- Program, no brownfield: ask for the program vision if missing.
- Milestone: do not ask for an idea; continue at Milestone mode (ground truth already presented when brownfield).
- Supplied spec: after the opening above, present settled coverage for correction, then interview only its gaps.
- Standard + brownfield: after ground truth, ask what this milestone should achieve against the code that exists.
For standard and program modes, ask small rounds of questions aimed at the weakest checklist areas that the opening did not already settle. Never ask a fact the map, audit, or supplied spec already answered. Use an interactive user-input tool when available. Otherwise ask concise numbered questions in chat and stop for the reply. Keep each round small enough to answer in one reply. When a question offers options, list the recommended one first marked (recommended) with a one-line reason; leave open questions open. Milestone mode skips this step; collect brownfield rulings if brownfield, then use the Milestone mode confirmation.
Surface contradictions immediately and ask the user to choose. Never average incompatible answers.
In standard and program modes, challenge the largest remaining assumption at least once: ask what happens if it is false. Do not challenge a fact the brownfield map already established. Milestone mode skips this step.
Stop when coverage is complete or the user says enough. Record remaining uncertainty under ## Open questions with RESEARCH or NEEDS-USER.
Classify the proposed milestone lane before writing the approval draft. Milestone mode keeps Lane: milestone and skips this classification. Program mode writes CHARTER.md instead of INTENT.md. Otherwise choose quick when scope fits at most two deliverable-sized tasks (project policy) in one wave with no RESEARCH or NEEDS-USER items and no cross-wave integration risk; otherwise standard. Read the local intent template, write that proposed lane and the complete draft to .project/intent/INTENT.md, then ask for approval. Present an Outcome playback of the Summary and proposed lane, a Review Markdown link to the resolved absolute INTENT.md path, and one Next approval question with approve first as (recommended) only when the evidence supports it. Record corrections verbatim under ## Corrections, update the file, and present the new link before asking again. When STATE records a new new-GitHub REPOSITORY.md binding, include its remote, default checkout, GSD Path branch, and primary worktree under ## Constraints. Recompute and write the lane after every correction before relinking the file.

Output contract

At approval, retain the already reviewed Lane: value and its one-line reason. Before presenting an approval draft without a CHARTER or explicit panel choice, read settings.review_panel.value from the selected runtime's path_config.py show --repo <absolute-root> (bundle for legacy projects; off for older selected runtimes without config support). Include that preference in the draft. Retain Review panel: as reviewed: the CHARTER copy, the explicit user choice, or the configured future preference. Quick lane keeps the panel off.

When the active router recorded an intent pre-approval grant and the draft needs no answer from the user, run the router's workflow_run.py preauthorize --kind intent before asking. On complete, present Outcome and Review, say the owner's pre-approval passed this gate, and continue as approved. On blocked, ask as usual.

After approval, finalize .project/intent/INTENT.md and run pipeline_state.py transition with expected define/active, the exact current milestone/branch/archive values, event milestone intent approved, --set-phase define --set-status done --set-milestone <milestone slug>, and --project-dir .project/next in lookahead. Require returned define/done and the exact milestone. Confirm the approved outcome and link INTENT.md again. Use the executable phase handoff in AGENTS.md for the next action.

Rules

Trace every question to a checklist gap; omit curiosity questions.
In brownfield mode, state mapped facts for correction; never re-ask them.
Treat solution-shaped problems as hypotheses and uncover the underlying pain.
Preserve vetoes and corrections verbatim.
Wrap up when every coverage-checklist area is answered or the user signals done, and tag remaining gaps.