docs: restructure agent and contributor documentation (plan 427, PR 1)

[nabinchha]

📋 Summary

Restructure DataDesigner's documentation to clearly separate concerns: a concise architectural guide for agents (AGENTS.md), a comprehensive code style reference (STYLEGUIDE.md), a contributor-focused development guide (DEVELOPMENT.md), and an updated contribution guide (CONTRIBUTING.md). This is PR 1 of the agent-assisted development plan (plan #427), covering Phases 0–2.

🔄 Changes

✨ Added

• STYLEGUIDE.md — New comprehensive code style guide extracted from the old AGENTS.md, expanded with:
  • Google-style docstring conventions (Args:, Returns:, Raises:, Attributes:)
  • Pydantic model and dataclass guidance (when to use each, ConfigBase patterns, validator naming)
  • Error handling patterns (raise ... from exc, boundary wrapping, canonical error types)
  • f-string preference, nested function avoidance, and other style rules
• DEVELOPMENT.md — New development guide extracted from the old AGENTS.md and CONTRIBUTING.md, including:
  • Per-package test targets (make test-config, make test-engine, make test-interface)
  • E2E/tutorial/recipe test commands with API key setup note
  • Flat test function preference (no class-based suites)
  • Notebook regeneration commands (make convert-execute-notebooks, make generate-colab-notebooks)
  • Import performance CI threshold documentation (3-second average)
• .agents/README.md — Documents the .agents/ directory structure, symlink compatibility, and development-vs-usage scope
• architecture/ — 10 stub architecture documents (overview.md, config.md, engine.md, models.md, mcp.md, dataset-builders.md, sampling.md, cli.md, agent-introspection.md, plugins.md) ready for Phase 3 content

🔧 Changed

• AGENTS.md — Rewritten from ~626 lines to ~56 lines as a focused architectural guide: identity, layering, core concepts, design principles, structural invariants, and development pointers
• CONTRIBUTING.md — Overhauled to focus on agent-assisted contribution workflow, referencing the new doc structure
• README.md — Added brief mention of agent-assisted development
• .agents/skills/review-code/SKILL.md — Updated to reference the new three-file doc structure (AGENTS.md, STYLEGUIDE.md, DEVELOPMENT.md)
• plans/427/agent-first-development-plan.md — Updated delivery strategy to combine Phases 0–2 into PR 1

🗑️ Removed

• .claude/skills/new-sdg/ — Obsolete prototyping skill, superseded by skills/data-designer/

🏗️ Restructured

• .claude/skills/ and .claude/agents/ — Canonical files moved to .agents/skills/ and .agents/agents/; .claude/ directories replaced with symlinks for backward compatibility

🔍 Attention Areas

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

• AGENTS.md — This is the primary file agents read on every interaction. Verify the layering description, dependency direction, and structural invariants are accurate.
• .claude/agents and .claude/skills — These are now symlinks to .agents/. Verify they resolve correctly in your local checkout.
• STYLEGUIDE.md — New sections on docstrings, Pydantic/dataclass conventions, and error handling should be validated against current codebase patterns.

---

🤖 Generated with AI

PR-1 for #427

[greptile-apps]

Greptile Summary

This PR restructures DataDesigner's documentation into four focused files — a slim architectural guide (AGENTS.md, ~56 lines), a comprehensive style reference (STYLEGUIDE.md), a contributor development guide (DEVELOPMENT.md), and an overhauled contribution guide (CONTRIBUTING.md) — as part of the agent-assisted development plan (plan #427, Phases 0–2). Agent infrastructure is consolidated under .agents/ with .claude/ replaced by symlinks for backward compatibility.

Key changes:

• AGENTS.md reduced from ~626 lines to ~56 lines; content redistributed to STYLEGUIDE.md and DEVELOPMENT.md so agents load a focused architectural brief on every interaction
• STYLEGUIDE.md is new and adds Google-style docstring conventions, Pydantic/dataclass guidance, error handling patterns, and nested-function avoidance rules not present in the old AGENTS.md
• DEVELOPMENT.md documents per-package test targets (make test-config/engine/interface), E2E/notebook targets, the 3-second CI import threshold, and notebook regeneration commands — all of which are confirmed present in the Makefile
• All two issues flagged in prior review rounds (SIM enforcement wording, copyright year discrepancy) are confirmed resolved in commit eb5315b
• Ten architecture/ stubs are added with consistent structure, clearly marked for Phase 3 population
• .claude/agents and .claude/skills converted to symlinks (git mode 120000) pointing to ../.agents/agents and ../.agents/skills respectively — symlink targets are correct

Confidence Score: 5/5

• Safe to merge — documentation-only restructuring with no code changes, all Makefile targets verified, previous review concerns resolved.
• All referenced make targets (test-config, test-engine, test-interface, test-e2e, convert-execute-notebooks, generate-colab-notebooks, perf-import) are confirmed present in the existing Makefile. Prior review findings (SIM enforcement wording, copyright year mismatch) are confirmed fixed in eb5315b. PEP 420 reference for implicit namespace packages is accurate. Cross-references between AGENTS.md, STYLEGUIDE.md, DEVELOPMENT.md, and CONTRIBUTING.md are consistent. Symlink targets are correctly relative. No code changes — risk is documentation-only.
• No files require special attention. Reviewers may want to manually verify .claude/agents and .claude/skills symlinks resolve correctly in a local checkout (as called out in the PR description).

Important Files Changed

Filename	Overview
AGENTS.md	Refactored from ~626 lines to ~56 lines — now a focused architectural guide covering layering, core concepts, design principles, structural invariants, and pointers to STYLEGUIDE.md / DEVELOPMENT.md. PEP 420 namespace package reference is accurate.
STYLEGUIDE.md	New comprehensive style reference extracted and expanded from old AGENTS.md. Adds Google-style docstring conventions, Pydantic/dataclass guidance, error handling patterns, and nested-function avoidance. SIM enforcement wording correctly softened to "not yet enforced by CI" (per prior review fix in eb5315b).
DEVELOPMENT.md	New development guide with local setup, workflow, and testing documentation. All referenced Makefile targets (test-config, test-engine, test-interface, test-e2e, convert-execute-notebooks, generate-colab-notebooks, perf-import) confirmed present in the Makefile. CI threshold (3-second average, 1 cold + 4 warm import cycles) is well documented.
CONTRIBUTING.md	Overhauled to focus on agent-assisted contribution workflow. Previous copyright year inconsistency (2025 vs 2026) was resolved in eb5315b. Traditional bug report / feature request templates are removed, but this appears intentional per the agent-first plan — Phase 3 will add GitHub issue templates.
.agents/skills/review-code/SKILL.md	Updated to reference the new three-file doc structure (AGENTS.md, STYLEGUIDE.md, DEVELOPMENT.md) in the "Load Project Guidelines" step, replacing the monolithic AGENTS.md-only reference.
.claude/agents	Now a symlink (mode 120000) pointing to ../.agents/agents. Old directory contents moved to .agents/agents/ first. Symlink target path is correct relative to .claude/.
.claude/skills	Now a symlink (mode 120000) pointing to ../.agents/skills. Previous new-sdg skill removed (superseded by skills/data-designer/). Symlink target path is correct relative to .claude/.
plans/427/agent-first-development-plan.md	Delivery strategy updated to combine Phases 0–2 into PR 1. New execution order table is well-structured with authoring sequence notes. Architecture stubs scope clarified (content to be populated in PR 2).

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    subgraph Agent["Agent Entry Points"]
        A1[".claude/agents (symlink)"]
        A2[".claude/skills (symlink)"]
    end

    subgraph Canonical[".agents/ (Canonical Source)"]
        B1[".agents/agents/"]
        B2[".agents/skills/"]
    end

    subgraph DocFiles["Root Documentation Files"]
        D1["AGENTS.md\n(~56 lines: arch + invariants)"]
        D2["STYLEGUIDE.md\n(style, types, imports, patterns)"]
        D3["DEVELOPMENT.md\n(setup, testing, workflow)"]
        D4["CONTRIBUTING.md\n(agent-assisted contribution workflow)"]
    end

    subgraph Arch["architecture/ (10 stubs)"]
        E1["overview.md"]
        E2["config.md / engine.md / models.md"]
        E3["cli.md / mcp.md / plugins.md / ..."]
    end

    A1 -->|symlink| B1
    A2 -->|symlink| B2
    B2 --> |review-code SKILL.md loads| D1
    B2 --> |review-code SKILL.md loads| D2
    B2 --> |review-code SKILL.md loads| D3
    D1 --> |"links to"| D2
    D1 --> |"links to"| D3
    D1 --> |"links to"| Arch
    D4 --> |"references"| D1
    D4 --> |"references"| D2
    D4 --> |"references"| D3

Loading

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

[nabinchha]

All findings addressed in eb5315b:

• STYLEGUIDE.md naming example — replaced pd.DataFrame return type with list[dict[str, str]] to avoid contradicting the lazy-import guidance in the same file.
• DEVELOPMENT.md upstream sync — added git remote add upstream instruction for fork-based contributors and changed fetch/merge to use upstream instead of origin.
• STYLEGUIDE.md SIM claim — softened to `SIM` rules; not yet enforced by CI but code should comply.
• CONTRIBUTING.md copyright year — updated from 2025 to 2026 to match STYLEGUIDE.md.