[FEATURE]: Auto-discover workspace identity files (SOUL.md, USER.md, TOOLS.md) like AGENTS.md

I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

I run OpenCode as my daily driver and I found myself constantly cramming everything into AGENTS.md — my personality preferences, user info, SSH hosts, API notes, skill routing, behavioral rules... it became a mess.

So I split it into separate files following a pattern inspired by OpenClaw's workspace:

SOUL.md — how the agent should behave (personality, values)
IDENTITY.md — quick identity card (model, role)
USER.md — who I am (timezone, accounts, preferences)
TOOLS.md — environment cheat sheet (IPs, SSH hosts, infra notes)
AGENTS.md — behavioral rules and skill routing only

This works great today using instructions in config:

{
  "instructions": [
    "~/.config/opencode/SOUL.md",
    "~/.config/opencode/IDENTITY.md",
    "~/.config/opencode/USER.md",
    "~/.config/opencode/TOOLS.md"
  ]
}

The request: It would be nice if OpenCode auto-discovered these files in ~/.config/opencode/ the same way it already auto-discovers AGENTS.md — no manual instructions config needed. If SOUL.md exists, load it. If not, skip it.

This would lower the barrier for users who want to give their agent persistent identity and structured context across sessions, without having to know about the instructions config field.

Bonus: if opencode init could scaffold empty templates for these files (like "fill in your name/timezone here"), that would make onboarding even smoother.

This issue doesn't fully meet our contributing guidelines.

What needs to be fixed:

Feature request titles must start with [FEATURE]: (current title uses "Feature Request:" instead)
Feature requests require a verification checkbox confirming the feature doesn't already exist — this is missing
The issue reads as AI-generated content (extensive structured tables, "Prior Art" / "Alternatives Considered" sections, references to tools like "OpenClaw"). We don't accept AI-generated walls of text; please rewrite this in your own words describing the actual problem you're facing

Please edit this issue to address the above within 2 hours, or it will be automatically closed.

If you believe this was flagged incorrectly, please let a maintainer know.

Hey, this is a good idea but we haven't gotten enough requests for this to consider mass adoption.

You can currently implement this via plugins and existing functionality (opencode.json)

Navigation Menu

Repository navigation

[FEATURE]: Auto-discover workspace identity files (SOUL.md, USER.md, TOOLS.md) like AGENTS.md #14285

Describe the enhancement you want to request

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[FEATURE]: Auto-discover workspace identity files (SOUL.md, USER.md, TOOLS.md) like AGENTS.md #14285

Description

Describe the enhancement you want to request

Activity

github-actions commented on Feb 19, 2026

R44VC0RP commented on Feb 19, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions