[Bug] Explore skill doesn't read project context from config.yaml

[lsmonki]

Problem

The opsx:explore skill has no awareness of the project's config.yaml context. When entering explore mode, it checks for active changes (openspec list --json) and reads change artifacts, but never reads the project context defined in openspec/config.yaml — tech stack, conventions, rules, etc.

This means explore mode operates without knowing basic project constraints (e.g., "TypeScript + ESM", "must be cross-platform", spec compliance rules).

Expected behavior

The explore skill should load the project context at the start of a session so it can ground its thinking in the project's actual constraints and conventions.

Possible approaches

1. Read config.yaml directly — simplest, but couples the skill to the file format
2. Add a CLI command (e.g., openspec config --project or openspec context) that outputs the local project context — cleaner, reusable by other skills
3. Use openspec instructions somehow — already reads and returns context, but requires an artifact ID and change name, which explore mode may not have

Context

Other skills like opsx:continue get the project context indirectly via openspec instructions ... --json, which calls readProjectConfig() internally. Explore doesn't use that pathway since it's not creating artifacts.

[1code-async]

Task completed.

Done. I've posted an enrichment comment on issue #696 covering:

1. Confirmation of the bug — The explore skill at skill-templates.ts:94-149 only runs openspec list --json at startup, never reading config.yaml
2. How other skills get context — Via openspec instructions which calls generateInstructions() → readProjectConfig(), a pathway that requires a change name (which explore doesn't have)
3. All relevant code locations with file paths and line numbers
4. Assessment of each proposed approach — Approach 1 (direct read) is simplest, Approach 2 (new CLI command) is cleanest, Approach 3 (openspec instructions) isn't viable without modifications
5. Suggested implementation path — A quick fix adding a config file read to the explore prompt, with a follow-up CLI command for consistency
6. No duplicates found across existing issues

---

View full conversation

Powered by 1Code

[1code-async]

Issue Analysis

Confirmed: Explore skill does not read project config

The explore skill's instructions at src/core/templates/skill-templates.ts:94-149 define its "OpenSpec Awareness" section. At session start, it only runs:

openspec list --json

This retrieves active changes (names, schemas, status) but never reads openspec/config.yaml. The project's context (tech stack, conventions, cross-platform rules) is not loaded.

For reference, this project's own config.yaml contains critical constraints like "TypeScript + ESM", "cross-platform requirements", and per-artifact rules for Windows path handling — none of which the explore skill would be aware of.

How other skills get project context

Other skills (e.g., opsx:continue, opsx:ff) get project context indirectly through the openspec instructions <artifact-id> --change "<name>" --json command:

1. That CLI command calls generateInstructions() at src/core/artifact-graph/instruction-loader.ts:211-275
2. Which calls readProjectConfig() at src/core/project-config.ts:66-161
3. Which reads and parses openspec/config.yaml, extracting context and rules fields
4. These are returned as structured fields in the instructions JSON (lines 269-270)

The continue skill template (skill-templates.ts:442-451) documents how it consumes these fields:

• context: Project background (constraints for AI - not included in output)
• rules: Artifact-specific rules (constraints for AI)

The problem: This pathway requires both an artifact-id and a --change name, which explore mode may not have (it operates outside of a specific change context).

Relevant code locations

File	Lines	What
src/core/templates/skill-templates.ts	24-149	Explore skill template & OpenSpec awareness section
src/core/templates/skill-templates.ts	394-493	Continue skill template (for comparison)
src/core/project-config.ts	66-161	readProjectConfig() — parses config.yaml
src/core/project-config.ts	19-43	ProjectConfigSchema Zod definition
src/core/artifact-graph/instruction-loader.ts	211-275	generateInstructions() — where config is injected
openspec/config.yaml	1-25	This project's own config (example of what's missed)

Assessment of proposed approaches

Approach 1: Read config.yaml directly in the skill prompt — The simplest fix. The explore skill prompt could instruct the AI to read openspec/config.yaml at session start (just like it already reads openspec list --json). This couples the skill to the file format, but readProjectConfig() already handles .yaml/.yml fallback, validation, and a 50KB size limit (project-config.ts:96-114), so the file format is stable. A raw file read by the AI would bypass the Zod validation but for read-only context-gathering in explore mode, this is likely acceptable.

Approach 2: Add a CLI command (e.g., openspec context) — Cleaner and reusable. Currently openspec config exists but is for global OpenSpec settings (editor prefs, etc.) at src/commands/config.ts, not project-level config. A new openspec context or openspec config --project command that calls readProjectConfig() and outputs the structured result would be the most consistent with how other skills consume config. This would also benefit any future skills that need project context without a change.

Approach 3: Use openspec instructions — Not viable without modifications. The instructionsCommand() at src/commands/workflow/instructions.ts:44-95 requires both an artifact ID and a change name, validating that the change exists before proceeding. Explore mode operates independently of changes by design.

Suggested implementation path

A combination of approaches 1 and 2 would work well:

1. Quick fix (Approach 1): Update the explore skill template's "Check for context" section (skill-templates.ts:98-108) to also read the config file:

   At the start, quickly check what exists:
   - Run `openspec list --json` (active changes)
   - Read `openspec/config.yaml` if it exists (project context & constraints)
   

   This is a one-line addition to the skill prompt and immediately solves the problem.

2. Follow-up (Approach 2): Add an openspec context CLI command that outputs parsed project config as JSON. This makes the pattern consistent with how other skills work and enables future skills to access project context cleanly.

No duplicates found

Searched existing issues for related terms (explore config, explore context, config.yaml, openspec, explore skill). No duplicate issues were found covering this specific gap.

[lsmonki]

This isn't limited to Explore.

Only Continue, FF, New, and Onboard get project context, because they call openspec instructions <artifact-id> --change which goes through generateInstructions() → readProjectConfig().

The most impactful gaps are Apply and Verify — they generate and validate code without knowing the project's constraints/conventions. For the operational skills (Archive, Bulk-archive, Sync) it's low-impact today, but would become relevant if lifecycle hooks (#701) are added in the future (e.g., a post-archive hook that generates a changelog following project conventions wouldn't have project context).

This reinforces Approach 2 — but rather than a separate command, a --context flag on the existing openspec instructions command (e.g., openspec instructions --context --json) would keep the API surface small. Every skill could call it at session start to load project context.