diff --git a/.github/agents/technical-doc-writer.agent.md b/.github/agents/technical-doc-writer.agent.md index 4889fb2dd9..1269435924 100644 --- a/.github/agents/technical-doc-writer.agent.md +++ b/.github/agents/technical-doc-writer.agent.md @@ -85,6 +85,152 @@ Use GitHub alert syntax sparingly: - Anticipate pitfalls and explain fixes empathetically. - Use alerts only when necessary. +## Build and Validation Workflow + +**ALWAYS** follow this workflow before completing your work or returning to the user: + +### 1. Build the Documentation + +Run the build command from the repository root: +```bash +make build-docs +``` + +This command will: +- Install dependencies if needed (via `deps-docs`) +- Run prebuild scripts (generate agent factory, build slides) +- Build the Astro documentation +- Validate internal links +- Generate search indexes + +### 2. Review Build Output + +Check the build output for: +- **Errors**: Build failures, compilation errors +- **Warnings**: Link validation issues, deprecated features +- **Success messages**: Verify pages are built correctly + +### 3. Fix Build Issues + +If the build fails or has warnings, fix these common issues: + +**Link validation errors:** +- Fix broken internal links (use `/gh-aw/path/to/page/` format for Astro) +- Update relative links to use correct paths +- Ensure linked pages exist + +**Frontmatter issues:** +- Ensure all `.md` files have required `title` and `description` +- Fix YAML syntax errors in frontmatter +- Verify frontmatter fields are valid + +**Markdown syntax errors:** +- Fix malformed code blocks (ensure proper language tags) +- Check for unclosed tags or brackets +- Verify proper heading hierarchy + +**Missing assets:** +- Check that referenced images exist in `docs/src/assets/` or `docs/public/` +- Fix broken image paths +- Verify asset file names match references + +**Astro/Starlight configuration:** +- Verify sidebar configuration in `astro.config.mjs` +- Check component imports and paths +- Ensure content collections are properly defined + +### 4. Rebuild and Verify + +After fixing issues, rebuild to verify: +```bash +make build-docs +``` + +Check that: +- Build completes successfully without errors +- `docs/dist` directory is created and populated +- All pages are generated correctly +- Link validation passes + +### 5. Only Return When Build Succeeds + +**Do not return to the user until:** +- ✅ `make build-docs` completes successfully without errors +- ✅ All warnings are addressed or documented +- ✅ Built documentation in `docs/dist` is verified +- ✅ Links and navigation validate correctly + +## Available Build Commands + +Use these commands from the repository root: + +```bash +# Install documentation dependencies (Node.js 20+ required) +make deps-docs + +# Build the documentation (recommended before completing work) +make build-docs + +# Start development server for live preview at http://localhost:4321 +make dev-docs + +# Preview built documentation with production server +make preview-docs + +# Clean documentation artifacts (dist, node_modules, .astro) +make clean-docs +``` + +## Build Troubleshooting Guide + +### Common Build Errors and Solutions + +**Error: "Link validation failed"** +``` +Solution: Check for broken internal links and fix paths +``` + +**Error: "Missing frontmatter field"** +``` +Solution: Add required title and description to .md files +``` + +**Error: "Invalid markdown syntax"** +``` +Solution: Check code blocks, headings, and frontmatter YAML +``` + +**Error: "Module not found" or "Cannot find file"** +``` +Solution: Verify file paths and imports are correct +``` + +**Error: "Starlight plugin error"** +``` +Solution: Check astro.config.mjs for configuration issues +``` + +### Debugging Process + +1. **Read error messages carefully** - they usually indicate the exact issue +2. **Check the failing file** - look at the file mentioned in the error +3. **Fix the issue** - apply the appropriate solution +4. **Rebuild** - run `make build-docs` again to verify +5. **Repeat if needed** - continue until build succeeds + +### Development Server for Testing + +Use the development server to preview changes in real-time: +```bash +make dev-docs +``` + +This starts Astro dev server at http://localhost:4321 with: +- Hot module reloading +- Fast refresh for instant updates +- Live error reporting +- Interactive debugging + ## Example Document Skeleton ```md --- diff --git a/.github/workflows/repository-quality-improver.lock.yml b/.github/workflows/repository-quality-improver.lock.yml index 6fd6b4cb7b..41f0b5136d 100644 --- a/.github/workflows/repository-quality-improver.lock.yml +++ b/.github/workflows/repository-quality-improver.lock.yml @@ -29,7 +29,6 @@ name: "Repository Quality Improvement Agent" "on": schedule: - cron: "0 13 * * 1-5" - # Friendly format: daily (scattered) workflow_dispatch: permissions: diff --git a/.github/workflows/technical-doc-writer.lock.yml b/.github/workflows/technical-doc-writer.lock.yml index 3174f9a2e5..c6f5d6b47b 100644 --- a/.github/workflows/technical-doc-writer.lock.yml +++ b/.github/workflows/technical-doc-writer.lock.yml @@ -26,7 +26,7 @@ # - ../../skills/documentation/SKILL.md # - ../agents/technical-doc-writer.agent.md -name: "Technical Doc Writer" +name: "Rebuild the documentation after making changes" "on": workflow_dispatch: inputs: @@ -44,7 +44,7 @@ permissions: concurrency: group: "gh-aw-${{ github.workflow }}" -run-name: "Technical Doc Writer" +run-name: "Rebuild the documentation after making changes" jobs: activation: @@ -526,7 +526,7 @@ jobs: model: process.env.GH_AW_MODEL_AGENT_COPILOT || "", version: "", agent_version: "0.0.381", - workflow_name: "Technical Doc Writer", + workflow_name: "Rebuild the documentation after making changes", experimental: false, supports_tools_allowlist: true, supports_http_transport: true, @@ -890,6 +890,152 @@ jobs: - Anticipate pitfalls and explain fixes empathetically. - Use alerts only when necessary. + ## Build and Validation Workflow + + **ALWAYS** follow this workflow before completing your work or returning to the user: + + ### 1. Build the Documentation + + Run the build command from the repository root: + ```bash + make build-docs + ``` + + This command will: + - Install dependencies if needed (via `deps-docs`) + - Run prebuild scripts (generate agent factory, build slides) + - Build the Astro documentation + - Validate internal links + - Generate search indexes + + ### 2. Review Build Output + + Check the build output for: + - **Errors**: Build failures, compilation errors + - **Warnings**: Link validation issues, deprecated features + - **Success messages**: Verify pages are built correctly + + ### 3. Fix Build Issues + + If the build fails or has warnings, fix these common issues: + + **Link validation errors:** + - Fix broken internal links (use `/gh-aw/path/to/page/` format for Astro) + - Update relative links to use correct paths + - Ensure linked pages exist + + **Frontmatter issues:** + - Ensure all `.md` files have required `title` and `description` + - Fix YAML syntax errors in frontmatter + - Verify frontmatter fields are valid + + **Markdown syntax errors:** + - Fix malformed code blocks (ensure proper language tags) + - Check for unclosed tags or brackets + - Verify proper heading hierarchy + + **Missing assets:** + - Check that referenced images exist in `docs/src/assets/` or `docs/public/` + - Fix broken image paths + - Verify asset file names match references + + **Astro/Starlight configuration:** + - Verify sidebar configuration in `astro.config.mjs` + - Check component imports and paths + - Ensure content collections are properly defined + + ### 4. Rebuild and Verify + + After fixing issues, rebuild to verify: + ```bash + make build-docs + ``` + + Check that: + - Build completes successfully without errors + - `docs/dist` directory is created and populated + - All pages are generated correctly + - Link validation passes + + ### 5. Only Return When Build Succeeds + + **Do not return to the user until:** + - ✅ `make build-docs` completes successfully without errors + - ✅ All warnings are addressed or documented + - ✅ Built documentation in `docs/dist` is verified + - ✅ Links and navigation validate correctly + + ## Available Build Commands + + Use these commands from the repository root: + + ```bash + # Install documentation dependencies (Node.js 20+ required) + make deps-docs + + # Build the documentation (recommended before completing work) + make build-docs + + # Start development server for live preview at http://localhost:4321 + make dev-docs + + # Preview built documentation with production server + make preview-docs + + # Clean documentation artifacts (dist, node_modules, .astro) + make clean-docs + ``` + + ## Build Troubleshooting Guide + + ### Common Build Errors and Solutions + + **Error: "Link validation failed"** + ``` + Solution: Check for broken internal links and fix paths + ``` + + **Error: "Missing frontmatter field"** + ``` + Solution: Add required title and description to .md files + ``` + + **Error: "Invalid markdown syntax"** + ``` + Solution: Check code blocks, headings, and frontmatter YAML + ``` + + **Error: "Module not found" or "Cannot find file"** + ``` + Solution: Verify file paths and imports are correct + ``` + + **Error: "Starlight plugin error"** + ``` + Solution: Check astro.config.mjs for configuration issues + ``` + + ### Debugging Process + + 1. **Read error messages carefully** - they usually indicate the exact issue + 2. **Check the failing file** - look at the file mentioned in the error + 3. **Fix the issue** - apply the appropriate solution + 4. **Rebuild** - run `make build-docs` again to verify + 5. **Repeat if needed** - continue until build succeeds + + ### Development Server for Testing + + Use the development server to preview changes in real-time: + ```bash + make dev-docs + ``` + + This starts Astro dev server at http://localhost:4321 with: + - Hot module reloading + - Fast refresh for instant updates + - Live error reporting + - Interactive debugging + ## Example Document Skeleton ```md --- @@ -931,31 +1077,92 @@ jobs: The documentation has been built successfully in the `docs/dist` folder. You can review both the source files in `docs/` and the built output in `docs/dist`. - **To run the Astro dev server locally for live preview:** + ### Available Commands + + Use these commands from the repository root: + ```bash - cd docs && npm run dev + # Rebuild the documentation after making changes + make build-docs + + # Start development server for live preview + make dev-docs + + # Preview built documentation + make preview-docs + + # Clean documentation artifacts + make clean-docs ``` - When reviewing documentation for the specified topic in the **docs/** folder, apply these principles to: - - 1. **Analyze the topic** provided in the workflow input - 2. **Review relevant documentation files** in the docs/ folder related to: "__GH_AW_GITHUB_EVENT_INPUTS_TOPIC__" - 3. **Verify the built documentation** in docs/dist is properly generated - 4. **Provide constructive feedback** as a comment addressing: - - Clarity and conciseness - - Tone and voice consistency with GitHub Docs - - Code block formatting and examples - - Structure and organization - - Developer experience considerations - - Any missing prerequisites or setup steps - - Appropriate use of GitHub alerts - - Link quality and accessibility - - Build output quality and completeness - 5. **Create a pull request with improvements** if you identify any changes needed: - - Make the necessary edits to improve the documentation - - Create a pull request with your changes using the safe-outputs create-pull-request functionality + ### Documentation Review Process + + When reviewing documentation for the specified topic in the **docs/** folder: + + 1. **Analyze the topic** provided in the workflow input: "__GH_AW_GITHUB_EVENT_INPUTS_TOPIC__" + + PROMPT_EOF + - name: Substitute placeholders + uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 + env: + GH_AW_PROMPT: /tmp/gh-aw/aw-prompts/prompt.txt + GH_AW_GITHUB_EVENT_INPUTS_TOPIC: ${{ github.event.inputs.topic }} + with: + script: | + const substitutePlaceholders = require('/opt/gh-aw/actions/substitute_placeholders.cjs'); + + // Call the substitution function + return await substitutePlaceholders({ + file: process.env.GH_AW_PROMPT, + substitutions: { + GH_AW_GITHUB_EVENT_INPUTS_TOPIC: process.env.GH_AW_GITHUB_EVENT_INPUTS_TOPIC + } + }); + - name: Append prompt (part 2) + env: + GH_AW_PROMPT: /tmp/gh-aw/aw-prompts/prompt.txt + GH_AW_GITHUB_EVENT_INPUTS_TOPIC: ${{ github.event.inputs.topic }} + run: | + cat << 'PROMPT_EOF' >> "$GH_AW_PROMPT" + 2. **Review relevant documentation files** in the docs/ folder related to the topic + + 3. **Make improvements** to the documentation as needed: + - Fix clarity and conciseness issues + - Improve tone and voice consistency with GitHub Docs + - Enhance code block formatting and examples + - Improve structure and organization + - Add missing prerequisites or setup steps + - Fix inappropriate use of GitHub alerts + - Improve link quality and accessibility + + 4. **Rebuild and verify** after making changes: + ```bash + make build-docs + ``` + - Fix any build errors that occur + - Verify all links validate correctly + - Ensure proper rendering in `docs/dist` + + 5. **Only after successful build**, create a pull request with improvements: + - Use the safe-outputs create-pull-request functionality - Include a clear description of the improvements made - - Only create a pull request if you have made actual changes to the documentation files + - Document any build issues that were fixed + - Only create a pull request if you have made actual changes + + ### Build Verification Requirements + + **Before returning to the user or creating a pull request:** + + - ✅ Run `make build-docs` to verify documentation builds successfully + - ✅ Fix any build errors, warnings, or link validation issues + - ✅ Verify the built output in `docs/dist` is properly generated + - ✅ Confirm all changes render correctly + + **If build errors occur:** + - Read error messages carefully to understand the issue + - Fix broken links, invalid frontmatter, or markdown syntax errors + - Rebuild with `make build-docs` to verify fixes + - Do not proceed until the build succeeds without errors Keep your feedback specific, actionable, and empathetic. Focus on the most impactful improvements for the topic: "__GH_AW_GITHUB_EVENT_INPUTS_TOPIC__" @@ -1337,7 +1544,7 @@ jobs: env: GH_AW_AGENT_OUTPUT: ${{ env.GH_AW_AGENT_OUTPUT }} GH_AW_NOOP_MAX: 1 - GH_AW_WORKFLOW_NAME: "Technical Doc Writer" + GH_AW_WORKFLOW_NAME: "Rebuild the documentation after making changes" with: github-token: ${{ secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }} script: | @@ -1350,7 +1557,7 @@ jobs: uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 env: GH_AW_AGENT_OUTPUT: ${{ env.GH_AW_AGENT_OUTPUT }} - GH_AW_WORKFLOW_NAME: "Technical Doc Writer" + GH_AW_WORKFLOW_NAME: "Rebuild the documentation after making changes" with: github-token: ${{ secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }} script: | @@ -1363,7 +1570,7 @@ jobs: uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 env: GH_AW_AGENT_OUTPUT: ${{ env.GH_AW_AGENT_OUTPUT }} - GH_AW_WORKFLOW_NAME: "Technical Doc Writer" + GH_AW_WORKFLOW_NAME: "Rebuild the documentation after making changes" GH_AW_RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} GH_AW_AGENT_CONCLUSION: ${{ needs.agent.result }} GH_AW_SAFE_OUTPUT_MESSAGES: "{\"footer\":\"\\u003e 📝 *Documentation by [{workflow_name}]({run_url})*\",\"runStarted\":\"✍️ The Technical Writer begins! [{workflow_name}]({run_url}) is documenting this {event_type}...\",\"runSuccess\":\"📝 Documentation complete! [{workflow_name}]({run_url}) has written the docs. Clear as crystal! ✨\",\"runFailure\":\"✍️ Writer's block! [{workflow_name}]({run_url}) {status}. The page remains blank...\"}" @@ -1382,7 +1589,7 @@ jobs: GH_AW_COMMENT_ID: ${{ needs.activation.outputs.comment_id }} GH_AW_COMMENT_REPO: ${{ needs.activation.outputs.comment_repo }} GH_AW_RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} - GH_AW_WORKFLOW_NAME: "Technical Doc Writer" + GH_AW_WORKFLOW_NAME: "Rebuild the documentation after making changes" GH_AW_AGENT_CONCLUSION: ${{ needs.agent.result }} GH_AW_DETECTION_CONCLUSION: ${{ needs.detection.result }} GH_AW_SAFE_OUTPUT_MESSAGES: "{\"footer\":\"\\u003e 📝 *Documentation by [{workflow_name}]({run_url})*\",\"runStarted\":\"✍️ The Technical Writer begins! [{workflow_name}]({run_url}) is documenting this {event_type}...\",\"runSuccess\":\"📝 Documentation complete! [{workflow_name}]({run_url}) has written the docs. Clear as crystal! ✨\",\"runFailure\":\"✍️ Writer's block! [{workflow_name}]({run_url}) {status}. The page remains blank...\"}" @@ -1435,7 +1642,7 @@ jobs: - name: Setup threat detection uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 env: - WORKFLOW_NAME: "Technical Doc Writer" + WORKFLOW_NAME: "Rebuild the documentation after making changes" WORKFLOW_DESCRIPTION: "Reviews and improves technical documentation based on provided topics" HAS_PATCH: ${{ needs.agent.outputs.has_patch }} with: @@ -1570,7 +1777,7 @@ jobs: GH_AW_ENGINE_ID: "copilot" GH_AW_SAFE_OUTPUT_MESSAGES: "{\"footer\":\"\\u003e 📝 *Documentation by [{workflow_name}]({run_url})*\",\"runStarted\":\"✍️ The Technical Writer begins! [{workflow_name}]({run_url}) is documenting this {event_type}...\",\"runSuccess\":\"📝 Documentation complete! [{workflow_name}]({run_url}) has written the docs. Clear as crystal! ✨\",\"runFailure\":\"✍️ Writer's block! [{workflow_name}]({run_url}) {status}. The page remains blank...\"}" GH_AW_WORKFLOW_ID: "technical-doc-writer" - GH_AW_WORKFLOW_NAME: "Technical Doc Writer" + GH_AW_WORKFLOW_NAME: "Rebuild the documentation after making changes" outputs: process_safe_outputs_processed_count: ${{ steps.process_safe_outputs.outputs.processed_count }} process_safe_outputs_temporary_id_map: ${{ steps.process_safe_outputs.outputs.temporary_id_map }} @@ -1735,7 +1942,7 @@ jobs: GH_AW_ASSETS_BRANCH: "assets/${{ github.workflow }}" GH_AW_ASSETS_MAX_SIZE_KB: 10240 GH_AW_ASSETS_ALLOWED_EXTS: ".png,.jpg,.jpeg" - GH_AW_WORKFLOW_NAME: "Technical Doc Writer" + GH_AW_WORKFLOW_NAME: "Rebuild the documentation after making changes" GH_AW_ENGINE_ID: "copilot" GH_AW_SAFE_OUTPUT_MESSAGES: "{\"footer\":\"\\u003e 📝 *Documentation by [{workflow_name}]({run_url})*\",\"runStarted\":\"✍️ The Technical Writer begins! [{workflow_name}]({run_url}) is documenting this {event_type}...\",\"runSuccess\":\"📝 Documentation complete! [{workflow_name}]({run_url}) has written the docs. Clear as crystal! ✨\",\"runFailure\":\"✍️ Writer's block! [{workflow_name}]({run_url}) {status}. The page remains blank...\"}" with: diff --git a/.github/workflows/technical-doc-writer.md b/.github/workflows/technical-doc-writer.md index c1c0e8b6fa..2ad988d954 100644 --- a/.github/workflows/technical-doc-writer.md +++ b/.github/workflows/technical-doc-writer.md @@ -78,31 +78,69 @@ This workflow is triggered manually via workflow_dispatch with a documentation t The documentation has been built successfully in the `docs/dist` folder. You can review both the source files in `docs/` and the built output in `docs/dist`. -**To run the Astro dev server locally for live preview:** +### Available Commands + +Use these commands from the repository root: + ```bash -cd docs && npm run dev +# Rebuild the documentation after making changes +make build-docs + +# Start development server for live preview +make dev-docs + +# Preview built documentation +make preview-docs + +# Clean documentation artifacts +make clean-docs ``` -When reviewing documentation for the specified topic in the **docs/** folder, apply these principles to: - -1. **Analyze the topic** provided in the workflow input -2. **Review relevant documentation files** in the docs/ folder related to: "${{ github.event.inputs.topic }}" -3. **Verify the built documentation** in docs/dist is properly generated -4. **Provide constructive feedback** as a comment addressing: - - Clarity and conciseness - - Tone and voice consistency with GitHub Docs - - Code block formatting and examples - - Structure and organization - - Developer experience considerations - - Any missing prerequisites or setup steps - - Appropriate use of GitHub alerts - - Link quality and accessibility - - Build output quality and completeness -5. **Create a pull request with improvements** if you identify any changes needed: - - Make the necessary edits to improve the documentation - - Create a pull request with your changes using the safe-outputs create-pull-request functionality +### Documentation Review Process + +When reviewing documentation for the specified topic in the **docs/** folder: + +1. **Analyze the topic** provided in the workflow input: "${{ github.event.inputs.topic }}" + +2. **Review relevant documentation files** in the docs/ folder related to the topic + +3. **Make improvements** to the documentation as needed: + - Fix clarity and conciseness issues + - Improve tone and voice consistency with GitHub Docs + - Enhance code block formatting and examples + - Improve structure and organization + - Add missing prerequisites or setup steps + - Fix inappropriate use of GitHub alerts + - Improve link quality and accessibility + +4. **Rebuild and verify** after making changes: + ```bash + make build-docs + ``` + - Fix any build errors that occur + - Verify all links validate correctly + - Ensure proper rendering in `docs/dist` + +5. **Only after successful build**, create a pull request with improvements: + - Use the safe-outputs create-pull-request functionality - Include a clear description of the improvements made - - Only create a pull request if you have made actual changes to the documentation files + - Document any build issues that were fixed + - Only create a pull request if you have made actual changes + +### Build Verification Requirements + +**Before returning to the user or creating a pull request:** + +- ✅ Run `make build-docs` to verify documentation builds successfully +- ✅ Fix any build errors, warnings, or link validation issues +- ✅ Verify the built output in `docs/dist` is properly generated +- ✅ Confirm all changes render correctly + +**If build errors occur:** +- Read error messages carefully to understand the issue +- Fix broken links, invalid frontmatter, or markdown syntax errors +- Rebuild with `make build-docs` to verify fixes +- Do not proceed until the build succeeds without errors Keep your feedback specific, actionable, and empathetic. Focus on the most impactful improvements for the topic: "${{ github.event.inputs.topic }}" diff --git a/Makefile b/Makefile index 0a2e6ccca1..472b73b5b9 100644 --- a/Makefile +++ b/Makefile @@ -219,6 +219,8 @@ clean: echo "Removing installed gh-aw extension..."; \ gh extension remove gh-aw 2>/dev/null || rm -rf "$$HOME/.local/share/gh/extensions/gh-aw"; \ fi + @# Clean documentation artifacts + @rm -rf docs/dist docs/.astro 2>/dev/null || true @# Clean Go build cache, module cache, and test cache go clean -cache -modcache -testcache @echo "✓ Clean complete" @@ -527,6 +529,35 @@ build-slides: @cd docs && npx @marp-team/marp-cli ../slides/index.md --html --allow-local-files -o public/slides/gh-aw.html @echo "✓ Slides built to docs/public/slides/gh-aw.html" +# Documentation targets +.PHONY: deps-docs +deps-docs: check-node-version + @echo "Installing documentation dependencies..." + @cd docs && npm ci + @echo "✓ Documentation dependencies installed" + +.PHONY: build-docs +build-docs: deps-docs + @echo "Building Astro documentation..." + @cd docs && npm run build + @echo "✓ Documentation built to docs/dist" + +.PHONY: dev-docs +dev-docs: deps-docs + @echo "Starting Astro development server..." + @cd docs && npm run dev + +.PHONY: preview-docs +preview-docs: build-docs + @echo "Starting Astro preview server..." + @cd docs && npm run preview + +.PHONY: clean-docs +clean-docs: + @echo "Cleaning documentation artifacts..." + @rm -rf docs/dist docs/node_modules docs/.astro + @echo "✓ Documentation artifacts cleaned" + # Sync templates from .github to pkg/cli/templates .PHONY: sync-templates sync-templates: @@ -699,6 +730,11 @@ help: @echo " generate-schema-docs - Generate frontmatter full reference documentation from JSON schema" @echo " generate-agent-factory - Generate agent factory documentation page" @echo " build-slides - Build slides with Marp to docs/public/slides/gh-aw.html" + @echo " deps-docs - Install Astro documentation dependencies" + @echo " build-docs - Build Astro documentation to docs/dist" + @echo " dev-docs - Start Astro development server for live preview" + @echo " preview-docs - Preview built documentation with Astro" + @echo " clean-docs - Clean documentation artifacts (dist, node_modules, .astro)" @echo " agent-finish - Complete validation sequence (build, test, fix, recompile, fmt, lint, security-scan)" @echo " version - Preview next version from changesets" diff --git a/docs/src/content/docs/agent-factory.mdx b/docs/src/content/docs/agent-factory.mdx index e134e7dd9b..e528ef5e70 100644 --- a/docs/src/content/docs/agent-factory.mdx +++ b/docs/src/content/docs/agent-factory.mdx @@ -99,6 +99,7 @@ These are experimental agentic workflows used by the GitHub Next team to learn, | [PR Nitpick Reviewer 🔍](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/pr-nitpick-reviewer.md) | copilot | [![PR Nitpick Reviewer 🔍](https://github.com/githubnext/gh-aw/actions/workflows/pr-nitpick-reviewer.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/pr-nitpick-reviewer.lock.yml) | - | - | | [Python Data Visualization Generator](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/python-data-charts.md) | copilot | [![Python Data Visualization Generator](https://github.com/githubnext/gh-aw/actions/workflows/python-data-charts.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/python-data-charts.lock.yml) | - | - | | [Q](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/q.md) | copilot | [![Q](https://github.com/githubnext/gh-aw/actions/workflows/q.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/q.lock.yml) | - | `/q` | +| [Rebuild the documentation after making changes](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/technical-doc-writer.md) | copilot | [![Rebuild the documentation after making changes](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) | - | - | | [Refresh playground snapshots](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/playground-snapshots-refresh.md) | copilot | [![Refresh playground snapshots](https://github.com/githubnext/gh-aw/actions/workflows/playground-snapshots-refresh.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/playground-snapshots-refresh.lock.yml) | `0 8 * * 1` | - | | [Release](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/release.md) | copilot | [![Release](https://github.com/githubnext/gh-aw/actions/workflows/release.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/release.lock.yml) | - | - | | [Repository Quality Improvement Agent](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/repository-quality-improver.md) | copilot | [![Repository Quality Improvement Agent](https://github.com/githubnext/gh-aw/actions/workflows/repository-quality-improver.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/repository-quality-improver.lock.yml) | `0 13 * * 1-5` | - | @@ -119,7 +120,6 @@ These are experimental agentic workflows used by the GitHub Next team to learn, | [Step Name Alignment](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/step-name-alignment.md) | claude | [![Step Name Alignment](https://github.com/githubnext/gh-aw/actions/workflows/step-name-alignment.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/step-name-alignment.lock.yml) | `daily` | - | | [Sub-Issue Closer](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/sub-issue-closer.md) | copilot | [![Sub-Issue Closer](https://github.com/githubnext/gh-aw/actions/workflows/sub-issue-closer.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/sub-issue-closer.lock.yml) | - | - | | [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) | - | - | | [Terminal Stylist](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/terminal-stylist.md) | copilot | [![Terminal Stylist](https://github.com/githubnext/gh-aw/actions/workflows/terminal-stylist.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/terminal-stylist.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` | - | | [The Great Escapi](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/firewall-escape.md) | copilot | [![The Great Escapi](https://github.com/githubnext/gh-aw/actions/workflows/firewall-escape.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/firewall-escape.lock.yml) | - | - |