Skip to content

getaero-io/gtm-eng-skills / skills/deepline-engine

deepline-engine

Verified

Build, publish, and verify a Deepline Play as a durable state machine over Customer DB tables, including a small paid pilot. Invoke this skill explicitly when the user asks to build an engine.

FileKindSize
SKILL.mdskill md17.5 KB
agents/openai.yamlconfig517 B
references/post-fix-verification.mdmarkdown3.0 KB
references/state-machine-contract.mdmarkdown13.3 KB
skill-metadata.jsonconfig520 B

references/state-machine-contract.md

View on GitHub
# State machine contract

Use this contract to turn a user-defined workflow into a composable set of Plays: one durable orchestrator plus one child Play for each transformation. The names below describe roles, not required table or field names.

## Transition matrix

Write the matrix before the Play:

| Current state | How state is determined                                        | Input table | Transition Play        | Allowed next states | Output table | Terminal?  |
| ------------- | -------------------------------------------------------------- | ----------- | ---------------------- | ------------------- | ------------ | ---------- |
| `<state>`     | `<explicit field, durable lookup, or user-defined classifier>` | `<table>`   | `<owned/prebuilt/new>` | `<states>`          | `<table>`    | `<yes/no>` |

Infer routine structural details from the request and project conventions, and record those assumptions. Do not invent missing business policy. Ask only when competing interpretations would materially change a state decision, allowed transition, transformation, or terminal outcome.

## Table roles

Each state's input table needs enough information to identify and process one item:

- stable business row key
- current state or the inputs required by the state-decision rule
- payload or a stable reference to it
- received timestamp
- transition idempotency key
- source or prior-transition reference when relevant

Each state's output table needs enough information to audit the transition:

- stable business row key
- reference to the accepted input
- `from_state` and `to_state`
- transformation result
- `completed`, `failed`, `invalid`, or another user-defined status
- typed error or miss reason
- processed timestamp
- Play/workflow version
- transition Play reference and version
- transition idempotency key

When a transition is nonterminal, its output supplies the next state's input. Use the same stable business key and a deterministic handoff key so replay repairs a missing handoff without creating another one.

## Resolve transition Plays

Treat each state transformation as a callable Play, not a helper function hidden inside the engine. Before writing one:

```bash
deepline search "<transition input -> transition outcome>"
deepline describe <owned-or-prebuilt-candidate>
```

Search results include Plays created in the user's workspace as well as prebuilts. Search by the transformation's outcome and input contract, not a guessed name. Prefer an exact owned or prebuilt contract over new code. Record why each candidate fits or fails; a similar title is not enough.

The orchestrator composes the selected Play with `deepline.runPlay`. That boundary accepts scalar child Plays only. A child that uses `deepline.dataset()`, `deepline.csv()`, a Runtime Sheet, an event wait, or an explicit timeout owns a separate lifecycle and cannot be used as an inline transition. When no compatible Play exists, author a scalar transition Play and include it in the engine's automatic dependency-ordered check and publication workflow.

## Maintained source tree

Generate the engine in a durable project directory that follows the repository's source conventions. Keep these artifacts together:

- orchestrator Play
- newly authored child transition Plays
- shared state and transition types
- README describing the contract, local validation, and automatic publication and synthetic-test boundaries
- Mermaid `stateDiagram-v2` source for the complete machine

Do not put these artifacts in an ignored `tmp/` directory. Before handoff, confirm the chosen directory is durable and visible to the project's source-control workflow.

## Orchestrator shape

Keep the state machine visible in code:

```ts
import deepline from 'deepline';
// Helpers are placeholders for the user's table contract; pass `deepline` in.

type EngineInput = {
  itemKey: string;
  payload: Record<string, unknown>;
  state?: string;
};

type TransitionResult = {
  nextState: string;
  output: Record<string, unknown>;
};

export const config = {
  description: 'Advance one item through the user-defined state machine.',
};

export default async function (input: EngineInput) {
  const state = await determineState(deepline, input); // implement the user's rule
  let transition: TransitionResult;

  try {
    switch (state) {
      case 'user-defined-state-a':
        transition = await deepline.runPlay<TransitionResult>(
          'transition-from-state-a',
          'user-owned-or-prebuilt-transition-play-a',
          { itemKey: input.itemKey, payload: input.payload },
          { description: 'Apply the user-defined transition from state A.' },
        );
        break;
      case 'user-defined-state-b':
        transition = await deepline.runPlay<TransitionResult>(
          'transition-from-state-b',
          'user-owned-or-prebuilt-transition-play-b',
          { itemKey: input.itemKey, payload: input.payload },
          { description: 'Apply the user-defined transition from state B.' },
        );
        break;
      default:
        throw new UnknownEngineStateError(state);
    }
  } catch (error) {
    await persistTransitionFailure(deepline, input, state, {
      status: isUnknownStateError(error) ? 'invalid' : 'failed',
      error: toTypedTransitionError(error),
    });
    throw error;
  }

  try {
    assertAllowedTransition(state, transition.nextState);
  } catch (error) {
    await persistInvalidTransition(deepline, input, state, transition, {
      error: toTypedTransitionError(error),
    });
    throw error;
  }

  await persistTransitionAndHandoff(deepline, input, state, transition);
  return transition;
}
```

Replace every placeholder with the user's contract. Do not copy the example state names into a real engine.

The example shows dispatch and outcome ordering; its named error and persistence helpers are placeholders for the user's table contract. Implement those helpers with `deepline.customerDb.query(...)`: use schema-qualified Customer DB `INSERT ... ON CONFLICT` mutations keyed by the transition idempotency key for state outputs and deterministic handoff keys for next-state inputs. Persist a typed `failed` output when the child Play rejects and a typed `invalid` output when the state or proposed next state is forbidden, without writing a next-state handoff. After a valid child result, write the completed output first, then the next-state input; replay must repair a missing handoff without duplicating either row. Do not use `deepline.dataset(...)` for engine state tables: it materializes a run-scoped Runtime Sheet, not durable Customer DB state. A dataset may expose an optional per-run view, but it is not the engine's persistence layer. Keep Customer DB reads bounded and provider calls or other transformation work inside the transition Play; call the child through `deepline.runPlay(...)` so retries reuse durable work.

## Advancement choice

Choose one model explicitly:

- **One transition per invocation:** easiest to observe and repair. Choose an explicit supported caller, such as an API/CLI submission, webhook, schedule, or another user-approved dispatch path, to start the next run from the next-state input. Writing an arbitrary Customer DB table does not itself trigger a Play; SQL listeners bind only to supported monitor tool streams.
- **Multiple transitions per invocation:** lower handoff latency, but one run owns more control flow. Persist every state boundary before continuing so a resume does not repeat completed work.

Infer the model from the workflow. When no external event must occur between states, default to multiple transitions through terminal completion. Record the choice and its retry and observability implications. The same state and table contracts apply to both.

## Test matrix

Before publication, prove with static checks and provider-free fixtures:

- every declared state dispatches to the intended transition Play
- every transition reuses a described compatible owned/prebuilt Play or has a checked new transition Play
- every allowed transition writes the correct output and next-state input
- terminal transitions do not enqueue another state
- unknown states and forbidden transitions fail loudly
- transition Play failures retain the input and a typed failure result
- a child result proposing a forbidden next state fails before handoff
- replaying the same transition idempotency key does not duplicate output or handoff rows
- two different business keys remain independent
- the Play passes `deepline plays check <file.play.ts>`

Do not execute a provider during this pre-publication matrix. Defer provider-backed edge tests to the bounded pilot after the caps and workspace gate below are verified. Use synthetic rows for all tests. An explicit request to build an engine authorizes publication. The multi-record authoring pilot below runs only in an explicit internal/test workspace; it does not authorize third-party customer workspaces, real customer rows, trigger installation, a larger run, or unrelated Customer DB mutations.

This section governs the new-engine authoring pilot. It does not replace the
required post-fix Production acceptance when a code fix depends on a real
paid-provider response or Production usage admission/settlement. Run that
separate one-case check through the public SDK/API path in an owner-verified
operator personal workspace or designated Deepline-owned internal Production
workspace, following
[post-fix verification](post-fix-verification.md).
The acceptance uses that runbook's budget and keeps the ordinary settled
charge; do not apply this pilot's multi-record/replay or credit-restoration
requirements to it.

## Automatic publication and paid pilot

Inspect live Deepline balance and pricing before publishing paid code. Choose the pilot records and calculate the per-run cap. Put a static `billing.maxCreditsPerRun` no greater than the orchestrator cap on every newly authored provider-backed child before its first check or publication, then check and publish the capped children needed for `deepline.runPlay` resolution. A published child is independently callable, so relying only on the parent's inline cap leaves its root-run path unbounded. Never publish an uncapped revision of a newly authored paid child.

Place the static `billing.maxCreditsPerRun` in the orchestrator source before checking or publishing it. A preliminary uncapped live revision creates an avoidable window for unbounded runs, especially if bindings are added later.

Check the capped orchestrator against the live child contracts and publish it once. Verify each publication with `deepline plays get <name>`: read its `Live version` and `Live max credits per run` lines, which come from the live revision, not a working revision. Reconcile that version with the publication result and `deepline plays versions --name <name>`. `deepline describe` and revision summaries omit the billing limit, so they cannot verify a cap by themselves. Report the checked version, published version, live revision, every provider-backed Play's live cap, and any mismatch. Stop on a failed check, publish, or verification instead of publishing a dependent Play against an uncertain contract.

Calculate and disclose the aggregate pilot maximum as `(number of pilot top-level runs + one replay attempt) × billing.maxCreditsPerRun`. A per-run cap resets for each top-level run, so presenting it as the whole pilot bound understates exposure. Do not hardcode a credit-to-currency conversion. If credits are zero or unavailable, stop; quote any CLI-provided recovery commands exactly, but do not run them without approval.

Run this authoring pilot without another approval in an explicit internal/test workspace. Do not substitute a customer workspace for the authoring pilot. These pilot rules do not gate or replace the separate post-fix Production acceptance described above, which is one case in an owner-verified operator personal or designated Deepline-owned Production workspace. Do not turn this into a second design review or ask again between pilot records covered by the same bound.

Submit one representative synthetic record through the published engine and its real paid transitions with `deepline run <orchestrator-name> --input '{...}'`; keep the run id and cost from its receipt. Add at most two more synthetic records only when distinct branches need coverage, and keep all records within one bounded pilot. Stop when outputs are wrong, coverage is poor, a required field is missing, or observed cost per usable result is too high. Replaying a completed transition by rerunning its record with the same command and idempotency key, without `--fresh`, must not create another provider charge, output, or handoff. When the engine has no paid transition, run the same live pilot and report zero spend; adding an unrelated provider would test a different workflow.

Show the pilot inputs, final outputs, observed Deepline spend, published `billing.maxCreditsPerRun`, aggregate bound, and replay result in the deliverable. Retain exact per-step traces, including provider calls and charges, and offer them on request instead of including them by default. Real customer data, installed triggers, a larger run, or other external side effects require separate approval. Before a larger paid run, show the pilot results, observed spend, proposed scope, and proposed Deepline-credit cap, then ask for explicit approval. Scaling requires a newly checked and published revision with that approved cap; do not silently remove or raise the pilot cap.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall