[RFC]: Enhancing Extensions Functionality - Extensions that produce deliverables, not just verify constraints

[smchavan84]

Summary

Extend the AI-DLC extension mechanism so extensions can generate artifacts (documents, reports, matrices) at stage boundaries, not just verify that constraints are met. This requires two new fields in the extension rule format (Template and Output), one addition to the core workflow, and conventions for template authoring and artifact management.

Motivation

The current extension system enforces rules as blocking constraints: "does this code meet the security baseline?" If not, the stage blocks. This works well for verification. But many domains need extensions that produce deliverables alongside code:

• Medical device teams need Software Requirements Specifications, Risk Analyses, Traceability Matrices, and SBOMs generated at specific development stages (IEC 62304, ISO 14971, FDA Cybersecurity)
• Financial services teams need SOX audit evidence and data lineage records produced during development
• Government teams need FedRAMP authorization artifacts generated as the system is built
• Any organization with internal documentation standards needs architecture decision records, API docs, or security review artifacts produced at the right time

Today, these artifacts are produced manually by separate teams after development completes. If extensions could generate them during development using the same context the AI used to write the code, the artifacts would be accurate, traced, and produced without additional effort.

Detailed Proposal

1. Two new optional fields in extension rules

Add Template and Output fields to the existing rule format. Example:

## Rule EXAMPLE-01: Architecture Decision Record

**Applies at AI-DLC Stage(s)**: Inception - Application Design

**Rule**: An Architecture Decision Record MUST be produced for each
significant technical decision, documenting context, options considered,
and rationale.

**Template**: `templates/architecture-decision-record.md`

**Output**: `aidlc-docs/decisions/adr-{number}.md`

**Verification**:
- ADR exists for each significant decision
- Context, options, and rationale sections are populated

Behavior:

• Rules with Template + Output: AI generates the artifact using the template and saves to the output path
• Rules with Verification only (no Template/Output): AI verifies compliance (current behavior, unchanged)
• Rules with both: AI generates the artifact AND verifies compliance

2. One addition to core workflow

Add a single mandatory section to core-workflow.md:

## MANDATORY: Extension Artifact Generation Before Closing Any Stage

Before closing any Stage in any Phase, validate and execute the following
for all opted-in extensions:

1. For each opted-in extension, check its rules for
   `**Applies at AI-DLC Stage(s)**` matching the current stage
2. For rules that have BOTH a `**Template**` and `**Output**` field:
   GENERATE the artifact using the template and save to the output path.
   If the artifact already exists, UPDATE it with new content from the
   current stage.
3. For rules that have `**Verification**` only: verify compliance against
   the stage's artifacts
4. Track extension deliverables in `aidlc-docs/aidlc-state.md`
5. Include an Extension Compliance Summary in the stage completion message
6. If any applicable rule is non-compliant, this is a **blocking finding**

**Artifact existence verification**: After generating or updating any
artifact, confirm the file exists at the output path before marking it
complete. Missing file = blocking finding.

**Construction close — artifact-to-code validation**: Before presenting
Build and Test completion, cross-reference all extension artifacts against
actual generated code for accuracy and update them to reflect actual
implementation status.

3. Template conventions

Templates use placeholder syntax that the AI populates with project-specific content:

• {{GENERATE: description of what to fill in}} — AI generates content based on project context
• {{PROJECT_NAME}}, {{UNIT_NAME}}, {{DATE}}, {{REVISION}} — variable substitutions
• <!-- REQUIRED per {standard} {clause} --> — sections that must not be removed
• <!-- CUSTOMIZE: description --> — sections where organizations insert their own content

Example template file (templates/architecture-decision-record.md):

<!--
  TEMPLATE: Architecture Decision Record
  RULE: EXAMPLE-01
-->

# Architecture Decision Record: {{GENERATE: Decision title}}

<!-- CUSTOMIZE: Replace with your organization's document control header -->
| Field | Value |
|---|---|
| Project | {{PROJECT_NAME}} |
| Unit | {{UNIT_NAME}} |
| Date | {{DATE}} |
| Status | Proposed |

## 1. Context

<!-- REQUIRED -->
{{GENERATE: Describe the technical context and forces at play. What is the
situation that requires a decision? Include relevant constraints, requirements,
and quality attributes that influence the decision.}}

## 2. Decision

<!-- REQUIRED -->
{{GENERATE: State the decision clearly. Use active voice: "We will use X
for Y because Z."}}

## 3. Options Considered

<!-- REQUIRED -->

### Option A: {{GENERATE: Option name}}
{{GENERATE: Description, pros, cons}}

### Option B: {{GENERATE: Option name}}
{{GENERATE: Description, pros, cons}}

## 4. Rationale

<!-- REQUIRED -->
{{GENERATE: Explain why the chosen option was selected over alternatives.
Reference specific requirements or constraints that drove the decision.}}

## 5. Consequences

<!-- REQUIRED -->
{{GENERATE: Describe the resulting context after applying the decision.
What becomes easier? What becomes harder?}}

## 6. Traceability

| Traces To | Reference |
|---|---|
| Requirement(s) | {{GENERATE: Requirement IDs this decision addresses}} |
| Component(s) | {{GENERATE: Components affected by this decision}} |

4. Project-level vs per-unit artifacts

• Output paths without {unit-name}: project-level (one per project). Created on first encounter, updated on subsequent units. Never duplicated.
• Output paths with {unit-name}: per-unit (one per unit of work). Created fresh for each unit.

5. Backward compatibility

This proposal is fully backward compatible:

• Existing extensions (security-baseline, property-based-testing) have no Template or Output fields — they continue to work as verification-only constraints
• The new core workflow section only triggers artifact generation for rules that have both fields
• No changes to the opt-in mechanism, enforcement behavior, or blocking finding semantics

Alternatives Considered

1. Common rules for extensions: Place artifact generation instructions in the common/ rules directory so they load at workflow start and apply to all extensions. Rejected because common rules are generic (content validation, question format) and not extension-specific. Artifact generation behavior is tightly coupled to which extensions are enabled and what stage triggers apply. Putting it in common rules would either be too generic to be actionable or would require common rules to know about specific extensions.

2. Separate steering document instead of core workflow modification: Create a standalone steering file (e.g., extensions-workflow.md) with the artifact generation instructions rather than modifying core-workflow.md. Tested and rejected because the AI reads steering files once at session start, then loses them from active attention as context fills with stage-specific work. The instruction needs to be in the core workflow where the AI re-encounters it at every stage boundary. A separate steering file was consistently forgotten by the AI during later Construction stages.

Drawbacks

• Context consumption: Loading templates and generating artifacts consumes context window space. For projects with many extensions enabled, this adds pressure on context limits.
• Nudging required: As the number of enabled extensions increases, the AI starts context-optimizing and forgets the artifact generation instructions since they are not called out explicitly as steps within each stage's execution. The core workflow instruction is clear, but it competes with stage-specific steps for attention.

Additional Context

This approach was implemented and tested with extensions created specifically for medical device software documentation requirements.

Reference implementation: https://github.com/aws-samples/sample-aidlc-medical-devices-regulatory-extensions

This repository demonstrates the approach with 9 medical device regulatory standards. It includes:

• 9 extension rule files (one per standard) with Template, Output, and Verification fields per rule
• 42 document templates with {{GENERATE:}} placeholders
• A consolidated opt-in mechanism with dependency management
• A modified core-workflow.md with the artifact generation section proposed above

The same pattern applies to any domain requiring structured documentation alongside code (financial services, government, automotive, internal standards).