Documentation / Getting Started
Build workflows with a coding agent
Connect Codex, Claude Code, Antigravity, or any local coding agent with Rippflow's bundled offline documentation and portable skill.
1. Initialize the portable skill
Connect your AI agent (Codex, Claude Code, or Antigravity) by initializing the bundled skill in your repository:
rippflow docs skill --init
rippflow docs skill --init --path .claude/skills/rippflow-docs/SKILL.md--init writes .agents/skills/rippflow-docs/SKILL.md by default (or --path) without overwriting existing files. Use rippflow docs skill to inspect stdout. Bundled docs run offline without remote permissions.
2. Search and read bundled contracts
rippflow docs info --json
rippflow search_docs "workflow handlers" --limit 5 --json
rippflow vector_search_docs "workflow fanin" --limit 5 --json
rippflow get_doc docs/public/workflows.md --json
rippflow get_docs docs/public/workflows.md docs/public/reference/cli.md --json
rippflow get_docs --limit 20 --offset 0 --jsonThe read-only snapshot contains reviewed public documentation; check corpus revision and source hashes first. Vector search uses deterministic lexical hash vectors, not neural embeddings; empty results never define a contract. Reinstall a verified CLI to recover an invalid index. Run rippflow commands --json before remote commands.
3. Prompt your coding agent and verify locally
Copy this prompt into Codex, Claude Code, Antigravity, or your local CLI agent:
Use the Rippflow CLI and bundled documentation to help me build a workflow that processes uploaded documents, runs three analysis handlers in parallel, combines their results, and performs a quality check. Generate one canonical project and its handlers. Discover installed capabilities, bind each phase to an installed runtime group, validate the definition, run local dev and tests, and deploy a local HTTPS endpoint for curl verification. Profile representative workloads and verify each invocation stays within its group memory slice and timeout. Test resource violations and cleanup, inspect machine-readable results, and report unsupported or unverified behavior. For callback workflows, prove authenticated callback receipt and actual downstream execution. Do not deploy remotely without approval.Expected agent command sequence (init → validate → dev → deploy --local):
rippflow docs info --json
rippflow search_docs "parallel fan_in_all outcomes" --limit 5 --json
rippflow get_doc docs/public/workflows.md --json
rippflow init doc-pipeline --lang python
cd doc-pipeline
# Edit workflow, handlers, input, and fixture expectations for your pipeline.
rippflow validate rippflow.yaml --json
rippflow dev --input input.json --report .outputs/dev-run.json
rippflow test --project rippflow.yaml --json
rippflow deploy --local --json
# Start a workflow over HTTPS and inspect saved run results:
curl -sk -X POST https://localhost:8443/v1/workflows/doc-pipeline/run \
-H "Authorization: Bearer $DEPLOY_TOKEN" -H "Content-Type: application/json" -d @input.json
curl -sk https://localhost:8443/v1/runs/latest -H "Authorization: Bearer $DEPLOY_TOKEN"
rippflow deploy --local --status
rippflow deploy --local --stop4. Verify resource boundaries and completion
Use one manifest and workflow. Pin each phase's installed runtime group, memory slice, and deadline.
rippflow test --project rippflow.yaml --profile --json
rippflow inspect --report .outputs/last-run.json --jsonInspect exit codes and profile results: older CLI builds may return zero with a FAIL profile. Test real memory and deadline overruns, cleanup, and downstream suppression. Synthetic memory overrides test report logic only. Record versions, inputs, measurements, and limitations.
| Diagnostic surface | Guaranteed runtime contract |
|---|---|
| Partial run reports & timelines | Failure, phase/callback/workflow timeout, and signal cancellation (exit 130) persist partial RunReport envelopes (--report, .outputs/last-run.json, .outputs/run-<workflow>-<runId>.json) with phaseTimeline. |
| Structured identity & failure reasons | Events and timeline entries stamp timestampMs, elapsedMs, runId, phase, shard, operationId, iterationId, dispatchGeneration, attempt, and loopCount alongside StructuredFailureReason (code, category, remediation). |
| Attributed concurrent logs | Concurrent child stderr streams are captured non-blockingly, redacted for rfacb_v1_* and rf_tok_* secrets, prefixed with [<phase>#<shard> round=<L> inv=<N>], and emitted as handler_log events. |
| Failed vs genuinely stalled | rippflow ui and profile reports never mark failed, timed-out, or cancelled phases PASS, and distinguish HANDLER_EXECUTION_FAILED, WORKFLOW_TIMEOUT, and REWORK_LIMIT_EXHAUSTED from unrouted queue drain (WORKFLOW_STALLED). |
5. Prove asynchronous callback continuation
Verify dispatch releases worker capacity, authenticated callbacks resume execution, and downstream phases finish once. Test duplicates, invalid credentials, expiry, and restart recovery. A workflow_advanced flag alone is insufficient evidence.
Check support. Cloud Lambda callbacks need reachable authenticated intake; localhost is not reachable. Distinguish local simulation from deployed acceptance. See local HTTPS & callback contracts →
| Capability | Supported contract & explicit constraints |
|---|---|
| HTTPS callback ingress & slim launchers | rippflow deploy --local accepts concurrent POST /v1/callbacks authenticated via per-operation scoped_token_hmac (rfacb_v1_..., TLS CA in RIPPFLOW_LOCAL_CA_CERT) without exposing admin rf_tok_.... Active launcher budget (executionTimeMs, RSS, 8-slot pool released on {"outcome":"dispatched"}) is measured separately from callbackWaitTimeMs (up to 900s). |
| Credential-safe rejection diagnostics | Invalid or replayed callbacks return structured 400/403/409 JSON (idempotent exact retry returns 200 with duplicate: true) using redacted sha256:<8-hex> tokenFingerprint values, emit async_callback_rejected, and surface rejection counts on timeout. |
Cyclic rerun_phase & sibling callbacks | Root DAG backward loops (for example, outcomes.changes_requested.rerun_phase: build with max_loops: 9 for 10 bounded rounds failing closed as REWORK_LIMIT_EXHAUSTED) and out-of-order parallel async_tool sibling callbacks ({reviewer_a, reviewer_b} -> decision) are supported via per-phase fencing and loop-scoped join tracking. |
| Explicit architectural constraints | requires is strictly an ALL barrier: native first-approval early-exit ANY joins (cancelling in-flight sibling reviewers) and automatic sibling payload merging at fan-in are not built in. Persist round/commit-scoped reviewer verdicts explicitly, note that Root <-> PerShard transitions reset loop_count, and treat type: loop (loop.body) as schema-only. |
Verified sources
Checked 2026-11-05.
- Offline documentation commands 7f5ea32 · main
- Portable coding-agent skill 7f5ea32 · main
- Contract, failure modes and authoring journey 5a75ec6 · main