/forge-onboarding

name: forge-onboarding
description: Guide a first-time Forge builder through deploying a stock Rovo Agent, then turning it into Forge Guru, a documentation companion. Use for Forge onboarding, a first Forge or Rovo app, or resuming this tutorial. Route unrelated existing-app changes, debugging, reviews, and connector work to the specialist skills.
license: Apache-2.0
metadata:
  labels: "confluence,jira,atlassian,forge,onboarding,rovo,agent"
  maintainer: amoore
  namespace: cloud

Forge onboarding

Help the user ship and use an app while learning the manifest, module, and backend function. The default journey has two loops: deploy the stock Rovo Agent, then customize the same registered app into Forge Guru. Adapt the teaching pace to the user.

Load guidance by phase

Read only the reference for the current phase, plus any reference it conditionally requires. Do not preload the entire journey, README, assets, or evaluation cases. Use these stable phase names in state and transitions; do not depend on numbered steps.

| Phase | Read when | Reference | Evidence to advance | | --- | --- | --- | --- | | `welcome` | Starting a new guided session | Use the short welcome below | User is ready, or has already asked to start | | `setup` | Prerequisites are unknown or a tool fails | [Setup](references/setup.md) | Tools and authentication work; warnings are distinguished from blockers | | `orientation` | User wants introductory teaching | [Mental model](references/mental-model.md) | Concepts explained, or user skips them | | `scaffold` | Choosing targets and registering an app | [Environment and scaffold](references/environment-and-scaffold.md) | Registered app and stock files verified | | `hello-world` | Walking through, deploying, and using the stock app | [Loop 1](references/loop-1-hello-world.md) | Deployment, target installation, and stock action observed | | `guru` | Customizing and deploying the docs companion | [Loop 2](references/loop-2-forge-guru.md) | Authorized edits verified, upgrade installed, response quality checked | | `next-steps` | Closing the tutorial | [Next steps](references/next-steps.md) | Outcome and relevant next route explained | | Recovery | An observed failure needs investigation | [Recovery](references/recovery.md) | Failure resolved or concrete blocker reported | | Platform check | A phase needs current CLI, schema, or endpoint facts | [Platform contract](references/platform-contract.md) | Relevant fact verified and evidence recorded |

Default transition: `welcome → setup → orientation → scaffold → hello-world → guru → next-steps`. Recovery returns to the interrupted phase. An exit stops the workflow immediately.

Keep a compact session record

Retain these values in conversation context, updating them after meaningful actions:

| State | Record | | --- | --- | | Position | Phase, last completed action, next action, requested teaching pace | | Local environment | OS/shell, Node and CLI versions, authentication result, accepted warnings | | Local target | Absolute parent directory and app path; whether destination existed before creation | | Atlassian target | Account, Developer Space name/ID, exact site, product, environment | | Identity | Registered `app.id`, runtime, actual agent key/name, handler and action names | | Progress | Scaffold verified; edits applied; dependencies installed; lint result; deployments and installs confirmed | | Live evidence | Stock action observed; Guru response and whether it used search or fallback | | Authorization | Exact approved actions, targets and impacts; terms consent separate from creation |

Do not store credentials. Do not create a progress file unless the user requests one. Record consent as an action and target, not a blanket permission for future commands.

Skip, exit, and resume

• Honor "skip setup", "skip to Loop 1", "less explanation", and "exit".
• Skip introductions, conceptual lessons, and file walkthroughs when requested. Do not repeat

a ready-check when the user has already said to proceed.

• When skipping setup, reuse known results. Run only missing checks needed for the next

command. A version warning is not a failed executable: explain it once and honor the user's choice to continue if the tools run.

• Collect targets when needed. Creation needs a directory and Developer Space; installation

needs a site. A missing site need not block scaffolding.

• The stock live-action checkpoint is the default. If explicitly skipped, mark it unverified

and continue with authorized customization; do not claim it was observed.

• Skipping teaching does not supply credentials, select ambiguous targets, accept terms,

or authorize deployment or installation.

• On exit, stop tools and questions. Briefly state what changed and what remains, using

recorded evidence. Do not keep offering the next tutorial step.

• On resume, reuse context and inspect the app. Check identity and installation as relevant.

Never rerun creation over an existing app or replay completed edits, installs, consent, or lessons without a reason.

• Without a session record, infer progress from read-only inspection and ask only about

unresolved choices. Directory existence alone does not prove a valid scaffold.

Preserve execution boundaries

1. Explain each imminent command briefly, including its effect. Batch explanations for independent checks. Report observed results rather than anticipated success. 2. Keep secrets out of chat and files. Login and unexpected credential prompts go to the user's interactive terminal; never ask them to paste an API token here. 3. Before creation, provisioning, deployment, installation, or upgrade, resolve the action and target and show its effects. Reuse explicit authorization for that same scope; otherwise ask. Local walkthroughs and read-only checks need no extra gate. 4. Terms and billing consent are separate from "build my app". The sibling creation helper currently pas