hammerkit 1.6.0 → 1.7.0

package/.agents/skills/before-commit/SKILL.md

@@ -1,101 +0,0 @@
----
-name: before-commit
-description: Pre-commit checklist for the hammerkit repo. Run the same gates CI enforces — prettier, eslint, tsc build, and the unit suite — before committing, so a push doesn't fail the build/test workflows. Use before any git commit in this repository.
----
-
-# Before committing (hammerkit)
-
-Run these locally before `git commit`/`git push`. Each maps to a GitHub Actions
-gate; passing them locally is the difference between a green push and a red one.
-Run from the repo root.
-
-Making a gate pass means **fixing the cause**, not disabling the check (no skipped
-tests, no relaxed lint/prettier config to dodge an error) — see the `do-the-work`
-skill.
-
-## 1. Prettier — the most common CI break
-
-The `build` workflow runs `prettier --check 'src/**'`, and it is **strict**: a
-single unformatted file fails the entire `build` workflow (even if your own
-changes are clean — it checks all of `src/`).
-
-```bash
-node_modules/.bin/prettier --check 'src/**'
-```
-
-If it reports issues, fix them:
-
-```bash
-npm run format   # prettier -w src/** && eslint . --fix --ext .ts
-```
-
-Style is enforced: no semicolons, single quotes, 120 cols, 2-space indent,
-trailing commas `es5`.
-
-## 2. ESLint
-
-```bash
-npm run lint     # eslint . --ext .ts
-```
-
-Note `no-console: error` — never write to `console.*` in `src/`. Route output
-through the `Environment` (`stdout`/`stderr`/`console`/`status`).
-
-## 3. Typecheck / build
-
-```bash
-npm run build    # tsc -b tsconfig.json
-```
-
-This typechecks spec files too, so it catches test-only type errors.
-
-## 4. Unit tests — mirror CI with `CI=true`
-
-```bash
-CI=true npm test
-```
-
-Run with `CI=true`. In CI the container/k8s tests gate themselves to a no-op
-when their env flag is unset (see `src/testing/requires-*.ts`); **without**
-`CI=true` those same tests try to talk to Docker/Kubernetes locally and fail.
-The unit suite (`jest`) excludes `src/testing/integration/`, so it needs no
-Docker.
-
-Single test while iterating:
-
-```bash
-node_modules/.bin/jest src/path/to/file.spec.ts -t "test name"
-```
-
-## 5. Integration tests — only when you touched docker / k8s / execution
-
-These need a running Docker daemon (and are slow). They are **not** required for
-most commits; the self-hosted `integration` workflow covers them. Run locally
-only if your change affects container/k8s execution:
-
-```bash
-# Docker must be running. CI runs this --runInBand.
-LINUX_CONTAINERS=true npm run test:integration -- --runInBand
-```
-
-Add `CLUSTER_NAME=<kube-context>` to also exercise the kubernetes specs.
-
-## Cross-platform note
-
-The `test` workflow runs the unit suite on **ubuntu, windows, and macos**, plus
-a `macos-containers` job. Keep changes portable:
-
-- Build paths with `path` helpers; in tests, make separator-sensitive
-  expectations native (`val.split(posix.sep).join(sep)`) rather than hardcoding
-  `/` — see `src/planner/utils/parse-work-mount.spec.ts`.
-- File-watch + repeated process-spawn tests are unreliable on Windows hosted
-  runners; the watch-restart cases in `src/executer/execute.spec.ts` are gated
-  off win32. If you add similar tests, expect to gate them too.
-
-## One-liner
-
-```bash
-node_modules/.bin/prettier --check 'src/**' && npm run lint && npm run build && CI=true npm test
-```
-
-If all four pass, the `build` and `test` workflows should pass on push.

package/.agents/skills/do-the-work/SKILL.md

@@ -1,64 +0,0 @@
----
-name: do-the-work
-description: >-
-  Do the actual work instead of avoiding it, and don't make the user repeat
-  feedback. Use whenever the task is to fix something — fix CI, fix a failing or
-  flaky test, fix the build, make a check green, resolve a bug — or any time you
-  are tempted to skip, disable, exclude, defer, or stop early. Read and apply the
-  repo feedback log before working; append to it when corrected.
----
-
-# Do the work (hammerkit)
-
-The job is to **fix the thing**, not to find a way around fixing it. This skill
-exists because avoidance kept showing up as the default reflex, and because the
-user does not want to repeat feedback he has already given.
-
-## The contract
-
-When the task is to make something pass — CI, a test, the build, a check — the
-deliverable is that it passes **because the underlying problem is fixed**. The
-following are *never* the resolution (only do them if the user explicitly asks in
-this conversation):
-
-- `.skip` / `it.skip` / `describe.skip` / `xfail` / `test.todo`
-- excluding files or paths from a suite, or commenting-out / deleting a test
-- loosening or removing an assertion so it stops failing
-- raising a timeout to a giant fixed value to paper over a hang
-- declaring something "flaky locally" and moving on
-- stopping early and handing back an unfixed failure as if it were done
-
-Instead: diagnose the root cause (timing, environment, file-watching, resource
-leaks, ordering, a real bug) and fix it so the check passes legitimately. If a
-failure is genuinely container/k8s/infra-only and can't be reproduced on this
-host, **say so explicitly** and rely on CI to confirm — that is honest reporting,
-not skipping.
-
-## Good questions vs. avoidance dressed as a question
-
-- **Ask freely:** how to implement something, which design/approach to take,
-  genuine ambiguity in the requirements, trade-offs that change the outcome. These
-  are welcome.
-- **Don't ask — just do it:** "Can I skip this test?", "Is it ok to leave this
-  failing?", "Should I just remove/disable it?", "Want me to stop here?" If the
-  effect of the question is to *avoid the assigned work*, the answer is already no
-  — do the work.
-- **Only escalate when truly blocked:** missing access/credentials, a product
-  decision only the user can make, or contradictory requirements. Even then,
-  propose the fix path, not the avoidance.
-
-## Feedback discipline (don't make the user repeat himself)
-
-The repo keeps a durable log at `.agents/FEEDBACK.md`.
-
-1. **Read it before you start working** and apply every rule there.
-2. **Don't re-ask anything it already answers.**
-3. **When the user corrects you or states a preference, append an entry to it
-   immediately** (rule + **Why** + **How to apply** + date), so it's never
-   re-litigated.
-
-## Canonical instance
-
-"Never skip tests to go green" is the sharpest example of the contract — see the
-`never skip tests` rule in `.agents/FEEDBACK.md`. The `fix-ci` and `before-commit`
-skills are how you actually fix CI without skipping.

package/.agents/skills/fix-ci/SKILL.md

@@ -1,98 +0,0 @@
----
-name: fix-ci
-description: >-
-  Iterate until CI is green on the current branch. Use when GitHub Actions is red, a push
-  broke the build, or the user asks to "fix CI" / "get CI green". Loop: read the failing run
-  via gh -> diagnose the root cause from the logs -> implement a fix -> verify locally with
-  the before-commit skill -> commit -> push -> watch the run -> repeat on failure.
----
-
-# Fix CI (hammerkit)
-
-Drive CI to green on the current branch. This skill is the **loop around a fix**; for the
-actual local checks, use the **`before-commit`** skill — do not re-run an ad-hoc checklist
-here.
-
-Repeat until the run is green:
-**check status → diagnose → fix → verify (before-commit) → commit → push → watch → repeat.**
-
-## Step 1 — Check CI status
-
-```bash
-git branch --show-current
-gh run list --branch "$(git branch --show-current)" --limit 5
-gh run view <run-id> --log-failed     # or: gh pr checks   (if a PR is open)
-```
-
-Identify the failing **job** and **step**, then read its log to pin the root cause. Use this
-workflow → gate map only to decide which `before-commit` gate to re-run (the command details
-live in `before-commit`, not here):
-
-- `build` → prettier (strict over all of `src/`), eslint, tsc build.
-- `test` → the jest unit matrix on **ubuntu, windows, macos** (+ a `macos-containers` job).
-- `integration` / `macos-containers` → docker/k8s tests; need Docker/Kubernetes and usually
-  **cannot** be reproduced locally.
-
-## Step 2 — Implement a fix
-
-Make the **smallest** change that addresses the identified root cause. Repo conventions are
-enforced by `before-commit`'s gates, so don't restate them — just keep the change clean. For
-OS-specific (e.g. windows-only) or container/k8s failures, note that the fix may only be
-verifiable in CI, not on this host.
-
-## Step 3 — Verify locally (use `before-commit`)
-
-Run the **`before-commit` skill** to run the same gates CI enforces, then re-run the
-specific failing case while iterating (e.g.
-`node_modules/.bin/jest src/path/to/file.spec.ts -t "test name"`).
-
-If the failure is container/k8s-only and can't be reproduced on this host, **say so
-explicitly** and rely on CI to confirm — never claim a gate passed that you didn't run.
-
-## Step 4 — Commit
-
-Stage only the files relevant to the fix and commit with a clear `type(scope): summary`
-message describing the CI problem fixed (matching the repo's git-log style, e.g.
-`fix: ...`, `test(ci): ...`, `style: ...`).
-
-## Step 5 — Push
-
-Push the current branch to its remote. (Never force-push.)
-
-## Step 6 — Wait for CI
-
-Watch the run produced by the push to completion:
-
-```bash
-gh run watch <run-id> --exit-status     # resolve <run-id> from the just-pushed commit
-```
-
-Or poll `gh run list --branch <branch>` / `gh pr checks` until the run finishes.
-
-## Step 7 — Loop on red
-
-- **Green** → report success and stop.
-- **Red** → go back to Step 1 with the new failing logs and repeat.
-
-## Guardrails
-
-- **Fix the failure; never skip it.** Getting CI green means fixing what's broken —
-  not skipping, disabling, excluding, `.skip`/`xfail`, weakening an assertion, or
-  deleting the failing test. That defeats the whole point of this skill. See the
-  `do-the-work` skill and `.agents/FEEDBACK.md`.
-- Cap attempts (~3–5). If the **same** failure recurs across iterations, stop and surface it.
-- Treat infra/flake as not-your-bug: the `integration` workflow runs on a self-hosted runner,
-  and the `macos-containers` job uses colima (flaky, slow). If a failure looks like infra,
-  stop and tell the user rather than looping.
-- Never force-push and never touch files unrelated to the fix.
-
-## Quick reference (gh — unique to this skill)
-
-```bash
-gh run list --branch <branch> --limit 5     # latest runs for the branch
-gh run view <run-id> --log-failed           # failing logs only
-gh pr checks                                 # status when a PR is open
-gh run watch <run-id> --exit-status          # block until done; non-zero on failure
-```
-
-For local verification commands, see the **`before-commit`** skill.

package/.agents/skills/speckit-git-commit/SKILL.md

@@ -1,53 +0,0 @@
----
-name: speckit-git-commit
-description: Auto-commit changes after a Spec Kit command completes
-compatibility: Requires spec-kit project structure with .specify/ directory
-metadata:
-  author: github-spec-kit
-  source: git:commands/speckit.git.commit.md
----
-
-# Auto-Commit Changes
-
-Automatically stage and commit all changes after a Spec Kit command completes.
-
-## Behavior
-
-This command is invoked as a hook after (or before) core commands. It:
-
-1. Determines the event name from the hook context (e.g., if invoked as an `after_specify` hook, the event is `after_specify`; if `before_plan`, the event is `before_plan`)
-2. Checks `.specify/extensions/git/git-config.yml` for the `auto_commit` section
-3. Looks up the specific event key to see if auto-commit is enabled
-4. Falls back to `auto_commit.default` if no event-specific key exists
-5. Uses the per-command `message` if configured, otherwise a default message
-6. If enabled and there are uncommitted changes, runs `git add .` + `git commit`
-
-## Execution
-
-Determine the event name from the hook that triggered this command, then run the script:
-
-- **Bash**: `.specify/extensions/git/scripts/bash/auto-commit.sh <event_name>`
-- **PowerShell**: `.specify/extensions/git/scripts/powershell/auto-commit.ps1 <event_name>`
-
-Replace `<event_name>` with the actual hook event (e.g., `after_specify`, `before_plan`, `after_implement`).
-
-## Configuration
-
-In `.specify/extensions/git/git-config.yml`:
-
-```yaml
-auto_commit:
-  default: false          # Global toggle — set true to enable for all commands
-  after_specify:
-    enabled: true          # Override per-command
-    message: "[Spec Kit] Add specification"
-  after_plan:
-    enabled: false
-    message: "[Spec Kit] Add implementation plan"
-```
-
-## Graceful Degradation
-
-- If Git is not available or the current directory is not a repository: skips with a warning
-- If no config file exists: skips (disabled by default)
-- If no changes to commit: skips with a message

package/.agents/skills/speckit-git-feature/SKILL.md

@@ -1,72 +0,0 @@
----
-name: speckit-git-feature
-description: Create a feature branch with sequential or timestamp numbering
-compatibility: Requires spec-kit project structure with .specify/ directory
-metadata:
-  author: github-spec-kit
-  source: git:commands/speckit.git.feature.md
----
-
-# Create Feature Branch
-
-Create and switch to a new git feature branch for the given specification. This command handles **branch creation only** — the spec directory and files are created by the core `/speckit-specify` workflow.
-
-## User Input
-
-```text
-$ARGUMENTS
-```
-
-You **MUST** consider the user input before proceeding (if not empty).
-
-## Environment Variable Override
-
-If the user explicitly provided `GIT_BRANCH_NAME` (e.g., via environment variable, argument, or in their request), pass it through to the script by setting the `GIT_BRANCH_NAME` environment variable before invoking the script. When `GIT_BRANCH_NAME` is set:
-- The script uses the exact value as the branch name, bypassing all prefix/suffix generation
-- `--short-name`, `--number`, and `--timestamp` flags are ignored
-- `FEATURE_NUM` is extracted from the name if it starts with a numeric prefix, otherwise set to the full branch name
-
-## Prerequisites
-
-- Verify Git is available by running `git rev-parse --is-inside-work-tree 2>/dev/null`
-- If Git is not available, warn the user and skip branch creation
-
-## Branch Numbering Mode
-
-Determine the branch numbering strategy by checking configuration in this order:
-
-1. Check `.specify/extensions/git/git-config.yml` for `branch_numbering` value
-2. Check `.specify/init-options.json` for `branch_numbering` value (backward compatibility)
-3. Default to `sequential` if neither exists
-
-## Execution
-
-Generate a concise short name (2-4 words) for the branch:
-- Analyze the feature description and extract the most meaningful keywords
-- Use action-noun format when possible (e.g., "add-user-auth", "fix-payment-bug")
-- Preserve technical terms and acronyms (OAuth2, API, JWT, etc.)
-
-Run the appropriate script based on your platform:
-
-- **Bash**: `.specify/extensions/git/scripts/bash/create-new-feature.sh --json --short-name "<short-name>" "<feature description>"`
-- **Bash (timestamp)**: `.specify/extensions/git/scripts/bash/create-new-feature.sh --json --timestamp --short-name "<short-name>" "<feature description>"`
-- **PowerShell**: `.specify/extensions/git/scripts/powershell/create-new-feature.ps1 -Json -ShortName "<short-name>" "<feature description>"`
-- **PowerShell (timestamp)**: `.specify/extensions/git/scripts/powershell/create-new-feature.ps1 -Json -Timestamp -ShortName "<short-name>" "<feature description>"`
-
-**IMPORTANT**:
-- Do NOT pass `--number` — the script determines the correct next number automatically
-- Always include the JSON flag (`--json` for Bash, `-Json` for PowerShell) so the output can be parsed reliably
-- You must only ever run this script once per feature
-- The JSON output will contain `BRANCH_NAME` and `FEATURE_NUM`
-
-## Graceful Degradation
-
-If Git is not installed or the current directory is not a Git repository:
-- Branch creation is skipped with a warning: `[specify] Warning: Git repository not detected; skipped branch creation`
-- The script still outputs `BRANCH_NAME` and `FEATURE_NUM` so the caller can reference them
-
-## Output
-
-The script outputs JSON with:
-- `BRANCH_NAME`: The branch name (e.g., `003-user-auth` or `20260319-143022-user-auth`)
-- `FEATURE_NUM`: The numeric or timestamp prefix used

package/.agents/skills/speckit-git-initialize/SKILL.md

@@ -1,54 +0,0 @@
----
-name: speckit-git-initialize
-description: Initialize a Git repository with an initial commit
-compatibility: Requires spec-kit project structure with .specify/ directory
-metadata:
-  author: github-spec-kit
-  source: git:commands/speckit.git.initialize.md
----
-
-# Initialize Git Repository
-
-Initialize a Git repository in the current project directory if one does not already exist.
-
-## Execution
-
-Run the appropriate script from the project root:
-
-- **Bash**: `.specify/extensions/git/scripts/bash/initialize-repo.sh`
-- **PowerShell**: `.specify/extensions/git/scripts/powershell/initialize-repo.ps1`
-
-If the extension scripts are not found, fall back to:
-- **Bash**: `git init && git add . && git commit -m "Initial commit from Specify template"`
-- **PowerShell**: `git init; git add .; git commit -m "Initial commit from Specify template"`
-
-The script handles all checks internally:
-- Skips if Git is not available
-- Skips if already inside a Git repository
-- Runs `git init`, `git add .`, and `git commit` with an initial commit message
-
-## Customization
-
-Replace the script to add project-specific Git initialization steps:
-- Custom `.gitignore` templates
-- Default branch naming (`git config init.defaultBranch`)
-- Git LFS setup
-- Git hooks installation
-- Commit signing configuration
-- Git Flow initialization
-
-## Output
-
-On success:
-- `[OK] Git repository initialized`
-
-## Graceful Degradation
-
-If Git is not installed:
-- Warn the user
-- Skip repository initialization
-- The project continues to function without Git (specs can still be created under `specs/`)
-
-If Git is installed but `git init`, `git add .`, or `git commit` fails:
-- Surface the error to the user
-- Stop this command rather than continuing with a partially initialized repository

package/.agents/skills/speckit-git-remote/SKILL.md

@@ -1,50 +0,0 @@
----
-name: speckit-git-remote
-description: Detect Git remote URL for GitHub integration
-compatibility: Requires spec-kit project structure with .specify/ directory
-metadata:
-  author: github-spec-kit
-  source: git:commands/speckit.git.remote.md
----
-
-# Detect Git Remote URL
-
-Detect the Git remote URL for integration with GitHub services (e.g., issue creation).
-
-## Prerequisites
-
-- Check if Git is available by running `git rev-parse --is-inside-work-tree 2>/dev/null`
-- If Git is not available, output a warning and return empty:
-  ```
-  [specify] Warning: Git repository not detected; cannot determine remote URL
-  ```
-
-## Execution
-
-Run the following command to get the remote URL:
-
-```bash
-git config --get remote.origin.url
-```
-
-## Output
-
-Parse the remote URL and determine:
-
-1. **Repository owner**: Extract from the URL (e.g., `github` from `https://github.com/github/spec-kit.git`)
-2. **Repository name**: Extract from the URL (e.g., `spec-kit` from `https://github.com/github/spec-kit.git`)
-3. **Is GitHub**: Whether the remote points to a GitHub repository
-
-Supported URL formats:
-- HTTPS: `https://github.com/<owner>/<repo>.git`
-- SSH: `git@github.com:<owner>/<repo>.git`
-
-> [!CAUTION]
-> ONLY report a GitHub repository if the remote URL actually points to github.com.
-> Do NOT assume the remote is GitHub if the URL format doesn't match.
-
-## Graceful Degradation
-
-If Git is not installed, the directory is not a Git repository, or no remote is configured:
-- Return an empty result
-- Do NOT error — other workflows should continue without Git remote information

package/.agents/skills/speckit-git-validate/SKILL.md

@@ -1,54 +0,0 @@
----
-name: speckit-git-validate
-description: Validate current branch follows feature branch naming conventions
-compatibility: Requires spec-kit project structure with .specify/ directory
-metadata:
-  author: github-spec-kit
-  source: git:commands/speckit.git.validate.md
----
-
-# Validate Feature Branch
-
-Validate that the current Git branch follows the expected feature branch naming conventions.
-
-## Prerequisites
-
-- Check if Git is available by running `git rev-parse --is-inside-work-tree 2>/dev/null`
-- If Git is not available, output a warning and skip validation:
-  ```
-  [specify] Warning: Git repository not detected; skipped branch validation
-  ```
-
-## Validation Rules
-
-Get the current branch name:
-
-```bash
-git rev-parse --abbrev-ref HEAD
-```
-
-The branch name must match one of these patterns:
-
-1. **Sequential**: `^[0-9]{3,}-` (e.g., `001-feature-name`, `042-fix-bug`, `1000-big-feature`)
-2. **Timestamp**: `^[0-9]{8}-[0-9]{6}-` (e.g., `20260319-143022-feature-name`)
-
-## Execution
-
-If on a feature branch (matches either pattern):
-- Output: `✓ On feature branch: <branch-name>`
-- Check if the corresponding spec directory exists under `specs/`:
-  - For sequential branches, look for `specs/<prefix>-*` where prefix matches the numeric portion
-  - For timestamp branches, look for `specs/<prefix>-*` where prefix matches the `YYYYMMDD-HHMMSS` portion
-- If spec directory exists: `✓ Spec directory found: <path>`
-- If spec directory missing: `⚠ No spec directory found for prefix <prefix>`
-
-If NOT on a feature branch:
-- Output: `✗ Not on a feature branch. Current branch: <branch-name>`
-- Output: `Feature branches should be named like: 001-feature-name or 20260319-143022-feature-name`
-
-## Graceful Degradation
-
-If Git is not installed or the directory is not a Git repository:
-- Check the `SPECIFY_FEATURE` environment variable as a fallback
-- If set, validate that value against the naming patterns
-- If not set, skip validation with a warning

package/.devcontainer/Dockerfile

@@ -1,5 +0,0 @@
-FROM node:24-alpine
-
-RUN apk add git npm
-
-USER root

package/.devcontainer/devcontainer.json

@@ -1,40 +0,0 @@
-// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:
-// https://github.com/microsoft/vscode-dev-containers/tree/v0.195.0/containers/javascript-node
-{
-	"name": "Hammerkit",
-	"build": {
-		"dockerfile": "Dockerfile"
-	},
-
-	// Configure tool-specific properties.
-	"customizations": {
-		// Configure properties specific to VS Code.
-		"vscode": {
-			// Set *default* container specific settings.json values on container create.
-			"settings": {},
-			
-			// Add the IDs of extensions you want installed when the container is created.
-			"extensions": [
-				"dbaeumer.vscode-eslint"
-			]
-		}
-	},
-
-	// Use 'forwardPorts' to make a list of ports inside the container available locally.
-	// "forwardPorts": [3000],
-
-	// Use 'portsAttributes' to set default properties for specific forwarded ports. More info: https://code.visualstudio.com/docs/remote/devcontainerjson-reference.
-	"portsAttributes": {
-	},
-
-	// Use 'otherPortsAttributes' to configure any ports that aren't configured using 'portsAttributes'.
-	// "otherPortsAttributes": {
-	// 		"onAutoForward": "silent"
-	// },
-
-	// Use 'postCreateCommand' to run commands after the container is created.
-	"postCreateCommand": "npm install",
-
-	// Comment out connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
-	"remoteUser": "node"
-}

package/.gitbook.yaml

@@ -1,5 +0,0 @@
-root: ./
-
-structure:
-  readme: README.md
-  summary: SUMMARY.md

package/.specify/extensions/.registry

@@ -1,37 +0,0 @@
-{
-  "schema_version": "1.0",
-  "extensions": {
-    "git": {
-      "version": "1.0.0",
-      "source": "local",
-      "manifest_hash": "sha256:9731aa8143a72fbebfdb440f155038ab42642517c2b2bdbbf67c8fdbe076ed79",
-      "enabled": true,
-      "priority": 10,
-      "registered_commands": {
-        "agy": [
-          "speckit.git.feature",
-          "speckit.git.validate",
-          "speckit.git.remote",
-          "speckit.git.initialize",
-          "speckit.git.commit"
-        ],
-        "claude": [
-          "speckit.git.feature",
-          "speckit.git.validate",
-          "speckit.git.remote",
-          "speckit.git.initialize",
-          "speckit.git.commit"
-        ],
-        "codex": [
-          "speckit.git.feature",
-          "speckit.git.validate",
-          "speckit.git.remote",
-          "speckit.git.initialize",
-          "speckit.git.commit"
-        ]
-      },
-      "registered_skills": [],
-      "installed_at": "2026-05-30T06:27:46.894357+00:00"
-    }
-  }
-}