HitKeep Local Development and Contribution Setup

HitKeep uses the repository-owned ./hk CLI as the canonical development workflow for people, automation, and coding agents. It owns setup, workspace isolation, development variants, 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

hk reads pinned tool versions from the repository and prepares the selected Git worktree. Check prerequisites and the current isolated workspace at any time:

./hk doctor
./hk workspace status

Use ./hk help for the current command reference. Agents and automation should use ./hk catalog --output json rather than copying variants, build tags, QA gates, ports, or tool versions into prompts and scripts.

Develop

Start the normal native development workflow with realistic seed data:

./hk dev --seed

Use the container-backed runtime when host prerequisites are unavailable or container parity matters:

./hk dev --runtime container --seed

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.

Long operations wait by default for humans. Agents can detach and consume the versioned JSON result envelope:

./hk dev --detach --output json
./hk run status <run_id> --output json
./hk run logs <run_id> --limit 80 --output json

Complete logs remain on disk at returned artifact 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.

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 a worktree-specific registration 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 versioned schema, workspace ID, isolated server name, stable launcher path, stdio transport, and exact arguments. hk does not silently edit client-owned configuration.

The registration launches ./hk mcp serve over stdio for the selected worktree.

The generated registration is equivalent to:

{
  "mcpServers": {
    "hitkeep-dev-<workspace-id>": {
      "command": "/absolute/path/to/worktree/hk",
      "args": ["--workspace", "/absolute/path/to/worktree", "mcp", "serve"]
    }
  }
}

Register the generated definition in the MCP client, restart or reload it, and verify discovery with hk_workspace_status. Configure one stdio MCP process per worktree. 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 structured ./hk --output json fallback when MCP is unavailable.

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 and structured 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.