[Feature Request] - Browser-Based Questionnaire Mode for Discussion Workflows - SDD

[leoreisdias]

First off, congrats on Plannotator! It’s a super interesting and creative project!

Summary

I’d like to propose a new Plannotator mode for structured clarification: a browser-based questionnaire flow that an agent can open whenever it needs focused user input before continuing implementation.

This would be especially useful for spec-driven development, planning, architecture decisions, and other workflows where the agent should pause, ask targeted questions, capture the answers in a structured way, and then continue with better context. It could start as a one-shot questionnaire flow and later evolve into a live adaptive clarification session where follow-up questions are inserted dynamically based on the user’s responses.

Problem

There is currently a gap between:

1. plain-text clarification in chat
2. plan review / annotation workflows
3. native interactive question tools that only exist in some agent environments or only in some modes

A concrete example is the AskUserQuestion tool in Claude Code. That kind of interaction is extremely useful because it lets the agent ask focused, structured questions instead of relying on free-form back-and-forth.

In Codex, there is also a dedicated interactive question tool, but it is only available in Plan mode. Outside of that mode, the agent has to fall back to normal chat questions.

That means there is a real UX gap in workflows where structured clarification matters, but the current session is not in the one specific mode where the native question tool is available.

In practice, this matters a lot for flows like:

• spec-driven development
• requirements clarification before coding
• architecture and design decisions
• risky refactors
• migration planning
• implementation planning with human checkpoints

For these workflows, the ideal interaction is often not “review this plan” and not “annotate this markdown.” It is:

• ask 2-5 targeted questions
• collect answers in a structured format
• return them to the agent
• continue the same workflow with less ambiguity

Why this seems like a good fit for Plannotator

From looking through the project, Plannotator already appears to have most of the runtime shape needed for this kind of feature:

• ephemeral local server flow
• browser-opened interactive UI
• blocking / wait-for-decision flow
• structured output returned to the calling agent/CLI
• existing session and SSE infrastructure for richer interactions

Why this would be useful

This seems especially valuable for structured workflows and frameworks that depend on deliberate questioning before execution.

Examples:

• Things like BMAD, GSD, OpenSpec
• gated plan → review → tasks → implementation workflows
• any human-in-the-loop coding flow where the agent should not silently assume requirements

A browser-based questionnaire mode would give these workflows a better interface for requirement gathering and decision capture than plain chat alone.

It could also provide a more visual and intentional experience than text-only clarification, for example:

• multiple-choice questions
• recommended option highlighting
• short free-text inputs
• boolean toggles
• final confirmation before submission

Proposal

Add a new mode such as questionnaire or clarify that allows an agent to launch a browser session for structured user questions.

Possible CLI shape:

plannotator questionnaire
plannotator questionnaire --schema questions.json
plannotator questionnaire --prompt-file clarify.md

For an MVP, possible browser UX:

• focused questionnaire UI
• support for multiple input types
• recommended option styling
• structured answer export
• agent resumes immediately with the collected answers

Example output:

{
  "answers": {
    "primary_goal": "ship the safest fast version",
    "risk_tolerance": "low",
    "needs_migration": true,
    "preferred_approach": "incremental rollout"
  }
}

MVP suggestion

A simple first version could be a one-shot blocking flow:

1. agent decides it needs clarification
2. plannotator questionnaire opens a browser UI
3. user answers one or more questions
4. answers are submitted
5. CLI returns structured output
6. agent resumes with better context

This already seems very useful, even without live adaptive follow-up questioning.

Possible future direction

If the MVP works well, it could later evolve into a live adaptive clarification session rather than only a one-shot questionnaire.

For example:

• the browser session stays open while the agent is still reasoning
• the agent can inspect each answer as it arrives
• if an answer is ambiguous or opens a new branch, the agent can insert a follow-up question immediately
• the question flow is therefore dynamic, not fixed upfront
• the session closes only when the agent decides enough clarification has been gathered

Example:

1. Agent asks questions 1-5
2. User answers question 2 in a surprising way
3. Before continuing to question 3, the agent inserts a new clarification question
4. The flow becomes 1, 2, 2a, 3, 4, 5

This would make the mode especially useful for spec-driven and requirements-elicitation workflows, where the right next question often depends on the previous answer.

Questions for maintainers

• Does this direction fit the product vision for Plannotator?
• Would you prefer this as:
  • a new standalone mode
  • an extension of annotate mode
  • or part of a more general interaction/session framework?
• Are there architectural constraints in the current CLI/server/UI flow that would make this a poor fit?

Contribution offer

If this direction sounds useful and aligned, I’d be happy to contribute to it.

I’ve been exploring the current architecture and would be glad to work on a scoped MVP, likely starting with the one-shot questionnaire flow and designing it so it can later evolve into a richer multi-turn session if that is desirable.