# Plan First

> |

- **Type:** Skill
- **Install:** `agentstack add skill-bearded-illirian-trailmark-plan-first`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [bearded-illirian](https://agentstack.voostack.com/s/bearded-illirian)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [bearded-illirian](https://github.com/bearded-illirian)
- **Source:** https://github.com/bearded-illirian/trailmark/tree/main/aihub/.claude/skills/plan-first

## Install

```sh
agentstack add skill-bearded-illirian-trailmark-plan-first
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Plan-First Protocol

Mandatory protocol before **any** of the following:

- Writing a document (spec, README, guide, architecture)
- Writing new code (file, module, component)
- Refactoring existing code
- Database migration
- Writing tests / test plan
- Git operations (commit, PR, merge)

## Input

The approved `library-first-{N}.{R}.md` with atomic rows the plan will execute.

## Output

A 7-15 row plan table saved as `plan-first-{N}.{R}.md`; after execution — `report-{N}.{R}.md` and `user-note-{N}.{R}.md`.

## Hands off to

`ship-first` — per-block mode closes the block and moves to next; task-level mode closes the task.

---

## Step 0 — Task context

Ensure `{log_dir}` and `{slug}` are known.

---

## Step 1 — Build the plan table

A table of 7–15 rows. Each row = one atomic step.

Columns:
- **#** — sequential number
- **Step title** — verb + object ("create X", "update Y", "delete Z")
- **Short summary** — 1 sentence what this step actually does

Rules:
- 7 to 15 rows — fewer means the block is too small (skip planning), more means it's too big (decompose)
- Right column is a concrete summary, not "TBD" or empty
- No research steps ("read X", "figure out Y") — those belong in flow-first / library-first, not plan-first

---

## Step 2 — Show table + pick mode

Show the plan table to the user. Ask for one of three modes:

```
Mode:
1 — Autopilot: I execute every step without pauses, then a final report
2 — Step-by-step: I pause after each step, wait for "ok" to continue
3 — Draft only: I don't execute, just save the plan for later
```

Wait for the user's response.

Auto-execution context (e.g. `dev-auto-first`): mode = 1 (autopilot) chosen automatically.

---

## Step 3 — Save the artifact

Write `{log_dir}/plan-first-{N}.{R}.md` where:
- `N` = current block number
- `R` = round (1 by default, 2+ on revision)

Structure:

```markdown
> 🔗 Task: tasks/log/{slug}/task.md

# plan-first — plan for block {N}

**Date:** {date}
**Mode:** {chosen mode}

## Plan

| # | Step title | Short summary |
|:-:|---|---|
| 1 | ... | ... |
| ... | ... | ... |

## Risks

- {risk 1}
- ...

## Out of scope

- {what is deliberately not done in this block}
```

Register in `task_artifacts` (`artifact_type = 'plan-first'`, `round_num = R`).

---

## Step 4 — Execute per mode

**Mode 1 (Autopilot):** run each step in order. Report only when done.

**Mode 2 (Step-by-step):** after each step ask "next?". User writes "ok" → continue. User writes anything else → treat as feedback, adjust.

**Mode 3 (Draft only):** stop after saving the plan. Do not execute.

Handle failures per step:
- Non-critical error → log and continue
- Critical error → stop, report, wait for the user

---

## Step 5 — Deploy (default embedded, opt-out only)

Unless the user says "no deploy" or the changes are draft-only:
- Commit the changes with a message referencing the block
- Push to `origin main`
- Sync to sibling projects if the change affects shared skills / commands (`sync-agents.sh`)

Rule: deploy is the default. Only pause for confirmation when the diff touches non-whitelist paths (per CLAUDE.md push policy).

---

## Principles

1. **Every code / doc change goes through plan-first** — otherwise the actual scope drifts silently
2. **7–15 rows** — the sweet spot. Under 7 = block too small, over 15 = decompose the block
3. **Verb + object per step** — makes progress checkable
4. **Explicit out-of-scope** — prevents feature creep during execution
5. **Save the plan even in draft mode** — future you can resume

---

## Anti-patterns

### ❌ Skipping plan-first for "quick" edits
"It's just one line" — until it accidentally breaks three consumers. Plan-first anchors the change.

### ❌ Research steps in the plan table
"Read X to figure out Y" belongs in flow-first / library-first, not plan-first. Plan-first steps are actions, not investigations.

### ❌ Empty "short summary" column
"TBD" or blank means the plan isn't real. Every step must be concretely described.

### ❌ Skipping "Risks" and "Out of scope" sections
Even if you write `—`, mark them explicitly. Silence = these dimensions weren't thought about.

### ❌ Executing before user picks a mode
Wait for mode selection. Even in autopilot orchestration, the mode is picked via automated answer, not silent execution.

### ❌ Inlining instead of `Skill()`
Always via the Skill tool.

---

## Related skills

- **flow-first** — landscape check before planning (Tier 1 cycle)
- **library-first** — reuse audit before planning (Tier 1 and Tier 2 cycles)
- **ship-first** — finalization after execution

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [bearded-illirian](https://github.com/bearded-illirian)
- **Source:** [bearded-illirian/trailmark](https://github.com/bearded-illirian/trailmark)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-bearded-illirian-trailmark-plan-first
- Seller: https://agentstack.voostack.com/s/bearded-illirian
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.