Entity Codes and References

Short, stable codes (F-002, US-014, T-001.email) that name any entity unambiguously. · Optional

Every entity gets a code the moment it's created. You never have to type them, but they're the most precise way to point the agent at a specific entity — useful whenever two entities share similar names.

The code prefixes

Codes are sequential per project, stable for the life of the entity, and shown throughout the UI. Schema columns don't get their own code — they're addressed relative to their parent table as table code + dot + column name:

• T-001.email — the email column on table T-001
• T-002.status — the status column on table T-002

Referencing entities in chat

The agent understands four ways of pointing at your entities.

1. #table — focus on an entity type

Type # to insert a table reference, e.g. #features or #user-stories. This tells the agent which kind of entity you mean:

• "Create three #user-stories for the search feature"
• "Which #pages are missing sections?"

2. @table:identifier — explicit record references

Type @ followed by a table name and colon to open a record picker, e.g. @pages: then choose one. The reference renders as a chip in your message:

• @pages:PG-002 — a specific page
• @schema_table:T-001.email — a specific column

3. Bare codes in plain text

No special syntax needed — just use the code in a normal sentence and the agent resolves it. Codes must be uppercase:

• "Combine PG-002 and PG-003 into a single settings page"
• "Delete US-014"
• "Move AC-003 to F-005"

4. Bare column references

Column references work the same way in plain text:

• "Rename T-002.status to state"
• "Make T-001.email NOT NULL"

Codes in the agent's replies

The agent uses the same codes in its own responses — "I've split F-002 into F-007 and F-008" — so you can always trace which entities were touched and reference them in your next message.

⚡ Power-user hints

• Prefer codes over names when precision matters. "Delete the login page" is ambiguous with PG-004 Login and PG-009 Admin Login; "Delete PG-009" is not.
• Codes are stable. Renaming an entity never changes its code, so codes in older conversations stay valid.
• Codes are references, not names. The agent won't bake a code into an entity name it generates.

↔ The traditional way

In a hand-written spec you disambiguate by copying a heading or a Jira ticket ID into your instruction and hoping the reader finds the right one. Entity codes give the whole project a single, stable naming scheme that both you and the agent share — closer to citing a primary key than quoting a title.

What's next

• 8.2 — Using the agent — put codes to work in real requests.
• 9.1 — Guided mode — let the agent proactively steer your project.