fastworkflow

Load this skill when you need to understand or preserve fastWorkflow's load-bearing runtime design before changing core code: anything touching WorkflowExecutionContext, ChatSession, the CME/wildcard NLU pipeline, ask_user suspension/resume, AskUserSuspend / CommandCancelledError, SessionStateStore, TurnResult/TurnOutput/process_turn, the TurnRegistry turns engine, context models, or session serialization. Trigger phrases: "why is this a BaseException", "Topology A vs Topology B", "where does the turn get finalized", "is it safe to run two turns on one channel", "what breaks if I rename a command", "what is the cme workflow", "context_hierarchy_model". Do NOT load it for step-by-step debugging of a failure (use fastworkflow-debugging-playbook), for running the server/CLI (fastworkflow-run-and-operate), for model/threshold details of the NLU stack (fastworkflow-nlu-pipeline-reference), or for env-var/flag lookups (fastworkflow-config-and-flags).

Load this skill when setting up the fastWorkflow dev environment from scratch or fixing a broken one: fresh clone, "which Python / poetry install / pip extras do I need", "tests are all skipping", "FileNotFoundError threshold.json", "make gen-env fails", "where do API keys go", "env/.env vs passwords/.env vs fastworkflow.env", or re-provisioning after the hello_world model was wiped. Do NOT load it for running/operating workflows (fastworkflow-run-and-operate), the full env-var catalog (fastworkflow-config-and-flags), test-writing policy (fastworkflow-validation-and-qa), or debugging runtime failures (fastworkflow-debugging-playbook).

Load this skill BEFORE making any change to the fastWorkflow repo that touches git, beads (bd), version numbers, tests, or documents in docs/. Triggers: "commit this", "push", "bump the version", "close the issue", "bd create/update/close", "delete this test", "clean up docs/", "should this get a design doc?", "is this a patch or a minor?", "can I commit the skills library?". Also load when you see symptoms like a bd close that didn't stick, an epic that looks shipped but shows open, or untracked team-private docs in git status. Do NOT load for debugging runtime failures (use fastworkflow-debugging-playbook), for running/operating the app (fastworkflow-run-and-operate), or for how-to-test mechanics (fastworkflow-validation-and-qa).

Load this skill whenever you touch fastWorkflow configuration: any LLM_* / LITELLM_API_KEY_* / SPEEDDICT_FOLDERNAME / INTENT_DETECTION_* / SESSION_STATE_* env var, the fastworkflow.env or fastworkflow.passwords.env files, a fastworkflow CLI subcommand or flag, LiteLLM proxy routing, or JWT server settings. Trigger symptoms: "env var not found" warnings, "SPEEDDICT_FOLDERNAME env var not found!", "DSPy Language Model not provided", shell exports being mysteriously ignored, refine failing with a missing-LM ValueError, or needing to add a new config knob. Do NOT use it for how to run/operate workflows end to end (fastworkflow-run-and-operate), recreating the dev environment and secrets (fastworkflow-build-and-env), or debugging non-config runtime failures (fastworkflow-debugging-playbook).

Symptom-to-triage playbook for fastWorkflow runtime, build, and train failures. Load this when you see: the wrong command being matched, "threshold.json not found" / FileNotFoundError in ___command_info, the internal CME workflow retraining on every `fastworkflow train`, parameter extraction looping on NOT_FOUND, the CLI hanging or never printing an agent question, FastAPI 409/202 surprises or "poll /turns" advice, DeprecationWarning about process_message, commands with too few training utterances, stale/frozen LLM outputs (DSPy cache), RocksDB/speedict lock errors, env vars that "don't take effect", or tests that mysteriously pass/fail/skip. Do NOT load this for writing new tests (fastworkflow-validation-and-qa), env-var reference (fastworkflow-config-and-flags), historical post-mortems (fastworkflow-failure-archaeology), or tau2 benchmark work (tau2-reliability-campaign).

Load this skill when you need to MEASURE a fastWorkflow workflow instead of eyeballing it — inspect ___command_info trained artifacts, check whether cached command snapshots are stale (fingerprint FRESH/STALE), capture or read a turn's command traces / action.jsonl, smoke-test intent-classifier accuracy, configure LOG_LEVEL, inspect the DSPy LLM cache, or hit the server probe endpoints. Trigger phrases/symptoms: "why did it rebuild", "is this workflow trained", "what did the agent actually do", "traces are empty", "stale cache", "threshold.json", "confusion between commands", "cache hit hides the LLM call". Do NOT load for diagnosing a specific failure end-to-end (use fastworkflow-debugging-playbook), for NLU/model theory (use fastworkflow-nlu-pipeline-reference), or for statistics like pass^k variance (use fastworkflow-proof-and-analysis-toolkit).

Load when writing, editing, or citing any fastWorkflow documentation or public claim — README changes, design docs, articles, benchmark numbers, DOIs, "which doc is authoritative?", "can we say/publish X?", "the README/CLAUDE.md says...", starting a new design doc or design review, or handling the team-private docs in docs/. Triggers include "article" (there are TWO colliding series), "DOI", "Tau Bench results", "positioning", "doc rot", "commit message style". Do NOT load for running the code (use fastworkflow-run-and-operate), the statistical evidence bar for experiments (fastworkflow-research-methodology), tau-bench mechanics (fastworkflow-taubench-reference), or the change-gating process itself (fastworkflow-change-control).

Load this when you are about to investigate, revert, re-attempt, or "clean up" something in fastWorkflow and suspect a battle may already have been fought: symptoms like "this bug looks old", "why does this dead code / legacy file exist", "should we just delete X", "the revert didn't revert", "bd close didn't stick", "payload is None in agent mode", "why was feature Y removed", or "did we already try this approach". Also load before proposing any feature that resembles: command dependency graphs, a standalone FastAPI service, probabilistic response generation, rich CLI, ensemble intent voting, or RLM-style memory layers — all have prior art documented here. Do NOT load for live triage of a current failure (use fastworkflow-debugging-playbook), for the rules governing changes (fastworkflow-change-control), or for how the architecture is supposed to work (fastworkflow-architecture-contract).

Domain reference for fastWorkflow's NLU stack AS IMPLEMENTED IN THIS REPO: two-tier TinyBERT/DistilBERT intent classifiers, confidence thresholds, synthetic utterance generation (litellm + PersonaHub), DSPy parameter extraction, runtime matching layers (fuzzy/embedding-cache/classifier), and per-role litellm model routing. Load this when you hear: "wrong command predicted", "ambiguous intent", "intent detection", "parameter extraction returned NOT_FOUND", "threshold.json", "confidence threshold", "utterance generation", "DSPy signature/cache", "LabeledFewShot", "litellm_proxy", "why did the classifier pick X", or when modifying anything under model_pipeline_training.py, intent_detection.py, signatures.py, generate_synthetic.py, or cache_matching.py. Do NOT load for step-by-step failure triage (use fastworkflow-debugging-playbook), the full env-var catalog (fastworkflow-config-and-flags), or tau-bench benchmark mechanics (fastworkflow-taubench-reference).

Load when you are about to propose, run, review, accept, or retire a research idea or experiment in this repo — trigger phrases include "I have a hypothesis", "let's try adding X and see if the score improves", "the numbers went up so it works", "should we pin the simulator temperature", "write up this experiment", "is this result real", "kill this idea", or any request to design an E-card / pre-registration / adversarial review. Do NOT load for executing the tau2 campaign step-by-step (use tau2-reliability-campaign), for statistics recipes and pass^k math (use fastworkflow-proof-and-analysis-toolkit), for picking WHICH open problem to work on (use fastworkflow-research-frontier), or for ordinary bug fixing (use fastworkflow-debugging-playbook).

Operate fastWorkflow at runtime: use when you need to run the CLI (examples/build/refine/ train/run/run_fastapi_mcp), fetch or pick a bundled example workflow, do the quickstart, understand agent vs assistant vs "/" deterministic mode, identify or clean runtime artifacts (___command_info, ___workflow_contexts, ___convo_info, action.jsonl, jwt_keys), launch or call the FastAPI+MCP server (endpoints, 202/409 turns semantics, JWT/security posture), or when you see symptoms like "workflow is not trained", HTTP 409 "turn already in progress", a hanging 202 response, or "server extra not installed". Do NOT use for training internals or intent-model tuning (fastworkflow-nlu-pipeline-reference), env-var semantics (fastworkflow-config-and-flags), dev-environment setup (fastworkflow-build-and-env), or tau-bench benchmark runs (fastworkflow-taubench-reference / tau2-reliability-campaign).

What counts as evidence in fastWorkflow: the real state of the 495-test pytest suite, which tests skip/no-op and why, the golden test workflows and trained artifacts you must never destroy, how to add integration tests, and the acceptance bar before a release tag. Load this when you are about to run the test suite, interpret pass/fail/skip results, add or modify tests, decide whether "CI is green" means anything (it barely does), or judge whether a change has enough evidence to ship. Symptoms that trigger it: "tests pass but should they?", "why did 4 FastAPI tests suddenly fail with FileNotFoundError on threshold.json", "can I mock this?", "is this test flaky?", "what do I run before tagging a release?". Do NOT load it for debugging a failing feature (fastworkflow-debugging-playbook), for running the app itself (fastworkflow-run-and-operate), or for pass^k reliability measurement design (tau2-reliability-campaign / fastworkflow-proof-and-analysis-toolkit).

Integrate a fastWorkflow-based agentic chat agent into an existing application so users can execute the app's business logic and ask questions in natural language, with a popup chat UI that streams internal workflow/assistant conversations before the final answer. Use when a developer asks to add a chat agent, conversational UI, natural-language interface, or fastWorkflow backend to their app, or mentions "AI-enabling" their application.

Uses bd (beads) for issue tracking. Use when finding work, claiming or closing issues, syncing with git, or when the user mentions bd, beads, issues, or tasks.

Completes work sessions by running quality gates, syncing bd, pushing to remote, and handing off. Use when ending a work session, landing the plane, session completion, or when the user asks to wrap up or finish work.