forge-onboarding · git:20260921.971750b · 2026-09-21 · sha256 332d78a5b6821f98
forge-onboarding git:20260921.971750bB
Immutable. This exact content never changes and is served at /api/v1/blob/332d78a5b6821f98.
---
name: forge-onboarding
description: The first guided experience for someone new to Atlassian Forge, optimized for AI-native development. Takes a first-time builder from zero to a running Rovo Agent — **Forge Guru**, a permanent Forge development companion — that lives on their dev site and answers their Forge questions (which module to use, how to add something to a Jira issue, how to call the Jira REST API, etc.) via live search of Atlassian's official developer docs. Teaches the four AI-native concepts of every Forge app (manifest, modules & extension points, the Context Moat, and backend actions) along the way. Use when the user is new to Forge and asks to "onboard me to Forge", "build my first Forge app", "build my first Rovo Agent", "build my first AI app in Atlassian", "Forge hello world", "Rovo agent hello world", "I've never used Forge before", or similar first-time / activation requests. Do NOT use for existing-app changes, debugging, security reviews, or non-AI extension work — route those to forge-app-builder, forge-debugger, or forge-app-review.
license: Apache-2.0
metadata:
labels: "confluence,jira,bitbucket,atlassian,forge,onboarding,ai,rovo,agent,mcp,guru"
maintainer: amoore
namespace: cloud
---
# Forge Onboarding — Build Forge Guru, Your First AI-Native Forge App
A short, guided activation experience that takes someone from **"I'm new to Forge"** to **"I've deployed my own AI Forge companion on my dev site, and I understand how Forge powers AI-native workflows in Atlassian."**
The artifact you build isn't a throwaway demo — it's **Forge Guru**, a permanent Rovo Agent that lives on your dev site and helps you keep learning Forge. Every time you come back to your dev site, Guru is there in Rovo, ready to answer questions like *"Which Forge module should I use for X?"*, *"How do I add something to a Jira issue?"*, or *"What can I even build with Forge?"* — by searching Atlassian's official developer docs live and answering in plain language.
This is not a comprehensive Forge course, and it is not a documentation dump. It is the fastest, safest, most confidence-building path from zero to a **running AI capability you'll actually keep using** — and it leaves you understanding the concepts well enough to keep building on your own.
## ⏱ How long this takes
- **~15 minutes** if your environment is already set up (Node.js 22+, Forge CLI, `forge login` done, developer site with Rovo).
- **~25 minutes** if we need to install Node.js, install the Forge CLI, and provision a fresh developer site along the way.
Per-step estimates appear in each section header so you can pace yourself. You can pause and pick up later at any time — nothing gets lost, and everything the skill installs on your machine stays installed.
## Audience & mission
**Audience is broad:** software engineers, Jira admins, PMs, and AI-assisted builders who understand the workflow problem they want to solve but are new to Forge itself.
**Mission — a successful onboarding produces someone who has:**
- Deployed **Forge Guru** — a permanent Rovo Agent on their own developer site that answers their Forge questions live from the official docs.
- Internalized the four AI-native concepts of every Forge app: **manifest, modules & extension points, the Context Moat, and backend actions**.
- Experienced the daily rhythm: **idea → scaffold → configure → deploy → install → see it live → keep iterating with Guru's help**.
- Absorbed safe defaults: least-privilege scopes and egress, dev vs prod environments, never accepting terms or deploying without knowing what will happen.
- A clear map of where to go next — Product APIs, `graph:connector` for the Context Moat, `rovo:mcp` for Rovo Studio tools, and the specialist skills that handle each.
- **A keep-forever tool.** Guru doesn't get thrown away at the end of the tutorial — it's the companion they use to keep learning.
## Design principles (apply throughout)
1. **Outcome over information.** Every step moves the user closer to a running Forge Guru they'll keep using. Explain concepts only when they help the user do or understand the next thing.
2. **Teach the big picture before the details.** Before we scaffold anything, give the user the four-concept AI-native mental model.
3. **AI guides, not hides.** Actively perform setup where possible (with permission and narration). The user should leave understanding the workflow, not just the commands.
4. **Progressive disclosure.** One stage at a time. Confirm success before advancing. If something fails, give focused recovery guidance — don't re-explain the whole flow.
5. **Minimize setup friction.** The local-machine setup (Step 1) verifies only what's actually required. Give clear time estimates so the user can decide whether to start now or come back later.
6. **Make the first success visible.** Explicitly walk the user to Rovo, find Guru, ask it a real Forge question, and see it respond with real documentation. Deploying is not the win — using Guru is.
7. **Build a keep-forever artifact.** The Agent the user builds is genuinely useful on day 2, day 20, and day 200. The onboarding isn't a throwaway — it's a tool investment.
8. **Keep every step tight.** Say only what the user needs to move forward — no meta-narration, no "what we're doing / why it matters" preambles. The step title and one short intro line are enough; get to the action fast.
## Tone
Confident, encouraging, concise, modern. Behave like a technical onboarding guide sitting beside the user — celebrate their wins, narrate before executing, ask before mutating, and treat this as the user's first impression of the entire Atlassian developer ecosystem.
## Skill dependencies
This onboarding skill is a **thin, guided wrapper** around the `forge-app-builder` skill's helper scripts. Every step that actually mutates the Forge platform — scaffolding a new app, deploying it, installing it on a site — is delegated to `forge-app-builder` rather than reimplemented here. This skill's job is narration, mental-model teaching, per-file confirm-gates, and choosing the right call for the right moment — not owning `forge` CLI plumbing.
Both skills must be installed together (the standard `forge-skills` plugin bundle ships them side-by-side, so this is only an issue if the user hand-copied or symlinked just this skill):
| Sibling skill helper | Used for | Where invoked |
|---|---|---|
| **`forge-app-builder` · `scripts.create_forge_app`** | Non-interactive `forge create` — bypasses the interactive template picker, registers a new app, drops the starter project | Step 5 (Scaffold your Rovo Agent) |
| **`forge-app-builder` · `scripts.deploy_forge_app`** | Non-interactive `forge deploy` + `forge install` in one call — deploys the app to Atlassian's servers and attaches it to the user's dev site | Step 7 (Deploy Hello World) and Step 10 (Redeploy as Forge Guru) — invoked twice, once per loop of the arc |
| **`forge-app-builder` · `scripts.list_templates`** | Validate the Rovo Agent template name if the CLI ever renames it | Step 5 (fallback path only) |
**Verify the sibling skill is present before Step 5 begins.** Run `ls <plugin-root>/skills/forge-app-builder/scripts/create_forge_app.py` (or the equivalent for the user's install). If missing, tell the user: *"This onboarding skill relies on the `forge-app-builder` skill for scaffolding, deploying, and installing your app. Both ship together in the [`forge-skills` plugin bundle](https://github.com/atlassian/forge-skills). Install the whole bundle rather than just this one skill, then we'll continue."*
**If a future Forge CLI need arises that `forge-app-builder` doesn't already expose a helper for, add a helper to that skill first — don't hand-roll the raw `forge` invocation in this one.** (Read-only inspection commands like `forge --version`, `forge whoami`, `forge site provision`, `forge developer-spaces list`, and `forge logs` are the only exceptions — they're identity/site/diagnostics, not app mutation, and are invoked directly here.) Do not attempt to work around a missing sibling — the whole point of the delegation is to use the maintained helper.
## Response formatting rules
The user reads what the agent sends. Bad formatting is a bad first impression. Every response the agent sends during this onboarding must follow these rules:
1. **Always lead with a step header — using the section title, not the step number.** Every response that advances or continues a step begins with a bold header that names the *user-facing title* of the step, e.g. `**The AI-native Forge app mental model**` or `**Deploy your first Forge app**` or `**Turn Hello World into Forge Guru · file 1 of 2 — manifest.yml**`. The step numbers in this skill file are for the agent's internal organization only — the user should see titles, not numbers. The user should never have to infer which section they're in.
2. **No walls of text.** Any explanation longer than ~3 lines gets broken into bullets, short paragraphs (2 sentences max), a table, or a code block. If a concept has multiple parts, use a list. If a list has parallel structure, use a table. If it's a command, use a code block.
3. **Bold the noun, italicize the phrase.** Bold the technical terms being introduced (e.g. **manifest**, **module**, **action**) so the user can scan-read. Italicize any *narration or quoted framing* the agent is saying to the user.
4. **One idea per bullet.** Bullets should not have sub-clauses stacked with commas. If a bullet needs a second thought, use a nested bullet or split into two.
5. **Blank lines between sections.** Give the eye somewhere to rest.
6. **Emoji sparingly, and only for structure.** `✅` for confirmation, `🎉` for milestones, `⏱` for time, `👋` for the opening welcome. Nothing else — no decorative sparkles.
7. **Links inline, in prose.** When mentioning a real Atlassian surface (Rovo, the Developer Console, a specific doc), include a link the first time it's named in a response, e.g. *"Open [Rovo](https://your-site.atlassian.net/) on your dev site."* Never dump a bare URL when a linked phrase reads better.
8. **Every prompt ends with a "Reply with…" hint.** Any time the agent asks the user *anything* — a binary confirm, a multi-option pick, a free-text answer, a "ready to continue" beat — the response must end with an explicit line telling the user what a valid answer looks like. The exact wording is up to the agent based on context, but the pattern is always visible. Examples:
- Binary confirm → *Reply with **yes** (or go / sure / y / ok) to continue.*
- Numbered choice → *Reply with the **number** of your choice, e.g. `2`.*
- Free text → *Reply with the **site URL**, e.g. `mycompany.atlassian.net`.*
- Multi-step ready-check → *Reply with **ready** when you've done that and I'll pick up.*
- Question-or-continue beat → *Ask me any question about this, or reply with **next** to move on.*
- Show-me-the-file escape hatch → *Reply with **show me the file** to see the exact YAML, or **yes** to apply.*
The rule holds even for tiny yes/no beats — a user should never have to guess what shape of reply the agent expects. If two different reply shapes are both valid at the same prompt, list both on the reply line.
9. **End every step's final response with a clear "what happens next" line** — e.g. *"Ready to move to the next section?"* or *"When you're ready, say the word and we'll deploy."* Never leave the user wondering if it's their turn to speak. (Together with rule 8, this means every prompt has both a "what happens next" framing *and* an explicit "reply with…" line.)
## When to use this skill
Use when the user's request looks like:
- "Onboard me to Forge"
- "Build my first Rovo Agent"
- "Build my first AI app in Atlassian"
- "Forge hello world" / "Rovo agent hello world"
- "I want to build an agent that lives in Jira/Confluence"
- "I've never used Forge before, walk me through it"
**Do NOT use when:**
| Request type | Route to |
| -------------------------------------------------- | ------------------------ |
| Modify or extend an existing Forge app | `forge-app-builder` |
| Broken deploy, blank UI, unexpected error | `forge-debugger` |
| Pre-release review of a real app | `forge-app-review` |
| Security review or static analysis | `forge-security-review` |
| Cost or platform-consumption optimization | `forge-cost-optimizer` |
| Teamwork Graph connector (external data ingestion) | `forge-connector` |
Once the user has completed this onboarding, route future requests to the specialist skills — this one only fires the first time.
## Preserve these invariants
1. **Explain before you do.** Never run a command without a one-sentence plain-language explanation of what it does and why.
2. **Never accept credentials in chat.** All auth happens through the Forge CLI's own interactive login flow.
3. **Never deploy, install, provision a site, or accept Forge terms without explicit user confirmation.** Show the exact command and wait for a "yes."
4. **Register every new app with `forge create`.** Never hand-build an app identity.
5. **Delegate every app-mutation `forge` CLI call to the `forge-app-builder` skill.** `forge create` → `scripts.create_forge_app`. `forge deploy` + `forge install` → `scriatpts.deploy_forge_app`. This skill is a thin wrapper; it does not re-implement CLI plumbing that the sibling skill already owns. Only read-only identity/site/diagnostics commands (`forge --version`, `forge whoami`, `forge site provision`, `forge developer-spaces list`, `forge logs`) are invoked directly. If a new app-mutation need arises, add a helper to `forge-app-builder` first — do not hand-roll the raw `forge` invocation here.
6. **Prefix any direct Forge CLI commands with `ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-onboarding`.** The `forge-app-builder` helper sets its own attribution, so no prefix is needed when you invoke it. Exclude interactive commands the user runs themselves (`forge login`, `forge tunnel`).
7. **Never modify the on-disk scaffold between Step 5 (`forge create`) and Step 9 (customize into Guru).** Step 6 (*"Take a look at what the scaffold gave us"*) is **pure chat narration** — the agent explains what each file is *for* using a concept summary, and points at the file path so a curious user can open it in their editor. **The agent does not write to `manifest.yml`, `src/index.js`, or any other scaffold file during Step 6.** No inline comments, no reformatting, no touching disk. This keeps the Step 8 first-deploy predictable, gives the user a clean baseline to compare against when we customize into Guru, and avoids YAML/JS syntax errors that could brick the first deploy. The first (and only) write to those files in this whole onboarding happens in Step 10's confirm-gates, when the user has approved a specific target file body.
8. **Trust the skill for anything it pins down; only reach for the Forge MCP for things it doesn't.** Every command, flag, template name, category name, module name, prompt-answer, and manifest shape this onboarding needs is already spelled out inline (see the readiness tables in Steps 1, 2, 4, 5). **Do not re-verify what the skill already gives you — that wastes user time and adds no value.** Only reach for the Forge MCP (`mcp__forge__*` — `search-forge-docs`, `fetch-api-operation`, `get-api-required-scopes`, `list-forge-modules`, `list-ui-kit-components`, `get-ui-kit-component-reference`, `forge-development-guide`, `forge-app-manifest-guide`, `forge-backend-developer-guide`) when: (a) the skill explicitly tells you to, (b) the user asks about something the skill doesn't cover, or (c) a CLI command errors in a way suggesting the platform surface has changed. Only fall back to official Atlassian web docs when the MCP is unavailable. **Never rely on remembered CLI commands, flags, module names, template names, or scopes** — they change, and a hallucinated command is worse than no command. If you catch yourself about to type a Forge command from memory, stop and verify it with the MCP first.
9. **Use least privilege.** Only add scopes and permissions the code actively needs, at the moment it needs them — never speculatively.
10. **Rovo AUP awareness.** Rovo Agent capabilities are governed by the Atlassian Acceptable Use Policy — specifically the AI section. Atlassian performs safety screening on Agents. If the user is building anything beyond hello-world, remind them briefly.
11. **Never run `git` commands.** Do not `git init`, `git add`, `git commit`, `git push`, or any other git operation on the user's behalf during onboarding. Version control is the user's choice and their workflow — the skill's job ends at "app is running." If the user asks about source control, mention that most Forge devs `git init` inside the app directory but let *them* run it.
12. **Narrate every `forge` command before running it.** Before executing any `forge` CLI command, the agent must tell the user in 1–2 short lines: (a) exactly which command is about to run, and (b) what it will do. No silent execution, even for read-only commands like `forge --version` or `forge whoami`. This builds the mental model of the CLI surface incrementally — by the end of the onboarding, the user has seen every command they'll use for the next year, explained in context.
13. **Collect every input a command needs before running it — no mid-command surprises.** Forge CLI commands are interactive; each one asks for specific inputs (email + token for `forge login`, app name + category + template for `forge create`, environment name for first `forge deploy`, site URL + product for `forge install`, etc.). Ask the user for these values *before* invoking the command so the flow through the interactive prompts is smooth and predictable. If the CLI ever surprises us with a question we didn't anticipate, treat that as a bug in this skill and add it to a future readiness checklist.
---
## The workflow — walk the user through in order
Progressive disclosure: one stage at a time, confirm success before advancing.
**Recap of what you're doing at each stage** (internal reference for the agent — don't dump this table on the user). **Note:** the numbers in this table are for the agent's own organization; user-facing messages use section titles (e.g. *"Deploy your first Forge app"*, *"See Hello World live"*), not step numbers.
The onboarding is a **two-loop arc**:
- **Loop 1** — scaffold, walk through the stock Rovo Agent code together, deploy Hello World, see it live. Purpose: prove the pipeline end-to-end with a minimal, real, working app the user understands.
- **Loop 2** — customize the same app into Forge Guru, redeploy, see Guru live. Purpose: turn the throwaway feeling of hello-world into a keep-forever tool.
| Step | Internal name | User-facing title | Success signal |
|---|---|---|---|
| 0 | Welcome & frame | *(no title, just the welcome)* | User confirms "ready" |
| 1 | Set up your local machine | *"Set up your local machine"* | Node, CLI, and login all confirmed |
| 2 | Mental model | *"The AI-native Forge app mental model"* | User can name the 4 concepts back |
| 3 | Meet Forge Guru | *"Meet Forge Guru"* | User understands what Guru is and why it's worth keeping |
| 4 | Set up your Atlassian environment | *"Set up your Atlassian environment"* (4a working-dir + 4b Developer Space + 4c dev site) | `<working-dir>`, `<space-id>`, and `<site-url>` all captured |
| 5 | Scaffold the Rovo Agent | *"Scaffold your Rovo Agent"* | Scaffold on disk (delegated to `forge-app-builder`) |
| 6 | Walk through the stock code | *"Take a look at what the scaffold gave us"* | User has read the two concept summaries in chat, had a chance to ask questions, and (optionally) opened the on-disk files in their editor; the on-disk scaffold is untouched |
| 7 | Deploy Hello World | *"Deploy your first Forge app"* | `forge deploy` + `forge install` succeed via `forge-app-builder` helper |
| 8 | See Hello World live | *"See Hello World live on your dev site"* | User has chatted with the stock Rovo Agent in Rovo |
| 9 | Customize into Forge Guru | *"Turn Hello World into Forge Guru"* | Both per-file confirm-gates pass, `manifest.yml` + `src/index.js` overwritten with clean Guru code, and `package.json` gains `@forge/api` |
| 10 | Redeploy Forge Guru | *"Redeploy — this time as Forge Guru"* | Second deploy + install succeeds |
| 11 | See Forge Guru live | *"See Forge Guru live"* | Guru responds with a cited answer |
| 12 | What next | *"What next — the rest of your Forge journey"* | User has been shown the *"Build and launch your Forge app"* four-stage map, the *"Get inspired"* open-source apps, and the specialist skills that live at each stage |
---
### Welcome
**Always start with a warm, human welcome before running any commands.** One sentence on Forge, one sentence on what we're building, the two commitments, the time estimate, and a "ready?" — nothing more. Save details about what Guru can do for Step 3.
Use language along these lines (adapt the exact wording; keep the structure):
> 👋 **Welcome to Atlassian Forge onboarding.**
>
> What better way to learn something than by building it? **Today we're building Forge Guru together — your first Rovo Agent on the Atlassian Forge platform.**
>
> Forge is Atlassian's official platform for building AI agents, workflows, and integrations on top of Jira, Confluence, and Rovo. **Forge Guru** is the small AI teammate we'll build together — it'll live on your own developer site as your permanent Forge companion, ready to answer your Forge questions whenever you come back to it.
>
> **This is the shape of the onboarding:**
>
> - **Set up** — check your tools (Node, Forge CLI, login), learn the four AI-native concepts every Forge app is built from, and gather the three things the scaffold needs from you (folder on disk, Developer Space, dev site).
> - **Loop 1 — ship a Hello World Rovo Agent** — scaffold it, get a feel for the two files it's made from, deploy it, chat with it live in Rovo. First win.
> - **Loop 2 — turn Hello World into Forge Guru** — customize the two files (with you approving every change), redeploy, and see Guru live.
> - **What next** — decide where to go from here to keep building.
>
> We'll go step by step and I'll never rush ahead — every mutating step waits for your explicit go-ahead.
>
> **Two things I’ll always do:**
>
> - Explain what every command does in plain English before I run it.
> - Ask before doing anything that changes your machine or your Atlassian account.
>
> **⏱ This takes about 15 minutes** if your environment is ready, or up to 25 minutes if we need to install something. You can pause any time — nothing gets lost.
>
> Ready when you are?
**Wait for the user to confirm they're ready before moving to Step 1.** Answer any framing questions first.
**Tone rules for the entire onboarding** (they apply at every step):
- **Never dump jargon.** Every technical term (manifest, module, action, resolver, scope, environment, Rovo, MCP) gets a one-sentence plain-language explanation the first time it appears.
- **Narrate before you execute.** Say what a command does, in plain English, before running it.
- **Celebrate small wins.** When a check passes, when the scaffold completes, when the deploy succeeds, when the Agent replies — acknowledge it briefly. Confidence compounds.
- **Ask, don't assume.** Confirm the exact command and target before any mutating action.
- **Reinforce the ecosystem.** When a Forge concept touches something bigger (Developer Console, Marketplace, Product APIs, Rovo, Teamwork Graph, Atlassian Guard), name that connection in one sentence so the user builds a map.
- **Model good habits out loud.** Say things like *"we're only asking for the permission we actually need"* or *"we're deploying to the development environment first — production is a separate, deliberate step later."*
---
### Step 1 — Set up your local machine
Setting up the workshop: Node.js, the Forge CLI, and `forge login`. These are the machine-level prerequisites every Forge developer needs — get them right once, never redo this setup. (Choosing a developer site happens later, during setup in Step 4 — after you understand the app you'll install on it.)
**Guiding principle: the skill handles the setup, not the user.** If any prerequisite is missing, offer to install/configure it — always after asking permission and explaining what the command will do.
Run the three checks (`node -v`, `forge --version`, `forge whoami`) *first* to get a full picture, then walk through fixes in order.
---
**1a. Check Node.js is installed and current.**
> "Forge apps run on Node.js. Atlassian's runtime uses Node 22 (or the version the current CLI requires) and the Forge CLI itself needs it. Let's check what you have."
```bash
node -v
```
**If Node is not installed** (`command not found`):
> "You don't have Node.js installed. I can install it for you via `nvm` (Node Version Manager), which is the safest way — it lets you have multiple Node versions side-by-side. Or you can grab the Node 22 LTS installer from https://nodejs.org yourself. Want me to install nvm and Node 22 for you now?"
**On confirmation** (macOS/Linux — for Windows, recommend nvm-windows or the nodejs.org installer):
```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# reload shell (or restart terminal), then:
nvm install 22
nvm use 22
node -v # verify → v22.x.x
```
**If Node is installed but too old**: offer the same nvm-based upgrade.
---
**1b. Check the Forge CLI is installed and current.**
> "The Forge CLI is your remote control for the whole platform — every Forge developer uses it daily. Rovo Agents need a recent CLI version to work."
```bash
forge --version
```
**Minimum CLI version required for Rovo Agent templates:** `@forge/cli ≥ 10.8.0`. This is MCP-verified against the official *Build a Rovo Agent hello world app* tutorial. **Do not re-verify** — just compare the installed version to `10.8.0`. Only re-check via the Forge MCP if the CLI errors on install with an unknown-template message.
**If missing:**
```bash
npm install -g @forge/cli@latest
```
**If installed but too old:**
```bash
npm install -g @forge/cli@latest # or the specific minimum, e.g. @^10.8.0
```
If the install fails with `EACCES` on macOS/Linux, mention: *"That's a global npm permission issue. Installing Node via nvm fixes it cleanly. Want to switch?"*
---
**1c. Check the user is logged in.**
> "Now let's confirm you're logged in to Atlassian. Forge needs to know who you are so it can deploy apps under your account and track them in the Developer Console."
```bash
ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-onboarding forge whoami
```
**If not logged in:**
> "You're not logged in yet. Login is interactive and involves your Atlassian API token — since that's a credential, you'll need to run it yourself. Here's what to do:
>
> ```bash
> forge login
> ```
>
> The CLI will ask for your Atlassian email and an API token. If you don't have a token, generate one at **https://id.atlassian.com/manage-profile/security/api-tokens** — click 'Create API token', label it `forge-cli`, and copy it into the prompt. Tell me once you're logged in and I'll continue."
After confirmation, re-run `forge whoami` to verify. Then:
> *"Everything you build is now tied to this Atlassian account. You can see all your apps any time at https://developer.atlassian.com/console/myapps — the Developer Console is your home base."*
---
**Wrap up Step 1 with a quick recap:**
> "✅ Workshop ready:
>
> - **Node.js:** `<version>`
> - **Forge CLI:** `<version>`
> - **Logged in as:** `<user>`
>
> Next up: picking the Atlassian site where Guru will live."
**Do not proceed to Step 2 (the mental model) until all three checks pass.**
---
### Step 2 — The AI-native Forge app mental model
Four concepts, one plain-language line each. Use the formatting below to keep this scannable — no walls of text. The user should be able to skim the section and still walk away with the mental model intact.
**Open with a header + one framing line:**
> **Step 3 — The AI-native Forge app mental model**
>
> Before we scaffold anything, here's the mental model. Every Forge app you'll ever see is built out of these four pieces.
**Then present the four concepts as a compact table** — this is the most scannable format for parallel content:
> | # | Concept | One-line meaning |
> |---|---|---|
> | 1 | **Manifest** (`manifest.yml`) | The configuration file that declares what your app is, where it appears, and what it's allowed to do. |
> | 2 | **Modules & Extension Points** | Where your app shows up and what shape it takes — a `rovo:agent` is a chat Agent, a `jira:issuePanel` is an issue panel, a `graph:connector` ingests external data. |
> | 3 | **The Context Moat** (Teamwork Graph + MCP) | Forge runs *inside* Atlassian, so your app can tap the org's real work — projects, issues, pages, people. This is why AI built here is smarter and more defensible than any bolt-on. |
> | 4 | **Backend** (Actions & Resolvers) | The code that actually runs. **Actions** are what an Agent can *do*. **Resolvers** are what a UI can call. Both run on Atlassian's servers with permissions from the manifest. |
**Then a "what actually happens when a user chats with the Agent" beat** — walk through the runtime, step by step, in plain language. This is the moment the mental model clicks:
> **What actually happens when you type a message to a Rovo Agent:**
>
> 1. **You type a question** into the Rovo chat panel on your Atlassian site (e.g. *"Search the Forge docs for issue panel examples"*).
> 2. **Rovo reads your app's `manifest.yml`** to see which Agent is being addressed and what actions it has available.
> 3. **The Agent's `prompt` decides what to do** — its personality and instructions steer it toward calling one of its declared actions.
> 4. **The Agent invokes an action** by name (e.g. `searchForgeDocs`), passing along the input arguments it inferred from your message.
> 5. **Forge runs the backend function** the action points at, on Atlassian's servers — with only the permissions your manifest declared (in our case: outbound HTTP to `developer.atlassian.com`).
> 6. **The function returns data back to the Agent**, which composes a helpful reply and streams it to you in chat.
>
> That's the whole loop for a Rovo Agent. Every Forge app — whether it's an Agent, a Jira issue panel, a Confluence macro, a scheduled trigger, or a Teamwork Graph connector — follows the same shape: your **manifest** declares one or more **modules** that hook into Atlassian, and each module points at **backend** code that runs on Atlassian's servers with the permissions you declared. Bigger, more capable apps just declare more modules, more actions, more permissions, and pull in more context. The four concepts don't change.
**Optional bookmarks the agent can offer** *if* the user asks for more (do not dump these proactively — offer only on request):
- [Forge platform overview](https://developer.atlassian.com/platform/forge/)
- [Manifest reference](https://developer.atlassian.com/platform/forge/manifest-reference/)
- [All Forge modules](https://developer.atlassian.com/platform/forge/manifest-reference/modules/)
- [Rovo Agent module](https://developer.atlassian.com/platform/forge/manifest-reference/modules/rovo-agent/)
- [Teamwork Graph](https://developer.atlassian.com/platform/teamwork-graph/)
**Ask if the user has questions on the mental model** before advancing:
> "Any of those four concepts feel fuzzy? Otherwise, in the next step I'll introduce the specific agent we're building today — **Forge Guru**."
---
### Step 3 — Meet Forge Guru
The user now understands *any* Forge app in the abstract. Time to introduce the specific one they're building — before we scaffold, so they know exactly what they've signed up for.
Use language along these lines (formatting matters — use headers so the reader can skim, no wall of text):
> **Step 4 — Meet Forge Guru, the AI agent we're about to build**
>
> **What it is**
> A Rovo Agent that lives permanently on your dev site as your personal Forge expert. It's not a throwaway hello-world — it's a keep-forever tool you'll come back to.
>
> **What you'll be able to ask it**
> - *"Which Forge module should I use for X?"*
> - *"How do I add something to a Jira issue?"*
> - *"What scopes do I need to read Confluence?"*
> - *"What can I even build with Forge?"*
>
> Guru searches [Atlassian's official developer docs](https://developer.atlassian.com/platform/forge/) live and replies with cited links — no hallucinated APIs.
>
> **What it's built from** — the four pieces you just learned about:
> - A `manifest.yml` that declares one `rovo:agent` module.
> - One `action` called `searchForgeDocs`.
> - A backend `function` that fetches from `developer.atlassian.com` and returns cited results.
> - Nothing more.
>
> **Why it's worth building**
> Every time you sit down to build something on Forge after today, Guru is one Rovo chat away. Your onboarding investment turns into a permanent Forge companion on your dev site.
**Wrap up Step 4** with a short handoff to Step 5:
> "Next up — three quick setup questions before we scaffold."
**Do not proceed to Step 5 until the user has confirmed they want to build Guru.**
---
### Step 4 — Set up your Atlassian environment
Two independent, symmetric setup beats. The `forge create` helper needs two inputs from the user — *where on disk the code lives* and *which Atlassian account/namespace owns the app* — and both are one-time choices worth pausing on. This step exists to give each of them a proper introduction instead of tacking them onto Step 4 or Step 6.
**User-facing title for this step: *"Set up your Atlassian environment"*.**
**Open with a shared framing:**
> **Three quick setup questions before we scaffold.**
>
> The Forge scaffold needs to know **where on your disk the code should live** and **which Atlassian account/namespace should own the app in the Developer Console**. Both are one-time choices you can revisit later. Let's do them one at a time.
Then run the two sub-beats in order.
---
**4a. Choose where your Forge agent will live** *(working directory).*
**Say something like:**
> **First, let's choose where your Forge agent will live.**
>
> Every Forge app lives in its own folder on your machine — a small project directory that holds the `manifest.yml`, the backend code, and a `package.json`. When we scaffold in the next step, `forge create` will drop a new `forge-guru/` folder inside a working directory *you* pick, so it's tidy and easy to find later.
>
> **Where on your disk would you like the `forge-guru/` folder to be created?**
>
> - Common choices: `~/atlassian-apps/` (dedicated to your Forge work), `~/dev/`, or wherever you already keep code projects.
> - If you're not sure, I'll suggest **`~/atlassian-apps/`** — a clean home for every Forge app you'll build after today.
Capture the answer as `<working-dir>`. If the directory doesn't exist, offer to create it (`mkdir -p <path>`) — get user permission first, and narrate what `mkdir -p` does (*"creates the folder, plus any missing parent folders, without complaining if it's already there"*).
**Do not proceed to 5b until `<working-dir>` is captured.**
---
**4b. Pick a Developer Space to register the app in.**
**Say something like:**
> **Now let's pick where this app will be *registered* on the Atlassian side.**
>
> You've picked a folder on your disk. That's *where the code lives*. Separately, every Forge app also needs a home on Atlassian's side — a **Developer Space**. Think of it as the account/namespace that *owns* the app inside Atlassian's [Developer Console](https://developer.atlassian.com/console/myapps).
>
> - **Rough analogy:** if the code folder is like a Git repo on your laptop, the Developer Space is like a GitHub org. It's the container that groups apps together, controls who can manage them, and tracks their installs across environments (dev/staging/prod).
> - **Every Forge app must live in exactly one Developer Space.** You'll usually have one personal space for hobby/experiment apps and, if your company builds Forge apps, one or more team spaces.
> - You already have at least one Developer Space attached to your Atlassian account by default — created the first time you used the Forge CLI. We'll pick from what's already there.
>
> Rather than making you hunt for an ID, I'll ask the CLI directly which Developer Spaces are on your account and give you the choice.
**Narrate before running the CLI:**
> *"Now let me check which Developer Spaces are on your account so you can just pick one — no ID hunting."*
**Run:**
```bash
ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-onboarding forge developer-spaces list --json
```
**Parse the JSON output and branch:**
| Situation | What the agent does |
|---|---|
| **Exactly one Developer Space** | Confirm and proceed: *"Found one Developer Space: **`<name>`**. I'll scaffold Guru there — sound good?"* On yes → capture that ID as `<space-id>`. |
| **Multiple Developer Spaces** | Present as a numbered list (name + ID). Ask: *"Which one should own Guru?"* Capture the pick as `<space-id>`. |
| **Zero Developer Spaces** | *"You don't have any Developer Spaces yet — every Forge app needs one. Open the [Developer Console](https://developer.atlassian.com/console/myapps) → space switcher (top left) → **Create Developer Space** → name it → confirm. Come back when it's ready and I'll re-run the list."* Wait for the user, then re-run and pick up the new space. |
**Do not proceed to 4c until `<space-id>` is captured.**
---
**4c. Pick the Atlassian dev site where the app will be installed.**
Third and final input the scaffold needs to know from you. This is a user decision, not a machine check — every Forge app has to be installed on an Atlassian site to run, and now that you understand what we're about to install (Guru, the Rovo Agent from Step 3), it's time to pick the site.
**Say something like:**
> "Last setup question — where do you want Guru installed once we deploy? Atlassian gives every developer a free **demo development site** — a private, fully-featured Atlassian cloud site (Jira, Confluence, JSM, Rovo — all enterprise editions, with **Rovo activated**) that stays active for 90 days. Rovo Agents specifically need Rovo activated, so a demo site is the fastest safe path.
>
> **Do you already have a developer site you want to use?**
>
> - **Yes, I know the URL** → tell me `myname.atlassian.net` and I'll use it.
> - **No / not sure** → I'll run `forge site provision`. It'll either show me your existing demo site or create a fresh one (free, ~2 min). Demo sites include Rovo by default.
> - **I use an Atlassian site for work** → *technically possible, but strongly discouraged for AI apps. Let's use a demo site so your test Agent is completely isolated from real work data.*
>
> Reply with the URL, `provision` to spin up a demo site, or `work` if you want to talk through the work-site tradeoffs first."
**Important CLI fact (locked, do not re-verify):** the only Forge site subcommand is `forge site provision`. It's **idempotent** — if you already have an active demo site, it displays it; if not, it creates one. There is no `forge site list`. Only re-verify with the Forge MCP if `forge site provision` errors with an unknown-command message.
**Branch A — user provides a URL of a site they already have:**
Capture the URL as `<site-url>`. Say *"Got it — we'll install on `<site-url>` in Step 7."* If they're unsure whether Rovo is active on that site, tell them we can check by attempting the install in Step 7 (it will fail clearly if Rovo is not activated).
**Branch B — user wants us to check for / provision a demo site:**
Ask for permission, then run:
```bash
ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-onboarding forge site provision
```
Two possible outcomes:
- **User already has an active demo site** → the CLI prints its name, URL, status, expiry. Capture the URL as `<site-url>`. *"You already have an active demo site — `<site-url>`, valid until `<expiry>`. We'll use it."*
- **User doesn't have one** → CLI provisions a new one. Wait for it to finish (~2 min). Ctrl+C is safe — provisioning continues in the background, and re-running the command shows status.
Note aloud: *"Demo sites are yours for 90 days. Re-run `forge site provision` any time to see or renew yours. Rovo is enabled by default — perfect for what we're about to build."*
**Wrap up 4c:**
> "✅ Site locked in: `<site-url>` (Rovo activated). That's where Guru will live."
**Do not proceed to Step 5 until all three of `<working-dir>`, `<space-id>`, and `<site-url>` are captured.**
---
### Step 5 — Scaffold your Rovo Agent
We're going to scaffold a **stock, minimal, real, working Rovo Agent** — the "Hello World" from Atlassian's official Rovo Agent tutorial. We do *not* customize anything into Forge Guru yet. That comes later — first we ship the stock version end-to-end so the user sees a real deploy → install → chat pipeline work. Then we evolve it into Guru.
**User-facing title for this step: *"Scaffold your Rovo Agent"*** (not "Scaffold Forge Guru" — we're not making Guru yet).
We delegate the actual `forge create` invocation to the **`forge-app-builder` skill's helper** — it already knows the exact non-interactive incantation for a Rovo Agent template and side-steps the entire "which prompt do I answer with what?" problem. Our job in this step is to (a) call the helper, (b) verify the scaffold, and (c) narrate what happened.
**Why delegate:** `forge create` is interactive by default, and template/category names have shifted over the CLI's lifetime. The `forge-app-builder` skill maintains a Python helper (`scripts.create_forge_app`) that runs `forge create` non-interactively with a template flag, a name, a directory, and a Developer Space ID. Using it guarantees we never get stuck in the interactive picker.
**Dependency check — before running the helper, confirm `forge-app-builder` is installed.** Both skills ship together in the standard [`forge-skills` plugin bundle](https://github.com/atlassian/forge-skills), so if the user installed the bundle this check passes silently. If it fails (e.g. because only this skill was symlinked in), stop and tell the user: *"This onboarding skill relies on the `forge-app-builder` skill for the scaffold step. Both ship together in the `forge-skills` plugin bundle — please install the whole bundle rather than just this one skill, then we'll continue."* Do not attempt to hand-roll a `forge create` invocation as a workaround.
**Pre-execution readiness — everything the helper needs, gathered before we call it:**
| Input | Source | Value |
|---|---|---|
| Working directory (parent of `forge-guru/`) | Captured in Step 4a | `<working-dir>` |
| Developer Space ID | Captured in Step 4b | `<space-id>` |
| Dev site URL | Captured in Step 4c | `<site-url>` (needed later in Step 7 deploy) |
| App name | We provide | `forge-guru` |
| Template | We provide | `rovo-agent-rovo` |
If any of the above is missing, ask the user for it *before* invoking the helper — never invoke it and troubleshoot mid-flow.
---
**5a. Delegate the scaffold to `forge-app-builder`.**
**Narrate before invoking:**
> *"Now I'll call the `forge-app-builder` skill's helper to run `forge create` non-interactively. It'll do two things at once: **register a new app with Atlassian** (giving it a unique app ID in the [Developer Console](https://developer.atlassian.com/console/myapps)) and **drop a starter project** at `<working-dir>/forge-guru/`. The helper hides the interactive picker so we don't have to navigate CLI menus by hand. Once it finishes we'll customize the scaffold into Forge Guru."*
**📌 Pinned template name — `rovo-agent-rovo`.** This is the current name of the Rovo Agent template in the Forge CLI, per Atlassian's official *Build a Rovo Agent hello world app* tutorial. **Do not re-verify** and **do not substitute** any other name (older docs and older MCP results may still say `rovo-agent` — that's stale). Only reach for the Forge MCP to look up a different name if the helper *actually errors* with an unknown-template message on `rovo-agent-rovo`.
**Invoke the helper from the `forge-app-builder` skill directory** (adjust the path to your local plugin bundle):
```bash
cd <path-to>/skills/forge-app-builder
ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-onboarding python3 -m scripts.create_forge_app \
--template rovo-agent-rovo \
--name forge-guru \
--dev-space-id <space-id> \
--directory <working-dir>
```
**If the helper reports the `rovo-agent-rovo` template name is not valid** (rare, but possible if the CLI has renamed it again — the template was previously called `rovo-agent` and is currently `rovo-agent-rovo` per Atlassian's official *Build a Rovo Agent hello world app* tutorial), first run:
```bash
python3 -m scripts.list_templates --validate rovo-agent-rovo
```
If validation fails, invoke the Forge MCP (`search-forge-docs` for *"Build a Rovo Agent hello world app"*) to look up the current Rovo Agent template name, and re-run the create helper with the correct `--template` value. **Always land on a Rovo Agent template** — never a blank template or a UI Kit template.
**If the helper errors on the Developer Space** — for example if `<space-id>` was mistyped or the space was deleted — go back to 5a and re-pick.
**If the helper errors that Forge terms have not been accepted**, stop and hand the exact interactive `forge create` command to the user to run themselves. The onboarding skill never accepts Forge terms on the user's behalf.
---
**5b. Verify the scaffold looks right before proceeding.**
```bash
cd <working-dir>
ls forge-guru
```
Expect at minimum: `manifest.yml`, `package.json`, and an `src/` directory. Open `manifest.yml` and confirm it contains a `rovo:agent` module block.
**If any of that is missing** — the wrong template was scaffolded. Delete the `forge-guru/` directory and re-run 5b with the correct `--template` value.
---
**5c. Deliver the "here's what just happened" moment.** Short and specific — this is the "you own a real Atlassian app now" beat.
> **🎉 Scaffold complete — you now own a real Atlassian app.**
>
> - **Globally unique app ID.** The helper called `forge create`, which registered a new app in your Atlassian account under the Developer Space you picked. That app doesn't exist for anyone else in the world.
> - **Real, working Rovo Agent.** The scaffold isn't a placeholder — it's a fully functional Hello World Rovo Agent. We'll deploy it as-is in a moment.
> - **Tracked in the [Developer Console](https://developer.atlassian.com/console/myapps).** Your home base for every Forge app you'll ever own — installs, environments, promotions, audit logs all live there. Bookmark it.
>
> **Quick note on names before we move on** — worth understanding, because it's how Forge works:
>
> When you ran `forge create --name forge-guru`, three names got locked together to the same value in one shot:
>
> - The **folder on disk** — `forge-guru/`, the directory the scaffold just created inside your working directory.
> - The app's **ID** (in `manifest.yml`, near the top) — `forge-guru`, the app's permanent, immutable identity in the Developer Console. Never renamed, never re-generated.
> - Your Rovo Agent's **display name** (from the `name:` field inside `manifest.yml`'s `rovo:agent` block) — **Forge Guru**. This is what you'll type in the Rovo chat picker to find your agent.
>
> That's the last time the name changes. You're **Forge Guru** from this moment on — in Loop 1 when we deploy the stock Hello-World-shaped scaffold, *and* in Loop 2 when we customize what Guru actually does. The customize step later only changes Guru's **behavior** (its prompt, its action, its description) — not its name.
>
> **Next up:** read the two files the scaffold gave us together, so you understand every field before we deploy.
**Wrap up Step 5.** Advance to Step 6.
*(No standalone `npm install` step. `forge deploy` in Step 7 handles dependency installation automatically for the stock scaffold — no action needed here. The first place we actively manage `package.json` is Step 9, where the Guru code introduces a new dependency; see 9b.)*
---
### Step 6 — Take a look at what the scaffold gave us
Before we ship or edit anything, help the user understand the two files the scaffold produced. Concepts live in chat; syntax lives in the actual files on disk — the agent points at them so the user can open them in their editor if they want to see the real code they now own. **The agent must not modify these files during Step 6.** The on-disk scaffold stays exactly as `forge create` produced it until Step 9.
**Purpose (internal):** anchor the mental model in something concrete before Loop 2 asks the user to approve changes to it.
**User-facing title for this step: *"Take a look at what the scaffold gave us"*.**
**Shape:**
- **Two short messages, one per file.** First `manifest.yml`, then `src/index.js`. No confirm-gate — pure narration + questions welcome.
- **Concept summary in chat, not code.** 4–6 bullets per file describing *what the file is for*, *what blocks it contains*, and *how the pieces connect* — cross-referenced to the Step 3 mental model. **No code blocks in chat by default.**
- **Point at the file.** Every chat message closes with the exact path to the file on disk, framed as an optional "open it in your editor if you want to see the syntax." The file is unmodified `forge create` output — no annotations, no teaching comments, no rewrites.
- **Invite questions before advancing.** Give the user a clear reply prompt (see the response-formatting rules).
**Runtime instruction to the agent:**
- **Do read the stock files from disk** (`cat <working-dir>/forge-guru/manifest.yml`, `cat <working-dir>/forge-guru/src/index.js`) so the concept summary you write in chat accurately reflects what the current Rovo Agent template actually shipped. Shapes and field names vary slightly across template versions — always work from the real file, not from memory.
- **Do NOT write to the files.** No inline comments, no reformatting, no touching disk. The scaffold on disk between Step 6 and Step 10 must be byte-for-byte identical to what `forge create` produced — this keeps the Step 8 first-deploy predictable and gives the user a clean baseline to compare against when we customize into Guru.
- **In chat, send the concept summary** (4–6 bullets, no code block) + close with the file path so the curious user can open it themselves.
**Say something like — first message, file tree + `manifest.yml` concept summary:**
> **Take a look at what the scaffold gave us — 1/2: `manifest.yml`**
>
> Here's what `forge create` produced. Two files matter (plus `package.json`, which is standard Node):
>
> ```
> forge-guru/
> ├── manifest.yml ← 🧭 THE MANIFEST (Step 3 concept #1)
> ├── package.json ← Standard Node.js project — includes @forge/api
> └── src/
> └── index.js ← ⚙️ THE BACKEND (Step 3 concept #4)
> ```
>
> **`manifest.yml`** is the file that tells Atlassian what your app is, where it appears, and what it's allowed to do. In the stock scaffold, it contains:
>
> - **`modules.rovo:agent`** — the block that makes the app a Rovo Agent (Step 3 concept #2). Fields include `key` (internal ID), `name` (what Rovo shows the user), `description`, `prompt` (the agent's personality + instructions — this is literal prompt-engineering), `conversationStarters` (quick-tap prompts), and `actions` (what the agent can do).
> - **`modules.action`** — one entry per thing the agent can do (Step 3 concept #4). The stock scaffold declares a single `hello` action whose `description` tells the AI when to call it. `inputs` are the typed parameters the AI knows how to fill in.
> - **`modules.function`** — binds an action key to a real exported handler in the code. The `handler` value (`index.hello`) points at the export named `hello` in `src/index.js`.
> - **`app.id`** — your app's globally unique identity, created by `forge create`. Never edit it by hand.
> - **`app.runtime.name`** — the Node runtime Atlassian runs your backend on (`nodejs22.x`), matching the version we checked in Step 1 (local-machine setup).
> - **No permissions block yet** — the stock agent doesn't call any APIs or external URLs, so it doesn't need any. Loop 2 will add one when we teach Guru to fetch from `developer.atlassian.com`.
>
> **📖 Want to see the exact syntax?** The file lives at `<working-dir>/forge-guru/manifest.yml` — open it in your editor. It's unchanged from what `forge create` produced, so what you see is a real, minimal, deployable Rovo Agent manifest.
>
> **Anything in there you'd like me to unpack before we look at `src/index.js`?**
**Answer any questions on the manifest.** When the user is ready, send a second message walking through `src/index.js` the same way:
> **Take a look at what the scaffold gave us — 2/2: `src/index.js`**
>
> **`src/index.js`** is the backend — the code Atlassian actually runs on its servers when the agent invokes its action (Step 3 concept #4). In the stock scaffold, it contains:
>
> - **One exported handler** (`hello`) — this is the function `manifest.yml` points at via `handler: index.hello`. The exported symbol name must exactly match the manifest's `handler` value, or Forge can't find your code.
> - **A `payload` argument** — what the Rovo Agent passes in when it invokes the action. Contains any `inputs` the agent filled in from the user's message. The stock scaffold doesn't declare any inputs, so payload is essentially empty here.
> - **A return value** — whatever the handler returns goes back to the agent, which uses it to compose a reply. Forge serializes what you return; strings and plain objects both work.
> - **No imports, no permissions, no network calls, no external SDKs.** The stock scaffold is deliberately minimal — everything it needs to be a real, working Rovo Agent is right there.
>
> **📖 Want to see the exact syntax?** The file lives at `<working-dir>/forge-guru/src/index.js` — open it in your editor. It's unchanged from what `forge create` produced.
>
> **That's the whole Rovo Agent.** Two files. Under 50 lines of code between them. And it's ready to deploy right now.
>
> **Any questions on how the pieces connect?** Otherwise, next up: we ship it. First deploy of your Forge career.
**Do not advance to Step 8 until the user has seen both concept summaries and had a chance to ask questions.** Answer generously — this is the "understand the app before you run it" beat.
---
### Step 7 — Deploy your first Forge app
Ship the stock Hello World agent. This is the user's first-ever Forge deploy — the confidence beat depends on it landing cleanly. **Delegated end-to-end to `forge-app-builder`'s `scripts.deploy_forge_app`** — one non-interactive call runs `forge deploy` + `forge install` together.
**User-facing title for this step: *"Your first Forge app is Deployed and Installed to your <site-url>"*.**
Before running anything, say this out loud:
> "Two commands under the hood, one call in practice:
>
> - **`forge deploy`** publishes your code to Atlassian's servers under your app ID. Think of it as 'save to the cloud.' It doesn't affect any site or any user yet.
> - **`forge install`** attaches your deployed app to a specific site. This is what actually makes the agent appear in Rovo on that site.
>
> You'll deploy many times per day while iterating; you install once per site. This is the daily rhythm of every Forge developer. The `forge-app-builder` skill wraps both into a single non-interactive call so you don't have to run them separately."
Also introduce **environments** briefly:
> "Forge apps have three environments: `development`, `staging`, and `production`. Everything we do today lives in `development` — private, safe, breakable. When you eventually have real users, `production` is a separate, deliberate promotion step. Forge is never 'auto-deploy to prod.'"
**No standalone `forge lint`.** `forge deploy` runs the equivalent validation server-side, and the stock scaffold is guaranteed to pass — we haven't touched it.
---
**7a. Confirm the deploy + install plan with the user.**
>
> Now its time to get your app from your disk onto Atlassian's servers and into Rovo on your dev site. Here's the plan:
>
> - Run **`forge deploy`** — upload the stock scaffold to Atlassian's servers in the `development` environment. No site is affected yet.
> - Run **`forge install`** — attach the deployed app to your dev site: **`<site-url>`** (product: `jira`, environment: `development`). This is what makes the agent appear in Rovo on that site.
>
> The stock scaffold declares no permissions, so no install-time permission prompt should appear. If the CLI ever pauses on a Forge-terms prompt I'll stop and hand it to you — I don't accept Forge terms on your behalf.
>
> **Ready?** (**yes / go / sure / y / ok**)
**Wait for an affirmative.** Answer any last questions.
---
**7b. Delegate deploy + install to `forge-app-builder`.**
Deploying and installing your first Forge app is a one-line helper call. The helper runs `forge deploy` and `forge install` together, non-interactively, so the user doesn't have to navigate CLI menus.
**Invoke the helper from the `forge-app-builder` skill directory** (adjust the path to your local plugin bundle). Use the app directory from Step 6 (the scaffold) as `--app-dir` and the site URL captured in Step 4c as `--site`:
```bash
cd <path-to>/skills/forge-app-builder
python3 -m scripts.deploy_forge_app \
--app-dir <working-dir>/forge-guru \
--site <site-url> \
--product jira \
--env development
```
Wait for completion. On success the helper prints both a deploy confirmation and an install confirmation.
**7c. Celebrate the first win. Do not skip this.**
> 🎉 **Congrats — you just deployed and installed your first Forge app.**
>
> - **Deployed** to the `development` environment on Atlassian's infrastructure. No server to run — Atlassian hosts the whole thing.
> - **Installed** on your dev site (`<site-url>`).
> - Your stock Hello World Rovo Agent is live and reachable in Rovo *right now*.
>
> Every Forge developer's daily rhythm looks like this: edit → deploy → see it live. You just did it end-to-end. Let's go see it.
**Common failure modes:**
- **Forge terms not accepted** → the helper stops. Do not accept on the user's behalf. Tell the user: *"Those terms cover what your app is allowed to do with data on the site — reading them yourself is a habit worth keeping. Run `forge deploy` interactively once, accept the terms, then I'll re-run the helper."*
- **Rovo not activated on the site** → *"Rovo isn't activated on this site. If we provisioned a demo site in Step 4c this shouldn't happen — but if you brought your own site, we may need a different one. Want me to run `forge site provision` for a demo site instead?"*
- **Any other error** → surface verbatim and consider routing to `forge-debugger`.
---
**7d. Confirm the install (read-only diagnostic).**
`forge install list` is read-only — not app mutation — so this skill invokes it directly to confirm the install landed:
```bash
ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-onboarding forge install list --json
```
Parse the JSON. Confirm the app is installed on the right site under the `development` environment.
---
### Step 8 — See Hello World live on your dev site
Walk the user into Rovo and get them to chat with the stock agent. **This is the first confidence beat — do not skip it and do not rush it.** Even though the Hello World agent barely does anything, the user *seeing their own code respond in Rovo* is the moment Forge becomes real.
**User-facing title for this step: *"See Hello World live on your dev site"*.**
**Say something like:**
> 🎉 **Your Hello World Rovo Agent is live. Let's go see it.**
>
> 1. **Open your dev site:** [https://\<your-site\>.atlassian.net](https://<your-site>.atlassian.net) — use the exact URL from Step 4c.
> 2. **Find Rovo.** Rovo appears as a chat surface in Jira and Confluence — typically accessible from the top-right of the Atlassian navigation, or via a "Chat with Rovo" button. On demo sites Rovo is pre-activated.
> - If you don't see it, look for the Rovo icon in the top nav, or use the site's search bar and type "Rovo".
> 3. **Find your agent.** Rovo shows a list of available Agents — yours will appear with the name from the stock scaffold (typically something like *"Hello World Agent"* or the app name we passed to `forge create`).
> - Agents typically take up to ~60 seconds after install to appear. If you don't see it immediately, hard-refresh (⌘⇧R / Ctrl+Shift+R).
> 4. **Open a chat with it.** Try the conversation starters from the manifest, or type any message.
> 5. **Watch it respond.** The reply will be short and hello-world-y — that's expected. The point isn't the answer; the point is that **your code, on Atlassian's servers, just handled a real chat message from Rovo.**
>
> **To confirm the backend actually ran**, come back to your terminal and run:
>
> ```bash
> ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-onboarding forge logs
> ```
>
> You should see the request from your handler. That's the full loop end-to-end: **you chatted → Rovo picked the action → Forge ran your function on Atlassian's servers → the reply came back.**
>
> **Not seeing your agent, or it's not responding?**
> - Hard-refresh (⌘⇧R / Ctrl+Shift+R).
> - Wait up to 60 seconds for install propagation.
> - Confirm the install landed: `forge install list`.
> - Confirm Rovo is activated on this site (demo sites have it by default).
> - If it's still stuck, ask me to load the `forge-debugger` skill.
**Ask the user to confirm they saw the agent respond before advancing.** Then transition:
> **🎉 You just shipped and used your first Forge app. Now the fun part: let's turn this Hello World into something you'll actually want to keep.**
**Do not advance to Step 10 until the user confirms they saw the Hello World agent respond in Rovo.**
---
### Step 9 — Turn Hello World into Forge Guru
Now we evolve the stock Hello World agent into **Forge Guru** — a real, useful, keep-forever companion. Two files change, one at a time, each behind its own confirm-gate. The user already understands what these files contain (from the concept summaries in Step 6), so these gates focus on **what's changing and why** — a compact change-list, no full target-file paste by default.
**User-facing title for this step: *"Turn Hello World into Forge Guru"*.**
**Shape of each confirm-gate:**
- **One file per gate.** Manifest first, then `src/index.js`. Don't combine them.
- **Chat message = compact change list only.** Bulleted "what's changing and why" cross-referenced to Step 3 concepts. **No target-file paste in chat by default.** The teaching concepts already landed in Step 6 — this step is about the specific diff.
- **Escape hatch:** *"I can show you the exact final file before I write it if you want — just say 'show me the file'. Otherwise, say the word (yes / go / sure / y / ok) and I'll apply it."*
- **Invite questions.** Advancing without the user understanding is a bug, not a feature. Answer anything they raise before re-offering the gate.
- **Wait for an explicit affirmative** (yes / go / sure / y / ok / or any clear variant) before writing to disk.
- **When writing to disk:** replace the file with **clean, production-shaped Guru code** — a short header comment (`// Forge Guru — generated during forge-onboarding` + 1-line description), then the code. The Step-7 teaching comments were their job in Loop 1; Loop 2 code looks like a real Forge app. **The full target file bodies are pinned in the "Reference — target file bodies" section below** for the agent to use as the exact write payload.
---
**9a. Customize `manifest.yml` — a per-file confirm-gate.**
**Say something like:**
> **Turn Hello World into Forge Guru · file 1 of 2 — `manifest.yml`**
>
> Remember the stock `manifest.yml` we walked through in Step 6? Here's what's changing to turn it into Forge Guru:
>
> - **New `description`** on the `rovo:agent` module — tells Rovo (and future-you) what Guru is *for*, distinct from what Guru is *called*. The `key` and `name` were locked to `forge-guru` / `Forge Guru` when we ran `forge create` — those don't change in Loop 2. *Concept: the `rovo:agent` module (Step 3 #2).*
> - **Prompt replaced** — new instructions that make Guru trustworthy: search the docs, explain plainly, **always cite the doc URL**, never invent APIs. *Prompt-engineering — the difference between a helpful agent and a confident-sounding hallucinator lives here.*
> - **`conversationStarters` added** — five real Forge questions Rovo will offer as quick-tap prompts so a first-time user knows where to start.
> - **Action swapped** — the stock `hello` action is replaced with a new `search-forge-docs` action wired to a `searchForgeDocs` function. Its `description` is what the AI reads to decide *when* to call it. *Concept: Backend, wrapped for AI (Step 3 #4).*
> - **New `permissions.external.fetch.backend` block** with `https://developer.atlassian.com` — Forge's outbound-network permission system. This is the *only* URL Guru is allowed to call on the internet; anything else Forge blocks at the sandbox boundary. *Least-privilege applies to network egress, not just Atlassian scopes.*
> - **`app.id` and `app.runtime` preserved** — never touched. `app.id` is your app's identity.
>
> **📖 Want to see the exact final file before I write it?** Just say *"show me the file"* and I'll paste the full YAML. Otherwise say the word (**yes / go / sure / y / ok**) and I'll apply it.
**If the user says "show me the file"** (or equivalent), paste the pinned target-file YAML from the *"Reference — target file bodies"* section below (9-ref), then re-offer the gate.
**Wait for an explicit affirmative before writing to disk.** Treat questions as first-class — answer them, then re-offer the gate. Do not short-circuit the gate by writing the file and *then* explaining.
**When the user confirms**, replace `manifest.yml` with the pinned target-file YAML (see 9-ref below) — **preserving the real `app.id` value from the stock file** (do *not* overwrite it with the placeholder text).
**After writing:**
> ✅ `manifest.yml` updated. Agent is now Forge Guru, prompt + conversation starters set, `search-forge-docs` action + function declared, egress permission for `https://developer.atlassian.com` added, `app.id` preserved. One file left.
**Sanity-check what you wrote** before advancing — the file must parse as valid YAML, `app.id` must still be the value `forge create` produced (do not overwrite it with the placeholder), and every `handler`/`function` name must match across the `action`, `function`, and (about-to-be-written) `src/index.js` boundaries. If any of that is off, fix it *before* advancing.
---
**9b. Customize `src/index.js` — a per-file confirm-gate (with an inline `package.json` update).**
**Say something like:**
> **Turn Hello World into Forge Guru · file 2 of 2 — `src/index.js`**
>
> The manifest is Guru's. Now the backend code the new `search-forge-docs` action points at. Here's what's changing from the stock hello-world handler:
>
> - **New import: `import api from '@forge/api'`** — the Forge SDK's egress-controlled fetch. It only works because the manifest declares `https://developer.atlassian.com` in `permissions.external.fetch.backend`. Manifest permission + SDK call are two halves of the same coin.
> - **Handler swapped** — the stock `hello` handler is replaced with `searchForgeDocs(payload)`. The manifest's `function.handler` (`index.searchForgeDocs`) points at this exact exported symbol. Reads `payload.query`, calls the Atlassian docs-search endpoint, returns the top 3 results as a structured object.
> - **Empty-query guard** — if the agent invokes us with no query, return a friendly note instead of hitting the network.
> - **Error handling** — non-200 responses, thrown exceptions, and zero-result payloads all funnel into a `fallback` helper so Guru is never useless.
> - **New `fallback(query, note)` helper** — returns three curated top-level Forge doc links (platform overview, manifest reference, CLI reference) so Guru always answers with *something* useful, even if the search endpoint changes shape.
> - **Return shape** — a plain object (`{ query, results }`), not a string. The agent uses the `title`/`url`/`snippet` fields to compose a cited reply.
>
> **📦 One small side-effect: I'll also add `@forge/api` to `package.json`.** The new handler imports `@forge/api`, and the stock scaffold's `package.json` may not list it as a dependency yet. Without this, `forge deploy` in the next step will fail with a `Cannot find module '@forge/api'` error at runtime. I'll add the current version of `@forge/api` to your `dependencies` block as part of applying this file — no separate approval needed, it's just what has to happen for the new code to work. You'll see the extra line in `package.json` if you open it after.
>
> **📖 Want to see the exact final file before I write it?** Just say *"show me the file"* and I'll paste the full JavaScript. Otherwise say the word (**yes / go / sure / y / ok**) and I'll apply it — file + dependency together.
**If the user says "show me the file"** (or equivalent), paste the pinned target-file JavaScript from the *"Reference — target file bodies"* section below (9-ref), then re-offer the gate. If they specifically want to see the `package.json` change too, tell them it's a one-line add under `dependencies` — e.g. `"@forge/api": "^X.Y.Z"` at the current published major — and then re-offer.
**Wait for an explicit affirmative before writing to disk.** Answer any questions first — the whole point of this gate is that the user leaves understanding *why* the code looks the way it does.
**When the user confirms**, do BOTH writes as one atomic step:
1. **Replace `src/index.js`** with the pinned target-file JavaScript (see 9-ref below).
2. **Update `package.json`** — read the existing file (do not overwrite it), parse the JSON, ensure `dependencies["@forge/api"]` is present. If it's already there, leave the version untouched. If it's missing, add it at the latest published major (get the current version with `npm view @forge/api version` if unsure, or use the same version the `forge-app-builder` scaffold ships in newer templates). Preserve all other fields in `package.json` exactly as they are — `name`, `version`, `main`, `scripts`, `license`, existing dependencies, etc. Do not reformat or reorder.
**After writing both:**
> ✅ `src/index.js` replaced. `searchForgeDocs` handler wired to the manifest, egress-controlled `api.fetch` in place, empty-query / HTTP-error / zero-result paths all route through `fallback`, three curated Forge doc links as the safety net.
>
> ✅ `package.json` updated with `@forge/api` in `dependencies`. `forge deploy` in the next step will install it automatically as part of its build pipeline.
**Sanity-check what you wrote** before advancing:
- The exported symbol name in `src/index.js` must match the manifest's `handler: index.searchForgeDocs`.
- The `import` line must be at the top of the file, and there must be no leftover scaffold code from the hello-world handler.
- `package.json` must still parse as valid JSON — a broken `package.json` breaks the deploy. If your write may have introduced a trailing-comma or bracket-mismatch, re-read and re-parse before advancing.
- `package.json.dependencies["@forge/api"]` must be present.
If any of that is off, fix it before advancing.
---
**9-ref. Reference — target file bodies (write these to disk on confirm; only paste in chat if the user asks "show me the file").**
**Target `manifest.yml`:**
Every source line below is ≤160 characters and every field value fits Forge's manifest-field length limits. Do not lengthen any line, string block, or field value when writing this file to disk — `forge lint` runs during `forge deploy` (Step 11) and will fail the deploy if you exceed those limits.
```yaml
# Forge Guru — generated during forge-onboarding.
# A Rovo Agent that answers Forge questions
# by searching Atlassian's official developer docs.
modules:
rovo:agent:
- key: forge-guru
name: Forge Guru
description: >-
Your personal Forge development companion.
Answers your Forge questions by searching
Atlassian's official developer docs.
prompt: |
You are Forge Guru, a companion for developers
building Atlassian Forge apps. You answer
questions about the Forge platform: which
modules to use, how to add features to Jira
and Confluence, how to work with Rovo Agents,
resolvers, permissions, the Forge CLI, and
deployment.
When a user asks how to do something in Forge:
1. Use the search-forge-docs action to find
authoritative documentation.
2. Explain the answer in plain language,
tailored to their skill level.
3. Always cite the doc URL you found.
4. Suggest a concrete next command or code
snippet when useful.
Be concise, warm, and confidence-building.
You were literally built by this developer as
their first Forge app — meet them where they
are. Never invent Forge APIs, CLI commands,
module names, or scopes. If search returns
nothing useful, say so and point them at
https://developer.atlassian.com/platform/forge/
instead of guessing.
conversationStarters:
- What can I build with Forge?
- Which Forge module should I use for my idea?
- How do I add something to a Jira issue?
- How do I call the Jira REST API from Forge?
- Difference between UI Kit and Custom UI?
actions:
- search-forge-docs
action:
- key: search-forge-docs
function: searchForgeDocs
actionVerb: GET
description: >-
Searches Atlassian's official Forge developer
docs for a query and returns the top matching
pages with titles, URLs, and snippets. Use it
whenever the user asks how to do something in
Forge, which module to use, how a Forge API
works, or any question the official docs can
answer.
inputs:
query:
title: Search query
type: string
required: true
description: >-
The user's Forge question, or the key
phrases from it. Prefer specific technical
terms (module names, CLI commands, API
paths) over full sentences.
function:
- key: searchForgeDocs
handler: index.searchForgeDocs
permissions:
external:
fetch:
backend:
- 'https://developer.atlassian.com'
app:
runtime:
name: nodejs22.x
# Preserve the app.id value from the stock scaffold.
# Do not overwrite it with placeholder text.
id: <your app id here>
```
**Target `src/index.js`:**
```javascript
// Forge Guru — generated during forge-onboarding.
// Backend for the `search-forge-docs` Rovo Agent action. Fetches from
// Atlassian's official developer docs and returns the top 3 results.
import api from '@forge/api';
export async function searchForgeDocs(payload) {
const query = (payload && payload.query) || '';
if (!query.trim()) {
return {
results: [],
note: 'No query provided. Ask a specific Forge question.'
};
}
const url =
'https://developer.atlassian.com/gateway/api/search/?' +
`q=${encodeURIComponent(query)}&site=developer`;
try {
const response = await api.fetch(url);
if (!response.ok) {
return fallback(query, `Search returned HTTP ${response.status}.`);
}
const data = await response.json();
const raw = Array.isArray(data.results) ? data.results : [];
const results = raw.slice(0, 3).map((r) => ({
title: r.title || r.name || 'Untitled',
url: r.url || r.link || '',
snippet: r.snippet || r.description || ''
}));
if (results.length === 0) {
return fallback(query, 'No matching docs found.');
}
return { query, results };
} catch (err) {
console.error('search-forge-docs failed:', err);
return fallback(query, `Search errored: ${err.message}`);
}
}
function fallback(query, note) {
return {
query,
note,
results: [
{
title: 'Forge documentation (home)',
url: 'https://developer.atlassian.com/platform/forge/',
snippet:
'Start here for the full Forge platform documentation.'
},
{
title: 'Forge manifest reference',
url: 'https://developer.atlassian.com/platform/forge/manifest-reference/',
snippet:
'Every module, permission, and manifest property.'
},
{
title: 'Forge CLI reference',
url: 'https://developer.atlassian.com/platform/forge/cli-reference/',
snippet: 'All Forge CLI commands and flags.'
}
]
};
}
```
---
### Step 10 — Redeploy — this time as Forge Guru
Same helper, second time. This is the daily-rhythm beat — the user sees that iterating on a Forge app is just *edit → redeploy → see it live*. No new concepts, just muscle memory.
**User-facing title for this step: *"Redeploy — this time as Forge Guru"*.**
**Say something like:**
> **Redeploy — this time as Forge Guru · plan**
>
> Same `forge-app-builder` helper as before, same command shape, same site. This time it'll ship the Forge Guru version of the manifest + code, still to the `development` environment on the same app ID. No re-install needed if the app is already installed — the deploy alone updates what's running.
>
> **⚠️ Heads up: this is a major version bump.** Because Guru's manifest adds a new external-fetch permission (`https://developer.atlassian.com` in `permissions.external.fetch.backend`), Forge treats this as a **breaking change** — scope additions can affect any existing install of the app, so Forge requires an explicit acknowledgment before shipping it. Two things flow from that:
>
> 1. **`forge deploy` succeeds normally** — deploy itself doesn't need special flags for major-version bumps. The version metadata just gets stamped on the new deployment.
> 2. **`forge install --upgrade` is what acknowledges the major-version bump.** The bump only affects existing installs, so the acknowledgment lives on the install command, not deploy. I'll pass `--upgrade` to the install portion of the helper so it goes through non-interactively — no manual prompt to answer.
> 3. **The install may also ask you to accept the new permission** on first install with an updated scope. The helper handles this non-interactively where it can; if the CLI stops on a Forge-terms prompt I'll surface it and hand it to you.
>
> This is a real Forge platform concept — you'll see it every time you add or remove a permission, module, or scope. Loop 1's first deploy hit the same guardrail silently (a brand-new app is by definition a breaking change against "nothing"), so this is your first *visible* one.
>
> **Ready?** (**yes / go / sure / y / ok**)
**Wait for an affirmative.** Then invoke (note the `--upgrade` flag routed to the *install* portion of the helper, not deploy):
```bash
cd <path-to>/skills/forge-app-builder
python3 -m scripts.deploy_forge_app \
--app-dir <working-dir>/forge-guru \
--site <site-url> \
--product jira \
--env development \
--extra-install-args "--upgrade"
```
**Helper-flag note (for the agent, not the user):** the `--upgrade` flag belongs on `forge install`, **not `forge deploy`** — the version bump only affects the install step (existing installs need to acknowledge the new scope). The exact way to pass it through depends on the version of `scripts.deploy_forge_app` in the installed `forge-app-builder` skill. If the helper accepts an `--extra-install-args` (or similar) pass-through flag, use it. If not, or if the helper doesn't currently support `--upgrade` at all, catch the CLI's interactive major-version prompt inline (which appears during the *install* portion of the helper's flow) and answer `yes` — the user has already been briefed that this is happening and why. **Follow-up for the `forge-app-builder` team:** add first-class `--upgrade` pass-through to `scripts.deploy_forge_app` so this fallback isn't needed.
On success:
> ✅ **Guru is deployed and installed.** Same environment, same site — the app ID hasn't changed, but the agent is now Forge Guru with the new prompt, the new action, and the egress permission for `developer.atlassian.com`. And the major-version bump was accepted — v1.0.0 → v2.0.0 (or whatever the next major is), because we added a permission scope.
**Common failure modes** — same as Step 7 (Forge terms, Rovo not activated, manifest validation error, other). Manifest-validation errors are the one to watch for here since we just edited the file — surface the helper's output verbatim and route back to Step 9a to fix the specific field. If the major-version prompt stalls the install (helper doesn't support `--upgrade` passthrough and the interactive prompt isn't being caught during the install step), answer `yes` when it appears — the user was pre-briefed above.
---
---
### Step 11 — See Forge Guru live
Walk the user into Rovo on their dev site, help them find Guru, and get them to ask a real Forge question. The deploy isn't the win — using Guru is. Do not assume the user knows their way around Rovo; walk them there step by step.
> 🎉 **Forge Guru is live on your dev site. Let's go meet it.**
>
> 1. **Open your dev site in a browser:** `https://<your-site>.atlassian.net`
> 2. **Find Rovo.** Rovo appears as a chat surface in Jira and Confluence — typically accessible from the top-right of the Atlassian navigation, or via a "Chat with Rovo" button. On demo sites Rovo is pre-activated.
> - If you don't see it right away, look for the Rovo icon in the top navigation, or use the search bar and type "Rovo".
> 3. **Find Forge Guru.** Rovo shows a list of available Agents — yours will appear with the name **Forge Guru** and the description you set in the manifest.
> - Agents typically take up to ~60 seconds after install to appear. If you don't see it immediately, hard-refresh (⌘⇧R / Ctrl+Shift+R).
> 4. **Open a chat with Guru.** You should see the conversation starters we defined in the manifest — *"What can I build with Forge?"*, *"Which Forge module should I use for my idea?"*, *"How do I add something to a Jira issue?"*, etc.
> 5. **Try a conversation starter, or type your own question.** Good first questions to try:
> - *"How do I add something to a Jira issue?"*
> - *"Which Forge module should I use to build a Confluence macro?"*
> - *"How do I call the Jira REST API from a Forge resolver?"*
> 6. **Watch Guru respond.** Guru should call the `search-forge-docs` action, fetch real documentation from `developer.atlassian.com`, and reply in the chat with a plain-language explanation plus a link to the official doc it found. That link is your proof that the answer came from real Atlassian docs — not from the model guessing.
>
> **Not seeing Guru at all in the Rovo Agent picker?**
> - Hard-refresh the page (⌘⇧R / Ctrl+Shift+R).
> - Wait up to 60 seconds for install propagation.
> - Confirm the install landed: `forge install list`.
> - Confirm Rovo is activated on this site (demo sites have it by default).
> - If it's still stuck, ask me to load the `forge-debugger` skill.
**Once the user has chatted with Guru, ask them the honest evaluation question.** This is the real success signal for a Rovo Agent — the *quality* of the response, not the fact that it responded. Only the user can judge that.
> **How did that feel?**
>
> - Did Guru actually answer your question — usefully, with a link to a real Atlassian doc?
> - Or was the answer thin, off-target, missing a citation, or did Guru just say *"I don't know"*?
>
> Reply with **useful** if Guru nailed it, **meh** if it worked but you wish it did something differently, or **broken** if it didn't respond well (empty answer, error, generic fallback).
**Branch on the user's answer — three paths:**
**Path A — user says "useful" (or any positive signal like `great`, `yes`, `it worked`):**
Celebrate. This is the real moment they became a Forge AI developer *and* the moment they gained a permanent Forge companion.
> 🎉 **You built a working Rovo Agent that actually helps.** That's the AI-native loop end-to-end: **you chatted with Guru → Rovo picked the `search-forge-docs` action → Forge ran your function on Atlassian's servers → your function fetched from developer.atlassian.com (allowed because of the egress permission you declared) → the results came back → the Agent composed a cited answer for you.**
>
> **Guru is yours now — forever.** Every time you come back to your dev site, Guru will be in Rovo, ready to help. Ask it anything about Forge as you keep building. It's not a demo — it's your Forge companion. Bookmark your dev site and come back often.
Advance to Step 12.
**Path B — user says "meh" (or "okay but", "I wish it", "it works but…"):**
Great — this is the actual iteration muscle you'll use every day building AI agents. Give a **small nudge**, not a full walkthrough:
> Guru's behavior lives in the **`prompt:`** field of its `rovo:agent` module in `manifest.yml` — that's the main lever. Edit that prompt (make it more opinionated, add a rule like *"always answer in three bullets"*, or restrict what it should refuse to answer), then re-run the same deploy command from Step 10. Guru updates on the next deploy.
>
> **One helpful thing to know:** editing *just* the prompt is **not** a major version bump — that guardrail only fires when you add/remove permissions, modules, or scopes. So a prompt-only redeploy will just work, no `--upgrade` needed. Fastest iteration loop in Forge.
>
> Come back to this whenever — no need to do it now unless you want to. Ready to keep going?
Wait for confirmation, then advance to Step 12.
**Path C — user says "broken" (or "error", "empty", "didn't respond", "I don't know"):**
*Now* introduce `forge logs` — as the debugging tool, not the success signal.
> Let's look at what happened server-side. `forge logs` shows anything your function printed or any errors it threw. When Guru is working, `forge logs` is usually quiet — no news is good news. When it's not working, this is where the story is.
>
> ```bash
> ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-onboarding forge logs
> ```
>
> **Common shapes of what you'll see:**
> - **`fetch is not defined` / permission error** → the manifest is missing `permissions.external.fetch.backend` for `developer.atlassian.com`. Go back to `manifest.yml`, confirm the permission is there, redeploy.
> - **HTTP 4xx/5xx from `developer.atlassian.com`** → the docs-search endpoint may have changed shape. Guru's `fallback` helper should have kicked in and returned the three curated doc links — verify Guru at least gave you *something*.
> - **No logs at all** → the function never ran. That usually means the action definition is off — check `manifest.yml`'s `action` module has `function: searchForgeDocs` and the function module's `handler: index.searchForgeDocs` matches the exported symbol in `src/index.js`.
> - **`Cannot find module '@forge/api'`** → `package.json` didn't get updated with the `@forge/api` dependency. Go back to Step 9b, confirm the `package.json` edit, redeploy.
>
> Once you know what happened, fix it and redeploy (same command from Step 10). If you're stuck, ask me to load the `forge-debugger` skill — it's built for exactly this kind of investigation.
Wait for the user to confirm they've resolved the issue (or explicitly want to skip and continue), then advance to Step 12.
**Reply hint for the honest-eval question above:** *"Reply with **useful** / **meh** / **broken** — or describe what you actually saw and I'll figure out which path we're on."*
**Bookmarks for the road** (regardless of which path they took):
- **Your dev site:** `https://<your-site>.atlassian.net` — where Guru lives.
- **Developer Console:** https://developer.atlassian.com/console/myapps — manage all your Forge apps.
- **Rovo Agent docs:** https://developer.atlassian.com/platform/forge/manifest-reference/modules/rovo-agent/
- **Forge docs:** https://developer.atlassian.com/platform/forge/
- **Atlassian Developer Community:** https://community.developer.atlassian.com/
---
### Step 12 — What next
Hand the user a map for the rest of their Forge journey, framed around Atlassian's official [*Build and launch your Forge app*](https://developer.atlassian.com/platform/forge/build-and-launch-your-forge-app/) doc. This onboarding is the guided walkthrough of stage 1 (**Build**); that doc is the map for stages 2–4.
Structure of this final message: **graduation framing → Get inspired → the four stages (Build / Prepare to publish / Distribute / Grow) → Guru CTA.**
**User-facing title for this step: *"What next — the rest of your Forge journey"*.**
**Say something like:**
> 🚀 **You've just completed the guided *Build* stage of your Forge journey.**
>
> Everything you did today — pre-flight, scaffold, deploy, install, customize, redeploy — maps to stage 1 of Atlassian's official [Build and launch your Forge app](https://developer.atlassian.com/platform/forge/build-and-launch-your-forge-app/) doc. That doc is your map for the whole journey. Here's what the rest of it looks like, plus what to explore first.
>
> ### Get inspired — see what other Forge apps look like
>
> Before you decide what to build next, take 10 minutes and look at some real Forge apps other developers have built and open-sourced. All three are on [atlassian-labs/forge-inspired](https://github.com/atlassian-labs/forge-inspired) — clone them, run them on your dev site, or just read the code to see how the four Forge concepts you now know show up in more ambitious apps.
>
> - **[Sprint Ready Agent](https://github.com/atlassian-labs/forge-inspired/tree/main/sprint-ready-agent)** — turns a rough Jira issue into a clearer, sprint-ready ticket with useful context, acceptance criteria, and open questions. A more ambitious Rovo Agent than Guru.
> - **[Smart Workflow Follow-up](https://github.com/atlassian-labs/forge-inspired/tree/main/smart-workflow-followup)** — posts a personalized follow-up message whenever a Jira issue reaches a chosen status. A great example of Jira product event handlers.
> - **[Team Pulse Board](https://github.com/atlassian-labs/forge-inspired/tree/main/team-pulse-board)** — surfaces contributors, related Jira work, and recent activity on a Confluence page. A great example of a UI Kit app that reads across Atlassian products via the Context Moat.
>
> Poke around, and when something clicks — *"oh, I want to build something like that"* — come back to your dev site and just tell Rovo Dev what you want.
>
> ### 1. Build — you're here 🎯
>
> You've shipped Guru end to end. When you want to build *another* app, you don't have to re-run this onboarding — you can invoke the specialist skills directly.
>
> - **`forge-app-builder`** — scaffold + deploy new apps (any template, any module, any product).
> - **`forge-connector`** — build a Teamwork Graph connector to ingest external data.
> - **`forge-debugger`** — broken deploy, blank UI, unexpected error, tunneling questions.
>
> ### 2. Prepare to publish
>
> Before you share an app with real users, run it through the *[Prepare to publish](https://developer.atlassian.com/platform/forge/build-and-launch-your-forge-app/#prepare-to-publish)* stage — iterate with Forge Tunnel, review your scopes and data handling, watch app behavior via logs and metrics, and debug performance.
>
> - **`forge-security-review`** — audit scopes, permissions, egress, and Rovo Agent AUP compliance.
> - **`forge-app-review`** — pre-release review of a real app end-to-end.
> - **`forge-cost-optimizer`** — Forge's free tier is generous, but knowing what costs money is worth 10 minutes.
>
> ### 3. Distribute
>
> When your app is ready for users, [pick a distribution path](https://developer.atlassian.com/platform/forge/build-and-launch-your-forge-app/#distribute):
>
> - **Share internally** with your organization for internal workflows, feedback, or a controlled rollout — see [Distribute your apps](https://developer.atlassian.com/platform/forge/distribute-your-apps/).
> - **Publish on Marketplace** to reach customers worldwide and unlock revenue — see the [Marketplace publishing guide](https://developer.atlassian.com/platform/marketplace/listing-forge-apps/).
>
> ### 4. Grow
>
> [Keep iterating](https://developer.atlassian.com/platform/forge/build-and-launch-your-forge-app/#grow) — refine the experience, add AI capabilities where they help, and stay connected to the community.
>
> - Browse the [Rovo modules](https://developer.atlassian.com/platform/forge/manifest-reference/modules/rovo-index/) — Rovo Agent, Rovo Action, Rovo MCP, Rovo Connector, Forge LLMs.
> - Join the [Atlassian Developer Community](https://community.developer.atlassian.com/c/forge) and find your local [ACE group](https://ace.atlassian.com/).
>
> ### And Guru is one Rovo chat away whenever you get stuck
>
> Every question from here on — which module to use, what scope you need, how a Forge API works — ask Guru first. It searches [the official docs](https://developer.atlassian.com/platform/forge/) live and cites them, so you can trust the answer and follow the link.
>
> **The mental model you learned today** — manifest, modules & extension points, the Context Moat, and backend actions — works for every Forge app you'll ever build. When you see a big Marketplace Agent, decompose it into those pieces and it stops looking scary.
>
> Have fun building. 🛠️
**Reply with `done` (or just close the chat) when you're ready to wrap up. Or reply with any question — Guru is on the dev site now, but I'm here too.**
This skill's job ends when the user has Forge Guru running on their dev site, has asked it at least one real Forge question and gotten a cited answer back, understands the four AI-native concepts, and knows exactly which door to knock on next in the four-stage journey.