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,78 @@
+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_PATTERN = /^https:\/\/schema\.agentcore\.aws\.dev\/.+\.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 as the first key', async () => {
+    const config = await readRawConfig(project.projectPath);
+    expect(config.$schema).toMatch(SCHEMA_URL_PATTERN);
+    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).toMatch(SCHEMA_URL_PATTERN);
+
+    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);
+
+    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,6 +1,5 @@
 import { APP_DIR, CONFIG_DIR, ConfigIO, setEnvVar, setSessionProjectRoot } from '../../../lib';
 import type {
-  AgentCoreProjectSpec,
   BuildType,
   DeployedState,
   ModelProvider,
@@ -19,29 +18,12 @@ import {
 } from '../../operations/agent/generate';
 import { executeImportAgent } from '../../operations/agent/import';
 import { credentialPrimitive } from '../../primitives/registry';
+import { createDefaultProjectSpec } from '../../project';
 import { CDKRenderer, createRenderer } from '../../templates';
 import type { CreateResult } from './types';
 import { mkdir } from 'fs/promises';
 import { join } from 'path';
 
-function createDefaultProjectSpec(projectName: string): AgentCoreProjectSpec {
-  return {
-    name: projectName,
-    version: 1,
-    agents: [],
-    memories: [],
-    credentials: [],
-    evaluators: [],
-    onlineEvalConfigs: [],
-    agentCoreGateways: [],
-    policyEngines: [],
-    tags: {
-      'agentcore:created-by': 'agentcore-cli',
-      'agentcore:project-name': projectName,
-    },
-  };
-}
-
 function createDefaultDeployedState(): DeployedState {
   return { targets: {} };
 }

src/cli/project.ts

@@ -0,0 +1,25 @@
+import { getSchemaUrlForVersion } from '../lib';
+import type { AgentCoreProjectSpec } from '../schema';
+import { SCHEMA_VERSION } from './constants';
+
+/**
+ * Create a default AgentCore project spec with standard defaults.
+ */
+export function createDefaultProjectSpec(projectName: string): AgentCoreProjectSpec {
+  return {
+    $schema: getSchemaUrlForVersion(SCHEMA_VERSION),
+    name: projectName,
+    version: SCHEMA_VERSION,
+    agents: [],
+    memories: [],
+    credentials: [],
+    evaluators: [],
+    onlineEvalConfigs: [],
+    agentCoreGateways: [],
+    policyEngines: [],
+    tags: {
+      'agentcore:created-by': 'agentcore-cli',
+      'agentcore:project-name': projectName,
+    },
+  };
+}

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

@@ -1,5 +1,5 @@
 import { APP_DIR, CONFIG_DIR, ConfigIO, findConfigRoot, setEnvVar, setSessionProjectRoot } from '../../../../lib';
-import type { AgentCoreProjectSpec, DeployedState } from '../../../../schema';
+import type { DeployedState } from '../../../../schema';
 import { getErrorMessage } from '../../../errors';
 import { CreateLogger } from '../../../logging';
 import { initGitRepo, setupPythonProject, writeEnvFile, writeGitignore } from '../../../operations';
@@ -13,6 +13,7 @@ import { executeImportAgent } from '../../../operations/agent/import';
 import { createManagedOAuthCredential } from '../../../primitives/auth-utils';
 import { computeDefaultCredentialEnvVarName } from '../../../primitives/credential-utils';
 import { credentialPrimitive } from '../../../primitives/registry';
+import { createDefaultProjectSpec } from '../../../project';
 import { CDKRenderer, createRenderer } from '../../../templates';
 import { type Step, areStepsComplete, hasStepError } from '../../components';
 import { withMinDuration } from '../../utils';
@@ -69,24 +70,6 @@ function getCreateSteps(projectName: string, agentConfig: AddAgentConfig | null)
   return steps;
 }
 
-function createDefaultProjectSpec(projectName: string): AgentCoreProjectSpec {
-  return {
-    name: projectName,
-    version: 1,
-    tags: {
-      'agentcore:created-by': 'agentcore-cli',
-      'agentcore:project-name': projectName,
-    },
-    agents: [],
-    memories: [],
-    credentials: [],
-    evaluators: [],
-    onlineEvalConfigs: [],
-    agentCoreGateways: [],
-    policyEngines: [],
-  };
-}
-
 function createDefaultDeployedState(): DeployedState {
   return {
     targets: {},

src/cli/tui/screens/remove/useRemoveFlow.ts

@@ -1,7 +1,7 @@
 import { ConfigIO, getWorkingDirectory } from '../../../../lib';
-import type { AgentCoreProjectSpec } from '../../../../schema';
 import { findStack } from '../../../cloudformation/stack-discovery';
 import { getErrorMessage } from '../../../errors';
+import { createDefaultProjectSpec } from '../../../project';
 import { type Step, areStepsComplete, hasStepError } from '../../components';
 import { withMinDuration } from '../../utils';
 import { useCallback, useEffect, useMemo, useState } from 'react';
@@ -27,20 +27,6 @@ function getRemoveSteps(): Step[] {
   return [{ label: 'Reset project schemas', status: 'pending' }];
 }
 
-function createDefaultProjectSpec(projectName: string): AgentCoreProjectSpec {
-  return {
-    name: projectName,
-    version: 1,
-    agents: [],
-    memories: [],
-    credentials: [],
-    evaluators: [],
-    onlineEvalConfigs: [],
-    agentCoreGateways: [],
-    policyEngines: [],
-  };
-}
-
 export function useRemoveFlow({ force, dryRun }: RemoveFlowOptions): RemoveFlowState {
   const [phase, setPhase] = useState<RemovePhase>('checking');
   const [steps, setSteps] = useState<Step[]>([]);

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

@@ -21,7 +21,9 @@ 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 function getSchemaUrlForVersion(version: number): string {
+  return `https://schema.agentcore.aws.dev/v${version}/agentcore.json`;
+}
 
 /**
  * Manages reading, writing, and validation of AgentCore configuration files
@@ -105,10 +107,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, getSchemaUrlForVersion } from './config-io';
 export { readCliConfig, type CliConfig } from './cli-config';