@harness-forge/cli 0.1.0

package/skills/api-contract-review/references/examples.md

@@ -0,0 +1,15 @@
+# Examples
+
+## Additive HTTP change
+
+- add optional response field
+- keep existing status codes and error shapes unchanged
+- update OpenAPI examples and client snapshots
+- verdict: usually safe if consumers tolerate unknown fields
+
+## Breaking schema change
+
+- rename a required request field
+- tighten validation without versioning
+- generated clients now serialize a different property name
+- verdict: breaking unless versioned or migrated with a compatibility window

package/skills/api-contract-review/references/http-contract-checklist.md

@@ -0,0 +1,24 @@
+# HTTP Contract Checklist
+
+## Requests
+
+- method and route stability
+- required vs optional fields
+- null vs absent semantics
+- header requirements and auth expectations
+- pagination, filtering, and sorting conventions
+
+## Responses
+
+- status code meanings
+- error shape consistency
+- enum and discriminator behavior
+- date, time, and numeric encoding
+- default values and omitted fields
+
+## Behavior semantics
+
+- idempotency for safe retry scenarios
+- partial update semantics for PATCH-like operations
+- backward-compatible additions vs required-field changes
+- whether new validation rejects payloads that used to succeed

package/skills/api-contract-review/references/protobuf-and-buf.md

@@ -0,0 +1,12 @@
+# Protobuf And Buf
+
+## Protobuf compatibility rules
+
+- never reuse field numbers for different meanings
+- reserve removed field numbers and names when a field is retired
+- be careful with required-like semantics implemented in application code even if the wire format stays compatible
+- think about JSON mapping as well as binary wire compatibility when the schema is used through gateways
+
+## Buf guidance
+
+Buf breaking checks let a repo choose stricter or looser policies such as `FILE`, `PACKAGE`, `WIRE_JSON`, or `WIRE`. Treat the chosen category as a floor, not a substitute for reasoning about client behavior.

package/skills/api-contract-review/references/review-template.md

@@ -0,0 +1,19 @@
+# Review Template
+
+## Contract Summary
+
+- changed endpoints, messages, or schemas
+- source of truth checked
+- generated artifacts affected
+
+## Compatibility Verdict
+
+- safe, risky, or breaking
+- exact fields, operations, or semantics that drive the verdict
+
+## Consumer Impact
+
+- provider changes required
+- client or SDK updates required
+- docs or example updates required
+- rollout or versioning guidance

package/skills/api-contract-review/references/schema-compatibility.md

@@ -0,0 +1,20 @@
+# Schema Compatibility
+
+## Usually additive
+
+- new optional fields
+- new endpoints or operations
+- new enum values only when consumers are documented to tolerate unknown values
+- broader examples that still validate against the old schema
+
+## Often breaking
+
+- making a field required
+- removing fields, enum values, or response variants
+- changing field types, formats, or nullability semantics
+- changing validation in a way that rejects previously valid input
+- reusing a field name while changing its meaning
+
+## Rule of thumb
+
+Compatibility is about consumer behavior, not just shape compatibility. A response can validate and still be breaking if its semantics or defaults changed in a way existing clients do not expect.

package/skills/api-contract-review/references/style-and-linting.md

@@ -0,0 +1,15 @@
+# Style And Linting
+
+## OpenAPI and AsyncAPI
+
+Use machine-readable specs as the first review surface, not just handwritten docs. OpenAPI is the standard description format for HTTP APIs, and AsyncAPI plays the same role for asynchronous APIs.
+
+## Linting surfaces
+
+- Spectral is a strong general-purpose linter for OpenAPI, AsyncAPI, and related JSON or YAML rulesets
+- Redocly CLI is useful when the repo wants linting tied closely to OpenAPI quality, docs, or governance rules
+- JSON Schema should be reviewed for both validation intent and how generators or clients interpret optionality and nullability
+
+## Review rule
+
+Lint passes are necessary but not sufficient. Always reason about examples, generated clients, and consumer migration cost.

package/skills/architecture-decision-records/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: architecture-decision-records
+description: create and maintain high-signal adrs for architecture, package, runtime, workflow, and operational decisions. use when a decision should stay reviewable after the current session or when multiple credible options need a durable rationale.
+---
+
+# Architecture Decision Records
+
+## Trigger Signals
+
+- the task changes architecture, package boundaries, runtime behavior, support guarantees, or operating model
+- more than one credible option exists and the trade-off should stay reviewable later
+- a decision will affect multiple teams, releases, or future migrations
+
+## Inspect First
+
+- the affected specs, tasks, plans, and runtime boundaries
+- any existing ADRs, design docs, or release notes that already capture related decisions
+- operational constraints such as support window, migration cost, reliability, security, or compliance
+
+## Workflow
+
+1. frame the actual decision, not the implementation diary around it
+2. capture the strongest drivers, constraints, and alternatives that were seriously considered
+3. choose a concise ADR shape and write context, decision, status, and consequences in plain language
+4. note follow-up actions, migration implications, and what would invalidate the decision later
+5. update or supersede older ADRs explicitly when the decision changes an earlier one
+
+## Output Contract
+
+- ADR title, status, and date-ready decision summary
+- short context section with the forces that matter
+- options considered and why the chosen path won
+- consequences, follow-up actions, and superseded links when relevant
+
+## Failure Modes
+
+- the real decision has not been framed clearly yet
+- the work is still exploratory enough that no stable rationale exists
+- the note drifts into a long implementation log instead of a decision record
+
+## Escalation
+
+- escalate when the decision changes public contracts, support commitments, or cross-team ownership
+- escalate when alternatives have materially different operational or migration risk
+- escalate when the ADR appears to conflict with an existing record and the supersession path is unclear
+
+## References
+
+- `skills/architecture-decision-records/references/adr-template.md`
+- `skills/architecture-decision-records/references/decision-rubric.md`
+- `skills/architecture-decision-records/references/madr-style-guide.md`
+- `skills/architecture-decision-records/references/adr-anti-patterns.md`
+- `skills/architecture-decision-records/references/examples.md`

package/skills/architecture-decision-records/references/adr-anti-patterns.md

@@ -0,0 +1,10 @@
+# ADR Anti Patterns
+
+## Avoid these failures
+
+- writing a feature summary instead of a decision record
+- describing only the chosen path with no real alternatives
+- omitting the constraints that made the choice sensible
+- hiding trade-offs because the team wants the record to look tidy
+- leaving follow-up actions implicit
+- never superseding old ADRs when reality changed

package/skills/architecture-decision-records/references/adr-template.md

@@ -0,0 +1,31 @@
+# ADR Template
+
+## Title
+
+Choose a title that states the decision, not the meeting topic.
+
+## Status
+
+- proposed
+- accepted
+- superseded
+- deprecated
+
+## Context
+
+Describe the forces that matter now: scale, reliability, migration cost, team boundaries, deadlines, support window, or compliance needs.
+
+## Decision
+
+State the chosen path directly. Make it possible for a future reader to understand the answer in one paragraph.
+
+## Alternatives Considered
+
+List the strongest alternatives that were genuinely plausible.
+
+## Consequences
+
+- positive effects
+- trade-offs and costs
+- follow-up actions or guardrails
+- what would trigger a revisit

package/skills/architecture-decision-records/references/decision-rubric.md

@@ -0,0 +1,22 @@
+# Decision Rubric
+
+## Write an ADR when
+
+- the decision changes long-lived architecture or operations
+- reversing it later will be expensive
+- multiple teams or future features will depend on it
+- the rationale is easy to lose after the current implementation lands
+
+## Skip or defer an ADR when
+
+- the change is tiny, local, and low risk
+- the decision is purely tactical and short-lived
+- requirements are still moving too fast to state a stable rationale
+
+## Good decision drivers
+
+- reliability and operability
+- migration cost and reversibility
+- complexity and maintenance burden
+- security and compliance posture
+- developer experience and delivery speed

package/skills/architecture-decision-records/references/examples.md

@@ -0,0 +1,15 @@
+# Examples
+
+## Good ADR title
+
+Adopt incremental schema expand-and-contract for multi-release database changes
+
+## Weak ADR title
+
+Database notes
+
+## Good consequence section
+
+- enables rolling deploys across mixed application versions
+- increases short-term write-path complexity because dual-write remains until the contract phase
+- requires migration telemetry before old columns can be removed

package/skills/architecture-decision-records/references/madr-style-guide.md

@@ -0,0 +1,17 @@
+# MADR Style Guide
+
+## Lean writing rules
+
+- keep the ADR small enough to scan quickly
+- write in decisive language
+- separate context from decision from consequences
+- prefer real alternatives over strawman options
+- include both positive and negative consequences
+
+## Status discipline
+
+Use status consistently. When a new ADR replaces an old one, say so directly instead of leaving both records to contradict each other.
+
+## Tone
+
+The document should explain the decision to a future engineer, not relive the full discussion transcript.

package/skills/cloud-architect/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: cloud-architect
+description: Cloud architecture guidance for platform design, deployment topology, reliability, security, observability, and cost trade-offs.
+origin: Harness Forge
+---
+
+# Cloud Architect
+
+Use this skill when the task is dominated by platform shape rather than a single
+code path: cloud topology, deployment design, distributed systems behavior,
+reliability, migration planning, security posture, observability, or cost.
+
+## Trigger Signals
+
+- the task mentions AWS, Azure, GCP, Kubernetes, Terraform, containers, or platform architecture
+- the change spans multiple services, environments, or deployment stages
+- reliability, security, latency, observability, or cost trade-offs are first-class concerns
+
+## Inspect First
+
+- infrastructure and deployment definitions
+- runtime configuration, environment boundaries, and secret handling
+- service topology, dependencies, and data or event flows
+- existing observability, SLO, reliability, and incident surfaces
+
+## Workflow
+
+1. map the current topology, ownership boundaries, and runtime dependencies
+2. identify the highest-risk architectural seams before proposing change
+3. compare the repository's current patterns against the closest stable reference pattern
+4. recommend the smallest architecture move that improves reliability, clarity, or operability
+5. define validation, rollout, and rollback expectations before implementation handoff
+
+## Output Contract
+
+- architecture summary with current state and proposed direction
+- trade-off notes covering reliability, security, observability, and cost
+- rollout or validation guidance with concrete follow-up checks
+
+## Failure Modes
+
+- stop when the current topology cannot be inferred from repository evidence
+- stop when compliance, tenancy, or secret-management assumptions would materially change the recommendation
+- stop when the task is really a single-service code change and should stay with a language skill
+
+## Escalation
+
+- escalate when cloud-provider constraints, compliance rules, or budget targets are missing
+- escalate when migration risk crosses team or service ownership boundaries
+- escalate when rollout and rollback expectations are undefined for a production-critical path
+
+## Supplemental References
+
+- `skills/cloud-architect/references/repo-exploration.md`
+- `skills/cloud-architect/references/output-templates.md`
+- `skills/cloud-architect/references/agent-patterns.md`
+- `skills/cloud-architect/references/debugging-playbook.md`
+- `skills/cloud-architect/references/distributed-systems.md`
+- `skills/cloud-architect/references/platform-and-deployment.md`
+- `skills/cloud-architect/references/reliability-security-cost.md`
+- `skills/cloud-architect/references/examples.md`

package/skills/cloud-architect/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/cloud-architect/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/cloud-architect/references/distributed-systems.md

@@ -0,0 +1,13 @@
+# Distributed Systems Fundamentals
+
+## Non-Negotiables
+- define failure domains
+- know consistency needs per workflow
+- prefer explicit idempotency for retried commands/events
+- design for degraded modes, not perfect availability
+
+## Core Questions
+- request/response, event-driven, batch, or hybrid?
+- stateful or stateless scaling?
+- sync orchestration or async choreography?
+- latency-critical or throughput-oriented?

package/skills/cloud-architect/references/examples.md

@@ -0,0 +1,19 @@
+# Examples
+
+## Example: Design multi-tenant SaaS backend
+- isolate tenant data model
+- choose identity/auth boundary
+- define noisy-neighbor controls
+- plan observability dimensions by tenant and workload
+- decide whether tenant isolation is logical, pooled, or dedicated
+
+## Example: Migrate monolith to cloud without over-fragmenting
+- first containerize or platform-host intact service
+- extract seams only where scaling, ownership, or release cadence justify it
+- preserve transaction and data consistency behavior during transition
+
+## Example: Event-driven integration
+- define event schema ownership
+- idempotent consumers
+- dead-letter handling and replay policy
+- tracing across async boundaries

package/skills/cloud-architect/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/cloud-architect/references/platform-and-deployment.md

@@ -0,0 +1,13 @@
+# Platform and Deployment
+
+## Compute Options
+- containers for portability and controlled runtime
+- serverless for bursty/event-driven workloads with operational simplicity
+- VMs when OS/runtime control is essential
+- managed platforms when reducing operational burden is the main goal
+
+## Deployment Guidance
+- immutable deployments preferred
+- progressive rollout where risk warrants it
+- separate build artifact creation from environment configuration
+- health checks and rollback criteria must be explicit

package/skills/cloud-architect/references/reliability-security-cost.md

@@ -0,0 +1,17 @@
+# Reliability, Security, Cost
+
+## Reliability
+- define SLOs before scaling conversations drift into guesswork
+- instrument critical user journeys and asynchronous pipelines
+- backpressure and timeouts beat blind retries
+
+## Security
+- least privilege
+- secret rotation and boundary-aware trust model
+- network segmentation guided by actual threat surface
+- auditability for control-plane changes
+
+## Cost
+- right-size after measurement
+- know fixed vs variable cost drivers
+- optimize data transfer, storage tiering, and idle capacity

package/skills/cloud-architect/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/cpp-engineering/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: cpp-engineering
+description: c++ engineering guidance for structured Harness Forge language packs.
+---
+
+# C++ Engineering
+
+Use this skill when the repository is primarily C++ or when the task touches native source, headers, or build files.
+
+## Activation
+
+- native code dominates the task or repository
+- the work touches ABI-sensitive, performance-critical, or concurrency-heavy code
+
+## Load Order
+
+- `rules/common/`
+- `rules/cpp/`
+- `knowledge-bases/structured/cpp/docs/`
+- `knowledge-bases/structured/cpp/examples/`
+
+## Execution Contract
+
+1. inspect ownership, build, and interface boundaries
+2. select the common and C++-specific rules for the change
+3. implement with explicit compatibility and memory-safety tradeoffs
+4. verify with the repo native build/test path and the structured checklist
+
+## Outputs
+
+- touched-module summary
+- implementation summary
+- validation result or blocker note
+
+## Validation
+
+- run the repo native validation path when available
+- consult `knowledge-bases/structured/cpp/docs/review-checklist.md`
+
+## Escalation
+
+- escalate when ABI, threading, or platform-specific changes are involved
+- escalate when the safe ownership strategy is not obvious

package/skills/db-migration-review/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: db-migration-review
+description: review database migrations for safety, compatibility windows, backfills, reversibility, and rollout risk. use when migration files, schema diffs, orm model changes, indexes, constraints, or data backfills change.
+---
+
+# DB Migration Review
+
+## Trigger Signals
+
+- the task adds or edits migrations, DDL, backfills, seed data, or schema-affecting ORM changes
+- the change touches EF Core, Flyway, Liquibase, Prisma, Atlas, handcrafted SQL, or online migration tooling
+- rollout safety matters because the database is large, hot, replicated, or shared by multiple services
+
+## Inspect First
+
+- migration files, generated SQL, and schema model diffs
+- the application code that reads or writes the changed tables or columns
+- deployment order, backfill jobs, feature flags, and rollback expectations
+- table size, hot paths, index usage, and engine-specific lock sensitivity when evidence exists
+
+## Workflow
+
+1. classify the change as additive, destructive, rewrite-heavy, data-moving, or operationally sensitive
+2. determine the compatibility window between old code, new code, and intermediate schema states
+3. inspect lock, rewrite, replication, and backfill risk with the engine and tool in mind
+4. verify reversibility, forward-fix options, and post-deploy validation steps
+5. emit a risk-ranked review with concrete rollout guidance, not generic warnings
+
+## Output Contract
+
+- migration summary grouped by schema change, data change, and rollout shape
+- risk level with the exact reasons it is safe, risky, or blocked
+- expand-and-contract verdict, rollback or forward-fix plan, and validation queries or checks
+- follow-up tasks for app changes, monitoring, throttling, or staged deployment
+
+## Failure Modes
+
+- engine, table size, or traffic profile is unknown and materially changes risk
+- the migration file exists without the surrounding application rollout plan
+- generated SQL is unavailable for toolchains that hide the real DDL
+
+## Escalation
+
+- escalate when a migration can drop data, rewrite a large table, block hot paths, or break mixed-version application deployments
+- escalate when backfills are non-idempotent, unthrottled, or lack checkpointing
+- escalate when rollback is impossible and no forward-fix path or validation telemetry exists
+
+## References
+
+- `skills/db-migration-review/references/risk-taxonomy.md`
+- `skills/db-migration-review/references/expand-contract.md`
+- `skills/db-migration-review/references/engine-specific-hotspots.md`
+- `skills/db-migration-review/references/tooling-signals.md`
+- `skills/db-migration-review/references/rollout-and-backfill.md`
+- `skills/db-migration-review/references/review-template.md`
+- `skills/db-migration-review/references/examples.md`

package/skills/db-migration-review/references/engine-specific-hotspots.md

@@ -0,0 +1,21 @@
+# Engine Specific Hotspots
+
+## PostgreSQL
+
+Watch for table rewrites, long-running transactions, constraint validation cost, and index creation strategy. Large DDL can block more than the migration author expects if it runs on hot tables.
+
+## MySQL and MariaDB
+
+Watch for metadata locks, table-copy behavior, and cut-over risk. Online-migration tools can reduce risk, but they introduce their own operational steps and failure modes.
+
+## SQL Server
+
+Watch for index rebuild behavior, lock escalation, long transactions, and the difference between online and offline operations.
+
+## SQLite and embedded stores
+
+Many schema changes are effectively copy-and-rewrite operations. Treat data volume and file-lock behavior as rollout concerns, not just local-dev concerns.
+
+## Cross-engine rule
+
+If the migration tool abstracts SQL away, inspect the emitted SQL or engine-specific plan before approving anything beyond trivial additive changes.

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

@@ -0,0 +1,16 @@
+# Examples
+
+## Safe additive change
+
+- add nullable column
+- write both old and new fields from the app
+- backfill historical rows in chunks
+- switch reads after validation
+- drop old field in a later release
+
+## Risky contract change
+
+- rename column through ORM model edit only
+- generated SQL drops and re-creates the column
+- no dual-read path or backfill plan exists
+- verdict: blocked until the migration is rewritten as a preserve-data rename or expand-and-contract sequence