From 4c9d72b291e4d9776bb3a7d6ea3eba47e6fe5a84 Mon Sep 17 00:00:00 2001 From: Clay Good Date: Mon, 28 Sep 2026 09:38:39 -0500 Subject: [PATCH 1/2] docs(config): focus project guidance on durable constraints --- docs-lab/customize/project-config.md | 14 +++++++------- docs-lab/reference/configuration/config-yaml.md | 6 +++--- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs-lab/customize/project-config.md b/docs-lab/customize/project-config.md index 2cccd7e740..1603cdf678 100644 --- a/docs-lab/customize/project-config.md +++ b/docs-lab/customize/project-config.md @@ -35,8 +35,8 @@ For example, with a `context` field and the rule from the top of this page, here - Tech stack: TypeScript, Node.js - Domain: e-commerce platform + Public API changes must remain backward compatible for one minor release + Customer-visible changes need rollout and rollback plans @@ -74,16 +74,16 @@ The last column is exact, so a field reaches only the steps listed there. In par ### context -`context` is what the agent should know up front when planning a change, whether it's creating an artifact, applying tasks, or archiving: +`context` is project information that should shape every artifact and workflow step: ```yaml context: | - We ship cross-platform; designs and tasks must cover Windows, macOS, and Linux - Tech stack: TypeScript, Node.js, Commander.js - We use conventional commits + Public API changes must remain backward compatible for one minor release + Customer-visible changes need rollout and rollback plans + The desktop app must work offline after first sign-in ``` -This is planning context, not project documentation. Add a fact when it should shape every plan, like the cross-platform line above. Leave out anything the agent can learn by reading the code. +Use `context` for constraints the agent can't reliably learn from the code. Leave out tech stack inventories, code style, and general project documentation. **Another language**: because context reaches every artifact, it's also how you change the output language. One line, like `Write all artifacts in Spanish.`, switches every proposal, spec, and tasks file the workflows write. diff --git a/docs-lab/reference/configuration/config-yaml.md b/docs-lab/reference/configuration/config-yaml.md index 315053f3f6..a823c026e5 100644 --- a/docs-lab/reference/configuration/config-yaml.md +++ b/docs-lab/reference/configuration/config-yaml.md @@ -77,9 +77,9 @@ A filled-in config.yaml: schema: spec-driven context: | - Tech stack: TypeScript, React, Node.js - We use conventional commits - Domain: e-commerce platform + Public API changes must remain backward compatible for one minor release + Customer-visible changes need rollout and rollback plans + The desktop app must work offline after first sign-in rules: proposal: From 28abd9728f9bff83ac057344d806e37f421d75f6 Mon Sep 17 00:00:00 2001 From: Clay Good Date: Mon, 28 Sep 2026 10:00:04 -0500 Subject: [PATCH 2/2] docs(config): align generated context guidance --- docs-lab/customize/project-config.md | 2 +- docs-lab/reference/configuration/config-yaml.md | 2 +- src/core/config-prompts.ts | 10 +++++----- test/core/init.test.ts | 13 ++++++++++++- 4 files changed, 19 insertions(+), 8 deletions(-) diff --git a/docs-lab/customize/project-config.md b/docs-lab/customize/project-config.md index 1603cdf678..a0dbbe573b 100644 --- a/docs-lab/customize/project-config.md +++ b/docs-lab/customize/project-config.md @@ -74,7 +74,7 @@ The last column is exact, so a field reaches only the steps listed there. In par ### context -`context` is project information that should shape every artifact and workflow step: +`context` is project information that should shape every artifact, plus apply and archive: ```yaml context: | diff --git a/docs-lab/reference/configuration/config-yaml.md b/docs-lab/reference/configuration/config-yaml.md index a823c026e5..6835555b8d 100644 --- a/docs-lab/reference/configuration/config-yaml.md +++ b/docs-lab/reference/configuration/config-yaml.md @@ -11,7 +11,7 @@ Each OpenSpec project keeps its config file at `openspec/config.yaml`, in the pr | Key | Type | Required | Effect | | --- | --- | --- | --- | | `schema` | string | Yes | The workflow schema this project's changes follow | -| `context` | string | No | Injected into every artifact's instructions | +| `context` | string | No | Injected into every artifact, apply, and archive | | `rules` | map: artifact ID → list of strings | No | Extra rules added to one artifact's built-in guidance | | `operations` | map: operation → guidance list | No | Advisory guidance for apply and archive work | | `store` | string | No | Fallback OpenSpec root when this openspec/ is config-only | diff --git a/src/core/config-prompts.ts b/src/core/config-prompts.ts index a2259184a6..0eb2094df7 100644 --- a/src/core/config-prompts.ts +++ b/src/core/config-prompts.ts @@ -22,13 +22,13 @@ export function serializeConfig(config: Partial): string { } else { // Context section with comments lines.push('# Project context (optional)'); - lines.push('# This is shown to AI when creating artifacts.'); - lines.push('# Add your tech stack, conventions, style guides, domain knowledge, etc.'); + lines.push('# This is shown to AI when creating artifacts and during apply and archive.'); + lines.push('# Add durable constraints the AI cannot reliably learn from the code.'); lines.push('# Example:'); lines.push('# context: |'); - lines.push('# Tech stack: TypeScript, React, Node.js'); - lines.push('# We use conventional commits'); - lines.push('# Domain: e-commerce platform'); + lines.push('# Public API changes must remain backward compatible for one minor release'); + lines.push('# Customer-visible changes need rollout and rollback plans'); + lines.push('# The desktop app must work offline after first sign-in'); lines.push(''); } diff --git a/test/core/init.test.ts b/test/core/init.test.ts index 9b7cf1b6ec..4e5bba42ae 100644 --- a/test/core/init.test.ts +++ b/test/core/init.test.ts @@ -144,7 +144,7 @@ describe('InitCommand', () => { }, ); - it('should create config.yaml with default schema', async () => { + it('should create config.yaml with default schema and durable context guidance', async () => { const initCommand = new InitCommand({ tools: 'claude', force: true }); await initCommand.execute(testDir); @@ -154,6 +154,17 @@ describe('InitCommand', () => { const content = await fs.readFile(configPath, 'utf-8'); expect(content).toContain('schema: spec-driven'); + expect(content).toContain( + '# This is shown to AI when creating artifacts and during apply and archive.' + ); + expect(content).toContain( + '# Add durable constraints the AI cannot reliably learn from the code.' + ); + expect(content).toContain( + '# Public API changes must remain backward compatible for one minor release' + ); + expect(content).not.toContain('Tech stack:'); + expect(content).not.toContain('We use conventional commits'); }); it('should add the requested artifact language to a new config', async () => {