Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
f01a88a12b | ||
|
|
9a3843b31d | ||
|
|
1528b31d7f |
@@ -28,7 +28,7 @@ hooks:
|
||||
- type: command
|
||||
command: "SH=\"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
|
||||
metadata:
|
||||
version: "3.20.1"
|
||||
version: "3.20.2"
|
||||
---
|
||||
|
||||
# Planning with Files
|
||||
|
||||
@@ -10,7 +10,7 @@
|
||||
"name": "planning-with-files",
|
||||
"source": "./",
|
||||
"description": "Persistent project planning files with lifecycle hooks that inject selected plan context. Automatic recovery uses project files only. Explicit catchup modes may read same-project local session records to emit aggregate counts or bounded nonce-framed excerpts. Optional gated mode can request continuation on capable hosts and never runs commands declared in Markdown. No network upload path. Installs across 60+ agents.",
|
||||
"version": "3.20.1"
|
||||
"version": "3.20.2"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "planning-with-files",
|
||||
"version": "3.20.1",
|
||||
"version": "3.20.2",
|
||||
"description": "Persistent project planning files with lifecycle hooks that inject selected plan context. Automatic recovery uses project files only. Explicit catchup modes may read same-project local session records to emit aggregate counts or bounded nonce-framed excerpts. Optional gated mode can request continuation on capable hosts and never runs commands declared in Markdown. No network upload path. Works across 60+ agents and includes Arabic, German, Spanish, Simplified Chinese, and Traditional Chinese.",
|
||||
"author": {
|
||||
"name": "OthmanAdi",
|
||||
|
||||
@@ -36,7 +36,7 @@ hooks:
|
||||
- type: command
|
||||
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"${CODEBUDDY_PLUGIN_ROOT}/scripts/skill-hook.sh\" \"$HOME/.codebuddy/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
|
||||
metadata:
|
||||
version: "3.20.1"
|
||||
version: "3.20.2"
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "planning-with-files",
|
||||
"version": "3.20.1",
|
||||
"version": "3.20.2",
|
||||
"description": "Persistent project planning for Codex. Opt-in lifecycle hooks inject selected plan context; automatic recovery uses project files only. Explicit catchup modes may read same-project local session records to emit aggregate counts or bounded nonce-framed excerpts. Optional gated mode can request continuation on capable hosts and never runs Markdown-declared commands. No network upload path.",
|
||||
"author": {
|
||||
"name": "OthmanAdi",
|
||||
|
||||
@@ -36,7 +36,7 @@ hooks:
|
||||
- type: command
|
||||
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.codex/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
|
||||
metadata:
|
||||
version: "3.20.1"
|
||||
version: "3.20.2"
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -36,7 +36,7 @@ hooks:
|
||||
- type: command
|
||||
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.cursor/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
|
||||
metadata:
|
||||
version: "3.20.1"
|
||||
version: "3.20.2"
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -36,7 +36,7 @@ hooks:
|
||||
- type: command
|
||||
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.factory/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
|
||||
metadata:
|
||||
version: "3.20.1"
|
||||
version: "3.20.2"
|
||||
---
|
||||
|
||||
# Planning with Files
|
||||
|
||||
@@ -1,12 +1,21 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import importlib
|
||||
import json
|
||||
import os
|
||||
import shlex
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from .hooks import post_tool_call, pre_llm_call, pre_verify
|
||||
from .paths import normalize_cwd, plugin_skill_dir
|
||||
from .hooks import (
|
||||
WORKTREES_DIR_NAME,
|
||||
launch_dir_has_planning_state,
|
||||
launch_dir_notice,
|
||||
post_tool_call,
|
||||
pre_llm_call,
|
||||
pre_verify,
|
||||
)
|
||||
from .paths import effective_project_root, normalize_cwd, plan_root_is_pinned, plugin_skill_dir
|
||||
from .tools import (
|
||||
planning_with_files_check_complete,
|
||||
planning_with_files_init,
|
||||
@@ -14,10 +23,25 @@ from .tools import (
|
||||
)
|
||||
|
||||
SLASH_COMMANDS = ("pwf", "pwf-status", "plan-status")
|
||||
BROKEN_PIN_MESSAGE = (
|
||||
"planning-with-files: PWF_PLAN_ROOT is set but does not resolve to an absolute, "
|
||||
"existing directory; nothing done."
|
||||
)
|
||||
|
||||
|
||||
def _command_cwd() -> Path:
|
||||
"""Project directory for a slash command: the Hermes session cwd, else the process cwd."""
|
||||
def _command_cwd() -> Path | None:
|
||||
"""Project directory for a slash command.
|
||||
|
||||
The PWF_PLAN_ROOT pin wins, exactly as it does for the hooks, and a broken
|
||||
pin returns None instead of a fallback (issue #272: on Hermes 0.21.3 the
|
||||
session cwd can name the home directory, and a pinned operator must not
|
||||
get a plan created or reported there). Without a pin: the Hermes session
|
||||
cwd, else the process cwd. A command handler receives only its arguments,
|
||||
no platform or session, so the CLI-only launch-directory rule of the hooks
|
||||
cannot be applied here; the pin is the documented answer for commands.
|
||||
"""
|
||||
if plan_root_is_pinned():
|
||||
return effective_project_root(normalize_cwd())
|
||||
try:
|
||||
from agent.runtime_cwd import resolve_agent_cwd
|
||||
|
||||
@@ -81,6 +105,8 @@ def pwf_command(raw_args: str = "") -> str:
|
||||
name_parts.append(token)
|
||||
index += 1
|
||||
project_dir = _command_cwd()
|
||||
if project_dir is None:
|
||||
return BROKEN_PIN_MESSAGE
|
||||
result = json.loads(
|
||||
planning_with_files_init(
|
||||
template=template, cwd=str(project_dir), name=" ".join(name_parts), mode=mode
|
||||
@@ -97,14 +123,61 @@ def pwf_command(raw_args: str = "") -> str:
|
||||
if result.get("attestation"):
|
||||
lines.append(f" attested: sha256 {result['attestation'][:12]}...")
|
||||
lines.append(" next: read task_plan.md, findings.md and progress.md, then fill in the goal and phases.")
|
||||
if not plan_root_is_pinned():
|
||||
# Issue #272: the plan just went where Hermes pointed while the launch
|
||||
# directory already holds one; say so instead of leaving two plans apart.
|
||||
hint = _launch_dir_hint(project_dir)
|
||||
if hint:
|
||||
lines.append(hint)
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def status_command(raw_args: str = "") -> str:
|
||||
"""/pwf-status and /plan-status: compact planning state for the current project."""
|
||||
project_dir = _command_cwd()
|
||||
if project_dir is None:
|
||||
return BROKEN_PIN_MESSAGE
|
||||
payload = json.loads(planning_with_files_status(cwd=str(project_dir)))
|
||||
return _format_status(payload)
|
||||
report = _format_status(payload)
|
||||
if not payload.get("exists") and not plan_root_is_pinned():
|
||||
hint = _launch_dir_hint(project_dir)
|
||||
if hint:
|
||||
report = "\n".join((report, hint))
|
||||
return report
|
||||
|
||||
|
||||
def _session_cwd_is_pinned() -> bool:
|
||||
"""True when Hermes pinned this context's cwd per session (``agent.runtime_cwd._SESSION_CWD``).
|
||||
|
||||
A pinned context runs in a multi-session backend whose process cwd is the
|
||||
backend's start directory, not a launch directory, so the hint would
|
||||
compare the wrong things. Prompt turns on the TUI and Desktop carry the
|
||||
pin; their plugin command dispatch does not, so this is a best-effort
|
||||
exemption. Read-only inspection; any failure counts as not pinned.
|
||||
"""
|
||||
try:
|
||||
value = importlib.import_module("agent.runtime_cwd")._SESSION_CWD.get()
|
||||
except Exception: # noqa: BLE001 - a host without the pin keeps the hint
|
||||
return False
|
||||
return isinstance(value, str) and bool(value.strip())
|
||||
|
||||
|
||||
def _launch_dir_hint(project_dir: Path) -> str:
|
||||
"""Issue #272 diagnostic for the slash commands: name the launch directory's plan.
|
||||
|
||||
Read-only and platform-blind (a command handler has no platform), so it is
|
||||
a hint under the report, never a refusal. Worktree sessions and sessions
|
||||
whose cwd Hermes pinned per session are exempt.
|
||||
"""
|
||||
if WORKTREES_DIR_NAME in project_dir.parts or _session_cwd_is_pinned():
|
||||
return ""
|
||||
try:
|
||||
launch = normalize_cwd(os.getcwd())
|
||||
if not launch.is_dir() or launch == project_dir or not launch_dir_has_planning_state(launch):
|
||||
return ""
|
||||
except (OSError, RuntimeError, ValueError):
|
||||
return ""
|
||||
return launch_dir_notice(project_dir, launch)
|
||||
|
||||
|
||||
def _register_commands(ctx: Any) -> None:
|
||||
|
||||
@@ -54,6 +54,66 @@ def _runtime_project_dir(kwargs: dict[str, Any]) -> Path | None:
|
||||
return effective_project_root(project)
|
||||
|
||||
|
||||
WORKTREES_DIR_NAME = ".worktrees" # hermes -w and /worktree new place trees at <repo>/.worktrees/<name>
|
||||
|
||||
|
||||
def launch_dir_has_planning_state(launch: Path) -> bool:
|
||||
"""True when the process launch directory holds a plan, or several plans.
|
||||
|
||||
A plan with a nested-root conflict still counts (``explicit=True`` skips
|
||||
only that check), because the question here is whether the directory the
|
||||
session was started in carries planning state at all.
|
||||
"""
|
||||
return (
|
||||
resolve_plan(launch, explicit=True)[0] is not None
|
||||
or multiple_plans_require_selector(launch)
|
||||
)
|
||||
|
||||
|
||||
def launch_dir_notice(project_dir: Path, launch: Path) -> str:
|
||||
"""The once-per-turn line for issue #272; the resolved root and the launch directory differ."""
|
||||
return (
|
||||
f"[planning-with-files] Hermes resolved {project_dir} as the working directory, "
|
||||
f"but the launch directory {launch} holds a plan. Nothing injected. "
|
||||
f"Pin the thread with PWF_PLAN_ROOT={launch}."
|
||||
)
|
||||
|
||||
|
||||
def _launch_dir_notice(project_dir: Path, kwargs: dict[str, Any]) -> str | None:
|
||||
"""Issue #272: the resolved root holds no plan while the launch directory does.
|
||||
|
||||
Hermes 0.21.3 rewrites the process-global TERMINAL_CWD during the first
|
||||
turn of a CLI session (``agent/relay_runtime.py`` imports ``gateway/run.py``
|
||||
lazily; its import-time bridge applies the ``Path.home()`` fallback), so
|
||||
``resolve_agent_cwd`` names the home directory while ``os.getcwd()`` still
|
||||
names the directory the session was started in (upstream hermes-agent
|
||||
#86411 and #95577). The rewrite runs before the first hook, so the adapter
|
||||
cannot recover the root on its own and never switches to the launch
|
||||
directory: it says why nothing was injected and names the pin.
|
||||
|
||||
Silent by design: platforms other than the CLI (their process cwd is not a
|
||||
launch directory), Hermes worktree sessions (``hermes -w`` points
|
||||
TERMINAL_CWD at ``<repo>/.worktrees/<name>`` without a chdir, which is the
|
||||
intended split), a launch directory without planning state, and a launch
|
||||
directory whose session isolation refuses this session anyway.
|
||||
"""
|
||||
if str(kwargs.get("platform", "")).strip().lower() != "cli":
|
||||
return None
|
||||
if WORKTREES_DIR_NAME in project_dir.parts:
|
||||
return None
|
||||
try:
|
||||
launch = normalize_cwd(os.getcwd())
|
||||
if not launch.is_dir() or launch == project_dir:
|
||||
return None
|
||||
if _session_attachment(launch, _session_id(kwargs)) == ATTACH_DETACHED:
|
||||
return None
|
||||
if not launch_dir_has_planning_state(launch):
|
||||
return None
|
||||
except (OSError, RuntimeError, ValueError):
|
||||
return None
|
||||
return launch_dir_notice(project_dir, launch)
|
||||
|
||||
|
||||
def _session_attachment(project_dir: Path, session_id: str) -> str:
|
||||
"""Opt-in isolation state once a project creates its sessions directory."""
|
||||
sessions_dir = project_dir / ".planning" / "sessions"
|
||||
@@ -174,6 +234,10 @@ def pre_llm_call(**kwargs: Any) -> dict[str, str] | None:
|
||||
return {"context": MULTIPLE_PLANS_NOTICE}
|
||||
if conflicts:
|
||||
return {"context": ambiguity_notice(conflicts)}
|
||||
if not plan_root_is_pinned():
|
||||
notice = _launch_dir_notice(project_dir, kwargs)
|
||||
if notice:
|
||||
return {"context": notice}
|
||||
return None
|
||||
user_message = str(kwargs.get("user_message", ""))
|
||||
reminder_messages = pop_reminders(project_dir, session_id)
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
name: planning-with-files
|
||||
version: 0.2.1
|
||||
version: 0.2.2
|
||||
description: Hermes adapter for persistent project planning and selected context injection. Resolves root and .planning/<slug> plans, injects the attested plan each turn, reminds after writes, and registers /pwf and /pwf-status. Optional gated mode can request continuation only through the Hermes pre_verify hook, bounded by agent.max_verify_nudges; legacy plans stay advisory. Explicit catchup modes read same-project local session records for aggregate counts or bounded replay. No network upload path.
|
||||
author: planning-with-files contributors
|
||||
provides_tools:
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
name: planning-with-files
|
||||
description: "Persistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk; lifecycle hooks inject selected project planning context. Automatic recovery reads project planning files only. Explicit session-catchup.py --metadata reads same-project local agent session records and emits aggregate counts only; --replay may emit bounded nonce-framed excerpts. Optional gated mode can request continuation only when the host supports it and never runs commands declared in Markdown. The skill has no network upload path. Use for research or work needing 5+ tool calls."
|
||||
metadata:
|
||||
version: "3.20.1"
|
||||
version: "3.20.2"
|
||||
hermes:
|
||||
tags: [planning, long-running-tasks, context-engineering, workflow]
|
||||
---
|
||||
|
||||
@@ -36,7 +36,7 @@ hooks:
|
||||
- type: command
|
||||
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.mastracode/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
|
||||
metadata:
|
||||
version: "3.20.1"
|
||||
version: "3.20.2"
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -36,7 +36,7 @@ hooks:
|
||||
- type: command
|
||||
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.config/opencode/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.opencode/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
|
||||
metadata:
|
||||
version: "3.20.1"
|
||||
version: "3.20.2"
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "planning-with-files",
|
||||
"version": "3.20.1",
|
||||
"version": "3.20.2",
|
||||
"description": "Persistent project planning with selected context injection. Automatic recovery uses project files only; explicit catchup modes read same-project local session records for aggregate counts or bounded replay. The host-aware gate never runs Markdown-declared commands. No network upload path. Ships the skill plus a Pi Coding Agent extension.",
|
||||
"keywords": [
|
||||
"pi-package",
|
||||
|
||||
@@ -4,6 +4,17 @@ All notable changes to this project will be documented in this file.
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
## [3.20.2] - 2026-09-19
|
||||
|
||||
### Fixed
|
||||
- Hermes plugin: on Hermes 0.21.3 the host rewrites the process-global `TERMINAL_CWD` to the home directory during the first turn of a CLI session (`agent/relay_runtime.py` imports `gateway/run.py` lazily, and that module's import-time bridge applies the `Path.home()` fallback for an empty or placeholder `terminal.cwd`), so `resolve_agent_cwd()` named the home directory, the hooks found no plan there and injected nothing, with no signal that the plan in the launch directory had been skipped. The rewrite runs before the first plugin hook, so the plugin cannot recover the root on its own and does not guess: when the resolved directory holds no plan and the launch directory of a CLI session does, `pre_llm_call` now injects one line naming both directories and the `PWF_PLAN_ROOT` pin instead of returning nothing, `/pwf-status` prints the same line under `No planning files found.`, `/pwf` appends it when the plan it created went somewhere other than a launch directory that already holds one, and `/pwf` and `/pwf-status` honor `PWF_PLAN_ROOT` like the hooks and report a pin that does not resolve instead of creating or reading a plan in the directory Hermes named. The line stays silent outside the CLI, in `hermes -w` worktree sessions (`TERMINAL_CWD` at `<repo>/.worktrees/<name>` without a chdir is the intended split), for a launch directory without planning state, and for a launch directory whose session isolation refuses the session. Upstream: NousResearch/hermes-agent#86411 and #95577 (#272).
|
||||
|
||||
### Changed
|
||||
- `docs/hermes.md` documents the Hermes 0.21.3 working-directory rewrite, what was reproduced with the 0.21.0 source, the pin for project-scoped CLI sessions, and the shell-hook route as the unaffected alternative.
|
||||
|
||||
### Thanks
|
||||
- @ericshunhinglee-cloud, for the report with the setter stack trace, the on-the-wire token evidence and the upstream cross-references in #272.
|
||||
|
||||
## [3.20.1] - 2026-09-18
|
||||
|
||||
### Fixed
|
||||
|
||||
+2
-2
@@ -7,8 +7,8 @@ authors:
|
||||
- family-names: Adi
|
||||
given-names: Ahmad Othman Ammar
|
||||
alias: OthmanAdi
|
||||
version: "3.20.1"
|
||||
date-released: "2026-09-18"
|
||||
version: "3.20.2"
|
||||
date-released: "2026-09-19"
|
||||
license: MIT
|
||||
url: "https://github.com/OthmanAdi/planning-with-files"
|
||||
repository-code: "https://github.com/OthmanAdi/planning-with-files"
|
||||
|
||||
+5
-2
@@ -106,6 +106,9 @@ These amazing people have contributed code, documentation, or significant improv
|
||||
|
||||
### Other Contributors
|
||||
|
||||
- **[@ericshunhinglee-cloud](https://github.com/ericshunhinglee-cloud)**, [Issue #272](https://github.com/OthmanAdi/planning-with-files/issues/272)
|
||||
- Reported and traced the Hermes 0.21.3 first-turn `TERMINAL_CWD` rewrite that made the Hermes plugin resolve the home directory as the project root, with a setter stack trace, on-the-wire token evidence and the upstream cross-references.
|
||||
|
||||
- **[Shaun Lin](https://github.com/ShaunLinTW)**, [PR #245](https://github.com/OthmanAdi/planning-with-files/pull/245), [PR #247](https://github.com/OthmanAdi/planning-with-files/pull/247), [PR #263](https://github.com/OthmanAdi/planning-with-files/pull/263)
|
||||
- Isolated Python calls in the Codex, Gemini, and GitHub Copilot shell adapters and added regression coverage for project-local import shadowing.
|
||||
- Added named-plan slug mode to the PowerShell initializer with root-mode policy inheritance, host-aware attestation, and Windows PowerShell regression coverage.
|
||||
@@ -446,6 +449,6 @@ If you've contributed and don't see your name here, please open an issue! We wan
|
||||
|
||||
---
|
||||
|
||||
**Total Contributors:** 64+ and growing!
|
||||
**Total Contributors:** 65+ and growing!
|
||||
|
||||
*Last updated: 2026-09-18*
|
||||
*Last updated: 2026-09-19*
|
||||
|
||||
@@ -347,6 +347,7 @@ One hook fire measures 289ms wall-clock since the v3.6.0 optimization, down from
|
||||
|
||||
| Version | Highlights |
|
||||
|---------|------------|
|
||||
| **v3.20.2** | Hermes plugin: Hermes 0.21.3 re-homes `TERMINAL_CWD` to the home directory on the first CLI turn, so the plan in the launch directory was skipped silently. The first turn now says why nothing was injected and names the `PWF_PLAN_ROOT` pin, `/pwf-status` and `/pwf` print the same diagnostic, and the slash commands honor the pin (#272, reported by @ericshunhinglee-cloud). |
|
||||
| **v3.20.1** | Fixes four maintainer-filed issues from the v3.19.0 and v3.20.0 cycles: newline-safe shell slugs (#257, PR #266 by @TayfurYldz), attestation bound to the current project when `PWF_PLAN_ROOT` is inherited (#261, PR #265 by @TayfurYldz), malformed OpenCode part rows skipped by session catchup (#258, PR #263 by @ShaunLinTW), and the several-plans rule in the Hermes plugin (#264, PR #267 by @kuei51307-hub). |
|
||||
| **v3.20.0** | **DeepSeek Harness becomes a first-class host** (closes #252, reported by @loarland): the native Cordis plugin `dsh-planning-with-files` injects the plan on every prompt and after compaction, reminds after writes, holds the turn boundary in gated mode, and registers `/pwf`, `/pwf-status` and the `pwf_*` tools; `dsh plugin --profile web add dsh-planning-with-files`. Cursor's native PowerShell hooks resolve named plans (PR #251 by @kuei51307-hub, item 9 of #250); the PowerShell resolver and attester run on Windows PowerShell 5.1 with a pin and in bracketed project paths; the OpenCode and DSH plugins require `PLAN_ID` for several named plans (the #240 rule); the README is shorter (one 3-file pattern block, a first-class hosts table, one commands collapsible). |
|
||||
| **v3.19.0** | Adds PowerShell named-plan slug mode (#247), anchors session catchup only on exact planning filenames across every shipped copy (#248), and replaces active-plan pointers through the selectors with planning-root containment in both initializers (#249). |
|
||||
|
||||
+16
-2
@@ -1,6 +1,6 @@
|
||||
# Hermes Agent Setup
|
||||
|
||||
planning-with-files treats [Hermes Agent](https://github.com/NousResearch/hermes-agent) by Nous Research as a first-class host: the Hermes CLI, the Hermes TUI and gateway sessions, and the Hermes Desktop app all run the same adapter. Everything on this page was verified against the Hermes v0.19.1 source and a live Hermes install on Windows; the POSIX paths follow Hermes' own defaults.
|
||||
planning-with-files treats [Hermes Agent](https://github.com/NousResearch/hermes-agent) by Nous Research as a first-class host: the Hermes CLI, the Hermes TUI and gateway sessions, and the Hermes Desktop app all run the same adapter. Everything on this page was verified against the Hermes v0.19.1 source and a live Hermes install on Windows; the Hermes 0.21.3 working-directory rewrite described below was reproduced with the 0.21.0 source. The POSIX paths follow Hermes' own defaults.
|
||||
|
||||
The adapter has two parts:
|
||||
|
||||
@@ -76,6 +76,20 @@ Hermes Desktop runs the same backend (`hermes serve`) and therefore the same plu
|
||||
- The hub does not deliver the PowerShell scripts; nothing in the adapter needs them.
|
||||
- Short-name paths (`C:\Users\OASRVA~1\...`) in `HERMES_HOME` make `hermes skills install` fail its subpath check. Use the long form.
|
||||
|
||||
## Hermes 0.21.3: the working directory can move to the home directory on the first turn
|
||||
|
||||
Reported on Hermes 0.21.3 ([#272](https://github.com/OthmanAdi/planning-with-files/issues/272)): during the first turn of a CLI session, `agent/relay_runtime.py` imports `gateway/run.py` lazily, and that module's import-time bridge sets the process-global `TERMINAL_CWD` to the home directory when the variable is empty or a placeholder (`terminal.cwd: "."`). `agent.runtime_cwd.resolve_agent_cwd()`, the documented single source of truth the plugin reads, then names the home directory instead of the one the session was started in, while `os.getcwd()` still names the launch directory. The rewrite runs before the first plugin hook of the session, so no hook ever sees the launch directory. Hermes' own project-context discovery and its terminal tool follow the same rewritten value. Upstream reports: [hermes-agent#86411](https://github.com/NousResearch/hermes-agent/issues/86411) (an explicit `terminal.cwd` re-asserted mid-turn) and [hermes-agent#95577](https://github.com/NousResearch/hermes-agent/issues/95577) (one-shot sessions anchored at the home directory).
|
||||
|
||||
What was reproduced here: the bridge in the Hermes 0.21.0 source, driven with the real `resolve_agent_cwd()` and an empty `TERMINAL_CWD`, the state the report shows at the first turn on 0.21.3. What empties the variable on that install is not established: the upstream `cli.py` at the reported commit still exports `TERMINAL_CWD=os.getcwd()` for the local backend when `cli` is imported, and skips that export only when `_HERMES_GATEWAY=1` is inherited from the environment. With the variable exported, only an explicit `terminal.cwd` in `config.yaml` triggers the rewrite (#86411). The plugin keys off the observed condition, not off a version.
|
||||
|
||||
What the plugin does since v3.20.2:
|
||||
|
||||
- The failure is no longer silent. When the resolved directory holds no plan and the launch directory of a CLI session does, `pre_llm_call` injects one line instead of nothing: `[planning-with-files] Hermes resolved <dir> as the working directory, but the launch directory <project> holds a plan. Nothing injected. Pin the thread with PWF_PLAN_ROOT=<project>.` The plugin never switches to the launch directory on its own: Hermes' terminal and file tools follow the rewritten directory too, so which root the session should use is the operator's call. The line is CLI-only (other surfaces have no launch directory), and it stays silent for `hermes -w` worktree sessions (Hermes points `TERMINAL_CWD` at `<repo>/.worktrees/<name>` without a chdir, by design), for a launch directory without planning state, and for a launch directory whose session isolation refuses this session anyway.
|
||||
- `/pwf-status` prints the same line under `No planning files found.` when the launch directory holds a plan, so the diagnostic command tells you what the hooks see, and `/pwf` appends it when the plan it just created went somewhere other than a launch directory that already holds one. Both stay silent for worktree sessions and for contexts whose working directory Hermes has pinned per session at command time; the TUI and Desktop dispatch plugin commands outside that context, where `/pwf-status` has always reported the backend's directory rather than the session's.
|
||||
- `/pwf` and `/pwf-status` honor `PWF_PLAN_ROOT` exactly like the hooks. A pin that does not resolve is reported instead of creating or reading a plan in whatever directory Hermes named. Without a pin the slash commands follow the Hermes working directory (a command handler receives only its arguments, no platform), so on an affected host an unpinned `/pwf name` creates the plan under the home directory and prints that path; the `planning_with_files_init` tool uses the process working directory instead.
|
||||
|
||||
On an affected host, start project-scoped CLI sessions with the pin until the upstream fix lands: `PWF_PLAN_ROOT=/abs/path/to/project hermes chat` (PowerShell: `$env:PWF_PLAN_ROOT = "C:\path\to\project"`). The pin fails closed when the path does not resolve. The shell-hook route below reads the process working directory and is not affected. The pin restores the plan injection only; the agent's terminal and file tools keep following the rewritten directory (`hermes chat --in <project>` does not change that on an affected build), so ask the model to work with absolute paths. Keep planning files out of your home directory: on an affected host a `~/.planning/` or `~/task_plan.md` would be resolved by every session started anywhere.
|
||||
|
||||
## Usage
|
||||
|
||||
- `/pwf` creates `task_plan.md`, `findings.md` and `progress.md` in the project root. `/pwf Night run` creates an isolated `.planning/YYYY-MM-DD-night-run/` plan and points `.planning/.active_plan` at it. `/pwf --gated Night run` also writes `.mode`, `.nonce`, resets the gate counter and attests the plan, mirroring `init-session.sh --gated`.
|
||||
@@ -125,7 +139,7 @@ Hermes asks for consent on first use (`hermes hooks list` shows the allowlist st
|
||||
python -m pytest tests/test_hermes_adapter.py tests/test_hermes_first_class.py -q
|
||||
```
|
||||
|
||||
`tests/test_hermes_first_class.py` covers slug resolution, the `PWF_PLAN_ROOT` pin, the ambiguity rule, `PLANNING_DISABLED`, slug attestation, the `pre_verify` gate (block, counter, stall, cap), `/pwf` and `/pwf-status`, bundled-skill registration, the Python completion fallback and the shell-hook bridge.
|
||||
`tests/test_hermes_first_class.py` covers slug resolution, the `PWF_PLAN_ROOT` pin, the ambiguity rule, `PLANNING_DISABLED`, slug attestation, the `pre_verify` gate (block, counter, stall, cap), `/pwf` and `/pwf-status`, bundled-skill registration, the Python completion fallback, the shell-hook bridge, and the Hermes 0.21.3 working-directory cases of #272 (the launch-directory notice and where it stays silent, the `/pwf-status` hint, the pinned slash commands).
|
||||
|
||||
## Integration Notes
|
||||
|
||||
|
||||
@@ -36,7 +36,7 @@ hooks:
|
||||
- type: command
|
||||
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files-ar/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
|
||||
metadata:
|
||||
version: "3.20.1"
|
||||
version: "3.20.2"
|
||||
---
|
||||
|
||||
# نظام تخطيط الملفات
|
||||
|
||||
@@ -36,7 +36,7 @@ hooks:
|
||||
- type: command
|
||||
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files-de/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
|
||||
metadata:
|
||||
version: "3.20.1"
|
||||
version: "3.20.2"
|
||||
---
|
||||
|
||||
# Dateiplanungssystem
|
||||
|
||||
@@ -36,7 +36,7 @@ hooks:
|
||||
- type: command
|
||||
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files-es/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
|
||||
metadata:
|
||||
version: "3.20.1"
|
||||
version: "3.20.2"
|
||||
---
|
||||
|
||||
# Sistema de Planificación con Archivos
|
||||
|
||||
@@ -37,7 +37,7 @@ hooks:
|
||||
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files-zh/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
|
||||
metadata:
|
||||
|
||||
version: "3.20.1"
|
||||
version: "3.20.2"
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -37,7 +37,7 @@ hooks:
|
||||
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files-zht/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
|
||||
metadata:
|
||||
|
||||
version: "3.20.1"
|
||||
version: "3.20.2"
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -28,7 +28,7 @@ hooks:
|
||||
- type: command
|
||||
command: "[ -n \"${CLAUDE_PLUGIN_ROOT:-}\" ] && exit 0; SH=\"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
|
||||
metadata:
|
||||
version: "3.20.1"
|
||||
version: "3.20.2"
|
||||
---
|
||||
|
||||
# Planning with Files
|
||||
|
||||
@@ -583,6 +583,154 @@ class HermesFirstClassTests(unittest.TestCase):
|
||||
hooks_module.post_tool_call(tool_name="write_file", session_id="s1", args={"path": "a", "content": "b"})
|
||||
self.assertEqual([], hook_state_module.pop_reminders(root, "s1"))
|
||||
|
||||
# -- issue #272: the host re-homes the process-global cwd ------------------
|
||||
|
||||
def _hermes_reports(self, directory: Path) -> None:
|
||||
"""Point the stubbed resolve_agent_cwd at *directory* (what TERMINAL_CWD would say)."""
|
||||
sys.modules["agent.runtime_cwd"].resolve_agent_cwd = lambda: directory # type: ignore[attr-defined]
|
||||
|
||||
def _first_turn(self, session: str, platform: str = "cli"):
|
||||
return hooks_module.pre_llm_call(user_message="hi", is_first_turn=True, session_id=session, platform=platform)
|
||||
|
||||
def test_rehomed_cli_session_gets_the_pin_notice_instead_of_silence(self) -> None:
|
||||
with self._workspace() as tmp:
|
||||
root = tmp / "project"
|
||||
home = tmp / "home"
|
||||
root.mkdir()
|
||||
home.mkdir()
|
||||
self._slug_plan(root, "2026-09-19-run", pointer=True)
|
||||
os.chdir(root)
|
||||
# Hermes 0.21.3: the first turn already reports the home directory
|
||||
self._hermes_reports(home)
|
||||
payload = self._first_turn("s1")
|
||||
assert payload is not None
|
||||
notice = payload["context"]
|
||||
self.assertTrue(notice.startswith("[planning-with-files] Hermes resolved "), notice)
|
||||
self.assertIn(str(home), notice)
|
||||
self.assertIn(f"launch directory {root} holds a plan", notice)
|
||||
self.assertIn("Nothing injected", notice)
|
||||
self.assertIn(f"PWF_PLAN_ROOT={root}", notice)
|
||||
self.assertNotIn("Build the adapter", notice)
|
||||
# the notice is turn-scoped: the other hooks stay quiet, like the ambiguity notice
|
||||
hooks_module.post_tool_call(tool_name="write_file", session_id="s1", args={"path": "a", "content": "b"})
|
||||
self.assertEqual([], hook_state_module.pop_reminders(root, "s1"))
|
||||
self.assertEqual([], hook_state_module.pop_reminders(home, "s1"))
|
||||
self.assertIsNone(self._pre_verify("s1"))
|
||||
# following the notice restores the plan; the pin also silences the notice
|
||||
os.environ["PWF_PLAN_ROOT"] = str(root)
|
||||
pinned = self._first_turn("s1")
|
||||
assert pinned is not None
|
||||
self.assertIn("Build the adapter", pinned["context"])
|
||||
self.assertNotIn("Hermes resolved", pinned["context"])
|
||||
os.environ.pop("PWF_PLAN_ROOT")
|
||||
# a host that reports the launch directory is unchanged: plan, no notice
|
||||
self._hermes_reports(root)
|
||||
healthy = self._first_turn("s2")
|
||||
assert healthy is not None
|
||||
self.assertIn("Build the adapter", healthy["context"])
|
||||
self.assertNotIn("Hermes resolved", healthy["context"])
|
||||
# two selectable plans at the launch directory still count as "holds a plan"
|
||||
self._hermes_reports(home)
|
||||
self._slug_plan(root, "2026-09-19-other")
|
||||
several = self._first_turn("s3")
|
||||
assert several is not None
|
||||
self.assertIn("holds a plan", several["context"])
|
||||
|
||||
def test_pin_notice_stays_silent_where_it_would_mislead(self) -> None:
|
||||
with self._workspace() as tmp:
|
||||
root = tmp / "project"
|
||||
home = tmp / "home"
|
||||
root.mkdir()
|
||||
home.mkdir()
|
||||
self._slug_plan(root, "2026-09-19-run", pointer=True)
|
||||
os.chdir(root)
|
||||
self._hermes_reports(home)
|
||||
# only the CLI has a launch directory: gateway, TUI and Desktop sessions stay silent
|
||||
for platform in ("telegram", "tui", "desktop", ""):
|
||||
self.assertIsNone(self._first_turn("s9", platform), platform)
|
||||
# PLANNING_DISABLED still silences everything
|
||||
os.environ["PLANNING_DISABLED"] = "1"
|
||||
self.assertIsNone(self._first_turn("s1"))
|
||||
os.environ.pop("PLANNING_DISABLED")
|
||||
# a launch directory without planning state: silent, as before
|
||||
os.chdir(home)
|
||||
self.assertIsNone(self._first_turn("s4"))
|
||||
os.chdir(root)
|
||||
# hermes -w: TERMINAL_CWD names <repo>/.worktrees/<name> without a chdir, by design
|
||||
worktree = root / ".worktrees" / "hermes-abc123"
|
||||
worktree.mkdir(parents=True)
|
||||
self._hermes_reports(worktree)
|
||||
self.assertIsNone(self._first_turn("s5"))
|
||||
# a launch directory whose session isolation refuses this session: the pin would not help
|
||||
self._hermes_reports(home)
|
||||
(root / ".planning" / "sessions").mkdir()
|
||||
self.assertIsNone(self._first_turn("s6"))
|
||||
key = hook_state_module.state_key(root, "s6")
|
||||
(root / ".planning" / "sessions" / f"{key}.attached").write_text("attached\n", encoding="ascii")
|
||||
attached = self._first_turn("s6")
|
||||
assert attached is not None
|
||||
self.assertIn("holds a plan", attached["context"])
|
||||
|
||||
def test_slash_commands_honor_the_plan_root_pin(self) -> None:
|
||||
with self._workspace() as tmp:
|
||||
home = tmp / "home"
|
||||
project = tmp / "project"
|
||||
home.mkdir()
|
||||
project.mkdir()
|
||||
self._slug_plan(project, "2026-09-19-run", mode="autonomous gate", attest=True, pointer=True)
|
||||
os.chdir(home)
|
||||
self._hermes_reports(home)
|
||||
self.assertEqual("No planning files found. Run planning_with_files_init first.", plugin.status_command(""))
|
||||
os.environ["PWF_PLAN_ROOT"] = str(project)
|
||||
self.assertIn("2026-09-19-run", plugin.status_command(""))
|
||||
created = plugin.pwf_command("--gated Second Run")
|
||||
self.assertIn("gated mode", created)
|
||||
self.assertEqual(1, len(list((project / ".planning").glob("*-second-run"))))
|
||||
self.assertFalse((home / ".planning").exists())
|
||||
os.environ["PWF_PLAN_ROOT"] = str(tmp / "missing")
|
||||
self.assertEqual(plugin.BROKEN_PIN_MESSAGE, plugin.status_command(""))
|
||||
self.assertEqual(plugin.BROKEN_PIN_MESSAGE, plugin.pwf_command("--gated Third Run"))
|
||||
self.assertFalse((home / ".planning").exists())
|
||||
self.assertFalse((home / "task_plan.md").exists())
|
||||
|
||||
def test_status_command_names_the_launch_directory_plan(self) -> None:
|
||||
with self._workspace() as tmp:
|
||||
home = tmp / "home"
|
||||
project = tmp / "project"
|
||||
home.mkdir()
|
||||
project.mkdir()
|
||||
self._slug_plan(project, "2026-09-19-run", pointer=True)
|
||||
os.chdir(project)
|
||||
self._hermes_reports(home)
|
||||
report = plugin.status_command("")
|
||||
self.assertTrue(report.startswith("No planning files found."), report)
|
||||
self.assertIn(f"launch directory {project} holds a plan", report)
|
||||
self.assertIn(f"PWF_PLAN_ROOT={project}", report)
|
||||
# the hint is diagnostic only: a plan found where Hermes points needs none
|
||||
self._hermes_reports(project)
|
||||
self.assertNotIn("Hermes resolved", plugin.status_command(""))
|
||||
# worktree sessions are exempt, and the pin replaces the hint
|
||||
worktree = project / ".worktrees" / "hermes-abc123"
|
||||
worktree.mkdir(parents=True)
|
||||
self._hermes_reports(worktree)
|
||||
self.assertEqual("No planning files found. Run planning_with_files_init first.", plugin.status_command(""))
|
||||
self._hermes_reports(home)
|
||||
# a TUI or Desktop context pins its cwd per session: the process cwd is no launch directory
|
||||
runtime = sys.modules["agent.runtime_cwd"]
|
||||
runtime._SESSION_CWD = types.SimpleNamespace(get=lambda: str(home)) # type: ignore[attr-defined]
|
||||
self.assertEqual("No planning files found. Run planning_with_files_init first.", plugin.status_command(""))
|
||||
runtime._SESSION_CWD = types.SimpleNamespace(get=lambda: "") # type: ignore[attr-defined]
|
||||
self.assertIn("holds a plan", plugin.status_command(""))
|
||||
del runtime._SESSION_CWD
|
||||
# /pwf follows the Hermes directory and says where the plan went and what was skipped
|
||||
created = plugin.pwf_command("Second Run")
|
||||
self.assertIn(f"directory: {home / '.planning'}", created)
|
||||
self.assertIn(f"launch directory {project} holds a plan", created)
|
||||
self.assertEqual(1, len(list((home / ".planning").glob("*-second-run"))))
|
||||
os.environ["PWF_PLAN_ROOT"] = str(project)
|
||||
self.assertIn("2026-09-19-run", plugin.status_command(""))
|
||||
self.assertNotIn("Hermes resolved", plugin.pwf_command("Third Run"))
|
||||
|
||||
# -- injection ------------------------------------------------------------
|
||||
|
||||
def test_slug_plan_injection_names_plan_and_reads_slug_attestation(self) -> None:
|
||||
|
||||
Reference in New Issue
Block a user