@harness-forge/cli 0.1.0

package/skills/perl-engineering/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: perl-engineering
+description: perl engineering guidance for structured Harness Forge language packs.
+---
+
+# Perl Engineering
+
+Use this skill when the repository is primarily Perl or when the task touches `.pl`, `.pm`, or legacy automation built in Perl.
+
+## Activation
+
+- Perl dominates the task or repository
+- the work touches legacy automation, modules, or compatibility-sensitive code
+
+## Load Order
+
+- `rules/common/`
+- `rules/perl/`
+- `knowledge-bases/structured/perl/docs/`
+- `knowledge-bases/structured/perl/examples/`
+
+## Execution Contract
+
+1. inspect module boundaries, runtime expectations, and compatibility constraints
+2. select the common and Perl-specific rules for the change
+3. implement with explicit package, testing, and risk decisions
+4. verify with the repo Perl validation path and the structured checklist
+
+## Outputs
+
+- touched-module summary
+- implementation summary
+- validation result or blocker note
+
+## Validation
+
+- run the repo Perl test path when available
+- consult `knowledge-bases/structured/perl/docs/review-checklist.md`
+
+## Escalation
+
+- escalate when runtime version compatibility or legacy coupling is unclear
+- escalate when the change affects broad automation behavior

package/skills/php-engineering/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: php-engineering
+description: php engineering guidance for structured Harness Forge language packs.
+---
+
+# PHP Engineering
+
+Use this skill when the repository is primarily PHP or when the task touches `.php` or `composer.json`.
+
+## Activation
+
+- PHP dominates the task or repository
+- the work touches application, API, package, or framework code
+
+## Load Order
+
+- `rules/common/`
+- `rules/php/`
+- `knowledge-bases/structured/php/docs/`
+- `knowledge-bases/structured/php/examples/`
+
+## Execution Contract
+
+1. inspect framework or application entrypoints and service boundaries
+2. select the common and PHP-specific rules for the change
+3. implement with explicit validation, DI, and data-flow decisions
+4. verify with the repo PHP validation path and the structured checklist
+
+## Outputs
+
+- touched-module summary
+- implementation summary
+- validation result or blocker note
+
+## Validation
+
+- run the repo PHP test path when available
+- consult `knowledge-bases/structured/php/docs/review-checklist.md`
+
+## Escalation
+
+- escalate when framework behavior is under-specified by the current pack
+- escalate when routing, migration, or container changes affect broad surfaces

package/skills/powershell-engineering/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: powershell-engineering
+description: PowerShell engineering guidance seeded from the Harness Forge knowledge base.
+origin: Harness Forge
+---
+
+# PowerShell Engineering
+
+Use this skill when the repo contains `.ps1`, `.psm1`, or `.psd1` files, or
+when the task involves automation, administration, CI scripting, or Windows-focused 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/powershell/coding-style.md`
+- `rules/powershell/patterns.md`
+- `rules/powershell/testing.md`
+- `rules/powershell/security.md`
+- `rules/powershell/hooks.md`
+
+## Seeded references
+
+- `knowledge-bases/seeded/powershell/docs/overview.md`
+- `knowledge-bases/seeded/powershell/docs/review-checklist.md`
+- `knowledge-bases/seeded/powershell/docs/frameworks.md`
+- `knowledge-bases/seeded/powershell/examples/`
+
+## Supplemental engineering references
+
+- `skills/powershell-engineering/references/repo-exploration.md`
+- `skills/powershell-engineering/references/output-templates.md`
+- `skills/powershell-engineering/references/agent-patterns.md`
+- `skills/powershell-engineering/references/debugging-playbook.md`
+- `skills/powershell-engineering/references/scripting-and-modules.md`
+- `skills/powershell-engineering/references/remoting-and-ops.md`
+- `skills/powershell-engineering/references/testing-and-ci.md`
+- `skills/powershell-engineering/references/examples.md`
+
+## Assistant expectations
+
+- write scripts that are explicit, safe, and compatible with modern PowerShell
+- favor parameterized commands, clear output, and idempotent automation
+- apply the review checklist before completing operational scripts
+- use the seeded examples to shape module, CI, and bootstrap flows

package/skills/powershell-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/powershell-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/powershell-engineering/references/examples.md

@@ -0,0 +1,17 @@
+# Examples
+
+## Example: Convert admin script into module command
+- extract reusable function with approved verb-noun name
+- add parameter validation and pipeline support
+- return objects and keep formatting in wrapper/example usage
+- add Pester tests
+
+## Example: Safe bulk operation
+- implement `SupportsShouldProcess`
+- dry-run by default when repository patterns support it
+- emit summary object with successes/failures
+
+## Example: Debug remoting failure
+- isolate auth vs network vs endpoint config
+- log target/session details
+- retry only when the operation is safe and idempotent

package/skills/powershell-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/powershell-engineering/references/remoting-and-ops.md

@@ -0,0 +1,12 @@
+# Remoting and Operations
+
+## Remoting Guidance
+- detect whether the repo uses WinRM, SSH remoting, Azure automation, or custom orchestration
+- fail clearly on connectivity/auth issues
+- design for idempotency when acting on infrastructure
+- log enough context for later operational triage
+
+## Safety
+- support `-WhatIf` and confirmation where appropriate
+- avoid global preference mutation unless scoped and restored
+- treat credentials and secrets explicitly

package/skills/powershell-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/powershell-engineering/references/scripting-and-modules.md

@@ -0,0 +1,14 @@
+# Scripting and Modules
+
+## Design Rules
+- Prefer advanced functions for reusable automation.
+- Support pipeline input intentionally.
+- Separate discovery, transformation, and side effects.
+- Use approved verbs and meaningful noun names.
+- Prefer modules over monolithic script folders when reuse matters.
+
+## Function Shape
+- parameter validation
+- begin/process/end only when pipeline semantics require it
+- `SupportsShouldProcess` for destructive operations
+- return objects, not formatted text, from reusable functions

package/skills/powershell-engineering/references/testing-and-ci.md

@@ -0,0 +1,11 @@
+# Testing and CI
+
+## Testing
+- Pester for unit and integration tests
+- isolate filesystem/process/network dependencies behind functions when feasible
+- assert object shape and side effects separately
+
+## CI
+- verify PowerShell edition and OS matrix assumptions
+- keep scripts non-interactive in automation contexts
+- prefer structured errors over host-only messaging

package/skills/pr-triage-and-summary/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: pr-triage-and-summary
+description: Turn a change set into a concise implementation and risk summary.
+---
+
+# PR Triage And Summary
+
+## Trigger Signals
+
+- the task needs a concise reviewable summary of a large diff
+
+## Inspect First
+
+- changed files, tests, docs, and validation evidence
+
+## Workflow
+
+1. identify the main change areas
+2. summarize risks and missing validation
+3. compress the diff into reviewable outcomes
+4. emit a short handoff summary
+
+## Output Contract
+
+- change summary
+- validation summary
+- open risks or questions
+
+## Failure Modes
+
+- the diff is too large to summarize safely without slicing it first
+
+## Escalation
+
+- escalate when the change mixes unrelated scopes or lacks validation evidence

package/skills/python-engineering/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: python-engineering
+description: python engineering guidance for structured Harness Forge language packs.
+---
+
+# Python Engineering
+
+Use this skill when the repository is primarily Python or when the task touches `.py`, `pyproject.toml`, or `requirements.txt`.
+
+## Activation
+
+- Python files dominate the task or repository
+- the work touches packaging, services, automation, or framework code
+
+## Load Order
+
+- `rules/common/`
+- `rules/python/`
+- `knowledge-bases/structured/python/docs/`
+- `knowledge-bases/structured/python/examples/`
+- `skills/python-engineering/references/`
+
+## Execution Contract
+
+1. orient on module boundaries, entrypoints, and the active framework
+2. select the Python and common rule files that constrain the change
+3. implement with explicit typing, validation, and dependency choices
+4. verify with the repo test path and the structured review checklist
+
+## Outputs
+
+- touched-file plan
+- implementation summary
+- validation result or blocker note
+
+## Validation
+
+- run the repo's Python verification path when available
+- consult `knowledge-bases/structured/python/docs/review-checklist.md`
+- use the supplemental reference pack when the task needs ecosystem, async, or debugging heuristics not covered in the structured pack
+
+## Supplemental Engineering References
+
+- `skills/python-engineering/references/repo-exploration.md`
+- `skills/python-engineering/references/output-templates.md`
+- `skills/python-engineering/references/agent-patterns.md`
+- `skills/python-engineering/references/debugging-playbook.md`
+- `skills/python-engineering/references/ecosystem-guide.md`
+- `skills/python-engineering/references/async-and-concurrency.md`
+- `skills/python-engineering/references/testing-and-quality.md`
+- `skills/python-engineering/references/examples.md`
+
+## Escalation
+
+- escalate when a framework pattern is missing from the structured pack
+- escalate when deployment, dependency, or typing constraints conflict with the repo

package/skills/python-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/python-engineering/references/async-and-concurrency.md

@@ -0,0 +1,19 @@
+# Async and Concurrency
+
+## When to Use asyncio
+Use asyncio when the workload is I/O bound and the ecosystem already exposes async APIs.
+
+## Rules
+- Do not mix sync and async haphazardly; make boundary adapters explicit.
+- Avoid blocking calls inside async paths.
+- Use timeouts, cancellation propagation, and context-aware cleanup.
+- Prefer task groups or structured concurrency patterns when available.
+
+## Common Pitfalls
+- calling synchronous DB or HTTP clients in async handlers
+- fire-and-forget tasks without lifecycle ownership
+- hidden event loop assumptions in tests
+- mutable shared state across async tasks
+
+## Example
+A FastAPI handler should delegate to async service functions only if the underlying client stack is async end-to-end.

package/skills/python-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/python-engineering/references/ecosystem-guide.md

@@ -0,0 +1,32 @@
+# Python Ecosystem Guide
+
+## Default Assumptions
+- Prefer Python 3.11+ idioms unless repository constraints say otherwise.
+- Prefer `pyproject.toml` over legacy packaging files when the repo supports it.
+- Use type hints for public APIs and non-trivial internal flows.
+- Prefer `pathlib`, `dataclasses`, `enum`, and `typing` over ad hoc utility code.
+
+## Project Shapes
+### Library
+- public API in a stable package root
+- limited side effects at import time
+- semantic versioning awareness
+- docs/examples close to API
+
+### Service
+- clear composition root
+- config boundary separated from domain logic
+- structured logging and health probes
+- dependencies injected instead of globally imported singletons
+
+### CLI Tool
+- thin entrypoint
+- parsing isolated from execution
+- machine-readable exit/error behavior
+- support for dry-run where practical
+
+## Packaging Heuristics
+- `src/` layout is safer for libraries.
+- Use extras for optional capabilities.
+- Pin narrowly for applications, loosely for libraries.
+- Put dev tooling config in `pyproject.toml` when available.

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

@@ -0,0 +1,19 @@
+# Examples
+
+## Example: Add a repository-backed service feature
+1. Extend request/DTO schema.
+2. Add domain-level validation.
+3. Update service method.
+4. Add repository query or persistence logic.
+5. Add unit test for validation and integration test for persistence.
+
+## Example: Fix async timeout bug
+- Symptom: requests hang under load.
+- Investigation: inspect HTTP client timeout defaults, retry policy, cancellation handling.
+- Fix: explicit timeout config + cancellation-aware awaits + regression test using a delayed fake server.
+
+## Example: Refactor script into package
+- move logic from monolithic script to package modules
+- keep thin CLI entrypoint
+- preserve backward-compatible command surface
+- add smoke test for CLI and focused unit tests for extracted logic

package/skills/python-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/python-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/python-engineering/references/testing-and-quality.md

@@ -0,0 +1,16 @@
+# Testing and Quality
+
+## Testing Strategy
+- Unit tests for domain logic and transformations.
+- Integration tests for persistence, HTTP clients, queues, and framework glue.
+- Property or table-driven tests for parsers and edge-case-heavy logic.
+
+## Tooling Defaults
+- `pytest`
+- `pytest-asyncio` for async code
+- `hypothesis` where generative coverage matters
+- type checking via `pyright` or `mypy`
+- formatting/linting via `ruff`
+
+## Agent Guidance
+Before proposing a patch, look for the nearest existing test style and mirror it.