@spencerbeggs/claude-coordinator-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+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,101 @@
+# @spencerbeggs/claude-coordinator-core
+
+Core schemas and TypeScript types for the Claude Coordinator system, providing
+Zod-based validation and type-safe communication primitives.
+
+## Features
+
+- **Type-safe schemas** - Zod schemas with full TypeScript inference
+- **Runtime validation** - Validate all data at runtime with helpful error
+  messages
+- **Zero runtime deps** - Only Zod required at runtime
+- **Schema-first design** - Define once, use everywhere
+
+## Installation
+
+```bash
+npm install @spencerbeggs/claude-coordinator-core
+```
+
+## Quick Start
+
+```typescript
+import {
+  AgentSchema,
+  JoinInputSchema,
+  QuestionSchema,
+  type Agent,
+  type JoinInput,
+} from "@spencerbeggs/claude-coordinator-core";
+
+// Validate input data
+const input = JoinInputSchema.parse({
+  name: "my-agent",
+  role: "source",
+  repoPath: "/path/to/repo",
+});
+
+// Type inference works automatically
+const agent: Agent = {
+  id: "550e8400-e29b-41d4-a716-446655440000",
+  role: "source",
+  name: "my-agent",
+  repoPath: "/path/to/repo",
+  connectedAt: new Date(),
+};
+
+// Validate the agent
+AgentSchema.parse(agent);
+```
+
+## API Overview
+
+### Schemas
+
+| Schema | Description |
+| ------ | ----------- |
+| `AgentSchema` | Connected agent identity |
+| `JoinInputSchema` | Input for joining a session |
+| `JoinResultSchema` | Result from joining (agent + sessionId) |
+| `ContextEntrySchema` | Shared context key-value entry |
+| `ShareContextInputSchema` | Input for sharing context |
+| `QuestionSchema` | Question with optional answer |
+| `AskInputSchema` | Input for asking a question |
+| `AnswerInputSchema` | Input for answering a question |
+| `DecisionSchema` | Logged decision with rationale |
+| `LogDecisionInputSchema` | Input for logging a decision |
+
+### Types
+
+All types are inferred from schemas:
+
+```typescript
+import type {
+  Agent,
+  JoinInput,
+  JoinResult,
+  ContextEntry,
+  Question,
+  Decision,
+} from "@spencerbeggs/claude-coordinator-core";
+```
+
+### Constants
+
+```typescript
+import {
+  DEFAULT_PORT,   // 3030
+  DEFAULT_HOST,   // "localhost"
+  DEFAULT_URL,    // "ws://localhost:3030"
+} from "@spencerbeggs/claude-coordinator-core";
+```
+
+## Documentation
+
+- [Architecture Design Doc](../../.claude/design/claude-coordinator-core/architecture.md)
+- [Server Package](../claude-coordinator-server/README.md)
+- [MCP Bridge Package](../claude-coordinator-mcp/README.md)
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,242 @@
+/**
+ * \@spencerbeggs/claude-coordinator-core
+ *
+ * Core schemas and types for the Claude Coordinator system.
+ * Provides Zod schemas for validation and TypeScript types for
+ * communication between Claude Code instances.
+ *
+ * @packageDocumentation
+ */
+
+import { z } from 'zod';
+
+export declare type Agent = z.infer<typeof AgentSchema>;
+
+export declare type AgentRole = z.infer<typeof AgentRoleSchema>;
+
+/**
+ * Role of an agent in the coordination session
+ */
+export declare const AgentRoleSchema: z.ZodEnum<{
+    source: "source";
+    target: "target";
+}>;
+
+/**
+ * Schema for a connected agent in the coordination session
+ */
+export declare const AgentSchema: z.ZodObject<{
+    id: z.ZodString;
+    role: z.ZodEnum<{
+        source: "source";
+        target: "target";
+    }>;
+    name: z.ZodString;
+    repoPath: z.ZodString;
+    connectedAt: z.ZodCoercedDate<unknown>;
+}, z.core.$strip>;
+
+export declare type AnswerEvent = z.infer<typeof AnswerEventSchema>;
+
+/**
+ * Event emitted when a question is answered
+ */
+export declare const AnswerEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"answer">;
+    question: z.ZodObject<{
+        id: z.ZodString;
+        question: z.ZodString;
+        from: z.ZodString;
+        to: z.ZodOptional<z.ZodString>;
+        answer: z.ZodOptional<z.ZodString>;
+        answeredBy: z.ZodOptional<z.ZodString>;
+        status: z.ZodEnum<{
+            answered: "answered";
+            pending: "pending";
+        }>;
+        createdAt: z.ZodCoercedDate<unknown>;
+        answeredAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+
+export declare type AnswerInput = z.infer<typeof AnswerInputSchema>;
+
+/**
+ * Input schema for answering a question
+ */
+export declare const AnswerInputSchema: z.ZodObject<{
+    questionId: z.ZodString;
+    answer: z.ZodString;
+}, z.core.$strip>;
+
+export declare type AskInput = z.infer<typeof AskInputSchema>;
+
+/**
+ * Input schema for asking a question
+ */
+export declare const AskInputSchema: z.ZodObject<{
+    question: z.ZodString;
+    to: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+
+export declare type ContextEntry = z.infer<typeof ContextEntrySchema>;
+
+/**
+ * Schema for a shared context entry
+ */
+export declare const ContextEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    key: z.ZodString;
+    value: z.ZodString;
+    tags: z.ZodArray<z.ZodString>;
+    createdBy: z.ZodString;
+    createdAt: z.ZodCoercedDate<unknown>;
+    updatedAt: z.ZodCoercedDate<unknown>;
+}, z.core.$strip>;
+
+export declare type Decision = z.infer<typeof DecisionSchema>;
+
+/**
+ * Schema for a logged decision
+ */
+export declare const DecisionSchema: z.ZodObject<{
+    id: z.ZodString;
+    decision: z.ZodString;
+    rationale: z.ZodOptional<z.ZodString>;
+    by: z.ZodString;
+    createdAt: z.ZodCoercedDate<unknown>;
+}, z.core.$strip>;
+
+export declare const DEFAULT_HOST: string;
+
+export declare const DEFAULT_PORT: number;
+
+export declare const DEFAULT_URL: string;
+
+export declare type GetContextInput = z.infer<typeof GetContextInputSchema>;
+
+/**
+ * Input schema for retrieving a context entry by key
+ */
+export declare const GetContextInputSchema: z.ZodObject<{
+    key: z.ZodString;
+}, z.core.$strip>;
+
+export declare type JoinInput = z.infer<typeof JoinInputSchema>;
+
+/**
+ * Input schema for joining a coordination session
+ */
+export declare const JoinInputSchema: z.ZodObject<{
+    name: z.ZodString;
+    role: z.ZodEnum<{
+        source: "source";
+        target: "target";
+    }>;
+    repoPath: z.ZodString;
+}, z.core.$strip>;
+
+export declare type JoinResult = z.infer<typeof JoinResultSchema>;
+
+/**
+ * Result of joining a coordination session
+ */
+export declare const JoinResultSchema: z.ZodObject<{
+    agent: z.ZodObject<{
+        id: z.ZodString;
+        role: z.ZodEnum<{
+            source: "source";
+            target: "target";
+        }>;
+        name: z.ZodString;
+        repoPath: z.ZodString;
+        connectedAt: z.ZodCoercedDate<unknown>;
+    }, z.core.$strip>;
+    sessionId: z.ZodString;
+}, z.core.$strip>;
+
+export declare type ListContextInput = z.infer<typeof ListContextInputSchema>;
+
+/**
+ * Input schema for listing context entries with optional filters
+ */
+export declare const ListContextInputSchema: z.ZodObject<{
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    createdBy: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+
+export declare type LogDecisionInput = z.infer<typeof LogDecisionInputSchema>;
+
+/**
+ * Input schema for logging a decision
+ */
+export declare const LogDecisionInputSchema: z.ZodObject<{
+    decision: z.ZodString;
+    rationale: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+
+export declare type Question = z.infer<typeof QuestionSchema>;
+
+export declare type QuestionEvent = z.infer<typeof QuestionEventSchema>;
+
+/**
+ * Event emitted when a question is asked
+ */
+export declare const QuestionEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"question">;
+    question: z.ZodObject<{
+        id: z.ZodString;
+        question: z.ZodString;
+        from: z.ZodString;
+        to: z.ZodOptional<z.ZodString>;
+        answer: z.ZodOptional<z.ZodString>;
+        answeredBy: z.ZodOptional<z.ZodString>;
+        status: z.ZodEnum<{
+            answered: "answered";
+            pending: "pending";
+        }>;
+        createdAt: z.ZodCoercedDate<unknown>;
+        answeredAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+
+/**
+ * Schema for a question between agents
+ */
+export declare const QuestionSchema: z.ZodObject<{
+    id: z.ZodString;
+    question: z.ZodString;
+    from: z.ZodString;
+    to: z.ZodOptional<z.ZodString>;
+    answer: z.ZodOptional<z.ZodString>;
+    answeredBy: z.ZodOptional<z.ZodString>;
+    status: z.ZodEnum<{
+        answered: "answered";
+        pending: "pending";
+    }>;
+    createdAt: z.ZodCoercedDate<unknown>;
+    answeredAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+}, z.core.$strip>;
+
+export declare type QuestionStatus = z.infer<typeof QuestionStatusSchema>;
+
+/**
+ * Status of a question
+ */
+export declare const QuestionStatusSchema: z.ZodEnum<{
+    answered: "answered";
+    pending: "pending";
+}>;
+
+export declare type ShareContextInput = z.infer<typeof ShareContextInputSchema>;
+
+/**
+ * Input schema for sharing a context entry
+ */
+export declare const ShareContextInputSchema: z.ZodObject<{
+    key: z.ZodString;
+    value: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+
+export { }

package/index.js

@@ -0,0 +1,88 @@
+import { z } from "zod";
+const AgentRoleSchema = z["enum"]([
+    "source",
+    "target"
+]).describe("The role of the agent: 'source' provides knowledge, 'target' receives knowledge");
+const AgentSchema = z.object({
+    id: z.string().uuid().describe("Unique identifier for the agent"),
+    role: AgentRoleSchema,
+    name: z.string().min(1).describe("Human-readable name for the agent"),
+    repoPath: z.string().min(1).describe("Path to the repository this agent is working in"),
+    connectedAt: z.coerce.date().describe("Timestamp when the agent connected")
+}).describe("A connected agent in the coordination session");
+const JoinInputSchema = z.object({
+    name: z.string().min(1).describe("Human-readable name for the agent"),
+    role: AgentRoleSchema,
+    repoPath: z.string().min(1).describe("Path to the repository this agent is working in")
+}).describe("Input for joining a coordination session");
+const JoinResultSchema = z.object({
+    agent: AgentSchema,
+    sessionId: z.string().uuid().describe("Unique identifier for the session")
+}).describe("Result of joining a coordination session");
+const ContextEntrySchema = z.object({
+    id: z.string().uuid().describe("Unique identifier for this context entry"),
+    key: z.string().min(1).describe("Key to identify this context entry"),
+    value: z.string().describe("The context value/content"),
+    tags: z.array(z.string()).describe("Tags for categorizing context"),
+    createdBy: z.string().uuid().describe("ID of the agent that created this entry"),
+    createdAt: z.coerce.date().describe("Timestamp when the entry was created"),
+    updatedAt: z.coerce.date().describe("Timestamp when the entry was last updated")
+}).describe("A shared context entry");
+const ShareContextInputSchema = z.object({
+    key: z.string().min(1).describe("Key to identify this context entry"),
+    value: z.string().describe("The context value/content to share"),
+    tags: z.array(z.string()).optional().describe("Optional tags for categorizing context")
+}).describe("Input for sharing a context entry");
+const GetContextInputSchema = z.object({
+    key: z.string().min(1).describe("Key of the context entry to retrieve")
+}).describe("Input for retrieving a context entry by key");
+const ListContextInputSchema = z.object({
+    tags: z.array(z.string()).optional().describe("Filter by tags (entries must have all specified tags)"),
+    createdBy: z.string().uuid().optional().describe("Filter by creator agent ID")
+}).describe("Input for listing context entries with optional filters");
+const DecisionSchema = z.object({
+    id: z.string().uuid().describe("Unique identifier for this decision"),
+    decision: z.string().min(1).describe("The decision that was made"),
+    rationale: z.string().optional().describe("Explanation for why this decision was made"),
+    by: z.string().uuid().describe("ID of the agent that made this decision"),
+    createdAt: z.coerce.date().describe("Timestamp when the decision was logged")
+}).describe("A logged decision");
+const LogDecisionInputSchema = z.object({
+    decision: z.string().min(1).describe("The decision that was made"),
+    rationale: z.string().optional().describe("Explanation for why this decision was made")
+}).describe("Input for logging a decision");
+const QuestionStatusSchema = z["enum"]([
+    "pending",
+    "answered"
+]).describe("Status of the question");
+const QuestionSchema = z.object({
+    id: z.string().uuid().describe("Unique identifier for this question"),
+    question: z.string().min(1).describe("The question being asked"),
+    from: z.string().uuid().describe("ID of the agent asking the question"),
+    to: z.string().uuid().optional().describe("ID of a specific agent to answer (optional)"),
+    answer: z.string().optional().describe("The answer to the question"),
+    answeredBy: z.string().uuid().optional().describe("ID of the agent that answered"),
+    status: QuestionStatusSchema,
+    createdAt: z.coerce.date().describe("Timestamp when the question was asked"),
+    answeredAt: z.coerce.date().optional().describe("Timestamp when the question was answered")
+}).describe("A question between agents");
+const AskInputSchema = z.object({
+    question: z.string().min(1).describe("The question to ask"),
+    to: z.string().uuid().optional().describe("ID of a specific agent to answer (optional)")
+}).describe("Input for asking a question");
+const AnswerInputSchema = z.object({
+    questionId: z.string().uuid().describe("ID of the question to answer"),
+    answer: z.string().min(1).describe("The answer to the question")
+}).describe("Input for answering a question");
+const QuestionEventSchema = z.object({
+    type: z.literal("question"),
+    question: QuestionSchema
+}).describe("Event emitted when a question is asked");
+const AnswerEventSchema = z.object({
+    type: z.literal("answer"),
+    question: QuestionSchema
+}).describe("Event emitted when a question is answered");
+const DEFAULT_PORT = 3030;
+const DEFAULT_HOST = "localhost";
+const DEFAULT_URL = `ws://${DEFAULT_HOST}:${DEFAULT_PORT}`;
+export { AgentRoleSchema, AgentSchema, AnswerEventSchema, AnswerInputSchema, AskInputSchema, ContextEntrySchema, DEFAULT_HOST, DEFAULT_PORT, DEFAULT_URL, DecisionSchema, GetContextInputSchema, JoinInputSchema, JoinResultSchema, ListContextInputSchema, LogDecisionInputSchema, QuestionEventSchema, QuestionSchema, QuestionStatusSchema, ShareContextInputSchema };

package/package.json

@@ -0,0 +1,43 @@
+{
+	"name": "@spencerbeggs/claude-coordinator-core",
+	"version": "0.1.0",
+	"private": false,
+	"description": "Core schemas and types for Claude Coordinator",
+	"keywords": [
+		"claude",
+		"coordinator",
+		"trpc",
+		"schemas"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/claude-design-coordinator.git",
+		"directory": "pkgs/claude-coordinator-core"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@beggs.codes",
+		"url": "https://spencerbeg.gs"
+	},
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js"
+		}
+	},
+	"dependencies": {
+		"zod": "^4.3.5"
+	},
+	"engines": {
+		"node": ">=20.0.0"
+	},
+	"files": [
+		"LICENSE",
+		"README.md",
+		"index.d.ts",
+		"index.js",
+		"package.json"
+	]
+}