@harness-forge/cli 0.1.0

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

@@ -0,0 +1,24 @@
+# Repo Exploration
+
+## Inspect these files first
+
+- `package.json` and lockfiles
+- bundler and test config such as Vite, Webpack, Rollup, Vitest, Jest, or Playwright config
+- CLI entrypoint scripts, `bin` declarations, and publish config
+- SSR, serverless, worker, or browser deployment config
+- package `exports`, `imports`, and top-level `type`
+
+## Classify the runtime shape
+
+- **Node service**: request handling, env loading, and operational behavior matter most
+- **Browser app**: bundler, code-splitting, asset handling, and hydration matter
+- **CLI or tooling**: shebangs, path handling, cross-platform spawn behavior, and package publishing matter
+- **Library**: public entrypoints, side effects, tree shaking, and semver matter
+
+## High-signal risk surfaces
+
+- mixed `.cjs` and `.mjs` modules
+- private internal files consumed by downstream imports
+- shared code that assumes both Node and browser globals
+- build output checked into source or consumed by tests
+- root scripts that orchestrate many packages with hidden dependencies

package/skills/javascript-engineering/references/testing-and-debugging.md

@@ -0,0 +1,13 @@
+# Testing And Debugging
+
+## Testing layers
+
+- unit tests for pure modules and boundary adapters
+- integration tests for HTTP, filesystem, process, or browser boundaries
+- smoke tests for published CLI or bundle behavior
+
+## Tooling notes
+
+- ESLint is the baseline static analysis surface for JS repos
+- Vitest is a good fit when the repo already uses Vite because it reuses Vite config and plugins
+- when the repo is Jest-first, extend the existing harness instead of forcing a tool migration inside a feature patch

package/skills/kotlin-engineering/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: kotlin-engineering
+description: kotlin engineering guidance for structured Harness Forge language packs.
+---
+
+# Kotlin Engineering
+
+Use this skill when the repository is primarily Kotlin or when the task touches `.kt`, `.kts`, or Gradle Kotlin DSL.
+
+## Activation
+
+- Kotlin dominates the task or repository
+- the work touches server modules, Android, multiplatform code, or build logic
+
+## Load Order
+
+- `rules/common/`
+- `rules/kotlin/`
+- `knowledge-bases/structured/kotlin/docs/`
+- `knowledge-bases/structured/kotlin/examples/`
+
+## Execution Contract
+
+1. inspect module boundaries, state flow, and platform assumptions
+2. select common and Kotlin-specific rules for the change
+3. implement with explicit nullability, coroutine, and API decisions
+4. verify with the repo test path and the structured checklist
+
+## Outputs
+
+- touched-module summary
+- implementation summary
+- validation result or blocker note
+
+## Validation
+
+- run the repo Kotlin or Gradle validation path when available
+- consult `knowledge-bases/structured/kotlin/docs/review-checklist.md`
+
+## Escalation
+
+- escalate when platform boundaries or concurrency semantics stay ambiguous
+- escalate when the task needs framework guidance beyond the shipped pack

package/skills/lua-engineering/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: lua-engineering
+description: lua engineering guidance seeded from the harness forge knowledge base. use when the repo or task is dominated by .lua files, neovim plugins, openresty, love2d, embedded scripting, luajit, or host-specific lua automation where runtime compatibility matters.
+origin: Harness Forge
+---
+
+# Lua Engineering
+
+Use this skill when the repository is Lua-first and the safest next move depends on runtime flavor, host APIs, coroutine behavior, editor or game integration, or disciplined module boundaries.
+
+## Activation
+
+- the task touches `.lua` files, host-specific Lua config, Neovim plugins, OpenResty services, Love2D gameplay code, or embedded automation
+- the runtime may vary across Lua 5.x, LuaJIT, or a host-specific flavor such as Luau or editor-embedded Lua
+- the change depends on module contracts, async or coroutine behavior, or host lifecycle hooks
+
+## Load Order
+
+- `rules/common/README.md`
+- `rules/common/coding-style.md`
+- `rules/common/patterns.md`
+- `rules/common/testing.md`
+- `rules/common/security.md`
+- `rules/lua/README.md`
+- `rules/lua/coding-style.md`
+- `rules/lua/patterns.md`
+- `rules/lua/testing.md`
+- `rules/lua/security.md`
+- `templates/workflows/implement-lua-change.md`
+- `knowledge-bases/seeded/lua/docs/overview.md`
+- `knowledge-bases/seeded/lua/docs/frameworks.md`
+- `knowledge-bases/seeded/lua/docs/review-checklist.md`
+- `knowledge-bases/seeded/lua/examples/`
+- `skills/lua-engineering/references/`
+
+## Execution Contract
+
+1. identify the active runtime and host before changing code: pure Lua, LuaJIT, Neovim, OpenResty, Love2D, or embedded automation
+2. preserve local module conventions and avoid accidental global state
+3. prefer small table-based modules, explicit contracts, and readable control flow over metatable-heavy cleverness unless the repo already relies on it
+4. treat coroutine, event-loop, and host-lifecycle behavior as first-class design constraints
+5. validate with the host's actual entrypoint, tests, formatting, or language-server checks before finalizing
+
+## Outputs
+
+- touched-file plan grouped by module or host surface
+- implementation or debugging summary with the exact runtime assumption that changed
+- validation path with formatter, tests, host smoke steps, or editor checks
+- compatibility note when the runtime flavor or host API assumptions changed
+
+## Validation
+
+- use the repo's preferred test and formatting path first
+- confirm the target runtime version and host before using syntax or standard-library APIs
+- use LuaLS diagnostics and annotations when the repo already depends on them
+- add or update Busted tests when the code is pure enough to isolate from the host
+- consult `knowledge-bases/seeded/lua/docs/review-checklist.md` before finalizing a patch or design note
+
+## Escalation
+
+- escalate when the repo mixes Lua versions or host APIs with incompatible assumptions
+- escalate when performance-sensitive LuaJIT or FFI behavior is changed without evidence
+- escalate when host lifecycle, coroutine scheduling, or plugin loading order are unclear
+
+## Supplemental Engineering References
+
+- `skills/lua-engineering/references/repo-exploration.md`
+- `skills/lua-engineering/references/output-templates.md`
+- `skills/lua-engineering/references/agent-patterns.md`
+- `skills/lua-engineering/references/debugging-playbook.md`
+- `skills/lua-engineering/references/language-idioms.md`
+- `skills/lua-engineering/references/runtime-profiles.md`
+- `skills/lua-engineering/references/neovim-and-editor-patterns.md`
+- `skills/lua-engineering/references/openresty-patterns.md`
+- `skills/lua-engineering/references/game-and-addon-patterns.md`
+- `skills/lua-engineering/references/debugging-and-testing.md`
+- `skills/lua-engineering/references/tooling-and-quality.md`
+- `skills/lua-engineering/references/examples.md`

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

@@ -0,0 +1,22 @@
+# Agent Patterns
+
+## Non-negotiables
+
+- confirm the runtime flavor before relying on syntax or APIs
+- preserve the repo's module style unless the task explicitly calls for refactor
+- keep implicit globals and side effects out of reusable code
+- prefer simple table-based contracts to hidden metatable magic when clarity matters
+
+## Default implementation bias
+
+- return small module tables from files
+- make state ownership explicit
+- isolate host API access behind adapters when the logic can be tested separately
+- annotate or document table shapes when the repo already uses LuaLS conventions
+
+## Review questions
+
+- which runtime and host executes this code?
+- what event loop or callback model constrains the behavior?
+- where can pure logic be separated from host glue?
+- does this edit rely on LuaJIT-only or host-only behavior?

package/skills/lua-engineering/references/debugging-and-testing.md

@@ -0,0 +1,13 @@
+# Debugging And Testing
+
+## Testing layers
+
+- pure module tests with Busted where practical
+- host smoke tests for plugin, web, or game integration paths
+- formatter and language-server checks for consistency and early diagnostics
+
+## Tooling notes
+
+- Busted is the standard lightweight unit-test surface for many Lua projects
+- StyLua is a strong deterministic formatter across Lua 5.x, LuaJIT, Luau, and CfxLua ecosystems
+- LuaLS provides annotations, diagnostics, and runtime-aware checking that help a lot in mixed host environments

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

@@ -0,0 +1,17 @@
+# Debugging Playbook
+
+## Plugin or script loads but behavior is wrong
+
+Check module load order, returned tables, accidental globals, and whether the host loaded a stale compiled or cached artifact.
+
+## Coroutine or async bug
+
+Trace where a coroutine is created, resumed, and awaited by the host. Many Lua bugs come from assuming a scheduling model the host does not guarantee.
+
+## Host-only failure
+
+Look for editor, web-server, or game-loop lifecycle assumptions. A module that works in isolation can still fail because the host callback order differs from what the code expects.
+
+## Native or FFI issue
+
+Confirm runtime flavor, platform, and library availability before reasoning about Lua logic. Native-boundary bugs often look like ordinary Lua failures until you inspect the binding layer.

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

@@ -0,0 +1,15 @@
+# Examples
+
+## Add a Neovim feature safely
+
+1. split setup wiring from core behavior
+2. keep keymaps and commands near startup code
+3. test pure logic separately from editor state
+4. validate with a real editor session or health check
+
+## Fix an OpenResty bug
+
+1. identify request phase and shared state use
+2. confirm the APIs are nonblocking for that phase
+3. add the smallest fix that preserves worker and request behavior
+4. run the repo's integration or smoke path

package/skills/lua-engineering/references/game-and-addon-patterns.md

@@ -0,0 +1,15 @@
+# Game And Addon Patterns
+
+## Love2D and frame-loop code
+
+Keep update, draw, input, and asset lifecycle concerns explicit. Avoid hidden cross-frame mutation that makes gameplay or UI bugs hard to reproduce.
+
+## Addon or mod ecosystems
+
+Respect host load order, config discovery, and sandbox rules. Prefer additive hooks and stable extension points over monkey-patching shared globals unless the host ecosystem already expects that pattern.
+
+## State management
+
+- isolate frame or tick updates
+- keep save-data schema changes explicit
+- document deterministic vs time-based behavior when debugging gameplay issues

package/skills/lua-engineering/references/language-idioms.md

@@ -0,0 +1,16 @@
+# Language Idioms
+
+## Prefer
+
+- local scope by default
+- small returned module tables
+- explicit function arguments over mutable ambient state
+- simple tables for data carriers and clear metamethod use only where it adds real leverage
+- readable loops and guards over dense one-liners
+
+## Use caution with
+
+- deep metatable chains that hide behavior
+- mutation of shared tables from many modules
+- version-specific syntax without a runtime check
+- dynamic code loading unless the repo already uses it intentionally

package/skills/lua-engineering/references/neovim-and-editor-patterns.md

@@ -0,0 +1,17 @@
+# Neovim And Editor Patterns
+
+## Plugin structure
+
+- separate user-facing setup from core logic
+- keep autocmds, keymaps, and commands near startup wiring
+- isolate editor API calls so pure logic can be tested or reasoned about separately
+
+## LSP and tooling
+
+The modern Neovim LSP path prefers `vim.lsp.config` and `vim.lsp.enable` on newer Neovim versions. Legacy `require('lspconfig')` setup is deprecated in the upstream config project.
+
+## Debugging tips
+
+- use `:checkhealth` for environment issues
+- verify runtimepath and lazy-loading assumptions
+- check whether a plugin manager changed load order or optional dependency timing

package/skills/lua-engineering/references/openresty-patterns.md

@@ -0,0 +1,15 @@
+# OpenResty Patterns
+
+## Request-phase awareness
+
+Know which NGINX phase the code runs in before changing behavior. Request rewriting, access checks, content generation, timers, and worker init all have different constraints.
+
+## Nonblocking discipline
+
+Prefer host-approved nonblocking APIs and shared libraries already used by the repo. Do not assume that generic Lua socket or filesystem behavior is safe inside a latency-sensitive request path.
+
+## Operational checks
+
+- verify worker initialization behavior
+- note shared dictionary or cache dependencies
+- keep per-request allocations and logging under control on hot paths

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

@@ -0,0 +1,17 @@
+# Output Templates
+
+## Patch Proposal
+
+- objective
+- active runtime and host
+- affected modules and contracts
+- validation path
+- compatibility note
+
+## Debugging Report
+
+- symptom and host surface
+- likely root causes ranked by probability
+- confirmation steps
+- proposed fix
+- validation steps

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

@@ -0,0 +1,25 @@
+# Repo Exploration
+
+## Inspect these files first
+
+- top-level Lua entrypoints and module layout
+- host config for Neovim, OpenResty, game loops, or embedded runtimes
+- test config, formatter config, and language-server settings
+- any FFI bindings, C modules, or native build steps
+- README or docs that describe runtime version and startup order
+
+## Classify the runtime shape
+
+- **Pure Lua library**: module boundaries and table contracts matter most
+- **Neovim plugin**: editor lifecycle, autocmds, user commands, and LSP integration matter
+- **OpenResty**: request phases, worker lifecycle, and nonblocking behavior matter
+- **Love2D or game code**: frame loop, input, and asset lifecycle matter
+- **Embedded automation**: host callbacks, sandboxing, and IO limits matter
+
+## High-signal risk surfaces
+
+- accidental globals and mutable shared tables
+- coroutine scheduling across host callbacks
+- runtime-version-specific syntax or library use
+- metatable behavior that changes public contracts implicitly
+- FFI or native-boundary code paths

package/skills/lua-engineering/references/runtime-profiles.md

@@ -0,0 +1,12 @@
+# Runtime Profiles
+
+## Lua 5.x and LuaJIT
+
+Check the exact runtime before using standard-library behavior, integer semantics, or performance assumptions. LuaLS supports multiple Lua versions and LuaJIT, which makes it useful for catching version drift in mixed environments.
+
+## Host-specific rules
+
+- **Neovim**: editor APIs, runtimepath, and lazy loading shape module boundaries
+- **OpenResty**: request phases and nonblocking IO rules matter more than generic Lua advice
+- **Love2D**: frame lifecycle and asset handling define safe state boundaries
+- **Embedded hosts**: sandboxing and API availability may be narrower than stock Lua

package/skills/lua-engineering/references/tooling-and-quality.md

@@ -0,0 +1,16 @@
+# Tooling And Quality
+
+## Good defaults when the repo supports them
+
+- StyLua for formatting
+- LuaLS for diagnostics, annotations, and editor support
+- Busted for unit tests
+- host-native smoke checks for lifecycle-sensitive behavior
+
+## Review checklist
+
+- confirm runtime version
+- confirm host API assumptions
+- check for accidental globals
+- verify coroutine or callback ordering
+- validate with the real host entrypoint when integration matters

package/skills/observability-and-eval/SKILL.md

@@ -0,0 +1,6 @@
+# Observability And Eval
+
+Use this skill when local events, derived summaries, or benchmark expectations
+need to be inspected or updated.
+
+Prefer local, reproducible artifacts over external telemetry.

package/skills/observability-setup/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: observability-setup
+description: Define local-first logging, metrics, and diagnostic signals for a runtime surface.
+---
+
+# Observability Setup
+
+## Trigger Signals
+
+- the task needs better local diagnostics or effectiveness tracking
+
+## Inspect First
+
+- runtime entrypoints, existing logs, metrics, and failure reporting surfaces
+
+## Workflow
+
+1. identify the signals worth recording
+2. choose low-risk local-first storage
+3. define summary and reporting needs
+4. recommend the smallest useful setup
+
+## Output Contract
+
+- signal inventory
+- storage approach
+- reporting approach
+
+## Failure Modes
+
+- the task lacks a clear runtime boundary to instrument
+
+## Escalation
+
+- escalate when observability requirements imply privacy or performance tradeoffs

package/skills/parallel-worktree-supervisor/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: parallel-worktree-supervisor
+description: plan and supervise low-overlap parallel work across git worktrees or stacked branches. use when a backlog could be split safely, when multiple small dependent changes need reviewable sequencing, or when merge-blocking risks must be made explicit before parallel execution.
+---
+
+# Parallel Worktree Supervisor
+
+## Trigger Signals
+
+- the backlog could be split into low-overlap tracks with clear ownership boundaries
+- multiple small dependent changes need stacked review instead of one giant branch
+- the team wants explicit merge blockers, rebase rules, and validation gates before parallel execution
+
+## Inspect First
+
+- task list or issue graph, including dependencies and shared prerequisites
+- repo hotspots such as root config, lockfiles, generated artifacts, migrations, and shared contracts
+- code ownership, test entrypoints, and branch protection or merge expectations
+- whether worktrees, stacked branches, or plain feature branches are already in use
+
+## Workflow
+
+1. map tasks by dependency, risk, and shared-file overlap
+2. carve the work into tracks that minimize contention on root config, generated files, and public contracts
+3. assign a branch or worktree plan with base branch, stack order, and merge blockers
+4. define rebase cadence, validation gates, and when a track must pause for another track to land
+5. report status in terms of ready, blocked, risky overlap, or merge-ready
+
+## Output Contract
+
+- sharding plan with branch or worktree names and ownership notes
+- explicit dependency graph and merge order
+- overlap hotspots and the files or contracts that make them risky
+- validation and rebase expectations for each track
+
+## Failure Modes
+
+- hidden coupling means the work is not actually independent enough to parallelize
+- the repo relies on shared generated files, lockfiles, or root config that every track must touch
+- there is no trustworthy validation path to catch skew between branches
+
+## Escalation
+
+- escalate when a schema, API, or root-build change affects multiple tracks at once
+- escalate when stacked branches become too interdependent to review independently
+- escalate when branch protection, review ownership, or release timing constraints are unclear
+
+## References
+
+- `skills/parallel-worktree-supervisor/references/task-sharding-rules.md`
+- `skills/parallel-worktree-supervisor/references/worktree-operations.md`
+- `skills/parallel-worktree-supervisor/references/stacked-diffs-and-review.md`
+- `skills/parallel-worktree-supervisor/references/merge-readiness.md`
+- `skills/parallel-worktree-supervisor/references/output-template.md`
+- `skills/parallel-worktree-supervisor/references/examples.md`

package/skills/parallel-worktree-supervisor/references/examples.md

@@ -0,0 +1,14 @@
+# Examples
+
+## Good split
+
+- track 1: add shared API contract and fixtures
+- track 2: provider implementation against the new contract
+- track 3: consumer UI updates after the provider contract lands
+- merge order: 1, then 2 and 3 as dependencies clear
+
+## Bad split
+
+- every track edits the same root config, migration, and shared schema file
+- one track cannot validate until all others are merged
+- result: do not parallelize; sequence the work instead

package/skills/parallel-worktree-supervisor/references/merge-readiness.md

@@ -0,0 +1,15 @@
+# Merge Readiness
+
+## A track is merge-ready when
+
+- its direct prerequisites are landed or no longer required
+- validation passes in the same shape the base branch expects
+- conflict hotspots were rebased recently enough to trust the diff
+- no hidden dependency on unpublished generated output or local-only state remains
+
+## Merge blockers to call out explicitly
+
+- schema or API prerequisites not landed yet
+- lockfile or root-config conflicts likely on rebase
+- failing tests caused by another branch's unpublished changes
+- code-owner or release-window constraints

package/skills/parallel-worktree-supervisor/references/output-template.md

@@ -0,0 +1,16 @@
+# Output Template
+
+## Track Table
+
+- track name
+- base branch or parent track
+- objective
+- likely files or contracts touched
+- blockers
+- validation path
+
+## Overall Notes
+
+- shared hotspots
+- recommended merge order
+- when to pause parallelization and collapse back to a single stream

package/skills/parallel-worktree-supervisor/references/stacked-diffs-and-review.md

@@ -0,0 +1,17 @@
+# Stacked Diffs And Review
+
+## When to stack instead of shard
+
+Use stacked branches when each change logically depends on the previous one but is still small enough to review on its own.
+
+## Best practices
+
+- keep each diff narrow and coherent
+- make dependencies explicit in the branch order
+- rebase the stack regularly onto the base branch or the previous landed diff
+- merge from the bottom of the stack upward
+- do not hide unrelated cleanup inside a dependency stack
+
+## Review rule
+
+A stack should speed review, not create archaeology. If reviewers cannot understand a diff without reading the whole stack, the slices are wrong.

package/skills/parallel-worktree-supervisor/references/task-sharding-rules.md

@@ -0,0 +1,22 @@
+# Task Sharding Rules
+
+## Good split signals
+
+- packages or services with clean ownership boundaries
+- additive work that touches separate source roots
+- changes that can be reviewed and validated independently
+- one shared prerequisite followed by several independent follow-up tracks
+
+## Bad split signals
+
+- one migration or contract change every track depends on immediately
+- repo-wide formatting or config edits mixed with feature work
+- shared generated artifacts or lockfiles touched by all tracks
+- a cross-cutting refactor disguised as many small tasks
+
+## Preferred strategy
+
+- isolate the prerequisite or high-risk seam first
+- keep follow-up tracks small and purpose-built
+- sequence contract or schema changes ahead of consumer updates when possible
+- leave root-level cleanup or broad modernization for a dedicated track, not mixed into feature branches

package/skills/parallel-worktree-supervisor/references/worktree-operations.md

@@ -0,0 +1,16 @@
+# Worktree Operations
+
+## Core commands and hygiene
+
+Git worktree lets one repository manage multiple working trees attached to different branches. Use it when contributors need isolated working directories without cloning the repo repeatedly.
+
+## Practical rules
+
+- create one worktree per track with a clear branch name
+- keep each worktree focused on a single reviewable objective
+- prune and remove stale worktrees when tracks land or are abandoned
+- lock long-lived worktrees only when there is a real reason to protect them from pruning
+
+## Operational caution
+
+Worktrees solve filesystem isolation, not dependency management. Shared caches, generated files, or external environments can still create cross-track interference.

package/skills/performance-profiling/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: performance-profiling
+description: Profile likely hotspots and turn performance work into measurable next steps.
+---
+
+# Performance Profiling
+
+## Trigger Signals
+
+- the task is slow, resource-heavy, or performance-sensitive
+
+## Inspect First
+
+- hotspot code paths, timing data, memory cues, and benchmark surfaces
+
+## Workflow
+
+1. identify the slow path and measurement surface
+2. isolate likely bottlenecks
+3. define low-risk experiments and verification
+4. report findings and next action
+
+## Output Contract
+
+- hotspot summary
+- likely bottlenecks
+- measurement or benchmark plan
+- recommended next step
+
+## Failure Modes
+
+- no measurable baseline exists
+
+## Escalation
+
+- escalate when optimization risks correctness or public contracts