Decisions and trade-offs

The framework records architecture decisions under docs/architecture/decisions/. Both ADRs have status ACCEPTED FOR BUILD DESIGN, which the ADRs themselves distinguish from product or live verification.

ADR-001 — One canonical static specification with contained Skill resources

Decision (source):

Author product content in src/kiyo/ with exactly eight skills/<name>/SKILL.md entries, and use stable control IDs that are independent of any standard’s clause numbering.
Keep canonical frontmatter to name and description. Host metadata goes in three overlays. Access and approval contracts stay in Markdown, not in unsupported native keys.
Each Skill reads the compact bootstrap before workflow actions, then its procedure and relevant references.
At build time, copy the complete shared subtree into each installed Skill’s references/kiyo/, preserving structure and bytes.
Keep mutable policy and Memory in the consumer project, defaulting to .kiyo/policy.md and .kiyo/memory/.
Keep tools, tests, research, and evidence developer-only; put derived bundles in dist/.

Alternatives considered and rejected:

Alternative	Reason not selected
Hand-maintained host-specific core and Skills	Competing specifications and silent parity drift
One shared plugin-root resource tree for all hosts	Relies on inconsistent or untested cross-Skill resolution
Long rules copied into every `SKILL.md`	Loses single-definition maintenance and progressive loading
Symlink to a checkout, or a runtime fetch or resolver	Breaks self-containment, cache portability, and the no-runtime boundary
Copy the complete Core into project instructions	Bloats initial context; creates stale copies after updates

Consequences: generated bundles repeat shared bytes, so each package holds roughly 794 files. Those copies are not editable authorities, and deterministic copy, parity, and reference checks prevent drift. The unsupported Codex IDE route stays an explicit gap.

ADR-002 — Bound the complete mandatory Core bootstrap

Decision (source): KIYO.md plus framework/bootstrap.md combined must fit 120 physical lines and 600 words. Each selected SKILL.md fits 250 lines and 1,200 words. The project adapter keeps its 250-word ceiling. No token equivalence or host limit is claimed.

Consequence: mandatory text cannot hide in an unbounded include. Other Core files are conditional references, and static counts enforce the ceilings (see Context budgets).

Observable trade-offs

Choice	Benefit	Cost
Static Markdown, no runtime	Nothing executable to trust or install; portable across hosts	No enforcement; compliance depends on the agent and host
Full snapshot per Skill	Every link resolves inside one folder; survives cache relocation	Larger packages; generated duplication
Explicit selection as the documented route	Honest about activation	More typing than always-on behavior; automatic loading untested
Separate G-mode, risk, and preset	No false equivalences between different questions	More concepts to learn
Approved decisions preserved over code	Intent survives drift	Conflicts need human decisions to resolve

Open owner decisions

From docs/build/DECISIONS.md. All are OPEN:

ID	Decision
DEC-001	Final publication name and native marketplace identifiers; “Kiyo Axiom Framework” is only the working name
DEC-002	Confirm the license intended for publication; the existing MIT LICENSE remains intact
DEC-003	Publisher identity, namespace, and authorized publication destination
DEC-004	Treatment of the Codex IDE native-plugin gap; no fallback or scope reduction approved

Superseding either ADR requires a new ADR with a reason and its migration and verification impact. The ADRs explicitly forbid erasing a decision to match later drift.