opsx-config - updating config.yaml

[mhenke]

I would propose a md instruction to update the config.yaml:

Role

You are a Principal Systems Architect specializing in OpenSpec v1.1+. Fetch any additional information about OpenSpec from the internet if needed.

Use the following resources:

• https://github.com/Fission-AI/OpenSpec/
• https://github.com/Fission-AI/OpenSpec/blob/main/docs/opsx.md#creating-config

Task

Initialize the context: field for an @openspec/config.yaml file. This field serves as the "worldview" for all future AI agent actions. You must be concise, deterministic, and strictly avoid hallucinations.

Instructions

1. Analyze the input details provided.
2. You must use the source code of this project to generate the context.
3. If a specific technical detail is unknown or unavailable, you must use "N/A".
4. Format the result as a single, valid YAML string under the context: key.
5. Maintain high token efficiency (aiming for under 50KB).

---

Example (One-Shot)

Input:

1. System: Simple Todo App.
2. Stack: React, Node, SQLite.
3. Patterns: Functional components.
4. Standards: Arrow functions.
5. Auth: N/A.

Output:
context: |
domain:
description: "Task management system for individual productivity."
rules: "Items must have a unique ID and timestamp."
tech_stack:
web_frontend: "React"
backend: "Node.js"
database: "SQLite"
auth: "N/A"
architecture:
pattern: "Functional programming; no class-based components."
standards:
coding: "ES6 arrow functions exclusively for components."

---

Target Task

Input:

1. System Overview & Domain: [Insert Description]
2. Technical Stack & Versions:
   • WEB FRONTEND: [Insert]
   • NATIVE FRONTEND: [Insert]
   • BACKEND: [Insert]
   • RUNTIME: [Insert]
   • API: [Insert]
   • DATABASE: [Insert]
   • ORM: [Insert]
   • DB SETUP: [Insert]
   • WEB DEPLOY: [Insert]
   • SERVER DEPLOY: [Insert]
   • AUTH: [Insert]
   • PAYMENTS: [Insert]
   • VALIDATION: [Insert]
   • STYLING: [Insert]
   • MPC SERVERS: [Insert]
3. Architectural Patterns & Constraints: [Insert Patterns/Rules]
4. Coding Standards: [Insert Conventions]

Output:

[1code-async]

Task completed.

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

Analysis posted to issue #688:

• What the issue proposes: A markdown prompt for AI agents to auto-generate the context: field in openspec/config.yaml by analyzing a project's source code
• Relevant code references: Linked to config-prompts.ts, init.ts, docs/opsx.md, and the config validation schema showing how config is currently created (minimal, with context left blank for manual filling)
• Related issues: Connected to project context, will the project context be automatically changed if there are significant changes? #621 (auto-updating context), [Question] What's the differences between openspec's config.yaml, Cursor's AGENTS.md and Claude Code's CLAUDE.md #659 (config.yaml vs AGENTS.md), and [Proposal]: Configurable specs path (specsPath in config.yaml) #664 (configurable paths)
• Related in-progress changes: Noted the add-opsx-onboard-skill and project-config changes already in development that overlap with this proposal
• Key considerations: Config's 50KB limit, the structured template vs freeform string format, and overlap with existing issues
• Suggested approach: Implementing this as a new /opsx:config skill template that follows the existing skill architecture in skill-generation.ts, auto-generated for all 31 supported AI tools

---

View full conversation

Powered by 1Code

[1code-async]

Issue Analysis

Thanks for the proposal, @mhenke. Here's some context from the codebase to help frame the discussion.

What this issue proposes

This issue suggests adding a markdown-based prompt/instruction that an AI agent can use to automatically generate the context: field in openspec/config.yaml. The prompt is structured as a "Principal Systems Architect" role that analyzes a project's source code and produces a structured YAML context block covering domain, tech stack, architecture, and coding standards.

Relevant existing code and docs

Current config creation flow:

• During openspec init, a minimal config.yaml is created via serializeConfig() in src/core/config-prompts.ts:1-39 — it produces a schema-only config with commented-out examples for context and rules
• The createConfig() method in src/core/init.ts:485-507 handles writing the file, but only writes the schema field — context is left for the user to fill in manually

Current config.yaml structure (openspec/config.yaml):

schema: spec-driven
context: |
  Tech stack: TypeScript, Node.js (≥20.19.0), ESM modules
  ...
rules:
  specs: [...]
  tasks: [...]
  design: [...]

Config documentation: docs/opsx.md:70-153 — documents the context, schema, and rules fields, including the 50KB size limit for context and the injection mechanism (<context>...</context> XML tags prepended to artifact instructions)

Config validation: The ProjectConfigSchema (Zod) validates context as an optional string and rules as a Record<string, string[]> — see the spec in openspec/changes/project-config/proposal.md

Related issues

#	Title	Relevance
#621	Project context — will it be automatically changed if there are significant changes?	Directly related — asks about auto-updating the context: field
#659	What's the difference between openspec's config.yaml, Cursor's AGENTS.md and Claude Code's CLAUDE.md?	Related — discusses the role and scope of config.yaml
#664	Configurable specs path (specsPath in config.yaml)	Related config enhancement

Related in-progress changes

• openspec/changes/add-opsx-onboard-skill/ — An /opsx:onboard skill is being developed that guides users through their first complete workflow cycle, including analyzing the codebase to suggest tasks. This onboard skill could potentially incorporate context generation as part of its flow.
• openspec/changes/project-config/ — The full project-config design spec, which documents config creation strategy, schema, validation, and injection mechanics.

Key considerations for implementation

1. Where would this live? The proposed prompt could become:

   • A new /opsx:config skill/slash command (alongside existing skills in src/core/templates/skill-templates.ts)
   • An enhancement to the existing openspec init interactive flow (extending serializeConfig() in src/core/config-prompts.ts)
   • A standalone markdown instruction file that users invoke manually

2. Context size limit: The codebase enforces a 50KB limit on the context: field (docs/opsx.md:150). The proposed prompt's instruction to "aim for under 50KB" aligns with this.

3. OpenSpec reference: The prompt references https://github.com/Fission-AI/OpenSpec/blob/main/docs/opsx.md#creating-config — the relevant section is at docs/opsx.md:74-96 which documents the config format.

4. Overlap with project context, will the project context be automatically changed if there are significant changes? #621: Issue project context, will the project context be automatically changed if there are significant changes? #621 asks about auto-updating context when the project changes significantly — this proposal addresses the initial generation side of that problem. Together they suggest a broader feature around context lifecycle management.

5. Template structure: The proposed YAML template uses nested keys (domain, tech_stack, architecture, standards) which is more structured than the current freeform context: | string format used in the codebase. The config parser treats context as a plain string, so nested YAML within the | block would work but would be opaque to validation.

Suggested approach

The most natural integration point would be as a new skill template (similar to existing skills like openspec-explore, openspec-new-change, etc.) that could be invoked via /opsx:config. This would:

• Follow the existing skill architecture in src/core/shared/skill-generation.ts:49-80
• Be auto-generated for all 31 supported AI tools during openspec init
• Leverage the codebase analysis pattern already planned for /opsx:onboard

The skill could analyze the project's source code (package.json, tsconfig, framework files, etc.) and produce a well-structured context: value following the template proposed in this issue.

[xuanswe]

Hello, I would like to ask one question: if I already described my project and tech stack in claude.md, why do I need to write it again in openspec/config.yaml's context field? I don't want to manage the same thing in 2 places.

Am I missing something?

[supergeoff]

Hello, same question here

[Bappy1988]

for the question above, you could simply state

You have further project information available in ./claude.md' if you haven't already read it.

in the context file. This would prevent duplication and also ensure that your agents are bothering to read the context