I have idea about spec

[SilentFlower]

I have an idea. Currently, the generated specs are mostly business-related. Could we also generate corresponding specs for non-business aspects, such as coding standards, so the model can take them into context?

Specifically, I think we could set up spec indexes within the context of config.yaml. This way, they would be included during the exploration and implementation phases for the model to read, thereby achieving a higher level of consistency in a sense.

[1code-async]

Task completed.

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

Key findings:

• The project already has a config.yaml mechanism with context and rules fields that inject non-business context into the AI model, but it's separate from the spec system
• The spec system currently enforces a strict business-requirement structure (SHALL/MUST keywords, WHEN/THEN scenarios) that wouldn't naturally fit coding standards
• Three closely related open issues were identified: Enhancement: Rules #447 (dedicated rules folder), opsx-config - updating config.yaml #688 (structured coding standards in config.yaml), and [Proposal] Add hierarchical spec structure support #662 (hierarchical spec structure with _global/ namespace)
• Four potential implementation approaches were outlined with pointers to the relevant code locations

---

View full conversation

Powered by 1Code

[1code-async]

Issue Analysis

Thanks for the idea, @SilentFlower. Here's some context from the codebase to help frame this discussion.

Current State: How Non-Business Context Reaches the Model

The project already has a mechanism for injecting non-business context (like coding standards) into the AI model, but it's done through config.yaml rather than through the spec system:

• context field in openspec/config.yaml — a free-form string (max 50KB) injected into all artifact instructions as <project_context>. Currently used for tech stack info and cross-platform path handling rules. See src/core/project-config.ts:19-41 for the schema definition.
• rules field in openspec/config.yaml — per-artifact rule lists (keyed by artifact ID like specs, tasks, design) injected as <rules>. See src/core/artifact-graph/instruction-loader.ts:256-270 for how they're loaded.

Both are passed to the AI during the instruction generation phase (src/commands/workflow/instructions.ts:135-152).

How Specs Differ Today

The spec system (openspec/specs/) is currently designed for business/feature specifications with a strict structure enforced by Zod validation:

• Each spec must have a name, overview, and at least one requirement (src/core/schemas/spec.schema.ts:5-17)
• Requirements must contain SHALL or MUST keywords (src/core/schemas/base.schema.ts:8-16)
• Requirements must have at least one scenario with WHEN/THEN format

This structure works well for testable business requirements but would be a poor fit for coding standards (e.g., "use arrow functions for components") without schema modifications.

Closely Related Open Issues

This idea overlaps significantly with several open proposals:

• Enhancement: Rules #447 — "Enhancement: Rules" — Proposes a dedicated openspec/rules/ folder with .rules.md files for conventions and standards (e.g., typescript.rules.md, solid.rules.md). Very similar goal, different mechanism.
• opsx-config - updating config.yaml #688 — "opsx-config - updating config.yaml" — Proposes structured fields within config.yaml for "Coding Standards" and "Architectural Patterns & Constraints", which directly addresses the "spec indexes in config.yaml" idea.
• [Proposal] Add hierarchical spec structure support #662 — "Add hierarchical spec structure support" — Proposes a _global/ namespace for cross-cutting concerns like testing standards and security requirements.
• [Proposal]: Configurable specs path (specsPath in config.yaml) #664 — "Configurable specs path" — Proposes specsPath in config.yaml for configuring where specs live.

Potential Approaches

Based on the codebase, there are a few directions this could take:

1. Extend config.yaml with structured fields (aligns with opsx-config - updating config.yaml #688) — Add dedicated sections like standards.coding, standards.architecture that get injected into <project_context>. This is the simplest path since readProjectConfig() (src/core/project-config.ts:66-161) already supports resilient field-by-field validation.

2. Dedicated rules folder (aligns with Enhancement: Rules #447) — Create a new openspec/rules/ directory with separate markdown files for different standard categories. Would require new loading logic in generateInstructions() (src/core/artifact-graph/instruction-loader.ts:211-275).

3. New spec type/schema — Extend the spec format to support a "standards" or "conventions" type that relaxes the SHALL/MUST + scenario requirements. Would require changes to the Zod schemas and parsers.

4. Spec index in config.yaml (as proposed) — Add a specIndex field in config.yaml that references spec files to always include in context. This would work with existing spec loading but needs a way to reference and resolve spec paths.

Given the overlap with #447 and #688, it may be worth consolidating the discussion there to converge on a single approach.