YADA

YADA (Yet Another Devising Assistant) is a deterministic DAG orchestration library with CLI interface. It compiles declarative Design Prescriptions (DPs) into executable workflow graphs.

Key Features

• Production-ready npm package - Install via npm install yada-kit
• Dependency Graph Engine - Parses and resolves complex dependencies
• Deterministic Compilation - Predictable execution order based on priority
• Parallel Level Grouping - Identifies parallelizable tasks
• State Persistence - Tracks progress with .yadasmith file
• CLI & Programmatic API - Use as CLI tool or import as library

---

Installation

npm install yada-kit
yada --help

---

Project Structure

your-project/
├── dps/                          # Design Prescriptions directory
│   ├── 01-setup.yada
│   ├── 02-architecture.yada
│   └── 03-implementation.yada
└── .yadasmith                    # Compiled workflow (auto-generated)

---

Design Prescriptions (DPs)

Basic DP Structure

name: my-feature
nature: standard
phase: development
priority: 50
description: |
  /* Description of what this DP accomplishes */

dependencies:                    # External DP dependencies
  - previous-feature

subdps:
  order: false                   # true = chain subdps 1→2→3
  1:
    name: sub-feature-1
    type: specification          # specification = has workflow steps
    description: |
      /* Description */
    workflow:
      - step 1
      - step 2
    intents:
      - Goal achieved

  2:
    name: sub-feature-2
    type: dependency            # dependency = has prerequisites
    nature: required             # optional | required
    description: |
      /* Description */
    dependencies:
      - sub-feature-1           # Local subdp dependency
    intents:
      - Another goal

DP Fields Reference

Field	Required	Values	Description
name	Yes	string	Human-readable identifier
nature	Yes	module | standard	Module = foundational, Standard = regular
phase	No	string	Phase classification
priority	Yes	number (0-100)	Higher = executed first at same level
description	Yes	string	What this DP accomplishes
dependencies	No	DP IDs	External DP references
subdps.order	Yes	boolean	Chain subdps numerically?
subdp.type	Yes	specification | dependency	Specification = has workflow, Dependency = has deps
subdp.nature	No	optional | required	Only for type=dependency
subdp.workflow	No	string[]	Steps (only for type=specification)
subdp.dependencies	No	string[]	Prerequisites (for type=dependency)
subdp.intents	No	string[]	Goals/intended outcomes

Naming Convention

IMPORTANT: DP filenames MUST use numbered IDs:

01-project-foundation.yada
02-architecture-design.yada
03-infrastructure-setup.yada

Then reference them with those IDs:

dependencies:
  - 01-project-foundation    # Correct
  - project-foundation        # Will fail

---

CLI Commands

Compile Command

Parses all DPs, validates dependencies, builds graph, writes .yadasmith.

# Basic compilation
yada compile

# Verbose output
yada compile --verbose
yada compile -V

# Force recompile (overwrite existing)
yada compile --force

Output Files Generated:

• .yadasmith - Compiled workflow state

Status Command

Shows current workflow progress.

# Basic status
yada status

# Verbose output
yada status --verbose
yada status -V

# JSON output (for scripts)
yada status --json

Mark Command

Mark a task as completed.

# Mark specific task
yada --mark 01-project-foundation

How it works:

• Marks the specified task as completed
• Tasks before it in the execution order remain completed
• Tasks after it remain pending

Check Commands

Validate DPs for errors and missing dependencies.

# Check all DPs
yada --check-dps

# Check specific DP
yada --check-dp 01-setup.yada

# Check with verbose output
yada --check-dps --verbose

What it validates:

• Required fields present
• Dependencies exist
• No circular dependencies
• Subdp types valid
• Priority values valid

Reset Command

Reset all tasks to pending.

# Reset with confirmation
yada reset

# Force reset (skip confirmation)
yada reset --force

Help Command

yada --help
yada -h

Version Command

yada --version
yada -v

---

Programmatic API

Import YADA as Library

import {
  parseAll,
  validateAll,
  resolve,
  readYadasmith,
  writeYadasmith,
  getStatus,
  markOne,
  resetAll
} from 'yada';

Usage Examples

Compile Workflow

import { parseAll, validateAll, resolve, writeYadasmith } from 'yada';

const rootDir = './my-project';

// 1. Parse all DPs
const parseResult = parseAll(rootDir);
if (parseResult.errors.length > 0) {
  console.error('Parse errors:', parseResult.errors);
  process.exit(1);
}

// 2. Validate DPs
const validationResult = validateAll(parseResult.dps);
if (!validationResult.valid) {
  console.error('Validation errors:', validationResult.errors);
  process.exit(1);
}

// 3. Resolve graph
const resolveResult = resolve(parseResult.dps, true);

// 4. Write output
writeYadasmith(rootDir, resolveResult.yadasmith);

console.log(`Compiled ${resolveResult.yadasmith.levels.length} levels`);

Check Task Status

import { readYadasmith, getStatus, getTaskById } from 'yada';

const rootDir = './my-project';
const status = getStatus(rootDir);

console.log(`${status.completed}/${status.total} tasks completed`);

if (status.nextTask) {
  console.log('Next:', status.nextTask.ref);
}

---

Dependency Resolution Logic

How Levels Are Calculated

1. Build Graph - Create adjacency list from DPs
2. Detect Cycles - Fail if circular dependencies found
3. Calculate In-Degrees - Count dependencies per node
4. Start with Level 1 - Nodes with no dependencies
5. BFS Propagation - Level = max(parent level) + 1
6. Group by Level - Parallel tasks same level

Priority Resolution

When multiple tasks are at the same level:

1. Higher priority value executes first
2. Alphabetical order as tiebreaker

---

Best Practices

1. Number Your DPs Sequentially
2. Use Clear Priorities (90-100: Critical, 70-89: High, 50-69: Standard, 1-29: Optional)
3. Group Related Subdps with order: true
4. Document Intents Clearly

---

Examples

Simple Example (3 DPs)

cd example
yada compile --verbose
yada status
yada --mark 01-setup
yada status

Enterprise Example (15 DPs)

cd example2
yada compile --verbose
yada status --json
yada --check-dps
yada --mark 01-project-foundation
yada status

---

Troubleshooting

"DP file not found"

Ensure filename matches exactly (case-sensitive):

# Wrong
yada --check-dp Setup.yada
yada --check-dp 1-setup

# Correct
yada --check-dp 01-setup.yada

"Dependency not found"

Check that:

1. Dependency DP file exists
2. Filename uses numbered ID
3. ID format matches exactly (e.g., 01-setup not setup)

"Circular dependency detected"

Review dependency chain and remove one of the circular references.

---

Summary

Command	Purpose
yada compile	Parse & build workflow
yada status	Show progress
yada --mark <id>	Mark task complete
yada --check-dps	Validate all DPs
yada reset	Reset all tasks

YADA transforms declarative DPs into executable workflows with deterministic ordering and state tracking.

Ready to use: npm install yada-kit