--- name: ai-sdlc-shared-runtime description: Portable AI SDLC shared-helper runtime. Use when an AI assistant installs, verifies, diagnoses, or repairs project-scoped AI SDLC skills whose deterministic scripts depend on shared state, artifact, context, path, TOON, migration, or index modules. This is an installation dependency, not a lifecycle entry point. --- # 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 Keep installed AI SDLC capabilities executable without assuming that the user cloned the harness source repository. Skills CLI discovers folders containing `SKILL.md`; this package deliberately makes the formerly source-only shared runtime part of that discovered installation set. ## 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 A passing verification reports: ```text runtime: present downstream helper: executable consumer root: preserved mutation: none, or disposable fixture only next: owning lifecycle skill ``` Quality gate: - 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 Valid diagnosis: ```text The SDD helper cannot import ai_sdlc_artifact_helper because the shared runtime package is absent. Reinstall the complete pinned package, then rerun --help. ``` Invalid diagnosis: ```text Copy one module from an arbitrary checkout into the installed package and keep working. ``` Reject the invalid path because it bypasses package provenance and can mix incompatible runtime bytes. ## 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 This skill verifies the portable runtime dependency. It does not select product work, approve network access, change policy, implement features, repair Git, publish releases, or mutate authoritative lifecycle evidence.