highway-objectives

Imported from jacob623/highway-skills (.github/skills/highway-objectives/SKILL.md). Install upstream with npx skills add jacob623/highway-skills --skill highway-objectives. Copyright stays with the author.

highway-objectives

Purpose

Maintains the repository-wide Business Objective baseline as user-owned, identified Markdown records that explain the business direction later Highway artifacts may reference.

Interactive Workflow UX Contract

Objective creation follows the Interactive Workflow UX Contract in the Highway Experience Standard. It uses adaptive discovery across Outcome, Success, and Significance. Evaluate the complete active response before selecting the next action, expose at most one unresolved response-demanding question or decision, and never report fixed discovery progress. Put the Next Action first and omit implementation details unless requested.

User Exits are pause, cancel, or stop responding; Owner Outcomes are declined, aborted, or blocked. Resume Applicability: New interaction; unanswered prompts, drafts, and checkpoints are not restored. Objective ownership remains authoritative for identifiers, records, catalogs, and completion claims.

When to use

Use this skill to set up, configure, inspect, add, create, update, remove, or reset Business Objectives. The supported actions are exactly setup, configure, view, show, describe, readiness, add, new, update, remove, and reset.

Use it when a user wants a durable objective with measurable success measures, a user-approved rationale, or a stable OBJ reference for future Capability relationships.

Use readiness for a read-only assessment of whether the Objective baseline is usable. This action owns Objective completeness and does not start setup or mutation.

When not to use

Do not use this skill to author Controls, Non-Functional Requirements, Capabilities, or other Highway governance baselines. Route those requests to their owning skill.

Do not edit an objective record or library/governance/objectives.md directly. Direct edits break the permanent identifier, catalog, and baseline version together.

Inputs

A plain-language request naming one supported action and, for a mutation, the desired objective change. The project root, identified by locating .highway/. If .highway/ cannot be located, the project root is unknown and no objective path may be guessed.

The user-owned objective records at library/objectives/OBJXXXXXX.md, never beneath .highway.

The user-owned catalog at library/governance/objectives.md, when a baseline exists. The catalog is authoritative for next_id and the semantic baseline version.

The complete retained-record structure in .highway/library/templates/output/objective-record.md. The template defines the required frontmatter and body ordering; its values remain user-owned.

The complete catalog structure in .highway/library/templates/output/objective-catalog.md.

Objectives is a Repository Context Participating Skill. Its declared Repository Context Documents are Identity, Highway Vision, Highway Platform Objectives, and Profile. Identity supplies behavioral framing only; Highway Vision supplies downstream traceability framing only; Highway Platform Objectives evaluates Highway assistance only; Profile is the only declared source that may supply accepted organizational evidence for Objective interpretation, suggestions, Significance, or Rationale. Existing Objective records are accepted context for exact duplicate and semantic overlap guidance, not a declared context document or a source of new organizational facts.

Consume only context relevant to the active decision. Record each unavailable or malformed context document, exclude it from interpretation, and continue with valid evidence. An owner-level malformed Profile baseline remains authoritative as Blocked. Active user evidence remains authoritative when it conflicts with accepted context. An exact duplicate names the existing Objective and asks whether to change it or create a distinct outcome; semantic overlap is advisory and never silently merges, deletes, or rewrites an Objective.

Outputs

A read-only status response, or a mutation report containing exactly these fields. Confirmed objective records follow the complete structure in .highway/library/templates/output/objective-record.md.

The readiness action emits exactly these four lines in this order:

Status: <Complete, Missing, or Blocked>
Summary: <objective baseline explanation>
Next Action: <owner route or None>
Blocking Reason: <reason or None>

At least one valid Objective with a consistent catalog and next_id is Complete. No valid records is Missing; a malformed record, catalog, or allocation state is Blocked. A blocked response has a non-empty reason; every other response uses Blocking Reason: None. Readiness does not write records, catalogs, or identifiers.

Mutation reports contain these fields in this order:

Action: <action>
File: <changed file>
Summary: <change summary>
Affected Entries: <affected identifiers or None>
Confirmation Status: <Confirmed or non-write state>
Resulting Version: <version or unchanged>

Readiness does not write records, catalogs, or identifiers. The readiness state names are exact: Status: Missing routes to /highway-objectives setup, Status: Complete has Next Action: None, and Status: Blocked has Next Action: None plus a non-empty Blocking Reason.

Confirmed mutations write objective records beneath library/objectives/ and regenerate the catalog at library/governance/objectives.md. No objective record is ever written beneath .highway.

The catalog contains the baseline version, next_id, an objective index ordered by permanent identifier, each title and status, an ownership statement, and a warning not to edit the catalog directly. No timestamp, random identifier, or environment-derived value is emitted.

Action selection

Accept exactly these actions: setup, configure, view, show, describe, readiness, add, new, update, remove, and reset. view, show, and describe are equivalent read-only actions. setup, configure, add, and new are the guided creation workflow.

If the request contains an unsupported or ambiguous action, stop and ask the user to clarify. Do not infer an action and do not write any file. If no objective baseline exists during a read-only action, report its absence without creating an artifact.

For direct invocation, /highway-objectives setup and bare /highway-objectives add provide concise direct invocation context explaining that the interaction identifies an outcome worth pursuing; they do not claim Setup introduced the purpose or emit Setup's transition language. /highway-objectives add <evidence> evaluates supplied evidence before selecting a question and skips the opening Outcome question when Outcome is already supported.

Read-only workflow

For readiness, read and validate the complete baseline, classify it using the Objective rules, and emit the exact four-field response without mutation. For view, show, or describe, read and validate the complete baseline, then report the current version, objective count, and every objective identifier, title, and status in stable identifier order. Do not modify objective files, the catalog, or any other file. The same bytes must remain before and after the response.

Creation and update workflow

Before producing any context-dependent output, consult available declared Repository Context Documents and use only context relevant to the active interaction. Record unavailable or malformed declared context and do not fabricate substitute context or user-owned evidence.

For setup, configure, add, and new, begin with concise direct-invocation context when Setup has not introduced the purpose, then render this complete Objectives-owned opening when no usable Outcome evidence was supplied:

What's an important outcome you'd like to achieve?

If you'd like some suggestions based on your organization's Profile, just let me know. If you're not sure, just say "I don't know," and we'll work through it together.

Process supplied /highway-objectives add evidence before choosing a question. Evaluate all active evidence across Outcome, Success, and Significance, then select exactly one next action in this order:

1. If Outcome is unresolved, ask one conversational Outcome question.
2. Otherwise, if Success is unresolved, ask one Success question. When a Success question has a downstream implication not already established, explain how the answer defines success for future Highway work.
3. Otherwise, if Significance is unresolved, ask one question about why the outcome matters.
4. Otherwise, present the complete proposal.

Accept ordinary business language, uncertainty, activity descriptions, natural correction, replacement, rejection, cancellation, abandonment, and multiple dimensions in one answer. When multiple meaningful outcomes are present without explicit grouping, ask whether to represent them together or separately. Preserve explicitly grouped outcomes and retain explicitly separate outcomes in user-provided order for sequential processing. I don't know starts guided discovery and does not manufacture a recommendation. An explicit request for suggestions may present one to three distinct possibilities grounded only in relevant accepted Profile evidence; suggestions remain transient until the user selects, restates, modifies, or otherwise clearly adopts one. Asking for more information about a suggestion is not adoption. If Profile evidence cannot support a meaningful suggestion, say: I don't see enough in your Profile to make a useful suggestion here, but we can work through it together. Then ask one exploratory question.

When user input materially changes the interpretation, suggestion relevance, Rationale synthesis, overlap handling, or downstream relationship guidance, provide one concise contextual acknowledgment explaining what changed before asking the next question or presenting the next decision. Do not turn the acknowledgment into an additional response-demanding question.

After a correction, re-evaluate staged Outcome, Success, and Significance evidence and discard staged interpretations that no longer support the revised intent.

When Outcome evidence supports a Statement, Success evidence supports at least one Success Measure, and Significance is supported by either an explicit reason in the active conversation or an applicable direct organizational connection from accepted Profile evidence that can be stated without adding unsupported facts, present one complete proposal with distinct user-facing sections:

Here's the objective I've captured:

[Objective Title]

[Statement]

Success looks like:

• [Success Measure]

Why it matters: [Rationale]

Does this reflect what you're trying to accomplish?

Do not expose an unallocated or newly allocated identifier, catalog change, or version in normal pre-persistence review. Natural acceptance authorizes non-destructive creation without a second persistence-confirmation question. Natural correction, replacement, rejection, cancellation, abandonment, or interruption keeps the proposal transient and writes nothing.

After each verified creation, ask Anything else you'd like to accomplish?. A directly supplied outcome starts the next transient conversation immediately; an affirmative response without an outcome asks What's another important outcome you'd like to achieve?; a suggestion request uses the same Profile-grounded behavior; uncertainty about whether another Objective exists offers help without requiring discovery; and an explicit finish returns terminal collection success.

For update, resolve exactly one existing objective by identifier and title before staging a change. Preserve its identifier and every untouched field. Confirm the complete staged record and catalog before writing. An update changes the baseline by exactly one PATCH increment.

Destructive workflow

For remove, resolve the target before staging and show its identifier and title. Request explicit confirmation before deleting the record and regenerating the catalog.

For reset, list every objective identifier and title that would be removed. Request explicit confirmation before replacing the baseline. A count alone is not sufficient review.

A declined, ambiguous, malformed, or aborted remove/reset operation writes nothing. It preserves every affected file byte-for-byte and leaves the baseline version and next_id unchanged.

Baseline invariants and transactions

Read and validate the complete baseline before proposing any mutation. Every objective record must be under library/objectives/, have a unique valid OBJ identifier, and contain id, title, status, capabilities: [], statement, success measures, and rationale. Every catalog entry must resolve to exactly one record. A catalog with objective files but no catalog, duplicate identifiers, a missing catalog target, an invalid next_id, or a record outside library/objectives/ is malformed and must be rejected without overwriting user-owned content.

The catalog owns allocation state. next_id must be greater than every allocated identifier, including identifiers whose records were removed. An identifier is permanent and is never changed or reused, including after reset. Stable OBJ identifiers are reserved for future Capability relationships.

Stage every mutation as a transaction: read and validate the complete baseline, re-evaluate the final proposal and overlap, construct the proposal, obtain natural user validation, revalidate the authoritative baseline and overlap state, allocate one permanent identifier, construct record and catalog mutations, persist both retained outputs as one successful operation, and verify both outputs before claiming completion. If validation, writing, or retained-output verification fails, preserve the prior verified bytes; the workflow does not claim successful creation and identifies the unverified record or catalog output. Regenerate identical catalog bytes from identical objective inputs, with stable identifier ordering and no timestamp, random value, or environment value.

If pre-write revalidation discovers a new overlap, name the overlapping Objective and return to one user decision. The previous creation confirmation is no longer active; if the proposal changes, re-evaluate the staged Outcome, Success, and Significance evidence, present the resulting complete proposal again, and require natural validation again before persistence.

Increment the baseline exactly once per confirmed action: Add/New is MINOR, Update is PATCH, and Remove/Reset is MAJOR. Failed or declined actions do not change the version. A confirmed mutation report names the action, changed file, summary, affected entries, Confirmation Status: Confirmed, and resulting version. A declined or failed report names the reason and the applicable non-write confirmation state.

Verification

• Confirm objective records are under library/objectives/, never .highway, and the catalog is under library/governance/objectives.md.
• Confirm the eleven supported actions route exactly as specified and unsupported or ambiguous input asks for clarification without a write.
• Confirm read-only actions report version, count, identifiers, titles, and statuses without byte changes, including when the baseline is absent.
• Confirm readiness emits the exact four ordered fields, classifies missing and malformed baselines, and leaves records, catalogs, and next_id unchanged.
• Confirm every record identifier is unique, permanent, six digits, and never reused; confirm catalog next_id is greater than every allocated identifier.
• Confirm every catalog entry resolves to one record and malformed baselines are rejected without overwriting user content.
• Confirm setup/configure/add/new use adaptive discovery, process rich evidence without redundant questions, preserve user-owned wording, and create the complete retained record with capabilities: [] only after natural validation.
• Confirm the opening, complete proposal labels, one unresolved decision rule, uncertainty guidance, suggestion adoption boundary, collection loop, and New interaction resume behavior.
• Confirm every suggestion is grounded in relevant accepted Profile evidence, excludes unrelated Profile information, and contains no unsupported organizational facts.
• Confirm materially changing input receives one concise contextual acknowledgment and that multiple outcomes are grouped or processed in explicit user-provided order.
• Confirm absent or malformed Identity, Highway Vision, Highway Platform Objectives, and Profile are recorded without fabricated replacement context or user-owned evidence.
• Confirm no normal pre-persistence review exposes an identifier, catalog change, or version.
• Confirm final baseline and overlap revalidation precedes allocation, both retained outputs verify before completion, and persistence failure names the unverified output without claiming success.
• Confirm add/new, update, and remove/reset increment MINOR, PATCH, and MAJOR exactly once only after a confirmed successful mutation.
• Confirm declined, ambiguous, malformed, or aborted operations leave all affected bytes byte-for-byte unchanged.
• Confirm identical inputs regenerate identical catalog bytes and emitted artifacts contain no timestamp, random identifier, or environment-derived value.

Error Handling

• The project root cannot be located: abort and ask where .highway/ is located.
• An action is unsupported or ambiguous: abort, ask for clarification, and write nothing.
• The catalog is absent while objective records exist: abort and ask for catalog repair.
• A record, catalog entry, identifier, or next_id is malformed or inconsistent: abort, name the inconsistency, and leave all user-owned content untouched.
• A referenced objective does not exist: abort and name what was searched for.
• A destructive action lacks explicit confirmation: abort after the impact preview and write nothing.
• A mutation cannot complete as one staged transaction: abort and preserve the original bytes.

Example

/highway-objectives add Improve delivery reliability by reducing escaped defects.

The skill treats the supplied text as initial Outcome evidence, asks only for unresolved Success or Significance evidence, presents the complete labeled proposal for natural validation, allocates the next permanent OBJ identifier only after confirmation, persists and verifies the record and catalog together, and reports the identifier only after successful verification.