Feature/wizard dx agent template

.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

.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

.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

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;
 

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.`,
       },
     ],
   };

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;
+    })(),
   };
 }
 

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);
 

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;
+}

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);
 }