@harness-forge/cli 0.1.0

package/skills/engineering-assistant/references/change-discipline.md

@@ -0,0 +1,37 @@
+# Change Discipline
+
+The imported pack required every meaningful skill, script, and reference change
+to be captured in a structured change log. Harness Forge keeps that rule as a
+project-owned discipline even before the translated helper commands land.
+
+## Record these fields
+
+- monotonically increasing change id
+- UTC timestamp
+- change type such as docs, rules, script, reference, or fix
+- one-line summary
+- short detail bullets
+- touched-file list
+
+## Update triggers
+
+- a canonical skill contract changes materially
+- a supporting reference or helper surface changes
+- runtime wiring or compatibility guidance changes
+- validation, governance, or provenance rules change
+
+## Minimal entry template
+
+- id
+- date
+- type
+- summary
+- details
+- files
+
+## MVP operating rule
+
+Until package-owned helper commands land, capture the same fields manually in
+the relevant feature notes, task updates, or maintainer-facing provenance. Keep
+the entry explicit enough that another maintainer can understand what changed
+and why without diff archaeology.

package/skills/engineering-assistant/references/project-notes.md

@@ -0,0 +1,36 @@
+# Project Notes Discipline
+
+The imported pack expected the skill to keep a lightweight but current project
+memory surface during meaningful work. Harness Forge preserves that discipline
+as guidance rather than shipping the source pack's sample note file.
+
+## Keep current
+
+- project name and primary goal
+- intended users and success metric
+- time, budget, security, compliance, performance, and availability constraints
+- proposed or active stack across frontend, backend, data, infra, CI, and observability
+- decisions as mini-ADRs with date and rationale
+- open questions and working glossary terms
+
+## Update triggers
+
+- a major design choice is made
+- a key requirement, constraint, or risk becomes clear
+- the active stack or ownership boundary changes
+- the team uncovers unknowns that materially affect delivery
+
+## Recommended structure
+
+1. project snapshot
+2. constraints
+3. proposed or active stack
+4. decisions as mini-ADRs
+5. open questions
+6. glossary
+
+## MVP operating rule
+
+Until package-owned helper commands land, update the equivalent notes manually
+using this structure and keep the rationale concise enough that another agent or
+maintainer can recover the project state quickly.

package/skills/engineering-assistant/references/skill-composition.md

@@ -0,0 +1,33 @@
+# Skill Composition
+
+Use this reference when engineering-assistant is orchestrating work across more
+specialized skills or knowledge packs.
+
+## Goal
+
+Route the implementation details to the most specific skill available while
+keeping engineering-assistant responsible for consistency, interfaces, and the
+delivery plan.
+
+## Routing rules
+
+- if a domain clearly matches an existing specialist skill, use that skill as the primary executor for the subtask
+- if multiple skills could apply, choose the most specific one instead of stacking broad generalists
+- keep engineering-assistant responsible for:
+  - plan framing
+  - architectural consistency
+  - integration boundaries
+  - project-memory and change-discipline expectations
+
+## Delegation pattern
+
+1. summarize the subtask in a few concrete bullets
+2. route the task to the specialist skill or knowledge pack
+3. integrate the result back into the broader architecture and delivery plan
+
+## Example
+
+User request: build a UI-heavy WoW addon workflow with architecture and rollout guidance.
+
+- route addon-specific implementation details to the WoW addon skill
+- keep engineering-assistant responsible for architecture choices, workflow coordination, and tracked decision records

package/skills/engineering-assistant/references/solid-and-patterns.md

@@ -0,0 +1,34 @@
+# SOLID and Patterns
+
+Use this reference to keep engineering-assistant output practical and explicit
+rather than abstract for abstraction's sake.
+
+## SOLID priorities
+
+- single responsibility: each module should have one clear reason to change
+- open or closed: extend through composition and policy seams rather than branching everywhere
+- Liskov substitution: verify interface contracts with tests when implementations vary
+- interface segregation: keep interfaces small and split sync versus async or read versus write concerns when useful
+- dependency inversion: point business logic at abstractions and isolate DB, HTTP, FS, and queue details behind boundaries
+
+## Preferred patterns
+
+- dependency injection when construction or orchestration is non-trivial
+- strategy or policy objects for replaceable behavior
+- adapter layers for infrastructure and third-party integration seams
+- factories only when object creation truly needs orchestration
+- specification-style rules for explicit business predicates
+- repositories only when aggregate coordination is complex enough to justify them
+
+## Anti-patterns
+
+- god services with broad ownership and vague boundaries
+- service locators and global state disguised as convenience
+- anemic domains where all real behavior lives in handlers or controllers
+- premature interfaces for everything before behavior actually diverges
+
+## Refactoring guidance
+
+- preserve behavior unless the change explicitly authorizes a semantic shift
+- prefer small, test-backed slices that keep the repo releasable after each step
+- include migration notes when public contracts, persistence formats, or operational behavior change

package/skills/go-engineering/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: go-engineering
+description: go engineering guidance for structured Harness Forge language packs.
+---
+
+# Go Engineering
+
+Use this skill when the repository is primarily Go or when the task touches `.go` or `go.mod`.
+
+## Activation
+
+- Go files dominate the task or repository
+- the work touches packages, services, CLIs, or concurrency-sensitive code
+
+## Load Order
+
+- `rules/common/`
+- `rules/golang/`
+- `knowledge-bases/structured/go/docs/`
+- `knowledge-bases/structured/go/examples/`
+
+## Execution Contract
+
+1. inspect package layout and public API boundaries
+2. select the common and Go-specific rules that fit the task
+3. implement with explicit error handling and interface discipline
+4. verify with the repo build or test path plus the structured checklist
+
+## Outputs
+
+- touched-package summary
+- implementation summary
+- validation result or blocker note
+
+## Validation
+
+- run the repo Go test path when available
+- consult `knowledge-bases/structured/go/docs/review-checklist.md`
+
+## Escalation
+
+- escalate when concurrency, performance, or protocol design risks become non-local
+- escalate when service boundaries remain ambiguous after discovery

package/skills/incident-triage/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: incident-triage
+description: Rapid incident framing for breakages, production regressions, and severe failures.
+---
+
+# Incident Triage
+
+## Trigger Signals
+
+- the task is an outage, regression, or urgent failure
+
+## Inspect First
+
+- failing logs, error output, recent changes, and impacted entrypoints
+
+## Workflow
+
+1. identify blast radius and failure signature
+2. isolate the most likely failing boundary
+3. define contain, mitigate, and verify steps
+4. summarize status and next action
+
+## Output Contract
+
+- incident summary
+- suspected root cause
+- containment plan
+- verification path
+
+## Failure Modes
+
+- no reliable reproduction or telemetry is available
+
+## Escalation
+
+- escalate when the blast radius or data risk is unclear

package/skills/java-engineering/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: java-engineering
+description: Java engineering guidance seeded from the Harness Forge knowledge base.
+origin: Harness Forge
+---
+
+# Java Engineering
+
+Use this skill when the repo contains `.java`, Gradle, or Maven files, or when
+the task involves Spring Boot services, backend modules, or JVM tooling.
+
+## Primary rule sources
+
+- `rules/common/coding-style.md`
+- `rules/common/patterns.md`
+- `rules/common/testing.md`
+- `rules/common/security.md`
+- `rules/common/hooks.md`
+- `rules/java/coding-style.md`
+- `rules/java/patterns.md`
+- `rules/java/testing.md`
+- `rules/java/security.md`
+- `rules/java/hooks.md`
+
+## Seeded references
+
+- `knowledge-bases/seeded/java/docs/overview.md`
+- `knowledge-bases/seeded/java/docs/review-checklist.md`
+- `knowledge-bases/seeded/java/docs/frameworks.md`
+- `knowledge-bases/seeded/java/examples/`
+
+## Supplemental engineering references
+
+- `skills/java-engineering/references/repo-exploration.md`
+- `skills/java-engineering/references/output-templates.md`
+- `skills/java-engineering/references/agent-patterns.md`
+- `skills/java-engineering/references/debugging-playbook.md`
+- `skills/java-engineering/references/build-and-structure.md`
+- `skills/java-engineering/references/spring-patterns.md`
+- `skills/java-engineering/references/testing-concurrency-performance.md`
+- `skills/java-engineering/references/examples.md`
+
+## Assistant expectations
+
+- prefer clear domain boundaries, small services, and explicit contracts
+- keep code idiomatic for modern Java and Spring Boot usage
+- consult the seeded review checklist before finalizing changes
+- use the seeded examples to shape module structure and testing strategy

package/skills/java-engineering/references/agent-patterns.md

@@ -0,0 +1,23 @@
+# Agent Patterns
+
+## General Rules
+- Prefer concrete repository evidence over generic advice.
+- Reuse existing abstractions before introducing new ones.
+- Match surrounding style, naming, and error handling.
+- Produce small reversible changes unless the user asks for a redesign.
+- Call out uncertainty explicitly when repository evidence is missing.
+
+## Research Compression
+When the task looks familiar, do not re-derive common patterns from scratch. Start from these reusable checklists:
+- module layout heuristics
+- dependency injection/composition root detection
+- config loading patterns
+- testing pyramid expectations for the ecosystem
+- release/build/deploy touchpoints
+
+## Examples
+### Good
+"This repo uses a service-repository split; add the feature in the service layer and keep controllers thin."
+
+### Weak
+"You could add a class somewhere in the project."

package/skills/java-engineering/references/build-and-structure.md

@@ -0,0 +1,14 @@
+# Build and Structure
+
+## Check First
+- Maven or Gradle
+- Java version/toolchain
+- module structure
+- package conventions
+- framework bootstrap and auto-configuration points
+
+## Architecture Signals
+- controller/service/repository split
+- ports/adapters boundaries
+- shared utility overuse
+- DTO/entity/domain separation

package/skills/java-engineering/references/debugging-playbook.md

@@ -0,0 +1,24 @@
+# Debugging Playbook
+
+## Triage Flow
+1. Reproduce with the narrowest failing command or input.
+2. Classify: build failure, runtime exception, wrong output, performance regression, flaky behavior.
+3. Inspect the closest automated test or create one.
+4. Trace input -> transformation -> side effects -> output.
+5. Confirm before fixing: logs, assertions, debugger, profiling, or targeted instrumentation.
+
+## Root Cause Buckets
+- environment/config mismatch
+- type or shape mismatch
+- async/concurrency ordering
+- serialization/deserialization drift
+- contract mismatch across module boundaries
+- dependency/version assumptions
+- hidden mutable state or caching
+
+## Fix Quality Bar
+A strong fix should include:
+- minimal blast radius
+- a regression test or reproducible verification
+- removal of dead code or misleading comments when relevant
+- notes on whether backporting is safe

package/skills/java-engineering/references/examples.md

@@ -0,0 +1,15 @@
+# Examples
+
+## Example: Add service method with transactional update
+- validate request at boundary
+- orchestrate in service layer
+- update repository logic with clear transaction semantics
+- add repository/integration coverage
+
+## Example: Debug startup failure
+- inspect auto-configuration, bean dependency cycle, missing properties, profile assumptions
+- narrow to minimal failing context test if possible
+
+## Example: Refactor utility class sprawl
+- move behavior closer to domain or adapter ownership
+- reduce static helper accumulation

package/skills/java-engineering/references/output-templates.md

@@ -0,0 +1,35 @@
+# Output Templates
+
+## Design Review
+### Summary
+- objective
+- constraints
+- recommendation
+
+### Trade-offs
+- chosen path
+- rejected alternatives
+- operational cost
+- migration complexity
+
+## Refactor Plan
+1. Current pain points
+2. Safe seams for change
+3. Stepwise plan
+4. Required tests
+5. Regression risks
+
+## Debugging Report
+- symptom
+- likely root causes
+- evidence to collect
+- fastest confirmation steps
+- proposed fix
+- validation steps
+
+## Patch Proposal
+- scope
+- files likely touched
+- pseudocode or code sketch
+- backward compatibility notes
+- tests

package/skills/java-engineering/references/repo-exploration.md

@@ -0,0 +1,42 @@
+# Repo Exploration Guide
+
+## Goal
+Help the agent map an unfamiliar repository fast without re-researching standard heuristics.
+
+## Exploration Order
+1. Read `README*`, `package.json`, `pyproject.toml`, `pom.xml`, `*.csproj`, `go.mod`, `Cargo.toml`, or equivalent manifest.
+2. Identify entrypoints: CLI, service bootstrap, app host, worker, lambda/function handlers, tests.
+3. Locate dependency boundaries: core domain, infrastructure, adapters, UI, shared libraries.
+4. Inspect CI and automation: `.github/workflows`, `azure-pipelines.yml`, `Jenkinsfile`, `Dockerfile`, IaC.
+5. Inspect tests to infer intended behavior before modifying implementation.
+6. Search for configuration, feature flags, secrets handling, and environment assumptions.
+7. Trace hot paths from public API or command surface inward.
+
+## What to Extract
+- build system and package manager
+- runtime versions and compatibility constraints
+- architecture style (layered, modular monolith, microservice, plugin, hexagonal)
+- naming conventions and folder semantics
+- state boundaries: persistence, cache, external APIs, queues
+- extension points and anti-corruption layers
+- risky areas: reflection, dynamic imports, generated files, migrations, security-sensitive code
+
+## Output Template
+### Repository Map
+- Purpose:
+- Entry points:
+- Build/test commands:
+- Main modules:
+- Persistence/external systems:
+- Cross-cutting concerns:
+- High-risk areas:
+
+### Change Strategy
+- Safe insertion point:
+- Code paths affected:
+- Tests to add/update:
+- Rollback strategy:
+
+## Example
+Input: "Add rate limiting to a Node API repo"
+Output should identify middleware composition, framework bootstrap, shared error handling, config loading, and observability hooks before suggesting a patch.

package/skills/java-engineering/references/spring-patterns.md

@@ -0,0 +1,12 @@
+# Spring Patterns
+
+## Core Guidance
+- keep controllers thin
+- avoid burying business logic in annotations/config classes
+- treat transaction boundaries intentionally
+- prefer constructor injection
+- understand bean lifecycle before introducing dynamic behavior
+
+## Persistence
+- verify fetch behavior and transaction scope
+- avoid exposing JPA entities directly as external contracts when it complicates evolution

package/skills/java-engineering/references/testing-concurrency-performance.md

@@ -0,0 +1,11 @@
+# Testing, Concurrency, Performance
+
+## Testing
+- JUnit 5 by default
+- use slice tests when the repo already relies on them
+- integration tests for persistence and messaging boundaries
+
+## Concurrency and Performance
+- distinguish CPU-bound from I/O-bound workloads
+- watch thread pool ownership and queueing behavior
+- confirm serialization and reflection costs only when they matter on hot paths

package/skills/javascript-engineering/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: javascript-engineering
+description: javascript engineering guidance for node.js, browser apps, clis, and packages. use when .js, .jsx, .mjs, .cjs, bundler config, or package contract behavior dominate the task and a typescript-first pack would be too type-system-centric.
+origin: Harness Forge
+---
+
+# JavaScript Engineering
+
+Use this skill when the repository is JavaScript-first or the task depends more on runtime behavior, packaging, module format, or toolchain quirks than on a TypeScript type system.
+
+## Activation
+
+- JavaScript files, Node runtime behavior, browser bundling, or package publishing dominate the task
+- the repo uses `.js`, `.jsx`, `.mjs`, `.cjs`, or mixed module formats
+- package `exports`, `imports`, CLI behavior, or browser and server boundaries are central to the change
+
+## Load Order
+
+- `rules/common/README.md`
+- `rules/common/coding-style.md`
+- `rules/common/patterns.md`
+- `rules/common/testing.md`
+- `rules/common/security.md`
+- `skills/javascript-engineering/references/`
+- `knowledge-bases/seeded/typescript/docs/frameworks.md` when the repository shares the wider Node, React, or Vite ecosystem
+
+## Execution Contract
+
+1. map entrypoints, scripts, package manager, module system, and bundler behavior before editing code
+2. identify whether the edited code runs in Node, the browser, SSR, workers, or multiple runtimes
+3. preserve public package contracts unless the task explicitly authorizes a breaking change
+4. prefer plain, explicit JavaScript and JSDoc-backed contracts over hidden conventions
+5. validate the actual runtime path and packaging behavior, not just lint output
+
+## Outputs
+
+- touched-file plan grouped by package or runtime boundary
+- implementation or debugging summary with the exact module or packaging seam that changed
+- validation path with lint, test, smoke, and package-contract checks
+- compatibility note when `exports`, entrypoints, or environment assumptions changed
+
+## Validation
+
+- run the repo's preferred test, lint, and smoke commands first
+- confirm Node version, package manager, and lockfile assumptions before touching dependencies or module format
+- inspect `package.json` `type`, `main`, `module`, `exports`, and `imports` when resolution is part of the bug
+- verify browser, SSR, and Node boundaries explicitly when code is shared across environments
+
+## Escalation
+
+- escalate when the repo mixes incompatible ESM, CommonJS, bundler, or runtime assumptions
+- escalate when changing `exports` would break undocumented consumer entrypoints
+- escalate when package publishing, CLI behavior, or deployment constraints are unclear
+
+## Supplemental Engineering References
+
+- `skills/javascript-engineering/references/repo-exploration.md`
+- `skills/javascript-engineering/references/output-templates.md`
+- `skills/javascript-engineering/references/agent-patterns.md`
+- `skills/javascript-engineering/references/debugging-playbook.md`
+- `skills/javascript-engineering/references/ecosystem-guide.md`
+- `skills/javascript-engineering/references/node-service-patterns.md`
+- `skills/javascript-engineering/references/browser-and-bundler-patterns.md`
+- `skills/javascript-engineering/references/package-contracts.md`
+- `skills/javascript-engineering/references/testing-and-debugging.md`
+- `skills/javascript-engineering/references/examples.md`

package/skills/javascript-engineering/references/agent-patterns.md

@@ -0,0 +1,22 @@
+# Agent Patterns
+
+## Non-negotiables
+
+- reason from the real runtime, not from file extensions alone
+- treat package contract changes as semver-sensitive until proven otherwise
+- keep global side effects explicit and localize them to startup or setup modules
+- prefer small reversible edits over sweeping rewrites
+
+## Default implementation bias
+
+- use JSDoc or lightweight schema validation when contracts need clarity
+- keep framework glue separate from reusable core logic
+- centralize environment access and process-level side effects
+- make async startup and shutdown behavior explicit in services and CLIs
+
+## Review questions
+
+- where does this code actually run?
+- which entrypoint or package surface owns the behavior?
+- what consumer contracts might break if imports or exports move?
+- what test or smoke command proves the runtime path still works?

package/skills/javascript-engineering/references/browser-and-bundler-patterns.md

@@ -0,0 +1,14 @@
+# Browser And Bundler Patterns
+
+## Browser boundary rules
+
+- isolate DOM and browser API access from shared pure logic
+- make loading, error, and offline states explicit
+- keep side effects in startup or framework lifecycle hooks
+
+## Bundler review checklist
+
+- confirm aliasing and path resolution
+- inspect code-splitting or lazy-load boundaries
+- verify asset and CSS handling when moving files
+- watch for build-time env replacement that changes runtime behavior

package/skills/javascript-engineering/references/debugging-playbook.md

@@ -0,0 +1,17 @@
+# Debugging Playbook
+
+## Module not found or wrong default export
+
+Inspect `package.json` `type`, `exports`, file extensions, and bundler aliasing first. Many JS bugs are resolution bugs, not logic bugs.
+
+## Works in dev, fails in production bundle
+
+Check tree shaking, side-effect markers, environment replacement, dynamic imports, and whether code depends on path or process behavior that the bundle changes.
+
+## Browser-only failure
+
+Look for Node builtins, server-only secrets, hydration order, or DOM timing assumptions leaking into shared modules.
+
+## Node-only failure
+
+Check environment loading, working-directory assumptions, spawn paths, ESM/CJS interop, and whether tests run transpiled code differently from production.

package/skills/javascript-engineering/references/ecosystem-guide.md

@@ -0,0 +1,19 @@
+# Ecosystem Guide
+
+## Module systems
+
+Node has both CommonJS and ECMAScript modules. The package `type` field and file extensions such as `.mjs` and `.cjs` decide how source is interpreted.
+
+## Packaging
+
+For modern packages, `exports` is the preferred way to define the public interface. It supports multiple entrypoints and encapsulates internal files. Adding it later can be a breaking change if consumers relied on private paths.
+
+## Tooling signals
+
+- ESLint remains the baseline linter for JS projects
+- Vitest is a strong default when the repo is already Vite-oriented
+- browser apps often hide runtime assumptions inside bundler config rather than source files
+
+## Semver note
+
+Public entrypoints, file paths, default vs named export shape, and env-variable behavior are consumer-facing contracts even when the repo does not describe them formally.

package/skills/javascript-engineering/references/examples.md

@@ -0,0 +1,15 @@
+# Examples
+
+## Fix a package export bug
+
+1. inspect `package.json` entrypoints and file extensions
+2. confirm how consumers import the package today
+3. adjust the smallest public surface needed
+4. run the real consumer or smoke path after the change
+
+## Fix a browser and server boundary bug
+
+1. identify where shared code touches runtime-specific APIs
+2. split the boundary or inject the dependency
+3. validate both browser and server entrypoints
+4. confirm the bundle or SSR build still passes

package/skills/javascript-engineering/references/node-service-patterns.md

@@ -0,0 +1,15 @@
+# Node Service Patterns
+
+## Service boundaries
+
+- keep request parsing and auth near the transport edge
+- isolate domain logic from framework glue
+- centralize configuration, logging, and shutdown behavior
+- make retries, timeouts, and concurrency visible in code rather than implicit in nested helpers
+
+## Operational concerns
+
+- validate env vars before startup continues
+- handle process signals and graceful shutdown explicitly
+- avoid unbounded background work tied to request handlers
+- surface health and readiness checks where deployment expects them

package/skills/javascript-engineering/references/output-templates.md

@@ -0,0 +1,17 @@
+# Output Templates
+
+## Patch Proposal
+
+- objective
+- affected runtime or package boundary
+- package or build implications
+- validation path
+- compatibility note
+
+## Runtime Debugging Report
+
+- symptom and failing runtime
+- likely causes ranked by probability
+- confirmation steps
+- proposed fix
+- post-fix checks

package/skills/javascript-engineering/references/package-contracts.md

@@ -0,0 +1,12 @@
+# Package Contracts
+
+## Exports and imports
+
+Use `exports` to define the public package surface. It takes precedence over `main` in modern Node versions, encapsulates unexported subpaths, and is recommended for new packages. Adding `exports` to an existing package is often a breaking change unless every previously supported entrypoint remains exported.
+
+## Safe package changes
+
+- preserve existing consumer entrypoints when possible
+- document default vs named export changes
+- keep `main` aligned with `exports` when compatibility with older tools matters
+- avoid publishing build artifacts with unstable file names when consumers may deep-import them