@harness-forge/cli 0.1.0

package/skills/db-migration-review/references/expand-contract.md

@@ -0,0 +1,19 @@
+# Expand And Contract
+
+## Default rollout shape
+
+1. **Expand**: add new columns, tables, indexes, or write paths in a backward-compatible way
+2. **Dual-read or dual-write when needed**: let old and new application versions coexist safely
+3. **Backfill**: migrate existing data in resumable chunks with checkpointing and monitoring
+4. **Contract**: remove old columns or code paths only after traffic proves the new path is stable
+
+## Good questions
+
+- can old binaries run against the new schema?
+- can new binaries run before the backfill finishes?
+- is there a safe intermediate state for blue-green or rolling deploys?
+- what proves the contract phase is safe to execute later?
+
+## Common trap
+
+Schema tools often make additive changes easy and destructive changes too easy. A safe review always asks how mixed-version application traffic behaves between those two phases.

package/skills/db-migration-review/references/review-template.md

@@ -0,0 +1,25 @@
+# Review Template
+
+## Change Summary
+
+- schema changes
+- data movement changes
+- application rollout dependencies
+
+## Risk Verdict
+
+- level: low, medium, high, or blocked
+- why that level is justified
+
+## Compatibility Window
+
+- old app against new schema
+- new app before backfill completes
+- contract conditions for cleanup
+
+## Rollout Plan
+
+- deploy order
+- backfill strategy
+- observability or validation steps
+- rollback or forward-fix plan

package/skills/db-migration-review/references/risk-taxonomy.md

@@ -0,0 +1,30 @@
+# Risk Taxonomy
+
+## Usually low risk
+
+- adding nullable columns
+- adding non-blocking indexes with an engine-appropriate strategy
+- additive tables not yet referenced by production traffic
+- additive enum or lookup values where consumers tolerate them
+
+## Medium risk
+
+- tightening nullability after a backfill
+- renaming columns or tables when the migration tool may emit drop-and-create SQL
+- adding unique constraints after validating existing data
+- large backfills that are chunked but still compete with production load
+
+## High risk
+
+- dropping columns, tables, indexes, or enum values still used by live code
+- type narrowing or incompatible default changes
+- table rewrites on hot paths
+- online migrations that depend on exact replica, trigger, or cut-over behavior
+- mixed app and schema rollouts without an intermediate compatibility window
+
+## Block until clarified
+
+- no rollback or forward-fix strategy
+- backfill logic cannot resume safely
+- generated SQL is unavailable for a complex migration
+- production traffic shape, table size, or engine is unknown for a potentially invasive change

package/skills/db-migration-review/references/rollout-and-backfill.md

@@ -0,0 +1,23 @@
+# Rollout And Backfill
+
+## Backfill rules
+
+- chunk work by a stable key or bounded window
+- checkpoint progress so the job can resume safely
+- make the job idempotent
+- throttle to protect hot paths and replicas
+- emit metrics for rows processed, lag, failures, and remaining work
+
+## Rollout checks
+
+- deployment order between schema, app, and backfill job
+- whether reads and writes remain correct before the backfill completes
+- whether monitoring can distinguish migration-induced errors from ordinary traffic noise
+- whether rollback means actual rollback or forward-fix with a new migration
+
+## Verification ideas
+
+- row count parity between old and new shapes
+- null or default-value audits
+- duplicate detection before adding uniqueness constraints
+- query plans on new indexes for hot endpoints

package/skills/db-migration-review/references/tooling-signals.md

@@ -0,0 +1,21 @@
+# Tooling Signals
+
+## Flyway and Liquibase
+
+Treat ordered migration history as the source of truth and check whether rollback scripts or rollback metadata actually exist. Repeatable migrations, checksums, and environment drift are part of the review surface.
+
+## Prisma
+
+When a rename or data-preserving change is needed, prefer customizing the generated SQL instead of accepting a destructive drop-and-recreate plan. Expand-and-contract is the default safe posture for production data movement.
+
+## EF Core
+
+Inspect the generated migration and script output. Renames, seed changes, and default-value changes can hide data-loss or locking issues behind innocent-looking model edits.
+
+## Atlas
+
+Declarative diffs are powerful, but the review still has to reason about the actual engine-specific statements and rollout order.
+
+## Online migration tools
+
+Tools such as gh-ost can reduce MySQL lock risk, but they add requirements around cut-over, replica health, throttling, and operational supervision.

package/skills/dependency-upgrade-safety/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: dependency-upgrade-safety
+description: Review and stage dependency upgrades with compatibility and rollback awareness.
+---
+
+# Dependency Upgrade Safety
+
+## Trigger Signals
+
+- the task upgrades packages, libraries, SDKs, or frameworks
+
+## Inspect First
+
+- dependency manifests, lockfiles, changelogs, and affected entrypoints
+
+## Workflow
+
+1. identify changed packages and affected surfaces
+2. evaluate compatibility and migration risk
+3. define validation and rollback expectations
+4. summarize upgrade safety status
+
+## Output Contract
+
+- upgrade impact summary
+- compatibility risks
+- validation plan
+- rollback note
+
+## Failure Modes
+
+- release notes or migration notes are missing
+
+## Escalation
+
+- escalate when the upgrade changes a critical runtime contract

package/skills/documentation-lookup/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: documentation-lookup
+description: Find the right docs, templates, and catalog entries inside Harness Forge before improvising.
+---
+
+# Documentation Lookup
+
+## Trigger Signals
+
+- the task needs the canonical docs surface before implementation
+- there are multiple possible rules, frameworks, or templates and guessing would be risky
+
+## Inspect First
+
+- `docs/catalog/`
+- `rules/`
+- `skills/`
+- `templates/workflows/`
+
+## Workflow
+
+1. identify the dominant language, framework, or workflow intent
+2. find the most specific canonical doc surfaces
+3. summarize the minimum required guidance and unresolved gaps
+4. point the caller to the exact files to load next
+
+## Output Contract
+
+- recommended doc paths
+- why those paths match the task
+- unresolved gaps or ambiguity notes
+
+## Failure Modes
+
+- multiple docs surfaces conflict materially
+- no specific framework or language match exists
+
+## Escalation
+
+- escalate when the canonical docs disagree with shipped runtime behavior
+- escalate when the missing docs would make implementation unsafe
+
+## References
+
+- `skills/documentation-lookup/references/source-priority.md`

package/skills/documentation-lookup/references/source-priority.md

@@ -0,0 +1,6 @@
+# Documentation Source Priority
+
+1. exact language or framework pack docs
+2. matching rules directory
+3. matching skill and workflow
+4. broader catalog or front-door docs

package/skills/dotnet-engineering/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: dotnet-engineering
+description: .net and c# engineering guidance seeded from the harness forge knowledge base. use when the repo or task is dominated by .cs, .csproj, .sln, asp.net core, ef core, worker services, cli tooling, test projects, or modern distributed .net surfaces such as aspire.
+origin: Harness Forge
+---
+
+# .NET Engineering
+
+Use this skill when the repository or task is clearly .NET-first and the best next move depends on understanding project layout, dependency injection, hosting, data access, or the package and test graph.
+
+## Activation
+
+- the task touches `.cs`, `.csproj`, `.sln`, `Directory.Build.props`, `global.json`, or `Directory.Packages.props`
+- the repo is an ASP.NET Core app, worker service, library pack, CLI, test harness, or Aspire-oriented distributed app
+- runtime behavior depends on DI lifetimes, configuration binding, logging, background execution, or EF Core
+
+## Load Order
+
+- `rules/common/README.md`
+- `rules/common/coding-style.md`
+- `rules/common/patterns.md`
+- `rules/common/testing.md`
+- `rules/common/security.md`
+- `rules/dotnet/README.md`
+- `rules/dotnet/coding-style.md`
+- `rules/dotnet/patterns.md`
+- `rules/dotnet/testing.md`
+- `rules/dotnet/security.md`
+- `templates/workflows/implement-dotnet-change.md`
+- `knowledge-bases/seeded/dotnet/docs/overview.md`
+- `knowledge-bases/seeded/dotnet/docs/frameworks.md`
+- `knowledge-bases/seeded/dotnet/docs/review-checklist.md`
+- `knowledge-bases/seeded/dotnet/examples/`
+- `skills/dotnet-engineering/references/`
+
+## Execution Contract
+
+1. map the solution graph before editing code: startup project, shared libraries, test projects, migration surfaces, and deployment entrypoints
+2. determine the composition root and preserve local boundaries instead of inventing new layers
+3. prefer constructor injection, explicit options binding and validation, and cancellation-aware async flows
+4. keep transport concerns at the edge and domain behavior in reusable services, handlers, or application modules
+5. when persistence changes, inspect the generated migration or SQL, mixed-version compatibility window, and rollback or forward-fix path
+6. when hosting changes, verify logging, health, configuration, and observability assumptions at the same time as the code change
+
+## Outputs
+
+- touched-file plan grouped by project or layer
+- implementation summary with the exact runtime seam that changed
+- validation path with build, test, or smoke commands
+- migration or rollout note when data access, hosting, or package boundaries changed
+
+## Validation
+
+- use the repo's preferred .NET entrypoints first; otherwise fall back to targeted `dotnet build`, `dotnet test`, or solution-level validation
+- inspect `global.json`, central package management, analyzers, and nullable settings before changing code style or package versions
+- add or update integration coverage when behavior crosses middleware, serialization, configuration, auth, or background execution boundaries
+- inspect EF Core migrations and prefer reviewed SQL scripts for production-oriented schema changes
+- consult `knowledge-bases/seeded/dotnet/docs/review-checklist.md` before finalizing a patch or design note
+
+## Escalation
+
+- escalate when target framework, trimming, native interop, or publish constraints are unclear
+- escalate when DI lifetimes, async behavior, or transaction boundaries cannot be inferred from repository evidence
+- escalate when a migration, worker, or distributed-app change lacks rollout and observability coverage
+
+## Supplemental Engineering References
+
+- `skills/dotnet-engineering/references/repo-exploration.md`
+- `skills/dotnet-engineering/references/output-templates.md`
+- `skills/dotnet-engineering/references/agent-patterns.md`
+- `skills/dotnet-engineering/references/debugging-playbook.md`
+- `skills/dotnet-engineering/references/architecture-and-di.md`
+- `skills/dotnet-engineering/references/aspnet-and-efcore.md`
+- `skills/dotnet-engineering/references/testing-and-performance.md`
+- `skills/dotnet-engineering/references/cloud-native-and-aspire.md`
+- `skills/dotnet-engineering/references/examples.md`

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

@@ -0,0 +1,30 @@
+# Agent Patterns
+
+## Non-negotiables
+
+- prefer repository evidence over generic framework advice
+- preserve established boundaries unless the task explicitly calls for redesign
+- keep public contracts stable and make behavior changes explicit
+- bias toward small, reversible edits with clear validation
+
+## Default design moves
+
+- inject dependencies through constructors instead of resolving them ad hoc
+- bind configuration once, validate where failure should be surfaced, and pass typed settings inward
+- keep controllers, endpoints, and message handlers thin; move orchestration into application services or domain modules
+- propagate `CancellationToken` through I/O and background workflows
+- add packages only when the repo lacks an equivalent abstraction or pattern already in use
+
+## Review questions
+
+- which project should own this behavior?
+- where is configuration bound, validated, and refreshed?
+- what is the narrowest test seam that proves the change?
+- does the change alter a public contract, migration sequence, or deployment assumption?
+
+## Avoid
+
+- service locator patterns or hidden runtime resolution
+- fire-and-forget tasks inside request paths
+- long-lived tracked entities with implicit side effects
+- repository-wide rewrites when the task needs a local fix

package/skills/dotnet-engineering/references/architecture-and-di.md

@@ -0,0 +1,28 @@
+# Architecture And DI
+
+## Composition root discipline
+
+Register dependencies at the application boundary and keep feature code free of service locator behavior. Constructor injection keeps required dependencies explicit and easier to review.
+
+## Lifetime heuristics
+
+- **Singleton**: stateless, thread-safe, cache-like, or expensive shared resources with careful ownership
+- **Scoped**: request or message bound behavior such as `DbContext`
+- **Transient**: lightweight components without shared mutable state
+
+When in doubt, start with scoped or transient and promote only with evidence.
+
+## Configuration
+
+Use typed options for stable configuration groups. Validate values that would make startup unsafe or cause silent runtime corruption. Avoid sprinkling raw configuration lookups through feature code.
+
+## Boundary choices
+
+- keep transport types near the transport layer
+- keep persistence details near infrastructure code
+- let domain or application types express business rules
+- use interfaces when a real seam exists, not by reflex
+
+## HTTP and outgoing calls
+
+Centralize HTTP client construction and resilience behavior. Prefer typed or named clients over ad hoc `new HttpClient()` creation. Keep retry, timeout, and authentication behavior visible.

package/skills/dotnet-engineering/references/aspnet-and-efcore.md

@@ -0,0 +1,22 @@
+# ASP.NET And EF Core
+
+## ASP.NET Core
+
+- validate untrusted input at the edge and map failures to consistent HTTP responses
+- keep endpoint code focused on routing, auth, validation, and result mapping
+- make serialization, casing, and null-handling decisions explicit when contracts matter
+- when auth or middleware changes, review the full request pipeline rather than one handler in isolation
+
+## EF Core query and model guidance
+
+- use the smallest query shape that satisfies the caller
+- prefer explicit includes or projections over accidental lazy graph loading
+- use no-tracking reads where mutation is not required
+- be careful with client-side evaluation, large tracked graphs, and hidden N+1 patterns
+
+## Migration guidance
+
+- inspect generated migrations for rename-vs-drop mistakes and unexpected data loss
+- prefer production-reviewed SQL scripts, especially for high-risk schema changes
+- treat index builds, constraint validation, and large table rewrites as rollout topics, not just code topics
+- verify mixed-version compatibility whenever old and new binaries may coexist during deployment

package/skills/dotnet-engineering/references/cloud-native-and-aspire.md

@@ -0,0 +1,21 @@
+# Cloud Native And Aspire
+
+## When Aspire is present
+
+Look for AppHost, service-defaults, shared telemetry wiring, or distributed-application bootstrap code. Keep orchestration and local dev topology in those surfaces instead of scattering environment-specific behavior across services.
+
+## Service defaults
+
+A repo with shared service defaults usually wants consistent health checks, telemetry, service discovery, and resilience behavior. Reuse that wiring before introducing service-local copies.
+
+## Distributed changes
+
+When a change spans multiple services:
+
+- note the exact service-to-service contract that changed
+- update local orchestration, configuration, and health expectations together
+- make rollout order explicit when one service depends on another schema or endpoint change
+
+## Non-Aspire cloud-native surfaces
+
+Even without Aspire, carry the same discipline forward: configuration by environment, explicit health and readiness checks, structured logs, and a clear local-dev story.

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

@@ -0,0 +1,21 @@
+# Debugging Playbook
+
+## Startup fails before first request
+
+Check DI registration, options binding, and environment-dependent configuration first. Startup exceptions often come from missing configuration values, invalid options, or a service lifetime mismatch.
+
+## Request succeeds locally but fails in integration or staging
+
+Inspect middleware order, auth configuration, serialization options, culture or timezone assumptions, and reverse-proxy headers. Many ASP.NET issues are environment-shape problems, not controller logic bugs.
+
+## Data behavior is wrong
+
+Inspect generated SQL, tracking mode, transaction scope, and whether a migration changed the data shape the code expects. Prefer reproducing with the actual query rather than guessing from LINQ alone.
+
+## Background worker looks idle or duplicated
+
+Trace startup registration, host lifetime, queue polling cadence, and cancellation handling. Look for scoped services captured by singletons, unbounded retries, or swallowed exceptions inside loops.
+
+## CI-only failures
+
+Compare SDK version, analyzer severity, OS path behavior, and test ordering. Many .NET CI regressions come from stricter analyzers, pinned SDK differences, or tests that share state.

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

@@ -0,0 +1,22 @@
+# Examples
+
+## Add an endpoint safely
+
+1. find the current HTTP seam and auth pattern
+2. add request validation and result mapping at the edge
+3. implement behavior in the existing application or service layer
+4. add integration coverage for serialization and middleware-sensitive behavior
+
+## Add a background job
+
+1. identify queue, schedule, or trigger semantics
+2. isolate the work into a testable unit
+3. make retries, cancellation, and idempotency explicit
+4. add observability and operational notes with the code change
+
+## Review a migration-backed feature
+
+1. compare old and new code against the intermediate schema state
+2. verify generated migration or SQL for data-loss or lock risk
+3. define deployment order and post-deploy checks
+4. surface rollback or forward-fix assumptions

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

@@ -0,0 +1,33 @@
+# Output Templates
+
+## Patch Proposal
+
+- objective
+- affected projects and why they own the change
+- key code moves or API changes
+- validation path
+- rollout note if runtime behavior changes
+
+## Design Review
+
+- current behavior
+- decision drivers
+- recommended approach
+- alternatives rejected
+- operational impact
+
+## Migration Note
+
+- schema change summary
+- mixed-version compatibility window
+- deployment order
+- rollback or forward-fix plan
+- post-deploy verification
+
+## Debugging Report
+
+- symptom and exact failing surface
+- likely root causes ranked by probability
+- fastest confirmation step for each cause
+- proposed fix
+- validation steps

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

@@ -0,0 +1,38 @@
+# Repo Exploration
+
+## Inspect these files first
+
+- `global.json` for SDK pinning
+- `Directory.Build.props` and `Directory.Build.targets` for shared compiler and analyzer rules
+- `Directory.Packages.props` for central package management
+- solution files and project references to map the dependency graph
+- `appsettings*.json`, secrets wiring, or environment-specific configuration surfaces
+- migration folders, test projects, container definitions, and deployment manifests
+
+## Classify the repo shape
+
+- **Single service**: one startup project plus a few supporting libraries
+- **Library pack**: multiple publishable packages with test suites and sample apps
+- **Distributed app**: AppHost or service-orchestration surfaces, often with shared service defaults
+- **Worker or automation**: background scheduling, queue processing, or CLI execution with minimal HTTP surface
+- **Legacy mixed solution**: older csproj formats, partial framework upgrades, or custom build targets
+
+## Find the composition root
+
+Look for one of these first:
+
+- `Program.cs`
+- `Startup.cs`
+- service-registration extensions such as `AddApplication`, `AddInfrastructure`, or `ConfigureServices`
+- worker bootstrap code or CLI command registration
+
+This tells you where dependencies, configuration, and middleware are assembled. Keep new dependencies visible there unless the repo clearly centralizes them elsewhere.
+
+## High-signal risk surfaces
+
+- custom middleware, auth handlers, or filters
+- source generators, analyzers, Roslyn-based tooling, or codegen
+- EF Core migration history and database startup behavior
+- background services, timers, or queue consumers
+- solution-wide props files that can affect every project in one edit
+- publish profiles, trimming or AOT settings, and container build stages

package/skills/dotnet-engineering/references/testing-and-performance.md

@@ -0,0 +1,25 @@
+# Testing And Performance
+
+## Testing layers
+
+- unit tests for pure logic and edge cases
+- integration tests for middleware, serialization, persistence, and auth boundaries
+- focused end-to-end or smoke checks for the highest-risk runtime paths
+
+If the repo already uses `WebApplicationFactory`, extend that path for endpoint and middleware verification instead of building custom harnesses.
+
+## Worker and background testing
+
+Prefer extracting loop bodies or handlers into testable units. Validate retry, idempotency, and cancellation logic separately from the host loop.
+
+## Performance hotspots
+
+- repeated allocations in hot paths
+- synchronous I/O on request threads
+- oversized object graphs or serializer churn
+- database overfetch and chatty data access
+- logging inside tight loops without level guards
+
+## Validation hints
+
+Use the narrowest command that proves the change. When performance is part of the task, compare before and after behavior with the same workload shape instead of relying on intuition.

package/skills/engineering-assistant/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: engineering-assistant
+description: architecture and implementation orchestrator for cross-cutting engineering work. use when a task needs system design, code architecture, refactoring strategy, implementation planning, specialist-skill routing, or explicit project-memory and change-discipline guidance in one surface.
+---
+
+# Engineering Assistant
+
+## Trigger Signals
+
+- the task spans architecture, implementation, and workflow discipline instead of a single narrow code edit
+- the user wants design options, trade-offs, and a buildable recommendation rather than only raw implementation
+- multiple specialist skills or language packs may need coordination under one consistent delivery plan
+- project memory, decision records, or structured change capture matter to the success of the work
+
+## Inspect First
+
+- the repo surfaces that define architecture, runtime boundaries, and current validation entrypoints
+- `skills/engineering-assistant/references/architecture.md`
+- `skills/engineering-assistant/references/solid-and-patterns.md`
+- `skills/engineering-assistant/references/skill-composition.md`
+- `skills/engineering-assistant/references/project-notes.md`
+- `skills/engineering-assistant/references/change-discipline.md`
+
+## Workflow
+
+1. establish context, requirements, constraints, and the current repo operating path before proposing change
+2. present at least two viable options with trade-offs and name the invariants that must hold across all choices
+3. choose the smallest reversible step that advances the chosen option without losing validation or recovery paths
+4. route subdomains to the most specific existing skill or knowledge pack when deeper specialist guidance is needed
+5. keep architecture, interface consistency, project-memory updates, and change-discipline expectations coherent across the full task
+
+## Output Contract
+
+- context summary with functional and non-functional constraints
+- option set with trade-offs and an explicit chosen direction
+- component, module, or workflow boundaries with named invariants
+- implementation plan or concrete code change summary tied to validation
+- project-memory and change-discipline follow-up expectations when the work is meaningful
+
+## Failure Modes
+
+- the repo lacks enough context or validation to recommend a safe architecture or implementation path
+- multiple options exist but the constraints are too unclear to choose responsibly
+- specialist domains are required but no clear handoff or governing interface has been defined
+- project-memory or change-discipline expectations would become ceremony without a clear reason or owner
+
+## Escalation
+
+- escalate when the architecture choice changes public contracts, data ownership, or release risk without explicit approval
+- escalate when the work crosses multiple skills, teams, or runtime boundaries and ownership is unclear
+- escalate when constraints such as compliance, reliability, migration safety, or support windows are unknown but materially affect the decision
+
+## References
+
+- `skills/engineering-assistant/references/architecture.md`
+- `skills/engineering-assistant/references/solid-and-patterns.md`
+- `skills/engineering-assistant/references/skill-composition.md`
+- `skills/engineering-assistant/references/project-notes.md`
+- `skills/engineering-assistant/references/change-discipline.md`

package/skills/engineering-assistant/references/architecture.md

@@ -0,0 +1,47 @@
+# Architecture Playbook
+
+Use this checklist when the engineering-assistant skill is responsible for
+architecture, delivery framing, or architecture-informed implementation.
+
+## What to produce
+
+1. requirements and constraints, including functional and non-functional needs
+2. at least two viable architecture options with trade-offs
+3. the selected design with boundaries, data flow, failure modes, and operating model
+4. decision records for the choices that materially shape implementation
+5. a delivery plan with milestones, risks, and validation expectations
+
+## Cloud and platform checklist
+
+- network segmentation, ingress and egress, and private-surface expectations
+- identity, secrets handling, least privilege, and workload identity
+- data classification, encryption, retention, backup, and restore expectations
+- reliability requirements such as SLOs, retries, idempotency, DLQs, and rollback
+- observability expectations across logs, metrics, traces, dashboards, and alerts
+- cost drivers such as scale knobs, storage tiers, and egress exposure
+
+## Code architecture checklist
+
+- ownership boundaries across modules, packages, or services
+- contract stability, versioning, and backward-compatibility expectations
+- domain-versus-infrastructure separation and dependency direction
+- unit, integration, and contract-test coverage needed to trust the design
+- error and invariant handling, including recovery and operator visibility
+
+## Common patterns
+
+### Backend and services
+
+- ports and adapters when infrastructure seams need isolation
+- CQRS when read and write concerns truly diverge
+- outbox or transactional messaging when durable event publication matters
+
+### Frontend and apps
+
+- feature-based slicing with shared primitives
+- explicit separation between server state and client state
+
+### Data
+
+- default to Postgres or another measured OLTP store before adding search or cache tiers
+- add event streaming only when async workflows or multiple consumers are first-class requirements