Orqestria Download
← Back to Recruitment · project planning pack

Skill · Version 1.0.0

Integration adoption planning

Turns a technical recommendation into a concrete integration plan with local touchpoints, lifecycle boundaries and visible uncertainty.

integration-architecture-adoption-plan

Agents using this skill

See how it helps

When is it useful?

Use it after narrowing library or service candidates and before committing implementation effort.

What does it help you do?

  • Ranks alternatives by fit, licensing, footprint and maintenance.
  • Names host modules, data contracts and error translation boundaries.
  • Plans initialization, cancellation, cleanup and uncertain effort ranges.

Try asking this

Plan adoption of a search library with exact adapter boundaries and exit costs. Implement a minimal search adapter for one real query. Demonstrate error translation and cancellation, then describe how stored data can leave the library later.

Detailed documentation

Read the skill’s original instructions, examples and checks in their authored language.

Details…Show less

Integration Architecture & Adoption Plan

Research must culminate in an actionable architecture decision and a concrete integration blueprint tailored to the host codebase.

The Five Canonical Adoption Modes

Evaluate finalists and recommend one explicit path:

  1. Use As-Is (Direct Dependency): The library is small, well-maintained, license-compatible, and fits our runtime and types cleanly.
  2. Integrate Behind an Adapter / Seam (Feathers & Hohpe): The library solves a complex core problem (e.g., parser, protocol engine, layout solver), but we wrap it behind a narrow domain interface so its types, errors, and upgrade churn never leak across our codebase.
  3. Vendor / Adapt a Permitted Subset: We only need 100 lines of a 20,000-line permissive (MIT/Apache-2.0/BSD) package; copy or adapt the minimal module with full license/copyright attribution and unit tests.
  4. Build a Scoped In-House Solution: External candidates are over-engineered, poorly maintained, or mismatched; implement a focused internal module informed by the best patterns observed during research.
  5. Reject / Defer: The capability is unnecessary or unviable right now.

Workflow

  1. Lead with the ranked recommendation:
    • State the recommended option first, followed by a structured comparison matrix of finalists across consistent criteria (fit, mechanism, footprint, license, maintenance, integration effort, key risks).
  2. Map exact host-codebase touchpoints:
    • Name the exact files, modules, schemas, and configuration surfaces in our project where the integration will live:
      • Boundary & data flow: Input/output types, serialization boundaries, and error translation into domain errors.
      • Lifecycle & resource control: Initialization, timeouts, cancellation (AbortSignal), memory cleanup, and concurrency limits.
      • Rollback & replaceability: How the integration can be feature-flagged, tested in isolation, or swapped out later.
  3. Provide uncertainty-aware effort estimates and next steps:
    • Break the adoption plan into concrete, ordered implementation tasks.
    • Express effort estimates as ranges with explicit uncertainty drivers (e.g., "0.5–1 day for core adapter; +0.5 day if custom streaming backpressure is needed").

Anti-Patterns to Avoid

  • Recommending a full framework migration for a minor feature: Never propose replacing the host project's core framework just to adopt a convenience library.
  • Leaking third-party types into every domain model: Always define a clean boundary seam at the integration edge.

Included files 1

  • SKILL.md