ai-sdlc-host-adapter: Portable Host Negotiation

Internal AI SDLC skill, not client-facing by default. Negotiation describes host behavior; it never invokes the host.

0. Skill Card

• Skill name:

  ai-sdlc-host-adapter

• Primary audience: Dev, Delivery, Architecture
• Supporting audience: Security, QA
• Audience tags: Dev, Delivery, Architecture, Security
• SDLC stage: Portable execution handoff
• Purpose: Preserve workflow semantics across hosts with explicit mappings and safe fallbacks.
• Output:

  _ai_sdlc/adapters/<adapter-id>/negotiation.{toon,json,md}

0.1 Required Inputs

• Versioned adapter manifest and capability request.
• Exact portable operations, required capabilities, isolation need, and desired concurrency.

0.2 Clarification Rules

• Ask when required semantics or host operation identity is ambiguous.
• Reject unknown fields, duplicate operations, invalid API ranges, undeclared capabilities, or non-equivalent native mappings.
• Never infer shell, filesystem, network, isolation, concurrency, or approval support.

0.2.1 Flow Mode Flags

• Support

  --quick-flow

  and

  --full-flow

  ; full flow takes precedence.
• Both modes use identical compatibility and fallback rules.
• Full flow reviews every mapping, limit, fallback, and unsupported requirement.

0.3 Output Rules

• Default to complete TOON with mappings, missing requirements, fallbacks, effective limits, compatibility, source fingerprint, and result fingerprint.
• Return summaries directly in the Codex response.
• Emit

  ai-sdlc-handoff/v1

  with

  result

  ,

  blockers

  ,

  next_required

  , and

  next_optional

  ; actions include

  reason

  ,

  command

  , and

  expected_artifact

  .
• Do not create

  summary.txt

  ,

  *-summary.txt

  , or another standalone summary file.

0.4 Artifact Routing

• Write negotiations only below

  _ai_sdlc/adapters/<adapter-id>/

  .
• Keep manifests in repository-owned visible paths or skill conformance fixtures.
• Never mutate a manifest during negotiation.

0.5 Feature State Machine

• Read owning feature

  _ai_sdlc/state.toon

  before execution handoff.
• Negotiation does not advance feature or runtime state.

0.6 Artifact Metadata And Metatags

• Related Markdown uses canonical

  artifact_metadata

  and

  metatags

  .
• Machine records use versioned adapter, request, and negotiation schemas.

0.7 Specs Index

• Read

  _ai_sdlc/specs-index.toon

  first and use

  specs-index.md

  for human review.
• Negotiation does not refresh either index.

References

• Read

  references/adapter-contract.md

  before adding a mapping or fallback.
• Validate manifests and requests with the JSON schemas in

  references/

  .
• Use

  scripts/adapter.py

  for validation and negotiation.
• Use

  references/fixtures/

  only as contract conformance hosts, not claims about products.

Script Usage

python3 skills/ai-sdlc-host-adapter/scripts/adapter.py . --adapter adapter.json --validate
python3 skills/ai-sdlc-host-adapter/scripts/adapter.py . --adapter adapter.json --negotiate --request request.json --write

Purpose

Steps

1. Validate manifest identity, API range, unique capabilities, mappings, and limits.
2. Validate the exact capability request.
3. Prefer equivalent native mappings.
4. Use only registered deterministic fallbacks whose prerequisites are supported.
5. Reduce concurrency or isolation to sequential execution with exact reasons.
6. Fail incompatible when a required operation or capability has no safe mapping.
7. Emit a complete TOON-first negotiation without invoking host operations.

Output Spec

• Pass only when every required operation and capability has an equivalent mapping or registered semantic-preserving fallback.
• Fail closed when host behavior would change workflow semantics.

Scope Boundary

• Do not execute host operations, commands, hooks, or approvals.
• Do not claim capabilities not declared by the adapter.
• Do not silently drop workflow steps or required gates.