Feedback: Support custom openspec/ directory path

[eimaj]

Allow config.yaml or env var to relocate the openspec/ folder to a custom path like ./ai/openspec/.

In larger monorepos, keeping AI/spec tooling under a dedicated directory (e.g., ./ai/) helps reduce root-level clutter and keeps related concerns grouped together.

[1code-async]

Task completed.

Done. I posted an enrichment comment on issue #697 with the following information:

• 5 related/overlapping issues identified ([Proposal]: Configurable specs path (specsPath in config.yaml) #664, How do I specify the output path for OpenSpec artifacts? #654, [Feature Request] Allow configurable OpenSpec directory name #581, Use dot folder instead of root folder for OpenSpec #449, Feature Request: Add support for custom command directory paths during openspec init #350) — with [Proposal]: Configurable specs path (specsPath in config.yaml) #664 being the most comprehensive proposal that could serve as a consolidation point
• Codebase analysis pinpointing all locations where openspec/ paths are hardcoded (9+ files), starting from the OPENSPEC_DIR_NAME constant in src/core/config.ts:1
• Existing configuration patterns that provide prior art for configurable paths (XDG support, schema resolution tiers, Zod-based config validation)
• Suggested implementation approach covering the config field addition, path centralization, the bootstrap chicken-and-egg problem, and the env var alternative

Comment: #697 (comment)

---

View full conversation

Powered by 1Code

[1code-async]

Issue Analysis: Custom openspec/ Directory Path

Thanks for the feedback! This is a well-motivated request for monorepo scenarios. Here's what I found from analyzing the codebase and existing issues.

Related Issues

This request overlaps significantly with several open issues:

Issue	Focus
#664 — Configurable specsPath in config.yaml	Most detailed proposal; covers specsPath with full implementation plan
#654 — How do I specify the output path?	User asking to relocate openspec/ under docs/ai/openspec/
#581 — Configurable OpenSpec directory name	Rename the directory (e.g., .openspec/, specs/)
#449 — Use dot folder instead of root folder	Default to .openspec for convention alignment
#350 — Custom command directory paths during init	Customize where command files are stored

#664 is the most comprehensive proposal and would be a good candidate for consolidation.

---

Codebase Context

The root constant is defined in src/core/config.ts:1:

export const OPENSPEC_DIR_NAME = 'openspec';

Hardcoded path constructions appear throughout the codebase using path.join(projectRoot, 'openspec', ...). Key locations:

File	What it does
src/core/init.ts (lines 84–122)	Creates the entire directory structure during openspec init
src/core/project-config.ts (lines 67–74)	Reads openspec/config.yaml or openspec/config.yml
src/utils/item-discovery.ts (lines 4–65)	Discovers changes, specs, and archived changes by scanning subdirectories
src/utils/change-utils.ts (line 142)	Constructs paths for new changes
src/core/archive.ts (lines 57–58)	Builds archive and specs paths
src/core/artifact-graph/resolver.ts (lines 44–45)	Resolves project-local schemas from openspec/schemas/
src/core/specs-apply.ts (lines 385–386)	Updates spec files
src/commands/change.ts (lines 11, 29, 98)	Change command path references
src/commands/validate.ts (lines 133, 142, 200)	Validation path references

---

Existing Configuration Patterns

The codebase already has precedent for configurable paths:

• Global config/data dirs respect XDG_CONFIG_HOME / XDG_DATA_HOME env vars (src/core/global-config.ts, lines 26–78)
• Schema resolution has a 3-tier priority: project-local → user override → package built-in (src/core/artifact-graph/resolver.ts, lines 63–91)
• Project config (openspec/config.yaml) already uses Zod schemas for validation (src/core/project-config.ts, lines 19–41), making it straightforward to add a new field

---

Suggested Approach

A potential implementation could follow this path:

1. Add a config field (e.g., directory or rootPath) to ProjectConfigSchema in src/core/project-config.ts:19, and/or support an env var like OPENSPEC_DIR

2. Centralize path resolution — Create a helper (e.g., getOpenSpecDir(projectRoot)) that checks config/env and falls back to the current default 'openspec'. This replaces the scattered path.join(projectRoot, 'openspec', ...) calls

3. Bootstrap problem — The config lives inside openspec/config.yaml, so for relocating the entire directory, an env var or a root-level marker file (e.g., .openspecrc) may be needed to locate the directory before config can be read. Alternatively, a CLI flag like --dir could work

4. Update all path consumers — The files listed above would need to use the centralized resolver instead of hardcoded 'openspec'

The bootstrap problem (point 3) is the key design decision — how to discover the custom path before reading the config that specifies it. The env var approach (OPENSPEC_DIR=./ai/openspec) avoids this chicken-and-egg problem entirely.

---

References

• Config schema: src/core/project-config.ts:19-41
• Directory name constant: src/core/config.ts:1
• Directory structure creation: src/core/init.ts:84-122
• Global config path resolution (prior art): src/core/global-config.ts:26-78