# Darwin Plan Template

> Structured plan template for the Architect agent. Use when creating infrastructure or code change plans. Use when this capability is needed.

- Skill: `tomevault-io/darwin-plan-template` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/darwin-plan-template`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/darwin-plan-template/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/darwin-plan-template

---


# Darwin Plan Template

Use this structure for all plans:

```markdown
---
plan: [Action] [Target]
service: [name]
repository: [repo URL]
path: [helm path or source path]
domain: [CLEAR|COMPLICATED|COMPLEX]
risk: [low|medium|high]
steps:
  - id: 1
    agent: [agent]
    mode: [mode]
    summary: [short description]
    status: pending
  - id: 2
    agent: [agent]
    mode: [mode]
    summary: [short description]
    status: pending
---

# Plan: [Action] [Target]

## Reason
[Why this change is needed, based on evidence]

## Steps
1. Specific action with implementation details
2. Specific action with implementation details

## UX Considerations (include when plan touches frontend/UI)
- User goal: [what the user is trying to accomplish]
- Current friction: [what's wrong with the current experience]
- Interaction pattern: [expand/collapse, modal, inline edit, etc.]
- States: [loading, empty, error -- how each is handled]

## Risk Assessment
- Risk level: [low/medium/high]
- Rollback: [how to undo]

## Verification
- [How will we know the change worked?]
- [What metric or signal confirms success?]
```

The frontmatter YAML header is machine-readable by the Brain and executing agents (Developer, QE).
The `status` field starts as `pending` and the executing team updates it to `in_progress`, `completed`, or `failed` as they work through the steps.
The Markdown body below the frontmatter contains the full human-readable details for each step.

## Available Agents for Step Assignment

Assign each step in the frontmatter `steps:` array to an agent and mode:

- **sysAdmin** -- Kubernetes and GitOps operations
  - `investigate` -- Read-only cluster and service inspection, remote cluster access
  - `execute` -- GitOps mutations (Helm value changes, commit, push)
  - `rollback` -- Revert last GitOps change, verify CD sync

- **developer** -- Code implementation agent
  - `investigate` -- Read-only: check MR/PR status, code inspection
  - `execute` -- Single write actions: post comment, merge MR, tag release
  - `implement` -- Code changes. Brain dispatches Developer first, then QE for verification.

- **qe** -- Quality verification agent
  - `test` -- Run tests, verify deployments via browser (Playwright MCP or repo Playwright tests)
  - `investigate` -- Read-only test status checks

- **architect** -- Planning and review (use sparingly, avoid self-referential loops)
  - `review` -- Code/MR review with severity findings
  - `analyze` -- Information gathering and status report

**How to write steps for developer and QE:**

- For code changes that need verification: assign implementation steps to `developer` with `mode: implement`,
  and verification steps to `qe` with `mode: test`. Brain dispatches them sequentially.
- For read-only checks (MR status, code inspection): use `developer` with `mode: investigate`.
- For single Git actions (merge, comment, tag): use `developer` with `mode: execute`.

For COMPLICATED plans with multiple options, present options WITHOUT step assignments in the frontmatter.
Only the selected option's execution steps get `agent` and `mode` fields.

## Domain Classification

- **CLEAR** (known fix): produce a minimal 2-3 step plan
- **COMPLICATED** (needs analysis): present 2-3 options with trade-offs
- **COMPLEX** (novel/unknown): propose a probe -- a small safe-to-fail experiment

## Principles

- Every plan is a Controller: takes the system from current state (PV) to desired state (SP)
- Every plan MUST include a Verification section
- Every plan MUST include a Feedback mechanism (metric or signal)
- Break large changes into small, independently deployable batches
- If your plan has more than 5 steps, ask: am I overcomplicating this?
- If the plan changes frontend/UI, include the "UX Considerations" section and apply the darwin-ux-patterns skill

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/the-darwin-project) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->