Add package-level documentation to core packages

[Copilot]

Sergo analysis identified 5 major packages lacking package-level documentation, preventing proper go doc output and pkg.go.dev presentation.

Changes

Added doc.go files to:

• pkg/workflow/ - Core compilation pipeline: markdown → GitHub Actions YAML, with security features (SHA pinning, safe outputs, network sandboxing)
• pkg/types/ - Shared type definitions bridging parser and workflow packages (e.g., BaseMCPServerConfig)
• pkg/cli/ - Command-line interface structure, standard flags, console formatting patterns
• pkg/parser/ - Frontmatter extraction, import resolution, GitHub URL handling
• pkg/logger/ - Zero-overhead namespace-based debug logging with pattern matching

Each doc includes:

• Package purpose and key concepts
• Runnable usage examples
• Architecture overview showing component interactions
• Cross-references to related packages

Example

// Package workflow provides compilation and generation of GitHub Actions workflows
// from markdown-based agentic workflow specifications.
//
// # Basic Usage
//
//	compiler := workflow.NewCompiler(workflow.CompilerOptions{
//		Verbose: true,
//	})
//	err := compiler.CompileWorkflow("path/to/workflow.md")

Documentation now appears correctly in go doc and will render properly on pkg.go.dev.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[plan] Add package-level documentation to core packages</issue_title>
<issue_description>## Objective

Add comprehensive package-level documentation comments to major packages for better API discoverability and developer onboarding.

Context

From discussion githubnext/gh-aw#12006: Sergo analysis found missing package-level documentation across 5+ major packages. Go convention requires // Package X comments for proper pkg.go.dev presentation and go doc output.

Packages to Document

Priority order:

1. pkg/workflow/ - Core compilation logic (600+ files, most critical)
2. pkg/types/ - Type definitions
3. pkg/cli/ - CLI interface
4. pkg/parser/ - Markdown/YAML parsing
5. pkg/logger/ - Logging utilities

Documentation Requirements

Each package doc should include:

• Purpose: What the package does
• Key concepts: Main abstractions and terminology
• Basic usage: Simple code example
• Architecture: How components fit together
• Links: Related packages or documentation

Example Template

// Package workflow provides compilation and generation of GitHub Actions workflows
// from markdown-based agentic workflow specifications.
//
// The workflow package is the core of gh-aw, handling the transformation of
// user-friendly markdown files into production-ready GitHub Actions YAML workflows.
// It supports advanced features including:
//   - Agentic AI workflow execution with Claude, Codex, and Copilot engines
//   - Safe output handling with configurable permissions
//   - MCP (Model Context Protocol) server integration
//   - Network sandboxing and firewall configuration
//
// # Basic Usage
//
//     compiler := workflow.NewCompiler(workflow.CompilerOptions{
//         Verbose: true,
//     })
//     err := compiler.CompileWorkflow("path/to/workflow.md")
//
// # Architecture
//
// The compilation process consists of:
//  1. Frontmatter parsing (YAML metadata extraction)
//  2. Markdown processing (prompt extraction)
//  3. Tool configuration (MCP servers, safe outputs)
//  4. Job generation (main, activation, safe output jobs)
//  5. YAML generation (final GitHub Actions workflow)
package workflow

Acceptance Criteria

• All 5 packages have comprehensive package-level docs
• Documentation includes purpose, usage example, and architecture overview
• go doc pkg/workflow produces readable output
• pkg.go.dev presentation is clear and professional
• Code examples compile without errors

AI generated by Plan Command for discussion #12006

Comments on the Issue (you are @copilot in this section)

• Fixes [plan] Add package-level documentation to core packages #12181

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[github-actions]

🔍 PR Triage Results

Category: docs | Risk: low | Priority: 39/100

Scores Breakdown

• Impact: 18/50 - Documentation improvements enhance developer onboarding and API discoverability
• Urgency: 12/30 - Very recent PR (<1 hour old), CI showing some feedback
• Quality: 9/20 - Draft status, CI unstable but providing feedback

📋 Recommended Action: defer

Rationale: This PR adds comprehensive package-level documentation to 5 core packages (workflow, parser, cli, logger, types), improving pkg.go.dev presentation and go doc output. While low-risk (documentation only), it should remain deferred until out of draft. The 390 lines of new documentation follow Go conventions and include usage examples.

Next steps: Mark as ready for review when CI is green and all packages are properly documented.

---

Triaged by PR Triage Agent on 2026-01-28

AI generated by PR Triage Agent