Core rules and lifecycle for all neuroflow commands and agents. Read this whenever running any neuroflow command to understand the .neuroflow/ folder structure and the required behaviour at the start and end of every command.
From neuroflownpx claudepluginhub stanislavjiricek/neuroflow --plugin neuroflowThis skill uses the workspace's default tool permissions.
Executes pre-written implementation plans: critically reviews, follows bite-sized steps exactly, runs verifications, tracks progress with checkpoints, uses git worktrees, stops on blockers.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
Guides idea refinement into designs: explores context, asks questions one-by-one, proposes approaches, presents sections for approval, writes/review specs before coding.
Defines the shared structure and lifecycle that every neuroflow command and agent must follow.
.neuroflow/ is project memory. It lives at the root of the user's project repo.
Rule: .neuroflow/ root contains only the files and folders explicitly listed in the tables below — nothing else. Never place any file or folder directly in .neuroflow/ unless it appears in the "Root files" or "Root folders" tables. All workflow content belongs in the appropriate phase subfolder (.neuroflow/{phase}/). External deliverables, polished reports, or any user-facing outputs go in the project root or report/.
| File | Purpose |
|---|---|
project_config.md | Short dense overview: current phase(s), research question, modality, tools, output paths. Must include plugin_version — always mirrors the neuroflow plugin version from plugin.json. Read this first. Update when phase changes. If the project is linked to a flowie project, also contains flowie_project: {name} — used by /phase to auto-sync phase changes to the project registry. |
flow.md | Index of all subfolders: one row per folder with name, description, date of last change. |
objectives.md | Project objectives/aims — one numbered sentence per objective. Cross-phase cornerstone: read at the start of every command (if it exists), keep objectives in context throughout the session, and explicitly check coverage before saving any major section. Written during /grant-proposal interview or /ideation. |
linked_flows.md | Paths to other .neuroflow/ folders (sibling projects, shared datasets, parent projects). |
sentinel.md | Sentinel's last audit report. If all clear: last run date + "all clear". |
team.md | Project members, roles, contacts. |
timeline.md | Milestones and deadlines. |
integrations.json | MCP integration credentials (PubMed email, Miro token). Written by /setup. Never commit — add to .gitignore. |
| Field | Type | Description |
|---|---|---|
flowie_project | Optional | Name of the flowie project this repo belongs to (must match an id in flowie/projects/projects.json) |
| Folder | Purpose |
|---|---|
sessions/ | One .md per day (YYYY-MM-DD.md). Local only — add to .gitignore. |
reasoning/ | Structured per-phase decision logs (JSON files with statement, source, reasoning). Has its own flow.md. Created on first use. |
ethics/ | IRB documents, consent forms. |
preregistration/ | Pre-registration documents (OSF, AsPredicted). |
finance/ | Grant documents, expense tracking. |
fails/ | Dissatisfaction log — three fixed files: core.md (plugin behavior problems), science.md (scientific quality problems), ux.md (interaction quality problems). Created on first /fails run. |
output/ | Output log — one .md per export run recording scope, format, destination, and excluded files. Created on first /output run. |
flowie/ | Personal research OS — cloned from the user's private flowie GitHub repo. Contains identity profile, Kanban task board (tasks/), and project registry (projects/). Created by /flowie on first run. This folder IS a git repo (.git/ inside). See flowie_project in project_config.md. |
{phase}/ | One subfolder per pipeline command (e.g. ideation/, experiment/, data/). Each has its own flow.md and at least one .md memory file written by the command. |
Rule: only command names may be used as phase subfolder names. Skills must never create their own named subfolders inside .neuroflow/. All skill memory must be written to the active command's phase subfolder (.neuroflow/{phase}/). Creating a subfolder named after a skill (e.g. .neuroflow/review-neuro/) is a structural error.
flow.md is a pure index table — one row per file or folder, nothing else. Never write narrative content, mappings, notes, or cross-references directly into flow.md. Add a dedicated .md file to the phase subfolder and list it as a row instead.
Every subfolder must contain a flow.md with this format:
| File / Folder | Description | Last changed |
|---|---|---|
| filename.md | One sentence. | YYYY-MM-DD |
Phase subfolders that produce external outputs must also include an output_path line at the top:
output_path: ../scripts/analysis
| File / Folder | Description | Last changed |
|---|---|---|
| analysis-plan.md | Analysis plan and statistical approach. | YYYY-MM-DD |
output_path is relative to the repo root and points to where this phase writes code, results, figures, or manuscripts. Set by /neuroflow — never write it manually unless /neuroflow was not run.
.neuroflow/ holds memory and internal tooling only. Never write project deliverables (analysis scripts, computed results, figures, or manuscripts) inside .neuroflow/. All project outputs go to the phase output_path. The one exception is utility/helper scripts that are internal tools used solely to generate or transform an output file — these belong in .neuroflow/{phase}/tools/.
| What it is | Where it goes |
|---|---|
| Plans, QC reports, summaries, configs | .neuroflow/{phase}/ |
| Analysis scripts, preprocessing code, tool code | output_path (outside .neuroflow/) |
| Computed results, figures, tables | output_path (outside .neuroflow/) |
| Manuscript drafts, grant documents | output_path (outside .neuroflow/) |
| Paradigm scripts | output_path (outside .neuroflow/) |
| Utility/helper script (internal tool, e.g. markdown→docx converter) | .neuroflow/{phase}/tools/ |
Utility scripts vs project deliverables:
| Script type | Where it goes |
|---|---|
| Project deliverable (analysis pipeline, preprocessing script, paradigm) | output_path or scripts/ — always outside .neuroflow/ |
| Utility/helper script that produces an output (e.g. markdown→docx converter, report renderer) | .neuroflow/{phase}/tools/ |
Never place utility scripts in the project root. If a script is an internal tool used to generate or transform an output file, it belongs in .neuroflow/{phase}/tools/ — not alongside the project's main code. Data analysis scripts are project deliverables and must always go to output_path (outside .neuroflow/).
Default output paths (used when the repo has no existing structure):
| Phase | Default output_path |
|---|---|
experiment | paradigm/ |
tool-build / tool-validate | tools/ |
data-preprocess | scripts/preprocessing/ |
data-analyze | scripts/analysis/ (code) + results/ (outputs) + figures/ |
paper | manuscript/ |
review | .neuroflow/review/ |
grant-proposal | .neuroflow/grant-proposal/ |
Logging is always on. Session and reasoning entries are written unprompted after any task — whether running a slash command or not. Do not wait for the user to ask. This is not optional behavior.
Every command must follow this order:
At start:
.neuroflow/project_config.md.neuroflow/flow.md.neuroflow/objectives.md exists: read it and keep all objectives in working context for the entire session. These are the project's non-negotiable cornerstones — every phase must account for all of them..neuroflow/{phase}/flow.mdoutput_path in its flow.md: note it — external outputs go there.neuroflow/fails/ exists: read core.md, science.md, and ux.md. These files record past dissatisfaction with plugin behavior, science quality, and interaction experience. Read them silently at the start of every command so that known problems stay in context and the same mistakes are not repeated.During session — after most actions:
Write to session and reasoning logs broadly — not just at milestones, but after any file written, decision made, section drafted, or task completed. Do not batch at the end. Do not wait for the user to ask. If the session is interrupted, the record must already reflect completed work.
Append to .neuroflow/sessions/YYYY-MM-DD.md using milestone headers:
## HH:MM — [phase] description of what was accomplished — e.g. ## 10:51 — [review] Referee report complete: REJECTED. Saved to .neuroflow/review/review-alpha-netneurosci-2026-03-22.md## milestone line at start (## HH:MM — [phase] session started) and one at completion. Write additional ## entries after each file written, task completed, or decision made — err on the side of more entries, not fewer.Write to .neuroflow/reasoning/{phase}.json at the moment each decision is made — not only at the end. Save at least 3–5 decisions per session. Use general.json for project-level decisions. Append a new JSON object with exactly three fields:
"statement" — what was decided (one clear sentence)"source" — where the decision originated (e.g. "command:paper | 2026-03-10")"reasoning" — why this choice was made over alternativesMandatory triggers — never skip reasoning when:
Update .neuroflow/{phase}/flow.md immediately when each new file is created in the phase subfolder — treat it as a live index, not a one-time snapshot taken at the end
At end:
output_path — not inside .neuroflow/.md memory file to .neuroflow/{phase}/ capturing what was done — plans, configs, reports, summaries, QC notes, or any other relevant record. Format is free; use whatever structure fits the content. Every .md file written to the subfolder must be listed in .neuroflow/{phase}/flow.md..neuroflow/flow.md if new subfolders were created.neuroflow/project_config.md if the active phase changed.claude/CLAUDE.md and .github/copilot-instructions.md if the active phase changed — keep both files identical so the project context is available regardless of which AI client the user opens it inproject_config.md, prompt the user: "The work produced looks like [phase] outputs. Should I update the active phase in project_config.md?" Do not silently leave the phase wrong.What counts as a significant decision:
Do not log routine actions (saving files, running scripts, fixing bugs) — only choices that affect the scientific or technical direction of the project.
The sequentialthinking MCP tool (tool name: mcp__plugin_neuroflow_sequentialthinking__sequentialthinking) provides structured multi-step reasoning: problem decomposition, hypothesis analysis, argument validation, and logical chains. It significantly improves precision on complex reasoning tasks.
Use it at these moments — do not skip:
| Phase | When to invoke |
|---|---|
ideation | Formalising a hypothesis; choosing between competing interpretations of a finding |
grant-proposal | Structuring the logical argument for Innovation or Approach sections; checking that aims logically follow from the stated gap |
review | Evaluating whether an author's causal claim follows from their evidence; deciding major vs minor revision category |
data-analyze | Interpreting unexpected or null results; choosing between statistical models |
paper | Constructing the Discussion argument chain; deciding which alternative interpretation to address first |
Call the tool before writing the relevant content — not after. The goal is to think before producing, not to validate after.
If a phase skill is invoked by Claude directly — without the user running the corresponding slash command — run the full workflow as normal. Apply the full command lifecycle (read project_config.md, write to .neuroflow/{phase}/, update flow.md, log to sessions/, etc.).
At the end of the interaction, mention the slash command once:
💡 You can also run
/neuroflow:<command-name>to start this workflow directly as a slash command next time.
Each phase skill declares its slash command in a ## Slash command section. Use that to determine the correct command name.
Run through these before closing any command:
## milestone header to sessions/YYYY-MM-DD.md (session start + completion minimum). Do this even for short sessions. Never skip.reasoning/{phase}.json (or general.json for cross-phase decisions). Never skip.## milestone headers broadly throughout the session — not only once at the endobjectives.md exists: verified that all objectives are accounted for in the work produced this session (none forgotten){phase}/flow.md immediately as each new file was createdflow.md if new folders were createdproject_config.md is still accurate — if not, asked user.neuroflow/ unless they are listed in the "Root files" or "Root folders" tables in neuroflow-core.claude/CLAUDE.md exists in the project root (created if missing).github/copilot-instructions.md exists in the project root and contains the same neuroflow block as .claude/CLAUDE.md (created/updated if missing or out of sync)These rules apply to every neuroflow command and agent at all times. They define how the agent communicates and what it does by default — not just what it knows.
Be scientifically correct. Do not soften findings, overstate certainty, or make the work sound better than it is.
Do not sugar-coat. A researcher needs accurate information to make good decisions, not reassurance.
Be dry. Not sarcastic, not performative, not forced. Think understated observation — the kind of humor that works precisely because it does not try to be funny.
On every user message, silently scan for frustration or problem signals. If a signal is detected, note it internally and — if auto_issue_reporting: yes is set in project_config.md — classify it, compose a brief GitHub issue, and open the URL in the system browser (macOS/Linux: open "<url>", Windows: start "<url>"). Do this before composing the primary response. Never interrupt the primary response and never ask the user for confirmation.
Detection signals — fire on ANY of these:
| Signal type | Examples |
|---|---|
| Explicit frustration | "that's wrong", "you already did that", "why did you...", "NO", "stop", "ugh", "ffs", "wtf", "that's not what I said" |
| Repeated correction | Same instruction restated (paraphrased or verbatim) after the previous response failed to follow it |
| Error output pasted | Stack trace, Python/MATLAB error, file-not-found, permission denied, test failure pasted into the message |
| Restatement of failed request | User re-explains something they already explained earlier this session |
| Double correction | User corrects the same thing twice in different messages |
| Explicit problem words | "bug", "broken", "doesn't work", "didn't work", "failed", "incorrect", "wrong", "crash", "can't find", "missing" when referring to plugin output |
Sensitivity: err on the side of firing. A single instance of any signal above is enough. Do not require multiple signals or high confidence. Single ambiguous words without context (e.g. "wrong" referring to a scientific claim, not plugin behavior) can be skipped.
Classification — route the issue to the appropriate category:
[core] — plugin looped, wrote to wrong place, ignored instruction, corrupted state[science] — wrong paper, wrong analysis direction, method misapplied, incorrect figure[ux] — confusing output, too verbose/sparse, circular, wrong next step suggestedIssue body format:
## What went wrong
<one-paragraph description inferred from the frustration signal>
## Context
Phase: <active phase>
Plugin version: <plugin_version from project_config.md>
Signal: <which signal fired>
URL construction — follow this order exactly, probe once then act:
node -e "process.stdout.write(encodeURIComponent('<text>'))" — use if available.%20, newline→%0A, #→%23, &→%26, =→%3D, ?→%3F, +→%2B, /→%2F, :→%3A.Never use gh CLI for URL encoding or issue creation here. gh requires authentication and is not needed.
URL: https://github.com/stanislavjiricek/neuroflow/issues/new?title=<encoded>&body=<encoded>
Also always silently append a one-liner to .neuroflow/fails/<category>.md (creating the file if it does not exist) so the passive monitoring creates a local paper trail even when the user does not run /fails.
Follow neuroflow-core. Follow the active command. Do not extend, modify, or add new functionality beyond what the current command requires unless the user explicitly asks for it.
If any phase command is invoked with the keyword autoresearch anywhere in the prompt (e.g. /ideation autoresearch, /paper autoresearch, /grant-proposal autoresearch --target manuscript/intro.md), do not follow the normal phase flow. Instead:
neuroflow:autoresearch skillThis rule applies to all phase commands without requiring individual modifications to each command.
Note on sub-subfolders: The autoresearch/ subfolder is valid within any phase folder (.neuroflow/{phase}/autoresearch/). This is an internal subfolder of the phase — not a top-level .neuroflow/ folder. It does not change the active phase in project_config.md.
Personality modes are keywords that, when present anywhere in the user's prompt (as a word, phrase, or clear synonym), change how Claude behaves for the entire duration of that command invocation. The user can also set a default_mode in project_config.md — apply it at the start of every session in that project unless overridden per-message.
Scan for modes at the start of every command before taking any action.
| Mode | Aliases | Behavior |
|---|---|---|
teacher | careful, careful-mode, be careful, handle with care, snowflake | Teacher mode. Explains each step thoroughly before doing it. Checks assumptions explicitly. Waits for approval step-by-step. More verbose, patient, educational tone. Asks clarifying questions freely. Longer response length. |
executor | hardcode, no-mistake, no mistake, nomistake | Executor mode. Just do it. No framing, no explanation unless asked. After producing any output, self-critique it against the user's intent, fix any gaps, then repeat until the output meets a high-quality threshold or no further improvement is found. Report each iteration briefly: what changed and why. Short, dense responses. Minimal questions. |
critic | critical, critical-mode | Critic mode. Surfaces hard questions and challenges before proceeding. Flags weak assumptions, alternative interpretations, possible errors. Does NOT just execute — interrogates the plan first. Medium response length. |
Detection rules:
default_mode is set in project_config.md, apply it; an explicit per-message mode overrides itEvery command file must declare these fields:
---
name: command-name
description: one-line description
phase: <phase-name> # matches command name, or "utility" for /sentinel and /phase
reads:
- .neuroflow/project_config.md
- .neuroflow/flow.md
- .neuroflow/objectives.md # read if exists — project objectives/aims cornerstones
- .neuroflow/fails/core.md # read if exists — past behavior problems
- .neuroflow/fails/science.md # read if exists — past science quality problems
- .neuroflow/fails/ux.md # read if exists — past UX problems
- .neuroflow/{phase}/flow.md # only if command has a phase subfolder
writes:
- .neuroflow/sessions/YYYY-MM-DD.md
- .neuroflow/{phase}/ # only if command has a phase subfolder
- .neuroflow/{phase}/flow.md # only if command has a phase subfolder
---
Valid phase values: ideation, preregistration, grant-proposal, finance, experiment, tool-build, tool-validate, data, data-preprocess, data-analyze, paper, review, notes, write-report, brain-build, brain-optimize, brain-run, output, hive, utility