feat: ✨ Add Linear integration and notification services (#23)

* Introduced `LinearClient` for managing Linear issues, including fetching, updating, and labeling.
* Implemented email notification functionality via `sendTaskOutcomeEmail` and `buildTaskOutcomeEmailPayload`.
* Created utility functions for generating prompts and comments related to planning, implementation, and review processes.
* Added logging and shell command utilities for better error handling and command execution.
* Enhanced tests to cover new features and ensure reliability across the application.

Author: 0xroylee

ARCHITECTURE.md

@@ -6,14 +6,16 @@ ADHD.ai is a multi-project orchestration hub that pulls eligible Linear issues a
 
 ## Ownership Boundaries
 
-1. `src/config.ts` is the only runtime config resolver for env vars and config files.
-2. `src/workflow.ts` owns stage transitions, retries, and orchestration order.
-3. Integration modules stay isolated:
-   - `src/linear.ts`
-   - `src/github.ts`
-   - `src/codex.ts`
-4. `src/state.ts` owns run-state paths and legacy fallback behavior.
-5. `src/args.ts` and `src/index.ts` own CLI parsing and command dispatch.
+1. `src/core/config.ts` is the only runtime config resolver for env vars and config files.
+2. `src/core/workflow.ts` owns stage transitions, retries, and orchestration order.
+3. Integration modules stay isolated under `src/services/`:
+   - `src/services/linear.ts`
+   - `src/services/github.ts`
+   - `src/services/codex.ts`
+   - `src/services/cron.ts`
+   - `src/services/notifications.ts`
+4. `src/core/state.ts` owns run-state paths and legacy fallback behavior.
+5. `src/args.ts` and `src/index.ts` own CLI parsing and command dispatch with command handlers in `src/commands/`.
 
 ## Stage Model
 

README.md

@@ -53,6 +53,7 @@ flowchart LR
 Configuration is loaded from `adhd-ai.config.ts` and resolved into project-specific runtime settings. Existing `piv-loop.config.ts` files are still accepted as a legacy fallback.
 
 - Root defaults can define shared repo, linear, codex, skills, and dry-run behavior.
+- Optional root `notifications.email` settings can enable terminal outcome emails through Resend.
 - Polling is a single global config at the root `polling` key (`intervalMs`, `maxCycles`, `exitWhenIdle`, `staleRunTimeoutMs`) and applies to all selected projects in a run.
 - Optional `linear.projectId` can scope each ADHD.ai project to a specific Linear project when selecting assigned work.
 - For targeted runs with `--all-projects --issue <KEY>`, ADHD.ai routes the issue to exactly one project by matching `linear.projectId` to the Linear issue's `projectId`.
@@ -132,6 +133,23 @@ Supported schedules:
 - `daily`: `{ frequency: "daily", time: "HH:mm" }`
 - `weekly`: `{ frequency: "weekly", dayOfWeek: "sun"|"mon"|...|"sat", time: "HH:mm" }`
 
+## Email Notifications
+
+Email notifications are optional and global. ADHD.ai sends a notification when an issue reaches a terminal outcome (`done` or `blocked`).
+
+Configuration options:
+
+- `notifications.email.enabled` (optional boolean; defaults to auto-enabled when a Resend API key exists)
+- `notifications.email.resendApiKey`
+- `notifications.email.from`
+- `notifications.email.to` (array of recipients)
+
+Environment fallbacks:
+
+- `RESEND_API_KEY`
+- `RESEND_FROM`
+- `RESEND_TO` (comma-separated recipients)
+
 ## Required Environment
 
 Set these variables before running:
@@ -174,6 +192,9 @@ The `PIV_*` environment variable namespace remains supported for compatibility w
 - `CODEX_HOME` to override Codex runtime state directory
 - `PIV_LOG_LEVEL` (optional; default `info`)
 - `PIV_LOG_PRETTY` (optional; default `1` in TTY, `0` otherwise)
+- `RESEND_API_KEY` (optional; enables email notifications when configured with sender/recipients)
+- `RESEND_FROM` (optional; required when email notifications are enabled)
+- `RESEND_TO` (optional; comma-separated recipients, required when email notifications are enabled)
 
 `LINEAR_STATUS_*` values may be either Linear workflow state IDs or exact state names (for example `Todo`, `In Progress`, `Done`). Names are resolved to IDs at runtime.
 

adhd-ai.config.ts

@@ -1,5 +1,5 @@
 import path from "node:path";
-import type { AdhdAiRootConfig, DeepPartial } from "./src/types";
+import type { AdhdAiRootConfig, DeepPartial } from "./src/core/types";
 
 const cwd = process.cwd();
 

src/args.ts

@@ -1,4 +1,4 @@
-import type { RunOptions } from "./types";
+import type { RunOptions } from "./core/types";
 
 export type CliCommand =
 	| { kind: "run"; options: RunOptions }

src/commands/handlers.ts

@@ -0,0 +1,70 @@
+import type { CliCommand } from "../args";
+import type { LoadedConfig } from "../core/config";
+import { getProjectById } from "../core/config";
+import { loadRunState, normalizeIssueKey } from "../core/state";
+import { runWorkflow } from "../core/workflow";
+import { runCronScheduler } from "../services/cron";
+
+type RunnableCommand = Exclude<CliCommand, { kind: "help" }>;
+
+export async function handleCommand(
+	command: RunnableCommand,
+	config: LoadedConfig,
+): Promise<void> {
+	if (command.kind === "run") {
+		await runWorkflow(config, command.options);
+		return;
+	}
+
+	if (command.kind === "cron") {
+		await runCronScheduler(config, { jobId: command.jobId });
+		return;
+	}
+
+	if (command.kind === "projects") {
+		for (const project of config.projects) {
+			process.stdout.write(
+				`${[
+					project.id,
+					project.name,
+					`exec=${project.executionPath}`,
+					`state=${project.workspacePath}`,
+				].join("\t")}\n`,
+			);
+		}
+		return;
+	}
+
+	const project = getProjectById(config, command.projectId);
+	if (!project) {
+		throw new Error(`Project '${command.projectId}' not found`);
+	}
+	const key = normalizeIssueKey(command.issueKey);
+	const state = await loadRunState(project.workspacePath, project.id, key);
+	if (!state) {
+		process.stdout.write(
+			`No run state found for ${key} in project ${project.id}\n`,
+		);
+		return;
+	}
+	process.stdout.write(`${JSON.stringify(state, null, 2)}\n`);
+}
+
+export function printHelp(): void {
+	process.stdout.write(
+		`${[
+			"adhd-ai - Agent-Driven Development Hub (ADHD.ai) CLI orchestration workflow",
+			"",
+			"Commands:",
+			"  adhd-ai run [--project <PROJECT_ID>] [--issue <LINEAR_KEY_OR_URL>] [--poll] [--no-exit-when-idle] [--poll-interval-ms <MS>] [--max-poll-cycles <N>]",
+			"  adhd-ai run --all-projects [--issue <LINEAR_KEY_OR_URL>] [--poll] [--no-exit-when-idle]",
+			"  adhd-ai cron [--job <JOB_ID>]",
+			"  adhd-ai status --project <PROJECT_ID> --issue <LINEAR_KEY>",
+			"  adhd-ai projects",
+			"  adhd-ai help",
+			"",
+			"Environment:",
+			"  LINEAR_API_KEY, LINEAR_STATUS_* state IDs, GITHUB_* repo settings",
+		].join("\n")}\n`,
+	);
+}

src/config.ts src/core/config.tssrc/config.ts renamed to src/core/config.ts

@@ -8,9 +8,11 @@ import type {
 	CronJobSchedule,
 	CronScheduleDayOfWeek,
 	DeepPartial,
+	NotificationConfig,
 	PollingConfig,
 	ProjectConfig,
 	ProjectRuntimeConfig,
+	ResolvedNotificationConfig,
 	ResolvedProjectConfig,
 	RunOptions,
 } from "./types";
@@ -26,21 +28,29 @@ export interface LoadedConfig {
 	projects: ResolvedProjectConfig[];
 	polling: PollingConfig;
 	cron: CronConfig;
+	notifications: ResolvedNotificationConfig;
 }
 
 export async function loadConfig(cwd: string): Promise<LoadedConfig> {
 	const envBase = buildEnvBase(cwd);
 	const envPolling = buildEnvPolling();
+	const envNotifications = buildEnvNotifications();
 	const loadedOverride = await loadConfigOverride(cwd);
 	const root = normalizeOverrideToRoot(loadedOverride);
 	assertNoProjectPolling(root.projects);
+	assertNoProjectNotifications(root.projects);
 	const projects = resolveProjects(envBase, root);
 	const polling = resolvePolling(envPolling, root.polling);
 	const cron = resolveCron(root.cron);
+	const notifications = resolveNotifications(
+		envNotifications,
+		root.notifications,
+	);
 	validateProjects(projects);
 	validatePolling(polling);
 	validateCron(cron);
-	return { projects, polling, cron };
+	validateNotifications(notifications);
+	return { projects, polling, cron, notifications };
 }
 
 export function getProjectById(
@@ -122,6 +132,18 @@ function buildEnvPolling(): PollingConfig {
 	};
 }
 
+function buildEnvNotifications(): ResolvedNotificationConfig {
+	const env = process.env;
+	return {
+		email: {
+			enabled: false,
+			resendApiKey: normalizeOptionalValue(env.RESEND_API_KEY),
+			from: normalizeOptionalValue(env.RESEND_FROM),
+			to: parseRecipientsFromEnv(env.RESEND_TO),
+		},
+	};
+}
+
 async function loadConfigOverride(cwd: string): Promise<AnyOverride> {
 	for (const configFile of [DEFAULT_CONFIG_FILE, LEGACY_CONFIG_FILE]) {
 		const configPath = path.join(cwd, configFile);
@@ -171,7 +193,13 @@ function resolveProjects(
 function stripProjects(
 	root: AdhdAiRootConfig,
 ): DeepPartial<ProjectRuntimeConfig> {
-	const { projects: _, polling: __, cron: ___, ...rest } = root;
+	const {
+		projects: _,
+		polling: __,
+		cron: ___,
+		notifications: ____,
+		...rest
+	} = root;
 	return rest;
 }
 
@@ -194,6 +222,77 @@ function resolveCron(
 	};
 }
 
+function resolveNotifications(
+	base: ResolvedNotificationConfig,
+	override: DeepPartial<NotificationConfig> | undefined,
+): ResolvedNotificationConfig {
+	const email = override?.email;
+	const resendApiKey =
+		typeof email?.resendApiKey === "string"
+			? normalizeOptionalValue(email.resendApiKey)
+			: base.email.resendApiKey;
+	const from =
+		typeof email?.from === "string"
+			? normalizeOptionalValue(email.from)
+			: base.email.from;
+	const to = normalizeRecipientsOverride(email?.to) ?? base.email.to;
+	const enabled = resolveNotificationEnabled(email?.enabled, resendApiKey);
+
+	return {
+		email: {
+			enabled,
+			resendApiKey,
+			from,
+			to,
+		},
+	};
+}
+
+function resolveNotificationEnabled(
+	input: unknown,
+	resendApiKey: string | undefined,
+): boolean {
+	if (input === undefined) {
+		return Boolean(resendApiKey);
+	}
+	if (input === true) {
+		return true;
+	}
+	if (input === false) {
+		return false;
+	}
+	throw new Error("notifications.email.enabled must be a boolean");
+}
+
+function normalizeRecipientsOverride(input: unknown): string[] | undefined {
+	if (input === undefined) {
+		return undefined;
+	}
+	if (!Array.isArray(input)) {
+		throw new Error("notifications.email.to must be an array of email strings");
+	}
+
+	const recipients = input.map((value, index) => {
+		if (typeof value !== "string") {
+			throw new Error(
+				`notifications.email.to[${index}] must be an email string`,
+			);
+		}
+		return value.trim();
+	});
+	return recipients.filter((recipient) => recipient.length > 0);
+}
+
+function parseRecipientsFromEnv(input: string | undefined): string[] {
+	if (!input) {
+		return [];
+	}
+	return input
+		.split(",")
+		.map((value) => value.trim())
+		.filter((value) => value.length > 0);
+}
+
 function resolveCronJob(
 	job: DeepPartial<CronJobConfig>,
 	index: number,
@@ -555,6 +654,30 @@ function validateCron(cron: CronConfig): void {
 	}
 }
 
+function validateNotifications(
+	notifications: ResolvedNotificationConfig,
+): void {
+	const { email } = notifications;
+	if (!email.enabled) {
+		return;
+	}
+	if (!email.resendApiKey) {
+		throw new Error(
+			"notifications.email.resendApiKey (or RESEND_API_KEY) is required when email notifications are enabled",
+		);
+	}
+	if (!email.from) {
+		throw new Error(
+			"notifications.email.from (or RESEND_FROM) is required when email notifications are enabled",
+		);
+	}
+	if (email.to.length === 0) {
+		throw new Error(
+			"notifications.email.to (or RESEND_TO) must include at least one recipient when email notifications are enabled",
+		);
+	}
+}
+
 function validateCronSchedule(jobId: string, schedule: CronJobSchedule): void {
 	if (schedule.frequency === "minute") {
 		const every = schedule.every ?? 1;
@@ -636,3 +759,13 @@ function assertNoProjectPolling(projects: ProjectConfig[]): void {
 		}
 	}
 }
+
+function assertNoProjectNotifications(projects: ProjectConfig[]): void {
+	for (const project of projects) {
+		if ("notifications" in (project as unknown as Record<string, unknown>)) {
+			throw new Error(
+				`Project-level notifications config is not supported for project '${project.id}'. Configure notifications once at root level.`,
+			);
+		}
+	}
+}

src/review.ts src/core/review.tssrc/review.ts renamed to src/core/review.ts

@@ -148,9 +148,32 @@ export interface CronConfig {
 	jobs: CronJobConfig[];
 }
 
+export interface NotificationEmailConfig {
+	enabled?: boolean;
+	resendApiKey?: string;
+	from?: string;
+	to?: string[];
+}
+
+export interface NotificationConfig {
+	email?: NotificationEmailConfig;
+}
+
+export interface ResolvedNotificationEmailConfig {
+	enabled: boolean;
+	resendApiKey?: string;
+	from?: string;
+	to: string[];
+}
+
+export interface ResolvedNotificationConfig {
+	email: ResolvedNotificationEmailConfig;
+}
+
 export type AdhdAiRootConfig = DeepPartial<ProjectRuntimeConfig> & {
 	polling?: DeepPartial<PollingConfig>;
 	cron?: DeepPartial<CronConfig>;
+	notifications?: DeepPartial<NotificationConfig>;
 	projects: ProjectConfig[];
 };