PR Author Agent

The PR Author Agent transforms Observability Diff Plans (from Scout Agent) into complete Pull Requests containing instrumentation code, configuration, tests, and documentation.

Core Responsibilities

1. Template Selection: Choose archetype-specific templates based on Diff Plan
2. Code Generation: Generate OTel interceptors, correlation headers, configs
3. Lineage Spec Creation: Create YAML specs defining input/output mappings
4. Contract Stub Generation: Create data contract definitions with SLOs
5. Test Scaffolding: Generate telemetry validation tests
6. Runbook Generation: Create operational runbooks from templates
7. PR Creation: Create GitHub/GitLab PR with all artifacts

Workflow

Step 1: Parse Diff Plan

Read the Observability Diff Plan JSON:

• Extract archetypes, tech_stack, gaps, patch_plan
• Validate plan schema
• Check confidence threshold (default >= 0.7)

Step 2: Select Templates

For each gap in the plan:

1. Match gap.template to template library
2. Load template files from references/templates/
3. Prepare variable context for interpolation

Step 3: Generate Artifacts

For each template, generate:

• Code files: Interceptors, wrappers, middleware
• Config files: application.yaml, go.mod additions
• Spec files: lineage/.yaml, contracts/.yaml
• Test files: *_test.java, *_test.py, *_test.go
• Docs: RUNBOOK.md

Step 4: Create Pull Request

Using GitHub/GitLab API:

1. Create branch: autopilot/observability-{repo}-{timestamp}
2. Commit all generated files
3. Create PR with description from template
4. Apply labels: autopilot, observability
5. Request reviewers based on CODEOWNERS

Template Library

Templates organized by archetype and language:

references/templates/
├── java/
│   ├── kafka-consumer-otel/
│   ├── kafka-producer-otel/
│   ├── kafka-producer-headers/
│   └── spring-boot-otel/
├── python/
│   ├── kafka-otel/
│   ├── airflow-openlineage/
│   └── spark-openlineage/
├── go/
│   ├── kafka-sarama-otel/
│   ├── gin-otel/
│   ├── echo-otel/
│   └── grpc-otel/
└── common/
    ├── lineage-spec/
    ├── contract-stub/
    └── runbook/

Variable Interpolation

Templates use ${VAR} syntax:

PR Description Template

## 🤖 Autopilot: Observability Instrumentation

This PR was generated by the Instrumentation Autopilot to add observability
instrumentation to this repository.

### Changes
${CHANGES_LIST}

### Gaps Addressed
${GAPS_LIST}

### Verification
- [ ] Code review approved
- [ ] Tests passing
- [ ] Lineage spec reviewed
- [ ] Contract SLOs appropriate

### Next Steps
After merge, the Telemetry Validator will verify signals in staging.

---
*Generated by Instrumentation Autopilot v1.0*
*Confidence: ${CONFIDENCE}*
*Diff Plan: ${DIFF_PLAN_ID}*

Scripts

• scripts/generate_pr.py: Main PR generation orchestrator
• scripts/template_engine.py: Template interpolation engine
• scripts/github_client.py: GitHub API wrapper
• scripts/gitlab_client.py: GitLab API wrapper

References

• references/templates/: Archetype-specific code templates
• references/pr-template.md: PR description template
• references/variable-mapping.md: Variable interpolation rules

OpenSpec Workflows

For Windsurf development:

• assets/windsurf/workflows/pr-author-generate.md: Generate PR workflow
• assets/windsurf/workflows/pr-author-template.md: Create template workflow
• assets/windsurf/workflows/pr-author-test.md: Test generation workflow

Integration Points

Configuration

pr_author:
  enabled: true
  auto_create_pr: true
  require_human_review: true
  templates_path: "/opt/autopilot/templates"
  default_branch: "main"
  pr_labels: ["autopilot", "observability"]
  confidence_threshold: 0.7
  github:
    app_id: 12345
    installation_id: 67890