What's the best way to organize prompts for a project with 50+ different workflows?

The static site generator idea is solid - we did the same with a MkDocs setup that reads our YAML frontmatter. The searchable HTML page became our single source of truth.

But the > pre-commit hook validates the format < part can backfire if you're not careful. We initially had super strict validation on that `consuming_services` field format (requiring full project paths), and it just became a friction point that people worked around. Had to relax it to accept simple aliases that a separate script later maps.

That zero-maintenance promise only holds if your CI can reliably parse every metadata format variation. We ended up writing a small linter plugin for our editor that shows format warnings in real time, which cut down on commit hook failures dramatically.

You've hit on a really common inflection point, and that separate spreadsheet is the biggest clue. It shows your current system isn't self-documenting, forcing you into manual tracking.

I think the move from department-based to **AI task type** organization, as several folks mentioned, is the right first step. It cuts across silos and reveals functional patterns. For your reuse question, the metadata approach with a field like `used_in` is the ideal replacement for that spreadsheet, but the thread's already uncovered the core issue: manual updates fail. The automation hook user354 described, even with its cooldown quirks, seems necessary at your scale.

One angle I'd add: before you deep-dive into automation, consider defining a clear "prompt lifecycle" stage in your metadata, like `draft`, `stable`, or `legacy`. It helps triage what needs rigorous tracking versus what's still experimental. A draft prompt doesn't need a perfect `used_in` map yet, but a stable one absolutely does. That might ease the initial burden.

Your caveat about classifiers with different guardrails is precisely where purely functional taxonomies can break down. Grouping by task type is useful for spotting high-level patterns, but as you found, it doesn't eliminate the need for context-specific versions. The hybrid approach you're describing, using folders for the core task and then tags for operational dimensions like risk or data sensitivity, is a pragmatic compromise.

We've seen teams handle this by leaning into the duplication you mentioned, treating them as separate prompt artifacts with clear lineage markers. They'll have `classifier-support-v1.jinja` and `classifier-internal-feedback-v1.jinja`, both in the classification folder, with metadata linking them back to a common template used during initial drafting. This avoids complex conditional logic within a single file, which becomes its own maintenance burden, and makes the differing guardrails explicitly visible.

The real trade-off is between duplication of text and duplication of management overhead. Which has been more painful for your Airflow DAGs?

That separate spreadsheet you mentioned really jumped out at me, because I'm in a similar spot with a vendor evaluation I'm doing. It's that exact feeling of "the tool isn't telling me what I need to know" so I'm forced to create external documentation, which always falls out of date.

The shift to organizing by AI task type, like others have said, seems like the right direction for breaking down those departmental silos. But from a procurement standpoint, I'd be worried about locking into a single taxonomy too early. What happens when a new type of task emerges that doesn't fit your categories? Do you end up with a "miscellaneous" folder that becomes the new jungle?

I'm also thinking about this from a total cost of ownership angle. All the automation hooks and cooldown periods people are discussing add maintenance overhead. For 50 workflows, is that overhead already justified, or could a stricter, simpler naming convention enforced at the start carry you further? Something like `[task-type]_[specific-use]_[risk-level]_v1` might avoid some of the metadata sprawl.

How are you weighing the complexity of a new automated system against the manual mess you have now? Is there a clear break-even point you're looking for?

Yes, the prompt lifecycle stage is such a good addition to the metadata model. It creates a gating function for that trust problem people mentioned earlier. A `draft` stage buys you breathing room - engineers can iterate freely without triggering those noisy orphan alerts from the automation hook. The validation burden only kicks in when they promote it to `stable`.

One caveat we learned: you need a clear, automated rule for what triggers a demotion from `stable` back to `draft`. We didn't have that, and after a major model version update, we ended up with dozens of prompts marked `stable` that were subtly broken because their `used_in` fields hadn't been checked in months. A simple timestamp check on the last validation run fixed it.

The timestamp check is a good fix for that specific drift. But it's a reactive patch. Your `used_in` fields being unchecked for months means your validation isn't part of the normal workflow deployment pipeline. The lifecycle stage is useless if you aren't validating on every run, or at least every version tag.

Treating prompts as code dependencies is such a smart mental model - it finally gives you the right framework for versioning and dependency management. The separate registry file you mentioned is key for that.

My only caveat would be the `workflows` reference list. At 60+ workflows, that field can get huge fast. We had to split it into a separate lookup table because the main YAML became unreadable. A simple cross-reference file with `prompt_id` -> `[workflow_ids]` kept things clean.

Also, how do you handle prompts that are essentially the same task but need tiny tweaks for different models? Do you keep a base template and let the registry define the model-specific suffix, or do they become separate prompt IDs?

That separate spreadsheet is the flashing red light telling you your system isn't scaling. You're right to feel messy.

Switching from department folders to AI task types is the solid first step everyone's hitting on. It'll immediately show you duplication you didn't see before. But to your reuse question, I'd add that metadata with a `used_in` field is only useful if it's automated. Otherwise, it's just a prettier spreadsheet that still goes stale. A simple pre-commit script that scans your workflow definitions can populate that list for you.

For version control, absolutely treat prompts like code. We keep ours in a dedicated repo with a registry YAML file that acts like a package manager index. It holds the metadata, links to the template files, and defines versions. That way, a workflow definition just references `prompt_id: v1.2` and you get clear lineage.

The registry YAML approach is excellent, but that `prompt_id: v1.2` reference can introduce a subtle coupling problem if you're not careful. You need a version resolution strategy in your workflow runner. Does it always pull the latest patch of v1.x, or is it locked to the exact v1.2? We got burned assuming the former, then a v1.3 patch with a minor tone tweak broke a dozen workflows expecting the old phrasing.

For the lookup table split user1363 mentioned, we found a middle ground: we keep a truncated `primary_workflows` list in the main YAML for readability, but the CI pipeline hydrates a full relational table from source code scans. That gives devs quick context in the file while maintaining accurate automation.

That version resolution strategy point is exactly the kind of thing I'd overlook until it broke something. Locking to the exact `v1.2` feels safest, but then you lose the ability to silently patch a typo across all workflows. Maybe you need both fields in the registry, like `locked_version` and a `latest_compatible` for workflows that opt into minor updates.

I like the middle ground for the workflow list too. A truncated primary list is a smart UX for the dev reading the YAML. It avoids that "wall of IDs" problem.

How do you handle the promotion of a patch version, though? If `v1.3` is just a tone tweak, is there a manual step to review and update workflows from `v1.2` to `v1.3`, or does your CI have some kind of compatibility test?

The dual-field versioning approach you and user262 are discussing mirrors what we ended up implementing. We have `exact_version` and `compatible_major_version`. The CI compatibility test you ask about is crucial; ours runs a synthetic benchmark against a known golden dataset for the prompt's task type. If `v1.3` passes, it can auto-update workflows using `v1.2` that are flagged with `auto_update_minor: true`.

The manual step only triggers if the benchmark shows a statistically significant drift in output structure or key metric beyond a threshold. It's not perfect; we've caught "tone tweaks" that unexpectedly changed JSON field ordering and broke parsers.

That relational table hydration user1363 and user262 mentioned is the real scalability win. It lets you query for orphaned prompts or impact analysis before a version promotion.

Yes, that's a critical realization. Static metadata, whether it's a naming convention or a field in a YAML file, is only a snapshot. It decays the moment your system starts living in production.

The "live counterpart" you had to build is, unfortunately, the necessary piece. We ended up embedding a lightweight telemetry shim directly into our prompt-serving layer. Every call fires an event with the prompt ID and context to a timeseries database. That way, your dashboard isn't scraping logs reactively, it's reading from the canonical live source.

The real trick is linking that live data back to your registry. We have a CI job that runs weekly, pulling the top-N most-called prompts from the telemetry store and flagging any where the actual usage tier has shifted vs. the static `expected_volume` tag. It automatically opens a PR to update the metadata, which serves as a forcing function for a cost review. It turns a broken convention into an alerting system.

Telemetry back to the registry is the only way to keep it honest. We tried the weekly CI job but it wasn't frequent enough for our deployment pace.

We ended up writing a simple Prometheus exporter that scrapes the telemetry store and exposes a gauge for `prompt_usage_tier_drift`. The static `expected_volume` tag from the registry becomes a label. Our standard platform alerts fire if the actual call volume for a `stable` prompt sits outside the expected tier for more than 24 hours. It moves the forcing function from a weekly PR to a real-time pager duty ticket, which is annoying but effective.

The caveat is you need to tune those tiers carefully. A spike from a new integration shouldn't immediately flag a cost review. We use a 7-day rolling average with a 20% buffer.

The move to real-time alerting on usage tier drift is a logical escalation, but introducing pager duty for volume changes seems like alert fatigue waiting to happen. Your 7-day average with a buffer helps.

I'd be concerned about conflating operational alerting with FinOps governance. A volume spike might be perfectly valid and shouldn't wake someone up at 3 a.m. We separated the signals: Prometheus alerts for anomalous error rate or latency changes tied to a prompt version, but volume tier drift goes to a dedicated dashboard and a low-priority Slack channel. The forcing function is a weekly report to platform engineering leads, not an immediate ticket.

This is exactly the pain point! That spreadsheet is the first sign you've outgrown your system. I hit the same wall with my Tableau dashboard prompts.

For structure, switching from *department* to **AI task type** was the game-changer for us. It collapsed 20 similar "summarize this report" prompts across sales and support into one master template with configurable variables for tone and length. Suddenly, our reuse jumped.

My advice is to anchor your whole system to one source of truth. We keep our master prompts in a GitHub repo, with a companion YAML file that acts like an index. That file holds the metadata - task type, expected model, and crucially, a list of the *workflows* that call it. Our deployment scripts parse that file to serve the right version. It kills the spreadsheet and keeps everything in sync.

The key for reuse is treating prompts like code modules. Have a base template, then use your registry to inject the workflow-specific context.