Spec: Scaffold, Managed Skill, and Operator Follow-ups

Context

Recent consumer reports exposed four released scaffold/skill defects and one operator UX defect. Scoped prompt specifications make agents repeat installed skill semantics and generic evidence prose. Delivery can route an unretained local spec into a backlog gate that requires a stable blob URL. An unescaped pipe corrupts the Effect recovery strategy table during formatting. The docs-onboarding skill names an unsupported command in released projections. Recognized Codex hosts can still be asked for a raw Skills CLI agent key because Harness detects fewer safe host markers than the adapter it invokes.

The fixes must originate in each owning source, preserve immutable stack lineage, and update managed projections only through supported synchronization and scaffold paths.

Non-Goals

• Remove exact agent targeting from Skills CLI list, install, update, or remove operations.
• Let one operator command mutate every detected or registered agent binding.
• Redesign root or shared agent guidance outside the scoped prompt continuation.
• Patch .devpunks/pre-existing-skills or another consumer snapshot as authority.
• Publish npm solely for packaged-skill byte changes.
• Activate dormant Production release authority or bypass its approval gates.

User Stories

US-001: Author concise scoped prompts

As a repository maintainer, I want generated scoped prompt specs to require only repository-specific invariants and terse skill invocation pointers so that final AGENTS.md files stay compact without losing selected skills or validation seams.

US-002: Route incomplete spec retention correctly

As a delivery operator, I want a local agent-ready spec without verified remote retention and a stable blob URL to return to spec repair so that backlog routing does not dead-end.

US-003: Preserve the Effect recovery table

As an Effect skill reader, I want the complete Effect.all mode expression and its notes to remain in a valid three-column table after formatting and baseline installation.

US-004: Receive supported onboarding guidance

As a new Harness operator, I want docs onboarding to direct me to hi init so that the documented command exists.

US-005: Avoid meaningless agent prompts on recognized hosts

As an operator running Harness from Codex, I want operator subcommands to detect the active Skills CLI target without asking me for an internal adapter name.

Acceptance Criteria

• AC-001: Generated docs/workspace prompt specs require repository-specific structural invariants, placement/dependency rules, local conventions, terse explicit-invocation skill pointers, Source Guide links, mirrors, and validation seams without requiring restatement of complete skill semantics, model-discovery triggers, or generic evidence prose.
  • Covers: US-001
• AC-002: A representative 15-scope scaffold continuation preserves every selected skill ID, Source Guide link, CLAUDE mirror, and validation seam while avoiding the reported 1,718-line obligation shape.
  • Covers: US-001
• AC-003: Delivery routes an otherwise agent-ready SPEC.md with missing or unverified remote retention/blob URL through spec repair before backlog.
  • Covers: US-002
• AC-004: The canonical Effect strategy row contains an escaped literal pipe, remains exactly three columns after the pinned formatter, and renders the full mode expression and Notes cell after baseline extraction and an isolated managed-consumer update using the candidate baseline.
  • Covers: US-003
• AC-005: Canonical shared source, Harness packaged source, and an isolated managed-consumer docs-onboarding projection from the candidate baseline contain hi init and exclude hi scaffold init.
  • Covers: US-004
• AC-006: CODEX_CI and CODEX_SANDBOX resolve the Codex operator target without prompting, while explicit HI_OPERATOR_AGENT retains highest precedence.
  • Covers: US-005
• AC-007: Operator integration still passes exactly one resolved --agent to Skills CLI inspection, installation, update, migration removal, and guarded retries.
  • Covers: US-005
• AC-008: Interactive unknown hosts may request a target and noninteractive unknown hosts fail closed without guessing.
  • Covers: US-005

Constraints

• Shared skills are edited first in wearedevpunks-skills, pushed to an immutable ref, then synchronized into Harness from that exact ref.
• Skill edits use writing-for-agents; behavior-changing CLI edits use test-first public-interface coverage.
• The parent PR remains first. This child stays based on team/stefan/cache-release-diff-classification-requirements until PR #123 merges.
• The unavailable control-plane baseline authority is a release-proof blocker, not scaffold drift evidence.
• Operator workflow and AI scaffold behavior changes update CLI docs and runbooks.

Dependency Readiness

Ready.

• Parent PR #123 live head fb8c216f61a4f5e8c27f9d00784056e3541f6a29 is the verified base of this child branch. The user-supplied 435af1ec was its pre-rebase equivalent and is not an ancestor of the live head.
• Research is retained at origin/research/issue-125-operator-followups, immutable commit 82c8cfe2e4c960b6acd04131c13dfd43de711805.
• Shared-skill source origin/main is available for a dedicated source-first child branch; no unlanded source branch is required as an implementation base.

Branch/Base Intent

• Harness parent/base: team/stefan/cache-release-diff-classification-requirements at live PR #123 head fb8c216f61a4f5e8c27f9d00784056e3541f6a29.
• Harness child: team/stefan/scaffold-skill-operator-followups.
• Child PR base remains the parent branch until #123 merges, then the child is rebased onto main and the PR retargeted to main.
• Shared skills use a dedicated team/stefan/* branch from current shared origin/main; Harness sync pins an immutable tag created at its pushed head.

Accepted Technical Decisions

• Supersede the verbose parts of the implemented scoped-guidance contract with compact repository-invariant and invocation-pointer requirements.
• Treat remote spec retention and stable blob URL verification as part of delivery's complete spec state.
• Escape the Effect union pipe in canonical Markdown before formatting.
• Treat pre-existing-skill snapshots as evidence only.
• Align Harness host detection and safe marker forwarding with supported Codex markers while retaining one explicit Skills CLI target throughout lifecycle state.

Accepted Testing Decisions

• Capture RED public-contract assertions before changing each behavior.
• Parse or render the Effect table semantically after formatting; formatter idempotence alone is insufficient.
• Cover scoped prompt compactness with semantic invariants and a representative multi-scope size regression, not only a hard global line limit.
• Cover operator marker detection, safe environment forwarding, packaged PTY non-prompt behavior, unknown-host behavior, and exact child argv.
• Validate canonical shared sources before exact-ref synchronization, then verify source/package/projection parity and baseline archive readback.

Verification Seams

• Scoped prompt seam: rendered docs/workspace prompt specifications and a representative scaffold continuation.
• Delivery seam: router contract for a local agent-ready but unretained spec.
• Markdown seam: parsed/rendered three-column table after formatter and archive extraction.
• Onboarding seam: canonical and installed docs-onboarding bytes plus CLI catalog truth.
• Operator seam: packaged hi operator PTY output and Skills CLI runtime argv trace.

Parked Decisions

• Production release authority activation. Owner: Stefan. Resume trigger: explicit approval after environment/OIDC and credential gates are ready.
• Broader multi-agent operator lifecycle. Owner: Harness maintainers. Resume trigger: a separate requirement to manage more than the active host binding.

Decision Log