---
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
```