# Planlet Plan > Explore, propose, create, or revise one repository-local Planlet without implementing product changes. Use when a user wants to investigate and persist a focused plan, refine an existing planlet, or prepare a reviewable implementation handoff. - Skill: `vipentti/planlet-plan` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds@latest add vipentti/planlet-plan` - Raw SKILL.md: https://api.skillmd.com/api/skills/vipentti/planlet-plan/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: MIT - Author: vipentti (https://skillmd.com/u/vipentti) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/vipentti/planlet-plan --- # Planlet Plan Create or revise one focused planlet while keeping planning separate from implementation. ## Start the workflow 1. Discover the repository root without traversing above its boundary. 2. Use one available `planlet` executable throughout the workflow. Confirm each needed operation with `planlet help `; do not infer support from this skill. Pass `--root ""` to every operational command. Treat angle-bracket runtime values as separate argv values; when invoking through a shell, apply shell-specific escaping instead of interpolating raw text. 3. Use `planlet --root "" list` to inspect active logical slugs and `planlet --root "" list --completed` to inspect completed logical slugs. For a revision, resolve exactly one active slug, run `planlet --root "" validate `, and read both files completely with `planlet --root "" --full show --part plan` and `planlet --root "" --full show --part tasks`. 4. Read applicable repository instructions when present. 5. The `planlet` CLI is required. If no executable is available, install it (`npm install -g @vipentti/planlet`) or invoke it through `npx @vipentti/planlet`. If it still cannot run, stop and report that, naming the missing executable. Do not reimplement CLI operations by editing planlet files. ## Develop the proposal 1. Inspect the repository before recommending an approach. 2. Look up repository facts instead of asking. - For a vague or incomplete request, surface material open decisions that affect outcome, boundaries, constraints, acceptance, verification, or task sizing. - Ask in small related batches (prefer about 2–4 related decisions; one-at-a-time only when answers depend on each other) with a recommended answer for each decision. - Settle those decisions enough for a fresh-session handoff before narrowing into a concrete proposal. - If the request is already precise, proceed without ceremonial questions. 3. Define the outcome, scope, exclusions, approach, acceptance criteria, verification, and meaningful risks. Compare options only when the choice matters. Keep `plan.md` static: verification records strategy, never results of a past or future run. Treat `plan.md` as the authoritative change-specific design and acceptance contract for this planlet, subject to applicable repository instructions and higher-level design documents. State each material requirement once in the most appropriate section instead of repeating it across Scope, Approach, Acceptance Criteria, Verification, and tasks. 4. Propose a descriptive slug matching `^[a-z0-9]+(?:-[a-z0-9]+)*$` and verify that its logical slug is unused among active and completed planlets. 5. Turn the proposal into `plan.md` and a compact execution index in `tasks.md`. An implementer is expected to read both files before starting: `plan.md` owns design decisions, boundaries, invariants, acceptance criteria, and broad verification strategy; `tasks.md` orders the delivered outcomes needed to realize that plan. Keep each task small enough that a typical agent can implement and verify one outcome without guessing its ownership. Do not duplicate detailed plan requirements in tasks. Prefer one concise task sentence; include likely components or task-specific verification only when they materially reduce ambiguity. If a task needs a long explanation or many independent requirements, move shared detail into `plan.md` or split the task. Read [planning guidance](references/planning-guidance.md) and use the templates in [plan-template.md](assets/plan-template.md) and [tasks-template.md](assets/tasks-template.md). 6. Before presenting the proposal, run a compression pass over the draft `tasks.md` against `plan.md` to remove recoverable detail; see [planning guidance](references/planning-guidance.md) for the full procedure. 7. Present the proposed plan and tasks in conversation. Outside the proposed file content, keep commentary brief: call out only material assumptions, exclusions, unresolved decisions, or tradeoffs that need review. Do not restate the plan in a second narrative summary. Obtain explicit confirmation before writing either file. If confirmation is declined or absent, leave the repository unchanged. ## Persist or revise For a new confirmed planlet: 1. Run `planlet --root "" create --title ""`. Treat non-zero exit as no authorization to write around a slug, path, or collision failure. 2. Confirm CLI created only H1 stubs. When the harness exposes a dedicated file-reading capability, read each created file with it rather than through a shell command, because such a harness can reject a write to a file it has not read and may not count a shell read. Then replace those two stubs with approved `plan.md` and `tasks.md` content, because `create` writes H1 stubs only and no CLI command accepts plan or task body content. Never use `create` for revision or overwrite an existing planlet. 3. Run `planlet --root "<repository-root>" validate <slug>`, then re-read both files with `planlet --root "<repository-root>" --full show <slug> --part plan` and `planlet --root "<repository-root>" --full show <slug> --part tasks`; inspect exact persisted content. For a confirmed revision, edit both existing files directly because CLI has no semantic revision operation. When the harness exposes a dedicated file-reading capability, read each file with it before editing, because such a harness can reject an edit to a file it has not read and may not count a shell read. Preserve IDs for unchanged tasks, assign new IDs above highest numeric suffix, and never silently remove completed work. Then run targeted `validate` and full `show` inspection as above. Do not modify product code, create extra planning documents by default, or begin implementation unless the user separately requests it. ## Finish Report selected logical slug, paths written or revised, proposal status, exact CLI validation result, warnings, and unresolved decisions.