feat: add CodeNomad architecture guide skill for contributors

[VooDisss]

Summary

Add comprehensive architecture and SDK navigation skill to help contributors navigate the codebase without missing related code.

What's Included

• Architecture Overview — 6 functional areas (UserInterface, ServerBackend, DesktopClient, SpeechAndAudio, BuildAndPackaging, CloudflareDeployment), package map, and key entry points
• UI Conventions — SolidJS patterns, i18n system (7 locales), signal-based stores, component styling
• Server Conventions — Fastify route patterns, API types, configuration, testing approach
• Desktop Conventions — Electron + Tauri parity rules, native API abstractions
• SDK API Reference — All 10 OpenCode SDK V2 categories used by CodeNomad with signatures and wrapper locations
• SDK Critical Behaviors — Schema gotchas (assistant part metadata, ignored flag asymmetry), decision matrix, race conditions
• SDK Integration Patterns — Client lifecycle, worktree routing, error handling, optimistic updates
• Feature Traces — 5 end-to-end flows with decision branches: permissions, sessions, speech, background processes, git clone
• Anti-Patterns — Common mistakes with file references to correct implementations
• Implementation Checklist — Actionable steps before submitting changes

Design Decisions

• All navigation guidance uses standard grep/file search tools (no RPG MCP server required)
• Split into 8 reference files to stay under 300 lines each
• File references included for every anti-pattern and convention
• Decision branches in feature traces (not just linear flows)
• Weighted quick start by contribution frequency

Files Added

.opencode/skills/codenomad-architecture-guide/ ├── SKILL.md └── references/ ├── architecture-overview.md ├── ui-conventions.md ├── server-conventions.md ├── desktop-conventions.md ├── sdk-api-reference.md ├── sdk-critical-behaviors.md ├── sdk-integration-patterns.md └── feature-traces.md

[pascalandr]

@CodeNomadBot

I want you to perform the gatekeeper checks for latest PR state

check for regressions
check for better possible implementations
Be the PR gatekeeper
Be ruthless about code quality

[codenomadbot]

Gatekeeper review for latest PR state, as requested. I reviewed this as a strict quality/regression check for the added .opencode/skills/codenomad-architecture-guide skill. I did not make code changes.

Verdict: request changes

The idea is useful, but the current skill is not merge-ready because it contains several authoritative-looking references that are wrong for this repository. For a navigation skill, stale or invalid guidance is a functional regression: it will cause future agents to waste time, trust non-existent files, and implement against APIs/events that do not exist.

Blocking findings

1. Non-existent SDK/OpenCode source paths are presented as mandatory verification targets.

   SKILL.md:73-79, references/sdk-api-reference.md:7-8, and references/sdk-critical-behaviors.md:17 tell agents to verify SDK schemas or backend behavior in packages/sdk/js/src/v2/gen/types.gen.ts, packages/sdk/js/src/v2/gen/sdk.gen.ts, and packages/opencode/src/session/message-v2.ts. Those files do not exist in this repo. The current repo imports SDK types from the external package @opencode-ai/sdk/v2/client, for example packages/ui/src/lib/sdk-manager.ts:1.

   This is a hard blocker because the skill's mandatory verification path is impossible to follow. It also makes the detailed claims about assistant metadata and ignored-flag backend behavior unverifiable from the CodeNomad tree. The skill should either point to the actual vendored/generated SDK files if they are intentionally added, or clearly say the SDK implementation lives outside this repo and tell agents to verify against the installed package / generated type declarations actually available to the workspace.

2. Permission/question event names and server route references do not match current code.

   references/feature-traces.md:7, references/feature-traces.md:36, and references/sdk-integration-patterns.md:130-146 document events such as permission.requested and message.permission.replied, and cite packages/server/src/server/routes/permissions.ts. There is no permissions.ts route in packages/server/src/server/routes/. The UI event manager currently handles permission.asked, permission.updated, and permission.replied in packages/ui/src/lib/sse-manager.ts:76-79 and packages/ui/src/lib/sse-manager.ts:161-173.

   Same issue for questions: the docs describe question.requested / message-scoped question reply events, while current UI handling is question.asked, question.replied, and question.rejected. This will mislead future event-handling changes into searching for the wrong event names and files.

3. SDK method paths in the reference are wrong for the code that actually exists.

   references/sdk-api-reference.md:35, references/sdk-api-reference.md:39, and references/sdk-api-reference.md:47 document client.session.deleteMessage(...) and client.session.message.part.update/delete(...). Current CodeNomad code uses client.part.delete(...) for part deletion in packages/ui/src/stores/session-actions.ts:427-434, and explicitly notes that the generated SDK does not expose typed message deletion, so it falls back to a raw DELETE /session/:sessionID/message/:messageID call in packages/ui/src/stores/session-actions.ts:451-457.

   A guide that is supposed to prevent SDK misuse should not teach non-existent or differently-shaped APIs. Please update these sections to reflect the real @opencode-ai/sdk/v2/client surface as consumed by CodeNomad.

4. The skill asserts detailed backend SDK behavior using repo-local line references that cannot be validated here.

   references/sdk-critical-behaviors.md:5-12 and references/sdk-critical-behaviors.md:67-90 make strong claims about ignored, assistant part metadata, provider metadata schema failures, and session revert behavior, all anchored to packages/opencode/src/... paths that are absent. Some of these may be true upstream, but in this repo they read as precise local facts with broken references.

   If these are intentionally upstream OpenCode behaviors, the implementation should say that explicitly and include a reliable verification strategy. Otherwise this is risky institutional knowledge masquerading as checked repo truth.

Better implementation direction

• Replace every non-existent path with an actual CodeNomad path, or label it as external/upstream and give a concrete verification method.
• Generate the SDK/API reference from the installed @opencode-ai/sdk/v2/client types or reduce it to CodeNomad wrapper locations plus “inspect the imported SDK type before use.”
• Align feature traces with current event names from packages/ui/src/lib/sse-manager.ts and the current stores that process those events.
• Keep the skill as a navigation guide, not a frozen copy of SDK internals, unless the upstream source is vendored or linked in a way agents can reliably inspect.

Non-blocking notes

• The skill shape and path are valid for opencode: .opencode/skills/codenomad-architecture-guide/SKILL.md with matching name looks structurally correct.
• File sizes are fine; the largest added reference is references/sdk-integration-patterns.md at about 207 lines.
• I ignored an unrelated local modification in .opencode/package-lock.json; it is not part of the PR diff I reviewed.

Given the purpose of this PR, accuracy is the product. I would not merge until the false paths and mismatched SDK/event references are corrected.

--
Yours,
CodeNomadBot

[github-actions]

PR builds are available as GitHub Actions artifacts:

https://github.com/NeuralNomadsAI/CodeNomad/actions/runs/26216907505

Artifacts expire in 7 days.
Artifacts:

• pr-493-20ff6cc14577777a5651f1ef4a225e43260236e8-tauri-linux
• pr-493-20ff6cc14577777a5651f1ef4a225e43260236e8-tauri-macos
• pr-493-20ff6cc14577777a5651f1ef4a225e43260236e8-tauri-windows
• pr-493-20ff6cc14577777a5651f1ef4a225e43260236e8-tauri-macos-arm64
• pr-493-20ff6cc14577777a5651f1ef4a225e43260236e8-electron-macos
• pr-493-20ff6cc14577777a5651f1ef4a225e43260236e8-electron-windows
• pr-493-20ff6cc14577777a5651f1ef4a225e43260236e8-electron-linux

[github-actions]

PR builds are available as GitHub Actions artifacts:

https://github.com/NeuralNomadsAI/CodeNomad/actions/runs/26216907505

Artifacts expire in 7 days.
Artifacts:

• pr-493-20ff6cc14577777a5651f1ef4a225e43260236e8-tauri-linux
• pr-493-20ff6cc14577777a5651f1ef4a225e43260236e8-tauri-macos
• pr-493-20ff6cc14577777a5651f1ef4a225e43260236e8-tauri-windows
• pr-493-20ff6cc14577777a5651f1ef4a225e43260236e8-tauri-macos-arm64
• pr-493-20ff6cc14577777a5651f1ef4a225e43260236e8-electron-macos
• pr-493-20ff6cc14577777a5651f1ef4a225e43260236e8-electron-windows
• pr-493-20ff6cc14577777a5651f1ef4a225e43260236e8-electron-linux

[VooDisss]

Commit: 60faefdc — fix(skill): correct SDK references and event names in architecture guide

Files changed (5):

• SKILL.md — Updated verification instructions
• references/sdk-api-reference.md — Fixed to only document actually-used SDK methods
• references/sdk-critical-behaviors.md — Removed non-existent paths, labeled upstream behaviors
• references/feature-traces.md — Fixed event names (permission.asked, question.asked)
• references/sdk-integration-patterns.md — Fixed event names and references

[pascalandr]

@CodeNomadBot
same review please

[codenomadbot]

Gatekeeper re-review for latest PR state after 60faefdc, as requested. I reviewed the updated .opencode/skills/codenomad-architecture-guide files and checked the previously reported blockers against the current tree. I did not make code changes.

Verdict: request changes

The previous major issues are mostly improved: the deleted repo-local SDK/OpenCode source paths are gone, permission/question event names are now aligned with packages/ui/src/lib/sse-manager.ts, and message deletion / part deletion docs now reflect the current CodeNomad call sites more accurately.

There are still correctness issues that matter for a navigation skill.

Blocking findings

1. Mandatory SDK verification still points to a file that is not present in the checkout.

   SKILL.md:73-79 and references/sdk-api-reference.md:7-10 instruct agents to verify SDK schemas in node_modules/@opencode-ai/sdk/v2/client.d.ts. That file is not present in the current worktree. I also found no **/@opencode-ai/sdk/**/client*.d.ts under the checkout.

   This is better than the previous non-existent repo paths, but it is still not a reliable mandatory verification instruction. A future agent may be running in a fresh checkout without node_modules, exactly like this review environment. If the guide requires SDK type inspection, it should either say “after dependencies are installed, inspect ...” and include a fallback, or point to the actual generated declaration location guaranteed by the repo/tooling. As written, the mandatory step can still fail before the agent even starts the task.

2. Question reply payload type is documented incorrectly.

   references/sdk-api-reference.md:77 documents:

   client.question.reply({ requestID, answers: string[] })

   Current CodeNomad code uses answers: string[][]:

   • packages/ui/src/stores/instances.ts:1029-1050 declares sendQuestionReply(..., answers: string[][]) and passes that value to client.question.reply({ requestID, answers }).
   • The UI question components also store draft answers as Record<string, string[][]> in packages/ui/src/components/tool-call/question-block.tsx and packages/ui/src/components/tool-call.tsx.

   This is a concrete SDK reference error. The guide should not teach the wrong shape for one of the core interruption flows.

Non-blocking notes

• The previously bad event names (permission.requested, message.permission.replied, question.requested) appear corrected to permission.asked / permission.updated / permission.replied and question.asked / question.replied / question.rejected.
• The previous non-existent packages/server/src/server/routes/permissions.ts reference appears removed.
• The SDK method reference for part deletion now matches current usage: client.part.delete(...) in packages/ui/src/stores/session-actions.ts:427-434.
• File sizes remain fine; the largest added file is still around 209 lines.

Recommendation

Fix the answers: string[][] documentation and make SDK verification resilient in fresh checkouts. After that, I would be comfortable with this as a contributor navigation skill, assuming no new changes introduce fresh stale references.

--
Yours,
CodeNomadBot

[VooDisss]

Commit: f63b5808 — fix(skill): make SDK verification resilient and correct question reply type

Fixes applied:

• Removed mandatory SDK verification that fails in fresh checkouts
• Added fallback: "When node_modules unavailable, read actual CodeNomad usage"
• Fixed client.question.reply type: answers: string[][] (was string[])
• Verified: packages/ui/src/stores/instances.ts:1033 confirms string[][]

[github-actions]

PR builds are available as GitHub Actions artifacts:

https://github.com/NeuralNomadsAI/CodeNomad/actions/runs/26217770794

Artifacts expire in 7 days.
Artifacts:

• pr-493-60faefdc0b7601dfe501e1720a8c85d9463a3c4b-tauri-macos-arm64
• pr-493-60faefdc0b7601dfe501e1720a8c85d9463a3c4b-tauri-linux
• pr-493-60faefdc0b7601dfe501e1720a8c85d9463a3c4b-tauri-windows
• pr-493-60faefdc0b7601dfe501e1720a8c85d9463a3c4b-electron-macos
• pr-493-60faefdc0b7601dfe501e1720a8c85d9463a3c4b-electron-windows
• pr-493-60faefdc0b7601dfe501e1720a8c85d9463a3c4b-electron-linux

[pascalandr]

@CodeNomadBot
same review please

[codenomadbot]

Gatekeeper re-review for latest PR state after f63b580, as requested. I reviewed the updated .opencode/skills/codenomad-architecture-guide files and rechecked the two remaining blockers from the previous pass. I did not make code changes.

Verdict: acceptable to merge from my review

I do not see remaining blocking issues in the updated skill.

Previously blocking items

1. SDK verification path resilience: fixed enough.

   SKILL.md:73-81 now correctly states that the OpenCode SDK is external, makes node_modules/@opencode-ai/sdk/v2/client.d.ts conditional on npm install, and provides a fallback to actual CodeNomad usage patterns. references/sdk-api-reference.md:7-11 does the same. That addresses the fresh-checkout failure mode from my previous review.

2. Question reply payload type: fixed.

   references/sdk-api-reference.md:77 now documents client.question.reply({ requestID, answers: string[][] }), which matches current CodeNomad usage in packages/ui/src/stores/instances.ts:1029-1050.

Additional checks performed

• Re-scanned the skill for the previously stale patterns: packages/sdk/js, packages/opencode/src, permission.requested, message.permission.*, question.requested, client.session.message.*, and the old answers: string[] shape. No stale blocking references remain.
• Rechecked that the permission/question event names now align with packages/ui/src/lib/sse-manager.ts (permission.asked, permission.updated, permission.replied, question.asked, question.replied, question.rejected).
• Spot-checked referenced CodeNomad paths used in feature traces and integration docs; the sampled paths exist.
• File sizes are still fine; the largest added reference is about 209 lines.

Non-blocking polish

• SKILL.md:120 still says Verify SDK compatibility: Check types in node_modules/@opencode-ai/sdk/v2/client.d.ts without repeating the fallback from SKILL.md:77-79. Since the fallback is documented immediately above, I would not block on this, but making the checklist say “check installed SDK types when available, otherwise follow the fallback usage scan” would make the guide more self-contained.

No further blocker from me on this PR.

--
Yours,
CodeNomadBot

[github-actions]

PR builds are available as GitHub Actions artifacts:

https://github.com/NeuralNomadsAI/CodeNomad/actions/runs/26218623852

Artifacts expire in 7 days.
Artifacts:

• pr-493-f63b580876607e544b7a4df3749b301c01d2f1bb-electron-macos
• pr-493-f63b580876607e544b7a4df3749b301c01d2f1bb-tauri-macos
• pr-493-f63b580876607e544b7a4df3749b301c01d2f1bb-tauri-macos-arm64
• pr-493-f63b580876607e544b7a4df3749b301c01d2f1bb-tauri-windows
• pr-493-f63b580876607e544b7a4df3749b301c01d2f1bb-tauri-linux
• pr-493-f63b580876607e544b7a4df3749b301c01d2f1bb-electron-windows
• pr-493-f63b580876607e544b7a4df3749b301c01d2f1bb-electron-linux

[pascalandr]

@VooDisss

1. Why .opencode/skills/ is the right place for this instead of docs/ or AGENTS.md?
2. Since this includes many code paths and SDK/event details, how do you expect us to keep it up to date over time? who is going to maintain it ?

[VooDisss]

@pascalandr

1. Because then anyone who has CodeNomad codebase open in opencode - their opencode will load that skill if needed or suggest loading it using "skills" tool and when receive explicit user permission - agent will load it into context and use it.

2. Not sure how it will be maintained - it should evolve as time goes by. It's way better than nothing, I think.

[bluelovers]

agent easy forgot AGENTS.md, but user can /skillname for make agent load skill if he didnt

[pascalandr]

@VooDisss

1. client.file.list() / client.file.read()

The PR says they are not used by the UI, but they are used in:

packages/ui/src/components/instance/shell/right-panel/RightPanel.tsx

Examples:

browserClient().file.list({ path: normalized })
browserClient().file.read({ path })

2. “All SDK calls go through requestData()”

That statement is too absolute. There are direct SDK calls in:

packages/ui/src/stores/session-api.ts

Examples:

const projectResponse = await rootClient.project.current()
const response = await rootClient.session.list()

So the doc should say “most SDK calls” or “when using SDK methods returning { data, error }, prefer requestData()”, not “all”.

3. config.json / state.json

I’m sure about the substance, but the wording should be nuanced.

The code still has a fallback / legacy path for:

~/.config/codenomad/config.json

But the current resolved structure uses:

config.yaml
state.yaml

In packages/server/src/config/location.ts, we can see:

configYamlPath: path.join(baseDir, "config.yaml")
stateYamlPath: path.join(baseDir, "state.yaml")
legacyJsonPath: path.join(baseDir, "config.json")

So it would be better to say:

The current canonical persisted files appear to be config.yaml and state.yaml; config.json is still supported as a legacy/input fallback.

I would adjust the comment to avoid being too categorical on this point.

[VooDisss]

@pascalandr

I want you to perform the gatekeeper checks for latest PR state

check for regressions
check for better possible implementations
Be the PR gatekeeper
Be ruthless about code quality

[github-actions]

PR builds are available as GitHub Actions artifacts:

https://github.com/NeuralNomadsAI/CodeNomad/actions/runs/26230995447

Artifacts expire in 7 days.
Artifacts:

• pr-493-b6b68b26e3af23b3cf358f142f11bae6f6f7609d-tauri-macos
• pr-493-b6b68b26e3af23b3cf358f142f11bae6f6f7609d-tauri-linux
• pr-493-b6b68b26e3af23b3cf358f142f11bae6f6f7609d-tauri-windows
• pr-493-b6b68b26e3af23b3cf358f142f11bae6f6f7609d-electron-macos
• pr-493-b6b68b26e3af23b3cf358f142f11bae6f6f7609d-tauri-macos-arm64
• pr-493-b6b68b26e3af23b3cf358f142f11bae6f6f7609d-electron-windows
• pr-493-b6b68b26e3af23b3cf358f142f11bae6f6f7609d-electron-linux