@harness-forge/cli 0.1.0

package/.specify/scripts/powershell/common.ps1

@@ -0,0 +1,263 @@
+#!/usr/bin/env pwsh
+# Common PowerShell functions analogous to common.sh
+
+# Find repository root by searching upward for .specify directory
+# This is the primary marker for spec-kit projects
+function Find-SpecifyRoot {
+    param([string]$StartDir = (Get-Location).Path)
+
+    # Normalize to absolute path to prevent issues with relative paths
+    # Use -LiteralPath to handle paths with wildcard characters ([, ], *, ?)
+    $resolvedStartDir = Resolve-Path -LiteralPath $StartDir -ErrorAction SilentlyContinue
+    $current = if ($resolvedStartDir) { $resolvedStartDir.Path } else { $null }
+    if (-not $current) { return $null }
+
+    while ($true) {
+        if (Test-Path -LiteralPath (Join-Path $current ".specify") -PathType Container) {
+            return $current
+        }
+        $parent = Split-Path $current -Parent
+        if ([string]::IsNullOrEmpty($parent) -or $parent -eq $current) {
+            return $null
+        }
+        $current = $parent
+    }
+}
+
+# Get repository root, prioritizing .specify directory over git
+# This prevents using a parent git repo when spec-kit is initialized in a subdirectory
+function Get-RepoRoot {
+    # First, look for .specify directory (spec-kit's own marker)
+    $specifyRoot = Find-SpecifyRoot
+    if ($specifyRoot) {
+        return $specifyRoot
+    }
+
+    # Fallback to git if no .specify found
+    try {
+        $result = git rev-parse --show-toplevel 2>$null
+        if ($LASTEXITCODE -eq 0) {
+            return $result
+        }
+    } catch {
+        # Git command failed
+    }
+
+    # Final fallback to script location for non-git repos
+    # Use -LiteralPath to handle paths with wildcard characters
+    return (Resolve-Path -LiteralPath (Join-Path $PSScriptRoot "../../..")).Path
+}
+
+function Get-CurrentBranch {
+    # First check if SPECIFY_FEATURE environment variable is set
+    if ($env:SPECIFY_FEATURE) {
+        return $env:SPECIFY_FEATURE
+    }
+
+    # Then check git if available at the spec-kit root (not parent)
+    $repoRoot = Get-RepoRoot
+    if (Test-HasGit) {
+        try {
+            $result = git -C $repoRoot rev-parse --abbrev-ref HEAD 2>$null
+            if ($LASTEXITCODE -eq 0) {
+                return $result
+            }
+        } catch {
+            # Git command failed
+        }
+    }
+
+    # For non-git repos, try to find the latest feature directory
+    $specsDir = Join-Path $repoRoot "specs"
+    
+    if (Test-Path $specsDir) {
+        $latestFeature = ""
+        $highest = 0
+        $latestTimestamp = ""
+
+        Get-ChildItem -Path $specsDir -Directory | ForEach-Object {
+            if ($_.Name -match '^(\d{8}-\d{6})-') {
+                # Timestamp-based branch: compare lexicographically
+                $ts = $matches[1]
+                if ($ts -gt $latestTimestamp) {
+                    $latestTimestamp = $ts
+                    $latestFeature = $_.Name
+                }
+            } elseif ($_.Name -match '^(\d{3})-') {
+                $num = [int]$matches[1]
+                if ($num -gt $highest) {
+                    $highest = $num
+                    # Only update if no timestamp branch found yet
+                    if (-not $latestTimestamp) {
+                        $latestFeature = $_.Name
+                    }
+                }
+            }
+        }
+
+        if ($latestFeature) {
+            return $latestFeature
+        }
+    }
+    
+    # Final fallback
+    return "main"
+}
+
+# Check if we have git available at the spec-kit root level
+# Returns true only if git is installed and the repo root is inside a git work tree
+# Handles both regular repos (.git directory) and worktrees/submodules (.git file)
+function Test-HasGit {
+    # First check if git command is available (before calling Get-RepoRoot which may use git)
+    if (-not (Get-Command git -ErrorAction SilentlyContinue)) {
+        return $false
+    }
+    $repoRoot = Get-RepoRoot
+    # Check if .git exists (directory or file for worktrees/submodules)
+    # Use -LiteralPath to handle paths with wildcard characters
+    if (-not (Test-Path -LiteralPath (Join-Path $repoRoot ".git"))) {
+        return $false
+    }
+    # Verify it's actually a valid git work tree
+    try {
+        $null = git -C $repoRoot rev-parse --is-inside-work-tree 2>$null
+        return ($LASTEXITCODE -eq 0)
+    } catch {
+        return $false
+    }
+}
+
+function Test-FeatureBranch {
+    param(
+        [string]$Branch,
+        [bool]$HasGit = $true
+    )
+    
+    # For non-git repos, we can't enforce branch naming but still provide output
+    if (-not $HasGit) {
+        Write-Warning "[specify] Warning: Git repository not detected; skipped branch validation"
+        return $true
+    }
+    
+    if ($Branch -notmatch '^[0-9]{3}-' -and $Branch -notmatch '^\d{8}-\d{6}-') {
+        Write-Output "ERROR: Not on a feature branch. Current branch: $Branch"
+        Write-Output "Feature branches should be named like: 001-feature-name or 20260319-143022-feature-name"
+        return $false
+    }
+    return $true
+}
+
+function Get-FeatureDir {
+    param([string]$RepoRoot, [string]$Branch)
+    Join-Path $RepoRoot "specs/$Branch"
+}
+
+function Get-FeaturePathsEnv {
+    $repoRoot = Get-RepoRoot
+    $currentBranch = Get-CurrentBranch
+    $hasGit = Test-HasGit
+    $featureDir = Get-FeatureDir -RepoRoot $repoRoot -Branch $currentBranch
+    
+    [PSCustomObject]@{
+        REPO_ROOT     = $repoRoot
+        CURRENT_BRANCH = $currentBranch
+        HAS_GIT       = $hasGit
+        FEATURE_DIR   = $featureDir
+        FEATURE_SPEC  = Join-Path $featureDir 'spec.md'
+        IMPL_PLAN     = Join-Path $featureDir 'plan.md'
+        TASKS         = Join-Path $featureDir 'tasks.md'
+        RESEARCH      = Join-Path $featureDir 'research.md'
+        DATA_MODEL    = Join-Path $featureDir 'data-model.md'
+        QUICKSTART    = Join-Path $featureDir 'quickstart.md'
+        CONTRACTS_DIR = Join-Path $featureDir 'contracts'
+    }
+}
+
+function Test-FileExists {
+    param([string]$Path, [string]$Description)
+    if (Test-Path -Path $Path -PathType Leaf) {
+        Write-Output "  ✓ $Description"
+        return $true
+    } else {
+        Write-Output "  ✗ $Description"
+        return $false
+    }
+}
+
+function Test-DirHasFiles {
+    param([string]$Path, [string]$Description)
+    if ((Test-Path -Path $Path -PathType Container) -and (Get-ChildItem -Path $Path -ErrorAction SilentlyContinue | Where-Object { -not $_.PSIsContainer } | Select-Object -First 1)) {
+        Write-Output "  ✓ $Description"
+        return $true
+    } else {
+        Write-Output "  ✗ $Description"
+        return $false
+    }
+}
+
+# Resolve a template name to a file path using the priority stack:
+#   1. .specify/templates/overrides/
+#   2. .specify/presets/<preset-id>/templates/ (sorted by priority from .registry)
+#   3. .specify/extensions/<ext-id>/templates/
+#   4. .specify/templates/ (core)
+function Resolve-Template {
+    param(
+        [Parameter(Mandatory=$true)][string]$TemplateName,
+        [Parameter(Mandatory=$true)][string]$RepoRoot
+    )
+
+    $base = Join-Path $RepoRoot '.specify/templates'
+
+    # Priority 1: Project overrides
+    $override = Join-Path $base "overrides/$TemplateName.md"
+    if (Test-Path $override) { return $override }
+
+    # Priority 2: Installed presets (sorted by priority from .registry)
+    $presetsDir = Join-Path $RepoRoot '.specify/presets'
+    if (Test-Path $presetsDir) {
+        $registryFile = Join-Path $presetsDir '.registry'
+        $sortedPresets = @()
+        if (Test-Path $registryFile) {
+            try {
+                $registryData = Get-Content $registryFile -Raw | ConvertFrom-Json
+                $presets = $registryData.presets
+                if ($presets) {
+                    $sortedPresets = $presets.PSObject.Properties |
+                        Sort-Object { if ($null -ne $_.Value.priority) { $_.Value.priority } else { 10 } } |
+                        ForEach-Object { $_.Name }
+                }
+            } catch {
+                # Fallback: alphabetical directory order
+                $sortedPresets = @()
+            }
+        }
+
+        if ($sortedPresets.Count -gt 0) {
+            foreach ($presetId in $sortedPresets) {
+                $candidate = Join-Path $presetsDir "$presetId/templates/$TemplateName.md"
+                if (Test-Path $candidate) { return $candidate }
+            }
+        } else {
+            # Fallback: alphabetical directory order
+            foreach ($preset in Get-ChildItem -Path $presetsDir -Directory -ErrorAction SilentlyContinue | Where-Object { $_.Name -notlike '.*' }) {
+                $candidate = Join-Path $preset.FullName "templates/$TemplateName.md"
+                if (Test-Path $candidate) { return $candidate }
+            }
+        }
+    }
+
+    # Priority 3: Extension-provided templates
+    $extDir = Join-Path $RepoRoot '.specify/extensions'
+    if (Test-Path $extDir) {
+        foreach ($ext in Get-ChildItem -Path $extDir -Directory -ErrorAction SilentlyContinue | Where-Object { $_.Name -notlike '.*' } | Sort-Object Name) {
+            $candidate = Join-Path $ext.FullName "templates/$TemplateName.md"
+            if (Test-Path $candidate) { return $candidate }
+        }
+    }
+
+    # Priority 4: Core templates
+    $core = Join-Path $base "$TemplateName.md"
+    if (Test-Path $core) { return $core }
+
+    return $null
+}

package/.specify/scripts/powershell/create-new-feature.ps1

@@ -0,0 +1,23 @@
+[CmdletBinding()]
+param(
+  [Parameter(Mandatory = $true)][string]$Name,
+  [string]$Id = $(Get-Date -Format 'yyyyMMdd-HHmm')
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+$safe = ($Name.ToLowerInvariant() -replace '[^a-z0-9]+', '-').Trim('-')
+$featureRel = ".specify/features/$Id-$safe"
+$featureDir = Join-Path (Get-Location) $featureRel
+New-Item -ItemType Directory -Force -Path $featureDir | Out-Null
+
+foreach ($file in @("spec.md", "plan.md", "tasks.md")) {
+  $path = Join-Path $featureDir $file
+  if (-not (Test-Path $path)) { New-Item -ItemType File -Path $path | Out-Null }
+}
+
+$stateDir = Join-Path (Get-Location) ".specify/state"
+New-Item -ItemType Directory -Force -Path $stateDir | Out-Null
+Set-Content -Path (Join-Path $stateDir "active-feature.txt") -Value $featureRel -Encoding UTF8
+Write-Output $featureDir

package/.specify/scripts/powershell/setup-plan.ps1

@@ -0,0 +1,10 @@
+[CmdletBinding()]
+param([switch]$Json)
+
+$result = & "$PSScriptRoot/check-prerequisites.ps1" -Json -RequireTasks:$false
+if ($Json) {
+  $result
+  exit 0
+}
+
+$result | ConvertFrom-Json | Format-List

package/.specify/scripts/powershell/update-agent-context.ps1

@@ -0,0 +1,6 @@
+[CmdletBinding()]
+param([Parameter(Mandatory = $true)][string]$Summary)
+
+$stateDir = Join-Path (Get-Location) ".specify/state"
+New-Item -ItemType Directory -Force -Path $stateDir | Out-Null
+Set-Content -Path (Join-Path $stateDir "agent-context.md") -Value $Summary -Encoding UTF8

package/.specify/state/agent-context.md

@@ -0,0 +1 @@
+Feature 006 planning adds cross-agent skill porting for the imported engineering-assistant pack, including canonical skill ownership, runtime-compatibility translation across agent targets, reusable helper-surface packaging for project memory and change discipline, and validation-governance contracts for discovery, helper assets, and compatibility claims.

package/.specify/state/flow-state.json

@@ -0,0 +1,21 @@
+{
+  "featureId": "003-platform-enhancements",
+  "currentStage": "implement",
+  "status": "active",
+  "lastArtifact": "specs/003-platform-enhancements/tasks.md",
+  "nextAction": "Continue implementation and keep specs/003-platform-enhancements/tasks.md updated.",
+  "updatedAt": "2026-03-25T06:12:03.963Z",
+  "artifactLineage": [
+    "specs/003-platform-enhancements/spec.md",
+    "specs/003-platform-enhancements/checklists/requirements.md",
+    "specs/003-platform-enhancements/plan.md",
+    "specs/003-platform-enhancements/research.md",
+    "specs/003-platform-enhancements/data-model.md",
+    "specs/003-platform-enhancements/quickstart.md",
+    "specs/003-platform-enhancements/contracts/repo-intelligence-contract.md",
+    "specs/003-platform-enhancements/contracts/flow-state-contract.md",
+    "specs/003-platform-enhancements/contracts/hook-manifest-contract.md",
+    "specs/003-platform-enhancements/contracts/compatibility-matrix-contract.md",
+    "specs/003-platform-enhancements/tasks.md"
+  ]
+}

package/.specify/templates/agent-file-template.md

@@ -0,0 +1,40 @@
+# [PROJECT NAME] Development Guidelines
+
+Auto-generated from all feature plans. Last updated: [DATE]
+
+## Active Technologies
+
+[EXTRACTED FROM ALL PLAN.MD FILES]
+
+## Project Structure
+
+```text
+[ACTUAL STRUCTURE FROM PLANS]
+```
+
+## Commands
+
+[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES]
+
+## Code Style
+
+[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE]
+
+## Architecture Rules
+
+- Prefer small modules with explicit contracts and dependency direction.
+- Keep domain logic separate from transport, persistence, and framework glue.
+- Justify new abstractions when a simpler structure would work.
+
+## Quality Gates
+
+- Define executable verification before implementing behavior changes.
+- Validate inputs at system boundaries and keep secrets out of source control.
+- Update docs and shared agent guidance when commands, architecture, or behavior change.
+
+## Recent Changes
+
+[LAST 3 FEATURES AND WHAT THEY ADDED]
+
+<!-- MANUAL ADDITIONS START -->
+<!-- MANUAL ADDITIONS END -->

package/.specify/templates/checklist-template.md

@@ -0,0 +1,5 @@
+# Checklist
+
+- [ ] Requirements confirmed
+- [ ] Risks documented
+- [ ] Validation plan defined

package/.specify/templates/commands/plan.md

@@ -0,0 +1 @@
+Use this template to turn a spec into an implementation plan.

package/.specify/templates/commands/specify.md

@@ -0,0 +1 @@
+Use this template to turn a request into a spec.

package/.specify/templates/commands/tasks.md

@@ -0,0 +1 @@
+Use this template to break a plan into tasks.

package/.specify/templates/constitution-template.md

@@ -0,0 +1,5 @@
+# Constitution Template
+
+- decision boundaries
+- quality bars
+- release expectations

package/.specify/templates/plan-template.md

@@ -0,0 +1,9 @@
+# Implementation Plan
+
+## Scope
+
+## Proposed design
+
+## Validation plan
+
+## Rollback plan

package/.specify/templates/spec-template.md

@@ -0,0 +1,9 @@
+# Feature Spec
+
+## Outcome
+
+## Users and jobs to be done
+
+## Acceptance criteria
+
+## Risks and assumptions

package/.specify/templates/tasks-template.md

@@ -0,0 +1,5 @@
+# Task List
+
+- [ ] Define the smallest valid implementation slice
+- [ ] Implement the slice
+- [ ] Verify the slice

package/AGENTS.md

@@ -0,0 +1,75 @@
+# Harness Forge agent guidance
+
+Use the thin visible bridge surfaces first in installed workspaces:
+
+- `.agents/skills/` for auto-discoverable wrappers
+- `.hforge/agent-manifest.json` for the machine-readable custom-agent contract
+- `.specify/` for spec → plan → tasks
+- `.hforge/library/skills/` for canonical installed skills
+- `.hforge/library/rules/` plus the matching language directory for implementation guidance
+
+## Language discovery
+
+- prefer `.hforge/library/knowledge/seeded/typescript/` when the repo is TypeScript or JavaScript heavy in an installed workspace
+- prefer `skills/javascript-engineering/` when the repo is JavaScript-first and the task is not primarily about TypeScript typing
+- prefer `.hforge/library/knowledge/seeded/java/` for Java services and libraries in an installed workspace
+- prefer `.hforge/library/knowledge/seeded/dotnet/` for .NET repos in an installed workspace
+- prefer `.hforge/library/knowledge/seeded/lua/` for Lua work in an installed workspace
+- prefer `.hforge/library/knowledge/seeded/powershell/` for PowerShell and Windows automation in an installed workspace
+- use the structured packs under `.hforge/library/knowledge/structured/` for Python, Go, Kotlin, Rust, C++, PHP, Perl, Swift, and Shell in an installed workspace
+
+## Specialized skills
+
+- prefer `.hforge/library/skills/cloud-architect/` when the task is about deployment topology, distributed systems, reliability, observability, or cloud trade-offs across services in an installed workspace
+- prefer `.hforge/library/skills/engineering-assistant/` when the task needs architecture plus implementation orchestration, option framing, or explicit project-memory and change-discipline guidance in one surface in an installed workspace
+
+## Imported skill governance
+
+- treat `manifests/catalog/engineering-assistant-import-inventory.json` as the
+  review ledger for the single-skill engineering-assistant port
+- keep maintainer-facing provenance for that port in
+  `docs/authoring/engineering-assistant-port.md`
+- treat `manifests/catalog/enhanced-skill-import-inventory.json` as the review
+  ledger for embedded skill packs and use it before changing imported skill
+  surfaces
+- treat `.agents/skills/` as the discovery layer and `.hforge/library/skills/`
+  as the canonical installed execution layer
+- keep maintainer-facing provenance in
+  `docs/authoring/enhanced-skill-import.md`
+- use `RESEARCH-SOURCES.md` and `VALIDATION.md` only as additional provenance,
+  not as replacements for the canonical skill surfaces
+- prefer the project-owned canonical `skills/` surfaces over any raw imported
+  archive layout
+
+## Runtime notes
+
+- Claude Code installs map target runtime files into `.claude/`
+- Codex installs map target runtime files into `.codex/`
+- installed workspaces compile the shared intelligence runtime into
+  `.hforge/runtime/`
+- both targets still use `.agents/skills/`, `.specify/`, and the package validation surfaces
+
+## Repo intelligence
+
+- use `node dist/cli/index.js recommend <repo>` when the right pack, profile,
+  or skill is not obvious from file extensions alone
+- use `node dist/cli/index.js commands --json` or
+  `.hforge/generated/agent-command-catalog.json` to discover the shipped CLI
+  commands and npm scripts before inventing your own execution path
+- use `.hforge/agent-manifest.json` when a custom agent needs one stable
+  machine-readable file describing bridge files, canonical roots, local
+  launchers, and safe command discovery
+- use `.hforge/library/` as the canonical installed AI layer and avoid treating
+  root-visible bridge files as the full source of truth
+- use `.hforge/runtime/index.json` and `.hforge/runtime/README.md` to inspect
+  the installed shared runtime and its target discovery bridges before treating
+  target-specific files as authoritative in isolation
+- use `node dist/cli/index.js bootstrap --root . --yes` when the repository
+  needs target autodiscovery and one-pass Harness Forge setup
+- treat framework matches and validation gaps as first-class signals, not just
+  bundle decoration
+- prefer recommendation evidence over guessing from a single config file
+
+## Release gate
+
+Run `npm run validate:release` before publish or handoff.

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## Unreleased
+
+### Added
+
+- production-ready `init`, `refresh`, `task`, `pack`, `review`, and `export` command surfaces
+- deterministic workspace initialization with visible runtime schema metadata
+- release smoke validation via `scripts/ci/smoke-runner.mjs`
+- contributor and release-process documentation for local and release-grade validation
+
+### Changed
+
+- shared runtime metadata now records package version and runtime schema version
+- CI and release guidance are aligned around `validate:local`, `validate:release`, and `release:dry-run`

package/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing
+
+## Local setup
+
+```bash
+npm install
+npm run build
+```
+
+## Validation levels
+
+- `npm run validate:local` for the routine maintainer path before opening a PR
+- `npm run validate:release` for the full release-grade gate
+- `npm run release:dry-run` before tagging or publishing a package candidate
+
+## Typical contributor loop
+
+1. Run `npm run build`.
+2. Run targeted tests while changing code.
+3. Run `npm run validate:local` before asking for review.
+4. Update `README.md`, `docs/`, or `CHANGELOG.md` if the operator surface changed.
+
+## Release-sensitive changes
+
+Treat these as production-facing:
+
+- `package.json` and `.npmignore`
+- `src/cli/`
+- `src/application/install/`
+- `scripts/ci/`
+- `.github/workflows/`
+- `README.md` and `docs/commands.md`
+
+## Troubleshooting
+
+- use `hforge doctor --root <repo>` when install/runtime state looks wrong
+- use `hforge audit --root <repo>` for a fuller package/runtime summary
+- use `hforge refresh --root <repo>` after install changes when shared runtime artifacts drift