mop-flow 0.1.8

package/AGENTS.md

@@ -0,0 +1,180 @@
+# MOP Core - Cross-Agent Instructions
+
+## Authentication Gate - First Action
+
+Before doing anything in this workspace, read `.MOP/STATE.json` and
+follow `.MOP/PROTOCOL.md`.
+
+- `initialized: false` -> output `MOP belum di-setup. Jalankan /mop-setup.` Run the setup wizard only.
+- `initialized: true` with no `activeMember` -> output `Codename dan password.` Do not continue until verified.
+- Verify credentials through `node .MOP/scripts/mop-core.mjs login --codename <codename> --password "<password>"`.
+- Wrong credentials -> output `Credentials tidak sah.`
+- After authentication, run the Agent Router before answering or acting:
+  `mop-core.mjs agent route --actor <codename> --task "<user task>"`.
+  It selects one primary role and may recommend any number of support roles
+  when genuinely needed. If no named agent exists for a needed role, ask the
+  user to name it and save it with `agent activate`.
+- Before answering an authenticated task, restore monthly memory:
+  `mop-core.mjs memory brief --actor <codename>`.
+- Every authenticated user-facing answer must start with the routed named agent
+  line from `answerContract.firstLine`, for example:
+  `agent: <agent-name> (<agent-role>) to <user>`.
+- After meaningful work or a useful answer, save memory:
+  `mop-core.mjs memory add --actor <codename> --kind conversation --summary "<one-line outcome>"`.
+
+| Role | Name | Description |
+| :--- | :--- | :--- |
+| **[qa]**         | QA Engineer             | Test plans, coverage gaps, regression                  |
+| **[ai]**         | Prompt Alchemist        | Prompt engineering, AI tuning, LLM evaluation          |
+| **[seo]**        | SEO Strategist          | Technical SEO, on-page, audits, implementation specs   |
+| **[browser]**    | Browsing Agent          | Web browsing, scraping, form filling, bot bypass, extraction |
+
+- If the router marks the task as ambiguous, the named primary agent must ask
+  clarifying questions before implementation.
+- If the router returns `nextAction: "name-required-party-agents"`, ask every
+  question in `missingAgentQuestions` and stop until those agents are named.
+- **[browser] Agent Rule**: Before browser, scraping, extraction, click
+  automation, login flow, bot-detection, or form-filling work, run
+  `mop-core.mjs browser preflight`. It scans the default browser when possible.
+  If it reports Edge, Brave, or Opera, use browser-act `chrome-direct` mode and
+  guide the user to start remote debugging (`--remote-debugging-port`). If it
+  cannot detect a supported browser, ask which browser they use before doing
+  browser work. Never create a default Chrome session first when the user uses
+  another supported browser.
+- If the router returns `partyMode.active: true`, use Party Mode. Show
+  `PARTY MODE` in large uppercase before the dialogue, then generate the
+  agent-to-agent and agent-to-user dialogue explicitly in your response using this exact format:
+  `agent: <from-name> (<from-role>) to agent: <to-name> (<to-role>)`
+  `          <message>`
+  Party Mode normally uses at least 3 agents and prefers 4 when relevant roles exist.
+- For complex work or "what next?" questions, use MOP Workflow:
+  `mop-workflow.mjs help --actor <codename> --task "<user task>"`.
+- Before implementation, run the readiness gate. If it is not `ready`, ask
+  clarification or create/update the needed artifact before coding.
+- For risky changes, run adversarial review before implementation or merge.
+
+For `/mop-setup`, ask in order: project name (default folder name), owner display
+name, owner codename, password, solo/team, conversation language, coding
+language, GitHub link, GitHub username, Git commit email (`github-noreply` by
+default), join mode if team, then whether to activate auto-deploy now or later.
+
+Agent role/template names are not personal AI names. When a role agent is first
+needed, ask the user to name it and save it with `mop-core.mjs agent activate`.
+In team mode, the same agent name is shared across members; different names are
+different agents.
+The active named agent must be recorded on every memory/ledger action. Do not
+activate irrelevant agents; route to one primary agent first, then add support
+agents through Party Mode only when useful.
+If the assistant cannot show the active agent line, it must stop and repair the
+agent route instead of answering invisibly.
+
+Default skill: `autosycn`. After meaningful changes, use
+`.MOP/scripts/mop-autosycn.mjs`. It must commit and merge with the
+real member Git identity from state, never with the AI tool identity.
+Member commits must use the active member GitHub account; by default MOP derives
+`ID+USERNAME@users.noreply.github.com` from `gh api user` and refuses mismatched
+GitHub accounts. `BURHAN-MOP` identity is only for merge guardian commits.
+In team mode, run `preflight --actor <codename>` before starting work; work goes
+to `dev/<codename>`. Every small or large change is pushed there first, then
+BURHAN-MOP reviews and merges to `main` only when checks pass.
+
+Default skill: `auto-deploy`. It supports GitHub, Docker, and Vercel, but must
+ask before activation. If the user says later/no, reply that deploy can be set
+up when they ask.
+
+Default skill: `mop-help`. It answers "lepas ni buat apa?", routes the next MOP
+workflow phase, and names the next artifact/gate.
+
+Installer command: `npx mop-flow install`.
+Legacy compatibility command: `npx burhan-mop install`.
+GitHub source fallback for development builds:
+`npx --yes github:BURHANDEV-ENTERPRISE/BURHAN-MOP install`.
+
+This directory is the portable **MOP Flow** agent core. MOP Flow is the
+provider-neutral layer above upstream Ruflo / Claude Flow runtime compatibility.
+It must work across Claude Code, Codex / ChatGPT coding surfaces, Gemini CLI,
+and Google Antigravity. Treat this file as the provider-neutral source of truth.
+
+## Provider Entry Points
+
+- Claude Code: read `CLAUDE.md` and `.claude/settings.json`.
+- Codex / ChatGPT coding agents: read this `AGENTS.md`.
+- Gemini CLI: read `GEMINI.md`, which imports this file, and `.gemini/settings.json`.
+- Antigravity managed agents: read `.agents/AGENTS.md` and `.agents/skills/`.
+
+## MOP Flow Canonical Layer
+
+- User-facing brand: **MOP Flow**.
+- Canonical MCP server name: `mop-flow`.
+- Upstream runtime command: `npx -y ruflo@latest mcp start`.
+- Compatibility env vars such as `CLAUDE_FLOW_*` may remain because the upstream
+  runtime expects them; they do not make Claude the owner of the workflow.
+- Before using runtime skills/tools, check provider parity when relevant:
+
+```bash
+node .MOP/scripts/mop-flow.mjs status --json
+node .MOP/scripts/mop-flow.mjs skills list
+```
+
+## Core Rules
+
+- Do what the user asked, with the smallest safe change.
+- Always read an existing file before editing it.
+- Treat the current workspace root as the project root. Do not create a nested
+  project wrapper like `portfolio/`, `my-app/`, or `<project-name>/`; scaffold
+  app files directly in root using normal folders such as `src`, `app`,
+  `components`, `public`, `tests`, `docs`, `config`, and `scripts`.
+- Do not create root working files, throwaway tests, or generated logs.
+- Never read, print, copy, commit, or summarize `.env` or `.env.*` files.
+- Validate JSON, TOML, YAML, and Markdown after changing configuration.
+- Keep provider-specific commands isolated. If a tool name is unavailable in the
+  current agent surface, use the nearest local shell or MCP equivalent.
+- Prefer `rg` or `rg --files` for search. If unavailable, use the next fastest
+  platform-native search.
+- Do not assume Claude-only hooks, slash commands, or Agent tools exist outside
+  Claude Code. Translate the workflow into the current provider's tools.
+
+## MOP Flow Runtime
+
+The upstream runtime data lives in `.claude-flow/`, but MOP Flow owns the
+workflow, memory gates, agent routing, and skill bridge. The shared MCP
+declaration is in `.mcp.json`. Claude-specific hooks and helper scripts live in
+`.claude/`.
+
+Use these commands when the current environment supports shell execution:
+
+```bash
+node .MOP/scripts/mop-flow.mjs status
+npx -y ruflo@latest doctor --fix
+npx -y ruflo@latest mcp start
+npx -y ruflo@latest swarm status
+npx -y ruflo@latest memory search --query "task keywords"
+```
+
+Do not start long-running daemons unless the user asked for it. Prefer status and
+diagnostic commands before making changes.
+
+## Cross-Provider Adaptation
+
+- If instructions mention `SendMessage`, `Agent`, or Claude subagents, map the
+  idea to the current provider's delegation model. If no delegation tool exists,
+  perform the task directly and keep a clear checklist.
+- If instructions mention Claude hooks, treat them as policy guidance in Codex,
+  Gemini, or Antigravity unless that provider has an equivalent hook system.
+- If instructions mention `.claude/skills`, bridge those files through MOP Flow.
+  The canonical portable skill surface is `.agents/skills/` for all providers.
+- If MCP is available, prefer MCP for live tools and stateful integrations. If
+  MCP is unavailable, continue with filesystem and shell inspection.
+- Do not call the user-facing system Claude Flow unless explaining upstream
+  compatibility. In normal work, call it MOP Flow.
+
+## Verification
+
+Before finishing any configuration change in this core:
+
+- Parse `.mcp.json`, `.claude/settings.json`, and `.gemini/settings.json` when
+  present.
+- Run `node .MOP/scripts/mop-flow.mjs status --json` for provider/skill changes.
+- Check TOML files with a parser if one is available.
+- Confirm no secrets were introduced.
+- Report which provider surfaces are covered and which need manual auth.

package/CLAUDE.md

@@ -0,0 +1,277 @@
+# MOP Flow - Claude Code Configuration
+
+## MOP Authentication Gate - First Action
+
+Before doing anything in this workspace, read `.MOP/STATE.json` and
+follow `.MOP/PROTOCOL.md`.
+
+- `initialized: false` -> output `MOP belum di-setup. Jalankan /mop-setup.` Run the setup wizard only.
+- `initialized: true` with no `activeMember` -> output `Codename dan password.` Do not continue until verified.
+- Verify credentials through `node .MOP/scripts/mop-core.mjs login --codename <codename> --password "<password>"`.
+- Wrong credentials -> output `Credentials tidak sah.`
+- After authentication, run the Agent Router before answering or acting:
+  `mop-core.mjs agent route --actor <codename> --task "<user task>"`.
+  It selects one primary role and may recommend any number of support roles
+  when genuinely needed. If no named agent exists for a needed role, ask the
+  user to name it and save it with `agent activate`.
+- Before answering an authenticated task, restore monthly memory:
+  `mop-core.mjs memory brief --actor <codename>`.
+- Every authenticated user-facing answer must start with the routed named agent
+  line from `answerContract.firstLine`, for example:
+  `agent: <agent-name> (<agent-role>) to <user>`.
+- After meaningful work or a useful answer, save memory:
+  `mop-core.mjs memory add --actor <codename> --kind conversation --summary "<one-line outcome>"`.
+- If the router marks the task as ambiguous, the named primary agent must ask
+  clarifying questions before implementation.
+- If the router returns `nextAction: "name-required-party-agents"`, ask every
+  question in `missingAgentQuestions` and stop until those agents are named.
+- Before browser, scraping, extraction, click automation, login flow,
+  bot-detection, or form-filling work, run `mop-core.mjs browser preflight`. If
+  it reports Edge, Brave, or Opera, use browser-act `chrome-direct` mode and
+  guide the user to start remote debugging (`--remote-debugging-port`). If it
+  cannot detect a supported browser, ask which browser they use before doing
+  browser work.
+- If the router returns `partyMode.active: true`, use Party Mode. Show
+  `PARTY MODE` in large uppercase before the dialogue, then show
+  agent-to-agent and agent-to-user dialogue with the exact format from
+  `.MOP/PROTOCOL.md`. Party Mode normally uses at least 3 agents and
+  prefers 4 when relevant roles exist.
+- For complex work or "what next?" questions, use MOP Workflow:
+  `mop-workflow.mjs help --actor <codename> --task "<user task>"`.
+- Before implementation, run the readiness gate. If it is not `ready`, ask
+  clarification or create/update the needed artifact before coding.
+- For risky changes, run adversarial review before implementation or merge.
+
+Agent role/template names are not personal AI names. When a role agent is first
+needed, ask the user to name it and save it with `mop-core.mjs agent activate`.
+In team mode, the same agent name is shared across members; different names are
+different agents.
+The active named agent must be recorded on every memory/ledger action. Do not
+activate irrelevant agents; route to one primary agent first, then add support
+agents through Party Mode only when useful.
+If the assistant cannot show the active agent line, it must stop and repair the
+agent route instead of answering invisibly.
+
+Default skill: `autosycn`. After meaningful changes, use
+`.MOP/scripts/mop-autosycn.mjs`. It must commit and merge with the
+real member Git identity from state, never with the AI tool identity.
+Member commits must use the active member GitHub account; by default MOP derives
+`ID+USERNAME@users.noreply.github.com` from `gh api user` and refuses mismatched
+GitHub accounts. `BURHAN-MOP` identity is only for merge guardian commits.
+In team mode, run `preflight --actor <codename>` before starting work; work goes
+to `dev/<codename>`. Every small or large change is pushed there first, then
+BURHAN-MOP reviews and merges to `main` only when checks pass.
+
+Default skill: `auto-deploy`. It supports GitHub, Docker, and Vercel, but must
+ask before activation. If the user says later/no, reply that deploy can be set
+up when they ask.
+
+Default skill: `mop-help`. It answers "lepas ni buat apa?", routes the next MOP
+workflow phase, and names the next artifact/gate.
+
+Installer command: `npx mop-flow install`.
+Legacy compatibility command: `npx burhan-mop install`.
+GitHub source fallback for development builds:
+`npx --yes github:BURHANDEV-ENTERPRISE/BURHAN-MOP install`.
+
+During `/mop-setup`, ask whether to activate auto-deploy after the Git/GitHub
+identity questions.
+
+## MOP Flow Canonical Layer
+
+MOP Flow is the user-facing system. Ruflo / Claude Flow are upstream runtime
+compatibility names only. Claude Code must still follow MOP auth, Agent Router,
+memory, workflow, readiness, and autosycn before using Claude-native hooks or
+skills.
+
+```bash
+node .MOP/scripts/mop-flow.mjs status --json
+node .MOP/scripts/mop-flow.mjs skills list
+```
+
+- Canonical MCP server name: `mop-flow`.
+- Portable skill source: `.agents/skills/`.
+- Runtime-native skill source: `.claude/skills/`.
+- When a skill must work outside Claude, bridge it through MOP Flow instead of
+  treating Claude hooks or slash commands as universal.
+
+## Rules
+
+- Do what has been asked; nothing more, nothing less
+- NEVER create files unless absolutely necessary — prefer editing existing files
+- NEVER create documentation files unless explicitly requested
+- Treat the current workspace root as the project root. Do not create a nested
+  project wrapper like `portfolio/`, `my-app/`, or `<project-name>/`; scaffold
+  app files directly in root using normal folders such as `src`, `app`,
+  `components`, `public`, `tests`, `docs`, `config`, and `scripts`.
+- NEVER save working files or tests to root — use `/src`, `/tests`, `/docs`, `/config`, `/scripts`
+- ALWAYS read a file before editing it
+- NEVER commit secrets, credentials, or .env files
+- NEVER add a `Co-Authored-By` trailer to user commits unless this project's `.claude/settings.json` has `attribution.commit` set (#2078). The Claude Code Bash tool may suggest one in its default commit-message template — ignore it. `Co-Authored-By` is semantic authorship attribution under git/GitHub convention; the tool is the facilitator, not a co-author.
+- Keep files under 500 lines
+- Validate input at system boundaries
+
+## Agent Comms (SendMessage-First Coordination)
+
+Named agents coordinate via `SendMessage`, not polling or shared state.
+
+```
+Lead (you) ←→ architect ←→ developer ←→ tester ←→ reviewer
+              (named agents message each other directly)
+```
+
+### Spawning a Coordinated Team
+
+```javascript
+// ALL agents in ONE message, each knows WHO to message next
+Agent({ prompt: "Research the codebase. SendMessage findings to 'architect'.",
+  subagent_type: "researcher", name: "researcher", run_in_background: true })
+Agent({ prompt: "Wait for 'researcher'. Design solution. SendMessage to 'coder'.",
+  subagent_type: "system-architect", name: "architect", run_in_background: true })
+Agent({ prompt: "Wait for 'architect'. Implement it. SendMessage to 'tester'.",
+  subagent_type: "coder", name: "coder", run_in_background: true })
+Agent({ prompt: "Wait for 'coder'. Write tests. SendMessage results to 'reviewer'.",
+  subagent_type: "tester", name: "tester", run_in_background: true })
+Agent({ prompt: "Wait for 'tester'. Review code quality and security.",
+  subagent_type: "reviewer", name: "reviewer", run_in_background: true })
+
+// Kick off the pipeline
+SendMessage({ to: "researcher", summary: "Start", message: "[task context]" })
+```
+
+### Patterns
+
+| Pattern | Flow | Use When |
+|---------|------|----------|
+| **Pipeline** | A → B → C → D | Sequential dependencies (feature dev) |
+| **Fan-out** | Lead → A, B, C → Lead | Independent parallel work (research) |
+| **Supervisor** | Lead ↔ workers | Ongoing coordination (complex refactor) |
+
+### Rules
+
+- ALWAYS name agents — `name: "role"` makes them addressable
+- ALWAYS include comms instructions in prompts — who to message, what to send
+- Spawn ALL agents in ONE message with `run_in_background: true`
+- After spawning: STOP, tell user what's running, wait for results
+- NEVER poll status — agents message back or complete automatically
+
+## MOP Flow Swarm & Routing
+
+### Config
+- **Topology**: adaptive (anti-drift)
+- **Max Agents**: 50
+- **Memory**: hybrid
+- **HNSW**: Enabled
+- **Neural**: Enabled
+
+```bash
+npx ruflo@latest swarm init --topology hierarchical --max-agents 8 --strategy specialized
+```
+
+### Agent Routing
+
+| Task | Agents | Topology |
+|------|--------|----------|
+| Bug Fix | researcher, coder, tester | hierarchical |
+| Feature | architect, coder, tester, reviewer | hierarchical |
+| Refactor | architect, coder, reviewer | hierarchical |
+| Performance | perf-engineer, coder | hierarchical |
+| Security | security-architect, auditor | hierarchical |
+
+### When to Swarm
+- **YES**: 3+ files, new features, cross-module refactoring, API changes, security, performance
+- **NO**: single file edits, 1-2 line fixes, docs updates, config changes, questions
+
+### 3-Tier Model Routing
+
+| Tier | Handler | Use Cases |
+|------|---------|-----------|
+| 1 | Agent Booster (WASM) | Simple transforms — skip LLM, use Edit directly |
+| 2 | Haiku | Simple tasks, low complexity |
+| 3 | Sonnet/Opus | Architecture, security, complex reasoning |
+
+## Memory & Learning
+
+### Before Any Task
+```bash
+node .MOP/scripts/mop-flow.mjs status --json
+npx ruflo@latest memory search --query "[task keywords]" --namespace patterns
+npx ruflo@latest hooks route --task "[task description]"
+```
+
+### After Success
+```bash
+npx ruflo@latest memory store --namespace patterns --key "[name]" --value "[what worked]"
+npx ruflo@latest hooks post-task --task-id "[id]" --success true --store-results true
+```
+
+### MCP Tools (use `ToolSearch("keyword")` to discover)
+
+| Category | Key Tools |
+|----------|-----------|
+| **Memory** | `memory_store`, `memory_search`, `memory_search_unified` |
+| **Bridge** | `memory_import_claude`, `memory_bridge_status` |
+| **Swarm** | `swarm_init`, `swarm_status`, `swarm_health` |
+| **Agents** | `agent_spawn`, `agent_list`, `agent_status` |
+| **Hooks** | `hooks_route`, `hooks_post-task`, `hooks_worker-dispatch` |
+| **Security** | `aidefence_scan`, `aidefence_is_safe`, `aidefence_has_pii` |
+| **Hive-Mind** | `hive-mind_init`, `hive-mind_consensus`, `hive-mind_spawn` |
+
+### Background Workers
+
+| Worker | When |
+|--------|------|
+| `audit` | After security changes |
+| `optimize` | After performance work |
+| `testgaps` | After adding features |
+| `map` | Every 5+ file changes |
+| `document` | After API changes |
+
+```bash
+npx ruflo@latest hooks worker dispatch --trigger audit
+```
+
+## Agents
+
+**Core**: `coder`, `reviewer`, `tester`, `planner`, `researcher`
+**Architecture**: `system-architect`, `backend-dev`, `mobile-dev`
+**Security**: `security-architect`, `security-auditor`
+**Performance**: `performance-engineer`, `perf-analyzer`
+**Coordination**: `hierarchical-coordinator`, `mesh-coordinator`, `adaptive-coordinator`
+**GitHub**: `pr-manager`, `code-review-swarm`, `issue-tracker`, `release-manager`
+
+Any string works as a custom agent type.
+
+## Build & Test
+
+- ALWAYS run tests after code changes
+- ALWAYS verify build succeeds before committing
+
+```bash
+npm run build && npm test
+```
+
+## CLI Quick Reference
+
+```bash
+node .MOP/scripts/mop-flow.mjs status                # Provider parity
+npx ruflo@latest init --wizard                       # Runtime setup
+npx ruflo@latest swarm init --v3-mode                 # Start swarm
+npx ruflo@latest memory search --query ""             # Vector search
+npx ruflo@latest hooks route --task ""                # Route to agent
+npx ruflo@latest doctor --fix                         # Diagnostics
+npx ruflo@latest security scan                        # Security scan
+npx ruflo@latest performance benchmark                # Benchmarks
+```
+
+26 commands, 140+ subcommands. Use `--help` on any command for details.
+
+## Setup
+
+```bash
+claude mcp add mop-flow -- npx -y ruflo@latest mcp start
+npx ruflo@latest daemon start
+npx ruflo@latest doctor --fix
+```
+
+**Agent tool** handles execution (agents, files, code, git). **MCP tools** handle coordination (swarm, memory, hooks). **CLI** is the same via Bash.

package/GEMINI.md

@@ -0,0 +1,48 @@
+# MOP Core - Gemini CLI Instructions
+
+Gemini CLI should load this file as project context. The main provider-neutral
+rules are imported below.
+
+@./AGENTS.md
+
+## MOP Flow Notes
+
+- Use MOP Flow as the canonical system name.
+- Use `.agents/skills/` as the portable skill surface.
+- When a capability exists only in `.claude/skills/`, read it as a MOP Flow
+  bridged skill and translate Claude-only hooks/slash commands into Gemini CLI
+  tools or local shell/MCP equivalents.
+- Check provider parity with:
+
+```bash
+node .MOP/scripts/mop-flow.mjs status --json
+```
+
+## Gemini-Specific Notes
+
+- First action still applies: read `.MOP/STATE.json` and follow
+  `.MOP/PROTOCOL.md`.
+- After authentication, run `mop-core.mjs memory brief --actor <codename>` and
+  `mop-core.mjs agent route --actor <codename> --task "<user task>"` before
+  answering.
+- Every authenticated answer must start with `answerContract.firstLine`, for
+  example: `agent: <agent-name> (<agent-role>) to <user>`.
+- Save a one-line memory after meaningful work with
+  `mop-core.mjs memory add --actor <codename> --kind conversation --summary "<outcome>"`.
+- If `agent route` returns `nextAction: "name-required-party-agents"`, ask every
+  question in `missingAgentQuestions` and stop until those agents are named.
+- Before browser, scraping, extraction, click automation, login flow,
+  bot-detection, or form-filling work, run `mop-core.mjs browser preflight` and
+  follow its mode/question before doing browser work.
+- Autosycn member commits must use the active member GitHub account. MOP derives
+  `ID+USERNAME@users.noreply.github.com` from `gh api user` by default and
+  refuses mismatched GitHub accounts.
+- Treat the current workspace root as the project root; do not create a nested
+  project wrapper folder for app work unless the user explicitly asks for it.
+- Use `.gemini/settings.json` for context filenames and MCP server setup.
+- Use `/memory show` to verify which context files Gemini loaded.
+- Use `/memory refresh` after editing `AGENTS.md`, `GEMINI.md`, or nested context
+  files.
+- If MCP servers fail to start, continue with local filesystem inspection and
+  report the failed server name clearly. Prefer the `mop-flow` server name when
+  referring to the Ruflo-backed runtime.

package/README.bm.md

@@ -0,0 +1,171 @@
+<h1 align="center">MOP Flow</h1>
+
+<p align="center">
+  <strong>MOP portable AI MemoryCore untuk Claude, Codex / ChatGPT, Gemini, dan Antigravity.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/mop-flow">
+    <img src="https://img.shields.io/npm/v/mop-flow?style=for-the-badge&label=NPM" alt="npm version">
+  </a>
+  <a href="https://github.com/BURHANDEV-ENTERPRISE/BURHAN-MOP">
+    <img src="https://img.shields.io/badge/GitHub-BURHAN--MOP-181717?style=for-the-badge&logo=github" alt="GitHub repository">
+  </a>
+  <img src="https://img.shields.io/badge/Node-%3E%3D20-1FAE4B?style=for-the-badge&logo=node.js&logoColor=white" alt="Node 20+">
+  <img src="https://img.shields.io/badge/License-UNLICENSED-9CA3AF?style=for-the-badge" alt="License">
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Claude-ready-5A45FF?style=flat-square" alt="Claude ready">
+  <img src="https://img.shields.io/badge/Codex-ready-111111?style=flat-square" alt="Codex ready">
+  <img src="https://img.shields.io/badge/Gemini-ready-4285F4?style=flat-square" alt="Gemini ready">
+  <img src="https://img.shields.io/badge/Antigravity-ready-00A67E?style=flat-square" alt="Antigravity ready">
+  <img src="https://img.shields.io/badge/MOP_Flow-provider_neutral-00A67E?style=flat-square" alt="MOP Flow">
+  <img src="https://img.shields.io/badge/MOP_Workflow-BMAD_inspired-FFB000?style=flat-square" alt="MOP workflow">
+</p>
+
+<p align="center">
+  <a href="./README.md">English</a>
+  |
+  <strong>Bahasa Melayu</strong>
+</p>
+
+---
+
+## Apa Itu MOP Flow?
+
+MOP Flow ialah **MOP (Memory of Planet) core** yang portable untuk workspace
+coding AI. Ia bagi semua AI provider sumber kebenaran yang sama: memory project,
+peraturan agent, workflow gate, folder artifact, autosycn, dan setup deploy.
+
+Maksudnya mudah: pasang sekali, kemudian Claude, Codex / ChatGPT, Gemini, dan
+Antigravity boleh masuk project yang sama dengan context yang sama.
+
+## MOP Flow
+
+MOP Flow ialah layer orchestration dan skill bridge yang neutral provider untuk
+MOP. Ia pastikan brand dan rules MOP berada di atas upstream runtime
+Ruflo / Claude Flow, jadi Claude, Codex, Gemini, dan Antigravity nampak skill
+inventory dan MCP runtime surface yang sama.
+
+```bash
+node .MOP/scripts/mop-flow.mjs status
+node .MOP/scripts/mop-flow.mjs skills list
+node .MOP/scripts/mop-flow.mjs manifest refresh
+```
+
+Roadmap improvement aktif ada di `.MOP/flow/ROADMAP.md`.
+
+## Install
+
+Jalankan dalam root project:
+
+```bash
+npx mop-flow install
+npx mop-flow doctor
+```
+
+Install ke folder lain:
+
+```bash
+npx mop-flow install --target "C:\path\to\project"
+```
+
+Paksa overwrite install sedia ada:
+
+```bash
+npx mop-flow install --force
+```
+
+Installer akan tunjuk terminal UI yang kemas secara default. Untuk automation,
+guna JSON:
+
+```bash
+npx mop-flow install --json
+npx mop-flow doctor --json
+```
+
+Selepas install, buka AI coding chat dalam project itu dan jalankan:
+
+```text
+/mop-setup
+```
+
+## Apa Yang Dipasang
+
+| Path | Fungsi |
+| --- | --- |
+| `.MOP/` | State, protocol, script, workflow config, dan template artifact MOP. |
+| `AGENTS.md` | Arahan neutral untuk Codex / ChatGPT coding agents. |
+| `CLAUDE.md` | Entry point dan rules untuk Claude Code. |
+| `GEMINI.md` | Entry point untuk Gemini CLI. |
+| `.agents/` | Agent dan skill yang sesuai untuk Antigravity. |
+| `.codex/`, `.gemini/`, `.claude/` | Config dan skill surface ikut provider. |
+
+## Fungsi Utama
+
+| Fungsi | Apa dia buat |
+| --- | --- |
+| Auth Gate | First action mesti setup/login. AI tidak terus bekerja sebelum gate lulus. |
+| Agent Router | Pilih satu primary agent dan tambah support agent bila perlu. |
+| Party Mode | Tunjuk perbincangan agent-to-agent untuk keputusan multi-role. |
+| MOP Flow | Skill bridge dan MCP runtime wrapper neutral provider untuk Claude, Codex, Gemini, dan Antigravity. |
+| MOP Workflow | Flow inspirasi BMAD dari idea sampai release dengan readiness gate. |
+| Artifacts | Simpan plan, spec, review, dan release notes dalam `.MOP/artifacts/`. |
+| Autosycn | Commit dan push guna identiti user sebenar, bukan identiti AI tool. |
+| Auto Deploy | Setup optional untuk GitHub, Docker, dan Vercel. |
+
+## Flow Sesi Pertama
+
+```text
+1. AI baca .MOP/STATE.json
+2. Jika belum setup, AI suruh jalankan /mop-setup
+3. Setup tanya nama project, owner, codename, password, mode, bahasa, dan GitHub
+4. Selepas login, setiap task lalu Agent Router
+5. Task kompleks guna MOP Workflow dan readiness gate sebelum coding
+```
+
+## Command Berguna
+
+```bash
+npx mop-flow install
+npx mop-flow doctor
+npx mop-flow package
+```
+
+Helper dalam project:
+
+```bash
+node .MOP/scripts/mop-core.mjs status
+node .MOP/scripts/mop-core.mjs validate
+node .MOP/scripts/mop-flow.mjs status
+node .MOP/scripts/mop-workflow.mjs help --actor <codename> --task "<task>"
+node .MOP/scripts/mop-autosycn.mjs run --actor <codename> --reason "<apa berubah>"
+```
+
+## Workflow Team
+
+Dalam team mode, kerja akan push ke branch user dulu:
+
+```text
+dev/<codename> -> BURHAN-MOP review -> main
+```
+
+BURHAN-MOP bertindak sebagai merge guardian. Ia semak branch, validate state,
+dan merge hanya bila workflow selamat.
+
+## Release
+
+| Item | Nilai |
+| --- | --- |
+| npm package | [`mop-flow`](https://www.npmjs.com/package/mop-flow) |
+| command latest | `npx mop-flow install` |
+| legacy alias | `npx burhan-mop install` |
+| GitHub release | [`v0.1.8`](https://github.com/BURHANDEV-ENTERPRISE/BURHAN-MOP/releases/tag/v0.1.8) |
+| Node | `>=20` |
+
+## Links
+
+- npm: https://www.npmjs.com/package/mop-flow
+- GitHub: https://github.com/BURHANDEV-ENTERPRISE/BURHAN-MOP
+- English README: [README.md](./README.md)