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 populates all 10 architecture/ stubs from PR 1 with accurate, source-verified content, adds GitHub issue/PR templates with agent-assisted workflow fields, and aligns the create-pr skill with the new PR template structure. The documentation-only changes carry no risk; all key technical claims were verified against the actual source code (_MCP_IO_SERVICE singleton, atexit registration, AsyncTaskScheduler/RowGroupBufferManager class names, strip_rate_limit_codes async/sync split in http_model_client.py).

The one minor omission worth noting: .agents/skills/review-code/SKILL.md is in the file diff but is not described in the PR's Changes section — it appears to have been updated to reference the newly populated architecture/*.md files as documentation sources for code review. Worth a quick mention so future readers understand why it changed.

Confidence Score: 5/5

Documentation and template changes only; no testable logic, no code paths modified.

All architecture docs were verified against source code — class names, singleton patterns, sync/async client behavior. Issue templates use correct required/optional designations. The only finding is a P2 omission in the PR description (review-code/SKILL.md not mentioned in Changes), which does not affect correctness or safety.

No files require special attention; review-code/SKILL.md change is undocumented in the PR description but harmless.

Important Files Changed

Filename	Overview
architecture/overview.md	Accurately describes three-package layout, PEP 420 namespace packages, data flow, and dual execution engines; cross-references verified
architecture/config.md	Accurately covers builder API, discriminated unions, model configs, and lazy imports; consistent with source structure
architecture/engine.md	Correctly documents compilation pipeline, registry system, column generator hierarchy, and ResourceProvider
architecture/models.md	AIMD throttling, strip_rate_limit_codes sync/async behavior, and facade pattern verified against source; accurate
architecture/mcp.md	_MCP_IO_SERVICE singleton, atexit registration, session pooling, and tool coalescing verified against io.py; accurate
architecture/dataset-builders.md	AsyncTaskScheduler and RowGroupBufferManager class names verified; sequential and async execution paths accurately described
architecture/sampling.md	Accurately describes DatasetGenerator, constraint system, PeopleGen/PeopleGenFaker hierarchy, and managed datasets
architecture/cli.md	Correctly documents lazy command loading, controller/service/repo pattern, and generation command delegation
architecture/agent-introspection.md	FamilySpec, type discovery, state commands, and AGENT_COMMANDS single-source registration accurately documented
architecture/plugins.md	Entry-point discovery, PluginRegistry singleton, union injection, and custom column comparison table accurately described
.github/PULL_REQUEST_TEMPLATE.md	New PR template with Summary, Related Issue, Changes, Testing, and Checklist sections; well-structured
.github/ISSUE_TEMPLATE/bug-report.yml	Adds optional Agent Diagnostic field and investigation checklist; required/optional designations are appropriate
.github/ISSUE_TEMPLATE/feature-request.yml	Adds optional Agent Investigation field; existing required fields preserved correctly
.github/ISSUE_TEMPLATE/development-task.yml	Adds Investigation/Context and Agent Plan optional fields; consistent with other template additions
.github/ISSUE_TEMPLATE/config.yml	Updates Discussions link copy to mention agent-assisted workflow
.agents/skills/create-pr/SKILL.md	Updated to produce PR descriptions matching new template structure; steps consistent with PULL_REQUEST_TEMPLATE.md
.agents/skills/review-code/SKILL.md	Updated documentation sources to reference newly populated architecture/*.md files; change not described in PR Changes section

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[PR 1: Architecture stubs created] --> B[PR 2: This PR]
    B --> C[Architecture docs populated ×10]
    B --> D[GitHub Templates updated]
    B --> E[create-pr SKILL updated]
    B --> F[review-code SKILL updated]
    C --> C1[overview.md]
    C --> C2[config.md]
    C --> C3[engine.md]
    C --> C4[models.md]
    C --> C5[mcp.md]
    C --> C6[dataset-builders.md]
    C --> C7[sampling.md]
    C --> C8[cli.md]
    C --> C9[agent-introspection.md]
    C --> C10[plugins.md]
    D --> D1[PULL_REQUEST_TEMPLATE.md]
    D --> D2[bug-report.yml]
    D --> D3[feature-request.yml]
    D --> D4[development-task.yml]
    D --> D5[config.yml]

Loading

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

[andreatgretel]

good candidate for the Monday docs-and-references suite from #472 - symbol-level checks would catch this kind of drift automatically going forward.