fix: inject $schema only on project creation, not on every write

- Move $schema injection from writeProjectSpec to createDefaultProjectSpec
  in both CLI and TUI create flows
- Existing projects are never modified — no git churn on upgrade
- Custom $schema values are preserved through read-modify-write cycles
- Add integ tests verifying injection, preservation, and non-injection

Author: Hweinstock

integ-tests/schema-injection.test.ts

@@ -0,0 +1,86 @@
+import { createTestProject, runCLI } from '../src/test-utils/index.js';
+import type { TestProject } from '../src/test-utils/index.js';
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+const SCHEMA_URL = 'https://schema.agentcore.aws.dev/v1/agentcore.json';
+
+async function readRawConfig(projectPath: string): Promise<Record<string, unknown>> {
+  const raw = await readFile(join(projectPath, 'agentcore', 'agentcore.json'), 'utf-8');
+  return JSON.parse(raw) as Record<string, unknown>;
+}
+
+describe('integration: $schema injection in agentcore.json', () => {
+  let project: TestProject;
+
+  beforeAll(async () => {
+    project = await createTestProject({
+      language: 'Python',
+      framework: 'Strands',
+      modelProvider: 'Bedrock',
+      memory: 'none',
+    });
+  });
+
+  afterAll(async () => {
+    await project.cleanup();
+  });
+
+  it('new project has $schema set to the official URL', async () => {
+    const config = await readRawConfig(project.projectPath);
+    expect(config.$schema).toBe(SCHEMA_URL);
+  });
+
+  it('$schema appears as the first key in the JSON', async () => {
+    const config = await readRawConfig(project.projectPath);
+    expect(Object.keys(config)[0]).toBe('$schema');
+  });
+
+  it('$schema persists after adding a resource', async () => {
+    const memName = `SchemaMem${Date.now().toString().slice(-6)}`;
+    await runCLI(['add', 'memory', '--name', memName, '--json'], project.projectPath);
+
+    const config = await readRawConfig(project.projectPath);
+    expect(config.$schema).toBe(SCHEMA_URL);
+
+    await runCLI(['remove', 'memory', '--name', memName, '--json'], project.projectPath);
+  });
+
+  it('does not overwrite a custom $schema value', async () => {
+    const configPath = join(project.projectPath, 'agentcore', 'agentcore.json');
+    const config = await readRawConfig(project.projectPath);
+    const customUrl = 'https://example.com/custom-schema.json';
+    config.$schema = customUrl;
+    await writeFile(configPath, JSON.stringify(config, null, 2));
+
+    const memName = `CustomMem${Date.now().toString().slice(-6)}`;
+    await runCLI(['add', 'memory', '--name', memName, '--json'], project.projectPath);
+
+    const updated = await readRawConfig(project.projectPath);
+    expect(updated.$schema).toBe(customUrl);
+
+    // Restore original
+    updated.$schema = SCHEMA_URL;
+    await writeFile(configPath, JSON.stringify(updated, null, 2));
+    await runCLI(['remove', 'memory', '--name', memName, '--json'], project.projectPath);
+  });
+
+  it('does not inject $schema into a pre-existing project that lacks one', async () => {
+    const configPath = join(project.projectPath, 'agentcore', 'agentcore.json');
+    const config = await readRawConfig(project.projectPath);
+
+    // Simulate an old project by stripping $schema
+    delete config.$schema;
+    await writeFile(configPath, JSON.stringify(config, null, 2));
+
+    // Trigger a write
+    const memName = `OldProj${Date.now().toString().slice(-6)}`;
+    await runCLI(['add', 'memory', '--name', memName, '--json'], project.projectPath);
+
+    const updated = await readRawConfig(project.projectPath);
+    expect(updated.$schema).toBeUndefined();
+
+    await runCLI(['remove', 'memory', '--name', memName, '--json'], project.projectPath);
+  });
+});

src/cli/commands/create/action.ts

@@ -1,4 +1,4 @@
-import { APP_DIR, CONFIG_DIR, ConfigIO, setEnvVar, setSessionProjectRoot } from '../../../lib';
+import { APP_DIR, CONFIG_DIR, ConfigIO, SCHEMA_URL, setEnvVar, setSessionProjectRoot } from '../../../lib';
 import type {
   AgentCoreProjectSpec,
   BuildType,
@@ -26,6 +26,7 @@ import { join } from 'path';
 
 function createDefaultProjectSpec(projectName: string): AgentCoreProjectSpec {
   return {
+    $schema: SCHEMA_URL,
     name: projectName,
     version: 1,
     agents: [],

src/cli/tui/screens/create/useCreateFlow.ts

@@ -1,4 +1,12 @@
-import { APP_DIR, CONFIG_DIR, ConfigIO, findConfigRoot, setEnvVar, setSessionProjectRoot } from '../../../../lib';
+import {
+  APP_DIR,
+  CONFIG_DIR,
+  ConfigIO,
+  SCHEMA_URL,
+  findConfigRoot,
+  setEnvVar,
+  setSessionProjectRoot,
+} from '../../../../lib';
 import type { AgentCoreProjectSpec, DeployedState } from '../../../../schema';
 import { getErrorMessage } from '../../../errors';
 import { CreateLogger } from '../../../logging';
@@ -71,6 +79,7 @@ function getCreateSteps(projectName: string, agentConfig: AddAgentConfig | null)
 
 function createDefaultProjectSpec(projectName: string): AgentCoreProjectSpec {
   return {
+    $schema: SCHEMA_URL,
     name: projectName,
     version: 1,
     tags: {

src/lib/schemas/io/config-io.ts

@@ -21,7 +21,7 @@ import { mkdir, readFile, writeFile } from 'fs/promises';
 import { dirname } from 'path';
 import { type ZodType } from 'zod';
 
-const SCHEMA_URL = 'https://schema.agentcore.aws.dev/v1/agentcore.json';
+export const SCHEMA_URL = 'https://schema.agentcore.aws.dev/v1/agentcore.json';
 
 /**
  * Manages reading, writing, and validation of AgentCore configuration files
@@ -105,10 +105,7 @@ export class ConfigIO {
    */
   async writeProjectSpec(data: AgentCoreProjectSpec): Promise<void> {
     const filePath = this.pathResolver.getAgentConfigPath();
-    await this.validateAndWrite(filePath, 'AgentCore Project Config', AgentCoreProjectSpecSchema, {
-      ...data,
-      $schema: SCHEMA_URL,
-    });
+    await this.validateAndWrite(filePath, 'AgentCore Project Config', AgentCoreProjectSpecSchema, data);
   }
 
   /**

src/lib/schemas/io/index.ts

@@ -10,5 +10,5 @@ export {
   NoProjectError,
   type PathConfig,
 } from './path-resolver';
-export { ConfigIO, createConfigIO } from './config-io';
+export { ConfigIO, createConfigIO, SCHEMA_URL } from './config-io';
 export { readCliConfig, type CliConfig } from './cli-config';