How Scope Architect works

Scope Architect turns a raw idea into an agent-ready specification in four steps. The whole loop takes minutes, not hours.

1. Drop in your idea— paste raw notes, a bullet dump, a Linear ticket, or a one-liner. Format doesn’t matter. The engine parses intent, not structure.
2. Recursive decomposition— the engine expands your idea into modules → features → atomic tasks. Each task gets an effort level, complexity signal, and acceptance criteria. No task larger than one agent session.
3. Refine in Architect Chat— talk to the AI to adjust scope. “Split the auth module into two.” “Add edge cases for rate limiting.” “Make the Stripe tasks more granular.” Preview the diff, apply in one click.
4. Execute with your agent — connect via MCP (recommended) so the agent reads and updates the live blueprint, or copy a single task / export JSON or Markdown when you need a one-off handoff.

The recursive engine is what separates Scope Architect from one-shot spec generators. It decomposes your idea in passes, each pass going one level deeper until every task is truly atomic.

How decomposition works

Pass 1 identifies top-level modules — the major work areas in your project (e.g., Auth, Billing, Dashboard, API). Pass 2 expands each module into features. Pass 3 decomposes each feature into atomic tasks — independently executable units with no hidden dependencies.

Effort levels

Every task gets an effort level that signals complexity to your agent. You can override effort levels per-task in the builder view, or retune the underlying constants in Builder Profile.

Dependency graph

The engine automatically detects and surfaces task dependencies — which tasks must complete before others can start. The handoff export includes this graph so your agent executes in the right order without follow-up questions.

Architect Chat is a live editing interface for your spec. Describe what you want to change in plain English — the AI proposes a structured diff, you preview it, and apply in one click. No manual data entry.

Useful prompts

• “Add a module for background job processing with BullMQ.”
• “Make all the Stripe tasks more granular — break them into atomic steps.”
• “Flag the third-party integrations as high risk.”
• “Write sharper acceptance criteria for the auth tasks.”
• “Remove the mobile app module — we’re web-only for now.”
• “Reorder modules so infrastructure comes before features.”

Builder Profile is your global configuration. It tells the recursive engine about your stack, your preferred agent, how you estimate, and what code style to target. Every scope you generate inherits these defaults — but you can override them per-project.

Access it from Settings → Builder profile in the app (https://app.scopearchitect.com/settings/profile). Changes apply to new generations immediately.

Core fields

Multiple profiles

Builder (paid) and Team plans support unlimited Builder Profiles — useful when you work across multiple stacks or projects. Switch profiles from the project sidebar. The active profile is shown in the top nav.

Each project has a knowledge layer your agents read on every MCP session. Humans edit it in the Context tab; agents maintain it via MCP when decisions must outlive a single session.

MCP is the recommended path. Your IDE agent runs a local stdio server (@scope-architect/mcp) that talks to app.scopearchitect.com with a handoff API key. The plan stays live — status, acceptance criteria, comments, memory, and docs update in both directions.

Setup (in the app)

1. Open Settings → MCP (requires MCP access — see Team roles).
2. Generate a team key (sa_handoff_…, all projects) or a project key (psa_…, one project). The raw key is shown once; we store only a hash.
3. Pick your client (Claude Code, Cursor, VS Code, Windsurf, Codex, Gemini CLI, or generic JSON) and copy the tailored config snippet.
4. Restart the agent so it loads the MCP server. On connect, call get_project to load the knowledge briefing + full scope JSON.

What agents can do (30 tools)

Prefer UUIDs from get_project when updating tasks. Builder notes on tasks are human-internal and are not exposed to agents.

Claude Code skill (optional)

For Claude Code / Claude Desktop, install the standing workflow skill: npx skills add scope-architect/agent-skills. Cursor and other clients rely on MCP tool descriptions and the briefing from get_project.

Manual handoff (no MCP)

From the scope header, open Agent Handoff to copy one task or export the project as JSON or Markdown, tuned for Cursor, Claude Code, Devin, Windsurf, or generic agents. Use this for agents without MCP, CI scripts, or quick one-offs. Manual exports do not write status back — MCP keeps the workspace authoritative.

Projects are saved to the cloud automatically — they survive device switches, cleared caches, and deploys. You never need to hit “Save.”

Project management

Views

The same scope is available as a blueprint tree, kanban, list, and activity feed. Task drawers hold details, comments, and per-item Architect chat.

Task statuses

Agent-ready & handoff

Mark tasks agent-ready when they should appear in MCP and exports. Use Agent Handoffon a task for a one-click copy of that task’s prompt. With MCP, prefer get_next_ready_task and update_task_status so the board stays in sync.

Workspaces are team-scoped. Every user has one of four roles. Invite and manage members at Settings → Team (admins and owners only).

Member permissions (optional toggles)

Owners and admins can open Manage access on a member row and enable granular capabilities:

• Create projects — start new scopes
• View usage — see credit usage on the team page
• API keys — BYOK provider keys
• MCP — generate handoff keys and open MCP setup
• Coding tools — “Open in” agent/IDE dispatch
• Builder profile — edit team Builder profile defaults

Admins and owners always have these capabilities. Settings pages you cannot access show an access-required state instead of the configuration UI.

Bring Your Own Keys (BYOK) is available on Builder and Team plans. With BYOK, all AI requests are routed through your own API keys — you pay providers directly at their published rates with zero markup from Scope Architect.

Configure keys at Settings → API keys (requires API key access on your role). Supported providers include Anthropic, OpenAI, Google, xAI, and DeepSeek — choose models in Builder profile or per chat.

How it works

1. Paste your provider API key in Settings → API keys.
2. Keys are encrypted at rest and never logged in plaintext.
3. Architect Chat and scope generation use your key when BYOK is enabled on your plan.
4. You pay the provider directly; Scope Architect does not markup provider usage.