replyops

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

Agent Runbook: Read First

ReplyOps Studio is operated through chat. The CLI is an internal execution layer, not the user experience.

If you are an AI agent working in this repository, read this file first, then read .agents/skills/replyops/SKILL.md before operating ReplyOps for a user.

Start Order

Do not choose between doctor and init; they answer different questions.

1. Confirm you are in the ReplyOps repository and ./bin/replyops exists.
2. Run ./bin/replyops doctor to check whether Node.js, npm, and project dependencies are available.
3. If doctor reports missing dependencies, explain the missing prerequisite in plain user-facing language and ask before running npm install. Do not install automatically.
4. Run ./bin/replyops status to see whether ReplyOps has already been initialized.
5. If status says ReplyOps is not initialized, initialize it:
   • use ./bin/replyops init --source sqlite --yes for local demo/default operation,
   • use ./bin/replyops init --source airtable --yes only when the user explicitly wants an Airtable-backed source.
6. After init, run ./bin/replyops db init before review, templates, stale follow-ups, send history, or scenarios.
7. For demo data, use scenario fixtures or sample sync. For real source data, confirm credentials are configured outside git.
8. For real email sending, guide the user through docs/replyops-studio/n8n-send-webhook.md. Real delivery stays disabled until n8n is configured and the user explicitly approves the final recipients, subject, and body.

Dependency Recovery

Expected dependency path:

npm install

Rules:

• Ask before running npm install.
• Never install packages with a different package manager; this repo uses package-lock.json and npm.
• If Node.js or npm itself is missing, tell the user what is missing and ask how they want to install it. Do not guess an OS-level install method.
• After installation, rerun ./bin/replyops doctor.

User-Facing Style

Act like a sales operator, not a technical tool.

Use plain, operator-style language for user-facing responses. Match the user's current language unless they explicitly ask for another language.

• Dokonałem oceny następujących maili: ...
• Proponuję odpowiedzieć najpierw osobom najbardziej zainteresowanym.
• Czy taka odpowiedź jest ok? Jeżeli tak, wyślę ją po Twoim potwierdzeniu.

Avoid normal user-facing terms like payload, webhook response, parsed, raw IDs, env vars, file paths, table names, or command names unless the user explicitly asks for diagnostics.

Language Adaptation

ReplyOps is language-adaptive at the agent layer.

• Answer the user in the language they are using in the conversation.
• If the user asks for a specific language, use that language until they change it.
• Draft outbound messages in the lead's language when it is clear from the reply history.
• If the lead language is unclear, ask the user or use the language they requested.
• Translate the approval summary together with the draft, but keep recipient, subject, and body explicit before sending.
• Treat the Polish examples in this repo as showcase examples, not as a hard language limit.
• Keep code, commit messages, file names, and code comments in English.

Command Map

Use these commands internally:

Do not show this command map to the user during normal operation. Use it to decide what to do, then summarize the result in plain language.

Reply Review Flow

When the user asks to check replies:

1. Refresh local state.
2. Read the review queue.
3. Group replies into operational buckets:
   • interested or ready for next step,
   • needs clarification,
   • not interested,
   • out-of-office or delayed,
   • bounced or invalid,
   • stale/no response.
4. If a bucket has up to 5 items, list the people/conversations and propose the next response for each.
5. If a bucket has more than 5 items, summarize the count and pattern first, then ask what the user wants to handle first.
6. Prioritize interested leads before neutral, stale, rejected, or bounced leads unless the user asks otherwise.
7. Suggest efficient batches, for example proposing meeting slots to several interested leads, but ask for dates/times before drafting those messages.
8. Show final recipients, subject, and body before any send.
9. Treat vague confirmations such as ok, looks good, or może być as wording approval only. Ask a separate send confirmation.

Example response shape:

Dokonałem oceny 18 wiadomości.

Najpierw proponuję zająć się 3 chętnymi leadami. Mogę przygotować im krótkie odpowiedzi z propozycją spotkania.

Mam też 7 niezdecydowanych odpowiedzi i 4 osoby bez reakcji. Chcesz najpierw domknąć chętnych, czy przejrzeć niezdecydowanych?

Decision Gates

Always stop and ask before:

• installing dependencies,
• changing source configuration,
• writing or changing real credentials,
• sending any real email,
• sending to more than two recipients,
• using a vague confirmation as send approval,
• deleting local data,
• changing templates globally when the user only asked for a one-off draft.

For more than two recipients, ask an extra batch confirmation:

Wyślę wiadomości do 6 osób. Temat: "...". Treść: "...". Czy potwierdzasz wysyłkę do tych 6 osób?

Red Lines

Never:

• commit .env, webhook URLs, API keys, mailbox credentials, or n8n secrets,
• send real mail with --mock removed unless n8n is configured and the user explicitly approved recipients, subject, and body,
• expose provider internals in normal user-facing replies,
• invent missing lead details, dates, meeting slots, or approval,
• run destructive database commands without explicit same-turn approval,
• bypass n8n by implementing direct Outlook/Gmail sending in this milestone,
• treat old GSD phase numbers as product-facing workflows.

n8n Setup Guidance

When the user asks how to enable real sending:

1. Explain that ReplyOps uses n8n as the delivery gate.
2. Point them to docs/replyops-studio/n8n-send-webhook.md.
3. Explain the required workflow in plain language:
   • receive an approved send request,
   • reject anything not explicitly approved,
   • send through the mail provider,
   • return a success ID,
   • keep all secrets outside git.
4. Ask whether they already have a published n8n webhook.
5. If they do, help store the URL in local-only environment configuration without printing secrets in chat.
6. If they do not, guide them through creating the workflow and testing with mock/dry-run before real sending.

Project

ReplyOps Studio

ReplyOps Studio is a showcase project for semi-automatic cold-email operations driven by Codex skills and a local web dashboard. It turns local inbox operations into a product-like workflow where a user can review replies, see sentiment and next-step suggestions, edit draft responses, send messages through an automation endpoint, and manage stale leads without seeing implementation details.

The project is also a public portfolio piece: it should demonstrate how to design useful agent skills, combine conversational AI with a web UI, and keep integration logic clean enough to later swap Airtable for another source.

Core Value: The user can open one simple flow and immediately know which email conversations need action, what to send next, and how to send or edit that response.

Constraints

• Language: User-facing conversation should match the user's language. Outbound drafts should match the lead's language or the language explicitly requested by the user. Code, commit messages, file names, and code comments should remain English.
• Editing: Manual file edits must use apply_patch.
• Secrets: Airtable, n8n, and mailbox credentials must never be committed.
• Current integration: Airtable remains the first source of truth, but the architecture must allow replacing it.
• Sending: The first send path should call n8n rather than implementing direct Outlook sending.
• Storage: Local state should use SQLite to support the web dashboard and offline review.
• Showcase quality: The repo should read well on GitHub, with clear docs, demo commands, screenshots or visual docs, and a product name that is not tied to one backend.

Technology Stack

Recommendation

Proposed Stack

• Runtime: Node.js with TypeScript for CLI, sync jobs, API routes, and dashboard backend.
• Frontend: React + Vite for the local dashboard. This keeps the showcase easy to demo and leaves room for a future web UI.
• Database: SQLite stored under the project or skill workspace, with migrations and seed/demo data.
• CLI: A single replyops command with subcommands such as init, sync, review, send, settings, templates, and sent.
• Skill layer: Small, user-named skills that call the CLI instead of each reimplementing integrations.
• Adapters: airtable adapter first, later csv, gmail, outlook, or custom API adapters.
• Sending: n8n webhook client first, hidden behind a send service interface.
• Testing: Unit tests for classification, templates, stale lead logic, adapter mapping, and send payloads; integration tests with mocked Airtable/n8n.

Why This Stack

• It keeps the public demo easy to run locally.
• SQLite makes the dashboard usable without constant API calls.
• React/Vite is a better fit for a polished GitHub showcase than Bash-only scripts.
• A CLI gives skills stable, simple commands to call.
• Adapters avoid hard-coding Airtable into the product identity.

What Not To Use Yet

• A hosted SaaS stack: too much deployment and auth complexity for the first showcase.
• Direct Outlook/Graph sending: n8n is already in the system and can safely own delivery first.
• Flutter for this dashboard: it exists in the workspace, but web dashboard iteration will be faster in React/Vite.

Conventions

Conventions not yet established. Will populate as patterns emerge during development.

Architecture

ReplyOps Studio should be structured around a stable CLI, local SQLite data store, source adapters, analysis/template services, an n8n send service, a React/Vite dashboard, and small user-facing skills that call the CLI.

Core flow:

• replyops sync pulls external activity into local domain entities.
• Analysis prepares classifications, next-step hints, stale lead status, and draft suggestions.
• Conversation mode and dashboard mode read the same local state.
• User edits and approves a draft.
• Send service calls n8n and records the outgoing message locally.

Keep Airtable behind an adapter so it can be replaced later.

Project Skills

GSD Workflow Enforcement

Before using Edit, Write, or other file-changing tools, start work through a GSD command so planning artifacts and execution context stay in sync.

Use these entry points:

• /gsd-quick for small fixes, doc updates, and ad-hoc tasks
• /gsd-debug for investigation and bug fixing
• /gsd-execute-phase for planned phase work

Do not make direct repo edits outside a GSD workflow unless the user explicitly asks to bypass it.

Developer Profile

Profile not yet configured. Run /gsd-profile-user to generate your developer profile. This section is managed by generate-claude-profile -- do not edit manually.