qadam-builder
Skill5 starsChanged 39 days agoMITView on GitHub
Builds Qadam Flow qadams (integrations) with actions and triggers. Use when the user asks to create a new qadam, add actions to a qadam, add triggers to a qadam, or build an integration for a third-party app. Also use when the user mentions qadams, pieces, connectors, or integration development.
- Reads credentials
- Deletes or force-pushes
In this repository15 other files it gives its agents.
- .agents/features/agents.mdAGENTS.md
- AGENTS.mdAGENTS.md
- add-endpointSkill
- add-entitySkill
- add-featureSkill
- agent-browserSkill
- db-migrationSkill
- designSkill
- grill-meSkill
- local-docker-deploySkill
- mcp-builderSkill
- mintlifySkill
- playwright-e2e-testingSkill
- ubiquitous-languageSkill
- versioningSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 4 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 22
Search the web for the target app's REST API documentation
- Distinctive: line 32
Ask the user: if OAuth2 config is unclear, there are >10 possible actions, or API behavior is ambiguous
- Very specific: line 36
Create this structure under packages/qadams/community/<name>/:
- Very specific: line 71
Add third-party SDKs to dependencies with a pinned version (e.g.
- Very specific: line 154
Test locally: Add AP_DEV_PIECES=<name> to packages/server/api/.env, start with npm start, open localhost:4200.
- Distinctive: line 160
Every change to an existing piece needs a changeset naming it and its level.
- Distinctive: line 262
Auth descriptions: must include step-by-step instructions to get the API key or set up OAuth.
- Very specific: line 293
If an action calls context.run.waitForWaitpoint(...) — directly or through a common/ helper — it pauses the run, and it must say so on …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Qadam Flow Qadam Builder
Pick your task mode first
| Mode | What you're doing | Where to go |
| New piece | Building an integration for an app that has no piece yet | Full 5-step workflow below |
| Add action / trigger | An existing qadam needs another operation or event | Skip Steps 1–3. Open the existing piece, match its conventions (its common/ helpers, auth access, file naming, error handling), then jump to Step 4 IMPLEMENT and Step 5 WIRE & VERIFY. Declare a changeset for the piece. |
| Fix a bug | An existing action/trigger misbehaves | Reproduce → read the offending file and its common/ helpers → smallest fix that matches surrounding style → Step 5 VERIFY. Declare a changeset for the piece. |
Golden rule for existing-piece modes: the piece you're editing is the source of truth, not these templates. If the piece already has a helper, a particular auth access pattern, or a way of shaping output, follow that. Reach into the reference files only for a pattern the piece doesn't already demonstrate.
Workflow (new piece)
Step 1: RESEARCH
- Search the web for the target app's REST API documentation
- Identify the auth method (API key, OAuth2, Basic Auth, custom)
- List available endpoints; check if webhooks are supported
- Note base URL, pagination, and rate limits
Step 2: PLAN
- Location:
packages/qadams/community/by default;packages/qadams/custom/only if the user says "custom piece". See Piece Types below. - Choose the correct auth type — see Quick Auth Reference below
- Select the most useful actions (CRUD, search, list) and triggers (webhook if supported, polling otherwise)
- Ask the user if OAuth2 config is unclear, there are >10 possible actions, or API behavior is ambiguous
Step 3: SCAFFOLD
Create this structure under packages/qadams/community/<name>/:
src/
index.ts
lib/
auth.ts # Auth always lives here — never inline in index.ts
actions/ # One file per action
triggers/ # One file per trigger
common/ # Shared helpers (optional)
package.json
tsconfig.json
tsconfig.lib.jsonpackage.json
{
"name": "@aiqadam/qadam-<name>",
"version": "0.0.1",
"main": "./dist/src/index.js",
"types": "./dist/src/index.d.ts",
"scripts": {
"build": "tsc -p tsconfig.lib.json && cp package.json dist/ && rm -rf dist/src/i18n && cp -r src/i18n dist/src/i18n",
"lint": "eslint 'src/**/*.ts'"
},
"dependencies": {
"@aiqadam/qadams-common": "workspace:*",
"@aiqadam/qadams-framework": "workspace:*",
"tslib": "2.6.2"
}
}Add third-party SDKs to dependencies with a pinned version (e.g. "stripe": "18.2.1").
There is no per-qadam ESLint config: every qadam is linted with packages/qadams/eslint.config.mjs, which ESLint finds by walking up from the qadam directory.
tsconfig.json
{
"extends": "../../../../tsconfig.base.json",
"compilerOptions": {
"module": "commonjs",
"forceConsistentCasingInFileNames": true,
"strict": true,
"noImplicitOverride": true,
"noPropertyAccessFromIndexSignature": true,
"noImplicitReturns": true,
"noFallthroughCasesInSwitch": true
},
"files": [],
"include": [],
"references": [{ "path": "./tsconfig.lib.json" }]
}tsconfig.lib.json
{
"extends": "./tsconfig.json",
"compilerOptions": {
"rootDir": ".",
"baseUrl": ".",
"paths": {},
"outDir": "./dist",
"declaration": true,
"types": ["node"]
},
"include": ["src/**/*.ts"],
"exclude": ["jest.config.ts", "src/**/*.spec.ts", "src/**/*.test.ts"]
}Step 4: IMPLEMENT
The condensed rules in this file (Quick Auth Reference, Quick Piece Definition Template, UX Quality, Output Quality) cover the common case. Open a reference file when you need a concrete copy-ready example for the specific pattern you're building.
When you need a pattern, read the relevant reference file — do not grep other pieces in the codebase. The reference files contain copy-ready examples for every common case. Searching packages/qadams/community/ surfaces inconsistent older code and wastes context.
| When you reach for it | Open this file |
| Wiring auth beyond the Quick Auth Reference table | auth-patterns.md |
| Your first action in this piece (full file shape) | action-patterns.md |
| A trigger — polling, webhook, handshake, or renewal | trigger-patterns.md |
| A prop type you haven't used (dropdowns, dynamic, arrays, files) | props-patterns.md |
Shared API helper, pagination, or createCustomApiCallAction | common-patterns.md |
| An advanced UX pattern (source selectors, AWS-style auth) | ux-guidelines.md |
| Flattening a deeply nested API response | output-quality.md |
| Tagging an action/trigger for AI agents | ai-metadata.md |
Step 5: WIRE & VERIFY
Wiring checklist:
- Import every action in
src/index.ts→ add toactions: [...] - Import every trigger in
src/index.ts→ add totriggers: [...] - Add
createCustomApiCallActiontoactions: [...] - Register in
tsconfig.base.jsonat repo root (insert alphabetically — build fails without this):"@aiqadam/qadam-<name>": ["packages/qadams/community/<name>/src/index.ts"]
Build and lint:
bun install # new pieces only — creates workspace symlinks
npx turbo run build --filter=@aiqadam/qadam-<name>
npx turbo run lint --filter=@aiqadam/qadam-<name>Both must pass. Lint failures (unused imports, any types, unused vars) block CI even when the build is green.
Common TS errors: missing import in src/index.ts, missing tsconfig.base.json entry, reading context.auth as a plain string for SecretText (use context.auth.secret_text), missing sampleData on a trigger.
Test locally: Add AP_DEV_PIECES=<name> to packages/server/api/.env, start with npm start, open localhost:4200.
Versioning an existing piece
Every change to an existing piece needs a changeset naming it and its level. Without it the release PR never raises the version, and live flows never pick up your change.
Which level, and how to apply it, is the versioning skill — open it now; it is mandatory for any change to a qadam. What each level promises (the qadam row of ADR-0001's table, the 0.x shift, the behaviour question) is .agents/rules/versioning.md. Neither is repeated here. The one qadam-specific trap they point back to is below.
Adding a prop to an action/trigger that has already shipped (#479)
A flow built against the old schema stores its configuration once, at authoring time. If you add a required prop with no defaultValue, every flow that was correctly configured before your change now has a step.settings.input with no value for a field the schema demands — it was never wrong, and nobody touched it.
So a new prop on an already-shipped action or trigger must be one of:
- Optional (
required: falseor the key omitted) — the safe default for almost every new prop. - Required, with a
defaultValuethat reproduces the exact behavior a flow authored before the prop existed already had. This is whatexecutionModeoncallFlowdid when it was added in PR #365 (addressing #363):defaultValue: 'queue', matching the only behavior that existed before — thedefaultValuepattern is worth copying. (That PR did not itself bumpqadam-subflows's version, which is a pre-existing gap in that PR's process, not something to copy — declare yours in a changeset, per theversioningskill.)
A required prop with no default is a breaking change to the piece, not an oversight to catch in review after the fact — declare the breaking slot (minor on 0.x, major from 1.0.0 on) for the qadam in a changeset in the same PR that adds the prop. npm run check-required-prop-defaults (tools/ci/check-required-prop-defaults.mjs) enforces the mechanical half of this in CI: it diffs the pull request's own base and head, and fails if a prop becomes required with no default on an action/trigger that already existed before the PR, unless a changeset added in the same diff declares the breaking slot for the qadam's base version. When the base version is 0.x, a minor declaration counts (0.4.15 → 0.5.0); otherwise only a major declaration does. A major declaration always counts, so 0.4.15 → 1.0.0 also passes the check. A hand-edited version no longer satisfies it (gate 1 fails hand edits). Its header comment documents exactly what it can and cannot see — most importantly, it cannot audit props that already shipped this way before the check existed, and it cannot see a change that never went through a pull request.
Giving a required prop a default does not, by itself, make already-published flows revalidate as configured — the resolver backfilling a schema default into a flow's already-stored step.settings.input is separate, unresolved machinery (tracked outside this ticket). What this rule and its CI check guarantee is narrower and entirely within a qadam author's control: the schema a new required prop declares does not, by construction, orphan the value a flow built under the old schema already had.
Piece Types
| Location | Purpose |
packages/qadams/community/ | Third-party integrations (Slack, Stripe, etc.) — use this for almost all work |
packages/qadams/core/ | Built-in platform utilities (HTTP, Store, Math, etc.) — do NOT recreate these |
packages/qadams/custom/ | Private customer-specific pieces |
Full reference: piece-types.md — includes all QadamCategory values and the list of existing core pieces.
Quick Auth Reference
In actions and triggers, context.auth is the resolved connection object — not a flat string:
| API Auth Method | QadamAuth Type | Access Pattern |
| API key / Bearer token | QadamAuth.SecretText() | context.auth.secret_text |
| OAuth2 | QadamAuth.OAuth2() | context.auth.access_token; extra props via context.auth.props?.['<key>'] |
| Username + password | QadamAuth.BasicAuth() | context.auth.username, context.auth.password |
| Multiple fields | QadamAuth.CustomAuth() | context.auth.props.<field_name> |
| No auth needed | QadamAuth.None() | No context.auth available |
Inside the auth's own validate callback the shape is different — it receives the raw entered values (plain string for SecretText, flat object for CustomAuth). The table above applies to action/trigger run() only.
Full code examples: read auth-patterns.md
Quick Piece Definition Template
src/lib/auth.ts
import { QadamAuth } from '@aiqadam/qadams-framework';
export const myAppAuth = QadamAuth.SecretText({
displayName: 'API Key',
description: 'Go to Settings > API Keys in your dashboard to generate a key.',
required: true,
});src/index.ts
import { createQadam, QadamCategory } from '@aiqadam/qadams-framework';
import { createCustomApiCallAction } from '@aiqadam/qadams-common';
import { myAppAuth } from './lib/auth';
import { myAction } from './lib/actions/my-action';
import { myTrigger } from './lib/triggers/my-trigger';
export const myApp = createQadam({
displayName: 'My App',
description: 'What the app does in one sentence.',
logoUrl: '/assets/qadams/my-app.png',
categories: [QadamCategory.PRODUCTIVITY],
auth: myAppAuth,
authors: ['your-github-username'],
actions: [
myAction,
createCustomApiCallAction({
baseUrl: () => 'https://api.example.com/v1',
auth: myAppAuth,
authMapping: async (auth) => ({
Authorization: `Bearer ${auth.secret_text}`,
}),
}),
],
triggers: [myTrigger],
});UX Quality: Easy for Non-Technical Users
Pieces are used by people who have never seen an API — props, dropdowns, and descriptions must be self-explanatory.
- Never ask users to type IDs — Use dynamic dropdowns so they pick items by name (
"Jane Doe (jane@x.com)"not"cus_abc123"). - Descriptions must teach — Don't say "Enter the thread timestamp." Say "Click the three dots next to the message, select Copy Link, and paste the number at the end."
- Use Markdown instructions for complex setup — Add
Property.MarkDown()with numbered steps when a prop requires configuration in the third-party app. - Set sensible defaults — If 90% of users want the same value, make it the default.
- Plain language display names —
"Create Contact"not"POST /contacts". Triggers:"New Order"not"order.created webhook". - Auth descriptions must include step-by-step instructions to get the API key or set up OAuth.
- Helpful dropdown placeholders —
"Please select a project first"not empty.
Full patterns and examples: read ux-guidelines.md
Output Quality: Table-Ready Data
Users pipe qadam outputs into Google Sheets and Qadam Flow Tables constantly — nested or inconsistent output breaks their flows.
- Flatten nested objects —
{ user: { name: "Jo" } }→{ user_name: "Jo" }. - Arrays of records must have consistent flat keys — same keys on every object so each maps to a column.
- Single-record actions return a flat object. List/search actions return a flat array.
- Human-readable key names —
company_namenotcName. These become column headers.
Full patterns and examples: read output-quality.md
AI-Ready Metadata (Optional)
audience(actions only):'human' | 'ai' | 'both'— fence an action to one surface. Default is both.aiMetadata:{ description?, idempotent? }— agent-facing description and safe-retry hint.
Skip both unless deliberately tuning for agents. Full guidance: read ai-metadata.md
Actions that pause the run (pauses marker)
If an action calls context.run.waitForWaitpoint(...) — directly or through a common/ helper —
it pauses the run, and it must say so on createAction:
pauses: true— every execution waits (approval requests,delay_until, a webhook wait).pauses: 'conditional'— whether it waits depends on the step's configuration (delayForabove its in-process threshold,transcribewithwait_until_ready, Queue-modecallFlowwithwaitForResponse).
Creating a waitpoint is not pausing: create_approval_links calls createWaitpoint and
returns, so it carries no marker. ap_validate_flow reads the marker to refuse an inline subflow
that would pause at run time (#426), and npm run check-pause-markers
(tools/ci/check-pause-markers.mjs, in CI) fails on a file that calls waitForWaitpoint whose
action lacks the marker, on a helper consumer that lacks it, and on a stale marker where nothing
waits. A 'conditional' action the validator has no evaluator for is reported as "may pause"
rather than assumed safe, so a new conditional action is visible without an API change.
Critical Reminders
- Register in
tsconfig.base.json— alphabetically incompilerOptions.paths. Build fails silently without this. - Action/trigger
namefields are permanent — never change them after publishing; flows store them. - Auth lives in
src/lib/auth.ts— define there, import in actions/triggers viaimport { myAppAuth } from '../auth'. Do NOT re-export fromindex.ts. - Always provide
sampleDataon triggers — even{}. - Build AND lint must both pass — lint failures (unused imports,
any, unused vars) block CI even when build is green. - Declare a changeset on every existing-piece change — the
versioningskill. Skipping means the release never raises the version, and flows never get your fix. - Never import
@aiqadam/shared— qadams import only@aiqadam/qadams-frameworkand@aiqadam/qadams-common(ADR-0001).QadamCategory,isNil,MarkdownVariantand every other qadam-facingsharedsymbol come from@aiqadam/qadams-framework; a missing one is added topackages/qadams/framework/src/lib/shared-reexports.ts. Lint fails on the import.
When to Ask the User
Pause and ask if:
- OAuth2 authUrl/tokenUrl/scopes are missing from the API docs
- Auth method is unclear or undocumented
- More than 10 possible actions exist — ask which to prioritize
- API uses webhook signature verification
- You need test credentials or sandbox access
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

