diff --git a/migration-examples/.ai/parser/AGENT.md b/.agents/skills/write-parser/SKILL.md similarity index 68% rename from migration-examples/.ai/parser/AGENT.md rename to .agents/skills/write-parser/SKILL.md index 043cac83..31bc876c 100644 --- a/migration-examples/.ai/parser/AGENT.md +++ b/.agents/skills/write-parser/SKILL.md @@ -1,21 +1,19 @@ -# Role Definition +--- +name: write-parser +description: > + Write Groovy parsers and import scripts that map source data formats + (XML, JSON, CSV, etc.) into the Quadient Inspire Migration Model. + Use this skill when asked to create, generate, update, or fix a parser, + importer, field mapping, or source-to-model transformation for migration-examples. +compatibility: Requires Quadient Inspire Designer or Interactive for deployment of parsed output +--- -You are a supportive AI assistant for **migration-stack**, a tool to help with migrations from various CCM (Customer -Communications Management) software to Quadient Inspire. +# Parser Development -## Required Context +You help with migrations from various CCM (Customer Communications Management) software to Quadient Inspire by creating +parsing scripts that transform source data into the Migration Model. -**Before starting any parser work, read all files in this folder:** - -- `AGENT.md` (this file) - Your role, responsibilities, and workflow -- `API-REFERENCE.md` - Complete Migration Library API documentation -- `EXAMPLES.md` (when available) - Sample parsers, common patterns, and troubleshooting tips - -These files work together to provide complete context for parser development. - -## Your Responsibilities - -You help with: +## Responsibilities - **Input format analysis** - Analyze source format structure and map it to the Migration Model - **Parsing script creation** - Generate Groovy scripts that transform source data into the Migration Model @@ -35,8 +33,6 @@ You help with: ## Workflow -### Iterative Development Process - Follow this process for every parsing script: 1. **Analyze** - Understand the source format structure and data @@ -46,11 +42,13 @@ Follow this process for every parsing script: 5. **Fix** - Resolve any runtime errors iteratively 6. **Validate** - Verify output structure matches expected Migration Model -**⚠️ Critical:** Always run generated scripts and fix runtime errors before considering the task complete. Do not stop at script generation—test execution is mandatory. +**⚠️ Critical:** Always run generated scripts and fix runtime errors before considering the task complete. Do not stop at +script generation—test execution is mandatory. ### Common Runtime Issues Watch out for these recurring problems: + - Null pointer exceptions when accessing optional elements - Type mismatches (String vs Integer, etc.) - Missing or incorrect API method calls @@ -75,4 +73,9 @@ model, which consists of: - **Text/Paragraph Styles** - Formatting definitions - **Document Objects** - Templates, Pages, Blocks, Sections - **Display Rules** - Conditional logic -- **Images** - Visual resources \ No newline at end of file +- **Images** - Visual resources + +## References + +- [Migration Library API](references/MIGRATION-API.md) - Complete API documentation for builders, repositories, and model objects +- If present, consult [Examples & Patterns](references/EXAMPLES.md) for proven parsing patterns and troubleshooting tips diff --git a/migration-examples/.ai/parser/API-REFERENCE.md b/.agents/skills/write-parser/references/MIGRATION-API.md similarity index 98% rename from migration-examples/.ai/parser/API-REFERENCE.md rename to .agents/skills/write-parser/references/MIGRATION-API.md index 2c5f1536..36b4ae62 100644 --- a/migration-examples/.ai/parser/API-REFERENCE.md +++ b/.agents/skills/write-parser/references/MIGRATION-API.md @@ -1,4 +1,4 @@ -# API Reference +# Migration Library API Reference ## Overview @@ -7,8 +7,6 @@ XML, JSON, CSV, etc.) into the **Migration Model** - a common intermediate repre All objects are created using **Builder classes** with a fluent API and stored in repositories. -**Related:** See `AGENT.md` for your role and workflow guidance. - ## Getting Started Every parser script starts with: @@ -90,7 +88,7 @@ have `customFields`, `originLocations`, or `name` properties. - **Organize with Target Folders** - Use logical folder structure: `.targetFolder("blocks/invoices/headers")` - **Use Skip for Non-Migratable Content** - Mark complex/unsupported content: `.skip("manual-name", "reason...")` - **Check for Null** - Verify data exists before calling builder methods that expect non-null values -- **Test Iteratively** - Run your script frequently to catch errors early (see AGENT.md workflow) +- **Test Iteratively** - Run your script frequently to catch errors early ## Repository API @@ -624,7 +622,7 @@ def inputPath = migration.projectConfig.inputDataPath.toString() Objects support metadata for source system tracking, organized in named groups: ```groovy -. metadata("DocumentInfo") { mb -> +.metadata("DocumentInfo") { mb -> mb.string("Document type: Technical Example") mb.integer(42L) mb.dateTime(Instant.parse("2024-01-15T10:30:00Z")) @@ -638,7 +636,7 @@ Objects support metadata for source system tracking, organized in named groups: Mark objects that cannot be automatically migrated: ```groovy -. skip("placeholder-name", "reason for skipping") +.skip("placeholder-name", "reason for skipping") ``` --- @@ -652,5 +650,5 @@ values, and existence of referenced objects. Validation errors will fail at runt ## Working Example -See `migration-examples/src/main/groovy/com/quadient/migration/example/example/Import.groovy` for a complete example -demonstrating all major object types, conditional logic, language-specific content, tables, and document assembly. \ No newline at end of file +See `src/main/groovy/com/quadient/migration/example/example/Import.groovy` for a complete example +demonstrating all major object types, conditional logic, language-specific content, tables, and document assembly. diff --git a/CHANGELOG.md b/CHANGELOG.md index 9c17aa55..ed5d3a62 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) - Fallback placeholder text for unmapped repeated content and row to be distinguishable from one another - Minimal supported Designer version is now 17.0.674.0 +- Restructure the AI parser instructions as skill, based on the https://agentskills.io/specification ### Fixed