Plan a Feature

Turn a feature idea into a tracked, well-structured plan inside Flownix. Prerequisite: flownix-basics (hierarchy, statuses, components, "ticket is memory").

0. Load project context

cat .flownix 2>/dev/null || cat .ai-flow

Parse the YAML for project_id / org_id. Neither file exists → run flownix-init.

Then read the project's policy — before creating anything:

get_project_policy({ project_id })

If spec_first is on, this skill is not the one you want. In that mode the order of work is reversed: the feature's document is written and approved first, and the server refuses to create a task or plan under a feature whose delta is not approved. Hand over to spec-first-change and follow it instead — everything below assumes decomposition may happen now.

Everything else in this skill is for spec_first: false, which is the default and covers every project that has not deliberately switched over.

1. Orient

• get_tree for the structure, list_components({ project_id }) for the shape of the system.
• Search semantically before creating anything — the tree shows titles, not meaning:

  rag_query({ project_id, query: "<the request in one sentence>", k: 8 })
  rag_context({ project_id, query: "<domain area> — prior decisions and conventions" })

  get_node the plausible hits and decide explicitly: extend an existing node, depend on it, or create new. Record that decision in the [plan] comment (step 4). Empty results are not proof of absence — check rag_status. See flownix-rag-search.

2. Decompose

Top-down, shallowest tree that fits — don't over-nest:

• epic only for a genuinely large body of work.
• feature — the shippable capability (create_node, kind feature).
• plan under the feature — the implementation approach in content as Markdown: goals, approach, risks, an ordered checklist of tasks.
• task per concrete executable unit, under the plan. Each task's content must be self-contained: what to do, acceptance criteria, and the context an executor needs.
• doc node for the feature's durable specification (create_doc_node) — the intended behaviour and contract after it ships, not a repeat of the task checklist. Then set_references on each task with this doc, so executors and the strict close gate have an explicit task → spec link.
• ticket_ref — if the request names an external tracker ticket (Jira/YouTrack/…), set it on every node you create for it (create_node, ticket_ref: "PROJ-123"). Optional in the schema, mandatory whenever a ticket is mentioned.

3. Bind to system components — mandatory

Every node and the spec doc must be linked to at least one component. Nothing you create in step 2 is finished until it is bound.

list_components({ project_id })        // what the system already knows about itself
create_node({ ..., components: ["AF-COMP-3", "AF-COMP-7"] })   // link at creation
set_node_components({ node: "AF-TASK-12", components: ["AF-COMP-3"] })  // replaces the set

• Several components are normal. A feature touching the API and the web app is linked to both; link every part it actually touches, not just the first one that fits.
• The doc/spec is bound too — same call, same rule. An unbound spec is unreachable from the service it describes.
• No suitable component? Create it — create_component(\{ project_id, title, repo_path, component_kind, parent \}) with the name it really has in the repository, then link. Read the repo before naming it; never invent a component that no code corresponds to.
• If the project has no components at all, inventory the repository first with map-components, then plan — planning into a system nobody has described produces work that lands nowhere.
• The only exception is a truly cross-cutting node (release checklist, process ticket). Say so in the [plan] comment instead of leaving it silently unlinked.

4. Enrich

• add_tag per node (backend, frontend, db, infra) so work can be filtered and routed.
• add_dependency for real ordering only. The edge reads "from_node depends on to_node": from_node waits, to_node is the blocker finished first. Verify with get_dependencies (depends_on = blockers, blocks = waiters). Don't over-couple.

5. Write the feature's spec, then STOP for approval

A feature ships a contract, and that contract lives in a doc node the feature references. The plan holds the how; the spec holds the what.

The procedure is its own skill — read flownix-write-spec and follow it. It owns the OpenSpec format, validate_spec, propose_doc_delta and the approval gate. It is not repeated here on purpose: the format used to be restated in three skills, and three copies drift.

Two things this step must not get wrong:

• The OpenSpec format is the only accepted way to record behaviour. ## Purpose, ### Requirement: <name> with a RFC 2119 keyword, #### Scenario: with GIVEN/WHEN/THEN. Freeform prose in a doc node is a defect, not a style choice.
• When the project has require_proposal_approval on (get_project_policy), planning ends at the proposal. Propose the delta, tell the user it is waiting for approve_doc_delta, and do not move any task of this feature into in_progress until list_doc_deltas shows review_status: approved. The server refuses those transitions anyway — but a plan that walks into the refusal wastes the user's turn instead of handing them the decision.

With spec_first: false — that is, in this skill's mode — decomposing the tree (steps 2–4) is fine before approval: it is the implementation that waits, not the planning. What must not happen is code, or a task claimed as started, on a contract nobody agreed to.

That sentence is about this mode only, and it used to be written as a general rule. It is not one: with spec_first on, decomposing before approval is exactly what is forbidden, and the server enforces it. If you got here without reading step 0, go back and read it.

6. Record the plan as memory

• add_comment on the plan/feature with [plan]: the decomposition rationale, trade-offs, what you deliberately deferred, and which components you bound to and why.
• Leave new nodes in backlog — planning records intent; execute-task moves them forward.

7. Write so the plan can be found later

Content and comments are indexed for semantic search. Name the subject explicitly in the title and first paragraph, use the domain words a future searcher would use (including alternatives you rejected), and record the why as a [decision] comment. Indexing is automatic and eventually consistent — never verify your own write with rag_query, use get_node.