highway-architecture
Manages one reference architecture from one accepted adr. Use when an ADR is accepted and the person wants the reference architecture that realizes it, or when highway-onboarding hands off an accepted ADR.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- highway-architecture
- license
- Apache-2.0
- metadata
- { "usage": "Run highway-architecture with one adr id.", "version": "5.8.0" }
- description
- Manages one reference architecture from one accepted adr. Use when an ADR is accepted and the person wants the reference architecture that realizes it, or when highway-onboarding hands off an accepted ADR.
02 资源文件 3
- 资产文件assets/architecture-record.md2.9 KB
- 参考文档references/proposal.md2.4 KB
- 参考文档references/record.md8.5 KB
03 SKILL.md 正文
highway-architecture
Purpose
Creates one proposed Reference Architecture from an accepted ADR after the person accepts the proposed architecture.
When to use
- The person invokes
highway-architecturewith one ADR id. - The person invokes
highway-architecturewithout an ADR id. highway-onboardinghands off an accepted ADR id.
When not to use
Do not select an ADR by recency, filename, or batch.
Do not use an ADR whose status is not accepted.
Do not change the Discovery, Request, Profile, Objectives, Controls, or NFRs.
Do not change the ADR or its catalog row, except its Reference Architecture field and its Architecture ID.
Do not select a different ADR alternative.
Do not create a Reference Implementation or authorize implementation.
Do not create capability records or capability ids.
Do not report Status, Summary, Next Action, Blocking Reason, Missing, Complete, or Blocked.
Inputs
- One ADR id that matches one row in
adrs/adrs.md, when the person supplies one. adrs/adrs.mdandarchitectures/architectures.md.- The accepted ADR at
adrs/[ID].md. - Accepted Profile, Objectives, Controls, and NFRs when present.
architectures/architectures.mdandarchitectures/RA*.mdwhen present.assets/architecture-record.md.highway-implementation.- The highway-experience skill, activated first.
Outputs
The complete structure is assets/architecture-record.md. adrs/adrs.md and architectures/architectures.md keep the structure highway-setup seeded.
- One architecture record at
architectures/[ID].mdafter the person accepts the proposed architecture, or whenhighway-onboardinghands off an accepted ADR id. - An updated
architectures/architectures.mdwritten with that record. - The ADR's Reference Architecture field set to that architecture id, and the ADR's Architecture ID in
adrs/adrs.mdset to the same id. - A closing message that names the architecture and the implementation command.
- No architecture when the ADR is missing, not accepted, or a write fails.
Procedure
Activate the highway-experience skill before any output the person sees, and follow it for Highway's identity, the Experience Standard, and the storage contract.
Before the first question, confirm these seeded files exist: adrs/adrs.md, architectures/architectures.md.
When any is absent, emit the message below exactly, stop, and write nothing.
Oops... we need to setup your repository.
Highway needs to gather your organizational preferences and set up your repository. Run highway-setup to get started.
Emit only the active template. Follow this order: onboarding when highway-onboarding hands off an accepted ADR id; choose when no ADR id is supplied; otherwise start, then identifier, title when needed, write, name, and close. The ADR remains the decision. Inherit its decision, rationale, alternatives, consequences, and constraints without changing their meaning. Describe the architecture in conceptual terms. A platform, product, vendor, or specific technology stays in the inherited decision and is not part of the architecture. A missing Profile, Objective, Control, or NFR continues without invented evidence. A malformed one of those baselines stops the skill and writes nothing.
One accepted ADR produces at most one architecture. When the architecture catalog already has that ADR as Parent, show the recorded architecture and write no second one.
Before a step in this table, read its file and follow it to the end.
| File | Steps |
|---|---|
references/proposal.md |
start |
references/record.md |
identifier, title, write, name |
Entry
When highway-onboarding hands off an accepted ADR id, go to onboarding.
- Read the invocation for one ADR id. When it has no ADR id and contains the exact title of one waiting ADR, as
choosedefines it, that ADR's id is present. Compare without regard to case. - When none is present, go to
choose. - When an ADR id is present, resolve it. When it matches no ADR, stop. Say the ADR was not found. Write nothing.
- When that ADR status is not
accepted, stop. Say the ADR is not accepted. Write nothing. - When the ADR's Reference Architecture field names an RA id, show that architecture and write nothing.
- When that ADR already appears in an architecture catalog ADR ID cell, show the recorded architecture. When the ADR's Reference Architecture field is still
None, go toname. Otherwise write nothing. - Otherwise go to
start. Create an architecture only when the accepted ADR names none.
choose
Read adrs/adrs.md and architectures/architectures.md. An ADR is waiting when its Status is accepted, its Architecture ID column is None, and its ADR ID does not appear as a whole id in any architecture catalog ADR ID cell. A removed architecture row still counts as that ADR already having an architecture. Do not open ADR records to build this list.
When none are waiting, say that no ADR is waiting for a Reference Architecture. Write nothing.
Otherwise emit one numbered line per waiting ADR, starting at 1, in ADR catalog order. Show the ADR ID and its title. A stated number selects that ADR.
1. [ADR ID]: [ADR Title]
Which ADR would you like to turn into a Reference Architecture?
- An ADR id, a listed ADR title, or its number: follow Entry from case 3.
unknown: re-emit this list. Stay onchoose.decline: stop. Write nothing.
onboarding
highway-onboarding hands off one accepted ADR id. Write the architecture as accepted without asking the person, except for the questions in step 4. Emit nothing else.
- Resolve the ADR as Entry does from case 3. When Entry would stop, return to
highway-onboardingand say why. - When the ADR's Reference Architecture field names an
RAid, return that id tohighway-onboarding. Write nothing. When the ADR already appears in an architecture catalog ADR ID cell and its field is stillNone, follownamefor that architecture, then return its id. - Build the architecture as
startdoes, without emitting it. Current Decisions is this ADR. Do not write Key Technologies. Do not copy the decision statement. Do not ask whether a decision replaces or runs beside another. - Derive the title and the id as
identifierdoes. Ask only these: the purpose question, whenidentifierwould ask it; thetitlemessage, whenidentifierwould go totitle. Write nothing until the person gives a usable title. Adeclinewrites nothing and returns tohighway-onboardingwithout an architecture. - When
identifierreuses the existing record, go to step 6. Otherwise write aswritedoes. The catalog ADR ID cell is this ADR id. A failed write leaves every existing architecture byte unchanged. Return tohighway-onboardingand say the architecture could not be written. - Follow
name. Do not go toclose. Return theRAid tohighway-onboarding. When the ADR could not be updated, say so with the id.
Classify
Classify the latest reply before any other action.
edit: adds, removes, corrects, or replaces architecture text.accept: affirms the proposed architecture and adds no fact.unknown: the person says they do not know.question: asks for an explanation.decline: the person stops or cancels.
On start, "looks good" is accept.
close
Reference Architecture accepted
- Architecture record:
architectures/[RA id].md - Title: [Title]
- Identifier:
[RA id] - ADR:
[ADR id]
Run highway-implementation [RA id] to create the Reference Implementation.
Verification
- An ADR id for an accepted ADR opens the proposed architecture.
- An invocation without an ADR id lists the accepted ADRs whose ADR ID is absent from every architecture catalog row. Each line shows the ADR ID and its title. The list is numbered. A stated number selects that ADR. A removed architecture row keeps that ADR off the list.
- One accepted ADR produces at most one architecture.
- The proposed architecture is accepted before the record is written.
- The architecture does not change the ADR decision.
- The architecture remains conceptual. It names no platform, product, vendor, or specific technology. It has no Key Technologies section.
- The record identifier is an
RAid. The record status isacceptedafter the person accepts the architecture. It does not use anARCHidentifier or statusproposed. - Context states when the architecture applies and what it leaves open. The style states why it was chosen.
- Variation, Responsibilities, Information, and each component's responsibility and interface are in the record.
- Relationship lines use
advances,bound by, andsatisfies, orNone. - Required capabilities name their component, follow the capability title rule, and have no capability ids.
- Implementation is not authorized.
- The closing message names
highway-implementation [RA id]. - The skill creates no Reference Implementation.
- A handoff from
highway-onboardingwrites an accepted architecture without a proposal, names it on the ADR and in the ADR catalog, and returns itsRAid. It asks only the purpose question or the title message, when the title cannot be used. Adeclinewrites nothing.
Error Handling
- A missing or unknown ADR stops the skill and writes nothing.
- An ADR that is not accepted stops the skill and writes nothing.
- A second architecture for the same ADR stops the write and shows the existing architecture.
- A malformed present Profile, Objective, Control, or NFR baseline stops the skill and writes nothing.
- A failed write leaves existing architecture and catalog bytes unchanged.
- A failed ADR update keeps the architecture, says the ADR could not be updated, and does not call the chain complete.
Example
/highway-architecture ADRb7c41e20
04 同仓库更多 Skills
valid-skill
A fully conformant fixture skill used only by the tests to validate the authoring framework. Use when the tests exercise the validator.
invalid_skill_bad_id
Fixture whose directory name is not kebab-case, to test the id failure path. Use when the tests exercise the validator.
invalid-skill-undeclared-key
A fully conformant fixture skill used only by the tests to validate the authoring framework. Use when the tests exercise the validator.
invalid-skill-short-description
暂无简介
invalid-skill-relative-link
Fixture whose body carries a relative Markdown link target, to test the P8.7 failure path. Use when the tests exercise the validator.
invalid-skill-nondeterministic-criterion
Fixture whose decision criteria depend on when they are read, to test the P6.4 failure path. Use when the tests exercise the validator.