docs: rewrite AGENTS.md as a concise agent operating guide

[johnnygreco]

📋 Summary

Rewrites AGENTS.md from a verbose ~574-line reference document into a concise ~230-line operating guide, optimized for agent consumption with clear priorities, actionable checklists, and a visual architecture diagram.

🔄 Changes

🔧 Changed

• AGENTS.md: Complete rewrite with the following structural improvements:
  • Added a Mission section with explicit optimization priorities (correctness → fast iteration → API stability)
  • Added a First 5 Minutes Checklist for quick agent onboarding
  • Replaced prose architecture description with a mermaid flowchart showing the full execution path
  • Condensed file map to only high-value entry points
  • Consolidated coding rules into a single Non-Negotiable Coding Rules section
  • Streamlined development workflow into a Testing and Validation Workflow section with preferred make targets
  • Added a Change Strategy section with a 5-step implementation approach
  • Added a Common Pitfalls section targeting known pain points (circular imports, registry state leakage, type hint drift)
  • Added a Quality Gate Before Hand-Off checklist

🗑️ Removed

• Verbose code style examples (PEP 8 naming, common pitfalls with code samples, active linter rules listing)
• Detailed testing patterns section with example test structure
• Registry system detailed listing
• Pre-commit hooks documentation
• Redundant import convention examples that duplicated ruff enforcement

---

🤖 Generated with AI

Made with Cursor

[greptile-apps]

Greptile Overview

Greptile Summary

Complete rewrite of AGENTS.md from a verbose 574-line reference document into a focused 254-line operating guide optimized for AI agent consumption. The restructured document prioritizes actionable information with:

• Clear mission statement with explicit optimization priorities (correctness → fast iteration → API stability)
• First 5 Minutes Checklist for rapid agent onboarding
• Visual mermaid flowchart replacing prose architecture descriptions, showing the full execution path from config builder through generation pipeline
• Condensed file map focusing on high-value entry points only
• Consolidated Non-Negotiable Coding Rules section combining previously scattered guidelines
• Streamlined Testing and Validation Workflow with preferred make targets and clear command hierarchy
• New Change Strategy section with 5-step implementation approach
• New Common Pitfalls section addressing known pain points (circular imports, registry state leakage, type hint drift)
• New Quality Gate Before Hand-Off checklist

The rewrite removes verbose examples and detailed listings (PEP 8 naming examples, testing patterns with code samples, pre-commit hooks documentation, active linter rules listing) in favor of concise, actionable guidance. All technical references to file paths, make commands, and core patterns are accurate and verified against the codebase.

Confidence Score: 4/5

• This documentation change is safe to merge with minimal risk
• Score reflects that this is a documentation-only change that successfully condenses verbose reference material into a concise agent operating guide. The restructuring improves usability with visual diagrams, checklists, and actionable workflows. One minor issue found: two column config types (EmbeddingColumnConfig and CustomColumnConfig) are missing from the quick reference list but are exported in the public API. All file paths, make commands, and ModelConfig fields are technically accurate.
• AGENTS.md needs two column config types added to the list (lines 206-214)

Important Files Changed

Filename	Overview
AGENTS.md	rewrites documentation as concise agent guide with architecture diagram, checklists, and streamlined workflow - missing two column config types from list

Sequence Diagram

sequenceDiagram
    participant User as User/App Code
    participant Builder as DataDesignerConfigBuilder
    participant Interface as DataDesigner Interface
    participant ResourceProvider as ResourceProvider
    participant Compiler as compile_data_designer_config
    participant ColumnBuilder as ColumnWiseDatasetBuilder
    participant DAG as DAG Sorter
    participant Registry as DataDesignerRegistry
    participant Generators as Column Generators
    participant BatchManager as DatasetBatchManager
    participant Processors as Processors
    participant Storage as ArtifactStorage
    participant Profiler as DatasetProfiler

    User->>Builder: create config (add_column calls)
    Builder->>Builder: build() → DataDesignerConfig
    User->>Interface: generate() or validate()
    Interface->>ResourceProvider: create_resource_provider()
    ResourceProvider->>ResourceProvider: initialize ModelRegistry, MCPRegistry, SeedReaderRegistry, ArtifactStorage
    Interface->>Compiler: compile_data_designer_config()
    Compiler->>ColumnBuilder: create ColumnWiseDatasetBuilder
    ColumnBuilder->>DAG: sort columns by dependencies
    DAG->>Registry: resolve generators/validators from config
    Registry->>Generators: instantiate column generators
    loop For each batch
        Generators->>BatchManager: generate column data
        BatchManager->>Processors: apply processors
        Processors->>Storage: store artifacts
    end
    Storage->>Profiler: profile dataset
    Profiler->>Interface: return results
    Interface->>User: return DataDesignerResult

Loading

[greptile-apps]

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[nabinchha]

Suggested change

	- Add type annotations to all functions/methods/class attributes (including tests).
	- Design code with KISS, DRY, YAGNI, and SOLID software engineering principles.
	- Add type annotations to all functions/methods/class attributes (including tests).

[nabinchha]

Suggested change

	- Prefer `make` targets over raw tool commands when a matching `Makefile` target exists.
	- Write function based unit tests without complicated mocking and fixtures. Only test via public api never accessing private properties or methods of classes/modules being tested.
	- Prefer `make` targets over raw tool commands when a matching `Makefile` target exists.

[nabinchha]

Should we add something about make coverage and that coverage >= 90%?

[nabinchha]

does this mean we need to keep this up to date?