Pr Author Agent

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