feat: /plan graduates from bundled skill to built-in command on every surface
The bundled plan skill's 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 at
index 57 of 82 bundled skills). Converting it to a first-class CommandDef
gives it a guaranteed core-tier menu slot on every platform.
- agent/plan_prompt.py: build_plan_prompt() — plan-mode rules + authoring
craft distilled from the retired skill; prompt-injection pattern like
/learn and /init (no engine, no model-tool footprint, cache-safe).
- CLI: _handle_plan_command mixin handler (pending-input injection).
- Gateway: /plan branch rewrites event.text and falls through (role
alternation preserved).
- TUI: command.dispatch branch ('plan' was already in
_PENDING_INPUT_COMMANDS).
- Removed skills/software-development/plan/ + docs pages (EN + zh-Hans),
catalog rows, sidebar entry, related_skills references.
- PROTECTED_BUILTIN_SKILLS is now empty (mechanism kept); dependent
curator/usage tests moved to monkeypatched sentinels.
Salvages #67292 by @webtecnica (credit: first /plan command submission,
issue #67264); reworked from inline planning prompt to the prompt-injection
pattern with workspace-saved plans. Closes #67264, closes #36821 (empty
/plan infers task from conversation context).
This commit is contained in:
Teknium
103
agent/plan_prompt.py
Normal file
103
agent/plan_prompt.py
Normal file
@@ -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-<slug>.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
|
||||
)
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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\".",
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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]
|
||||
|
||||
---
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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-<slug>.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.**
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
84
tests/agent/test_plan_prompt.py
Normal file
84
tests/agent/test_plan_prompt.py
Normal file
@@ -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-<slug>.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()
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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"
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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` |
|
||||
|
||||
@@ -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 — `/<name>` 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 <what to learn from>` | 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 <id>` to create the proposed automation, `/suggestions dismiss <id>` 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 <what to learn from>` | 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 (`/<name>` 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). |
|
||||
|
||||
@@ -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/<name>/SKILL.md` directly with your editor. The pin guards tool-driven deletion, not your own filesystem access.
|
||||
|
||||
|
||||
@@ -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:
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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-<slug>.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.**
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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` |
|
||||
|
||||
@@ -11,7 +11,7 @@ Hermes 有两个斜杠命令入口，均由 `hermes_cli/commands.py` 中的中
|
||||
- **交互式 CLI 斜杠命令** — 由 `cli.py` 分发，支持从注册表自动补全
|
||||
- **消息平台斜杠命令** — 由 `gateway/run.py` 分发，帮助文本和平台菜单均从注册表生成
|
||||
|
||||
已安装的 skill（技能）也会在两个入口以动态斜杠命令的形式暴露。这包括内置 skill，如 `/plan`，它会打开计划模式并将 markdown 计划保存在活动工作区/后端工作目录下的 `.hermes/plans/` 中。
|
||||
已安装的 skill（技能）也会在两个入口以动态斜杠命令的形式暴露。（`/plan` 曾是其中之一；它现在是内置命令 — 见下方 Session 表。）
|
||||
|
||||
## 权限与管理员/用户分级
|
||||
|
||||
|
||||
@@ -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 交互：
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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-<slug>.md`
|
||||
|
||||
将该路径视为相对于活跃工作目录 / 后端工作区的路径。Hermes 文件工具具备后端感知能力，使用此相对路径可确保计划文件在 local、docker、ssh、modal 和 daytona 后端上均与工作区保持一致。
|
||||
|
||||
如果运行时提供了具体的目标路径，则使用该精确路径。
|
||||
如果没有，则自行在 `.hermes/plans/` 下创建一个合理的带时间戳的文件名。
|
||||
|
||||
## 交互风格
|
||||
|
||||
- 如果请求足够清晰，直接编写计划。
|
||||
- 如果 `/plan` 没有附带明确指令，则从当前对话上下文中推断任务。
|
||||
- 如果任务确实描述不足，提出简短的澄清问题，而非凭空猜测。
|
||||
- 保存计划后，简要回复你所规划的内容及保存路径。
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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',
|
||||
|
||||
Reference in New Issue
Block a user