← Files stark AI DeveloperARCHIVED FILE
skills/architecture-compass/references/adr-catalog.md
54.3 KB · Oct 2, 2026 · 00:31 UTC
# Architecture Compass ADR Catalog Use this catalog to select only applicable decisions. Read Short first, Long when the decision governs the task, and Guide for current implementation mechanics. Long is canonical. ## Skill runtime These decisions govern Architecture Compass itself. They are not target-repository adoption candidates. ### Governance | ID | Status | Decision | Applies when | Tags | Short | Long | Guide | | ---------- | ---------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | AC-ADR-001 | Superseded | Route Architecture Compass through canonical ADR triplets | Discovering, loading, linking, validating, or presenting library rules | adr, catalog, progressive-disclosure | [Short](ac-adr-001-route-architecture-compass-through-canonical-adr-triplets.short.md) | [Long, canonical](ac-adr-001-route-architecture-compass-through-canonical-adr-triplets.long.md) | [Guide](ac-adr-001-route-architecture-compass-through-canonical-adr-triplets.guide.md) | | AC-ADR-002 | Superseded | Select actions, resolve authority, and record guardrail adoption | Historical setup/refactor, authority, and adoption behavior | actions, authority, adoption, conflict | [Short](ac-adr-002-select-actions-resolve-authority-and-record-guardrail-adoption.short.md) | [Long, canonical](ac-adr-002-select-actions-resolve-authority-and-record-guardrail-adoption.long.md) | [Guide](ac-adr-002-select-actions-resolve-authority-and-record-guardrail-adoption.guide.md) | | AC-ADR-026 | Superseded | Route Architecture Compass through explicit Setup and Apply pipelines | Historical explicit Setup/Apply selection and mapping behavior | actions, explicit-selection, setup, apply | [Short](ac-adr-026-route-architecture-compass-through-explicit-setup-and-apply-pipelines.short.md) | [Long, canonical](ac-adr-026-route-architecture-compass-through-explicit-setup-and-apply-pipelines.long.md) | [Guide](ac-adr-026-route-architecture-compass-through-explicit-setup-and-apply-pipelines.guide.md) | | AC-ADR-039 | Accepted | Prefer existing public skills conditionally | A public skill may satisfy a capability before bespoke implementation | skill-reuse, consent, installation | [Short](ac-adr-039-prefer-existing-public-skills-conditionally.short.md) | [Long, canonical](ac-adr-039-prefer-existing-public-skills-conditionally.long.md) | [Guide](ac-adr-039-prefer-existing-public-skills-conditionally.guide.md) | | AC-ADR-043 | Superseded | Route explicit Setup and Apply pipelines with risk-based validation | Historical validation-aware Setup/Apply selection and mapping behavior | actions, setup, apply, validation | [Short](ac-adr-043-route-architecture-compass-through-explicit-setup-and-apply-pipelines-with-risk-based-validation.short.md) | [Long, canonical](ac-adr-043-route-architecture-compass-through-explicit-setup-and-apply-pipelines-with-risk-based-validation.long.md) | [Guide](ac-adr-043-route-architecture-compass-through-explicit-setup-and-apply-pipelines-with-risk-based-validation.guide.md) | | AC-ADR-044 | Accepted | Record material decision lineage in non-normative Guides | Creating or maintaining an AC-ADR or its repository-ADR derivation record | decision-lineage, provenance, adr, validation | [Short](ac-adr-044-record-material-decision-lineage-in-non-normative-guides.short.md) | [Long, canonical](ac-adr-044-record-material-decision-lineage-in-non-normative-guides.long.md) | [Guide](ac-adr-044-record-material-decision-lineage-in-non-normative-guides.guide.md) | | AC-ADR-045 | Superseded | Route Architecture Compass through Setup, Audit, and Refactor with intent-bound agent selection | Historical five-workflow routing before bounded post-Plan governance persistence | actions, intent-routing, setup, audit, refactor | [Short](ac-adr-045-route-architecture-compass-through-setup-audit-and-refactor-with-intent-bound-agent-selection.short.md) | [Long, canonical](ac-adr-045-route-architecture-compass-through-setup-audit-and-refactor-with-intent-bound-agent-selection.long.md) | [Guide](ac-adr-045-route-architecture-compass-through-setup-audit-and-refactor-with-intent-bound-agent-selection.guide.md) | | AC-ADR-046 | Accepted | Rank architecture evidence without expanding operational authority | Resolving architecture evidence, implementation drift, or conflicting sources | evidence, authority, conflict, precedence | [Short](ac-adr-046-rank-architecture-evidence-without-expanding-operational-authority.short.md) | [Long, canonical](ac-adr-046-rank-architecture-evidence-without-expanding-operational-authority.long.md) | [Guide](ac-adr-046-rank-architecture-evidence-without-expanding-operational-authority.guide.md) | | AC-ADR-048 | Superseded | Persist approved governance before planned architecture refactors | Establishing governance, auditing architecture, planning, or performing ADR-guided refactoring | actions, intent-routing, planning, persistence | [Short](ac-adr-048-persist-approved-governance-before-planned-architecture-refactors.short.md) | [Long, canonical](ac-adr-048-persist-approved-governance-before-planned-architecture-refactors.long.md) | [Guide](ac-adr-048-persist-approved-governance-before-planned-architecture-refactors.guide.md) | | AC-ADR-051 | Accepted | Route Architecture Compass through public and internal decision namespaces | Architecture Compass implementation-only mechanics need a validated internal ADR namespace | adr-library, internal-policy, progressive-disclosure, validation | [Short](ac-adr-051-route-architecture-compass-through-public-and-internal-decision-namespaces.short.md) | [Long, canonical](ac-adr-051-route-architecture-compass-through-public-and-internal-decision-namespaces.long.md) | [Guide](ac-adr-051-route-architecture-compass-through-public-and-internal-decision-namespaces.guide.md) | | AC-ADR-052 | Accepted | Persist agent governance through host-neutral repository surfaces | Establishing or repairing durable governance across agent hosts | persistence, host-adapters, instructions, portability, authority | [Short](ac-adr-052-persist-agent-governance-through-host-neutral-repository-surfaces.short.md) | [Long, canonical](ac-adr-052-persist-agent-governance-through-host-neutral-repository-surfaces.long.md) | [Guide](ac-adr-052-persist-agent-governance-through-host-neutral-repository-surfaces.guide.md) | | AC-ADR-064 | Accepted | Preserve Approved Scope Through Capability-Aware Planning | Planning and approving bounded architecture work across host controls | planning, approval, capabilities | [Short](ac-adr-064-preserve-approved-scope-through-capability-aware-planning.short.md) | [Long, canonical](ac-adr-064-preserve-approved-scope-through-capability-aware-planning.long.md) | [Guide](ac-adr-064-preserve-approved-scope-through-capability-aware-planning.guide.md) | ### Agent lifecycle | ID | Status | Decision | Applies when | Tags | Short | Long | Guide | | ---------- | -------- | ---------------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- | | AC-ADR-003 | Accepted | Coordinate agents and execute only approved bounded slices | Planning, delegation, approval, mutation, interruption, or re-entry | collaboration, permissions, planning, reentry | [Short](ac-adr-003-coordinate-agents-and-execute-only-approved-bounded-slices.short.md) | [Long, canonical](ac-adr-003-coordinate-agents-and-execute-only-approved-bounded-slices.long.md) | [Guide](ac-adr-003-coordinate-agents-and-execute-only-approved-bounded-slices.guide.md) | | AC-ADR-036 | Accepted | Keep Architecture Compass portable through host adapters | Translating planning, questions, review, permissions, or instructions | portability, host-adapters, capabilities | [Short](ac-adr-036-keep-architecture-compass-portable-through-host-adapters.short.md) | [Long, canonical](ac-adr-036-keep-architecture-compass-portable-through-host-adapters.long.md) | [Guide](ac-adr-036-keep-architecture-compass-portable-through-host-adapters.guide.md) | ### Quality and delivery | ID | Status | Decision | Applies when | Tags | Short | Long | Guide | | ---------- | -------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | | AC-ADR-004 | Accepted | Report staged evidence and protect public outputs | Reporting validation, completion, publication, deployment, or unavailable evidence | evidence, reporting, privacy, publication | [Short](ac-adr-004-report-staged-evidence-and-protect-public-outputs.short.md) | [Long, canonical](ac-adr-004-report-staged-evidence-and-protect-public-outputs.long.md) | [Guide](ac-adr-004-report-staged-evidence-and-protect-public-outputs.guide.md) | | AC-ADR-050 | Accepted | Use semantic status markers in user-facing receipts | Presenting concise completion, validation, setup, audit, or limitation summaries | accessibility, reporting, status-markers, usability | [Short](ac-adr-050-use-semantic-status-markers-in-user-facing-receipts.short.md) | [Long, canonical](ac-adr-050-use-semantic-status-markers-in-user-facing-receipts.long.md) | [Guide](ac-adr-050-use-semantic-status-markers-in-user-facing-receipts.guide.md) | | AC-ADR-053 | Accepted | Use capability-aware presentation profiles for portable agent receipts | Presenting final concise receipts across human, terminal, chat, CI, redirect, or unknown-host surfaces | reporting, receipts, accessibility, portability, capabilities, token-cost | [Short](ac-adr-053-use-capability-aware-presentation-profiles-for-portable-agent-receipts.short.md) | [Long, canonical](ac-adr-053-use-capability-aware-presentation-profiles-for-portable-agent-receipts.long.md) | [Guide](ac-adr-053-use-capability-aware-presentation-profiles-for-portable-agent-receipts.guide.md) | ## Target repository These entries are adoption candidates. Setup records each as `adopt`, `adapt`, `defer`, or `reject`. ### Governance | ID | Status | Decision | Applies when | Tags | Short | Long | Guide | | ---------- | -------- | ----------------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | AC-ADR-005 | Accepted | Make repository ADRs binding agent guardrails | Installing or refreshing ADR governance | adr, agent-instructions, supersession | [Short](ac-adr-005-make-repository-adrs-binding-agent-guardrails.short.md) | [Long, canonical](ac-adr-005-make-repository-adrs-binding-agent-guardrails.long.md) | [Guide](ac-adr-005-make-repository-adrs-binding-agent-guardrails.guide.md) | | AC-ADR-065 | Accepted | Require qualified Jev host advice after repository adoption | A repository requires qualified Jev advice on authorized agent hosts | jev, adoption, authorization, eligibility, qualification | [Short](ac-adr-065-require-qualified-jev-host-advice-after-repository-adoption.short.md) | [Long, canonical](ac-adr-065-require-qualified-jev-host-advice-after-repository-adoption.long.md) | [Guide](ac-adr-065-require-qualified-jev-host-advice-after-repository-adoption.guide.md) | | AC-ADR-027 | Accepted | Use the open Agent Skills specification | Creating, validating, or publishing public Agent Skills | agent-skills, specification, portability | [Short](ac-adr-027-use-the-open-agent-skills-specification.short.md) | [Long, canonical](ac-adr-027-use-the-open-agent-skills-specification.long.md) | [Guide](ac-adr-027-use-the-open-agent-skills-specification.guide.md) | | AC-ADR-028 | Accepted | Keep candidates outside the promoted public catalog | Creating a candidate or deciding public catalog membership | catalog, incubation, discovery, promotion | [Short](ac-adr-028-keep-candidates-outside-the-promoted-public-catalog.short.md) | [Long, canonical](ac-adr-028-keep-candidates-outside-the-promoted-public-catalog.long.md) | [Guide](ac-adr-028-keep-candidates-outside-the-promoted-public-catalog.guide.md) | | AC-ADR-030 | Accepted | License public skill repositories under Apache-2.0 | Establishing or changing a public skill repository license | license, apache-2-0, patent, attribution | [Short](ac-adr-030-license-public-skill-repositories-under-apache-2-0.short.md) | [Long, canonical](ac-adr-030-license-public-skill-repositories-under-apache-2-0.long.md) | [Guide](ac-adr-030-license-public-skill-repositories-under-apache-2-0.guide.md) | | AC-ADR-035 | Accepted | Classify skill portability before choosing variants | Naming, placing, splitting, or adding host metadata to a skill | portability, host-variants, metadata | [Short](ac-adr-035-classify-skill-portability-before-choosing-host-variants.short.md) | [Long, canonical](ac-adr-035-classify-skill-portability-before-choosing-host-variants.long.md) | [Guide](ac-adr-035-classify-skill-portability-before-choosing-host-variants.guide.md) | ### Repository architecture | ID | Status | Decision | Applies when | Tags | Short | Long | Guide | | ---------- | -------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | AC-ADR-006 | Accepted | Assign workspace ownership and source roles | Adding, moving, or sharing source, tests, docs, generated, or infrastructure files | workspace, source-roles, ownership | [Short](ac-adr-006-assign-workspace-ownership-and-source-roles.short.md) | [Long, canonical](ac-adr-006-assign-workspace-ownership-and-source-roles.long.md) | [Guide](ac-adr-006-assign-workspace-ownership-and-source-roles.guide.md) | | AC-ADR-007 | Accepted | Enforce runtime-safe module and public package boundaries | Code crosses browser/server, app/package, shared/private, or public API boundaries | modules, packages, server-only, exports | [Short](ac-adr-007-enforce-runtime-safe-module-and-public-package-boundaries.short.md) | [Long, canonical](ac-adr-007-enforce-runtime-safe-module-and-public-package-boundaries.long.md) | [Guide](ac-adr-007-enforce-runtime-safe-module-and-public-package-boundaries.guide.md) | | AC-ADR-032 | Accepted | Keep maintainer-local helper state out of public repos | Installing or recording local helper skills, links, caches, or locks | local-state, helpers, lockfiles | [Short](ac-adr-032-keep-maintainer-local-helper-state-out-of-public-repositories.short.md) | [Long, canonical](ac-adr-032-keep-maintainer-local-helper-state-out-of-public-repositories.long.md) | [Guide](ac-adr-032-keep-maintainer-local-helper-state-out-of-public-repositories.guide.md) | | AC-ADR-037 | Accepted | Preserve target contracts and gate gateway extraction | Routing across hosts, splitting variants, or extracting a gateway | target-contracts, gateways, isolation | [Short](ac-adr-037-preserve-target-contracts-and-gate-gateway-extraction.short.md) | [Long, canonical](ac-adr-037-preserve-target-contracts-and-gate-gateway-extraction.long.md) | [Guide](ac-adr-037-preserve-target-contracts-and-gate-gateway-extraction.guide.md) | | AC-ADR-054 | Accepted | Isolate agent writes in external Git worktrees | An agent may modify repository state, whether manually, through delegation, or through an orchestrator | agents, git, multi-agent, worktree, workspace | [Short](ac-adr-054-isolate-agent-writes-in-external-git-worktrees.short.md) | [Long, canonical](ac-adr-054-isolate-agent-writes-in-external-git-worktrees.long.md) | [Guide](ac-adr-054-isolate-agent-writes-in-external-git-worktrees.guide.md) | ### Frontend | ID | Status | Decision | Applies when | Tags | Short | Long | Guide | | ---------- | -------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | AC-ADR-008 | Accepted | Compose Next.js routes, rendering, and component responsibilities | Creating or refactoring a substantial App Router screen or entrypoint | nextjs, rsc, client-boundary, rendering | [Short](ac-adr-008-compose-nextjs-routes-rendering-and-component-responsibilities.short.md) | [Long, canonical](ac-adr-008-compose-nextjs-routes-rendering-and-component-responsibilities.long.md) | [Guide](ac-adr-008-compose-nextjs-routes-rendering-and-component-responsibilities.guide.md) | | AC-ADR-009 | Accepted | Choose read, query, caching, and freshness boundaries | Data is read by Server Components, browser clients, external clients, or realtime consumers | reads, cache, tanstack-query, realtime | [Short](ac-adr-009-choose-read-query-caching-and-freshness-boundaries.short.md) | [Long, canonical](ac-adr-009-choose-read-query-caching-and-freshness-boundaries.long.md) | [Guide](ac-adr-009-choose-read-query-caching-and-freshness-boundaries.guide.md) | | AC-ADR-010 | Accepted | Protect writes behind validated command boundaries | Browser interaction, webhook, external client, or integration mutates trusted state | writes, server-actions, authorization, validation | [Short](ac-adr-010-protect-writes-behind-validated-command-boundaries.short.md) | [Long, canonical](ac-adr-010-protect-writes-behind-validated-command-boundaries.long.md) | [Guide](ac-adr-010-protect-writes-behind-validated-command-boundaries.guide.md) | | AC-ADR-015 | Accepted | Select frontend capability libraries by product need | Choosing validation, dates, forms, URL state, i18n, UI, animation, charts, or email | ui, forms, i18n, dates, visualization | [Short](ac-adr-015-select-frontend-capability-libraries-by-product-need.short.md) | [Long, canonical](ac-adr-015-select-frontend-capability-libraries-by-product-need.long.md) | [Guide](ac-adr-015-select-frontend-capability-libraries-by-product-need.guide.md) | | AC-ADR-024 | Accepted | Meet an explicit accessibility baseline with automated and manual proof | Building or changing user-facing UI or interaction | accessibility, wcag, keyboard, assistive-technology | [Short](ac-adr-024-meet-an-explicit-accessibility-baseline-with-automated-and-manual-proof.short.md) | [Long, canonical](ac-adr-024-meet-an-explicit-accessibility-baseline-with-automated-and-manual-proof.long.md) | [Guide](ac-adr-024-meet-an-explicit-accessibility-baseline-with-automated-and-manual-proof.guide.md) | ### Backend | ID | Status | Decision | Applies when | Tags | Short | Long | Guide | | ---------- | -------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | AC-ADR-011 | Accepted | Compose long-running backend runtimes and lifecycles explicitly | Creating a service, worker, HTTP process, route plugin, registry, or DI boundary | backend, lifecycle, composition, health | [Short](ac-adr-011-compose-long-running-backend-runtimes-and-lifecycles-explicitly.short.md) | [Long, canonical](ac-adr-011-compose-long-running-backend-runtimes-and-lifecycles-explicitly.long.md) | [Guide](ac-adr-011-compose-long-running-backend-runtimes-and-lifecycles-explicitly.guide.md) | ### Runtime and platform | ID | Status | Decision | Applies when | Tags | Short | Long | Guide | | ---------- | -------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | AC-ADR-012 | Accepted | Resolve environment and configuration at deployable boundaries | A deployable reads environment, secrets, URLs, ports, or runtime configuration | env, config, bootstrap, secrets | [Short](ac-adr-012-resolve-environment-and-configuration-at-deployable-boundaries.short.md) | [Long, canonical](ac-adr-012-resolve-environment-and-configuration-at-deployable-boundaries.long.md) | [Guide](ac-adr-012-resolve-environment-and-configuration-at-deployable-boundaries.guide.md) | | AC-ADR-014 | Accepted | Select application runtimes, deployment hosts, and additional targets by evidence | Choosing Next.js, Bun/Node, Elysia, hosting, mobile, or desktop delivery | runtime, hosting, mobile, desktop | [Short](ac-adr-014-select-application-runtimes-deployment-hosts-and-additional-targets-by-evidence.short.md) | [Long, canonical](ac-adr-014-select-application-runtimes-deployment-hosts-and-additional-targets-by-evidence.long.md) | [Guide](ac-adr-014-select-application-runtimes-deployment-hosts-and-additional-targets-by-evidence.guide.md) | | AC-ADR-016 | Accepted | Select AI model, streaming, UI, and agent capabilities deliberately | Adding model access, streaming, tools, AI UI, or agent orchestration | ai, models, tools, streaming, agents | [Short](ac-adr-016-select-ai-model-streaming-ui-and-agent-capabilities-deliberately.short.md) | [Long, canonical](ac-adr-016-select-ai-model-streaming-ui-and-agent-capabilities-deliberately.long.md) | [Guide](ac-adr-016-select-ai-model-streaming-ui-and-agent-capabilities-deliberately.guide.md) | | AC-ADR-023 | Accepted | Operate services with observable health, readiness, failure, and cleanup | Introducing a runtime, job, queue, subscription, integration, or critical dependency | observability, resilience, health, readiness | [Short](ac-adr-023-operate-services-with-observable-health-readiness-failure-and-cleanup.short.md) | [Long, canonical](ac-adr-023-operate-services-with-observable-health-readiness-failure-and-cleanup.long.md) | [Guide](ac-adr-023-operate-services-with-observable-health-readiness-failure-and-cleanup.guide.md) | | AC-ADR-038 | Accepted | Gate optional capabilities and tool side effects | Calling providers, installing tools, launching browsers, or using higher-side-effect paths | providers, tools, approval, fallback | [Short](ac-adr-038-gate-optional-capabilities-and-tool-side-effects.short.md) | [Long, canonical](ac-adr-038-gate-optional-capabilities-and-tool-side-effects.long.md) | [Guide](ac-adr-038-gate-optional-capabilities-and-tool-side-effects.guide.md) | ### Security and data | ID | Status | Decision | Applies when | Tags | Short | Long | Guide | | ---------- | -------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- | | AC-ADR-017 | Accepted | Select relational, cache, queue, and realtime capabilities by data requirements | Choosing persistence, ORM, cache, queue, rate limiting, or realtime transport | database, cache, queue, realtime | [Short](ac-adr-017-select-relational-cache-queue-and-realtime-capabilities-by-data-requirements.short.md) | [Long, canonical](ac-adr-017-select-relational-cache-queue-and-realtime-capabilities-by-data-requirements.long.md) | [Guide](ac-adr-017-select-relational-cache-queue-and-realtime-capabilities-by-data-requirements.guide.md) | | AC-ADR-019 | Accepted | Apply security and privacy controls at every trust boundary | Processing identity, credentials, untrusted input, logs, errors, or third-party access | security, privacy, authorization, least-privilege | [Short](ac-adr-019-apply-security-and-privacy-controls-at-every-trust-boundary.short.md) | [Long, canonical](ac-adr-019-apply-security-and-privacy-controls-at-every-trust-boundary.long.md) | [Guide](ac-adr-019-apply-security-and-privacy-controls-at-every-trust-boundary.guide.md) | | AC-ADR-020 | Accepted | Define data ownership, tenancy, retention, and deletion before access paths | Introducing persisted personal, tenant, device, generated, or synchronized data | data-ownership, tenancy, retention, deletion | [Short](ac-adr-020-define-data-ownership-tenancy-retention-and-deletion-before-access-paths.short.md) | [Long, canonical](ac-adr-020-define-data-ownership-tenancy-retention-and-deletion-before-access-paths.long.md) | [Guide](ac-adr-020-define-data-ownership-tenancy-retention-and-deletion-before-access-paths.guide.md) | ### Stack and tooling | ID | Status | Decision | Applies when | Tags | Short | Long | Guide | | ---------- | -------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | AC-ADR-013 | Accepted | Own language, package, build, lint, and supply-chain tooling explicitly | Establishing or changing compiler, package manager, workspace, orchestration, lint, format, or dependency trust | typescript, pnpm, oxc, turbo, supply-chain | [Short](ac-adr-013-own-language-package-build-lint-and-supply-chain-tooling-explicitly.short.md) | [Long, canonical](ac-adr-013-own-language-package-build-lint-and-supply-chain-tooling-explicitly.long.md) | [Guide](ac-adr-013-own-language-package-build-lint-and-supply-chain-tooling-explicitly.guide.md) | | AC-ADR-033 | Accepted | Choose portable dependency-light skill helpers | Adding or replacing an executable helper inside a public skill | helpers, nodejs, python, portability | [Short](ac-adr-033-choose-portable-dependency-light-skill-helpers.short.md) | [Long, canonical](ac-adr-033-choose-portable-dependency-light-skill-helpers.long.md) | [Guide](ac-adr-033-choose-portable-dependency-light-skill-helpers.guide.md) | | AC-ADR-040 | Accepted | Offer an opinionated stack profile for new public skill repositories | Setting up a new public skill repository with a concrete maintained baseline | stack-profile, typescript-7, pnpm, oxc | [Short](ac-adr-040-offer-an-opinionated-stack-profile-for-new-public-skill-repositories.short.md) | [Long, canonical](ac-adr-040-offer-an-opinionated-stack-profile-for-new-public-skill-repositories.long.md) | [Guide](ac-adr-040-offer-an-opinionated-stack-profile-for-new-public-skill-repositories.guide.md) | | AC-ADR-058 | Accepted | Use pnpm for package management and Bun for execution | Establishing or changing JavaScript/TypeScript package ownership, execution, build, test, or deployment tooling | bun, pnpm, runtime, scripts, deployment | [Short](ac-adr-058-use-pnpm-for-package-management-and-bun-for-execution.short.md) | [Long, canonical](ac-adr-058-use-pnpm-for-package-management-and-bun-for-execution.long.md) | [Guide](ac-adr-058-use-pnpm-for-package-management-and-bun-for-execution.guide.md) | | AC-ADR-063 | Accepted | Enforce Tailwind Design-System Contracts with shadcn lint | Adopting or changing design-system lint enforcement in compatible Tailwind v4 source | tailwind, shadcn, design-system, lint, components | [Short](ac-adr-063-enforce-tailwind-design-system-contracts-with-shadcn-lint.short.md) | [Long, canonical](ac-adr-063-enforce-tailwind-design-system-contracts-with-shadcn-lint.long.md) | [Guide](ac-adr-063-enforce-tailwind-design-system-contracts-with-shadcn-lint.guide.md) | | AC-ADR-066 | Accepted | Use Portless for Local Development Endpoints | Establishing, reviewing or changing local HTTP/WebSocket development endpoints, including parallel worktrees | portless, local-development, https, endpoints, worktrees | [Short](ac-adr-066-use-portless-for-local-development-endpoints.short.md) | [Long, canonical](ac-adr-066-use-portless-for-local-development-endpoints.long.md) | [Guide](ac-adr-066-use-portless-for-local-development-endpoints.guide.md) | ### Quality and delivery | ID | Status | Decision | Applies when | Tags | Short | Long | Guide | | ---------- | ---------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | AC-ADR-018 | Accepted | Validate behavior at the owning boundary and promote enforcement gradually | Implementing, refactoring, reviewing, or automating a documented rule | testing, validation, enforcement, evidence | [Short](ac-adr-018-validate-behavior-at-the-owning-boundary-and-promote-enforcement-gradually.short.md) | [Long, canonical](ac-adr-018-validate-behavior-at-the-owning-boundary-and-promote-enforcement-gradually.long.md) | [Guide](ac-adr-018-validate-behavior-at-the-owning-boundary-and-promote-enforcement-gradually.guide.md) | | AC-ADR-021 | Accepted | Preserve compatibility through explicit migrations and deprecation windows | Changing schemas, APIs, events, exports, runtimes, stored data, or accepted ADR contracts | migration, compatibility, deprecation, schema | [Short](ac-adr-021-preserve-compatibility-through-explicit-migrations-and-deprecation-windows.short.md) | [Long, canonical](ac-adr-021-preserve-compatibility-through-explicit-migrations-and-deprecation-windows.long.md) | [Guide](ac-adr-021-preserve-compatibility-through-explicit-migrations-and-deprecation-windows.guide.md) | | AC-ADR-022 | Accepted | Deliver reversible slices with explicit rollback and promotion gates | Work spans phases, environments, release boundaries, or irreversible operations | delivery, rollback, rollout, approval | [Short](ac-adr-022-deliver-reversible-slices-with-explicit-rollback-and-promotion-gates.short.md) | [Long, canonical](ac-adr-022-deliver-reversible-slices-with-explicit-rollback-and-promotion-gates.long.md) | [Guide](ac-adr-022-deliver-reversible-slices-with-explicit-rollback-and-promotion-gates.guide.md) | | AC-ADR-025 | Accepted | Set measurable performance budgets and optimize from evidence | A change affects rendering, bundles, network, cache, database, jobs, or user-perceived latency | performance, budgets, lab, field-data | [Short](ac-adr-025-set-measurable-performance-budgets-and-optimize-from-evidence.short.md) | [Long, canonical](ac-adr-025-set-measurable-performance-budgets-and-optimize-from-evidence.long.md) | [Guide](ac-adr-025-set-measurable-performance-budgets-and-optimize-from-evidence.guide.md) | | AC-ADR-029 | Accepted | Promote skills through an evidence and maintenance gate | Evaluating whether a candidate is ready for the promoted public catalog | promotion, evals, activation, maintenance | [Short](ac-adr-029-promote-skills-through-an-evidence-and-maintenance-gate.short.md) | [Long, canonical](ac-adr-029-promote-skills-through-an-evidence-and-maintenance-gate.long.md) | [Guide](ac-adr-029-promote-skills-through-an-evidence-and-maintenance-gate.guide.md) | | AC-ADR-031 | Accepted | Keep skill evaluation evidence outside the runtime payload | Adding eval cases, rubrics, transcripts, run evidence, or self-test fixtures | evals, runtime-payload, evidence, context | [Short](ac-adr-031-keep-skill-evaluation-evidence-outside-the-runtime-payload.short.md) | [Long, canonical](ac-adr-031-keep-skill-evaluation-evidence-outside-the-runtime-payload.long.md) | [Guide](ac-adr-031-keep-skill-evaluation-evidence-outside-the-runtime-payload.guide.md) | | AC-ADR-034 | Superseded | Keep release metadata coherent with public catalog changes | Historical same-change release metadata preparation before generated release aggregation | release, changelog, versioning, pull-request | [Short](ac-adr-034-keep-release-metadata-coherent-with-public-catalog-changes.short.md) | [Long, canonical](ac-adr-034-keep-release-metadata-coherent-with-public-catalog-changes.long.md) | [Guide](ac-adr-034-keep-release-metadata-coherent-with-public-catalog-changes.guide.md) | | AC-ADR-041 | Accepted | Publish public skills through GitHub and the open Skills CLI | Choosing or validating public source, discovery, installation, and release | github, skills-cli, publishing, installation | [Short](ac-adr-041-publish-public-skills-through-github-and-the-open-skills-cli.short.md) | [Long, canonical](ac-adr-041-publish-public-skills-through-github-and-the-open-skills-cli.long.md) | [Guide](ac-adr-041-publish-public-skills-through-github-and-the-open-skills-cli.guide.md) | | AC-ADR-042 | Superseded | Calibrate validation to change risk and reuse fresh evidence | Historical proportional validation before disjoint low/moderate risk criteria | testing, validation-cadence, evidence-reuse | [Short](ac-adr-042-calibrate-validation-to-change-risk-and-reuse-fresh-evidence.short.md) | [Long, canonical](ac-adr-042-calibrate-validation-to-change-risk-and-reuse-fresh-evidence.long.md) | [Guide](ac-adr-042-calibrate-validation-to-change-risk-and-reuse-fresh-evidence.guide.md) | | AC-ADR-047 | Superseded | Separate low and moderate validation risk with explicit triggers | Historical disjoint risk classification before observation-environment correction | testing, validation-cadence, evidence-reuse | [Short](ac-adr-047-separate-low-and-moderate-validation-risk-with-explicit-triggers.short.md) | [Long, canonical](ac-adr-047-separate-low-and-moderate-validation-risk-with-explicit-triggers.long.md) | [Guide](ac-adr-047-separate-low-and-moderate-validation-risk-with-explicit-triggers.guide.md) | | AC-ADR-049 | Accepted | Distinguish change risk from representative environment observation | Implementing, delegating, resuming, or validating a bounded change | testing, validation-cadence, evidence-reuse | [Short](ac-adr-049-distinguish-change-risk-from-representative-environment-observation.short.md) | [Long, canonical](ac-adr-049-distinguish-change-risk-from-representative-environment-observation.long.md) | [Guide](ac-adr-049-distinguish-change-risk-from-representative-environment-observation.guide.md) | | AC-ADR-055 | Accepted | Separate change impact from generated release publication | A repository separates generated preparation from protected publication | release, changelog, versioning, approval | [Short](ac-adr-055-separate-change-impact-from-generated-release-publication.short.md) | [Long, canonical](ac-adr-055-separate-change-impact-from-generated-release-publication.long.md) | [Guide](ac-adr-055-separate-change-impact-from-generated-release-publication.guide.md) | | AC-ADR-056 | Accepted | Preserve release candidates through verified protected history | A validated release waits across protected-branch advancement | release, recovery, approval, protected-branch | [Short](ac-adr-056-preserve-release-candidates-through-verified-protected-history.short.md) | [Long, canonical](ac-adr-056-preserve-release-candidates-through-verified-protected-history.long.md) | [Guide](ac-adr-056-preserve-release-candidates-through-verified-protected-history.guide.md) | | AC-ADR-057 | Accepted | Separate metadata repair from installable artifact provenance | A mutable published release is missing exact metadata or an installable artifact | release, recovery, artifacts, attestations | [Short](ac-adr-057-separate-metadata-repair-from-installable-artifact-provenance.short.md) | [Long, canonical](ac-adr-057-separate-metadata-repair-from-installable-artifact-provenance.long.md) | [Guide](ac-adr-057-separate-metadata-repair-from-installable-artifact-provenance.guide.md) | | AC-ADR-059 | Accepted | Own repository validation through discoverable framework tests | Adding or migrating repository-maintenance checks that assert configuration, source, documentation, generated-output or release contracts | testing, validation, ownership, discoverability, migration | [Short](ac-adr-059-own-repository-validation-through-discoverable-framework-tests.short.md) | [Long, canonical](ac-adr-059-own-repository-validation-through-discoverable-framework-tests.long.md) | [Guide](ac-adr-059-own-repository-validation-through-discoverable-framework-tests.guide.md) | | AC-ADR-060 | Accepted | Isolate test execution by effects and runtime contracts | Tests share mutable resources, spawn processes, access external systems or exercise runtime-specific behavior | testing, isolation, runtime-evidence, concurrency, hermeticity | [Short](ac-adr-060-isolate-test-execution-by-effects-and-runtime-contracts.short.md) | [Long, canonical](ac-adr-060-isolate-test-execution-by-effects-and-runtime-contracts.long.md) | [Guide](ac-adr-060-isolate-test-execution-by-effects-and-runtime-contracts.guide.md) | | AC-ADR-061 | Accepted | Shard tests as complete fail-closed evidence sets | A required test obligation is distributed across workers, machines, platforms or independently reported jobs | testing, sharding, ci, evidence-integrity, performance | [Short](ac-adr-061-shard-tests-as-complete-fail-closed-evidence-sets.short.md) | [Long, canonical](ac-adr-061-shard-tests-as-complete-fail-closed-evidence-sets.long.md) | [Guide](ac-adr-061-shard-tests-as-complete-fail-closed-evidence-sets.guide.md) | | AC-ADR-062 | Accepted | Cache test transforms without reusing correctness | Persisting or restoring transformed test modules to reduce repeated validation work | testing, transform-cache, invalidation, trust-boundaries, performance | [Short](ac-adr-062-cache-test-transforms-without-reusing-correctness.short.md) | [Long, canonical](ac-adr-062-cache-test-transforms-without-reusing-correctness.long.md) | [Guide](ac-adr-062-cache-test-transforms-without-reusing-correctness.guide.md) | ## Concern views | Concern | Start with | | ------------------------------ | -------------------------------------------------------------------------- | | Testing and validation | AC-ADR-049, then AC-ADR-018 and the owning boundary ADR | | Repository test ownership | AC-ADR-059, then AC-ADR-018/049 and AC-ADR-058 when applicable | | Test runtime and state effects | AC-ADR-060, then the applicable runtime and owning boundary ADRs | | Distributed test proof | AC-ADR-061, then AC-ADR-025/049 | | Transform cache evaluation | AC-ADR-062, then AC-ADR-025/049 | | User-facing evidence receipts | AC-ADR-053, then AC-ADR-050, AC-ADR-004, and AC-ADR-049 | | Accessibility | AC-ADR-024 plus AC-ADR-008 or AC-ADR-015 | | Performance | AC-ADR-025 plus AC-ADR-008, AC-ADR-009, AC-ADR-017, or AC-ADR-023 | | Observability and resilience | AC-ADR-023 plus AC-ADR-004 and AC-ADR-018 | | Migration and compatibility | AC-ADR-021 plus AC-ADR-020 and AC-ADR-022 | | AI | AC-ADR-016 plus AC-ADR-019, AC-ADR-020, AC-ADR-023, and AC-ADR-025 | | Collaboration | AC-ADR-003 plus AC-ADR-064, AC-ADR-046, AC-ADR-036, and AC-ADR-004 | | Skill portability | AC-ADR-035, then AC-ADR-036, AC-ADR-037, or AC-ADR-038 | | Internal/public ADR routing | AC-ADR-051, then AC-ADR-001 and AC-ADR-044 | | Host-neutral persistence | AC-ADR-052, then AC-ADR-064, AC-ADR-036, and AC-ADR-004 | | Public skill reuse | AC-ADR-039 plus target authority and AC-ADR-004 | | New public skill repository | AC-ADR-040, then its linked component provider ADRs | | JavaScript/TypeScript tooling | AC-ADR-058, then AC-ADR-013, AC-ADR-014, and AC-ADR-018 | | Local development endpoints | AC-ADR-066, then AC-ADR-013/014/019/054 and AC-ADR-058 when applicable | | Tailwind design-system lint | AC-ADR-063, then AC-ADR-013/018 and AC-ADR-058 when applicable | | Public skill publication | AC-ADR-055, AC-ADR-056, AC-ADR-057, AC-ADR-041, AC-ADR-028, and AC-ADR-029 | | ADR decision lineage | AC-ADR-044 plus AC-ADR-001 and AC-ADR-004 | | Adopted Jev host advice | AC-ADR-065, then AC-ADR-019, AC-ADR-038, and local adoption evidence |
SHA-256: 56e4732eac9398e9eb571fa40cabc41faf5ef34bdacddecfe532d0a053c438bd