[Feature]: ALDLC 1.0 True Orchestrator

[harmjeff]

Proposal: Add a Machine-Readable Stage Registry to aidlc-workflows

Status: Draft — for discussion
Target repo: awslabs/aidlc-workflows
Impact to existing users: None (addition only, no behavioral change for CLAUDE.md / AGENTS.md users)

---

The Core Insight

The same rule files can serve both human-agent and programmatic consumers without maintaining two sets of rules. The difference between the two modes is only in how rules are delivered to the model — not what the rules say.

Human-agent mode (CLAUDE.md, AGENTS.md, Cursor, Kiro, Amazon Q): The model reads core-workflow.md and follows its prose instructions — e.g., "Load all steps from inception/requirements-analysis.md." The model fetches rule files from disk on demand as it reaches each stage. This already works and this proposal does not change it.

Programmatic mode (Strands agents, Bedrock agents, multi-agent platforms): A program assembles rules and passes them to the model via API. It cannot follow prose instructions — it needs to know, before a stage runs, which file to inject. With a machine-readable registry, the program reads the registry, fetches the same canonical files the human-agent mode uses, and injects them at the right moment. Same files, different delivery.

The registry enables one rule set for both modes. Without it, any programmatic consumer is forced to either load everything upfront (wasteful) or maintain its own copy of the dispatch mapping (which diverges over time). With it, programmatic consumers point at the canonical source and stay synchronized automatically.

---

Use Cases

UC-1: Building a programmatic AI-DLC agent

A team wants to run AI-DLC as a fully automated Strands or Bedrock agent — no CLAUDE.md, no human copying files, invoked via API. Today they must load all 22 rule files into the system prompt at startup because there is no machine-readable way to know which file is needed at which stage. With a stage registry, the agent reads the registry at startup, injects only the 4 common rules, then fetches each stage's rule file on demand as the workflow progresses. A skipped stage injects nothing.

UC-2: Building a multi-agent pack that uses canonical rules

A team wants to package AI-DLC as a multi-agent system (conductor + specialist agents per stage) for distribution via a packaging tool. Without a registry, they must maintain parallel prompt files — independent rewrites of aws-aidlc-rule-details/ — because there is no canonical pointer to which rule file covers which stage. With a stage registry and a pack definition, each specialist agent references its canonical rule file directly. The parallel rewrites are retired. One set of rules, two consumption modes.

UC-3: Staying synchronized as the rules evolve

Any programmatic consumer that hard-codes its own stage-to-file mapping will drift as AI-DLC rules evolve — new stages added, files renamed, extensions introduced. With a versioned stage-registry.yaml, the consumer detects version changes and knows exactly which mappings have changed. Without it, drift is silent and cumulative.

---

Current Problems

Problem 1: No Machine-Readable Dispatch Table

Programmatic consumers have no way to determine which rule file belongs to which stage without parsing prose. The only safe option today is loading all rule files at startup:

RULE_PATHS = [
    "aidlc-rules/aws-aidlc-rules/core-workflow.md",
    "aidlc-rules/aws-aidlc-rule-details/common/process-overview.md",
    # ... 20 more files, regardless of which stages will actually run
]

def assemble_system_prompt() -> str:
    # All 22 files concatenated into one system prompt, every session

A 13-stage workflow that skips 6 conditional stages still injects 100% of the rules. There is no hook to do otherwise.

Problem 2: Parallel Implementations Drift Without a Canonical Reference

An existing agentic packaging prototype independently decomposes the AI-DLC workflow into 10 specialist agents. Because there is no machine-readable registry to point at the canonical rule files, the prototype maintains parallel prompt files — independent rewrites of aws-aidlc-rule-details/ content that are not synchronized with core-workflow.md. Two sources of truth now exist for the same methodology and they have already diverged.

This is a direct consequence of Problem 1. A registry makes the canonical files the single source of truth for both modes, eliminating the need for any parallel copies.

---

What Is NOT Being Proposed

• No changes to any file in aws-aidlc-rule-details/
• No changes to the CLAUDE.md / AGENTS.md / Cursor / Kiro / Amazon Q user experience
• No renaming of the public contract directories (aws-aidlc-rules/, aws-aidlc-rule-details/)
• No new required setup step for existing users
• No removal of any existing prose in core-workflow.md
• No second set of rules — the proposal enables one set of rules consumed two ways

All options below are additive only.

---

The Required Semantics (shared by all options)

A machine-readable registry encodes what core-workflow.md already states in prose:

Session start — always inject:

• common/process-overview.md
• common/session-continuity.md
• common/content-validation.md
• common/question-format-guide.md

Per-stage dispatch:

Stage	Rule File	Phase	Condition
workspace_detection	inception/workspace-detection.md	inception	always
requirements_analysis	inception/requirements-analysis.md	inception	always
reverse_engineering	inception/reverse-engineering.md	inception	conditional
user_stories	inception/user-stories.md	inception	conditional
workflow_planning	inception/workflow-planning.md	inception	always
application_design	inception/application-design.md	inception	conditional
units_generation	inception/units-generation.md	inception	conditional
functional_design	construction/functional-design.md	construction	conditional
nfr_requirements	construction/nfr-requirements.md	construction	conditional
nfr_design	construction/nfr-design.md	construction	conditional
infrastructure_design	construction/infrastructure-design.md	construction	conditional
code_generation	construction/code-generation.md	construction	always
build_and_test	construction/build-and-test.md	construction	always

Extensions — inject only when user opts in:

The registry supports two types of extensions:

• Rule-injection extensions add rules into one or more existing stages (e.g., security-baseline adds blocking security rules during code generation). These carry an applies_to_stages list so programmatic consumers know exactly when to inject the rule file. Omitting applies_to_stages means inject at every stage.
• Stage-adding extensions insert a new stage into the workflow sequence (e.g., a compliance review, accessibility audit, or performance benchmarking stage). These use an adds_stage block declaring the stage name, rule file, phase, condition, and insertion point.

Both types are included in version: "1.0" to avoid a breaking schema change as the extension system grows. No stage-adding extensions exist yet; the schema is included now to avoid locking the format into an incompatible corner.

Extension	Opt-In File	Rule File	Type	Applies To
security_baseline	extensions/security/baseline/security-baseline.opt-in.md	extensions/security/baseline/security-baseline.md	rule-injection	code_generation
property_based_testing	extensions/testing/property-based/property-based-testing.opt-in.md	extensions/testing/property-based/property-based-testing.md	rule-injection	functional_design, code_generation

Full extension schema:

extensions:
  # Rule-injection: adds rules into specific existing stages
  security_baseline:
    opt_in_file: extensions/security/baseline/security-baseline.opt-in.md
    rule_file: extensions/security/baseline/security-baseline.md
    applies_to_stages:
      - code_generation

  property_based_testing:
    opt_in_file: extensions/testing/property-based/property-based-testing.opt-in.md
    rule_file: extensions/testing/property-based/property-based-testing.md
    applies_to_stages:
      - functional_design
      - code_generation

  # Stage-adding: inserts a new stage into the workflow sequence
  compliance_review:
    opt_in_file: extensions/compliance/compliance-review.opt-in.md
    adds_stage:
      name: compliance_review
      file: extensions/compliance/compliance-review.md
      phase: construction
      condition: conditional
      insert_after: nfr_requirements

---

Implementation Options

Option A — Embed a manifest table in core-workflow.md

Add the dispatch table above as a new ## STAGE_RULES Registry section near the top of core-workflow.md, immediately after the Adaptive Workflow Principle block. All existing stage prose sections remain unchanged below it.

Single rule set: Yes — human-agent users follow the prose below the table; programmatic consumers parse the table. Same file, same content.

Pros:

• Zero new files — no change to the public contract structure
• Single source of truth: the table and the prose it describes live in the same file
• Easiest contribution path — one file to update when a stage is added

Cons:

• Parsing a markdown table is brittle for programmatic consumers (column alignment, whitespace)
• Couples two concerns (human workflow instructions + machine dispatch) in one file
• Any edit to the table risks accidentally touching adjacent prose

---

Option B — Add a sibling stage-registry.yaml in aws-aidlc-rules/ ⭐ Recommended

Add aidlc-rules/aws-aidlc-rules/stage-registry.yaml alongside core-workflow.md. core-workflow.md gets a single-line reference comment pointing to it, but is otherwise untouched.

# stage-registry.yaml
version: "1.0"

startup:
  - common/process-overview.md
  - common/session-continuity.md
  - common/content-validation.md
  - common/question-format-guide.md

stages:
  workspace_detection:
    file: inception/workspace-detection.md
    phase: inception
    condition: always
  requirements_analysis:
    file: inception/requirements-analysis.md
    phase: inception
    condition: always
  reverse_engineering:
    file: inception/reverse-engineering.md
    phase: inception
    condition: conditional
  # ... remaining stages

extensions:
  security_baseline:
    opt_in_file: extensions/security/baseline/security-baseline.opt-in.md
    rule_file: extensions/security/baseline/security-baseline.md
    applies_to_stages:
      - code_generation
  property_based_testing:
    opt_in_file: extensions/testing/property-based/property-based-testing.opt-in.md
    rule_file: extensions/testing/property-based/property-based-testing.md
    applies_to_stages:
      - functional_design
      - code_generation

Single rule set: Yes — the registry points at the canonical rule files. Human-agent users follow prose in core-workflow.md; programmatic consumers read the registry and inject the same files. No parallel copies needed.

Pros:

• Clean separation of concerns — human workflow doc stays human, machine manifest stays machine
• Trivial to parse in any language (yaml.safe_load, one line)
• Explicit version field lets programmatic consumers detect breaking changes
• core-workflow.md is essentially untouched — lowest risk to existing users
• Closes the drift problem: parallel implementations can reference canonical files instead of maintaining rewrites

Cons:

• Adds one non-markdown file to a currently pure-markdown repo
• Two files to keep in sync when a stage is added (stage-registry.yaml + core-workflow.md prose)

---

Option C — No repo changes; downstream tools own the registry

Make no changes to awslabs/aidlc-workflows. Programmatic consumers maintain their own dispatch mappings independently.

Single rule set: No — this option structurally forces parallel copies. Without a canonical registry, programmatic consumers must either load everything or maintain their own mapping. Mappings that live outside the repo drift from the rules with no detection mechanism.

Pros:

• Zero changes to the rules repo — public contract completely frozen
• Each tool can optimize its registry for its own architecture

Cons:

• This is the current state — it has already produced divergence between aws-aidlc-rule-details/ and the agentic packaging prototype's bundled prompts
• Every new programmatic consumer faces the same forced choice: load everything or copy the mapping
• Nothing in the repo signals how stages map to files

---

Option D — Ship a platform-agnostic pack definition with aidlc-workflows ⭐ Also Recommended (follow-on)

Add an agent-pack.json to aidlc-rules/ that describes how to package the canonical rules as a multi-agent pack. This uses a format already validated by the existing prototype and directly closes the gap between the canonical rules and the agentic packaging layer.

{
  "name": "aidlc",
  "version": "0.1.0",
  "agents": [
    {
      "name": "aidlc-conductor",
      "description": "AI-DLC orchestrator — loads stage rules on demand and delegates",
      "prompt": "aws-aidlc-rules/core-workflow.md",
      "tools": ["fs_read", "fs_write", "grep", "glob", "execute_bash", "use_subagent"],
      "resources": [
        "aws-aidlc-rule-details/common/process-overview.md",
        "aws-aidlc-rule-details/common/session-continuity.md",
        "aws-aidlc-rule-details/common/content-validation.md",
        "aws-aidlc-rule-details/common/question-format-guide.md"
      ]
    }
  ],
  "platforms": [
    { "platform": "kiro-cli", "enabled": true },
    { "platform": "claude-code", "enabled": true }
  ]
}

Stage-specific specialist agents can be added as the multi-agent pattern matures.

Single rule set: Yes — agent-pack.json references the canonical rule files directly. The prototype's parallel prompt rewrites are replaced by pointers to aws-aidlc-rule-details/. One set of rules, consumed by both human-agent and packaged-agent modes.

Note: This option is only useful once a compatible packaging toolchain reaches public stability. It should follow Option B, not replace it.

Pros:

• References canonical files directly — prototype's parallel prompts can be retired
• A single install command becomes the canonical path for both Kiro and Claude Code
• Format is versioned and lends itself to schema validation

Cons:

• Provides no value until the packaging toolchain is publicly available and stable
• Couples the rules repo to a specific pack format — future maintainers must understand it
• Option B is the more broadly useful first step; D is the targeted follow-on

---

Recommendation

Option B now, Option D as a follow-on.

Option B is the right first step: it makes the canonical rule files usable by any programmatic consumer without duplication. It costs nothing if no programmatic consumer appears. When one does, it has a stable, versioned foundation that points at the canonical source — eliminating the need for parallel copies.

Option D follows once the packaging toolchain stabilizes. At that point, agent-pack.json references the canonical files directly, the prototype's parallel prompt rewrites are retired, and there is definitively one set of rules consumed two ways.

Option C is the current state and has already forced the divergence this proposal aims to prevent. Option A works but encodes the registry in a format that is brittle to parse and easy to accidentally corrupt during normal edits.

---

What On-Demand Injection Looks Like

Human-agent users already get this for free — the model reads files on demand as it follows core-workflow.md prose. For programmatic consumers, the difference:

Before (load-all, current pattern):

Session start:  22 files × ~3K chars  =  ~66K chars in system prompt, every session

After (registry-driven, Option B):

Session start:  core-workflow.md + 4 startup rules  =  ~18K chars
Stage inject:   1 rule file per active stage         =  ~3K chars added per stage
Skipped stages: 0 chars

For a typical greenfield workflow that skips 5 conditional stages, injected rule content drops by roughly 35–40%.

---

Impact Analysis

Audience	What Changes	Behavioral Impact
CLAUDE.md users	core-workflow.md gets a one-line reference comment	None
AGENTS.md users	Same	None
Cursor / Kiro / Amazon Q users	Same	None
Programmatic / Strands / Bedrock agents	stage-registry.yaml available	Canonical per-stage injection; no parallel copies needed
Agentic packager users	agent-pack.json available (Option D follow-on)	Prototype's parallel prompts retired; single rule set
Repo maintainers	One new YAML file to keep in sync	Minimal — CI lint can enforce consistency

---

Open Questions for Discussion

1. Pure-markdown constraint: Option B adds a YAML file. Is that acceptable, or does the repo have a hard constraint on file types?

2. Sync enforcement: Adding a stage requires updating both core-workflow.md (prose) and stage-registry.yaml (manifest). Is a CI lint check — e.g., verify every stage in the registry has a corresponding section heading in core-workflow.md — sufficient to keep them in sync?

3. Pack format timing (Option D): Should agent-pack.json wait until the packaging toolchain reaches a stable public release, or is shipping a draft format useful as a signal of intent even before the toolchain is ready?

4. Closing the drift now: Given that parallel prompts already exist in the agentic packaging prototype, should retiring those in favor of canonical file references be in scope for this proposal, or a separate follow-on?

5. Extension schema design: The registry distinguishes two extension types — rule-injection (adds rules to specific stages via applies_to_stages) and stage-adding (inserts a new stage via adds_stage). Both are included in version: "1.0" to avoid breaking changes as the extension system grows. Two design questions: (a) Is insert_after the right way to express stage position, or should it be insert_before, an explicit index, or a separate stage_order sequence? (b) Should omitting applies_to_stages on a rule-injection extension mean "inject at all stages" or should it be a validation error?