Tag Registry

Tags in FoundersOS are more than labels. They’re a managed vocabulary with validation, renaming with propagation, and smart convention nudges - while still letting you tag things freely.

See it in action: ask your AI to “run the tag registry demo” - a guided walkthrough on temporary data that cleans up after itself. More about demos.

What you can do

“Set up tags for our main workstreams - product, sales, ops.”

“Rename ‘Sales’ to ‘Revenue’ across everything.”

“What tags do we have?”

“Tag this task with doug and orbyte.”

That last one is where it gets interesting. The system notices “doug” matches a known contact and suggests @doug. It auto-registers “orbyte” as #orbyte since it’s new. No friction, just gentle guidance.

---

Tools

Tool	What it does
create_tag	Register a new tag with a name, optional color, and description
list_tags	See all registered tags, optionally filtered by scope
rename_tag	Rename a tag. Set propagate: true to update every task and customer that uses it.
remove_tag	Remove a tag from the vocabulary (does not strip it from existing records)

---

How validation works

Tag validation runs automatically on every create_task and update_task call. It never blocks - your task always gets created. But it returns structured warnings alongside the result to help keep things clean.

Four checks, in order

Typo detection - If a tag’s slug is close to an existing registered tag, the system warns you and suggests the match. The tag is NOT auto-registered. This catches “fundrasng” when “fundraising” exists.

Known-name detection - If a bare tag matches a contact’s first name, last name, or full name, the system suggests adding the @ prefix. “doug” becomes a hint to use @doug.

Prefix convention nudge - Tags without a #, @, or ! prefix get a gentle suggestion. State-like words (needs-review, on-hold, draft) get nudged toward !. Everything else gets nudged toward #.

Auto-registration - Tags that pass all checks with no close matches are automatically added to the registry. The vocabulary grows organically as you use it.

---

Tagging conventions

Three prefixes create lightweight structure without adding new tables or schemas:

#project for grouping work: #foundersos-v0.4, #talkdoc-ios, #mm-campaign. Filter tasks by tag to get a project view.

@person for waiting-on: @doug, @accountant. Different from assigned_to (who owns the task) - this is who you’re chasing.

!state for meta-states: !needs-review, !shipped-not-announced, !in-testing. Gives you states beyond the four built-in status values (todo, in_progress, blocked, done).

Tip: You don’t have to memorize these. The validation system will nudge you in the right direction when you forget a prefix.

---

Propagation

When you rename a tag, you can propagate the change across every task and customer that uses it. The system uses Postgres array_replace functions under the hood, so it’s fast even across thousands of records.

rename_tag({
  tag_id: "...",
  new_name: "Revenue",
  propagate: true
})

// Result: tag updated, 14 tasks and 6 customers updated

No manual find-and-replace. No stale references.