---

name: software-planning-execution description: | Plan, spike, and execute software development tasks with subagent-driven development, TDD, systematic debugging, and pre-commit verification. version: 1.0.0 platforms: [linux, macos, windows] metadata: hermes: tags: [planning, implementation, tdd, debugging, code-review, subagent, workflow]

related_skills: [github-code-review]

Software Planning & Execution

A unified workflow for planning, experimenting, implementing, and verifying software changes.

---

1. Planning

Plan Mode (lightweight)

When the user wants a plan without execution:

• Write a concrete markdown plan under .hermes/plans/YYYY-MM-DD_HHMMSS-<slug>.md
• Include: goal, context, approach, steps, files to change, tests, risks
• Do not implement code or edit project files except the plan file

Writing Implementation Plans (comprehensive)

For multi-step features or delegation:

• Task granularity: 2-5 minutes of focused work per task
• Required per task: exact file paths, complete copy-pasteable code, exact commands with expected output, verification steps
• Header: goal, architecture (2-3 sentences), tech stack
• Structure: setup → core functionality (TDD for each) → edge cases → integration → cleanup
• Principles: DRY, YAGNI, TDD, frequent commits

---

2. Feasibility & Exploration (Spikes)

Before committing to a build, validate with throwaway experiments:

Loop: decompose → research → build → verdict

1. Decompose into 2-5 independent feasibility questions
2. Research competing approaches (brief: 2-3 sentences + comparison table)
3. Build one directory per spike (spikes/NNN-name/)
   • Bias toward runnable CLI, minimal HTML, or small web server
   • Hardcode everything; avoid Docker, bundlers, config systems
4. Verdict: VALIDATED | PARTIAL | INVALIDATED
   • Document what worked, what didn't, surprises, recommendation

Comparison spikes: same question, different approaches (002a, 002b)

---

3. Execution (Subagent-Driven Development)

Execute plans by dispatching a fresh delegate_task subagent per task, followed by two-stage review.

Per-task workflow:

1. Dispatch implementer — provide full task text + project context
2. Spec compliance reviewer — verify all requirements met, no scope creep
3. Code quality reviewer — check conventions, error handling, tests, security
4. Mark complete — only when both reviews pass

Red flags:

• Never skip reviews
• Never let implementer self-review
• Never start quality review before spec compliance passes
• Never dispatch multiple implementers for tasks touching the same files

Final step: Integration review after all tasks complete.

---

4. Quality Practices

Test-Driven Development (TDD)

Iron law: No production code without a failing test first.

RED-GREEN-REFACTOR cycle:

1. Write one minimal test showing expected behavior
2. Run it — verify it FAILS for the right reason
3. Write minimal code to pass
4. Run it — verify it PASSES
5. Refactor (keep tests green)
6. Repeat

Never: write code before test, skip the RED step, keep "reference" code, rationalize "just this once."

Systematic Debugging

Iron law: No fixes without root cause investigation first.

Four phases:

1. Root Cause Investigation — read errors, reproduce, check recent changes, gather evidence at component boundaries, trace data flow upstream
2. Pattern Analysis — find working examples, compare, identify differences
3. Hypothesis & Testing — one hypothesis at a time, smallest possible change
4. Implementation — regression test first, fix root cause (not symptom), verify, full suite pass

Rule of Three: After 3 failed fixes, STOP and question the architecture.

Pre-Commit Verification

Automated pipeline before git commit:

1. Get diff (git diff --cached)
2. Static security scan (secrets, shell injection, eval, pickle, SQL injection)
3. Baseline-aware tests and linting (only NEW failures block)
4. Self-review checklist
5. Independent reviewer subagent (JSON verdict: passed, security_concerns, logic_errors)
6. Evaluate — any failures → auto-fix loop (max 2 cycles)
7. Commit with [verified] prefix

Skill Migration & Adaptation

When migrating skills from another AI platform (e.g., Claude Code → Hermes):

1. Format conversion: Add YAML frontmatter (name, description, version, metadata.hermes.tags/category/config)
2. Body restructuring: Convert to Hermes standard sections (When to Use, Procedure, Pitfalls, Verification)
3. Tool call adaptation: Map platform-specific tool calls to Hermes equivalents (tool_use("bash") → terminal, TaskCreate → delegate_task, WebFetch → browser_navigate)
4. Path adaptation: Update all hardcoded paths to the new skill directory (~/.hermes/skills/<skill-name>/)
5. Parallel agent limits: Respect delegation.max_concurrent_children (typically 3). Split 4+ parallel agents into batches.
6. No persistent team state: Hermes delegate_task returns summaries to parent. No TeamCreate/SendMessage equivalent.
7. Verification: Test all external scripts with new paths before declaring migration complete

---

5. Integration Between Practices

Requirements → writing-plans → subagent-driven-development
                                    ↓
                              TDD per task
                                    ↓
                        systematic-debugging (if bugs)
                                    ↓
                        requesting-code-review (pre-commit)
                                    ↓
                                  Commit

---

Remember

Bite-sized tasks (2-5 min)
Exact file paths
Complete code (copy-pasteable)
Exact commands with expected output
TDD: RED → GREEN → REFACTOR
Debug: root cause before fix
Review: independent reviewer, fail-closed