Skip to content

Pack v2: freeze commands and doctor final shape #668

@donbox

Description

@donbox

Summary

We need to freeze the durable Pack v2 contract for commands/ and doctor/ without accidentally hardening still-open design questions.

Why

The first-pass validation suite can safely gate discovery conventions, but the richer command/doctor meta-model is still under-specified. We should settle the final shape explicitly rather than letting tests or partial implementations fossilize it.

Freeze now

  • commands/<path>/run.sh as the default command entrypoint
  • doctor/<path>/run.sh as the default doctor entrypoint
  • directory shape implies command/check words by default
  • help.md as the default adjacent help surface
  • command.toml / doctor.toml as optional escape hatches
  • imported command/doctor exposure through import bindings

Decide here

  • what command.toml and doctor.toml are allowed to mean long-term
  • how much symmetry we want between command and doctor manifest shapes
  • collision policy boundaries
  • whether there is any richer top-level extension / command-identity model beyond the default directory convention

Out of scope for the current suite gate

  • final manifest symmetry/shape as a release gate
  • broader design ambitions that are not yet implemented or frozen

References

  • docs/packv2/doc-directory-conventions.md
  • docs/packv2/doc-pack-v2.md
  • docs/packv2/doc-conformance-matrix.md
  • task: migration-validation-suite-first-pass

Metadata

Metadata

Assignees

No one assigned

    Labels

    city-pack-v2City/pack v2 design and migration workkind/designDesign / Product questions we need to resolvephase/post-0.13.6Explicitly after the 0.13.6 merge wavestatus/needs-triageInbox — we haven't looked at it yet

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions