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