Add `--user` option to `openspec schema init` for user-level schemas

[askpatrickw]

Open Issues

This request makes sense on its own, but I'm curious why these files don't live in
~/.config/openspec/ instead.

Summary

Add a --user option to openspec schema init so developers can create a user-level schema directly (stored in ~/.local/share/openspec/schemas/) for reuse across multiple projects.

Problem / use case

OpenSpec already documents that schemas can be resolved from a user directory (~/.local/share/openspec/schemas/) to enable sharing across projects. However, the CLI currently positions schema init as project-local only (“Create a new project-local schema”), which creates friction for the “share across projects” workflow.

A common scenario:

• A developer or platform team maintains a personal (or internal) workflow schema they want to use in many repos (e.g., org-standard, security-review, rapid, etc.).
• They don’t want to copy/paste or “init then move” schemas manually for each project.
• They want a quick way to create and iterate on a schema once, then immediately use it from any repo on their machine.

Why this matters

A --user flag would:

• Make the documented user-level schema capability discoverable and easy to use from the CLI.
• Support “power users” and teams who work across many repos and want consistent workflows without duplicating schema definitions.
• Reduce manual filesystem steps and mistakes (wrong directory, inconsistent schema copies, forgetting to move templates, etc.).
• Encourage experimentation: users can prototype schemas globally before deciding to vendor a stable copy into a specific repo for version control.

Desired UX (from a user perspective)

• By default, openspec schema init <name> continues to create a project-local schema.
• With --user, openspec schema init --user <name> creates the schema in the user-level location, so it’s immediately available across projects via normal schema resolution.

Documentation alignment

This request directly supports the documented note:

OpenSpec also supports user-level schemas at ~/.local/share/openspec/schemas/ for sharing across projects…

Right now, the CLI help text and init behavior don’t reflect an easy path to that workflow.

[1code-async]

Task completed.

The enrichment comment has been posted on issue #756. Here's a summary of what was included:

Duplicate check: Not a duplicate, but closely related to #752 (openspec init --global) which proposes the same pattern for skills/commands. Six other related issues were linked.

Key codebase findings:

• The schema init command at src/commands/schema.ts:665 is hardcoded to project-local output
• getUserSchemasDir() already exists in src/core/artifact-graph/resolver.ts:35-37 and returns the correct user-level path
• The three-tier resolution system (resolver.ts:63-91) already resolves user-level schemas at runtime — there's just no CLI path to create them
• An existing --scope pattern in the config command (src/commands/config.ts:210-220) could serve as a design precedent

Implementation guidance: Outlined the 6 key changes needed, including a design question about --user (simple) vs --scope <project|user> (extensible, consistent with existing patterns), and the need to coordinate with #752 on naming conventions.

---

View full conversation

Powered by 1Code

[1code-async]

Issue Triage: Codebase Analysis

Not a Duplicate

No existing issue requests this exact feature. However, #752 (openspec init --global) proposes a very similar pattern (a flag to target a non-project-level directory) for skills/commands rather than schemas. These two issues should likely be coordinated to ensure a consistent CLI design.

Related issues worth considering together:

• [Proposal]: Configurable specs path (specsPath in config.yaml) #664 — Configurable specs path (specsPath in config.yaml)
• Feedback: Support custom openspec/ directory path #697 — Support custom openspec/ directory path
• [Feature Request] Allow configurable OpenSpec directory name #581 — Allow configurable OpenSpec directory name
• [Feature Request] Establish an official channel/registry for sharing custom artifact schemas #650 — Official channel/registry for sharing custom artifact schemas
• [Proposal] Add hierarchical spec structure support #662 — Hierarchical spec structure support

---

Relevant Code

schema init command definition:
src/commands/schema.ts:665-682 — Current options are --json, --description, --artifacts, --default, --no-default, --force. No scope/location flag exists today.

Schema target directory (hardcoded to project-local):
src/commands/schema.ts:687 — const projectRoot = process.cwd(); is used to derive the output path. The created schema always lands in <cwd>/openspec/schemas/<name>/.

User-level schemas directory helper (already exists):
src/core/artifact-graph/resolver.ts:35-37 — getUserSchemasDir() returns path.join(getGlobalDataDir(), 'schemas'), resolving to ~/.local/share/openspec/schemas/ on Linux/macOS.

Three-tier schema resolution (already supports user-level):
src/core/artifact-graph/resolver.ts:63-91 — getSchemaDir() resolves schemas in order: project-local → user-level → package built-in. User-level schemas already work at runtime; there's just no CLI path to create them.

Existing --scope pattern in the codebase:
src/commands/config.ts:210-220 — The config command uses --scope <scope> with a preAction validation hook. This is a potential design pattern to follow.

Documentation referencing user-level schemas:
docs/customization.md:272 — Already documents user-level schemas at ~/.local/share/openspec/schemas/ but notes they require manual filesystem work.

---

Implementation Approach

The infrastructure for user-level schemas already exists in the resolver. The main work is routing schema init to the correct directory. Key changes:

1. Add a flag to schema init — Two design options to consider:

   • --user (as proposed) — Simple boolean flag, matches the issue's UX request
   • --scope <project|user> — Mirrors the existing --scope pattern in the config command and is more extensible (e.g., could later support --scope package)

   Given openspec init --global: Install skills and commands to tool global directories #752 is proposing --global for a similar concept, it's worth aligning on naming conventions across all init-like commands.

2. Swap target directory in the schema init handler (src/commands/schema.ts:687):

   • Default (no flag): use getProjectSchemasDir(process.cwd())
   • With --user / --scope user: use getUserSchemasDir() from resolver.ts

3. Adjust --default behavior — Setting a project default (openspec/config.yaml) doesn't make sense for a user-level schema. When --user is active, either:

   • Skip the "set as default" prompt entirely
   • Or set a user-level default in the global config (~/.config/openspec/config.yaml)

4. Update help text — Change the description from "Create a new project-local schema" to something reflecting both scopes.

5. Update docs/customization.md — Add a section showing the --user workflow alongside the existing documentation note at line 272.

6. Consider extending schema fork similarly — src/commands/schema.ts:548-662 currently forks to project-local only. The same --user flag would be useful there for forking a built-in schema to user-level.

---

Design Question

The main design decision is --user vs --scope. Given the existing --scope pattern in config and the related --global proposal in #752, it may be worth establishing a consistent convention across all commands before implementing. A --scope <project|user> approach is more extensible but slightly more verbose for the common case.