create-workflows

Create Workflows

Goal

Create self-contained .task.md workflows that coordinate independent AI provider invocations through explicit files and artifacts. Treat workflow files as infrastructure: declarative, reviewable, deterministic to validate, and portable across projects that use the same workflow format.

Authoring Workflow

1. Inspect the target project before writing.

   • Find existing .task.md workflows and the workflow schema version if they exist.
   • Reuse provider IDs supplied by the user, already present in existing workflows, or configured in the target project. If none are available, use clear placeholders such as planner, builder, and reviewer and call out that the user must replace them.
   • Do not create or modify provider setup or other non-workflow files.
   • Keep the workflow independent of the skill location and do not reference implementation source files as required context.

2. Define the graph before writing prompts.

   • State the workflow goal, final deliverable, and validation gate.
   • Split work into nodes with explicit ownership and artifact handoff.
   • Add needs only where data or ordering is required. Independent roots should stay parallelizable.
   • Use upstream artifacts for handoff; do not assume providers share memory, sessions, or hidden state.
   • Keep each node's context bounded. Prefer artifact paths, concise findings, or exact file references over repeatedly inlining large upstream outputs.
   • For research, planning, and design work whose complete result matters to a dependent node, pass {{upstream.output_path}} and tell the consumer to open it. Do not reduce the canonical handoff to findings and risk losing detail.

3. Choose node modes conservatively.

   • Use mode: parallel for a normal one-shot invocation with one provider, or when multiple executor providers can run the same prompt independently and their outputs can be consolidated afterward.
   • Keep multi-provider parallel tasks and independent DAG roots read-only unless concurrent mutations are provably disjoint. Add needs edges to serialize nodes that may edit the same project files.
   • Use single-provider mode: sequential only for ordered repeated passes. Its depth is the total invocation count, and one pass's Markdown output is not automatically injected into the next pass. Omitted depth means one pass.
   • Use multi-provider mode: sequential for executor/reviewer loops.
   • Use mode: input for reusable raw-file boundaries. Input nodes have no Markdown body section. An input that remains in the composed workflow must have source; an import-required input may omit it when an importer binds it.
   • Keep DAG concurrency distinct from node mode: independent ready nodes can run concurrently even when each node is sequential.