Merge pull request #19 from atlassian/tkallady/app-builder-rework

Update app-builder-skill

Author: dpeach-jpg

skills/forge-app-builder/SKILL.md

@@ -0,0 +1,11 @@
+interface:
+  display_name: "Forge App Builder"
+  short_description: "Plan, build, and extend Forge apps safely"
+  default_prompt: "Use $forge-app-builder to route, plan, and implement this Forge app request using only the relevant current documentation."
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "forge"
+      description: "Current Atlassian Forge guides, modules, manifests, and documentation search"
+      transport: "streamable_http"
+      url: "https://mcp.atlassian.com/v1/forge/mcp"

skills/forge-app-builder/agents/openai.yaml

@@ -0,0 +1,21 @@
+modules:
+  jira:issuePanel:
+    - key: customer-summary-panel
+      resource: main
+      resolver:
+        function: resolver
+      render: native
+      title: Customer summary
+  function:
+    - key: resolver
+      handler: index.handler
+resources:
+  - key: main
+    path: src/frontend.jsx
+permissions:
+  scopes:
+    - read:jira-work
+app:
+  runtime:
+    name: nodejs22.x
+  id: ari:cloud:ecosystem::app/example-fixture

skills/forge-app-builder/evals/evals.json

@@ -0,0 +1,14 @@
+{
+  "name": "existing-ui-kit-fixture",
+  "private": true,
+  "scripts": {
+    "test": "jest"
+  },
+  "dependencies": {
+    "@forge/api": "^5.0.0",
+    "@forge/bridge": "^5.0.0",
+    "@forge/react": "^11.0.0",
+    "@forge/resolver": "^1.6.0",
+    "react": "^18.2.0"
+  }
+}

skills/forge-app-builder/evals/fixtures/existing-ui-kit-app/manifest.yml

@@ -0,0 +1,13 @@
+import React, { useEffect, useState } from 'react';
+import ForgeReconciler, { Text } from '@forge/react';
+import { invoke } from '@forge/bridge';
+
+const App = () => {
+  const [summary, setSummary] = useState('Loading');
+  useEffect(() => {
+    invoke('get-summary').then(setSummary);
+  }, []);
+  return <Text>{summary}</Text>;
+};
+
+ForgeReconciler.render(<App />);

skills/forge-app-builder/evals/fixtures/existing-ui-kit-app/package.json

@@ -0,0 +1,6 @@
+import Resolver from '@forge/resolver';
+
+const resolver = new Resolver();
+resolver.define('get-summary', async () => 'Existing summary');
+
+export const handler = resolver.getDefinitions();

skills/forge-app-builder/evals/fixtures/existing-ui-kit-app/src/frontend.jsx

@@ -0,0 +1,19 @@
+# APIs, permissions, and egress
+
+Read this reference when calling or exposing Atlassian, Forge app, or external APIs, changing authorization context, scopes, providers, remotes, endpoints, content permissions, or egress.
+
+Retrieve the exact current endpoint and permission documentation needed by the implementation. Choose user or app context according to whose authority the operation should use; protect app-context operations with appropriate backend authorization.
+
+For external systems, select a supported integration pattern from current documentation. Distinguish outbound fetch or OAuth, Forge Remote, web triggers, and Forge app REST APIs; check lifecycle status and caller authentication rather than treating them as interchangeable. Account for credentials, egress, data residency, eligibility, and installation or version effects when they apply.
+
+Use least-privilege scopes and narrowly necessary egress. Treat display conditions as presentation only. Keep tokens and runtime secrets out of manifests, frontend code, repositories, and chat.
+
+Official entries:
+
+- Permissions: <https://developer.atlassian.com/platform/forge/manifest-reference/permissions/>
+- Atlassian app APIs: <https://developer.atlassian.com/platform/forge/apis-reference/product-rest-api-reference/>
+- Forge app REST APIs: <https://developer.atlassian.com/platform/forge/app-rest-apis/>
+- External authentication: <https://developer.atlassian.com/platform/forge/use-an-external-oauth-2.0-api-with-fetch/>
+- Remotes: <https://developer.atlassian.com/platform/forge/manifest-reference/remotes/>
+- App context security: <https://developer.atlassian.com/platform/forge/app-context-security/>
+- Security: <https://developer.atlassian.com/platform/forge/security/>

skills/forge-app-builder/evals/fixtures/existing-ui-kit-app/src/index.js

@@ -0,0 +1,18 @@
+# Backend and events
+
+Read this reference for resolvers, functions, lifecycle events, product events, scheduled triggers, queues, async work, web triggers, Forge app REST APIs, realtime, or runtime services.
+
+Choose the execution model that fits the requested behavior and selected module. Retrieve the exact current function, event, runtime, and limit documentation that can affect the design, such as invocation context, delivery semantics, retries, timeouts, or concurrency.
+
+Account for authorization, tenant isolation, idempotency, and observability where the execution model makes them relevant. Treat every externally reachable entry point as an explicit authentication and lifecycle decision. Add useful failure telemetry without logging secrets or unnecessary end-user data.
+
+Official entries:
+
+- Functions: <https://developer.atlassian.com/platform/forge/function-reference/>
+- Resolver: <https://developer.atlassian.com/platform/forge/runtime-reference/forge-resolver/>
+- Events: <https://developer.atlassian.com/platform/forge/events/>
+- Forge app REST APIs: <https://developer.atlassian.com/platform/forge/app-rest-apis/>
+- Realtime: <https://developer.atlassian.com/platform/forge/realtime/>
+- Runtime: <https://developer.atlassian.com/platform/forge/runtime-reference/>
+- Limits: <https://developer.atlassian.com/platform/forge/platform-quotas-and-limits/>
+- Observability: <https://developer.atlassian.com/platform/forge/observability/>

skills/forge-app-builder/references/apis-permissions-and-egress.md

@@ -0,0 +1,64 @@
+# Create a new app
+
+Read this reference only for a new deployable Forge app.
+
+## Decide before scaffolding
+
+Resolve enough of the architecture to choose an appropriate current scaffold. Retrieve the exact module and scaffolding documentation before selecting a template.
+
+Check prerequisites only when creation is imminent. Retrieve current requirements, then inspect Node.js, Forge CLI, and authentication state. If login is required, direct the user to run `forge login` interactively without sharing credentials.
+
+Confirm the destination, app name, and Developer Space. If multiple spaces are available, require the user to choose. If one is available, inform the user before using it. Explain that `forge create` registers an external app identity in the selected Developer Space.
+
+Immediately before non-interactive creation, show that the helper passes the current CLI option for accepting Forge terms and any applicable billing consent, then obtain explicit authorization. Do not invoke the helper without that authorization. If authorization is absent, let the user complete the current interactive `forge create` flow; never accept terms on the user's behalf.
+
+## Choose one scaffold branch
+
+### Stable template-first branch
+
+Prefer a current module-specific `forge create` template when it cleanly matches the architecture. Use `scripts.create_forge_app` with the current documented template name. Do not use an undocumented registry as an independent source of truth.
+
+Run the helper from the skill directory:
+
+```bash
+python3 -m scripts.list_templates --validate <current-documented-template>
+
+python3 -m scripts.create_forge_app \
+  --template <current-documented-template> \
+  --name <app-name> \
+  --dev-space-id <selected-id> \
+  --directory <parent-directory>
+```
+
+### Compositional branch
+
+Consider a blank `forge create` app when the app needs several modules, no suitable stable template exists, or deliberate module composition is clearer.
+
+```bash
+python3 -m scripts.create_forge_app \
+  --template blank \
+  --name <app-name> \
+  --dev-space-id <selected-id> \
+  --directory <parent-directory>
+```
+
+Before using `forge module add`, retrieve its current lifecycle and CLI documentation. If it is non-GA, obtain agreement to that exposure. Inspect `forge module add --dry-run` before applying changes, and never use `--force` without explicit approval for the specific overwrites or dependency upgrades.
+
+Official entries:
+
+- `forge create`: <https://developer.atlassian.com/platform/forge/cli-reference/create/>
+- Developer Spaces: <https://developer.atlassian.com/platform/forge/developer-space/create-developer-space/>
+- Module command tutorial: <https://developer.atlassian.com/platform/forge/build-a-jira-app-with-the-module-command/>
+- `forge module add`: <https://developer.atlassian.com/platform/forge/cli-reference/module-add/>
+
+## Handle creation failure
+
+Show the complete failure and triage it by cause:
+
+- If the CLI requires interaction, provide the exact current interactive `forge create` command for the user to run in their terminal.
+- If no Developer Space exists, direct the user to create one in the Atlassian developer console, then retry after they confirm the target.
+- If the destination already exists, use a different confirmed name or destination. Never delete or overwrite the existing directory without explicit authorization.
+- If authentication is missing or expired, direct the user to run `forge login` interactively without sharing credentials, then retry.
+- For any other failure, preserve the command output, retrieve the relevant current documentation, and explain what blocks creation before asking for the input or external change needed to continue.
+
+Never construct a replacement app ID or manual scaffold. Route to `forge-debugger` if diagnosis of a persistent failure becomes the primary task.