Flownix Init

Set up your working context: find or create an organization, pick or create a project, write the .flownix config file to the working directory, and return the org_id and project_id that every other Flownix skill needs. This skill is the entry point when you don't yet know which project you're working on.

The project config file

After discovering or creating the project, write a .flownix file to the current working directory. This file is the single source of truth for project context — all other Flownix skills read it instead of asking the user for IDs.

# .flownix — auto-generated by flownix-init
spec_mode: "strict"
spec_first: false
org:
  id: "62c39018-..."
  name: "Mementai"
project:
  id: "d13b9da0-..."
  name: "Flownix"
  key: "AF"
  spec: |
    ## Goal
    Build an AI agent planning system...

File format

• YAML for human readability.
• Top-level keys: spec_mode, spec_first, org and project.
• spec_mode — the selected project's policy, exactly off or strict.
• spec_first — whether the project works document-first (see Q1b). Written so an agent knows the order of work before its first call, not after its first refusal.
• org.id and org.name — organization identifiers.
• project.id — the project UUID.
• project.name — human-readable project name.
• project.key — short uppercase slug used as prefix in node IDs (e.g. AF-TASK-1).
• project.spec — the project's Markdown spec/description (may be multiline with |).

When to write

• First init (no config exists): write .flownix after selecting/creating the project.
• Re-init (a config already exists): read it first. If the user confirms switching projects, overwrite the file with the new project's data.
• Verify on load: if a config exists, validate it still references a real project by calling get_tree with the stored project_id. If it fails, re-run init.

Workflow

1. Check for the existing config

The product was renamed, so two names are in circulation. Look for both — a project that has not been migrated must keep working without a single edit:

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

• If exists and valid: read it, confirm the project to the user, and proceed. Optionally skip to step 4 if the user says "same project".
• If missing or invalid: proceed to step 2.

2. Discover organizations

Call list_organizations to see which orgs the current user belongs to.

list_organizations()

• If you get orgs: present them to the user and ask which one to use.
• If none exist: create a default organization:

  create_organization(name: "default")

  Then use the returned org_id.

3. Discover or create a project

Call list_projects with the chosen org_id:

list_projects(org_id: "<org_id>")

• If projects exist: present them as numbered choices. Ask the user which project to work on.

• If "create new": ask the user for:

  • name — human-readable project name (e.g. "Flownix")
  • key — short uppercase slug used as prefix in node IDs (e.g. "AF")
  • spec — brief Markdown description of the project's goal and scope

  Then create it:

  create_project(org_id: "<org_id>", name: "Flownix", key: "AF", spec: "## Goal\nBuild an AI agent planning system...")

4. Write the config file

After you have all IDs, take spec_mode from the project discovery/creation response. If that response did not include it, call get_project_policy(project_id); never guess the mode. Then write the .flownix file to the current working directory. New configs are always written under the new name; if an old .ai-flow is lying next to it, say once that it can be deleted:

Write to .flownix:
```yaml
spec_mode: "<off-or-strict>"
spec_first: <true-or-false>
org:
  id: "<org_id>"
  name: "<org_name>"
project:
  id: "<project_id>"
  name: "<project_name>"
  key: "<key>"
  spec: |
    <project spec as markdown>
```

5. Onboarding — four questions, asked once

Ask all four in one batch, each with its default shown, before confirming context. If the user answers nothing, nothing changes and nothing runs: init stays complete and valid.

Fixed order — mode → spec → components → harness. The spec comes before the harness because the stack and architecture profile harness-blueprint bakes into its roles is read from doc nodes; with no spec it has to read the whole repository instead, and takes far longer.

Q1 — strict spec mode. Show the current value (from get_project_policy, or the one you just wrote to .flownix) and what changing it means: in strict, closing a task requires either an applied spec delta (propose_doc_delta → apply_doc_delta) or an explicit declare_no_spec_impact. Default: leave as is.

If the user asks to change it:

set_project_policy({ project_id, spec_mode: "strict" })   // or "off"

Then rewrite spec_mode in .flownix with the value the server returned, not the one the user asked for. The two differ whenever the write was rejected or adjusted, and the config is read as fact by every other skill.

Q1b — spec-first: the document before the tasks. Ask this whenever Q1 leaves the project in strict. It is a normal way to run a project, not an exotic setting, and the one sentence that describes it is: tasks are created after the feature's document is accepted, not before.

Concretely, with it on: a proposed delta starts as a draft that asks nobody anything, it reaches a human only when submitted, and creating a task under a feature is refused until that feature's delta is approved. It needs spec_mode: strict and require_proposal_approval — the server refuses to enable it without them, so all three go in one call:

set_project_policy({ project_id, spec_mode: "strict",
                     require_proposal_approval: true, spec_first: true })

Default: leave as is. Say plainly what the user is signing up for: every feature will need a document a human approves before any of its work can be tracked. On a project whose existing features have no deltas, that means declare_no_spec_impact on each of them before they can be decomposed again — worth saying before, not after.

Then rewrite spec_first in .flownix with the value the server returned, same rule as spec_mode. The procedure itself lives in spec-first-change.

Q2 — bootstrap the spec. Ask when project.spec is empty or boilerplate, or list_docs returns no doc nodes. On yes, switch to bootstrap-spec in this same session. Default: no — unless Q1 turned strict mode on.

Strict mode on a project with no doc nodes blocks the very first task at the close gate. When the user enables strict and there are no docs, say that plainly and make bootstrap the default answer to Q2 rather than a polite offer.

Q3 — map the system into components. Call list_components({ project_id }). If it returns nothing, offer map-components. Default: yes on a project that already has a repository — planning and execution both require every node and doc to be bound to a component, so a project with none forces every later skill to stop and inventory the repo itself. Say that plainly rather than offering it as a nicety. On a fresh, empty repository, default to no: there is nothing to inventory yet, and the first plan-feature run will create the components it needs.

Q4 — harness. Offer to build a council with harness-blueprint. Default: no — most projects never need one. On yes, hand over to that skill.

6. Confirm context

Once the file is written, confirm to the user:

Ready. Working in project "<project_name>" (<key>) — org "<org_name>".
project_id: <project_id>
org_id: <org_id>
Config written to .flownix

All other skills will now read from .flownix automatically.

Optionally check whether the project's semantic index is usable before relying on it: rag_status({ project_id }). A brand-new project reports total_chunks: 0 — the index fills itself as nodes are created (see flownix-rag-search); there is nothing to run.

Rules

• Always check for the config first (.flownix, then .ai-flow) — don't re-discover if it's already valid.
• Always call list_organizations if there is no config or it's invalid.
• Always call list_projects before creating a project — avoid duplicates.
• Present choices to the user; don't silently pick.
• The key must be 2-5 uppercase letters (used as node ID prefix, e.g. AF-TASK-1).
• Always write .flownix after resolving org + project — this is the contract for all other skills.
• Always persist the server-returned spec_mode and spec_first; an agent must know both before work starts, not after the first refusal.
• Never commit the config to version control — add .flownix (and the older .ai-flow) to .gitignore.
• Never change spec_mode or spec_first silently. They move only on an explicit answer to Q1/Q1b — never as a side effect of init, and never because a mode "looks like the better default".
• Never start bootstrap-spec, map-components or harness-blueprint without the user agreeing to it.
• Init must finish valid even if the user declines everything in step 5 — the onboarding questions are an offer, not a prerequisite.
• Once .flownix is written, you can load flownix-basics and proceed to plan/execute.