Answer

Short version: OneDev does not auto-inject Markdown reference syntax into the agent system prompt. Agents learn the useful forms mainly from the tod companion skills (and any custom system prompt / project instructions you add).

1. Is this injected by the OneDev runtime?

No. For task automation, the runtime builds the prompt roughly as:

1. A small fixed ### Rules block (e.g. that the agent is talking to an AI user, and to wait for sub-agents)
2. The AI user's optional system prompt from AI settings (if set)
3. The ### User task text

There is no built-in injection of issue #… / pr #… / build #… rules.

Docs for context: Working with AI User (optional system prompt) and Working with Workspaces (templates ship tod + companion skills).

2. Is there a schema/tool that enforces the Markdown syntax?

No enforcing schema or tool. Nothing validates comment text against OneDev reference syntax before posting.

What does exist:

• tod companion skills (onedev/tod skills/) teach agents workflow conventions. In particular, work-on-issue / submit-issue-work tell the agent that when a comment mentions a pull request, use the exact form pr #<number>.
• The using-tod skill documents CLI reference forms (123, #123, project#123, KEY-123). Those are for tod arguments, not a full Markdown linking guide.

Why prefixes matter (and a correction)

Issue / PR / build numbers are independent. In Markdown, a bare #123 is still recognized, but it is treated as an issue reference. So for PRs/builds you need an explicit type prefix, e.g. pr #45, build #67 (also pull request #45).

Cross-project forms use project path or key before the number, with the type prefix in front when needed:

• Same project: issue #45, pr #12, build #98
• Other project by path: issue path/to/project#45, pr path/to/project#12
• Other project by key: issue OD-45, pr OD-12 (or OD-45 for an issue)

The proposed path/to/project#issue-45 form is not the syntax OneDev parses.

3. Recommended way to keep custom agents from falling back to GitHub-style #123

1. Install tod + companion skills in the agent environment (workspace templates / images already do this; see tod skills README).
2. For stricter habit-forming, put short reference rules in the AI user's system prompt, and/or in project AGENTS.md / agent rules / a small custom skill—especially: never use bare #N when you mean a PR or build; use pr #N / build #N.
3. Relying only on a default system-prompt append for every AI user is not how the product works today; that would be a product change rather than current behavior.

If this answers the question, we can close the issue. If you want the default system-prompt append implemented as a product change, say so and we can follow up.

@servicedesk I do concede that a default system prompt append for AI users doesn't sound like it would be the best thing to do. It sounds like a workaround fix, and I'm trying to understand if there's a better fix. Would it be better to update the tod skills docs instead?

My only concern in doing it that way is that I have seen the ai agent not accurately use the TOD syntax. Hence the reason for my call to explicitly append the system prompt during workspace runtime.

Pros/cons? Your recommendation?

@zaakiy Yes — updating the tod companion skills is the better primary fix. Pros/cons and recommendation below.

Skills docs vs system-prompt append

Neither approach enforces syntax. Agents that mis-use references can ignore skills and system prompts. Hard guarantees would need validation/linting of posted text (a separate product feature).

Recommendation

1. Prefer improving tod skills as the main fix: add a clear Markdown reference section (same-project issue #N / pr #N / build #N, cross-project forms, and “bare #N means issue”) to using-tod, and reinforce it in comment-drafting steps of work-on-issue / submit-issue-work. That targets the real gap — CLI refs are documented; Markdown linking for comments is only lightly covered.

2. Use an optional system prompt (or project AGENTS.md) only as site-level reinforcement if you still see failures after the skills update — short, high-signal rules, not a long append for every AI user by default.

3. Do not make a default runtime system-prompt append the primary design; skills + optional local reinforcement is cleaner and matches how agents are already steered today.

If this recommendation works for you, we can close this question. If you'd like a follow-up to actually expand the tod skills (or explore comment-time validation), say which you prefer.

@servicedesk please create an issue for option one. Please note that I believe it's not in this project. I believe it should be created in the tod project. https://code.onedev.io/onedev/tod

CC @robin

@zaakiy Created the follow-up for option one in the tod project: issue onedev/tod#9 (assigned to robin). Linked it as Related to this issue. Closing this question as answered — please continue any discussion there.