Hands-on guides for turning informal requirements into production-ready technical specifications.
Tutorial covering the @devspeak/cli npm package: global installation, API key authentication via devspeak login, translating text from arguments or stdin, attaching local PDF and Markdown context with --file, and wiring the CLI into a CI pipeline using the DEVSPEAK_API_KEY environment variable.
Step-by-step DevSpeak tutorial that converts an informal stakeholder request into a formal technical specification. Covers the four translation parameters (target audience, tech context, output format, verbosity tone), the three-stage Optimize/Translate/Refine workflow, and how to verify the generated output.
Setup tutorial for the @devspeak/mcp Model Context Protocol server. Covers generating a DevSpeak API key, adding the stdio server block to Claude Code settings.json, Claude Desktop claude_desktop_config.json, Cursor .cursor/mcp.json, and Windsurf mcp_config.json, verifying the connection with the auth_confirm tool, reading tier and quota data with get_account_info, and diagnosing the common failure modes: missing DEVSPEAK_API_KEY, an unlisted server, and a 401 from a revoked key.
Tutorial on grounding DevSpeak MCP translations with Context Projects. Explains why MCP tools differ from DevSpeak's fixed connector registry, how to create a project and add document, link, and image assets, how the context7, github, and web_search connectors supply library docs, repository context, and web results, and how to pass contextProjectId to translate_text and refine_translation. Documents fail-open grounding, where an unknown project or failed connector degrades to an ungrounded request instead of erroring, plus the asset ingestion states pending, processing, ready, and failed.
Advanced reference for DevSpeak MCP server error handling and generation control. Covers the API envelope with success, data, and error fields, the meaning of HTTP 400, 401, 403, 429, and 5xx responses, honoring the Retry-After header and retryAfter body field on rate limits, handling request timeouts on long generations, pinning a specific model with the managedModel parameter, and requesting structured XML output with responseFormat.
Workflow tutorial for the DevSpeak MCP server showing the full three-stage pipeline inside an AI IDE: optimize_text for Stage 1 lexical cleanup of a raw stakeholder message, translate_text for Stage 2 generation of an API Design with audience, context, format, and tone parameters, and refine_translation for Stage 3 iterative revision using previousOutput and feedback. Explains why Stage 1 targets raw input while Stage 3 targets generated output, when to skip Stage 1, and how summarize_input handles text above the 10,000-character limit.
Complete beginner reference for the DevSpeak Translation Editor. Documents every control: the Web Search, Output (Prose/XML), Model, and Project feature-bar controls; the Target Audience, Tech Context, Output Format, and Tone parameters; the Optimize, Translate Text, Fast AI, and Stop Generation actions; the attachments drawer (PNG, JPG, WEBP, PDF, TXT, MD up to 10 MB); the Preview, Split, and Source output modes; the Iterate & Refine panel; and the command palette — with defaults and required subscription tiers.