From 0405583bd6cdf3b07610ee4600491329e961ae44 Mon Sep 17 00:00:00 2001 From: Kyle Adams Date: Wed, 5 Aug 2026 22:35:02 -0400 Subject: [PATCH 1/4] feat: improve pi compatibility and harness-agnostic config resolution --- .agents/plugins/marketplace.json | 48 ++++++++++ README.md | 27 +++++- docs/concepts.md | 4 +- docs/configuration.md | 23 ++++- docs/quickstart.md | 2 +- docs/templates/skill-long-form-template.md | 2 +- docs/why-solo-and-small-teams.md | 2 +- han-atlassian/references/config-rule.md | 17 ++-- .../code-overview-to-confluence/SKILL.md | 2 +- .../skills/investigate-to-confluence/SKILL.md | 2 +- .../skills/markdown-to-confluence/SKILL.md | 2 +- .../plan-a-feature-to-confluence/SKILL.md | 2 +- .../SKILL.md | 2 +- .../skills/work-items-to-jira/SKILL.md | 2 +- han-coding/references/config-rule.md | 17 ++-- .../skills/architectural-analysis/SKILL.md | 2 +- .../skills/automated-test-planning/SKILL.md | 2 +- han-coding/skills/code-overview/SKILL.md | 2 +- han-coding/skills/code-review/SKILL.md | 2 +- han-coding/skills/coding-standard/SKILL.md | 2 +- han-coding/skills/investigate/SKILL.md | 2 +- .../skills/manual-test-planning/SKILL.md | 2 +- han-coding/skills/refactor/SKILL.md | 2 +- han-coding/skills/tdd/SKILL.md | 2 +- han-communication/references/config-rule.md | 17 ++-- .../skills/edit-for-readability/SKILL.md | 2 +- .../skills/explanation-guidance/SKILL.md | 2 +- .../skills/readability-guidance/SKILL.md | 2 +- han-core/references/config-rule.md | 17 ++-- han-core/skills/project-discovery/SKILL.md | 2 +- han-documentation/references/config-rule.md | 17 ++-- .../architectural-decision-record/SKILL.md | 2 +- .../skills/project-documentation/SKILL.md | 2 +- han-documentation/skills/runbook/SKILL.md | 2 +- han-feedback/references/config-rule.md | 17 ++-- han-feedback/skills/han-feedback/SKILL.md | 2 +- han-github/references/config-rule.md | 17 ++-- .../skills/post-code-review-to-pr/SKILL.md | 2 +- .../skills/update-pr-description/SKILL.md | 2 +- .../skills/work-items-to-issues/SKILL.md | 2 +- han-linear/references/config-rule.md | 17 ++-- .../skills/work-items-to-linear/SKILL.md | 2 +- han-planning/references/config-rule.md | 17 ++-- .../skills/iterative-plan-review/SKILL.md | 2 +- han-planning/skills/plan-a-feature/SKILL.md | 2 +- .../skills/plan-a-phased-build/SKILL.md | 2 +- .../skills/plan-implementation/SKILL.md | 2 +- han-planning/skills/plan-work-items/SKILL.md | 2 +- han-plugin-builder/references/config-rule.md | 17 ++-- .../skills/agent-builder/SKILL.md | 2 +- han-plugin-builder/skills/guidance/SKILL.md | 2 +- .../context-injection-commands.md | 6 +- .../troubleshooting.md | 6 +- .../skills/skill-builder/SKILL.md | 2 +- han-reporting/references/config-rule.md | 17 ++-- han-reporting/skills/html-summary/SKILL.md | 2 +- .../skills/stakeholder-summary/SKILL.md | 2 +- han-research/references/config-rule.md | 17 ++-- han-research/skills/gap-analysis/SKILL.md | 2 +- han-research/skills/issue-triage/SKILL.md | 2 +- han-research/skills/research/SKILL.md | 2 +- package.json | 5 +- scripts/check-docs-host-wording.py | 85 +++++++++++++++++ scripts/check-pi-compat.py | 92 +++++++++++++++++++ 64 files changed, 431 insertions(+), 155 deletions(-) create mode 100644 scripts/check-docs-host-wording.py create mode 100644 scripts/check-pi-compat.py diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json index 81863116..28211c23 100644 --- a/.agents/plugins/marketplace.json +++ b/.agents/plugins/marketplace.json @@ -4,6 +4,18 @@ "displayName": "Han" }, "plugins": [ + { + "name": "han", + "source": { + "source": "local", + "path": "./han" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Developer Tools" + }, { "name": "han-communication", "source": { @@ -28,6 +40,30 @@ }, "category": "Developer Tools" }, + { + "name": "han-documentation", + "source": { + "source": "local", + "path": "./han-documentation" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Developer Tools" + }, + { + "name": "han-research", + "source": { + "source": "local", + "path": "./han-research" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Developer Tools" + }, { "name": "han-planning", "source": { @@ -100,6 +136,18 @@ }, "category": "Developer Tools" }, + { + "name": "han-linear", + "source": { + "source": "local", + "path": "./han-linear" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Developer Tools" + }, { "name": "han-plugin-builder", "source": { diff --git a/README.md b/README.md index e4698a5a..3a35f323 100644 --- a/README.md +++ b/README.md @@ -4,12 +4,12 @@ Han is a suite of AI skills and agents for solo (or small-team) product engineers. It combines evidence-based planning, test-driven implementation, full documentation maintenance, deep code review, and architectural analysis into a team of -specialists you can dispatch from Claude Code. +specialists you can dispatch from your coding-agent host, including Claude Code and Pi. ## What this plugin does Han turns planning, implementation, review, and documentation work that would normally take a team into a set of -deterministic skills you run from Claude Code. +deterministic skills you run from your coding-agent host. Each skill dispatches specialist agents, such as project managers, adversarial reviewers, investigators, architectural analysts, and testing and security specialists, to do the judgment-heavy work. It then folds their findings into an @@ -92,6 +92,29 @@ Install `han-feedback`, `han-atlassian`, `han-linear`, or `han-plugin-builder` s packages. Because Codex resolves no dependencies, install `han-communication` alongside `han-atlassian` (its wrapped prose-producing skills source the shared readability standard from it). +### Pi + +Han now ships a Pi marketplace manifest at `.agents/plugins/marketplace.json` with the same plugin set as the Claude +marketplace, including `han`, `han-documentation`, `han-research`, and `han-linear`. + +If you are installing through Pi, use this repository's `.agents/plugins/marketplace.json` as the source of truth for +available Han plugins. + +### Environment setup (optional) + +Han reads personal config from `{harness-config-root}/.han/config.md`. You can set `AGENT_CONFIG_DIR` to pick that +harness config root explicitly, independent of which host you are running under. + +```bash +# one-off +AGENT_CONFIG_DIR="$HOME/.config/agent" pi + +# persistent (zsh/bash profile) +export AGENT_CONFIG_DIR="$HOME/.config/agent" +``` + +Without this variable, Han falls back to `CLAUDE_CONFIG_DIR` and then `~/.claude`. + ## Documentation - [Concepts](./docs/concepts.md). Skill vs. agent, and how they compose. Read once before using the plugin. diff --git a/docs/concepts.md b/docs/concepts.md index 11d90060..5d81d962 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -38,7 +38,7 @@ Those three are the whole decision model. Everything else is vocabulary. ## Skills: the process layer -A skill is a fixed sequence of steps that Claude Code runs. Typing the slash command is the primary way to trigger it, +A skill is a fixed sequence of steps that your coding-agent host runs. Typing the slash command is the primary way to trigger it, but not the only one. - You invoke it: `/code-review`, `/plan-a-feature`, `/investigate`. This is the deliberate, primary path. @@ -204,7 +204,7 @@ table, and the fidelity guard. ## Configuration -Han reads two optional `.han/config.md` files on every skill run: a personal one in your Claude Code configuration +Han reads two optional `.han/config.md` files on every skill run: a personal one in your coding-agent configuration directory, and a project one at the project root. Either sets a base directory for the skills' markdown deliverables, a default swarm size for the sizing-aware skills, a writing-voice profile for the readability skills, and extra agents for the dispatching skills to consider. The personal file supplies defaults that follow you into every project, and the diff --git a/docs/configuration.md b/docs/configuration.md index 76c91016..aa453963 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,7 +1,7 @@ # Configuration Han reads two optional configuration files, and you can use either one or both. A personal `.han/config.md` in your -Claude Code configuration directory carries settings that follow you into every project. A project's own +coding-agent configuration directory carries settings that follow you into every project. A project's own `.han/config.md` adjusts those settings for that project. Both control where skills write their markdown deliverables, which extra agents dispatching skills consider, the default swarm size the sizing-aware skills start at, and the writing-voice profile the readability skills apply. Every Han skill reads both files on every run, so the overrides take @@ -31,11 +31,24 @@ effect without depending on the model remembering to look. Someone with neither ## Where each file goes -- **Personal:** `.han/config.md` inside your Claude Code configuration directory. That is `~/.claude` unless you have - set `CLAUDE_CONFIG_DIR`, in which case it is wherever that points. If you have moved your configuration directory, a - file left behind in `~/.claude/.han/` does not apply. +- **Personal:** `.han/config.md` inside your coding-agent configuration directory. The resolver checks + `AGENT_CONFIG_DIR` first, then `CLAUDE_CONFIG_DIR`, then falls back to `~/.claude`. If you have moved your configuration + directory, a file left behind in `~/.claude/.han/` does not apply. - **Project:** `.han/config.md` in the directory you run Han skills from. +### Environment setup (optional) + +If your harness stores user config outside `~/.claude`, set `AGENT_CONFIG_DIR` to the harness config root and Han will +read personal settings from `$AGENT_CONFIG_DIR/.han/config.md`. + +```bash +# one-off +AGENT_CONFIG_DIR="$HOME/.config/agent" pi + +# persistent (zsh/bash profile) +export AGENT_CONFIG_DIR="$HOME/.config/agent" +``` + Neither lookup walks up the directory tree. In a monorepo, each package can carry its own config; running a skill from a directory without one behaves as if the project file were absent, even when another directory in the repo has one. Your personal file still applies in all of them. @@ -50,7 +63,7 @@ Every setting is optional, everything unrecognized is ignored, and both files ta # folder and file structure beneath it, and creates the directory on first # write. A relative path is read from the folder holding this file, so the # same line means "inside this project" in a project config and "inside my -# Claude Code configuration directory" in a personal one. Full paths and a +# coding-agent configuration directory" in a personal one. Full paths and a # leading ~ are accepted, including paths outside the project. output-directory: docs/han diff --git a/docs/quickstart.md b/docs/quickstart.md index 4614c89f..7f04c2fe 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -126,7 +126,7 @@ need the real skill, spend it here. architectural decisions. 5. **[`.han/config.md`](./configuration.md)** _(as needed)._ Carry an optional config file to set a base directory for Han's markdown outputs, a default swarm size for the sizing-aware skills, a writing-voice profile, and extra agents - for dispatching skills to consider. Put it in your Claude Code configuration directory for settings that follow you + for dispatching skills to consider. Put it in your coding-agent configuration directory for settings that follow you everywhere, or at the project root for that project alone. **You are done when:** you have a `## Project Discovery` section in your AGENTS.md or CLAUDE.md and the docs and diff --git a/docs/templates/skill-long-form-template.md b/docs/templates/skill-long-form-template.md index d40f94f1..88dd680c 100644 --- a/docs/templates/skill-long-form-template.md +++ b/docs/templates/skill-long-form-template.md @@ -34,7 +34,7 @@ to use the skill. For what the skill does internally, read the skill definition ## How to invoke it -Run `/{skill-name}` in Claude Code. +Run `/{skill-name}` in your coding-agent host (for example Claude Code or Pi). Give it: diff --git a/docs/why-solo-and-small-teams.md b/docs/why-solo-and-small-teams.md index 5df7fde6..41b54279 100644 --- a/docs/why-solo-and-small-teams.md +++ b/docs/why-solo-and-small-teams.md @@ -3,7 +3,7 @@ _Audience: developers and engineering leaders evaluating Han for any team size. Time to read: about two minutes. Outcome: decide whether Han fits your situation, or stop here._ -> **Short answer.** Han is a Claude Code plugin that gives a single engineer the specialist coverage of a team. It does +> **Short answer.** Han is a coding-agent plugin suite that gives a single engineer the specialist coverage of a team. It does > not give a team the shared lift of an enterprise AI platform. If you need centralized governance, shared prompts > across developers, indexed org knowledge, or audited AI usage at org scale, Han is not your tool. Bolting those things > on later will cost more than starting with a product that includes them. If you are a solo engineer or a small team diff --git a/han-atlassian/references/config-rule.md b/han-atlassian/references/config-rule.md index 14b19bf2..ae9019d7 100644 --- a/han-atlassian/references/config-rule.md +++ b/han-atlassian/references/config-rule.md @@ -1,7 +1,7 @@ # Config Rule (`.han/config.md`) Han reads two optional configuration files, and either one may be absent. A person may carry a personal -`.han/config.md` inside their Claude Code configuration directory, and a consuming project may carry its own +`.han/config.md` inside their coding-agent configuration directory, and a consuming project may carry its own `.han/config.md`. The personal file supplies defaults that follow the person into every project; the project file adjusts them for that project. Each participating skill finds both through its `## Project Context` block; this rule defines how every skill interprets what that block yields, so one pair of files resolves identically across the whole @@ -12,9 +12,10 @@ suite. Every vendored copy of this file is byte-identical to the canonical `han- The `## Project Context` block carries two probe lines and directs one Read-tool call. This rule refers to each by the label it injects under, or by the file it reads. -- `personal config directory` (probe): the Claude Code configuration directory, resolved for this run. Named by the - `CLAUDE_CONFIG_DIR` environment variable when that variable is set, and `~/.claude` when it is not. This value is not - a setting. It is the folder a relative path in the personal file resolves against. +- `personal config directory` (probe): the coding-agent configuration directory, resolved for this run. Named by the + `AGENT_CONFIG_DIR` environment variable when that variable is set, otherwise by `CLAUDE_CONFIG_DIR` when that variable + is set, and `~/.claude` when neither is set. This value is not a setting. It is the folder a relative path in the + personal file resolves against. - The personal `.han/config.md` (Read tool): the content of `.han/config.md` inside that directory, or nothing. The skill reads this file itself as its first action rather than through a probe. A probe runs at skill load, where it cannot prompt and cannot degrade, so a permission decision against it aborts the skill instead of falling back to @@ -23,15 +24,15 @@ label it injects under, or by the file it reads. - `project .han/config.md` (probe): the content of `.han/config.md` in the directory the skill is running from, or nothing. -The two directories can both exist on one machine and point at different places, so the variable wins whenever it is -set. A personal file sitting in `~/.claude/.han/config.md` does not apply to a person who has pointed -`CLAUDE_CONFIG_DIR` somewhere else. +These directories can all exist on one machine and point at different places, so the first defined variable in the +precedence order wins. A personal file sitting in `~/.claude/.han/config.md` does not apply to a person who has pointed +`AGENT_CONFIG_DIR` or `CLAUDE_CONFIG_DIR` somewhere else. Neither lookup walks up the directory tree. The project file is found only in the directory the skill runs from, the same place the CLAUDE.md and project-discovery probes look. A config elsewhere in the repository does not apply. When neither lookup yields content, no config is present: behave exactly as the skill does without this rule, with no note. -When both lookups resolve to the same file, because the skill is running inside the Claude Code configuration +When both lookups resolve to the same file, because the skill is running inside the active coding-agent configuration directory, read it once and treat it as the project configuration. Nothing is counted twice, and its `## Extra Agents` list is one list. diff --git a/han-atlassian/skills/code-overview-to-confluence/SKILL.md b/han-atlassian/skills/code-overview-to-confluence/SKILL.md index 3641858d..f85acf53 100644 --- a/han-atlassian/skills/code-overview-to-confluence/SKILL.md +++ b/han-atlassian/skills/code-overview-to-confluence/SKILL.md @@ -17,7 +17,7 @@ allowed-tools: Read, Glob, Grep, Skill, Agent, Bash(find *), mcp__claude_ai_Atla ## Project Context -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-atlassian/skills/investigate-to-confluence/SKILL.md b/han-atlassian/skills/investigate-to-confluence/SKILL.md index f796d21a..acc292a7 100644 --- a/han-atlassian/skills/investigate-to-confluence/SKILL.md +++ b/han-atlassian/skills/investigate-to-confluence/SKILL.md @@ -16,7 +16,7 @@ allowed-tools: Read, Glob, Grep, Skill, Agent, Bash(find *), mcp__claude_ai_Atla ## Project Context -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-atlassian/skills/markdown-to-confluence/SKILL.md b/han-atlassian/skills/markdown-to-confluence/SKILL.md index aa9ce9d9..e9fe4554 100644 --- a/han-atlassian/skills/markdown-to-confluence/SKILL.md +++ b/han-atlassian/skills/markdown-to-confluence/SKILL.md @@ -18,7 +18,7 @@ allowed-tools: ## Project Context -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-atlassian/skills/plan-a-feature-to-confluence/SKILL.md b/han-atlassian/skills/plan-a-feature-to-confluence/SKILL.md index bd760869..dc2f2a73 100644 --- a/han-atlassian/skills/plan-a-feature-to-confluence/SKILL.md +++ b/han-atlassian/skills/plan-a-feature-to-confluence/SKILL.md @@ -18,7 +18,7 @@ allowed-tools: ## Project Context -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-atlassian/skills/project-documentation-to-confluence/SKILL.md b/han-atlassian/skills/project-documentation-to-confluence/SKILL.md index af563661..e8831996 100644 --- a/han-atlassian/skills/project-documentation-to-confluence/SKILL.md +++ b/han-atlassian/skills/project-documentation-to-confluence/SKILL.md @@ -17,7 +17,7 @@ allowed-tools: ## Project Context -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-atlassian/skills/work-items-to-jira/SKILL.md b/han-atlassian/skills/work-items-to-jira/SKILL.md index c15de891..ff79528e 100644 --- a/han-atlassian/skills/work-items-to-jira/SKILL.md +++ b/han-atlassian/skills/work-items-to-jira/SKILL.md @@ -21,7 +21,7 @@ allowed-tools: ## Project Context -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-coding/references/config-rule.md b/han-coding/references/config-rule.md index 14b19bf2..ae9019d7 100644 --- a/han-coding/references/config-rule.md +++ b/han-coding/references/config-rule.md @@ -1,7 +1,7 @@ # Config Rule (`.han/config.md`) Han reads two optional configuration files, and either one may be absent. A person may carry a personal -`.han/config.md` inside their Claude Code configuration directory, and a consuming project may carry its own +`.han/config.md` inside their coding-agent configuration directory, and a consuming project may carry its own `.han/config.md`. The personal file supplies defaults that follow the person into every project; the project file adjusts them for that project. Each participating skill finds both through its `## Project Context` block; this rule defines how every skill interprets what that block yields, so one pair of files resolves identically across the whole @@ -12,9 +12,10 @@ suite. Every vendored copy of this file is byte-identical to the canonical `han- The `## Project Context` block carries two probe lines and directs one Read-tool call. This rule refers to each by the label it injects under, or by the file it reads. -- `personal config directory` (probe): the Claude Code configuration directory, resolved for this run. Named by the - `CLAUDE_CONFIG_DIR` environment variable when that variable is set, and `~/.claude` when it is not. This value is not - a setting. It is the folder a relative path in the personal file resolves against. +- `personal config directory` (probe): the coding-agent configuration directory, resolved for this run. Named by the + `AGENT_CONFIG_DIR` environment variable when that variable is set, otherwise by `CLAUDE_CONFIG_DIR` when that variable + is set, and `~/.claude` when neither is set. This value is not a setting. It is the folder a relative path in the + personal file resolves against. - The personal `.han/config.md` (Read tool): the content of `.han/config.md` inside that directory, or nothing. The skill reads this file itself as its first action rather than through a probe. A probe runs at skill load, where it cannot prompt and cannot degrade, so a permission decision against it aborts the skill instead of falling back to @@ -23,15 +24,15 @@ label it injects under, or by the file it reads. - `project .han/config.md` (probe): the content of `.han/config.md` in the directory the skill is running from, or nothing. -The two directories can both exist on one machine and point at different places, so the variable wins whenever it is -set. A personal file sitting in `~/.claude/.han/config.md` does not apply to a person who has pointed -`CLAUDE_CONFIG_DIR` somewhere else. +These directories can all exist on one machine and point at different places, so the first defined variable in the +precedence order wins. A personal file sitting in `~/.claude/.han/config.md` does not apply to a person who has pointed +`AGENT_CONFIG_DIR` or `CLAUDE_CONFIG_DIR` somewhere else. Neither lookup walks up the directory tree. The project file is found only in the directory the skill runs from, the same place the CLAUDE.md and project-discovery probes look. A config elsewhere in the repository does not apply. When neither lookup yields content, no config is present: behave exactly as the skill does without this rule, with no note. -When both lookups resolve to the same file, because the skill is running inside the Claude Code configuration +When both lookups resolve to the same file, because the skill is running inside the active coding-agent configuration directory, read it once and treat it as the project configuration. Nothing is counted twice, and its `## Extra Agents` list is one list. diff --git a/han-coding/skills/architectural-analysis/SKILL.md b/han-coding/skills/architectural-analysis/SKILL.md index 1cf7fc8b..04828686 100644 --- a/han-coding/skills/architectural-analysis/SKILL.md +++ b/han-coding/skills/architectural-analysis/SKILL.md @@ -18,7 +18,7 @@ allowed-tools: Read, Glob, Grep, Agent, Bash(find *) - git installed: !`which git 2>/dev/null || echo "not installed"` - CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f` - project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f` -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-coding/skills/automated-test-planning/SKILL.md b/han-coding/skills/automated-test-planning/SKILL.md index c6c41113..850e72fb 100644 --- a/han-coding/skills/automated-test-planning/SKILL.md +++ b/han-coding/skills/automated-test-planning/SKILL.md @@ -38,7 +38,7 @@ allowed-tools: Bash(git *), Bash(find *), Read, Grep, Glob, Agent - git installed: !`which git 2>/dev/null || echo "not installed"` - CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f` - project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f` -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-coding/skills/code-overview/SKILL.md b/han-coding/skills/code-overview/SKILL.md index 5ab2ecc6..0b1aed44 100644 --- a/han-coding/skills/code-overview/SKILL.md +++ b/han-coding/skills/code-overview/SKILL.md @@ -22,7 +22,7 @@ allowed-tools: Read, Glob, Grep, Agent, Write, Bash(git *), Bash(gh *), Bash(fin - gh installed: !`which gh 2>/dev/null || echo "not installed"` - CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f` - project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f` -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-coding/skills/code-review/SKILL.md b/han-coding/skills/code-review/SKILL.md index 1007f124..d907ae1e 100644 --- a/han-coding/skills/code-review/SKILL.md +++ b/han-coding/skills/code-review/SKILL.md @@ -18,7 +18,7 @@ When running a code review, follow the process outlined here. - git installed: !`which git 2>/dev/null || echo "not installed"` - CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f` - project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f` -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-coding/skills/coding-standard/SKILL.md b/han-coding/skills/coding-standard/SKILL.md index 0e67b4a2..fec0330e 100644 --- a/han-coding/skills/coding-standard/SKILL.md +++ b/han-coding/skills/coding-standard/SKILL.md @@ -16,7 +16,7 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Agent, Bash(mkdir *), Bash(find *) - AGENTS.md: !`find . -maxdepth 1 -name "AGENTS.md" -type f` - project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f` - Rules directory: !`find . -maxdepth 4 -type d -path "*/.claude/rules/coding-standards"` -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-coding/skills/investigate/SKILL.md b/han-coding/skills/investigate/SKILL.md index 187a16c7..5ec9fbc1 100644 --- a/han-coding/skills/investigate/SKILL.md +++ b/han-coding/skills/investigate/SKILL.md @@ -16,7 +16,7 @@ allowed-tools: Read, Glob, Grep, Agent - CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f` - project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f` -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-coding/skills/manual-test-planning/SKILL.md b/han-coding/skills/manual-test-planning/SKILL.md index ecb05a42..6b8b36b4 100644 --- a/han-coding/skills/manual-test-planning/SKILL.md +++ b/han-coding/skills/manual-test-planning/SKILL.md @@ -16,7 +16,7 @@ allowed-tools: Bash(git *), Read, Grep, Glob, Write, Agent ## Project Context -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-coding/skills/refactor/SKILL.md b/han-coding/skills/refactor/SKILL.md index 1eb22ff1..bdd5a2a7 100644 --- a/han-coding/skills/refactor/SKILL.md +++ b/han-coding/skills/refactor/SKILL.md @@ -21,7 +21,7 @@ allowed-tools: - working tree: !`git status --porcelain 2>/dev/null | head -5` - CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f` - project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f` -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-coding/skills/tdd/SKILL.md b/han-coding/skills/tdd/SKILL.md index 634d02a0..7100a2bf 100644 --- a/han-coding/skills/tdd/SKILL.md +++ b/han-coding/skills/tdd/SKILL.md @@ -21,7 +21,7 @@ allowed-tools: - current branch: !`git branch --show-current 2>/dev/null || echo unknown` - CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f` - project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f` -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-communication/references/config-rule.md b/han-communication/references/config-rule.md index 14b19bf2..ae9019d7 100644 --- a/han-communication/references/config-rule.md +++ b/han-communication/references/config-rule.md @@ -1,7 +1,7 @@ # Config Rule (`.han/config.md`) Han reads two optional configuration files, and either one may be absent. A person may carry a personal -`.han/config.md` inside their Claude Code configuration directory, and a consuming project may carry its own +`.han/config.md` inside their coding-agent configuration directory, and a consuming project may carry its own `.han/config.md`. The personal file supplies defaults that follow the person into every project; the project file adjusts them for that project. Each participating skill finds both through its `## Project Context` block; this rule defines how every skill interprets what that block yields, so one pair of files resolves identically across the whole @@ -12,9 +12,10 @@ suite. Every vendored copy of this file is byte-identical to the canonical `han- The `## Project Context` block carries two probe lines and directs one Read-tool call. This rule refers to each by the label it injects under, or by the file it reads. -- `personal config directory` (probe): the Claude Code configuration directory, resolved for this run. Named by the - `CLAUDE_CONFIG_DIR` environment variable when that variable is set, and `~/.claude` when it is not. This value is not - a setting. It is the folder a relative path in the personal file resolves against. +- `personal config directory` (probe): the coding-agent configuration directory, resolved for this run. Named by the + `AGENT_CONFIG_DIR` environment variable when that variable is set, otherwise by `CLAUDE_CONFIG_DIR` when that variable + is set, and `~/.claude` when neither is set. This value is not a setting. It is the folder a relative path in the + personal file resolves against. - The personal `.han/config.md` (Read tool): the content of `.han/config.md` inside that directory, or nothing. The skill reads this file itself as its first action rather than through a probe. A probe runs at skill load, where it cannot prompt and cannot degrade, so a permission decision against it aborts the skill instead of falling back to @@ -23,15 +24,15 @@ label it injects under, or by the file it reads. - `project .han/config.md` (probe): the content of `.han/config.md` in the directory the skill is running from, or nothing. -The two directories can both exist on one machine and point at different places, so the variable wins whenever it is -set. A personal file sitting in `~/.claude/.han/config.md` does not apply to a person who has pointed -`CLAUDE_CONFIG_DIR` somewhere else. +These directories can all exist on one machine and point at different places, so the first defined variable in the +precedence order wins. A personal file sitting in `~/.claude/.han/config.md` does not apply to a person who has pointed +`AGENT_CONFIG_DIR` or `CLAUDE_CONFIG_DIR` somewhere else. Neither lookup walks up the directory tree. The project file is found only in the directory the skill runs from, the same place the CLAUDE.md and project-discovery probes look. A config elsewhere in the repository does not apply. When neither lookup yields content, no config is present: behave exactly as the skill does without this rule, with no note. -When both lookups resolve to the same file, because the skill is running inside the Claude Code configuration +When both lookups resolve to the same file, because the skill is running inside the active coding-agent configuration directory, read it once and treat it as the project configuration. Nothing is counted twice, and its `## Extra Agents` list is one list. diff --git a/han-communication/skills/edit-for-readability/SKILL.md b/han-communication/skills/edit-for-readability/SKILL.md index 158e0fa1..44324fc2 100644 --- a/han-communication/skills/edit-for-readability/SKILL.md +++ b/han-communication/skills/edit-for-readability/SKILL.md @@ -16,7 +16,7 @@ allowed-tools: Read, Write, Glob, Grep, Agent ## Project Context -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-communication/skills/explanation-guidance/SKILL.md b/han-communication/skills/explanation-guidance/SKILL.md index 7dc76d10..5e0771a2 100644 --- a/han-communication/skills/explanation-guidance/SKILL.md +++ b/han-communication/skills/explanation-guidance/SKILL.md @@ -13,7 +13,7 @@ allowed-tools: Read ## Project Context -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-communication/skills/readability-guidance/SKILL.md b/han-communication/skills/readability-guidance/SKILL.md index b0d0101f..d6c92beb 100644 --- a/han-communication/skills/readability-guidance/SKILL.md +++ b/han-communication/skills/readability-guidance/SKILL.md @@ -14,7 +14,7 @@ allowed-tools: Read ## Project Context -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-core/references/config-rule.md b/han-core/references/config-rule.md index 14b19bf2..ae9019d7 100644 --- a/han-core/references/config-rule.md +++ b/han-core/references/config-rule.md @@ -1,7 +1,7 @@ # Config Rule (`.han/config.md`) Han reads two optional configuration files, and either one may be absent. A person may carry a personal -`.han/config.md` inside their Claude Code configuration directory, and a consuming project may carry its own +`.han/config.md` inside their coding-agent configuration directory, and a consuming project may carry its own `.han/config.md`. The personal file supplies defaults that follow the person into every project; the project file adjusts them for that project. Each participating skill finds both through its `## Project Context` block; this rule defines how every skill interprets what that block yields, so one pair of files resolves identically across the whole @@ -12,9 +12,10 @@ suite. Every vendored copy of this file is byte-identical to the canonical `han- The `## Project Context` block carries two probe lines and directs one Read-tool call. This rule refers to each by the label it injects under, or by the file it reads. -- `personal config directory` (probe): the Claude Code configuration directory, resolved for this run. Named by the - `CLAUDE_CONFIG_DIR` environment variable when that variable is set, and `~/.claude` when it is not. This value is not - a setting. It is the folder a relative path in the personal file resolves against. +- `personal config directory` (probe): the coding-agent configuration directory, resolved for this run. Named by the + `AGENT_CONFIG_DIR` environment variable when that variable is set, otherwise by `CLAUDE_CONFIG_DIR` when that variable + is set, and `~/.claude` when neither is set. This value is not a setting. It is the folder a relative path in the + personal file resolves against. - The personal `.han/config.md` (Read tool): the content of `.han/config.md` inside that directory, or nothing. The skill reads this file itself as its first action rather than through a probe. A probe runs at skill load, where it cannot prompt and cannot degrade, so a permission decision against it aborts the skill instead of falling back to @@ -23,15 +24,15 @@ label it injects under, or by the file it reads. - `project .han/config.md` (probe): the content of `.han/config.md` in the directory the skill is running from, or nothing. -The two directories can both exist on one machine and point at different places, so the variable wins whenever it is -set. A personal file sitting in `~/.claude/.han/config.md` does not apply to a person who has pointed -`CLAUDE_CONFIG_DIR` somewhere else. +These directories can all exist on one machine and point at different places, so the first defined variable in the +precedence order wins. A personal file sitting in `~/.claude/.han/config.md` does not apply to a person who has pointed +`AGENT_CONFIG_DIR` or `CLAUDE_CONFIG_DIR` somewhere else. Neither lookup walks up the directory tree. The project file is found only in the directory the skill runs from, the same place the CLAUDE.md and project-discovery probes look. A config elsewhere in the repository does not apply. When neither lookup yields content, no config is present: behave exactly as the skill does without this rule, with no note. -When both lookups resolve to the same file, because the skill is running inside the Claude Code configuration +When both lookups resolve to the same file, because the skill is running inside the active coding-agent configuration directory, read it once and treat it as the project configuration. Nothing is counted twice, and its `## Extra Agents` list is one list. diff --git a/han-core/skills/project-discovery/SKILL.md b/han-core/skills/project-discovery/SKILL.md index d73b6b96..e00fbaba 100644 --- a/han-core/skills/project-discovery/SKILL.md +++ b/han-core/skills/project-discovery/SKILL.md @@ -15,7 +15,7 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Agent, Bash(git symbolic-ref *), B - AGENTS.md: !`find . -maxdepth 1 -name "AGENTS.md" -type f` - CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f` - README: !`find . -maxdepth 1 -name "README*" -type f` -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-documentation/references/config-rule.md b/han-documentation/references/config-rule.md index 14b19bf2..ae9019d7 100644 --- a/han-documentation/references/config-rule.md +++ b/han-documentation/references/config-rule.md @@ -1,7 +1,7 @@ # Config Rule (`.han/config.md`) Han reads two optional configuration files, and either one may be absent. A person may carry a personal -`.han/config.md` inside their Claude Code configuration directory, and a consuming project may carry its own +`.han/config.md` inside their coding-agent configuration directory, and a consuming project may carry its own `.han/config.md`. The personal file supplies defaults that follow the person into every project; the project file adjusts them for that project. Each participating skill finds both through its `## Project Context` block; this rule defines how every skill interprets what that block yields, so one pair of files resolves identically across the whole @@ -12,9 +12,10 @@ suite. Every vendored copy of this file is byte-identical to the canonical `han- The `## Project Context` block carries two probe lines and directs one Read-tool call. This rule refers to each by the label it injects under, or by the file it reads. -- `personal config directory` (probe): the Claude Code configuration directory, resolved for this run. Named by the - `CLAUDE_CONFIG_DIR` environment variable when that variable is set, and `~/.claude` when it is not. This value is not - a setting. It is the folder a relative path in the personal file resolves against. +- `personal config directory` (probe): the coding-agent configuration directory, resolved for this run. Named by the + `AGENT_CONFIG_DIR` environment variable when that variable is set, otherwise by `CLAUDE_CONFIG_DIR` when that variable + is set, and `~/.claude` when neither is set. This value is not a setting. It is the folder a relative path in the + personal file resolves against. - The personal `.han/config.md` (Read tool): the content of `.han/config.md` inside that directory, or nothing. The skill reads this file itself as its first action rather than through a probe. A probe runs at skill load, where it cannot prompt and cannot degrade, so a permission decision against it aborts the skill instead of falling back to @@ -23,15 +24,15 @@ label it injects under, or by the file it reads. - `project .han/config.md` (probe): the content of `.han/config.md` in the directory the skill is running from, or nothing. -The two directories can both exist on one machine and point at different places, so the variable wins whenever it is -set. A personal file sitting in `~/.claude/.han/config.md` does not apply to a person who has pointed -`CLAUDE_CONFIG_DIR` somewhere else. +These directories can all exist on one machine and point at different places, so the first defined variable in the +precedence order wins. A personal file sitting in `~/.claude/.han/config.md` does not apply to a person who has pointed +`AGENT_CONFIG_DIR` or `CLAUDE_CONFIG_DIR` somewhere else. Neither lookup walks up the directory tree. The project file is found only in the directory the skill runs from, the same place the CLAUDE.md and project-discovery probes look. A config elsewhere in the repository does not apply. When neither lookup yields content, no config is present: behave exactly as the skill does without this rule, with no note. -When both lookups resolve to the same file, because the skill is running inside the Claude Code configuration +When both lookups resolve to the same file, because the skill is running inside the active coding-agent configuration directory, read it once and treat it as the project configuration. Nothing is counted twice, and its `## Extra Agents` list is one list. diff --git a/han-documentation/skills/architectural-decision-record/SKILL.md b/han-documentation/skills/architectural-decision-record/SKILL.md index 56eb32d5..75067053 100644 --- a/han-documentation/skills/architectural-decision-record/SKILL.md +++ b/han-documentation/skills/architectural-decision-record/SKILL.md @@ -38,7 +38,7 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Agent, Bash(mkdir *), Bash(find *) - CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f` - project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f` -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-documentation/skills/project-documentation/SKILL.md b/han-documentation/skills/project-documentation/SKILL.md index 303b5b0c..589ee181 100644 --- a/han-documentation/skills/project-documentation/SKILL.md +++ b/han-documentation/skills/project-documentation/SKILL.md @@ -17,7 +17,7 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Agent, Bash(date *), Bash(mkdir *) - CLAUDE.md exists: !`find . -maxdepth 1 -name "CLAUDE.md" -type f` - project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f` -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-documentation/skills/runbook/SKILL.md b/han-documentation/skills/runbook/SKILL.md index 45b59ba0..21091653 100644 --- a/han-documentation/skills/runbook/SKILL.md +++ b/han-documentation/skills/runbook/SKILL.md @@ -47,7 +47,7 @@ allowed-tools: - Today's date: !`date +%Y-%m-%d` - CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f` - project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f` -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-feedback/references/config-rule.md b/han-feedback/references/config-rule.md index 14b19bf2..ae9019d7 100644 --- a/han-feedback/references/config-rule.md +++ b/han-feedback/references/config-rule.md @@ -1,7 +1,7 @@ # Config Rule (`.han/config.md`) Han reads two optional configuration files, and either one may be absent. A person may carry a personal -`.han/config.md` inside their Claude Code configuration directory, and a consuming project may carry its own +`.han/config.md` inside their coding-agent configuration directory, and a consuming project may carry its own `.han/config.md`. The personal file supplies defaults that follow the person into every project; the project file adjusts them for that project. Each participating skill finds both through its `## Project Context` block; this rule defines how every skill interprets what that block yields, so one pair of files resolves identically across the whole @@ -12,9 +12,10 @@ suite. Every vendored copy of this file is byte-identical to the canonical `han- The `## Project Context` block carries two probe lines and directs one Read-tool call. This rule refers to each by the label it injects under, or by the file it reads. -- `personal config directory` (probe): the Claude Code configuration directory, resolved for this run. Named by the - `CLAUDE_CONFIG_DIR` environment variable when that variable is set, and `~/.claude` when it is not. This value is not - a setting. It is the folder a relative path in the personal file resolves against. +- `personal config directory` (probe): the coding-agent configuration directory, resolved for this run. Named by the + `AGENT_CONFIG_DIR` environment variable when that variable is set, otherwise by `CLAUDE_CONFIG_DIR` when that variable + is set, and `~/.claude` when neither is set. This value is not a setting. It is the folder a relative path in the + personal file resolves against. - The personal `.han/config.md` (Read tool): the content of `.han/config.md` inside that directory, or nothing. The skill reads this file itself as its first action rather than through a probe. A probe runs at skill load, where it cannot prompt and cannot degrade, so a permission decision against it aborts the skill instead of falling back to @@ -23,15 +24,15 @@ label it injects under, or by the file it reads. - `project .han/config.md` (probe): the content of `.han/config.md` in the directory the skill is running from, or nothing. -The two directories can both exist on one machine and point at different places, so the variable wins whenever it is -set. A personal file sitting in `~/.claude/.han/config.md` does not apply to a person who has pointed -`CLAUDE_CONFIG_DIR` somewhere else. +These directories can all exist on one machine and point at different places, so the first defined variable in the +precedence order wins. A personal file sitting in `~/.claude/.han/config.md` does not apply to a person who has pointed +`AGENT_CONFIG_DIR` or `CLAUDE_CONFIG_DIR` somewhere else. Neither lookup walks up the directory tree. The project file is found only in the directory the skill runs from, the same place the CLAUDE.md and project-discovery probes look. A config elsewhere in the repository does not apply. When neither lookup yields content, no config is present: behave exactly as the skill does without this rule, with no note. -When both lookups resolve to the same file, because the skill is running inside the Claude Code configuration +When both lookups resolve to the same file, because the skill is running inside the active coding-agent configuration directory, read it once and treat it as the project configuration. Nothing is counted twice, and its `## Extra Agents` list is one list. diff --git a/han-feedback/skills/han-feedback/SKILL.md b/han-feedback/skills/han-feedback/SKILL.md index 718695db..cd5fc99d 100644 --- a/han-feedback/skills/han-feedback/SKILL.md +++ b/han-feedback/skills/han-feedback/SKILL.md @@ -12,7 +12,7 @@ allowed-tools: Read, Write, Bash(ls *), Bash(mkdir *), Bash(gh *), Bash(date *) ## Project Context - Today's date: !`date +%Y-%m-%d` -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-github/references/config-rule.md b/han-github/references/config-rule.md index 14b19bf2..ae9019d7 100644 --- a/han-github/references/config-rule.md +++ b/han-github/references/config-rule.md @@ -1,7 +1,7 @@ # Config Rule (`.han/config.md`) Han reads two optional configuration files, and either one may be absent. A person may carry a personal -`.han/config.md` inside their Claude Code configuration directory, and a consuming project may carry its own +`.han/config.md` inside their coding-agent configuration directory, and a consuming project may carry its own `.han/config.md`. The personal file supplies defaults that follow the person into every project; the project file adjusts them for that project. Each participating skill finds both through its `## Project Context` block; this rule defines how every skill interprets what that block yields, so one pair of files resolves identically across the whole @@ -12,9 +12,10 @@ suite. Every vendored copy of this file is byte-identical to the canonical `han- The `## Project Context` block carries two probe lines and directs one Read-tool call. This rule refers to each by the label it injects under, or by the file it reads. -- `personal config directory` (probe): the Claude Code configuration directory, resolved for this run. Named by the - `CLAUDE_CONFIG_DIR` environment variable when that variable is set, and `~/.claude` when it is not. This value is not - a setting. It is the folder a relative path in the personal file resolves against. +- `personal config directory` (probe): the coding-agent configuration directory, resolved for this run. Named by the + `AGENT_CONFIG_DIR` environment variable when that variable is set, otherwise by `CLAUDE_CONFIG_DIR` when that variable + is set, and `~/.claude` when neither is set. This value is not a setting. It is the folder a relative path in the + personal file resolves against. - The personal `.han/config.md` (Read tool): the content of `.han/config.md` inside that directory, or nothing. The skill reads this file itself as its first action rather than through a probe. A probe runs at skill load, where it cannot prompt and cannot degrade, so a permission decision against it aborts the skill instead of falling back to @@ -23,15 +24,15 @@ label it injects under, or by the file it reads. - `project .han/config.md` (probe): the content of `.han/config.md` in the directory the skill is running from, or nothing. -The two directories can both exist on one machine and point at different places, so the variable wins whenever it is -set. A personal file sitting in `~/.claude/.han/config.md` does not apply to a person who has pointed -`CLAUDE_CONFIG_DIR` somewhere else. +These directories can all exist on one machine and point at different places, so the first defined variable in the +precedence order wins. A personal file sitting in `~/.claude/.han/config.md` does not apply to a person who has pointed +`AGENT_CONFIG_DIR` or `CLAUDE_CONFIG_DIR` somewhere else. Neither lookup walks up the directory tree. The project file is found only in the directory the skill runs from, the same place the CLAUDE.md and project-discovery probes look. A config elsewhere in the repository does not apply. When neither lookup yields content, no config is present: behave exactly as the skill does without this rule, with no note. -When both lookups resolve to the same file, because the skill is running inside the Claude Code configuration +When both lookups resolve to the same file, because the skill is running inside the active coding-agent configuration directory, read it once and treat it as the project configuration. Nothing is counted twice, and its `## Extra Agents` list is one list. diff --git a/han-github/skills/post-code-review-to-pr/SKILL.md b/han-github/skills/post-code-review-to-pr/SKILL.md index 570b3044..cb725c14 100644 --- a/han-github/skills/post-code-review-to-pr/SKILL.md +++ b/han-github/skills/post-code-review-to-pr/SKILL.md @@ -24,7 +24,7 @@ be installed. In either case, immediately stop. - current branch: !`git branch --show-current 2>/dev/null || echo unknown` - default branch: !`git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || echo unknown` - changed files: !`gh pr diff --name-only 2>/dev/null || echo "no pr"` -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-github/skills/update-pr-description/SKILL.md b/han-github/skills/update-pr-description/SKILL.md index 8df4d158..e0f5af07 100644 --- a/han-github/skills/update-pr-description/SKILL.md +++ b/han-github/skills/update-pr-description/SKILL.md @@ -24,7 +24,7 @@ allowed-tools: Read, Glob, Grep, Agent, Bash(git *), Bash(gh *) - branch summary: !`git log origin/HEAD..HEAD --oneline 2>/dev/null || echo unknown` - branch stats: !`git diff origin/HEAD...HEAD --stat 2>/dev/null || echo unknown` - branch changes: !`git diff origin/HEAD...HEAD 2>/dev/null || echo unknown` -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-github/skills/work-items-to-issues/SKILL.md b/han-github/skills/work-items-to-issues/SKILL.md index 5621f446..ddf180c0 100644 --- a/han-github/skills/work-items-to-issues/SKILL.md +++ b/han-github/skills/work-items-to-issues/SKILL.md @@ -13,7 +13,7 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash(gh *), Bash(git *), Bash(find ## Project Context -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-linear/references/config-rule.md b/han-linear/references/config-rule.md index 14b19bf2..ae9019d7 100644 --- a/han-linear/references/config-rule.md +++ b/han-linear/references/config-rule.md @@ -1,7 +1,7 @@ # Config Rule (`.han/config.md`) Han reads two optional configuration files, and either one may be absent. A person may carry a personal -`.han/config.md` inside their Claude Code configuration directory, and a consuming project may carry its own +`.han/config.md` inside their coding-agent configuration directory, and a consuming project may carry its own `.han/config.md`. The personal file supplies defaults that follow the person into every project; the project file adjusts them for that project. Each participating skill finds both through its `## Project Context` block; this rule defines how every skill interprets what that block yields, so one pair of files resolves identically across the whole @@ -12,9 +12,10 @@ suite. Every vendored copy of this file is byte-identical to the canonical `han- The `## Project Context` block carries two probe lines and directs one Read-tool call. This rule refers to each by the label it injects under, or by the file it reads. -- `personal config directory` (probe): the Claude Code configuration directory, resolved for this run. Named by the - `CLAUDE_CONFIG_DIR` environment variable when that variable is set, and `~/.claude` when it is not. This value is not - a setting. It is the folder a relative path in the personal file resolves against. +- `personal config directory` (probe): the coding-agent configuration directory, resolved for this run. Named by the + `AGENT_CONFIG_DIR` environment variable when that variable is set, otherwise by `CLAUDE_CONFIG_DIR` when that variable + is set, and `~/.claude` when neither is set. This value is not a setting. It is the folder a relative path in the + personal file resolves against. - The personal `.han/config.md` (Read tool): the content of `.han/config.md` inside that directory, or nothing. The skill reads this file itself as its first action rather than through a probe. A probe runs at skill load, where it cannot prompt and cannot degrade, so a permission decision against it aborts the skill instead of falling back to @@ -23,15 +24,15 @@ label it injects under, or by the file it reads. - `project .han/config.md` (probe): the content of `.han/config.md` in the directory the skill is running from, or nothing. -The two directories can both exist on one machine and point at different places, so the variable wins whenever it is -set. A personal file sitting in `~/.claude/.han/config.md` does not apply to a person who has pointed -`CLAUDE_CONFIG_DIR` somewhere else. +These directories can all exist on one machine and point at different places, so the first defined variable in the +precedence order wins. A personal file sitting in `~/.claude/.han/config.md` does not apply to a person who has pointed +`AGENT_CONFIG_DIR` or `CLAUDE_CONFIG_DIR` somewhere else. Neither lookup walks up the directory tree. The project file is found only in the directory the skill runs from, the same place the CLAUDE.md and project-discovery probes look. A config elsewhere in the repository does not apply. When neither lookup yields content, no config is present: behave exactly as the skill does without this rule, with no note. -When both lookups resolve to the same file, because the skill is running inside the Claude Code configuration +When both lookups resolve to the same file, because the skill is running inside the active coding-agent configuration directory, read it once and treat it as the project configuration. Nothing is counted twice, and its `## Extra Agents` list is one list. diff --git a/han-linear/skills/work-items-to-linear/SKILL.md b/han-linear/skills/work-items-to-linear/SKILL.md index 099048f7..a4b3ef88 100644 --- a/han-linear/skills/work-items-to-linear/SKILL.md +++ b/han-linear/skills/work-items-to-linear/SKILL.md @@ -21,7 +21,7 @@ allowed-tools: ## Project Context -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-planning/references/config-rule.md b/han-planning/references/config-rule.md index 14b19bf2..ae9019d7 100644 --- a/han-planning/references/config-rule.md +++ b/han-planning/references/config-rule.md @@ -1,7 +1,7 @@ # Config Rule (`.han/config.md`) Han reads two optional configuration files, and either one may be absent. A person may carry a personal -`.han/config.md` inside their Claude Code configuration directory, and a consuming project may carry its own +`.han/config.md` inside their coding-agent configuration directory, and a consuming project may carry its own `.han/config.md`. The personal file supplies defaults that follow the person into every project; the project file adjusts them for that project. Each participating skill finds both through its `## Project Context` block; this rule defines how every skill interprets what that block yields, so one pair of files resolves identically across the whole @@ -12,9 +12,10 @@ suite. Every vendored copy of this file is byte-identical to the canonical `han- The `## Project Context` block carries two probe lines and directs one Read-tool call. This rule refers to each by the label it injects under, or by the file it reads. -- `personal config directory` (probe): the Claude Code configuration directory, resolved for this run. Named by the - `CLAUDE_CONFIG_DIR` environment variable when that variable is set, and `~/.claude` when it is not. This value is not - a setting. It is the folder a relative path in the personal file resolves against. +- `personal config directory` (probe): the coding-agent configuration directory, resolved for this run. Named by the + `AGENT_CONFIG_DIR` environment variable when that variable is set, otherwise by `CLAUDE_CONFIG_DIR` when that variable + is set, and `~/.claude` when neither is set. This value is not a setting. It is the folder a relative path in the + personal file resolves against. - The personal `.han/config.md` (Read tool): the content of `.han/config.md` inside that directory, or nothing. The skill reads this file itself as its first action rather than through a probe. A probe runs at skill load, where it cannot prompt and cannot degrade, so a permission decision against it aborts the skill instead of falling back to @@ -23,15 +24,15 @@ label it injects under, or by the file it reads. - `project .han/config.md` (probe): the content of `.han/config.md` in the directory the skill is running from, or nothing. -The two directories can both exist on one machine and point at different places, so the variable wins whenever it is -set. A personal file sitting in `~/.claude/.han/config.md` does not apply to a person who has pointed -`CLAUDE_CONFIG_DIR` somewhere else. +These directories can all exist on one machine and point at different places, so the first defined variable in the +precedence order wins. A personal file sitting in `~/.claude/.han/config.md` does not apply to a person who has pointed +`AGENT_CONFIG_DIR` or `CLAUDE_CONFIG_DIR` somewhere else. Neither lookup walks up the directory tree. The project file is found only in the directory the skill runs from, the same place the CLAUDE.md and project-discovery probes look. A config elsewhere in the repository does not apply. When neither lookup yields content, no config is present: behave exactly as the skill does without this rule, with no note. -When both lookups resolve to the same file, because the skill is running inside the Claude Code configuration +When both lookups resolve to the same file, because the skill is running inside the active coding-agent configuration directory, read it once and treat it as the project configuration. Nothing is counted twice, and its `## Extra Agents` list is one list. diff --git a/han-planning/skills/iterative-plan-review/SKILL.md b/han-planning/skills/iterative-plan-review/SKILL.md index e5b79602..3f819fc8 100644 --- a/han-planning/skills/iterative-plan-review/SKILL.md +++ b/han-planning/skills/iterative-plan-review/SKILL.md @@ -15,7 +15,7 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Agent, Bash(find *) - CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f` - project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f` -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-planning/skills/plan-a-feature/SKILL.md b/han-planning/skills/plan-a-feature/SKILL.md index 65881a1a..6b5b44a9 100644 --- a/han-planning/skills/plan-a-feature/SKILL.md +++ b/han-planning/skills/plan-a-feature/SKILL.md @@ -16,7 +16,7 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Agent, Bash(find *), Bash(mkdir *) - CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f` - project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f` -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-planning/skills/plan-a-phased-build/SKILL.md b/han-planning/skills/plan-a-phased-build/SKILL.md index 012b1467..6afbc647 100644 --- a/han-planning/skills/plan-a-phased-build/SKILL.md +++ b/han-planning/skills/plan-a-phased-build/SKILL.md @@ -15,7 +15,7 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Agent, Bash(find *), Bash(mkdir *) - CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f` - project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f` -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-planning/skills/plan-implementation/SKILL.md b/han-planning/skills/plan-implementation/SKILL.md index afe4564a..8f44f99c 100644 --- a/han-planning/skills/plan-implementation/SKILL.md +++ b/han-planning/skills/plan-implementation/SKILL.md @@ -14,7 +14,7 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Agent, Bash(find *), Bash(git *), - CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f` - project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f` -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-planning/skills/plan-work-items/SKILL.md b/han-planning/skills/plan-work-items/SKILL.md index 547c4762..b1a375ba 100644 --- a/han-planning/skills/plan-work-items/SKILL.md +++ b/han-planning/skills/plan-work-items/SKILL.md @@ -16,7 +16,7 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Agent, Bash(find *), Bash(mkdir *) - CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f` - project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f` - feature-implementation-plan.md: !`find . -maxdepth 5 -name "feature-implementation-plan.md" -type f` -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-plugin-builder/references/config-rule.md b/han-plugin-builder/references/config-rule.md index 14b19bf2..ae9019d7 100644 --- a/han-plugin-builder/references/config-rule.md +++ b/han-plugin-builder/references/config-rule.md @@ -1,7 +1,7 @@ # Config Rule (`.han/config.md`) Han reads two optional configuration files, and either one may be absent. A person may carry a personal -`.han/config.md` inside their Claude Code configuration directory, and a consuming project may carry its own +`.han/config.md` inside their coding-agent configuration directory, and a consuming project may carry its own `.han/config.md`. The personal file supplies defaults that follow the person into every project; the project file adjusts them for that project. Each participating skill finds both through its `## Project Context` block; this rule defines how every skill interprets what that block yields, so one pair of files resolves identically across the whole @@ -12,9 +12,10 @@ suite. Every vendored copy of this file is byte-identical to the canonical `han- The `## Project Context` block carries two probe lines and directs one Read-tool call. This rule refers to each by the label it injects under, or by the file it reads. -- `personal config directory` (probe): the Claude Code configuration directory, resolved for this run. Named by the - `CLAUDE_CONFIG_DIR` environment variable when that variable is set, and `~/.claude` when it is not. This value is not - a setting. It is the folder a relative path in the personal file resolves against. +- `personal config directory` (probe): the coding-agent configuration directory, resolved for this run. Named by the + `AGENT_CONFIG_DIR` environment variable when that variable is set, otherwise by `CLAUDE_CONFIG_DIR` when that variable + is set, and `~/.claude` when neither is set. This value is not a setting. It is the folder a relative path in the + personal file resolves against. - The personal `.han/config.md` (Read tool): the content of `.han/config.md` inside that directory, or nothing. The skill reads this file itself as its first action rather than through a probe. A probe runs at skill load, where it cannot prompt and cannot degrade, so a permission decision against it aborts the skill instead of falling back to @@ -23,15 +24,15 @@ label it injects under, or by the file it reads. - `project .han/config.md` (probe): the content of `.han/config.md` in the directory the skill is running from, or nothing. -The two directories can both exist on one machine and point at different places, so the variable wins whenever it is -set. A personal file sitting in `~/.claude/.han/config.md` does not apply to a person who has pointed -`CLAUDE_CONFIG_DIR` somewhere else. +These directories can all exist on one machine and point at different places, so the first defined variable in the +precedence order wins. A personal file sitting in `~/.claude/.han/config.md` does not apply to a person who has pointed +`AGENT_CONFIG_DIR` or `CLAUDE_CONFIG_DIR` somewhere else. Neither lookup walks up the directory tree. The project file is found only in the directory the skill runs from, the same place the CLAUDE.md and project-discovery probes look. A config elsewhere in the repository does not apply. When neither lookup yields content, no config is present: behave exactly as the skill does without this rule, with no note. -When both lookups resolve to the same file, because the skill is running inside the Claude Code configuration +When both lookups resolve to the same file, because the skill is running inside the active coding-agent configuration directory, read it once and treat it as the project configuration. Nothing is counted twice, and its `## Extra Agents` list is one list. diff --git a/han-plugin-builder/skills/agent-builder/SKILL.md b/han-plugin-builder/skills/agent-builder/SKILL.md index d8083535..a1b61886 100644 --- a/han-plugin-builder/skills/agent-builder/SKILL.md +++ b/han-plugin-builder/skills/agent-builder/SKILL.md @@ -12,7 +12,7 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash(find *), Bash(mkdir *) ## Project Context -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-plugin-builder/skills/guidance/SKILL.md b/han-plugin-builder/skills/guidance/SKILL.md index d9005621..86c37a55 100644 --- a/han-plugin-builder/skills/guidance/SKILL.md +++ b/han-plugin-builder/skills/guidance/SKILL.md @@ -13,7 +13,7 @@ allowed-tools: Read, Glob, Grep, Bash(find *) ## Project Context -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-plugin-builder/skills/guidance/references/skill-building-guidance/context-injection-commands.md b/han-plugin-builder/skills/guidance/references/skill-building-guidance/context-injection-commands.md index a0793ce6..36a412fd 100644 --- a/han-plugin-builder/skills/guidance/references/skill-building-guidance/context-injection-commands.md +++ b/han-plugin-builder/skills/guidance/references/skill-building-guidance/context-injection-commands.md @@ -139,7 +139,7 @@ configuration directory, and the refusal that followed took whole skills down be ``` Error: Shell command permission check failed for pattern -"!`cat "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/.han/config.md" 2>/dev/null || echo ""`": +"!`cat "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}/.han/config.md" 2>/dev/null || echo ""`": Permission for this action was denied by the Claude Code auto mode classifier. Reason: Blocked by classifier. ``` @@ -149,14 +149,14 @@ Resolving a path in a probe stays fine, because `echo` opens no file. Reading th **Prefer (probe resolves the location, a step reads the file):** ``` -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` ``` **Avoid (probe reads outside the project):** ``` !`cat "$HOME/.someconfig" 2>/dev/null || echo ""` -!`cat "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/.han/config.md" 2>/dev/null || echo ""` +!`cat "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}/.han/config.md" 2>/dev/null || echo ""` ``` ### Rule: Use shell scripts for complex operations diff --git a/han-plugin-builder/skills/guidance/references/skill-building-guidance/troubleshooting.md b/han-plugin-builder/skills/guidance/references/skill-building-guidance/troubleshooting.md index bd133249..e4f15804 100644 --- a/han-plugin-builder/skills/guidance/references/skill-building-guidance/troubleshooting.md +++ b/han-plugin-builder/skills/guidance/references/skill-building-guidance/troubleshooting.md @@ -338,7 +338,7 @@ case: ``` Error: Shell command permission check failed for pattern -"!`cat "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/.han/config.md" 2>/dev/null || echo ""`": +"!`cat "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}/.han/config.md" 2>/dev/null || echo ""`": Permission for this action was denied by the Claude Code auto mode classifier. Reason: Blocked by classifier. ``` @@ -356,13 +356,13 @@ Note the error text differs from the two failure modes below and above: it names **Before (broken — probe reads outside the project):** ```markdown -- personal config: !`cat "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/.han/config.md" 2>/dev/null || echo ""` +- personal config: !`cat "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}/.han/config.md" 2>/dev/null || echo ""` ``` **After (correct — probe resolves the location only):** ```markdown -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. ``` diff --git a/han-plugin-builder/skills/skill-builder/SKILL.md b/han-plugin-builder/skills/skill-builder/SKILL.md index f76f1dea..93c6cc83 100644 --- a/han-plugin-builder/skills/skill-builder/SKILL.md +++ b/han-plugin-builder/skills/skill-builder/SKILL.md @@ -12,7 +12,7 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash(find *), Bash(mkdir *) ## Project Context -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-reporting/references/config-rule.md b/han-reporting/references/config-rule.md index 14b19bf2..ae9019d7 100644 --- a/han-reporting/references/config-rule.md +++ b/han-reporting/references/config-rule.md @@ -1,7 +1,7 @@ # Config Rule (`.han/config.md`) Han reads two optional configuration files, and either one may be absent. A person may carry a personal -`.han/config.md` inside their Claude Code configuration directory, and a consuming project may carry its own +`.han/config.md` inside their coding-agent configuration directory, and a consuming project may carry its own `.han/config.md`. The personal file supplies defaults that follow the person into every project; the project file adjusts them for that project. Each participating skill finds both through its `## Project Context` block; this rule defines how every skill interprets what that block yields, so one pair of files resolves identically across the whole @@ -12,9 +12,10 @@ suite. Every vendored copy of this file is byte-identical to the canonical `han- The `## Project Context` block carries two probe lines and directs one Read-tool call. This rule refers to each by the label it injects under, or by the file it reads. -- `personal config directory` (probe): the Claude Code configuration directory, resolved for this run. Named by the - `CLAUDE_CONFIG_DIR` environment variable when that variable is set, and `~/.claude` when it is not. This value is not - a setting. It is the folder a relative path in the personal file resolves against. +- `personal config directory` (probe): the coding-agent configuration directory, resolved for this run. Named by the + `AGENT_CONFIG_DIR` environment variable when that variable is set, otherwise by `CLAUDE_CONFIG_DIR` when that variable + is set, and `~/.claude` when neither is set. This value is not a setting. It is the folder a relative path in the + personal file resolves against. - The personal `.han/config.md` (Read tool): the content of `.han/config.md` inside that directory, or nothing. The skill reads this file itself as its first action rather than through a probe. A probe runs at skill load, where it cannot prompt and cannot degrade, so a permission decision against it aborts the skill instead of falling back to @@ -23,15 +24,15 @@ label it injects under, or by the file it reads. - `project .han/config.md` (probe): the content of `.han/config.md` in the directory the skill is running from, or nothing. -The two directories can both exist on one machine and point at different places, so the variable wins whenever it is -set. A personal file sitting in `~/.claude/.han/config.md` does not apply to a person who has pointed -`CLAUDE_CONFIG_DIR` somewhere else. +These directories can all exist on one machine and point at different places, so the first defined variable in the +precedence order wins. A personal file sitting in `~/.claude/.han/config.md` does not apply to a person who has pointed +`AGENT_CONFIG_DIR` or `CLAUDE_CONFIG_DIR` somewhere else. Neither lookup walks up the directory tree. The project file is found only in the directory the skill runs from, the same place the CLAUDE.md and project-discovery probes look. A config elsewhere in the repository does not apply. When neither lookup yields content, no config is present: behave exactly as the skill does without this rule, with no note. -When both lookups resolve to the same file, because the skill is running inside the Claude Code configuration +When both lookups resolve to the same file, because the skill is running inside the active coding-agent configuration directory, read it once and treat it as the project configuration. Nothing is counted twice, and its `## Extra Agents` list is one list. diff --git a/han-reporting/skills/html-summary/SKILL.md b/han-reporting/skills/html-summary/SKILL.md index 0151cd50..da165468 100644 --- a/han-reporting/skills/html-summary/SKILL.md +++ b/han-reporting/skills/html-summary/SKILL.md @@ -12,7 +12,7 @@ allowed-tools: Read, Write ## Project Context -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-reporting/skills/stakeholder-summary/SKILL.md b/han-reporting/skills/stakeholder-summary/SKILL.md index b9dca3a1..0875850f 100644 --- a/han-reporting/skills/stakeholder-summary/SKILL.md +++ b/han-reporting/skills/stakeholder-summary/SKILL.md @@ -14,7 +14,7 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Agent, Bash(find *) - CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f` - project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f` -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-research/references/config-rule.md b/han-research/references/config-rule.md index 14b19bf2..ae9019d7 100644 --- a/han-research/references/config-rule.md +++ b/han-research/references/config-rule.md @@ -1,7 +1,7 @@ # Config Rule (`.han/config.md`) Han reads two optional configuration files, and either one may be absent. A person may carry a personal -`.han/config.md` inside their Claude Code configuration directory, and a consuming project may carry its own +`.han/config.md` inside their coding-agent configuration directory, and a consuming project may carry its own `.han/config.md`. The personal file supplies defaults that follow the person into every project; the project file adjusts them for that project. Each participating skill finds both through its `## Project Context` block; this rule defines how every skill interprets what that block yields, so one pair of files resolves identically across the whole @@ -12,9 +12,10 @@ suite. Every vendored copy of this file is byte-identical to the canonical `han- The `## Project Context` block carries two probe lines and directs one Read-tool call. This rule refers to each by the label it injects under, or by the file it reads. -- `personal config directory` (probe): the Claude Code configuration directory, resolved for this run. Named by the - `CLAUDE_CONFIG_DIR` environment variable when that variable is set, and `~/.claude` when it is not. This value is not - a setting. It is the folder a relative path in the personal file resolves against. +- `personal config directory` (probe): the coding-agent configuration directory, resolved for this run. Named by the + `AGENT_CONFIG_DIR` environment variable when that variable is set, otherwise by `CLAUDE_CONFIG_DIR` when that variable + is set, and `~/.claude` when neither is set. This value is not a setting. It is the folder a relative path in the + personal file resolves against. - The personal `.han/config.md` (Read tool): the content of `.han/config.md` inside that directory, or nothing. The skill reads this file itself as its first action rather than through a probe. A probe runs at skill load, where it cannot prompt and cannot degrade, so a permission decision against it aborts the skill instead of falling back to @@ -23,15 +24,15 @@ label it injects under, or by the file it reads. - `project .han/config.md` (probe): the content of `.han/config.md` in the directory the skill is running from, or nothing. -The two directories can both exist on one machine and point at different places, so the variable wins whenever it is -set. A personal file sitting in `~/.claude/.han/config.md` does not apply to a person who has pointed -`CLAUDE_CONFIG_DIR` somewhere else. +These directories can all exist on one machine and point at different places, so the first defined variable in the +precedence order wins. A personal file sitting in `~/.claude/.han/config.md` does not apply to a person who has pointed +`AGENT_CONFIG_DIR` or `CLAUDE_CONFIG_DIR` somewhere else. Neither lookup walks up the directory tree. The project file is found only in the directory the skill runs from, the same place the CLAUDE.md and project-discovery probes look. A config elsewhere in the repository does not apply. When neither lookup yields content, no config is present: behave exactly as the skill does without this rule, with no note. -When both lookups resolve to the same file, because the skill is running inside the Claude Code configuration +When both lookups resolve to the same file, because the skill is running inside the active coding-agent configuration directory, read it once and treat it as the project configuration. Nothing is counted twice, and its `## Extra Agents` list is one list. diff --git a/han-research/skills/gap-analysis/SKILL.md b/han-research/skills/gap-analysis/SKILL.md index 498f3dc7..9ef73612 100644 --- a/han-research/skills/gap-analysis/SKILL.md +++ b/han-research/skills/gap-analysis/SKILL.md @@ -16,7 +16,7 @@ allowed-tools: Read, Write, Glob, Grep, Agent, Bash(find *), Bash(git *) - CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f` - project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f` -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-research/skills/issue-triage/SKILL.md b/han-research/skills/issue-triage/SKILL.md index d4195dec..654d3e13 100644 --- a/han-research/skills/issue-triage/SKILL.md +++ b/han-research/skills/issue-triage/SKILL.md @@ -14,7 +14,7 @@ allowed-tools: Read, Write, Bash(find *), Bash(mkdir *) - CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f` - project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f` -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/han-research/skills/research/SKILL.md b/han-research/skills/research/SKILL.md index 100b1f84..c16fa7a7 100644 --- a/han-research/skills/research/SKILL.md +++ b/han-research/skills/research/SKILL.md @@ -21,7 +21,7 @@ allowed-tools: Read, Glob, Grep, Agent, WebSearch, WebFetch, Bash(find *) - git installed: !`which git 2>/dev/null || echo "not installed"` - CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f` - project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f` -- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- personal config directory: !`echo "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}"` - project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read diff --git a/package.json b/package.json index eb4a2a77..419839fc 100644 --- a/package.json +++ b/package.json @@ -5,7 +5,10 @@ "description": "Dev tooling for the han plugin suite (lint, format, and shell tests).", "scripts": { "lint": "prek run --all-files", - "test": "find . -name node_modules -prune -o -name '*.bats' -print0 | xargs -0 bats" + "test": "find . -name node_modules -prune -o -name '*.bats' -print0 | xargs -0 bats", + "check:pi-compat": "python3 scripts/check-pi-compat.py", + "check:docs-host-wording": "python3 scripts/check-docs-host-wording.py", + "check:compat": "npm run check:pi-compat && npm run check:docs-host-wording" }, "devDependencies": { "@j178/prek": "^0.4.9", diff --git a/scripts/check-docs-host-wording.py b/scripts/check-docs-host-wording.py new file mode 100644 index 00000000..3e2cbf3f --- /dev/null +++ b/scripts/check-docs-host-wording.py @@ -0,0 +1,85 @@ +#!/usr/bin/env python3 +"""Advisory guard against accidental Claude-only phrasing in core Han docs. + +Scope is intentionally narrow and excludes historical artifacts: +- checks only selected user-facing docs +- does not scan docs/plans/** or docs/research/** + +This is not a blanket ban on mentioning Claude Code. It flags phrasing that +presents Claude Code as the only host in generic guidance. + +Advisory mode: findings are reported, but this script exits 0. +""" + +from __future__ import annotations + +from pathlib import Path +import re +import sys + +ROOT = Path(__file__).resolve().parents[1] + +TARGET_FILES = [ + "README.md", + "docs/concepts.md", + "docs/quickstart.md", + "docs/configuration.md", + "docs/skills/README.md", + "docs/agents/README.md", + "docs/workflows.md", + "docs/templates/skill-long-form-template.md", + "docs/why-solo-and-small-teams.md", +] + +# Patterns that usually indicate accidental host lock-in for generic guidance. +BANNED_PATTERNS = [ + re.compile(r"\bRun `/.+` in Claude Code\b"), + re.compile(r"\bin your Claude Code configuration directory\b"), + re.compile(r"\bfrom Claude Code\b"), +] + +# Allowed mentions where Claude-specific wording is intentional. +ALLOW_SUBSTRINGS = [ + "### Claude Code", + "Claude Code Skills reference", + "Claude Code Subagents reference", + "for example Claude Code or Pi", + "Claude Code and Claude Cowork", + "Any MCP-compatible AI client (Claude Code, Cursor, GitHub Copilot,", +] + + +def main() -> int: + violations: list[str] = [] + + for rel in TARGET_FILES: + path = ROOT / rel + if not path.exists(): + continue + + for line_no, line in enumerate(path.read_text().splitlines(), start=1): + if "Claude Code" not in line: + continue + if any(allowed in line for allowed in ALLOW_SUBSTRINGS): + continue + + for pattern in BANNED_PATTERNS: + if pattern.search(line): + violations.append(f"{rel}:{line_no}: {line.strip()}") + break + + if violations: + print("Docs host-wording advisory: found Claude-only phrasing in core docs:\n") + print("\n".join(violations)) + print( + "\nUse host-neutral wording (for example, 'coding-agent host') unless the line is intentionally host-specific." + ) + print("\nContinuing in advisory mode (exit 0).") + return 0 + + print("Docs host-wording check passed.") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/check-pi-compat.py b/scripts/check-pi-compat.py new file mode 100644 index 00000000..46920431 --- /dev/null +++ b/scripts/check-pi-compat.py @@ -0,0 +1,92 @@ +#!/usr/bin/env python3 +"""Lightweight Pi compatibility checks for Han. + +Checks: +1) Pi marketplace includes the required Han plugin subset for Pi support. +2) Every SKILL.md that declares a "personal config directory" probe uses the cross-host fallback: + ${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}} +""" + +from __future__ import annotations + +import json +from pathlib import Path +import sys + +ROOT = Path(__file__).resolve().parents[1] +CLAUDE_MARKETPLACE = ROOT / ".claude-plugin" / "marketplace.json" +PI_MARKETPLACE = ROOT / ".agents" / "plugins" / "marketplace.json" +SKILL_PROBE_FALLBACK = "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}" + + +def check_marketplace_required_subset() -> list[str]: + errors: list[str] = [] + claude = json.loads(CLAUDE_MARKETPLACE.read_text()) + pi = json.loads(PI_MARKETPLACE.read_text()) + + claude_names = {plugin["name"] for plugin in claude["plugins"]} + pi_names = {plugin["name"] for plugin in pi["plugins"]} + + # Keep this explicit and small: the plugins we currently commit to exposing in Pi. + required_for_pi = { + "han", + "han-communication", + "han-core", + "han-documentation", + "han-research", + "han-planning", + "han-coding", + "han-github", + "han-reporting", + "han-feedback", + "han-atlassian", + "han-linear", + "han-plugin-builder", + } + + # Guard against stale required names. + unknown_required = sorted(required_for_pi - claude_names) + if unknown_required: + errors.append("Required Pi plugin set includes names missing from Claude marketplace:") + errors.extend(f" - {name}" for name in unknown_required) + + missing_in_pi = sorted(required_for_pi - pi_names) + if missing_in_pi: + errors.append("Pi marketplace missing required Han plugins:") + errors.extend(f" - {name}" for name in missing_in_pi) + + return errors + + +def check_skill_probe_fallback() -> list[str]: + errors: list[str] = [] + missing: list[str] = [] + + for skill in ROOT.rglob("SKILL.md"): + text = skill.read_text() + if "personal config directory:" in text and SKILL_PROBE_FALLBACK not in text: + missing.append(str(skill.relative_to(ROOT))) + + if missing: + errors.append("Missing HAN/CLAUDE config fallback probe in SKILL.md files:") + errors.extend(f" - {path}" for path in sorted(missing)) + + return errors + + +def main() -> int: + errors: list[str] = [] + errors.extend(check_marketplace_required_subset()) + errors.extend(check_skill_probe_fallback()) + + if errors: + print("Pi compatibility check failed:\n") + print("\n".join(errors)) + return 1 + + print("Pi compatibility check passed.") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) From 22f25327e85471db8da1f7e12ed130edd81e2acc Mon Sep 17 00:00:00 2001 From: Kyle Adams Date: Wed, 5 Aug 2026 22:37:49 -0400 Subject: [PATCH 2/4] chore: mark compatibility scripts executable --- scripts/check-docs-host-wording.py | 0 scripts/check-pi-compat.py | 0 2 files changed, 0 insertions(+), 0 deletions(-) mode change 100644 => 100755 scripts/check-docs-host-wording.py mode change 100644 => 100755 scripts/check-pi-compat.py diff --git a/scripts/check-docs-host-wording.py b/scripts/check-docs-host-wording.py old mode 100644 new mode 100755 diff --git a/scripts/check-pi-compat.py b/scripts/check-pi-compat.py old mode 100644 new mode 100755 From caf904480ea0008f149d922f2b0a0a7c2533487b Mon Sep 17 00:00:00 2001 From: Kyle Adams Date: Wed, 5 Aug 2026 22:43:41 -0400 Subject: [PATCH 3/4] chore: rename docs harness wording check script --- README.md | 6 +++--- docs/concepts.md | 4 ++-- docs/configuration.md | 6 +++--- docs/quickstart.md | 2 +- docs/templates/skill-long-form-template.md | 2 +- docs/why-solo-and-small-teams.md | 2 +- package.json | 4 ++-- ...k-docs-host-wording.py => check-docs-harness-wording.py} | 2 +- 8 files changed, 14 insertions(+), 14 deletions(-) rename scripts/{check-docs-host-wording.py => check-docs-harness-wording.py} (95%) diff --git a/README.md b/README.md index 3a35f323..4514bb76 100644 --- a/README.md +++ b/README.md @@ -4,12 +4,12 @@ Han is a suite of AI skills and agents for solo (or small-team) product engineers. It combines evidence-based planning, test-driven implementation, full documentation maintenance, deep code review, and architectural analysis into a team of -specialists you can dispatch from your coding-agent host, including Claude Code and Pi. +specialists you can dispatch from your agent harness, including Claude Code and Pi. ## What this plugin does Han turns planning, implementation, review, and documentation work that would normally take a team into a set of -deterministic skills you run from your coding-agent host. +deterministic skills you run from your agent harness. Each skill dispatches specialist agents, such as project managers, adversarial reviewers, investigators, architectural analysts, and testing and security specialists, to do the judgment-heavy work. It then folds their findings into an @@ -103,7 +103,7 @@ available Han plugins. ### Environment setup (optional) Han reads personal config from `{harness-config-root}/.han/config.md`. You can set `AGENT_CONFIG_DIR` to pick that -harness config root explicitly, independent of which host you are running under. +harness config root explicitly, independent of which harness you are running under. ```bash # one-off diff --git a/docs/concepts.md b/docs/concepts.md index 5d81d962..4d0c7f39 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -38,7 +38,7 @@ Those three are the whole decision model. Everything else is vocabulary. ## Skills: the process layer -A skill is a fixed sequence of steps that your coding-agent host runs. Typing the slash command is the primary way to trigger it, +A skill is a fixed sequence of steps that your agent harness runs. Typing the slash command is the primary way to trigger it, but not the only one. - You invoke it: `/code-review`, `/plan-a-feature`, `/investigate`. This is the deliberate, primary path. @@ -204,7 +204,7 @@ table, and the fidelity guard. ## Configuration -Han reads two optional `.han/config.md` files on every skill run: a personal one in your coding-agent configuration +Han reads two optional `.han/config.md` files on every skill run: a personal one in your harness configuration directory, and a project one at the project root. Either sets a base directory for the skills' markdown deliverables, a default swarm size for the sizing-aware skills, a writing-voice profile for the readability skills, and extra agents for the dispatching skills to consider. The personal file supplies defaults that follow you into every project, and the diff --git a/docs/configuration.md b/docs/configuration.md index aa453963..e943dbac 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,7 +1,7 @@ # Configuration Han reads two optional configuration files, and you can use either one or both. A personal `.han/config.md` in your -coding-agent configuration directory carries settings that follow you into every project. A project's own +harness configuration directory carries settings that follow you into every project. A project's own `.han/config.md` adjusts those settings for that project. Both control where skills write their markdown deliverables, which extra agents dispatching skills consider, the default swarm size the sizing-aware skills start at, and the writing-voice profile the readability skills apply. Every Han skill reads both files on every run, so the overrides take @@ -31,7 +31,7 @@ effect without depending on the model remembering to look. Someone with neither ## Where each file goes -- **Personal:** `.han/config.md` inside your coding-agent configuration directory. The resolver checks +- **Personal:** `.han/config.md` inside your harness configuration directory. The resolver checks `AGENT_CONFIG_DIR` first, then `CLAUDE_CONFIG_DIR`, then falls back to `~/.claude`. If you have moved your configuration directory, a file left behind in `~/.claude/.han/` does not apply. - **Project:** `.han/config.md` in the directory you run Han skills from. @@ -63,7 +63,7 @@ Every setting is optional, everything unrecognized is ignored, and both files ta # folder and file structure beneath it, and creates the directory on first # write. A relative path is read from the folder holding this file, so the # same line means "inside this project" in a project config and "inside my -# coding-agent configuration directory" in a personal one. Full paths and a +# harness configuration directory" in a personal one. Full paths and a # leading ~ are accepted, including paths outside the project. output-directory: docs/han diff --git a/docs/quickstart.md b/docs/quickstart.md index 7f04c2fe..ecc48193 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -126,7 +126,7 @@ need the real skill, spend it here. architectural decisions. 5. **[`.han/config.md`](./configuration.md)** _(as needed)._ Carry an optional config file to set a base directory for Han's markdown outputs, a default swarm size for the sizing-aware skills, a writing-voice profile, and extra agents - for dispatching skills to consider. Put it in your coding-agent configuration directory for settings that follow you + for dispatching skills to consider. Put it in your harness configuration directory for settings that follow you everywhere, or at the project root for that project alone. **You are done when:** you have a `## Project Discovery` section in your AGENTS.md or CLAUDE.md and the docs and diff --git a/docs/templates/skill-long-form-template.md b/docs/templates/skill-long-form-template.md index 88dd680c..8bbc3b52 100644 --- a/docs/templates/skill-long-form-template.md +++ b/docs/templates/skill-long-form-template.md @@ -34,7 +34,7 @@ to use the skill. For what the skill does internally, read the skill definition ## How to invoke it -Run `/{skill-name}` in your coding-agent host (for example Claude Code or Pi). +Run `/{skill-name}` in your agent harness (for example Claude Code or Pi). Give it: diff --git a/docs/why-solo-and-small-teams.md b/docs/why-solo-and-small-teams.md index 41b54279..b32fbd0c 100644 --- a/docs/why-solo-and-small-teams.md +++ b/docs/why-solo-and-small-teams.md @@ -3,7 +3,7 @@ _Audience: developers and engineering leaders evaluating Han for any team size. Time to read: about two minutes. Outcome: decide whether Han fits your situation, or stop here._ -> **Short answer.** Han is a coding-agent plugin suite that gives a single engineer the specialist coverage of a team. It does +> **Short answer.** Han is an agentic plugin suite that gives a single engineer the specialist coverage of a team. It does > not give a team the shared lift of an enterprise AI platform. If you need centralized governance, shared prompts > across developers, indexed org knowledge, or audited AI usage at org scale, Han is not your tool. Bolting those things > on later will cost more than starting with a product that includes them. If you are a solo engineer or a small team diff --git a/package.json b/package.json index 419839fc..ee3c077c 100644 --- a/package.json +++ b/package.json @@ -7,8 +7,8 @@ "lint": "prek run --all-files", "test": "find . -name node_modules -prune -o -name '*.bats' -print0 | xargs -0 bats", "check:pi-compat": "python3 scripts/check-pi-compat.py", - "check:docs-host-wording": "python3 scripts/check-docs-host-wording.py", - "check:compat": "npm run check:pi-compat && npm run check:docs-host-wording" + "check:docs-harness-wording": "python3 scripts/check-docs-harness-wording.py", + "check:compat": "npm run check:pi-compat && npm run check:docs-harness-wording" }, "devDependencies": { "@j178/prek": "^0.4.9", diff --git a/scripts/check-docs-host-wording.py b/scripts/check-docs-harness-wording.py similarity index 95% rename from scripts/check-docs-host-wording.py rename to scripts/check-docs-harness-wording.py index 3e2cbf3f..f734f28f 100755 --- a/scripts/check-docs-host-wording.py +++ b/scripts/check-docs-harness-wording.py @@ -72,7 +72,7 @@ def main() -> int: print("Docs host-wording advisory: found Claude-only phrasing in core docs:\n") print("\n".join(violations)) print( - "\nUse host-neutral wording (for example, 'coding-agent host') unless the line is intentionally host-specific." + "\nUse harness-neutral wording (for example, 'agent harness') unless the line is intentionally harness-specific." ) print("\nContinuing in advisory mode (exit 0).") return 0 From 771905bc37db9f669bef3ad70534657189105d9e Mon Sep 17 00:00:00 2001 From: Kyle Adams Date: Wed, 5 Aug 2026 22:53:21 -0400 Subject: [PATCH 4/4] chore: remove compatibility check scripts --- package.json | 5 +- scripts/check-docs-harness-wording.py | 85 ------------------------- scripts/check-pi-compat.py | 92 --------------------------- 3 files changed, 1 insertion(+), 181 deletions(-) delete mode 100755 scripts/check-docs-harness-wording.py delete mode 100755 scripts/check-pi-compat.py diff --git a/package.json b/package.json index ee3c077c..eb4a2a77 100644 --- a/package.json +++ b/package.json @@ -5,10 +5,7 @@ "description": "Dev tooling for the han plugin suite (lint, format, and shell tests).", "scripts": { "lint": "prek run --all-files", - "test": "find . -name node_modules -prune -o -name '*.bats' -print0 | xargs -0 bats", - "check:pi-compat": "python3 scripts/check-pi-compat.py", - "check:docs-harness-wording": "python3 scripts/check-docs-harness-wording.py", - "check:compat": "npm run check:pi-compat && npm run check:docs-harness-wording" + "test": "find . -name node_modules -prune -o -name '*.bats' -print0 | xargs -0 bats" }, "devDependencies": { "@j178/prek": "^0.4.9", diff --git a/scripts/check-docs-harness-wording.py b/scripts/check-docs-harness-wording.py deleted file mode 100755 index f734f28f..00000000 --- a/scripts/check-docs-harness-wording.py +++ /dev/null @@ -1,85 +0,0 @@ -#!/usr/bin/env python3 -"""Advisory guard against accidental Claude-only phrasing in core Han docs. - -Scope is intentionally narrow and excludes historical artifacts: -- checks only selected user-facing docs -- does not scan docs/plans/** or docs/research/** - -This is not a blanket ban on mentioning Claude Code. It flags phrasing that -presents Claude Code as the only host in generic guidance. - -Advisory mode: findings are reported, but this script exits 0. -""" - -from __future__ import annotations - -from pathlib import Path -import re -import sys - -ROOT = Path(__file__).resolve().parents[1] - -TARGET_FILES = [ - "README.md", - "docs/concepts.md", - "docs/quickstart.md", - "docs/configuration.md", - "docs/skills/README.md", - "docs/agents/README.md", - "docs/workflows.md", - "docs/templates/skill-long-form-template.md", - "docs/why-solo-and-small-teams.md", -] - -# Patterns that usually indicate accidental host lock-in for generic guidance. -BANNED_PATTERNS = [ - re.compile(r"\bRun `/.+` in Claude Code\b"), - re.compile(r"\bin your Claude Code configuration directory\b"), - re.compile(r"\bfrom Claude Code\b"), -] - -# Allowed mentions where Claude-specific wording is intentional. -ALLOW_SUBSTRINGS = [ - "### Claude Code", - "Claude Code Skills reference", - "Claude Code Subagents reference", - "for example Claude Code or Pi", - "Claude Code and Claude Cowork", - "Any MCP-compatible AI client (Claude Code, Cursor, GitHub Copilot,", -] - - -def main() -> int: - violations: list[str] = [] - - for rel in TARGET_FILES: - path = ROOT / rel - if not path.exists(): - continue - - for line_no, line in enumerate(path.read_text().splitlines(), start=1): - if "Claude Code" not in line: - continue - if any(allowed in line for allowed in ALLOW_SUBSTRINGS): - continue - - for pattern in BANNED_PATTERNS: - if pattern.search(line): - violations.append(f"{rel}:{line_no}: {line.strip()}") - break - - if violations: - print("Docs host-wording advisory: found Claude-only phrasing in core docs:\n") - print("\n".join(violations)) - print( - "\nUse harness-neutral wording (for example, 'agent harness') unless the line is intentionally harness-specific." - ) - print("\nContinuing in advisory mode (exit 0).") - return 0 - - print("Docs host-wording check passed.") - return 0 - - -if __name__ == "__main__": - sys.exit(main()) diff --git a/scripts/check-pi-compat.py b/scripts/check-pi-compat.py deleted file mode 100755 index 46920431..00000000 --- a/scripts/check-pi-compat.py +++ /dev/null @@ -1,92 +0,0 @@ -#!/usr/bin/env python3 -"""Lightweight Pi compatibility checks for Han. - -Checks: -1) Pi marketplace includes the required Han plugin subset for Pi support. -2) Every SKILL.md that declares a "personal config directory" probe uses the cross-host fallback: - ${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}} -""" - -from __future__ import annotations - -import json -from pathlib import Path -import sys - -ROOT = Path(__file__).resolve().parents[1] -CLAUDE_MARKETPLACE = ROOT / ".claude-plugin" / "marketplace.json" -PI_MARKETPLACE = ROOT / ".agents" / "plugins" / "marketplace.json" -SKILL_PROBE_FALLBACK = "${AGENT_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}" - - -def check_marketplace_required_subset() -> list[str]: - errors: list[str] = [] - claude = json.loads(CLAUDE_MARKETPLACE.read_text()) - pi = json.loads(PI_MARKETPLACE.read_text()) - - claude_names = {plugin["name"] for plugin in claude["plugins"]} - pi_names = {plugin["name"] for plugin in pi["plugins"]} - - # Keep this explicit and small: the plugins we currently commit to exposing in Pi. - required_for_pi = { - "han", - "han-communication", - "han-core", - "han-documentation", - "han-research", - "han-planning", - "han-coding", - "han-github", - "han-reporting", - "han-feedback", - "han-atlassian", - "han-linear", - "han-plugin-builder", - } - - # Guard against stale required names. - unknown_required = sorted(required_for_pi - claude_names) - if unknown_required: - errors.append("Required Pi plugin set includes names missing from Claude marketplace:") - errors.extend(f" - {name}" for name in unknown_required) - - missing_in_pi = sorted(required_for_pi - pi_names) - if missing_in_pi: - errors.append("Pi marketplace missing required Han plugins:") - errors.extend(f" - {name}" for name in missing_in_pi) - - return errors - - -def check_skill_probe_fallback() -> list[str]: - errors: list[str] = [] - missing: list[str] = [] - - for skill in ROOT.rglob("SKILL.md"): - text = skill.read_text() - if "personal config directory:" in text and SKILL_PROBE_FALLBACK not in text: - missing.append(str(skill.relative_to(ROOT))) - - if missing: - errors.append("Missing HAN/CLAUDE config fallback probe in SKILL.md files:") - errors.extend(f" - {path}" for path in sorted(missing)) - - return errors - - -def main() -> int: - errors: list[str] = [] - errors.extend(check_marketplace_required_subset()) - errors.extend(check_skill_probe_fallback()) - - if errors: - print("Pi compatibility check failed:\n") - print("\n".join(errors)) - return 1 - - print("Pi compatibility check passed.") - return 0 - - -if __name__ == "__main__": - sys.exit(main())