Journey Template

Journey Template Skill

Generate a complete agentic journey from a user's app idea. A journey is a hands-on learning experience where developers use GitHub Copilot (CLI, app, or IDE) to build and deploy an app to Azure.

Curriculum packaging (required)

Every journey README must include:

• No journey-sequence or learning-path numbering such as "Journey 2 of 5" — journeys are self-contained. Numbered phases and steps inside one journey are encouraged when they clarify the flow.
• Honest first-run time + cost if left running + same-day teardown
• Done when checklist with concrete manual verification steps
• Full-stack: one-line default stack at the first generate prompt (not a defaults table); put stack details in PLAN.md
• Plugin commands: only microsoft/azure-skills / azure@azure-skills
• What's Next uses plain links to related journeys, not prescribed-path or completion language
• OSS: shared deploy recipe (location, secrets, probes, resolve issues, issues.md)
• An isolated-workspace setup prompt that copies the journey, .github/agents, .github/skills, .github/scripts, and docs without modifying the source repository
• A prerequisite table, concrete local/Azure acceptance criteria, and a reusable exact-error recovery prompt
• A prompt that creates every generated verifier or diagnostic script before the README tells the learner to run it
• A read-only pre-deployment review with READY/NOT READY, PASS/FAIL evidence, and fail-closed blockers
• Agent-led azd environment preparation, followed by the learner running the consequential azd up command
• No checked-in journey issues.md: prompts create it only in the isolated learner workspace when a real issue occurs

Update root README.md learning path + journey table when adding a journey.

Journey Types

| Dimension | Full-Stack (e.g. AIMarket) | OSS Deployment (e.g. n8n, Grafana, Superset) | |-----------|---------------------------|----------------------------------------------| | What the learner does | Builds an app from scratch with GitHub Copilot | Deploys an existing OSS app via @oss-to-azure-deployer agent | | Files generated | README.md + PLAN.md | README.md + app-specific skill in .github/skills/ | | README structure | "The Journey" with 3-5 phases (adapt to app complexity) | "Deploy with the Agent" with 3 steps (Setup → Deploy → Verify) | | Images | 4-6 (one per phase boundary) | 2 (hero + deployment) | | Unique sections | "The Spec", "How Agentic AI is Used", one-line default stack at first prompt | "Configuration Reference", "Key Learnings", skip rules if expensive | | Compute target | Container Apps, App Service, Functions, Static Web Apps, AKS | Container Apps, AKS, App Service |

Output Structure

journeys//
├── README.md          # Learner-facing walkthrough
├── PLAN.md            # AI-readable spec (full-stack journeys only)
└── images/            # Generated images (added separately)

For OSS deployment journeys, also create an app-specific skill:

.github/skills/-azure/
├── SKILL.md              # Overview, quick start, architecture, verification
├── config/
│   ├── environment-variables.md
│   └── health-probes.md
└── troubleshooting.md

The SKILL.md needs YAML frontmatter:

---
name: -azure
description: Deploy  to Azure. Use when deploying  for .
---

OSS Skill SKILL.md Structure

The skill is what the @oss-to-azure-deployer agent reads. Follow this section order (reference n8n-azure as the primary example):

1. Overview / When to Use — one paragraph
2. Critical: Infrastructure Generation — infrastructure is generated fresh each deployment via azure-prepare plugin, NOT committed to the repo
3. Critical: Subscription Context — read the value with az account show --query id -o tsv, then pass it to azd env set AZURE_SUBSCRIPTION_ID without shell command substitution
4. Critical: \ — the #1 deployment failure cause (e.g., PostgreSQL SKU needs both name AND tier; Bicep outputs MUST use SCREAMINGSNAKECASE)
5. Official Documentation — link to app's docs
6. Quick Start (Verified) — exact prompt sequence, tested and confirmed
7. Key Configuration Files — table pointing to config/environment-variables.md, config/health-probes.md, troubleshooting.md
8. Architecture — Mermaid diagram of Azure resources
9. App-Specific Requirements — database, networking, storage, ports
10. Cost Estimate — table with SKUs and monthly costs
11. Verification Checklist — curl / az commands to confirm deployment
12. Tear Down — azd down --force --purge
13. Differences from Generic Patterns — what makes this app non-standard (startup timing, SSL, env vars, ports)

For AKS-based apps (like Superset), also include:

• references/kubernetes-manifests.md in the skill directory
• Default credentials section (e.g., admin/admin)
• "Why AKS Instead of Container Apps?" justification in the README
• Resource requirements table (CPU/Memory per pod)

---

README.md Template

Every journey README MUST follow this exact structure. Reference journeys/aimarket/README.md for a full-stack example and journeys/n8n/README.md for an OSS deployment example.

Required Sections (in order)

#  - 

> ✨ ****

  .jpg" alt="" width="800" />

## Learning Objectives

- 

> 💰 **Estimated Cost**: ~$X-Y/month ( — see [Cost Breakdown](#cost-breakdown)). **Clean up with `azd down` when done!**

## Prerequisites

### Acceptance criteria

---

## Architecture

**Azure resources created:**

- **Resource** — what it does

---

## Deploy with the Agent / The Journey

### Step 1: Setup

```bash
copilot

Once inside the interactive session, add the marketplace (first time only):

> /plugin marketplace add microsoft/azure-skills

Then install the plugin:

> /plugin install azure@azure-skills

> Already installed? If you completed the root [Quick Start](../../../README.md#quick-start) (or already installed azure@azure-skills), skip the install commands — the plugin persists across sessions. > Canonical only: microsoft/azure-skills — never document alternate marketplace names.

After installation, include a prompt that asks the agent to confirm which Azure Skills and MCP tools are available in the current session. Stop before Azure-file generation if the plugin is unavailable.

> /agent

Select oss-to-azure-deployer from the list.

Step 2: Deploy

Step 3: Verify

---

Configuration Reference (OSS journeys only — full-stack journeys put this in PLAN.md)

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | ... | Yes/No | ... |

Container Resources

| Setting | Value | Notes | |---------|-------|-------| | CPU | 0.5 | ... | | Memory | 1Gi | ... |

Health Probes

| Probe | Path | Timing | |-------|------|--------| | Liveness | /api/health | initialDelay: 30s, period: 10s | | Startup | /api/health | failureThreshold: 10, period: 10s |

---

Cost Breakdown

| Resource | SKU | Monthly Cost | |----------|-----|--------------| | ... | ... | ~$X | | Total | | ~$X-Y/month |

Use human-readable SKU names (e.g., "Pay-per-GB" not "PerGB2018").

---

Troubleshooting

Cause:

Fix:

Separate deployment errors from post-deployment usage issues with: > Post-Deployment Issues: The following issues relate to using the app after deployment, not the deployment itself.

---

Verification Checklist

---

Cleanup

> ⚠️ Confirm the selected azd environment belongs to this journey. Save RESOURCE_GROUP_NAME before teardown so deletion can be verified without guessing.

azd down --force --purge

Require successful exit, then verify the exact resource group no longer exists with az group exists --name returning false. Include resource-specific soft-delete purge guidance only when the architecture needs it.

---

Key Learnings

---

Assignment

---

What's Next

---

Resources

### Structural Variations by Journey Type

**OSS deployment journeys** use the base template as-is. Section order:

`Deploy with the Agent` (3 steps) → `Configuration Reference` → `Cost Breakdown` → `Troubleshooting` → `Verification Checklist` → `Cleanup` → `Key Learnings` → `Assignment` → `What's Next` → `Resources`

**Full-stack journeys** replace several sections:

| Base Template Section | Full-Stack Replacement |
|----------------------|----------------------|
| `Deploy with the Agent` (3 steps) | `The Journey` with app-specific numbered phases that end in Deploy |
| `Configuration Reference` | Omit — specs live in PLAN.md |
| `Key Learnings` | `How Agentic AI is Used` — table of agentic use cases |

Full-stack and from-plan static-web journeys also add:
- **"The Spec"** section after Architecture — links to PLAN.md and explains that it is shared implementation context
- **Phase-level images** — one image at each phase boundary (e.g., spec-to-code, testing, deployment)
- **Teaching markers** within each phase (🔍 Inspect, 💡 What you're learning, 🧪 Test it yourself)
- **Incremental prompts** that generate, inspect, test, and refine one bounded layer at a time
- **Generated-script provenance**: the README prompt must create a verifier or diagnostic before any command runs that path
- **Deployment handoff**: use the agent plus Azure Skills for preparation and review, but have the learner run `azd up` and observe its real output
- A cloud-agent/delegation option only when it teaches a real, self-contained asynchronous task; do not force two deployment options into every journey

For mobile frontends (iOS/Android), note in the README:
- Backend is deployed to Azure with `azd up`; mobile app runs locally or via TestFlight / Play Store internal testing
- API URL must be configurable (not hardcoded) — use environment config or build schemes
- Mobile app is NOT deployed by azd — only the Azure backend is
- Include device testing instructions (simulator/emulator + physical device)

For AKS deployments (e.g., Superset), add:
- **"Why AKS Instead of Container Apps?"** section after Architecture with architectural justification
- **AKS run-command verification** through `az aks command invoke`, not a local `kubectl` dependency
- **Complexity note** in the opening when the deployment is long-running or multi-step

For API-only journeys (no frontend):
- Omit Phase 2 entirely — journey goes straight from API/Backend to Deploy
- Remove `web` service from azure.yaml — single service only
- Skip the frontend rebuild step in the deployment flow
- Verification is curl/API testing only

### Emoji Conventions

Use consistently throughout all journeys:

| Emoji | Usage |
|-------|-------|
| ✨ | Tagline hook (one per journey) |
| 💰 | Cost estimate |
| 📋 | Prerequisites |
| 🔍 | Inspect what was generated (full-stack only) |
| 💡 | Meta-learning insight (full-stack only) |
| 🧪 | Test it yourself (full-stack only) |
| ⚠️ | Warning or critical note |

---

## PLAN.md Template (Full-Stack and From-Plan Journeys)

The PLAN.md is a spec document that GitHub Copilot reads to generate code. It is not tutorial content, but the learner should open it, understand the finished behavior, and keep it available as shared context. README prompts must cite exact PLAN section names; rename both in the same change. Reference current AIMarket and SmartTodo PLANs for examples.

### Required Sections

```markdown
# :  — Spec

. This document is the spec — GitHub Copilot reads it to generate the implementation.

**Out of scope:** 

---

## Choose Your Stack

| | Node.js | Python | .NET | Java |
|---|---------|--------|------|------|
| **Framework** | Express + TypeScript | FastAPI | ASP.NET Core Minimal APIs | Spring Boot |
| **Database** | `better-sqlite3` | `sqlite3` (stdlib) | `Microsoft.Data.Sqlite` | `JdbcTemplate` + SQLite |

Frontend: React, Angular, Vue, Swift/SwiftUI (iOS), Kotlin/Jetpack Compose (Android), React Native, Flutter, or none for API-only journeys. Deploy backend with **azd** + **Bicep using Azure Verified Modules (AVM)**.

## Project Structure

## Phase 1: API / Backend
### Data Access Layer (repository pattern — interfaces → implementations → factory)
### Data Models (with field types, constraints, and validation)
### Endpoints (with request/response JSON examples — VALIDATE ALL JSON IS VALID)
### Error Response Format (status codes, error codes, response schema)
### Seed Data (exact IDs, descriptions, image URLs)

## Phase 2: Frontend / Mobile Client (omit for API-only apps)
### Pages/Screens and Components
### State Management
### API Client
### Platform-Specific Notes (mobile only — Xcode setup, Android Studio, signing, etc.)

## Phase 3: AI Features (omit if not applicable)
### AI Feature 1: 
### AI Feature 2: 
### Environment Variables

## Phase N (final): Deploy to Azure
### Containerization (Dockerfiles, or Functions/App Service config if serverless)
### Azure Resources (AVM modules — list each resource with its module path)
### Bicep Requirements (list every deployment gotcha discovered during testing)
### Deployment (two-stage flow if frontend needs API URL at build time)
### Mobile Distribution (mobile only — TestFlight, Google Play internal testing, API URL configuration)
### Known Deployment Gotchas (document real failures — soft-deleted resources, SKU issues, etc.)

Key rules for PLAN.md:

• Validate ALL JSON — every request/response example must be valid JSON (check closing brackets)
• Seed data must be complete — exact IDs, names, descriptions, prices, image URLs
• Error format — specify the exact error response schema the API should return
• Deployment gotchas — document every real failure encountered during testing with the fix
• Model references — make primary/fallback models journey-specific, verify regional availability, and document model-specific request constraints
• Data access — if the app supports multiple database backends, reference the data-access-abstraction skill for the repository pattern
• Stable headings — README prompts reference exact PLAN section names; rename both in the same change
• Resolve source contradictions — when adapting an external plan, state the chosen behavior instead of carrying conflicting decisions into prompts
• No phantom scripts — PLAN and README state who creates each generated script, where it lands, and what it verifies

---

Deployment Patterns

azure.yaml Structure

name: 
metadata:
  template: @0.0.1
services:
  api:
    project: ./api
    host: containerapp
    language: ts
    docker:
      path: ./Dockerfile
  web:
    project: ./client
    host: containerapp
    language: ts
    docker:
      path: ./Dockerfile
infra:
  provider: bicep
  path: ./infra

Supported host values: containerapp, aks, appservice, function, staticwebapp, springapp. Choose based on your app's compute needs.

Static Web Apps Pattern

For a browser-only static journey, keep the deployment small:

services:
  web:
    project: .
    language: js
    host: staticwebapp
    dist: dist

• Prefer br/public:avm/res/web/static-site; fall back to raw Microsoft.Web/staticSites@2023-12-01 only when current AVM inputs block a working deployment, and record why.
• Tag the resource with azd-service-name: web and output WEB_URL, STATIC_WEB_APP_NAME, and RESOURCE_GROUP_NAME.
• Use Free SKU and provider: Custom when azd deploys directly. Do not create a deployment token or GitHub Actions workflow unless CI/CD is an explicit lesson.
• Static Web Apps has a narrower region list than resource groups. Normalize an unsupported request to a documented supported location such as eastus2.
• Use staticwebapp.config.json for navigation fallback and security headers.
• Azure Developer CLI rejects a Static Web App whose source and output folder both res

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: microsoft
• Source: microsoft/agentic-journeys
• License: MIT

Install and usage instructions live in the source repository linked above.