fdsx 0.2.2__tar.gz → 0.2.3__tar.gz

{fdsx-0.2.2 → fdsx-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fdsx
-Version: 0.2.2
+Version: 0.2.3
 Summary: Declarative AI agent workflow execution framework
 Author: kenfdev
 License-Expression: MIT
@@ -50,8 +50,10 @@ fdsx enables you to define AI agent workflows in YAML, combining the durability
 
 **Key features:**
 - Declarative YAML-based workflow definition
+- Interactive project initialization and scaffolding
 - Stateful execution with checkpoint/resume
 - Parallel execution with branch aggregation
+- Map state for iterating over arrays with sub-workflows
 - Batch task processing (in-memory and persistent)
 - Multiple LLM provider support (Claude, Codex, Gemini, OpenCode, and system commands)
 - Named profiles for reusable provider/model configuration
@@ -74,6 +76,14 @@ uv tool install fdsx
 
 ## Quick Start
 
+Initialize a new project:
+
+```bash
+fdsx init
+```
+
+This interactively scaffolds a `.fdsx/` directory with configuration and example workflows.
+
 Create a simple YAML workflow file:
 
 ```yaml
@@ -286,7 +296,7 @@ states:
           result_path: $.iter.step2
           retry: 0
     fail_fast: true                     # (bool, default: true) stop all iterations on first failure
-    result_path: $.map_results           # (string, optional) JSONPath for the results array
+    result_path: $.map_results           # (string, REQUIRED) JSONPath for the results array
     max_iterations: 10                  # (int, optional) max times this state can be re-entered
     hooks:                              # (optional)
     next: after_map                     # next / end — same rules as task
@@ -446,6 +456,10 @@ workflows_dir: .fdsx/workflows    # (string, default: ".fdsx/workflows")
                                   #   must be relative, no ".." components
                                   #   where `fdsx run --tasks-dir` discovers workflows
 
+# --- Default tasks directory ---
+default_tasks_dir: .fdsx/tasks    # (string, optional) default directory for bare `fdsx run`
+                                  #   when no workflow, --tasks, or --tasks-dir is given
+
 # --- Auto-workflow selection ---
 auto_workflow: false              # (bool, default: false) skip interactive confirmation UI
 
@@ -457,7 +471,7 @@ workflow_selector:
   extra_instructions: |           # (string, optional) appended to the selection prompt
     Prefer simple-impl for small tasks.
 
-# --- Task splitter: LLM used by `fdsx split` ---
+# --- Task splitter: LLM used by `fdsx add --split` ---
 task_splitter:
   profile: smarty                 # (string, optional) profile ref — mutually exclusive with provider/model
   # provider: claude              # (string, default: "claude")
@@ -477,6 +491,8 @@ providers:
     dangerously_skip_permissions: true   # (bool, default: false)
     allowed_tools: []                    # (list of strings, default: []) tool allowlist
     disallowed_tools: []                 # (list of strings, default: []) tool denylist
+    system_prompt: "Custom system prompt"  # (string, optional) override the default system prompt
+    append_system_prompt: "Extra instructions"  # (string, optional) append to the default system prompt
     inactivity_timeout: 600              # (int, optional) seconds before killing inactive subprocess
 
   codex:
@@ -526,6 +542,9 @@ hooks:
 
 | Command | Description |
 |---------|-------------|
+| `fdsx init` | Initialize a new fdsx project with interactive setup |
+| `fdsx init --skill` | Install the /fdsx Claude Code skill only (skip scaffold) |
+| `fdsx run` | Execute tasks from default tasks directory (`default_tasks_dir` or `.fdsx/tasks/`) |
 | `fdsx run <workflow.yaml>` | Execute a workflow |
 | `fdsx run <workflow.yaml> --input key=value` | Pass input variables |
 | `fdsx run <workflow.yaml> --tasks tasks.yaml` | In-memory batch execution |
@@ -538,8 +557,9 @@ hooks:
 | `fdsx validate <workflow.yaml>` | Validate YAML syntax |
 | `fdsx list` | List recent runs |
 | `fdsx list --base-dir <dir>` | List runs from custom base directory |
-| `fdsx split <task_file>` | Split a task file into individual task files |
-| `fdsx split <task_file> --force` | Clear existing tasks directory before splitting |
+| `fdsx add <task_file>` | Add a task file to the batch execution queue (single task) |
+| `fdsx add <task_file> --split` | Split a task file into individual task files |
+| `fdsx add <task_file> --split --force` | Clear existing tasks directory before splitting |
 
 ## Example Workflow
 
@@ -610,8 +630,8 @@ states:
 
 Run this example:
 ```bash
-# First run in a new directory scaffolds .fdsx/ with example workflows:
-fdsx run
+# Initialize the project (creates .fdsx/ with config and example workflows):
+fdsx init
 
 # Then run the scaffolded example workflow:
 fdsx run .fdsx/workflows/plan-implement-review/workflow.yaml --input task="Build a web calculator"

{fdsx-0.2.2 → fdsx-0.2.3}/README.md

@@ -10,8 +10,10 @@ fdsx enables you to define AI agent workflows in YAML, combining the durability
 
 **Key features:**
 - Declarative YAML-based workflow definition
+- Interactive project initialization and scaffolding
 - Stateful execution with checkpoint/resume
 - Parallel execution with branch aggregation
+- Map state for iterating over arrays with sub-workflows
 - Batch task processing (in-memory and persistent)
 - Multiple LLM provider support (Claude, Codex, Gemini, OpenCode, and system commands)
 - Named profiles for reusable provider/model configuration
@@ -34,6 +36,14 @@ uv tool install fdsx
 
 ## Quick Start
 
+Initialize a new project:
+
+```bash
+fdsx init
+```
+
+This interactively scaffolds a `.fdsx/` directory with configuration and example workflows.
+
 Create a simple YAML workflow file:
 
 ```yaml
@@ -246,7 +256,7 @@ states:
           result_path: $.iter.step2
           retry: 0
     fail_fast: true                     # (bool, default: true) stop all iterations on first failure
-    result_path: $.map_results           # (string, optional) JSONPath for the results array
+    result_path: $.map_results           # (string, REQUIRED) JSONPath for the results array
     max_iterations: 10                  # (int, optional) max times this state can be re-entered
     hooks:                              # (optional)
     next: after_map                     # next / end — same rules as task
@@ -406,6 +416,10 @@ workflows_dir: .fdsx/workflows    # (string, default: ".fdsx/workflows")
                                   #   must be relative, no ".." components
                                   #   where `fdsx run --tasks-dir` discovers workflows
 
+# --- Default tasks directory ---
+default_tasks_dir: .fdsx/tasks    # (string, optional) default directory for bare `fdsx run`
+                                  #   when no workflow, --tasks, or --tasks-dir is given
+
 # --- Auto-workflow selection ---
 auto_workflow: false              # (bool, default: false) skip interactive confirmation UI
 
@@ -417,7 +431,7 @@ workflow_selector:
   extra_instructions: |           # (string, optional) appended to the selection prompt
     Prefer simple-impl for small tasks.
 
-# --- Task splitter: LLM used by `fdsx split` ---
+# --- Task splitter: LLM used by `fdsx add --split` ---
 task_splitter:
   profile: smarty                 # (string, optional) profile ref — mutually exclusive with provider/model
   # provider: claude              # (string, default: "claude")
@@ -437,6 +451,8 @@ providers:
     dangerously_skip_permissions: true   # (bool, default: false)
     allowed_tools: []                    # (list of strings, default: []) tool allowlist
     disallowed_tools: []                 # (list of strings, default: []) tool denylist
+    system_prompt: "Custom system prompt"  # (string, optional) override the default system prompt
+    append_system_prompt: "Extra instructions"  # (string, optional) append to the default system prompt
     inactivity_timeout: 600              # (int, optional) seconds before killing inactive subprocess
 
   codex:
@@ -486,6 +502,9 @@ hooks:
 
 | Command | Description |
 |---------|-------------|
+| `fdsx init` | Initialize a new fdsx project with interactive setup |
+| `fdsx init --skill` | Install the /fdsx Claude Code skill only (skip scaffold) |
+| `fdsx run` | Execute tasks from default tasks directory (`default_tasks_dir` or `.fdsx/tasks/`) |
 | `fdsx run <workflow.yaml>` | Execute a workflow |
 | `fdsx run <workflow.yaml> --input key=value` | Pass input variables |
 | `fdsx run <workflow.yaml> --tasks tasks.yaml` | In-memory batch execution |
@@ -498,8 +517,9 @@ hooks:
 | `fdsx validate <workflow.yaml>` | Validate YAML syntax |
 | `fdsx list` | List recent runs |
 | `fdsx list --base-dir <dir>` | List runs from custom base directory |
-| `fdsx split <task_file>` | Split a task file into individual task files |
-| `fdsx split <task_file> --force` | Clear existing tasks directory before splitting |
+| `fdsx add <task_file>` | Add a task file to the batch execution queue (single task) |
+| `fdsx add <task_file> --split` | Split a task file into individual task files |
+| `fdsx add <task_file> --split --force` | Clear existing tasks directory before splitting |
 
 ## Example Workflow
 
@@ -570,8 +590,8 @@ states:
 
 Run this example:
 ```bash
-# First run in a new directory scaffolds .fdsx/ with example workflows:
-fdsx run
+# Initialize the project (creates .fdsx/ with config and example workflows):
+fdsx init
 
 # Then run the scaffolded example workflow:
 fdsx run .fdsx/workflows/plan-implement-review/workflow.yaml --input task="Build a web calculator"
@@ -592,4 +612,4 @@ fdsx list
 
 ## License
 
-MIT License.
+MIT License.

{fdsx-0.2.2 → fdsx-0.2.3}/src/fdsx/data/skills/fdsx/SKILL.md

@@ -4,10 +4,11 @@ description: >
   Expert guide for authoring, validating, and running fdsx declarative AI agent
   workflow YAML files. Use when writing fdsx workflows, editing workflow YAML,
   configuring fdsx providers (claude, codex, opencode, gemini), setting up
-  profiles, adding hooks, using choice/parallel/loop/wait/pass states, running
+  profiles, adding hooks, using choice/parallel/loop/wait/pass/map states, running
   fdsx CLI commands, debugging workflow validation errors, or asking about fdsx
   YAML schema. Also triggers on: "fdsx", "workflow YAML", "declarative agent
-  workflow", "multi-step AI pipeline", "provider options", "checkpoint resume".
+  workflow", "multi-step AI pipeline", "provider options", "checkpoint resume",
+  "map state", "iterator".
 ---
 
 # fdsx Workflow Authoring Guide
@@ -56,6 +57,7 @@ Read `references/yaml-schema.md` for the complete field-by-field schema referenc
 | `parallel` | Execute multiple branches concurrently | `branches`, `result_path`, `result_file`, `min_success` |
 | `pass` | Data transformation / aggregation | `parameters`, `aggregate` |
 | `wait` | Human input via terminal prompt | `mode: prompt`, `message`, `choices`, `result_path` |
+| `map` | Iterate over an array, execute sub-workflow per item | `items_path`, `iterator`, `result_path`, `fail_fast` |
 
 Every state except `choice` supports `next` (go to state) or `end: true` (terminate flow). These are mutually exclusive.
 
@@ -97,7 +99,7 @@ states:
 
 `profile` and explicit `provider`/`model` are mutually exclusive (XOR). Profiles can also be defined in `.fdsx/config.yaml` and are merged (workflow-level overrides config-level).
 
-Profile shorthand is supported on task states, parallel branches, and extract fallback configurations.
+Profile shorthand is supported on task states, parallel branches, and extract fallback configurations. Note: profile shorthand is **not** supported on map iterator task states.
 
 ## Variable Substitution
 
@@ -131,17 +133,24 @@ extract:
 ## CLI Commands
 
 ```
-fdsx run <workflow.yaml> [--input KEY=VALUE] [--tasks <file>] [--tasks-dir <dir>] [--thread-id <id>] [--quiet] [--auto-workflow] [--confirm-workflow]
+fdsx run [<workflow.yaml>] [--input KEY=VALUE] [--tasks <file>] [--tasks-dir <dir>] [--thread-id <id>] [--quiet] [--auto-workflow] [--confirm-workflow]
 fdsx validate <workflow.yaml>
 fdsx resume --thread-id <id> [--base-dir <path>]
 fdsx list [--base-dir <path>]
-fdsx split <task-file> [--force]
+fdsx add <task-file> [--split] [--force]
+fdsx init [--skill]
 fdsx --version
 fdsx --ci | --interactive        # global flags (mutually exclusive)
 ```
 
 `--auto-workflow` and `--confirm-workflow` are mutually exclusive. `--auto-workflow` skips interactive workflow confirmation; `--confirm-workflow` forces the confirmation UI.
 
+When `fdsx run` is invoked with no workflow, no `--tasks-dir`, no `--tasks`, and no `--input`, it falls back to the `default_tasks_dir` config value (default: `.fdsx/tasks/`) and runs in tasks-dir mode.
+
+`fdsx add <task-file>` adds a task file to the batch execution queue. Use `--split` to invoke the LLM task splitter to break the file into multiple task files in `.fdsx/tasks/`. Use `--force` to clear existing tasks before writing.
+
+`fdsx init` initializes a new fdsx project with interactive provider and template selection. Use `--skill` to install only the Claude Code skill without scaffolding `.fdsx/`.
+
 ## Hooks
 
 Shell commands that run before/after state or flow execution:
@@ -169,6 +178,7 @@ Hook data files are written to `.fdsx/runs/<thread-id>/hooks/<state-name>/input.
 ```yaml
 auto_workflow: false            # skip workflow confirmation UI (default: false)
 workflows_dir: .fdsx/workflows  # directory for workflow discovery
+default_tasks_dir: .fdsx/tasks/ # default tasks directory for no-arg fdsx run
 workflow_selector:
   provider: claude              # LLM for auto-selecting workflows
   model: claude-sonnet-4-6
@@ -192,6 +202,36 @@ Use `parallel` → `pass` (with `aggregate`) → `choice` to fan out reviews, ag
 **Human gate:**
 Use `wait` state with `mode: prompt` to pause for user input, then route with `choice`.
 
+**Map over items (e.g., process each file):**
+Use a preceding state to produce an array, then `map` to iterate over it with a sub-workflow per item:
+
+```yaml
+states:
+  collect:
+    type: task
+    provider: system
+    command: "echo '[{\"path\":\"a.py\"},{\"path\":\"b.py\"}]'"
+    result_path: $.files
+    next: process_each
+
+  process_each:
+    type: map
+    items_path: $.files
+    iterator:
+      states:
+        - type: task
+          name: review
+          provider: claude
+          model: claude-sonnet-4-6
+          prompt_template: "Review file: {item.path}"
+          result_path: $.review
+    result_path: $.reviews
+    fail_fast: true
+    end: true
+```
+
+Inside iterator states, `{item}` refers to the current array element. Use `{item.field}` for nested access.
+
 ## Validation Rules
 
 - `start_at` must reference an existing state name
@@ -200,4 +240,5 @@ Use `wait` state with `mode: prompt` to pause for user input, then route with `c
 - `prompt_template` and `prompt_file` are mutually exclusive
 - `next` and `end` are mutually exclusive
 - `result_file` must be a top-level `$.varname` path (no nesting)
-- Extract `result_path` must not use reserved keys: `output`, `exit_code`, `error`
+- Extract `result_path` must not use reserved keys: `output`, `exit_code`, `error`
+- Map iterator states must all have `type: task` and unique `name` fields

{fdsx-0.2.2 → fdsx-0.2.3}/src/fdsx/data/skills/fdsx/references/yaml-schema.md

@@ -10,6 +10,9 @@ Complete field-by-field reference for fdsx workflow YAML files, derived from the
 - [ParallelState](#parallelstate)
 - [PassState](#passstate)
 - [WaitState](#waitstate)
+- [MapState](#mapstate)
+- [IteratorDef](#iteratordef)
+- [IteratorTaskState](#iteratortaskstate)
 - [Branch (parallel)](#branch)
 - [ExtractRule](#extractrule)
 - [ChoiceRule](#choicerule)
@@ -35,6 +38,8 @@ hooks?: HookConfig              # optional — flow-level hooks
 profiles?: {name: {k: v}}       # optional — raw provider/model/extras dicts
 ```
 
+**State** is a discriminated union on the `type` field: `TaskState | ChoiceState | ParallelState | PassState | WaitState | MapState`.
+
 **Profiles at workflow level** are raw YAML dicts (`{provider, model, ...extras}`), not validated `ProfileConfig` objects. Profile resolution happens pre-validation: `profile` references in tasks/branches are expanded into `provider`/`model`/`provider_options` fields before Pydantic validation runs. Workflow-level profiles override config-level profiles (full replacement per name, not deep merge).
 
 **Validation:**
@@ -148,6 +153,77 @@ notify:
 
 ---
 
+## MapState
+
+```yaml
+type: "map"                     # literal discriminator
+items_path: string              # required — JSONPath to input array
+iterator: IteratorDef           # required — sub-workflow to execute for each item
+result_path: string             # required — JSONPath for results array
+fail_fast?: bool                # default: true — stop on first failure
+max_iterations?: int            # optional — >=1, max times this state can be entered
+hooks?: HookConfig              # optional — per-state hooks
+next?: string                   # XOR with end — target state
+end?: bool                      # XOR with next — terminate flow
+```
+
+**Variable context inside iterator:** Each iterator state receives the current array element as `{item}`. References like `{item.field}` access nested fields of the current element. Variables from preceding states in the outer flow are also available.
+
+**Validation:**
+- `next` and `end` are mutually exclusive
+- `items_path` must reference a variable set by a preceding state
+- Iterator states must all have `type: "task"` (no nested choice/parallel/pass/wait/map)
+- Iterator state names must be unique within the iterator
+
+---
+
+## IteratorDef
+
+Used inside `MapState.iterator`:
+
+```yaml
+iterator:
+  states: [IteratorTaskState]   # required — min 1 item, ordered list of task states
+```
+
+**Validation:**
+- All states must have `type: "task"` (non-task types are rejected)
+- State names must be unique within the iterator
+
+---
+
+## IteratorTaskState
+
+Used inside `IteratorDef.states`:
+
+```yaml
+type: "task"                    # literal discriminator (only "task" allowed)
+name: string                    # required — state name within the iterator
+provider: string                # required — claude|codex|opencode|gemini|system
+model?: string                  # required for LLM providers, forbidden for system
+prompt_template?: string        # XOR with prompt_file; required for LLM providers
+prompt_file?: string            # XOR with prompt_template; relative path
+command?: string                # required for system, forbidden for LLM providers
+result_path: string             # required — JSONPath for result
+result_file?: string            # optional — top-level $.varname only (no nesting)
+extract?: ExtractRule           # optional — output extraction
+retry?: int                     # default: 3
+timeout_seconds?: int           # optional — per-state timeout override
+provider_options?: {k: v}       # optional — per-task provider option overrides
+```
+
+**Differences from TaskState:** Has a required `name` field. Does not support `max_iterations`, `hooks`, `next`, or `end` (iteration order is determined by list position).
+
+**Note:** Profile shorthand (`profile: <name>`) is not currently supported on iterator task states. Use explicit `provider`/`model` fields.
+
+**Validation:**
+- `prompt_template` and `prompt_file` are mutually exclusive
+- `result_path` and `extract.result_path` must not overlap
+- `result_file` must match `$.varname` (no dots or brackets after `$.`)
+- Same provider field validation rules as TaskState
+
+---
+
 ## Branch
 
 Used inside `ParallelState.branches`:

{fdsx-0.2.2 → fdsx-0.2.3}/src/fdsx.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fdsx
-Version: 0.2.2
+Version: 0.2.3
 Summary: Declarative AI agent workflow execution framework
 Author: kenfdev
 License-Expression: MIT
@@ -50,8 +50,10 @@ fdsx enables you to define AI agent workflows in YAML, combining the durability
 
 **Key features:**
 - Declarative YAML-based workflow definition
+- Interactive project initialization and scaffolding
 - Stateful execution with checkpoint/resume
 - Parallel execution with branch aggregation
+- Map state for iterating over arrays with sub-workflows
 - Batch task processing (in-memory and persistent)
 - Multiple LLM provider support (Claude, Codex, Gemini, OpenCode, and system commands)
 - Named profiles for reusable provider/model configuration
@@ -74,6 +76,14 @@ uv tool install fdsx
 
 ## Quick Start
 
+Initialize a new project:
+
+```bash
+fdsx init
+```
+
+This interactively scaffolds a `.fdsx/` directory with configuration and example workflows.
+
 Create a simple YAML workflow file:
 
 ```yaml
@@ -286,7 +296,7 @@ states:
           result_path: $.iter.step2
           retry: 0
     fail_fast: true                     # (bool, default: true) stop all iterations on first failure
-    result_path: $.map_results           # (string, optional) JSONPath for the results array
+    result_path: $.map_results           # (string, REQUIRED) JSONPath for the results array
     max_iterations: 10                  # (int, optional) max times this state can be re-entered
     hooks:                              # (optional)
     next: after_map                     # next / end — same rules as task
@@ -446,6 +456,10 @@ workflows_dir: .fdsx/workflows    # (string, default: ".fdsx/workflows")
                                   #   must be relative, no ".." components
                                   #   where `fdsx run --tasks-dir` discovers workflows
 
+# --- Default tasks directory ---
+default_tasks_dir: .fdsx/tasks    # (string, optional) default directory for bare `fdsx run`
+                                  #   when no workflow, --tasks, or --tasks-dir is given
+
 # --- Auto-workflow selection ---
 auto_workflow: false              # (bool, default: false) skip interactive confirmation UI
 
@@ -457,7 +471,7 @@ workflow_selector:
   extra_instructions: |           # (string, optional) appended to the selection prompt
     Prefer simple-impl for small tasks.
 
-# --- Task splitter: LLM used by `fdsx split` ---
+# --- Task splitter: LLM used by `fdsx add --split` ---
 task_splitter:
   profile: smarty                 # (string, optional) profile ref — mutually exclusive with provider/model
   # provider: claude              # (string, default: "claude")
@@ -477,6 +491,8 @@ providers:
     dangerously_skip_permissions: true   # (bool, default: false)
     allowed_tools: []                    # (list of strings, default: []) tool allowlist
     disallowed_tools: []                 # (list of strings, default: []) tool denylist
+    system_prompt: "Custom system prompt"  # (string, optional) override the default system prompt
+    append_system_prompt: "Extra instructions"  # (string, optional) append to the default system prompt
     inactivity_timeout: 600              # (int, optional) seconds before killing inactive subprocess
 
   codex:
@@ -526,6 +542,9 @@ hooks:
 
 | Command | Description |
 |---------|-------------|
+| `fdsx init` | Initialize a new fdsx project with interactive setup |
+| `fdsx init --skill` | Install the /fdsx Claude Code skill only (skip scaffold) |
+| `fdsx run` | Execute tasks from default tasks directory (`default_tasks_dir` or `.fdsx/tasks/`) |
 | `fdsx run <workflow.yaml>` | Execute a workflow |
 | `fdsx run <workflow.yaml> --input key=value` | Pass input variables |
 | `fdsx run <workflow.yaml> --tasks tasks.yaml` | In-memory batch execution |
@@ -538,8 +557,9 @@ hooks:
 | `fdsx validate <workflow.yaml>` | Validate YAML syntax |
 | `fdsx list` | List recent runs |
 | `fdsx list --base-dir <dir>` | List runs from custom base directory |
-| `fdsx split <task_file>` | Split a task file into individual task files |
-| `fdsx split <task_file> --force` | Clear existing tasks directory before splitting |
+| `fdsx add <task_file>` | Add a task file to the batch execution queue (single task) |
+| `fdsx add <task_file> --split` | Split a task file into individual task files |
+| `fdsx add <task_file> --split --force` | Clear existing tasks directory before splitting |
 
 ## Example Workflow
 
@@ -610,8 +630,8 @@ states:
 
 Run this example:
 ```bash
-# First run in a new directory scaffolds .fdsx/ with example workflows:
-fdsx run
+# Initialize the project (creates .fdsx/ with config and example workflows):
+fdsx init
 
 # Then run the scaffolded example workflow:
 fdsx run .fdsx/workflows/plan-implement-review/workflow.yaml --input task="Build a web calculator"