ai-sdlc-shared-runtime: Portable Helper Dependency

Internal AI SDLC dependency, not a client-facing lifecycle skill. Do not select it instead of the navigator or an owning workflow. Every installed capability that imports shared helpers must resolve this sibling package before it executes.

0. Skill Card

• Skill name:

  ai-sdlc-shared-runtime

• Primary audience: agent runners, platform engineers, harness maintainers
• Supporting audience: AI assistants and repository owners diagnosing install failures
• Audience tags: Platform, Maintainer, Dev
• SDLC stage: Installation and cross-lifecycle runtime support
• Purpose: Make the deterministic shared Python runtime portable when Skills CLI installs individual skill directories without the source-only

  skills/_shared/

  directory.
• Output: Read-only runtime verification or an explicit installation blocker

0.1 Required Inputs

• The installed skills root, normally

  .agents/skills/

  for a project-scoped universal installation.
• The consumer repository root.
• The downstream skill script that failed or must be verified.
• The installed package revision or trusted source identity when known.

0.2 Clarification Rules

• Ask only when the installed skills root or failing downstream script cannot be located safely.
• Distinguish a missing runtime package from a corrupt runtime copy, missing Python, an unsupported package revision, and an application-level failure.
• Never infer that an import failure is permission to download or execute an unreviewed replacement.

0.2.1 Flow Mode Flags

• This package has no independent quick/full lifecycle flow.
• Preserve

  --quick-flow

  and

  --full-flow

  flags for the downstream owning skill; this runtime must not reinterpret them.
• Verification is read-only. Reinstallation or repair requires the same human authority and trusted source used for installation.

0.3 Output Rules

• Report the installed skills root, runtime path, checked downstream script, exact command, exit status, and any missing module.
• Return progress, blockers, and recommendations directly in the Codex response.
• Before the final response, emit the

  ai-sdlc-handoff/v1

  contract with

  result

  ,

  blockers

  ,

  next_required

  , and

  next_optional

  ; every action includes

  reason

  ,

  command

  , and

  expected_artifact

  .
• Do not create

  summary.txt

  ,

  *-summary.txt

  , or a runtime status artifact.
• Do not claim an installation is healthy from inventory alone; execute a representative downstream helper.

0.4 Artifact Routing

• This skill creates no refinement or implementation artifact.
• Read installed files from the agent-owned skills root and consumer evidence from the current repository.
• Do not write

  specs-refiniment/

  ,

  specs/

  ,

  _ai_sdlc/state.toon

  , or an

  _ai_sdlc/specs-index.toon

  during runtime verification.
• Route repair to the canonical install/update workflow and lifecycle work to the owning skill.

0.5 Feature State Machine

• This runtime is a utility and never begins or completes a feature stage.
• It may load

  ai_sdlc_state_machine

  for another skill, but it must not mutate lifecycle state on its own.
• Use

  state.toon

  only through the downstream owning workflow.

0.6 Artifact Metadata And Metatags

• Runtime verification is ephemeral and carries no

  artifact_metadata

  or

  metatags

  .
• The packaged helpers preserve the downstream skill's existing metadata and authority contracts; they do not create a second source of truth.

0.7 Specs Index

• The runtime exposes index helpers but does not rebuild

  specs-index.md

  or a machine index by itself.
• Index reads and writes remain owned by the selected lifecycle workflow.

References

• scripts/

  is a deterministic mirror of non-test Python helpers from

  skills/_shared/

  .
• The source mirror is maintained by

  python3 skills/_shared/sync_installed_runtime.py

  .
• Downstream scripts first use source

  skills/_shared/

  when present and then fall back to this installed sibling package.

Script Usage

• Verify the generated mirror in a harness source checkout:
  bash

  python3 skills/_shared/sync_installed_runtime.py --check

• Verify an installed downstream helper from a consumer repository:
  bash

  python3 .agents/skills/ai-sdlc-sdd/scripts/sdd_artifact_scaffold.py --help

• A missing

  ai-sdlc-shared-runtime/scripts/

  directory, stale mirror, import traceback, or non-zero helper smoke result is a blocker.

Purpose

SKILL.md

Inputs

• Resolve the current skill file and its sibling skills root.
• Locate

  ai-sdlc-shared-runtime/scripts/

  under that root.
• Select the smallest downstream helper that exercises the reported dependency.
• Preserve the consumer repository as the helper's working directory.

Steps

1. Confirm the runtime package and the requested downstream skill share one installed skills root.
2. Run the downstream helper with

   --help

   before any mutating action.
3. For SDD installation verification, write and finalize only a disposable fixture specification in a temporary consumer repository.
4. Classify failures as missing package, stale mirror, Python incompatibility, invalid consumer root, or downstream contract failure.
5. Reinstall from the reviewed pinned source when package bytes are missing or stale; do not patch installed generated files ad hoc.
6. Rerun the exact helper smoke command and return the owning workflow handoff.

Output Spec

runtime: present
downstream helper: executable
consumer root: preserved
mutation: none, or disposable fixture only
next: owning lifecycle skill

• Pass when the generated runtime mirror matches its canonical source and an installed downstream helper imports and executes successfully.
• Fail when inventory exists but imports fail, the runtime is installed under a different root, generated bytes drift, or verification mutates real delivery artifacts.

Examples

The SDD helper cannot import ai_sdlc_artifact_helper because the shared runtime
package is absent. Reinstall the complete pinned package, then rerun --help.

Copy one module from an arbitrary checkout into the installed package and keep
working.

Edge Cases

• A source checkout legitimately uses

  skills/_shared/

  ; this is not drift.
• A project may expose host-specific symlinks, but all selected skill folders and the runtime must resolve to compatible bytes.
• Installing only one downstream skill without this dependency is incomplete.

• --help

  proves importability, not correctness of a consumer feature; run the downstream workflow's own validation for that claim.

Scope Boundary