Should explore defer the implementation hand-off to the project workflow?

[kojifukada]

Context

We agree that openspec-explore should not implement anything while explore mode is active. That boundary works well for us.

The question is what happens next. When a user asks to move from exploration to implementation, the generated skill sends them to the propose workflow as the next step. Not every project uses an OpenSpec change for every normative change. For example, some projects use OpenSpec changes only when the proposed contract needs a lifecycle independent of the implementation PR, and otherwise ship the spec update in the implementation PR. OpenSpec's own CONTRIBUTING also decides per change whether a proposal is needed: a bug fix or small improvement "goes straight to a PR".

For such projects, the explore hand-off can compete with the project's own workflow rule about whether a change is needed.

Design question

Could these two concerns be separated?

1. Explore mode ends before implementation. This is a hard boundary, and we want to keep it.
2. Which workflow comes next is the project's decision.

Conceptually: exit explore → consult the project's workflow / context → decide whether propose is required.

Why context alone may not be enough

Project context in openspec/config.yaml is the supported way to tell agents about project rules, and explore is told to read it. In practice, though, the explore hand-off instruction can be acted on before the project workflow is consulted. In our runs, the agent sometimes skipped the context step entirely. Other times it read the context but still treated propose as the default exit.

Current behavior on OpenSpec 1.14.1

In OpenSpec 1.14.1, the current release at the time of testing, the generated explore skill makes the hand-off to propose explicit. For an implementation request, it says to "point them at /openspec-propose, which turns the discussion into a change. The work happens from that change, never from explore mode." The guardrail and the end-of-discovery prompt reinforce the same hand-off.

We regenerated the skills with 1.14.1 in a project whose context already says to decide, using the project's workflow doc, whether a change is needed before creating one. We then entered explore mode explicitly and asked to go straight to implementation ("the direction is decided, implement this"). Both agents pointed to propose as the only next step without consulting the project workflow:

• Claude Code did not read the context or the workflow doc.
• Codex read only the skill file.

Execution conditions. The runs intentionally prevented file writes, so that only the explore-to-implementation hand-off was observed. Claude Code 2.1.290 ran in plan mode; Codex 0.160.0 ran in a read-only sandbox. Each agent ran once. This is a limited characterization, not a statistical or deterministic claim, and we do not claim that an unrestricted implementation mode behaves the same way. The narrow claim is: the generated hand-off instruction can route to propose before the project workflow is consulted.

What we tried locally

• Our repo-level agent instructions already describe when a change is needed.
• We added a one-sentence routing hint for this transition to the project context.
• We looked at invocation controls. They limit implicit use, but the explicit /openspec-explore path, where this hand-off appears, remains.
• We avoided forking or patching the generated skills, since openspec update owns them.

Our conclusion: context helps when it is read, but it was not a reliable cross-agent gate for this hand-off.

Possible direction

One option, not a fixed proposal:

• keep the hard boundary: explore mode never implements;
• when implementation is requested, exit explore mode;
• then let the project's workflow / context decide what comes next;
• recommend propose when the project's policy calls for it, or when the project defines no such policy. In that case today's behavior is preserved, including the guard against jumping straight to code discussed in /openspec-explore loves to transition to implementation, skipping all the SDD part #1577.

We don't have a view on the exact wording or mechanism.

Questions

1. Is "propose is the next step after explore" an intentional core invariant of the workflow, or a default that could defer to project workflow?
2. If it can defer, should the generated skill leave room for that in the hand-off itself?
3. If project-specific routing is in scope, do you see context as the intended channel? Would you prefer to make the hand-off explicitly consult it?
4. Or would a separate extension point fit better (for example, project-level guidance for explore, similar to operations.<op>.guidance for apply/archive)?

Related

• fix(explore): name the propose workflow at every handoff #1788 — named the propose workflow at every explore hand-off. Opposite direction: it makes propose the fixed exit, and this asks whether that exit can defer to the project.
• /openspec-explore loves to transition to implementation, skipping all the SDD part #1577 (moved from /openspec-explore loves to transition to implementation, skipping all the SDD part #875) — explore jumping straight to implementation. Opposite failure: any change here should keep that guard.
• [Bug] Explore skill doesn't read project context from config.yaml #696 — explore reads the project config.yaml context. Related, but does not solve this hand-off: it informs explore, but does not gate where the hand-off points.
• Custom schemas without proposal are only partially supported #1161 — proposal-first assumptions in workflow surfaces. Same direction, from the schema side; it does not cover the explore hand-off.
• Feedback: Surface operations.propose.guidance at change-creation time… #1763 / feat(config): accept all lifecycle operations in operations (at minimum sync) #1913 — extend operations.<op>.guidance beyond apply/archive. Adjacent: a possible delivery channel; neither covers explore today.