| name | wa3-spec |
| description | Review, validate, author, build, or evolve WA3 skill-contract files (.tdy) and the WA3 specification. Use when a .tdy file is involved, when checking canonical form/signature/trust, when using the guided builder from answers JSON, or when reasoning about WA3 safety rules such as core vs renderer trust, authoring LLM boundaries, extension namespace ㄝ, RL/KR revocation, canonical signing, share-link providers, Runtime/Tile sandboxing, and operate semantics. |
WA3 Spec Bundle
This is the installable root package for the WA3 portable agent-skill contract.
It includes the normative specification, guided builder profile, adapter notes,
and Go conformance/demo tool.
Non-negotiable Invariants
wa3-core is trusted; renderer output and authoring LLM output are untrusted.- LLM output is only a suggestion. Schema ownership, provenance promotion,
secret/risk gates, canonicalization, lint, trust classification, and signing
decisions are enforced by deterministic code.
.tdy integrity comes from canonical Ed25519 signatures, not transport.- Unknown
ㄝ extension fields are preserved for canonical signing but are not
trusted for security decisions.
- Mutating operate must re-check the verified contract and require confirmation
unless a code-owned low-risk action explicitly allows a human-confirmed skip.
Read Order
skill.json for portable bundle metadata.AGENTS.md for the cross-agent quickstart.WA3-SPEC.md for normative rules.docs/PROMOTE.md before moving a draft/demo contract toward production signing.- End-to-end flow docs, each owning one stage of the publish/consume journey:
docs/EXTRACT_CONTRACT.md (webpage → builder answers, output untrusted),
docs/PUBLISH_CHECKLIST.md (sign → byte-stable link → share),
docs/IMPORT_TOFU.md (download → verify → TOFU pin), and
docs/RENDER_PIPELINE.md (compile → design-template binding → render).
builder/answers.schema.json, builder/templates/, and
builder/templates/catalog.json before building from guided answers or
recommending a functional template.design_templates/ and design_templates/catalog.json when you need a
visual reference for rendering a verified UI plan. Treat *.dsdy files as
display-only design guidance, never as executable or security-bearing
contracts.conformance/README.md before running parser, canonicalizer, builder, trust,
or bundle-check commands.
Authoring a Design Template
Use this workflow only for design_templates/*.dsdy. A design template is a
separate display-only profile inside the WA3 file family; it is not an
operable WA3 contract and does not use the operable canonical/signature trust
profile.
- Confirm the source is durable and redistributable enough to reference. Record
source and extraction date together in
ㄝㄌㄞ using bracket labels, for
example ㄝㄌㄞ：【source】frontend/src/style.css【extracted】2026-06-28.
- Extract only layout regions/grid/viewport, visual tokens, component
roles/shapes/states, WA3 block mapping, and interaction guidance.
- Exclude real copy, real action ids, backend targets, providers, permissions,
policies, secrets, remote assets, executable HTML/JS/CSS, third-party fonts,
and logos. Abstract placeholders are allowed when they cannot operate.
- Use
design_templates/_TEMPLATE.dsdy and keep the standard sections:
Purpose, Safety Boundary, Layout Profile, Visual Tokens, Component Roles,
WA3 Block Mapping, Interaction Guidance, and Source Notes.
- Keep
ㄈㄢ：reference-only and an empty ㄓㄥ：. A template with operable
namespaces such as ㄋㄥ, providers, permissions, concrete targets, or real
action ids must fail closed.
Selecting a Design Template
Before building, continuing, or restoring any .tdy, ask the user whether to
apply a *.dsdy design template. If they have a personal default design,
offer that first. Otherwise, or if the requested/default template is missing,
use design_templates/catalog.json to list the closest 3 candidates by tag fit.
The catalog is only a display recommendation index; it must not carry real
action ids, providers, backend targets, permissions, policies, secrets, or trust
state. Verified WA3 actions may be mapped to abstract component roles such as
primary_action_button at render time, but the design template never replaces
the verified action definition.
Selecting a Functional Template
Use builder/templates/catalog.json to recommend an operable builder template
before drafting answers. For product introduction pages, landing pages, solution
showcases, brochure sites, and public product pages, start from
product_showcase. For app-style product experiences, mobile product apps,
bottom-tab product apps, HMI apps, or field-engineer product apps, start from
mobile_product_app. Then show a Feature Manifest and ask which functions to
keep, remove, or rename. Functional template selection does not replace the
separate design-template question.
Common Commands
Run from conformance/:
go run ./tools/wa3 build --answers ../builder/examples/board.answers.json --out /tmp/board.draft.tdy --mock-demo /tmp/board.mock-demo.json
go run ./tools/wa3 build --answers ../builder/examples/board.answers.json --out /tmp/board.test-signed.tdy --test-sign
go run ./tools/wa3 trust /tmp/board.test-signed.tdy
go run ./tools/wa3 bundle-check
Adapter Notes
- Codex can install this root folder as the skill package because this file sits
beside
builder/, conformance/, and the full spec.
design_templates/ contains agent-readable *.dsdy visual profiles. They
can guide renderer styling, but they never override verified contract data,
action ids, permissions, confirmation requirements, or trust state. They are a
distinct display-only design format in the WA3 file family, not operable WA3
contracts. Use design_templates/catalog.json only to recommend candidates
after asking the user.- OpenHands can load the root package through
.plugin/plugin.json and
adapters/openhands/.
skills/wa3-spec/ remains the concise Codex adapter mirror for hosts that
only want the spec-reading skill without the full builder toolchain.- Claude Code, OpenClaw, Hermes, Haler, LangGraph, Voiceflow, Mistral, and
Eigent adapters live under
adapters/.
