ivy-readme-key-features

name	ivy-readme-key-features
description	Generate key-features and setup fragments from one Axon Ivy Maven main module only.
argument-hint	<main-module-path>
user-invocable	true

Ivy README Key Features

Generate product description, key-feature bullets, demo intro, and complete setup/variables/openapi sections for Axon Ivy/Maven repositories.

Inputs

• mainModule (required): main module path
• Optional: language (default: en) - preferred language for CMS lookups and synthesized prose. When generating the source README.md, callers MUST set language: en so extracted prose is English. Use language: de only when producing README_DE.md during translation.

Behavior

0. Source priority (enhanced for marketing/UX):
   • Priority 1: module documentation sources (README/README_*.md in product or main module) for section structure, intro, images, external links, and long instructional blocks
   • Priority 2: configuration sources (config/variables.yaml, config/rest-clients.yaml, config/roles.xml)
   • Priority 3: process/cms hints (processes/*.p.json, cms files)
   • If intro block is missing, synthesize a marketing-friendly intro with product image and external links if available. - If an image is present in the intro block, include the image markdown in the productDescriptionSection.content and record a placement hint intro for the productImageSection (so assemblers embed the image inline into the intro).
   • Add fallback synthesis logic to ensure a default product description is always generated:
     • Use repository name and module name to create a generic description.
     • Example: "The [module name] connector integrates seamlessly with Microsoft 365 services, providing robust features for [key services]."
     • Include a placeholder image or link if none are found.
   • If key features are missing, synthesize user-centric, benefit-driven bullets grouped by service area (Mail, Calendar, Files, Teams, ToDo, etc.) with real-world examples.
   • Never fabricate setup steps that are not present in sources, but always synthesize intro/features if missing.

0.1 Anti-duplication source safety (mandatory):

• Never treat the current generation target file (targetReadme, typically <productModule>/README.md) as authoritative source input in the same generation run.
• On regeneration, if <productModule>/README.md already exists and appears to be assembler-generated (for example contains the canonical template headings like ## Demo, ## Setup, ## Components), do not ingest any section content from it.
• Do not scan <productModule>/README.md for compatibility in the default flow.
• If extraction detects nested top-level heading blocks (# ...) inside a fragment candidate, discard that candidate and continue with non-generated sources.

0.2 Hard enforcement gates (mandatory):

• Every extracted fragment MUST be checked before assembly. If any forbidden field, raw technical metadata, or section-specific disallowed token appears in a candidate fragment, discard that fragment and regenerate it from allowed sources only.
• The generated output is invalid unless all hard gates pass for every fragment.
• Key Features gate: reject any candidate that contains raw callable-sub identifiers, input parameter names/types, result types, config keys, visual.description, or process JSON field names. Key feature bullets must stay user-facing and benefit-driven.
• Product Description / Demo gate: reject any candidate that introduces build badges, workflow status, navigation-only CTA lines, self-referential README links, or section headings that belong to the generated target README.
• Setup gate: reject any candidate that inlines large raw YAML/JSON/XML payloads, repeats the exact @variables.yaml@ block outside variablesSection, or emits OpenAPI.Namespace, Url, Properties, or other client metadata as prose bullets.
• Roles gate: reject any candidate that exposes XML implementation details; only role names and their descriptions may appear.
• OpenAPI gate: reject any candidate that includes anything other than the OpenAPI.SpecUrl value rendered as a single link or bullet; never surface namespace, auth properties, or other rest-client fields here.
• Variables gate: the only valid content is the exact fenced placeholder block containing @variables.yaml@.
• If a fragment fails any hard gate, the run must regenerate that fragment until the forbidden token is removed.

1. Key Features (6 bullets, benefit-driven):

   • Format: Each bullet MUST start with user benefit, not technical implementation.
   • Source priority:
     1. Try: Extract from <mainModule>/README.md (existing Key Features section)
   2. Derive from connector processes: Extract CALLABLE_SUB process signatures from <mainModule>/processes/*.p.json
      • For each CallSubStart: extract name, input params, result type
      • Look for visual.description field to understand user capability
      • Map to service area (Mail, Calendar, Files, Teams, ToDo, etc.)
   3. Configuration hints: config/roles.xml and config/rest-clients.yaml
   • Synthesis rules (when no pre-written features found):
     • Use verb + object pattern: "Send emails", "Create calendar events", "Upload files"
     • Add outcome/benefit: "directly from your Axon Ivy processes"
     • Group by service: Mail, Calendar, Teams, Files, ToDo
     • Examples:
       • ❌ Wrong: "writeMail() callable sub sends messages"
       • ✅ Right: "Send emails and manage recipients directly from your processes"
   • Quality gate: If synthesized features are generic (e.g., "integrates X"), mark status=partial
   • Preserve sourced features exactly; never rewrite approved feature text.
   • Hard enforcement gate: if a candidate bullet contains a callable-sub name, parameter signature, type name, config path, process field name, or other implementation detail before the user benefit, discard it and regenerate the bullet from the service capability only.

   1.1 Product Description Section (mandatory, marketing style): - Extract the introductory product description block from module documentation sources. - If available, include product image and external links (e.g., Microsoft Graph overview, documentation, etc.). - Source priority with fallback: 1. Try: <mainModule>/README.md or <mainModule>/doc/README.md (first paragraph). Prefer the main module README as source of canonical intro text. 2. Fallback: Root repository README.md (extract first intro paragraph before any ### sections) 3. If no intro is found in docs, synthesize from repository evidence (config/*, process metadata, product.json). - If no intro is found, synthesize a marketing-friendly intro with product image and external links. - External image URLs found in source README files are valid and should be preserved (no forced local image copy required). - Exclude non-product intro noise from extracted intro blocks: - CI/CD badges, shields, workflow status images, and other badge-style images/links - self-referential documentation links that point to the generated target README or the current product module README - navigation-only CTA lines such as when they do not add product meaning - Preserve paragraph structure, image, and marketing-friendly wording.

2.1 Roles Section (NEW - extract from config/roles.xml):

• Scan <mainModule>/config/roles.xml for role definitions
• Extract role names and descriptions
• Format: **Roles:** [Role 1] (description), [Role 2] (description)
• If all roles granted: **Roles:** Everybody (configured in config/roles.xml)
• Return as rolesSection fragment
• If missing: set status: missing, content: "Roles configuration not documented"
• Hard enforcement gate: if the fragment contains config/roles.xml, raw XML tags, role IDs, or permission syntax instead of plain role names with descriptions, discard it and regenerate.

3. Variables Section:
   • Do not expand config/variables.yaml into the README.
   • variablesSection.content MUST be exactly the fenced block:

@variables.yaml@

• Never emit raw variable key/value YAML in variablesSection.
• If an extractor emits the token inline (@variables.yaml@), normalize it to the fenced block above.

3.1 OpenAPI Section: - Extract OpenAPI endpoint/spec details from config/rest-clients.yaml and related docs. - Present OpenAPI spec URL only from OpenAPI.SpecUrl. - Do not include namespace or any non-SpecUrl metadata. - Return as a dedicated openApiSection fragment for deterministic placement in assembly. - If no OpenAPI spec is found, set fragment status to missing and content to exactly: - No information was delivered for this section. - Hard enforcement gate: if the fragment contains Namespace, Url, Properties, Icon, Features, client IDs, or nested bullets under a client label, discard it and regenerate using only OpenAPI.SpecUrl.

4. Optional Authentication/Runtime Sections:

   • If optional authentication/runtime sections are documented (e.g., JWT, OAuth consent, service accounts), extract complete setup including:
     • Prerequisites context
     • All numbered steps with nested sub-steps
     • Image references ()
     • Final confirmation and service interactions
   • Keep explanation user-oriented: what to configure, why it matters, and what success looks like
   • Preserve nested lists and code blocks exactly when extracted from docs
   • If missing, synthesize a placeholder.
   • Hard enforcement gate: if the section leaks raw configuration dumps, implementation-only fields, or self-referential README headings, discard it and regenerate from the documented user-facing steps only.

5. Maven Artifacts: Extract artifact coordinates from product.json, then order the rendered list by the root pom.xml module sequence. Format as numbered list with XML dependency blocks and include only groupId, artifactId, and <type>; do NOT include a <version> element in the README (the build/pipeline should resolve versions). Use *(optional)* marker for optional artifacts and set status:missing if none found.

6. Return JSON fragments conforming to output-format.md

Language / CMS behavior

• When invoked with language=en, the skill MUST prefer English CMS files (cms_en.yaml) for string resolution and produce English prose for all synthesized sections. If English CMS is missing, fall back to repository defaults but favor English output.
• When invoked with language=de, the skill may prefer German CMS files (cms_de.yaml) and produce German prose for outputs intended for translation (for example when invoked by translate-readme).
• The central orchestration (generate-ivy-readme) must call extractors with language=en when building the source README.md and must call translate-readme to produce README_DE.md (which may use language=de internally).

Output Sections

• productDescriptionSection: Introductory description block with image and links
• keyFeatures: Feature bullets only (6 items, benefit-driven)
• demoIntroSection: Intro text + external links (from ## Demo section in source or market links)
• rolesSection: Roles configuration extracted from config/roles.xml
• openApiSection: OpenAPI resources/config details (Spec URL + Namespace) — goes INTO Setup section
• setupSection: All setup steps discovered from source docs/configuration (numbered steps, images preserved)
• variablesSection: Fixed literal fenced block containing @variables.yaml@
• mavenArtifactSection: Maven artifacts with numbered XML dependency blocks. Do not include a <version> element in the generated blocks; prefer leaving version resolution to the packaging/build pipeline.

Each section should include contract metadata when possible:

• preserveMode: verbatim for long instructional blocks, otherwise structured
• completeness: full|partial
• requiredSubsections: discovered subsection headings that must appear in final output

For setupSection, default to preserveMode: structured. Only use preserveMode: verbatim when no list normalization is required.

Quality criteria

• Scope limited to main module only
• Extract complete product intro + setup details, not simplified versions
• Setup prose is friendly and understandable for non-technical stakeholders while preserving exact technical values
• Preserve all inline comments and documentation
• Preserve image references exactly
• No demo/product scans in this step
• Must produce comprehensive output for Axon Ivy/Maven repositories