aos-harness 0.8.4 → 0.9.0

package/core/profiles/strategic-council/profile.yaml

@@ -58,7 +58,7 @@ constraints:
     max: 8
 
 error_handling:
-  agent_timeout_seconds: 120
+  agent_timeout_seconds: 3600           # Strategic deliberations can legitimately run 2-60 minutes per agent turn
   retry_policy:
     max_retries: 2
     backoff: exponential

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aos-harness",
-  "version": "0.8.4",
+  "version": "0.9.0",
   "description": "Agentic Orchestration System — assemble AI agents into deliberation and execution teams",
   "license": "MIT",
   "publishConfig": {
@@ -38,18 +38,18 @@
     "test": "bun run src/index.ts validate"
   },
   "dependencies": {
-    "@aos-harness/adapter-shared": "0.8.4",
-    "@aos-harness/runtime": "0.8.4",
+    "@aos-harness/adapter-shared": "0.9.0",
+    "@aos-harness/runtime": "0.9.0",
     "@clack/prompts": "^1.2.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "js-yaml": "^4.1.0",
     "yaml": "^2.8.3"
   },
   "peerDependencies": {
-    "@aos-harness/claude-code-adapter": ">=0.8.4 <1.0.0",
-    "@aos-harness/codex-adapter": ">=0.8.4 <1.0.0",
-    "@aos-harness/gemini-adapter": ">=0.8.4 <1.0.0",
-    "@aos-harness/pi-adapter": ">=0.8.4 <1.0.0"
+    "@aos-harness/claude-code-adapter": ">=0.9.0 <1.0.0",
+    "@aos-harness/codex-adapter": ">=0.9.0 <1.0.0",
+    "@aos-harness/gemini-adapter": ">=0.9.0 <1.0.0",
+    "@aos-harness/pi-adapter": ">=0.9.0 <1.0.0"
   },
   "peerDependenciesMeta": {
     "@aos-harness/claude-code-adapter": {

package/src/adapter-session.ts

@@ -65,6 +65,7 @@ export interface AdapterSessionConfig {
    * also batched to `${platformUrl}/api/sessions/:id/events`.
    */
   platformUrl?: string;
+  agentTimeoutMs?: number;
 }
 
 function createStreamingPrinter() {
@@ -523,6 +524,7 @@ export async function runAdapterSession(config: AdapterSessionConfig): Promise<v
         response = await adapter.sendMessage(arbiterHandle, kickoff, {
           extraArgs: mcpArgs,
           onStream: (partial) => printer.push(partial),
+          timeoutMs: config.agentTimeoutMs,
         });
       } finally {
         clearInterval(heartbeat);

package/src/brief/parse.ts

@@ -0,0 +1,58 @@
+export interface ParsedSection {
+  heading: string;
+  level: 1 | 2 | 3;
+  body: string;
+  startLine: number;
+}
+
+const HEADING_RE = /^(#{1,3})\s+(.+?)\s*$/;
+const TITLE_RE = /^#\s+Brief:\s+(.+?)\s*$/;
+
+export function parseTitle(markdown: string): string | null {
+  for (const line of markdown.split("\n")) {
+    const match = line.match(TITLE_RE);
+    if (match) return match[1];
+  }
+  return null;
+}
+
+export function parseSections(markdown: string): ParsedSection[] {
+  const lines = markdown.split("\n");
+  const sections: ParsedSection[] = [];
+  let current: ParsedSection | null = null;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const match = line.match(HEADING_RE);
+    if (match) {
+      const level = match[1].length as 1 | 2 | 3;
+      if (level === 1) {
+        if (current) {
+          sections.push(current);
+          current = null;
+        }
+        continue;
+      }
+      if (current) sections.push(current);
+      current = { heading: match[2], level, body: "", startLine: i };
+    } else if (current) {
+      current.body += `${line}\n`;
+    }
+  }
+
+  if (current) sections.push(current);
+  return sections;
+}
+
+export function isBodyEmpty(body: string): boolean {
+  return body.replace(/<!--[\s\S]*?-->/g, "").trim().length === 0;
+}
+
+export function findSection(
+  sections: ParsedSection[],
+  canonical: string,
+  aliases: string[] = [],
+): ParsedSection | null {
+  const candidates = [canonical, ...aliases].map((candidate) => candidate.toLowerCase());
+  return sections.find((section) => candidates.includes(section.heading.toLowerCase())) ?? null;
+}

package/src/brief/prompts.ts

@@ -0,0 +1,77 @@
+import type { BriefKind, BriefSections } from "./types";
+
+export interface LineReader {
+  readLine(): Promise<string>;
+}
+
+export interface PromptLoopOpts {
+  reader: LineReader;
+  kind?: BriefKind;
+  slug?: string;
+  title?: string;
+  seedText?: string;
+  log?: (line: string) => void;
+}
+
+export interface PromptLoopResult {
+  slug: string;
+  kind: BriefKind;
+  title: string;
+  sections: BriefSections;
+}
+
+const SECTION_PROMPTS: Record<BriefKind, Array<{ key: keyof BriefSections; label: string }>> = {
+  deliberation: [
+    { key: "situation", label: "What's the situation? (multi-line, end with blank line)" },
+    { key: "stakes", label: "What's at stake?" },
+    { key: "constraints", label: "What constraints apply?" },
+    { key: "keyQuestion", label: "What is the single key question for the council?" },
+  ],
+  execution: [
+    { key: "featureVision", label: "What feature or vision are we building?" },
+    { key: "context", label: "What context (environment, prior art, repo state)?" },
+    { key: "constraints", label: "What constraints apply?" },
+    { key: "successCriteria", label: "What success criteria define done?" },
+  ],
+};
+
+export async function runBriefPromptLoop(opts: PromptLoopOpts): Promise<PromptLoopResult> {
+  const log = opts.log ?? ((line: string) => console.log(line));
+
+  if (opts.seedText) log(`\nYour seed: ${opts.seedText}\n`);
+
+  const slug = opts.slug ?? (await ask(opts.reader, log, "Slug for this brief (kebab-case)?"));
+  let kind: BriefKind;
+  if (opts.kind) {
+    kind = opts.kind;
+  } else {
+    log("\nKind?");
+    log("  1. deliberation");
+    log("  2. execution");
+    kind = (await ask(opts.reader, log, "Enter number:")).trim() === "2" ? "execution" : "deliberation";
+  }
+
+  const title = opts.title ?? (await ask(opts.reader, log, "One-line title?"));
+  const sections: BriefSections = {};
+  for (const { key, label } of SECTION_PROMPTS[kind]) {
+    sections[key] = await askMultiline(opts.reader, log, label);
+  }
+
+  return { slug, kind, title, sections };
+}
+
+async function ask(reader: LineReader, log: (line: string) => void, label: string): Promise<string> {
+  log(`\n${label}`);
+  return (await reader.readLine()).trim();
+}
+
+async function askMultiline(reader: LineReader, log: (line: string) => void, label: string): Promise<string> {
+  log(`\n${label}`);
+  const lines: string[] = [];
+  while (true) {
+    const line = await reader.readLine();
+    if (line.trim() === "") break;
+    lines.push(line);
+  }
+  return lines.join("\n");
+}

package/src/brief/schema.ts

@@ -0,0 +1,24 @@
+import type { BriefKind, BriefSchemaDef } from "./types";
+
+export const DELIBERATION_SCHEMA: BriefSchemaDef = {
+  requiredSections: ["Situation", "Stakes", "Constraints", "Key Question"],
+  optionalSections: ["Background", "Out of scope"],
+  aliases: {},
+};
+
+export const EXECUTION_SCHEMA: BriefSchemaDef = {
+  requiredSections: ["Feature / Vision", "Context", "Constraints", "Success Criteria"],
+  optionalSections: ["Stakeholders", "Out of scope", "Open Questions"],
+  aliases: {
+    "Feature / Vision": ["Vision"],
+  },
+};
+
+export function briefSchema(kind: BriefKind): BriefSchemaDef {
+  return kind === "deliberation" ? DELIBERATION_SCHEMA : EXECUTION_SCHEMA;
+}
+
+export const DISCRIMINATING_HEADINGS: Record<BriefKind, string> = {
+  deliberation: "Key Question",
+  execution: "Success Criteria",
+};

package/src/brief/template.ts

@@ -0,0 +1,74 @@
+import type { BriefKind, BriefSections } from "./types";
+import { briefSchema } from "./schema";
+
+const SECTION_KEY_MAP: Record<BriefKind, Record<string, keyof BriefSections>> = {
+  deliberation: {
+    "Situation": "situation",
+    "Stakes": "stakes",
+    "Constraints": "constraints",
+    "Background": "background",
+    "Out of scope": "outOfScope",
+    "Key Question": "keyQuestion",
+  },
+  execution: {
+    "Feature / Vision": "featureVision",
+    "Context": "context",
+    "Constraints": "constraints",
+    "Stakeholders": "stakeholders",
+    "Out of scope": "outOfScope",
+    "Open Questions": "openQuestions",
+    "Success Criteria": "successCriteria",
+  },
+};
+
+const PLACEHOLDER_TEXT: Record<string, string> = {
+  "Situation": "Describe what is happening, who is involved, what triggered the decision.",
+  "Stakes": "Spell out upside and downside for each path.",
+  "Constraints": "List budget, timeline, technical, and regulatory constraints.",
+  "Key Question": "State the single decision question for the council.",
+  "Background": "Extended context (optional).",
+  "Out of scope": "Things explicitly not on the table (optional).",
+  "Feature / Vision": "What you're building and why.",
+  "Context": "Environment, prior art, repo state.",
+  "Success Criteria": "How will you know this is done?",
+  "Stakeholders": "Who consumes this output (optional).",
+  "Open Questions": "Known unknowns (optional).",
+};
+
+export interface RenderOpts {
+  kind: BriefKind;
+  title?: string;
+  prefilled?: BriefSections;
+  seedText?: string;
+}
+
+export function renderBriefTemplate(opts: RenderOpts): string {
+  const lines: string[] = [`# Brief: ${opts.title ?? "TODO"}`, ""];
+
+  if (opts.seedText) {
+    lines.push("<!-- raw idea seed:");
+    lines.push(...opts.seedText.split("\n"));
+    lines.push("-->", "");
+  }
+
+  const schema = briefSchema(opts.kind);
+  const ordered = [...schema.requiredSections];
+  for (const optional of schema.optionalSections) {
+    if (!ordered.includes(optional)) ordered.push(optional);
+  }
+
+  const keyMap = SECTION_KEY_MAP[opts.kind];
+  for (const heading of ordered) {
+    lines.push(`## ${heading}`, "");
+    const key = keyMap[heading];
+    const filled = key ? opts.prefilled?.[key] : undefined;
+    if (filled && filled.trim()) {
+      lines.push(filled.trim());
+    } else {
+      lines.push(`<!-- TODO: ${PLACEHOLDER_TEXT[heading] ?? `Describe ${heading.toLowerCase()}.`} -->`);
+    }
+    lines.push("");
+  }
+
+  return `${lines.join("\n").trimEnd()}\n`;
+}

package/src/brief/types.ts

@@ -0,0 +1,44 @@
+export type BriefKind = "deliberation" | "execution";
+
+export type BriefIssueKind =
+  | "missing-required"
+  | "empty-section"
+  | "missing-title"
+  | "title-format"
+  | "auto-detect-failed"
+  | "shape-mismatch-hint";
+
+export interface BriefIssue {
+  kind: BriefIssueKind;
+  section?: string;
+  message: string;
+}
+
+export interface BriefValidation {
+  ok: boolean;
+  detectedKind: BriefKind | null;
+  errors: BriefIssue[];
+  warnings: BriefIssue[];
+}
+
+export interface BriefSchemaDef {
+  requiredSections: string[];
+  optionalSections: string[];
+  aliases: Record<string, string[]>;
+}
+
+export interface BriefSections {
+  title?: string;
+  contextFiles?: string;
+  situation?: string;
+  stakes?: string;
+  background?: string;
+  outOfScope?: string;
+  keyQuestion?: string;
+  featureVision?: string;
+  context?: string;
+  stakeholders?: string;
+  openQuestions?: string;
+  successCriteria?: string;
+  constraints?: string;
+}

package/src/brief/validate.ts

@@ -0,0 +1,97 @@
+import type { BriefKind, BriefIssue, BriefValidation } from "./types";
+import { briefSchema, DISCRIMINATING_HEADINGS } from "./schema";
+import { findSection, isBodyEmpty, parseSections, parseTitle, type ParsedSection } from "./parse";
+
+export interface ValidateOptions {
+  expectedKind?: BriefKind;
+  strict?: boolean;
+}
+
+export function validateBrief(markdown: string, opts: ValidateOptions = {}): BriefValidation {
+  const errors: BriefIssue[] = [];
+  const warnings: BriefIssue[] = [];
+
+  if (!parseTitle(markdown)) {
+    errors.push({
+      kind: "missing-title",
+      message: "Title must be a H1 line starting with `Brief: ` (e.g. `# Brief: API Platform Decision`).",
+    });
+  }
+
+  const sections = parseSections(markdown);
+  const kind = opts.expectedKind ?? autoDetectKind(sections, errors);
+  if (!kind) {
+    return { ok: false, detectedKind: null, errors, warnings };
+  }
+
+  const schema = briefSchema(kind);
+  for (const required of schema.requiredSections) {
+    const aliases = schema.aliases[required] ?? [];
+    const found = findSection(sections, required, aliases);
+    if (!found) {
+      errors.push({
+        kind: "missing-required",
+        section: required,
+        message: `Missing required section: \`## ${required}\`.`,
+      });
+      continue;
+    }
+
+    if (isBodyEmpty(found.body)) {
+      const issue: BriefIssue = {
+        kind: "empty-section",
+        section: required,
+        message: `Section \`## ${required}\` is empty.`,
+      };
+      if (opts.strict) errors.push(issue);
+      else warnings.push(issue);
+    }
+  }
+
+  if (opts.expectedKind) {
+    const missingCount = errors.filter((issue) => issue.kind === "missing-required").length;
+    if (missingCount >= 2) {
+      const otherKind: BriefKind = opts.expectedKind === "deliberation" ? "execution" : "deliberation";
+      if (findSection(sections, DISCRIMINATING_HEADINGS[otherKind])) {
+        errors.push({
+          kind: "shape-mismatch-hint",
+          message: `This brief looks shaped for \`${otherKind}\`. Either run a \`${otherKind}\` profile or re-author with \`aos create brief --kind ${opts.expectedKind}\`.`,
+        });
+      }
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    detectedKind: kind,
+    errors,
+    warnings,
+  };
+}
+
+function autoDetectKind(sections: ParsedSection[], errors: BriefIssue[]): BriefKind | null {
+  const deliberationScore = scoreKind("deliberation", sections);
+  const executionScore = scoreKind("execution", sections);
+  const best = Math.max(deliberationScore, executionScore);
+
+  if (best < 2 || deliberationScore === executionScore && best < 4) {
+    errors.push({
+      kind: "auto-detect-failed",
+      message:
+        "Brief is missing too many required sections to determine kind. Specify `--kind deliberation` or `--kind execution`, or author from scratch with `aos create brief`.",
+    });
+    return null;
+  }
+
+  if (deliberationScore === executionScore) {
+    return "execution";
+  }
+  return deliberationScore > executionScore ? "deliberation" : "execution";
+}
+
+function scoreKind(kind: BriefKind, sections: ParsedSection[]): number {
+  const schema = briefSchema(kind);
+  return schema.requiredSections.filter((required) =>
+    findSection(sections, required, schema.aliases[required] ?? []),
+  ).length;
+}

package/src/brief/write.ts

@@ -0,0 +1,35 @@
+import { dirname } from "node:path";
+import { existsSync, mkdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+
+export interface WriteOpts {
+  force: boolean;
+}
+
+export async function atomicWriteBrief(targetPath: string, content: string, opts: WriteOpts): Promise<void> {
+  if (existsSync(targetPath) && !opts.force) {
+    throw new Error(`Brief already exists at ${targetPath}. Pass --force to overwrite.`);
+  }
+
+  const parent = dirname(targetPath);
+  try {
+    mkdirSync(parent, { recursive: true });
+  } catch (err: any) {
+    if (err.code === "EACCES" || err.code === "EROFS") {
+      throw new Error(`Cannot create directory ${parent}: permission denied. Use --out <path> to write somewhere else.`);
+    }
+    throw err;
+  }
+
+  const tmpPath = `${targetPath}.tmp.${process.pid}`;
+  try {
+    writeFileSync(tmpPath, content, "utf-8");
+    renameSync(tmpPath, targetPath);
+  } catch (err) {
+    try {
+      if (existsSync(tmpPath)) unlinkSync(tmpPath);
+    } catch {
+      // best-effort cleanup
+    }
+    throw err;
+  }
+}

package/src/commands/brief.ts

@@ -0,0 +1,167 @@
+import { existsSync, readFileSync } from "node:fs";
+import { Buffer } from "node:buffer";
+import { c, type ParsedArgs } from "../colors";
+import type { BriefKind } from "../brief/types";
+
+const HELP = `
+${c.bold("aos brief")} — Work with brief files
+
+${c.bold("USAGE")}
+  aos brief <subcommand> [options]
+
+${c.bold("SUBCOMMANDS")}
+  ${c.cyan("template")}    Render a blank brief template to stdout or --out
+  ${c.cyan("validate")}    Validate a brief against its schema
+  ${c.cyan("save")}        Atomically write a brief (used by skills)
+
+${c.bold("EXAMPLES")}
+  aos brief template --kind deliberation
+  aos brief validate ./briefs/foo/brief.md --kind deliberation
+  aos brief save ./briefs/foo/brief.md --kind execution --from-file draft.md
+`;
+
+export async function briefCommand(args: ParsedArgs): Promise<void> {
+  if (args.flags.help && !args.subcommand) {
+    console.log(HELP);
+    return;
+  }
+
+  switch (args.subcommand) {
+    case "template":
+      await templateCommand(args);
+      return;
+    case "validate":
+      await validateCommand(args);
+      return;
+    case "save":
+      await saveCommand(args);
+      return;
+    case "":
+    case undefined:
+    case null:
+      console.log(HELP);
+      return;
+    default:
+      console.error(c.red(`Unknown brief subcommand: "${args.subcommand}". Run "aos brief --help".`));
+      process.exit(2);
+  }
+}
+
+function parseKind(value: string | boolean | undefined): BriefKind | null {
+  return value === "deliberation" || value === "execution" ? value : null;
+}
+
+async function templateCommand(args: ParsedArgs): Promise<void> {
+  const kind = parseKind(args.flags.kind);
+  if (!args.flags.kind) {
+    console.error(c.red("Missing --kind. Use --kind deliberation or --kind execution."));
+    process.exit(2);
+  }
+  if (!kind) {
+    console.error(c.red(`--kind must be deliberation or execution (got "${args.flags.kind}").`));
+    process.exit(2);
+  }
+
+  const { renderBriefTemplate } = await import("../brief/template");
+  const out = renderBriefTemplate({
+    kind,
+    title: (args.flags.title as string | undefined) ?? "TODO",
+    seedText: args.flags.idea as string | undefined,
+  });
+
+  const outPath = args.flags.out as string | undefined;
+  if (outPath) {
+    const { atomicWriteBrief } = await import("../brief/write");
+    try {
+      await atomicWriteBrief(outPath, out, { force: Boolean(args.flags.force) });
+    } catch (err: any) {
+      console.error(c.red(err.message));
+      process.exit(1);
+    }
+    console.error(c.dim(`Template written to ${outPath}.`));
+  } else {
+    process.stdout.write(out);
+  }
+}
+
+async function validateCommand(args: ParsedArgs): Promise<void> {
+  const path = args.positional[1];
+  if (!path) {
+    console.error(c.red("Missing brief path. Usage: aos brief validate <path> [--kind <k>] [--strict]"));
+    process.exit(2);
+  }
+  if (!existsSync(path)) {
+    console.error(c.red(`Brief file not found: ${path}`));
+    process.exit(2);
+  }
+
+  const kind = args.flags.kind ? parseKind(args.flags.kind) : undefined;
+  if (args.flags.kind && !kind) {
+    console.error(c.red(`--kind must be deliberation or execution (got "${args.flags.kind}").`));
+    process.exit(2);
+  }
+
+  const { validateBrief } = await import("../brief/validate");
+  const result = validateBrief(readFileSync(path, "utf-8"), {
+    expectedKind: kind || undefined,
+    strict: Boolean(args.flags.strict),
+  });
+  for (const issue of [...result.errors, ...result.warnings]) {
+    const sectionLabel = issue.section ? `[${issue.section}] ` : "";
+    const color = issue.kind === "empty-section" && !args.flags.strict ? c.yellow : c.red;
+    console.error(color(`${sectionLabel}${issue.message}`));
+  }
+  process.exit(result.errors.length > 0 ? 1 : 0);
+}
+
+async function saveCommand(args: ParsedArgs): Promise<void> {
+  const path = args.positional[1];
+  if (!path) {
+    console.error(c.red("Missing target path. Usage: aos brief save <path> --kind <k> [--from-file <p> | --from-stdin]"));
+    process.exit(2);
+  }
+
+  const kind = parseKind(args.flags.kind);
+  if (!kind) {
+    console.error(c.red("--kind required (deliberation or execution)."));
+    process.exit(2);
+  }
+
+  let content: string;
+  const fromFile = args.flags["from-file"] as string | undefined;
+  const fromStdin = Boolean(args.flags["from-stdin"]);
+  if (fromFile) {
+    if (!existsSync(fromFile)) {
+      console.error(c.red(`--from-file path not found: ${fromFile}`));
+      process.exit(2);
+    }
+    content = readFileSync(fromFile, "utf-8");
+  } else if (fromStdin) {
+    const chunks: Uint8Array[] = [];
+    for await (const chunk of Bun.stdin.stream()) chunks.push(chunk);
+    content = new TextDecoder().decode(Buffer.concat(chunks));
+  } else {
+    console.error(c.red("Must pass --from-file <path> or --from-stdin."));
+    process.exit(2);
+  }
+
+  const { validateBrief } = await import("../brief/validate");
+  const validation = validateBrief(content, { expectedKind: kind, strict: true });
+  if (validation.errors.length > 0) {
+    console.error(c.red(`Brief validation failed (${validation.errors.length} error${validation.errors.length === 1 ? "" : "s"}):`));
+    for (const err of validation.errors) {
+      const sectionLabel = err.section ? `[${err.section}] ` : "";
+      console.error(c.red(`  ${sectionLabel}${err.message}`));
+    }
+    process.exit(1);
+  }
+
+  const { atomicWriteBrief } = await import("../brief/write");
+  try {
+    await atomicWriteBrief(path, content, { force: Boolean(args.flags.force) });
+  } catch (err: any) {
+    console.error(c.red(err.message));
+    process.exit(1);
+  }
+  console.log(c.green(`Brief saved to ${path}`));
+}

package/src/commands/create.ts

@@ -2,19 +2,21 @@
  * aos create — Scaffold new agents, profiles, and domains.
  */
 
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { Buffer } from "node:buffer";
 import { c, type ParsedArgs } from "../colors";
 import { getHarnessRoot, toKebabCase } from "../utils";
 
 const HELP = `
-${c.bold("aos create")} — Scaffold new agents, profiles, domains, and skills
+${c.bold("aos create")} — Scaffold new agents, profiles, domains, skills, and briefs
 
 ${c.bold("USAGE")}
   aos create agent <name>       Create a new custom agent
   aos create profile <name>     Create a new profile
   aos create domain <name>      Create a new domain pack
   aos create skill <name>       Create a new skill definition
+  aos create brief [slug]       Create a new deliberation or execution brief
 
 ${c.bold("DESCRIPTION")}
   Generates well-structured scaffolds that pass "aos validate" out of the box.
@@ -26,6 +28,8 @@ ${c.bold("EXAMPLES")}
   aos create profile security-review
   aos create domain healthcare
   aos create skill dependency-analysis
+  aos create brief my-decision --kind deliberation --non-interactive --title "Decision" \\
+    --situation "..." --stakes "..." --constraints "..." --key-question "?"
 `;
 
 // ── Agent scaffold ──────────────────────────────────────────────
@@ -371,12 +375,17 @@ export async function createCommand(args: ParsedArgs): Promise<void> {
   const type = args.subcommand;
   const name = args.positional[1];
 
-  if (!name) {
+  if (!name && type !== "brief") {
     console.error(c.red(`Missing name. Usage: aos create ${type} <name>`));
     process.exit(1);
   }
 
-  const id = toKebabCase(name);
+  if (type === "brief") {
+    await createBrief(args);
+    return;
+  }
+
+  const id = toKebabCase(name!);
   if (!/^[a-z0-9][a-z0-9-]*$/.test(id)) {
     console.error(c.red(`Invalid name "${name}": must kebab-case to /^[a-z0-9][a-z0-9-]*$/`));
     console.error(c.dim(`Allowed characters: a-z, 0-9, hyphen. Must start with a letter or digit.`));
@@ -490,7 +499,113 @@ ${c.bold("Next Steps")}
     }
 
     default:
-      console.error(c.red(`Unknown type: "${type}". Use "agent", "profile", "domain", or "skill".`));
+      console.error(c.red(`Unknown type: "${type}". Use "agent", "profile", "domain", "skill", or "brief".`));
       process.exit(1);
   }
 }
+
+async function createBrief(args: ParsedArgs): Promise<void> {
+  const { renderBriefTemplate } = await import("../brief/template");
+  const { validateBrief } = await import("../brief/validate");
+  const { atomicWriteBrief } = await import("../brief/write");
+  const { runBriefPromptLoop } = await import("../brief/prompts");
+
+  const slugPositional = args.positional[1];
+  const kindFlag = args.flags.kind as ("deliberation" | "execution" | undefined);
+  const titleFlag = args.flags.title as string | undefined;
+  const fromNotes = args.flags["from-notes"] as string | undefined;
+  const seedText = (args.flags.idea as string | undefined) ??
+    (fromNotes ? readFileSync(fromNotes, "utf-8") : undefined);
+  const nonInteractive = Boolean(args.flags["non-interactive"]);
+  const force = Boolean(args.flags.force);
+
+  let slug: string;
+  let kind: "deliberation" | "execution";
+  let title: string;
+  let sections: any = {};
+
+  if (nonInteractive) {
+    if (!slugPositional) {
+      console.error(c.red("--non-interactive requires <slug> positional."));
+      process.exit(2);
+    }
+    if (kindFlag !== "deliberation" && kindFlag !== "execution") {
+      console.error(c.red("--non-interactive requires --kind deliberation or --kind execution."));
+      process.exit(2);
+    }
+    if (!titleFlag) {
+      console.error(c.red("--non-interactive requires --title."));
+      process.exit(2);
+    }
+
+    slug = toKebabCase(slugPositional);
+    kind = kindFlag;
+    title = titleFlag;
+    sections = kind === "deliberation"
+      ? {
+          situation: args.flags.situation as string | undefined,
+          stakes: args.flags.stakes as string | undefined,
+          constraints: args.flags.constraints as string | undefined,
+          keyQuestion: args.flags["key-question"] as string | undefined,
+        }
+      : {
+          featureVision: args.flags.feature as string | undefined,
+          context: args.flags.context as string | undefined,
+          constraints: args.flags.constraints as string | undefined,
+          successCriteria: args.flags["success-criteria"] as string | undefined,
+        };
+  } else {
+    const reader = await createStdinLineReader();
+    const result = await runBriefPromptLoop({
+      reader,
+      kind: kindFlag,
+      slug: slugPositional ? toKebabCase(slugPositional) : undefined,
+      title: titleFlag,
+      seedText,
+    });
+    slug = toKebabCase(result.slug);
+    kind = result.kind;
+    title = result.title;
+    sections = result.sections;
+  }
+
+  const rendered = renderBriefTemplate({ kind, title, prefilled: sections, seedText });
+  const validation = validateBrief(rendered, { expectedKind: kind, strict: true });
+  if (validation.errors.length > 0) {
+    console.error(c.red("Brief incomplete:"));
+    for (const err of validation.errors) {
+      const sectionLabel = err.section ? `[${err.section}] ` : "";
+      console.error(c.red(`  ${sectionLabel}${err.message}`));
+    }
+    process.exit(1);
+  }
+
+  const outFlag = args.flags.out as string | undefined;
+  const targetPath = outFlag
+    ? resolve(process.cwd(), outFlag)
+    : Boolean(args.flags.shared)
+      ? join(getHarnessRoot(), "core", "briefs", slug, "brief.md")
+      : resolve(process.cwd(), "briefs", slug, "brief.md");
+
+  try {
+    await atomicWriteBrief(targetPath, rendered, { force });
+  } catch (err: any) {
+    console.error(c.red(err.message));
+    process.exit(1);
+  }
+
+  console.log(c.green(`Brief saved to ${targetPath}`));
+  console.log(c.dim(`Run with: aos run <profile> --brief ${targetPath}`));
+}
+
+async function createStdinLineReader() {
+  const chunks: Uint8Array[] = [];
+  for await (const chunk of Bun.stdin.stream()) chunks.push(chunk);
+  const lines = new TextDecoder().decode(Buffer.concat(chunks)).split(/\r?\n/);
+  let index = 0;
+  return {
+    async readLine(): Promise<string> {
+      return lines[index++] ?? "";
+    },
+  };
+}

package/src/commands/run.ts

@@ -236,10 +236,30 @@ export async function runCommand(args: ParsedArgs): Promise<void> {
     process.exit(3);
   }
 
-  const validation = validateBrief(briefPath, profile.input.required_sections);
-
   // ── Detect execution profile (has workflow field) ──────────
   const isExecutionProfile = !!profile.workflow;
+
+  // Brief lint is advisory. The existing profile section validation below
+  // remains the blocking compatibility check for run.
+  try {
+    const briefContent = readFileSync(briefPath, "utf-8");
+    const expectedKind: "deliberation" | "execution" = isExecutionProfile ? "execution" : "deliberation";
+    const { validateBrief: validateBriefShape } = await import("../brief/validate");
+    const briefValidation = validateBriefShape(briefContent, { expectedKind });
+    const errCount = briefValidation.errors.length;
+    const warnCount = briefValidation.warnings.length;
+    if (errCount === 0 && warnCount === 0) {
+      console.error(c.dim(`Brief lint: ${expectedKind} brief looks good (0 errors, 0 warnings).`));
+    } else {
+      console.error(c.yellow(`Brief lint: ${errCount} error${errCount === 1 ? "" : "s"}, ${warnCount} warning${warnCount === 1 ? "" : "s"}.`));
+      console.error(c.dim(`  Run \`aos brief validate ${briefPath}\` for details, or \`aos create brief\` to author from a template.`));
+    }
+  } catch (err) {
+    console.error(c.dim(`(brief lint skipped: ${(err as Error).message})`));
+  }
+
+  const validation = validateBrief(briefPath, profile.input.required_sections);
+
   let workflowConfig: Awaited<ReturnType<typeof loadWorkflow>> | null = null;
 
   if (isExecutionProfile) {
@@ -519,6 +539,10 @@ ${c.bold(`AOS ${sessionType} Session`)}
       useVendorDefaultModel: runtimeModelConfig.useVendorDefaultModel,
       toolPolicy,
       platformUrl: platformUrl ?? undefined,
+      agentTimeoutMs:
+        typeof profile.error_handling?.agent_timeout_seconds === "number"
+          ? profile.error_handling.agent_timeout_seconds * 1000
+          : undefined,
     });
   }
 }

package/src/commands/validate.ts

@@ -29,7 +29,7 @@ ${c.bold("CHECKS")}
   - Domain merging produces valid output
   - Skills load and have required fields (id, name, input, output, etc.)
   - Skills reference valid compatible agents
-  - Briefs pass section requirements
+  - Briefs are well-formed (deliberation or execution shape)
   - Template resolution works for all agents
   - Constraint engine initializes from profiles
   - Delegation router initializes from profiles
@@ -51,7 +51,7 @@ export async function validateCommand(args: ParsedArgs): Promise<void> {
   const coreDir = join(root, "core");
 
   // Import runtime modules
-  const { loadAgent, loadProfile, loadDomain, loadWorkflow, loadSkill, validateBrief } = await import("@aos-harness/runtime/config-loader");
+  const { loadAgent, loadProfile, loadDomain, loadWorkflow, loadSkill } = await import("@aos-harness/runtime/config-loader");
   const { applyDomain } = await import("@aos-harness/runtime/domain-merger");
   const { resolveTemplate } = await import("@aos-harness/runtime/template-resolver");
   const { ConstraintEngine } = await import("@aos-harness/runtime/constraint-engine");
@@ -246,26 +246,38 @@ export async function validateCommand(args: ParsedArgs): Promise<void> {
   }
 
   // ── 5. Validate briefs ────────────────────────────────────────
+  //
+  // Briefs are authored per-profile; checking every brief against every
+  // profile's required_sections (a cross-product) produces noise — `incident-
+  // response` and `strategic-council` have different required sections by
+  // design. We only check each brief is well-formed (matches one of the
+  // canonical kinds: deliberation or execution). Run-time enforcement of
+  // profile-specific required sections happens in `aos run` — both via the
+  // brief lint summary and via the runtime config-loader's validateBrief
+  // against the chosen profile.
 
   console.log(`${c.bold("Validating briefs...")}`);
 
   const briefsDir = join(coreDir, "briefs");
   if (existsSync(briefsDir)) {
+    const { readFileSync } = await import("node:fs");
+    const { validateBrief: lintBrief } = await import("../brief/validate");
+
     for (const entry of readdirSync(briefsDir, { withFileTypes: true })) {
       if (!entry.isDirectory()) continue;
       const briefPath = join(briefsDir, entry.name, "brief.md");
       if (!existsSync(briefPath)) continue;
 
-      // Validate against each profile's required sections
-      for (const profile of profiles) {
-        check(`Brief "${entry.name}" for profile "${profile.id}"`, () => {
-          const result = validateBrief(briefPath, profile.input.required_sections);
-          if (!result.valid) {
-            const missingNames = result.missing.map((s: any) => s.heading).join(", ");
-            throw new Error(`Missing sections: ${missingNames}. Add them to your brief.md and try again.`);
-          }
-        });
-      }
+      check(`Brief "${entry.name}" is well-formed`, () => {
+        const content = readFileSync(briefPath, "utf-8");
+        const result = lintBrief(content);
+        if (result.errors.length > 0) {
+          throw new Error(result.errors.map((e) => e.message).join(" "));
+        }
+        if (result.warnings.length > 0) {
+          console.log(c.dim(`    ${result.warnings.length} warning(s) — run \`aos brief validate ${briefPath}\` for details.`));
+        }
+      });
     }
   }
 

package/src/index.ts

@@ -16,6 +16,7 @@ import { createCommand } from "./commands/create";
 import { validateCommand } from "./commands/validate";
 import { listCommand } from "./commands/list";
 import { replayCommand } from "./commands/replay";
+import { briefCommand } from "./commands/brief";
 import { c, parseArgs } from "./colors";
 import { getCliVersion } from "./utils";
 
@@ -35,6 +36,7 @@ ${c.bold("COMMANDS")}
   ${c.cyan("create")} profile <name>          Scaffold a new profile
   ${c.cyan("create")} domain <name>           Scaffold a new domain
   ${c.cyan("create")} skill <name>            Scaffold a new skill definition
+  ${c.cyan("brief")} <sub>                    Work with brief files (template/validate/save)
   ${c.cyan("replay")} <transcript.jsonl>       Replay a deliberation transcript
   ${c.cyan("validate")}                       Validate all agents, profiles, domains, and skills
   ${c.cyan("list")}                           List all agents, profiles, domains, and skills
@@ -87,6 +89,9 @@ async function main(): Promise<void> {
     case "create":
       await createCommand(parsed);
       break;
+    case "brief":
+      await briefCommand(parsed);
+      break;
     case "replay":
       await replayCommand(parsed);
       break;