@thatix.io/context-first-agents-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thiago Abreu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# Context-First Agents CLI
+
+> Evolution of [context-first-cli](https://www.npmjs.com/package/context-first-cli): the
+> same project-agnostic methodology management **plus** dynamic, ephemeral AI-agent
+> orchestration derived from your specs.
+
+The Node CLI only **scaffolds and manages** (orchestrator, repos, config, worktrees-ready
+sessions). All agent **orchestration intelligence lives in `.md` command templates** that
+your AI tool runs — never in Node. This keeps the whole flow inside your existing
+command-driven workflow.
+
+```
+spec → complexity → execution DAG → context contract per node → ephemeral agents
+```
+
+---
+
+## What's new vs. context-first-cli
+
+| | context-first-cli | context-first-agents-cli |
+|---|---|---|
+| Work decomposition | you pick which command to run, in a fixed pipeline | `/orchestrate` derives the **minimum agent graph** from the spec |
+| Agents | one serial agent over one big shared context | **N ephemeral agents**, one per responsibility/repo, each with an isolated context |
+| Parallelism | none (sequential phases) | implementers per repo run in parallel, joined by `dependsOn` |
+| Context | everything in one bucket | **context contract per agent** (`select-do-not-dump`, `mustNotAssume`) |
+| Risk review | you remember to trigger it | `riskSignals` auto-trigger an adversarial reviewer |
+
+It stays **100% project-agnostic**: the core knows nothing about your stack or domain.
+Everything specific lives in `context-manifest.json`.
+
+---
+
+## Install
+
+```bash
+npm install -g context-first-agents-cli
+# binaries: context-agents  (alias: cfa)
+```
+
+## Quick start
+
+```bash
+# 1. Create an orchestrator
+context-agents create:orchestrator my-orchestrator
+cd my-orchestrator
+
+# 2. Register your repositories (with hints so the orchestrator can route)
+context-agents add:repo
+
+# 3. Validate the setup
+context-agents doctor
+
+# 4. In your AI tool, run the orchestration command:
+/orchestrate <ISSUE-ID or path/to/spec.md>
+```
+
+## Commands (Node — scaffold/management only)
+
+| Command | Purpose |
+|---|---|
+| `create:orchestrator [name]` | New orchestrator (manifest + `.md` commands) |
+| `init` | Install/refresh agent commands in an existing orchestrator |
+| `add:repo` | Add a repo to the manifest (id, role, **hints**, context, testCommand) |
+| `update:commands` | Overwrite the agent command templates |
+| `doctor` | Validate manifest, hints, indexes, installed commands |
+| `status` | Show repos, risk signals, and active sessions |
+
+`--lang en|pt-BR` selects the language of the installed `.md` commands.
+
+## The `.md` orchestration layer (the engine)
+
+Installed into `.claude/commands/`:
+
+- **`orchestrate.md`** — classifies complexity, builds the execution DAG, compiles a
+  context contract per node, and spawns ephemeral subagents (Task tool) wave by wave.
+- **`agents/CONTEXT-CONTRACT.md`** — the exact contract shape and the required return format.
+- **`agents/{implementer,reviewer,integrator,tester}.md`** — behavioral archetypes
+  (not domain agents). A concrete worker is compiled as
+  `archetype + objective + repository + context contract + tools`.
+
+## `context-manifest.json`
+
+The single source of project truth (backwards-compatible with context-first-cli, with
+additive fields). See `templates/orchestrator/context-manifest.example.json`.
+
+```jsonc
+{
+  "repositories": [
+    {
+      "id": "service-a",
+      "role": "service",
+      "hints": ["api", "backend"],          // ← how the orchestrator knows a task hits this repo
+      "context": ["../metaspecs/specs/api.md"], // ← what an agent here may read
+      "testCommand": "npm test"
+    }
+  ],
+  "orchestration": {
+    "riskSignals": ["migration", "payment", "security"], // ← trigger adversarial review
+    "indexes": ["../metaspecs/specs/index.md"],
+    "contextPolicy": "select-do-not-dump",
+    "parallelism": { "maxWorkers": 8, "maxPerRepository": 2 }
+  }
+}
+```
+
+## How complexity routing works
+
+`/orchestrate` counts, against the spec text:
+- **repoHits** — repos whose `id`/`hints` appear
+- **risks** — `riskSignals` that appear
+
+→ `simple` (1 repo: implementer + reviewer) · `medium` (impl per repo → integrator →
+tester) · `complex` (medium + adversarial reviewer). A spec may force it via
+`complexity:` frontmatter. Small tasks stay small by design.
+
+## Design rules
+
+- **No catalog of domain agents.** Expertise comes from selected context, not personas.
+- **Select, don't dump.** Each agent's context is bounded and auditable.
+- **Specs are normative.** Agents may read them; they must never modify them.
+
+## License
+
+MIT

package/dist/commands/add-repo.d.ts

@@ -0,0 +1 @@
+export declare function addRepoCommand(): Promise<void>;

package/dist/commands/add-repo.js

@@ -0,0 +1,54 @@
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { loadManifest, saveManifest, exitWithError, } from '../utils/config.js';
+export async function addRepoCommand() {
+    console.log(chalk.bold('\nContext-First Agents — add:repo\n'));
+    const cwd = process.cwd();
+    const manifest = await loadManifest(cwd);
+    if (!manifest)
+        exitWithError('No context-manifest.json here. Run inside an orchestrator.');
+    const a = await inquirer.prompt([
+        { type: 'input', name: 'id', message: 'Repository id (folder name):', validate: (v) => !!v || 'required' },
+        {
+            type: 'list',
+            name: 'role',
+            message: 'Role:',
+            choices: ['application', 'service', 'library', 'metaspecs', 'specs-provider'],
+            default: 'application',
+        },
+        { type: 'input', name: 'url', message: 'Git URL (optional):', default: '' },
+        { type: 'input', name: 'mainBranch', message: 'Main branch:', default: 'main' },
+        {
+            type: 'input',
+            name: 'hints',
+            message: 'Hints (comma-separated keywords that mean this repo is impacted):',
+            default: '',
+        },
+        {
+            type: 'input',
+            name: 'context',
+            message: 'Context files an agent here may read (comma-separated, optional):',
+            default: '',
+        },
+        { type: 'input', name: 'testCommand', message: 'Test command (optional):', default: '' },
+    ]);
+    const split = (s) => s.split(',').map((x) => x.trim()).filter(Boolean);
+    const repo = {
+        id: a.id,
+        role: a.role,
+        mainBranch: a.mainBranch,
+        ...(a.url ? { url: a.url } : {}),
+        ...(a.hints ? { hints: split(a.hints) } : {}),
+        ...(a.context ? { context: split(a.context) } : {}),
+        ...(a.testCommand ? { testCommand: a.testCommand } : {}),
+    };
+    if (manifest.repositories.some((r) => r.id === repo.id)) {
+        exitWithError(`Repository '${repo.id}' already exists in the manifest.`);
+    }
+    manifest.repositories.push(repo);
+    await saveManifest(cwd, manifest);
+    console.log(chalk.green(`\n✓ Added '${repo.id}'. Manifest now has ${manifest.repositories.length} repos.\n`));
+    if (!repo.hints) {
+        console.log(chalk.yellow('Tip: repos without `hints` are harder for the orchestrator to route. Add keywords later.\n'));
+    }
+}

package/dist/commands/create-orchestrator.d.ts

@@ -0,0 +1,8 @@
+interface CreateOpts {
+    lang?: string;
+    project?: string;
+    description?: string;
+    yes?: boolean;
+}
+export declare function createOrchestratorCommand(name: string | undefined, opts: CreateOpts): Promise<void>;
+export {};

package/dist/commands/create-orchestrator.js

@@ -0,0 +1,87 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { templatesDir } from '../utils/paths.js';
+import { installCommands } from '../core/install-commands.js';
+import { ensureDir, pathExists, exitWithError, DEFAULT_ARCHETYPES, DEFAULT_RISK_SIGNALS, } from '../utils/config.js';
+export async function createOrchestratorCommand(name, opts) {
+    console.log(chalk.bold('\nContext-First Agents — create:orchestrator\n'));
+    // Non-interactive when there is no TTY (CI/pipes) or --yes is passed.
+    const interactive = process.stdin.isTTY && !opts.yes;
+    let answers;
+    if (interactive) {
+        answers = await inquirer.prompt([
+            {
+                type: 'input',
+                name: 'name',
+                message: 'Orchestrator directory name:',
+                default: name ?? 'my-orchestrator',
+                when: !name,
+            },
+            { type: 'input', name: 'project', message: 'Project name:', default: name ?? 'my-project' },
+            { type: 'input', name: 'description', message: 'Description:', default: opts.description ?? '' },
+        ]);
+    }
+    else {
+        if (!name)
+            exitWithError('Non-interactive mode requires a name argument (context-agents create:orchestrator <name>).');
+        answers = {
+            name,
+            project: opts.project ?? name,
+            description: opts.description ?? '',
+        };
+    }
+    const dirName = name ?? answers.name;
+    const target = path.resolve(process.cwd(), dirName);
+    if (await pathExists(target))
+        exitWithError(`Directory already exists: ${target}`);
+    await ensureDir(target);
+    await ensureDir(path.join(target, '.sessions'));
+    // Seed a manifest with the orchestration block wired for agent routing.
+    const manifest = {
+        version: '1.0',
+        project: answers.project ?? dirName,
+        description: answers.description ?? '',
+        repositories: [
+            {
+                id: 'metaspecs',
+                role: 'metaspecs',
+                description: 'Normative specifications (source of truth)',
+                mainBranch: 'main',
+                hints: ['spec', 'adr', 'contract', 'documentation'],
+            },
+        ],
+        orchestration: {
+            archetypes: DEFAULT_ARCHETYPES,
+            riskSignals: DEFAULT_RISK_SIGNALS,
+            parallelism: { maxWorkers: 8, maxPerRepository: 2 },
+            contextPolicy: 'select-do-not-dump',
+            maxFilesPerWorker: 20,
+            indexes: ['../metaspecs/specs/index.md'],
+        },
+    };
+    await fs.writeFile(path.join(target, 'context-manifest.json'), JSON.stringify(manifest, null, 2), 'utf-8');
+    // Copy the ai.properties template if present.
+    const aiPropSrc = path.join(templatesDir(), 'orchestrator', 'ai.properties.md');
+    if (await pathExists(aiPropSrc)) {
+        await fs.copyFile(aiPropSrc, path.join(target, 'ai.properties.md'));
+    }
+    // .contextrc.json (local config, gitignored) — compatible with context-first-cli.
+    await fs.writeFile(path.join(target, '.contextrc.json'), JSON.stringify({
+        orchestratorRepo: `file://${target}`,
+        aiProvider: 'claude',
+        commandsDir: '.claude/commands',
+    }, null, 2), 'utf-8');
+    const gitignoreSrc = path.join(templatesDir(), 'orchestrator', 'gitignore');
+    if (await pathExists(gitignoreSrc)) {
+        await fs.copyFile(gitignoreSrc, path.join(target, '.gitignore'));
+    }
+    console.log(chalk.bold('\nInstalling agent command templates:'));
+    await installCommands(target, { lang: opts.lang, force: true });
+    console.log(chalk.green(`\n✓ Orchestrator created at ${target}`));
+    console.log(chalk.gray('\nNext steps:'));
+    console.log(chalk.gray(`  cd ${dirName}`));
+    console.log(chalk.gray('  context-agents add:repo        # register your repositories'));
+    console.log(chalk.gray('  # then in your AI tool:  /orchestrate <ISSUE-ID>\n'));
+}

package/dist/commands/doctor.d.ts

@@ -0,0 +1 @@
+export declare function doctorCommand(): Promise<void>;

package/dist/commands/doctor.js

@@ -0,0 +1,66 @@
+import path from 'node:path';
+import chalk from 'chalk';
+import { loadManifest, pathExists } from '../utils/config.js';
+import { repoLocalPath } from '../utils/paths.js';
+export async function doctorCommand() {
+    console.log(chalk.bold('\nContext-First Agents — doctor\n'));
+    const cwd = process.cwd();
+    let problems = 0;
+    let warnings = 0;
+    const manifest = await loadManifest(cwd);
+    if (!manifest) {
+        console.log(chalk.red('✗ context-manifest.json not found or invalid.'));
+        console.log(chalk.gray('  Run inside an orchestrator, or `create:orchestrator`.\n'));
+        process.exitCode = 1;
+        return;
+    }
+    console.log(chalk.green(`✓ Manifest OK — ${manifest.project} (${manifest.repositories.length} repos)`));
+    // Commands installed?
+    const commandsDir = path.join(cwd, '.claude', 'commands');
+    if (await pathExists(path.join(commandsDir, 'orchestrate.md'))) {
+        console.log(chalk.green('✓ /orchestrate command installed'));
+    }
+    else {
+        console.log(chalk.red('✗ orchestrate.md missing — run `context-agents init`'));
+        problems++;
+    }
+    // Orchestration block
+    const orch = manifest.orchestration;
+    if (!orch?.riskSignals?.length) {
+        console.log(chalk.yellow('! No orchestration.riskSignals — risky tasks won\'t trigger adversarial review'));
+        warnings++;
+    }
+    else {
+        console.log(chalk.green(`✓ ${orch.riskSignals.length} risk signals configured`));
+    }
+    if (!orch?.indexes?.length) {
+        console.log(chalk.yellow('! No orchestration.indexes — agents have no project-wide context router'));
+        warnings++;
+    }
+    // Per-repo checks
+    console.log(chalk.bold('\nRepositories:'));
+    for (const repo of manifest.repositories) {
+        const local = repoLocalPath(cwd, repo);
+        const exists = await pathExists(local);
+        const status = exists ? chalk.green('found') : chalk.yellow('missing locally');
+        const hints = repo.hints?.length ? chalk.gray(`hints: ${repo.hints.join(', ')}`) : chalk.yellow('no hints');
+        console.log(`  ${exists ? '✓' : '!'} ${repo.id} [${repo.role}] — ${status}; ${hints}`);
+        if (!exists)
+            warnings++;
+        if (!repo.hints?.length && repo.role !== 'metaspecs')
+            warnings++;
+        if (repo.role === 'application' && !repo.testCommand) {
+            console.log(chalk.gray(`      (no testCommand — tester agent will fall back to project defaults)`));
+        }
+    }
+    console.log('');
+    if (problems)
+        console.log(chalk.red(`${problems} problem(s)`));
+    if (warnings)
+        console.log(chalk.yellow(`${warnings} warning(s)`));
+    if (!problems && !warnings)
+        console.log(chalk.green('All good. Ready to /orchestrate.'));
+    console.log('');
+    if (problems)
+        process.exitCode = 1;
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,6 @@
+interface InitOpts {
+    lang?: string;
+    force?: boolean;
+}
+export declare function initCommand(opts: InitOpts): Promise<void>;
+export {};

package/dist/commands/init.js

@@ -0,0 +1,22 @@
+import path from 'node:path';
+import chalk from 'chalk';
+import { installCommands } from '../core/install-commands.js';
+import { loadManifest, pathExists, exitWithError } from '../utils/config.js';
+export async function initCommand(opts) {
+    const cwd = process.cwd();
+    console.log(chalk.bold('\nContext-First Agents — init\n'));
+    const hasManifest = await pathExists(path.join(cwd, 'context-manifest.json'));
+    if (!hasManifest) {
+        console.log(chalk.yellow('No context-manifest.json here. Run this inside an orchestrator, or use `create:orchestrator` first.'));
+    }
+    else {
+        const manifest = await loadManifest(cwd);
+        if (!manifest)
+            exitWithError('context-manifest.json is present but could not be parsed.');
+        console.log(chalk.gray(`Project: ${manifest.project} (${manifest.repositories.length} repos)`));
+    }
+    console.log(chalk.bold('\nInstalling agent command templates:'));
+    const written = await installCommands(cwd, { lang: opts.lang, force: opts.force });
+    console.log(chalk.green(`\n✓ Installed ${written.length} command file(s).`));
+    console.log(chalk.gray('\nNext: open your AI tool and run  /orchestrate <ISSUE-ID>\n'));
+}

package/dist/commands/status.d.ts

@@ -0,0 +1 @@
+export declare function statusCommand(): Promise<void>;

package/dist/commands/status.js

@@ -0,0 +1,31 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import chalk from 'chalk';
+import { loadManifest, pathExists } from '../utils/config.js';
+export async function statusCommand() {
+    console.log(chalk.bold('\nContext-First Agents — status\n'));
+    const cwd = process.cwd();
+    const manifest = await loadManifest(cwd);
+    if (!manifest) {
+        console.log(chalk.yellow('No context-manifest.json here.\n'));
+        return;
+    }
+    console.log(chalk.bold(`${manifest.project}`) + chalk.gray(` — ${manifest.description ?? ''}`));
+    console.log(chalk.gray(`Repositories (${manifest.repositories.length}):`));
+    for (const r of manifest.repositories) {
+        console.log(`  • ${r.id} [${r.role}]${r.hints?.length ? chalk.gray(` — ${r.hints.join(', ')}`) : ''}`);
+    }
+    const risk = manifest.orchestration?.riskSignals ?? [];
+    if (risk.length)
+        console.log(chalk.gray(`\nRisk signals: ${risk.join(', ')}`));
+    const sessionsDir = path.join(cwd, '.sessions');
+    if (await pathExists(sessionsDir)) {
+        const entries = (await fs.readdir(sessionsDir, { withFileTypes: true }))
+            .filter((e) => e.isDirectory() && !e.name.startsWith('_') && !e.name.startsWith('.'))
+            .map((e) => e.name);
+        console.log(chalk.bold(`\nActive sessions (${entries.length}):`));
+        for (const s of entries.sort())
+            console.log(`  • ${s}`);
+    }
+    console.log('');
+}

package/dist/commands/update-commands.d.ts

@@ -0,0 +1,5 @@
+interface UpdateOpts {
+    lang?: string;
+}
+export declare function updateCommandsCommand(opts: UpdateOpts): Promise<void>;
+export {};

package/dist/commands/update-commands.js

@@ -0,0 +1,7 @@
+import chalk from 'chalk';
+import { installCommands } from '../core/install-commands.js';
+export async function updateCommandsCommand(opts) {
+    console.log(chalk.bold('\nContext-First Agents — update:commands\n'));
+    const written = await installCommands(process.cwd(), { lang: opts.lang, force: true });
+    console.log(chalk.green(`\n✓ Updated ${written.length} command file(s).\n`));
+}

package/dist/core/install-commands.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Copy the agent command templates (.md) into an orchestrator's commands dir.
+ * These .md files ARE the orchestration engine — Node only places them.
+ */
+export declare function installCommands(orchestratorDir: string, opts?: {
+    lang?: string;
+    force?: boolean;
+    commandsDir?: string;
+}): Promise<string[]>;

package/dist/core/install-commands.js

@@ -0,0 +1,46 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import chalk from 'chalk';
+import { templatesDir } from '../utils/paths.js';
+import { ensureDir, pathExists } from '../utils/config.js';
+const SUPPORTED_LANGS = ['en', 'pt-BR'];
+/**
+ * Copy the agent command templates (.md) into an orchestrator's commands dir.
+ * These .md files ARE the orchestration engine — Node only places them.
+ */
+export async function installCommands(orchestratorDir, opts = {}) {
+    const lang = SUPPORTED_LANGS.includes(opts.lang ?? '') ? opts.lang : 'en';
+    const commandsDir = opts.commandsDir ?? '.claude/commands';
+    const srcRoot = path.join(templatesDir(), 'commands', lang);
+    const destRoot = path.join(orchestratorDir, commandsDir);
+    if (!(await pathExists(srcRoot))) {
+        // Fall back to en if a lang folder is missing.
+        return installCommands(orchestratorDir, { ...opts, lang: 'en' });
+    }
+    await ensureDir(destRoot);
+    const written = [];
+    await copyTree(srcRoot, destRoot, Boolean(opts.force), written);
+    written.sort();
+    for (const f of written)
+        console.log(chalk.green(`  ✓ ${path.relative(orchestratorDir, f)}`));
+    return written;
+}
+async function copyTree(src, dest, force, written) {
+    const entries = await fs.readdir(src, { withFileTypes: true });
+    for (const e of entries) {
+        const s = path.join(src, e.name);
+        const d = path.join(dest, e.name);
+        if (e.isDirectory()) {
+            await ensureDir(d);
+            await copyTree(s, d, force, written);
+        }
+        else {
+            if (!force && (await pathExists(d))) {
+                console.log(chalk.gray(`  · skip (exists) ${e.name}`));
+                continue;
+            }
+            await fs.copyFile(s, d);
+            written.push(d);
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { initCommand } from './commands/init.js';
+import { createOrchestratorCommand } from './commands/create-orchestrator.js';
+import { addRepoCommand } from './commands/add-repo.js';
+import { updateCommandsCommand } from './commands/update-commands.js';
+import { doctorCommand } from './commands/doctor.js';
+import { statusCommand } from './commands/status.js';
+const program = new Command();
+program
+    .name('context-agents')
+    .description('Context-First Agents CLI — scaffold orchestrators and run dynamic, ephemeral AI agents from specs.\n' +
+    'All agent orchestration lives in .md command templates; this Node CLI only scaffolds and manages.')
+    .version('0.1.0');
+program
+    .command('init')
+    .description('Add Context-First Agents command templates to an existing orchestrator')
+    .option('-l, --lang <lang>', 'Command language (en, pt-BR)', 'en')
+    .option('-f, --force', 'Overwrite existing command files')
+    .action(initCommand);
+program
+    .command('create:orchestrator [name]')
+    .description('Create a new orchestrator directory (context-manifest.json + .md commands)')
+    .option('-l, --lang <lang>', 'Command language (en, pt-BR)', 'en')
+    .option('-p, --project <name>', 'Project name (non-interactive)')
+    .option('-d, --description <text>', 'Project description (non-interactive)')
+    .option('-y, --yes', 'Skip prompts and use defaults/flags')
+    .action(createOrchestratorCommand);
+program
+    .command('add:repo')
+    .description('Add a repository to context-manifest.json (with hints/context/testCommand)')
+    .action(addRepoCommand);
+program
+    .command('update:commands')
+    .description('Update the agent command templates in an existing orchestrator')
+    .option('-l, --lang <lang>', 'Command language (en, pt-BR)', 'en')
+    .action(updateCommandsCommand);
+program
+    .command('doctor')
+    .description('Validate orchestrator config for agent orchestration (manifest, hints, indexes)')
+    .action(doctorCommand);
+program
+    .command('status')
+    .description('Show orchestrator repos, risk signals, and active sessions')
+    .action(statusCommand);
+program.parseAsync(process.argv);

package/dist/templates/commands/en/agents/CONTEXT-CONTRACT.md

@@ -0,0 +1,63 @@
+# Context Contract (shape)
+
+Every ephemeral agent is spawned with a contract. This is the exact object the
+Orchestrator compiles per node and pastes into the subagent's prompt. It is what makes
+each agent's context **small, bounded, and auditable** — the core of the architecture.
+
+```json
+{
+  "agentId": "agent-w001",
+  "archetype": "implementer",
+  "objective": "<the specific, bounded goal for this worker>",
+  "repository": "<repo-id or null for session-level workers>",
+  "read": [
+    { "type": "index", "path": "../metaspecs/specs/index.md", "reason": "project context router" },
+    { "type": "hint",  "path": "../metaspecs/specs/technical/API_SPECIFICATION.md", "reason": "repo context hint" }
+  ],
+  "mayDiscover": [
+    "references reachable from the indexes above",
+    "files in this repository required to complete the objective"
+  ],
+  "mustNotAssume": [
+    "unstated business rules",
+    "unindexed external contracts",
+    "requirements not present in the approved spec"
+  ],
+  "writeBoundary": ["assigned worktree for <repo-id>"],
+  "limits": { "policy": "select-do-not-dump", "maxFiles": 20 },
+  "return": ["summary", "changes", "evidence", "tests", "unresolved", "confidence"]
+}
+```
+
+## Rules the Orchestrator must enforce when compiling a contract
+
+- `read` includes ALL `orchestration.indexes` plus the repo's `context[]` — but only
+  paths that actually exist on disk. Drop the rest silently.
+- Session-level workers (integrator, tester, reviewer) have `repository: null` and
+  `writeBoundary: ["session artifacts only"]`.
+- Never expand `read` to "the whole repo". Discovery is allowed (`mayDiscover`) but
+  starts from the indexes, not from a blind directory dump.
+- The contract is the ONLY project context a subagent receives beyond its objective.
+  Do not paste the full conversation into subagents.
+
+## The return shape every agent must produce
+
+```markdown
+### summary
+<one paragraph: what was done>
+
+### changes
+<files created/modified, per repo>
+
+### evidence
+<commands run, outputs, links>
+
+### tests
+<tests added/run and their result>
+
+### unresolved
+<questions, spec conflicts, Jidoka stops — or "none">
+
+### confidence
+<low | medium | high> + one line why
+```

package/dist/templates/commands/en/agents/implementer.md

@@ -0,0 +1,27 @@
+# Archetype: implementer
+
+You are an **ephemeral implementer** for exactly one repository. You will be discarded
+when you return. Domain expertise comes from your context contract, not from a persona.
+
+## You receive
+- `objective`: the bounded goal.
+- `repository`: the repo id and its worktree path.
+- A **context contract** (read scope, writeBoundary, mustNotAssume, limits, return).
+
+## Do
+1. Read ONLY what your contract's `read` list allows; discover further ONLY from those
+   indexes/repo files (`mayDiscover`). Honor `limits.maxFiles`.
+2. Implement the objective inside your `writeBoundary` (your repo's worktree). Follow the
+   patterns you find in the repo and the normative specs. Do not introduce stack not
+   documented in the specs without flagging it in `unresolved`.
+3. Add/adjust tests per the repo's conventions.
+4. Commit atomically inside the worktree (`feat|fix|refactor|test|docs|chore: … Refs: <ISSUE-ID>`).
+
+## Never
+- Read or modify other repositories.
+- Modify normative specs.
+- Assume anything in `mustNotAssume` — if you need it, stop and put it in `unresolved`.
+
+## Return (exactly this shape)
+summary / changes / evidence / tests / unresolved / confidence
+(see CONTEXT-CONTRACT.md)