From 9f3b2425ec5b672f0f4f244c8249e7d7ed52f7b2 Mon Sep 17 00:00:00 2001
From: jpelletier1 <44589723+jpelletier1@users.noreply.github.com>
Date: Fri, 17 Oct 2025 12:35:24 -0400
Subject: [PATCH] Experimental first-time user onboarding microagent (#11413)

---
 microagents/onboarding.md | 87 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 microagents/onboarding.md

diff --git a/microagents/onboarding.md b/microagents/onboarding.md
new file mode 100644
index 0000000000..3e15c78afa
--- /dev/null
+++ b/microagents/onboarding.md
@@ -0,0 +1,87 @@
+---
+name: onboarding_agent
+type: knowledge
+version: 1.0.0
+agent: CodeActAgent
+triggers:
+- /onboard
+---
+
+# 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?”**