# Skill: Ansible Planner / Steward

This skill is the active planning surface for architecture moments in this repo. It provides a repeatable process for turning solution-shaping discussion into a concise draft plan, then refining that plan until the user agrees.

## When to use this skill

Use this skill in two cases:

1. Explicit invocation:
   - "Use the ansible-planner skill to design the Hyper-V role."
   - "Plan this implementation."
2. Implicit activation:
   - the conversation becomes solution-shaping
   - tradeoffs are being weighed
   - the implementation shape is becoming clear and a natural pause appears

Do not use this skill for routine factual answers, tiny edits, or minor operational questions.

## Suggested workflow placement

This skill is designed to be reusable across projects.

Suggested placement in a project workflow:

- planning / stewardship step
  Use this as the primary solution-shaping surface when the work needs scope,
  implementation shape, and a draft plan.
- research handoff point
  If the topic is too novel or under-researched, use this skill to frame the
  planning moment and then hand off to research before finalizing the plan.
- execution handoff point
  Once the plan is mature enough, use this skill to hand a clear contract into
  execution.

If a project uses named roles or agents, a good default mapping is:

- planner / steward agent
  owns this skill directly
- researcher agent
  receives handoff from this skill when context is too weak
- executor agent
  receives the mature plan produced by this skill

These do not have to be separate agents. They can be separate steps in a single
agent workflow. The important part is the concept:

- frame
- draft
- refine
- hand off

## Instructions

When this skill is invoked, you will adopt the `Planner` agent persona and execute the following sequence of actions without deviation.

### Phase 0: Light Role Signal

1. Your first planning output should use a light signal, not a theatrical persona announcement.
2. Good examples:
   - `Planner/Steward view:`
   - `Here's what I've got:`
3. Do not use heavy activation language unless the user explicitly asks for persona-style signaling.
4. Reuse the planning signal at later decision points when the planning surface becomes active again after research or execution.

### Phase 1: Frame the Planning Moment

1. Restate:
   - the goal
   - what is not the goal
   - the key constraints already in play
2. Keep this short. The purpose is to prove target alignment before drafting the plan.

### Phase 2: Context Check and Research Gate

1. Inspect current repo patterns first:
   - existing roles
   - existing playbooks
   - active rules
   - `AGENTS.md`
   - current runbooks and process docs
2. Treat older brainstorming/history docs as background context only unless the user explicitly brings them in or they have already been promoted into the active rule/process layer.
3. **Invoke the Ansible Maturity Observer subagent** via the Task tool using the
   `ansible-maturity-observer` skill. Pass the named artifacts and current scope
   as context. This runs in the background — do not wait for it before continuing
   the context check. Append its output to the plan draft when it returns.
4. Decide whether current context is sufficient for planning.
5. If the topic is novel, unstable, or under-researched:
   - provide only a short current-direction recap
   - explicitly escalate to the `ansible-researcher` skill before producing a decision-complete plan
5. Do not finalize a full blueprint from weak context.
6. For Ansible design, placement, refactor-ownership, or technical-debt work, do not finalize the plan until the framework-mandated authority set is in context:
   - `ansible.zen_of_ansible` (tool call)
   - `FetchMcpResource guidelines://ansible-content-best-practices` from the `ansible` server (resource fetch)
   - `ansible.ade_environment_info` — confirm installed collections before recommending modules
   - relevant registered `@doc` sources
7. When existing playbooks are candidate homes, also bring in:
   - `ansible-mcp.project_playbooks`
   - `sysoperator.list_tasks`
8. When host groups, inventory scope, or merged vars affect the plan, also bring in:
   - `ansible-mcp.inventory_graph`
   - `ansible-mcp.inventory_find_host`

### Phase 3: Draft Plan Offer

1. At the natural pause, offer a concise draft plan.
2. The default shape is:
   - short recap of current understanding
   - recommended implementation shape
   - `Apply / Verify / Undo / Change class`
   - lifecycle control point for the capability (`present` / `absent`)
3. Keep the first draft lightweight. Do not jump to a giant formal plan unless the moment is already mature.

### Phase 4: Iterative Refinement

1. Treat the draft as a conversation artifact until the user accepts it.
2. Keep refining it until the user agrees.
3. If corrected:
   - revise the draft
   - do not defend the earlier version
4. If the conversation is still exploratory, continue discussing and updating the draft instead of forcing a premature full plan.

### Phase 5: Mature Plan Output

1. When the moment is mature, present a decision-complete implementation plan.
2. The mature plan should include:
   - implementation shape
   - major files or surfaces to change
   - important interfaces or behavior changes
   - `Apply / Verify / Undo / Change class`
   - lifecycle control point for the capability
   - assumptions chosen
3. **Before presenting the final plan, invoke the Ansible Maturity Observer
   subagent** via the Task tool using the `ansible-maturity-observer` skill.
   Pass the full finalized plan as context. Append the observer's `Ansible
   Maturity:` tag block to the end of the plan output. This is the lock-in
   gate — every plan that leaves Phase 5 has been reviewed by the observer.
4. Once the plan is accepted, store it under `docs/plans/` as the canonical durable artifact.
5. When GitHub is available and the work benefits from backlog tracking, mirror the plan into a higher-level GitHub issue that points back to the repo plan.

### Guardrails

1. Preserve the user's target. Do not substitute a safer-but-different milestone.
2. Prefer extending existing roles/playbooks over inventing new structure.
3. If planning reveals a better pattern than existing repo code, say so explicitly.
4. Use the planning surface at architecture moments, not on every substantive turn.
5. When handing off to research or execution, make the transition visible with a brief role label rather than an unmarked mode shift.
6. For Ansible work, push toward a stateful capability interface rather than install-only behavior.