skills/ai-software-architect/assets/artifact-authoring-bundle.md

<!--
SPDX-FileCopyrightText: 2026 Leonardo Muffato (AUTOSOFT Engineering - www.autosoft-engineering.de)
SPDX-License-Identifier: MIT
Generated by adapters/codex/build_plugin.py; do not edit this packaged file.
-->

# Artifact Authoring Bundle

Load this generated resource once during Codex `record_and_handoff`. The separately maintained canonical sources below remain authoritative.

## Required output paths

Submit exactly one complete candidate at each required path:

- `.ai-architect/project-context.md`
- `.ai-architect/architecture-contract.yaml`
- `.ai-architect/implementation-plan.md`
- `.ai-architect/decisions/ADR-NNN[-slug].md`

Do not rename `implementation-plan.md` to coding-handoff, handoff, plan, or any other variant. The host adapter rejects alternate paths.

Keep the bundle proportionate to the evidence. For a repository completely covered by one small snapshot, use concise scalar values, one to three evidence-backed list items per optional field, and avoid repeating the full option comparison across artifacts. Target no more than 12,000 combined UTF-8 characters unless the required schema or material project complexity needs more; never omit required fields merely to meet that target.
ADR `considered_option_ids` entries and `selected_option_id` contain only plain `OPT-NNN` identifiers. Put option names and descriptions in their dedicated prose fields; never append labels to an option ID.

---

## ADR authoring rules

<!-- canonical-source: shared/skills/create-architecture-decisions/references/adr-authoring.md -->

<!--
SPDX-FileCopyrightText: 2026 Leonardo Muffato (AUTOSOFT Engineering - www.autosoft-engineering.de)
SPDX-License-Identifier: MIT
-->

# ADR Authoring

Record one material decision per ADR. State the context and forces that existed when deciding, enumerate credible options by stable identifiers, name the selected option, and capture positive and negative consequences without promotional language.

Use `proposed` before approval and `accepted` only after explicit approval. Never edit historical meaning invisibly: supersede an accepted decision with a new ADR and link both records. Make validation criteria observable. Keep confidential values and source excerpts out of the record.

The file begins with safe YAML frontmatter conforming to `ArchitectureDecisionArtifact`. The filename starts with the matching `ADR-NNN`; any slug uses lowercase ASCII letters, digits, and single hyphens. The Markdown body is a deterministic rendering of the same fields.

---

## ADR template

<!-- canonical-source: shared/skills/create-architecture-decisions/assets/adr-template.md -->

<!--
SPDX-FileCopyrightText: 2026 Leonardo Muffato (AUTOSOFT Engineering - www.autosoft-engineering.de)
SPDX-License-Identifier: MIT
Remove this source-template notice from generated user artifacts.
-->
---
schema_version: 1.0.0
revision: 1
decision:
  id: ADR-001
  title: Replace with approved decision title
  status: proposed
  context: Replace with decision context
  drivers:
    - Replace with a decision driver
  considered_option_ids:
    - OPT-001
  selected_option_id: null
  decision: Replace with the proposed decision
  positive_consequences: []
  negative_consequences: []
  assumptions: []
  validation_criteria:
    - Replace with an observable criterion
  supersedes: []
---

# ADR-001: Replace with approved decision title

Render the validated decision fields here without changing their meaning.

---

## Architecture contract example

<!-- canonical-source: shared/skills/create-architecture-decisions/assets/architecture-contract.example.yaml -->

# SPDX-FileCopyrightText: 2026 Leonardo Muffato (AUTOSOFT Engineering - www.autosoft-engineering.de)
# SPDX-License-Identifier: MIT
# Remove this source-template notice from generated user artifacts.

schema_version: 1.0.0
revision: 1
scope: notification-subsystem
architecture_style: modular-monolith-with-ports-and-adapters
quality_attributes:
  - name: reliable-delivery
    priority: 1
    rationale: Accepted notifications must not be silently lost.
    measurable_signal: Delivery outcomes are recorded for every accepted notification.
components:
  - id: domain
    responsibility: Own notification policy
    owns_data: []
    public_interfaces:
      - submit-notification
  - id: delivery-adapter
    responsibility: Deliver approved notifications through an external provider
    owns_data: []
    public_interfaces:
      - deliver-notification
external_boundaries:
  - id: notification-provider
    responsibility: Accept notification delivery requests
dependency_rules:
  - source: domain
    target: delivery-adapter
    policy: allow-via-interface
    via_interface: deliver-notification
    rationale: Domain policy must not depend on provider implementation details.
  - source: delivery-adapter
    target: notification-provider
    policy: allow
    rationale: The delivery adapter may call its configured external provider directly.
  - source: domain
    target: notification-provider
    policy: deny
    rationale: Domain policy must never depend directly on an external provider.
# Dependency policy rules:
# - allow-via-interface requires via_interface.
# - allow and deny must omit via_interface entirely.
required_practices: []
prohibited_practices: []
decision_ids: []
unresolved_questions:
  - id: Q-001
    question: Which delivery latency objective is required?
    decision_impact: The answer determines retry and timeout constraints.
    critical: false
    answer: null

---

## Implementation plan template

<!-- canonical-source: shared/skills/prepare-coding-handoff/assets/implementation-plan-template.md -->

<!--
SPDX-FileCopyrightText: 2026 Leonardo Muffato (AUTOSOFT Engineering - www.autosoft-engineering.de)
SPDX-License-Identifier: MIT
Remove this source-template notice from generated user artifacts.
-->

# Architecture-Driven Implementation Plan

## Accepted decisions

List governing ADRs and contract revision.

## Milestones

For each milestone, state outcome, files or components in scope, constraints, dependencies, and verification.

## Cross-cutting constraints

List security, data, integration, observability, and operational requirements.

## Explicit non-goals

List work intentionally excluded.

## Unresolved questions

List remaining questions and the milestone they block.