all-hands-cli 0.1.0

package/.allhands/harness/src/tui/status-pane.ts

@@ -0,0 +1,434 @@
+/**
+ * Status Pane - Right area showing spec info, active agents, and log stream
+ *
+ * Layout:
+ * ┌─ Status ─────────────────────┐
+ * │ Branch: feature/my-branch    │
+ * │ Base: main                   │
+ * │                              │
+ * │ ┌──────────────────────────┐ │  <- Selectable spec box (full width)
+ * │ │ ▸ my-feature-spec        │ │
+ * │ └──────────────────────────┘ │
+ * │ ┌──────────────────────────┐ │  <- Selectable alignment box (if exists)
+ * │ │ ▸ Alignment Doc          │ │
+ * │ └──────────────────────────┘ │
+ * │ ┌──────────────────────────┐ │  <- Selectable e2e box (if exists)
+ * │ │ ▸ E2E Test Plan          │ │
+ * │ └──────────────────────────┘ │
+ * │                              │
+ * │ ── Active Agents ────────────│
+ * │ ┌──────────────────────────┐ │  <- Selectable agent box
+ * │ │ coordinator      ● #01   │ │
+ * │ └──────────────────────────┘ │
+ * │                              │
+ * │ ── Recent Activity ──────────│
+ * │ [12:34] Agent spawned        │
+ * └──────────────────────────────┘
+ *
+ * Selection:
+ * - j/k navigates through docs + agents
+ * - Enter/Space on doc opens file viewer
+ * - x on agent deletes it
+ */
+
+import blessed from 'blessed';
+
+export interface AgentInfo {
+  name: string;
+  agentType: string;
+  promptNumber?: string;
+  isRunning: boolean;
+}
+
+export interface FileStates {
+  spec: boolean;
+  alignment: boolean;
+  e2eTestPlan: boolean;
+}
+
+export interface StatusPaneOptions {
+  onViewSpec?: () => void;
+  onViewAlignment?: () => void;
+  onViewE2ETestPlan?: () => void;
+  onDeleteAgent?: (agentName: string) => void;
+}
+
+export interface StatusPaneData {
+  spec?: string;
+  branch?: string;
+  agents: AgentInfo[];
+  logEntries?: string[];
+  fileStates?: FileStates;
+  options?: StatusPaneOptions;
+}
+
+/**
+ * Item types for selection tracking
+ */
+export type SelectableItemType = 'spec' | 'alignment' | 'e2e' | 'agent';
+
+export interface SelectableItem {
+  type: SelectableItemType;
+  agentName?: string; // Only for agent type
+}
+
+const HEADER_HEIGHT = 3;
+
+/**
+ * Calculate the list of selectable items based on current state
+ */
+export function getSelectableItems(
+  spec?: string,
+  fileStates?: FileStates,
+  agents: AgentInfo[] = []
+): SelectableItem[] {
+  const items: SelectableItem[] = [];
+
+  // Document items (only if they exist/are viewable)
+  if (spec) {
+    items.push({ type: 'spec' });
+  }
+  if (spec && fileStates?.alignment) {
+    items.push({ type: 'alignment' });
+  }
+  if (spec && fileStates?.e2eTestPlan) {
+    items.push({ type: 'e2e' });
+  }
+
+  // Agent items
+  for (const agent of agents) {
+    items.push({ type: 'agent', agentName: agent.name });
+  }
+
+  return items;
+}
+
+export function createStatusPane(
+  screen: blessed.Widgets.Screen,
+  agents: AgentInfo[],
+  selectedIndex?: number,
+  spec?: string,
+  branch?: string,
+  baseBranch?: string,
+  logEntries: string[] = [],
+  fileStates?: FileStates,
+  options?: StatusPaneOptions
+): blessed.Widgets.BoxElement {
+  const pane = blessed.box({
+    parent: screen,
+    top: HEADER_HEIGHT,
+    left: '50%+12',
+    width: '50%-12',
+    height: `100%-${HEADER_HEIGHT}`,
+    border: {
+      type: 'line',
+    },
+    label: ' Status ',
+    tags: true,
+    style: {
+      border: {
+        fg: '#4A34C5',
+      },
+    },
+  });
+
+  // Get the inner width for full-width boxes
+  const paneWidth = typeof pane.width === 'number' ? pane.width : 40;
+  const innerWidth = paneWidth - 4; // Account for pane borders and padding
+
+  let currentY = 0;
+
+  // Build selectable items list to track what index corresponds to what
+  const selectableItems = getSelectableItems(spec, fileStates, agents);
+  let currentSelectableIndex = 0;
+
+  // Branch line and base branch on separate lines for clarity
+  if (branch || baseBranch) {
+    if (branch) {
+      blessed.text({
+        parent: pane,
+        top: currentY,
+        left: 1,
+        content: `{#818cf8-fg}Branch:{/#818cf8-fg} {#c7d2fe-fg}${truncate(branch, 24)}{/#c7d2fe-fg}`,
+        tags: true,
+      });
+      currentY += 1;
+    }
+    if (baseBranch) {
+      blessed.text({
+        parent: pane,
+        top: currentY,
+        left: 1,
+        content: `{#5c6370-fg}Base: ${truncate(baseBranch, 26)}{/#5c6370-fg}`,
+        tags: true,
+      });
+      currentY += 1;
+    }
+  }
+
+  currentY += 1; // spacing before document links
+
+  // Document boxes section - full width, selectable
+  const DOC_BOX_HEIGHT = 3;
+
+  // Spec box - ALWAYS shows when spec is selected
+  if (spec) {
+    const isSelected = selectedIndex === currentSelectableIndex;
+    const specBox = blessed.box({
+      parent: pane,
+      top: currentY,
+      left: 1,
+      width: innerWidth,
+      height: DOC_BOX_HEIGHT,
+      border: { type: 'line' },
+      tags: true,
+      mouse: true,
+      style: {
+        border: { fg: isSelected ? '#a78bfa' : '#4A34C5' },
+        hover: { border: { fg: '#a78bfa' } },
+      },
+    });
+    const specLabel = isSelected
+      ? `{#a78bfa-fg}{bold}▸{/bold}{/#a78bfa-fg} {#e0e7ff-fg}{bold}${truncate(spec, innerWidth - 6)}{/bold}{/#e0e7ff-fg}`
+      : `{#a78bfa-fg}▸{/#a78bfa-fg} {#e0e7ff-fg}${truncate(spec, innerWidth - 6)}{/#e0e7ff-fg}`;
+    blessed.text({
+      parent: specBox,
+      top: 0,
+      left: 1,
+      content: specLabel,
+      tags: true,
+    });
+    specBox.on('click', () => options?.onViewSpec?.());
+    currentY += DOC_BOX_HEIGHT;
+    currentSelectableIndex++;
+  } else {
+    blessed.text({
+      parent: pane,
+      top: currentY,
+      left: 1,
+      content: '{#f59e0b-fg}No spec selected{/#f59e0b-fg}',
+      tags: true,
+    });
+    currentY += 1;
+  }
+
+  // Alignment Doc box (only if file exists)
+  if (spec && fileStates?.alignment) {
+    const isSelected = selectedIndex === currentSelectableIndex;
+    const alignBox = blessed.box({
+      parent: pane,
+      top: currentY,
+      left: 1,
+      width: innerWidth,
+      height: DOC_BOX_HEIGHT,
+      border: { type: 'line' },
+      tags: true,
+      mouse: true,
+      style: {
+        border: { fg: isSelected ? '#a78bfa' : '#4A34C5' },
+        hover: { border: { fg: '#a78bfa' } },
+      },
+    });
+    const alignLabel = isSelected
+      ? '{#a78bfa-fg}{bold}▸{/bold}{/#a78bfa-fg} {#e0e7ff-fg}{bold}Alignment Doc{/bold}{/#e0e7ff-fg}'
+      : '{#a78bfa-fg}▸{/#a78bfa-fg} {#e0e7ff-fg}Alignment Doc{/#e0e7ff-fg}';
+    blessed.text({
+      parent: alignBox,
+      top: 0,
+      left: 1,
+      content: alignLabel,
+      tags: true,
+    });
+    alignBox.on('click', () => options?.onViewAlignment?.());
+    currentY += DOC_BOX_HEIGHT;
+    currentSelectableIndex++;
+  }
+
+  // E2E Test Plan box (only if file exists)
+  if (spec && fileStates?.e2eTestPlan) {
+    const isSelected = selectedIndex === currentSelectableIndex;
+    const e2eBox = blessed.box({
+      parent: pane,
+      top: currentY,
+      left: 1,
+      width: innerWidth,
+      height: DOC_BOX_HEIGHT,
+      border: { type: 'line' },
+      tags: true,
+      mouse: true,
+      style: {
+        border: { fg: isSelected ? '#a78bfa' : '#4A34C5' },
+        hover: { border: { fg: '#a78bfa' } },
+      },
+    });
+    const e2eLabel = isSelected
+      ? '{#a78bfa-fg}{bold}▸{/bold}{/#a78bfa-fg} {#e0e7ff-fg}{bold}E2E Test Plan{/bold}{/#e0e7ff-fg}'
+      : '{#a78bfa-fg}▸{/#a78bfa-fg} {#e0e7ff-fg}E2E Test Plan{/#e0e7ff-fg}';
+    blessed.text({
+      parent: e2eBox,
+      top: 0,
+      left: 1,
+      content: e2eLabel,
+      tags: true,
+    });
+    e2eBox.on('click', () => options?.onViewE2ETestPlan?.());
+    currentY += DOC_BOX_HEIGHT;
+    currentSelectableIndex++;
+  }
+
+  currentY += 1;
+
+  // Separator
+  blessed.text({
+    parent: pane,
+    top: currentY,
+    left: 1,
+    content: '{#6366f1-fg}━━ Active Agents ━━{/#6366f1-fg}',
+    tags: true,
+  });
+  currentY += 1;
+
+  // Agent list (vertical, full width, selectable)
+  if (agents.length === 0) {
+    blessed.text({
+      parent: pane,
+      top: currentY,
+      left: 1,
+      content: '{239-fg}No active agents{/239-fg}',
+      tags: true,
+    });
+    currentY += 2;
+  } else {
+    const AGENT_BOX_HEIGHT = 3;
+
+    agents.forEach((agent, index) => {
+      const isSelected = selectedIndex === currentSelectableIndex;
+      const boxStyle = isSelected
+        ? { border: { fg: '#a78bfa' }, fg: 'white' }
+        : { border: { fg: '#3a3f5c' }, fg: 'white' };
+
+      const agentBox = blessed.box({
+        parent: pane,
+        top: currentY,
+        left: 1,
+        width: innerWidth,
+        height: AGENT_BOX_HEIGHT,
+        border: { type: 'line' },
+        tags: true,
+        mouse: true,
+        style: boxStyle,
+      });
+
+      // Agent name on the left, status indicator on the right
+      const displayName = truncate(agent.name, innerWidth - 12);
+      const nameStyle = isSelected ? '{bold}' : '';
+      const nameEndStyle = isSelected ? '{/bold}' : '';
+      blessed.text({
+        parent: agentBox,
+        top: 0,
+        left: 0,
+        content: `${nameStyle}${displayName}${nameEndStyle}`,
+        tags: true,
+      });
+
+      const statusLine = formatAgentStatus(agent);
+      blessed.text({
+        parent: agentBox,
+        top: 0,
+        right: 1,
+        content: statusLine,
+        tags: true,
+      });
+
+      // Click to select (could expand to show details)
+      agentBox.on('click', () => {
+        // For now, clicking just selects - x key will delete
+      });
+
+      currentY += AGENT_BOX_HEIGHT;
+      currentSelectableIndex++;
+    });
+
+    currentY += 1;
+  }
+
+  // Log stream section - calculate available space
+  // Pane inner height = pane height - 2 (borders) - 1 (help text at bottom)
+  const paneHeight = typeof pane.height === 'number' ? pane.height : 30;
+  const availableForLogs = paneHeight - 2 - 1 - currentY - 1; // -1 for "Recent Activity" header
+
+  // Only show logs section if there's space
+  if (availableForLogs > 1) {
+    blessed.text({
+      parent: pane,
+      top: currentY,
+      left: 1,
+      content: '{#6366f1-fg}━━ Recent Activity ━━{/#6366f1-fg}',
+      tags: true,
+    });
+    currentY += 1;
+
+    // Show as many log entries as will fit (newest first)
+    const maxLogLines = Math.max(0, availableForLogs - 1); // -1 for header already added
+    const recentLogs = logEntries.slice(-maxLogLines).reverse();
+
+    if (recentLogs.length === 0) {
+      blessed.text({
+        parent: pane,
+        top: currentY,
+        left: 1,
+        content: '{#5c6370-fg}No recent activity{/#5c6370-fg}',
+        tags: true,
+      });
+    } else {
+      recentLogs.forEach((entry, i) => {
+        // Truncate long entries
+        const truncatedEntry = entry.length > 35 ? entry.substring(0, 32) + '...' : entry;
+        blessed.text({
+          parent: pane,
+          top: currentY + i,
+          left: 1,
+          content: `{#8b92a8-fg}${truncatedEntry}{/#8b92a8-fg}`,
+          tags: true,
+        });
+      });
+    }
+  }
+
+  // Help text at bottom - show context-sensitive hint
+  const selectedItem = selectableItems[selectedIndex ?? -1];
+  let helpText = '{#5c6370-fg}[v] Full Log{/#5c6370-fg}';
+  if (selectedItem?.type === 'agent') {
+    helpText = '{#5c6370-fg}[x] Delete | [v] Log{/#5c6370-fg}';
+  } else if (selectedItem?.type === 'spec' || selectedItem?.type === 'alignment' || selectedItem?.type === 'e2e') {
+    helpText = '{#5c6370-fg}[Enter] View | [v] Log{/#5c6370-fg}';
+  }
+
+  blessed.text({
+    parent: pane,
+    bottom: 0,
+    left: 1,
+    content: helpText,
+    tags: true,
+  });
+
+  return pane;
+}
+
+function formatAgentStatus(agent: AgentInfo): string {
+  const indicator = agent.isRunning
+    ? '{green-fg}●{/green-fg}'
+    : '{red-fg}●{/red-fg}';
+
+  let info = indicator;
+  if (agent.promptNumber) {
+    info += ` #${agent.promptNumber}`;
+  }
+
+  return info;
+}
+
+function truncate(str: string, maxLen: number): string {
+  if (str.length <= maxLen) return str;
+  return str.substring(0, maxLen - 2) + '..';
+}

package/.allhands/harness/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "./dist",
+    "rootDir": ".",
+    "declaration": true,
+    "resolveJsonModule": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["src/**/*", "commands/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/.allhands/harness/vitest.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: false,
+    environment: 'node',
+    include: ['src/**/__tests__/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+    },
+  },
+});

package/.allhands/pillars.md

@@ -0,0 +1,33 @@
+## Functional Pillars of This Harness
+
+These are the load-bearing approaches that realize the First Principles in `principles.md`. Principles define **why**; pillars define **what** the harness structurally delivers.
+
+### 1. Prompt-Driven Execution Loop
+Prompt files are atomic units of work executed in tracked loops. Planned prompts deliver scoped tasks from the planner; emergent prompts are created by the emergent planner as non-overlapping hypotheses for executors to implement. Both follow the same execution primitive — the distinction is origin (planned vs emergent-generated), not execution path. Alignment documents track summaries and decisions across iterations.
+
+### 2. Knowledge Compounding
+Everything feeds forward. Branch-scoped ephemeral artifacts — pain points, decisions, learnings — distill into persistent knowledge: solutions, memories, and domain documentation. Future initiatives benefit from all past work through structured retrieval at key planning and discovery points.
+
+### 3. Approach Discoverability
+Unified tooling makes knowledge and implementation patterns accessible. Embedded documentation search, semantic code analysis, and sub-agent delegation for scoped retrieval — both codebase-specific and external research. Reduces the cost of finding relevant context to near-zero.
+
+### 4. Skills as Domain Practices
+Codebase-specific domain knowledge tuned from execution experience. Not documentation but operational guidance — how to use tools, what patterns to follow, what to avoid. Explicitly accessible per domain. Refined through compounding cycles so future agents inherit hard-won learnings.
+
+### 5. Context-Abstracted Tooling
+CLI commands, MCP tools, and context handlers that process externally, withholding raw data from agent context windows. Oracle delegation for LLM-enabled deterministic tasks. Deterministic tools applied stochastically by agents via flow-suggested use cases.
+
+### 6. Progressive Flow Architecture
+Instruction sets disclosed progressively as agents need them. Flows reference flows, enabling diverse path-finding through predetermined decision trees. Agents work within scoped guidelines toward specific goals without seeing the full system at once.
+
+### 7. Schema-Driven File Contracts
+Single source of configuration for how workflow-critical files are structured. Validated on write, eliminating programmatic dependencies. Stochastic agents write to deterministic contracts across ephemeral and persisted files — one schema definition governs interpretation and authoring system-wide.
+
+### 8. Initiative-Based Orchestration
+Harness-managed workflows for milestone development, investigation, optimization, refactoring, documentation, and triage — unified under a single entry point (New Initiative). **Workflow domain configs** (`.allhands/workflows/`) encode per-domain knowledge consumed by shared flows: ideation scoping adapts interview depth, spec planning calibrates research and jury gating, and the emergent planner caps tangential hypotheses — all driven by a single config file per domain rather than separate hardcoded flows. **Initiative steering** provides mid-execution deep replanning with domain-aware scope adjustment, pausing the prompt loop while the engineer redirects goals, modifies prompts, and amends alignment. The **two-phase emergence model** (core consolidation → tangential exploration) focuses emergent work on core goals first, then broadens to adjacent improvements once the initiative's foundation is solid. TMUX orchestration, lifecycle management, observability (tracing), TUI capabilities, and coding agent hook injection for maximum engineer visibility and control. Templated message injection provides workflow-state-specific context to dependent agents.
+
+### 9. Disposable Software & Variant Exploration
+Open decisions become emergent implementations behind feature flags. The emergent planner creates batches of non-overlapping hypotheses as prompt files; executors implement them as disposable variants. Multiple solutions to the same problem enable quality engineering: engineers choose conventions, kill weak approaches, or refine into A/B tests for production end-user validation. The coordinator filters unwanted emergent work from PRs via existing refinement analysis. Cheap software development with good guardrails and expectation setting during ideation.
+
+### 10. Agentic Validation Tooling
+Programmatic validation that decouples engineers from the implementation loop. Deterministic tooling (tests, migrations, type checks) provides quantitative pass/fail gating for CI/CD and regression prevention. Stochastic tooling (UI automation, log analysis, performance profiling) provides qualitative assessment via agent judgment. Both modes are first-class, discoverable, and compound through execution learnings — enabling engineers to focus on ideation and quality control while agents validate implementation against prepared expectations.

package/.allhands/principles.md

@@ -0,0 +1,88 @@
+## First Principles Driving This Architecture
+
+### 1. Context is Precious
+**Problem**: Agents degrade with large context windows. Too much information = worse decisions.
+
+**Solution**:
+- Isolated units of work (prompt files) with minimal scope (3-5 tasks)
+- Shared information is concise and intentional (alignment docs, not full history)
+- Progressive disclosure - agents only see what they need, when they need it
+- Loop architecture naturally bounds context per execution
+
+### 2. Prompt Files as Units of Work
+**Why this structure**:
+- **Language of implementation**: Prompts ARE the tasks, not descriptions of tasks
+- **Tokens of coordination**: Other agents (planners, reviewers) speak in prompt files
+- **Iterative refinement**: Same prompt can be re-run with accumulated learnings
+- **Record of decisions**: Completed prompts document what was decided, not just done
+- **Novely Emerges**: Prompt tasking is optimal for agent hypothesis and implementation to validate
+
+### 3. Ideation First
+**Why front-load exploration**:
+- Prevents low-level decision fatigue during implementation
+- Discovers limitations early (before they block progress)
+- Allows engineers to go as deep as desired during ideation
+- Compounds on roadmap dependencies regardless of implementation order
+- Consolidates user expectations, desires, concerns upfront
+
+### 4. Quality Engineering (Not Quantity Engineering)
+**The shift**:
+- With cheap software, the question isn't "can we build it?" but "which variant is best?"
+- Plan agents turn open questions into **variant prompt files with validation requirements**
+- Engineering effort goes to **quality control of variants**, not implementation
+- Decision points: consolidate to convention, kill, or ship for A/B testing
+
+### 5. Frontier Models are Capable
+**What agents minimally need**:
+- Control flows as core direction (not micromanagement)
+- Critical motivations for their allocated responsibility
+- Knowledge of how/when to call harness tooling
+- They turn **why** and **what** into **how**
+
+### 6. Agentic Validation Tooling
+**Why tight validation**:
+- Programmatic validation > human supervision
+- Strict acceptance criteria make prompt work verifiable
+- Types of validation: tests, UI automation, profiling, script results
+- Makes engineering supervision redundant for routine checks
+- Validation tooling is infrastructure - assess gaps before planning, create via specs
+- **Two dimensions**: Every validation domain has a stochastic dimension (agent-driven exploratory testing using model intuition) and a deterministic dimension (binary pass/fail gating for CI/CD). Both are first-class.
+- **Crystallization lifecycle**: Stochastic exploration discovers patterns → patterns crystallize into deterministic checks → deterministic checks entrench in CI/CD → stochastic exploration shifts to the frontier. This is how validation compounds.
+- **Suite existence threshold**: A validation suite must have a meaningful stochastic dimension to justify existing. Deterministic-only tools (type checking, linting, formatting) are test commands referenced directly in acceptance criteria and CI/CD — they are not suites.
+
+### 7. Knowledge Compounding
+**Everything feeds forward**:
+- Decisions, pivots, limitations, disagreements
+- Realizations, best practices, preferences
+- The harness implementation itself improves with use
+- Future tasks benefit from all past work
+
+
+---
+
+## Core Philosophy: This Harness Enables The Model-First Company 
+
+The harness exists to facilitate a fundamental shift in how software organizations operate:
+
+### 1. Software is Cheap, Expertise is Valuable
+- AI has made code generation nearly free
+- The bottleneck is now **ideation** and **quality judgment**
+- The harness optimizes for capturing human expertise and translating it to agent-executable work
+
+### 2. Product is Centralized
+- Single source of truth: codebase + connected services + compounded validation
+- Anyone can "talk to the product" through the harness
+- Removes knowledge silos between teams
+
+### 3. New Organizational Roles
+| Traditional | Model-First |
+|------------|-------------|
+| Developers write code | **Product Stakeholders** test, ideate, design |
+| Managers coordinate | **Product Engineers** scope, orchestrate, release |
+| Hierarchies gatekeep | Hierarchies become redundant |
+
+### 4. Ship Fast, Hide Uncertainty
+- Push frequently to main
+- Feature flags hide incomplete work
+- Convention is safe; experimentation is cheap
+

package/.allhands/schemas/alignment.yaml

@@ -0,0 +1,51 @@
+# Alignment Doc Schema
+# Single source of truth for alignment document structure
+
+frontmatter:
+  spec_name:
+    type: string
+    required: true
+    description: "Name of the spec this alignment doc serves"
+
+  spec_path:
+    type: string
+    required: true
+    description: "Path to the spec file"
+
+  validation_gaps_accepted:
+    type: array
+    items: string
+    required: false
+    description: "Validation gaps engineer accepted (e.g., 'No E2E - manual UI testing')"
+
+  core_consolidation:
+    type: enum
+    required: false
+    values: [pending, complete]
+    default: pending
+    description: "Emergence phase tracking — pending for core goal consolidation, complete enables tangential exploration"
+
+body:
+  description: "Markdown document with header and append sections"
+  sections:
+    - name: "Overview"
+      required: true
+      description: "High-level overview of spec motivations and goals"
+
+    - name: "Hard User Requirements"
+      required: true
+      description: "Concise, immutable user requirements. Guidelines for emergent work."
+
+    - name: "Engineer Decisions"
+      required: false
+      description: "ONLY deviations - do NOT record when engineer accepts recommendations. Captures: recommended → chosen instead → reasoning."
+
+    - name: "Prompt Summaries"
+      required: false
+      appended_by: "executor"
+      description: "Appended after prompt execution, not during planning."
+      format: |
+        ### ##-prompt-file-name.prompt.md
+        **Decision**: The most important decisions that were made during implementation
+        **Files**: List of key files of interest from the commit
+        **Summary**: Very brief explanation of implementation

package/.allhands/schemas/documentation.yaml

@@ -0,0 +1,10 @@
+# Documentation Doc Schema
+# Single source of truth for documentation document structure
+
+frontmatter:
+  description:
+    type: string
+    required: true
+    description: "1-2 sentence summary enabling semantic search discovery / understanding of this document's purpose"
+
+body: "No strict schema - just ensure code references are done via format: [ref:<file_path>:<symbol_name>] or [ref:<file_path>] (if no symbol is possible to include for the reference). Ensure that file references are used INSTEAD of code snippets."