Prompt workflows

ContractForge AI treats prompts as user intent, not as executable truth. The prompt is normalized into a deterministic project specification before any provider-backed enrichment is allowed.

Good prompt shape

A strong project-generation prompt includes:

• source system;
• connector type;
• source location or table;
• target platform or platforms;
• target catalog/schema/table pattern;
• requested layers;
• write mode per dataset when different;
• schedule and timezone;
• quality and governance requirements;
• explicit keys or a request to leave keys as decisions.

Example:

Create a Supabase medallion project for AWS and Databricks.
Use one shared JDBC connection for products and product_movements.
Products should use hash_diff_upsert with product_id as merge key.
Movements should append by movement_uid.
Run daily with cron 0 6 * * * in America/Sao_Paulo.
Add quality checks for product_id not null, movement_uid not null and quantity >= 0.
Generate review reports and keep platform differences minimal.

Prompt-to-plan

Start with plan-project when the prompt is still ambiguous:

contractforge-ai plan-project \
  --intent "Create Supabase medallion for AWS and Databricks daily at 6 Sao Paulo time." \
  --schema schemas/products.json \
  --preferred-target contractforge-yaml \
  --format markdown

The planner reports recommended generation commands and unresolved decisions. Use this before writing files when the prompt might omit keys, source details or platform choices.

Prompt-to-project

Use generate for intent-first project generation:

contractforge-ai generate \
  --prompt "Create a USGS earthquake REST GeoJSON medallion for Databricks and AWS. Bronze reads the all_day.geojson endpoint, silver extracts event fields, gold aggregates by magnitude band." \
  --schemas schemas/usgs-events.json \
  --with-ai \
  --provider openai \
  --output-dir generated/usgs-earthquakes

For multi-dataset requests, pass every schema:

contractforge-ai generate \
  --prompt "Create one Supabase project for products and product_movements using the same connector. Products use hash_diff_upsert, movements append. Generate AWS and Databricks-ready project files." \
  --schemas schemas/products.json schemas/product_movements.json \
  --with-ai \
  --provider openai \
  --output-dir generated/supabase

The user can override per-table behavior in the prompt. If one table needs a different connector, source table, write mode or keys, say that explicitly.

Required decisions

ContractForge AI must produce RequiredDecision instead of guessing when a prompt omits production-critical details:

Missing detail	Why it is not guessed
Merge keys	They define update identity and idempotency.
Hash-diff columns	They define change detection semantics.
Gold grain	It defines aggregation correctness.
PII policy	It defines legal and governance behavior.
Secret names	They must come from the target runtime or platform team.
Production compute	It changes cost and runtime behavior.

Provider guidance may suggest likely answers, but those answers stay review-required.

Platform hints

Platform hints are explicit:

Prompt wording	Result
Databricks, Unity Catalog, DAB, Auto Loader	Databricks hint.
AWS Glue, Athena, Lake Formation, Glue job	AWS hint.
s3://... only	Connector/storage hint, not automatically AWS.
Iceberg only	Table-format hint, not automatically AWS.

This prevents source storage from silently choosing the platform.

Validate the generated project

Always validate after generation:

contractforge-ai validate-project-structure generated/supabase \
  --adapter databricks \
  --adapter aws \
  --format html > generated/supabase/project_validation.html

Treat READY and READY_WITH_WARNINGS as usable validation gates. Treat NEEDS_DECISIONS, INVALID and UNSAFE as not deployable until resolved.