chore: plan 427, PR 2 of agent-first development plan

[nabinchha]

📋 Summary

Implements PR 2 of the agent-first development plan (#427), covering Phase 3 (GitHub machinery) and architecture doc population. PR 1 (#454) restructured the top-level documentation and created the architecture stubs; this PR fills them with content and adds the GitHub templates that make the agent-assisted contribution workflow concrete.

🔗 Related Issue

PR-2 for #427

🔄 Changes

Architecture Documentation (10 files populated)

All architecture/ stubs from PR 1 are now populated with content covering overview, key components, data flow, design decisions, and cross-references:

• overview.md — System architecture: three-package layout, PEP 420 namespace packages, end-to-end data flow, dual execution engines
• config.md — Config layer: builder API, column configs, discriminated unions, model configs, plugin injection, lazy imports
• engine.md — Engine layer: compilation pipeline, registry system, column generator hierarchy, ResourceProvider
• models.md — Model subsystem: facade pattern, AIMD throttling, retry transport, usage tracking, MCP tool loops
• mcp.md — MCP subsystem: MCPIOService, session pooling, tool schema coalescing, turn limits
• dataset-builders.md — Dataset builders: sequential/async execution, ExecutionGraph, CompletionTracker, DAG, DatasetBatchManager
• sampling.md — Sampling: DatasetGenerator, constraint system, person/entity generation, managed datasets
• cli.md — CLI: lazy command loading, controller/service/repo pattern, generation commands
• agent-introspection.md — Agent introspection: FamilySpec, type discovery, state commands, error handling
• plugins.md — Plugin system: entry-point discovery, PluginRegistry, union injection, custom columns comparison

GitHub Templates (Phase 3)

• .github/PULL_REQUEST_TEMPLATE.md — New PR template: Summary, Related Issue, Changes, Testing checklist, Checklist
• .github/ISSUE_TEMPLATE/bug-report.yml — Added Agent Diagnostic field and investigation checklist
• .github/ISSUE_TEMPLATE/feature-request.yml — Added Agent Investigation field and review checklist
• .github/ISSUE_TEMPLATE/development-task.yml — Added Investigation/Context and Agent Plan fields
• .github/ISSUE_TEMPLATE/config.yml — Updated Discussions link copy to mention agent-assisted workflow

Skill Template Conformance

• .agents/skills/create-pr/SKILL.md — Updated to produce PR descriptions matching the new PR template structure (Summary, Related Issue, Changes, Testing, Checklist)

Not Yet Addressed (from plan step list)

• CODEOWNERS update (step 9) — Plan calls for keeping the existing single-group ownership, so no change needed
• Label creation (step 10) — Already created via gh label create after merge, or in a follow-up

🔍 Attention Areas

⚠️ Reviewers: Please pay special attention to the following:

• Architecture docs accuracy — Each doc was written from source code analysis. Please verify the descriptions match current behavior, especially for dataset-builders.md (async engine) and models.md (AIMD throttling).
• Issue template fields — The new agent diagnostic/investigation fields are optional (not required). Verify this matches the intended contributor experience.

🧪 Testing

• N/A — documentation and template changes only, no testable logic

✅ Checklist

• Follows commit message conventions
• Commits are signed off (DCO)
• Architecture docs updated (this is the PR that populates them)

[greptile-apps]

Greptile Summary

This PR completes Phase 3 of the agent-first development plan (#427) by populating all ten architecture/ stub documents with source-accurate content and adding the GitHub machinery (PR template, updated issue templates, create-pr skill alignment) that makes the agent-assisted contribution workflow concrete.

Key changes:

• All ten architecture/ stubs are replaced with detailed documentation covering key components, data flow diagrams, design decisions, and cross-references — forming a complete, internally consistent system map for both human and agent contributors.
• A new PULL_REQUEST_TEMPLATE.md standardises PR descriptions with Summary, Related Issue, Changes, Testing, and Checklist sections.
• bug-report.yml, feature-request.yml, and development-task.yml each gain optional agent diagnostic/investigation fields and submission checklists.
• The create-pr skill is updated to generate PR bodies conforming to the new template structure.
• Two minor consistency issues found: (1) the \"This is a design proposal\" checkbox in feature-request.yml is required: true, which could block contributors who don't identify their request as a proposal; (2) PULL_REQUEST_TEMPLATE.md is missing the (or: N/A — no testable logic) annotation referenced in SKILL.md.

No code changes are included — this is a documentation and template-only PR.

Confidence Score: 5/5

Safe to merge — documentation and template-only changes with no runtime code impact.

All findings are P2 style/consistency suggestions. The only files that touch executable behaviour are GitHub form templates (YAML), and the only concern is a UX design choice (required checkbox) that is unlikely to cause user-facing failures. Architecture docs are accurate and internally consistent with AGENTS.md. No logic, security, or data-integrity risks.

.github/ISSUE_TEMPLATE/feature-request.yml — review the required=true checkbox; .github/PULL_REQUEST_TEMPLATE.md — consider adding 'or: N/A' annotation to the unit-tests line.

Important Files Changed

Filename	Overview
.github/ISSUE_TEMPLATE/feature-request.yml	Adds optional Agent Investigation field and checklist; 'This is a design proposal' is required=true, which hard-blocks submission for contributors not framing their request as a proposal.
.github/PULL_REQUEST_TEMPLATE.md	New PR template with Summary, Related Issue, Changes, Testing, and Checklist sections; testing items lack the 'or: N/A' annotation present in the SKILL.md example.
.agents/skills/create-pr/SKILL.md	Updated to align PR body generation with the new template structure; section guidelines are clear and comprehensive.
architecture/overview.md	Replaces stub with detailed architecture overview covering three-package layout, PEP 420 namespace packages, end-to-end data flow, and design decisions — consistent with AGENTS.md.
architecture/dataset-builders.md	Replaces stub with comprehensive documentation of both execution modes, ExecutionGraph, CompletionTracker, DAG, and DatasetBatchManager with accurate dual-mode data flow diagrams.
architecture/models.md	Replaces stub with layered model subsystem docs: ModelRegistry → ModelFacade → ThrottledModelClient (AIMD) → ModelClient → RetryTransport. Accurate description of facade pattern, usage tracking, and rate-limit handling.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Contributor / Agent] -->|opens issue| B{Issue Template}
    B -->|bug| C[bug-report.yml\n+ Agent Diagnostic field\n+ Checklist]
    B -->|feature| D[feature-request.yml\n+ Agent Investigation field\n+ Checklist]
    B -->|task| E[development-task.yml\n+ Investigation/Context\n+ Agent Plan fields]
    A -->|submits PR| F[PULL_REQUEST_TEMPLATE.md\nSummary · Related Issue\nChanges · Testing · Checklist]
    G[create-pr SKILL.md] -->|instructs AI to fill| F
    H[architecture/] -->|documents system for agents| A
    H --> H1[overview.md]
    H --> H2[config.md]
    H --> H3[engine.md]
    H --> H4[models.md]
    H --> H5[mcp.md]
    H --> H6[dataset-builders.md]
    H --> H7[sampling.md]
    H --> H8[cli.md]
    H --> H9[agent-introspection.md]
    H --> H10[plugins.md]
    style F fill:#d4edda,stroke:#28a745
    style G fill:#cce5ff,stroke:#004085
    style H fill:#fff3cd,stroke:#856404

Loading

Comments Outside Diff (2)

1. .github/ISSUE_TEMPLATE/feature-request.yml, line 213-215 (link)

   required: true may block legitimate feature requests

   Marking "This is a design proposal, not a 'please build this' request" as required: true means GitHub's form will hard-block submission unless the contributor checks this box. A user who simply wants to describe a desired capability — without thinking of themselves as writing a design proposal — will either abandon the form or check the box without meaning it. Both outcomes work against the goal of improving request quality.

   Consider making this optional (required: false) and relying on the description text to guide contributors, or rephrase the label so that almost any well-described feature request naturally satisfies it:

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: .github/ISSUE_TEMPLATE/feature-request.yml
   Line: 213-215
   
   Comment:
   **`required: true` may block legitimate feature requests**
   
   Marking "This is a design proposal, not a 'please build this' request" as `required: true` means GitHub's form will hard-block submission unless the contributor checks this box. A user who simply wants to describe a desired capability — without thinking of themselves as writing a design proposal — will either abandon the form or check the box without meaning it. Both outcomes work against the goal of improving request quality.
   
   Consider making this optional (`required: false`) and relying on the description text to guide contributors, or rephrase the label so that almost any well-described feature request naturally satisfies it:
   
   
   
   How can I resolve this? If you propose a fix, please make it concise.

   _{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

2. .github/PULL_REQUEST_TEMPLATE.md, line 233-235 (link)

   Testing checklist missing "or: N/A" annotation

   The create-pr SKILL.md example renders the unit-tests line as - [x] Unit tests added/updated (or: N/A — no testable logic), and its Section Guidelines explicitly say "Mark N/A items explicitly rather than leaving them unchecked without explanation." The actual PR template doesn't surface this guidance, so authors who don't read the skill won't know what to write for documentation-only PRs.

   Adding the hint directly keeps the two artefacts consistent:

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: .github/PULL_REQUEST_TEMPLATE.md
   Line: 233-235
   
   Comment:
   **Testing checklist missing "or: N/A" annotation**
   
   The `create-pr` SKILL.md example renders the unit-tests line as `- [x] Unit tests added/updated (or: N/A — no testable logic)`, and its Section Guidelines explicitly say "Mark N/A items explicitly rather than leaving them unchecked without explanation." The actual PR template doesn't surface this guidance, so authors who don't read the skill won't know what to write for documentation-only PRs.
   
   Adding the hint directly keeps the two artefacts consistent:
   
   
   
   How can I resolve this? If you propose a fix, please make it concise.

Prompt To Fix All With AI

This is a comment left during a code review.
Path: .github/ISSUE_TEMPLATE/feature-request.yml
Line: 213-215

Comment:
**`required: true` may block legitimate feature requests**

Marking "This is a design proposal, not a 'please build this' request" as `required: true` means GitHub's form will hard-block submission unless the contributor checks this box. A user who simply wants to describe a desired capability — without thinking of themselves as writing a design proposal — will either abandon the form or check the box without meaning it. Both outcomes work against the goal of improving request quality.

Consider making this optional (`required: false`) and relying on the description text to guide contributors, or rephrase the label so that almost any well-described feature request naturally satisfies it:

```suggestion
        - label: I've described the problem this would solve, not just the solution I want
          required: true
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: .github/PULL_REQUEST_TEMPLATE.md
Line: 233-235

Comment:
**Testing checklist missing "or: N/A" annotation**

The `create-pr` SKILL.md example renders the unit-tests line as `- [x] Unit tests added/updated (or: N/A — no testable logic)`, and its Section Guidelines explicitly say "Mark N/A items explicitly rather than leaving them unchecked without explanation." The actual PR template doesn't surface this guidance, so authors who don't read the skill won't know what to write for documentation-only PRs.

Adding the hint directly keeps the two artefacts consistent:

```suggestion
- [ ] `make test` passes
- [ ] Unit tests added/updated (or: N/A — no testable logic)
- [ ] E2E tests added/updated (if applicable)
```

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "Merge branch 'main' into nmulepati/docs/..." | Re-trigger Greptile}