Skip to content

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

New issue
New issue
Closed
#1408
Closed
[Bug] Explore skill doesn't read project context from config.yaml#696
#1408
Assignees
TabishB
Labels
bugSomething isn't working

Description

@lsmonki
lsmonki
opened on Feb 11, 2026

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.

Activity

  1. 21st-connector commented on Feb 11, 2026

    @21st-connector
    21st-connectorBot
    on Feb 11, 2026 – with 21st - Connector
    Contributor

    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

  2. 21st-connector commented on Feb 11, 2026

    @21st-connector
    21st-connectorBot
    on Feb 11, 2026 – with 21st - Connector
    Contributor

    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.

  3. TabishB
    self-assigned this
    on Feb 11, 2026

  4. lsmonki commented on Feb 12, 2026

    @lsmonki
    lsmonki
    on Feb 12, 2026
    Author

    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.

  5. clay-good
    added
    bugSomething isn't working
    on Jun 29, 2026
  6. clay-good
    added a commit that references this issue on Jul 22, 2026

    fix(templates): give explore the project's context and rules

    479fbe0
  7. clay-good
    closed this as completedin #1408on Jul 22, 2026
  8. pull
    added a commit that references this issue on Jul 22, 2026

    fix(templates): give explore the project's context and rules (Fission…

    378d468
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

bugSomething isn't working

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions