@manhd_d/ai-harness 0.7.0 → 0.8.0

package/capabilities/product/templates/mvp.md

@@ -0,0 +1,25 @@
+# MVP scope
+
+Status: draft / pending review
+Owner: TODO
+Sources and revisions: TODO
+Scope / related requirement and decision IDs: TODO
+Last verified against code: TODO (or not applicable with reason)
+
+## User and outcome
+Target actor, problem, value-bearing end-to-end journey and validation evidence.
+## Scope cuts
+| Capability | In / out | Value / dependency | Requirement / AC | Decision source |
+| --- | --- | --- | --- | --- |
+| TODO | TODO | TODO | TODO | TODO |
+## Minimum viable quality
+Authorization, data integrity, failure recovery and relevant NFRs that cannot be deferred.
+## Acceptance and learning
+Observable journey completion, success signals, measurement owner, known baseline/target or unknown.
+## Open decisions
+Options/trade-offs, recommended cut with evidence and actual owner answer; unanswered choices remain pending.
+
+
+## Review and handoff
+Record actual owner decisions, unresolved consequential questions, verification performed/skipped,
+next role, source/output paths and affected OpenSpec change. Draft text is not an accepted decision.

package/capabilities/product/templates/outcomes.md

@@ -0,0 +1,23 @@
+# Product outcomes
+
+Status: draft / pending review
+Owner: TODO
+Sources and revisions: TODO
+Scope / related requirement and decision IDs: TODO
+Last verified against code: TODO (or not applicable with reason)
+
+## Value hypothesis
+User problem and expected benefit; link MVP/PRD instead of duplicating scope.
+## Measurement plan
+| Outcome / metric | Definition / source | Baseline | Proposed target / authority | Owner / period |
+| --- | --- | --- | --- | --- |
+| TODO | TODO | unknown | pending | TODO |
+## Experiment and guardrails
+Hypothesis, smallest experiment, cost/privacy limits, negative effects and decision checkpoint.
+## Evidence and next action
+Separate observed results from forecasts; propose continue/pivot/stop without self-approving scope changes.
+
+
+## Review and handoff
+Record actual owner decisions, unresolved consequential questions, verification performed/skipped,
+next role, source/output paths and affected OpenSpec change. Draft text is not an accepted decision.

package/capabilities/product/workflows/document-driven.md

@@ -11,3 +11,7 @@ Use when a project already supplies authorized BA/PO materials (Confluence, BRD,
 7. **Source changes:** compare actual source revisions and propose a reviewed requirements/code impact diff rather than overwriting user-owned artifacts.
 
 Canonical enterprise source stays in the enterprise system; consumer repo stores pointers, versioned derived docs and project-local engineering artifacts. RAG is optional permission-scoped retrieval, not a replacement for a system of record. The `aih` CLI does not ingest data or run agents.
+
+For new/material journeys, continue with `product-to-solution.md` after resolving the relevant scope.
+Use reviewed MVP/outcomes and optional Architecture/Delivery to assess solution/dependencies before
+OpenSpec implementation. Existing approved sources remain canonical; small clear changes stay compact.

package/capabilities/product/workflows/idea-driven.md

@@ -11,3 +11,7 @@ Use this when the developer starts with an idea, including a solo project. Produ
 7. **Changes:** when the idea changes, perform impact analysis and propose minimal document diffs; never silently overwrite approved requirements.
 
 Deliverables are **consumer-owned** `docs/discovery/`, `docs/product/` and `openspec/` files. For Confluence publishing, preserve URLs/page versions and request explicit write permission; the Harness CLI does not connect or publish to Confluence.
+
+For new/material journeys, continue with `product-to-solution.md` after resolving the relevant scope.
+Use reviewed MVP/outcomes and optional Architecture/Delivery to assess solution/dependencies before
+OpenSpec implementation. Existing approved sources remain canonical; small clear changes stay compact.

package/capabilities/product/workflows/product-to-solution.md

@@ -0,0 +1,15 @@
+# BA → PO → Solution → Delivery
+
+Use for a new product or material feature. For a small clear fix, use the Core compact path.
+1. BA preserves idea/approved document revisions, identifies users, business rules and contradictions;
+   load existing business-analysis/use-case/AC skills. Source/output register is authoritative.
+2. PO uses mvp-definition and product-outcomes to propose a complete journey, in/out scope, minimum
+   quality and success evidence. Resolve consequential unknowns with actual owner; no self-approval.
+3. Pass reviewed FR/US/AC/NFR and decision status to installed Architecture discovery-to-design.
+   If Architecture is not selected, Core spec uses the same constraints and records relevant choices.
+4. Pass accepted solution boundaries, AC, dependencies and actual estimates to optional Delivery planning;
+   absent Delivery, record a proportional task order in the OpenSpec change.
+5. UI/UX can iterate with SA/PO; adapters implement accepted technical decisions. Verify and review
+   against requirements/ADRs. Evidence and scope changes loop back to the owning role.
+6. Carry source revisions, IDs, output paths, decisions, unresolved questions, actual checks and next
+   owner in every handoff. A role label never creates a worker or approves a stakeholder decision.

package/cli/agents.js

@@ -0,0 +1,165 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { safe, stat, readJson, isObject, SLUG, SOURCE, HarnessError } from './files.js';
+
+export const AGENT_CONFIG = '.harness/agents.json';
+export const DEFAULT_AGENTS = 'config/agents.default.json';
+export const PRESETS = ['recommended', 'economy', 'custom'];
+export const REASONING = ['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra'];
+const ROLE = /^[a-z][a-z0-9-]*:[a-z][a-z0-9-]*$/;
+const text = value => typeof value === 'string' && value.trim() === value && value.length > 0
+  && value.length <= 256 && !/[\x00-\x1f\x7f]/.test(value);
+const requireThat = (condition, label) => { if (!condition) throw new HarnessError('Invalid agent configuration: ' + label); };
+function fields(value, allowed, required, label) {
+  requireThat(isObject(value) && Object.keys(value).every(key => allowed.includes(key))
+    && required.every(key => Object.hasOwn(value, key)), label + ' fields');
+}
+function reference(value, label) {
+  requireThat(text(value), label + ' must be nonempty single-line text (max 256 characters)');
+  if (value.startsWith('@')) requireThat(SLUG.test(value.slice(1)), label + ' alias syntax');
+  else requireThat(!/\s/.test(value), label + ' model ID must not contain whitespace');
+}
+function provider(value, label) { requireThat(typeof value === 'string' && SLUG.test(value), label + ' provider ID'); }
+function reasoning(value, label) { requireThat(REASONING.includes(value), label + ' reasoning level'); }
+
+export function resolveModel(config, referenceValue, visited = []) {
+  if (!referenceValue.startsWith('@')) return { model: referenceValue, provider: config.provider };
+  const alias = referenceValue.slice(1);
+  requireThat(Object.hasOwn(config.models, alias), 'unknown alias @' + alias);
+  requireThat(!visited.includes(alias), 'cyclic alias @' + alias);
+  const descriptor = config.models[alias];
+  const next = typeof descriptor === 'string' ? descriptor : descriptor.model;
+  const resolved = resolveModel(config, next, [...visited, alias]);
+  return { ...resolved, provider: typeof descriptor === 'object' ? descriptor.provider ?? resolved.provider : resolved.provider };
+}
+
+export function validateAgentConfig(config) {
+  fields(config, ['schema_version', 'provider', 'defaultModel', 'defaultReasoning', 'models', 'agents', 'execution', 'hosts'],
+    ['schema_version', 'provider', 'defaultModel', 'defaultReasoning', 'models', 'agents', 'execution'], 'root');
+  requireThat(config.schema_version === 1, 'unsupported schema_version');
+  provider(config.provider, 'default'); reference(config.defaultModel, 'defaultModel');
+  reasoning(config.defaultReasoning, 'default');
+  requireThat(isObject(config.models) && Object.keys(config.models).length <= 64, 'models map (max 64 aliases)');
+  for (const [alias, descriptor] of Object.entries(config.models)) {
+    requireThat(SLUG.test(alias), 'alias ID');
+    if (typeof descriptor === 'string') reference(descriptor, 'models.' + alias);
+    else {
+      fields(descriptor, ['model', 'provider'], ['model'], 'models.' + alias);
+      reference(descriptor.model, 'models.' + alias);
+      if (descriptor.provider !== undefined) provider(descriptor.provider, 'models.' + alias);
+    }
+  }
+  resolveModel(config, config.defaultModel);
+  for (const alias of Object.keys(config.models)) resolveModel(config, '@' + alias);
+  requireThat(isObject(config.agents) && Object.keys(config.agents).length <= 128, 'agents map (max 128 roles)');
+  for (const [id, agent] of Object.entries(config.agents)) {
+    requireThat(ROLE.test(id), 'role ID must use namespace:role');
+    fields(agent, ['model', 'provider', 'reasoning', 'enabled'], [], id);
+    if (agent.model !== undefined) { reference(agent.model, id); resolveModel(config, agent.model); }
+    if (agent.provider !== undefined) provider(agent.provider, id);
+    if (agent.reasoning !== undefined) reasoning(agent.reasoning, id);
+    requireThat(agent.enabled === undefined || typeof agent.enabled === 'boolean', id + ' enabled');
+  }
+  const execution = config.execution;
+  fields(execution, ['mode', 'maxConcurrentAgents', 'maxRounds', 'autoEscalateToPremium'],
+    ['mode', 'maxConcurrentAgents', 'maxRounds', 'autoEscalateToPremium'], 'execution');
+  requireThat(['single-agent', 'hybrid', 'multi-agent'].includes(execution.mode), 'execution mode');
+  requireThat(Number.isSafeInteger(execution.maxConcurrentAgents) && execution.maxConcurrentAgents >= 1
+    && execution.maxConcurrentAgents <= 32, 'maxConcurrentAgents must be an integer from 1 to 32');
+  requireThat(execution.mode !== 'single-agent' || execution.maxConcurrentAgents === 1, 'single-agent requires maxConcurrentAgents=1');
+  requireThat(Number.isSafeInteger(execution.maxRounds) && execution.maxRounds >= 1 && execution.maxRounds <= 20,
+    'maxRounds must be an integer from 1 to 20');
+  requireThat(execution.autoEscalateToPremium === false, 'autoEscalateToPremium must be false; select premium explicitly');
+  const hosts = config.hosts ?? {};
+  requireThat(isObject(hosts) && Object.keys(hosts).length <= 16, 'hosts map (max 16 profiles)');
+  for (const [id, profile] of Object.entries(hosts)) {
+    requireThat(SLUG.test(id), 'host ID'); fields(profile, ['models', 'reasoning'], [], 'host ' + id);
+    for (const key of ['models', 'reasoning']) {
+      const map = profile[key] ?? {};
+      requireThat(isObject(map) && Object.keys(map).length <= 128, 'host ' + id + ' ' + key + ' map');
+      for (const [from, to] of Object.entries(map)) {
+        requireThat(key === 'models' ? text(from) && from.includes('/') : REASONING.includes(from), 'host mapping key');
+        requireThat(text(to) && !to.startsWith('@'), 'host mapping target must be explicit native text');
+      }
+    }
+  }
+  return config;
+}
+
+function readConfiguration(root, relative) {
+  const filename = safe(root, relative), info = stat(filename);
+  if (!info) return null;
+  requireThat(info.isFile() && info.size <= 1024 * 1024, relative + ' must be a file up to 1 MiB');
+  let config;
+  try { config = JSON.parse(fs.readFileSync(filename, 'utf8')); }
+  catch { throw new HarnessError('Invalid JSON in ' + relative); }
+  return validateAgentConfig(config);
+}
+export function loadAgentConfig(root) { return readConfiguration(root, AGENT_CONFIG); }
+
+export function agentDefaults(source = SOURCE, preset = 'recommended') {
+  requireThat(PRESETS.includes(preset), 'unknown preset; use recommended, economy or custom');
+  // Older alternate bundles remain usable; the packaged CLI supplies the new canonical seed.
+  const config = structuredClone(readConfiguration(source, DEFAULT_AGENTS) ?? readConfiguration(SOURCE, DEFAULT_AGENTS));
+  requireThat(config !== null, 'missing canonical default');
+  if (preset === 'economy') {
+    config.defaultModel = '@economy'; config.defaultReasoning = 'low';
+    config.execution.mode = 'single-agent'; config.execution.maxConcurrentAgents = 1;
+    for (const agent of Object.values(config.agents)) { agent.model = '@economy'; agent.reasoning = 'low'; }
+  }
+  return validateAgentConfig(config);
+}
+
+export function registeredRoles(source, capabilities = []) {
+  const roles = {};
+  const folder = path.dirname(safe(source, 'core/agents/.role-index'));
+  for (const name of fs.readdirSync(folder).filter(name => name.endsWith('.md')).sort()) {
+    roles['core:' + name.slice(0, -3)] = 'core/agents/' + name;
+  }
+  for (const id of capabilities) {
+    const metadata = readJson(safe(source, `capabilities/${id}/capability.json`));
+    for (const file of metadata.agents ?? []) {
+      const role = id + ':' + path.basename(file, '.md');
+      roles[role] = `capabilities/${id}/${file}`;
+    }
+  }
+  return roles;
+}
+
+export function resolveAgent(config, id) {
+  const agent = Object.hasOwn(config.agents, id) ? config.agents[id] : {};
+  const resolved = resolveModel(config, agent.model ?? config.defaultModel);
+  return { id, ...resolved, provider: agent.provider ?? resolved.provider,
+    reasoning: agent.reasoning ?? config.defaultReasoning, enabled: agent.enabled !== false,
+    source: Object.hasOwn(config.agents, id) ? 'role' : 'project-default' };
+}
+
+export function agentPlan(root, host) {
+  if (host !== undefined) requireThat(typeof host === 'string' && SLUG.test(host), 'host ID');
+  const config = loadAgentConfig(root);
+  const presets = [{ label: 'A', value: 'recommended', description: 'Sol, hybrid, at most two concurrent agents when supported.' },
+    { label: 'B', value: 'economy', description: 'Economy model, single-agent roles.' },
+    { label: 'C', value: 'custom', description: 'Edit provider/model/reasoning and role/host mappings explicitly.' }];
+  const note = 'Read-only declaration. No provider/model probing, native config writes, agent spawning, concurrency/token enforcement or usage tracking. Verify model access, effort and delegation in the actual host before execution.';
+  if (!config) return { status: 'not-configured', configured: false, presets, roles: [], note };
+  const lock = readJson(safe(root, '.harness/lock.json'));
+  const registry = registeredRoles(path.join(root, '.harness'), lock.capabilities ?? []);
+  const ids = [...new Set([...Object.keys(registry), ...Object.keys(config.agents)])].sort();
+  const profile = config.hosts?.[host] ?? {};
+  const roles = ids.map(id => {
+    const requested = resolveAgent(config, id);
+    const active = requested.enabled && Object.hasOwn(registry, id);
+    const mapping = profile.models?.[requested.provider + '/' + requested.model];
+    const incompatible = !mapping && ((host === 'claude-code' &&
+      (!['anthropic', 'bedrock', 'vertex'].includes(requested.provider) || requested.model.startsWith('gpt-'))) ||
+      (host === 'gemini-cli' && (!['google', 'vertex'].includes(requested.provider) || requested.model.startsWith('gpt-'))));
+    return { ...requested, active, contract: registry[id] ? '.harness/' + registry[id] : null,
+      host_model: mapping ?? requested.model, host_reasoning: profile.reasoning?.[requested.reasoning] ?? requested.reasoning,
+      mapping: mapping ? 'explicit-user-host-mapping' : 'requested',
+      availability: active && incompatible ? 'incompatible-provider' : 'unverified',
+      runtime_verified: false };
+  });
+  return { status: roles.some(role => role.active && role.availability === 'incompatible-provider') ? 'host-incompatible' : 'requires-host-verification',
+    configured: true, host: host ?? null, presets, execution: config.execution, roles,
+    missing_mappings: Object.keys(registry).filter(id => !Object.hasOwn(config.agents, id)), note };
+}

package/cli/environment.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { safe, stat, isObject, SLUG, HarnessError } from './files.js';
+import { agentPlan } from './agents.js';
 
 export const ENVIRONMENT = '.harness/environment.json';
 export const MACHINE = '.harness/machine.json';
@@ -119,7 +120,7 @@ export function environmentReport(root, env = process.env) {
     note: 'Presence/reference checks only. No commands executed; values and arguments are omitted. Never store credentials here.' };
 }
 
-export function setupPlan(root, adapters, env = process.env) {
+export function setupPlan(root, adapters, env = process.env, host) {
   const environment = environmentReport(root, env);
   const configuredTools = environment.entries.some(e => e.group === 'tools');
   const questions = [];
@@ -147,10 +148,22 @@ export function setupPlan(root, adapters, env = process.env) {
       { label: 'C', value: 'idea', description: 'Start from the user idea and clarify the scope.' }],
     recommendation: null, reason: 'The host must inspect existing local.md and sources before recommending.',
     allow_free_text: true
+  }, {
+    id: 'project-mode', question: 'What is the scope of the affected code?',
+    options: [{ label: 'A', value: 'maintain', description: 'Extend existing modules using their conventions and shared APIs.' },
+      { label: 'B', value: 'new', description: 'Start a new application with a minimal agreed adapter baseline.' },
+      { label: 'C', value: 'mixed', description: 'Add a new module while preserving repository-wide contracts.' }],
+    recommendation: null,
+    reason: 'Inspect the task, local.md and neighboring code; stack detection or environment configuration does not establish project mode. Skip if already known.',
+    allow_free_text: true
   });
   return { status: environment.problems.length ? 'blocked' : 'planned', environment, questions,
+    agent_configuration: agentPlan(root, host),
     next_steps: ['Read AGENTS.md, .harness/local.md and the installed project-setup workflow.',
+      'Apply installed Core project-conventions.md and relevant adapter conventions; establish mode per affected module even when no setup questions are suggested.',
+      'Inspect comparable code and search public shared APIs before creating files, dependencies or abstractions; record source paths and reuse/new-code rationale.',
       'Skip answered questions; ask at most 1–3 consequential questions with evidence-based recommendations.',
+      'Review agents.json provider/model/reasoning and preset choices; verify access/effort/delegation in the actual host before execution. No automatic premium fallback.',
       'Record shared decisions in local.md/environment.json; put only machine paths in ignored machine.json.',
       'Run aih doctor, then use the reviewed project commands through your AI host.'],
     note: 'Read-only host-facing suggestions, not an interactive terminal wizard or approval.' };

package/cli/harness.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import { emptyEnvironment, environmentReport } from './environment.js';
+import { AGENT_CONFIG, agentDefaults, loadAgentConfig } from './agents.js';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { loadAdapter } from './adapter-schema.js';
@@ -66,6 +67,7 @@ export function bundle(source, config) {
       files[dest] = fs.readFileSync(safe(source, `adapters/${a}/skills/${name}/SKILL.md`));
     }
   }
+  files['.harness/templates/agents.default.json'] = encode(agentDefaults(source));
   for (const c of capabilities) {
     const info = loadCapability(source, c);
     for (const name of info.skills) {
@@ -157,12 +159,15 @@ export function transaction(root, changes, writer = atomicWrite) {
   }
 }
 
-export function install(root, source, { command = 'init', adapters, capabilities, dryRun = false, allowMajor = false, writer } = {}) {
+export function install(root, source, { command = 'init', adapters, capabilities, agentPreset, dryRun = false, allowMajor = false, writer } = {}) {
   assertSeparate(root, source);
   return guard(root, () => {
     const hasLock = Boolean(stat(safe(root, LOCK)));
     if (command === 'update' && !hasLock) throw new HarnessError('Not installed; run init first');
     const old = hasLock ? loadLock(root) : null;
+    const existingAgents = loadAgentConfig(root);
+    if (agentPreset !== undefined && command !== 'init') throw new HarnessError('Agent preset is supported only by init');
+    if (agentPreset !== undefined && existingAgents) throw new HarnessError('agents.json is project-owned; edit it explicitly instead of applying an init preset');
     const config = projectConfig(root, adapters, capabilities, hasLock);
     const { files, lock, warnings } = bundle(source, config);
     if (old) {
@@ -186,10 +191,11 @@ export function install(root, source, { command = 'init', adapters, capabilities
     }
     if (old) for (const name of Object.keys(old.files)) if (!Object.hasOwn(files, name)) changes[name] = null;
     const seeds = {
+      [AGENT_CONFIG]: encode(agentDefaults(source, agentPreset ?? 'recommended')),
       [CONFIG]: encode(config),
       '.harness/environment.json': encode(emptyEnvironment()),
       'openspec/config.yaml': fs.readFileSync(safe(source, 'templates/openspec/config.yaml')),
-      '.harness/local.md': Buffer.from('# Project overrides\n\nRecord project facts and reviewed exceptions here. Never weaken security boundaries.\n'),
+      '.harness/local.md': Buffer.from('# Project overrides\n\nRecord project facts and reviewed exceptions here. Never weaken security boundaries.\n\n## Development conventions\nRecord scope/mode (new, maintain or mixed), authoritative source paths, module boundaries, reusable public APIs, naming/error/test conventions and configured checks. Link existing guides instead of duplicating them. Unknowns are not approved defaults; the AI host inspects evidence and asks only consequential questions.\n'),
     };
     for (const [name, data] of Object.entries(seeds)) if (!stat(safe(root, name))) changes[name] = data;
     // Project-owned ignore file: preserve all prior rules, place our anchored rule last.
@@ -210,6 +216,7 @@ export function install(root, source, { command = 'init', adapters, capabilities
 export function check(root) {
   const lock = loadLock(root), config = projectConfig(root, undefined, undefined, true);
   const problems = drift(root, lock);
+  loadAgentConfig(root); // Optional on legacy installs; validate user config without managing its bytes.
   if (JSON.stringify([...config.adapters].sort()) !== JSON.stringify([...lock.adapters].sort())) problems.push(`${CONFIG}: adapter selection changed; run update`);
   if (JSON.stringify([...(config.capabilities ?? [])].sort()) !== JSON.stringify([...(lock.capabilities ?? [])].sort())) problems.push(`${CONFIG}: capability selection changed; run update`);
   return { status: problems.length ? 'error' : 'ok', version: lock.version, problems };
@@ -237,20 +244,28 @@ export function newChange(root, name) {
   });
 }
 
-// Product drafts are project-owned and never added to the managed bundle.
-export function newDoc(root, name) {
+// Capability drafts are project-owned and never added to the managed bundle.
+export function newDoc(root, name, capability = 'product') {
   if (!SLUG.test(name)) throw new HarnessError('Document type must be a lowercase hyphenated slug');
+  if (!SLUG.test(capability)) throw new HarnessError('Capability must be a lowercase hyphenated slug');
   return guard(root, () => {
     if (check(root).status !== 'ok') throw new HarnessError('Fix installation drift before creating a document');
     const lock = loadLock(root);
-    if (!(lock.capabilities ?? []).includes('product')) throw new HarnessError('Product capability is not installed');
-    const sourceName = `.harness/capabilities/product/templates/${name}.md`;
-    if (!Object.hasOwn(lock.files, sourceName)) throw new HarnessError(`Unknown product document type: ${name}`);
-    const folder = ['idea', 'research'].includes(name) ? 'discovery' : 'product';
+    if (!(lock.capabilities ?? []).includes(capability)) {
+      throw new HarnessError(capability === 'product' ? 'Product capability is not installed' : `Capability is not installed: ${capability}`);
+    }
+    const sourceName = `.harness/capabilities/${capability}/templates/${name}.md`;
+    if (!Object.hasOwn(lock.files, `.harness/capabilities/${capability}/capability.json`)) {
+      throw new HarnessError(`Capability metadata is not locked: ${capability}`);
+    }
+    const declared = loadCapability(path.join(root, '.harness'), capability).templates;
+    if (!declared.includes(`templates/${name}.md`)) throw new HarnessError(`Unknown document type for ${capability}: ${name}`);
+    if (!Object.hasOwn(lock.files, sourceName)) throw new HarnessError(`Document template is not locked: ${capability}/${name}`);
+    const folder = capability === 'product' && ['idea', 'research'].includes(name) ? 'discovery' : capability;
     const outputName = `docs/${folder}/${name}.md`;
     if (stat(safe(root, outputName))) throw new HarnessError(`Document already exists: ${outputName}`);
     transaction(root, { [outputName]: fs.readFileSync(safe(root, sourceName)) });
-    return { status: 'ok', type: name, path: outputName,
+    return { status: 'ok', type: name, capability, path: outputName,
       note: 'Template only; populate from authorized evidence and obtain human approval.' };
   });
 }

package/cli/main.js

@@ -24,16 +24,19 @@ Usage: aih <command> [options]
   setup                Suggest first-run questions for the AI host (read-only)
   ready <id>           Check structural change readiness, not approval
   new-change <id>      Create an OpenSpec draft using installed templates
-  new-doc <type>       Scaffold a Product/Discovery document draft (requires product capability)
+  new-doc <type>       Scaffold a locked capability template (default: product)
 
 Options:
   --target <directory> Project directory (default: current directory)
   --detect            init only: opt in to detected stack selection
   --stage <type>      ready only: implement (default) or review
+  --capability <id>   new-doc only: installed template owner (default: product)
+  --agent-preset <id> init only: recommended (default), economy, custom; no overwrite
+  --host <id>         setup only: codex,claude-code,gemini-cli,cursor,copilot or custom host ID
   --scope <type>      verify/eval: adapters (default), capabilities, core, all
   --report <file>     eval only: score a reviewer-completed JSON report
   --adapters <a,b>     init/resolve: java-spring,react-nextjs,react-native,ai-python,kubernetes,astro
-  --capabilities <a,b> init/resolve: uiux,product,devops,monetization
+  --capabilities <a,b> init/resolve: uiux,product,architecture,delivery,devops,monetization
   --source <directory> init/update/list/detect/resolve: trusted alternate bundle directory
   --dry-run           init/update: preview without persistent changes
   --allow-major       init/update: acknowledge a major version migration
@@ -51,6 +54,8 @@ Examples:
   aih init --adapters astro --capabilities monetization
   aih resolve --adapters java-spring,kubernetes --capabilities product,uiux,devops
   aih setup
+  aih init --agent-preset economy
+  aih setup --host codex
   aih doctor
   aih ready add-order --stage implement
   aih skills
@@ -60,6 +65,9 @@ Examples:
   aih new-doc prd-lite
   aih new-doc srs
   aih new-doc use-cases
+  aih new-doc mvp
+  aih new-doc overview --capability architecture
+  aih new-doc delivery-plan --capability delivery
   aih init --adapters java-spring,kubernetes --capabilities product,devops
   aih skill harness-product-brd-generation
   aih skill harness-uiux-figma-design
@@ -71,7 +79,8 @@ export function main(argv = process.argv.slice(2)) {
   let args;
   try {
     args = parseArgs({ args: argv, allowPositionals: true, strict: true, tokens: true, options: {
-      target: { type: 'string' }, adapters: { type: 'string' }, capabilities: { type: 'string' }, source: { type: 'string' },
+      target: { type: 'string' }, adapters: { type: 'string' }, capabilities: { type: 'string' }, capability: { type: 'string' }, source: { type: 'string' },
+      'agent-preset': { type: 'string' }, host: { type: 'string' },
       detect: { type: 'boolean' }, report: { type: 'string' }, scope: { type: 'string' }, stage: { type: 'string' },
       'dry-run': { type: 'boolean' }, 'allow-major': { type: 'boolean' },
       help: { type: 'boolean', short: 'h' }, version: { type: 'boolean', short: 'v' },
@@ -87,9 +96,12 @@ export function main(argv = process.argv.slice(2)) {
     if (!['init', 'update', 'check', 'doctor', 'new-change', 'new-doc', 'list', 'detect', 'resolve', 'verify', 'eval', 'skills', 'skill', 'setup', 'ready'].includes(command)) throw new Error(`Unknown command: ${command}`);
     if (extra.length || (!['new-change', 'new-doc', 'skill', 'ready'].includes(command) && name !== undefined) || (['new-change', 'new-doc', 'skill', 'ready'].includes(command) && name === undefined)) throw new Error('Unexpected or missing positional argument; run aih --help');
     const allowed = new Set(['target', ...(['init', 'update'].includes(command) ? ['source', 'dry-run', 'allow-major'] : []), ...(['init', 'resolve'].includes(command) ? ['adapters', 'capabilities'] : []), ...(command === 'init' ? ['detect'] : []), ...(['list', 'detect', 'resolve'].includes(command) ? ['source'] : []), ...(command === 'eval' ? ['report'] : []), ...(command === 'ready' ? ['stage'] : []), ...(['verify', 'eval'].includes(command) ? ['scope'] : [])]);
+    if (command === 'new-doc') allowed.add('capability');
+    if (command === 'init') allowed.add('agent-preset');
+    if (command === 'setup') allowed.add('host');
     for (const key of Object.keys(args.values)) if (!allowed.has(key)) throw new Error(`--${key} is not supported for ${command}`);
     if (args.values.detect && args.values.adapters !== undefined) throw new Error('Choose either --detect or --adapters');
-    for (const key of ['target', 'source', 'adapters', 'capabilities', 'report']) if (args.values[key] !== undefined && !args.values[key].trim()) throw new Error(`--${key} cannot be empty`);
+    for (const key of ['target', 'source', 'adapters', 'capabilities', 'capability', 'report', 'agent-preset', 'host']) if (args.values[key] !== undefined && !args.values[key].trim()) throw new Error(`--${key} cannot be empty`);
   } catch (error) { console.error(JSON.stringify({ status: 'error', message: error.message })); return 2; }
   try {
     const { values, positionals: [command, name] } = args;
@@ -101,6 +113,7 @@ export function main(argv = process.argv.slice(2)) {
       if (values.detect && !selection.length) throw new Error('No stack detected; choose --adapters explicitly or omit --detect for core only');
       result = install(root, source, {
         command, adapters: selection ?? (values.adapters === undefined ? undefined : values.adapters.split(',').map(v => v.trim())),
+        agentPreset: values['agent-preset'],
         capabilities: values.capabilities === undefined ? undefined : values.capabilities.split(',').map(v => v.trim()),
         dryRun: values['dry-run'], allowMajor: values['allow-major'],
       });
@@ -121,10 +134,10 @@ export function main(argv = process.argv.slice(2)) {
     else if (command === 'setup' || command === 'ready') {
       const state = check(root);
       if (state.status !== 'ok') throw new Error('Fix installation drift before setup/readiness checks');
-      result = command === 'setup' ? setupPlan(root, loadLock(root).adapters) : ready(root, name, values.stage ?? 'implement');
+      result = command === 'setup' ? setupPlan(root, loadLock(root).adapters, process.env, values.host) : ready(root, name, values.stage ?? 'implement');
     }
     else if (command === 'new-change') result = newChange(root, name);
-    else if (command === 'new-doc') result = newDoc(root, name);
+    else if (command === 'new-doc') result = newDoc(root, name, values.capability ?? 'product');
     else result = command === 'doctor' ? doctor(root) : check(root);
     if (command === 'init' || command === 'update') result.next_steps = values['dry-run']
       ? ['Review the proposed changes, then repeat without --dry-run.']

package/config/agents.default.json

@@ -0,0 +1,80 @@
+{
+  "schema_version": 1,
+  "provider": "openai",
+  "defaultModel": "gpt-6.1-sol",
+  "defaultReasoning": "medium",
+  "models": {
+    "economy": "gpt-6-luna",
+    "balanced": "gpt-6.1-sol",
+    "premium": "gpt-6-astra"
+  },
+  "agents": {
+    "core:implementer": {
+      "model": "@balanced",
+      "reasoning": "medium"
+    },
+    "core:planner": {
+      "model": "@balanced",
+      "reasoning": "high"
+    },
+    "core:reviewer": {
+      "model": "@balanced",
+      "reasoning": "high"
+    },
+    "core:security-reviewer": {
+      "model": "@balanced",
+      "reasoning": "high"
+    },
+    "core:test-engineer": {
+      "model": "@balanced",
+      "reasoning": "medium"
+    },
+    "core:orchestrator": {
+      "model": "@balanced",
+      "reasoning": "high"
+    },
+    "core:documentation": {
+      "model": "@economy",
+      "reasoning": "low"
+    },
+    "product:business-analyst": {
+      "model": "@balanced",
+      "reasoning": "medium"
+    },
+    "product:product-manager": {
+      "model": "@balanced",
+      "reasoning": "medium"
+    },
+    "product:product-owner": {
+      "model": "@balanced",
+      "reasoning": "medium"
+    },
+    "product:project-manager": {
+      "model": "@balanced",
+      "reasoning": "medium"
+    },
+    "product:requirements-reviewer": {
+      "model": "@balanced",
+      "reasoning": "high"
+    },
+    "architecture:solution-architect": {
+      "model": "@balanced",
+      "reasoning": "high"
+    },
+    "architecture:architecture-reviewer": {
+      "model": "@balanced",
+      "reasoning": "high"
+    },
+    "delivery:project-manager": {
+      "model": "@balanced",
+      "reasoning": "medium"
+    }
+  },
+  "execution": {
+    "mode": "hybrid",
+    "maxConcurrentAgents": 2,
+    "maxRounds": 3,
+    "autoEscalateToPremium": false
+  },
+  "hosts": {}
+}

package/core/agents/documentation.md

@@ -0,0 +1,13 @@
+# Documentation
+
+Tool-neutral role contract; configuration is a preference, not a runtime.
+## Inputs
+Authorized task, current project facts, selected workflows, `.harness/agents.json` and actual host capability.
+## Outputs
+Source-linked document changes, preserved decision authority and actual verification limits.
+## Permissions and limits
+Follow Core permissions; never spawn workers, switch models or enforce token/round limits merely because
+JSON requests it. Premium requires explicit user model selection. No approval, merge or publication by role name.
+## Handoff
+Use `.harness/core/workflows/agent-routing.md`. Pass only scope, source paths/revisions, decisions,
+acceptance, actual checks, blockers and next owner. Keep simple tasks in one host session.

package/core/agents/implementer.md

@@ -4,9 +4,12 @@ This is a tool-neutral role contract, not an autonomous process or a promise of
 
 ## Inputs
 Agreed task, role handoff, adapter rules and tests.
+Include project mode, convention sources and reuse plan from `.harness/core/rules/project-conventions.md`.
 
 ## Outputs
 Produce a minimal diff, regression tests, executed check results and handoff to reviewer.
+Include reused symbol/source paths, intended placement and rationale for new dependencies/components.
+Preserve public boundaries; do not add parallel common helpers or unrelated abstractions.
 
 ## Permissions and limits
 May edit within authorized scope and run bounded checks. No credentials, unapproved external costs or automatic merge.
@@ -14,3 +17,7 @@ May edit within authorized scope and run bounded checks. No credentials, unappro
 ## Handoff
 State change ID, affected paths, decisions, evidence, outstanding questions and next owner.
 Load the relevant skill and adapter. Respect the host's delegation policy; roles can run sequentially.
+
+For new or consequential work, use `.harness/core/workflows/solution-framing.md` and relevant installed
+Product/Architecture/Delivery workflows. Carry source revisions, MVP/AC/NFR/ADR IDs, accepted boundaries,
+actual verification and unresolved dependencies in the handoff. Keep small clear fixes proportional.

package/core/agents/orchestrator.md

@@ -0,0 +1,13 @@
+# Orchestrator
+
+Tool-neutral role contract; configuration is a preference, not a runtime.
+## Inputs
+Authorized task, current project facts, selected workflows, `.harness/agents.json` and actual host capability.
+## Outputs
+Scoped plan, concise role handoffs and consolidated evidence/results.
+## Permissions and limits
+Follow Core permissions; never spawn workers, switch models or enforce token/round limits merely because
+JSON requests it. Premium requires explicit user model selection. No approval, merge or publication by role name.
+## Handoff
+Use `.harness/core/workflows/agent-routing.md`. Pass only scope, source paths/revisions, decisions,
+acceptance, actual checks, blockers and next owner. Keep simple tasks in one host session.

package/core/agents/planner.md

@@ -17,3 +17,7 @@ May read and draft specs. May not implement unrequested features, approve its ow
 ## Handoff
 State change ID, affected paths, decisions, evidence, outstanding questions and next owner.
 Load the relevant skill and adapter. Respect the host's delegation policy; roles can run sequentially.
+
+For new or consequential work, use `.harness/core/workflows/solution-framing.md` and relevant installed
+Product/Architecture/Delivery workflows. Carry source revisions, MVP/AC/NFR/ADR IDs, accepted boundaries,
+actual verification and unresolved dependencies in the handoff. Keep small clear fixes proportional.

package/core/agents/reviewer.md

@@ -4,9 +4,13 @@ This is a tool-neutral role contract, not an autonomous process or a promise of
 
 ## Inputs
 Base/head diff, proposal/specs, test logs and applicable standards.
+Include convention sources and reuse evidence required by `.harness/core/rules/project-conventions.md`.
 
 ## Outputs
 Produce prioritized findings with location, scenario, impact, remedy and remaining uncertainty.
+Check placement, naming, public dependency direction, duplicate behavior, unsafe inherited patterns,
+unnecessary abstractions/dependencies and unused code. Distinguish actual automated boundary results
+from manual inspection; never claim `aih check` proves application architecture compliance.
 
 ## Permissions and limits
 Review-only unless explicitly asked to fix findings. Never claim an independent review when the same model authored the code.
@@ -14,3 +18,7 @@ Review-only unless explicitly asked to fix findings. Never claim an independent
 ## Handoff
 State change ID, affected paths, decisions, evidence, outstanding questions and next owner.
 Load the relevant skill and adapter. Respect the host's delegation policy; roles can run sequentially.
+
+For new or consequential work, use `.harness/core/workflows/solution-framing.md` and relevant installed
+Product/Architecture/Delivery workflows. Carry source revisions, MVP/AC/NFR/ADR IDs, accepted boundaries,
+actual verification and unresolved dependencies in the handoff. Keep small clear fixes proportional.