@harness-forge/cli 0.1.0

package/scripts/runtime/render-observability-report.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const root = process.cwd();
+const summaryPath = path.join(root, ".hforge", "observability", "summary.json");
+
+let summary;
+try {
+  summary = JSON.parse(await fs.readFile(summaryPath, "utf8"));
+} catch {
+  summary = {
+    generatedAt: new Date().toISOString(),
+    totalEvents: 0,
+    byEventType: {},
+    byResult: {},
+    driftFindings: []
+  };
+}
+
+const lines = [
+  "# Observability Report",
+  "",
+  `Generated: ${summary.generatedAt}`,
+  `Total events: ${summary.totalEvents}`,
+  `Acceptance rate: ${summary.recommendationAcceptanceRate ?? "n/a"}`,
+  `Benchmark pass rate: ${summary.benchmarkPassRate ?? "n/a"}`,
+  "",
+  "## Event types"
+];
+
+for (const [eventType, count] of Object.entries(summary.byEventType ?? {})) {
+  lines.push(`- ${eventType}: ${count}`);
+}
+
+lines.push("", "## Results");
+for (const [result, count] of Object.entries(summary.byResult ?? {})) {
+  lines.push(`- ${result}: ${count}`);
+}
+
+lines.push("", "## Drift findings");
+if ((summary.driftFindings ?? []).length === 0) {
+  lines.push("- none");
+} else {
+  for (const finding of summary.driftFindings) {
+    lines.push(`- ${finding}`);
+  }
+}
+
+console.log(lines.join("\n"));

package/scripts/runtime/report-effectiveness.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const args = process.argv.slice(2);
+const json = args.includes("--json");
+const root = path.resolve(args.find((value) => !value.startsWith("--")) ?? ".");
+const filePath = path.join(root, ".hforge", "observability", "effectiveness-signals.json");
+
+let signals = [];
+try {
+  signals = JSON.parse(await fs.readFile(filePath, "utf8"));
+} catch {
+  signals = [];
+}
+
+const bySignalType = {};
+const byResult = {};
+for (const signal of signals) {
+  bySignalType[signal.signalType] = (bySignalType[signal.signalType] ?? 0) + 1;
+  byResult[signal.result] = (byResult[signal.result] ?? 0) + 1;
+}
+
+const summary = {
+  total: signals.length,
+  bySignalType,
+  byResult,
+  latest: signals[signals.length - 1] ?? null
+};
+
+if (json) {
+  console.log(JSON.stringify(summary, null, 2));
+} else {
+  console.log(JSON.stringify(summary, null, 2));
+}

package/scripts/runtime/summarize-observability.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const args = process.argv.slice(2);
+const json = args.includes("--json");
+const root = process.cwd();
+const eventsPath = path.join(root, ".hforge", "observability", "events.json");
+const effectivenessPath = path.join(root, ".hforge", "observability", "effectiveness-signals.json");
+const summaryPath = path.join(root, ".hforge", "observability", "summary.json");
+
+async function readJson(targetPath, fallback) {
+  try {
+    return JSON.parse(await fs.readFile(targetPath, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+const [events, effectivenessSignals] = await Promise.all([
+  readJson(eventsPath, []),
+  readJson(effectivenessPath, [])
+]);
+
+const byEventType = {};
+const byResult = {};
+for (const event of events) {
+  byEventType[event.eventType] = (byEventType[event.eventType] ?? 0) + 1;
+  byResult[event.result] = (byResult[event.result] ?? 0) + 1;
+}
+
+const accepted = (byResult.accepted ?? 0) + (byResult.success ?? 0);
+const rejected = (byResult.rejected ?? 0) + (byResult.failed ?? 0) + (byResult.blocked ?? 0);
+const benchmarkSignals = effectivenessSignals.filter((signal) => String(signal.signalType ?? "").includes("benchmark"));
+const benchmarkPasses = benchmarkSignals.filter((signal) => signal.result === "success").length;
+
+const summary = {
+  generatedAt: new Date().toISOString(),
+  totalEvents: events.length,
+  byEventType,
+  byResult,
+  recommendationAcceptanceRate: accepted + rejected > 0 ? Number((accepted / (accepted + rejected)).toFixed(2)) : undefined,
+  benchmarkPassRate:
+    benchmarkSignals.length > 0 ? Number((benchmarkPasses / benchmarkSignals.length).toFixed(2)) : undefined,
+  driftFindings: events
+    .filter((event) => event.eventType === "capability-drift" || event.result === "blocked")
+    .map((event) => `${event.eventType}:${event.result}`)
+};
+
+await fs.mkdir(path.dirname(summaryPath), { recursive: true });
+await fs.writeFile(summaryPath, `${JSON.stringify(summary, null, 2)}\n`, "utf8");
+
+if (json) {
+  console.log(JSON.stringify(summary, null, 2));
+} else {
+  console.log(JSON.stringify(summary, null, 2));
+}

package/scripts/templates/README.md

@@ -0,0 +1,40 @@
+# Template Validator Bundle
+
+Harness Forge ships the full task and workflow validator bundle inside `scripts/templates/`.
+
+## Included assets
+
+- shell validators in `scripts/templates/shell/`
+- PowerShell validators in `scripts/templates/powershell/`
+- shared config in `scripts/templates/config/required-sections.json`
+
+## Supported content
+
+- `templates/tasks/*.md`
+- `templates/workflows/*.md`
+
+## Usage
+
+### PowerShell
+
+```powershell
+pwsh ./scripts/templates/powershell/Check-TemplateFrontmatter.ps1 -Root .
+pwsh ./scripts/templates/powershell/Check-TemplateLinks.ps1 -Root .
+pwsh ./scripts/templates/powershell/Get-MissingTemplateSections.ps1 -Root .
+pwsh ./scripts/templates/powershell/Test-WorkflowContracts.ps1 -Root .
+```
+
+### POSIX shell
+
+```bash
+./scripts/templates/shell/check-template-frontmatter.sh .
+./scripts/templates/shell/check-template-links.sh .
+./scripts/templates/shell/list-missing-template-sections.sh .
+./scripts/templates/shell/verify-workflow-contracts.sh .
+```
+
+## Packaging expectations
+
+- these files are part of the published package surface
+- template docs and workflows must only reference these shipped paths
+- bundle completeness is enforced by release validation

package/scripts/templates/config/required-sections.json

@@ -0,0 +1,37 @@
+{
+  "task-template": [
+    "## Purpose",
+    "## When to Use",
+    "## Inputs",
+    "## Optional Inputs",
+    "## Constraints",
+    "## Expected Outputs",
+    "## Acceptance Criteria",
+    "## Quality Gates",
+    "## Suggested Workflow",
+    "## Related Commands",
+    "## Related Agents",
+    "## Examples"
+  ],
+  "workflow-template": [
+    "## Purpose",
+    "## When to Use",
+    "## Entry Conditions",
+    "## Workflow Stages",
+    "## Handoff Contracts",
+    "## Exit Conditions",
+    "## Failure Modes",
+    "## Escalation Rules",
+    "## Artifacts Produced",
+    "## Human Approval Points",
+    "## Examples"
+  ],
+  "workflow-stage-fields": [
+    "**Goal**",
+    "**Consumes**",
+    "**Produces**",
+    "**Exit Criteria**",
+    "**Failure Conditions**",
+    "**Next Trigger**"
+  ]
+}

package/scripts/templates/powershell/Check-TemplateFrontmatter.ps1

@@ -0,0 +1,54 @@
+param(
+  [string]$Root = "."
+)
+
+$TemplateDir = Join-Path $Root "templates"
+if (-not (Test-Path $TemplateDir)) {
+  Write-Error "Template directory not found: $TemplateDir"
+  exit 2
+}
+
+$requiredCommonFields = @(
+  'id','kind','title','status','version',
+  'supported_targets','supported_languages','owner','generated'
+)
+
+$requiredTaskFields = @('category','recommended_agents','recommended_commands')
+$requiredWorkflowFields = @('mode','default_agents')
+
+$failed = $false
+Get-ChildItem -Path $TemplateDir -Recurse -Filter *.md | Sort-Object FullName | ForEach-Object {
+  $file = $_
+  $content = Get-Content -Path $file.FullName
+  if ($content.Count -lt 3 -or $content[0] -ne '---') {
+    Write-Host "[FAIL] Missing front matter start: $($file.FullName)"
+    $failed = $true
+    return
+  }
+
+  $closing = ($content | Select-Object -Skip 1 | Select-String '^---$' | Select-Object -First 1)
+  if (-not $closing) {
+    Write-Host "[FAIL] Missing front matter end: $($file.FullName)"
+    $failed = $true
+    return
+  }
+
+  $requiredFields = @($requiredCommonFields)
+  $normalizedPath = $file.FullName -replace '\\', '/'
+  if ($normalizedPath -like "*/templates/tasks/*") {
+    $requiredFields += $requiredTaskFields
+  } elseif ($normalizedPath -like "*/templates/workflows/*") {
+    $requiredFields += $requiredWorkflowFields
+  }
+
+  foreach ($field in $requiredFields) {
+    $pattern = '^\s*' + [regex]::Escape($field) + ':'
+    if (-not ($content | Select-String $pattern -Quiet)) {
+      Write-Host "[FAIL] Missing front matter field '$field': $($file.FullName)"
+      $failed = $true
+    }
+  }
+}
+
+if ($failed) { exit 1 }
+Write-Host "Front matter validation passed."

package/scripts/templates/powershell/Check-TemplateLinks.ps1

@@ -0,0 +1,22 @@
+param(
+  [string]$Root = "."
+)
+
+$failed = $false
+Get-ChildItem -Path (Join-Path $Root "templates") -Recurse -Filter *.md | ForEach-Object {
+  $file = $_
+  $content = Get-Content $file.FullName -Raw
+  [regex]::Matches($content, '\[[^\]]+\]\(([^)]+)\)') | ForEach-Object {
+    $match = $_
+    $target = $match.Groups[1].Value
+    if ($target -match '^(https?:|mailto:|#)') { return }
+    $candidate = Join-Path $file.DirectoryName $target
+    if (-not (Test-Path $candidate) -and -not (Test-Path (Join-Path $Root $target))) {
+      Write-Host "[FAIL] Broken link in $($file.FullName): $target"
+      $failed = $true
+    }
+  }
+}
+
+if ($failed) { exit 1 }
+Write-Host "Template link validation passed."

package/scripts/templates/powershell/Get-MissingTemplateSections.ps1

@@ -0,0 +1,21 @@
+param(
+  [string]$Root = "."
+)
+
+$config = Get-Content (Join-Path $Root "scripts/templates/config/required-sections.json") -Raw | ConvertFrom-Json
+$failed = $false
+
+Get-ChildItem -Path (Join-Path $Root "templates") -Recurse -Filter *.md | ForEach-Object {
+  $content = Get-Content $_.FullName -Raw
+  $normalizedPath = $_.FullName -replace '\\', '/'
+  $kind = if ($normalizedPath -like "*/workflows/*") { 'workflow-template' } else { 'task-template' }
+  foreach ($section in $config.$kind) {
+    if ($content -notmatch [regex]::Escape($section)) {
+      Write-Host "[FAIL] Missing section '$section' in $($_.FullName)"
+      $failed = $true
+    }
+  }
+}
+
+if ($failed) { exit 1 }
+Write-Host "All required template sections are present."

package/scripts/templates/powershell/New-TemplateIndex.ps1

@@ -0,0 +1,19 @@
+param(
+  [string]$Root = ".",
+  [string]$OutPath = ""
+)
+
+if (-not $OutPath) {
+  $OutPath = Join-Path $Root "docs/templates/index.md"
+}
+
+$lines = @("# Template Index", "")
+Get-ChildItem -Path (Join-Path $Root "templates") -Recurse -Filter *.md | Sort-Object FullName | ForEach-Object {
+  $rel = $_.FullName.Replace("$Root\", "")
+  $lines += "- `$rel`"
+}
+
+$dir = Split-Path -Parent $OutPath
+if (-not (Test-Path $dir)) { New-Item -ItemType Directory -Force -Path $dir | Out-Null }
+Set-Content -Path $OutPath -Value $lines -Encoding utf8
+Write-Host "Wrote template index to $OutPath"

package/scripts/templates/powershell/Test-WorkflowContracts.ps1

@@ -0,0 +1,26 @@
+param(
+  [string]$Root = "."
+)
+
+$fields = @(
+  '**Goal**',
+  '**Consumes**',
+  '**Produces**',
+  '**Exit Criteria**',
+  '**Failure Conditions**',
+  '**Next Trigger**'
+)
+
+$failed = $false
+Get-ChildItem -Path (Join-Path $Root "templates/workflows") -Filter *.md | ForEach-Object {
+  $content = Get-Content $_.FullName -Raw
+  foreach ($field in $fields) {
+    if ($content -notmatch [regex]::Escape($field)) {
+      Write-Host "[FAIL] Missing workflow stage field '$field' in $($_.FullName)"
+      $failed = $true
+    }
+  }
+}
+
+if ($failed) { exit 1 }
+Write-Host "Workflow contracts look valid."

package/scripts/templates/shell/check-template-frontmatter.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="${1:-.}"
+TEMPLATE_DIR="$ROOT/templates"
+FAIL=0
+
+if [ ! -d "$TEMPLATE_DIR" ]; then
+  echo "Template directory not found: $TEMPLATE_DIR" >&2
+  exit 2
+fi
+
+while IFS= read -r file; do
+  first_line="$(head -n 1 "$file" || true)"
+  if [ "$first_line" != "---" ]; then
+    echo "[FAIL] Missing front matter start: $file"
+    FAIL=1
+    continue
+  fi
+
+  if ! awk 'NR>1 && /^---$/ { found=1; exit } END { exit found ? 0 : 1 }' "$file"; then
+    echo "[FAIL] Missing front matter end: $file"
+    FAIL=1
+    continue
+  fi
+
+  for field in id kind title status version supported_targets supported_languages owner generated; do
+    if ! sed -n '/^---$/,/^---$/p' "$file" | grep -Eq "^[[:space:]]*$field:"; then
+      echo "[FAIL] Missing front matter field '$field': $file"
+      FAIL=1
+    fi
+  done
+done < <(find "$TEMPLATE_DIR" -type f -name '*.md' | sort)
+
+if [ "$FAIL" -ne 0 ]; then
+  exit 1
+fi
+
+echo "Front matter validation passed."

package/scripts/templates/shell/check-template-links.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="${1:-.}"
+FAIL=0
+
+while IFS= read -r file; do
+  while IFS= read -r link; do
+    target="$(printf '%s' "$link" | sed -E 's/.*\(([^)]+)\)/\1/')"
+    case "$target" in
+      http*|mailto:*|'#'*) continue ;;
+    esac
+    dir="$(dirname "$file")"
+    if [ ! -e "$dir/$target" ] && [ ! -e "$ROOT/$target" ]; then
+      echo "[FAIL] Broken link in $file -> $target"
+      FAIL=1
+    fi
+  done < <(grep -o '\[[^]]*\]([^)]*)' "$file" || true)
+done < <(find "$ROOT/templates" -type f -name '*.md' | sort)
+
+if [ "$FAIL" -ne 0 ]; then
+  exit 1
+fi
+
+echo "Template link validation passed."

package/scripts/templates/shell/generate-template-index.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="${1:-.}"
+OUT="${2:-$ROOT/docs/templates/index.md}"
+
+mkdir -p "$(dirname "$OUT")"
+{
+  echo "# Template Index"
+  echo
+  find "$ROOT/templates" -type f -name '*.md' | sort | while IFS= read -r file; do
+    rel="${file#$ROOT/}"
+    echo "- \`$rel\`"
+  done
+} > "$OUT"
+
+echo "Wrote template index to $OUT"

package/scripts/templates/shell/list-missing-template-sections.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="${1:-.}"
+CONFIG="$ROOT/scripts/templates/config/required-sections.json"
+FAIL=0
+
+for file in "$ROOT"/templates/tasks/*.md "$ROOT"/templates/workflows/*.md; do
+  [ -f "$file" ] || continue
+  kind="task-template"
+  case "$file" in
+    *"/workflows/"*) kind="workflow-template" ;;
+  esac
+
+  python - "$CONFIG" "$kind" "$file" <<'PY'
+import json, sys, pathlib
+config = pathlib.Path(sys.argv[1])
+kind = sys.argv[2]
+file = pathlib.Path(sys.argv[3])
+required = json.loads(config.read_text(encoding="utf-8"))[kind]
+content = file.read_text(encoding="utf-8")
+missing = [section for section in required if section not in content]
+if missing:
+    print(f"[FAIL] {file}: missing sections -> {', '.join(missing)}")
+    sys.exit(1)
+PY
+  if [ $? -ne 0 ]; then
+    FAIL=1
+  fi
+done
+
+if [ "$FAIL" -ne 0 ]; then
+  exit 1
+fi
+
+echo "All required template sections are present."

package/scripts/templates/shell/verify-workflow-contracts.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="${1:-.}"
+FAIL=0
+
+for file in "$ROOT"/templates/workflows/*.md; do
+  [ -f "$file" ] || continue
+  for field in "**Goal**" "**Consumes**" "**Produces**" "**Exit Criteria**" "**Failure Conditions**" "**Next Trigger**"; do
+    if ! grep -qF "$field" "$file"; then
+      echo "[FAIL] Missing workflow stage field '$field' in $file"
+      FAIL=1
+    fi
+  done
+done
+
+if [ "$FAIL" -ne 0 ]; then
+  exit 1
+fi
+
+echo "Workflow contracts look valid."

package/skills/README.md

@@ -0,0 +1,94 @@
+# Skills
+
+Harness Forge ships four major skill families.
+
+## Discovery model
+
+- `.agents/skills/` wrappers are the lightweight discovery layer for supported agent runtimes
+- `skills/` directories are the canonical execution layer
+- `references/` directories hold deeper runtime-facing guidance
+- `docs/authoring/enhanced-skill-import.md` preserves maintainer-facing provenance for imported upgrades
+
+## Seeded language skills
+
+- `skills/typescript-engineering/`
+- `skills/java-engineering/`
+- `skills/dotnet-engineering/`
+- `skills/lua-engineering/`
+- `skills/powershell-engineering/`
+
+## Structured language skills
+
+- `skills/python-engineering/`
+- `skills/go-engineering/`
+- `skills/kotlin-engineering/`
+- `skills/rust-engineering/`
+- `skills/cpp-engineering/`
+- `skills/php-engineering/`
+- `skills/perl-engineering/`
+- `skills/swift-engineering/`
+- `skills/shell-engineering/`
+
+Several of these language skills now also ship supplemental `references/`
+packs so agents can pull repo-exploration, debugging, output-template, and
+ecosystem heuristics without leaving the project package.
+
+The March 2026 enhanced-skills import also deepened the TypeScript, .NET, Lua,
+and JavaScript packs with additional runtime-boundary, packaging, onboarding,
+and modernization guidance sourced into project-owned `references/` directories.
+
+## Workflow orchestration skills
+
+- `skills/speckit-analyze/`
+- `skills/speckit-checklist/`
+- `skills/speckit-clarify/`
+- `skills/speckit-constitution/`
+- `skills/speckit-implement/`
+- `skills/speckit-plan/`
+- `skills/speckit-specify/`
+- `skills/speckit-tasks/`
+- `skills/speckit-taskstoissues/`
+
+## Operational helper skills
+
+- `skills/engineering-assistant/`
+- `skills/repo-onboarding/`
+- `skills/documentation-lookup/`
+- `skills/security-scan/`
+- `skills/release-readiness/`
+- `skills/architecture-decision-records/`
+
+## Workload-specialized skills
+
+- `skills/incident-triage/`
+- `skills/dependency-upgrade-safety/`
+- `skills/performance-profiling/`
+- `skills/test-strategy-and-coverage/`
+- `skills/api-contract-review/`
+- `skills/db-migration-review/`
+- `skills/pr-triage-and-summary/`
+- `skills/observability-setup/`
+- `skills/parallel-worktree-supervisor/`
+- `skills/repo-modernization/`
+- `skills/cloud-architect/`
+
+## Supplemental engineering reference skills
+
+- `skills/javascript-engineering/`
+
+## Depth expectations
+
+Operational and workload skills should expose:
+
+- trigger signals
+- the repo surfaces to inspect first
+- a stable output contract
+- clear failure modes
+- escalation behavior
+
+Imported upgrades should also keep an auditable inventory record and preserve
+maintainer-facing provenance instead of shipping duplicate skill identities.
+
+Single-skill ports such as `engineering-assistant` should preserve the same
+discipline through `manifests/catalog/engineering-assistant-import-inventory.json`
+and `docs/authoring/engineering-assistant-port.md`.

package/skills/api-contract-review/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: api-contract-review
+description: review request, response, event, and schema contracts for compatibility and consumer safety. use when http, openapi, asyncapi, protobuf, json schema, generated clients, or external integration behavior changes.
+---
+
+# API Contract Review
+
+## Trigger Signals
+
+- the task changes HTTP routes, request or response shapes, headers, auth semantics, examples, or client SDKs
+- the repo edits OpenAPI, AsyncAPI, Protobuf, JSON Schema, or generated contract code
+- a versioning, deprecation, or compatibility question exists across providers and consumers
+
+## Inspect First
+
+- source-of-truth specs and the runtime handlers that implement them
+- schema validators, generated clients, examples, docs, and error-shape helpers
+- versioning and deprecation notes, auth requirements, and pagination or idempotency behavior
+- consumer code, integration tests, and release notes when a public contract changed
+
+## Workflow
+
+1. identify the canonical contract surface and compare it to the implementation
+2. classify the change by protocol: HTTP, event, schema-only, or wire-level
+3. evaluate backward compatibility for required fields, enums, defaults, errors, and behavior semantics
+4. verify examples, validation rules, and generated artifacts stay in sync
+5. emit a consumer-centered review with specific remediation or rollout guidance
+
+## Output Contract
+
+- changed contract summary grouped by endpoint, message, or schema
+- compatibility verdict with the precise breaking edges called out
+- consumer impact notes covering clients, codegen, docs, and deployment sequencing
+- follow-up actions for linting, versioning, deprecation, migration guides, or tests
+
+## Failure Modes
+
+- the runtime contract diverges from the checked-in spec and the source of truth is unclear
+- examples, docs, or generated clients are stale enough that contract behavior cannot be trusted
+- behavior semantics changed without any schema diff to explain it
+
+## Escalation
+
+- escalate when a breaking change lacks versioning, deprecation, or migration guidance
+- escalate when error semantics, auth requirements, or event-delivery guarantees change silently
+- escalate when wire compatibility for protobuf or event consumers is uncertain
+
+## References
+
+- `skills/api-contract-review/references/http-contract-checklist.md`
+- `skills/api-contract-review/references/schema-compatibility.md`
+- `skills/api-contract-review/references/event-and-async-contracts.md`
+- `skills/api-contract-review/references/protobuf-and-buf.md`
+- `skills/api-contract-review/references/style-and-linting.md`
+- `skills/api-contract-review/references/review-template.md`
+- `skills/api-contract-review/references/examples.md`

package/skills/api-contract-review/references/event-and-async-contracts.md

@@ -0,0 +1,16 @@
+# Event And Async Contracts
+
+## Review points
+
+- topic or channel name stability
+- message key or partitioning semantics
+- delivery guarantees that affect idempotency or ordering assumptions
+- schema evolution rules for consumers that may lag behind producers
+- replay and dead-letter behavior when validation tightens
+
+## Good async contract hygiene
+
+- keep envelope metadata stable
+- version payloads explicitly when semantics change
+- document whether consumers should ignore unknown fields
+- state ordering, duplication, and retry expectations clearly