Pomelo

Pomelo is an AI-native feature protocol for software teams using coding agents.

It does not try to become your IDE, your project manager, or your chat UI. Instead, it gives AI tools a shared local protocol under .pomelo/ so they can maintain durable feature memory, ingest new evidence, reconcile change, and derive plans without relying on fragile chat context alone.

In one sentence:

Pomelo is a CLI-first, file-based feature protocol that AI tools can follow directly.

Project Positioning

Pomelo is:

• an AI-native feature-memory protocol
• a local source-of-truth layer for coding agents
• a CLI for impact routing, truth updates, and plan generation
• a lightweight way to keep iterating on the same project feature over time

Pomelo is not:

• a UI-first product
• a PM tool
• a task tracker
• a general knowledge base
• an agent runtime or orchestration framework
• a cloud collaboration suite
• the intelligence layer itself

The model does the reasoning. Pomelo owns the structure, state, and persistence.

Quick Start

The fastest way to introduce Pomelo into an existing AI coding workflow is:

1. Install the CLI

npm install -g pomeloflow

Or without a global install:

npx pomeloflow --help

2. Initialize Pomelo In Your Project

From your project root:

pomelo init

This creates:

• .pomelo/
• .pomelo/config.json
• .agents/skills/pomelo-protocol/SKILL.md
• AGENTS.md instructions that tell coding agents when and how to call Pomelo

3. Let Your AI Coding Tool Follow The Installed Skill

Tell your AI tool to use .agents/skills/pomelo-protocol/SKILL.md.

Pomelo also writes a managed section into AGENTS.md that points agents toward the skill and CLI.

The important idea:

• keep using your normal AI coding tool
• let the AI call pomelo when work is large enough to need durable feature memory
• let Pomelo persist feature state between sessions

4. Start Or Match A Feature Module

When a change is large enough to deserve Pomelo:

pomelo init-feature feat-checkout-resilience --title "Checkout resilience"

Or if the project already has related feature memory:

pomelo route --title "Checkout timeout update" --content "..."

5. Ingest Evidence And Rebuild Truth

pomelo ingest feat-checkout-resilience --title "PRD summary" --content "..."
pomelo truth feat-checkout-resilience --json

6. Generate A Plan Before Coding

pomelo plan feat-checkout-resilience --for all --json

7. Typical AI-Native Loop

Once Pomelo is initialized, a coding agent usually follows this loop:

pomelo status --json
pomelo route --title "..." --content "..." --json
pomelo ingest <feature-id> --title "..." --content "..." --json
pomelo truth <feature-id> --json
pomelo plan <feature-id> --for all --json
pomelo cleanup <feature-id> --json

Low-token default for agents:

• read status --json, route --json, truth --json, and plan --json first
• use compact JSON fields to decide the next action
• only open truth/feature.md or plans/*.md when the JSON response indicates deeper review is needed

8. When Not To Use Pomelo

Do not force every small edit into the protocol.

Skip Pomelo for:

• typo fixes
• tiny style tweaks
• obvious one-off edits
• short-lived exploration with no durable shared context

When to Use What

Single AI agent working on a feature (most common): Use route → ingest → truth → plan — the core workflow handles everything.

Multiple agents or developers collaborating on the same feature: Add dispatch → consume → align on top of the core workflow to coordinate roles, track alignment, and propagate decisions across agents.

The multi-agent commands are optional — they enhance the core workflow, not replace it.

Why Feature Instead Of Requirement

PRDs, designs, meeting notes, APIs, QA findings are all sources. The durable object is a feature with canonical truth. Execution guidance becomes disposable plans.

Current Scope

• Initialize .pomelo/ workspace and feature scaffolds
• Route new input to the most likely feature
• Ingest source material and codebase-derived evidence
• Rebuild truth/feature.md and generate plans
• Mark and archive stale plans with pomelo cleanup
• Machine-friendly --json output for AI tooling

Note: route, truth, and plan are still early-stage engines. Pomelo uses a deterministic rules engine — it does not call LLMs.

Protocol Layout

Recommended workspace shape:

.pomelo/
  workspace.md
  config.json
  features/
    feat-example/
      sources/
        src-001.md
        src-002.md
      analysis/
        facts/
          fact-001.md
        issues/
          issue-001.md
        decisions/
          dec-001.md
      truth/
        feature.md
      plans/
        implementation.md
        test.md
      runtime/
        events/
      snapshots/

Key directories:

• sources/ incoming evidence from product, design, code, API, QA, or meetings
• analysis/ optional facts, issues, and decisions for structured reconciliation, conflicts, merge choices, or unresolved questions
• truth/feature.md canonical feature-module memory
• plans/ disposable implementation and test plans
• runtime/ change history and stale-plan signals

Reference material:

• JSON contract: docs/json-contract.md
• Minimal example workspace: examples/minimal-feature-workspace/

Core Workflow

The core loop: route → ingest → truth → plan → cleanup

route --json
  → supplement   → ingest → truth --json
  → conflict     → stop for review
  → new_feature  → init-feature → ingest → truth --json

truth --json
  → unchanged                → continue
  → supplement + merge       → plan if needed
  → conflict + review        → stop and resolve
  → regenerate_plans         → plan --json

plan --json
  → read generated targets → implement → cleanup when done

File Lifecycle

| Path | Created by | Lifetime | |------|------------|----------| | sources/*.md | pomelo ingest | Durable evidence | | truth/feature.md | pomelo init-feature | Canonical feature memory | | plans/*.md | pomelo plan | Disposable execution artifacts | | runtime/events/*.md | pomelo truth | Append-only change history | | snapshots/*.md | pomelo truth/cleanup | Historical trace | | analysis/issues/*.md | AI/human | Optional — only when conflicts arise |

AI Decision Table

Use machine-readable fields to decide the next action:

| Command | Field | Action | |---------|-------|--------| | route --json | decision = supplement | Ingest into matched feature | | route --json | decision = conflict | Stop for review | | route --json | decision = new_feature | Run init-feature first | | truth --json | changeType = unchanged | Continue, no replan needed | | truth --json | changeType = supplement | Merge truth, check plans | | truth --json | changeType = conflict | Stop and review | | truth --json | shouldMerge = false | Ask for human/AI review | | truth --json | recommendedNextAction = regenerate_plans | Run pomelo plan | | plan --json | planStatus = generated | Read plans, start implementation |

CLI

Quick Command Reference

| Purpose | Command | When to use | |---------|---------|-------------| | Initialize | pomelo init | Once per project | | New feature | pomelo init-feature <id> --title "..." | Start tracking a feature | | Route input | pomelo route --content "..." | Match input to a feature | | Add evidence | pomelo ingest <id> --title "..." --content "..." | Record a fact or decision | | Build truth | pomelo truth <id> | After adding evidence | | Generate plan | pomelo plan <id> | When truth is ready | | Orchestrate | pomelo dispatch <id> | Multi-agent: get task assignments | | Role view | pomelo consume <id> --role <role> | Multi-agent: sub-agent gets context | | Check gate | pomelo align <id> | Multi-agent: verify readiness | | View changes | pomelo events <id> | Track what changed | | Clean up | pomelo cleanup <id> | Archive stale plans |

Full Command Reference

Core commands:

pomelo init [--root <path>] [--title <name>] [--json]
pomelo init-feature <feature-id> --title <name> [--workspace-path <path>] [--summary <text>] [--json]
pomelo features [--root <path>] [--json]
pomelo config get [language] [--root <path>] [--json]
pomelo config set language <en|zh> [--root <path>] [--json]
pomelo route --content <text> [--title <title>] [--limit <n>] [--root <path>] [--json]
pomelo ingest <feature-id> --title <title> (--content <text> | --file <path>) [--role <pm|designer|frontend|backend|qa>] [--kind <markdown|figma_link|api_doc|meeting_note|code_snippet>] [--json]
pomelo truth <feature-id> [--root <path>] [--json]
pomelo plan <feature-id> [--for <implementation|test|all>] [--root <path>] [--json]
pomelo cleanup <feature-id> [--root <path>] [--json]
pomelo dispatch <feature-id> [--root <path>] [--json]    # Orchestrator: get alignment + tasks + notifications
pomelo consume <feature-id> --role <role> [--root <path>] [--json]  # Sub-agent: get role-specific view + task
pomelo align <feature-id> [--root <path>] [--json]       # Check alignment gate before plan/dev

Architecture

Pomelo is a deterministic rules engine — it does not call any LLM. AI tools call Pomelo CLI commands and interpret the structured JSON responses. Pomelo owns protocol structure and file persistence; AI tools own intelligent judgment.

See docs/json-contract.md for all machine-readable field definitions.

Multi-Agent Team Workflow

Pomelo supports multi-agent team collaboration where a master orchestrator coordinates multiple role-specific sub-agents.

Overview

Pomelo serves as the coordination layer for multi-agent teams:

• Orchestrator calls pomelo dispatch to get alignment status, pending tasks, and notifications
• Sub-agents call pomelo consume to get role-specific context and assigned work
• Alignment gates via pomelo align check whether the feature is ready for the next phase
• Truth remains the single source of truth for all agents

Seven-Dimensional Structured Truth

Truth is organized into seven sections with clear ownership:

| Section | Owner | Consumers | Purpose | |---------|-------|-----------|--------| | Feature Intent | PM | all | Business goals, scope, rules | | User Flows | Designer | Frontend, QA | Screens, states, interactions | | API Contracts | Backend | Frontend, QA | Endpoints, request/response shapes | | Frontend Contracts | Frontend | Backend, QA | Components, props, data flow | | Acceptance Criteria | QA | PM, Frontend, Backend | Test scenarios, Given-When-Then | | Open Issues | shared | all | Risks, questions, conflicts | | Confirmed Decisions | shared | all | Resolved decisions |

The Dispatch Loop

The orchestrator follows this core loop:

Orchestrator Loop:
  1. pomelo dispatch <feature-id> --json
     → Read alignment status, tasks, notifications, parallelGroups
  
  2. Dispatch sub-agents for each parallelGroup:
     → Each sub-agent runs: pomelo consume <feature-id> --role <role> --json
     → Sub-agent executes work based on consumed context
     → Sub-agent writes back: pomelo ingest ... --role <role>
  
  3. pomelo truth <feature-id> --json
     → Refresh truth after sub-agent contributions
  
  4. pomelo align <feature-id> --json
     → Check gate: ready_for_dev? ready_for_plan? not_ready? blocked?
  
  5. If not aligned → repeat from step 1
     If aligned → pomelo plan <feature-id> --for all --json → start coding

End-to-End Example

A complete workflow for "Checkout timeout retry" feature:

# 1. Route the requirement
pomelo route --title "Checkout timeout retry" --content "Preserve cart on timeout, show retry CTA" --json

# 2. Decompose and ingest by role
pomelo ingest feat-checkout-resilience --role pm --title "Business rule" \
  --content "Cart state must survive timeout; user stays on checkout page" --kind markdown
pomelo ingest feat-checkout-resilience --role backend --title "Retry API" \
  --content "POST /checkout/retry — idempotent, accepts cartId" --kind api_doc

# 3. Build truth
pomelo truth feat-checkout-resilience --json

# 4. Get orchestration instructions
pomelo dispatch feat-checkout-resilience --json
# → tasks: designer should provide user_flows, backend should provide api_contracts
# → parallelGroups: [["pm"], ["designer", "backend"], ["frontend"], ["qa"]]

# 5. After designer and backend complete their work...
pomelo truth feat-checkout-resilience --json
pomelo dispatch feat-checkout-resilience --json
# → tasks: frontend should provide frontend_contracts, qa should provide acceptance_criteria

# 6. After all roles contribute...
pomelo align feat-checkout-resilience --json
# → gate: "ready_for_plan"

# 7. Generate plans and start coding
pomelo plan feat-checkout-resilience --for all --json

Sub-Agent Protocol

Each role-specific sub-agent follows this standard protocol:

Sub-Agent Protocol:
  1. pomelo consume <feature-id> --role <my-role> --json → get context
  2. Check notifications → handle decisions/changes
  3. Execute role-specific work
  4. pomelo ingest <feature-id> --role <my-role> ... → write back
  5. pomelo truth <feature-id> --json → refresh truth

Alignment Gates

The pomelo align command returns one of four gate states:

| Gate | Condition | Action | |------|-----------|--------| | ready_for_dev | All core sections status = confirmed | Start implementation | | ready_for_plan | All core sections at least draft | Proceed to pomelo plan | | not_ready | Any section status = missing | Continue dispatch loop | | blocked | High-severity open issues exist | Address blockers first |

Skills for Agent Teams

Pomelo provides role-specific skills:

| Skill | Purpose | |-------|---------| | pomelo-protocol | Core protocol for any Pomelo user | | pomelo-orchestrator | Master agent orchestration — dispatch loop, sub-agent coordination | | pomelo-frontend-agent | Frontend role — components, UI logic, frontend contracts | | pomelo-backend-agent | Backend role — APIs, services, data models | | pomelo-qa-agent | QA role — acceptance criteria, test scenarios | | pomelo-designer-agent | Designer role — user flows, screens, interactions |

Lightweight Defaults

• sources/ is the only required evidence layer; analysis/ is optional
• plans/ are disposable outputs, not long-lived truth
• Agents should prefer --json and compact summaries before opening full Markdown files

Development

Install dependencies:

npm install

Build:

npm run build

Use after publishing:

npm install -g pomeloflow
pomelo status

Or without a global install:

npx pomeloflow status

Check the publish payload:

npm pack --dry-run

Publish:

npm publish