docs: agent-assisted development plan for DataDesigner

[nabinchha]

Summary

Adds a comprehensive development plan for introducing agent-assisted workflows into DataDesigner, inspired by NVIDIA/OpenShell. The plan covers infrastructure consolidation, documentation restructuring, and GitHub machinery updates across four phases.

Related Issue

Closes #427

Changes

• New plans/427/agent-first-development-plan.md with:
  • Problem statement: DataDesigner has meaningful agent infrastructure (7 skills, introspection CLI) but top-level docs don't surface it
  • Phase 1: Consolidate agent assets into .agents/ as a tool-agnostic canonical path, with symlinks for .claude/ and .codex/ compatibility
  • Phase 2: Restructure documentation — split AGENTS.md into focused files (STYLEGUIDE.md, DEVELOPMENT.md), update README.md and CONTRIBUTING.md to advertise agent workflows, create architecture/ skeleton
  • Phase 3: GitHub machinery — update issue templates with agent investigation fields, add PR template, update CODEOWNERS, create label taxonomy
  • Phase 4: Future work (new skills, sub-agent personas, triage automation) — flagged as requiring separate planning
  • Delivery strategy: Incremental PRs per phase, with Phase 4 requiring its own planning pass before implementation

[greptile-apps]

Greptile Summary

This PR adds plans/427/agent-first-development-plan.md, a structured four-phase roadmap for making DataDesigner's existing agent infrastructure (7 skills, sub-agent personas, introspection CLI) more visible and consistently organised. The plan covers consolidating skills into a tool-agnostic .agents/ directory, splitting the monolithic AGENTS.md into focused documents (STYLEGUIDE.md, DEVELOPMENT.md), overhauling CONTRIBUTING.md to reflect agent-assisted workflows, and adding GitHub machinery (PR/issue templates, label taxonomy). Phase 4 future work is explicitly deferred to a separate planning pass.

Key observations:

• The plan is well-structured, with a clear execution-order table, explicit dependency tracking, and a delivery strategy that favours incremental PRs over a big-bang rollout.
• The two-surface distinction (development tooling vs. usage tooling) is a useful framing but is not fully carried through: Phase 1b instructs labelling every skill as a development skill, which would incorrectly classify the new-sdg skill (a usage skill) and undermine the very separation the plan promotes.
• The architecture/ skeleton in Phase 2e is scoped conservatively (stubs only), which is appropriate for a planning document.
• Phase 4 items are correctly flagged as requiring their own planning pass before implementation.

Confidence Score: 4/5

• Documentation-only change; safe to merge with one targeted fix to the Phase 1b skill-labelling instruction.
• The plan is thorough, internally consistent, and well-sequenced. The one concrete issue — Phase 1b directing all skills to be labelled as development skills without carving out new-sdg (a usage skill) — should be addressed before implementation begins, but it does not affect anything in the repository today. All previous review concerns have been noted; this is a docs-only PR.
• plans/427/agent-first-development-plan.md — Phase 1b skill classification instruction needs a carve-out for new-sdg.

Important Files Changed

Filename	Overview
plans/427/agent-first-development-plan.md	Comprehensive agent-first development plan covering four phases (infrastructure consolidation, doc restructuring, GitHub machinery, future skills). Well-structured and internally consistent except for an unresolved classification of the new-sdg usage skill in the Phase 1b "label all skills as development" instruction.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    P0["Phase 0\nAGENTS.md restructure\n(~50 lines)"]
    P1["Phase 1\nSkill & Agent Infrastructure\n(.agents/ consolidation,\n.claude/ symlinks, .codex/ symlinks)"]
    P2A["Phase 2A\nSTYLEGUIDE.md +\nDEVELOPMENT.md\n(extracted from AGENTS.md)"]
    P2B["Phase 2B\nCONTRIBUTING.md overhaul"]
    P2C["Phase 2C\nREADME.md updates"]
    P3["Phase 3 (parallelisable)\nIssue templates\nPR template\nCODEOWNERS\nLabels\narchitecture/ skeleton\nSkill template conformance"]
    P4["Phase 4 (separate plan required)\nNew skills\nSub-agent personas\nIssue triage workflow"]

    P0 --> P1
    P0 --> P2A
    P2A --> P2B
    P2B --> P2C
    P2C --> P3
    P3 -.->|requires own planning pass| P4

Loading

Prompt To Fix All With AI

This is a comment left during a code review.
Path: plans/427/agent-first-development-plan.md
Line: 139-145

Comment:
**`new-sdg` classified incorrectly in Phase 1b**

Phase 1b directs that *every* skill file should have its description or frontmatter updated to identify it as a **development** skill. However, `new-sdg` is a usage skill — its own frontmatter reads `"Implement a new synthetic data generator using NeMo Data Designer by defining its configuration and executing a preview job."` and it is the exact kind of end-user usage tooling the plan distinguishes from development tooling (lines 13-18).

Labelling `new-sdg` as a development skill would contradict the plan's own stated goal of keeping the two surfaces clearly separate so agents don't confuse contributor work with dataset-building workflows.

The plan also does not say where `new-sdg` should live after the Phase 1 consolidation. If `.agents/skills/` is meant to be a **development-only** canonical path (which the framing strongly implies), then `new-sdg` either needs its own designated location or the plan needs an explicit note carving it out from the "label all skills as development" instruction and specifying its destination.

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

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

[johnnygreco]

Thanks @nabinchha!! Can't for this to land 🚀