diff --git a/.github/workflows/site-infra.yml b/.github/workflows/site-infra.yml new file mode 100644 index 0000000..7a1b436 --- /dev/null +++ b/.github/workflows/site-infra.yml @@ -0,0 +1,26 @@ +name: site-infra + +on: + push: + branches: [main] + paths: ['site/infra/**', '.github/workflows/site-infra.yml'] + pull_request: + paths: ['site/infra/**', '.github/workflows/site-infra.yml'] + +permissions: + contents: read + +jobs: + terraform-check: + runs-on: ubuntu-24.04 + defaults: + run: + working-directory: site/infra + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: hashicorp/setup-terraform@dfe3c3f87815947d99a8997f908cb6525fc44e9e # v4.0.1 + with: + terraform_version: 1.12.2 + - run: terraform fmt -check -recursive + - run: terraform init -backend=false + - run: terraform validate diff --git a/.github/workflows/site.yml b/.github/workflows/site.yml new file mode 100644 index 0000000..c1762d7 --- /dev/null +++ b/.github/workflows/site.yml @@ -0,0 +1,98 @@ +name: site + +on: + push: + branches: [main] + paths: + - '**/*.md' + - 'images/**' + - '**/images/**' + - 'the-broken-apps/**' + - 'the-observer/**' + - 'k8s-terraform/**' + - 'site/**' + - '.github/workflows/site.yml' + pull_request: + types: [opened, synchronize, reopened, closed] + paths: + - '**/*.md' + - 'images/**' + - '**/images/**' + - 'the-broken-apps/**' + - 'the-observer/**' + - 'k8s-terraform/**' + - 'site/**' + - '.github/workflows/site.yml' + +permissions: + contents: read + +concurrency: + group: site-${{ github.ref }} + cancel-in-progress: true + +jobs: + build-test: + if: github.event_name == 'push' || github.event.action != 'closed' + runs-on: ubuntu-24.04 + defaults: + run: + working-directory: site + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 + with: + node-version: '22.22.3' + cache: npm + cache-dependency-path: site/package-lock.json + - run: npm ci + - run: npm test + - run: npm run check + - run: npm run build + - run: npx playwright install --with-deps chromium + - run: npx playwright test + - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 + with: + name: site-dist + path: site/dist + if-no-files-found: error + + deploy: + needs: build-test + # Fork PRs have no access to secrets, so they build and test but don't deploy. + if: >- + github.event_name == 'push' || + (github.event.action != 'closed' && github.event.pull_request.head.repo.full_name == github.repository) + runs-on: ubuntu-24.04 + permissions: + contents: read + pull-requests: write + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 + with: + name: site-dist + path: site/dist + - uses: Azure/static-web-apps-deploy@4d27395796ac319302594769cfe812bd207490b1 # v1 + with: + azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }} + repo_token: ${{ secrets.GITHUB_TOKEN }} + action: upload + app_location: site/dist + skip_app_build: true + skip_api_build: true + + close-preview: + if: >- + github.event_name == 'pull_request' && github.event.action == 'closed' && + github.event.pull_request.head.repo.full_name == github.repository + runs-on: ubuntu-24.04 + permissions: + pull-requests: write + steps: + - uses: Azure/static-web-apps-deploy@4d27395796ac319302594769cfe812bd207490b1 # v1 + with: + azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }} + action: close diff --git a/.gitignore b/.gitignore index 71eadfc..b4cdd11 100644 --- a/.gitignore +++ b/.gitignore @@ -29,4 +29,13 @@ override.tf.json # !example_override.tf # Include tfplan files to ignore the plan output of command: terraform plan -out=tfplan -# example: *tfplan* \ No newline at end of file +# example: *tfplan* +# Agentic Field Guide site +.superpowers/ +site/node_modules/ +site/dist/ +site/.astro/ +site/test-results/ +site/playwright-report/ +site/infra/.terraform/ +site/infra/tfplan diff --git a/README.md b/README.md index 9aa6625..64347bd 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,12 @@ # Agentic AI The Hard Way +Prefer reading in a browser? Visit [agenticfieldguide.ai](https://agenticfieldguide.ai). + This tutorial contains four full, real-world scenarios for Agentic AI. As the industry moves from more of a GenAI mindset to an autonomous/Agentic AI way of thinking, having a few key scenarios that engineers can use to not only learn about Agentic AI, but get ideas on what they can implement with be the new need. **PLEASE NOTE:** This is currently a WIP and was started on 1/4/2026. If you click a link and it doesn't work or is blank, that is because this project is still being worked on. -![](images/banner.png) +![Agentic AI workloads architecture: AI agent, orchestrator, and task execution with feedback and human-in-the-loop review](images/banner.png) ## The Scenarios diff --git a/docs/superpowers/plans/2026-10-04-agentic-field-guide-site.md b/docs/superpowers/plans/2026-10-04-agentic-field-guide-site.md new file mode 100644 index 0000000..ead2a86 --- /dev/null +++ b/docs/superpowers/plans/2026-10-04-agentic-field-guide-site.md @@ -0,0 +1,4024 @@ +# Agentic Field Guide Website Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Build a static, interactive website for this repo's labs (branded Agentic Field Guide) from the repo's own markdown, and host it on Azure Static Web Apps at `agenticfieldguide.ai`. + +**Architecture:** An Astro 7 project in `site/` reads every lab `.md` file in place, using the content glob loader with `base: '..'`. It reads `README.md` to build the navigation. Three remark plugins: +- Rewrite GitHub links to site routes. +- Turn code blocks into HTML with `$VARS` marked. +- Demote markdown H1s. + +Small client scripts add copy buttons, variable fill-in, search (Pagefind), the theme toggle, and the Rough.js arrow. After `astro build`, Node scripts run: +- Pagefind indexing. +- `staticwebapp.config.json` generation, with a CSP hash. +- An internal link check. + +Terraform in `site/infra/` creates the Static Web App, the Azure DNS zone, and the apex custom domain. GitHub Actions builds, tests, and deploys. + +**Tech Stack:** +- Site and markdown: Astro 7.3.5, `@astrojs/markdown-remark` 7.3.1, unified/remark-parse 11, Rough.js 4.6.6, Pagefind 1.5.2. +- Fonts: `@fontsource` Atkinson Hyperlegible and IBM Plex Mono, plus Excalifont, self-hosted. +- Tests and checks: Vitest 5.0.3, Playwright 1.63.0, TypeScript 6.0.3. +- Infrastructure: Terraform ≥1.12 with azurerm 5.8.0, GitHub Actions. + +**Spec:** `docs/superpowers/specs/2026-10-04-agentic-field-guide-site-design.md` + +**Deviations from the spec (deliberate, small):** +1. The CSP `script-src` adds `'wasm-unsafe-eval'`, because Pagefind runs as WebAssembly (Task 12). +2. Terraform checks live in a separate workflow, `site-infra.yml` (Task 15). +3. Rough.js draws only the home-page flow arrow. Box outlines use the CSS irregular `border-radius` that the spec already uses for static boxes, which works without JavaScript (Tasks 8 and 11). + +## Global Constraints + +**Toolchain and versions** +- Node `>=22.12.0`. All npm dependencies are installed with `--save-exact`, and `site/package-lock.json` is committed. +- TypeScript is pinned to **6.0.3**. `@astrojs/check` 0.9.10 requires `^5 || ^6`; do not use TypeScript 7. +- Astro 7 uses Sätteri as its default markdown engine. Remark plugins only work with **`@astrojs/markdown-remark`** installed (verified 2026-10-04). +- Every npm/Make command runs **from `site/`**. Code finds the repo with `path.resolve(process.cwd(), '..')`. + +**Routing** +- Routes mirror repo paths, with a trailing slash: `a/b.md` → `/a/b/`; folder `a/b` → `/a/b/`. +- `trailingSlash: 'always'` and `build.format: 'directory'`. +- Only `https://github.com/AdminTurnedDevOps/Agentic-AI-The-Hard-Way/(blob|tree)/main/...` links and relative `.md` links are rewritten. Every other URL stays external. + +**CSP and markup** +- No inline `