@harness-forge/cli 0.1.0

package/skills/release-readiness/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: release-readiness
+description: Release-prep workflow for validation, documentation alignment, package surface, and handoff quality.
+---
+
+# Release Readiness
+
+## Trigger Signals
+
+- a package, feature, or release candidate is close to handoff
+- the task needs a go or no-go recommendation with evidence
+
+## Inspect First
+
+- validation scripts and package manifests
+- changed docs, commands, and install or upgrade surfaces
+- compatibility, migration, and support notes
+
+## Workflow
+
+1. collect the intended release surface and the current validation evidence
+2. verify docs, commands, package paths, and upgrade guidance align
+3. identify blockers, warnings, and missing follow-up work
+4. produce a release report with a go or no-go recommendation
+
+## Output Contract
+
+- release decision
+- blocking issues
+- warnings
+- validation evidence summary
+
+## Failure Modes
+
+- release scope is unclear
+- required validation surfaces are missing or untrusted
+
+## Escalation
+
+- escalate when a release-blocking validation gap remains unresolved
+- escalate when docs or package surfaces contradict runtime behavior
+
+## References
+
+- `skills/release-readiness/references/release-report-template.md`

package/skills/release-readiness/references/release-report-template.md

@@ -0,0 +1,7 @@
+# Release Report Template
+
+- Release scope
+- Validation evidence
+- Blocking issues
+- Warnings
+- Recommendation

package/skills/repo-cartographer/SKILL.md

@@ -0,0 +1,10 @@
+# Repo Cartographer
+
+Use this skill when you need a repo-aware map before recommending new guidance
+surfaces.
+
+Start with:
+
+- `node scripts/intelligence/cartograph-repo.mjs <repo> --json`
+- `node scripts/intelligence/classify-boundaries.mjs <repo> --json`
+- `node scripts/intelligence/synthesize-instructions.mjs <repo> --dry-run --json`

package/skills/repo-modernization/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: repo-modernization
+description: stage legacy cleanup and modernization without losing the current operating path. use when a repo has dependency drift, weak validation, outdated frameworks, monolith friction, or repeated delivery pain that needs a phased plan instead of a rewrite impulse.
+---
+
+# Repo Modernization
+
+## Trigger Signals
+
+- the repo is legacy, inconsistent, slow to change, or missing dependable workflows
+- dependencies, framework versions, or build tooling are clearly behind the desired support window
+- repeated pain shows up in build fragility, onboarding cost, release risk, or architectural drag
+
+## Inspect First
+
+- build, test, and release entrypoints
+- runtime and framework versions, dependency manifests, and lockfiles
+- architecture seams, integration boundaries, and highest-risk hotspots
+- observability, CI, documentation, and rollback surfaces that determine whether change is safe
+
+## Workflow
+
+1. establish the current operating path and the minimum validation baseline needed to change the repo safely
+2. group problems into modernization layers: visibility, build and dependency health, codebase consistency, and architecture
+3. separate quick wins from seam-first refactors and from truly strategic platform changes
+4. produce a staged roadmap with validation and rollback expectations for each phase
+5. prefer incremental replacement and automation over big-bang rewrites unless evidence says otherwise
+
+## Output Contract
+
+- current-state summary with the biggest sources of drag or risk
+- prioritized modernization themes and why they matter now
+- phased roadmap with prerequisites, safety rails, and likely owners
+- automation candidates, migration helpers, and explicit non-goals
+
+## Failure Modes
+
+- the repo lacks enough validation to support any meaningful modernization safely
+- production topology or support commitments are too unclear to judge migration risk
+- the proposed plan collapses into a rewrite with no intermediate value or rollback path
+
+## Escalation
+
+- escalate when modernization would break support or release commitments without a transition plan
+- escalate when the work crosses multiple teams or service boundaries with no owner alignment
+- escalate when data migration, security posture, or compliance constraints materially change the plan
+
+## References
+
+- `skills/repo-modernization/references/modernization-layers.md`
+- `skills/repo-modernization/references/strangler-and-seams.md`
+- `skills/repo-modernization/references/dependency-and-build-modernization.md`
+- `skills/repo-modernization/references/safety-rails.md`
+- `skills/repo-modernization/references/automation-candidates.md`
+- `skills/repo-modernization/references/roadmap-template.md`
+- `skills/repo-modernization/references/examples.md`

package/skills/repo-modernization/references/automation-candidates.md

@@ -0,0 +1,19 @@
+# Automation Candidates
+
+## High-value helpers
+
+- OpenRewrite for large-scale source refactors in JVM-heavy estates
+- modernize-dotnet or Upgrade Assistant style flows for .NET upgrade scaffolding
+- Renovate for controlled dependency update intake and risk visibility
+- language-native codemods, formatters, and linters for consistency fixes
+
+## Use automation when
+
+- the change pattern repeats many times
+- the transformation can be validated mechanically
+- humans should review policy, not hand-apply the same edit hundreds of times
+
+## Avoid automation when
+
+- the seam is still poorly understood
+- generated diffs would overwhelm review without strong validation

package/skills/repo-modernization/references/dependency-and-build-modernization.md

@@ -0,0 +1,16 @@
+# Dependency And Build Modernization
+
+## Safe sequence
+
+1. pin and document the current toolchain
+2. repair CI and local reproducibility
+3. update one framework or package family at a time
+4. keep build output and artifact shape stable where consumers depend on them
+5. only then change architecture surfaces that rely on the updated toolchain
+
+## Common modernization wins
+
+- centralize version management where the ecosystem supports it
+- automate dependency update intake and triage
+- collapse duplicate scripts and inconsistent build wrappers
+- remove abandoned generators or build steps after proving nothing consumes them

package/skills/repo-modernization/references/examples.md

@@ -0,0 +1,15 @@
+# Examples
+
+## Healthy modernization plan
+
+- first repair CI and document the release path
+- then upgrade the package manager and lockfile discipline
+- then automate dependency updates
+- only after that extract the legacy service adapter behind a stable interface
+
+## Risky modernization plan
+
+- rewrite the service into a new framework
+- upgrade every dependency at once
+- move to a new database access layer in the same release
+- remove the old path before telemetry proves parity

package/skills/repo-modernization/references/modernization-layers.md

@@ -0,0 +1,21 @@
+# Modernization Layers
+
+## Layer 1: Visibility and confidence
+
+Create or repair the basic map first: build commands, test paths, release path, ownership, and the critical systems that must not break.
+
+## Layer 2: Dependency and tooling health
+
+Update package managers, SDK pins, CI drift, and outdated dependencies with the smallest safe steps. This layer often unlocks everything else.
+
+## Layer 3: Codebase consistency
+
+Normalize linting, formatting, generated-code boundaries, package structure, and shared conventions so later refactors stop fighting the repo.
+
+## Layer 4: Architectural seams
+
+Only after the repo can validate itself reliably should you extract modules, split services, or change runtime boundaries.
+
+## Rule
+
+Do not start with architecture theater when the repo cannot build or test reliably.

package/skills/repo-modernization/references/roadmap-template.md

@@ -0,0 +1,25 @@
+# Roadmap Template
+
+## Phase 0: Stabilize
+
+- restore build and test confidence
+- document the current release path
+- identify owners and critical systems
+
+## Phase 1: Tooling and dependency health
+
+- pin toolchains
+- reduce drift
+- automate routine updates
+
+## Phase 2: Structural cleanup
+
+- normalize package or project layout
+- isolate generated code and shared contracts
+- improve observability and onboarding docs
+
+## Phase 3: Architectural moves
+
+- extract seams incrementally
+- migrate traffic or ownership in slices
+- remove legacy paths only after proving the replacement

package/skills/repo-modernization/references/safety-rails.md

@@ -0,0 +1,15 @@
+# Safety Rails
+
+## Before a risky phase
+
+- identify the commands that prove the repo still works
+- add smoke tests or contract tests for the highest-risk seams
+- define rollback or feature-flag posture
+- decide what metrics or telemetry would show regression quickly
+
+## During modernization
+
+- prefer one irreversible move at a time
+- keep migration notes close to the change
+- avoid mixing refactors with behavioral changes unless the repo forces that trade-off
+- keep old and new paths observable during transitions

package/skills/repo-modernization/references/strangler-and-seams.md

@@ -0,0 +1,18 @@
+# Strangler And Seams
+
+## Incremental replacement bias
+
+The strangler approach beats a rewrite impulse in most real repos because it creates a new path around the old system gradually, delivering value and reducing risk before the old path disappears.
+
+## Good seams
+
+- stable external contracts such as APIs, events, or file formats
+- packages or modules with clear ownership boundaries
+- adapters around data access, external services, or legacy framework glue
+- anti-corruption layers that let new code stop depending on old internals directly
+
+## Bad seams
+
+- boundaries defined only by folder names without behavioral ownership
+- fake service splits that keep one shared database and shared runtime assumptions untouched
+- "temporary" duplication with no cleanup trigger or stop condition

package/skills/repo-onboarding/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: repo-onboarding
+description: repository discovery, entrypoint mapping, and fast onboarding for unfamiliar codebases. use when the repo is new, mixed, legacy, monorepo-shaped, poorly documented, or when the next safe step is blocked on understanding layout, ownership, and commands.
+---
+
+# Repository Onboarding
+
+## Trigger Signals
+
+- the repository is unfamiliar, mixed, legacy, or monorepo-shaped
+- the next safe step is blocked on understanding layout, ownership, or workflow
+- docs are sparse, stale, or scattered across many entrypoints
+
+## Inspect First
+
+- repo root files such as `README.md`, top-level manifests, CI config, container config, and deployment hints
+- `AGENTS.md`, `.agents/skills/`, `.specify/`, or other repo-native guidance surfaces when present
+- top-level source, app, package, service, infra, and test directories
+- `CODEOWNERS`, contribution docs, issue or PR templates, and other health signals when present
+
+## Workflow
+
+1. identify the repo archetype and dominant implementation surfaces
+2. map build, test, run, deploy, and validation entrypoints
+3. infer ownership, boundaries, and high-risk hotspots from structure and metadata
+4. call out drift, missing validation, generated code, or conflicting conventions
+5. recommend the next best action and the best repo surfaces to load before changing code
+
+## Output Contract
+
+- repository summary with dominant languages, runtimes, and repo shape
+- key commands and entrypoints for build, test, run, and release
+- hotspots, blockers, and missing information that affect safe changes
+- recommended next action with the specific files or dirs to inspect next
+
+## Failure Modes
+
+- repo layout is too large to inspect safely in one pass
+- generated or vendored code hides the real ownership boundaries
+- no reliable build or validation entrypoints can be found
+
+## Escalation
+
+- escalate when ownership or architecture cannot be inferred safely
+- escalate when there is no trustworthy validation path for a risky change
+- escalate when docs and code disagree about the active workflow
+
+## References
+
+- `skills/repo-onboarding/references/output-template.md`
+- `skills/repo-onboarding/references/discovery-checklist.md`
+- `skills/repo-onboarding/references/repo-archetypes.md`
+- `skills/repo-onboarding/references/ownership-and-health-signals.md`
+- `skills/repo-onboarding/references/command-discovery.md`
+- `skills/repo-onboarding/references/monorepo-signals.md`
+- `skills/repo-onboarding/references/examples.md`

package/skills/repo-onboarding/references/command-discovery.md

@@ -0,0 +1,13 @@
+# Command Discovery
+
+## High-signal places to look
+
+- root manifests and script sections
+- Makefiles, task runners, or custom wrappers
+- CI workflows that reveal the authoritative commands
+- docs that show local dev or release steps
+- toolchain pins such as SDK or package-manager version files
+
+## Command selection rule
+
+Prefer the narrowest command that proves the requested change. When docs and CI disagree, treat CI as the more authoritative source unless there is strong evidence it is stale.

package/skills/repo-onboarding/references/discovery-checklist.md

@@ -0,0 +1,24 @@
+# Discovery Checklist
+
+## Start at the root
+
+- README and setup docs
+- manifests for package managers or language toolchains
+- CI workflows and release scripts
+- container or infra config
+- root config files that affect the whole repo
+
+## Then map the code
+
+- app or service roots
+- shared libraries or packages
+- test roots
+- generated code
+- docs and design notes
+
+## Then answer
+
+- how do I build and test this repo?
+- what are the dominant runtimes and frameworks?
+- where are the risky shared seams?
+- what should I inspect before making the requested change?

package/skills/repo-onboarding/references/examples.md

@@ -0,0 +1,13 @@
+# Examples
+
+## Good onboarding summary
+
+- this is a pnpm monorepo with one API, one web app, and two shared packages
+- the CI source of truth is the root workflow that runs `pnpm lint`, `pnpm test`, and app-specific builds
+- `CODEOWNERS` suggests the platform team owns root config and shared contracts
+- the next step for an API bug is to inspect the service package and its generated client package together
+
+## Weak onboarding summary
+
+- there are many files and some JavaScript
+- maybe run the tests

package/skills/repo-onboarding/references/monorepo-signals.md

@@ -0,0 +1,17 @@
+# Monorepo Signals
+
+## Look for
+
+- workspace manifests
+- shared config inherited by many packages
+- package boundaries that align with deployable units or domains
+- generated contract packages consumed by multiple apps
+- dependency direction between apps and shared libraries
+
+## Hotspots
+
+- root lockfiles and global config
+- shared schema or API packages
+- generated clients
+- root lint, formatting, and test orchestration
+- deployment and release scripts that touch many packages at once

package/skills/repo-onboarding/references/output-template.md

@@ -0,0 +1,26 @@
+# Output Template
+
+## Repo Summary
+
+- dominant languages and runtimes
+- repo archetype
+- highest-signal directories
+
+## Commands
+
+- build
+- test
+- run or dev
+- lint or validation
+- release or deploy if visible
+
+## Ownership And Risk
+
+- likely owners or code boundaries
+- hotspots and shared contracts
+- missing docs, validation, or setup details
+
+## Recommended Next Step
+
+- next file or directory to inspect
+- why that surface is the best leverage point

package/skills/repo-onboarding/references/ownership-and-health-signals.md

@@ -0,0 +1,21 @@
+# Ownership And Health Signals
+
+## Useful ownership clues
+
+- `CODEOWNERS`
+- package or project naming
+- team-specific directories
+- CI job ownership and deployment targets
+- release notes and changelog patterns
+
+## Useful health clues
+
+- README and CONTRIBUTING quality
+- issue and PR templates
+- active lockfiles and recent dependency hygiene
+- whether generated or vendored code is isolated clearly
+- whether GitHub surfaces show language breakdown and community health metadata clearly
+
+## Practical rule
+
+Treat missing ownership and missing validation as risk multipliers even if the code itself looks simple.

package/skills/repo-onboarding/references/repo-archetypes.md

@@ -0,0 +1,13 @@
+# Repo Archetypes
+
+## Common shapes
+
+- single app or service
+- package library or SDK
+- monorepo with apps and shared packages
+- polyglot platform repo with infra and service code
+- legacy mixed repo with partial migrations and duplicate tooling
+
+## Why the shape matters
+
+Repo shape predicts where commands live, where ownership is concentrated, and whether shared contracts or root config are likely to create change risk.

package/skills/rust-engineering/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: rust-engineering
+description: rust engineering guidance for structured Harness Forge language packs.
+---
+
+# Rust Engineering
+
+Use this skill when the repository is primarily Rust or when the task touches `.rs` or `Cargo.toml`.
+
+## Activation
+
+- Rust dominates the task or repository
+- the work touches ownership-heavy modules, CLIs, services, or libraries
+
+## Load Order
+
+- `rules/common/`
+- `rules/rust/`
+- `knowledge-bases/structured/rust/docs/`
+- `knowledge-bases/structured/rust/examples/`
+
+## Execution Contract
+
+1. inspect crate boundaries, ownership hotspots, and error paths
+2. select the common and Rust-specific rules for the change
+3. implement with explicit trait, ownership, and error-handling decisions
+4. verify with the repo cargo path and the structured checklist
+
+## Outputs
+
+- touched-crate summary
+- implementation summary
+- validation result or blocker note
+
+## Validation
+
+- run the repo Rust validation path when available
+- consult `knowledge-bases/structured/rust/docs/review-checklist.md`
+
+## Escalation
+
+- escalate when `unsafe`, public API compatibility, or performance-sensitive changes appear
+- escalate when ownership tradeoffs remain unclear after design

package/skills/security-scan/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: security-scan
+description: Defensive review checklist for secrets, auth boundaries, input validation, and package safety.
+---
+
+# Security Scan
+
+## Trigger Signals
+
+- the task touches auth, secrets, privileged routes, or network boundaries
+- the repository is a service or security-sensitive runtime
+
+## Inspect First
+
+- environment and config surfaces
+- auth middleware, handlers, route guards, and secret-loading code
+- dependency manifests and externally reachable entrypoints
+
+## Workflow
+
+1. identify exposed trust boundaries and secret-bearing paths
+2. inspect input validation, auth, and authorization behavior
+3. review dependency, logging, and data-exposure risks
+4. summarize concrete findings and remediation priorities
+
+## Output Contract
+
+- attack-surface summary
+- ordered findings with severity
+- recommended remediations
+- residual risk note
+
+## Failure Modes
+
+- the task scope hides the actual runtime boundary
+- there is no reliable way to trace user input to protected operations
+
+## Escalation
+
+- escalate when a likely secret leak or auth bypass is detected
+- escalate when the scan cannot safely verify a high-risk boundary
+
+## References
+
+- `skills/security-scan/references/review-checklist.md`

package/skills/security-scan/references/review-checklist.md

@@ -0,0 +1,7 @@
+# Security Scan Checklist
+
+- secret loading and storage
+- auth and authorization boundaries
+- request validation and serialization
+- dependency and package risk
+- logging and sensitive data exposure

package/skills/shell-engineering/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: shell-engineering
+description: shell engineering guidance for structured Harness Forge language packs.
+---
+
+# Shell Engineering
+
+Use this skill when the repository is primarily shell automation or when the task touches shell scripts.
+
+## Activation
+
+- shell scripts dominate the task or repository
+- the work touches automation, bootstrap, CI, or operational workflows
+
+## Load Order
+
+- `rules/common/`
+- `rules/shell/`
+- `knowledge-bases/structured/shell/docs/`
+- `knowledge-bases/structured/shell/examples/`
+
+## Execution Contract
+
+1. inspect execution context, portability, and failure handling assumptions
+2. select the common and shell-specific rules for the change
+3. implement with explicit quoting, safety, and destructive-operation boundaries
+4. verify with the safest repo script path and the structured checklist
+
+## Outputs
+
+- touched-script summary
+- implementation summary
+- validation result or blocker note
+
+## Validation
+
+- run the script in dry-run or non-destructive mode when possible
+- consult `knowledge-bases/structured/shell/docs/review-checklist.md`
+
+## Escalation
+
+- escalate when portability or destructive operations make the risk non-local
+- escalate when shell compatibility cannot be confirmed safely