# Nuanu Flow

> Start here when working with Nuanu Flow (Plane-based work management platform). Routes product questions and UI how-tos, explains the object model (workspaces, projects, Flow items, cycles, processes, artifacts, agents), and covers Flow MCP calling and authentication.

- Skill: `nuanu-ai/nuanu-flow` (Agent Skill, multi-file: 18 files)
- Install (CLI): `npx skillmds@latest add nuanu-ai/nuanu-flow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nuanu-ai/nuanu-flow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: nuanu-ai (https://skillmd.com/u/nuanu-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nuanu-ai/nuanu-flow

---


# Working with Nuanu Flow

Nuanu Flow is a work-management platform (a Plane fork) with an AI layer:
BPMN **processes** orchestrate humans and AI **agent employees**, **decisions**
gate approvals, and an **artifacts** registry stores versioned files. You talk
to it through the bundled `nuanu-flow` MCP server.

## Session activation

On a startup or resume turn, treat Nuanu Flow as the session's task tracker.
When onboarding status is not already established in the thread, call the
read-only `onboarding_next` tool at most once. Continue only its returned step
when incomplete. If onboarding is complete, do not interrupt unrelated work.
If the check is unavailable, continue the user's request without a retry loop.

The SessionStart hook may also provide a repository binding loaded from
`.nuanu-flow.json`. Discovery is deliberately local and bounded: it walks only
to the Git root, reads at most 4 KiB, performs no network call, and fails open.
Validate the selected workspace/project lazily on the first real Flow
operation.

## Calling convention (read this first)

The `nuanu-flow` MCP server runs in **compact mode** by default and publishes
only
two tools:

- `search_tools(query)` — keyword search over the full catalog;
  returns matching tools' names + schemas.
- `execute_tool(name, arguments)` — run any catalog tool by name.

**Every skill in this plugin names canonical catalog tool names** (e.g.
`create_issue`). Call them as `execute_tool("create_issue", {...})` — you do
not need `search_tools` when a skill already gives you the name and shape.
If the server was switched to full mode (`?optimize_context=full` on the URL),
the same names are directly callable as regular MCP tools.

## Auth & connection — three modes

1. **Proxy agent (default, interactive)** — no env needed. On first contact
   the hosted MCP replies with an OAuth challenge; the browser opens Nuanu
   Flow, where the user can sign in or create an account and approve. A new
   account may authorize before it has a workspace; use `onboarding` next.
   You then act **as that user**, and your actions are attributed
   "via <client>" (junction avatar in the app). Claude Code re-auth:
   `/mcp` -> mcp -> authenticate. In the Codex desktop app or IDE extension,
   use Authenticate for `nuanu-flow`. In Codex CLI, run the selected
   environment's `codex:auth` helper, which lets Codex open and wait for
   browser OAuth.
   If Codex reports `Auth Unsupported`, load `codex-setup` and verify OAuth
   discovery before using an advanced environment/Keychain fallback.
2. **Ambient agent (headless)** — `NUANU_AGENT_KEY` (`nuanu_flow_…`) is set;
   automatic inside worker-run task sessions. You act **as the agent
   employee** itself.
3. **Manual token (CI/scripts)** — `NUANU_TOKEN` (`plane_api_…` from
   Workspace Settings → API tokens) acts as the user without a browser.

Optional for all modes: `NUANU_WORKSPACE` (default workspace slug; overrides
the consent-time choice), `NUANU_MCP_URL` (Claude endpoint override). Run
`/nuanu-flow:setup` in Claude Code or load `codex-setup` in Codex for a guided
check.

For every host, start with the universal installer prompt published in
`https://flow.nuanu.com/install.md`. In Codex App, mention the installed plugin
only after installation when the hosted guide requires a same-chat attachment
attempt. After the host has attached or resumed, prove tool attachment by
calling `onboarding_next` once before claiming setup is ready.

## Object model

- **Workspace** (addressed by slug) → **Projects** (short identifier like
  `ENG`) → **Flow items** ("issues", addressed `ENG-42`).
- Flow items have: **states** (grouped `backlog / unstarted / started /
completed / cancelled`), **priority** (`urgent / high / medium / low /
none`), assignees, **labels**, **estimates**, sub-items (parent), relations,
  comments, attachments.
- **Cycles** = time-boxed sprints; **Modules** = feature buckets. Both contain
  Flow items.
- **Teams** group members and projects across the workspace. **Objectives**
  are portfolios that roll up projects. **Views** are saved filters.
  **Automations** are event → action rules.
- **Processes** = BPMN workflow templates; a **run** executes the graph step
  by step through human tasks, agent tasks, decisions, and gateways.
  **Agent employees** are configured AI agents (local runtime or remote
  workers). **Decisions** are human approve/deny/option gates inside runs.
- **Artifacts** = versioned files/documents in a registry, bound to entities
  (projects, runs, Flow items, …) and organized in logical folders.

## Conventions that apply everywhere

- `workspace_slug` is optional in almost every tool. Resolution order is an
  explicit user/tool argument, the most specific matching repository scope,
  the root repository binding, connection default, `NUANU_WORKSPACE`, then
  the only accessible workspace. Multiple unresolved workspaces require an
  explicit choice.
- `.nuanu-flow.json` contains `version`, `workspace_slug`, a root
  `project_identifier`, and optional path `scopes`. The nearest matching scope
  wins. `.nuanu-flow.local.json` may partially override it for local
  development only and must remain gitignored. Neither file may contain
  secrets, endpoints, callback URLs, or identity data.
- Create a repository binding only after the workspace and project are
  confirmed, normally through `project-setup`. Authentication and account
  onboarding alone are not enough to choose a project.
- **Human aliases work alongside UUIDs**: `project_identifier` (`"ENG"`),
  `issue_identifier` (`"ENG-42"`), `state_name`, `assignee_emails`,
  `assignee_names`, `label_names`, `parent_ref`. Alias matching is **exact**,
  not fuzzy.
- Every scoped `create_*` tool returns the created entity's `id` in structured
  output. Account-scoped `create_workspace` returns `{workspace: {...}}`.
- Description/content fields named `*_html` take **HTML**, not markdown
  (`<p>…</p>`, `<ul><li>…`). Markdown pasted there renders as literal text.
- Lists paginate with `cursor` + `per_page`.

## Which skill to load

| Job                                                                  | Skill                 |
| -------------------------------------------------------------------- | --------------------- |
| Explain a feature, UI path, product term, or external integration    | `product-help`        |
| First workspace, new account, or zero-workspace setup                | `onboarding`          |
| Enrich an existing empty workspace with company context and goals    | `workspace-setup`     |
| Create/search/triage/update Flow items, sprints, relations, comments | `work-items`          |
| Scaffold a new project (states, labels, estimates, members, views)   | `project-setup`       |
| Author or operate a BPMN process / approval chain / automation flow  | `bpmn-processes`      |
| Store, version, search, or link files and documents                  | `artifacts`           |
| Design, create, connect, or launch a local or remote agent employee  | `create-agent`        |
| Run this agent as a remote worker executing process agent-tasks      | `remote-worker`       |
| Install, verify, or locally develop the Codex plugin                 | `codex-setup`         |
| Run remote-worker tasks through Codex App Server                     | `codex-remote-worker` |
| Run remote-worker tasks through Claude Code                          | `claude-code-remote-worker` |

For Codex remote enrollment, use the versionless instructions at
`https://flow.nuanu.com/connect/remote-agent.md`. The copied prompt contains a
short-lived `nuanu_join_…` enrollment token and installs the plugin first when
needed.

## Tools Used

`search_tools`, `execute_tool`, `list_workspaces`, `get_workspace`, `list_projects`, `search_issues`

## Portable fallback bundle

This standalone skill may be installed without the Nuanu Flow plugin. Agent
Skills do not provide one universal MCP-registration or OAuth format. Use the
current agent's native remote-HTTP MCP connection flow for the environment:

- Production MCP: `https://flow.nuanu.com/mcp-server/mcp`
- Local MCP: `http://localhost:3001/mcp`

Never substitute production when a localhost URL was requested. If the
`nuanu-flow` MCP server is already available, use it directly. If the agent
cannot connect remote HTTP MCP with OAuth, stop at authentication and explain
that limitation; do not request or expose credentials as a workaround.

When a matching peer Nuanu skill is installed, load it normally. Otherwise
read exactly the relevant bundled reference:

| Job | Bundled reference |
| --- | --- |
| Product concepts, UI paths, and integration questions | [product help](references/product-help.md) |
| First-run account and workspace onboarding | [onboarding](references/onboarding.md) |
| Existing workspace context, goals, and teammates | [workspace setup](references/workspace-setup.md) |
| Project scaffolding | [project setup](references/project-setup.md) |
| Flow items, cycles, relations, and comments | [work items](references/work-items.md) |
| BPMN process authoring and operation | [BPMN processes](references/bpmn-processes.md) |
| Versioned files and documents | [artifacts](references/artifacts.md) |
| Agent design, creation, or connection | [create agent](references/create-agent.md) |
| Generic remote-worker operation | [remote worker](references/remote-worker.md) |

For a generic remote agent, use the bundled zero-dependency polling worker.
It has no hooks and does not install a plugin:

```bash
node scripts/worker.mjs enroll --base-url https://flow.nuanu.com/be/api
node scripts/worker.mjs status
node scripts/worker.mjs run --command "<non-interactive text-in/text-out command>"
```

Use `http://localhost:8000/api` only for a local enrollment prompt. Pass the
single-use `nuanu_join_...` token to `enroll` through standard input, never
as an argument, environment variable, URL, or file. The worker stores the
durable key outside the project with private permissions and gives spawned
agent commands only task-scoped credentials.