openproject
vbundle-v0.2.1Sync fields, status, docs, versions and time between spec-kit and OpenProject via MCP
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_implementhook forsync-status(seesync-status). The host offers the command after/speckit-implement. - More hooks can be added by hand to
.specify/extensions.ymlin the project, for exampleafter_tasks→speckit.taskstoissues. Untested, andspecify extension updateorremovemay rewrite the file. - A scheduled
claude -p "/speckit-openproject-sync-status --dry-run"reports drift without writing. Headless runs were tested (discover-fields, andsync-statuson 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:
- Reads types, statuses, priorities, versions and mandatory custom fields (read-only) and prints an overview.
- 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_progressandstatuses.done, each with a reason. You accept or change items by number. - 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. - Shows the changes as a numbered list and a diff. You approve
all,noneor 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. - Writes through a temporary file and one move, so the file is either unchanged or fully written.
--dry-runshows 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
toolsfrontmatter of an extension command in skills mode, and Claude Code'sallowed-toolsgrants 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_fieldsand 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_updatefalse 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_updatefalse 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:
| Situation | Result |
|---|---|
| work package done, box open | box is checked (pull) |
| work package reopened, box checked | box is unchecked (pull) |
| box checked, work package not done | work package moves to statuses.done (push), only if the server accepts the transition |
| box unchecked again, work package still done | box 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).
| Children | Rolled-up status |
|---|---|
| none (phase without task lines; feature whose phases are all ignored) | none: the parent is left alone (no tasks) |
| all finished | statuses.done |
| at least one finished or in progress | statuses.in_progress |
| otherwise | statuses.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 thetasks.md-changed-during-the-run case (S14, S15, S16 blocked path, S17; details and defects in../docs/TESTING.md). Untested: the labelclosed, not donewith a Rejected work package, accepting the hook offer inside theimplementflow, command mode, a stale work package, a failed single confirm, and a re-run ofspeckit.taskstoissuesover a synced ledger. A 14-work-package feature (ledger written bytaskstoissues) 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 doneandunmapped statusleft alone) and S37 (switched off, no parent write); run 2026-10-11: S39 (membership byparent_id, task above the first heading), S40 (## Phase 01heading, ledger keyphase-1) and S35b (arevertedpull written intotasks.mdtogether 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:
| Situation | Result |
|---|---|
| never synced, no attachment of that name | uploaded (new) |
| file changed since the last sync | the new version is uploaded first, then the outdated attachment is deleted (changed) |
| nothing changed | nothing is written, not even the ledger (unchanged) |
| the attachment was removed in OpenProject | uploaded again (restored) |
| the file no longer exists | the attachment stays, reported as orphan |
| an attachment of that name that the ledger does not know | blocked: 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
blockedand 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 missingspec.mdand 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_TIMEOUTunder 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 bytaskstoissuesin the same run, the stop for a missing upload capability (server withoutOPENPROJECT_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 asENABLE_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 changesif 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). Thelist-time-activitiescall 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-keyto 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
Version
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