Remove ambiguity with .openpackage directory usage

[vegastyle]

Issue

Currently it is not clear what are the responsibilities of the .openpackage folder and its metadata files.

.opencode

Currently the .opencode folder serves two purposes

1. It is the location for the local registry and opencode settings
2. It denotes that a directory is a openpackage package

This creates a confusion as to what is what and what purposes they should serve.

package.yml and package.index.yml

These two metadata files serve to denote metadata about the current package and file mappings respectively.

However package.yml is used to denote whether a package or a workspace, which are currently defined as two different things and have very different formats. This creates confusion and not a clear sep.

package.index.yml may potentially be redundant due to the file structure and platform configuration files denoting where files should be mapped to.

Proposed Solutions

.openpackage should only hold the registry and settings

Keep .openpackage a simple directory for holding settings, configurations and the local registry.

Introduce a new subfolder called .openpackage-meta OR rename package.yml to openpackage.yml

This would create a clear separation of concerns from .openpackage files and provides the following options:

1. Using a new subfolder, like .openpackage-meta, allows you to hold the package.yml and package.index.yml in a separate location outside the root of the package and you can keep using generic names.
2. Renaming package.yml to openpackage.yml makes it very clear that this subdirectory is a openpackage package and follows a similar structure of other coding languages and tools that use a metadata file to denote the purpose of the directory.

This also makes it easier to develop new packages outside of the .openpackage structure.

Use a new workspace.yml file instead of repurposing the package.yml

This helps avoid confusion and you have very clear separation of concerns between packages and workspaces.

[hyericlee]

Yeah this has been the most difficult part of the overall design haha.

After some extensive thought and prototyping, I've settled on a new structure that would address this ambiguity:

<package>
  openpackage.yml              # package manifest

  # Universal content (platform-mapped)
  commands/                    # standard universal subdirs (from platforms.jsonc)
  rules/
  agents/
  skills/
  <custom-subdirs>/            # custom subdirs defined in platforms.jsonc

  # Root files (merged)
  AGENTS.md                    # universal root AGENTS.md file
  <platform-root-files>        # platform-specific root files (e.g. CLAUDE.md)

  # Direct copy to workspace root
  root/                        # files copied 1:1 into the workspace root
    <any-files-or-dirs>/

  # Other root-level files/dirs (not installed by default)
  README.md                    # documentation
  LICENSE.md                   # license

My goal is to improve upon Claude Code Plugins:

• Root manifest file to simplify discovery
• Workspace file installations via root/ dir, useful for docs/, specs/, and various scaffolding needs
• AGENTS.md (and CLAUDE.md etc.) content installation and merges
• Dynamic and custom mappings via platforms.jsonc
• Support composition/dependencies

Furthermore, this will introduce a clear separation of package vs workspace distinction, without sacrificing support for dependencies declaration:

• Packages: Root openpackage.yml
• Workspaces: Root .openpackage/openpackage.yml

This allows OpenPackage to function similarly to npm, where workspace dependencies are listed in the workspace .openpackage/openpackage.yml file for reproducible installations

I'm currently finalizing the code for this, the next version will begin using this new package structure.

Thanks for your input in this, it's extremely helpful for pinpointing friction points and really paints a good picture on actual usage!