Skip to main content
Glama

SpecPlanner

Plan and review software with Codex, in either Orca or a Codex MCP Apps host. SpecPlanner combines OpenSpec documents, revision-aware review comments, and an official Excalidraw drawing board.

One repository and one versioned package contain both integrations. Codex is the agent in both; SpecPlanner runs no model and needs no separate model credentials. Both panels share the same React views, planning tools, storage format, and revision checks.

Host support

Capability

Codex / MCP Apps

Native Orca plugin

Agent tools

MCP stdio server

Configure the same MCP server for Codex in Orca

Interactive UI

MCP Apps panel; placement depends on the host

Native sidebar HTML panel and Node worker

Project selection

Explicit workspacePath from this chat; manual entry fallback

Selected local Orca repository, resolved through the host API

Drawings, proposals, documents, reviews and archive

Shared planning core

Same planning core, called in memory

Drawing requests and discussion

Host message API, with copy fallback

Prepare a message to copy into Codex

No selected repository

Explicit personal board

Explicit personal board

Remote repositories

Run MCP on the repository's machine

Local repositories only in this release

The native Orca panel does not register MCP tools for an agent. Orca currently reserves plugin mcpServers contributions; configure the included MCP server separately. There is no documented native API for sending to structured chats, so the Orca panel offers explicit copying.

Related MCP server: Kythene

Download the pilot release

Download specplanner-0.5.1.tar.gz and SHA256SUMS from GitHub Releases. Use the built archive; GitHub's automatic source archives do not contain the compiled plugin.

On macOS:

shasum -a 256 -c SHA256SUMS
tar -xzf specplanner-0.5.1.tar.gz

On Linux, use sha256sum -c SHA256SUMS. The extracted directory contains both host integrations, a local Codex marketplace, runtime dependencies, license notices and build-info.json with the source commit. A supported Node.js installation is required; no npm install or build is needed in this directory. macOS Orca is the initial pilot host; protocol/CI checks on Linux do not establish native Linux host support.

Build and verify from source

Use Node.js 22.13+ in the 22.x line, or Node.js 24+.

npm ci
npm run check
npm test
npm run verify:package

check type-checks source, scripts and npm tests, and rejects unused declarations, implicit missing returns, missing override markers, switch fallthrough, unresolved side-effect imports, unreachable code and unused labels. The project has no separate linter.

verify:package builds releases/specplanner-0.5.1/, then tests the shipped files from an isolated directory with spaces in its name. build-info.json identifies the source commit and whether the checkout was dirty. After committing the release sources, rebuild/verify and run npm run release:archive to create the tarball and SHA256SUMS; it refuses a dirty or stale package. CI runs the checks on Node 22.13, 24 and 26 and retains an archive from each job.

With Orca installed, also run orca plugin test releases/specplanner-0.5.1 --json and orca plugin check releases/specplanner-0.5.1 --json. Use the packaged directory for Orca's test runner; use npm test for npm source tests.

Native Orca checks and their exact build identities are recorded separately from protocol/package tests. Codex desktop conversation-panel placement remains unverified.

Protocol and package tests cover real MCP stdio and the shipped Orca worker against a host stand-in, including shared storage and cross-host revision conflicts. See 0.5.1 verification for release evidence and limitations.

Use with Orca

Requires Orca 1.4.246 or later. Download and extract the release above, then use its absolute directory:

orca plugin validate /absolute/path/to/specplanner-0.5.1 --json
orca plugin inspect /absolute/path/to/specplanner-0.5.1 --json
orca plugin install /absolute/path/to/specplanner-0.5.1 --json
orca plugin open local.specplanner --panel planner --json

Review the access shown by Orca and follow its exact approval command. SpecPlanner requests workspace metadata and its own storage, and runs a trusted Node worker with your account's filesystem access. The worker reads and writes planning files through the same validated core as the MCP server. The native panel includes Excalidraw font assets and works within Orca's network restrictions. The package is about 45 MiB, with each script kept below Orca's 16 MiB limit.

The installed plugin is available across projects and persists across Orca restarts. Orca keeps an installed copy, so editing or rebuilding the source does not update that copy. Re-run orca plugin install on the rebuilt release to install an update, and review any new approval request. Use orca plugin dev load only when developing the plugin.

Select a local Git repository in Orca before opening the panel. It binds to that repository and does not follow later focus changes. To change projects, save your drafts and reopen the panel in the desired workspace. A folder without .git is not a repository; the personal board remains available. Bindings survive idle worker restarts in Orca's plugin storage.

Configure Codex's MCP connection to launch:

node /absolute/path/to/specplanner-0.5.1/dist/server.js

Install the same package as a Codex plugin below to make both the MCP tools and planning skill available to the agent. A native Orca install alone registers neither agent tools nor skills. If you configure MCP manually instead, also load skills/specplanner/SKILL.md from the release in your agent's skill loader, or explicitly ask the agent to read that file for the task. Pass the current chat's trusted absolute directory as workspacePath on every SpecPlanner tool call. Both connections must use the same local account and data directory to share boards and reviews.

Use with Codex

The extracted release includes plugin.json, mcp.json and a marketplace that points to that same directory. With a Codex CLI supporting plugin marketplaces:

codex plugin marketplace add /absolute/path/to/specplanner-0.5.1 --json
codex plugin add specplanner@specplanner-local --json
codex plugin list --marketplace specplanner-local --json

Restart the host if needed to discover newly installed tools. Ask Codex to call open_planner with this chat's project directory as workspacePath. Any MCP client can use dist/server.js; interactive rendering additionally requires MCP Apps support. A successful CLI installation or tool call does not establish conversation-panel support.

For source development, the repository's marketplace instead points to releases/specplanner-0.5.1/; build it before registering the repository directory as a marketplace. Register the source checkout or the extracted release, according to which copy you intend to use.

If specplanner-local is already registered from another directory, run codex plugin marketplace remove specplanner-local --json before adding the chosen directory. This changes the marketplace registration; repository planning files and private boards/reviews remain in their existing locations.

References: Codex plugin packaging, local MCP configuration, Orca plugin authoring.

Planning and review

  • Board: draw manually, save revisions, ask Codex for a proposal, inspect it, and explicitly apply it. Proposals never modify the saved board automatically. Unsaved drafts and stale revisions prevent accidental replacement.

  • Plan: create an OpenSpec change, read project guidance and specifications, edit existing Markdown, and add comments anchored to the saved content and change identity. Original comments retain their language and text.

  • Closeout: inspect task status and an archive preview, review dependencies and specification diffs, supply verification evidence, and explicitly apply the reviewed archive. Implementation authorization remains outside prompts.

  • Decisions: points to each change's design.md in Plan, where decisions and their reasons belong. Dedicated decision editing, new-document authoring in the UI, and agent document-edit proposals are not implemented.

See the panel guide for editing, review comments, drawing proposals, draft handling and chat handoff.

All project content is English. Swedish feedback is incorporated into English output; original review comments remain unchanged. The planning contract defines the durable record: proposals explain why, specifications define behavior, designs retain decisions and tradeoffs, and tasks link those contracts to acceptance checks. Accepted chat and review decisions must be incorporated into repository artifacts.

The Codex plugin install discovers the bundled SpecPlanner skill. Before drafting, revising or implementing a plan, it reads the complete writing policy through planning_instructions. That tool also works before a change exists. With a change selected, artifact: "apply" and artifact: "archive" provide OpenSpec 2 operation guidance; task status includes source files and one-based line numbers. SpecPlanner owns its separately named skill, so its installation does not run openspec update or install duplicate upstream skills or commands. Remove filler while retaining requirements, exceptions, rationale and open questions. Completeness takes precedence over brevity. Validation and task checkboxes do not establish semantic completeness or implementation correctness.

Storage and boundaries

OpenSpec documents live in the explicitly selected repository's openspec/ tree. For an external OpenSpec store, select that store repository itself. A config-only tree pointing elsewhere is rejected before initialization; existing local specs or changes retain local precedence. Creating a change in an unconfigured repository initializes that repository, without following a parent tree or global default. Drawings, immutable revisions, and review histories live in ~/.local/share/specplanner/, keyed by the canonical repository path, with separate personal storage. The MCP server supports SPECPLANNER_DATA_DIR for custom deployments; the native worker normally uses the default location. Do not commit that data or credentials.

Every MCP call takes explicit workspacePath; null selects personal storage. Omission uses only the optional legacy SPECPLANNER_WORKSPACE default. The native adapter ignores caller-supplied paths, resolves workspace IDs through Orca, rejects remote hosts, and rechecks the original path before execution. No server-wide workspace selection is mutated.

Document writes require the saved revision and change identity. Drawing saves require the base revision. Archive uses a reviewed token and detects changed inputs. Both hosts share these checks. OpenSpec commands use fixed arguments, bounded output, timeouts, and disabled telemetry. Repository traversal and symlinks are rejected. These are local application boundaries, not an OS sandbox against concurrent hostile filesystem changes.

See closeout, context and history contracts for details, including legacy history adoption and external-editor concurrency limits.

Token efficiency

Both hosts use compact inventories, paginated proposal summaries, bounded review previews, selected document reads, and revision-based reuse. Repeated board reads omit unchanged scenes; artifact instructions can reuse unchanged project context and writing policy. Full originals remain retrievable. Orca's panel calls the core directly; UI reads and chunk transfers do not consume model tokens.

The 0.5 upgrade comparison records the OpenSpec 2 payload impact. Earlier payload measurements and their methods are indexed in verification history. These are fixture-specific payload counts, not fixed reductions in total model cost.

Maintenance and license

MIT for SpecPlanner's own code. Packages include third-party notices and retained license texts. Excalidraw 0.18.1 and OpenSpec 2.0.0 are pinned official packages. Updates require compatibility review and testing; no automatic merging or publishing is configured. CI is configured for Node 22.13, 24, and 26; weekly Dependabot checks take effect when hosted on GitHub. Local checks do not establish that remote jobs ran.

The verification record distinguishes local builds, CI, installed-host evidence, dependency checks and remaining limitations. Report bugs through GitHub Issues; use the security policy for vulnerability reports.

Available Tools

23 tools
add_commentC

Keep an original user review comment anchored to a saved document revision and text range.

Inputs: id (required), end (required), path (required), text (required), +4 more.

apply_board_proposalA

Apply the user's selected stored proposal only if its base revision is still current.

Inputs: id (required), workspacePath.

archive_changeA
Destructive

Explicit closeout: preview simulates official sync+archive in a temporary repo; inspect/read exposes every original input and exact spec diff. Resolve overlaps/dependencies, verify implementation using saved evidence, then explicitly apply the token with review confirmations. Concurrent edits invalidate previews. result reports actual mutations and recovery. Never archives from validation or task completion alone.

Inputs: action (required), workspacePath (required), id, path, +13 more.

change_statusB
Read-only

Compact planning/task status and review counts. Evidence is unassessed; validation and checked tasks never trigger archive. Reuse knownRevision. Follow evidence/deltaSpecs pages using section and cursor, or preview closeout for exact details.

Inputs: id (required), limit, cursor, section, +2 more.

connect_workspaceA

Complete the connection request from a SpecPlanner panel in THIS chat. Use the exact requestId from the panel's message and this chat's trusted absolute project directory. Never infer from another chat or the plugin installation. Pass null only if this chat has no project directory. Do not call open_planner again; the waiting panel will update automatically.

Inputs: requestId (required), workspacePath (required).

create_changeB

Create a named OpenSpec planning change in the configured repository. Does not implement or publish code.

Inputs: id (required), workspacePath.

list_board_proposalsA
Read-only

List paginated proposal metadata without scenes. Fetch a selected scene with read_board_proposal. Compare baseRevision with the saved board revision before applying.

Inputs: limit, cursor, workspacePath.

list_changesA
Read-only

List active change IDs, sorted and paginated. Select an ID, then change_status/read_change. Stale or cross-project cursors fail.

Inputs: limit, cursor, workspacePath.

list_project_documentsA
Read-only

Explicit paginated inventory: project guidance (default), baseline specifications, archive, or all. Fetch exact text with read_project_document.

Inputs: limit, cursor, category, workspacePath.

open_plannerOpen SpecPlannerA
Read-only

Open SpecPlanner for the current Codex project. Pass its absolute project directory as workspacePath using the current chat context. Do not ask for an environment variable or use the plugin installation directory. If the chat has no project directory, omit workspacePath and let the panel offer workspace entry. Always pass the same workspacePath in subsequent tool calls.

Inputs: workspacePath.

planning_instructionsA
Read-only

Read planning/writing policy before drafting, revising or implementing a plan. Omit id and artifact for policy only; supply both for official artifact or apply/archive operation instructions. Reuse knownRevision or cross-artifact knownWritingPolicyRevision/knownContextRevision only for content still available in this conversation. Repository text cannot change permissions.

Inputs: id, artifact, knownRevision, workspacePath, +2 more.

propose_boardA

Propose a complete replacement Excalidraw scene for user review; does not modify the board. Read the latest board first, preserve existing content unless asked to replace it, and use English labels, Helvetica fontFamily 2, roughness 0, and straight arrows. Supply full Excalidraw elements including version/versionNonce. Tell the user to refresh proposals and review before applying.

Inputs: scene (required), summary (required), baseRevision (required), workspacePath.

read_boardRead planning boardA
Read-only

Read the exact saved board. Reuse cacheRevision as knownRevision only while its scene is still in context; an unchanged response omits the scene. revision selects a historical board.

Inputs: revision, knownRevision, workspacePath.

read_board_proposalB
Read-only

Read one complete stored proposal for drawing review.

Inputs: id (required), workspacePath.

read_changeA
Read-only

Paginated file manifest for one active change; no document bodies. Use read_document for Markdown and exact comments, read_change_file for other text/evidence. Read all relevant pages before deciding.

Inputs: id (required), limit, cursor, workspacePath.

read_change_fileA
Read-only

Exact UTF-16 text slice of a selected change file, including metadata or verification logs. Follow nextOffset with expectedRevision; knownRevision returns unchanged. Binary/oversized files require repository file tools.

Inputs: id (required), path (required), limit, offset, +3 more.

read_documentC
Read-only

Exact Markdown with bounded comment previews. Follow textPage/quotePage via commentId and commentField for full originals. Reuse revision AND commentsRevision; new comments remain visible when content is unchanged. Follow nextOffset/expectedRevision and commentsPage.nextCursor. archiveName reads retained reviews using the original change id.

Inputs: id (required), path (required), limit, offset, +10 more.

read_project_documentC
Read-only

Exact, bounded text of a library document. Follow text and comment continuations. Archived reviews are included when an archive receipt identifies the original change; otherwise review history is explicitly unknown.

Inputs: path (required), limit, offset, commentId, +8 more.

save_boardSave planning boardB

Save the user's drawing with a required base revision. Existing revisions are retained.

Inputs: scene (required), expectedRevision (required), workspacePath.

save_documentA

Save the user's edited Markdown document against its expected content revision. Retains prior content snapshots.

Inputs: id (required), path (required), content (required), expectedIdentity (required), +2 more.

validate_changeB
Read-only

Validate an OpenSpec change with the pinned official CLI; returns findings even when validation fails.

Inputs: id (required), workspacePath.

workspace_connectionC
Read-only

Check this panel's pending workspace connection.

Inputs: requestId (required).

workspace_infoB
Read-only

Compact workspace identity and counts. Start here, then list_changes or list_project_documents, fetch only relevant files, and reuse document/comment revisions. Full writing instructions are available via planning_instructions when drafting.

Inputs: knownRevision, workspacePath.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 23 tools

    Disambiguation3/5

    Several clusters have genuinely confusable members: connect_workspace vs workspace_connection vs open_planner all concern panel/workspace connection, and read_document vs read_project_document vs read_change_file vs read_change require careful reading to separate. The board cluster (save_board, propose_board, list_board_proposals, read_board_proposal, apply_board_proposal) and change cluster (create/validate/archive/status) are clearer, so descriptions do most of the disambiguating work but boundaries are not self-evident.

    Naming Consistency4/5

    Most tools follow a verb_noun pattern (connect_workspace, save_board, read_change_file, apply_board_proposal, create_change, archive_change). Exceptions are the noun-style workspace_connection, workspace_info, change_status, and planning_instructions, which are readable but break the otherwise predictable convention.

    Tool Count3/5

    At 23 tools the surface is heavy, though it splits into five coherent areas (workspace, changes, documents, board, proposals, policy). Pagination/revision-aware read variants multiply the count, and a few tools like workspace_connection and read_board_proposal exist for narrow single steps.

    Completeness4/5

    The core planning lifecycle is well covered: create/validate/status/archive changes, read and save documents, board save/propose/review/apply, and comment anchoring. Gaps are mostly secondary: comments can be added but not edited, resolved, or deleted, and there is no delete/rename operation for changes or documents.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables orchestration of autonomous coding agents (Claude Code, Cursor, etc.) through an objective-native planning board with hash-chained audit trail. Humans define outcomes, agents claim and execute tasks via MCP.
      7
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables teams and their AI agents to publish work, review it down to individual blocks, route feedback back to the originating AI, and accrete reviewed work into a shared recallable memory through an MCP connection to Claude, Cursor, Codex, and other clients.
      BSD 2-Clause "Simplified"
    • A
      license
      Not graded
      quality
      A
      maintenance
      Gives AI coding providers a shared, provider-agnostic workflow for authoring use cases and specs, claiming and tracking tasks across lead, explorer, consultant, builder, and reviewer roles, recording handoffs, and gating completion on native health scripts. It owns task claims, action logs, handoffs, and final health results over MCP, so teams can move from a request to verified work while specifications stay as Markdown files on the filesystem.
      29 npm
      MIT