chore: superseded by #1995

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
 
   <!-- From your config.yaml: context -->
   <project_context>
-    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
   </project_context>
 
   <!-- From your config.yaml: rules for tasks -->
@@ -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, plus apply and archive:
 
 ```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.
 

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 |
@@ -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:

src/core/config-prompts.ts

@@ -22,13 +22,13 @@ export function serializeConfig(config: Partial<ProjectConfig>): 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('');
   }
 

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 () => {