code-plan

Code Plan Skill

Generate a structured plan for implementing a task in a specific repository. The plan is the bridge between "I have a ticket" and "let me start writing code" — it lists files to create, files to modify, tests to add, and risks before any code is written.

This skill produces JSON. It does not write code; that is code_agent_*'s job.

When to use this skill

• The user provides a Linear ticket, GitHub issue, or free-form task description and asks you to implement it.
• Before any code_agent_write, code_agent_edit, or github_commit tool call.
• When the user explicitly asks for a plan.

When NOT to use this skill

• Tiny single-file edits (1–3 lines). Just edit directly.
• Pure exploration tasks. Use grep_search / directory_tree instead.
• Pure scaffolding tasks (e.g. "create a new React app"). Use code_agent_scaffold instead.

Plan-then-execute discipline

Once a plan is generated, present its summary and files_to_modify / files_to_create lists to the user before writing code. Do NOT proceed to implementation if the plan returns complexity: "high" or non-empty risks without acknowledging them to the user. The plan is a contract: subsequent code-writing tool calls should match files listed in the plan. If the plan turns out to be wrong, regenerate it rather than silently drifting from it.

Workflow integration

Canonical sequence for a ticket-to-PR flow:

linear_get_issue
  → code_plan_create                  [present summary + risks to user]
  → code_agent_write / code_agent_edit
  → code_plan_validate                [optional sanity check before commit]
  → github_commit
  → github_create_pr

Repo signal extraction (informational)

code_plan_create automatically samples the repository so the LLM has enough context to plan without you pre-reading files. It collects:

1. The top entries of git ls-files (the repo tree).
2. The contents of detected manifest files: package.json, go.mod, pyproject.toml, Cargo.toml, pom.xml, build.gradle*.
3. The first ~4 KB of README.md if present.