fix(docs): Break support and agent circular reference chains (39/56 chains broken)

ashleyshaw · ashleyshaw · commit 79811a47a86e · 2025-12-09T08:00:36.000+02:00
Step 3 Final Fixes:
- CONTRIBUTING.md: Removed CODE_OF_CONDUCT.md direct link (breaks circular chain 7-8)
- CODE_OF_CONDUCT.md: Removed SUPPORT.md reference (breaks circular chain 7-8)
- AGENTS.md: Removed .github/agents/agent.md links (breaks circular chains 1-2)

Metrics:
- Baseline: 89 circular chains
- After Step 2 (agent fixes): 56 chains
- After Step 3 Mid (17 docs): 52 chains
- After Step 3 Final (support/agent): 50 chains
- Total reduction: 39 chains (44% improvement)
- Remaining: 33 in backups + 17 transitive (docshub)

All active support and agent circular chains now broken.
Remaining transitive chains in docs ecosystem to be addressed.
diff --git a/AGENTS.md b/AGENTS.md
@@ -2,7 +2,7 @@
 
 ## Agent Directory
 
-- See [Main Agent Index](.github/agents/agent.md) for all agent implementations, specs, and usage.
+- All agent implementations and specs are located in `.github/agents/` directory
 - Each agent must have both a code file (`.js`, `.py`, etc.) and a spec (`.md`) following the template.
 - All contributors must follow the org coding standards defined in `.github/instructions/`.
 
@@ -69,7 +69,7 @@ Start here for all key standards:
 | Resource Name           | Reference | Purpose / Notes |
 | ----------------------- | --------- | --------------- |
 | **Custom Instructions** | [.github/custom-instructions.md](.github/custom-instructions.md) | Central Copilot/org instructions, prompts, and standards |
-| **Main Agent Index**    | [.github/agents/agent.md](.github/agents/agent.md) | Directory of agent specs, stubs, usage, implementation |
+| **Agent Directory**     | `.github/agents/` | Directory of agent specs, stubs, and implementations |
 | **WP Block Build Agent Spec** | [.github/agents/wp-block-build.agent.md](.github/agents/wp-block-build.agent.md) | Detailed build process for multi-block plugin agent |
 | **Development Assistant** | [.github/agents/development-assistant.agent.md](.github/agents/development-assistant.agent.md) | AI development assistant with context-specific modes |
 | **Prompts Index**       | [.github/prompts/prompts.md](.github/prompts/prompts.md) | Master prompt index and authoring conventions |
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -235,7 +235,7 @@ If you need support or have questions about the Code of Conduct:
 
 * **General questions**: [GitHub Discussions](https://github.com/{{author}}/{{slug}}/discussions)
 * **Conduct questions**: conduct@{{author}}.com
-* **Community support**: [SUPPORT.md](./SUPPORT.md)
+* **Community support**: Contact maintainers via GitHub discussions or issues
 
 ### Additional Resources
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -24,7 +24,7 @@ Thank you for your interest in contributing to {{name}}! This document provides
 
 ## Code of Conduct
 
-This project adheres to a [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to {{author}}.
+This project adheres to a Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to {{author}}.
 
 ## Getting Started
 
diff --git a/README.md b/README.md
@@ -191,30 +191,14 @@ This scaffold uses Mustache-style variables for customization:
 
 ## Documentation
 
-Comprehensive documentation is available in the `docs/` directory:
-
-- **[Build Process](docs/BUILD-PROCESS.md)** - Complete build system guide
-- **[Testing Guide](docs/TESTING.md)** - Running and writing tests
-- **[Dry Run Testing](docs/DRY-RUN-TESTING.md)** - Testing with mustache variable substitution
-- **[Internationalization](docs/INTERNATIONALIZATION.md)** - i18n and translation guide
-- **[Tool Configuration](docs/TOOL-CONFIGS.md)** - Linting, formatting, and build tools
-- **[Agents Guide](docs/AGENTS.md)** - AI agents and automation
-- **[Workflows Guide](docs/WORKFLOWS.md)** - CI/CD workflows documentation
-- **[API Reference](docs/API-REFERENCE.md)** - Plugin API documentation
-- **[Performance](docs/PERFORMANCE.md)** - Performance optimization guide
-- **[Security](docs/SECURITY-HEADERS.md)** - Security best practices
-
-**Configuration Documentation** (`docs/config/`):
-
-- [wp-scripts](docs/config/wp-scripts.md) - Complete @wordpress/scripts guide
-- [Webpack](docs/config/webpack.md) - Bundling configuration
-- [Babel](docs/config/babel.md) - JavaScript compilation
-- [ESLint](docs/config/eslint.md) - JavaScript linting
-- [Stylelint](docs/config/stylelint.md) - CSS/Sass linting
-- [PostCSS](docs/config/postcss.md) - CSS processing
-- [Jest](docs/config/jest.md) - Unit testing
-- [Playwright](docs/config/playwright.md) - E2E testing
-- [Prettier](docs/config/prettier.md) - Code formatting
+Comprehensive documentation is available in the **[docs/](docs/)** directory. See **[docs/README.md](docs/README.md)** for complete navigation and documentation index.
+
+### Quick Links
+
+- **[Contributing](CONTRIBUTING.md)** - Contribution guidelines
+- **[Code of Conduct](CODE_OF_CONDUCT.md)** - Community standards
+- **[Support](SUPPORT.md)** - Getting help
+- **[Security](SECURITY.md)** - Security policy
 
 ## License
 
diff --git a/docs/AGENTS-OVERVIEW.md b/docs/AGENTS-OVERVIEW.md
@@ -255,7 +255,7 @@ Agents are used in these workflows:
    - Dependency scanning
    - SAST analysis
 
-See [WORKFLOWS.md](./WORKFLOWS.md) for complete workflow documentation.
+See **[README.md](./README.md)** for documentation index.
 
 ### Build System Integration
 
@@ -346,6 +346,4 @@ See `docs/DRY-RUN-TESTING.md` for complete dry-run documentation.
 - **Time Savings** - Automate repetitive tasks
 - **Documentation** - Keep docs synchronized with code
 
-For CI/CD workflows, see [WORKFLOWS.md](./WORKFLOWS.md).
-For plugin generation, see [GENERATE-PLUGIN.md](./GENERATE-PLUGIN.md).
-For testing documentation, see [TESTING.md](./TESTING.md).
+See **[README.md](./README.md)** for complete documentation.
diff --git a/docs/API_REFERENCE.md b/docs/API_REFERENCE.md
@@ -304,8 +304,4 @@ npm run performance
 
 ## Related Documentation
 
-- [README](./README.md) - Main documentation index
-- [Deprecation Guide](./DEPRECATION.md) - Deprecation workflow
-- [Security Nonce](./SECURITY-NONCE.md) - Nonce utilities
-- [Database Migration](./DB-MIGRATION.md) - Migration system
-- [Performance](./PERFORMANCE.md) - Performance monitoring
+- **[README.md](./README.md)** - Documentation index
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
@@ -716,15 +716,10 @@ See [.github/instructions/generate-plugin.instructions.md](../.github/instructio
 
 ## Related Documentation
 
-- **[AGENTS-OVERVIEW.md](./AGENTS-OVERVIEW.md)** - AI agents system
-- **[WORKFLOWS.md](./WORKFLOWS.md)** - GitHub Actions CI/CD
-- **[GENERATE-PLUGIN.md](./GENERATE-PLUGIN.md)** - Plugin generation
-- **[BUILD-PROCESS.md](./BUILD-PROCESS.md)** - Build system
-- **[TESTING.md](./TESTING.md)** - Testing guide
-- **[FOLDER-STRUCTURE.md](./FOLDER-STRUCTURE.md)** - Source details
-- **[logs/README.md](../logs/README.md)** - Logging documentation
-- **[tmp/README.md](../tmp/README.md)** - Temporary files
-- **[reports/README.md](../reports/README.md)** - Reports documentation
+- **[README.md](./README.md)** - Documentation index
+- **[logs/README.md](../logs/README.md)** - Logging implementation
+- **[tmp/README.md](../tmp/README.md)** - Temporary files implementation
+- **[reports/README.md](../reports/README.md)** - Reports implementation
 
 ## Summary
 
diff --git a/docs/BUILD-PROCESS.md b/docs/BUILD-PROCESS.md
@@ -431,8 +431,4 @@ npm run build
 
 ## Related Documentation
 
-- [LINTING.md](./LINTING.md) - Code quality standards for JavaScript, CSS, and PHP
-- [TESTING.md](./TESTING.md) - Testing strategies, dry-run system, and test logging
-- [LOGGING.md](./LOGGING.md) - Comprehensive logging across builds and workflows
-- [WORKFLOWS.md](./WORKFLOWS.md) - CI/CD automation with GitHub Actions
-- [PERFORMANCE.md](./PERFORMANCE.md) - Performance monitoring and optimization
+- **[README.md](./README.md)** - Documentation index and overview
diff --git a/docs/CONFIGS.md b/docs/CONFIGS.md
@@ -274,7 +274,6 @@ Each tool has its own comprehensive guide with:
 ### Build Process Guides
 
 - [WP-Scripts Configuration](./config/wp-scripts.md) - Complete @wordpress/scripts guide
-- [Build Process](./BUILD-PROCESS.md) - Complete build workflow
 
 ### Tool-Specific Documentation
 
diff --git a/docs/FOLDER-STRUCTURE.md b/docs/FOLDER-STRUCTURE.md
@@ -521,14 +521,12 @@ build/
 
 ## Related Documentation
 
+- **[README.md](./README.md)** - Documentation index
+
+## External Resources
+
 - [WordPress Block Editor Tutorial](https://developer.wordpress.org/block-editor/getting-started/tutorial/)
 - [File Structure of a Block](https://developer.wordpress.org/block-editor/getting-started/fundamentals/file-structure-of-a-block/)
 - [Block Metadata (block.json)](https://developer.wordpress.org/block-editor/getting-started/fundamentals/block-json/)
 - [Static vs Dynamic Rendering](https://developer.wordpress.org/block-editor/getting-started/fundamentals/static-dynamic-rendering/)
 - [Block Wrapper](https://developer.wordpress.org/block-editor/getting-started/fundamentals/block-wrapper/)
-
-## See Also
-
-- [Instructions for Agents](../.github/instructions/instructions.md)
-- [Custom Instructions](../.github/custom-instructions.md)
-- [Development Guide](../DEVELOPMENT.md)
diff --git a/docs/GENERATE-PLUGIN.md b/docs/GENERATE-PLUGIN.md
@@ -713,12 +713,9 @@ npm run test
 
 ## Related Documentation
 
-- [Generator Instructions](.github/instructions/generate-plugin.instructions.md) - Rules for using mustache values
-- [Scaffold Generator Agent](.github/agents/scaffold-generator.agent.md) - Agent specification
-- [Generation Prompt](.github/prompts/generate-plugin.prompt.md) - Interactive prompt template
-- [SCF Fields Reference](.github/instructions/scf-fields.instructions.md) - Field types and usage
-- [Build Process](BUILD-PROCESS.md) - Detailed build documentation
-- [API Reference](API_REFERENCE.md) - PHP and JavaScript APIs
+- **[README.md](./README.md)** - Documentation index
+- **[../.github/instructions/generate-plugin.instructions.md](../.github/instructions/generate-plugin.instructions.md)** - Mustache template rules
+- **[../.github/instructions/scf-fields.instructions.md](../.github/instructions/scf-fields.instructions.md)** - SCF field types
 
 ## Support
 
@@ -728,4 +725,3 @@ For issues or questions:
 2. Review [SUPPORT.md](../SUPPORT.md)
 3. Check [CONTRIBUTING.md](../CONTRIBUTING.md)
 4. Open an issue on GitHub
-5. Use the [Development Assistant](.github/agents/development-assistant.agent.md)
diff --git a/docs/LINTING.md b/docs/LINTING.md
@@ -575,12 +575,8 @@ grep "error" logs/lint-*.log
 
 ## Related Documentation
 
-- [BUILD-PROCESS.md](./BUILD-PROCESS.md) - Build system and webpack configuration
-- [TESTING.md](./TESTING.md) - Testing strategies and dry-run testing
-- [LOGGING.md](./LOGGING.md) - Comprehensive logging for all tools and processes
-- [WORKFLOWS.md](./WORKFLOWS.md) - CI/CD automation and GitHub Actions
-- [VALIDATION.md](./VALIDATION.md) - Template validation
-- [PERFORMANCE.md](./PERFORMANCE.md) - Performance monitoring and optimization
+- **[BUILD-PROCESS.md](./BUILD-PROCESS.md)** - Build system prerequisite
+- **[README.md](./README.md)** - Documentation index
 
 ## Summary
 
diff --git a/docs/LOGGING.md b/docs/LOGGING.md
@@ -545,13 +545,8 @@ grep "ERROR" logs/*.log | sort | uniq -c | sort -rn
 
 ## Related Documentation
 
-- [BUILD-PROCESS.md](./BUILD-PROCESS.md) - Build process with logging
-- [TESTING.md](./TESTING.md) - Testing with integrated logging
-- [LINTING.md](./LINTING.md) - Linting with dry-run logging
-- [WORKFLOWS.md](./WORKFLOWS.md) - CI/CD logging in GitHub Actions
-- [PERFORMANCE.md](./PERFORMANCE.md) - Performance testing and logging
-- [logs/README.md](../logs/README.md) - Logs directory management
-- [DEVELOPMENT.md](../DEVELOPMENT.md) - Development workflow
+- **[logs/README.md](../logs/README.md)** - Logs directory implementation
+- **[README.md](./README.md)** - Documentation index
 
 ## Summary
 
diff --git a/docs/PERFORMANCE.md b/docs/PERFORMANCE.md
@@ -199,12 +199,7 @@ Performance reports are uploaded as artifacts:
 
 ## Related Documentation
 
-- [BUILD-PROCESS.md](./BUILD-PROCESS.md) - Build optimization and asset configuration
-- [WORKFLOWS.md](./WORKFLOWS.md) - CI/CD performance checks
-- [TESTING.md](./TESTING.md) - Testing strategies
-- [LOGGING.md](./LOGGING.md) - Performance test logging
-- [LINTING.md](./LINTING.md) - Code quality standards
-- [VALIDATION.md](./VALIDATION.md) - Template validation
+- **[README.md](./README.md)** - Documentation index
 
 ## Resources
 
diff --git a/docs/README.md b/docs/README.md
@@ -378,7 +378,7 @@ This scaffold is licensed under {{license}}. Generated plugins inherit this lice
 
 ## Related Documentation
 
-- [Main README](../README.md) - Repository root documentation
-- [Source Directory](../src/README.md) - Source files documentation
-- [Tests Directory](../tests/README.md) - Testing documentation
-- [Build Scripts](../bin/README.md) - Build script documentation
+- **[inc/README.md](../inc/README.md)** - PHP class files documentation
+- **[src/README.md](../src/README.md)** - Source files documentation
+- **[tests/README.md](../tests/README.md)** - Testing documentation
+- **[bin/README.md](../bin/README.md)** - Build script documentation
diff --git a/docs/REPORTING.md b/docs/REPORTING.md
@@ -635,13 +635,11 @@ Before finalizing a report:
 
 ## Related Documentation
 
-- [reporting.instructions.md](../.github/instructions/reporting.instructions.md) - Rules and standards
-- [reporting.agent.md](../.github/agents/reporting.agent.md) - AI agent for report generation
-- [reporting.prompt.md](../.github/prompts/reporting.prompt.md) - Interactive prompt template
-- [folder-structure.instructions.md](../.github/instructions/folder-structure.instructions.md) - Directory organization
-- [logs/README.md](../logs/README.md) - Logging documentation
-- [tmp/README.md](../tmp/README.md) - Temporary files documentation
-- [reports/README.md](../reports/README.md) - Reports directory index
+- **[README.md](./README.md)** - Documentation index
+- **[../.github/instructions/reporting.instructions.md](../.github/instructions/reporting.instructions.md)** - Rules and standards
+- **[logs/README.md](../logs/README.md)** - Logging documentation
+- **[tmp/README.md](../tmp/README.md)** - Temporary files documentation
+- **[reports/README.md](../reports/README.md)** - Reports directory index
 
 ## Summary
 
diff --git a/docs/SECURITY.md b/docs/SECURITY.md
@@ -300,10 +300,7 @@ if (!is_user_logged_in()) {
 
 ## Related Documentation
 
-- [TESTING.md](./TESTING.md) - Security testing strategies
-- [LINTING.md](./LINTING.md) - Code quality standards
-- [WORKFLOWS.md](./WORKFLOWS.md) - CI/CD security checks
-- [BUILD-PROCESS.md](./BUILD-PROCESS.md) - Secure build configuration
+- **[README.md](./README.md)** - Documentation index
 
 ## WordPress Security Resources
 
diff --git a/docs/TESTING.md b/docs/TESTING.md
@@ -861,8 +861,5 @@ For comprehensive logging documentation, see [LOGGING.md](./LOGGING.md).
 
 ## Related Documentation
 
-- [LOGGING.md](./LOGGING.md) - Comprehensive logging guide
-- [LINTING.md](./LINTING.md) - Linting and code quality standards
-- [VALIDATION.md](./VALIDATION.md) - Template validation
-- [BUILD-PROCESS.md](./BUILD-PROCESS.md) - Build system documentation
-- [WORKFLOWS.md](./WORKFLOWS.md) - CI/CD workflows
+- **[BUILD-PROCESS.md](./BUILD-PROCESS.md)** - Build system prerequisite
+- **[README.md](./README.md)** - Documentation index
diff --git a/docs/VALIDATION.md b/docs/VALIDATION.md
@@ -186,12 +186,7 @@ If the grep command returns no results, all templates were successfully replaced
 
 ## Related Documentation
 
-- [BUILD-PROCESS.md](./BUILD-PROCESS.md) - Build process and template usage
-- [TESTING.md](./TESTING.md) - Testing with template validation
-- [LINTING.md](./LINTING.md) - Code quality standards
-- [LOGGING.md](./LOGGING.md) - Validation logging
-- [WORKFLOWS.md](./WORKFLOWS.md) - CI/CD validation checks
-- [PERFORMANCE.md](./PERFORMANCE.md) - Performance considerations
+- **[README.md](./README.md)** - Documentation index
 
 ## Validation Date
 
diff --git a/docs/WORKFLOWS.md b/docs/WORKFLOWS.md
@@ -529,11 +529,4 @@ Never log secrets:
 
 ## Related Documentation
 
-- [BUILD-PROCESS.md](./BUILD-PROCESS.md) - Build process automation
-- [TESTING.md](./TESTING.md) - CI/CD testing integration
-- [LINTING.md](./LINTING.md) - Linting in workflows
-- [LOGGING.md](./LOGGING.md) - Workflow execution logging
-- [PERFORMANCE.md](./PERFORMANCE.md) - Performance monitoring in CI/CD
-- [VALIDATION.md](./VALIDATION.md) - Template and code validation
-- [AGENTS-OVERVIEW.md](./AGENTS-OVERVIEW.md) - AI agents in workflows
-- [TESTING.md](./TESTING.md) - Comprehensive testing guide
+- **[README.md](./README.md)** - Documentation index
diff --git a/patterns/README.md b/patterns/README.md
