# Pr Author Agent

> AI-powered PR Author Agent that transforms Observability Diff Plans into Pull Requests. Use when: (1) Generating instrumentation code from Scout Agent output, (2) Creating OTel configuration, correlation headers, lineage specs, (3) Scaffolding telemetry validation tests, (4) Creating GitHub/GitLab PRs with observability artifacts. Triggers: "generate PR from diff plan", "create instrumentation PR", "scaffold observability code", "generate OTel config".

- Skill: `kart-rc/pr-author-agent` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kart-rc/pr-author-agent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kart-rc/pr-author-agent/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Kart-rc (https://skillmd.com/u/kart-rc)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/kart-rc/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:

| Variable | Source | Example |
|----------|--------|---------|
| `${SERVICE_NAME}` | Diff Plan repo name | `orders-enricher` |
| `${SERVICE_URN}` | Computed from repo | `urn:svc:prod:commerce:orders-enricher` |
| `${INPUT_TOPIC}` | Detected from code | `orders_raw` |
| `${OUTPUT_TOPIC}` | Detected from code | `orders_enriched` |
| `${OWNER_TEAM}` | CODEOWNERS or default | `orders-team` |
| `${CONSUMER_GROUP}` | Detected from config | `orders-enricher-cg` |

## PR Description Template

```markdown
## 🤖 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

| System | Integration | Purpose |
|--------|-------------|---------|
| Scout Agent | Event bus subscriber | Receive Diff Plans |
| GitHub | REST API | Create PRs, branches, commits |
| GitLab | REST API | Alternative VCS support |
| Schema Registry | REST API | Validate schema compatibility |
| Template Store | File system / S3 | Load templates |

## Configuration

```yaml
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
```