@agent-loom/loom 1.0.0

package/README.md

@@ -0,0 +1,144 @@
+# Loom
+
+**Template engine for coding agent workspaces.** Share and apply workspace configurations — instructions, skills, prompts, MCP servers, agents, and repos — across GitHub Copilot, Claude Code, and Cursor.
+
+Loom lets teams maintain reusable workspace templates in a GitHub repository and apply them with a single chat command. No database, no server — just Git and GitHub Pages.
+
+## Demo
+
+https://github.com/user-attachments/assets/8c937a54-cd23-45e6-9eb8-f7e2c86ec3f6
+
+## Why Loom?
+
+Coding agents (Copilot, Claude Code, Cursor) rely on workspace-level configuration: instruction files, skill definitions, MCP servers, prompt files, and repository references. Teams often need to share and reuse these configurations across projects:
+
+- **Onboarding** — new team members get a ready-to-go agent workspace in seconds
+- **Consistency** — shared instructions and skills stay in sync across projects
+- **Multi-agent support** — one template renders to Copilot, Claude Code, or Cursor format
+- **Personal setups** — host your own templates on a personal GitHub repo
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install -g @agent-loom/loom
+```
+
+### 2. Set up a registry
+
+```bash
+loom registry add my-templates https://github.com/<your-org>/<your-templates>
+```
+
+### 3. Search and apply templates
+
+In your coding agent's chat (Copilot, Claude Code, etc.):
+
+```
+Search for available Loom templates
+```
+
+```
+Apply the functions-dev template to this workspace
+```
+
+The agent handles the whole workflow — searching, selecting, and applying the template to your workspace.
+
+## Available Skills
+
+Loom ships with 5 skills that teach your coding agent how to use the system:
+
+| Skill | Purpose |
+|-------|---------|
+| **loom-setup** | Install CLI, configure registries, verify setup |
+| **loom-search** | Search and discover templates across registries |
+| **loom-apply** | Apply templates to scaffold workspaces |
+| **loom-scaffold** | Create new templates from existing projects |
+| **loom-workspaces** | Manage workspace history and navigate past projects |
+
+All skills are bundled with the [Craft catalog](https://www.npmjs.com/package/@agent-loom/craft). Install them with `npx @agent-loom/craft add <skill-name>`.
+
+## How It Works
+
+```
+Template Registry (GitHub repo)
+  ├── index.yaml              ← auto-generated template index
+  ├── shared/                 ← reusable instructions, MCP, repos, prompts
+  └── templates/
+      └── my-template/
+          └── manifest.yaml   ← declarative workspace definition
+              ↓
+          loom apply
+              ↓
+      ┌──── Target: Copilot ──────────────────┐
+      │ .github/copilot-instructions.md        │
+      │ .github/instructions/*.instructions.md │
+      │ .github/agents/*.agent.md              │
+      │ .github/skills/*/SKILL.md              │
+      │ .github/prompts/*.prompt.md            │
+      │ .vscode/mcp.json                       │
+      └────────────────────────────────────────┘
+      ┌──── Target: Claude Code ──────────────┐
+      │ CLAUDE.md                              │
+      │ .claude/agents/*.md                    │
+      │ .claude/skills/*/SKILL.md              │
+      │ .claude/settings.json                  │
+      │ .mcp.json                              │
+      └────────────────────────────────────────┘
+```
+
+Templates are declarative `manifest.yaml` files. Shared resources (instructions, MCP servers, repos, prerequisites) live in `shared/` and are referenced via `$ref`. Loom resolves all references, fetches registry skills, and renders target-specific files.
+
+## Template Registries
+
+A template registry is a GitHub repository with a specific layout:
+
+```
+my-registry/
+  ├── index.yaml
+  ├── shared/
+  │   ├── instructions/
+  │   ├── mcp/
+  │   ├── repos/
+  │   ├── prerequisites/
+  │   └── prompts/
+  └── templates/
+      ├── template-a/
+      │   └── manifest.yaml
+      └── template-b/
+          └── manifest.yaml
+```
+
+Create a GitHub repository with a template registry layout. See the [documentation](docs/getting-started.md) for a working example with CI/CD and a GitHub Pages catalog.
+
+## Catalog UI
+
+Registries can publish a browsable catalog site to GitHub Pages using `@agent-loom/loom-ui`. The catalog is a static Next.js export that displays all templates with their full manifest details, built and deployed automatically via CI/CD.
+
+## Documentation
+
+- [Getting Started](docs/getting-started.md) — Chat-based usage guide
+- [CLI Reference](docs/cli-reference.md) — Full command reference
+- [Architecture](docs/architecture.md) — System design and internals
+- [Skills Specification](docs/skills-spec.md) — How skills are defined and resolved
+
+## Packages
+
+| Package | Description |
+|---------|-------------|
+| [`@agent-loom/loom`](https://www.npmjs.com/package/@agent-loom/loom) | CLI + core library |
+| [`@agent-loom/loom-ui`](https://www.npmjs.com/package/@agent-loom/loom-ui) | Static catalog site generator (Next.js) |
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+node dist/cli.js --help
+```
+
+## License
+
+ISC

package/dist/apply.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Apply — resolves a template from a registry and renders it to a target workspace.
+ */
+import { type SkillFetcher } from './skill-fetcher.js';
+import { type CloneRepoResult } from './repo-clone.js';
+import type { TargetType } from './types.js';
+export interface ApplyOptions {
+    templateDir: string;
+    registryRoot: string;
+    outputDir: string;
+    target: TargetType;
+    /** Optional fetcher to resolve registry skills to local content */
+    skillFetcher?: SkillFetcher;
+    /** Clone mode for manifest repos: 'auto' | 'all' | 'none' | undefined (no clone) */
+    cloneRepos?: 'auto' | 'all' | 'none';
+    /** Clone strategy override: 'partial' applies blobless clone to all repos without explicit cloneStrategy */
+    cloneMode?: 'full' | 'partial';
+    /** Inject exec function for testing (repo cloning) */
+    execFn?: (cmd: string) => void;
+    /** Inject prompt function for testing (large repo decisions) */
+    promptFn?: (message: string, choices: string[]) => Promise<string>;
+    /** Inject link function for creating directory junctions/symlinks */
+    linkFn?: (target: string, linkPath: string) => Promise<void>;
+    /** Select specific agents (comma-separated IDs). If undefined, all agents used. */
+    agents?: string[];
+}
+export interface ApplyResult {
+    target: TargetType;
+    template: string;
+    filesGenerated: boolean;
+    /** Registry skills that were NOT fetched (returned only when no skillFetcher is provided) */
+    registrySkills: Array<{
+        registry: string;
+        ref: string;
+    }>;
+    /** Skills that were fetched and placed locally */
+    localizedSkills: Array<{
+        name: string;
+        registry: string;
+        ref: string;
+    }>;
+    /** Repo clone results (only present when cloneRepos is set) */
+    repoCloneResult?: CloneRepoResult;
+}
+/**
+ * Apply a template to a workspace directory.
+ *
+ * Steps:
+ * 1. Parse manifest.yaml from templateDir
+ * 2. Resolve all $ref / file references
+ * 3. Fetch registry skills if a skillFetcher is provided
+ * 4. Render output files using the appropriate renderer
+ * 5. Return list of registry skills that need external install (if not fetched)
+ */
+export declare function applyTemplate(options: ApplyOptions): Promise<ApplyResult>;
+//# sourceMappingURL=apply.d.ts.map

package/dist/apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../src/apply.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,EAAyB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAA6C,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClG,OAAO,KAAK,EAAE,UAAU,EAAmC,MAAM,YAAY,CAAC;AAE9E,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,UAAU,CAAC;IACnB,mEAAmE;IACnE,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,oFAAoF;IACpF,UAAU,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;IACrC,4GAA4G;IAC5G,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,sDAAsD;IACtD,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,gEAAgE;IAChE,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACnE,qEAAqE;IACrE,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D,mFAAmF;IACnF,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,OAAO,CAAC;IACxB,6FAA6F;IAC7F,cAAc,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACzD,kDAAkD;IAClD,eAAe,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxE,+DAA+D;IAC/D,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AAED;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CA2F/E"}

package/dist/apply.js

@@ -0,0 +1,97 @@
+/**
+ * Apply — resolves a template from a registry and renders it to a target workspace.
+ */
+import { join } from 'node:path';
+import { parseManifest, resolveManifest, parseAgentManifest, discoverNestedAgents, mergeTeamAndAgentManifests } from './manifest.js';
+import { renderCopilot } from './renderers/copilot.js';
+import { renderClaude } from './renderers/claude.js';
+import { resolveRegistrySkills } from './skill-fetcher.js';
+import { cloneManifestRepos } from './repo-clone.js';
+/**
+ * Apply a template to a workspace directory.
+ *
+ * Steps:
+ * 1. Parse manifest.yaml from templateDir
+ * 2. Resolve all $ref / file references
+ * 3. Fetch registry skills if a skillFetcher is provided
+ * 4. Render output files using the appropriate renderer
+ * 5. Return list of registry skills that need external install (if not fetched)
+ */
+export async function applyTemplate(options) {
+    const { templateDir, registryRoot, outputDir, target, skillFetcher, cloneRepos, cloneMode, execFn, promptFn, linkFn, agents: selectedAgents } = options;
+    const manifestPath = join(templateDir, 'manifest.yaml');
+    const teamManifest = await parseManifest(manifestPath);
+    // Detect nested agents
+    const nestedAgentIds = await discoverNestedAgents(templateDir);
+    let manifest = teamManifest;
+    if (nestedAgentIds.length > 0) {
+        // Nested template — determine which agents to include
+        const agentIds = selectedAgents && selectedAgents.length > 0
+            ? selectedAgents.filter((id) => nestedAgentIds.includes(id))
+            : nestedAgentIds; // All agents if none specified
+        // Parse agent manifests
+        const agentManifests = [];
+        for (const agentId of agentIds) {
+            const agentManifestPath = join(templateDir, 'agents', agentId, 'manifest.yaml');
+            const am = await parseAgentManifest(agentManifestPath);
+            agentManifests.push(am);
+        }
+        // Merge team + agent manifests
+        manifest = mergeTeamAndAgentManifests(teamManifest, agentManifests, agentIds);
+    }
+    const resolved = await resolveManifest(manifest, templateDir, registryRoot);
+    // Resolve registry skills to local if fetcher is provided
+    const resolvedSkills = await resolveRegistrySkills(resolved.skills, skillFetcher);
+    const manifestWithLocalSkills = {
+        ...resolved,
+        skills: resolvedSkills,
+    };
+    // Render
+    switch (target) {
+        case 'copilot':
+            await renderCopilot(manifestWithLocalSkills, outputDir);
+            break;
+        case 'claude':
+            await renderClaude(manifestWithLocalSkills, outputDir);
+            break;
+        case 'cursor':
+            // Cursor renderer not yet implemented — fall back to copilot
+            await renderCopilot(manifestWithLocalSkills, outputDir);
+            break;
+        default:
+            throw new Error(`Unknown target: ${target}`);
+    }
+    // Clone manifest repos if requested
+    let repoCloneResult;
+    if (cloneRepos && resolved.repos.length > 0) {
+        // Apply --clone-mode partial: override repos without explicit cloneStrategy
+        const repos = cloneMode === 'partial'
+            ? resolved.repos.map((r) => (!r.cloneStrategy && !r.sparse) ? { ...r, cloneStrategy: 'partial' } : r)
+            : resolved.repos;
+        repoCloneResult = await cloneManifestRepos({
+            repos,
+            workspaceDir: outputDir === '.' ? process.cwd() : outputDir,
+            mode: cloneRepos,
+            execFn,
+            promptFn,
+            linkFn,
+        });
+    }
+    // Collect registry skills that were NOT fetched (still type='registry')
+    const registrySkills = resolvedSkills
+        .filter((s) => s.type === 'registry' && s.registry && s.ref)
+        .map((s) => ({ registry: s.registry, ref: s.ref }));
+    // Collect skills that were fetched and localized
+    const localizedSkills = resolvedSkills
+        .filter((s) => s.type === 'local' && s.originalRegistry && s.originalRef)
+        .map((s) => ({ name: s.name, registry: s.originalRegistry, ref: s.originalRef }));
+    return {
+        target,
+        template: resolved.template.id,
+        filesGenerated: true,
+        registrySkills,
+        localizedSkills,
+        repoCloneResult,
+    };
+}
+//# sourceMappingURL=apply.js.map

package/dist/apply.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.js","sourceRoot":"","sources":["../src/apply.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Loom CLI — Entry Point
+ *
+ * Template engine for coding agent workspaces.
+ * Supports GitHub Copilot, Claude Code, and Cursor targets.
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;GAKG"}