@harness-forge/cli 0.1.0

package/skills/typescript-engineering/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: typescript-engineering
+description: typescript and javascript engineering guidance seeded from the harness forge knowledge base. use when the repo or task is dominated by .ts, .tsx, package.json, tsconfig, node.js services, react, next.js, frontend tooling, or multi-package workspaces where type boundaries matter.
+origin: Harness Forge
+---
+
+# TypeScript Engineering
+
+Use this skill when the repository is TypeScript-first and the right answer depends on module boundaries, runtime contracts, build graph shape, or strict typing discipline rather than ad hoc code edits.
+
+## Activation
+
+- the task touches `.ts`, `.tsx`, `package.json`, `tsconfig.json`, workspace configuration, or generated type surfaces
+- the repo is a Node service, CLI, package, React app, Next.js app, Vite app, or multi-package workspace
+- the change depends on public exports, schema validation, code generation, or cross-package contracts
+
+## Load Order
+
+- `rules/common/README.md`
+- `rules/common/coding-style.md`
+- `rules/common/patterns.md`
+- `rules/common/testing.md`
+- `rules/common/security.md`
+- `rules/typescript/README.md`
+- `rules/typescript/coding-style.md`
+- `rules/typescript/patterns.md`
+- `rules/typescript/testing.md`
+- `rules/typescript/security.md`
+- `templates/workflows/implement-typescript-change.md`
+- `knowledge-bases/seeded/typescript/docs/overview.md`
+- `knowledge-bases/seeded/typescript/docs/frameworks.md`
+- `knowledge-bases/seeded/typescript/docs/review-checklist.md`
+- `knowledge-bases/seeded/typescript/examples/`
+- `skills/typescript-engineering/references/`
+
+## Execution Contract
+
+1. map package manager, workspace layout, module system, and tsconfig graph before changing files
+2. identify runtime boundaries and pair static types with runtime validation where untrusted data enters the system
+3. preserve local export surfaces and semver expectations unless the task explicitly authorizes a contract change
+4. prefer narrow, composable types, discriminated unions, and explicit async behavior over clever type gymnastics
+5. when the repo is multi-package, keep references, build outputs, and import paths consistent across the workspace
+6. validate both TypeScript correctness and runtime or bundler correctness before finalizing
+
+## Outputs
+
+- touched-file plan grouped by package or app boundary
+- implementation summary with the exact contract or build seam that changed
+- validation path with typecheck, test, lint, and runtime or bundler confirmation
+- compatibility note when exports, generated types, or shared contracts changed
+
+## Validation
+
+- use the repo's preferred `typecheck`, `lint`, `test`, `build`, or workspace commands first
+- inspect `tsconfig` inheritance, path aliases, project references, and module-system settings before moving files or imports
+- confirm that runtime assumptions match compile-time assumptions, especially for ESM, CommonJS, browser, and server boundaries
+- add runtime validation or schema assertions when the code crosses an API, event, env-var, or persistence boundary
+- consult `knowledge-bases/seeded/typescript/docs/review-checklist.md` before finalizing a patch or design note
+
+## Escalation
+
+- escalate when the repo mixes incompatible ESM, CommonJS, browser, or server assumptions
+- escalate when a public package export or shared contract changes without migration guidance
+- escalate when generated types, codegen, or workspace build order are unclear
+
+## Supplemental Engineering References
+
+- `skills/typescript-engineering/references/repo-exploration.md`
+- `skills/typescript-engineering/references/output-templates.md`
+- `skills/typescript-engineering/references/agent-patterns.md`
+- `skills/typescript-engineering/references/debugging-playbook.md`
+- `skills/typescript-engineering/references/type-system-patterns.md`
+- `skills/typescript-engineering/references/tsconfig-and-build.md`
+- `skills/typescript-engineering/references/frontend-and-backend-patterns.md`
+- `skills/typescript-engineering/references/runtime-validation-and-boundaries.md`
+- `skills/typescript-engineering/references/workspace-and-monorepo.md`
+- `skills/typescript-engineering/references/examples.md`

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

@@ -0,0 +1,23 @@
+# Agent Patterns
+
+## Non-negotiables
+
+- prefer repository evidence over generic ecosystem fashion
+- protect runtime behavior even when the type system looks satisfied
+- keep public exports explicit and intentional
+- choose the smallest change that preserves local conventions
+
+## Default implementation bias
+
+- push untrusted data through validation at the boundary
+- model domain states with discriminated unions or explicit tagged objects
+- keep type helpers readable; favor clarity over type-level novelty
+- keep async flows explicit and avoid hidden promise fan-out in request paths
+- move shared contracts into a stable package only when multiple consumers already need them
+
+## Review questions
+
+- what is the real runtime boundary here?
+- which package or module owns this contract?
+- does the type change alter emitted JS, declaration output, or bundle shape?
+- how will the change behave under the active module system and bundler?

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

@@ -0,0 +1,21 @@
+# Debugging Playbook
+
+## Types pass, runtime fails
+
+Check environment assumptions first: ESM vs CommonJS, browser vs server globals, path alias resolution, and whether generated output matches the source tree the runtime actually executes.
+
+## Build passes, tests fail
+
+Inspect module mocks, hoisting behavior, fake timers, and environment configuration. Many test failures come from setup differences rather than business logic.
+
+## Monorepo package drift
+
+Check stale build output, declaration artifacts, cached references, and whether the consumer imports source or package output. A surprisingly common bug is editing one package without rebuilding the package another app actually consumes.
+
+## Serialization or API mismatch
+
+Validate the runtime payload, not just the TypeScript type. Confirm nullability, enum values, date encoding, and optional vs absent field semantics.
+
+## Browser-only or SSR-only bug
+
+Trace where code crosses the client/server boundary, where side effects run, and whether the bundler tree-shook or split the module the way the author expected.

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

@@ -0,0 +1,22 @@
+# Examples
+
+## Tighten an API contract
+
+1. validate the payload at the edge
+2. narrow internal types after validation
+3. update the shared client or schema package only if the contract itself changed
+4. run typecheck on both provider and consumer paths
+
+## Introduce a shared package safely
+
+1. confirm two or more real consumers need the shared surface
+2. define a narrow public API and explicit exports
+3. move only stable code first
+4. validate build, lint, and consumer imports before wider extraction
+
+## Fix an ESM or CommonJS bug
+
+1. inspect `package.json` `type`, `exports`, and test runner config
+2. align tsconfig with the actual runtime
+3. update imports or output shape with the smallest compatible change
+4. re-run the real runtime path, not just typecheck

package/skills/typescript-engineering/references/frontend-and-backend-patterns.md

@@ -0,0 +1,19 @@
+# Frontend And Backend Patterns
+
+## Backend
+
+- keep request parsing, auth, and validation at the edge
+- isolate business logic from transport and framework helpers
+- prefer explicit DTO mapping at service boundaries
+- keep side effects behind small abstractions that are easy to test
+
+## Frontend
+
+- keep server-state fetching separate from view components when the framework supports it
+- colocate component-specific logic, but move shared domain logic into stable modules
+- make loading, empty, error, and optimistic states explicit
+- keep browser-only APIs behind effect or boundary modules
+
+## Shared packages
+
+Only centralize code when at least two consumers already need the same contract or behavior. Premature shared packages create more churn than they save.

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

@@ -0,0 +1,25 @@
+# Output Templates
+
+## Patch Proposal
+
+- objective
+- affected packages or apps
+- type or runtime boundary changed
+- validation path
+- compatibility note
+
+## Design Review
+
+- current contract shape
+- decision drivers
+- recommended approach
+- alternatives rejected
+- build and runtime impact
+
+## Debugging Report
+
+- symptom
+- compile-time vs runtime mismatch check
+- likely root causes ranked by probability
+- fastest confirmation steps
+- proposed fix and validation

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

@@ -0,0 +1,25 @@
+# Repo Exploration
+
+## Inspect these files first
+
+- `package.json` and lockfiles to identify package manager and scripts
+- root and package-level `tsconfig*.json`
+- workspace manifests such as `pnpm-workspace.yaml`, npm or yarn workspace definitions, or monorepo config
+- framework config such as `next.config.*`, `vite.config.*`, `vitest.config.*`, bundler config, and lint config
+- generated API or schema clients, shared types packages, and codegen settings
+
+## Classify the runtime shape
+
+- **Node service or CLI**: entrypoint scripts, env loading, and package exports matter most
+- **React or Next app**: client and server boundaries, bundler behavior, and route conventions matter
+- **Library or SDK**: public exports, declaration output, dual-package support, and semver matter
+- **Workspace or monorepo**: project references, incremental builds, and shared package contracts matter
+
+## High-signal risk surfaces
+
+- package `exports` or `imports`
+- tsconfig inheritance and path aliasing
+- generated clients or schema-derived types
+- SSR and browser boundary crossings
+- dynamic imports, loaders, and environment-specific entrypoints
+- shared packages consumed by many apps in the workspace

package/skills/typescript-engineering/references/runtime-validation-and-boundaries.md

@@ -0,0 +1,20 @@
+# Runtime Validation And Boundaries
+
+## Boundaries that need runtime checks
+
+- HTTP requests and responses
+- message or event payloads
+- environment variables and config files
+- persistence reads where historical data may violate current assumptions
+- third-party SDK responses and browser APIs
+
+## Validation rules
+
+- validate as close to the boundary as possible
+- translate into trusted internal types after validation
+- preserve the original payload or error context when debugging matters
+- do not treat compile-time types as evidence that runtime data is safe
+
+## Contract evolution
+
+When changing a shared schema, identify whether consumers can coexist across versions. Additive changes are usually safer than required-field, enum, or semantics changes.

package/skills/typescript-engineering/references/tsconfig-and-build.md

@@ -0,0 +1,25 @@
+# TSConfig And Build
+
+## Module resolution heuristics
+
+- use `node16` or `nodenext` when the runtime is modern Node and both `import` and `require` semantics matter
+- use `bundler` when the code is primarily consumed through a bundler and extension rules should stay bundler-friendly
+- align `module`, `moduleResolution`, and emitted package shape before touching imports in a large repo
+
+## Project references
+
+Use project references when a workspace needs faster incremental builds, clearer package boundaries, or independent emit steps. They work best when each package has a clean entrypoint and explicit dependencies.
+
+## Build graph pitfalls
+
+- path aliases that compile but do not resolve at runtime
+- declaration emit that does not match the exported surface
+- multiple tsconfig layers with conflicting strictness or JSX settings
+- mixed ESM and CommonJS output without an explicit package strategy
+
+## Safe change order
+
+1. understand the current module and emit strategy
+2. change the minimal tsconfig surface needed
+3. typecheck the affected packages
+4. build the actual consumer path, not just the edited package

package/skills/typescript-engineering/references/type-system-patterns.md

@@ -0,0 +1,20 @@
+# Type System Patterns
+
+## Prefer these patterns
+
+- discriminated unions for stateful workflows
+- branded or nominal wrappers for IDs and opaque values when plain strings are too easy to mix up
+- narrow function inputs and rich return types over giant parameter bags
+- explicit `Result`-like objects when failure modes matter to callers
+- exhaustive switching on tagged unions for business-state handling
+
+## Use caution with
+
+- deeply nested conditional types that obscure intent
+- broad `any` or blanket assertion casts near critical logic
+- ambient global augmentation unless the repo already relies on it heavily
+- utility types that hide required vs optional field semantics
+
+## Contract rule
+
+Static types describe developer intent. Runtime checks protect real inputs. Use both where trust boundaries exist.

package/skills/typescript-engineering/references/workspace-and-monorepo.md

@@ -0,0 +1,23 @@
+# Workspace And Monorepo
+
+## Good monorepo signals
+
+- clear package ownership and naming
+- stable package entrypoints and dependency direction
+- root scripts that delegate to per-package tasks consistently
+- cached or incremental builds that understand package boundaries
+
+## Hot overlap surfaces
+
+- root lockfiles and workspace config
+- generated API clients or shared schema packages
+- lint or formatting config consumed by every package
+- root TypeScript config inheritance
+- package `exports` used by many apps
+
+## Safe workspace moves
+
+- change one package contract at a time
+- rebuild direct consumers when shared types change
+- keep import paths package-based rather than source-path based when publishability matters
+- document cross-package breaking changes even inside a single repo

package/targets/claude-code/adapter.json

@@ -0,0 +1,56 @@
+{
+  "id": "claude-code",
+  "displayName": "Claude Code",
+  "installRootStrategy": "repo-root",
+  "pathMappings": {
+    "AGENTS.md": "CLAUDE.md",
+    ".agents/skills": ".agents/skills",
+    ".specify": ".specify",
+    "templates/tasks/implement-feature.md": ".claude/templates/tasks/implement-feature.md",
+    "templates/tasks/fix-bug.md": ".claude/templates/tasks/fix-bug.md",
+    "templates/workflows/research-plan-implement-validate.md": ".claude/templates/workflows/research-plan-implement-validate.md",
+    "templates/workflows/triage-reproduce-fix-verify.md": ".claude/templates/workflows/triage-reproduce-fix-verify.md",
+    "targets/claude-code/runtime/.claude": ".claude"
+  },
+  "mergeRules": {
+    "AGENTS.md": "copy"
+  },
+  "supportsHooks": true,
+  "supportsCommands": true,
+  "supportsAgents": true,
+  "supportsContexts": true,
+  "supportsPlugins": true,
+  "capabilitySupportRef": "manifests/catalog/harness-capability-matrix.json",
+  "capabilityMatrix": {
+    "templates": true,
+    "workflow-validation": true
+  },
+  "sharedRuntimeBridge": {
+    "instructionSurfaces": [
+      "CLAUDE.md",
+      ".agents/skills",
+      ".claude/settings.json"
+    ],
+    "runtimeSurfaces": [
+      ".hforge/runtime/index.json",
+      ".hforge/runtime/README.md"
+    ],
+    "supportMode": "native",
+    "notes": "Claude Code keeps repo-root and .claude bridges thin while canonical skills, rules, knowledge, and templates live under the hidden .hforge layer.",
+    "authoritativeSurfaces": [
+      ".hforge/library/skills",
+      ".hforge/library/rules",
+      ".hforge/library/knowledge",
+      ".hforge/templates",
+      ".hforge/runtime"
+    ],
+    "visibleBridgePaths": [
+      "CLAUDE.md",
+      ".agents/skills",
+      ".specify",
+      ".claude"
+    ],
+    "visibilityMode": "hidden-ai-layer"
+  },
+  "guidanceTemplate": "claude-code"
+}

package/targets/claude-code/runtime/.claude/CLAUDE.md

@@ -0,0 +1,3 @@
+# Claude Code runtime
+
+Use the promoted language skills, `.specify/` flow, and shared release gates.

package/targets/claude-code/runtime/.claude/agents/documentation-lookup.md

@@ -0,0 +1,3 @@
+# Documentation Lookup
+
+Starter prompt for documentation lookup.

package/targets/claude-code/runtime/.claude/agents/release-readiness.md

@@ -0,0 +1,3 @@
+# Release Readiness
+
+Starter prompt for release readiness.

package/targets/claude-code/runtime/.claude/agents/repo-onboarding.md

@@ -0,0 +1,3 @@
+# Repo Onboarding
+
+Starter prompt for repo onboarding.

package/targets/claude-code/runtime/.claude/agents/security-scan.md

@@ -0,0 +1,3 @@
+# Security Scan
+
+Starter prompt for security scan.

package/targets/claude-code/runtime/.claude/hooks/post-tool-use.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+if [ -x hooks/shared/post-change-summary.sh ]; then exec hooks/shared/post-change-summary.sh; fi
+echo "[hforge] post-tool-use"

package/targets/claude-code/runtime/.claude/hooks/pre-tool-use.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+if [ -x hooks/shared/pre-change-quality-gate.sh ]; then exec hooks/shared/pre-change-quality-gate.sh; fi
+echo "[hforge] pre-tool-use"

package/targets/claude-code/runtime/.claude/settings.json

@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/pre-tool-use.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/post-tool-use.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/targets/codex/adapter.json

@@ -0,0 +1,56 @@
+{
+  "id": "codex",
+  "displayName": "Codex",
+  "installRootStrategy": "repo-root",
+  "pathMappings": {
+    "AGENTS.md": "AGENTS.md",
+    ".agents/skills": ".agents/skills",
+    ".specify": ".specify",
+    "templates/tasks/implement-feature.md": ".hforge/templates/tasks/implement-feature.md",
+    "templates/tasks/fix-bug.md": ".hforge/templates/tasks/fix-bug.md",
+    "templates/workflows/research-plan-implement-validate.md": ".hforge/templates/workflows/research-plan-implement-validate.md",
+    "templates/workflows/triage-reproduce-fix-verify.md": ".hforge/templates/workflows/triage-reproduce-fix-verify.md",
+    "targets/codex/runtime/.codex": ".codex"
+  },
+  "mergeRules": {
+    "AGENTS.md": "append-once"
+  },
+  "supportsHooks": false,
+  "supportsCommands": true,
+  "supportsAgents": true,
+  "supportsContexts": true,
+  "supportsPlugins": false,
+  "capabilitySupportRef": "manifests/catalog/harness-capability-matrix.json",
+  "capabilityMatrix": {
+    "templates": true,
+    "workflow-validation": true
+  },
+  "sharedRuntimeBridge": {
+    "instructionSurfaces": [
+      "AGENTS.md",
+      ".agents/skills",
+      ".codex/config.toml"
+    ],
+    "runtimeSurfaces": [
+      ".hforge/runtime/index.json",
+      ".hforge/runtime/README.md"
+    ],
+    "supportMode": "native",
+    "notes": "Codex keeps repo-root bridges thin and routes canonical AI content through the hidden .hforge library, template, and runtime layer.",
+    "authoritativeSurfaces": [
+      ".hforge/library/skills",
+      ".hforge/library/rules",
+      ".hforge/library/knowledge",
+      ".hforge/templates",
+      ".hforge/runtime"
+    ],
+    "visibleBridgePaths": [
+      "AGENTS.md",
+      ".agents/skills",
+      ".specify",
+      ".codex"
+    ],
+    "visibilityMode": "hidden-ai-layer"
+  },
+  "guidanceTemplate": "codex"
+}

package/targets/codex/runtime/.codex/README.md

@@ -0,0 +1,3 @@
+# Codex runtime
+
+Keep `.codex/config.toml` in the repo and use the merge helper when you want the same managed block in `~/.codex/config.toml`.

package/targets/codex/runtime/.codex/config.toml

@@ -0,0 +1,15 @@
+model = "gpt-5-codex"
+approval_policy = "on-request"
+sandbox_mode = "workspace-write"
+
+[mcp_servers.openai_docs]
+command = "npx"
+args = ["mcp-remote", "https://developers.openai.com/mcp"]
+
+[mcp_servers.context7]
+command = "npx"
+args = ["-y", "@upstash/context7-mcp@latest"]
+
+[mcp_servers.playwright]
+command = "npx"
+args = ["@playwright/mcp@latest"]

package/targets/cursor/adapter.json

@@ -0,0 +1,56 @@
+{
+  "id": "cursor",
+  "displayName": "Cursor",
+  "installRootStrategy": "repo-root",
+  "pathMappings": {
+    "AGENTS.md": "AGENTS.md",
+    ".agents/skills": ".agents/skills",
+    ".specify": ".specify"
+  },
+  "mergeRules": {},
+  "supportsHooks": false,
+  "supportsCommands": true,
+  "supportsAgents": false,
+  "supportsContexts": false,
+  "supportsPlugins": false,
+  "capabilitySupportRef": "manifests/catalog/harness-capability-matrix.json",
+  "capabilityMatrix": {
+    "templates": true,
+    "workflow-validation": false,
+    "repo-intelligence": true,
+    "flow-orchestration": false,
+    "typed-hooks": false,
+    "maintenance": false,
+    "observability": false
+  },
+  "supportLevel": "partial",
+  "supportNotes": [
+    "Content, manifests, and benchmark-driven recommendations are portable.",
+    "No first-class Cursor runtime mapping, hooks, or flow-state recovery surface ships in this package."
+  ],
+  "sharedRuntimeBridge": {
+    "instructionSurfaces": [
+      "AGENTS.md",
+      ".agents/skills"
+    ],
+    "runtimeSurfaces": [
+      ".hforge/runtime/index.json",
+      ".hforge/runtime/README.md"
+    ],
+    "supportMode": "translated",
+    "notes": "Cursor relies on thin visible bridges and the hidden .hforge runtime instead of a native runtime payload or root-visible canonical content.",
+    "authoritativeSurfaces": [
+      ".hforge/library/skills",
+      ".hforge/library/rules",
+      ".hforge/library/knowledge",
+      ".hforge/templates",
+      ".hforge/runtime"
+    ],
+    "visibleBridgePaths": [
+      "AGENTS.md",
+      ".agents/skills",
+      ".specify"
+    ],
+    "visibilityMode": "hidden-ai-layer"
+  }
+}

package/targets/opencode/adapter.json

@@ -0,0 +1,56 @@
+{
+  "id": "opencode",
+  "displayName": "OpenCode",
+  "installRootStrategy": "repo-root",
+  "pathMappings": {
+    "AGENTS.md": "AGENTS.md",
+    ".agents/skills": ".agents/skills",
+    ".specify": ".specify"
+  },
+  "mergeRules": {},
+  "supportsHooks": false,
+  "supportsCommands": true,
+  "supportsAgents": false,
+  "supportsContexts": false,
+  "supportsPlugins": false,
+  "capabilitySupportRef": "manifests/catalog/harness-capability-matrix.json",
+  "capabilityMatrix": {
+    "templates": true,
+    "workflow-validation": false,
+    "repo-intelligence": true,
+    "flow-orchestration": false,
+    "typed-hooks": false,
+    "maintenance": false,
+    "observability": false
+  },
+  "supportLevel": "partial",
+  "supportNotes": [
+    "Content, manifests, and recommendation metadata are portable.",
+    "No first-class OpenCode runtime mapping, hooks, or flow-state recovery surface ships in this package."
+  ],
+  "sharedRuntimeBridge": {
+    "instructionSurfaces": [
+      "AGENTS.md",
+      ".agents/skills"
+    ],
+    "runtimeSurfaces": [
+      ".hforge/runtime/index.json",
+      ".hforge/runtime/README.md"
+    ],
+    "supportMode": "translated",
+    "notes": "OpenCode relies on thin visible bridges and the hidden .hforge runtime instead of a native runtime payload or root-visible canonical content.",
+    "authoritativeSurfaces": [
+      ".hforge/library/skills",
+      ".hforge/library/rules",
+      ".hforge/library/knowledge",
+      ".hforge/templates",
+      ".hforge/runtime"
+    ],
+    "visibleBridgePaths": [
+      "AGENTS.md",
+      ".agents/skills",
+      ".specify"
+    ],
+    "visibilityMode": "hidden-ai-layer"
+  }
+}

package/templates/instructions/cursor-rule-template.mdc

@@ -0,0 +1,7 @@
+# Cursor Rule Template
+
+Use this rule when Cursor needs a narrow, inspectable adaptation of the root
+guidance rather than a claim of native runtime parity. Cursor should treat
+`AGENTS.md`, `.agents/skills/`, `.hforge/runtime/index.json`, and the hidden
+`.hforge/library/` surfaces as the bridge into the AI layer, not as evidence
+of a native runtime install.