Harness Intelligence Wiki
SpecsCLISettings Reconfiguration

CLI Settings Reconfiguration

CLI Settings Reconfiguration

User input

then lets bring a new command, hi ensure or smth that enables the selection of the initial scaffold init that lets you input backlog, asset manager, repo manager of the .devpunks/settings.json. this command should reuse the same code path of that initial selector picker steps. therefore we should abstract that code and put it in both commands.

this hi ensure essentially lets you reconfigure the settings.json without going a full run of scaffold init

we also have to add a new field in settings.json, the backlog project url. and make sure that write backlog always knows about such url.

Context

Repository operators need to change backlog, asset, and repository authorities after initial adoption without rerunning the full scaffold initializer. The configured backlog destination must also be explicit as backlogProjectUrl so backlog-writing agents target the intended project instead of rediscovering or guessing it.

Non-Goals

  • Rerun scaffold setup, regenerate managed assets, or rewrite project documentation as a side effect of settings reconfiguration.
  • Add provider-specific project creation or credential management.
  • Reject legacy settings files solely because they predate the backlog project URL field.
  • Bootstrap a repository that has no .devpunks/settings.json; operators must run hi scaffold init first.

Acceptance Criteria

  1. hi ensure lets an operator select backlogProvider, assetProviderSlug, and repositoryManager, then enter backlogProjectUrl. The URL is trimmed, must be an absolute HTTP(S) URL, and rejects empty, relative, or non-HTTP values.
  2. One shared settings-selection path owns the three provider prompts and backlogProjectUrl; both hi scaffold init and hi ensure use it, while init's wiki-framework prompt remains init-only.
  3. hi ensure updates .devpunks/settings.json without running the broader scaffold initialization flow or changing unrelated project files.
  4. Existing settings values are the prompt defaults; accepting every default is idempotent. A missing settings file exits with actionable guidance to run hi scaffold init.
  5. Reconfiguration preserves known non-provider fields and required tools not owned solely by the previous repository manager; it removes obsolete manager-only tools, adds the new manager's requirements, and de-duplicates the result.
  6. Existing settings without backlogProjectUrl remain readable and can be upgraded through hi ensure.
  7. Init writes the selected backlogProjectUrl; setup leaves it unchanged; update check is read-only; update apply preserves its exact trimmed value while refreshing managed settings fields.
  8. Before any provider materialization, scaffolded write-backlog guidance reads .devpunks/settings.json and treats backlogProvider plus backlogProjectUrl as destination authority. If the URL is missing or invalid, it stops with actionable hi ensure guidance rather than discovering or guessing a destination.
  9. The write-backlog change originates in wearedevpunks-skills, is synchronized into Harness and CLI baseline surfaces, and is present in a scaffolded consumer.
  10. Root and command help, docs/README.md, docs/runbooks/hi-cli-scaffolding.md, and routed wiki guidance explain hi ensure, its settings-only scope, and its distinction from tool-installing hi tools ensure.

Constraints

  • Keep .devpunks/settings.json backward compatible for existing repositories.
  • Continue using hi and hint as executable names while retaining the @punks/cli package identity.
  • Shared skill changes originate in wearedevpunks-skills and are synchronized into Harness Intelligence.
  • Provider selection and URL validation must remain provider-neutral; provider-specific URL parsing is outside this capability.

Decision Log

DecisionRationale
Use hi ensureMatches the requested working name; documentation can disambiguate the existing nested hi tools ensure.
Require the URL only when writing through the selectorPreserves legacy settings readability while ensuring new or reconfigured settings have a destination.
Accept absolute HTTP(S) URLsSupplies a useful project authority without inventing provider-specific URL formats.

On this page