improve methodology documentation

Author: dsyme

docs/ci-doctor.md

@@ -12,12 +12,17 @@ gh aw add ci-doctor -r githubnext/agentics --pr
 
 This creates a pull request to add the workflow to your repository. After merging the PR, the workflow will automatically trigger when monitored CI workflows fail. You cannot start this workflow manually as it responds to workflow failure events.
 
+**Checklist**
+
+* [ ] If in a fork, enable GitHub Actions and Issues in the fork settings
+
 ## Configuration
 
-- No build steps required - works out of the box for failure investigation
-- Edit the workflow file to specify which workflows to monitor (currently monitors "Daily Perf Improver" and "Daily Test Improver")
-- Customize investigation depth, failure categorization, and reporting format
-- After editing run `gh aw compile` to update the workflow.
+1. Use local configuation to specify which workflows to monitor (currently monitors "Daily Perf Improver" and "Daily Test Improver"), investigation depth, failure categorization, and reporting format. Local configuration can be done in `.github/workflows/agentics/ci-doctor.config.md`.
+
+2. Build tool configuration for build tools shared across all workflows installed from this pack can be done in `.github/workflows/agentics/build-tools.md`. 
+
+After editing run `gh aw compile` to update the workflow and commit all changes to the default branch.
 
 ## What it reads from GitHub
 

docs/daily-accessibility-review.md

@@ -10,20 +10,23 @@ The [daily accessibility review workflow](../workflows/daily-accessibility-revie
 gh aw add daily-accessibility-review -r githubnext/agentics --pr
 ```
 
-This creates a pull request to add the workflow to your repository. After merging the PR and syncing to main, you can start a run of this workflow immediately by running:
+This creates an issue in your repository recording accessibility problems found.
 
 ```bash
 gh aw run daily-accessibility-review
 ```
 
+**Checklist**
+
+* [ ] If in a fork, enable GitHub Actions and Issues in the fork settings
+
 ## Configuration
 
-- First run produces a pull request with inferred action pre-steps that need approval
-- Requires configuring build steps to run your application - initial runs may open issues suggesting new inferred commands that need approval
-- Edit the workflow to specify application startup commands and URLs to test
-- Customize accessibility testing tools and WCAG compliance levels
-- Add project-specific accessibility scenarios and user journey testing
-- After editing run `gh aw compile` to update the workflow.
+1. Use local configuation to specify which accessibility standards to check (e.g., WCAG 2.1, WCAG 2.2), types of accessibility issues to prioritize, and reporting format. Local configuration can be done in `.github/workflows/agentics/daily-accessibility-review.config.md`.
+
+2. Build tool configuration for build tools shared across all workflows installed from this pack can be done in `.github/workflows/agentics/build-tools.md`. 
+
+After editing run `gh aw compile` to update the workflow and commit all changes to the default branch.
 
 ## What it reads from GitHub
 
@@ -56,4 +59,3 @@ gh aw run daily-accessibility-review
 
 - If you're sufficiently isolated (e.g. operating in a fresh fork of an open source project, with Actions and Issues enabled ), you can enable all Bash commands by using `Bash: [":*"]` in the workflow file and then running `gh aw compile` to update the workflow. This may be useful for time-limited experiments.
 
-⚠️ See notes on coding tasks in the [main README](../README.md). You will need to edit the workflow file to add the commands to build and run your project. After editing run `gh aw compile` to update the workflow.

docs/daily-dependency-updates.md

@@ -16,11 +16,27 @@ This creates a pull request to add the workflow to your repository. After mergin
 gh aw run daily-dependency-updates
 ```
 
+**Checklist**
+
+* [ ] See notes on coding tasks in the [main README](../README.md). 
+
+* [ ] Enable "Allow GitHub Actions to create and approve pull requests" in the repository settings under "Actions > General"
+
+* [ ] Recommend enabling  "Always suggest updating pull request branches" in the repository settings
+
+* [ ] If in a fork, enable "GitHub Actions" and "GitHub Issues" in the fork project settings
+
+* [ ] When a pull request is created, you must review the changes carefully. 
+
+* [ ] Understand that your GitHub Actions runs will **not** trigger on pull requests created by this workflow, or indeed any Actions-created PRs. You must open/close the PR or push a new commit to trigger CI checks. This is not indicated in the GitHub UI. It's just something you need to be aware of.
+
 ## Configuration
 
-- Edit the workflow to specify dependency management tools (npm, pip, maven, etc.), customize dependency update strategies and version constraints
-- Configure which dependencies to include/exclude from automated updates
-- After editing run `gh aw compile` to update the workflow.
+1. Use local configuation to specify dependency management tools (npm, pip, maven, etc.), customize dependency update strategies and version constraints, onfigure which dependencies to include/exclude from automated updates. Local configuration can be done in `.github/workflows/agentics/daily-dependency-updates.config.md`.
+
+2. Build tool configuration for build tools shared across all workflows installed from this pack can be done in `.github/workflows/agentics/build-tools.md`.
+
+After editing run `gh aw compile` to update the workflow and commit all changes to the default branch.
 
 ## What it reads from GitHub
 
@@ -51,4 +67,3 @@ gh aw run daily-dependency-updates
 - By default this workflow will trigger for at most 48 hours, after which it will stop triggering. 
 - This allows you to experiment with the workflow for a limited time before deciding whether to keep it active.
 
-⚠️ See notes on coding tasks in the [main README](../README.md).

docs/daily-perf-improver.md

@@ -16,13 +16,37 @@ This creates a pull request to add the workflow to your repository. After mergin
 gh aw run daily-perf-improver
 ```
 
+To run continuously (at most one instance running at a time and sending a trigger every 3 minutes), use:
+
+```bash
+gh aw run daily-perf-improver --repeat 180
+```
+
+**Checklist**
+
+* [ ] See notes on coding tasks in the [main README](../README.md). 
+
+* [ ] Enable "Allow GitHub Actions to create and approve pull requests" in the repository settings under "Actions > General"
+
+* [ ] Recommend enabling  "Always suggest updating pull request branches" in the repository settings
+
+* [ ] If in a fork, enable "GitHub Actions" and "GitHub Issues" in the fork project settings
+
+* [ ] When a pull request is created, you must review the changes carefully. 
+
+* [ ] Understand that your GitHub Actions runs will **not** trigger on pull requests created by this workflow, or indeed any Actions-created PRs. You must open/close the PR or push a new commit to trigger CI checks. This is not indicated in the GitHub UI. It's just something you need to be aware of.
+
 ## Configuration
 
-- First run produces a pull request with inferred action pre-steps that need approval
-- Requires configuring build steps to run your application - initial runs may open issues suggesting new inferred commands that need approval
-- Edit the workflow to specify performance testing tools and benchmarking frameworks
-- Customize optimization targets, performance metrics, and profiling strategies
-- Add project-specific bottleneck identification and performance validation steps
+1. The first run of the workflow will produce a pull request with inferred action pre-steps that need approval
+
+2. The first run of the workflow will also create an issue in the repository with a plan for improving performance. You can comment on this issue to provide feedback or adjustments to the plan. Comments will not be picked up until the next run.
+
+3. Use local configuation to specify performance testing tools and benchmarking frameworks, optimization targets, performance metrics, and profiling strategies. Local configuration can be done in `.github/workflows/agentics/daily-perf-improver.config.md`.
+
+4. Build tool configuration for build tools shared across all workflows installed from this pack can be done in `.github/workflows/agentics/build-tools.md`. 
+
+After editing run `gh aw compile` to update the workflow and commit all changes to the default branch.
 
 ## What it reads from GitHub
 
@@ -60,6 +84,15 @@ gh aw run daily-perf-improver
 
 ## YOLO
 
-- If you're sufficiently isolated (e.g. operating in a fresh fork of an open source project, with Actions and Issues enabled ), you can enable all Bash commands by using `Bash: [":*"]` in the workflow file and then running `gh aw compile` to update the workflow. This may be useful for time-limited experiments.
+If you're sufficiently isolated (e.g. operating in a fresh fork of an open source project, with Actions and Issues enabled ), you can enable all Bash commands. This is not recommended for production use, but may be useful for time-limited experiments in isolated forks.
 
-⚠️ See notes on coding tasks in the [main README](../README.md). You will need to edit the workflow file to add the commands to build, test and profile. After editing run `gh aw compile` to update the workflow.
+`.github/workflows/agentics/build-tools.md`:
+
+```yaml
+---
+tools:
+claude:
+    allowed:
+    Bash: ["*"] # YOLO mode - all bash commands allowed or list specific tools
+---
+```

docs/daily-plan.md

@@ -16,12 +16,17 @@ This creates a pull request to add the workflow to your repository. After mergin
 gh aw run daily-plan
 ```
 
+**Checklist**
+
+* [ ] If in a fork, enable GitHub Actions and Issues in the fork settings
+
 ## Configuration
 
-- No build steps required - works out of the box
-- Edit the workflow file to customize planning format, priorities, planning categories, timeframes, or team coordination style
-- Add MCPs to integrate with other planning tools
-- After editing run `gh aw compile` to update the workflow.
+1. Use local configuation to specify planning focus areas, reporting format, and frequency. Local configuration can be done in `.github/workflows/agentics/daily-plan.config.md`.
+
+2. Build tool configuration for build tools shared across all workflows installed from this pack can be done in `.github/workflows/agentics/build-tools.md`. 
+
+After editing run `gh aw compile` to update the workflow and commit all changes to the default branch.
 
 ## What it reads from GitHub
 

docs/daily-qa.md

@@ -16,13 +16,17 @@ This creates a pull request to add the workflow to your repository. After mergin
 gh aw run daily-qa
 ```
 
+**Checklist**
+
+* [ ] If in a fork, enable GitHub Actions and Issues in the fork settings
+
 ## Configuration
 
-- Requires configuring build steps to run your application - initial runs may open issues suggesting new inferred commands that need approval
-- Edit the workflow to specify build tools, test frameworks, and QA scenarios
-- Customize quality checks, performance benchmarks, and validation steps
-- Add project-specific getting-started instructions and tutorial validation
-- After editing run `gh aw compile` to update the workflow.
+3. Use local configuation to specify QA tasks, testing scenarios, reporting format, and frequency. Local configuration can be done in `.github/workflows/agentics/daily-qa.config.md`.
+
+4. Build tool configuration for build tools shared across all workflows installed from this pack can be done in `.github/workflows/agentics/build-tools.md`.
+
+After editing run `gh aw compile` to update the workflow and commit all changes to the default branch.
 
 ## What it reads from GitHub
 
@@ -56,4 +60,3 @@ gh aw run daily-qa
 
 - If you're sufficiently isolated (e.g. operating in a fresh fork of an open source project, with Actions and Issues enabled ), you can enable all Bash commands by using `Bash: [":*"]` in the workflow file and then running `gh aw compile` to update the workflow. This may be useful for time-limited experiments.
 
-⚠️ See notes on coding tasks in the [main README](../README.md).

docs/daily-team-status.md

@@ -16,11 +16,15 @@ This creates a pull request to add the workflow to your repository. After mergin
 gh aw run daily-team-status
 ```
 
+**Checklist**
+
+* [ ] If in a fork, enable GitHub Actions and Issues in the fork settings
+
 ## Configuration
 
 - No build steps required - works out of the box
 - Edit the workflow file to customize status report format, metrics, modify report frequency or add specific team focuses
-- After editing run `gh aw compile` to update the workflow.
+- After editing run `gh aw compile` to update the workflow and commit all changes to the default branch.
 
 ## What it reads from GitHub
 

docs/daily-test-improver.md

@@ -16,13 +16,31 @@ This creates a pull request to add the workflow to your repository. After mergin
 gh aw run daily-test-improver
 ```
 
+**Checklist**
+
+* [ ] See notes on coding tasks in the [main README](../README.md). 
+
+* [ ] Enable "Allow GitHub Actions to create and approve pull requests" in the repository settings under "Actions > General"
+
+* [ ] Recommend enabling  "Always suggest updating pull request branches" in the repository settings
+
+* [ ] If in a fork, enable "GitHub Actions" and "GitHub Issues" in the fork project settings
+
+* [ ] When a pull request is created, you must review the changes carefully. 
+
+* [ ] Understand that your GitHub Actions runs will **not** trigger on pull requests created by this workflow, or indeed any Actions-created PRs. You must open/close the PR or push a new commit to trigger CI checks. This is not indicated in the GitHub UI. It's just something you need to be aware of.
+
 ## Configuration
 
-- First run produces a pull request with inferred action pre-steps that need approval
-- Requires configuring build steps to run your application - check reports from initial runs for new build commands that need approval. Add these to the workflow and then run `gh aw compile` to update the workflow.
-- Edit the workflow to customize test generation strategies, high-priority areas and coverage targets
-- Add project-specific test patterns and edge case identification
-- After editing run `gh aw compile` to update the workflow.
+1. The first run of the workflow will produce a pull request with inferred action pre-steps that need approval.
+
+2. The first run of the workflow will also create an issue in the repository with a plan for improving test coverage. You can comment on this issue to provide feedback or adjustments to the plan. Comments will not be picked up until the next run.
+
+3. Use local configuation or comment on the plan to specify test generation strategies, high-priority areas and coverage targets. Local configuration can be done in `.github/workflows/agentics/daily-test-improver.config.md`.
+
+4. Build tool configuration for build tools shared across all workflows installed from this pack can be done in `.github/workflows/agentics/build-tools.md`.
+
+After editing run `gh aw compile` to update the workflow and commit all changes to the default branch.
 
 ## What it reads from GitHub
 
@@ -56,4 +74,3 @@ gh aw run daily-test-improver
 
 - If you're sufficiently isolated (e.g. operating in a fresh fork of an open source project, with Actions and Issues enabled ), you can enable all Bash commands by using `Bash: [":*"]` in the workflow file and then running `gh aw compile` to update the workflow. This may be useful for time-limited experiments.
 
-⚠️ See notes on coding tasks in the [main README](../README.md). You will need to edit the workflow file to add the commands to build and run tests. After editing run `gh aw compile` to update the workflow.

docs/issue-triage.md

@@ -12,12 +12,16 @@ gh aw add issue-triage -r githubnext/agentics --pr
 
 This creates a pull request to add the workflow to your repository. You can't start a run of this workflow directly as it is triggered in the context of an issue.
 
+**Checklist**
+
+* [ ] If in a fork, enable GitHub Actions and Issues in the fork settings
+
 ## Configuration
 
 - No build steps required - works out of the box
 - Edit the workflow file to customize triage criteria, labeling logic, customize issue categorization, modify automated responses
 - Add MCPs to integrate with project management tools
-- After editing run `gh aw compile` to update the workflow.
+- After editing run `gh aw compile` to update the workflow and commit all changes to the default branch.
 
 ## What it reads from GitHub
 

docs/update-docs.md

@@ -16,14 +16,29 @@ This creates a pull request to add the workflow to your repository. After mergin
 gh aw run update-docs
 ```
 
+**Checklist**
+
+* [ ] See notes on coding tasks in the [main README](../README.md). 
+
+* [ ] Enable "Allow GitHub Actions to create and approve pull requests" in the repository settings under "Actions > General"
+
+* [ ] Recommend enabling  "Always suggest updating pull request branches" in the repository settings
+
+* [ ] If in a fork, enable "GitHub Actions" and "GitHub Issues" in the fork project settings
+
+* [ ] When a pull request is created, you must review the changes carefully. 
+
+* [ ] Understand that your GitHub Actions runs will **not** trigger on pull requests created by this workflow, or indeed any Actions-created PRs. You must open/close the PR or push a new commit to trigger CI checks. This is not indicated in the GitHub UI. It's just something you need to be aware of.
+
+
 ## Configuration
 
 - Benefits from configuring build steps for documentation generation
 - Edit the workflow to specify your documentation framework (Astro Starlight, MkDocs, etc.)
 - Customize documentation structure, themes, and generation commands
 - Add project-specific documentation validation and deployment steps
 - Configure which files and directories to include in documentation updates
-- After editing run `gh aw compile` to update the workflow.
+- After editing run `gh aw compile` to update the workflow and commit all changes to the default branch.
 
 ## What it reads from GitHub
 
@@ -57,4 +72,3 @@ gh aw run update-docs
 - By default this workflow will trigger for at most 30 days, after which it will stop triggering. 
 - This allows you to experiment with the workflow for a limited time before deciding whether to keep it active.
 
-⚠️ See notes on coding tasks in the [main README](../README.md).