Skip to main content

​
AI-DLC definition

The built-in AI-DLC workflow is published as a normal Fabriqa workflow definition.

​
Folder layout

definitions/ai-dlc/
  workflow.yaml
  agents/
    master.saf
    inception.saf
    construction.saf
    operations.saf
  prompts/
    master.md
    inception.md
    construction.md
    operations.md
  schemas/
    intent.yaml
    unit.yaml
    story.yaml
    bolt.yaml
    domain-design.yaml
    logical-design.yaml
    system-context.yaml
    implementation-plan.yaml
    walkthrough.yaml
    test-report.yaml
    deployment-unit.yaml
  connectors/
    file.yaml
  templates/
    intent.md.tmpl
    unit.md.tmpl
    story.md.tmpl
    bolt.md.tmpl
    domain-design.md.tmpl
    logical-design.md.tmpl
    system-context.md.tmpl
    implementation-plan.md.tmpl
    walkthrough.md.tmpl
    test-report.md.tmpl
    deployment-unit.md.tmpl

​
workflow.yaml

The AI-DLC workflow envelope stays orchestration-focused. 
workflow:
  id: ai-dlc
  name: AI-Driven Development Lifecycle
  version: 2.0.0
  description: >
    AI-native planning, execution, and operations workflow for complex software delivery.
  icon: zap

phases:
  - id: inception
    name: Inception
    agent: inception
  - id: construction
    name: Construction
    agent: construction
  - id: operations
    name: Operations
    agent: operations

relations:
  allowed:
    - depends_on
    - implements
    - validates
    - supersedes
    - related_to

agents:
  master: agents/master.saf
  inception: agents/inception.saf
  construction: agents/construction.saf
  operations: agents/operations.saf

artifacts:
  intent: schemas/intent.yaml
  unit: schemas/unit.yaml
  story: schemas/story.yaml
  bolt: schemas/bolt.yaml
  domain_design: schemas/domain-design.yaml
  logical_design: schemas/logical-design.yaml
  system_context: schemas/system-context.yaml
  implementation_plan: schemas/implementation-plan.yaml
  walkthrough: schemas/walkthrough.yaml
  test_report: schemas/test-report.yaml
  deployment_unit: schemas/deployment-unit.yaml

connectors:
  file: connectors/file.yaml

ui:
  sidebar:
    allowed_group_by:
      - type
      - phase
      - status
    default: status
The referenced agent SAF files still select from Fabriqa’s fixed tool vocabularies.
  • AI-DLC SAF files stay minimal: saf_version, agent.id, agent.name, agent.kind, system_prompt, and tools
  • AI-DLC declares master and inception as planning, and construction and operations as execution
  • tools.workflow uses only the predefined Fabriqa workflow-tool names documented in Agents and connectors
  • tools.coding uses either a predefined subset such as ["read_file", "web_search", "fetch"] or "full"
  • AI-DLC uses narrower read-oriented subsets for master and inception, "full" for construction, and a narrower subset including execute for operations
  • ACP behavior, provider capability checks, and runtime tool translation remain Fabriqa runtime concerns rather than authored workflow DSL
Notice what is not in workflow.yaml:
  • the detailed shape of walkthrough
  • the markdown sections of domain_design
  • bolt-specific execution-output rules
  • dashboard configuration
  • root artifact viewer tabs
  • workspace-specific connector enablement or target selection
That artifact-local meaning belongs in each schema file.

​
AI-DLC UI surfaces

AI-DLC uses the standard Fabriqa workflow surfaces:
  • a global sidebar
  • a status-driven dashboard
  • root artifact viewer tabs
+----------------------+--------------------------------------------------------------+
| AI-DLC sidebar       | Main workspace area                                          |
|                      |                                                              |
| [AI-DLC] [Agents]    | [Dashboard] [INT-001] [BOLT-004]                             |
| Group by: Status     |                                                              |
|                      | Dashboard                                                    |
| Draft                | +-------------+--------------+--------------+                |
|   INT-001            | | Draft       | In review    | Approved     |                |
|   STORY-014          | | intents...  | bolts...     | reports...   |                |
| In review            | +-------------+--------------+--------------+                |
|   BOLT-004           |                                                              |
| Approved             | Artifact viewer                                             |
|   TEST-002           | +--------------------------------+ +----------------------+ |
|                      | | Selected artifact document     | | Context rail         | |
|                      | | markdown body + meta row       | | tree, relations,     | |
|                      | | plain reading surface          | | chats, activity      | |
|                      | +--------------------------------+ +----------------------+ |
+----------------------+--------------------------------------------------------------+
AI-DLC relies on phase-aware root resolution:
  • clicking a story usually resolves to the surrounding planning root such as the intent
  • clicking a walkthrough or test_report resolves to the surrounding construction root such as the bolt
That means the viewer opens the right context tab instead of opening one isolated tab per child artifact. The artifact viewer contract is the same as the general Workflow DSL contract:
  • the document body is markdown-first and read-only
  • metadata stays as a compact row under the title
  • child artifacts do not repeat in the document body
  • the right rail contains the tree plus contextual lists for the selected artifact
  • the right rail is collapsible and resizable

​
connectors/file.yaml

AI-DLC can expose a file connector without baking workspace-specific file settings into the workflow definition. 
kind: file

artifacts:
  intent:
    template: templates/intent.md.tmpl
    filename: intents/{{ artifact.display_id }}.md
  bolt:
    template: templates/bolt.md.tmpl
    filename: bolts/{{ artifact.display_id }}.md
  walkthrough:
    template: templates/walkthrough.md.tmpl
    filename: walkthroughs/{{ artifact.display_id }}.md
  deployment_unit:
    template: templates/deployment-unit.md.tmpl
    filename: deployment/{{ artifact.display_id }}.md
When AI-DLC is activated on a workspace, Fabriqa can then let the user enable or disable the file connector and choose the target workspace project or export location as runtime configuration.

​
Lifecycle pattern

AI-DLC keeps lifecycles inline in each artifact schema. That means domain_design, logical_design, system_context, implementation_plan, walkthrough, and test_report may repeat similar lifecycle blocks on purpose. This is the simpler authoring model for now. Because those lifecycles are local to one artifact file, V1 does not give them separate lifecycle id or name fields.

​
Key artifact schema examples

​
bolt

bolt is the execution anchor in AI-DLC. It should carry:
  • grouped story references
  • explicit project targeting
  • stage progress
  • checkpoint state
artifact:
  id: bolt
  name: Bolt
  icon: zap
  phase: construction

parent: unit

lifecycle:
  initial: draft
  states:
    - id: draft
      label: Draft
      actor: system
    - id: in_review
      label: In review
      actor: human
      handoff: true
    - id: approved
      label: Approved
      actor: human
    - id: superseded
      label: Superseded
      actor: system
      terminal: true

schema:
  type: object
  properties:
    bolt_type:
      type: string
      required: true
      enum: [ddd, simple, spike]
      description: Execution pattern for this bolt.
    story_ids:
      type: array
      required: true
      items:
        type: string
      minItems: 1
      description: Story artifacts grouped into this bolt.
    execution_brief:
      type: string
      required: false
      description: Markdown summary of what this bolt is meant to deliver.
    current_stage:
      type: string
      required: false
      enum: [plan, model, design, implement, test, document]
    checkpoint_status:
      type: string
      required: false
      enum: [none, pending, approved, waived]

document:
  sections:
    - id: brief
      title: Execution brief
      field: execution_brief
      kind: markdown
Fabriqa still exposes built-in metadata such as status, tags, target_scope, and target_workspace_project_ids for bolt. They are not redeclared in the schema.

​
domain_design

In the document-first DSL, domain_design should read like a design note, not a structured form. 
artifact:
  id: domain_design
  name: Domain Design
  icon: git-branch
  phase: construction

parent: bolt

lifecycle:
  initial: draft
  states:
    - id: draft
      label: Draft
      actor: system
    - id: in_review
      label: In review
      actor: human
      handoff: true
    - id: approved
      label: Approved
      actor: human
    - id: superseded
      label: Superseded
      actor: system
      terminal: true

schema:
  type: object
  properties:
    summary:
      type: string
      required: true
      description: Markdown summary of the domain design.
    aggregates_notes:
      type: string
      required: false
      description: Markdown explanation of aggregate boundaries and invariants.
    entity_notes:
      type: string
      required: false
      description: Markdown explanation of entities and value objects.
    event_notes:
      type: string
      required: false
      description: Markdown explanation of domain events and triggers.

document:
  sections:
    - id: summary
      title: Summary
      field: summary
      kind: markdown
    - id: aggregates
      title: Aggregates and invariants
      field: aggregates_notes
      kind: markdown
    - id: entities
      title: Entities and value objects
      field: entity_notes
      kind: markdown
    - id: events
      title: Domain events
      field: event_notes
      kind: markdown

​
walkthrough

walkthrough is the human-readable execution narrative for the bolt. 
artifact:
  id: walkthrough
  name: Walkthrough
  icon: file-text
  phase: construction

parent: bolt

lifecycle:
  initial: draft
  states:
    - id: draft
      label: Draft
      actor: system
    - id: ready_for_review
      label: Ready for review
      actor: agent
    - id: verified
      label: Verified
      actor: human
      handoff: true
    - id: superseded
      label: Superseded
      actor: system
      terminal: true

schema:
  type: object
  properties:
    summary:
      type: string
      required: true
      description: Markdown summary of what changed and why.
    implementation_notes:
      type: string
      required: false
      description: Markdown explanation of the implementation.
    verification_summary:
      type: string
      required: true
      description: Markdown summary of the checks that were run.
    touched_files:
      type: array
      required: false
      items:
        type: string
      description: Repository-relative files touched while executing the bolt.

document:
  sections:
    - id: summary
      title: Summary
      field: summary
      kind: markdown
    - id: implementation
      title: Implementation notes
      field: implementation_notes
      kind: markdown
    - id: verification
      title: Verification
      field: verification_summary
      kind: markdown
Fabriqa can still attach built-in metadata such as touched_workspace_project_ids and tags to walkthrough without repeating them in the schema.

​
Prompt-driven, schema-informed

The prompts still decide:
  • when a bolt is ready
  • when to create system_context
  • when implementation_plan is necessary
  • when to emit walkthrough and test_report
The DSL tells the agents:
  • what those artifacts are
  • where they belong
  • which fields are mandatory
  • how they are structured as documents

AI-DLC overview

Go back to the AI-DLC overview page.

AI-DLC artifacts

Revisit the artifact meanings and execution artifact model.

Workflow DSL artifact schemas

Compare AI-DLC artifact design with the general DSL reference.

Workflow glossary

Keep the shared workflow vocabulary close while reviewing the definition.