diff --git a/.agents/skills/architecture-analysis/SKILL.md b/.agents/skills/architecture-analysis/SKILL.md
index 5da2dfc..e8ad702 100644
--- a/.agents/skills/architecture-analysis/SKILL.md
+++ b/.agents/skills/architecture-analysis/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: Architecture Analysis
-description: Deep codebase analysis: module boundaries, dependency graph, design patterns.
+description: "Deep codebase analysis: module boundaries, dependency graph, design patterns."
 ---
 
 # Architecture Analysis
diff --git a/.agents/skills/clean-code/SKILL.md b/.agents/skills/clean-code/SKILL.md
index 2c241aa..e7867eb 100644
--- a/.agents/skills/clean-code/SKILL.md
+++ b/.agents/skills/clean-code/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: Clean Code
-description: Follow clean code principles: small functions, meaningful names, no duplication.
+description: "Follow clean code principles: small functions, meaningful names, no duplication."
 ---
 
 # Clean Code
diff --git a/.agents/skills/triage/SKILL.md b/.agents/skills/triage/SKILL.md
index 74ddbec..e1e0ec3 100644
--- a/.agents/skills/triage/SKILL.md
+++ b/.agents/skills/triage/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: Triage
-description: Assess incoming requests: classify priority, estimate scope, identify blockers.
+description: "Assess incoming requests: classify priority, estimate scope, identify blockers."
 ---
 
 # Triage
diff --git a/src/application/validate-team.ts b/src/application/validate-team.ts
index 12f8c74..eec45b9 100644
--- a/src/application/validate-team.ts
+++ b/src/application/validate-team.ts
@@ -16,6 +16,7 @@ import {
   resolveEnvironmentPolicies,
 } from '../core/environment-resolver.js';
 import { checkManifestRegistry } from '../validator/checks/manifest-registry.js';
+import { builtinResourceLoader } from '../registry/resource-loader.js';
 
 export interface TeamValidationSummary {
   schemaErrors: Array<{ path: string; message: string }>;
@@ -36,6 +37,7 @@ export function evaluateTeam(
     };
   }
 
+  if (options?.cwd) builtinResourceLoader.loadUserResources(options.cwd);
   const rawManifest = applyDefaults(schemaResult.data);
   const resolvedManifest = options?.cwd ? resolveEnvironmentPolicies(rawManifest, options.cwd) : rawManifest;
 
diff --git a/src/cli/manage.ts b/src/cli/manage.ts
index 6883abc..997abbe 100644
--- a/src/cli/manage.ts
+++ b/src/cli/manage.ts
@@ -11,6 +11,7 @@ import {
   printError,
   printHeader,
   printCommandSuccess,
+  printNextSteps,
 } from '../utils/chalk-helpers.js';
 import type {
   CoreAgent,
@@ -364,6 +365,10 @@ export async function runAddAgentCommand(name: string, options: AddAgentOptions)
 
   applyManifestChanges(cwd, manifest, targetName, nextTeam);
   printCommandSuccess(`Agent "${name}" added and configuration regenerated`);
+  printNextSteps([
+    `Open ${chalk.bold('teamcast.yaml')} and fill in agent instructions based on ${chalk.yellow('// TODO')} comments`,
+    `Run ${chalk.bold('teamcast generate')} to apply your changes`,
+  ]);
 }
 
 export async function runCreateSkillCommand(name: string, options: TargetedOption): Promise<void> {
@@ -570,7 +575,11 @@ async function promptAgentConfig(name: string, targetContext: TargetContext): Pr
     instructions: [
       {
         kind: 'behavior',
-        content: `You are ${name}. Focus on the responsibilities described in your role and use your allowed tools appropriately.`,
+        content: `You are ${name}.\n// TODO: Describe the agent's core personality, rules, and constraints here.\n// Example: "You are a strict security auditor. Never trust user input."`,
+      },
+      {
+        kind: 'workflow',
+        content: `// TODO: Define the step-by-step process the agent should follow.\n// 1. Read the provided context.\n// 2. Perform analysis.\n// 3. Output the result.`,
       },
     ],
   };
diff --git a/src/core/environment-resolver.ts b/src/core/environment-resolver.ts
index b2a9a07..7b09135 100644
--- a/src/core/environment-resolver.ts
+++ b/src/core/environment-resolver.ts
@@ -3,7 +3,7 @@ import type { CoreTeam } from './types.js';
 import type { PoliciesConfig, TeamCastManifest, TargetConfig } from '../manifest/types.js';
 import { TARGET_NAMES, getManifestTargetConfig, setManifestTargetConfig } from '../manifest/targets.js';
 import { getEnvironment, detectEnvironments } from '../registry/environments.js';
-import { isEnvironmentId } from '../registry/types.js';
+import { isEnvironmentId } from '../registry/environments.js';
 import type { CapabilityToolMap, EnvironmentId, EnvironmentInstruction } from '../registry/types.js';
 import { agentHasCapability } from './capability-resolver.js';
 import type { TargetContext } from '../renderers/target-context.js';
@@ -98,31 +98,30 @@ function mergePoliciesSimple(base: PoliciesConfig, extra: PoliciesConfig): Polic
           }
         : undefined,
     hooks: base.hooks || extra.hooks
-      ? {
-          pre_tool_use: [...(base.hooks?.pre_tool_use ?? []), ...(extra.hooks?.pre_tool_use ?? [])].length > 0
-            ? [...(base.hooks?.pre_tool_use ?? []), ...(extra.hooks?.pre_tool_use ?? [])]
-            : undefined,
-          post_tool_use: [...(base.hooks?.post_tool_use ?? []), ...(extra.hooks?.post_tool_use ?? [])].length > 0
-            ? [...(base.hooks?.post_tool_use ?? []), ...(extra.hooks?.post_tool_use ?? [])]
-            : undefined,
-          notification: [...(base.hooks?.notification ?? []), ...(extra.hooks?.notification ?? [])].length > 0
-            ? [...(base.hooks?.notification ?? []), ...(extra.hooks?.notification ?? [])]
-            : undefined,
-        }
+      ? (() => {
+          const pre = [...(base.hooks?.pre_tool_use ?? []), ...(extra.hooks?.pre_tool_use ?? [])];
+          const post = [...(base.hooks?.post_tool_use ?? []), ...(extra.hooks?.post_tool_use ?? [])];
+          const notif = [...(base.hooks?.notification ?? []), ...(extra.hooks?.notification ?? [])];
+          return {
+            pre_tool_use: pre.length > 0 ? pre : undefined,
+            post_tool_use: post.length > 0 ? post : undefined,
+            notification: notif.length > 0 ? notif : undefined,
+          };
+        })()
       : undefined,
     network: base.network || extra.network
-      ? {
-          allowed_domains: [...new Set([
+      ? (() => {
+          const domains = [...new Set([
             ...(base.network?.allowed_domains ?? []),
             ...(extra.network?.allowed_domains ?? []),
-          ])].length > 0
-            ? [...new Set([...(base.network?.allowed_domains ?? []), ...(extra.network?.allowed_domains ?? [])])]
-            : undefined,
-        }
-      : undefined,
-    assertions: [...(base.assertions ?? []), ...(extra.assertions ?? [])].length > 0
-      ? [...(base.assertions ?? []), ...(extra.assertions ?? [])]
+          ])];
+          return { allowed_domains: domains.length > 0 ? domains : undefined };
+        })()
       : undefined,
+    assertions: (() => {
+      const merged = [...(base.assertions ?? []), ...(extra.assertions ?? [])];
+      return merged.length > 0 ? merged : undefined;
+    })(),
   };
 }
 
diff --git a/src/generator/index.ts b/src/generator/index.ts
index d16ee1c..52416de 100644
--- a/src/generator/index.ts
+++ b/src/generator/index.ts
@@ -10,11 +10,13 @@ import {
   resolveEnvironmentIds,
   resolveEnvironmentPolicies,
 } from '../core/environment-resolver.js';
+import { builtinResourceLoader } from '../registry/resource-loader.js';
 
 export function generate(
   manifest: TeamCastManifest,
   options: BuildGeneratedOutputsOptions,
 ) {
+  builtinResourceLoader.loadUserResources(options.cwd);
   const rawManifest = resolveEnvironmentPolicies(applyDefaults(manifest), options.cwd);
   const envIds = resolveEnvironmentIds(rawManifest, options.cwd);
 
diff --git a/src/registry/environment-schema.ts b/src/registry/environment-schema.ts
new file mode 100644
index 0000000..15ed65f
--- /dev/null
+++ b/src/registry/environment-schema.ts
@@ -0,0 +1,101 @@
+// Environment YAML schema — parse and convert YAML environment definitions
+// to runtime EnvironmentDef objects.
+
+import { existsSync } from 'fs';
+import { join } from 'path';
+import type { CapabilityId, EnvironmentDef, EnvironmentInstruction } from './types.js';
+import { isCapability } from './types.js';
+
+// --- YAML shape (what users write in .yaml files) ---
+
+export interface EnvironmentYamlInstruction {
+  content: string;
+  requires_capabilities: string[];
+}
+
+export interface EnvironmentYaml {
+  id: string;
+  description: string;
+  detect_files?: string[];
+  policy_rules: {
+    sandbox?: { enabled?: boolean };
+    allow?: string[];
+  };
+  instruction_fragments: Record<string, string | EnvironmentYamlInstruction>;
+}
+
+// --- Validation ---
+
+export function parseEnvironmentYaml(raw: unknown): EnvironmentYaml {
+  if (!raw || typeof raw !== 'object') {
+    throw new Error('Environment definition must be an object');
+  }
+
+  const obj = raw as Record<string, unknown>;
+
+  if (typeof obj.id !== 'string' || !obj.id) {
+    throw new Error('Environment definition requires a non-empty "id" field');
+  }
+  if (typeof obj.description !== 'string') {
+    throw new Error(`Environment "${obj.id}": "description" must be a string`);
+  }
+
+  if (obj.detect_files !== undefined) {
+    if (!Array.isArray(obj.detect_files) || !obj.detect_files.every((f: unknown) => typeof f === 'string')) {
+      throw new Error(`Environment "${obj.id}": "detect_files" must be a string array`);
+    }
+  }
+
+  if (!obj.policy_rules || typeof obj.policy_rules !== 'object') {
+    throw new Error(`Environment "${obj.id}": "policy_rules" must be an object`);
+  }
+
+  const policies = obj.policy_rules as Record<string, unknown>;
+  if (policies.allow !== undefined) {
+    if (!Array.isArray(policies.allow) || !policies.allow.every((a: unknown) => typeof a === 'string')) {
+      throw new Error(`Environment "${obj.id}": "policy_rules.allow" must be a string array`);
+    }
+  }
+
+  if (!obj.instruction_fragments || typeof obj.instruction_fragments !== 'object') {
+    throw new Error(`Environment "${obj.id}": "instruction_fragments" must be an object`);
+  }
+
+  return obj as unknown as EnvironmentYaml;
+}
+
+// --- Conversion to runtime EnvironmentDef ---
+
+function toEnvironmentInstruction(
+  value: string | EnvironmentYamlInstruction,
+): string | EnvironmentInstruction {
+  if (typeof value === 'string') return value;
+  return {
+    content: value.content,
+    requires_capabilities: value.requires_capabilities.filter(isCapability) as CapabilityId[],
+  };
+}
+
+export function environmentYamlToDef(yaml: EnvironmentYaml): EnvironmentDef {
+  const fragments: Record<string, string | EnvironmentInstruction> = {};
+  for (const [key, value] of Object.entries(yaml.instruction_fragments)) {
+    fragments[key] = toEnvironmentInstruction(value);
+  }
+
+  const def: EnvironmentDef = {
+    id: yaml.id,
+    description: yaml.description,
+    policyRules: {
+      sandbox: yaml.policy_rules.sandbox,
+      allow: yaml.policy_rules.allow,
+    },
+    instructionFragments: fragments,
+  };
+
+  if (yaml.detect_files?.length) {
+    const files = yaml.detect_files;
+    def.detect = (cwd: string) => files.some((file) => existsSync(join(cwd, file)));
+  }
+
+  return def;
+}
diff --git a/src/registry/environments.ts b/src/registry/environments.ts
index 9f4a5b1..cbfcd46 100644
--- a/src/registry/environments.ts
+++ b/src/registry/environments.ts
@@ -1,111 +1,22 @@
-import { existsSync } from 'fs';
-import { join } from 'path';
-import type { EnvironmentDef, EnvironmentId } from './types.js';
+// Environment registry — delegates to ResourceLoader (YAML is the sole source).
 
-const ENVIRONMENTS: Record<EnvironmentId, EnvironmentDef> = {
-  node: {
-    id: 'node',
-    description: 'Node.js environment, auto-detected via package.json',
-    detect: (cwd: string) => existsSync(join(cwd, 'package.json')),
-    policyRules: {
-      sandbox: { enabled: true },
-      allow: [
-        'Bash(npm run *)',
-        'Bash(npm test *)',
-        'Bash(npx *)',
-        'Bash(npm install)',
-        'Bash(node *)',
-      ],
-    },
-    instructionFragments: {
-      node_code_patterns: {
-        content: [
-          'This is a Node.js project.',
-          'Use ESM module syntax (import/export). All relative imports must use .js extensions.',
-          'Prefer named exports over default exports.',
-          'Use TypeScript strict mode when tsconfig.json is present.',
-        ].join('\n'),
-        requires_capabilities: ['read_files'],
-      },
-      node_development: {
-        content: [
-          'Install dependencies with `npm install`.',
-          'Use `npm run <script>` to execute package.json scripts.',
-          'Prefer async/await over raw Promises or callbacks.',
-          'Handle errors at system boundaries. Use typed error classes where the project defines them.',
-        ].join('\n'),
-        requires_capabilities: ['write_files'],
-      },
-      node_testing: {
-        content: [
-          'Run tests with `npm test`.',
-          'Run a specific test file with `npx vitest run <path>` (vitest) or `npx jest <path>` (jest).',
-          'Always run tests after making changes to verify nothing broke.',
-          'Follow existing test patterns: check the tests/ directory for conventions before writing new tests.',
-        ].join('\n'),
-        requires_capabilities: ['execute', 'write_files'],
-      },
-    },
-  },
-  python: {
-    id: 'python',
-    description: 'Python environment, auto-detected via pyproject.toml or requirements.txt',
-    detect: (cwd: string) =>
-      existsSync(join(cwd, 'pyproject.toml')) ||
-      existsSync(join(cwd, 'requirements.txt')) ||
-      existsSync(join(cwd, 'setup.py')),
-    policyRules: {
-      sandbox: { enabled: true },
-      allow: [
-        'Bash(pytest *)',
-        'Bash(python -m pytest *)',
-        'Bash(uv run *)',
-        'Bash(poetry run *)',
-        'Bash(python *)',
-      ],
-    },
-    instructionFragments: {
-      python_code_patterns: {
-        content: [
-          'This is a Python project.',
-          'Follow PEP 8 style conventions.',
-          'Use type hints for function signatures and class attributes.',
-          'Prefer pathlib.Path over os.path for file operations.',
-        ].join('\n'),
-        requires_capabilities: ['read_files'],
-      },
-      python_development: {
-        content: [
-          'If using poetry: `poetry install` and `poetry run <cmd>`. If using uv: `uv sync` and `uv run <cmd>`.',
-          'Otherwise use pip and virtualenv.',
-          'Use structured logging (logging module) instead of print statements.',
-          'Handle exceptions with specific types, not bare except clauses.',
-        ].join('\n'),
-        requires_capabilities: ['write_files'],
-      },
-      python_testing: {
-        content: [
-          'Run tests with `pytest`. If using poetry or uv, prefix with `poetry run` or `uv run`.',
-          'Run a specific test: `pytest <path>::<test_name>`.',
-          'Always run tests after changes. Follow existing test patterns in the tests/ directory.',
-          'Use fixtures for shared setup. Prefer parametrize for similar test cases.',
-        ].join('\n'),
-        requires_capabilities: ['execute', 'write_files'],
-      },
-    },
-  },
-};
+import type { EnvironmentDef } from './types.js';
+import { builtinResourceLoader } from './resource-loader.js';
 
-export function getEnvironment(id: EnvironmentId): EnvironmentDef {
-  return ENVIRONMENTS[id];
+export function isEnvironmentId(value: string): boolean {
+  return builtinResourceLoader.hasEnvironment(value);
+}
+
+export function getEnvironment(id: string): EnvironmentDef {
+  const env = builtinResourceLoader.getEnvironment(id);
+  if (!env) throw new Error(`Unknown environment "${id}"`);
+  return env;
 }
 
 export function listEnvironments(): EnvironmentDef[] {
-  return Object.values(ENVIRONMENTS);
+  return builtinResourceLoader.listEnvironments();
 }
 
-export function detectEnvironments(cwd: string): EnvironmentId[] {
-  return Object.values(ENVIRONMENTS)
-    .filter((env) => env.detect(cwd))
-    .map((env) => env.id);
+export function detectEnvironments(cwd: string): string[] {
+  return builtinResourceLoader.detectEnvironments(cwd);
 }
diff --git a/src/registry/resource-loader.ts b/src/registry/resource-loader.ts
new file mode 100644
index 0000000..e5ae0b0
--- /dev/null
+++ b/src/registry/resource-loader.ts
@@ -0,0 +1,93 @@
+// ResourceLoader — scans directories for YAML resource files and registers them.
+
+import { readFileSync, readdirSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { parse } from 'yaml';
+import type { EnvironmentDef } from './types.js';
+import { parseEnvironmentYaml, environmentYamlToDef } from './environment-schema.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const BUILTIN_ENVIRONMENTS_DIR = join(__dirname, '../../templates/environments');
+
+/** Check whether an environment matches the given cwd. */
+function matchesEnv(env: EnvironmentDef, cwd: string): boolean {
+  return env.detect ? env.detect(cwd) : false;
+}
+
+export class ResourceLoader {
+  private environments = new Map<string, EnvironmentDef>();
+  private loadedDirs = new Set<string>();
+
+  /** Load all *.yaml files from a directory as environment definitions.
+   * Each directory is only loaded once — adding files after the first call has no effect. */
+  loadEnvironmentsFromDir(dir: string, allowOverride = false): void {
+    if (this.loadedDirs.has(dir)) return;
+    this.loadedDirs.add(dir);
+
+    let files: string[];
+    try {
+      files = readdirSync(dir).filter((f) => f.endsWith('.yaml') || f.endsWith('.yml'));
+    } catch {
+      return; // Directory does not exist or is inaccessible
+    }
+
+    for (const file of files) {
+      const filePath = join(dir, file);
+      try {
+        const raw = parse(readFileSync(filePath, 'utf-8'));
+        const yaml = parseEnvironmentYaml(raw);
+        const def = environmentYamlToDef(yaml);
+
+        if (this.environments.has(def.id) && !allowOverride) continue;
+        this.environments.set(def.id, def);
+      } catch (err) {
+        if (allowOverride) {
+          // User-defined file — surface the error so the user can fix it
+          process.stderr.write(
+            `[agentforge] Warning: skipping "${filePath}": ${err instanceof Error ? err.message : String(err)}\n`,
+          );
+        }
+        // Builtin files should never fail — skip silently
+      }
+    }
+  }
+
+  /** Load user-defined resources from a project's .agentforge/ directory. */
+  loadUserResources(projectDir: string): void {
+    const envDir = join(projectDir, '.agentforge', 'environments');
+    this.loadEnvironmentsFromDir(envDir, true);
+  }
+
+  hasEnvironment(id: string): boolean {
+    return this.environments.has(id);
+  }
+
+  getEnvironment(id: string): EnvironmentDef | undefined {
+    return this.environments.get(id);
+  }
+
+  listEnvironments(): EnvironmentDef[] {
+    return [...this.environments.values()];
+  }
+
+  listEnvironmentIds(): string[] {
+    return [...this.environments.keys()];
+  }
+
+  detectEnvironments(cwd: string): string[] {
+    return this.listEnvironments()
+      .filter((env) => matchesEnv(env, cwd))
+      .map((env) => env.id);
+  }
+}
+
+// Singleton — loads builtin environments from templates/environments/
+function createBuiltinLoader(): ResourceLoader {
+  const loader = new ResourceLoader();
+  loader.loadEnvironmentsFromDir(BUILTIN_ENVIRONMENTS_DIR);
+  return loader;
+}
+
+export const builtinResourceLoader = createBuiltinLoader();
diff --git a/src/registry/types.ts b/src/registry/types.ts
index cf011b3..0d1b354 100644
--- a/src/registry/types.ts
+++ b/src/registry/types.ts
@@ -29,18 +29,22 @@ export interface CapabilityDefinition {
 
 // --- Capability Trait (named bundle of capabilities) ---
 
-export type CapabilityTraitId =
-  | 'base-read'
-  | 'file-authoring'
-  | 'command-execution'
-  | 'web-research'
-  | 'delegation'
-  | 'interaction'
-  | 'notebook-editing'
-  | 'no-file-edits'
-  | 'no-commands'
-  | 'no-web'
-  | 'full-access';
+export const BUILTIN_CAPABILITY_TRAIT_IDS = [
+  'base-read',
+  'file-authoring',
+  'command-execution',
+  'web-research',
+  'delegation',
+  'interaction',
+  'notebook-editing',
+  'no-file-edits',
+  'no-commands',
+  'no-web',
+  'full-access',
+] as const;
+
+export type BuiltinCapabilityTraitId = typeof BUILTIN_CAPABILITY_TRAIT_IDS[number];
+export type CapabilityTraitId = string;
 
 export interface CapabilityTraitDef {
   id: CapabilityTraitId;
@@ -50,15 +54,19 @@ export interface CapabilityTraitDef {
 
 // --- Policy Fragment ---
 
-export type PolicyFragmentId =
-  | 'allow-git-read'
-  | 'allow-git-write'
-  | 'ask-git-push'
-  | 'deny-destructive-shell'
-  | 'deny-network-downloads'
-  | 'deny-dynamic-exec'
-  | 'deny-env-files'
-  | 'sandbox-default';
+export const BUILTIN_POLICY_FRAGMENT_IDS = [
+  'allow-git-read',
+  'allow-git-write',
+  'ask-git-push',
+  'deny-destructive-shell',
+  'deny-network-downloads',
+  'deny-dynamic-exec',
+  'deny-env-files',
+  'sandbox-default',
+] as const;
+
+export type BuiltinPolicyFragmentId = typeof BUILTIN_POLICY_FRAGMENT_IDS[number];
+export type PolicyFragmentId = string;
 
 export interface PolicyFragmentDef {
   id: PolicyFragmentId;
@@ -69,51 +77,55 @@ export interface PolicyFragmentDef {
 
 export type InstructionKind = 'behavior' | 'workflow' | 'safety' | 'style' | 'delegation';
 
-export type InstructionFragmentId =
-  | 'coordination-core'
-  | 'delegate-first'
-  | 'planning-core'
-  | 'planning-read-only'
-  | 'research-core'
-  | 'research-citation'
-  | 'research-no-file-edits'
-  | 'development-core'
-  | 'development-workflow'
-  | 'tester-core'
-  | 'tester-read-only'
-  | 'review-core'
-  | 'review-feedback'
-  | 'security-audit-core'
-  | 'security-audit-severity'
-  | 'research-handoff'
-  | 'secure-planning'
-  | 'secure-development'
-  | 'secure-development-tests'
-  | 'security-review-gate'
-  | 'post-audit-review'
-  | 'solo-dev-core'
-  | 'solo-dev-workflow'
-  | 'solo-dev-style'
-  | 'feature-orchestrator-workflow'
-  | 'feature-orchestrator-output'
-  | 'feature-planner-workflow'
-  | 'feature-planner-read-only'
-  | 'feature-developer-core'
-  | 'feature-developer-workflow'
-  | 'feature-developer-summary'
-  | 'feature-reviewer-checklist'
-  | 'feature-reviewer-style'
-  | 'research-orchestrator-core'
-  | 'research-orchestrator-workflow'
-  | 'research-orchestrator-output'
-  | 'research-planner-core'
-  | 'research-planner-constraints'
-  | 'research-developer-core'
-  | 'research-developer-tests'
-  | 'secure-orchestrator-core'
-  | 'secure-orchestrator-workflow'
-  | 'secure-orchestrator-gate'
-  | 'post-audit-review-core';
+export const BUILTIN_INSTRUCTION_FRAGMENT_IDS = [
+  'coordination-core',
+  'delegate-first',
+  'planning-core',
+  'planning-read-only',
+  'research-core',
+  'research-citation',
+  'research-no-file-edits',
+  'development-core',
+  'development-workflow',
+  'tester-core',
+  'tester-read-only',
+  'review-core',
+  'review-feedback',
+  'security-audit-core',
+  'security-audit-severity',
+  'research-handoff',
+  'secure-planning',
+  'secure-development',
+  'secure-development-tests',
+  'security-review-gate',
+  'post-audit-review',
+  'solo-dev-core',
+  'solo-dev-workflow',
+  'solo-dev-style',
+  'feature-orchestrator-workflow',
+  'feature-orchestrator-output',
+  'feature-planner-workflow',
+  'feature-planner-read-only',
+  'feature-developer-core',
+  'feature-developer-workflow',
+  'feature-developer-summary',
+  'feature-reviewer-checklist',
+  'feature-reviewer-style',
+  'research-orchestrator-core',
+  'research-orchestrator-workflow',
+  'research-orchestrator-output',
+  'research-planner-core',
+  'research-planner-constraints',
+  'research-developer-core',
+  'research-developer-tests',
+  'secure-orchestrator-core',
+  'secure-orchestrator-workflow',
+  'secure-orchestrator-gate',
+  'post-audit-review-core',
+] as const;
+
+export type BuiltinInstructionFragmentId = typeof BUILTIN_INSTRUCTION_FRAGMENT_IDS[number];
+export type InstructionFragmentId = string;
 
 export interface InstructionFragmentDef {
   id: InstructionFragmentId;
@@ -160,13 +172,7 @@ export interface SkillDefinition {
 
 // --- Environment ---
 
-export type EnvironmentId = 'node' | 'python';
-
-export const ENVIRONMENT_IDS: readonly EnvironmentId[] = ['node', 'python'];
-
-export function isEnvironmentId(value: string): value is EnvironmentId {
-  return (ENVIRONMENT_IDS as readonly string[]).includes(value);
-}
+export type EnvironmentId = string;
 
 export interface EnvironmentInstruction {
   content: string;
@@ -174,9 +180,9 @@ export interface EnvironmentInstruction {
 }
 
 export interface EnvironmentDef {
-  id: EnvironmentId;
+  id: string;
   description: string;
-  detect: (cwd: string) => boolean;
+  detect?: (cwd: string) => boolean;
   policyRules: {
     sandbox?: { enabled?: boolean };
     allow?: string[];
diff --git a/src/renderers/codex/skill-md.ts b/src/renderers/codex/skill-md.ts
index 955f2d0..78f5df4 100644
--- a/src/renderers/codex/skill-md.ts
+++ b/src/renderers/codex/skill-md.ts
@@ -12,7 +12,7 @@ function getSkillBasePath(skillId: string): string {
 // --- Frontmatter (Codex: name + description only) ---
 
 function buildFrontmatter(name: string, description: string): string {
-  return ['---', `name: ${name}`, `description: ${description}`, '---'].join('\n');
+  return ['---', `name: ${JSON.stringify(name)}`, `description: ${JSON.stringify(description)}`, '---'].join('\n');
 }
 
 // --- Stub for unknown skills ---
diff --git a/src/validator/checks/manifest-registry.ts b/src/validator/checks/manifest-registry.ts
index 54adc30..67df954 100644
--- a/src/validator/checks/manifest-registry.ts
+++ b/src/validator/checks/manifest-registry.ts
@@ -3,7 +3,7 @@ import type { ValidationResult } from '../types.js';
 import { isCapabilityTraitName } from '../../registry/traits.js';
 import { isPolicyFragmentId } from '../../registry/policy-fragments.js';
 import { isInstructionFragmentId } from '../../registry/instruction-fragments.js';
-import { isEnvironmentId } from '../../registry/types.js';
+import { isEnvironmentId } from '../../registry/environments.js';
 import { getManifestTargetEntries } from '../../manifest/targets.js';
 
 /**
diff --git a/src/validator/checks/team-graph-enhanced.ts b/src/validator/checks/team-graph-enhanced.ts
index 963455a..425e29f 100644
--- a/src/validator/checks/team-graph-enhanced.ts
+++ b/src/validator/checks/team-graph-enhanced.ts
@@ -80,5 +80,25 @@ export function checkTeamGraphEnhanced(team: CoreTeam): ValidationResult[] {
     });
   }
 
+  // HANDOFF_CAPABILITY_MISMATCH — delegating to an agent with no tools
+  for (const [agentId, agent] of agentEntries) {
+    for (const target of agent.metadata?.handoffs ?? []) {
+      const targetAgent = team.agents[target];
+      if (!targetAgent) continue; // already caught by checkHandoffGraph
+
+      const targetTools = targetAgent.runtime.tools ?? [];
+      if (targetTools.length === 0) {
+        results.push({
+          severity: 'warning',
+          category: 'Team graph',
+          code: 'HANDOFF_CAPABILITY_MISMATCH',
+          phase: 'team-graph',
+          message: `Agent "${agentId}" hands off to "${target}" but "${target}" has no capabilities — delegation may be ineffective`,
+          agent: agentId,
+        });
+      }
+    }
+  }
+
   return results;
 }
diff --git a/src/validator/index.ts b/src/validator/index.ts
index 3c3523c..e0290b9 100644
--- a/src/validator/index.ts
+++ b/src/validator/index.ts
@@ -20,8 +20,8 @@ import type { TargetContext } from '../renderers/target-context.js';
 import type { CapabilityToolMap } from '../registry/types.js';
 
 const CHECKERS = (skillMap: CapabilityToolMap, targetName: string): Checker[] => [
-  checkRegistryReferences,
-  checkEnvironments,
+  checkRegistryReferences,                              // Phase 1
+  checkEnvironments,                                    // Phase 9
   checkTraitCapabilities,                               // Phase 2
   (team) => checkCapabilityTools(team, skillMap),       // Phase 3
   (team) => checkHandoffGraph(team, skillMap),
diff --git a/src/wizard/index.ts b/src/wizard/index.ts
index bc37fd4..a944b47 100644
--- a/src/wizard/index.ts
+++ b/src/wizard/index.ts
@@ -102,7 +102,8 @@ export async function runWizard(options: WizardOptions): Promise<void> {
   printCommandSuccess(`Agent team initialized for project "${rawManifest.project.name}"`);
   printManifestValidation(validation);
   printNextSteps([
+    `Open ${chalk.bold('teamcast.yaml')} and fill in agent instructions based on ${chalk.yellow('// TODO')} comments`,
     `${chalk.bold('teamcast explain')} - view the team structure`,
-    `Edit ${chalk.bold('teamcast.yaml')} and run ${chalk.bold('teamcast generate')} to apply changes`,
+    `Run ${chalk.bold('teamcast generate')} to apply your changes`,
   ]);
 }
diff --git a/src/wizard/steps/environment-selection.ts b/src/wizard/steps/environment-selection.ts
index a8ece03..f9ac2d1 100644
--- a/src/wizard/steps/environment-selection.ts
+++ b/src/wizard/steps/environment-selection.ts
@@ -1,6 +1,6 @@
 import chalk from 'chalk';
 import { detectEnvironments, listEnvironments } from '../../registry/environments.js';
-import { isEnvironmentId } from '../../registry/types.js';
+import { isEnvironmentId } from '../../registry/environments.js';
 import type { EnvironmentId } from '../../registry/types.js';
 import { promptCheckbox } from '../../utils/prompts.js';
 
diff --git a/templates/environments/docker.yaml b/templates/environments/docker.yaml
new file mode 100644
index 0000000..4d6bf04
--- /dev/null
+++ b/templates/environments/docker.yaml
@@ -0,0 +1,36 @@
+id: docker
+description: "Docker environment, auto-detected via Dockerfile"
+detect_files:
+  - Dockerfile
+  - docker-compose.yml
+  - docker-compose.yaml
+  - compose.yml
+  - compose.yaml
+policy_rules:
+  sandbox:
+    enabled: true
+  allow:
+    - "Bash(docker build *)"
+    - "Bash(docker run *)"
+    - "Bash(docker compose *)"
+    - "Bash(docker-compose *)"
+    - "Bash(docker ps *)"
+    - "Bash(docker logs *)"
+    - "Bash(docker images *)"
+instruction_fragments:
+  docker_patterns:
+    content: |
+      This project uses Docker.
+      Use multi-stage builds to minimize image size.
+      Prefer alpine or slim base images where practical.
+      Use .dockerignore to exclude unnecessary files from build context.
+    requires_capabilities:
+      - read_files
+  docker_development:
+    content: |
+      Build images with `docker build -t <tag> .`.
+      Use `docker compose up` for multi-container setups.
+      Pin base image versions for reproducible builds.
+      Order Dockerfile instructions to maximize layer caching (dependencies before source code).
+    requires_capabilities:
+      - write_files
diff --git a/templates/environments/go.yaml b/templates/environments/go.yaml
new file mode 100644
index 0000000..61ce532
--- /dev/null
+++ b/templates/environments/go.yaml
@@ -0,0 +1,40 @@
+id: go
+description: "Go environment, auto-detected via go.mod"
+detect_files:
+  - go.mod
+policy_rules:
+  sandbox:
+    enabled: true
+  allow:
+    - "Bash(go build *)"
+    - "Bash(go test *)"
+    - "Bash(go run *)"
+    - "Bash(go vet *)"
+    - "Bash(go mod *)"
+    - "Bash(go generate *)"
+instruction_fragments:
+  go_code_patterns:
+    content: |
+      This is a Go project.
+      Follow standard Go conventions and idiomatic patterns.
+      Use gofmt/goimports for formatting.
+      Prefer short variable names in small scopes, descriptive names in larger scopes.
+    requires_capabilities:
+      - read_files
+  go_development:
+    content: |
+      Use `go build ./...` to compile all packages.
+      Use `go mod tidy` to clean up dependencies.
+      Handle errors explicitly — do not ignore returned errors.
+      Prefer returning errors over panicking.
+    requires_capabilities:
+      - write_files
+  go_testing:
+    content: |
+      Run tests with `go test ./...`.
+      Run a specific test: `go test -run TestName ./path/to/package`.
+      Use table-driven tests for multiple cases.
+      Always run tests after changes to verify nothing broke.
+    requires_capabilities:
+      - execute
+      - write_files
diff --git a/templates/environments/java.yaml b/templates/environments/java.yaml
new file mode 100644
index 0000000..77cbb97
--- /dev/null
+++ b/templates/environments/java.yaml
@@ -0,0 +1,41 @@
+id: java
+description: "Java environment, auto-detected via pom.xml or build.gradle"
+detect_files:
+  - pom.xml
+  - build.gradle
+  - build.gradle.kts
+policy_rules:
+  sandbox:
+    enabled: true
+  allow:
+    - "Bash(mvn *)"
+    - "Bash(gradle *)"
+    - "Bash(./gradlew *)"
+    - "Bash(java *)"
+    - "Bash(javac *)"
+instruction_fragments:
+  java_code_patterns:
+    content: |
+      This is a Java project.
+      Follow standard Java naming conventions (camelCase for methods, PascalCase for classes).
+      Use appropriate access modifiers.
+      Prefer composition over inheritance where practical.
+    requires_capabilities:
+      - read_files
+  java_development:
+    content: |
+      If using Maven: `mvn compile` to build, `mvn package` to create artifacts.
+      If using Gradle: `./gradlew build` or `gradle build`.
+      Handle exceptions with specific types, not bare catch blocks.
+      Use try-with-resources for AutoCloseable resources.
+    requires_capabilities:
+      - write_files
+  java_testing:
+    content: |
+      Run tests with `mvn test` (Maven) or `./gradlew test` (Gradle).
+      Run a specific test: `mvn -Dtest=TestClassName test` or `./gradlew test --tests TestClassName`.
+      Use JUnit 5 annotations. Follow existing test patterns in the project.
+      Always run tests after changes to verify nothing broke.
+    requires_capabilities:
+      - execute
+      - write_files
diff --git a/templates/environments/node.yaml b/templates/environments/node.yaml
new file mode 100644
index 0000000..eeeb31a
--- /dev/null
+++ b/templates/environments/node.yaml
@@ -0,0 +1,39 @@
+id: node
+description: "Node.js environment, auto-detected via package.json"
+detect_files:
+  - package.json
+policy_rules:
+  sandbox:
+    enabled: true
+  allow:
+    - "Bash(npm run *)"
+    - "Bash(npm test *)"
+    - "Bash(npx *)"
+    - "Bash(npm install)"
+    - "Bash(node *)"
+instruction_fragments:
+  node_code_patterns:
+    content: |
+      This is a Node.js project.
+      Use ESM module syntax (import/export). All relative imports must use .js extensions.
+      Prefer named exports over default exports.
+      Use TypeScript strict mode when tsconfig.json is present.
+    requires_capabilities:
+      - read_files
+  node_development:
+    content: |
+      Install dependencies with `npm install`.
+      Use `npm run <script>` to execute package.json scripts.
+      Prefer async/await over raw Promises or callbacks.
+      Handle errors at system boundaries. Use typed error classes where the project defines them.
+    requires_capabilities:
+      - write_files
+  node_testing:
+    content: |
+      Run tests with `npm test`.
+      Run a specific test file with `npx vitest run <path>` (vitest) or `npx jest <path>` (jest).
+      Always run tests after making changes to verify nothing broke.
+      Follow existing test patterns: check the tests/ directory for conventions before writing new tests.
+    requires_capabilities:
+      - execute
+      - write_files
diff --git a/templates/environments/python.yaml b/templates/environments/python.yaml
new file mode 100644
index 0000000..c004738
--- /dev/null
+++ b/templates/environments/python.yaml
@@ -0,0 +1,41 @@
+id: python
+description: "Python environment, auto-detected via pyproject.toml or requirements.txt"
+detect_files:
+  - pyproject.toml
+  - requirements.txt
+  - setup.py
+policy_rules:
+  sandbox:
+    enabled: true
+  allow:
+    - "Bash(pytest *)"
+    - "Bash(python -m pytest *)"
+    - "Bash(uv run *)"
+    - "Bash(poetry run *)"
+    - "Bash(python *)"
+instruction_fragments:
+  python_code_patterns:
+    content: |
+      This is a Python project.
+      Follow PEP 8 style conventions.
+      Use type hints for function signatures and class attributes.
+      Prefer pathlib.Path over os.path for file operations.
+    requires_capabilities:
+      - read_files
+  python_development:
+    content: |
+      If using poetry: `poetry install` and `poetry run <cmd>`. If using uv: `uv sync` and `uv run <cmd>`.
+      Otherwise use pip and virtualenv.
+      Use structured logging (logging module) instead of print statements.
+      Handle exceptions with specific types, not bare except clauses.
+    requires_capabilities:
+      - write_files
+  python_testing:
+    content: |
+      Run tests with `pytest`. If using poetry or uv, prefix with `poetry run` or `uv run`.
+      Run a specific test: `pytest <path>::<test_name>`.
+      Always run tests after changes. Follow existing test patterns in the tests/ directory.
+      Use fixtures for shared setup. Prefer parametrize for similar test cases.
+    requires_capabilities:
+      - execute
+      - write_files
diff --git a/templates/environments/ruby.yaml b/templates/environments/ruby.yaml
new file mode 100644
index 0000000..a5b26a8
--- /dev/null
+++ b/templates/environments/ruby.yaml
@@ -0,0 +1,39 @@
+id: ruby
+description: "Ruby environment, auto-detected via Gemfile"
+detect_files:
+  - Gemfile
+policy_rules:
+  sandbox:
+    enabled: true
+  allow:
+    - "Bash(bundle *)"
+    - "Bash(rake *)"
+    - "Bash(rspec *)"
+    - "Bash(ruby *)"
+    - "Bash(rails *)"
+instruction_fragments:
+  ruby_code_patterns:
+    content: |
+      This is a Ruby project.
+      Follow Ruby style conventions (snake_case for methods/variables, PascalCase for classes).
+      Use frozen string literal comments where the project follows that convention.
+      Prefer blocks and enumerators over manual loops.
+    requires_capabilities:
+      - read_files
+  ruby_development:
+    content: |
+      Install dependencies with `bundle install`.
+      Use `bundle exec` to run commands in the context of the bundle.
+      Prefer keyword arguments for methods with multiple optional parameters.
+      Handle errors with specific exception classes.
+    requires_capabilities:
+      - write_files
+  ruby_testing:
+    content: |
+      Run tests with `bundle exec rspec` (RSpec) or `bundle exec rake test` (Minitest).
+      Run a specific test: `bundle exec rspec path/to/spec.rb:LINE`.
+      Follow existing test patterns. Use shared examples for reusable test behaviors.
+      Always run tests after changes to verify nothing broke.
+    requires_capabilities:
+      - execute
+      - write_files
diff --git a/templates/environments/rust.yaml b/templates/environments/rust.yaml
new file mode 100644
index 0000000..9bcba49
--- /dev/null
+++ b/templates/environments/rust.yaml
@@ -0,0 +1,41 @@
+id: rust
+description: "Rust environment, auto-detected via Cargo.toml"
+detect_files:
+  - Cargo.toml
+policy_rules:
+  sandbox:
+    enabled: true
+  allow:
+    - "Bash(cargo build *)"
+    - "Bash(cargo test *)"
+    - "Bash(cargo run *)"
+    - "Bash(cargo clippy *)"
+    - "Bash(cargo fmt *)"
+    - "Bash(cargo check *)"
+    - "Bash(rustfmt *)"
+instruction_fragments:
+  rust_code_patterns:
+    content: |
+      This is a Rust project.
+      Follow Rust idioms: prefer ownership over borrowing when practical.
+      Use clippy lints to catch common mistakes.
+      Prefer Result/Option over panicking.
+    requires_capabilities:
+      - read_files
+  rust_development:
+    content: |
+      Use `cargo build` to compile the project.
+      Use `cargo check` for fast feedback without full compilation.
+      Run `cargo clippy` before committing to catch lint issues.
+      Use `cargo fmt` to format code consistently.
+    requires_capabilities:
+      - write_files
+  rust_testing:
+    content: |
+      Run tests with `cargo test`.
+      Run a specific test: `cargo test test_name`.
+      Use `#[cfg(test)]` modules for unit tests within source files.
+      Always run tests after changes to verify nothing broke.
+    requires_capabilities:
+      - execute
+      - write_files
diff --git a/templates/environments/terraform.yaml b/templates/environments/terraform.yaml
new file mode 100644
index 0000000..35d1a90
--- /dev/null
+++ b/templates/environments/terraform.yaml
@@ -0,0 +1,31 @@
+id: terraform
+description: "Terraform environment, auto-detected via main.tf"
+detect_files:
+  - main.tf
+  - terraform.tf
+policy_rules:
+  sandbox:
+    enabled: true
+  allow:
+    - "Bash(terraform init *)"
+    - "Bash(terraform plan *)"
+    - "Bash(terraform validate *)"
+    - "Bash(terraform fmt *)"
+    - "Bash(terraform state *)"
+instruction_fragments:
+  terraform_patterns:
+    content: |
+      This project uses Terraform for infrastructure as code.
+      Follow HCL conventions: use snake_case for resource names and variables.
+      Organize configuration into logical files (main.tf, variables.tf, outputs.tf).
+      Use modules for reusable infrastructure components.
+    requires_capabilities:
+      - read_files
+  terraform_development:
+    content: |
+      Run `terraform init` to initialize providers and modules.
+      Run `terraform plan` to preview changes before applying.
+      Run `terraform validate` and `terraform fmt` before committing.
+      Never apply changes without reviewing the plan first.
+    requires_capabilities:
+      - write_files
diff --git a/tests/unit/generator/codex-skill-md.test.ts b/tests/unit/generator/codex-skill-md.test.ts
index dc0c45e..0567419 100644
--- a/tests/unit/generator/codex-skill-md.test.ts
+++ b/tests/unit/generator/codex-skill-md.test.ts
@@ -49,12 +49,39 @@ describe('renderCodexSkillMd', () => {
     const files = renderCodexSkillMd(normalizeManifest(applyDefaults(manifest), codexTarget));
     const content = files.find((f) => f.path.endsWith('SKILL.md'))!.content;
     expect(content).toMatch(/^---\n/);
-    expect(content).toContain('name: Test First');
-    expect(content).toContain('description: ');
+    expect(content).toContain('name: "Test First"');
+    expect(content).toContain('description: "Write tests before implementation. Verify each change with a failing test first."');
     // Codex frontmatter does NOT include allowed-tools
     expect(content).not.toContain('allowed-tools');
   });
 
+  it('always quotes frontmatter values', () => {
+    const skillId = 'codex-colon-description-test';
+    if (!defaultRegistry.getSkill(skillId)) {
+      defaultRegistry.registerSkills({
+        [skillId]: {
+          id: skillId,
+          name: 'Codex Colon Description Test',
+          description: 'Checks YAML safety: colons should not break parsing.',
+          instructions: 'Render safe frontmatter.',
+          source: 'user',
+        },
+      });
+    }
+
+    const manifest: TeamCastManifest = {
+      ...base,
+      codex: { agents: {
+        dev: { description: 'Dev', skills: [skillId] },
+      } },
+    };
+
+    const files = renderCodexSkillMd(normalizeManifest(applyDefaults(manifest), codexTarget));
+    const content = files.find((f) => f.path === `.agents/skills/${skillId}/SKILL.md`)!.content;
+    expect(content).toContain('name: "Codex Colon Description Test"');
+    expect(content).toContain('description: "Checks YAML safety: colons should not break parsing."');
+  });
+
   it('renders instructions from builtin skill definition', () => {
     const manifest: TeamCastManifest = {
       ...base,
@@ -78,7 +105,7 @@ describe('renderCodexSkillMd', () => {
     const files = renderCodexSkillMd(normalizeManifest(applyDefaults(manifest), codexTarget));
     const content = files[0].content;
     expect(content).toMatch(/^---\n/);
-    expect(content).toContain('name: My Custom Skill');
+    expect(content).toContain('name: "My Custom Skill"');
     expect(content).toContain('## When to use this skill');
     expect(content).toContain('## Steps');
   });
diff --git a/tests/unit/registry/builtin-environments.test.ts b/tests/unit/registry/builtin-environments.test.ts
new file mode 100644
index 0000000..c757103
--- /dev/null
+++ b/tests/unit/registry/builtin-environments.test.ts
@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest';
+import { isEnvironmentId, listEnvironments, getEnvironment } from '../../../src/registry/environments.js';
+
+const EXPECTED_IDS = ['node', 'python', 'go', 'rust', 'java', 'ruby', 'docker', 'terraform'];
+
+describe('builtin environments (YAML-loaded)', () => {
+  it('loads all 8 builtin environments', () => {
+    const envs = listEnvironments();
+    expect(envs.length).toBe(8);
+  });
+
+  it('has all expected environment IDs', () => {
+    const ids = listEnvironments().map((e) => e.id).sort();
+    expect(ids).toEqual([...EXPECTED_IDS].sort());
+  });
+
+  for (const id of EXPECTED_IDS) {
+    describe(id, () => {
+      it('isEnvironmentId returns true', () => {
+        expect(isEnvironmentId(id)).toBe(true);
+      });
+
+      it('getEnvironment returns a definition', () => {
+        const env = getEnvironment(id);
+        expect(env).toBeDefined();
+        expect(env.id).toBe(id);
+        expect(env.description).toBeTruthy();
+      });
+
+      it('has policy rules with allow list', () => {
+        const env = getEnvironment(id);
+        expect(env.policyRules).toBeDefined();
+        expect(Array.isArray(env.policyRules.allow)).toBe(true);
+        expect(env.policyRules.allow!.length).toBeGreaterThan(0);
+      });
+
+      it('has instruction fragments', () => {
+        const env = getEnvironment(id);
+        expect(Object.keys(env.instructionFragments).length).toBeGreaterThan(0);
+      });
+
+      it('has a working detect function', () => {
+        const env = getEnvironment(id);
+        // All YAML-loaded environments get a detect function from detectRule
+        expect(typeof env.detect).toBe('function');
+      });
+    });
+  }
+
+  it('isEnvironmentId returns false for unknown IDs', () => {
+    expect(isEnvironmentId('not-a-real-env-xyz')).toBe(false);
+    expect(isEnvironmentId('')).toBe(false);
+  });
+});
diff --git a/tests/unit/registry/environment-yaml.test.ts b/tests/unit/registry/environment-yaml.test.ts
new file mode 100644
index 0000000..78d8621
--- /dev/null
+++ b/tests/unit/registry/environment-yaml.test.ts
@@ -0,0 +1,79 @@
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { parse } from 'yaml';
+import { describe, expect, it } from 'vitest';
+import { parseEnvironmentYaml, environmentYamlToDef } from '../../../src/registry/environment-schema.js';
+import { getEnvironment } from '../../../src/registry/environments.js';
+import type { EnvironmentInstruction } from '../../../src/registry/types.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ENVIRONMENTS_DIR = join(__dirname, '../../../templates/environments');
+
+function loadYamlEnv(name: string) {
+  const raw = parse(readFileSync(join(ENVIRONMENTS_DIR, `${name}.yaml`), 'utf-8'));
+  return environmentYamlToDef(parseEnvironmentYaml(raw));
+}
+
+describe('environment YAML definitions', () => {
+  for (const envId of ['node', 'python'] as const) {
+    describe(envId, () => {
+      it('parses without errors', () => {
+        expect(() => loadYamlEnv(envId)).not.toThrow();
+      });
+
+      it('has matching id and description', () => {
+        const yaml = loadYamlEnv(envId);
+        const ts = getEnvironment(envId);
+        expect(yaml.id).toBe(ts.id);
+        expect(yaml.description).toBe(ts.description);
+      });
+
+      it('has matching policy rules', () => {
+        const yaml = loadYamlEnv(envId);
+        const ts = getEnvironment(envId);
+        expect(yaml.policyRules.sandbox).toEqual(ts.policyRules.sandbox);
+        expect(yaml.policyRules.allow).toEqual(ts.policyRules.allow);
+      });
+
+      it('has matching instruction fragment keys', () => {
+        const yaml = loadYamlEnv(envId);
+        const ts = getEnvironment(envId);
+        expect(Object.keys(yaml.instructionFragments).sort()).toEqual(
+          Object.keys(ts.instructionFragments).sort(),
+        );
+      });
+
+      it('has matching instruction fragment capabilities', () => {
+        const yaml = loadYamlEnv(envId);
+        const ts = getEnvironment(envId);
+        for (const key of Object.keys(ts.instructionFragments)) {
+          const tsValue = ts.instructionFragments[key];
+          const yamlValue = yaml.instructionFragments[key];
+          if (typeof tsValue === 'string') {
+            expect(typeof yamlValue).toBe('string');
+          } else {
+            const tsInstr = tsValue as EnvironmentInstruction;
+            const yamlInstr = yamlValue as EnvironmentInstruction;
+            expect(yamlInstr.requires_capabilities).toEqual(tsInstr.requires_capabilities);
+          }
+        }
+      });
+
+      it('detect function works correctly', () => {
+        const yaml = loadYamlEnv(envId);
+        expect(yaml.detect).toBeDefined();
+        // detect should be a function generated from detect_files
+        expect(typeof yaml.detect).toBe('function');
+      });
+    });
+  }
+
+  it('rejects invalid YAML (missing id)', () => {
+    expect(() => parseEnvironmentYaml({ description: 'test' })).toThrow(/id/);
+  });
+
+  it('rejects invalid YAML (missing policy_rules)', () => {
+    expect(() => parseEnvironmentYaml({ id: 'test', description: 'test' })).toThrow(/policy_rules/);
+  });
+});
diff --git a/tests/unit/registry/user-overrides.test.ts b/tests/unit/registry/user-overrides.test.ts
new file mode 100644
index 0000000..26b1d1c
--- /dev/null
+++ b/tests/unit/registry/user-overrides.test.ts
@@ -0,0 +1,111 @@
+import { mkdirSync, writeFileSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+import { ResourceLoader } from '../../../src/registry/resource-loader.js';
+
+const TEST_ENV_YAML = `
+id: custom-env
+description: "Custom test environment"
+detect_files:
+  - custom.config.js
+policy_rules:
+  sandbox:
+    enabled: true
+  allow:
+    - "Bash(custom-tool *)"
+instruction_fragments:
+  custom_patterns:
+    content: "This is a custom environment."
+    requires_capabilities:
+      - read_files
+`;
+
+const NODE_OVERRIDE_YAML = `
+id: node
+description: "Custom Node.js override with extra tools"
+detect_files:
+  - package.json
+policy_rules:
+  sandbox:
+    enabled: true
+  allow:
+    - "Bash(npm run *)"
+    - "Bash(pnpm *)"
+instruction_fragments:
+  node_custom:
+    content: "Use pnpm instead of npm."
+    requires_capabilities:
+      - read_files
+`;
+
+describe('user resource overrides', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = join(tmpdir(), `agentforge-test-${Date.now()}`);
+    mkdirSync(join(tempDir, '.agentforge', 'environments'), { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('loads a custom user environment', () => {
+    writeFileSync(join(tempDir, '.agentforge', 'environments', 'custom-env.yaml'), TEST_ENV_YAML);
+
+    const loader = new ResourceLoader();
+    loader.loadUserResources(tempDir);
+
+    expect(loader.hasEnvironment('custom-env')).toBe(true);
+    const env = loader.getEnvironment('custom-env')!;
+    expect(env.description).toBe('Custom test environment');
+    expect(env.policyRules.allow).toContain('Bash(custom-tool *)');
+  });
+
+  it('user environment can override a builtin', () => {
+    writeFileSync(join(tempDir, '.agentforge', 'environments', 'node.yaml'), NODE_OVERRIDE_YAML);
+
+    const loader = new ResourceLoader();
+    // First load builtins
+    loader.loadEnvironmentsFromDir(join(tempDir, 'fake-builtins'));
+    // Then load user overrides
+    loader.loadUserResources(tempDir);
+
+    const env = loader.getEnvironment('node')!;
+    expect(env.description).toBe('Custom Node.js override with extra tools');
+    expect(env.policyRules.allow).toContain('Bash(pnpm *)');
+  });
+
+  it('does nothing when .agentforge directory does not exist', () => {
+    const loader = new ResourceLoader();
+    const emptyDir = join(tmpdir(), `agentforge-empty-${Date.now()}`);
+    mkdirSync(emptyDir, { recursive: true });
+
+    expect(() => loader.loadUserResources(emptyDir)).not.toThrow();
+    expect(loader.listEnvironments()).toHaveLength(0);
+
+    rmSync(emptyDir, { recursive: true, force: true });
+  });
+
+  it('loadUserResources is idempotent', () => {
+    writeFileSync(join(tempDir, '.agentforge', 'environments', 'custom-env.yaml'), TEST_ENV_YAML);
+
+    const loader = new ResourceLoader();
+    loader.loadUserResources(tempDir);
+    loader.loadUserResources(tempDir); // second call should be no-op
+
+    expect(loader.listEnvironments()).toHaveLength(1);
+  });
+
+  it('detects custom environments by cwd', () => {
+    writeFileSync(join(tempDir, '.agentforge', 'environments', 'custom-env.yaml'), TEST_ENV_YAML);
+    writeFileSync(join(tempDir, 'custom.config.js'), '// marker');
+
+    const loader = new ResourceLoader();
+    loader.loadUserResources(tempDir);
+
+    const detected = loader.detectEnvironments(tempDir);
+    expect(detected).toContain('custom-env');
+  });
+});
diff --git a/tests/unit/validator/manifest-registry.test.ts b/tests/unit/validator/manifest-registry.test.ts
index a452623..b73184b 100644
--- a/tests/unit/validator/manifest-registry.test.ts
+++ b/tests/unit/validator/manifest-registry.test.ts
@@ -167,7 +167,7 @@ describe('checkManifestRegistry', () => {
       const manifest = makeManifest({
         project: {
           name: 'test',
-          environments: ['node', 'ruby'],
+          environments: ['node', 'not-a-real-env-xyz'],
         },
       });
 
@@ -176,7 +176,7 @@ describe('checkManifestRegistry', () => {
       expect(errors).toHaveLength(1);
       expect(errors[0].severity).toBe('error');
       expect(errors[0].phase).toBe('registry');
-      expect(errors[0].message).toContain('"ruby"');
+      expect(errors[0].message).toContain('"not-a-real-env-xyz"');
     });
 
     it('produces no error for valid environments', () => {