ai-delivery-workflow 0.2.2

package/skills/ai-delivery-close-version/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: ai-delivery-close-version
+description: Close an independently verified planned version without publishing it by freezing its candidate, recording cumulative lineage, creating an immutable version-ready tag, advancing the product development line, marking artifacts release-ready, and archiving closed task context. Use after iteration candidate verification passes or when resuming an interrupted version-closeout node.
+---
+
+# Close Planned Version
+
+Finish one planned version and stop before release. Never start a release from this skill.
+
+## Preflight
+
+1. Recover or initialize the `12-version-closeout` task through `$ai-delivery-checkpoint-task`.
+2. Run `node .workflow/tools/state/state.mjs verify`.
+3. Require a passing immutable candidate, closed version tasks, complete requirement/test/material traceability, and no unresolved blocking defect.
+4. Read the preceding version lineage and Git policy. Require the candidate to descend from the current `line/<product-id>` head, except for the first version.
+
+## Close The Version
+
+1. Read `.workflow/config/workspace.yaml`; verify the candidate in the configured code repository and populate `repo_id`, `code_commit`, `source_path`, and SHA-256.
+2. Freeze the candidate commit and create code `version-ready/<version-id>/rN`. Never move or replace an existing Tag; increment `rN` only for a newly verified replacement candidate.
+3. Fast-forward code `line/<product-id>` to the tagged commit. Never advance code `main` here.
+4. Copy the closeout assets into `.workflow/iterations/<version-id>/12-version-closeout/`, populate the code Tag identity, and compute the final manifest SHA-256.
+5. Register the version materials with the formal state CLI, set the closeout artifact to `release-ready`, and complete `12-version-closeout` with that registered artifact as evidence.
+6. Commit all version workflow materials and create immutable workflow `workflow-ready/<version-id>/rN` at that exact workflow commit. Record the workflow commit, workflow Tag, and manifest checksum in the lineage index without rewriting the tagged manifest.
+7. Verify both Tags and the manifest checksum. Inspect the current workflow revision, then run `state.mjs transition --expected-revision <revision> --event version-closed --iteration-id <version-id> --artifact-id <closeout-artifact-id>` to update the audited cumulative development identity. Never edit `latest_line_version_id` directly.
+8. Run formal state `verify`, archive tasks with `task-state.mjs archive-version --version-status release-ready --candidate-id <candidate-id> --evidence <closeout-artifact-id>`, checkpoint the Git and archive evidence, and finish the task.
+9. Invoke `$ai-delivery-evolve-workflow evaluate --safe-point version --iteration-id <version-id>`. Record trial results and decisions, but never use an Evolution result as release intent.
+
+## Stop Boundary
+
+Report the release-ready version, code Tag, workflow Tag, manifest checksum, cumulative line head, archived task count, and next planned version. Stop and wait for either the next version iteration or an explicit user release request. Do not invoke release orchestration implicitly.
+
+Read [version-closeout-contract.md](references/version-closeout-contract.md) before writing outputs.

package/skills/ai-delivery-close-version/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Close Planned Version"
+  short_description: "Freeze a verified version as release-ready"
+  default_prompt: "Use $ai-delivery-close-version to bind code Tag, workflow Tag, and manifest checksum without publishing."

package/skills/ai-delivery-close-version/assets/line-advance-record.yaml

@@ -0,0 +1,12 @@
+schema_version: 2
+repo_id: "app"
+repository_path: "code"
+product_id: "PRODUCT-001"
+branch: "line/PRODUCT-001"
+previous_head: null
+new_head: "<git-sha>"
+version_id: "VER-0001"
+version_ready_tag: "version-ready/VER-0001/r1"
+fast_forward_verified: true
+actor: "ai:<agent-id>"
+advanced_at: "<RFC3339>"

package/skills/ai-delivery-close-version/assets/version-lineage.yaml

@@ -0,0 +1,12 @@
+schema_version: 2
+product_id: "PRODUCT-001"
+version_id: "VER-0001"
+predecessor_version_id: null
+candidate_id: "CAND-0001"
+repo_id: "app"
+candidate_commit: "<git-sha>"
+version_ready_tag: "version-ready/VER-0001/r1"
+workflow_commit: "<workflow-git-sha>"
+workflow_ready_tag: "workflow-ready/VER-0001/r1"
+artifact_manifest: ".workflow/iterations/VER-0001/12-version-closeout/version-manifest.yaml"
+artifact_sha256: "<sha256>"

package/skills/ai-delivery-close-version/assets/version-manifest.yaml

@@ -0,0 +1,20 @@
+schema_version: 2
+version_id: "VER-0001"
+product_id: "PRODUCT-001"
+predecessor_version_id: null
+status: "release-ready"
+candidate_id: "CAND-0001"
+repository:
+  repo_id: "app"
+  code_commit: "<git-sha>"
+  code_tag: "version-ready/VER-0001/r1"
+  source_path: "code"
+candidate_commit: "<git-sha>"
+candidate_sha256: "<sha256>"
+version_ready_tag: "version-ready/VER-0001/r1"
+workflow_identity_record: ".workflow/delivery/version-lineage.yaml"
+verification_artifact_id: "ART-VERIFY-0001"
+material_index_artifact_id: "ART-MATERIAL-0001"
+task_archive_manifest: ".workflow/control/archives/versions/VER-0001/version-manifest.json"
+standards_baseline_id: "STANDARDS-BASELINE-001"
+closed_at: "<RFC3339>"

package/skills/ai-delivery-close-version/references/version-closeout-contract.md

@@ -0,0 +1,20 @@
+# Version Closeout Contract
+
+## Required inputs
+
+- planned version ID, product ID, predecessor version, and iteration plan;
+- immutable candidate ID, commit, artifact digest, and passing verification decision;
+- complete closed-task summary and unresolved-risk statement;
+- current `line/<product-id>` head and applicable standards baseline.
+
+## Required outputs
+
+`version-manifest.yaml` binds the version to its candidate, verification, task archive, product/architecture/prototype/test baselines, and material index. `version-lineage.yaml` records exactly one predecessor and the cumulative ordered ancestry. `line-advance-record.yaml` records the old/new line heads, immutable tag, actor, and checks.
+
+All outputs live under `.workflow/iterations/<version-id>/12-version-closeout/`, use stable IDs, and are registered through the formal state CLI. A version is `release-ready` only when every checksum resolves and the line fast-forward is proven.
+
+After the `release-ready` closeout artifact is registered, `12-version-closeout` is completed, and both immutable Tags are verified, run the formal `version-closed` transition with that artifact ID. This audited event is the only writer of `workflow-state.yaml.latest_line_version_id`. Then archive version tasks to `.workflow/control/archives/versions/<version-id>/` and verify that active task/checkpoint shards were removed. The task archive is a separate checkpoint operation and does not replace this formal transition.
+
+## Failure rules
+
+Block closeout for active tasks, mutable candidates, failed verification, missing materials, Git divergence, an existing tag resolving to another commit, or a candidate that does not include a synchronized production hotfix. Mark affected candidates `stale`; never edit a previously closed version.

package/skills/ai-delivery-define-product/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: ai-delivery-define-product
+description: Discover and define a product through a guided interview, then produce versioned discovery and product baselines. Use for a new product idea, a material feature request, unclear business requirements, product scope changes, terminal/channel decisions, product terminology changes, or when downstream work reports an ambiguous requirement.
+---
+
+# Define Product
+
+Turn an initial idea into two human-approved baselines without inventing unresolved business decisions.
+
+## Artifact Location
+
+Write every workflow document produced by this skill under project `.workflow/`. Place version-scoped node outputs in `.workflow/iterations/<iteration-id>/<node-id>/` and approved reusable product baselines in `.workflow/product/`. Do not relocate source code, automated test source, repository configuration, or non-document build artifacts.
+
+## Task State
+
+1. Invoke `$ai-delivery-checkpoint-task` before preflight to recover or initialize the task snapshot.
+2. Checkpoint after every meaningful artifact, gate, validation, merge, deployment action, or other external milestone, and before compaction or interruption.
+3. Before returning, finish the snapshot as `completed`, `blocked`, `failed`, or `interrupted`, with actual outputs, evidence, blockers, and one idempotent next action. A Hook event alone never proves completion.
+4. When the next discovery decision belongs to the user, persist the exact single question with `--next-action-owner user`, then stop without any further mutation. After the user answers, explicitly transfer ownership to `agent` together with a new idempotent next action before continuing. Never recover or activate a user-owned question merely because a new session begins.
+
+## Preflight
+
+Read the project state, artifact registry, applicable standards, and existing product baseline. For a change, identify the affected terms, terminals, features, stories, and acceptance criteria before editing. In prototype-reconciliation mode also read the complete adjustment log, requirement change set, formal UI confirmations, prototype set, and bidirectional product coverage.
+
+## Run Discovery
+
+1. Interview the business sponsor one decision at a time. Recommend an answer and distinguish facts, assumptions, and proposals.
+2. Define the problem, target users and stakeholders, goals, measurable outcomes, scope, non-scope, constraints, risks, core scenarios, and open questions.
+3. Challenge ambiguous terms and capture the selected business vocabulary in the product manual. Do not perform other DDD activities.
+4. Produce the discovery baseline and run completeness and contradiction checks.
+5. Submit discovery Gate A for human approval. Do not start product definition while Gate A is rejected or incomplete.
+
+## Define The Product
+
+1. Define the product specification, capability structure, business flows, user stories, acceptance criteria, non-functional requirements, and business priority.
+2. Create the mandatory channel and terminal scope matrix. Product decides which terminals exist; architecture decides how they are implemented.
+3. Create a two-level feature definition:
+   - a feature catalog for global scope and prioritization;
+   - feature detail records for user goals, preconditions, behavior, outcomes, states, exceptions, and business rules.
+4. Give every terminal, feature, story, and acceptance criterion a stable ID.
+5. Trace features to terminals, stories, acceptance criteria, and goals. Represent many-to-many relationships in dedicated CSV association files.
+6. Keep implementation choices out of product artifacts.
+
+## Submit Gate B
+
+Submit the complete product baseline as one review package while allowing each required artifact to be approved or rejected independently. Gate B passes only when every required item is approved. After any revision, revalidate consistency across the whole package.
+
+Required outputs:
+
+- `product-manual.md`, including the sole approved business glossary;
+- `terminals.csv`;
+- `features.csv` and feature detail Markdown files;
+- `feature-terminals.csv`;
+- `user-stories.csv`;
+- `acceptance-criteria.csv`;
+- traceability association CSV files;
+- `product-baseline.yaml` with versions and item-level approval state.
+
+In prototype-reconciliation mode also produce the terminal requirement change set, bidirectional product coverage, product artifact delta, and `product-prototype-reconciliation.yaml`.
+
+Use the schemas and controlled values in [product-contract.md](references/product-contract.md). Copy starter files from `assets/product-template/` when creating the first baseline.
+
+## Reconcile Confirmed Prototypes
+
+Run this mode only after every visual or interactive prototype member is candidate-approved and its adjustments are terminal.
+
+1. Review every row in `requirement-change-set.csv`; classify it as approved, rejected, or requiring clarification. Do not approve a requirement merely because the prototype implements it.
+2. Verify both directions of `prototype-product-coverage.csv`: every prototype behavior must resolve to an approved feature/story/acceptance criterion, and every visual product behavior must resolve to a prototype element or justified `not-applicable` row.
+3. Apply approved added, modified, retired, or superseded requirements to a new product baseline version. Preserve stable IDs for modifications and retire IDs instead of reusing them.
+4. Re-run Gate B for every changed product artifact and record exact approval evidence. When nothing changes, retain the existing baseline and record an `aligned` no-change decision.
+5. Write `product-prototype-reconciliation.yaml` with the input/output product baseline checksums, prototype/formal-UI checksums, terminal and terminology checks, requirement-change closure, stale artifacts, and required prototype revalidation.
+6. Return rejected prototype behavior to experience for removal. Return an updated baseline to experience, mark affected prototype members stale, and require their staged re-approval. Repeat until the receipt is `status: valid`, `decision: aligned`, and every requirement change is terminal.
+
+## Handoff
+
+Hand an approved Gate B baseline to initial architecture. In prototype-reconciliation mode, hand the exact approved or unchanged product baseline plus a valid aligned reconciliation receipt back to experience design. Downstream stages must return new or conflicting business terms here rather than defining them locally.

package/skills/ai-delivery-define-product/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Define Product"
+  short_description: "Discover requirements and produce an approved product baseline"
+  default_prompt: "Use $ai-delivery-define-product to discover and define the product baseline."

package/skills/ai-delivery-define-product/assets/product-template/acceptance-criteria.csv

@@ -0,0 +1 @@
+acceptance_id,story_id,given,when,then,quality_constraint,status

package/skills/ai-delivery-define-product/assets/product-template/discovery-baseline.md

@@ -0,0 +1,19 @@
+# Discovery Baseline
+
+## Problem And Evidence
+
+## Users And Stakeholders
+
+## Goals And Measurable Outcomes
+
+## Scope And Non-Scope
+
+## Core Scenarios
+
+## Constraints
+
+## Risks And Assumptions
+
+## Open Questions
+
+## Gate A Approval

package/skills/ai-delivery-define-product/assets/product-template/feature-detail.md

@@ -0,0 +1,19 @@
+# Feature Detail: FEATURE-ID
+
+## User Goal And Role
+
+## Terminals
+
+## Trigger And Preconditions
+
+## Main Behavior
+
+## Alternate Behavior
+
+## Outcomes
+
+## States And Exceptions
+
+## Business Rules
+
+## Source And Traceability IDs

package/skills/ai-delivery-define-product/assets/product-template/feature-terminals.csv

@@ -0,0 +1 @@
+feature_id,terminal_id,terminal_behavior,priority

package/skills/ai-delivery-define-product/assets/product-template/features.csv

@@ -0,0 +1 @@
+feature_id,module,feature,subfeature,user_role,user_goal,description,preconditions,outcome,states_and_exceptions,priority,target_release,status

package/skills/ai-delivery-define-product/assets/product-template/product-baseline.yaml

@@ -0,0 +1,8 @@
+artifact_id: PRODUCT-BASELINE-0001
+version: 1.0.0
+status: pending-approval
+gate_a:
+  status: pending
+gate_b_items: []
+standards: []
+inputs: []

package/skills/ai-delivery-define-product/assets/product-template/product-manual.md

@@ -0,0 +1,24 @@
+# Product Manual
+
+## Summary
+
+## Problem
+
+## Users And Stakeholders
+
+## Goals And Success Metrics
+
+## Scope And Non-Scope
+
+## Business Flows
+
+## Product Capabilities
+
+## Business Glossary
+
+| Canonical term | Definition | Excludes | Deprecated synonyms | Example | Related roles or flows | English identifier |
+|---|---|---|---|---|---|---|
+
+## Business Rules
+
+## Risks, Assumptions, And Open Questions

package/skills/ai-delivery-define-product/assets/product-template/terminals.csv

@@ -0,0 +1 @@
+terminal_id,name,audience,core_scenarios,release_scope,priority,notes

package/skills/ai-delivery-define-product/assets/product-template/user-stories.csv

@@ -0,0 +1 @@
+story_id,feature_id,user_role,want,benefit,priority,status

package/skills/ai-delivery-define-product/references/product-contract.md

@@ -0,0 +1,57 @@
+# Product Contract
+
+## Controlled Values
+
+- Business priority: `must`, `should`, `could`, `wont`.
+- Scope: `mvp`, `planned`, `later`, `excluded`.
+- Approval: `pending`, `approved`, `rejected`.
+
+## CSV Schemas
+
+`terminals.csv`:
+
+`terminal_id,name,audience,core_scenarios,release_scope,priority,notes`
+
+`features.csv`:
+
+`feature_id,module,feature,subfeature,user_role,user_goal,description,preconditions,outcome,states_and_exceptions,priority,target_release,status`
+
+`feature-terminals.csv`:
+
+`feature_id,terminal_id,terminal_behavior,priority`
+
+`user-stories.csv`:
+
+`story_id,feature_id,user_role,want,benefit,priority,status`
+
+`acceptance-criteria.csv`:
+
+`acceptance_id,story_id,given,when,then,quality_constraint,status`
+
+Use separate two-column or three-column association CSV files for other many-to-many relationships. Never encode reference lists with commas or semicolons inside a cell.
+
+## Prototype-Originated Requirement Changes
+
+`requirement-change-set.csv`:
+
+`requirement_change_id,source_adjustment_id,change_type,artifact_type,affected_id,proposed_id,phase,summary,before_ref,after_ref,reason,product_impact,architecture_impact,experience_impact,test_impact,status`
+
+Use change types `added`, `modified`, `retired`, and `superseded`. Use statuses `identified`, `product-triage`, `awaiting-product-confirmation`, `approved`, `rejected`, `product-baseline-updated`, `impact-propagated`, `prototype-rebased`, and `closed`. A rejected row is terminal only with human rationale and evidence; an approved semantic change is terminal only after the approved product baseline and affected prototype revisions are linked.
+
+`prototype-product-coverage.csv`:
+
+`feature_id,story_id,acceptance_id,terminal_id,prototype_artifact_id,page_id,prototype_element_id,coverage_status,rationale`
+
+Use `covered`, `not-applicable`, and `missing`. Every `not-applicable` row requires a rationale. Product reconciliation fails on `missing`, an unapproved prototype behavior, an uncovered visual requirement, or a non-terminal requirement change.
+
+`product-prototype-reconciliation.yaml` records exact input/output product baseline identities and checksums, the complete candidate prototype set and formal-UI confirmations, coverage/change-set checksums, terminal/terminology/state checks, stale artifacts, required revalidation, and decision `aligned`, `product-update-required`, or `prototype-correction-required`. Only `aligned` may use `status: valid`.
+
+## Product Manual
+
+Include product summary, problem, users, goals, success metrics, scope, non-scope, business flows, product capability structure, business glossary, business rules, risks, assumptions, and open questions.
+
+For each glossary term record canonical term, definition, exclusion, deprecated synonyms, usage example, related roles or flows, and canonical English identifier. Do not add bounded contexts, aggregates, repositories, or other DDD artifacts.
+
+## Feature Details
+
+Create one detail record per feature when the catalog description is insufficient. Cover goal, trigger, preconditions, main behavior, alternate behavior, outcomes, states, exceptions, business rules, and source IDs. Do not prescribe UI layout or technical implementation.

package/skills/ai-delivery-deploy-production/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: ai-delivery-deploy-production
+description: Execute R08 production deployment of one human-approved immutable release package, including cumulative multi-version and same-version redeploy packages. Use only when the exact release manifest, package checksum, target environment, ordered delivery inventory, verification plan, and rollback plan are approved and unchanged at R07.
+---
+
+# Deploy Production
+
+Execute the approved plan exactly. Do not rebuild, patch, add unlisted items, change configuration ad hoc, or decide that the release succeeded.
+
+## Artifact Location
+
+Write deployment records and evidence to `.workflow/releases/<release-id>/R08-production-deployment/`. Deployed binaries, images, and other non-document artifacts remain in their release systems; record their immutable identities and digests in `.workflow/`.
+
+## Task State
+
+1. Invoke `$ai-delivery-checkpoint-task` before preflight to recover or initialize the task snapshot.
+2. Checkpoint after every meaningful artifact, gate, validation, merge, deployment action, or other external milestone, and before compaction or interruption.
+3. Before returning, finish the snapshot as `completed`, `blocked`, `failed`, or `interrupted`, with actual outputs, evidence, blockers, and one idempotent next action. A Hook event alone never proves completion.
+
+## Preflight
+
+1. Re-read human approval and verify its release version and package hash.
+2. Resolve the configured code repository from `.workflow/config/workspace.yaml`; compare its `repo_id`, commit, code Tag, workflow Tag, manifest checksum, image digests, configuration baseline, migrations, IaC plan, target environment, and delivery inventory with the approved manifest.
+3. Confirm the previous stable image digest and rollback compatibility evidence.
+4. Confirm exclusive production release ownership and required credentials without exposing secrets.
+5. Stop on any mismatch, missing item, expired approval, concurrent release, or unapproved operation.
+
+## Execute
+
+1. Record the current production version and environment state.
+2. Execute listed items in approved order.
+3. Record actual commands or deployment actions, actor, timestamps, results, and resulting identifiers.
+4. Stop according to the approved failure policy. Do not improvise repairs.
+5. Mark the deployment `deployed` only when execution finishes; do not mark it `released`.
+6. Write deployment facts only to the workflow repository. Do not create or advance a code branch during deployment.
+
+## Output
+
+Produce an immutable deployment record containing release mode, current and target versions, newly included version range, actual delivery items, image digests, configuration and migration references, timestamps, results, deviations, and the production-verification handoff.
+
+Read [deployment-contract.md](references/deployment-contract.md).
+
+## Handoff
+
+Invoke `$ai-delivery-verify-production`. Production success, image rollback, and `main` advancement belong to that node.

package/skills/ai-delivery-deploy-production/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Deploy Production"
+  short_description: "Deploy one approved immutable iteration version to production"
+  default_prompt: "Use $ai-delivery-deploy-production to deploy the approved immutable package and record facts in the workflow repository."

package/skills/ai-delivery-deploy-production/references/deployment-contract.md

@@ -0,0 +1,7 @@
+# Production Deployment Contract
+
+Require explicit release ID, mode, current/target versions, selected version range, R07-approved package hash, target environment, release lock, ordered delivery items, exact artifact digests, configuration and migration references, verification plan, rollback plan, and previous stable image digest.
+
+Record deployment ID, actor, start and end timestamps, source and target versions, every attempted item, actual resulting identifiers, failures, deviations, and handoff state.
+
+Abort on unlisted work, identity mismatch, mutable Tag, missing digest, stale approval, concurrent release, or unavailable rollback prerequisite. Never rebuild or patch in production.

package/skills/ai-delivery-design-architecture/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: ai-delivery-design-architecture
+description: Design and reconcile a coherent application, technical, data, security, deployment, and observability architecture. Use after an approved product baseline, after experience design, for a material architecture change, when choosing a technology stack, or when downstream implementation or verification reveals an architectural constraint.
+---
+
+# Design Architecture
+
+Use one skill with `initial` and `reconcile` modes so coupled architecture views remain consistent.
+
+## Artifact Location
+
+Write every workflow document produced by this skill under project `.workflow/`. Place version-scoped node outputs in `.workflow/iterations/<iteration-id>/<node-id>/` and approved reusable architecture baselines in `.workflow/architecture/`. Do not relocate source code, automated test source, repository configuration, or non-document build artifacts.
+
+## Task State
+
+1. Invoke `$ai-delivery-checkpoint-task` before preflight to recover or initialize the task snapshot.
+2. Checkpoint after every meaningful artifact, gate, validation, merge, deployment action, or other external milestone, and before compaction or interruption.
+3. Before returning, finish the snapshot as `completed`, `blocked`, `failed`, or `interrupted`, with actual outputs, evidence, blockers, and one idempotent next action. A Hook event alone never proves completion.
+
+## Preflight
+
+Read the approved product baseline, business glossary, terminal matrix, feature catalog, applicable standards, and prior architecture decisions. Reject incomplete or inconsistent inputs instead of guessing product scope.
+
+## Initial Mode
+
+1. Convert non-functional requirements into measurable quality scenarios and budgets.
+2. Define system context, application and component boundaries, terminal implementation strategies, data ownership, authentication and authorization, security controls, deployment topology, observability, and operational constraints.
+3. Select technology stacks with exact supported versions, package and build tools, repository layout, dependency policy, and required commands.
+4. Draft APIs, events, data contracts, migration strategy, test seams, and delivery constraints.
+5. Record only decisions that are costly to reverse and based on real tradeoffs.
+6. Submit major decisions for human approval before experience design proceeds.
+
+Major decisions include platforms, paid services, security or privacy boundaries, hard-to-reverse data or infrastructure choices, material cost/performance/schedule tradeoffs, and deviations from approved product scope.
+
+## Reconcile Mode
+
+1. Read the experience baseline, `ui-handoff.yaml`, all staged Gate receipts (`UX-LF`, `UX-VS`, and `UX-UI`), aligned `product-prototype-reconciliation.yaml` receipt, experience/requirement change sets, interaction contract, design tokens, framework selection, component-state matrix, page-component map, frozen prototype set, every member manifest, management catalogs, review/impact records, traceability, and each source confirmation. Verify exact identities/checksums and require the handoff to be complete and free of stale references.
+2. Verify that the selected UI framework/version is compatible with the architecture stack and dependency policy, and that every page family, component mapping, interaction, state, permission, query, upload, real-time behavior, failure mode, responsive rule, and accessibility requirement is technically supported. Use stable change/page/canvas/file/element/component IDs in findings.
+3. Write one `prototype-architecture-validation.yaml` per set member with the UI handoff identity/checksum, all consumed artifact versions/checksums, exact architecture baseline version/checksum, implementability decision, affected changes/contracts/components, issues, and return node. An accepted receipt uses `status: valid`; a `changes-required` receipt uses `status: invalid`. Accept the handoff only when all member receipts pass, then advance accepted experience changes from `formal-ui-confirmed` to `architecture-accepted` and `ready-for-development` through the state CLI.
+4. Return product or experience defects to their producer. Do not silently weaken approved behavior or edit the frozen prototype.
+5. Finalize APIs, data access, events, component boundaries, test seams, deployment requirements, and implementation constraints.
+6. Reopen human approval only when reconciliation creates or changes a major decision.
+
+## Outputs
+
+Produce one versioned architecture baseline containing:
+
+- context, container, component, data, security, and deployment views;
+- stack and version manifest;
+- API/event contracts and schemas;
+- data model and migration policy;
+- authentication, authorization, threat controls, and audit requirements;
+- quality budgets and capacity assumptions;
+- repository, build, test, configuration, and observability rules;
+- architecture decisions, risks, assumptions, and validation tasks;
+- versioned major-decision gate/approval evidence in initial mode;
+- prototype architecture validation receipt in reconcile mode;
+- UI framework/dependency acceptance and exact `ui-handoff.yaml` receipt in reconcile mode;
+- final test seams and component impact map.
+
+Do not require DDD constructs. Use business terms from the product manual and provide explicit mappings for unavoidable technical names.
+
+Read [architecture-contract.md](references/architecture-contract.md) and use `assets/architecture-template/` for a new baseline.
+
+## Handoff
+
+Initial mode feeds experience design and delivery-platform preparation. Reconcile mode accepts only an exact confirmed prototype version and produces the final baseline plus its prototype validation receipt for planning, test design, platform work, and implementation.

package/skills/ai-delivery-design-architecture/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Design Architecture"
+  short_description: "Reconcile architecture and prototype feasibility"
+  default_prompt: "Use $ai-delivery-design-architecture to create or reconcile the architecture and validate the exact prototype."

package/skills/ai-delivery-design-architecture/assets/architecture-template/architecture-baseline.md

@@ -0,0 +1,25 @@
+# Architecture Baseline
+
+## Mode And Sources
+
+## Quality Scenarios And Budgets
+
+## System Context And Terminal Strategy
+
+## Application And Component Boundaries
+
+## Technology Stack And Commands
+
+## APIs, Events, And Schemas
+
+## Data And Migration
+
+## Security And Privacy
+
+## Deployment, Configuration, And Observability
+
+## Test Seams
+
+## Decisions, Risks, Assumptions, And Probes
+
+## Experience Reconciliation

package/skills/ai-delivery-design-architecture/assets/architecture-template/architecture-gate.yaml

@@ -0,0 +1,15 @@
+artifact_id: ARCH-GATE-0001
+artifact_type: architecture-major-decision-gate
+version: 1
+iteration_id: ITER-0001
+status: pending
+producer_skill: ai-delivery-design-architecture
+architecture_baseline_ref: ARCH-INITIAL-0001@1
+architecture_baseline_checksum: REPLACE_WITH_SHA256
+major_decision_ids: []
+human_approval_required: false
+decision: not-required
+approved_by: null
+approved_at: null
+evidence: []
+standards: []

package/skills/ai-delivery-design-architecture/assets/architecture-template/prototype-architecture-validation.yaml

@@ -0,0 +1,58 @@
+artifact_id: PROTOTYPE-ARCH-VALIDATION-0001
+artifact_type: prototype-architecture-validation
+version: 1
+iteration_id: ITER-0001
+status: draft
+producer_skill: ai-delivery-design-architecture
+input_artifacts:
+  ui_handoff: UI-HANDOFF-0001@1
+  prototype_set: PROTOTYPE-SET-0001@1
+  prototype_manifest: PROTOTYPE-0001@1
+  prototype_confirmation: PROTOTYPE-CONFIRMATION-0001@1
+  prototype_tool_selection: PROTOTYPE-TOOL-SELECTION-0001@1
+  prototype_review_decision: PROTOTYPE-REVIEW-DECISION-0001@1
+  prototype_impact_assessment: PROTOTYPE-IMPACT-ASSESSMENT-0001@1
+standards: []
+ui_handoff_ref: UI-HANDOFF-0001@1
+ui_handoff_checksum: REPLACE_WITH_SHA256
+prototype_set_ref: PROTOTYPE-SET-0001@1
+prototype_set_checksum: REPLACE_WITH_SHA256
+prototype_artifact_id: PROTOTYPE-0001
+prototype_version: 1
+prototype_manifest_ref: prototype-manifest-PROTOTYPE-0001.yaml
+prototype_manifest_checksum: REPLACE_WITH_SHA256
+prototype_confirmation_ref: PROTOTYPE-CONFIRMATION-0001@1
+prototype_confirmation_checksum: REPLACE_WITH_SHA256
+source_revision: REVISION-0001
+review_bundle_algorithm: sha256
+review_bundle_checksum: REPLACE_WITH_SHA256
+tool_selection_checksum: REPLACE_WITH_SHA256
+page_catalog_checksum: REPLACE_WITH_SHA256
+canvas_catalog_checksum: REPLACE_WITH_SHA256
+canvas_pages_checksum: REPLACE_WITH_SHA256
+prototype_files_checksum: REPLACE_WITH_SHA256
+prototype_file_terminals_checksum: REPLACE_WITH_SHA256
+prototype_review_decision_checksum: REPLACE_WITH_SHA256
+prototype_review_sessions_checksum: REPLACE_WITH_SHA256
+prototype_review_comments_checksum: REPLACE_WITH_SHA256
+prototype_adjustment_log_checksum: REPLACE_WITH_SHA256
+prototype_impact_assessment_checksum: REPLACE_WITH_SHA256
+traceability_checksum: REPLACE_WITH_SHA256
+state_catalog_checksum: REPLACE_WITH_SHA256
+feature_screen_coverage_checksum: REPLACE_WITH_SHA256
+architecture_baseline_id: ARCH-FINAL-0001
+architecture_baseline_version: 1
+architecture_baseline_checksum: REPLACE_WITH_SHA256
+decision: changes-required
+affected_page_ids: []
+affected_canvas_ids: []
+affected_prototype_file_ids: []
+affected_prototype_element_ids: []
+affected_experience_change_ids: []
+affected_ui_component_ids: []
+component_impacts: []
+contract_impacts: []
+quality_budget_conflicts: []
+blocking_issues: []
+return_node: experience-design
+evidence: []

package/skills/ai-delivery-design-architecture/references/architecture-contract.md

@@ -0,0 +1,32 @@
+# Architecture Contract
+
+## Initial Baseline
+
+Include:
+
+- system context and external dependencies;
+- terminal implementation strategy;
+- application and component boundaries;
+- technology stack with exact versions and lifecycle risk;
+- data ownership, models, retention, migration, and recovery strategy;
+- authentication, authorization, security, privacy, and audit controls;
+- deployment topology, configuration, secrets, networking, and observability;
+- measurable quality scenarios and budgets;
+- draft APIs, events, schemas, test seams, and repository conventions;
+- decision records, risks, assumptions, and validation probes.
+
+Produce a versioned architecture-gate artifact that lists major decision IDs and records either their exact human approval evidence or an explicit `not-required` assessment. Use decisions `approved`, `not-required`, and `changes-required`; use `status: valid` only for `approved` or justified `not-required`. Experience design must not start from missing, pending, or invalid gate evidence.
+
+## Reconciled Baseline
+
+Add experience coverage validation, exact UI handoff acceptance, selected framework/dependency compatibility, interaction-driven queries, design-token/component constraints, final APIs/events/schemas, final component impact map, final public test seams, and implementation commands.
+
+Produce one `prototype-architecture-validation.yaml` per prototype-set member. Pin the `ui-handoff.yaml` version/checksum, prototype-set and member identities, source confirmation, staged Gate receipts, aligned product reconciliation, framework selection, design tokens, interaction/component contracts, change sets, management/review/impact checksums, linked coverage, and final architecture baseline. Record decision (`accepted` or `changes-required`), affected experience change/page/canvas/file/element/component IDs, dependency/component/contract impacts, quality-budget conflicts, unresolved issues, evidence, and return node. Use `status: valid` only with `accepted`; reject any identity mismatch or handoff not ready for development. Do not modify experience artifacts.
+
+## Architecture Decision Test
+
+Record a decision only when it is costly to reverse, surprising without context, and based on a real tradeoff. Mark platform, paid service, security/privacy boundary, irreversible data/infrastructure, material cost or schedule, and product-deviation decisions as human-gated.
+
+## Naming
+
+Use product-manual terms. When technical naming must differ, record `business_term`, `technical_name`, and reason.