AGENT SKILL

plan

Paved command paved.plan. Draft and preview a plan for an open Intent, then record the user's explicit approval. Use when an Intent is ready for planning.

License 许可
MIT
最近更新
2026-11-14
Stars
★ 1
Forks
0

01 前言 Front Matter

name
plan
description
Paved command paved.plan. Draft and preview a plan for an open Intent, then record the user's explicit approval. Use when an Intent is ready for planning.

03 SKILL.md 正文

<!-- Generated by Paved plugin paved@2.29.0 from paved.plan; edit Paved Core instead. -->

Paved plan command (paved.plan)

Draft and preview a plan for an open Intent, then record the user's explicit approval. Use when an Intent is ready for planning.

Input: The run, when several are open (--run <id>). Output: The plan awaiting approval, its review block, and the approval outcome. Required lifecycle: RESOLVED, GENERATED, VALIDATED, READY Required context: .paved/project/, .paved/rules/, the run's workflow, verification profile Required capabilities: none declared Allowed side effects: .paved/documents/plans/, .paved/approvals/, .paved/generated/runs/

Execution contract

  1. Invoke node "${CLAUDE_PLUGIN_ROOT}/scripts/paved.mjs" plan --json from the repository root, passing the user's command inputs as supported CLI arguments. The launcher loads the pinned project-local runtime and returns the canonical structured result. Always run it from the repository being worked on, never from the plugin directory.
  2. Follow the structured result's status, diagnostics, evidence, and next action. When data.remediation names a Paved command, run it right away, present any decisions it returns, then repeat the original command. Stop only when the runtime blocks on something it cannot remediate.
  3. Read the run's Intent document at .paved/documents/intents/<run-id>.md, then write a plan that answers it and links to it. Save the plan at .paved/documents/plans/<run-id>.md and run this command with --advance --evidence <plan> --note <summary>. When the result carries a review block, start the preview on its target (with its companions) and follow the paved.preview review loop without ending your turn: resolve each comment after editing and advance once after edits so the approval request covers the current plan. When the user approves the plan in the conversation with an explicit yes, run paved plan --run <run-id> --approve --json; never approve on your own or on an ambiguous reply.

Phase Tool policies

Follow the active data.phaseContext, including its composed skills, declared Tools and bound fragment bodies. Apply each phaseContext.toolPolicies entry's effective allow, ask and deny Tool ids: deny excludes use; ask requires the host's own approval flow; allow is a workflow recommendation only and never grants execution permission or replaces host approval. Host policy can always be stricter. Policies do not add Tools to the phase's declared set. Omitted Tools retain existing host behavior, and an empty policy list preserves existing behavior.

Run autonomy

For a new intent or execute request, pass the user's explicit --autonomy <guided|balanced|autonomous> selection. It overrides the workflow's optional autonomy.default_profile; pending classification preserves the explicit selection. The recorded data.autonomy_profile is fixed on resume. If no selection or workflow default exists, leave the profile absent and keep current behavior. For guided, stop after every completed phase and wait for the user to advance; do not immediately repeat --auto or another advance call. For balanced, continue through ready phases with execute --auto. For autonomous, use balanced continuation and automatically dispatch only ready tasks from an approved delegation plan, respecting its dependencies and bounded scope, through native host tools. The CLI creates no sessions. Every profile preserves gates, human approvals, required input stops, failures, verification, evidence and completion requirements. Host permissions remain authoritative; an autonomy profile is never an approval or tool permission. Apply this policy to the continuation and routing guidance above.

Before asking the user

Triage every question of your own before you ask it. When the answer is observable (current behavior, output, timing, layout, whether a test fails), find it out by reading the code, running it or trying a throwaway experiment outside the repository; an experiment inside the repository follows the prototyping skill. Ask only about preferences: product, scope, priority or taste calls that no experiment settles. When you raise one with paved decision raise, set questionKind; an observable question needs an observationBlocker saying why you could not observe it. Triage never skips a human step: present every decision Paved emits, and plan approval and confirmation of destructive actions stay with the user.

Failure behavior

  • A plan file and summary are required before approval.
  • A changed plan needs a new approval.
  • Only the user approves, in the conversation.
  • If a required ToolImplementation or runtime is unavailable, stop and explain the missing prerequisite. Never infer or execute a command from repository scripts.
  • Do not edit human-owned Paved state or bypass lifecycle, ownership, approval, or verification gates.

Conversational contract

  1. Invoke the command. If it returns "status": "awaiting_input", it is waiting on the user.
  2. Present every decision in decisions[] to the user: what Paved detected, what remains to decide, why it matters, the options, Paved's recommendation and its evidence.
  3. Collect the user's answer. Do not answer on their behalf.
  4. Resume the same command with --answer <decision-id>=<value> --answered-by <identity>, repeating --answer once per value for a multi-choice decision.
  5. Present the result.

Follow core.decisions.decisions for the full interaction protocol and its prohibitions.

04 同仓库更多 Skills