manus-research

Manus Research

Delegate user story creation, requirements gathering, and discovery research to a Manus.im agent. The agent produces a markdown document; this skill imports it into the project so Claude Code can implement against it.

The primary use case: the user describes a feature, Manus produces structured stories/requirements, Claude Code reads them and writes the code.

When to use

• User asks for user stories for a feature ("user stories para checkout com cupons")
• User asks to gather requirements (functional and non-functional) for a feature
• User asks for a discovery brief before implementation ("levanta requisitos para chat em tempo real")
• User wants a comparative analysis or state of the art as input to a plan
• User explicitly mentions Manus / manus.im / /manus-research

When NOT to use

• For local code questions, refactors, or debugging — use Claude directly.
• When the user already has the markdown — read it and implement against it directly.
• For real-time facts the Manus agent cannot fetch — use WebSearch / WebFetch.

Prerequisites (one-time setup)

1. Get a Manus API key: https://manus.im/app?show_settings=integrations&app_name=api → "Create API Key"
2. Store it locally:

   mkdir -p ~/.credentials/manus && chmod 700 ~/.credentials/manus
   echo "<KEY>" > ~/.credentials/manus/api-key && chmod 600 ~/.credentials/manus/api-key
   

   Or export MANUS_API_KEY in your shell.
3. Required CLI tools: curl, jq (install with your package manager).

Workflow

1. Refine the prompt with the user. A good Manus prompt for stories/requirements is specific:
   • Feature scope (what is in / out of scope)
   • Personas / actors (who uses it)
   • Required output sections (e.g. "1. Stories, 2. Acceptance criteria, 3. Non-functional, 4. Edge cases, 5. Open questions")
   • Format — suggest INVEST + Given/When/Then if appropriate, but let the user decide (some prefer narrative, MoSCoW, job stories, etc.)
   • Constraints ("PT-BR", "max 1500 words", "cite sources where possible")
2. Confirm the output path with the user. Default: docs/research/<slug>.md in the current working directory.
3. Run the orchestrator script (it handles: create task → poll → save markdown):

   ${CLAUDE_PLUGIN_ROOT}/scripts/manus_research.sh "<prompt>" [output_path]
   

   The script prints progress to stderr and the final path to stdout.
4. Read the saved file with the Read tool and summarise key findings to the user (3-5 bullets covering: stories produced, biggest unknowns, risks, dependencies).
5. Offer next step: ask if they want you to implement (start coding) or to enter plan mode first.

Output convention

The saved file has YAML frontmatter for traceability:

---
source: manus.im
task_id: <id>
task_url: https://manus.im/app/<id>
title: <task title from manus>
generated_at: <UTC ISO timestamp>
prompt: |
  <original prompt>
---

<agent markdown content>

This frontmatter lets you re-open the live Manus session if the user wants to ask follow-ups.

Suggested formats (offer to user, do not impose)

When the user is unsure how to structure stories/requirements, offer one of these formats. Do not force a format if they want something else.

A) Classic user story + acceptance criteria (INVEST + Given/When/Then)

## Story 1 — Login com Google
**Como** um visitante
**Quero** entrar com a minha conta Google
**Para** evitar criar mais uma password

### Acceptance criteria
- **Given** estou na pagina de login
  **When** clico em "Entrar com Google" e autorizo
  **Then** sou redirecionado para o dashboard com sessao iniciada
- **Given** estou na pagina de login
  **When** cancelo a autorizacao Google
  **Then** volto a pagina de login com mensagem "login cancelado"

### Edge cases
- Email Google ja existe com password local: ofereco merge de contas
- Token Google expirado: refresh automatico ou redirect para re-auth

B) Job story (jobs-to-be-done)

**When** I land on the product page after a marketing campaign,
**I want to** add the item to cart in one click without creating an account,
**So I can** check out fast while the intent is high.

C) Requirements list (MoSCoW)

## Functional
- **Must**: ...
- **Should**: ...
- **Could**: ...
- **Won't (this iteration)**: ...

## Non-functional
- Performance: ...
- Security: ...
- Accessibility: ...

Tips for good prompts

• Be specific about scope: "user stories para checkout com cupons e split de pagamento" beats "stories para checkout".
• Name the personas: anonymous visitor, registered user, admin, etc.
• Ask for structure: tell Manus the section headings you want.
• Set expectations: "no fluff, max 1500 words, list edge cases explicitly".
• Iterate: if the first output is shallow, ask the user to confirm scope refinement and re-run with a sharper prompt.

Cost

Each task consumes Manus credits (typically 1-10+ depending on depth). Free tier provides ~1000 credits + 300/day. Long research tasks (deep web browsing) consume more.

Errors

• MANUS_API_KEY not set — set the env var or create ~/.credentials/manus/api-key.
• task ended with error — surface the JSON error to the user; ask if they want to retry with a refined prompt.
• task stuck in 'waiting' for Ns — the agent paused waiting for input for more than MANUS_WAITING_GRACE_SEC seconds (default 60s). Brief waiting is transient and tolerated; only persistent waiting aborts. Share the live task_url so the user can answer in the Manus UI.
• timeout — the task is still running after 15min. The user can extend with MANUS_TIMEOUT_SEC=1800, or check the live URL.
• permission_denied — wrong or revoked API key; ask the user to regenerate at https://manus.im/app?show_settings=integrations&app_name=api

Security

• Never commit ~/.credentials/manus/api-key.
• Never echo the API key to the conversation or any file inside the project.
• The orchestrator script reads the key only from env or the credentials file.