openproject

vbundle-v0.2.1

Sync fields, status, docs, versions and time between spec-kit and OpenProject via MCP

Community extension — Independently maintained. Use at your own discretion. Learn more

spec-kit extension: openproject

Version 0.1.0. Implemented: speckit.openproject.discover-fields, speckit.openproject.sync-status, speckit.openproject.sync-docs, speckit.openproject.sync-version, speckit.openproject.log-time. Requires the openproject preset for speckit.taskstoissues.

Install

From a release (replace the version as needed). spec-kit asks you to confirm the download source; answer y:

specify extension add openproject --from https://github.com/Nachklang-io/speckit-openproject/releases/download/extension-v0.2.0/openproject-extension-0.2.0.zip

For local development, from a clone of https://github.com/Nachklang-io/speckit-openproject:

specify extension add --dev ./extension

Install the preset in the same way (see preset/README.md), or install both with the bundle (bundle/README.md). Configure the OpenProject MCP server in your agent's MCP client config, as the preset README describes. Changes are listed in the repository's CHANGELOG.md under "Extension".

Step-by-step setup for new and existing spec-kit projects, which command to run when, and the options for automatic sync: setup guide. If a run stops or reports blocked, failed or stale items: when something goes wrong. Typical order: discover-fields once, speckit.taskstoissues after /speckit-tasks, sync-version and sync-docs when planning, sync-status after implementing, log-time when time was spent.

Automation

Every command shows a plan and asks once before it writes; there is no unattended write mode.

  • The manifest registers an optional after_implement hook for sync-status (see sync-status). The host offers the command after /speckit-implement.
  • More hooks can be added by hand to .specify/extensions.yml in the project, for example after_tasks → speckit.taskstoissues. Untested, and specify extension update or remove may rewrite the file.
  • A scheduled claude -p "/speckit-openproject-sync-status --dry-run" reports drift without writing. Headless runs were tested (discover-fields, and sync-status on earlier prompt revisions); running them from a scheduler was not.

discover-fields

Reads the target project's types, statuses, priorities, versions and mandatory custom fields through an OpenProject MCP server and creates or updates .specify/openproject/config.yml, so that speckit.taskstoissues works without hand-editing.

/speckit-openproject-discover-fields [project] [--dry-run]    # skills mode
/speckit.openproject.discover-fields [project] [--dry-run]    # command mode

Requires the MCP server jtauschl/openproject-ce-mcp (verified v0.4.1), configured as described in the preset README. The project is resolved from the argument, then .specify/openproject/config.yml, then SPECKIT_OPENPROJECT_PROJECT, then you are asked.

What a run does:

  1. Reads types, statuses, priorities, versions and mandatory custom fields (read-only) and prints an overview.
  2. Proposes the types for feature, phase and task (for example "Summary task" for phase, because a default instance has no "Phase" type) and the status names for statuses.open, statuses.in_progress and statuses.done, each with a reason. You accept or change items by number.
  3. Asks for a value for every mandatory custom field of the used types. A field you leave empty is reported and the run ends as incomplete; no placeholder is invented.
  4. Shows the changes as a numbered list and a diff. You approve all, none or a list of numbers. Only approved keys are changed; comments, key order and valid keys the command does not manage stay as they are. If the existing config is invalid (YAML or schema errors, keys unknown to the schema), all violations are listed and a rebuild is shown as a diff; the file changes only after you approve it.
  5. Writes through a temporary file and one move, so the file is either unchanged or fully written. --dry-run shows everything and writes nothing.

Run results: complete, incomplete, no changes, dry run, stopped. Re-running on an unchanged project and config reports no changes and does not touch the file.

Rules: it only reads from OpenProject, it never writes tokens, URLs or .env content, and it never deletes anything.

Limitations and untested paths

  • Interactive only; there is no non-interactive mode.
  • "Read only" is enforced by the prompt, not by the client: spec-kit does not install the tools frontmatter of an extension command in skills mode, and Claude Code's allowed-tools grants permission without restricting other tools. A session that exposes the server's write tools could call them; the prompt forbids it and the tests check that it names no write tool.
  • Custom fields of type list: the chosen title is stored as a string; whether the server accepts that on creation is untested. Custom fields of type user, multi-select, hierarchy or formatted text cannot be stored in required_custom_fields and are reported.
  • Verified against the sandbox (2026-10-06): versions with data (one open, one closed) and the per-project list of enabled types match the web UI, and so do the statuses per type (workflow of the role Member). Untested: other instances and OpenProject versions, projects with several hundred versions or types.
  • Command mode (/speckit.openproject.discover-fields) was run as a dry run and as a real bootstrap in a project set up with spec-kit's generic integration (the Claude integration installs skills only). Untested: command mode in a Claude-integration project, and the elapsed time of a skills-mode run (SC-001 was measured in command mode only: 1 min 8 s).
  • An invalid config with several violations at once, and the YAML-syntax-error case, were not run; only a single unknown key was (dry run and real rebuild).
  • Read-only handling of a project with can_update false and the redaction of secrets in server errors are checked by prompt text and string tests only, not by a live run.
  • It was not verified how spec-kit forms hook keys for extension commands, so this command has no hook check.
  • The project must be readable by the server; if it reports can_update false the run warns that write commands will fail. The server's own allowlist cannot be inspected.
  • Error text from the server is shown with URLs and host names replaced by <redacted-host>, and tokens or Authorization headers by <redacted-secret>.

sync-status

Keeps task progress consistent between the checkboxes of a feature's tasks.md and the work packages that speckit.taskstoissues created for it. OpenProject owns the status.

/speckit-openproject-sync-status [feature] [--dry-run]    # skills mode
/speckit.openproject.sync-status [feature] [--dry-run]    # command mode

Needs the config written by discover-fields (project, types.task, statuses.done) and the ledger .specify/openproject/mapping-<feature>.json of the feature. The feature is the argument, or .specify/feature.json, or the current branch.

For every task with a ledger entry it compares the checkbox, the work package status now, and the status recorded at the last sync:

SituationResult
work package done, box openbox is checked (pull)
work package reopened, box checkedbox is unchecked (pull)
box checked, work package not donework package moves to statuses.done (push), only if the server accepts the transition
box unchecked again, work package still donebox is checked again, reported as "reverted"; a work package never leaves the done status
both sides changed and disagree (for example checked locally, "On hold" in OpenProject)OpenProject wins, the report names the overwritten checkbox
status changed without changing done-ness (New → In progress)only the ledger changes; shown as "in progress"
closed but not done (for example Rejected)reported as "closed, not done"; never pushed, box unchanged
first sync of a ledger without a last synced status"baseline": a missing status counts as not done, never a conflict

A transition the server does not accept is reported as blocked (with the server's reason and the statuses available for the task type) and left alone; no intermediate statuses are tried. The assignee is recorded in the ledger and shown in the report, never written to tasks.md.

A run prints a plan table first. --dry-run shows it and writes nothing; otherwise you confirm the whole plan once. Writes: the status of task work packages (preview, then confirm, ledger updated after each), checkbox characters of tasks.md (through a temporary file and one move; nothing is written if the file changed while the command ran), and the ledger. Results: complete, incomplete (a task failed, is blocked or was skipped because tasks.md changed while the command ran), no changes, dry run, stopped. A second run on unchanged inputs reports no changes.

Optional hook: the manifest registers an optional after_implement hook (optional: true), so the host offers the sync after /speckit-implement and it never runs unasked. The offer was seen once in skills mode after a no-op implement run (see ../docs/TESTING.md).

Parent roll-up

After the task part, the command rolls the status of the phase and feature work packages up from their children (the task lines of a phase; the phases of the feature). A task counts as finished if its status is statuses.done or another closed status (for example Rejected), as in progress if it is statuses.in_progress, and as open otherwise (also On hold, and a task that is unpublished, stale or blocked or whose push did not confirm).

ChildrenRolled-up status
none (phase without task lines; feature whose phases are all ignored)none: the parent is left alone (no tasks)
all finishedstatuses.done
at least one finished or in progressstatuses.in_progress
otherwisestatuses.open

Guards, checked in this order: a parent whose work package no longer exists is stale and never recreated; a parent in statuses.done never leaves it (stays done); a parent in another closed status (closed, not done) or in a status that is none of statuses.open, statuses.in_progress and statuses.done (unmapped status) is left alone; a parent already in the rolled-up status is unchanged. Only the remaining parents are written, and only their status. This includes moving a parent from in progress back to open when none of its children is started (for example a phase set to In progress by hand); that is not a reopen, since neither status is closed. Phases are written in numeric order, the feature last, after the task pushes and the checkbox pulls; a failed task push recomputes the plan (plan changed), a parent whose status changed after the plan is not written (changed meanwhile). A valid preview does not guarantee the write: if the server rejects the confirm (for example a workflow rule it applies only when writing), the parent or task is failed, the server's answer is shown verbatim and the next run reads it again.

A task counts for the phase its work package is a child of in OpenProject (parent_id, read together with the status); without a matching phase it counts for the phase of the nearest ## Phase N heading above it (N without leading zeros). A task counted for another phase than its heading, for example one above the first heading, is named in the Parents section.

Every parent write is previewed in the same preview pass as the task pushes and is part of the one confirmation of the whole plan; --dry-run shows the Parents section and the second counts line (parents: rolled up N, unchanged N, left alone N, blocked N, failed N, stale N, skipped N) and writes nothing. When a parent gets a closed status, the server sets its percent complete to 100 (shown in the plan). A parent's percent complete is derived from its children and may already show 100 while it is open or in progress; if a closed parent is reopened by hand later, the server keeps 100. The ledger records the status of each parent after the run; its assignee is never written.

The roll-up is on by default. Set rollup_parents: false in .specify/openproject/config.yml to turn it off: then no parent is written and phase and feature work packages are shown in the report only, as before. While it is on, the command needs statuses.open and statuses.in_progress besides statuses.done (written by discover-fields, which keeps an existing rollup_parents value).

Version pairing: rollup_parents is accepted only by extension 0.2.0 and preset 1.0.2 or later. Older prompts reject the key as unknown, so update both packages together before setting it.

Limitations and untested paths

  • Interactive only. Without the roll-up (rollup_parents: false), phase and feature work packages are shown in the report only.
  • "Writes only the status" is enforced by the prompt, not by the client (same caveat as discover-fields).
  • A closed status sets the percentage done to 100 on the server (observed in the preview); the command does not touch that field itself.
  • Run so far (2026-10-06, skills mode, headless, sandbox, 7 work packages created by hand, hand-written ledger): on earlier prompt revisions (the prompt changed afterwards): pull, push, baseline, conflict, reverted, a transition the server rejects (blocked, restricted workflow), the stop conditions and the tasks.md-changed-during-the-run case (S14, S15, S16 blocked path, S17; details and defects in ../docs/TESTING.md). Untested: the label closed, not done with a Rejected work package, accepting the hook offer inside the implement flow, command mode, a stale work package, a failed single confirm, and a re-run of speckit.taskstoissues over a synced ledger. A 14-work-package feature (ledger written by taskstoissues) was synced with one confirmation in 88 s of command time.
  • Parent roll-up (feature 007): run 2026-10-10 (skills mode, headless, sandbox): S34 (all done, re-run no changes), S35 (mixed progress, stays done), S36 (closed, not done and unmapped status left alone) and S37 (switched off, no parent write); run 2026-10-11: S39 (membership by parent_id, task above the first heading), S40 (## Phase 01 heading, ledger key phase-1) and S35b (a reverted pull written into tasks.md together with the roll-up); details in ../docs/TESTING.md. Untested: S38 (a parent transition the workflow forbids), a pull of an open checkbox to a status closed in OpenProject together with the roll-up, a task line moved under another phase heading, a failed parent confirm, the stop after three tool errors, duplicate phase headings, command mode and the hook offer.

sync-docs

Publishes the design documents of a feature to its feature work package: spec.md, plan.md and, if they exist, research.md and data-model.md become attachments, and one generated summary block in the work package description lists them with a link and a short hash. Wiki pages cannot be created through the OpenProject API (ADR-0003), so attachments and the description are used.

/speckit-openproject-sync-docs [feature] [--dry-run]    # skills mode
/speckit.openproject.sync-docs [feature] [--dry-run]    # command mode

Prerequisite: the upload directory. The MCP server registers its upload tool only when it runs with OPENPROJECT_ATTACHMENT_ROOT set to an absolute directory, and it accepts only files under that directory. Set it in the MCP client configuration (not in this repo's files) to a directory that contains your project, for example the project root, and restart the server. Without it the command stops at its first step (also with --dry-run) and names the missing capability; it has no description-only fallback.

Needs the config written by discover-fields (project) and the ledger .specify/openproject/mapping-<feature>.json with the feature work package (created by speckit.taskstoissues). The command never creates a work package.

Per document it compares the SHA-256 of the file, the hash in the ledger (documents.<file>) and the attachments on the work package:

SituationResult
never synced, no attachment of that nameuploaded (new)
file changed since the last syncthe new version is uploaded first, then the outdated attachment is deleted (changed)
nothing changednothing is written, not even the ledger (unchanged)
the attachment was removed in OpenProjectuploaded again (restored)
the file no longer existsthe attachment stays, reported as orphan
an attachment of that name that the ledger does not knowblocked: nothing is written or deleted for that document; resolve it by hand
an interrupted replacement (ledger has pending_delete)the next run deletes the superseded attachment (cleaned)

The description is changed only between the markers <!-- speckit-docs:begin --> and <!-- speckit-docs:end --> (appended once if absent); all text outside is kept. The block is rendered from the ledger: file name as a path-only link, short hash (8 characters) and sync date; no excerpts. Text before the block is never trimmed. Inconsistent markers (a marker twice or missing, end before begin) stop the run before any write, also with --dry-run; repair the description by hand.

Deletion. The only thing this command deletes is the attachment it uploaded itself and replaced, identified by the attachment id in the ledger (ADR-0004, constitution principle III). It never deletes attachments it did not upload.

A run prints a plan table first. --dry-run shows it and writes nothing; otherwise you confirm the whole plan once, and the question names every attachment that will be deleted. Uploads and the description update go through the server's preview, then confirm; the ledger is written after every write through a temporary file that is read back and validated.

Limitations and untested paths

  • Interactive only; one feature per run; at most four documents; the file names are fixed.
  • OpenProject does not version attachments: "a new version" means a new attachment with the same name replaces the old one. Content changed in OpenProject by someone else is not detected (the ledger hash decides).
  • A crash between an upload and the ledger write leaves an attachment the ledger does not know: the next run reports it as blocked and deletes nothing; remove it by hand.
  • Links are paths without a host (/…/api/v3/attachments/<id>/content); they break if the instance's path prefix changes and are rewritten the next time a document changes.
  • Run so far (2026-10-06, skills mode, headless, sandbox, scratch ledger written by hand for one feature work package; the last runs on prompt revision a1d7224 after the review, the earlier ones on 42ddf12): first sync, no-change run, replacement of a changed document, restored, cleaned, blocked (foreign and ambiguous), stops for a missing spec.md and a missing ledger; a stale work package was observed once by accident (an earlier scratch work package had been deleted). The interrupted run was simulated by writing the ledger state by hand.
  • Not run: the stop for an MCP server that is not connected (two runs ended with CONNECT_TIMEOUT under host load and stopped at the capability check, which is not a planned scenario), the equality of the dry-run plan and the real-run plan (only the unchanged ledger checksum was compared), command mode, a ledger written by taskstoissues in the same run, the stop for a missing upload capability (server without OPENPROJECT_ATTACHMENT_ROOT), inconsistent markers in a real description, a truncated description, files above the server's size limit or outside the upload directory through the command, a real interruption, other instances and servers. See ../docs/TESTING.md.

sync-version

Maps a feature to an OpenProject version (creating if needed) and assigns it to the feature's work packages.

/speckit-openproject-sync-version [feature] [--version <name>] [--dry-run]    # skills mode
/speckit.openproject.sync-version [feature] [--version <name>] [--dry-run]    # command mode

Needs the config written by discover-fields (project, defaults.version) and the ledger .specify/openproject/mapping-<feature>.json (created by speckit.taskstoissues) with work packages to assign.

The version name is resolved by priority: --version argument, defaults.version from config, or the feature directory name. A version is created if it does not exist; if an existing version with that name is found, it is reused. Work packages without a version are assigned; those already in another version are reported but never moved.

A run prints a plan table first. --dry-run shows it and writes nothing; otherwise you confirm the whole plan once. Writes: the version (via create-version if new), work package target_versions (via bulk-update-work-packages with per-item fallback), and the ledger version key. Results: complete, incomplete, no changes, dry run, stopped.

Limitations and untested paths

  • Interactive only.
  • Server configuration: the MCP server must be configured with OPENPROJECT_ENABLE_VERSION_WRITE=true (same flag as ENABLE_WORK_PACKAGE_WRITE). Without it the command stops at its pre-flight check.
  • Versions with status closed or locked are reported and block assignment of any work package.
  • Re-runs are idempotent: a second run reports no changes if the version exists and all work packages are assigned.
  • The ledger records only the active version id and name; no version history is kept.
  • Not run: command mode, a version shared across projects, an instance with start/end date tracking enabled, a project without the "versions" module, an interrupted run (version created but ledger not written), closed or locked versions (not tested live), and very large work package batches. See ../docs/TESTING.md.

log-time

Logs time entries on work packages from lines of the form <task key>: <duration> [on <YYYY-MM-DD>].

/speckit-openproject-log-time [feature] [--activity <name>] [--entry-key <key>] [--dry-run] [lines]    # skills mode
/speckit.openproject.log-time [feature] [--activity <name>] [--entry-key <key>] [--dry-run] [lines]    # command mode

Needs the config written by discover-fields (project, defaults.activity) and the ledger .specify/openproject/mapping-<feature>.json with work packages. Input lines are taken from the arguments or asked for interactively.

The duration is parsed from formats like 1h30, 1h30m, 1:30, 90m, 45m, 1.5h, 2h. The date defaults to today (date +%F); dates in the future are rejected. The activity is resolved by priority: --activity argument, defaults.activity from config, or a choice from the server's activity list. Each line creates one time entry; the ledger records an entry key (work package id, date, activity and hours) to prevent duplicates on re-run. The --entry-key flag forces a deliberate second entry when all other parameters are identical.

A run prints a plan table first. --dry-run shows it and writes nothing; otherwise you confirm the whole plan once. Writes: time entries (via create-time-entry, preview then confirm) and the ledger time_entries array. Results: complete, incomplete, no changes, dry run, stopped.

Limitations and untested paths

  • Interactive only.
  • Server configuration: the MCP server must be configured with OPENPROJECT_ENABLE_WORK_PACKAGE_WRITE=true (same flag as version write). The list-time-activities call uses the read flag; it does not check whether time tracking is enabled on the project.
  • The ledger is the sole source of truth for entry identity: no re-verification against OpenProject. A re-run of an identical line is idempotent (reports unchanged); deliberate duplicates use --entry-key.
  • A crash between a confirmed time entry and the ledger write leaves an entry the ledger does not know. A re-run of that line would create a duplicate; use --entry-key to force it with a different key, or check OpenProject and add the entry to the ledger manually.
  • Not run: command mode, a project without the time-tracking module, an instance with start/end time tracking enabled, an interrupted run (entry created but ledger not written), and large batches. See ../docs/TESTING.md.

Stats

1 star

Version

bundle-v0.2.1release
Updated about 1 month ago

Install

Using the Specify CLI

specify extension add openproject --from https://github.com/Nachklang-io/speckit-openproject/releases/download/extension-v0.2.0/openproject-extension-0.2.0.zip

License

MIT