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 the conversational surface for your whole build. Talk to it to interrogate and edit the scope, read your connected codebase, and queue or launch cloud runs — all from one thread, with a live run rail beside the conversation. Nothing changes or executes until you approve the card it proposes.

Useful prompts

• “Add a module for background job processing with BullMQ.”
• “Make all the Stripe tasks more granular — break them into atomic steps.”
• “Look at how auth works in the repo and tighten the auth tasks to match.”
• “Write sharper acceptance criteria for the auth tasks.”
• “Queue everything that’s agent-ready in the payments module and start the first run.”
• “What’s running right now, and what’s up next in the queue?”

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

One profile per workspace

Each workspace has a single shared Builder Profile, so every teammate and agent scopes against the same defaults. Need a different stack for one project? Override it in that project’s configuration — it creates a project-specific copy without touching your other projects.

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 (36 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.

Cloud Runs execute scoped tasks without your machine. Dispatch an agent-ready task and a fresh, isolated VM spins up for the run; the agent builds inside it, and the run ends in a pull request against your linked repo. Your project’s workspace persists on a saved disk between runs, so the next run resumes instantly — nothing sits idle in between.

How a run works

1. Link a GitHub repo to the project and enable its cloud workspace.
2. Connect an agent CLI (Claude Code or Grok) in Settings → Cloud Agents.
3. Dispatch an agent-ready task to a cloud run from the workspace.
4. Follow the run live in the Command Center — status, logs, and comments update as the agent works. If it needs input, reply in the task’s comments and the run resumes.
5. Review the pull request the run opens against your repo.

Concurrent runs

Builder includes 1 concurrent run across all your projects; Team includes 1 per seat — one run per project at a time. Extra concurrent runs are a $19/mo add-on in Settings → Cloud Runs.

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.