Your first project

Walk this page once, all the way through. By the end you'll have a project with a tree of tasks, one completed task, and a trail of work from which the next agent — or you, a month later — can recover the context without asking anyone.

Everything below is a real command. Skills are invoked as Claude Code slash commands: /skill-name, with an argument on the same line where one is needed.

Assumed done already:

• MCP connected — claude mcp list shows flownix;
• skills installed — the skill directories are in ~/.claude/skills/ and Claude Code has been restarted.

Step 1. Create the project

Go to the directory with your code (an empty one is fine) and run:

/flownix-init

What happens, step by step:

1. The agent looks for a .flownix file next to it; if there is none, it moves on.
2. list_organizations — shows your organizations or offers to create one (create_organization).
3. list_projects — the same for projects. A new one goes through create_project, and you pick the project key: two or three uppercase letters that task slugs are built from. Key AF gives AF-TASK-1; key SHOP gives SHOP-TASK-1.
4. It writes .flownix into the current directory.

spec_mode: "off"
org:
  id: "62c39018-..."
  name: "Mementai"
project:
  id: "d13b9da0-..."
  name: "My product"
  key: "AF"
  spec: |
    ## Goal
    ...

Every other skill reads this file on its own from here on, and you never type identifiers by hand again.

The agent then asks three questions: turn on strict spec mode, build a spec from the existing code (/bootstrap-spec), set up an agent council. On a first project answer "no" to all three — you can come back to any of them later.

Step 2. Describe the intent

The intent, not the task. Breaking it into tasks is the agent's job, and doing it for the agent throws away its strong side.

/plan-feature Magic-link sign-in: an email with a link instead of a password,
the link lives 15 minutes, one link means one sign-in.

What happens, step by step:

1. Search first, create second. rag_query on the meaning of your phrasing and rag_context on the domain area. If something similar was already planned, the agent finds it and offers to extend it rather than create a second copy. An empty result isn't proof of absence — it checks rag_status.
2. Top-down decomposition via create_node: feature → plan → task. An epic is created only for a genuinely large body of work; an extra level helps no one.
3. The spec as its own document — create_doc_node: what the product becomes after this feature, not what needs doing. Each task is linked to it with set_references.
4. Dependencies — add_dependency. Read it as a sentence: "from depends on to", meaning to is the blocker and goes first.
5. Tags (add_tag) and, if the system is mapped into components, set_node_components.

The agent finishes by naming the slugs it created — roughly like this:

AF-FEAT-1  — Magic-link sign-in
  AF-PLAN-1  — Implementing one-time links
    AF-TASK-1  — Token model and migration
    AF-TASK-2  — Issue a link and send the email   (depends on AF-TASK-1)
    AF-TASK-3  — Exchange a link for a session     (depends on AF-TASK-1)
AF-DOC-1   — Spec: sign-in by link

Step 3. Look at what came out

Open the project in the web app: the tree on the left, the graph on the right — dependencies and links visible at a glance. This is where you fix what you disagree with; it's your half of the work and it can't be delegated.

Worth checking before any code is written:

• Are the tasks genuinely self-contained? A task you can't finish in one sitting is a plan, not a task.
• Do the dependencies reflect the real order? A spurious dependency stalls work for nothing.
• Does the spec describe the outcome rather than retell the task list?

You can fix things in words, without leaving the session:

AF-TASK-2 is too big — split it in two and move the dependency

Step 4. Do the first task

/execute-task AF-TASK-1

What happens, step by step:

1. get_node(slug: "AF-TASK-1") — the description and every comment: that's where earlier decisions live.
2. get_dependencies — if a blocker is still open, the agent doesn't start; it says so.
3. rag_context — the surrounding context: similar tasks, recorded decisions, neighbouring modules.
4. update_node_status(status: "in_progress") — the board shows what it is busy with.
5. The work itself, with add_comment along the way: [progress] what was done, [decision] why this way, [blocker] what is in the way.
6. update_node_status(status: "testing") with the commit hash and a [done] comment on how to verify it.

The task stops at testing rather than done on purpose: doing and verifying are separate roles. Who moves it on — you or a separate verification pass — is step 6.

This trail is not paperwork. The ticket works as the agent's memory: between sessions an agent remembers nothing, and anything not written into the node is lost. Hence the rule the product rests on: a decision that isn't in the ticket wasn't made.

Step 5. See what's left behind

Open AF-TASK-1 in the web app. It has:

• the status — what is actually happening, not "in progress" for months;
• the comments [progress], [decision], [done] — the course of work and the decisions taken;
• the commit hash — the link to the code;
• the progress of AF-PLAN-1, recomputed on its own from the statuses inside it.

The next agent, picking up AF-TASK-2, reads all of this and doesn't start from scratch.

Step 6. Close the task

A task in testing is waiting to be verified. You can verify it yourself, or hand it to a second pass — an agent that didn't write this code:

/review-work AF-TASK-1

What happens, step by step:

1. The agent reads the acceptance criteria from the task description and the executor's comments.
2. It pulls recorded decisions for the affected subsystem with rag_query: a change that contradicts someone's [decision] is a finding, not a detail.
3. It walks the criteria one by one, not "looks fine overall".
4. It records the outcome as a [review] comment and routes the task: to done if the criteria hold, or back to regression with a list of what doesn't.
5. If the work warrants it, it creates a document (create_doc_node) and links it to the feature and the tasks with set_references.

When AF-TASK-1 moves to done, the progress of AF-PLAN-1 recomputes itself.

What's next

• Plan a feature — what you just did, in detail.
• Execute a task — statuses, the trail, when to close.
• Strict mode — when documentation has to change with the code.
• You already have a repository — starting from something.
• Cases — what this looks like in concrete situations.