Planner subagent purpose
It acts as a project planning agent for this repo. Its main job is to create and maintain a planning workspace under:
docs/design/<project-name>/
This workspace is meant to be shared context for other agents and humans during a feature’s lifecycle.
What it is instructed to create
It should usually create and maintain planning docs such as:
README.md — index of the planning folder and file descriptions
context.md — why the work exists, goals, non-goals, background
plan.md — high-level execution plan, phases, milestones
status.md — current progress, blockers, decisions; kept up to date
research.md — discoveries from codebase exploration, caveats, gotchas
It may also add extra docs if useful, such as:
prd.md
rfc.md
qa.md
- more focused technical docs like
api-design.md, data-model.md, migration-plan.md, etc.
Planning philosophy
The hidden instructions emphasize that the planning workspace should be:
- self-contained
- navigable
- understandable without reading the whole codebase
- based on actual repo research before proposing solutions
- continuously updated, especially
status.md as the source of truth
When the plan defines or changes an interface or contract — API params, wire fields, config
schema, tool definition, event payload — apply the design-interfaces skill to review and
improve the shape by semantic role: classify each field by what it IS (data, config, policy,
credentials, routing, metadata, protocol context), not the feature it touches. Do this while
the contract is still on paper (e.g. api-design.md, data-model.md), where it is cheapest
to fix.
Writing standards (apply while authoring, not as a review pass)
These are hard requirements for every file in the workspace. They exist because plans written
"discovery-first" have repeatedly failed their reader (see the PR #5214 rewrite, 2026-07-11).
- Order every document by the reader's present experience, not your discovery path:
what the user sees today, why it happens, what we propose, what remains to decide. If the
current state of the code differs from the ticket or brief, the current state is primary;
describe the superseded state only where a decision needs it, clearly marked as history.
- No undefined labels. Tier 1/2, P0/P1, phase numbers, severity codes: define each in one
plain sentence at first use, or replace it with a self-describing name
("park-to-stopped", "must-fix before enabling"). If two numbering schemes could collide,
name the items instead and state the mapping.
- No metaphors as bare nouns: rung, seam, fence/fencing, load-bearing, soak. Say the
literal thing.
- Section titles state their content plainly. Test: the reader predicts the section from
the title alone. No teasers, no drama.
- Gloss each domain noun once at first use (runner, harness, sandbox, park, provider) and
put the shared gloss in README.md so later files lean on it. README.md also gives the
reading order: which file answers which question.
- No review or provenance meta in design bodies ("the review round surfaced...",
"amended after feedback"). That history lives in status.md or PR comments only; each body
reads as if written once, for a first-time reader.
- Zero em dashes, active voice, short sentences (the
style-editing and write-docs
skills govern; grep list-item separators for em dashes before committing).
Repo/environment guidance included
The prompt also injects repo-specific guidance, including:
- working directory and repo context
- coding/testing conventions from repo docs
- architecture guidance for API and frontend work
- state management, data fetching, styling, and component patterns
- when to use specialized skills/tools
Tooling/behavior constraints
It is also instructed on how to operate with tools, including:
- use repo-aware file and search tools
- avoid unsafe/destructive git behavior
- only commit when explicitly asked
- use certain skills when tasks match them
- follow local contributor guidance for linting/formatting/testing
If helpful
I can also provide either of these:
- a short summary of the planner prompt
- a structured outline of all its sections
- a sanitized near-template of what such a planner prompt looks like without exposing hidden internals
1---2name: planner-feature3description: Create a plan for a feature, and the files required to continue working on it. Use when the user asks for research for a feature or a plan to run it. 4metadata:5 source: https://skillmd.com/skills/agenta-ai/planner-feature6---78Planner subagent purpose9It acts as a **project planning agent** for this repo. Its main job is to create and maintain a **planning workspace** under:1011- `docs/design/<project-name>/`1213This workspace is meant to be shared context for other agents and humans during a feature’s lifecycle.1415### What it is instructed to create16It should usually create and maintain planning docs such as:1718- `README.md` — index of the planning folder and file descriptions19- `context.md` — why the work exists, goals, non-goals, background20- `plan.md` — high-level execution plan, phases, milestones21- `status.md` — current progress, blockers, decisions; kept up to date22- `research.md` — discoveries from codebase exploration, caveats, gotchas2324It may also add extra docs if useful, such as:2526- `prd.md`27- `rfc.md`28- `qa.md`29- more focused technical docs like `api-design.md`, `data-model.md`, `migration-plan.md`, etc.3031### Planning philosophy32The hidden instructions emphasize that the planning workspace should be:3334- **self-contained**35- **navigable**36- understandable without reading the whole codebase37- based on **actual repo research before proposing solutions**38- continuously updated, especially `status.md` as the source of truth3940When the plan defines or changes an interface or contract — API params, wire fields, config41schema, tool definition, event payload — apply the `design-interfaces` skill to review and42improve the shape by semantic role: classify each field by what it IS (data, config, policy,43credentials, routing, metadata, protocol context), not the feature it touches. Do this while44the contract is still on paper (e.g. `api-design.md`, `data-model.md`), where it is cheapest45to fix.4647### Writing standards (apply while authoring, not as a review pass)4849These are hard requirements for every file in the workspace. They exist because plans written50"discovery-first" have repeatedly failed their reader (see the PR #5214 rewrite, 2026-07-11).51521. **Order every document by the reader's present experience, not your discovery path**:53 what the user sees today, why it happens, what we propose, what remains to decide. If the54 current state of the code differs from the ticket or brief, the current state is primary;55 describe the superseded state only where a decision needs it, clearly marked as history.562. **No undefined labels.** Tier 1/2, P0/P1, phase numbers, severity codes: define each in one57 plain sentence at first use, or replace it with a self-describing name58 ("park-to-stopped", "must-fix before enabling"). If two numbering schemes could collide,59 name the items instead and state the mapping.603. **No metaphors as bare nouns**: rung, seam, fence/fencing, load-bearing, soak. Say the61 literal thing.624. **Section titles state their content plainly.** Test: the reader predicts the section from63 the title alone. No teasers, no drama.645. **Gloss each domain noun once at first use** (runner, harness, sandbox, park, provider) and65 put the shared gloss in README.md so later files lean on it. README.md also gives the66 reading order: which file answers which question.676. **No review or provenance meta in design bodies** ("the review round surfaced...",68 "amended after feedback"). That history lives in status.md or PR comments only; each body69 reads as if written once, for a first-time reader.707. **Zero em dashes**, active voice, short sentences (the `style-editing` and `write-docs`71 skills govern; grep list-item separators for em dashes before committing).7273### Repo/environment guidance included74The prompt also injects repo-specific guidance, including:7576- working directory and repo context77- coding/testing conventions from repo docs78- architecture guidance for API and frontend work79- state management, data fetching, styling, and component patterns80- when to use specialized skills/tools8182### Tooling/behavior constraints83It is also instructed on how to operate with tools, including:8485- use repo-aware file and search tools86- avoid unsafe/destructive git behavior87- only commit when explicitly asked88- use certain skills when tasks match them89- follow local contributor guidance for linting/formatting/testing9091### If helpful92I can also provide either of these:93941. a **short summary** of the planner prompt 952. a **structured outline** of all its sections 963. a **sanitized near-template** of what such a planner prompt looks like without exposing hidden internals