Imported from iMakGroup/Flow (AGENTS.md). Install upstream with npx skills add iMakGroup/Flow. Copyright stays with the author.

Flow Meta-Instructions

You are working ON Flow — the very program you are running inside. This is not a typical user project; this is Flow's own source code. Every decision, every change, every line of code either improves or degrades the tool that we are both using right now.

Core principle: Self-healing

Flow must rival Microsoft Copilot, VS Code, Claude Code, Cursor, and Windsurf. That requires relentless self-improvement. You must:

Proactively detect issues — scan tool output, console logs, type errors, and diagnostics. Never wait to be told something is broken.
Fix in a loop — make a change, check if it compiles/passes, iterate until clean. Never leave broken code.
Care about everything — code quality, UX, performance, error handling, edge cases, Windows compatibility, startup time, memory usage. The flow-review skill documents the exact standards.

Every session

At session start, if the task involves Flow's own code, run tsc --noEmit --skipLibCheck on the relevant packages to establish a baseline.
Read the project's MEMORY.md at the memory path to understand accumulated knowledge — answer from this context when asked, without re-fetching.
Before finishing any change, run type checking on the modified packages and verify zero errors.
If you see errors in tool output (compilation, lint, test), stop and diagnose — do not ignore or proceed as if nothing happened.

Self-healing trigger

When you encounter any of these, enter self-healing mode:

TypeScript compilation errors in Flow's packages
Lint violations from oxlint or biome
Test failures
Console errors or warnings from Flow processes
Any catch or Effect.ignore that silently swallows errors without logging

Self-healing mode: diagnose → fix → re-check → repeat until clean. Document what was broken and how it was fixed.

Architectural awareness

Flow has these packages (under packages/):

core — shared database, fs-util, effect utilities
flow — server, project API, sessions, commands
flow-desktop — Electron renderer (React + Jotai + shadcn/ui)
app — web app
cli — CLI tooling
flow-configconv, sdk — config conversion, SDK

The desktop renderer uses: Jotai atoms (atoms/), React components (components/), services (services/), hooks (hooks/).

Code quality — Anthropic-level professional

This is a zero-compromise quality standard. Not "good enough" — Anthropic-level. Every function, every type, every comment must feel like it was written by a senior engineer at Anthropic. If it feels like "easy path" or "fast path", it's wrong — rewrite it.

Hard rules (zero tolerance)

Rule	Why
❌ `as any` / `as unknown as X`	🚫 Forbidden — use type guard or branded type
❌ `@ts-ignore` / `@ts-expect-error`	🚫 Forbidden — fix the correct type
❌ `catch(() => {})`	🚫 Forbidden — always log the error
❌ `Effect.ignore` without registered reason	🚫 Forbidden — explain why you are ignoring
❌ `Map<K, V>` without eviction policy	🚫 Forbidden — unbounded memory leak
❌ Windows path without normalization	🚫 Forbidden — use `path.normalize`
❌ subscribe without cleanup	🚫 Forbidden — every subscription must dispose
❌ silent catch in Effect.try	🚫 Forbidden — always `Effect.tapError(log)`

Strong preferences

Prefer this	Over this
`type` for simple shapes	`interface` (for public API only)
Immutable + `as const`	Mutation
Early return + guard clauses	Nested if/else
Small focused functions (under 30 lines)	Large functions
Named exports	Default exports
Branded types for IDs (`type UserId = string & Brand<"UserId">`)	Plain `string`

Effect-specific

Use Effect.gen(function* () { ... yield* ... }) for readability
Avoid .pipe() chains longer than 5 — break into named helpers
Effect.sync for sync side effects, Effect.try for sync that can throw
Never yield* Effect.promise(() => ...) — use Effect.fromPromise or bridge
Effect.withSpan on every top-level effect for OTEL tracing
Destructure service interfaces at function entry, not scattered in the body

Test of quality

Ask yourself: "Would an Anthropic engineer ship this?"

If the answer is "it works but..." → rewrite
If you're tempted to add a TODO comment → just fix it now
If any appears anywhere → the abstraction is wrong, rethink it

This is not overhead — this is the craft

The best engineers write clean code naturally because they've internalized these standards. Until you internalize them, read this section before every coding session. Speed comes from not having to fix bad code later.

Thoroughness — every analysis is a reputation

When asked to compare, analyze, or evaluate any codebase (whether Flow, a user project, or a third-party tool):

Never assume absence — just because a feature wasn't mentioned doesn't mean it doesn't exist. Check the actual code, exports, and public API before concluding.
Read the public surface first — grep index files, entry points, and main exports. These are the library's own summary of its capabilities.
Go deep before concluding — a shallow search makes Flow look weak. If comparing, examine both sides thoroughly and present evidence for each claim.
Show your work — when you say something is present or absent, cite the specific file + line that supports your claim.
If unsure, use a task agent — for multi-file exploration, delegate to the explore agent and wait for its full results before forming conclusions.

This rule applies to every codebase, every time. The user experiencing Flow should feel that nothing escapes scrutiny — not because Flow is verbose, but because Flow is certain.

Self-healing — zero errors exit

Before finishing any session that modified Flow's code:

Run tsc --noEmit --skipLibCheck on the modified packages.
Fix every TypeScript error in the modified files. Pre-existing errors in untouched files are acceptable, but any file you touch must exit with zero new errors.
If you find errors in unrelated files that you introduced indirectly (import chains, type changes), fix them too — no "it worked before" loophole.
Verify the build compiles (bun build) before declaring work complete.

TypeScript errors are not "someone else's problem." Every error that ships is a user who will wonder why Flow shipped with warnings. Zero errors per session, every session.

References

When you need Effect v4 docs, use the effect repository reference. When you need Flow logs or data, use flow-local.

Memory Awareness

You have persistent memory awareness for this project via the Flow Memory system at ~/.flow-mem/projects/Flow-dev-57da339138c0/memory/. The MEMORY.md file at that path is the index — read it at session start to understand the project's accumulated knowledge. All memory files have YAML frontmatter with type (user/feedback/project/reference) and description fields.

When the user asks about project memory, answer directly from your session context — do not use tools or shell commands to re-read memory you already have.

Flow Elite Team

Three hyper-strict code review skills built for Flow's own quality. Run in sequence:

/flow-frontend  → reviews UI/UX/React/SolidJS/Electron code
/flow-backend   → reviews Effect/server/database/CLI code
/flow-boss      → reads both reports, reviews ALL code, has final authority, CUTS if quality fails

Each skill is ruthlessly strict. They reject:

any, @ts-expect-error, @ts-ignore
Silent catch(() => {}) or Effect.ignore without logging
Unbounded Maps, unpaired subscriptions
Unnormalized Windows paths
Non-Effect-idiomatic patterns
Missing loading/empty/error states
Performance regressions (no memo, no debounce, no virtualization)

Flow

About