feat: implement modular primitive architecture

Refactor all resource types (agent, memory, credential, gateway,
gateway-target) into self-contained primitive classes that own the
full add/remove lifecycle. Each primitive extends BasePrimitive and
implements add(), remove(), previewRemove(), getRemovable(), and
registerCommands(). Primitives absorb scattered operation functions
and register their own CLI subcommands via a registry loop.

Author: tejaskash

AGENTS.md

@@ -10,9 +10,10 @@ src/
 ├── schema/            # Schema definitions with Zod validators
 ├── lib/               # Shared utilities (ConfigIO, packaging)
 ├── cli/               # CLI implementation
-│   ├── commands/      # CLI commands
+│   ├── primitives/    # Resource primitives (add/remove logic per resource type)
+│   ├── commands/      # CLI commands (thin Commander registration)
 │   ├── tui/           # Terminal UI (Ink/React)
-│   ├── operations/    # Business logic
+│   ├── operations/    # Shared business logic (schema mapping, deploy, etc.)
 │   ├── cdk/           # CDK toolkit wrapper for programmatic CDK operations
 │   └── templates/     # Project templating
 └── assets/            # Template assets vended to users
@@ -50,6 +51,25 @@ Note: CDK L3 constructs are in a separate package `@aws/agentcore-cdk`.
 
 - MCP gateway and tool support (`add gateway`, `add mcp-tool`) - currently hidden
 
+## Primitives Architecture
+
+All resource types (agent, memory, identity, gateway, mcp-tool) are modeled as **primitives** — self-contained classes
+in `src/cli/primitives/` that own the full add/remove lifecycle for their resource type.
+
+Each primitive extends `BasePrimitive` and implements: `add()`, `remove()`, `previewRemove()`, `getRemovable()`,
+`registerCommands()`, and `addScreen()`.
+
+Current primitives:
+
+- `AgentPrimitive` — agent creation (template + BYO), removal, credential resolution
+- `MemoryPrimitive` — memory creation with strategies, removal
+- `CredentialPrimitive` — credential/identity creation, .env management, removal
+- `GatewayPrimitive` — MCP gateway creation/removal (hidden, coming soon)
+- `GatewayTargetPrimitive` — MCP tool creation/removal with code generation (hidden, coming soon)
+
+Singletons are created in `registry.ts` and wired into CLI commands via `cli.ts`. See `src/cli/AGENTS.md` for details on
+adding new primitives.
+
 ## Vended CDK Project
 
 When users run `agentcore create`, we vend a CDK project at `agentcore/cdk/` that:
@@ -88,3 +108,16 @@ See `docs/TESTING.md` for details.
 ## Related Package
 
 - `@aws/agentcore-cdk` - CDK constructs used by vended projects
+
+## Code Style
+
+- Never use inline imports. Imports must always go at the top of the file.
+- Wheverever there is a requirement to use something that returns a success result and an error message you must use
+  this format
+
+```javascript
+{ success: Boolean, error?:string}
+```
+
+- Always look for existing types before creating a new type inline.
+- Re-usable constants must be defined in a constants file in the closest sensible subdirectory.

RefactorTest/AGENTS.md

@@ -0,0 +1,113 @@
+# AgentCore Project
+
+This project contains configuration and infrastructure for an Amazon Bedrock AgentCore application.
+
+The `agentcore/` directory serves as a declarative model of an AgentCore project along with a concrete implementation
+through the `agentcore/cdk/` project which is modeled to take the configs as input. The project uses a **flat resource
+model** where agents, memories, and credentials are top-level arrays.
+
+## Mental Model
+
+The project uses a **flat resource model**. Agents, memories, and credentials are independent top-level arrays in
+`agentcore.json`. There is no binding or attachment between resources in the schema — each resource is provisioned
+independently. To use a memory or credential from an agent, the application code discovers the resource at runtime
+(e.g., via environment variables or SDK calls).
+
+## Critical Invariants
+
+1. **Schema-First Authority:** The `.json` files are the absolute source of truth. Do not attempt to modify agent
+   behavior by editing the generated CDK code in `cdk/`.
+2. **Resource Identity:** The `name` field in the schema determines the CloudFormation Logical ID.
+   - **Renaming** an agent or target will **destroy and recreate** that resource.
+   - **Modifying** other fields (descriptions, config) will update the resource **in-place**.
+3. **1:1 Validation:** The schema maps directly to valid CloudFormation. If your JSON conforms to the types in
+   `.llm-context/`, it will deploy successfully.
+4. **Resource Removal:** To remove all resources, use `agentcore remove all`. To tear down deployed infrastructure, run
+   `agentcore deploy` after removal — it will detect the empty state and offer a teardown flow.
+
+## Directory Structure
+
+```
+myNewProject/
+├── AGENTS.md               # This file - AI coding assistant context
+├── agentcore/              # AgentCore configuration directory
+│   ├── agentcore.json      # Main project config (AgentCoreProjectSpec)
+│   ├── aws-targets.json    # Deployment targets
+│   ├── .llm-context/       # TypeScript type definitions for AI coding assistants
+│   │   ├── README.md       # Guide to using the schema files
+│   │   ├── agentcore.ts    # AgentCoreProjectSpec types
+│   │   └── aws-targets.ts  # AWS deployment target types
+│   └── cdk/                # AWS CDK project for deployment
+└── app/                    # Application code (if agents were created)
+```
+
+## Schema Reference
+
+The `agentcore/.llm-context/` directory contains TypeScript type definitions optimized for AI coding assistants. Each
+file maps to a JSON config file and includes validation constraints as comments.
+
+| JSON Config                  | Schema File                             | Root Type               |
+| ---------------------------- | --------------------------------------- | ----------------------- |
+| `agentcore/agentcore.json`   | `agentcore/.llm-context/agentcore.ts`   | `AgentCoreProjectSpec`  |
+| `agentcore/aws-targets.json` | `agentcore/.llm-context/aws-targets.ts` | `AWSDeploymentTarget[]` |
+
+### Key Types
+
+- **AgentCoreProjectSpec**: Root project configuration with `agents`, `memories`, `credentials` arrays
+- **AgentEnvSpec**: Agent configuration (runtime, entrypoint, code location)
+- **Memory**: Memory resource with strategies and expiry
+- **Credential**: API key credential provider
+
+### Common Enum Values
+
+- **BuildType**: `'CodeZip'` | `'Container'`
+- **NetworkMode**: `'PUBLIC'`
+- **RuntimeVersion**: `'PYTHON_3_10'` | `'PYTHON_3_11'` | `'PYTHON_3_12'` | `'PYTHON_3_13'`
+- **MemoryStrategyType**: `'SEMANTIC'` | `'SUMMARIZATION'` | `'USER_PREFERENCE'`
+
+### Build Types
+
+- **CodeZip**: Python source is packaged as a zip artifact and deployed directly to AgentCore Runtime.
+- **Container**: Agent code is built as a Docker container image. Requires a `Dockerfile` in the agent's `codeLocation`
+  directory. At deploy time, the source is uploaded to S3, built in CodeBuild (ARM64), pushed to a per-agent ECR
+  repository, and the container URI is provided to the AgentCore Runtime. For local development (`agentcore dev`), the
+  container is built and run locally with volume-mounted hot-reload.
+
+### Supported Frameworks (for template agents)
+
+- **Strands** - Works with Bedrock, Anthropic, OpenAI, Gemini
+- **LangChain_LangGraph** - Works with Bedrock, Anthropic, OpenAI, Gemini
+- **CrewAI** - Works with Bedrock, Anthropic, OpenAI, Gemini
+- **GoogleADK** - Gemini only
+- **OpenAIAgents** - OpenAI only
+- **AutoGen** - Works with Bedrock, Anthropic, OpenAI, Gemini
+
+### Specific Context
+
+Directory pathing to local projects is required for runtimes. Both CodeZip (Python zip) and Container (Docker image)
+deployment options are available.
+
+## Deployment
+
+The `agentcore/cdk/` subdirectory contains an AWS CDK node project.
+
+Deployments of this project are primarily intended to be orchestrated through the `agentcore deploy` command in the CLI.
+
+Alternatively, the project can be deployed directly as a traditional CDK project:
+
+```bash
+cd agentcore/cdk
+npm install
+npx cdk synth   # Preview CloudFormation template
+npx cdk deploy  # Deploy to AWS
+```
+
+## Editing Schemas
+
+When modifying JSON config files:
+
+1. Read the corresponding `agentcore/.llm-context/*.ts` file for type definitions
+2. Check validation constraint comments (`@regex`, `@min`, `@max`)
+3. Use exact enum values as string literals
+4. Use CloudFormation-safe names (alphanumeric, start with letter)
+5. Run `agentcore validate` command to verify changes.

RefactorTest/README.md

@@ -0,0 +1,79 @@
+# AgentCore Project
+
+This project was created with the [AgentCore CLI](https://github.com/aws/agentcore-cli).
+
+## Project Structure
+
+```
+.
+my-project/
+├── agentcore/
+│   ├── .env.local          # API keys (gitignored)
+│   ├── agentcore.json      # Resource specifications
+│   ├── aws-targets.json    # Deployment targets
+│   └── cdk/                # CDK infrastructure
+├── app/                    # Application code
+```
+
+## Getting Started
+
+### Prerequisites
+
+- **Node.js** 20.x or later
+- **uv** for Python agents ([install](https://docs.astral.sh/uv/getting-started/installation/))
+
+### Development
+
+Run your agent locally:
+
+```bash
+agentcore dev
+```
+
+### Deployment
+
+Deploy to AWS:
+
+```bash
+agentcore deploy
+```
+
+Or use CDK directly:
+
+```bash
+cd agentcore/cdk
+npx cdk deploy
+```
+
+## Configuration
+
+Edit the JSON files in `agentcore/` to configure your agents, memory, and credentials. See `agentcore/.llm-context/` for
+type definitions and validation constraints.
+
+The project uses a **flat resource model** where agents, memories, and credentials are top-level arrays in
+`agentcore.json`.
+
+## Commands
+
+| Command              | Description                                     |
+| -------------------- | ----------------------------------------------- |
+| `agentcore create`   | Create a new AgentCore project                  |
+| `agentcore add`      | Add resources (agent, memory, identity, target) |
+| `agentcore remove`   | Remove resources                                |
+| `agentcore dev`      | Run agent locally                               |
+| `agentcore deploy`   | Deploy to AWS                                   |
+| `agentcore status`   | Show deployment status                          |
+| `agentcore invoke`   | Invoke agent (local or deployed)                |
+| `agentcore package`  | Package agent artifacts                         |
+| `agentcore validate` | Validate configuration                          |
+| `agentcore update`   | Check for CLI updates                           |
+
+### Agent Types
+
+- **Template agents**: Created from framework templates (Strands, LangChain_LangGraph, GoogleADK, OpenAIAgents)
+- **BYO agents**: Bring your own code with `agentcore add agent --type byo`
+
+## Documentation
+
+- [AgentCore CLI Documentation](https://github.com/aws/agentcore-cli)
+- [Amazon Bedrock AgentCore](https://aws.amazon.com/bedrock/agentcore/)

RefactorTest/agentcore/.cli/deployed-state.json

@@ -0,0 +1,3 @@
+{
+  "targets": {}
+}

RefactorTest/agentcore/.gitignore

@@ -0,0 +1,15 @@
+# Secrets (local environment files are never committed)
+.env.local
+
+# CDK Build Artifacts
+cdk/cdk.out/
+cdk/node_modules/
+
+# CLI Internals
+.cli/*
+
+# Ephemeral Staging
+.cache/*
+
+# Exception: Commit the State
+!.cli/deployed-state.json

RefactorTest/agentcore/.llm-context/README.md

@@ -0,0 +1,15 @@
+# LLM Context Files
+
+**DO NOT EDIT THESE FILES** - They are read-only reference for AI coding assistants.
+
+## Files
+
+| File             | JSON Config        | Purpose                              |
+| ---------------- | ------------------ | ------------------------------------ |
+| `agentcore.ts`   | `agentcore.json`   | Project and agent environment config |
+| `aws-targets.ts` | `aws-targets.json` | Deployment targets                   |
+
+## Usage
+
+When editing schema JSON files, reference the corresponding `.ts` file here for type definitions and validation
+constraints (marked with `@regex`, `@min`, `@max`).

RefactorTest/agentcore/.llm-context/agentcore.ts

@@ -0,0 +1,94 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+/**
+ * READ-ONLY LLM CONTEXT - Do not edit this file.
+ *
+ * JSON File: agentcore/agentcore.json
+ * Purpose: Top-level project configuration with flat resource model
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ROOT SCHEMA: AgentCoreProjectSpec
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface AgentCoreProjectSpec {
+  name: string; // @regex ^[A-Za-z][A-Za-z0-9]{0,22}$ @max 23 - project name
+  version: number; // Schema version (integer)
+  agents: AgentEnvSpec[]; // Unique by name
+  memories: Memory[]; // Unique by name
+  credentials: Credential[]; // Unique by name
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ENUMS
+// ─────────────────────────────────────────────────────────────────────────────
+
+type BuildType = 'CodeZip' | 'Container';
+type PythonRuntime = 'PYTHON_3_10' | 'PYTHON_3_11' | 'PYTHON_3_12' | 'PYTHON_3_13';
+type NodeRuntime = 'NODE_18' | 'NODE_20' | 'NODE_22';
+type RuntimeVersion = PythonRuntime | NodeRuntime;
+type NetworkMode = 'PUBLIC' | 'VPC';
+type MemoryStrategyType = 'SEMANTIC' | 'SUMMARIZATION' | 'USER_PREFERENCE';
+type ModelProvider = 'Bedrock' | 'Gemini' | 'OpenAI' | 'Anthropic';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// NETWORK CONFIG
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface NetworkConfig {
+  subnets: string[]; // @regex ^subnet-[0-9a-zA-Z]{8,17}$ @min 1 @max 16
+  securityGroups: string[]; // @regex ^sg-[0-9a-zA-Z]{8,17}$ @min 1 @max 16
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// AGENT
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface AgentEnvSpec {
+  type: 'AgentCoreRuntime';
+  name: string; // @regex ^[a-zA-Z][a-zA-Z0-9_]{0,47}$ @max 48
+  build: BuildType;
+  entrypoint: string; // @regex ^[a-zA-Z0-9_][a-zA-Z0-9_/.-]*\.(py|ts|js)(:[a-zA-Z_][a-zA-Z0-9_]*)?$ e.g. "main.py:handler" or "index.ts"
+  codeLocation: string; // Directory path
+  runtimeVersion: RuntimeVersion;
+  envVars?: EnvVar[];
+  networkMode?: NetworkMode; // default 'PUBLIC'
+  networkConfig?: NetworkConfig; // Required when networkMode is 'VPC'
+  instrumentation?: Instrumentation; // OTel settings
+  modelProvider?: ModelProvider; // Model provider used by this agent
+}
+
+interface Instrumentation {
+  enableOtel: boolean; // default true - wrap entrypoint with opentelemetry-instrument
+}
+
+interface EnvVar {
+  name: string; // @regex ^[A-Za-z_][A-Za-z0-9_]*$ @max 255
+  value: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MEMORY
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface Memory {
+  type: 'AgentCoreMemory';
+  name: string; // @regex ^[a-zA-Z][a-zA-Z0-9_]{0,47}$ @max 48
+  eventExpiryDuration: number; // @min 7 @max 365 (days)
+  strategies: MemoryStrategy[]; // @min 1, unique by type
+}
+
+interface MemoryStrategy {
+  type: MemoryStrategyType;
+  name?: string; // @regex ^[a-zA-Z][a-zA-Z0-9_]{0,47}$ @max 48
+  description?: string;
+  namespaces?: string[];
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CREDENTIAL
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface Credential {
+  type: 'ApiKeyCredentialProvider';
+  name: string; // @regex ^[A-Za-z0-9_.-]+$ @min 3 @max 255
+}