diff --git a/docs/src/content/docs/blog/2026-01-30-imports-and-sharing.md b/docs/src/content/docs/blog/2026-01-30-imports-and-sharing.md index da906c817c..2b66497750 100644 --- a/docs/src/content/docs/blog/2026-01-30-imports-and-sharing.md +++ b/docs/src/content/docs/blog/2026-01-30-imports-and-sharing.md @@ -31,45 +31,15 @@ Let's dive in! ## The Power of Imports -Imports provide several game-changing benefits that transformed how we develop and maintain the factory: +Imports transform workflow development through four key benefits: -### 🔄 DRY Principle for Agentic Workflows +**DRY Principle**: When we enhanced [`reporting.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/reporting.md), all 46 workflows that imported it immediately benefited. One change, 46 workflows improved. -When we improve report formatting or update an MCP server configuration, the change automatically propagates to all workflows that import it. No need to update 46 workflows individually. That's huge! +**Composable Capabilities**: Workflows mix and match components like LEGO blocks. Need visualization, JSON processing, and web search? Just import `python-dataviz.md`, `jqschema.md`, and `mcp/tavily.md`. -For example, when we enhanced the [`reporting.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/reporting.md) component with better formatting guidelines, all 46 workflows that imported it immediately benefited. One change, 46 workflows improved. Magic. +**Separation of Concerns**: Infrastructure teams manage MCP servers, security teams handle network policies, data teams build visualization components, and agent authors focus on prompts. -### 🧩 Composable Workflow Capabilities - -Workflows can mix and match capabilities by importing different shared components - like combining data visualization, trending analysis, and web search in a single import list. - -A typical analytical workflow might import: - -- `reporting.md` for report formatting -- `python-dataviz.md` for visualization capabilities -- `jqschema.md` for JSON processing -- `mcp/tavily.md` for web search - -Each import adds a specific capability, and workflows compose exactly what they need. It's like LEGO blocks for agents! - -### 🎯 Separation of Concerns - -Tools configuration, network permissions, data fetching logic, and agent instructions can be maintained independently by different experts, then composed together. - -This allows specialization: - -- Infrastructure team manages MCP server configurations -- Security team maintains network policies -- Data team builds visualization components -- Agent authors focus on prompts and logic - -Everyone works on what they know best, and it all comes together seamlessly. - -### ⚡ Rapid Experimentation - -Creating a new workflow often means writing just the agent-specific prompt and importing 3-5 shared components. We can prototype new agents in minutes instead of hours. - -Example minimal workflow: +**Rapid Experimentation**: New workflows often need just a prompt and 3-5 imports. Prototype agents in minutes: ```markdown --- @@ -83,125 +53,34 @@ imports: Analyze the codebase for common patterns... ``` -That's it! Three imports give you reporting, code analysis, and JSON processing. You just focus on writing the prompt. - ## The Import Library The factory organized shared components into two main directories: ### Core Capabilities: `.github/workflows/shared/` -35+ components providing fundamental capabilities: - -#### Most Popular Shared Components - -**[`reporting.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/reporting.md?plain=1)** (46 imports) - -- Report formatting guidelines -- Workflow run references -- Footer standards -- Consistent structure - -**[`jqschema.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/jqschema.md?plain=1)** (17 imports) - -- JSON querying utilities -- Schema validation -- Data transformation patterns - -**[`python-dataviz.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/python-dataviz.md?plain=1)** (7 imports) - -- Python environment with NumPy, Pandas, Matplotlib, Seaborn -- Data visualization templates -- Chart generation utilities - -**[`trending-charts-simple.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/trending-charts-simple.md?plain=1)** (6 imports) - -- Quick setup for trend visualizations -- Time-series analysis -- Comparison charts +35+ components providing fundamental capabilities. Top imports: -**[`gh.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/gh.md?plain=1)** (4 imports) +- [`reporting.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/reporting.md?plain=1) (46) - Report formatting, workflow references, consistent structure +- [`jqschema.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/jqschema.md?plain=1) (17) - JSON querying and schema validation +- [`python-dataviz.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/python-dataviz.md?plain=1) (7) - Data visualization with NumPy, Pandas, Matplotlib +- [`trending-charts-simple.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/trending-charts-simple.md?plain=1) (6) - Trend visualizations and time-series +- [`gh.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/gh.md?plain=1) (4) - Safe-input wrapper for GitHub CLI +- [`copilot-pr-data-fetch.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/copilot-pr-data-fetch.md?plain=1) (4) - Copilot data fetching and cache management -- Safe-input wrapper for GitHub CLI -- Authentication handling -- Common gh commands - -**[`copilot-pr-data-fetch.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/copilot-pr-data-fetch.md?plain=1)** (4 imports) - -- Fetch GitHub Copilot PR data -- Cache management -- Data preprocessing - -#### Specialized Components - -**Data Analysis** - -- [`charts-with-trending.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/charts-with-trending.md) - Comprehensive trending with cache-memory -- [`ci-data-analysis.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/ci-data-analysis.md) - CI workflow analysis -- [`session-analysis-charts.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/session-analysis-charts.md) - Copilot session visualization - -**Prompting & Output** - -- [`keep-it-short.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/keep-it-short.md) - Guidance for concise responses -- [`safe-output-app.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/safe-output-app.md) - Safe output patterns +Plus specialized components for data analysis ([`charts-with-trending.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/charts-with-trending.md), [`ci-data-analysis.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/ci-data-analysis.md)), prompting ([`keep-it-short.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/keep-it-short.md)), and safe outputs ([`safe-output-app.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/safe-output-app.md)). ### MCP Server Configurations: `.github/workflows/shared/mcp/` -20+ MCP server configurations for specialized capabilities: - -#### Most Used MCP Servers - -**[`gh-aw.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/mcp/gh-aw.md?plain=1)** (12 imports) - -- GitHub Agentic Workflows MCP server -- `logs` command for workflow debugging -- Workflow metadata access - -**[`tavily.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/mcp/tavily.md?plain=1)** (5 imports) - -- Web search via Tavily API -- Research capabilities -- Current information access - -**[`markitdown.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/mcp/markitdown.md?plain=1)** (3 imports) - -- Document conversion (PDF, Office, images to Markdown) -- Content extraction -- Multimedia analysis - -**[`ast-grep.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/mcp/ast-grep.md?plain=1)** (2 imports) - -- Structural code search and analysis -- Pattern matching -- Refactoring support - -**[`brave.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/mcp/brave.md?plain=1)** (2 imports) - -- Alternative web search via Brave API -- Privacy-focused search -- Diverse search results - -#### Infrastructure & Analysis - -**Development Tools** - -- [`jupyter.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/mcp/jupyter.md) - Jupyter notebook environment with Docker services -- [`skillz.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/mcp/skillz.md) - Dynamic skill loading from `.github/skills/` -- [`serena.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/mcp/serena.md) - Semantic code analysis - -**Knowledge & Search** +20+ MCP server configurations for specialized capabilities. Top servers: -- [`context7.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/mcp/context7.md) - Context-aware search -- [`deepwiki.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/mcp/deepwiki.md) - Wikipedia deep search -- [`microsoft-docs.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/mcp/microsoft-docs.md) - Microsoft documentation -- [`arxiv.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/mcp/arxiv.md) - Academic paper research +- [`gh-aw.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/mcp/gh-aw.md?plain=1) (12) - Workflow debugging and metadata access +- [`tavily.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/mcp/tavily.md?plain=1) (5) - Web search and research +- [`markitdown.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/mcp/markitdown.md?plain=1) (3) - Document conversion (PDF, Office to Markdown) +- [`ast-grep.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/mcp/ast-grep.md?plain=1) (2) - Structural code search +- [`brave.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/mcp/brave.md?plain=1) (2) - Privacy-focused web search -**External Integrations** - -- [`slack.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/mcp/slack.md) - Slack workspace integration -- [`notion.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/mcp/notion.md) - Notion workspace integration -- [`sentry.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/mcp/sentry.md) - Error tracking -- [`datadog.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/mcp/datadog.md) - Observability platform +Plus development tools ([`jupyter.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/mcp/jupyter.md), [`serena.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/mcp/serena.md)), knowledge sources ([`arxiv.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/mcp/arxiv.md), [`deepwiki.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/mcp/deepwiki.md)), and external integrations ([`slack.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/mcp/slack.md), [`notion.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/mcp/notion.md), [`sentry.md`](https://github.com/githubnext/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/shared/mcp/sentry.md)). ## Import Statistics @@ -262,61 +141,13 @@ This ensures stability for production workflows while allowing experimentation w ## Best Practices for Imports -### Creating Shared Components - -**Do:** - -- ✅ Make components focused and single-purpose -- ✅ Document configuration options -- ✅ Version significant changes -- ✅ Test with multiple importers -- ✅ Provide examples - -**Don't:** - -- ❌ Create monolithic "kitchen sink" components -- ❌ Break existing importers without versioning -- ❌ Duplicate functionality across components -- ❌ Hard-code repository-specific values -- ❌ Forget to update documentation - -### Using Imports Effectively +**Creating shared components**: Keep them focused and single-purpose. Document configuration options, version significant changes, and test with multiple importers. Avoid monolithic components, breaking changes without versioning, or hard-coding repository-specific values. -**Do:** - -- ✅ Import only what you need -- ✅ Override imported settings when necessary -- ✅ Pin critical production workflows -- ✅ Document why each import is needed -- ✅ Test after updating imports - -**Don't:** - -- ❌ Import conflicting components -- ❌ Override without understanding impact -- ❌ Use unpinned imports in production -- ❌ Cargo-cult import lists -- ❌ Forget to recompile after changes +**Using imports effectively**: Import only what you need and pin critical production workflows. Override imported settings when necessary, but understand the impact. Test after updates and document why each import is needed. Avoid conflicting components and cargo-cult import lists. ## Evolution of Shared Components -The shared component library evolved organically: - -### Phase 1: Duplication (Workflows 1-10) - -Early workflows duplicated configuration. Copy-paste was fastest for initial prototypes. - -### Phase 2: Extraction (Workflows 11-30) - -As patterns emerged, we extracted common configurations into shared files. First components: `reporting.md` and `python-dataviz.md`. - -### Phase 3: Ecosystem (Workflows 31-80) - -Component library grew to cover most common needs. New workflows primarily composed existing components. - -### Phase 4: Specialization (Later Workflows) - -Highly specialized components emerged for specific domains (Copilot analysis, security scanning, etc.). +The shared component library evolved organically from duplication (workflows 1-10 copy-pasted configuration) to extraction (11-30 created `reporting.md` and `python-dataviz.md`) to ecosystem (31-80 composed existing components) to specialization (domain-specific components for Copilot analysis, security scanning). ## Impact on Velocity @@ -332,49 +163,13 @@ The imports system dramatically accelerated development: ## Common Import Patterns -### The Analyst Stack - -```markdown -imports: - - shared/reporting.md - - shared/jqschema.md - - shared/python-dataviz.md -``` - -For read-only analysis workflows with visualization. - -### The Researcher Stack - -```markdown -imports: - - shared/reporting.md - - shared/mcp/tavily.md - - shared/mcp/arxiv.md -``` - -For research-heavy workflows needing web search and academic papers. - -### The Code Intelligence Stack +**Analyst**: `reporting.md` + `jqschema.md` + `python-dataviz.md` for read-only analysis with visualization. -```markdown -imports: - - shared/reporting.md - - shared/mcp/serena.md - - shared/mcp/ast-grep.md -``` - -For semantic code analysis and refactoring. +**Researcher**: `reporting.md` + `mcp/tavily.md` + `mcp/arxiv.md` for web search and academic papers. -### The Meta-Agent Stack - -```markdown -imports: - - shared/reporting.md - - shared/mcp/gh-aw.md - - shared/charts-with-trending.md -``` +**Code Intelligence**: `reporting.md` + `mcp/serena.md` + `mcp/ast-grep.md` for semantic analysis and refactoring. -For workflows that analyze other workflows. +**Meta-Agent**: `reporting.md` + `mcp/gh-aw.md` + `charts-with-trending.md` for workflows analyzing workflows. ## What's Next?