Maintain Integration

maintain-integration

When to use vs create-integration

Use this skill when the package already exists:

• reviewing quality, ECS compliance, or correctness of an existing package
• fixing specific issues: pipeline errors, field mappings, ECS categorization, CEL programs, manifests
• running a full quality improvement pass (review → fix → re-validate loop)
• making minor adjustments to existing data streams

Use create-integration instead when:

• creating a new integration package from scratch
• adding a new data stream to an existing package (create-integration → references/add-datastream-workflow.md)

Modes

Review only (read-only, no edits)

→ Read `references/review-workflow.md` fully before starting.

Run automated validation, delegate inspection to a subagent (see Dispatch convention in references/review-workflow.md) pointing it at review-integration/references/reviewer-subagent-guidance.md as its operating manual, present findings with no file changes.

Full improvement pass (analyze → fix → re-validate)

→ Read `references/improve-workflow.md` fully before starting.

Analyze issues (from prior review or fresh reviewer run), prioritize by severity, fix directly or delegate to subagents, re-validate, and report.

Minor direct fix (no subagents needed)

For small targeted changes you can handle inline without loading a full workflow:

• manifest field corrections (title, description, format_version, conditions, owner)
• changelog entries and version bumps — see package-spec skill
• documentation placeholder text in _dev/build/docs/README.md
• _dev/build/build.yml creation or ECS reference bump
• simple field file fixes (typos, missing entry, duplicate removal)
• CEL formatting only — run celfmt -s -agent -i cel.yml.hbs -o cel.yml.hbs in the stream's agent/stream/ directory

Run elastic-package lint and elastic-package check after any direct edits to confirm no regressions.

Skills to load for direct work

• elastic-package-cli — validation and test commands
• package-spec — manifest rules, version bumps, and changelog schema

Do not load domain-specific skills (pipelines, CEL, ECS, field mappings) into your own context. Delegate to subagents that already have that knowledge.

Subagents

All specialised work is delegated to the platform's generic / general-purpose subagent (Cursor: generalPurpose Task agent; Claude Code: general-purpose Task agent; or the equivalent on other platforms). Each task prompt must *point the subagent at the relevant `-subagent-guidance.md file by path** and instruct it to read that file (plus the skill SKILL.md it lists in "First steps") end-to-end before doing any other work. **Do NOT read the guidance file yourself or paste its contents into the task prompt** — that doubles its context cost. Pass only the path plus the task-specific context. The subagent will load the manual itself in its own fresh context. Full dispatch rules and per-workflow detail live in references/review-workflow.md and references/improve-workflow.md`.

When delegating, provide the subagent with: package path, data stream path, specific issues to fix (paste findings), sample data if relevant, and any constraints.

Data anonymization

All data committed must be fully anonymized — no real IPs, hostnames, emails, tokens, or org identifiers in any committed file. When fixing or adding test fixtures, mock responses, sample events, or documentation examples, verify all values are synthetic. Anonymize any real data found as part of the improvement pass.

References

• references/review-workflow.md — read-only review workflow (phases 1–4, mandatory checklists, output format)
• references/improve-workflow.md — full improvement workflow (analyze → prioritize → fix → re-validate → report)

Improve Workflow

Full improvement pass for an existing Elastic integration package: analyze issues, prioritize by severity, fix directly or delegate to subagents, re-validate, and report.

What to provide

Default: quality-first — analyze all aspects and fix highest-impact issues.

Dispatch convention (read once, applies to every subagent step below)

All specialised work in this workflow is delegated to the platform's generic / general-purpose subagent (Cursor: generalPurpose Task agent; Claude Code: general-purpose Task agent; or the equivalent on other platforms). Do not invoke a named specialised subagent.

Every subagent task prompt must:

1. Begin with an instruction to read the subagent's operating manual. Point the subagent at the relevant *-subagent-guidance.md file by path and tell it to read that file (plus the skill SKILL.md it points at in its "First steps" section) end-to-end before doing any other work. Do NOT read the guidance file yourself or paste/embed its content into the task prompt — that doubles the context cost. The subagent must load the manual itself in its own fresh context. The guidance file contains the skill-load sequence, workflow, scope boundaries, and reporting contract. 2. Provide all context the subagent needs (it cannot see your conversation): package path, data stream path, specific issues to fix (paste findings), sample data if relevant, and any constraints.

Available manuals in this workflow (pass these by path, do not embed):

Phase 1: Analyze

If the user provided prior review findings, use those as the issue list. Read any @-mentioned files and fetch any documentation or API URLs provided inline.

If no prior review is available, run a quick pre-check yourself, then dispatch the reviewer:

cd packages/<package_name>

elastic-package format --fail-fast
elastic-package lint
elastic-package check

Then dispatch a subagent per the Dispatch convention above, instructing it to read review-integration/references/reviewer-subagent-guidance.md as its operating manual, to perform the review.

The task prompt must include (in addition to the read-the-manual directive):

1. Package path 2. Any user-provided requirements, research brief, or focus areas 3. Automated validation results from the pre-check above (so the subagent does not re-run them) 4. Any constraints

The reviewer returns a severity-ranked issue list with domain tags.

Phase 2: Prioritize

Categorize all issues by severity:

1. CRITICAL — broken functionality, build/lint failures, missing required files 2. HIGH — quality standard violations (missing error handling, wrong ECS values, no test coverage) 3. MEDIUM — suboptimal patterns, missing edge case coverage, documentation gaps 4. LOW — style issues, minor improvements

Default strategy: address all issues in priority order — CRITICAL → HIGH → MEDIUM → LOW. Every finding must result in either a fix or an explicit decision not to fix (with a stated reason). If the user specified a focus area, prioritize that regardless of severity ranking.

Phase 3: Route and fix

Route each issue to the appropriate handler based on the domain tag from the review:

Fix directly (no subagent needed)

CEL formatting you can fix directly (not logic errors):

cd packages/<package_name>/data_stream/<stream>/agent/stream
celfmt -s -agent -i cel.yml.hbs -ocel.yml.hbs

If celfmt reports syntax errors, fix the source before re-running. Do not proceed until celfmt exits cleanly (no stdout output).

Dispatch the pipeline builder

Per the Dispatch convention above, point the subagent at ingest-pipelines/references/builder-subagent-guidance.md as its operating manual.

Use for:

• pipeline — JSE00001 compliance, on_failure handlers, processor tags, date parsing, type conversions, grok patterns, ECS categorization, processor ordering
• fields (complex) — field type mismatches or new ECS fields intertwined with pipeline changes
• tests (pipeline) — missing pipeline test fixtures, broken expected output

Dispatch the CEL program builder

Per the Dispatch convention above, point the subagent at cel-programs/references/builder-subagent-guidance.md as its operating manual.

Use for:

• cel — error handling, cursor management, want_more logic, state.with() structure, redact.fields, auth scope, template configuration, system test mock API

If the user provided API credentials, pass them to the subagent so it can re-validate the fix with mito against the real API in addition to the mock.

When delegating, batch all related issues for the same data stream into a single subagent launch.

Phase 4: Re-validate

After all fixes (direct and subagent) are applied:

elastic-package format
elastic-package lint
elastic-package check

If pipeline test fixtures exist:

elastic-package test pipeline

If the pipeline changed and expected output needs regeneration:

elastic-package test pipeline --generate

Review the generated *-expected.json to confirm correctness, then re-run elastic-package test pipeline.

Phase 5: Final review and fix loop

Dispatch a subagent per the Dispatch convention above, instructing it to read review-integration/references/reviewer-subagent-guidance.md as its operating manual, for a final verification pass.

The task prompt must include (in addition to the read-the-manual directive):

1. Package path 2. Summary of what was fixed 3. Automated validation results from Phase 4 (so the subagent does not re-run them) 4. Original requirements (if available)

If the reviewer returns remaining issues, do not attempt to fix them all yourself. Re-delegate (per the Dispatch convention):

• Pipeline/field/test issues: point the subagent at ingest-pipelines/references/builder-subagent-guidance.md with the specific issues to fix
• CEL issues: point the subagent at cel-programs/references/builder-subagent-guidance.md with the specific issues to fix
• Only fix minor issues (manifest, changelog, docs, simple field typos) yourself

After subagent fixes complete, re-run elastic-package check and re-launch the reviewer the same way. Repeat until the reviewer returns APPROVED or only APPROVED_WITH_SUGGESTIONS (LOW/MEDIUM) findings remain.

Phase 6: Report

# Improvement Report: <Package Name>

## Issues Found
(total count by severity: X CRITICAL, Y HIGH, Z MEDIUM, W LOW)

## Fixes Applied
1. [CRITICAL] <description> — <file(s) changed> — fixed by: self/pipeline-builder/cel-builder
2. [HIGH] <description> — <file(s) changed> — fixed by: ...
...

## Validation After Fixes
- format: PASS/FAIL
- lint: PASS/FAIL
- check: PASS/FAIL
- test pipeline: PASS/FAIL/SKIPPED

## Final Review
- Verdict: APPROVED / NEEDS CHANGES
- Remaining issues (if any)

## Remaining Issues (not fixed)
1. [MEDIUM] <description> — <suggested fix>
2. [LOW] <description> — <suggested fix>
...

## Files Changed
- <path> (created/modified/deleted)
...

## Next Steps
- Items requiring user input
- Tests that need stack availability
- Suggested follow-up improvements

Guardrails

• Always analyze before fixing. Never apply fixes without understanding the full issue landscape.
• Fix the minimal set of changes needed. Do not refactor working code that has no quality issue.
• Re-validate after every batch of fixes. Do not accumulate many changes without checking.
• Never hand-write sample_event.json or *-expected.json. Always generate with --generate.
• Never remove or weaken existing test coverage.
• When fixing pipelines, preserve existing processor logic that works correctly.
• When adding field mappings, follow the ECS mapping strategy already in use by the package.
• Update changelog.yml when the changes are user-visible (follow package-spec skill).
• If a fix requires decisions the user hasn't made (auth method, field naming, categorization), mark it as a TODO rather than guessing.
• Do not load domain-specific skills (CEL, pipelines, ECS, field mappings) into your own context. Delegate to subagents.

Review Workflow

Read-only quality review of an existing Elastic integration package. No file edits. Use this when the goal is feedback and findings only; for actually fixing the issues, use improve-workflow.md.

What to provide

Default scope: full review when no restriction is given.

Phase 1: Parse scope and context

1. Identify the package directory and read its root manifest.yml. 2. Read any @-mentioned files; fetch any documentation URLs provided. 3. List all data streams and their input types. 4. Determine review scope: full package, specific streams, or specific aspects.

Phase 2: Automated validation

Run validation and capture all output. This is fast and requires no domain context.

cd packages/<package_name>

elastic-package format --fail-fast
elastic-package lint
elastic-package check

If an Elasticsearch stack is available, run pipeline tests:

elastic-package test pipeline

If a full stack is available and system tests exist:

elastic-package test system

Record every failure with its full error message.

Phase 3: Dispatch the integration reviewer

Delegate to the platform's generic / general-purpose subagent (Cursor: generalPurpose Task agent; Claude Code: general-purpose Task agent; or the equivalent on other platforms). Do not invoke a named specialised subagent.

The task prompt must include:

1. An instruction to read `review-integration/references/reviewer-subagent-guidance.md` as the subagent's operating manual before doing any other work — that file contains its scope, skill-load sequence (load review-integration skill and the domain skills/checklists it routes to), read-only operating rules, per-issue format checklist, verdict rules, and reporting contract. Pass only the path; do NOT read the file yourself or paste/embed its contents into the task prompt — the subagent will load it in its own fresh context. 2. Package path — absolute path to the package directory. 3. Review scope — full review or focused areas/streams. 4. Requirements / brief — paste key content or reference the file (the subagent cannot see your conversation). 5. Specific concerns — any areas the user highlighted. 6. Automated validation results — paste Phase 2 output so the reviewer does not re-run commands unnecessarily. 7. Data stream list — names and input types for each stream.

The subagent will: read changelog.yml to determine new-vs-existing severity calibration, classify every in-scope file by domain (using the review-integration skill's classification table), load the relevant domain skills and review checklists, run its full manual inspection, and produce findings in the format defined by review-integration/references/review-output-template.md.

The subagent already knows from the guidance file it reads to: avoid re-running validation the orchestrator already reported, read every in-scope file end to end (not just diffs), apply first-version leniency from conflict-resolutions.md, calibrate severity per severity-rubric.md's new-vs-existing tables, consolidate duplicate findings, omit empty domains, include exactly one domain tag and a code-block recommendation on every finding, and never edit any files.

Phase 4: Present results

The subagent returns its findings already formatted per review-integration/references/review-output-template.md and also writes the same content to tmp/integration-review.md. Present the reviewer's output in full — do not truncate, summarise, or re-format.

The template defines: per-domain sections (package root manifest/changelog/build, per-data-stream manifest/input/pipeline/field-mapping/tests, dashboards, transforms, documentation, anonymization, cross-domain consistency), per-issue format (title, severity, location, problem, recommendation with code block, domain tag), a summary count table, and the verdict line.

For severity definitions and the new-vs-existing calibration table, see review-integration/references/severity-rubric.md and review-integration/SKILL.md → "Reviewing new vs existing integrations". The reviewer subagent applies these automatically based on its reading of changelog.yml.

Guardrails

• Do not edit any files. This workflow is read-only.
• Do not skip or summarize the reviewer's findings. Present them in full.
• When automated validation commands fail, include the full error output in the report.
• Do not load domain-specific skills yourself. The reviewer subagent loads everything it needs via the review-integration skill referenced from its guidance file.