HitKeep Local Development and Contribution Setup

Esta página aún no está disponible en tu idioma.

HitKeep uses the repository-owned ./hk CLI as the canonical development workflow for people, automation, and coding agents. It owns container setup, workspace isolation, development sessions, builds, smoke tests, QA planning, and concise structured output.

The root CONTRIBUTING.md and AGENTS.md remain the repository policy sources. This page provides the maintained public onboarding path.

Documentation source boundary

The HitKeep application repository and its contributor skills are public and MIT licensed. This rendered documentation website is public, but the PascaleBeier/hitkeep-docs source repository is private by design and is not included in the application’s MIT license.

External contributors should describe documentation impact in the public application pull request or issue. Maintainers with access apply the corresponding website change; contributors are not expected to edit or clone the private documentation repository.

Prepare a checkout

git clone https://github.com/pascalebeier/hitkeep.git
cd hitkeep
./hk setup

The checked-in ./hk file is an executable POSIX launcher, not a compiled binary. It builds the current worktree’s developer CLI locally and caches the native executable by source content. Supported hosts are macOS and Linux on AMD64 or ARM64; WSL2 follows the Linux path, while WSL1 is not supported. The exact repository Go version is used directly when available, with Docker as the first-bootstrap fallback.

Developer CLI binaries are neither committed nor published as HitKeep release assets. Git keeps the launcher and implementation aligned with the checked-out branch; GitHub Releases contain deployable HitKeep product artifacts. hk reads pinned tool versions from the repository and prepares the selected Git worktree’s development containers. Host Go and Node installations remain useful for fast QA and source tooling, but Docker Compose is the only application development runtime. Check prerequisites and the current isolated workspace at any time:

./hk doctor
./hk workspace status

Use ./hk help and subcommand help for human guidance. Agents and automation should use ./hk catalog commands --output json for the complete command and flag inventory, and ./hk catalog --output json for variants and QA gates. Do not copy commands, build tags, ports, or tool versions into prompts and scripts.

Develop

Development is one container-only session per workspace. Start it in the foreground with realistic seed data:

./hk dev --seed

The foreground command prints workspace URLs and component-labelled logs. It owns the complete Compose stack, so pressing Ctrl+C stops the backend, frontend, Mailpit, log follower, and orphaned services. Running ./hk dev while an equivalent session is active reports its current state and URLs instead of starting a duplicate.

The everyday lifecycle is:

./hk dev
./hk dev logs
./hk dev restart
./hk dev stop
./hk dev reset --seed

restart preserves the selected workspace’s application data. reset stops development, deletes only that workspace’s development data, and starts a fresh session. A seed request never mutates an active session; use ./hk dev reset --seed when active development must be replaced with fresh seeded data.

Use the cloud variant only for local managed-cloud parity work:

./hk dev --variant cloud

Always open the URLs returned by ./hk workspace status. hk allocates workspace-specific ports, Compose project names, data, logs, artifacts, and generated configuration; conventional ports may belong to another worktree.

Use an explicit detached session when no terminal should own development:

./hk dev --detach --output json
./hk dev status --output json
./hk dev logs --cursor <next_cursor> --output json
./hk dev logs --follow --output ndjson

--detach waits until the session is ready or failed before returning. Development has status and event cursors, not a run or session ID. Human ./hk dev logs follows by default; pressing Ctrl+C detaches only that viewer. JSON log output is a bounded batch, while NDJSON supports event streaming. JSON start, restart, and reset require --detach; foreground NDJSON can stream lifecycle events.

Setup, QA, builds, and smoke tests remain finite asynchronous runs. Their CLI forms wait by default and accept --detach when a caller needs a run ID immediately:

./hk run list --output json
./hk run status <run_id> --output json
./hk run logs <run_id> --cursor <next_cursor> --limit 80 --output json
./hk run cancel <run_id> --output json

Complete logs and artifacts remain on disk at returned paths so successful output stays compact.

Build and smoke variants

Discover current variants and targets through ./hk help or the structured catalog, then use the typed build surface:

./hk build binary
./hk build image
./hk build image --variant cloud
./hk smoke --variant cloud

Cloud images are local-only and cannot be published by hk. Public release images continue to package self-hosted binaries, while managed cloud consumes its separate cloud-tagged artifact.

Format source

Formatting and pinned Go migrations use explicit, workspace-confined CLI operations:

./hk fmt
./hk fmt check
./hk fmt --scope frontend
./hk fmt check --scope frontend
./hk fix
./hk fix check

Go is the default formatting scope. Check modes do not modify files; write modes are deliberate source mutations and are not exposed through the developer MCP. Review the returned changed paths before continuing.

Validate changes

Use the change-aware profile while iterating, PR parity before review, and the exhaustive profile for release, cloud, or image risk:

./hk qa
./hk qa pr
./hk qa full

Inspect a plan without running it:

./hk qa plan changed --output json

Before opening a pull request, report the profile, stable gate IDs, run status, and any gate that could not run. Keep successful logs out of the report; retain run IDs and artifact paths.

Multiple worktrees and agents

Git worktree creation and deletion remain external responsibilities. hk never creates or deletes worktrees and never runs destructive Git cleanup.

./hk workspace list
./hk workspace handoff --output json

Workspace IDs, ports, mutable data, services, logs, artifacts, and generated configuration stay isolated. Safe dependency and compiler caches can be shared, allowing development and QA to run concurrently.

Local developer MCP

MCP-capable agents can call the same application services without parsing terminal output. Generate one central registration from a long-lived HitKeep clone instead of copying paths or server names by hand:

./hk mcp manifest

Human output is a copyable generic mcpServers object. Agents can use ./hk mcp manifest --output json for the hk.dev/mcp-manifest/v3 schema, central scope, client-root routing, workspace-MCP delegation, progress and logging notification support, stable launcher path, stdio transport, and exact arguments. hk does not silently edit client-owned configuration.

The registration launches ./hk mcp serve over stdio from that central clone.

The generated registration is equivalent to:

{
  "mcpServers": {
    "hitkeep-dev": {
      "command": "/absolute/path/to/central/hitkeep/hk",
      "args": ["mcp", "serve"]
    }
  }
}

Register the generated definition in the MCP client, restart or reload it, and verify discovery with hk_workspace_status. The central broker resolves the MCP client’s active HitKeep roots on every request, then delegates to the selected worktree’s own checked-in hk implementation. With multiple active HitKeep roots, tools accept an optional workspace name, workspace ID, or path. Clients without roots support can use an explicit worktree registration as a compatibility fallback.

Development tools are workspace-scoped: hk_dev_start, hk_dev_status, hk_dev_logs, and hk_dev_stop never require a run or session ID. Start and stop stream progress, component logs use structured logging notifications, and following logs ends on client cancellation without stopping development. hk_run_status, hk_run_list, hk_logs_tail, and hk_run_cancel are exclusively for finite operations. Reset and data deletion remain CLI-only.

The broker forwards the client’s progress token, progress notifications, structured logging, and cancellation to the selected workspace MCP. The developer MCP is separate from HitKeep’s production analytics /mcp endpoint. It cannot execute arbitrary commands, mutate Git, publish artifacts, manage credentials, delete worktrees, perform cleanup, or deploy infrastructure.

Contributor Agent Skills

Four canonical contributor skills live under .agents/skills:

Skill	Responsibility
`hitkeep-development`	Contribution routing, setup, development, build variants, and implementation references.
`hitkeep-workspace`	Isolated worktree state, services, ports, runs, logs, and handoff.
`hitkeep-qa`	Live QA planning, execution, failure investigation, and completion evidence.
`hitkeep-i18n`	Dashboard localization procedure and language-sensitive validation.

List or install only this pack by targeting its repository subdirectory:

npx skills add https://github.com/PascaleBeier/hitkeep/tree/main/.agents/skills --list

These are the canonical bodies used by repository agents; there is no generated proxy layer. Prefer the local developer MCP and use the machine-readable command catalog plus structured ./hk --output json fallback when MCP is unavailable.

Structured CLI and MCP starts request machine-readable output from supported child tools. The QA catalog exposes an agent_command when it differs from the human command. Tools without a JSON mode run without terminal color and remain bounded by the surrounding hk.dev/v2 envelope and cursor-addressed logs.

The separate skills/ directory contains end-user analytics skills paired with production MCP. Their transport-neutral procedures are shared with Ask AI, but they are not contributor instructions.

Documentation authority

Development facts follow this order:

./hk help, ./hk catalog commands --output json, and structured domain catalogs define current commands and facts.
The local developer MCP exposes typed live workspace operations.
Contributor skills provide workflow judgment and routing.
AGENTS.md defines repository policy and product invariants.
Root CONTRIBUTING.md and this guide provide onboarding narrative.

./hk skills check verifies both skill packs. ./hk docs check catches duplicated mutable workflow commands and documentation drift.

Submit a pull request

Keep the change focused and preserve unrelated worktree edits.
Follow the nearest existing implementation pattern and repository policy.
Run focused checks while iterating and ./hk qa pr before review when feasible.
Use a Conventional Commit message.
Report QA evidence, documentation impact, migrations, compatibility concerns, and anything that could not run.