| Document Number: | CPPA0001R0 |
|---|---|
| Date: | 2026-01-22 |
| Project: | C++ Alliance Clang Initiative |
| Reply-to: | C++ Alliance Staff |
| Audience: | Technical collaborators, contributors |
This document specifies a human-agentic workflow for systematic Clang development. The workflow combines GitHub-based coordination, high-performance cloud build infrastructure, and frontier AI coding models to amplify the effectiveness of human compiler experts. Staff create issues requesting fixes or features; an AI backend generates candidate patches; human reviewers refine submissions through iterative collaboration; validated patches advance to upstream LLVM. The architecture preserves human judgment at all critical decision points while delegating production tasks to AI systems.
The Clang compiler maintains a substantial bug backlog. New C++ standard features require implementation effort that exceeds available contributor bandwidth. Traditional development workflows constrain throughput: each patch requires manual authorship, testing, and iteration through review cycles. Human experts spend significant time on mechanical tasks—generating boilerplate, writing tests, formatting code—that do not require their specialized judgment.
A human-agentic workflow restructures the development process around a core insight: AI systems excel at production tasks while humans provide irreplaceable judgment. By routing mechanical work to AI and reserving human attention for decisions that require compiler expertise, the workflow amplifies expert effectiveness by approximately two orders of magnitude.
The system comprises three integrated components:
- GitHub Interface Layer: Issues, pull requests, and branches provide the coordination substrate
- Cloud Build Infrastructure: High-performance servers deliver near-instant Clang compilation
- AI Processing Backend: Frontier coding models generate candidate patches under GitHub App orchestration
The workflow operates through GitHub as the primary interface. A GitHub App monitors repository events and dispatches work to AI coding models. A dedicated cloud instance provides continuous integration with build times sufficient to validate patches without blocking iteration.
flowchart LR
Issue[Staff Opens Issue] --> AI[AI Generates Patch]
AI --> PR[PR to Fork]
PR --> Build[Cloud Build]
Build --> Review[Human Expert Review]
Review -->|Feedback| AI
Review -->|Approved| Merge[Merge to Fork]
Merge --> Upstream[Submit Upstream]
The C++ Alliance maintains a fork of Clang under its GitHub organization. The repository structure isolates AI-assisted work from upstream until human validation completes:
- Orphan branch (default): Contains project documentation, strategy, and roadmap without code history
- Feature branches: Each AI-assisted contribution occupies a dedicated branch
- Main tracking branch: Mirrors upstream LLVM/Clang for synchronization
This structure ensures that only polished, human-validated patches reach upstream review.
Staff members open issues in the fork repository requesting specific fixes or feature implementations. Issues follow a structured format:
- Clear problem statement or feature specification
- Relevant upstream bug references where applicable
- Acceptance criteria for the patch
- Priority designation
The GitHub App monitors issue creation events and initiates processing.
Upon issue assignment, the AI backend:
- Retrieves issue context and referenced materials
- Analyzes relevant Clang source files
- Generates a candidate patch addressing the specification
- Produces accompanying test cases
- Submits a pull request to the fork
The AI operates as a contributor, not an authority. All generated code requires human approval before advancement.
Designated reviewers examine AI-generated pull requests. The review team comprises compiler experts with deep knowledge of Clang internals:
- Technical evaluation: Correctness, edge cases, performance implications
- Style conformance: LLVM coding standards compliance
- Test adequacy: Coverage of specified behavior
Reviewers interact with the AI as a collaborator. Review comments trigger refinement cycles:
- Reviewer posts feedback on the pull request
- GitHub App detects review activity
- AI processes feedback and generates updated patch
- Cycle repeats until approval or rejection
This interaction model preserves the reviewer's technical authority while eliminating manual patch revision effort.
Upon approval:
- Pull request merges to the fork's feature branch
- Staff prepares the patch for upstream submission
- Patch enters standard LLVM review process
- Accepted patches merge to official Clang repository
The private-first approach ensures AI-generated code undergoes refinement before public exposure, avoiding premature scrutiny of unpolished work.
Each pull request that has been approved for upstream will have an accompanying markdown document explaining the change along with rationale, impact, and highlighting non-obvious things. This document will be inlined into the commit message so it becomes a permanent, searchable record in the repository.
The workflow demands build infrastructure capable of:
- Near-instant validation: Patches must compile and test without blocking review iteration
- Continuous synchronization: Builds track upstream LLVM head
- Parallel capacity: Multiple pull requests build concurrently
A dedicated cloud instance provides:
- High core count for parallel compilation
- SSD storage for source and build artifacts
- Persistent incremental build state
- Automated upstream synchronization
Build results post directly to pull requests, providing immediate feedback on patch viability.
The GitHub App serves as the orchestration layer:
- Monitors repository events (issues, pull requests, comments)
- Dispatches work to AI coding models
- Posts AI responses as pull requests and comments
- Tracks conversation state across review cycles
The backend employs frontier AI coding models capable of:
- Understanding compiler source code structure
- Generating syntactically and semantically correct patches
- Producing test cases that exercise specified behavior
- Incorporating review feedback into revisions
Model selection prioritizes code generation quality over latency. The asynchronous workflow accommodates model response times without blocking human reviewers.
Effective patch generation requires appropriate context:
- Issue specification and acceptance criteria
- Relevant source files from the Clang codebase
- Prior review comments and revision history
- LLVM coding standards and conventions
The GitHub App assembles context packages before dispatching to AI models.
Human attention constitutes the scarcest resource in the workflow. Compiler experts possess judgment that AI systems cannot replicate: understanding of subtle correctness requirements, awareness of historical design decisions, and intuition about maintainability implications.
The workflow maximizes the value of expert attention by:
- Routing only decision-requiring work to humans
- Presenting AI-generated options for evaluation rather than blank slates
- Automating mechanical revision based on human feedback
Traditional workflows require experts to perform both judgment and production tasks. An expert reviewing a bug might spend:
- 20% of time on technical evaluation (judgment)
- 80% of time on patch authorship, testing, and revision (production)
The human-agentic workflow inverts this ratio. Experts focus on evaluation and feedback while AI handles production. The same expert attention that previously addressed one bug now addresses ten or more.
Expert corrections accumulate as workflow artifacts:
- Review comments capture reasoning about correctness
- Revision history shows how feedback transforms into code
- Approved patterns inform future AI generations
Unlike tacit knowledge that disappears when experts depart, workflow artifacts persist in the repository.
Every patch passes through mandatory gates:
- AI generation: Initial patch must compile and pass existing tests
- Human review: Designated expert must approve
- Build validation: CI confirms no regressions
- Upstream review: Standard LLVM process applies
No patch advances without explicit human approval at gate 2.
AI-generated patches remain in the private fork until human review completes. This approach:
- Avoids exposing unrefined work to upstream maintainers
- Prevents "AI allergy" reactions to clearly machine-generated code
- Ensures public submissions meet community quality expectations
Patches submitted upstream conform to LLVM requirements:
- Coding style compliance
- Test coverage
- Documentation updates where applicable
- Commit message conventions
The workflow produces patches indistinguishable from traditional human-authored contributions.
- Staff: Open issues, prioritize work, coordinate upstream submission
- Reviewers: Provide technical evaluation and approval
- AI Backend: Generate patches and revisions
- Infrastructure: Maintain build systems and GitHub App
The #cppa-clang Slack channel provides coordination among team members. Technical discussion occurs primarily in GitHub issue and pull request comments to preserve context in the repository.
- Eliminate existing Clang bug backlog
- Respond to new issues immediately upon filing
- Establish sustainable patch velocity
- Implement C++ standard library components ahead of other vendors
- Ship complete feature support for each new C++ standard before competitors
- Establish C++ Alliance as a major Clang contributor
- Expand reviewer pool as patch volume increases
- Add support for additional LLVM subprojects
- Develop specialized AI prompting for different contribution types
- Retrospective analysis of upstream acceptance rates
- Feedback loop from upstream review to AI training
- Metrics collection on reviewer time and patch quality
- LLVM Coding Standards: https://llvm.org/docs/CodingStandards.html
- LLVM Code Review Policy: https://llvm.org/docs/CodeReview.html
- Clang Developer Documentation: https://clang.llvm.org/docs/InternalsManual.html