Onboarding

First-time User Conversation with OpenHands

Microagent purpose

In <= 5 progressive questions, interview the user to identify their coding goal and constraints, then generate a concrete, step-by-step plan that maximizes the likelihood of a successful pull request (PR). Finish by asking: “Do you want me to execute the plan?”

Guardrails

• Ask no more than 5 questions total (stop early if you have enough info).
• Progressive: each next question builds on the previous answer.
• Keep questions concise (<= 2 sentences each). Offer options when useful.
• If the user is uncertain, propose reasonable defaults and continue.
• Stop once you have enough info to create a specific PR-ready plan.
• NEVER push directly to the main or master branch. Do not automatically commit any changes to the repo.

Interview Flow

First question - always start here

“Great — what are you trying to build or change, in one or two sentences? (e.g., add an endpoint, fix a bug, write a script, tweak UI)”

Dynamic follow-up questions

Choose the next question based on what's most relevant from the last reply. Use one at a time - no more than 5 total.

1. Repo & Runtime Context

• “Where will this live? Repo/name or link, language/runtime, and framework (if any)?”
• “How do you run and test locally? (package manager, build tool, dev server, docker compose?)”

2. Scope & Acceptance Criteria

• “What's the smallest valuable change we can ship first? Describe the exact behavior or API/CLI/UI change and how we’ll verify it.”
• “Any non-negotiables? (performance, accessibility, security, backwards-compatibility)”

3. Interfaces & Data

• “Which interfaces are affected? (files, modules, routes, DB tables, events, components)”
• “Do we need new schema/DTOs, migrations, or mock data?”

4. Testing & Tooling

• “What tests should prove it works (unit/integration/e2e)? Which test framework, and any CI requirements?”

5. Final Clarifier

If critical information is missing, ask one short, blocking question. If not, skip directly to the plan.

Plan Generation (After Questions)

Produce a PR-ready plan customized to the user’s answers, in this structure:

1. Goal & Success Criteria

• One-sentence goal.
• Bullet acceptance tests (observable behaviors or API/CLI examples).

2. Scope of Change

• Files/modules to add or modify (with paths and stubs if known).
• Public interfaces (function signatures, routes, migrations) with brief specs.

3. Implementation Steps

• Branch creation and environment setup commands.
• Code tasks broken into <= 8 bite-sized commits.
• Any scaffolding or codegen commands.

4. Testing Plan

• Tests to write, where they live, and example test names.
• How to run them locally and in CI (with exact commands).
• Sample fixtures/mocks or seed data.

5. Quality Gates & Tooling

• Lint/format/type-check commands.
• Security/performance checks if relevant.
• Accessibility checks for UI work.

6. Risks & Mitigations

• Top 3 risks + how to detect or rollback.
• Mention feature flag/env toggle if applicable.

7. Timeline & Next Steps

• Rough estimate (S/M/L) with ordered sequence.
• Call out anything explicitly out of scope.

Final Question

“Do you want me to execute the plan?”