Documentation Index
Fetch the complete documentation index at: https://developer.kodexa.ai/llms.txt
Use this file to discover all available pages before exploring further.
Claude Code is most useful when it works against real files in a metadata repository. The goal is not to generate a disconnected YAML snippet. The goal is to update the same files that kdx sync will validate and deploy.
Start From A Synced Repository
If the environment already contains resources, pull them first:
kdx sync pull --target my-org --env dev --discover --discover-dir kodexa-resources
git add sync-config.yaml manifests kodexa-resources .sync-state
git commit -m "Sync Kodexa metadata baseline"
Give Claude Code The Right Scope
Open Claude Code from the repository root:
cd my-kodexa-config
claude
We are modeling invoice intake as an Activity-first Kodexa workflow.
Please inspect sync-config.yaml, manifests, and kodexa-resources.
Then propose the smallest file changes needed to add:
- an invoice data definition
- a review task template
- a review data form
- an Activity Plan that extracts, creates the review task, waits for completion,
and calls the finance ERP service bridge after approval
Do not deploy anything. Do not create secrets. Keep changes reviewable.
Ask For A Plan Before Large Edits
For non-trivial changes, ask Claude Code to describe the file plan first:
Before editing files, list the resources you will create or modify, their file paths,
and which existing resources they reference.
- resource scope: organization-level versus project-scoped
- filenames and slugs
- references to existing task templates, data forms, modules, bridges, and knowledge resources
- whether a trigger or project binding is needed
- whether the manifest needs to include new files
Useful Prompt Patterns
Create A Data Definition
Use the Kodexa data-definition skill to create a data definition for commercial invoices.
Include invoice number, invoice date, purchase order number, vendor name, currency,
subtotal, tax, total, and repeating line items. Put the file under
kodexa-resources/data-definitions/invoice.yaml and add it to the manifest.
Create a reusable task template and V2 data form for invoice review.
The task is the human review point inside the Activity, not the process itself.
Bind the form to the invoice data definition and make the form suitable for
field correction and exception review.
Create An Activity Plan
Create an Activity Plan named invoice-intake.
It should run extraction, create an invoice review task when review is required,
wait for completion, branch on approval or rejection, and call the ERP service bridge
only after approval. Use current Activity Plan step kinds and avoid legacy planTemplate fields.
Add Knowledge-Driven Behavior
Use the knowledge-system skill to add vendor-specific extraction guidance.
Create feature and item type YAML where needed, then create a knowledge set that
applies an extraction prompt override when the vendor feature matches.
Review the Activity Plan, task template, data form, and project binding files for
broken references, legacy fields, missing manifest entries, and deployment risk.
Return findings with file paths and exact changes to make.
Keep References Portable
Prefer sync-friendly references over environment-specific UUIDs when the KDX sync resolver supports them.
Examples:
activityPlanRef: "activity-plan://${org}/invoice-intake"
taskTemplateRef: "${taskTemplate.invoice-review}"
dataFormRef: "${dataForm.invoice-review}"
Review The Diff
After Claude Code edits files:
Ask Claude Code to explain the diff in Kodexa terms:
Explain this diff as a Kodexa deployment review. Focus on new resources,
references between resources, manifest changes, and risks before sync.
Avoid These Mistakes
| Mistake | Better approach |
|---|
| Putting process orchestration inside a Task template | Create an Activity Plan and have it create or wait for Tasks |
| Creating one-off project-specific copies of reusable resources | Define organization-level resources and bind them into projects |
| Hard-coding environment UUIDs in files | Use slugs and sync reference placeholders where supported |
| Writing API keys or vendor credentials into YAML | Use Kodexa secrets or environment-specific secret references |
| Letting Claude Code deploy immediately after editing | Validate and dry-run first |
Ignoring .sync-state/ | Commit sync state so conflict detection works |
Before You Sync
Run these checks before pushing configuration:
git diff --check
find kodexa-resources -name '*.yaml' -print0 | xargs -0 -n1 kdx validate -f
kdx sync push --target my-org --env dev --dry-run
