diff --git a/agent/plan_prompt.py b/agent/plan_prompt.py new file mode 100644 index 0000000000..0678371d50 --- /dev/null +++ b/agent/plan_prompt.py @@ -0,0 +1,103 @@ +#!/usr/bin/env python3 +"""``/plan`` — build the plan-mode prompt that turns the user's request into a +saved markdown implementation plan, with no execution. + +``/plan`` used to be a bundled skill (``skills/software-development/plan``) +whose auto-generated slash command fell off the capped Telegram/Discord command +menus for most installs (skills are the only tier trimmed at the platform +caps, alphabetically — ``plan`` sat past the cutoff). It is now a first-class +built-in: this module builds ONE prompt that instructs the live agent to + + 1. Stay in planning mode for the turn — read-only inspection is allowed, + but no implementation, no mutating commands, no side effects. + 2. Write a concrete, bite-sized, TDD-shaped markdown plan under + ``.hermes/plans/`` in the active workspace via ``write_file``. + +There is no engine and no model-tool footprint: the agent does the work with +its existing toolset, so this works identically on local, Docker, and remote +terminal backends. Every surface (CLI ``/plan``, gateway ``/plan``, TUI +``/plan``) calls :func:`build_plan_prompt` and feeds the result to the agent +as a normal turn — same pattern as ``/learn`` and ``/init``, preserving +prompt-cache invariants (no system-prompt or history mutation). +""" + +from __future__ import annotations + +# The plan-mode ground rules + authoring craft, distilled from the retired +# bundled skill (v2.0.0, writing-craft adapted from obra/superpowers). +# Embedded in the prompt so the agent plans the way a maintainer would. +_PLAN_MODE_RULES = """\ +For this turn, you are in PLAN MODE — planning only. + +- Do not implement code. +- Do not edit project files except the plan markdown file itself. +- Do not run mutating terminal commands, commit, push, or perform external + actions. +- You may inspect the repo or other context with read-only commands/tools + when needed. +- Your deliverable is a markdown plan saved inside the active workspace under + `.hermes/plans/YYYY-MM-DD_HHMMSS-.md` (create the directory if + needed; Hermes file tools are backend-aware, so this relative path keeps + the plan with the workspace on local, docker, ssh, modal, and daytona + backends). If the runtime provides a specific target path, use that exact + path instead. +""" + +_PLAN_CRAFT = """\ +Write the plan for an implementer with zero context for the codebase and +questionable taste. A good plan makes implementation obvious — if someone has +to guess, the plan is incomplete. + +Structure (include the sections that are relevant): +- Goal — one sentence. +- Current context / assumptions. +- Architecture / proposed approach — 2-3 sentences. +- Step-by-step tasks. Each task is bite-sized (2-5 minutes of focused work), + names exact file paths (`src/models/user.py`, not "the model file"), + includes complete copy-pasteable code where code is needed, and exact + commands with expected output for verification. +- Tests / validation — for code tasks, follow the TDD cycle per task: write + the failing test, run it to verify failure, implement minimally, run to + verify pass, commit. +- Risks, tradeoffs, and open questions. + +Principles: DRY, YAGNI, TDD, frequent commits. Avoid vague tasks ("add +authentication"), incomplete code ("add validation here"), and unverifiable +steps ("test it works" — instead: the exact command and its expected output). + +Interaction style: +- If the request is clear enough, write the plan directly. +- If it is genuinely underspecified, ask a brief clarifying question instead + of guessing. +- After saving the plan, reply briefly with what you planned and the saved + path, and offer to execute it (e.g. via subagent-driven development) — + but do not start executing in this turn. +""" + + +def build_plan_prompt(task: str = "") -> str: + """Build the plan-mode prompt for the live agent. + + Args: + task: What to plan. Empty → infer the task from the current + conversation context (mirrors the retired skill's behavior and + issue #36821's "plan from context" expectation). + """ + task = (task or "").strip() + if task: + task_block = f"Task to plan:\n{task}\n" + else: + task_block = ( + "No explicit task was given with /plan — infer the task from the " + "current conversation context (the thing we have been discussing " + "or working toward). If the conversation does not imply a task, " + "ask a brief clarifying question.\n" + ) + return ( + "[/plan — plan mode]\n\n" + + _PLAN_MODE_RULES + + "\n" + + task_block + + "\n" + + _PLAN_CRAFT + ) diff --git a/gateway/run.py b/gateway/run.py index df62736448..24abe13daf 100644 --- a/gateway/run.py +++ b/gateway/run.py @@ -18457,6 +18457,34 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew except Exception: return "Could not start /learn — please try again." + if canonical == "plan": + # /plan: rewrite the turn to the plan-mode prompt and fall + # through to normal agent processing (same fall-through as /learn + # so role alternation is preserved). The live agent inspects the + # workspace with read-only tools and saves the markdown plan + # under .hermes/plans/ via write_file. No engine, works on any + # backend. + from agent.plan_prompt import build_plan_prompt + + _plan_task = event.get_command_args().strip() + _ack = ( + f"Planning: {_plan_task[:80]}{'…' if len(_plan_task) > 80 else ''}" + if _plan_task + else "Planning from this conversation's context…" + ) + try: + adapter = self._adapter_for_source(source) + if adapter: + _ack_meta = self._thread_metadata_for_source(source) + await adapter.send(str(source.chat_id), _ack, metadata=_ack_meta) + except Exception: + logger.debug("plan ack send failed", exc_info=True) + try: + event.text = build_plan_prompt(_plan_task) + # fall through to agent processing + except Exception: + return "Could not start /plan — please try again." + if canonical == "init": # /init: rewrite the turn to a guidance-laden prompt and fall # through to normal agent processing (same fall-through as /learn diff --git a/hermes_cli/cli_commands_mixin.py b/hermes_cli/cli_commands_mixin.py index 833317d17f..52a416fc93 100644 --- a/hermes_cli/cli_commands_mixin.py +++ b/hermes_cli/cli_commands_mixin.py @@ -2201,6 +2201,33 @@ class CLICommandsMixin: else: # pragma: no cover - defensive (no live input loop) print(" /learn needs an active chat session to run.") + def _handle_plan_command(self, cmd: str): + """Handle /plan — write a markdown implementation plan, no execution. + + Mirrors /learn: build the plan-mode prompt and inject it onto the + agent's input queue as a normal user turn. The live agent inspects + the workspace with read-only tools and saves the plan under + ``.hermes/plans/`` via ``write_file``. No engine, no model-tool + footprint, works on any terminal backend, and preserves prompt-cache + invariants (no system prompt or history mutation). + """ + from agent.plan_prompt import build_plan_prompt + + # Everything after the command word is the task to plan (optional — + # empty infers the task from conversation context). + parts = cmd.strip().split(None, 1) + task = parts[1].strip() if len(parts) > 1 else "" + + msg = build_plan_prompt(task) + if task: + print(f"\n📋 Planning: {task[:80]}{'...' if len(task) > 80 else ''}") + else: + print("\n📋 Planning from this conversation's context...") + if hasattr(self, "_pending_input"): + self._pending_input.put(msg) + else: # pragma: no cover - defensive (no live input loop) + print(" /plan needs an active chat session to run.") + def _handle_init_command(self, cmd: str): """Handle /init — generate or update AGENTS.md from a project scan. diff --git a/hermes_cli/tips.py b/hermes_cli/tips.py index 1723365d3b..0a8f89b4df 100644 --- a/hermes_cli/tips.py +++ b/hermes_cli/tips.py @@ -175,7 +175,7 @@ TIPS = [ "Skills can restrict to specific OS platforms — some only load on macOS or Linux.", "skills.external_dirs in config.yaml lets you load skills from custom directories.", "The agent can create its own skills as procedural memory using skill_manage.", - "The plan skill saves markdown plans under .hermes/plans/ in the active workspace.", + "/plan writes a markdown implementation plan to .hermes/plans/ without executing anything.", # --- Cron & Scheduling --- "Cron jobs can attach skills: hermes cron add --skill blogwatcher \"Check for new posts\".", diff --git a/optional-skills/software-development/grill-me/SKILL.md b/optional-skills/software-development/grill-me/SKILL.md index 1b723f9c51..18d9d06ac9 100644 --- a/optional-skills/software-development/grill-me/SKILL.md +++ b/optional-skills/software-development/grill-me/SKILL.md @@ -8,7 +8,7 @@ platforms: [linux, macos, windows] metadata: hermes: tags: [planning, adversarial, interview, decision-tree, pre-implementation, review, alignment] - related_skills: [plan, requesting-code-review, subagent-driven-development, test-driven-development] + related_skills: [requesting-code-review, subagent-driven-development, test-driven-development] --- # Grill Me diff --git a/optional-skills/software-development/subagent-driven-development/SKILL.md b/optional-skills/software-development/subagent-driven-development/SKILL.md index 3a1469f360..57904fd5b4 100644 --- a/optional-skills/software-development/subagent-driven-development/SKILL.md +++ b/optional-skills/software-development/subagent-driven-development/SKILL.md @@ -8,7 +8,7 @@ platforms: [linux, macos, windows] metadata: hermes: tags: [delegation, subagent, implementation, workflow, parallel] - related_skills: [plan, requesting-code-review, test-driven-development] + related_skills: [requesting-code-review, test-driven-development] --- # Subagent-Driven Development diff --git a/skills/research/research-paper-writing/SKILL.md b/skills/research/research-paper-writing/SKILL.md index d230ff6ca2..4e8d89c02e 100644 --- a/skills/research/research-paper-writing/SKILL.md +++ b/skills/research/research-paper-writing/SKILL.md @@ -11,7 +11,7 @@ metadata: hermes: tags: [Research, Paper Writing, Experiments, ML, AI, NeurIPS, ICML, ICLR, ACL, AAAI, COLM, LaTeX, Citations, Statistical Analysis] category: research - related_skills: [arxiv, subagent-driven-development, plan] + related_skills: [arxiv, subagent-driven-development] requires_toolsets: [terminal, files] --- diff --git a/skills/software-development/hermes-agent-skill-authoring/SKILL.md b/skills/software-development/hermes-agent-skill-authoring/SKILL.md index c199a0c589..e979f1b481 100644 --- a/skills/software-development/hermes-agent-skill-authoring/SKILL.md +++ b/skills/software-development/hermes-agent-skill-authoring/SKILL.md @@ -8,7 +8,7 @@ platforms: [linux, macos, windows] metadata: hermes: tags: [skills, authoring, hermes-agent, conventions, skill-md] - related_skills: [plan, requesting-code-review] + related_skills: [requesting-code-review] --- # Authoring Hermes-Agent Skills (in-repo) diff --git a/skills/software-development/plan/SKILL.md b/skills/software-development/plan/SKILL.md deleted file mode 100644 index e97eb6abcd..0000000000 --- a/skills/software-development/plan/SKILL.md +++ /dev/null @@ -1,338 +0,0 @@ ---- -name: plan -description: Write a markdown plan to .hermes/plans/; no execution. -version: 2.0.0 -author: Hermes Agent (writing-craft adapted from obra/superpowers) -license: MIT -platforms: [linux, macos, windows] -metadata: - hermes: - tags: [planning, plan-mode, implementation, workflow, design, documentation] - related_skills: [subagent-driven-development, test-driven-development, requesting-code-review] ---- - -# Plan Mode - -Use this skill when the user wants a plan instead of execution. - -## Core behavior - -For this turn, you are planning only. - -- Do not implement code. -- Do not edit project files except the plan markdown file. -- Do not run mutating terminal commands, commit, push, or perform external actions. -- You may inspect the repo or other context with read-only commands/tools when needed. -- Your deliverable is a markdown plan saved inside the active workspace under `.hermes/plans/`. - -## Output requirements - -Write a markdown plan that is concrete and actionable. - -Include, when relevant: -- Goal -- Current context / assumptions -- Proposed approach -- Step-by-step plan -- Files likely to change -- Tests / validation -- Risks, tradeoffs, and open questions - -If the task is code-related, include exact file paths, likely test targets, and verification steps. - -## Save location - -Save the plan with `write_file` under: -- `.hermes/plans/YYYY-MM-DD_HHMMSS-.md` - -Treat that as relative to the active working directory / backend workspace. Hermes file tools are backend-aware, so using this relative path keeps the plan with the workspace on local, docker, ssh, modal, and daytona backends. - -If the runtime provides a specific target path, use that exact path. -If not, create a sensible timestamped filename yourself under `.hermes/plans/`. - -## Interaction style - -- If the request is clear enough, write the plan directly. -- If no explicit instruction accompanies `/plan`, infer the task from the current conversation context. -- If it is genuinely underspecified, ask a brief clarifying question instead of guessing. -- After saving the plan, reply briefly with what you planned and the saved path. - ---- - -# Writing the Plan Well - -The rest of this skill is the craft of authoring a *good* implementation plan — the content that goes inside the markdown file above. - -## Overview - -Write comprehensive implementation plans assuming the implementer has zero context for the codebase and questionable taste. Document everything they need: which files to touch, complete code, testing commands, docs to check, how to verify. Give them bite-sized tasks. DRY. YAGNI. TDD. Frequent commits. - -Assume the implementer is a skilled developer but knows almost nothing about the toolset or problem domain. Assume they don't know good test design very well. - -**Core principle:** A good plan makes implementation obvious. If someone has to guess, the plan is incomplete. - -## When a Full Implementation Plan Helps - -**Always use before:** -- Implementing multi-step features -- Breaking down complex requirements -- Delegating to subagents via subagent-driven-development - -**Don't skip when:** -- Feature seems simple (assumptions cause bugs) -- You plan to implement it yourself (future you needs guidance) -- Working alone (documentation matters) - -## Bite-Sized Task Granularity - -**Each task = 2-5 minutes of focused work.** - -Every step is one action: -- "Write the failing test" — step -- "Run it to make sure it fails" — step -- "Implement the minimal code to make the test pass" — step -- "Run the tests and make sure they pass" — step -- "Commit" — step - -**Too big:** -```markdown -### Task 1: Build authentication system -[50 lines of code across 5 files] -``` - -**Right size:** -```markdown -### Task 1: Create User model with email field -[10 lines, 1 file] - -### Task 2: Add password hash field to User -[8 lines, 1 file] - -### Task 3: Create password hashing utility -[15 lines, 1 file] -``` - -## Plan Document Structure - -### Header (Required) - -Every plan MUST start with: - -```markdown -# [Feature Name] Implementation Plan - -> **For Hermes:** Use subagent-driven-development skill to implement this plan task-by-task. - -**Goal:** [One sentence describing what this builds] - -**Architecture:** [2-3 sentences about approach] - -**Tech Stack:** [Key technologies/libraries] - ---- -``` - -### Task Structure - -Each task follows this format: - -````markdown -### Task N: [Descriptive Name] - -**Objective:** What this task accomplishes (one sentence) - -**Files:** -- Create: `exact/path/to/new_file.py` -- Modify: `exact/path/to/existing.py:45-67` (line numbers if known) -- Test: `tests/path/to/test_file.py` - -**Step 1: Write failing test** - -```python -def test_specific_behavior(): - result = function(input) - assert result == expected -``` - -**Step 2: Run test to verify failure** - -Run: `pytest tests/path/test.py::test_specific_behavior -v` -Expected: FAIL — "function not defined" - -**Step 3: Write minimal implementation** - -```python -def function(input): - return expected -``` - -**Step 4: Run test to verify pass** - -Run: `pytest tests/path/test.py::test_specific_behavior -v` -Expected: PASS - -**Step 5: Commit** - -```bash -git add tests/path/test.py src/path/file.py -git commit -m "feat: add specific feature" -``` -```` - -## Writing Process - -### Step 1: Understand Requirements - -Read and understand: -- Feature requirements -- Design documents or user description -- Acceptance criteria -- Constraints - -### Step 2: Explore the Codebase - -Use Hermes tools to understand the project: - -```python -# Understand project structure -search_files("*.py", target="files", path="src/") - -# Look at similar features -search_files("similar_pattern", path="src/", file_glob="*.py") - -# Check existing tests -search_files("*.py", target="files", path="tests/") - -# Read key files -read_file("src/app.py") -``` - -### Step 3: Design Approach - -Decide: -- Architecture pattern -- File organization -- Dependencies needed -- Testing strategy - -### Step 4: Write Tasks - -Create tasks in order: -1. Setup/infrastructure -2. Core functionality (TDD for each) -3. Edge cases -4. Integration -5. Cleanup/documentation - -### Step 5: Add Complete Details - -For each task, include: -- **Exact file paths** (not "the config file" but `src/config/settings.py`) -- **Complete code examples** (not "add validation" but the actual code) -- **Exact commands** with expected output -- **Verification steps** that prove the task works - -### Step 6: Review the Plan - -Check: -- [ ] Tasks are sequential and logical -- [ ] Each task is bite-sized (2-5 min) -- [ ] File paths are exact -- [ ] Code examples are complete (copy-pasteable) -- [ ] Commands are exact with expected output -- [ ] No missing context -- [ ] DRY, YAGNI, TDD principles applied - -## Principles - -### DRY (Don't Repeat Yourself) - -**Bad:** Copy-paste validation in 3 places -**Good:** Extract validation function, use everywhere - -### YAGNI (You Aren't Gonna Need It) - -**Bad:** Add "flexibility" for future requirements -**Good:** Implement only what's needed now - -```python -# Bad — YAGNI violation -class User: - def __init__(self, name, email): - self.name = name - self.email = email - self.preferences = {} # Not needed yet! - self.metadata = {} # Not needed yet! - -# Good — YAGNI -class User: - def __init__(self, name, email): - self.name = name - self.email = email -``` - -### TDD (Test-Driven Development) - -Every task that produces code should include the full TDD cycle: -1. Write failing test -2. Run to verify failure -3. Write minimal code -4. Run to verify pass - -See `test-driven-development` skill for details. - -### Frequent Commits - -Commit after every task: -```bash -git add [files] -git commit -m "type: description" -``` - -## Common Mistakes - -### Vague Tasks - -**Bad:** "Add authentication" -**Good:** "Create User model with email and password_hash fields" - -### Incomplete Code - -**Bad:** "Step 1: Add validation function" -**Good:** "Step 1: Add validation function" followed by the complete function code - -### Missing Verification - -**Bad:** "Step 3: Test it works" -**Good:** "Step 3: Run `pytest tests/test_auth.py -v`, expected: 3 passed" - -### Missing File Paths - -**Bad:** "Create the model file" -**Good:** "Create: `src/models/user.py`" - -## Execution Handoff - -After saving the plan, offer the execution approach: - -**"Plan complete and saved. Ready to execute using subagent-driven-development — I'll dispatch a fresh subagent per task with two-stage review (spec compliance then code quality). Shall I proceed?"** - -When executing, use the `subagent-driven-development` skill: -- Fresh `delegate_task` per task with full context -- Spec compliance review after each task -- Code quality review after spec passes -- Proceed only when both reviews approve - -## Remember - -``` -Bite-sized tasks (2-5 min each) -Exact file paths -Complete code (copy-pasteable) -Exact commands with expected output -Verification steps -DRY, YAGNI, TDD -Frequent commits -``` - -**A good plan makes implementation obvious.** diff --git a/skills/software-development/requesting-code-review/SKILL.md b/skills/software-development/requesting-code-review/SKILL.md index ad861e9ff0..0a543cee2b 100644 --- a/skills/software-development/requesting-code-review/SKILL.md +++ b/skills/software-development/requesting-code-review/SKILL.md @@ -8,7 +8,7 @@ platforms: [linux, macos, windows] metadata: hermes: tags: [code-review, security, verification, quality, pre-commit, auto-fix] - related_skills: [subagent-driven-development, plan, test-driven-development, github-code-review] + related_skills: [subagent-driven-development, test-driven-development, github-code-review] --- # Pre-Commit Code Verification diff --git a/skills/software-development/simplify-code/SKILL.md b/skills/software-development/simplify-code/SKILL.md index b1ca84fdc4..0dcfae3084 100644 --- a/skills/software-development/simplify-code/SKILL.md +++ b/skills/software-development/simplify-code/SKILL.md @@ -8,7 +8,7 @@ platforms: [linux, macos, windows] metadata: hermes: tags: [code-review, cleanup, refactor, delegation, subagent, parallel, simplify] - related_skills: [requesting-code-review, test-driven-development, plan] + related_skills: [requesting-code-review, test-driven-development] --- # Simplify Code — Parallel Review & Cleanup diff --git a/skills/software-development/spike/SKILL.md b/skills/software-development/spike/SKILL.md index 94ca054dd2..cd2d97fb14 100644 --- a/skills/software-development/spike/SKILL.md +++ b/skills/software-development/spike/SKILL.md @@ -8,7 +8,7 @@ platforms: [linux, macos, windows] metadata: hermes: tags: [spike, prototype, experiment, feasibility, throwaway, exploration, research, planning, mvp, proof-of-concept] - related_skills: [sketch, subagent-driven-development, plan] + related_skills: [sketch, subagent-driven-development] --- # Spike diff --git a/skills/software-development/systematic-debugging/SKILL.md b/skills/software-development/systematic-debugging/SKILL.md index 7ff990e278..275746e7bb 100644 --- a/skills/software-development/systematic-debugging/SKILL.md +++ b/skills/software-development/systematic-debugging/SKILL.md @@ -8,7 +8,7 @@ platforms: [linux, macos, windows] metadata: hermes: tags: [debugging, troubleshooting, problem-solving, root-cause, investigation] - related_skills: [test-driven-development, plan, subagent-driven-development] + related_skills: [test-driven-development, subagent-driven-development] --- # Systematic Debugging diff --git a/skills/software-development/test-driven-development/SKILL.md b/skills/software-development/test-driven-development/SKILL.md index 67fd061ea7..0979f7222a 100644 --- a/skills/software-development/test-driven-development/SKILL.md +++ b/skills/software-development/test-driven-development/SKILL.md @@ -8,7 +8,7 @@ platforms: [linux, macos, windows] metadata: hermes: tags: [testing, tdd, development, quality, red-green-refactor] - related_skills: [systematic-debugging, plan, subagent-driven-development] + related_skills: [systematic-debugging, subagent-driven-development] --- # Test-Driven Development (TDD) diff --git a/tests/agent/test_curator.py b/tests/agent/test_curator.py index a7defb7338..4b8a46c9bb 100644 --- a/tests/agent/test_curator.py +++ b/tests/agent/test_curator.py @@ -331,13 +331,17 @@ def _disable_prune_builtins(curator_env, monkeypatch): def test_protected_builtin_never_archived_even_when_stale(curator_env, monkeypatch): - """A protected built-in (e.g. `plan`) is never archived, even when it is a - stale bundled skill under prune_builtins — it backs a load-bearing slash - command and must survive every curator pass.""" + """A protected built-in is never archived, even when it is a stale + bundled skill under prune_builtins — it backs a load-bearing UX path and + must survive every curator pass. + + The shipped set is currently empty (``plan`` graduated to a built-in + command), so the mechanism is exercised with a sentinel name.""" u = curator_env["usage"] c = curator_env["curator"] skills_dir = curator_env["home"] / "skills" - name = next(iter(u.PROTECTED_BUILTIN_SKILLS)) # the real protected name(s) + name = "sentinel-protected-skill" + monkeypatch.setattr(u, "PROTECTED_BUILTIN_SKILLS", {name}) _write_skill(skills_dir, name) (skills_dir / ".bundled_manifest").write_text(f"{name}:abc\n", encoding="utf-8") _enable_prune_builtins(curator_env, monkeypatch) diff --git a/tests/agent/test_plan_prompt.py b/tests/agent/test_plan_prompt.py new file mode 100644 index 0000000000..63cf357ce9 --- /dev/null +++ b/tests/agent/test_plan_prompt.py @@ -0,0 +1,84 @@ +"""Tests for the built-in /plan command (formerly the bundled `plan` skill). + +Covers the shared prompt builder (agent.plan_prompt.build_plan_prompt) and the +registry wiring that makes /plan a first-class command on every surface — +CLI, gateway messengers, and TUI. The skill-to-builtin move exists precisely +so /plan survives the Telegram/Discord command-menu caps that trimmed it as +an alphabetical skill entry. +""" + +from agent.plan_prompt import build_plan_prompt + + +class TestBuildPlanPrompt: + def test_task_is_included_verbatim(self): + task = "migrate the auth provider to OIDC with zero downtime" + prompt = build_plan_prompt(task) + assert task in prompt + + def test_empty_task_infers_from_conversation(self): + prompt = build_plan_prompt("") + assert "infer the task from the current conversation context" in prompt + # Whitespace-only behaves the same. + assert "infer the task" in build_plan_prompt(" ") + + def test_plan_mode_ground_rules_always_present(self): + for arg in ("", "build a REST API"): + prompt = build_plan_prompt(arg) + assert "PLAN MODE" in prompt + assert "Do not implement code" in prompt + assert "Do not run mutating terminal commands" in prompt + assert "read-only" in prompt + + def test_save_location_contract(self): + prompt = build_plan_prompt("anything") + assert ".hermes/plans/" in prompt + assert "YYYY-MM-DD_HHMMSS-.md" in prompt + + def test_authoring_craft_travels_with_every_prompt(self): + prompt = build_plan_prompt("x") + assert "bite-sized" in prompt + assert "exact file paths" in prompt.lower() + assert "TDD" in prompt + assert "YAGNI" in prompt + + def test_no_execution_handoff_in_same_turn(self): + prompt = build_plan_prompt("x") + assert "do not start executing in this turn" in prompt + + +class TestPlanRegistryWiring: + def test_plan_is_registered_and_resolves(self): + from hermes_cli.commands import resolve_command + + cmd = resolve_command("plan") + assert cmd is not None + assert cmd.name == "plan" + + def test_plan_is_not_cli_only(self): + # /plan must reach messaging gateways — the whole point of the + # builtin conversion is menu visibility on Telegram/Discord. + from hermes_cli.commands import resolve_command + + assert not resolve_command("plan").cli_only + + def test_plan_reaches_gateway_dispatch(self): + from hermes_cli.commands import GATEWAY_KNOWN_COMMANDS + + assert "plan" in GATEWAY_KNOWN_COMMANDS + + def test_plan_in_telegram_bot_commands(self): + from hermes_cli.commands import telegram_bot_commands + + names = {n for n, _ in telegram_bot_commands()} + assert "plan" in names + + def test_no_bundled_plan_skill_remains(self): + # The bundled skill was removed with the builtin conversion; a + # leftover copy would collide with the core command at scan time + # (scan_skill_commands skips core-colliding skill slugs with a + # warning, so the skill would be silently unreachable). + from pathlib import Path + + repo_root = Path(__file__).resolve().parents[2] + assert not (repo_root / "skills" / "software-development" / "plan").exists() diff --git a/tests/hermes_cli/test_curator_pin_visibility.py b/tests/hermes_cli/test_curator_pin_visibility.py index 7e62740adf..a00b17102c 100644 --- a/tests/hermes_cli/test_curator_pin_visibility.py +++ b/tests/hermes_cli/test_curator_pin_visibility.py @@ -82,18 +82,22 @@ def pin_env(tmp_path, monkeypatch): # --------------------------------------------------------------------------- -def test_pin_fails_loudly_when_write_does_not_land(pin_env, capsys): +def test_pin_fails_loudly_when_write_does_not_land(pin_env, capsys, monkeypatch): """A skill that passes `is_agent_created()` but fails `is_curation_eligible()` must produce a NONZERO exit and an explanatory error — not a success message over a silent no-write. Real trigger: PROTECTED_BUILTIN_SKILLS blocks by NAME. A user's own skill - literally named ``plan`` is not in the bundled manifest, so - ``is_agent_created()`` says True — but ``is_protected_builtin()`` makes it - ineligible, and ``set_pinned()`` silently no-ops through - ``_mutate(require_curation_eligible=True)``.""" + whose name collides with a protected entry is not in the bundled + manifest, so ``is_agent_created()`` says True — but + ``is_protected_builtin()`` makes it ineligible, and ``set_pinned()`` + silently no-ops through ``_mutate(require_curation_eligible=True)``. + + The shipped set is currently empty (``plan`` graduated to a built-in + command), so the collision is staged with a monkeypatched sentinel.""" env = pin_env - name = "plan" # collides with the protected built-in name + name = "sentinel-protected-skill" # collides with the (patched) protected name + monkeypatch.setattr(env["usage"], "PROTECTED_BUILTIN_SKILLS", {name}) _make_skill(env["skills"], name) diff --git a/tests/tools/test_skill_usage.py b/tests/tools/test_skill_usage.py index 05a4bcef8a..87f22703de 100644 --- a/tests/tools/test_skill_usage.py +++ b/tests/tools/test_skill_usage.py @@ -539,7 +539,10 @@ def test_adopt_refuses_skills_the_user_does_not_own(skills_home, monkeypatch, ki json.dumps({"installed": {name: {}}}), encoding="utf-8", ) elif kind == "protected": - name = sorted(skill_usage.PROTECTED_BUILTIN_SKILLS)[0] + # Shipped set is currently empty (plan graduated to a built-in + # command) — stage a sentinel to exercise the mechanism. + name = "sentinel-protected-skill" + monkeypatch.setattr(skill_usage, "PROTECTED_BUILTIN_SKILLS", {name}) _write_skill(skills_dir, name) else: name = "no-such-skill" diff --git a/tools/skill_usage.py b/tools/skill_usage.py index 5fd6425cc7..2bd076388e 100644 --- a/tools/skill_usage.py +++ b/tools/skill_usage.py @@ -57,15 +57,14 @@ _VALID_STATES = {STATE_ACTIVE, STATE_STALE, STATE_ARCHIVED} # Load-bearing bundled built-ins the curator must NEVER archive or consolidate, # regardless of ``curator.prune_builtins``, pin state, or LLM judgment. These -# back advertised UX paths (e.g. ``plan`` powers the ``/plan`` slash-command -# flow and is referenced in tips/docs/fresh-profile seeding); silently archiving -# one turns its slash command into "Unknown command" with no signal to the user. +# back advertised UX paths; silently archiving one turns its slash command +# into "Unknown command" with no signal to the user. # Protection is by skill ``name`` (frontmatter ``name:``), matching the keys used # throughout this module. Keep this list tiny and intentional — it is not a # substitute for ``curator.prune_builtins: false``, which exempts ALL built-ins. -PROTECTED_BUILTIN_SKILLS: Set[str] = { - "plan", -} +# (``plan`` used to live here; it is now a first-class built-in command with +# no skill on disk, so the set is currently empty.) +PROTECTED_BUILTIN_SKILLS: Set[str] = set() def is_protected_builtin(skill_name: str) -> bool: diff --git a/tui_gateway/methods_tools.py b/tui_gateway/methods_tools.py index 80d94deee4..d31adb5242 100644 --- a/tui_gateway/methods_tools.py +++ b/tui_gateway/methods_tools.py @@ -622,6 +622,14 @@ def _(rid, params: dict) -> dict: from agent.learn_prompt import build_learn_prompt return _ok(rid, {"type": "send", "message": build_learn_prompt(arg)}) + if name == "plan": + # Plan mode: build the plan-mode prompt and submit it as a normal + # agent turn (same pattern as /learn). The live agent inspects the + # workspace read-only and saves the markdown plan under + # .hermes/plans/ via write_file. Works on any backend. + from agent.plan_prompt import build_plan_prompt + + return _ok(rid, {"type": "send", "message": build_plan_prompt(arg)}) if name == "init": # Generate-or-update AGENTS.md: build the guidance-laden prompt and # submit it as a normal agent turn (same pattern as /learn). The live diff --git a/website/docs/reference/skills-catalog.md b/website/docs/reference/skills-catalog.md index 419788352d..a5bf58c88b 100644 --- a/website/docs/reference/skills-catalog.md +++ b/website/docs/reference/skills-catalog.md @@ -149,7 +149,6 @@ If a skill is missing from this list but present in the repo, the catalog is reg | [`hermes-agent-skill-authoring`](/docs/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring) | Author in-repo SKILL.md files: frontmatter and structure. | `software-development/hermes-agent-skill-authoring` | | [`inspecting-hermes-desktop-dom`](/docs/user-guide/skills/bundled/software-development/software-development-inspecting-hermes-desktop-dom) | Read the live Hermes desktop DOM/CSS over CDP. | `software-development/inspecting-hermes-desktop-dom` | | [`node-inspect-debugger`](/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger) | Debug Node.js via --inspect + Chrome DevTools Protocol CLI. | `software-development/node-inspect-debugger` | -| [`plan`](/docs/user-guide/skills/bundled/software-development/software-development-plan) | Write a markdown plan to .hermes/plans/; no execution. | `software-development/plan` | | [`python-debugpy`](/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy) | Debug Python: pdb REPL + debugpy remote (DAP). | `software-development/python-debugpy` | | [`requesting-code-review`](/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review) | Pre-commit review: security scan, quality gates, auto-fix. | `software-development/requesting-code-review` | | [`simplify-code`](/docs/user-guide/skills/bundled/software-development/software-development-simplify-code) | Parallel 4-agent cleanup of recent code changes. | `software-development/simplify-code` | diff --git a/website/docs/reference/slash-commands.md b/website/docs/reference/slash-commands.md index 608eb80b15..1dcc916782 100644 --- a/website/docs/reference/slash-commands.md +++ b/website/docs/reference/slash-commands.md @@ -11,7 +11,7 @@ Hermes has two slash-command surfaces, both driven by a central `COMMAND_REGISTR - **Interactive CLI slash commands** — dispatched by `cli.py`, with autocomplete from the registry - **Messaging slash commands** — dispatched by `gateway/run.py`, with help text and platform menus generated from the registry -Installed skills are also exposed as dynamic slash commands on both surfaces. That includes bundled skills like `/plan`, which opens plan mode and saves markdown plans under `.hermes/plans/` relative to the active workspace/backend working directory. +Installed skills are also exposed as dynamic slash commands on both surfaces. (`/plan` used to be one of these; it is now a built-in command — see the Session table below.) ## Permissions and admin/user split @@ -108,6 +108,7 @@ Type `/` in the CLI to open the autocomplete menu. Built-in commands are case-in | `/memory [pending\|approve\|reject\|approval]` | Review pending memory writes staged by the write-approval gate (`memory.write_approval`) and toggle the gate. See [Controlling memory writes](/user-guide/features/memory#controlling-memory-writes-write_approval). | | `/bundles` | List configured skill bundles — `/` slash aliases that preload several skills at once. Configure under `bundles:` in `~/.hermes/config.yaml`. See [Skill Bundles](/user-guide/features/skills#skill-bundles). | | `/learn ` | Distill a reusable skill from anything you describe — a directory, a URL, the workflow you just walked the agent through, or pasted notes. Open-ended: the agent gathers the sources with its own tools and authors a `SKILL.md` following the house authoring standards. Works in the CLI, the messaging gateway, the TUI, and the dashboard Skills page. | +| `/plan [task]` | Write a markdown implementation plan to `.hermes/plans/` in the active workspace — planning only, no execution. Empty argument infers the task from the conversation. (Formerly the bundled `plan` skill; now built-in so it survives the Telegram/Discord command-menu caps.) | | `/init [notes]` | Generate or update `AGENTS.md` project instructions from a repo scan (port of Codex `/init`). The agent inspects manifests, layout, and toolchain configs with its read-only tools, then writes a concise `AGENTS.md` — or, if one exists, merge-updates it preserving your content. Optional notes steer the emphasis. Works in the CLI, the messaging gateway, and the TUI. | | `/cron` | Manage scheduled tasks (list, add/create, edit, pause, resume, run, remove) | | `/suggestions [accept\|dismiss N\|catalog\|clear]` (alias: `/suggest`) | Review suggested automations. Use `/suggestions` to list pending suggestions, `/suggestions accept ` to create the proposed automation, `/suggestions dismiss ` to reject one, `/suggestions catalog` to add curated starter automations, and `/suggestions clear` to clear resolved suggestion records. Accepted jobs preserve the current surface as the delivery origin. | @@ -268,6 +269,7 @@ The messaging gateway supports the following built-in commands inside Telegram, | `/egress [status]` | Show Docker egress proxy status. | | `/init [notes]` | Generate or update `AGENTS.md` from a repo scan. | | `/learn ` | Distill a reusable skill from anything you describe. | +| `/plan [task]` | Write a markdown implementation plan to `.hermes/plans/`; no execution. | | `/bundles` | List configured skill bundles (`/` aliases that preload several skills). | | `/reload-skills` (alias: `/reload_skills`) | Re-scan `~/.hermes/skills/` for newly installed or removed skills. | | `/footer [on\|off\|status]` | Toggle the runtime-metadata footer on final replies (shows model, context %, and cwd). | diff --git a/website/docs/user-guide/features/curator.md b/website/docs/user-guide/features/curator.md index e6d8617f16..66dd545cc7 100644 --- a/website/docs/user-guide/features/curator.md +++ b/website/docs/user-guide/features/curator.md @@ -315,7 +315,7 @@ Skills named in any cron job's `skills:` list are protected the same way for **a Only **agent-created** skills can be pinned — `hermes curator pin` refuses on bundled and hub-installed skills with an explanatory message if you try. Hub-installed skills are never subject to curator mutation. Bundled built-in skills are only touched when `curator.prune_builtins: true` (the default), and even then only archived after `archive_after_days` of non-use — never patched, consolidated, or deleted. Set `curator.prune_builtins: false` to exempt bundled skills entirely. -A small set of **protected built-ins** is hardcoded as never-archivable and never-consolidatable, regardless of `curator.prune_builtins`, pin state, or LLM judgment. These back load-bearing UX — for example, `plan` powers the `/plan` slash-command flow — so silently archiving one would turn its slash command into an "Unknown command" error with no signal to you. Protected built-ins are filtered out of the curator's candidate list entirely, so the consolidation pass never sees them. +A small set of **protected built-ins** can be hardcoded as never-archivable and never-consolidatable, regardless of `curator.prune_builtins`, pin state, or LLM judgment. These back load-bearing UX, so silently archiving one would turn its slash command into an "Unknown command" error with no signal to you. (The set is currently empty — `plan`, its original member, graduated to a built-in `/plan` command with no skill on disk.) Protected built-ins are filtered out of the curator's candidate list entirely, so the consolidation pass never sees them. If you want a stronger guarantee than "no deletion" — for instance, freezing a skill's content entirely while the agent still reads it — edit `~/.hermes/skills//SKILL.md` directly with your editor. The pin guards tool-driven deletion, not your own filesystem access. diff --git a/website/docs/user-guide/features/skills.md b/website/docs/user-guide/features/skills.md index ec71205d0c..105c7da7a2 100644 --- a/website/docs/user-guide/features/skills.md +++ b/website/docs/user-guide/features/skills.md @@ -56,7 +56,7 @@ Every installed skill is automatically available as a slash command: /gif-search funny cats /axolotl help me fine-tune Llama 3 on my dataset /github-pr-workflow create a PR for the auth refactor -/plan design a rollout for migrating our auth provider +/songsee analyze the frequency spread of this mix # Just the skill name loads it and lets the agent ask what you need: /excalidraw @@ -82,7 +82,7 @@ that happen to start with `/` (like file paths) are never swallowed: For combinations you use repeatedly, prefer a [skill bundle](#skill-bundles) — same effect under one short command. -The bundled `plan` skill is a good example. Running `/plan [request]` loads the skill's instructions, telling Hermes to inspect context if needed, write a markdown implementation plan instead of executing the task, and save the result under `.hermes/plans/` relative to the active workspace/backend working directory. +(Plan mode works the same way but is a built-in command now: `/plan [request]` tells Hermes to inspect context if needed, write a markdown implementation plan instead of executing the task, and save the result under `.hermes/plans/` relative to the active workspace/backend working directory.) You can also interact with skills through natural conversation: diff --git a/website/docs/user-guide/skills/bundled/research/research-research-paper-writing.md b/website/docs/user-guide/skills/bundled/research/research-research-paper-writing.md index d7677cac8e..3514a6d73f 100644 --- a/website/docs/user-guide/skills/bundled/research/research-research-paper-writing.md +++ b/website/docs/user-guide/skills/bundled/research/research-research-paper-writing.md @@ -22,7 +22,7 @@ Write ML papers for NeurIPS/ICML/ICLR: design→submit. | Dependencies | `semanticscholar`, `arxiv`, `habanero`, `requests`, `scipy`, `numpy`, `matplotlib`, `SciencePlots` | | Platforms | linux, macos | | Tags | `Research`, `Paper Writing`, `Experiments`, `ML`, `AI`, `NeurIPS`, `ICML`, `ICLR`, `ACL`, `AAAI`, `COLM`, `LaTeX`, `Citations`, `Statistical Analysis` | -| Related skills | [`arxiv`](/docs/user-guide/skills/bundled/research/research-arxiv), [`subagent-driven-development`](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development), [`plan`](/docs/user-guide/skills/bundled/software-development/software-development-plan) | +| Related skills | [`arxiv`](/docs/user-guide/skills/bundled/research/research-arxiv), [`subagent-driven-development`](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development), `plan` (now the built-in `/plan` command) | ## Reference: full SKILL.md diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring.md b/website/docs/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring.md index 8953ec3d86..8a3eceb19d 100644 --- a/website/docs/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring.md +++ b/website/docs/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring.md @@ -21,7 +21,7 @@ Author in-repo SKILL.md files: frontmatter and structure. | License | MIT | | Platforms | linux, macos, windows | | Tags | `skills`, `authoring`, `hermes-agent`, `conventions`, `skill-md` | -| Related skills | [`plan`](/docs/user-guide/skills/bundled/software-development/software-development-plan), [`requesting-code-review`](/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review) | +| Related skills | `plan` (now the built-in `/plan` command), [`requesting-code-review`](/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review) | ## Reference: full SKILL.md diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-plan.md b/website/docs/user-guide/skills/bundled/software-development/software-development-plan.md deleted file mode 100644 index 2368cfc6d2..0000000000 --- a/website/docs/user-guide/skills/bundled/software-development/software-development-plan.md +++ /dev/null @@ -1,356 +0,0 @@ ---- -title: "Plan — Write a markdown plan to .hermes/plans/; no execution" -sidebar_label: "Plan" -description: "Write a markdown plan to .hermes/plans/; no execution" ---- - -{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} - -# Plan - -Write a markdown plan to .hermes/plans/; no execution. - -## Skill metadata - -| | | -|---|---| -| Source | Bundled (installed by default) | -| Path | `skills/software-development/plan` | -| Version | `2.0.0` | -| Author | Hermes Agent (writing-craft adapted from obra/superpowers) | -| License | MIT | -| Platforms | linux, macos, windows | -| Tags | `planning`, `plan-mode`, `implementation`, `workflow`, `design`, `documentation` | -| Related skills | [`subagent-driven-development`](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development), [`test-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development), [`requesting-code-review`](/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review) | - -## Reference: full SKILL.md - -:::info -The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active. -::: - -# Plan Mode - -Use this skill when the user wants a plan instead of execution. - -## Core behavior - -For this turn, you are planning only. - -- Do not implement code. -- Do not edit project files except the plan markdown file. -- Do not run mutating terminal commands, commit, push, or perform external actions. -- You may inspect the repo or other context with read-only commands/tools when needed. -- Your deliverable is a markdown plan saved inside the active workspace under `.hermes/plans/`. - -## Output requirements - -Write a markdown plan that is concrete and actionable. - -Include, when relevant: -- Goal -- Current context / assumptions -- Proposed approach -- Step-by-step plan -- Files likely to change -- Tests / validation -- Risks, tradeoffs, and open questions - -If the task is code-related, include exact file paths, likely test targets, and verification steps. - -## Save location - -Save the plan with `write_file` under: -- `.hermes/plans/YYYY-MM-DD_HHMMSS-.md` - -Treat that as relative to the active working directory / backend workspace. Hermes file tools are backend-aware, so using this relative path keeps the plan with the workspace on local, docker, ssh, modal, and daytona backends. - -If the runtime provides a specific target path, use that exact path. -If not, create a sensible timestamped filename yourself under `.hermes/plans/`. - -## Interaction style - -- If the request is clear enough, write the plan directly. -- If no explicit instruction accompanies `/plan`, infer the task from the current conversation context. -- If it is genuinely underspecified, ask a brief clarifying question instead of guessing. -- After saving the plan, reply briefly with what you planned and the saved path. - ---- - -# Writing the Plan Well - -The rest of this skill is the craft of authoring a *good* implementation plan — the content that goes inside the markdown file above. - -## Overview - -Write comprehensive implementation plans assuming the implementer has zero context for the codebase and questionable taste. Document everything they need: which files to touch, complete code, testing commands, docs to check, how to verify. Give them bite-sized tasks. DRY. YAGNI. TDD. Frequent commits. - -Assume the implementer is a skilled developer but knows almost nothing about the toolset or problem domain. Assume they don't know good test design very well. - -**Core principle:** A good plan makes implementation obvious. If someone has to guess, the plan is incomplete. - -## When a Full Implementation Plan Helps - -**Always use before:** -- Implementing multi-step features -- Breaking down complex requirements -- Delegating to subagents via subagent-driven-development - -**Don't skip when:** -- Feature seems simple (assumptions cause bugs) -- You plan to implement it yourself (future you needs guidance) -- Working alone (documentation matters) - -## Bite-Sized Task Granularity - -**Each task = 2-5 minutes of focused work.** - -Every step is one action: -- "Write the failing test" — step -- "Run it to make sure it fails" — step -- "Implement the minimal code to make the test pass" — step -- "Run the tests and make sure they pass" — step -- "Commit" — step - -**Too big:** -```markdown -### Task 1: Build authentication system -[50 lines of code across 5 files] -``` - -**Right size:** -```markdown -### Task 1: Create User model with email field -[10 lines, 1 file] - -### Task 2: Add password hash field to User -[8 lines, 1 file] - -### Task 3: Create password hashing utility -[15 lines, 1 file] -``` - -## Plan Document Structure - -### Header (Required) - -Every plan MUST start with: - -```markdown -# [Feature Name] Implementation Plan - -> **For Hermes:** Use subagent-driven-development skill to implement this plan task-by-task. - -**Goal:** [One sentence describing what this builds] - -**Architecture:** [2-3 sentences about approach] - -**Tech Stack:** [Key technologies/libraries] - ---- -``` - -### Task Structure - -Each task follows this format: - -````markdown -### Task N: [Descriptive Name] - -**Objective:** What this task accomplishes (one sentence) - -**Files:** -- Create: `exact/path/to/new_file.py` -- Modify: `exact/path/to/existing.py:45-67` (line numbers if known) -- Test: `tests/path/to/test_file.py` - -**Step 1: Write failing test** - -```python -def test_specific_behavior(): - result = function(input) - assert result == expected -``` - -**Step 2: Run test to verify failure** - -Run: `pytest tests/path/test.py::test_specific_behavior -v` -Expected: FAIL — "function not defined" - -**Step 3: Write minimal implementation** - -```python -def function(input): - return expected -``` - -**Step 4: Run test to verify pass** - -Run: `pytest tests/path/test.py::test_specific_behavior -v` -Expected: PASS - -**Step 5: Commit** - -```bash -git add tests/path/test.py src/path/file.py -git commit -m "feat: add specific feature" -``` -```` - -## Writing Process - -### Step 1: Understand Requirements - -Read and understand: -- Feature requirements -- Design documents or user description -- Acceptance criteria -- Constraints - -### Step 2: Explore the Codebase - -Use Hermes tools to understand the project: - -```python -# Understand project structure -search_files("*.py", target="files", path="src/") - -# Look at similar features -search_files("similar_pattern", path="src/", file_glob="*.py") - -# Check existing tests -search_files("*.py", target="files", path="tests/") - -# Read key files -read_file("src/app.py") -``` - -### Step 3: Design Approach - -Decide: -- Architecture pattern -- File organization -- Dependencies needed -- Testing strategy - -### Step 4: Write Tasks - -Create tasks in order: -1. Setup/infrastructure -2. Core functionality (TDD for each) -3. Edge cases -4. Integration -5. Cleanup/documentation - -### Step 5: Add Complete Details - -For each task, include: -- **Exact file paths** (not "the config file" but `src/config/settings.py`) -- **Complete code examples** (not "add validation" but the actual code) -- **Exact commands** with expected output -- **Verification steps** that prove the task works - -### Step 6: Review the Plan - -Check: -- [ ] Tasks are sequential and logical -- [ ] Each task is bite-sized (2-5 min) -- [ ] File paths are exact -- [ ] Code examples are complete (copy-pasteable) -- [ ] Commands are exact with expected output -- [ ] No missing context -- [ ] DRY, YAGNI, TDD principles applied - -## Principles - -### DRY (Don't Repeat Yourself) - -**Bad:** Copy-paste validation in 3 places -**Good:** Extract validation function, use everywhere - -### YAGNI (You Aren't Gonna Need It) - -**Bad:** Add "flexibility" for future requirements -**Good:** Implement only what's needed now - -```python -# Bad — YAGNI violation -class User: - def __init__(self, name, email): - self.name = name - self.email = email - self.preferences = {} # Not needed yet! - self.metadata = {} # Not needed yet! - -# Good — YAGNI -class User: - def __init__(self, name, email): - self.name = name - self.email = email -``` - -### TDD (Test-Driven Development) - -Every task that produces code should include the full TDD cycle: -1. Write failing test -2. Run to verify failure -3. Write minimal code -4. Run to verify pass - -See `test-driven-development` skill for details. - -### Frequent Commits - -Commit after every task: -```bash -git add [files] -git commit -m "type: description" -``` - -## Common Mistakes - -### Vague Tasks - -**Bad:** "Add authentication" -**Good:** "Create User model with email and password_hash fields" - -### Incomplete Code - -**Bad:** "Step 1: Add validation function" -**Good:** "Step 1: Add validation function" followed by the complete function code - -### Missing Verification - -**Bad:** "Step 3: Test it works" -**Good:** "Step 3: Run `pytest tests/test_auth.py -v`, expected: 3 passed" - -### Missing File Paths - -**Bad:** "Create the model file" -**Good:** "Create: `src/models/user.py`" - -## Execution Handoff - -After saving the plan, offer the execution approach: - -**"Plan complete and saved. Ready to execute using subagent-driven-development — I'll dispatch a fresh subagent per task with two-stage review (spec compliance then code quality). Shall I proceed?"** - -When executing, use the `subagent-driven-development` skill: -- Fresh `delegate_task` per task with full context -- Spec compliance review after each task -- Code quality review after spec passes -- Proceed only when both reviews approve - -## Remember - -``` -Bite-sized tasks (2-5 min each) -Exact file paths -Complete code (copy-pasteable) -Exact commands with expected output -Verification steps -DRY, YAGNI, TDD -Frequent commits -``` - -**A good plan makes implementation obvious.** diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review.md b/website/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review.md index 66100e83fd..bf6f13b70d 100644 --- a/website/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review.md +++ b/website/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review.md @@ -21,7 +21,7 @@ Pre-commit review: security scan, quality gates, auto-fix. | License | MIT | | Platforms | linux, macos, windows | | Tags | `code-review`, `security`, `verification`, `quality`, `pre-commit`, `auto-fix` | -| Related skills | [`subagent-driven-development`](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development), [`plan`](/docs/user-guide/skills/bundled/software-development/software-development-plan), [`test-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development), [`github-code-review`](/docs/user-guide/skills/bundled/github/github-github-code-review) | +| Related skills | [`subagent-driven-development`](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development), `plan` (now the built-in `/plan` command), [`test-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development), [`github-code-review`](/docs/user-guide/skills/bundled/github/github-github-code-review) | ## Reference: full SKILL.md diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-simplify-code.md b/website/docs/user-guide/skills/bundled/software-development/software-development-simplify-code.md index 49e3d0143d..57a1534692 100644 --- a/website/docs/user-guide/skills/bundled/software-development/software-development-simplify-code.md +++ b/website/docs/user-guide/skills/bundled/software-development/software-development-simplify-code.md @@ -21,7 +21,7 @@ Parallel 4-agent cleanup of recent code changes. | License | MIT | | Platforms | linux, macos, windows | | Tags | `code-review`, `cleanup`, `refactor`, `delegation`, `subagent`, `parallel`, `simplify` | -| Related skills | [`requesting-code-review`](/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review), [`test-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development), [`plan`](/docs/user-guide/skills/bundled/software-development/software-development-plan) | +| Related skills | [`requesting-code-review`](/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review), [`test-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development), `plan` (now the built-in `/plan` command) | ## Reference: full SKILL.md diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-spike.md b/website/docs/user-guide/skills/bundled/software-development/software-development-spike.md index 56c0954b69..470e984504 100644 --- a/website/docs/user-guide/skills/bundled/software-development/software-development-spike.md +++ b/website/docs/user-guide/skills/bundled/software-development/software-development-spike.md @@ -21,7 +21,7 @@ Throwaway experiments to validate an idea before build. | License | MIT | | Platforms | linux, macos, windows | | Tags | `spike`, `prototype`, `experiment`, `feasibility`, `throwaway`, `exploration`, `research`, `planning`, `mvp`, `proof-of-concept` | -| Related skills | [`sketch`](/docs/user-guide/skills/bundled/creative/creative-sketch), [`subagent-driven-development`](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development), [`plan`](/docs/user-guide/skills/bundled/software-development/software-development-plan) | +| Related skills | [`sketch`](/docs/user-guide/skills/bundled/creative/creative-sketch), [`subagent-driven-development`](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development), `plan` (now the built-in `/plan` command) | ## Reference: full SKILL.md diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging.md b/website/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging.md index 09c9e3c268..a3f9f288aa 100644 --- a/website/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging.md +++ b/website/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging.md @@ -21,7 +21,7 @@ description: "4-phase root cause debugging: understand bugs before fixing" | License | MIT | | Platforms | linux, macos, windows | | Tags | `debugging`, `troubleshooting`, `problem-solving`, `root-cause`, `investigation` | -| Related skills | [`test-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development), [`plan`](/docs/user-guide/skills/bundled/software-development/software-development-plan), [`subagent-driven-development`](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development) | +| Related skills | [`test-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development), `plan` (now the built-in `/plan` command), [`subagent-driven-development`](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development) | ## Reference: full SKILL.md diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development.md b/website/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development.md index bdf88a6620..4ef912ec90 100644 --- a/website/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development.md +++ b/website/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development.md @@ -21,7 +21,7 @@ TDD: enforce RED-GREEN-REFACTOR, tests before code. | License | MIT | | Platforms | linux, macos, windows | | Tags | `testing`, `tdd`, `development`, `quality`, `red-green-refactor` | -| Related skills | [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`plan`](/docs/user-guide/skills/bundled/software-development/software-development-plan), [`subagent-driven-development`](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development) | +| Related skills | [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging), `plan` (now the built-in `/plan` command), [`subagent-driven-development`](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development) | ## Reference: full SKILL.md diff --git a/website/docs/user-guide/skills/optional/software-development/software-development-grill-me.md b/website/docs/user-guide/skills/optional/software-development/software-development-grill-me.md index fef5deb6ee..8adeabcea0 100644 --- a/website/docs/user-guide/skills/optional/software-development/software-development-grill-me.md +++ b/website/docs/user-guide/skills/optional/software-development/software-development-grill-me.md @@ -21,7 +21,7 @@ Adversarial plan interview before implementation. | License | MIT | | Platforms | linux, macos, windows | | Tags | `planning`, `adversarial`, `interview`, `decision-tree`, `pre-implementation`, `review`, `alignment` | -| Related skills | [`plan`](/docs/user-guide/skills/bundled/software-development/software-development-plan), [`requesting-code-review`](/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review), [`subagent-driven-development`](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development), [`test-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development) | +| Related skills | `plan` (now the built-in `/plan` command), [`requesting-code-review`](/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review), [`subagent-driven-development`](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development), [`test-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development) | ## Reference: full SKILL.md diff --git a/website/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development.md b/website/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development.md index e773edd76c..5d884d63e7 100644 --- a/website/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development.md +++ b/website/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development.md @@ -21,7 +21,7 @@ Execute plans via delegate_task subagents (2-stage review). | License | MIT | | Platforms | linux, macos, windows | | Tags | `delegation`, `subagent`, `implementation`, `workflow`, `parallel` | -| Related skills | [`plan`](/docs/user-guide/skills/bundled/software-development/software-development-plan), [`requesting-code-review`](/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review), [`test-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development) | +| Related skills | `plan` (now the built-in `/plan` command), [`requesting-code-review`](/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review), [`test-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development) | ## Reference: full SKILL.md diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/skills-catalog.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/skills-catalog.md index 10962e16d1..618ff58c8b 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/skills-catalog.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/skills-catalog.md @@ -150,7 +150,6 @@ Hermes 在执行 `hermes update` 时也会同步内置技能,但同步清单 | [`dogfood`](/user-guide/skills/bundled/software-development/software-development-dogfood) | Web 应用探索性 QA:发现 bug、收集证据、生成报告。 | `software-development/dogfood` | | [`hermes-agent-skill-authoring`](/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring) | 编写仓库内 SKILL.md:frontmatter、验证器、结构规范。 | `software-development/hermes-agent-skill-authoring` | | [`node-inspect-debugger`](/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger) | 通过 --inspect + Chrome DevTools Protocol CLI 调试 Node.js。 | `software-development/node-inspect-debugger` | -| [`plan`](/user-guide/skills/bundled/software-development/software-development-plan) | 计划模式:将 Markdown 计划写入 `.hermes/plans/`,不执行。 | `software-development/plan` | | [`python-debugpy`](/user-guide/skills/bundled/software-development/software-development-python-debugpy) | 调试 Python:pdb REPL + debugpy 远程调试(DAP)。 | `software-development/python-debugpy` | | [`requesting-code-review`](/user-guide/skills/bundled/software-development/software-development-requesting-code-review) | 提交前审查:安全扫描、质量门控、自动修复。 | `software-development/requesting-code-review` | | [`spike`](/user-guide/skills/bundled/software-development/software-development-spike) | 一次性实验,在正式构建前验证想法。 | `software-development/spike` | diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/slash-commands.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/slash-commands.md index f40215a40c..8bb77fa52b 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/slash-commands.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/slash-commands.md @@ -11,7 +11,7 @@ Hermes 有两个斜杠命令入口,均由 `hermes_cli/commands.py` 中的中 - **交互式 CLI 斜杠命令** — 由 `cli.py` 分发,支持从注册表自动补全 - **消息平台斜杠命令** — 由 `gateway/run.py` 分发,帮助文本和平台菜单均从注册表生成 -已安装的 skill(技能)也会在两个入口以动态斜杠命令的形式暴露。这包括内置 skill,如 `/plan`,它会打开计划模式并将 markdown 计划保存在活动工作区/后端工作目录下的 `.hermes/plans/` 中。 +已安装的 skill(技能)也会在两个入口以动态斜杠命令的形式暴露。(`/plan` 曾是其中之一;它现在是内置命令 — 见下方 Session 表。) ## 权限与管理员/用户分级 diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/skills.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/skills.md index 78ac16c5d0..f2b2650084 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/skills.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/skills.md @@ -26,13 +26,13 @@ Skills 是 agent 在需要时可以加载的按需知识文档。它们遵循** /gif-search funny cats /axolotl help me fine-tune Llama 3 on my dataset /github-pr-workflow create a PR for the auth refactor -/plan design a rollout for migrating our auth provider +/songsee analyze the frequency spread of this mix # 只输入 skill 名称即可加载它,并让 agent 询问你的需求: /excalidraw ``` -捆绑的 `plan` skill 是一个很好的示例。运行 `/plan [request]` 会加载该 skill 的指令,告知 Hermes 在需要时检查上下文、编写 markdown 实现计划而非直接执行任务,并将结果保存在相对于当前工作区/后端工作目录的 `.hermes/plans/` 下。 +(计划模式的工作方式相同,但现在是内置命令:`/plan [request]` 告知 Hermes 在需要时检查上下文、编写 markdown 实现计划而非直接执行任务,并将结果保存在相对于当前工作区/后端工作目录的 `.hermes/plans/` 下。) 你也可以通过自然对话与 skills 交互: diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/research/research-research-paper-writing.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/research/research-research-paper-writing.md index 035f3c42a7..633bb1453a 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/research/research-research-paper-writing.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/research/research-research-paper-writing.md @@ -22,7 +22,7 @@ description: "为 NeurIPS/ICML/ICLR 撰写 ML 论文:设计→投稿" | 依赖项 | `semanticscholar`, `arxiv`, `habanero`, `requests`, `scipy`, `numpy`, `matplotlib`, `SciencePlots` | | 平台 | linux, macos | | 标签 | `Research`, `Paper Writing`, `Experiments`, `ML`, `AI`, `NeurIPS`, `ICML`, `ICLR`, `ACL`, `AAAI`, `COLM`, `LaTeX`, `Citations`, `Statistical Analysis` | -| 相关 skill | [`arxiv`](/user-guide/skills/bundled/research/research-arxiv), [`subagent-driven-development`](/user-guide/skills/bundled/software-development/software-development-subagent-driven-development), [`plan`](/user-guide/skills/bundled/software-development/software-development-plan) | +| 相关 skill | [`arxiv`](/user-guide/skills/bundled/research/research-arxiv), [`subagent-driven-development`](/user-guide/skills/bundled/software-development/software-development-subagent-driven-development), `plan`(现为内置 `/plan` 命令) | ## 参考:完整 SKILL.md diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/software-development/software-development-plan.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/software-development/software-development-plan.md deleted file mode 100644 index fc5bce2f41..0000000000 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/software-development/software-development-plan.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: "Plan — Plan 模式:将 Markdown 计划写入" -sidebar_label: "Plan" -description: "Plan 模式:将 Markdown 计划写入" ---- - -{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} - -# Plan - -Plan 模式:将 Markdown 计划写入 .hermes/plans/,不执行任何操作。 - -## Skill 元数据 - -| | | -|---|---| -| 来源 | 内置(默认安装) | -| 路径 | `skills/software-development/plan` | -| 版本 | `1.0.0` | -| 作者 | Hermes Agent | -| 许可证 | MIT | -| 平台 | linux, macos, windows | -| 标签 | `planning`, `plan-mode`, `implementation`, `workflow` | -| 相关 skill | [`writing-plans`](/user-guide/skills/bundled/software-development/software-development-writing-plans), [`subagent-driven-development`](/user-guide/skills/bundled/software-development/software-development-subagent-driven-development) | - -## 参考:完整 SKILL.md - -:::info -以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 所看到的指令内容。 -::: - -# Plan 模式 - -当用户需要计划而非执行时,使用此 skill。 - -## 核心行为 - -在本轮中,你仅进行规划。 - -- 不实现代码。 -- 不编辑项目文件,计划 Markdown 文件除外。 -- 不运行有副作用的终端命令,不提交、不推送,不执行外部操作。 -- 必要时可使用只读命令/工具检查仓库或其他上下文。 -- 你的交付物是保存在活跃工作区 `.hermes/plans/` 目录下的 Markdown 计划文件。 - -## 输出要求 - -编写一份具体且可操作的 Markdown 计划。 - -在相关时包含以下内容: -- 目标 -- 当前上下文 / 假设 -- 建议方案 -- 分步计划 -- 可能变更的文件 -- 测试 / 验证 -- 风险、权衡与待解问题 - -如果任务与代码相关,请包含精确的文件路径、可能的测试目标以及验证步骤。 - -## 保存位置 - -使用 `write_file` 将计划保存至: -- `.hermes/plans/YYYY-MM-DD_HHMMSS-.md` - -将该路径视为相对于活跃工作目录 / 后端工作区的路径。Hermes 文件工具具备后端感知能力,使用此相对路径可确保计划文件在 local、docker、ssh、modal 和 daytona 后端上均与工作区保持一致。 - -如果运行时提供了具体的目标路径,则使用该精确路径。 -如果没有,则自行在 `.hermes/plans/` 下创建一个合理的带时间戳的文件名。 - -## 交互风格 - -- 如果请求足够清晰,直接编写计划。 -- 如果 `/plan` 没有附带明确指令,则从当前对话上下文中推断任务。 -- 如果任务确实描述不足,提出简短的澄清问题,而非凭空猜测。 -- 保存计划后,简要回复你所规划的内容及保存路径。 \ No newline at end of file diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/software-development/software-development-spike.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/software-development/software-development-spike.md index e5486edd0d..6e4c54988d 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/software-development/software-development-spike.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/software-development/software-development-spike.md @@ -21,7 +21,7 @@ description: "在构建前验证想法的一次性实验" | 许可证 | MIT | | 平台 | linux, macos, windows | | 标签 | `spike`, `prototype`, `experiment`, `feasibility`, `throwaway`, `exploration`, `research`, `planning`, `mvp`, `proof-of-concept` | -| 相关 skill | [`sketch`](/user-guide/skills/bundled/creative/creative-sketch)、[`writing-plans`](/user-guide/skills/bundled/software-development/software-development-writing-plans)、[`subagent-driven-development`](/user-guide/skills/bundled/software-development/software-development-subagent-driven-development)、[`plan`](/user-guide/skills/bundled/software-development/software-development-plan) | +| 相关 skill | [`sketch`](/user-guide/skills/bundled/creative/creative-sketch)、[`writing-plans`](/user-guide/skills/bundled/software-development/software-development-writing-plans)、[`subagent-driven-development`](/user-guide/skills/bundled/software-development/software-development-subagent-driven-development)、`plan`(现为内置 `/plan` 命令) | ## 参考:完整 SKILL.md diff --git a/website/sidebars.ts b/website/sidebars.ts index f8eff725d5..8288c1cfde 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -324,7 +324,6 @@ const sidebars: SidebarsConfig = { 'user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring', 'user-guide/skills/bundled/software-development/software-development-inspecting-hermes-desktop-dom', 'user-guide/skills/bundled/software-development/software-development-node-inspect-debugger', - 'user-guide/skills/bundled/software-development/software-development-plan', 'user-guide/skills/bundled/software-development/software-development-python-debugpy', 'user-guide/skills/bundled/software-development/software-development-requesting-code-review', 'user-guide/skills/bundled/software-development/software-development-simplify-code',