# HyperTwist Skillization And Command Surface Doctrine - 2026-05-21

## Purpose

This document defines how HyperTwist should turn retained repo value into:

- first-party commands
- first-party operator skills
- clean-room skill specifications
- placeholder skill families

It exists to prevent two failures:

1. donor command surfaces quietly becoming product truth
2. trying to make every retained feature into a skill

## Canonical rule

HyperTwist skills must sit on top of first-party command or service contracts.

They must not be the primary truth of a feature.

They must not be the only way to use a feature.

They must remain optional under the assistive-feature doctrine.

Governing companion authorities:

- `C:\HyperTwist\docs\ops\HYPERTWIST_OPTIONAL_ASSISTIVE_FEATURE_DEACTIVATION_AND_REMOVABILITY_DOCTRINE_2026-05-21.md`
- `C:\HyperTwist\docs\ops\HYPERTWIST_CROSS_LANE_AUTHORITY_HIERARCHY_AND_RECONCILIATION_2026-05-20.md`
- `C:\HyperTwist\docs\ops\HYPERTWIST_MEMORY_LANE_AUTHORITY_AND_PHASE_IMPLEMENTATION_DOCTRINE_2026-05-21.md`
- `C:\HyperTwist\docs\ops\HYPERTWIST_PROVIDER_NEUTRALITY_AND_BYOK_DOCTRINE_2026-05-21.md`
- `C:\HyperTwist\docs\ops\HYPERTWIST_IMPLEMENTATION_PHASE_1_KICKOFF.md`
- `C:\HyperTwist\docs\v6_5_deep_manual_pack\HyperTwist\FEATURE_REGISTRY.md`
- `C:\HyperTwist\docs\v6_5_deep_manual_pack\HyperTwist\SKILLS.md`
- `C:\HyperTwist\docs\ops\TOOL_ACCESS_AND_REFACTORING_LOG.md`

## Distinctions that must stay explicit

### 1. Product feature

A product feature is a durable capability of HyperTwist itself.

Examples:

- recognition and reconstruction
- replay and explanation
- training/coaching orchestration
- hyper puzzle catalog and topology runtime
- provider-neutral speech/vision sidecar contracts

### 2. First-party command surface

A command surface is the stable product-owned operational interface that
exposes a bounded capability.

Target-shape examples:

- `ht train ...`
- `ht recognition ...`
- `ht replay ...`
- `ht coach ...`
- `ht catalog ...`
- `ht provider ...`
- `ht memory ...`
- `ht review ...`

These are target-shape examples, not live implementation claims.

### 3. Skill

A skill is an optional assistance layer that helps the model or operator apply
bounded first-party capabilities correctly.

A skill may:

- choose the right command sequence
- assemble context
- produce a structured plan
- enforce a workflow checklist
- summarize bounded outputs

A skill must not replace the underlying command or service.

### 4. Donor command reference

This is upstream command behavior recorded for analysis or operator use in
external custody.

It is useful design input.

It is not the first-party HyperTwist contract.

### 5. Clean-room skill specification

This is a first-party specification of intended behavior derived from a
restrictive or boundary-sensitive source.

It may describe:

- workflow
- inputs/outputs
- safety rules
- expected first-party commands

It must not copy donor wording into the shippable product contract.

## Restrictive repo rule

For restrictive, mixed-custody, or no-grant repos, HyperTwist must define its
own commands.

That matters immediately for retained restrictive lanes such as:

- `onionhoney/roux-trainers`
- `cubing/alg.js`
- `cubing/twisty.js`
- `HactarCE/2x2x2x2-Scrambler`
- `kash/cubedesk`

Donor commands remain:

- research input
- comparison input
- clean-room planning input

They do not become the canonical HyperTwist command surface.

## Not every feature should become a skill

Create a skill when the capability is:

- user- or operator-invoked
- repetitive enough to deserve workflow packaging
- multi-step enough that sequencing matters
- bounded enough to expose clear inputs and outputs
- safe to disable without breaking product truth

Do not make a skill the primary surface for:

- low-level storage engines
- provider transport internals
- recognition transport internals
- passive overlays that should simply read normalized state
- narrow math/runtime kernels

## Skill status taxonomy

Every planned HyperTwist skill should be classified as one of:

### `Live first-party skill`

- backed by implemented first-party commands/services
- safe to expose in live product/UI

### `Command-contract pending`

- feature authority is understood
- first-party capability is retained
- command contract is not yet stable enough to wrap

### `Clean-room spec pending`

- retained source value exists
- product-side skill may only be specified, not implemented yet
- waiting for clean-room command design or bounded reimplementation

### `Placeholder family`

- known useful future skill family
- not yet source-grounded or not yet worth formalizing

## Phase implementation strategy

Keep the `S1-S7` macro-order, but execute it through bounded sub-packets.

### S1 - skill substrate and registry

Build the shared base first:

- first-party skill registry
- enable/disable state
- menu/settings exposure
- provenance/invocation logging
- command/service binding metadata
- examples and validation harness

#### `S1-A` registry and manifest contract

Outputs:

- first-party skill manifest schema
- skill id, version, owner lane, and status fields
- command/service binding declaration
- permission/scope declaration
- provenance/log declaration

Acceptance gates:

- every skill can be described without ad hoc metadata
- disabled skills remain installed but inert

Current state:

- the bounded first-party `Phase S1-A` skill registry and manifest contract
  packet is now landed in current code
- settings/menu/off-state runtime controls remain deferred to `S1-B`
- the bounded first-party `Phase S1-C` invocation/provenance/audit-ledger
  packet is now landed above the registry substrate

#### `S1-B` settings, menu, and visibility controls

Outputs:

- global skill enable/disable master switch
- per-skill enable/disable state
- visibility grouping

Acceptance gates:

- core product still works with all skills off
- no skill requires prompt babysitting to disable

Current state:

- the bounded first-party `Phase S1-B` settings/menu/off-state control packet
  is now landed in current code
- the bounded first-party `Phase S1-C` invocation/provenance/audit-ledger
  packet is now landed in current code
- the bounded first-party `Phase S2-A` permissive analyzer wrapper packet is
  now landed in current code

#### `S1-C` invocation, provenance, and audit ledger

Outputs:

- invocation record format
- command/service provenance
- failure/cancel recording

Acceptance gates:

- skill output never becomes untraceable product truth

Current state:

- the bounded first-party `Phase S1-C` invocation/provenance/audit-ledger
  packet is now landed in current code
- the bounded first-party `Phase S1-D` authoring/examples/validation-harness
  packet is now landed in current code
- the bounded first-party `Phase S2-A` permissive analyzer wrapper packet is
  now landed in current code

#### `S1-D` authoring, examples, and validation harness

Outputs:

- first-party skill authoring template
- validation corpus structure
- per-skill smoke/eval contract

Acceptance gates:

- new skills can be added without inventing structure

Current state:

- the bounded first-party `Phase S1-D` authoring/examples/validation-harness
  packet is now landed in current code
- the bounded first-party `Phase S2-A` permissive analyzer wrapper packet is
  now landed in current code
- the bounded first-party `Phase S2-B` clean-room command-contract packet is
  now landed in current code

### S2 - refactor and analyzer skills

Start with the highest-leverage engineering/tooling family.

#### `S2-A` permissive live analyzer wrappers

Outputs:

- architecture scan
- policy scan
- route inspection
- watch-and-recheck

Acceptance gates:

- each skill maps to a stable first-party invocation pattern
- each skill can surface structured output

Current state:

- the bounded first-party `Phase S2-A` packet is now landed in current code
- review/analyzer wrappers now own architecture scan and policy scan output
- provider/ops wrappers now own route inspection output
- memory/continuity wrappers now own watch-and-recheck output
- restrictive training/coaching lanes now have first-party clean-room
  command-contract specs and a bounded safety model

#### `S2-B` clean-room command-contract spec

Scope:

- restrictive training/replay/coaching lanes

Outputs:

- first-party command-contract specs for clean-room lanes
- safety model for bounded clean-room skill work

Acceptance gates:

- a future skill can wrap the first-party contract without donor wording

Current state:

- the bounded first-party `Phase S2-B` packet is now landed in current code
- restrictive training/coaching lanes now carry first-party command-contract
  specs in HyperTwist-owned terms
- eval posture now defers only until `S2-C` clean-room skill specs
- the bounded first-party `Phase S2-C` clean-room skill-spec packet is now
  landed in current code

#### `S2-C` clean-room skill specs

Outputs:

- clean-room-ready skill specs
- not necessarily live implementation yet

Acceptance gates:

- the skills are expressible entirely in first-party terms

Current state:

- the bounded first-party `Phase S2-C` packet is now landed in current code
- restrictive training/coaching lanes now carry clean-room-ready skill specs in
  first-party terms
- the skillization foundation now stays bounded until later live
  implementation is separately justified

### S3 - memory and continuity skills

#### `S3-A` continuity and resume skills

Outputs:

- `resume-session`
- `search-history`
- `capture-note`

Acceptance gates:

- continuity skills read authoritative stores

Current state:

- the bounded first-party `Phase S3-A` packet is now landed in current code
- `resume-session` is live over the landed first-party continuity/resume seam
- `search-history` is live over the landed first-party recall/provenance seam
- `capture-note` remains explicit but non-live, because active user-authored
  note capture is still separately owner-gated beyond the bounded `Phase 6R-M5`
  posture seam

#### `S3-B` recall and compact-view skills

Outputs:

- `recall-memory`
- `generate-compact-view`

Acceptance gates:

- compact views remain optional and linked to authoritative sources

Current state:

- the bounded first-party `Phase S3-B` packet is now landed in current code
- `recall-memory` is live over the landed first-party recall and provenance
  drill-down seam
- `generate-compact-view` is live over the landed derived adjunct seam while
  remaining optional and linked back to authoritative sources

#### `S3-C` workflow-memory capture skills

Outputs:

- bounded procedural-memory capture skills

Acceptance gates:

- workflow memory does not collapse into opaque summaries

Current landed posture:

- the bounded first-party `Phase S3-C` packet is now landed in current code
- `capture-session-template` is live over the landed first-party procedural
  workflow ledger seam for authoritative session-template and drill-workflow
  entities
- `capture-follow-up-routine` is live over the landed first-party procedural
  workflow and continuity seams for authoritative review-plan, coach-action-plan,
  and queue follow-up entities
- workflow capture remains separate from user-authored notes and does not
  collapse into opaque summaries
- bounded first-party `Phase S4-A` extraction skills are live for
  `extract-docs` and `extract-design-spec` over authoritative first-party
  docs/design source surfaces
- bounded first-party `Phase S4-B` browser diagnostics skills are live for
  `capture-browser-trace` and `discover-browser-api` over authoritative
  first-party browser/service source surfaces while remaining separate from
  design translation
- bounded first-party `Phase S4-C` design shell skills are live for
  `translate-design-shell` and `translate-design-interaction` over
  authoritative first-party docs, design, browser, and packet source surfaces
  while remaining separate from generic browser-shell orchestration
- bounded first-party `Phase S5-A` workflow/review wrappers are live for
  `review-proposal`, `review-diff`, and `wrap-bounded-workflow` over
  authoritative first-party extraction, workflow-memory, design-shell, and
  packet source surfaces while remaining separate from implementation-review,
  delegation, and plan-synthesis widening
- bounded first-party `Phase S5-B` implementation/delegation specs are live
  for `review-implementation` and `specify-bounded-delegation` over
  authoritative first-party workflow/review, design-shell, and packet source
  surfaces while remaining separate from plan synthesis, autonomous execution
  claims, and broad orchestration widening
- bounded first-party `Phase S5-C` plan/orchestration glue is live for
  `synthesize-plan` and `chain-bounded-workflow` over authoritative
  first-party implementation/delegation, workflow-memory, workflow/review, and
  packet source surfaces while remaining separate from provider routing,
  domain skill-pack widening, and autonomous execution claims
- bounded first-party `Phase S6-A` provider-neutral profile/routing skills are
  live for `inspect-provider-profile`, `setup-byok-profile`, and
  `diagnose-provider-routing` over authoritative first-party provider-neutral
  session-config, BYOK custody, routing-policy, route-decision, route-health,
  and wrapper source surfaces while keeping OpenAI-compatible custom endpoints
  first-class and remaining separate from provider-specific overlays
- bounded first-party `Phase S6-B` usage and operations audit skills are live
  for `audit-provider-usage`, `inspect-provider-topology`, and
  `diagnose-route-service` over authoritative first-party normalized
  usage/cost, quota, route/service-health, and operator-shell source surfaces
  while preserving normalized first-party accounting ownership and remaining
  separate from settlement execution or provider-portal widening
- bounded first-party `Phase S7-A` domain-pack framework skills are live for
  `specify-domain-packaging` and `specify-domain-pack-grouping` over
  authoritative first-party plan/orchestration, provider usage/operations
  audit, and placeholder-domain source surfaces while preserving placeholder
  pack deferral and remaining separate from retained domain-pack claims or
  creative/media widening
- bounded first-party `Phase S7-B` retained domain-pack skills are live for
  `review-training-replay-pack`, `curate-curriculum-content-pack`, and
  `prepare-media-export-pack` over authoritative first-party framework,
  training/replay, catalog/content, and media/export source surfaces while
  preserving first-party retained-pack grounding and remaining separate from
  creative adjunct widening

### S4 - browser/docs/design skills

#### `S4-A` extraction skills

Outputs:

- docs extraction
- design-spec extraction

#### `S4-B` browser diagnostics skills

Outputs:

- browser trace capture
- browser/API discovery

#### `S4-C` translation/design-to-native skills

Outputs:

- bounded design-to-native translation skills

### S5 - workflow and review skills

#### `S5-A` permissive workflow/review wrappers

Outputs:

- proposal review
- diff review
- bounded workflow wrappers

#### `S5-B` implementation-review and delegation specs

Outputs:

- implementation review
- bounded delegation specs

#### `S5-C` plan synthesis/orchestration glue

Outputs:

- plan synthesis
- bounded workflow chaining

### S6 - provider/gateway/operations skills

#### `S6-A` provider-neutral profile/routing skills

Outputs:

- inspect provider profile
- setup BYOK profile
- diagnose routing

Acceptance gates:

- custom OpenAI-compatible endpoints remain first-class

#### `S6-B` usage and operations audit skills

Outputs:

- usage audit
- topology inspection
- route/service diagnostics

Acceptance gates:

- provider skills read normalized first-party state

### S7 - domain and creative skill packs

#### `S7-A` domain-pack framework

Outputs:

- packaging rules
- enable/disable grouping

#### `S7-B` first retained domain packs

Likely families:

- training/replay review pack
- curriculum/content pack
- media/export pack

#### `S7-C` creative/media packs

Outputs:

- optional adjunct creative/media packs

## Packet acceptance matrix

Every skill packet should record:

1. packet scope
2. feature/lane owner
3. `A/R/F` authority basis
4. first-party command/service dependency
5. UI/settings exposure plan
6. audit/provenance plan
7. validation cases
8. off-state behavior
9. non-goals

If `4`, `7`, or `8` are missing, the packet is not ready.

## Initial first-party command families to formalize

Preferred future command families:

- `ht analyze ...`
- `ht graph ...`
- `ht watch ...`
- `ht route ...`
- `ht review ...`
- `ht train ...`
- `ht recognition ...`
- `ht replay ...`
- `ht coach ...`
- `ht catalog ...`
- `ht memory ...`
- `ht provider ...`

These are target-shape command families, not claims of implemented reality.

## Current named skillization endpoint

The browser/docs/design extraction base, browser diagnostics seam,
design-shell translation seam, workflow/review family, implementation/
delegation spec layer, bounded plan/orchestration glue layer, and bounded
provider-neutral profile/routing layer are now live, and the bounded
provider usage/operations audit layer is now live, and the bounded domain-pack
framework layer is now live, and the bounded retained domain-pack layer is now
live, and the bounded creative/media adjunct layer is now live for:

- `compose-replay-explainer-pack`
- `prepare-media-parser-pack`
- `curate-shared-fixture-pack`

Creative/media widening has now reopened through `S7-C` without skipping the
normalized provider/ops, framework, and retained-pack lanes, and the current
named first-party skillization ladder is now landed through `S7-C`.

## Product messaging rule

Later user-facing docs may say HyperTwist has:

- optional operator skills
- review/analyzer skills
- memory/continuity skills
- provider/ops skills
- domain skill packs

But those claims must still respect the feature-registry tiers:

- implemented now
- deep-source grounded retained
- shallow placeholder

## Bottom line

Yes, HyperTwist should grow a broad skill layer.

But the mature path is:

- first-party command contracts first
- skills second
- clean-room command specs for restrictive lanes
- no donor command surface promoted into product truth by accident
