github · pelikhan · Dec 8, 2025 · Dec 8, 2025 · Dec 8, 2025 · Dec 8, 2025
diff --git a/.github/workflows/release.lock.yml b/.github/workflows/release.lock.yml
diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx
@@ -42,6 +42,26 @@ import FeatureGrid from '../../components/FeatureGrid.astro';
   }
 `}</style>
 
+## What are Agentic Workflows?
+
+**Agentic workflows** are AI-powered automation that can understand context, make decisions, and take meaningful actions—all from natural language instructions you write in markdown.
+
+Unlike traditional automation with fixed if-then rules, agentic workflows use AI agents (like GitHub Copilot) to:
+- **Understand context**: Read your repository, issues, and pull requests to grasp the current situation
+- **Make decisions**: Choose appropriate actions based on the context, not just predefined conditions
+- **Adapt behavior**: Respond flexibly to different scenarios without requiring explicit programming for each case
+
+For example, instead of writing complex scripts to triage issues, you simply describe what you want: "Analyze this issue and ask for clarification if details are missing." The AI agent reads the issue, understands what information is needed, and generates an appropriate response.
+
+**From this** (natural language):
+```markdown
+When an issue is opened, analyze it and ask for 
+clarification if important details are missing.
+```
+
+**To automated action**: The AI reads the issue, determines what's missing, and posts a helpful comment requesting specific information—adapting its response to each unique issue.
+
+This is "agentic" because the AI acts as an intelligent agent with agency to make context-aware decisions, rather than just executing predefined steps.
 
 ## Key Features
 

diff --git a/docs/src/content/docs/introduction/how-it-works.mdx b/docs/src/content/docs/introduction/how-it-works.mdx
@@ -5,7 +5,7 @@ sidebar:
   order: 2
 ---
 
-GitHub Agentic Workflows enable AI agents to perform complex, multi-step tasks automatically with your team. Built on [GitHub Actions](https://docs.github.com/en/actions), they use [**GitHub Copilot**](/gh-aw/reference/engines/#github-copilot-cli) (or experimental engines like Claude and Codex) to interpret natural language instructions and enable [Continuous AI](https://githubnext.com/projects/continuous-ai) — systematic, automated application of AI to software collaboration.
+GitHub Agentic Workflows enable AI [agents](/gh-aw/reference/glossary/#agent) (autonomous AI systems that can make decisions) to perform complex, multi-step tasks automatically with your team. Built on [GitHub Actions](https://docs.github.com/en/actions), they use [**GitHub Copilot**](/gh-aw/reference/engines/#github-copilot-cli) (or experimental engines like Claude and Codex) to interpret natural language instructions and enable [Continuous AI](https://githubnext.com/projects/continuous-ai) — systematic, automated application of AI to software collaboration.
 
 ## Workflow Structure
 
@@ -31,7 +31,9 @@ Workflows use [tools](/gh-aw/reference/tools/) through the **Model Context Proto
 
 ## Agentic vs. Traditional Workflows
 
-Traditional GitHub Actions execute pre-programmed steps. Agentic workflows use AI to understand context, make decisions, and generate content by interpreting natural language instructions flexibly, combining deterministic GitHub Actions steps with AI-driven instructions.
+**Traditional workflows** execute pre-programmed steps with fixed if/then logic. They do exactly what you tell them, every time, in the same way.
+
+**[Agentic workflows](/gh-aw/reference/glossary/#agentic)** use AI to understand context, make decisions, and generate content by interpreting natural language instructions flexibly. They combine deterministic GitHub Actions infrastructure with AI-driven decision-making, adapting their behavior based on the specific situation they encounter.
 
 ## Security Design
 

diff --git a/docs/src/content/docs/introduction/overview.mdx b/docs/src/content/docs/introduction/overview.mdx
@@ -27,7 +27,9 @@ safe-outputs:
 Analyze the current issue and ask for additional details if the issue is unclear.
 ```
 
-The `gh aw` cli compiles this into a [GitHub Actions Workflow](https://docs.github.com/en/actions/concepts/workflows-and-actions/workflows#about-workflows) (.yml) that runs an AI agent (Claude, Codex, ...) in a containerized environment whenever a new issue is opened in the repository. [Compilation](/gh-aw/reference/glossary/#compilation) (converting markdown to GitHub Actions YAML) ensures your workflow is secure and validated before it runs.
+The `gh aw compile` command transforms this markdown into a secure [GitHub Actions Workflow](https://docs.github.com/en/actions/concepts/workflows-and-actions/workflows#about-workflows) (`.lock.yml` file) that runs an AI agent in a containerized environment whenever a new issue is opened. 
+
+[Compilation](/gh-aw/reference/glossary/#compilation) (the process of converting markdown to GitHub Actions YAML) validates your configuration, applies security hardening, and generates the final workflow file that GitHub Actions can execute. Think of it like compiling code—you write human-friendly markdown, the compiler produces machine-ready YAML.
 
 The AI agent reads your repository context, understands the issue content, and takes appropriate actions - all defined in natural language rather than complex code.
 

diff --git a/docs/src/content/docs/labs.mdx b/docs/src/content/docs/labs.mdx
@@ -93,13 +93,18 @@ These are experimental agentic workflows used by the GitHub Next team to learn,
 | [Smoke Copilot](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/smoke-copilot.md) | copilot | [![Smoke Copilot](https://github.com/githubnext/gh-aw/actions/workflows/smoke-copilot.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/smoke-copilot.lock.yml) | `0 0,7,13,19 * * *` | - |
 | [Smoke Copilot No Firewall](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/smoke-copilot-no-firewall.md) | copilot | [![Smoke Copilot No Firewall](https://github.com/githubnext/gh-aw/actions/workflows/smoke-copilot-no-firewall.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/smoke-copilot-no-firewall.lock.yml) | `0 0,6,12,18 * * *` | - |
 | [Smoke Copilot Playwright](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/smoke-copilot-playwright.md) | copilot | [![Smoke Copilot Playwright](https://github.com/githubnext/gh-aw/actions/workflows/smoke-copilot-playwright.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/smoke-copilot-playwright.lock.yml) | `0 0,6,12,18 * * *` | - |
+| [Smoke Copilot Safe Inputs](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/smoke-copilot-safe-inputs.md) | copilot | [![Smoke Copilot Safe Inputs](https://github.com/githubnext/gh-aw/actions/workflows/smoke-copilot-safe-inputs.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/smoke-copilot-safe-inputs.lock.yml) | `0 0,7,13,19 * * *` | - |
 | [Smoke Detector - Smoke Test Failure Investigator](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/smoke-detector.md) | claude | [![Smoke Detector - Smoke Test Failure Investigator](https://github.com/githubnext/gh-aw/actions/workflows/smoke-detector.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/smoke-detector.lock.yml) | - | - |
 | [Smoke SRT](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/smoke-srt.md) | copilot | [![Smoke SRT](https://github.com/githubnext/gh-aw/actions/workflows/smoke-srt.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/smoke-srt.lock.yml) | - | - |
 | [Smoke SRT Custom Config](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/smoke-srt-custom-config.md) | copilot | [![Smoke SRT Custom Config](https://github.com/githubnext/gh-aw/actions/workflows/smoke-srt-custom-config.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/smoke-srt-custom-config.lock.yml) | - | - |
+| [Spec Kit Executor](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/spec-kit-executor.md) | copilot | [![Spec Kit Executor](https://github.com/githubnext/gh-aw/actions/workflows/spec-kit-executor.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/spec-kit-executor.lock.yml) | `0 8 * * *` | - |
+| [Spec-Kit Command Dispatcher](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/speckit-dispatcher.md) | copilot | [![Spec-Kit Command Dispatcher](https://github.com/githubnext/gh-aw/actions/workflows/speckit-dispatcher.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/speckit-dispatcher.lock.yml) | - | `/speckit` |
+| [Spec-Kit Execute](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/spec-kit-execute.md) | copilot | [![Spec-Kit Execute](https://github.com/githubnext/gh-aw/actions/workflows/spec-kit-execute.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/spec-kit-execute.lock.yml) | `0 */6 * * *` | - |
 | [Stale Repository Identifier](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/stale-repo-identifier.md) | copilot | [![Stale Repository Identifier](https://github.com/githubnext/gh-aw/actions/workflows/stale-repo-identifier.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/stale-repo-identifier.lock.yml) | `3 2 1 * *` | - |
 | [Static Analysis Report](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/static-analysis-report.md) | claude | [![Static Analysis Report](https://github.com/githubnext/gh-aw/actions/workflows/static-analysis-report.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/static-analysis-report.lock.yml) | `0 9 * * *` | - |
 | [Super Linter Report](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/super-linter.md) | copilot | [![Super Linter Report](https://github.com/githubnext/gh-aw/actions/workflows/super-linter.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/super-linter.lock.yml) | `0 14 * * 1-5` | - |
 | [Technical Doc Writer](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/technical-doc-writer.md) | copilot | [![Technical Doc Writer](https://github.com/githubnext/gh-aw/actions/workflows/technical-doc-writer.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/technical-doc-writer.lock.yml) | - | - |
+| [Test Expires Field](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/test-discussion-expires.md) | copilot | [![Test Expires Field](https://github.com/githubnext/gh-aw/actions/workflows/test-discussion-expires.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/test-discussion-expires.lock.yml) | - | - |
 | [The Daily Repository Chronicle](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/daily-repo-chronicle.md) | copilot | [![The Daily Repository Chronicle](https://github.com/githubnext/gh-aw/actions/workflows/daily-repo-chronicle.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/daily-repo-chronicle.lock.yml) | `0 16 * * 1-5` | - |
 | [Tidy](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/tidy.md) | copilot | [![Tidy](https://github.com/githubnext/gh-aw/actions/workflows/tidy.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/tidy.lock.yml) | - | - |
 | [Typist - Go Type Analysis](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/typist.md) | claude | [![Typist - Go Type Analysis](https://github.com/githubnext/gh-aw/actions/workflows/typist.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/typist.lock.yml) | `0 11 * * 1-5` | - |

diff --git a/docs/src/content/docs/reference/glossary.md b/docs/src/content/docs/reference/glossary.md
@@ -9,12 +9,32 @@ This glossary provides definitions for key technical terms and concepts used in
 
 ## Core Concepts
 
+### Agentic
+
+The term **"agentic"** means having agency—the ability to act independently, make context-aware decisions, and adapt behavior based on circumstances. When applied to workflows:
+
+- **Agentic workflows** use AI to understand context and choose appropriate actions, rather than just following predefined steps
+- **Agentic systems** can reason about situations and make informed decisions without explicit programming for every scenario
+- Contrasts with **deterministic** workflows that execute fixed sequences of actions
+
+The word comes from "agent" (an entity that acts on behalf of someone) + "-ic" (having the characteristics of).
+
 ### Agentic Workflow
 An AI-powered workflow that can reason, make decisions, and take autonomous actions using natural language instructions. Unlike traditional workflows with fixed if/then rules, agentic workflows interpret context and adapt their behavior based on the situation they encounter.
 
+**Key characteristics:**
+- Written in natural language markdown instead of complex YAML
+- Uses AI to understand repository context (issues, PRs, code)
+- Makes context-aware decisions without explicit conditionals
+- Adapts responses to different situations flexibly
+
+**Example:** Instead of "if issue has label X, do Y", you write "analyze this issue and provide helpful context", and the AI decides what's helpful based on the specific issue content.
+
 ### Agent
 The AI system (typically GitHub Copilot CLI) that executes natural language instructions in an agentic workflow. The agent interprets tasks, uses available tools, and generates outputs based on context.
 
+Think of the agent as an AI assistant with access to tools (GitHub API, file system, web search) that can understand your instructions and complete tasks autonomously. The agent is the "intelligence" that makes workflows agentic.
+
 ### Frontmatter
 The configuration section at the top of a workflow file, enclosed between `---` markers. Contains YAML settings that control when the workflow runs, what permissions it has, and what tools it can use. Separates technical configuration from natural language instructions.