[Feature]: Extension Lenses — Industry and Perspective Bundles for AIDLC

[harmjeff]

Description

RFC: Extension Lenses — Industry and Perspective Bundles for AIDLC

Summary

This RFC proposes a new extensibility concept called Lenses — named, versioned bundles of extensions and domain-specific rules that configure AIDLC for a specific industry, regulatory environment, or organizational perspective.

A team working on a payment processing system would activate the Banking Lens and get pre-configured security extensions, PCI-DSS and SOX traceability checkpoints, financial domain terminology, and approved/prohibited technology classifications — without needing to understand or configure each concern individually.

This proposal is related to the AIDLC 2.0 extensibility requirement:

"The AI-DLC 2.0 Workflows SHALL support an extensibility mechanism whereby users can customize the workflows as per their organizational needs. Examples of such extensions include security, compliance, testing frameworks, tech stack preferences etc."

Lenses are the highest-level unit of that extensibility system.

---

Problem

The current extensions system (security-baseline, property-based-testing) handles single cross-cutting technical concerns well. It does not address the needs of teams operating in regulated industries or specific business domains where multiple concerns must be configured together and where the workflow needs to use precise domain vocabulary.

Today, a financial services team using AIDLC must:

• Manually activate each relevant extension at Requirements Analysis
• Know which regulatory frameworks apply and what they require
• Add compliance checkpoints themselves at each stage
• Correct AI-generated artifacts that use generic terms instead of domain-precise ones
• Know which technology patterns are prohibited by their regulatory environment

This knowledge cannot live in vision.md or tech-env.md because it is stable across all projects in an industry — not project-specific. The gap means that for regulated industries, correct use of AIDLC requires expert configuration that most teams lack.

---

Proposed Solution

A Lens is a file bundle that lives under a new lenses/ directory in the repo:

lenses/
  <lens-name>/
    <lens-name>.opt-in.md     ← lightweight, loaded at workflow start
    <lens-name>.md            ← full rules, loaded on activation only
    modules/                  ← optional, for lenses with multiple independent
      <framework>.md            regulatory frameworks (e.g., PCI-DSS vs. SOX)

A Lens file contains:

• Extensions — which existing extensions are automatically activated (required vs. recommended)
• Terminology — domain vocabulary that must appear correctly in artifacts
• NFR Defaults — industry-standard non-functional requirements proposed as pre-populated defaults
• Stage Additions — per-stage checklist items for compliance, traceability, and domain-specific design
• Technology Guardrails — approved / preferred / review-required / prohibited classifications
• Compliance Gates — blocking checkpoints where regulatory evidence must be present before proceeding
• Artifact Additions — documents required in addition to the standard AIDLC artifact set

Lenses follow the existing extension opt-in pattern: lightweight opt-in files are scanned at workflow start, auto-detection is attempted against vision.md and tech-env.md using declared keywords, and the full rules file is loaded only when the user activates the lens.

For lenses covering multiple independently applicable regulatory frameworks (e.g., banking where PCI-DSS and SOX can each apply or not apply independently), an optional modules/ sub-directory allows per-framework rules to be loaded on demand after scope is confirmed at Requirements Analysis.

A reference design including two complete example lenses (Banking, Manufacturing) and a full authoring guide has been drafted at harmjeff/playground — lenses/.

---

Implementation Alternatives

Option A: New lenses/ directory (proposed above)

A first-class directory alongside extensions/, with its own file convention (*.opt-in.md + *.md) mirroring the extension pattern and adding an optional modules/ subdirectory.

Pros:

• Clean separation between single-concern extensions and multi-concern lenses
• The file convention is already familiar to anyone who has authored an extension
• Modular structure cleanly handles the independent-frameworks problem without over-engineering the common case
• Can be discovered, indexed, and validated independently of extensions

Cons:

• New directory and naming convention to document and maintain
• Authors need to understand the lens vs. extension distinction to choose the right one

---

Option B: Lenses as "meta-extensions" in the existing extensions/ directory

Lenses live in extensions/ alongside regular extensions. A lens is just an extension that declares Type: lens in its metadata and a Bundles: list of other extensions it activates.

extensions/
  security/
    security-baseline.opt-in.md
    security-baseline.md
  banking/
    banking.opt-in.md          ← declares Type: lens, Bundles: [security-baseline, ...]
    banking.md

Pros:

• No new directory or loading logic — lenses are discovered by the same extension scan
• Smaller surface area for authors to understand

Cons:

• Conflates two different concerns under one directory: single-concern technical extensions and multi-concern domain bundles
• Lens files are substantially larger and more complex than extension files; putting them side-by-side makes the extensions directory harder to navigate
• The modules/ pattern for complex regulatory lenses becomes awkward inside extensions/
• Naming convention can't distinguish lens from extension without reading metadata

---

Option C: Lens as pure configuration (no new rule content)

A lens is a YAML or TOML manifest that only declares which extensions to activate and which terminology/NFR defaults to inject — no new rule prose. All enforcement logic lives in extensions; lenses are just activation profiles.

# lenses/banking/banking.lens.yaml
name: banking
extensions:
  required: [security-baseline, audit-logging, data-classification]
  recommended: [property-based-testing]
terminology:
  - term: Transaction
    definition: An atomic operation that moves value between accounts
    avoid: [operation, transfer]
nfr_defaults:
  encryption_at_rest: AES-256
  session_timeout_minutes: 15

Stage additions, compliance gates, and artifact additions would need to be implemented as extensions themselves.

Pros:

• Machine-readable; easier to validate programmatically
• Smallest possible context footprint (no rule prose loaded at all)
• Aligns well with a v2 skill/hook model where behavior is code, not prompts

Cons:

• Pushes stage additions and compliance gates into extensions, which fragments domain logic across many files
• YAML manifest is not directly usable by the agent as instructions — requires a loader that translates config into agent-readable guidance
• Significantly more implementation work before any lens is usable
• Makes it harder for contributors to author a lens without knowing the extension system internals

---

Option D: Single combined lens file, no modules sub-pattern

Same as the proposed solution but without the optional modules/ directory. All regulatory frameworks covered by a lens live in a single file, always loaded together.

Pros:

• Simpler file structure — one activation, one file
• Easier to author and review
• Appropriate for the majority of lenses that have a single regulatory regime

Cons:

• For lenses like banking where PCI-DSS and SOX are independently applicable, loading both unconditionally causes the agent to flag irrelevant findings for out-of-scope projects
• Context overhead grows linearly with the number of frameworks covered
• Can be worked around by authoring separate lenses (banking-pci, banking-sox) but that puts the composition burden back on the user

---

Recommendation

Option A (new lenses/ directory) with the modules/ sub-pattern treated as optional.

The key reasons:

1. The lens/extension distinction is real and worth making explicit. An extension is a single technical concern. A lens is an industry perspective that bundles multiple concerns with domain semantics. Mixing them in extensions/ obscures both.

2. The opt-in file convention is already proven. The existing extension pattern works well; lenses should inherit it rather than invent a new loading mechanism.

3. Single-file is the right default. Most lenses will cover one regulatory regime and should stay simple. The modules/ pattern is opt-in for the cases (banking, healthcare, government) where independent frameworks genuinely need independent activation.

4. Option C is the right long-term direction for v2 — a machine-readable manifest with behavior implemented as skills/hooks — but it requires infrastructure that does not yet exist. Option A is forward-compatible with that direction: the *.md rules files can be replaced by skills as v2 matures, while the directory structure and discovery convention stay the same.

The lenses/ directory should be added to the core-workflow.md extension loading section alongside the existing extensions/ scan, so agents discover lenses at the same moment they discover extensions.

---

Open Questions

1. Lens versioning and breaking changes. When a lens is updated with new blocking gates, existing projects that activated the previous version now have unmet compliance gates. Should aidlc-state.md pin the lens version, and should agents warn when a newer version is available?

2. Organizational private lenses. Teams will want to author private lenses for internal standards (not publishable to the public repo). Should the spec define a convention for a local lenses/ override directory, similar to how some tools support ~/.config/<tool>/ for user-local config?

3. Lens conflicts. Can two lenses be active simultaneously (e.g., a healthcare organization also using a government-federal lens for public payers)? The current design does not prohibit it, but merging terminology tables and compliance gates from two lenses has not been specified.

4. Testing lenses. The evaluator framework has test cases for core workflow stages. Should lens authors be required to provide an evaluator test scenario (example vision.md + tech-env.md + expected activated lens) as part of the contribution?

5. Lens discovery UX. The opt-in prompt currently lists available lenses alongside extensions during Requirements Analysis. As the number of lenses grows, this list could become long. Should lenses be surfaced separately from extensions, or should auto-detection be the primary discovery path?

---

Related

• AIDLC 2.0 Requirements: Extensibility requirement
• Existing extensions: extensions/security/, extensions/testing/
• Reference design: harmjeff/playground — lenses/

Use Case

Use Cases

Financial Services Team — New Payment Integration

A team at a bank is building a new payment gateway integration. They start an AIDLC session, the agent detects the word "payment" in vision.md, and proposes the Banking Lens. They activate it. For the rest of the project:

• Requirements Analysis surfaces a data classification checklist — the team identifies which data is cardholder data (PCI scope) and which is internal
• Application Design asks them to mark the CDE boundary on their component diagram
• NFR Requirements arrives with AES-256 at-rest, TLS 1.3 in-transit, and 15-minute session timeout pre-filled — they adjust the session timeout for their specific operator interface
• Code Generation flags a double type used for a currency field as a blocking finding and proposes BigDecimal
• Build and Test includes a pre-generated test case for idempotency (duplicate payment request must not double-charge)
• The project closes with a compliance-attestation.md artifact ready to hand to their compliance officer

Without the lens, each of these steps would require a team member who knows PCI-DSS to manually add them. That person is often not on the development team.

---

Manufacturer — Shop Floor Data Collection System

A team is building a new IIoT data collection layer that bridges PLCs on the shop floor to a cloud analytics platform. They start an AIDLC session. The agent detects "PLC" and "shop floor" in tech-env.md and proposes the Manufacturing Lens.

• Requirements Analysis asks them to locate the system on the OT/IT network boundary and document offline tolerance — the team realizes they have not yet decided what happens when cloud connectivity drops for four hours during a shift
• Application Design prompts them to classify the edge agent component as [CONTROL-PATH] vs. data-only — they confirm it is data-only (read-only from PLC, no write-back), which relaxes the real-time constraints
• NFR Requirements arrives with store-and-forward resilience and OPC UA as a preferred protocol pre-filled
• Infrastructure Design adds a network segmentation diagram requirement, which surfaces a discussion about whether the edge device lives in the OT zone or the DMZ — a decision they had been deferring
• Build and Test includes a connectivity loss simulation test they would not have written on their own

---

Healthcare SaaS Provider — Patient Scheduling Feature

A team building a new scheduling feature on a HIPAA-covered SaaS platform activates a Healthcare Lens (not yet in the repo — this illustrates future scope). The lens knows that patient demographic data is PHI, that audit logs must meet HIPAA's 6-year retention requirement, and that any third-party scheduling library must have a signed BAA before use. These facts are stable across every feature this team will ever build — they do not need to rediscover them project by project.

---

Platform Team — Internal Organizational Standards

A platform team wants every application team at their company to follow internal architecture standards: approved cloud services, required observability stack, prohibited direct database access from Lambda, mandatory secrets manager usage. They author a private org-standard lens that lives in their internal template repository alongside their vision.md and tech-env.md templates. New application teams clone the template and get the org standards enforced automatically without reading a separate standards document.

This use case also illustrates the private lens question raised in Open Questions below.

Area

Inception phase rules

Additional Context

No response