Hand off to your coding agent
This guide explains how to hand off a task from the PlanQ workbench to your preferred coding agent. By using the project-scoped Agent Skill, your agent can automatically manage, validate, and apply changes directly to your .plan files.
PlanQ provides the planq CLI and the plan-gantt Agent Skill, but you must bring your own coding agent with access to the repository. Native project discovery is verified for Codex, Claude Code, and TRAE. Other agents can still follow the handoff by explicitly reading the canonical Skill. For a manual workflow without an agent, see the Quickstart.
1. Copy the handoff prompt
To begin, open your project in the workbench and click the Hand off to your coding agent dialog:
This generates a prompt containing the specific context and instructions your agent needs. Copy this prompt and paste it into your coding agent's chat interface. You can optionally add any specific goals or details you want the agent to focus on.
Note: The generated prompt contains only contextual instructions. It does not include any sensitive credentials, browser session tokens, Bridge token, Workspace ID, or local absolute path.
2. Environment verification
Once you provide the prompt, your coding agent will automatically verify its environment. First, it will run planq version to ensure the PlanQ CLI is installed and available in the current worktree.
If the CLI is missing or unsupported on your platform, the agent will notify you so you can follow the installation guide to set it up. For more details on commands, check the CLI reference.
3. Skill installation and checks
Next, the agent runs planq skill status. The top-level result.status describes the canonical payload only. result.integrations reports project discovery separately for Codex, Claude Code, and TRAE.
Depending on the status, the agent will take the appropriate action:
- Missing: The agent runs
planq skill installonce, then checks again. - Current: The path exactly matches the bundled canonical payload, forwarder, or supported repository-local relative symlink.
- Conflict: The agent stops and reports the returned relative paths. PlanQ does not overwrite different versions, local changes, or unknown files.
For a known runtime, both canonical result.status and that runtime's integration status must be current. An unknown agent must not claim native discovery support.
| Runtime | Project discovery path | Installed mode |
|---|---|---|
| Codex | .agents/skills/plan-gantt/ | Canonical payload |
| Claude Code | .claude/skills/plan-gantt/SKILL.md | Lightweight forwarder |
| TRAE | .trae/skills/plan-gantt/SKILL.md | Lightweight forwarder or an existing safe relative symlink |
| Other / unknown | No promised native path | Explicit canonical read only |
planq skill install is always project-scoped. It does not support --global, --agent, or --force, does not create .codex/skills, and does not write a Skill into your home directory.
These files are project dependencies and can be committed to version control. For ownership details, see the project files reference.
4. Loading the Skill
After verification, every agent explicitly reads .agents/skills/plan-gantt/SKILL.md, even when native discovery is current. The Claude Code and TRAE files contain discovery metadata and a pointer only; they do not duplicate the canonical rules, references, or fixtures.
5. Applying and validating changes
With the Skill loaded, the agent understands your plan goals and begins making the necessary updates to your .plan source files.
PlanQ enforces strict validation to ensure your plans are always in a healthy state. After making changes, the agent will automatically run planq validate <entry> to verify that the syntax, dependencies, and constraints are correct. The handoff is considered successful once the validation passes without any errors.
6. Previewing the result
The agent will not open a preview unless the user explicitly asks for one. If you want to see the updated plan visually, simply ask your agent to open a preview. The agent will use the CLI to launch a local, read-only preview of your Gantt chart in the browser.
For more details on the preview functionality, see the Local Preview guide.