teamcast 1.0.2 → 1.1.0

package/README.md

@@ -1,11 +1,17 @@
 # TeamCast
 
+[![CI](https://github.com/Katoshy/teamcast/actions/workflows/ci.yml/badge.svg)](https://github.com/Katoshy/teamcast/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/teamcast)](https://www.npmjs.com/package/teamcast)
+[![License](https://img.shields.io/github/license/Katoshy/teamcast)](https://github.com/Katoshy/teamcast/blob/main/LICENSE)
+
 CLI to design, generate, and validate multi-target agent teams for Claude Code and Codex from a single manifest.
 
 Define your agent team in one `teamcast.yaml` file. TeamCast validates the manifest, generates `.claude/` and/or `.codex/` config files, and keeps generated output in sync with the source config.
 
 ## Install
 
+Requires Node.js 24 or newer.
+
 ```bash
 npm install -g teamcast
 ```
@@ -16,6 +22,14 @@ Or run without installing:
 npx teamcast <command>
 ```
 
+## Community
+
+- Contribution guide: [CONTRIBUTING.md](./CONTRIBUTING.md)
+- Code of conduct: [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)
+- Security policy: [SECURITY.md](./SECURITY.md)
+- Bug reports and feature requests: use the GitHub issue templates
+- Pull requests: use the repository PR template and run `npm test` plus `npm run build` before opening one
+
 ## Quick Start
 
 ```bash
@@ -43,6 +57,7 @@ After `generate`, your project will have files for the selected target(s):
 - Codex target:
   - `.codex/config.toml` - workspace-level Codex config
   - `.codex/agents/<name>.toml` - one TOML config per agent
+  - `.agents/skills/<skill>/SKILL.md` - one stub file per unique skill
   - `AGENTS.md` - team-level instructions for Codex agents
 
 Use `teamcast init --target claude|codex|both` to choose which outputs are generated up front.
@@ -54,7 +69,7 @@ TeamCast now uses a canonical manifest shape with target-specific blocks:
 - `claude.agents.<name>` - native Claude Code runtime fields and doc outputs
 - `codex.agents.<name>` - native Codex runtime fields and TOML outputs
 - `<target>.agents.<name>.forge` - TeamCast-only metadata such as delegation graph
-- `project.environments` - active project environments such as `node`, `python` — auto-detected or explicit
+- `project.environments` - active project environments (`node`, `python`, `go`, `rust`, `java`, `ruby`, `docker`, `terraform`) — auto-detected or explicit
 
 TeamCast includes a built-in registry of capabilities, traits, instruction fragments, policy fragments, models, and skills. These are not serialized into `teamcast.yaml`.
 
@@ -273,7 +288,7 @@ Use `--yes` to skip confirmation.
 
 ### `create skill <name>`
 
-`teamcast create skill <name>` registers a new skill name on one agent, writes `teamcast.yaml`, and generates `.claude/skills/<name>/SKILL.md`.
+`teamcast create skill <name>` registers a new skill name on one agent, writes `teamcast.yaml`, and generates a target-specific stub: `.claude/skills/<name>/SKILL.md` for Claude or `.agents/skills/<name>/SKILL.md` for Codex.
 
 Rules and prompts:
 
@@ -310,7 +325,7 @@ teamcast generate --dry-run
 Behavior:
 
 - `generate` overwrites generated agent/docs/settings files
-- skill stub files under `.claude/skills/` are created only if missing
+- skill stub files under `.claude/skills/` and `.agents/skills/` are created only if missing
 - `--dry-run` shows what would be generated without writing anything
 
 ### `diff`
@@ -429,6 +444,7 @@ It targets:
 
 - `.claude/agents`
 - `.claude/skills`
+- generated Codex skill files under `.agents/skills/`
 - `.claude/settings.json`
 - `.claude/settings.local.json`
 - `CLAUDE.md`
@@ -467,9 +483,9 @@ Everything is defined in `teamcast.yaml` at the root of your project.
 
 For Claude targets, TeamCast renders `.claude/agents/<name>.md` and `CLAUDE.md` from `claude.agents.<name>`.
 
-For Codex targets, TeamCast renders `.codex/agents/<name>.toml` plus `.codex/config.toml` from `codex.agents.<name>`.
+For Codex targets, TeamCast renders `.codex/agents/<name>.toml` plus `.codex/config.toml` from `codex.agents.<name>`, and writes Codex skill docs to `.agents/skills/<skill>/`.
 
-`.codex/config.toml` is the workspace-level agent index. Concrete agent runtime config lives in `.codex/agents/<name>.toml`.
+`.codex/config.toml` is the workspace-level agent index. Concrete agent runtime config lives in `.codex/agents/<name>.toml`. Codex skill discovery uses `.agents/skills/`, not `.codex/`.
 
 Native Claude Code fields are rendered into frontmatter:
 
@@ -510,6 +526,50 @@ This means a **reviewer** (read + execute, no write) gets code patterns but NOT
 
 Custom agents work the same way — a `react-dev` with `write_files` + `execute` automatically gets the right fragments without any role-name matching.
 
+#### Built-in environments
+
+| Environment | Auto-detected by | Policy allows |
+|---|---|---|
+| `node` | `package.json` | `npm`, `npx`, `node` |
+| `python` | `pyproject.toml`, `requirements.txt`, `setup.py` | `pytest`, `python`, `uv`, `poetry` |
+| `go` | `go.mod` | `go build/test/run/vet/mod` |
+| `rust` | `Cargo.toml` | `cargo`, `rustfmt`, `clippy` |
+| `java` | `pom.xml`, `build.gradle` | `mvn`, `gradle`, `./gradlew` |
+| `ruby` | `Gemfile` | `bundle`, `rake`, `rspec` |
+| `docker` | `Dockerfile`, `docker-compose.yml` | `docker`, `docker compose` |
+| `terraform` | `main.tf`, `terraform.tf` | `terraform init/plan/validate/fmt` |
+
+#### Custom environments
+
+Drop a YAML file into `.agentforge/environments/` to add a new environment or override a builtin:
+
+```yaml
+# .agentforge/environments/bun.yaml
+id: bun
+description: "Bun runtime environment"
+detect_files:
+  - bun.lockb
+policy_rules:
+  sandbox:
+    enabled: true
+  allow:
+    - "Bash(bun *)"
+instruction_fragments:
+  bun_patterns:
+    content: |
+      This project uses Bun.
+      Use `bun install`, `bun run`, and `bun test`.
+    requires_capabilities:
+      - read_files
+```
+
+Reference it in `teamcast.yaml` by id:
+
+```yaml
+project:
+  environments: [node, bun]
+```
+
 ### Instruction Layers
 
 Agent prompts are composed from three layers:
@@ -518,7 +578,7 @@ Agent prompts are composed from three layers:
 |-------|--------|-------|
 | **instruction_blocks** | `teamcast.yaml` or preset | Project-specific behavior, workflow rules |
 | **instruction_fragments** | Built-in registry | Reusable role patterns (e.g. `feature-developer-workflow`) |
-| **environment instructions** | Built-in environments | Toolchain best practices, injected by capability |
+| **environment instructions** | Built-in + custom environments | Toolchain best practices, injected by capability |
 
 Presets provide sensible defaults for `instruction_blocks` and `instruction_fragments`. For deeper customization, edit `teamcast.yaml` and run `teamcast generate`.
 
@@ -642,6 +702,7 @@ claude:
 | `claude.tools`            | string[]                                                         | Native Claude Code tool allow-list                                                             |
 | `claude.disallowed_tools` | string[]                                                         | Native Claude Code tool deny-list                                                              |
 | `claude.skills`           | string[]                                                         | Skill names. Each unique skill generates `.claude/skills/<skill>/SKILL.md`                     |
+| `codex.skills`            | string[]                                                         | Skill names. Each unique skill generates `.agents/skills/<skill>/SKILL.md`                     |
 | `claude.max_turns`        | number                                                           | Maximum agentic turns                                                                          |
 | `claude.mcp_servers`      | object[]                                                         | MCP server definitions                                                                         |
 | `claude.permission_mode`  | `default \| acceptEdits \| bypassPermissions \| plan \| dontAsk` | Claude Code permission mode                                                                    |

package/dist/application/build-generated-files.js

@@ -7,8 +7,11 @@ export function buildGeneratedOutputs(team, targetName, options) {
     const renderer = target.renderer;
     const files = renderer.render(spec);
     if (!options.dryRun) {
-        const editable = files.filter((file) => isUserEditableGeneratedFile(file.path));
-        const generated = files.filter((file) => !isUserEditableGeneratedFile(file.path));
+        const editable = [];
+        const generated = [];
+        for (const file of files) {
+            (isUserEditableGeneratedFile(file.path) ? editable : generated).push(file);
+        }
         writeFiles(generated, options.cwd);
         writeFiles(editable, options.cwd, { skipExisting: true });
     }

package/dist/application/validate-team.js

@@ -7,6 +7,7 @@ import { hasErrors, printManifestValidationSummary, } from '../validator/reporte
 import { getTarget, getRegisteredTargetNames } from '../renderers/registry.js';
 import { applyEnvironmentInstructions, resolveEnvironmentIds, resolveEnvironmentPolicies, } from '../core/environment-resolver.js';
 import { checkManifestRegistry } from '../validator/checks/manifest-registry.js';
+import { builtinResourceLoader } from '../registry/resource-loader.js';
 export function evaluateTeam(manifest, options) {
     const schemaResult = validateSchema(manifest);
     if (!schemaResult.valid) {
@@ -15,6 +16,8 @@ export function evaluateTeam(manifest, options) {
             validationResults: [],
         };
     }
+    if (options?.cwd)
+        builtinResourceLoader.loadUserResources(options.cwd);
     const rawManifest = applyDefaults(schemaResult.data);
     const resolvedManifest = options?.cwd ? resolveEnvironmentPolicies(rawManifest, options.cwd) : rawManifest;
     const manifestRegistryResults = checkManifestRegistry(resolvedManifest);

package/dist/cli/manage.js

@@ -6,7 +6,7 @@ import { writeManifest } from '../manifest/writer.js';
 import { expandCapabilities } from '../core/capability-resolver.js';
 import { generate } from '../generator/index.js';
 import { defaultRegistry } from '../registry/index.js';
-import { printSuccess, printError, printHeader, printCommandSuccess, } from '../utils/chalk-helpers.js';
+import { printSuccess, printError, printHeader, printCommandSuccess, printNextSteps, } from '../utils/chalk-helpers.js';
 import { getTarget, getRegisteredTargetNames } from '../renderers/registry.js';
 import { evaluateTeam, teamHasBlockingIssues, printManifestValidation, } from '../application/validate-team.js';
 import { promptConfirm, promptInput, promptList, promptCheckbox, } from '../utils/prompts.js';
@@ -248,6 +248,10 @@ export async function runAddAgentCommand(name, options) {
     const nextTeam = addAgentToTeam(team, name, agent);
     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, options) {
     const cwd = process.cwd();
@@ -407,7 +411,11 @@ async function promptAgentConfig(name, targetContext) {
         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.`,
             },
         ],
     };

package/dist/cli/registrars/manage.js

@@ -12,7 +12,7 @@ export function registerManageCommands(program) {
     const createCmd = program.command('create').description('Create a new resource');
     createCmd
         .command('skill <name>')
-        .description('Create a new skill (generates stub file in .claude/skills/)')
+        .description('Create a new skill (Claude: .claude/skills/, Codex: .agents/skills/)')
         .option('--target <name>', 'Target block to modify')
         .action(async (name, options) => {
         const { runCreateSkillCommand } = await import('../manage.js');

package/dist/cli/reset.js

@@ -1,6 +1,6 @@
 import chalk from 'chalk';
 import { existsSync, rmSync, readdirSync, statSync } from 'fs';
-import { join } from 'path';
+import { dirname, join } from 'path';
 import { readManifest, ManifestError } from '../manifest/reader.js';
 import { generate } from '../generator/index.js';
 import { printSuccess, printHeader, printCommandSuccess, printDim, } from '../utils/chalk-helpers.js';
@@ -47,6 +47,22 @@ function deleteEmptyDirIfPossible(cwd, rel) {
         printSuccess(`Deleted ${rel}/`);
     }
 }
+function pruneEmptyAncestorDirs(cwd, rel) {
+    let current = dirname(rel);
+    while (current !== '.' && current !== '') {
+        const abs = join(cwd, current);
+        if (!existsSync(abs)) {
+            current = dirname(current);
+            continue;
+        }
+        if (readdirSync(abs).length > 0) {
+            break;
+        }
+        rmSync(abs, { recursive: true });
+        printSuccess(`Deleted ${current}/`);
+        current = dirname(current);
+    }
+}
 function deleteFiles(cwd, paths) {
     for (const rel of paths) {
         const abs = join(cwd, rel);
@@ -60,6 +76,7 @@ function deleteFiles(cwd, paths) {
             rmSync(abs);
         }
         printSuccess(`Deleted ${rel}`);
+        pruneEmptyAncestorDirs(cwd, rel);
     }
     deleteEmptyDirIfPossible(cwd, '.claude/agents');
     deleteEmptyDirIfPossible(cwd, '.claude/skills');

package/dist/core/environment-resolver.js

@@ -1,6 +1,6 @@
 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 { agentHasCapability } from './capability-resolver.js';
 /**
  * Resolves environment IDs from the manifest, combining:
@@ -80,31 +80,30 @@ function mergePoliciesSimple(base, extra) {
             }
             : 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;
+        })(),
     };
 }
 function resolveTargetPolicies(envPolicies, targetConfig) {

package/dist/generator/file-policies.js

@@ -1,3 +1,3 @@
 export function isUserEditableGeneratedFile(path) {
-    return path.startsWith('.claude/skills/');
+    return path.startsWith('.claude/skills/') || path.startsWith('.agents/skills/');
 }

package/dist/generator/index.js

@@ -3,7 +3,9 @@ import { buildGeneratedOutputs } from '../application/build-generated-files.js';
 import { getRegisteredTargetNames, getTarget } from '../renderers/registry.js';
 import { normalizeManifest } from '../manifest/normalize.js';
 import { applyEnvironmentInstructions, resolveEnvironmentIds, resolveEnvironmentPolicies, } from '../core/environment-resolver.js';
+import { builtinResourceLoader } from '../registry/resource-loader.js';
 export function generate(manifest, options) {
+    builtinResourceLoader.loadUserResources(options.cwd);
     const rawManifest = resolveEnvironmentPolicies(applyDefaults(manifest), options.cwd);
     const envIds = resolveEnvironmentIds(rawManifest, options.cwd);
     const rawManifestRecord = rawManifest;

package/dist/registry/environment-schema.js

@@ -0,0 +1,65 @@
+// Environment YAML schema — parse and convert YAML environment definitions
+// to runtime EnvironmentDef objects.
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { isCapability } from './types.js';
+// --- Validation ---
+export function parseEnvironmentYaml(raw) {
+    if (!raw || typeof raw !== 'object') {
+        throw new Error('Environment definition must be an object');
+    }
+    const obj = raw;
+    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) => 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;
+    if (policies.allow !== undefined) {
+        if (!Array.isArray(policies.allow) || !policies.allow.every((a) => 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;
+}
+// --- Conversion to runtime EnvironmentDef ---
+function toEnvironmentInstruction(value) {
+    if (typeof value === 'string')
+        return value;
+    return {
+        content: value.content,
+        requires_capabilities: value.requires_capabilities.filter(isCapability),
+    };
+}
+export function environmentYamlToDef(yaml) {
+    const fragments = {};
+    for (const [key, value] of Object.entries(yaml.instruction_fragments)) {
+        fragments[key] = toEnvironmentInstruction(value);
+    }
+    const def = {
+        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) => files.some((file) => existsSync(join(cwd, file)));
+    }
+    return def;
+}

package/dist/registry/environments.js

@@ -1,105 +1,17 @@
-import { existsSync } from 'fs';
-import { join } from 'path';
-const ENVIRONMENTS = {
-    node: {
-        id: 'node',
-        description: 'Node.js environment, auto-detected via package.json',
-        detect: (cwd) => 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) => 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'],
-            },
-        },
-    },
-};
+// Environment registry — delegates to ResourceLoader (YAML is the sole source).
+import { builtinResourceLoader } from './resource-loader.js';
+export function isEnvironmentId(value) {
+    return builtinResourceLoader.hasEnvironment(value);
+}
 export function getEnvironment(id) {
-    return ENVIRONMENTS[id];
+    const env = builtinResourceLoader.getEnvironment(id);
+    if (!env)
+        throw new Error(`Unknown environment "${id}"`);
+    return env;
 }
 export function listEnvironments() {
-    return Object.values(ENVIRONMENTS);
+    return builtinResourceLoader.listEnvironments();
 }
 export function detectEnvironments(cwd) {
-    return Object.values(ENVIRONMENTS)
-        .filter((env) => env.detect(cwd))
-        .map((env) => env.id);
+    return builtinResourceLoader.detectEnvironments(cwd);
 }

package/dist/registry/resource-loader.js

@@ -0,0 +1,78 @@
+// 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 { 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, cwd) {
+    return env.detect ? env.detect(cwd) : false;
+}
+export class ResourceLoader {
+    environments = new Map();
+    loadedDirs = new Set();
+    /** 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, allowOverride = false) {
+        if (this.loadedDirs.has(dir))
+            return;
+        this.loadedDirs.add(dir);
+        let files;
+        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) {
+        const envDir = join(projectDir, '.agentforge', 'environments');
+        this.loadEnvironmentsFromDir(envDir, true);
+    }
+    hasEnvironment(id) {
+        return this.environments.has(id);
+    }
+    getEnvironment(id) {
+        return this.environments.get(id);
+    }
+    listEnvironments() {
+        return [...this.environments.values()];
+    }
+    listEnvironmentIds() {
+        return [...this.environments.keys()];
+    }
+    detectEnvironments(cwd) {
+        return this.listEnvironments()
+            .filter((env) => matchesEnv(env, cwd))
+            .map((env) => env.id);
+    }
+}
+// Singleton — loads builtin environments from templates/environments/
+function createBuiltinLoader() {
+    const loader = new ResourceLoader();
+    loader.loadEnvironmentsFromDir(BUILTIN_ENVIRONMENTS_DIR);
+    return loader;
+}
+export const builtinResourceLoader = createBuiltinLoader();

package/dist/registry/types.js

@@ -14,7 +14,74 @@ export const CAPABILITY_IDS = [
 export function isCapability(value) {
     return CAPABILITY_IDS.includes(value);
 }
-export const ENVIRONMENT_IDS = ['node', 'python'];
-export function isEnvironmentId(value) {
-    return ENVIRONMENT_IDS.includes(value);
-}
+// --- Capability Trait (named bundle of capabilities) ---
+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',
+];
+// --- Policy Fragment ---
+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',
+];
+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',
+];

package/dist/renderers/codex/skill-md.js

@@ -1,8 +1,11 @@
-// Codex skill renderer — generates {id}/SKILL.md + agents/openai.yaml per skill.
+// Codex skill renderer — generates .agents/skills/{id}/SKILL.md + agents/openai.yaml per skill.
 import { defaultRegistry } from '../../registry/index.js';
+function getSkillBasePath(skillId) {
+    return `.agents/skills/${skillId}`;
+}
 // --- Frontmatter (Codex: name + description only) ---
 function buildFrontmatter(name, description) {
-    return ['---', `name: ${name}`, `description: ${description}`, '---'].join('\n');
+    return ['---', `name: ${JSON.stringify(name)}`, `description: ${JSON.stringify(description)}`, '---'].join('\n');
 }
 // --- Stub for unknown skills ---
 function generateSkillStub(skillName) {
@@ -59,15 +62,16 @@ function renderOpenaiYaml(skill) {
         if (skill.metadata.version)
             lines.push(`version: "${skill.metadata.version}"`);
     }
-    if (hasTools) {
+    if (hasTools || hasMcp) {
         lines.push('dependencies:');
+    }
+    if (hasTools) {
         lines.push('  tools:');
         for (const tool of skill.allowed_tools) {
             lines.push(`    - ${tool}`);
         }
     }
     if (hasMcp) {
-        lines.push('dependencies:');
         lines.push('  mcp_servers:');
         for (const server of skill.required_mcp_servers) {
             lines.push(`    - ${server}`);
@@ -78,7 +82,7 @@ function renderOpenaiYaml(skill) {
 // --- Companion files ---
 function renderCompanionFiles(skillId, skill) {
     const files = [];
-    const base = skillId;
+    const base = getSkillBasePath(skillId);
     if (skill.reference_files) {
         for (const [name, content] of Object.entries(skill.reference_files)) {
             files.push({ path: `${base}/references/${name}`, content });
@@ -108,14 +112,14 @@ export function renderCodexSkillMd(team) {
         const definition = defaultRegistry.getSkill(skillName);
         if (definition) {
             files.push({
-                path: `${skillName}/SKILL.md`,
+                path: `${getSkillBasePath(skillName)}/SKILL.md`,
                 content: renderSkillContent(definition),
             });
             files.push(...renderCompanionFiles(skillName, definition));
         }
         else {
             files.push({
-                path: `${skillName}/SKILL.md`,
+                path: `${getSkillBasePath(skillName)}/SKILL.md`,
                 content: generateSkillStub(skillName),
             });
         }

package/dist/validator/checks/manifest-registry.js

@@ -1,7 +1,7 @@
 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';
 /**
  * Pre-normalization manifest-level registry checks.

package/dist/validator/checks/team-graph-enhanced.js

@@ -66,5 +66,24 @@ export function checkTeamGraphEnhanced(team) {
             message: `Multiple root agents detected: ${roots.join(', ')} — consider a single orchestrator entry point`,
         });
     }
+    // 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;
 }

package/dist/validator/index.js

@@ -15,8 +15,8 @@ import { checkSkillRequirements } from './checks/skill-requirements.js';
 import { checkMcpServers } from './checks/mcp.js';
 import { checkTeamGraphEnhanced } from './checks/team-graph-enhanced.js';
 const CHECKERS = (skillMap, targetName) => [
-    checkRegistryReferences,
-    checkEnvironments,
+    checkRegistryReferences, // Phase 1
+    checkEnvironments, // Phase 9
     checkTraitCapabilities, // Phase 2
     (team) => checkCapabilityTools(team, skillMap), // Phase 3
     (team) => checkHandoffGraph(team, skillMap),

package/dist/wizard/index.js

@@ -76,7 +76,8 @@ export async function runWizard(options) {
     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`,
     ]);
 }

package/dist/wizard/steps/environment-selection.js

@@ -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 { promptCheckbox } from '../../utils/prompts.js';
 function mergeEnvironmentIds(...lists) {
     return [...new Set(lists.flatMap((list) => list ?? []))].filter(isEnvironmentId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teamcast",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "YAML-driven CLI to design, validate, and generate multi-target agent teams for Claude Code and Codex",
   "type": "module",
   "bin": {

package/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

package/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

package/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

package/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

package/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

package/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

package/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

package/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