Integrate Graty

Documentation Structure

The Graty repository contains comprehensive documentation:

Getting Started:

• docs/USER_GUIDE.md - Complete usage guide (installation, configuration, testing)
• docs/EXAMPLES_DESCRIPTION.md - Quick start with examples

Reference:

• docs/API_REFERENCE.md - Python API documentation (Graty class, methods)
• docs/CLI_REFERENCE.md - CLI commands (graty init, graty run)
• docs/GRATY_EXAMPLES.md - Code examples and patterns
• docs/cleanup_strategies.md - Detailed cleanup strategy guide

Technical:

• docs/TECHNICAL_REFERENCE.md - Architecture and design details
• docs/PROJECT_SUMMARY.md - Current status and limitations

See references/documentation-index.md for complete documentation links and lookup strategies.

How to Access Documentation

When you need specific information:

1. Identify the relevant document from the index in references/documentation-index.md
2. Fetch it using GitHub MCP tool:

   mcp__github__get_file_contents(
       owner="haronka1999",
       repo="graty",
       path="docs/USER_GUIDE.md",
       branch="master"
   )
   

3. Or use WebFetch for raw content:

   WebFetch(
       url="https://raw.githubusercontent.com/haronka1999/graty/master/docs/USER_GUIDE.md",
       prompt="Extract configuration options and validation rules"
   )
   

When to Fetch Documentation

Always fetch documentation when:

• User asks about specific configuration options
• You need to explain cleanup strategies in detail
• You need API method signatures or parameters
• You're unsure about best practices or recommendations
• User encounters an error or issue
• You need code examples for migration patterns

Quick lookups:

• Configuration questions → USER_GUIDE.md (Configuration section)
• API usage questions → API_REFERENCE.md
• Cleanup strategy questions → cleanup_strategies.md
• CLI commands → CLI_REFERENCE.md
• Code examples → GRATY_EXAMPLES.md
• Troubleshooting → USER_GUIDE.md (Troubleshooting section)

Integration Process

Follow these steps in order. Do not skip steps or make assumptions - always confirm with the user when required.

Step 0: Fetch Core Documentation (IMPORTANT)

Before starting the integration, fetch the essential documentation:

1. Fetch USER_GUIDE.md to understand current best practices:

   mcp__github__get_file_contents(
       owner="haronka1999",
       repo="graty",
       path="docs/USER_GUIDE.md",
       branch="master"
   )
   

2. Fetch cleanup_strategies.md for cleanup strategy details:

   mcp__github__get_file_contents(
       owner="haronka1999",
       repo="graty",
       path="docs/cleanup_strategies.md",
       branch="master"
   )
   

3. Fetch API_REFERENCE.md for API details:

   mcp__github__get_file_contents(
       owner="haronka1999",
       repo="graty",
       path="docs/API_REFERENCE.md",
       branch="master"
   )
   

This ensures you have the latest, accurate information for guiding the integration.

Step 1: Discover Repository Context

Explore the repository to understand the project structure:

1. Search for SQL schema files using Glob tool:

   • Look for **/*.sql files
   • Check common locations: schema/, db/, migrations/, sql/
   • Note all schema files found

2. Search for test directories using Glob tool:

   • Look for test directories: tests/, test/, spec/
   • Look for test files: **/test_*.py, **/*_test.py, **/test*.py
   • Identify the test framework (pytest or unittest)

3. Search for database configuration using Grep tool:

   • Look for docker-compose.yml or docker-compose.yaml
   • Look for .env files or configuration files
   • Search for PostgreSQL connection strings
   • Search for database setup scripts

Present your findings to the user in a clear, organized format showing:

• Schema files found (with paths)
• Test directories/files found (with paths)
• Current database setup (if any)

Step 2: Gather Required Information

Now ask the user for the information needed to create graty.yaml. Use the AskUserQuestion tool to gather this information.

2.1 Database Type and Version

Ask the user about their database:

• Database type (currently only PostgreSQL is supported)
• PostgreSQL version (supported: 9-16, recommended: 15)

If they don't know, suggest: PostgreSQL 15 (default)

Reference: Check USER_GUIDE.md for current version support if needed.

2.2 SQL Schema Path

Based on what you found in Step 1:

If you found SQL schema files:

• Present the found schema files to the user
• Ask which schema file they want to use
• Confirm the path is correct

If you did NOT find SQL schema files:

• Ask the user to provide the path to their SQL schema file
• Inform them they can create one if they don't have it yet
• Suggest they might want to dump their existing database schema

Validation:

• The schema file path should be relative to the project root for portability
• Example: schema.sql, db/schema.sql, migrations/schema.sql

Reference: See USER_GUIDE.md for schema configuration details.

2.3 Test Location

Based on what you found in Step 1:

If you found test directories:

• Present the found test directories
• Ask which directory contains (or will contain) their integration tests
• Confirm they want to use this location

If you did NOT find test directories:

• Suggest creating tests/integration/ (Graty convention)
• Ask if they want a different location
• Confirm the directory path

Validation:

• The path should be relative to project root
• Example: tests/integration/, tests/, test/integration/

2.4 Cleanup Strategy

IMPORTANT: Fetch cleanup_strategies.md if you haven't already to get accurate, detailed information.

Explain the cleanup strategies based on official documentation and ask the user to choose. Use AskUserQuestion with these options:

truncate (Recommended for most cases):

• Fast performance (10-100x faster than recreate)
• Clears all table data between tests
• Preserves schema structure
• Resets sequences/auto-increment
• Best for: Most integration test suites

recreate (Thorough but slower):

• Drops and recreates the entire database between tests
• Guarantees completely fresh state
• Slower performance
• Best for: Tests that modify schema or require absolute isolation

none (Manual control):

• No automatic cleanup
• User manages cleanup manually in tests
• Maximum control and flexibility
• Best for: Advanced use cases with custom cleanup logic

Default recommendation: Start with truncate - it's fast and works for 90% of use cases.

Also ask about cleanup level:

• function (default): Cleanup after each test function
• class: Cleanup after each test class
• module: Cleanup after each test module
• session: Cleanup once after all tests

Reference: See cleanup_strategies.md for detailed comparison and performance benchmarks.

Step 3: Generate graty.yaml Configuration

Now that you have all the information, create the graty.yaml file in the project root.

IMPORTANT: If you're unsure about configuration format, fetch USER_GUIDE.md for the latest configuration schema.

Use the template from references/graty-template.yaml as a base, but verify against official docs.

Required sections:

# Graty Configuration
# Generated by integrate-graty skill
# Documentation: https://github.com/haronka1999/graty/blob/master/docs/USER_GUIDE.md