Support project-scoped profile/workflow config via --scope project #914

Activity

1. 21st-connector commented on Apr 3, 2026

   

   21st-connectorBot

   on Apr 3, 2026 – with 21st - Connector

   Contributor

   More actions

   🤖 Automation triggered: Enrich Github Issue

   I'm starting to work on this automatically.

   ---

   View live progress

   Powered by 1Code
2. 21st-connector commented on Apr 3, 2026

   

   21st-connectorBot

   on Apr 3, 2026 – with 21st - Connector

   Contributor

   More actions

   Issue Analysis

   Codebase References

   The issue correctly identifies the key files. Here are the exact locations:

   Scope gate (the placeholder to remove):

   • src/commands/config.ts:214-220 — preAction hook rejects non-global scope with "Error: Project-local config is not yet implemented". This is the explicit placeholder for this feature.

   Global config storage:

   • src/core/global-config.ts:35-56 — getGlobalConfigDir() resolves to $XDG_CONFIG_HOME/openspec/ or ~/.config/openspec/
   • src/core/global-config.ts:92-94 — getGlobalConfigPath() returns [configDir]/config.json
   • src/core/global-config.ts:101-139 — getGlobalConfig() loads and deep-merges with defaults
   • src/core/global-config.ts:145-155 — saveGlobalConfig() writes the full config

   Config schema & validation:

   • src/core/config-schema.ts:7-25 — Zod schema defining GlobalConfig shape (profile, delivery, workflows, featureFlags), uses .passthrough() for forward compatibility
   • src/core/config-schema.ts:44-68 — validateConfigKeyPath() restricts valid key paths to known top-level keys

   Update workflow resolution (reads global-only today):

   • src/core/update.ts:96-106 — Reads getGlobalConfig(), resolves profile/delivery/workflows, derives desiredWorkflows and delivery flags
   • src/core/update.ts:139-144 — getToolsNeedingProfileSync() compares desired state against installed artifacts

   Profile system:

   • src/core/profiles.ts:14 — CORE_WORKFLOWS = ['propose', 'explore', 'apply', 'archive']
   • src/core/profiles.ts:19-31 — ALL_WORKFLOWS (11 total)
   • src/core/profiles.ts:42-50 — getProfileWorkflows() resolves workflows by profile type

   Profile drift detection:

   • src/core/profile-sync-drift.ts:14-26 — WORKFLOW_TO_SKILL_DIR mapping
   • src/core/profile-sync-drift.ts:166-176 — getToolsNeedingProfileSync()
   • src/core/profile-sync-drift.ts:218-240 — hasProjectConfigDrift() — checks all tools for drift

   Existing project config (for context/rules only, not profile):

   • src/core/project-config.ts:19-41 — ProjectConfig interface: schema, context, rules
   • src/core/project-config.ts:66-161 — readProjectConfig() reads openspec/config.yaml
   • Note: This file already reads project-level YAML config but only for schema/context/rules — not for profile/delivery/workflows.

   Config command subcommands affected:

   • config list — src/commands/config.ts:231-268
   • config get — src/commands/config.ts:271-288
   • config set — src/commands/config.ts:291-330
   • config unset — src/commands/config.ts:332-346
   • config profile — src/commands/config.ts:452-644 (interactive profile wizard)

   ---

   Related Issues & Prior Art

   Directly referenced:

   • /opsx-archive can offer 'Sync now' even when openspec-sync-specs is not installed (core profile) #913 (open) — /opsx-archive offers "Sync now" even when openspec-sync-specs is not installed (core profile). This is a concrete example of cross-project coupling: changing the global profile to add sync for one project would affect all other projects. Project-scoped config would let individual repos opt into sync without global side effects.
   • Introduce --profile expanded to init compatibly with 1.1.x #779 (open) — Requests --profile expanded for init. The pain point is that the global profile is volatile and not writable in some environments. Project-scoped config would solve this by storing profile selection in-repo.

   Related closed issues/PRs (precedence model):

   • User-global custom skills/commands (with override precedence, like schemas) #757 (closed) — "User-global custom skills/commands (with override precedence, like schemas)" — proposed the same project > global > built-in precedence model for skills/commands. The precedence model in this issue aligns with that design.
   • Add --user option to openspec schema init for user-level schemas #756 (closed) — Added --user option for user-level schemas, addressing the same global-vs-project tension for schemas.
   • PR feat: add openspec init --global for tool global directory installation #753 (closed, not merged) — Attempted openspec init --global for tool global directory installation — different direction but same underlying tension.

   Foundational PRs:

   • PR feat(core): implement global config directory with XDG support #377 (merged) — Established the current global config system with XDG support (src/core/global-config.ts)
   • PR feat: simplify skill installation with profiles and smart defaults #726 (merged) — Introduced the core/custom profile system and delivery config
   • PR Prune deselected workflows during update sync #741 (merged) — Added workflow pruning during openspec update based on profile drift detection

   Other related open issues:

   • Global config.yaml support for custom workflow rules #835 — Requests global config.yaml support for custom workflow rules (inverse direction: global rules that apply to all projects)
   • feature request: Skill to create or update the config.yaml #854 — Feature request for a skill to create/update config.yaml

   Not a duplicate. No existing issue or PR addresses project-scoped profile/delivery/workflow config specifically.

   ---

   Existing Precedence Pattern

   The codebase already implements a multi-level precedence model for schemas (docs/opsx.md:110-114, docs/customization.md:83-90):

   1. CLI flag (--schema <name>)
   2. Change metadata (.openspec.yaml)
   3. Project config (openspec/config.yaml)
   4. Default (spec-driven)

   The proposed profile/workflow precedence model mirrors this existing pattern, which is a good sign for consistency.

   ---

   Implementation Approach

   Based on codebase analysis, here is a suggested approach:

   1. Extend openspec/config.yaml (project-config.ts)

   The project config file already exists and is read by readProjectConfig() at src/core/project-config.ts:66-161. The natural place to store project-scoped profile/delivery/workflows is to extend this file:

   # openspec/config.yaml
   schema: spec-driven
   context: |
     ...
   # New fields:
   profile: custom
   delivery: both
   workflows:
     - propose
     - explore
     - apply
     - archive
     - sync

   This requires:

   • Extending ProjectConfig interface (src/core/project-config.ts:19-41) with optional profile, delivery, workflows fields
   • Extending the Zod schema in readProjectConfig() to validate these new fields

   2. Create an effective config resolver

   A new function (e.g., resolveEffectiveConfig()) that merges configs with the proposed precedence:

   1. CLI flags (already handled per-command)
   2. Project config (openspec/config.yaml profile/delivery/workflows)
   3. Global config (~/.config/openspec/config.json)
   4. Built-in defaults (core, both)

   This could live in a new file like src/core/effective-config.ts or be added to src/core/global-config.ts.

   3. Update src/core/update.ts:96-106

   Replace the direct getGlobalConfig() call with the new effective config resolver. The update command already receives resolvedProjectPath (line 82), so it has access to the project root for reading project config.

   4. Update config command (src/commands/config.ts)

   • Remove the preAction scope gate at lines 214-220
   • For --scope project: read/write to openspec/config.yaml instead of ~/.config/openspec/config.json
   • config list should show effective (merged) config with source annotations (e.g., (project), (global), (default))
   • config profile --scope project should write to project config

   5. Update resolveCurrentProfileState() (src/commands/config.ts:99-108)

   This function currently takes only GlobalConfig. It would need to accept the effective merged config or take both global and project configs.

   Key consideration: The config set/unset commands use src/core/config-schema.ts:44-68 for key validation, which currently only allows featureFlags, profile, delivery, workflows. For project scope, the same keys should be valid, but they need to be written to the YAML project config instead of the JSON global config.

   ---

   Testing Considerations

   • Verify that openspec update picks up project config when present and falls back to global when absent
   • Verify that config list correctly shows source annotations
   • Verify that modifying project config does not affect global config
   • Verify precedence: project profile: custom + workflows: [sync] overrides global profile: core
   • Verify that projects without project-scoped config are completely unaffected (backwards compatibility)
   • Edge case: what happens when project config has profile: core but also has workflows: [sync, propose]? The getProfileWorkflows() function at src/core/profiles.ts:42-50 ignores custom workflows for the core profile — this interaction needs to be defined clearly.
3. jamessawle commented on Apr 24, 2026

   

   jamessawle

   on Apr 24, 2026

   More actions

   We're hitting this exact problem. We have a shared repo where we want a specific subset of workflows (9 of the 11), but since config is global-only, each developer has to configure their machine individually. This makes onboarding friction and causes drift when someone has a different profile set globally.

   Would you be open to a community PR for this? Happy to contribute but wanted to check before investing the effort.
4. clay-good

   added

   design-reviewNeeds product/design decisionNeeds product/design decision

   on Aug 27, 2026