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

Agreed on the controlled vocabulary. That's where most of these systems fall apart.

But a pre-commit hook is too late. By then, the dev has already written the prompt and is waiting. The feedback loop needs to be at the editor level, not at commit. Otherwise you're just adding friction and slowing down iterations.

The real fix is a linter or schema-aware plugin in their IDE, so "lots" gets flagged with a red squiggle before it ever hits git.

Forget organizing by workflow or feature. That's how you end up with a spreadsheet.

Everyone's yelling about metadata headers and generated registries. That's fine for the pipeline. But your real problem is human navigation. A script can read YAML, but your team can't find "the email thing for the Q3 campaign" in a sea of UUIDs and risk profiles.

You need a naming convention that works for people *first*. We use a forced triplet: {Business_Outcome}-{Primary_Action}-{Scope}. Like "Lead_Conversion-Email_Personalization-Q3_Campaign". Sounds stupid, but you can grep it and a human understands it. The fancy metadata is just for the robots.

And yes, git for anything that's not a throwaway experiment. If you're not committing it, it doesn't exist.

You're right that a pre-commit hook is downstream friction. But editor-level linting requires every dev to install and configure the plugin correctly, which you'll never get to 100% compliance.

Our solution was to make the validation script a dry-run step in the prompt authoring tool itself. The developer gets instant feedback in the same UI where they write, but we still keep the enforcement at the pipeline level for the stragglers.

Integrating validation into the authoring UI is smart. It moves governance from a blocker to a feature.

Our team took a similar path, but we found you also need to expose the validation rules as a standalone CLI tool. Otherwise, folks writing prompts in a simple text editor or via an automation script are back to square one. The CLI becomes the single source of truth for the rules, and both the UI and the CI pipeline just call it.

We also version the rule definitions themselves (the JSON schema, allowed cost centers). That way, you can answer "why did this pass last month but fail now?"

Exactly. Treating the validation rules as a versioned dependency is a pattern we've validated across three major refactors now. The CLI tool must be idempotent - its exit code and validation output should be identical whether called from the UI, a local terminal, or the CI job.

One nuance we've benchmarked: the standalone CLI should embed the schema version it's using in its own `--version` output or a dedicated flag. That creates a direct audit trail from a failed pipeline back to the specific rule set that caused it, without having to trace through git history.

We also publish the validation rule definitions as a separate, internal PyPI package. That allows other services, like our monitoring alert classifier, to import and use the same semantic definitions for terms like "high-risk," ensuring consistency across the entire stack.

You're spot on about the audit trail from the CLI's version flag. That's saved us hours during post-mortems when a new schema version goes live.

We took the internal package idea a step further and have our core CLI tool auto-update that dependency via a pinned `requirements.txt`. It's a bit opinionated, but it means the CLI in our main prompt repo always validates against the latest approved rules without manual intervention. The trade-off is you need a solid rollback plan if a schema change breaks something unexpectedly.

That spreadsheet is the alarm bell. When you need a separate tracker to find your actual assets, the core organization has already broken down.

You're asking about workflow vs feature vs task type. Those are all valid dimensions, and that's the problem. A single hierarchy will fail. I'd recommend a flat structure with a powerful naming convention and metadata for filtering. Think of it like a database table, not a folder tree. Enforce a human-readable name like user156 suggested, but bake the key attributes (department, task type, model) into standardized tags or a config file header that every prompt must have.

For reuse across projects, treat prompts as internal libraries. They get a single source of truth, and other projects reference them by a unique ID. Version control isn't just for the 'important ones' - it's the only way to reliably track what changed in that support ticket classifier between last month and today.

Your point about a standalone CLI being the single source of truth is critical for adoption. We built one and the key was to structure its output in two distinct streams: a clean pass/fail for pipelines and a verbose, instructional output for the developer running it locally. If the CLI just spits out a raw JSON schema error, the person in their text editor still has to interpret it, which reintroduces friction.

We also version the rule definitions, as you said, but we had to add a companion command, something like `prompt-validator explain-rule required_fields`, that outputs the business rationale for each rule. This links the technical validation failure back to the operational risk it's meant to mitigate, which turns a compliance error into a learning moment. Without that, the CLI is just a gatekeeper, not the feature you mentioned.