Claude

Specivo

Specivo is a self-hosted project tracker, knowledge base, and AI-safe automation platform. It exposes an HTTP MCP server whose tools (prefixed mcp__specivo__ or referred to as specivo_* in this skill) are the correct way to read and write project data.

This skill explains how to use those tools well. It is project-agnostic: the same patterns apply whether you are working in an established project, bootstrapping a new one, or helping a user who just installed Specivo for the first time.

Before anything else: load the live tool surface

On the first Specivo interaction in a new session, call:

specivo_setup_guide(format="claude")

This returns the authoritative, version-matched list of tools, workflows, and anti-patterns from the server you are actually connected to. Treat its output as the source of truth when it disagrees with this skill — Specivo ships new tools frequently and the server knows what it supports today. Call it once per session, not on every request.

If the user has never used Specivo before, the setup guide also describes how to set up their project. Don't duplicate that guidance here; hand them the setup guide output.

Identity and project discovery

Two tools answer "who am I" and "where can I work":

specivo_whoami()            # your user_id, login, display name, admin status
specivo_list_projects()     # projects visible to you, with their keys

Call whoami once per session when you'll be creating or assigning issues — the returned user_id is what you pass as assigned_to_id for self-assignment. Call list_projects when the user hasn't told you which project key to use, or when they mention a project by human name and you need the key.

Projects are addressed by key (e.g. FOO, BAR). Issues inside a project are addressed by ref (FOO-123). Use the ref form everywhere — never raw numeric IDs in your output, since refs are what the user sees in the UI and in URLs.

Lookups: get IDs before writing

Before creating or updating an issue, fetch the numeric IDs your instance uses for trackers, statuses, priorities, and activities:

specivo_list_lookups()

These IDs are per-instance and sometimes per-project. Do not hard-code them from memory or from another project. Typical shapes you'll see (but always verify):

• Trackers: Bug, Feature, Task, Support
• Statuses: New, In Progress, Resolved, Feedback, Closed, Rejected
• Priorities: Low, Normal, High, Urgent, Immediate
• Activities: Development, Design, Testing, Meetings, Support (used by time logging)

Cache the lookups in working memory for the session and refer to statuses/trackers by name in your explanations to the user, even though the API needs integer IDs.

Issue workflow

Creating an issue

specivo_create_issue(
    project_key="FOO",
    tracker_id=<id from list_lookups>,
    subject="Short imperative title",
    description="Narrative description in Markdown",
    assigned_to_id=<your user_id if self-assigning>,
    priority_id=<id>,
    fixed_version_id=<id, optional>,
)

Guidance:

• Subject: imperative, concrete, one line. "Fix pagination off-by-one in search results", not "Pagination bug".
• Description: narrative only. Do not put commit hashes, branch names, or PR/MR URLs here — those belong in metadata (see below). Do not write other issue refs as plain text — use relations.
• Self-assign when the user tells you to pick up the work. Fetch user_id from whoami once per session and reuse it.
• Version mapping: if the user is on a release branch (e.g. release/1.4.2), look up the matching version with specivo_list_versions(project_key="FOO") and set fixed_version_id. If there is no matching version, ask before creating one.

Moving an issue through its states

When you begin work on an issue, transition it immediately so the board reflects reality:

specivo_update_issue(issue_ref="FOO-123", status_id=<In Progress id>)

When the work is done:

specivo_update_issue(
    issue_ref="FOO-123",
    status_id=<Resolved id>,
    done_ratio=100,
    notes="Short summary of what shipped and where to verify it.",
)

Use specivo_add_comment(issue_ref=..., notes=...) for longer commentary that is not a state transition — it keeps the activity feed readable.

Linking related issues

Never write an issue ref as text in a description or comment to imply a relationship. Use the relation API so the link is structured and bidirectional:

specivo_add_relation(
    issue_ref="FOO-123",
    issue_to_key="FOO-145",
    relation_type="relates",
)

Relation types: relates, blocks, blocked, duplicates, duplicated, precedes, follows. Pick the most specific one that fits — "blocks" and "precedes" both imply ordering but mean different things, and stakeholders filter on them.

Remove stale relations with specivo_remove_relation rather than letting them rot.

Metadata: commits, branches, pull requests, component

Specivo projects typically attach a metadata schema to their trackers. The most common one (often called Software Development) provides these array/string keys:

• commits (array of strings) — full 40-char git SHAs
• branches (array of strings) — git branch names
• pull_requests (array of strings) — PR/MR URLs or identifiers
• component (string) — the module or subsystem touched

These are the single source of truth. Never inline them in descriptions or notes. The description is narrative; the metadata is structured and queryable.

After committing work for an issue, append the hash:

specivo_metadata(
    target_ref="FOO-123",
    key="commits",
    op="append",
    value="<full-40-char-sha>",
)

Get the full SHA with git log -1 --format="%H". For multiple commits in one call, pass value=["<sha1>", "<sha2>"]. Supported ops: get, set, append, remove, delete.

If the expected keys aren't available on an issue, list the project's schemas to see what's attached:

specivo_list_metadata_schemas(project_key="FOO")

If a project has no schema attached yet, tell the user — this is a one-time project-setup action they (or an admin) should perform, not something to route around by stuffing data into descriptions.

Reading issues

specivo_show_issue(issue_ref="FOO-123")       # fields, metadata, comment count
specivo_list_issues(project_key="FOO", ...)   # filtered list
specivo_list_relations(issue_ref="FOO-123")   # what it blocks / is blocked by
specivo_list_comments(issue_ref="FOO-123",    # paginated comment thread
                      limit=10, offset=0, order="desc")

show_issue returns the issue's fields, metadata, and the count of comments — not the comment bodies. If the user wants to see what people actually wrote, follow up with list_comments.

list_issues accepts filters (status, assignee, tracker, version). Prefer a narrow filter over pulling the full backlog; the output is cheaper and easier to reason about.

list_comments is paginated and returns only journals with actual notes, skipping pure field-change entries so you get human commentary without audit-log noise. Default order="desc" gives newest first, which is usually what the user wants ("what's the latest on FOO-123?"); switch to "asc" when reading a thread chronologically from the start. Use offset to page through long threads.

Search

Specivo's search is the primary entry point when you don't already know the issue ref or wiki slug:

specivo_search(query="<keywords>", project_key="FOO", scope="all", limit=10)

Scopes: all, issues, wiki. Narrow the scope when you know what you're after — it reduces noise and token cost.

Patterns:

• Unclear task: search issues + wiki for the user's keywords before asking clarifying questions. Often the context is already written down.
• Investigating a bug: search for error text, the affected component, or the ticket ID if the user mentioned one.
• Finding conventions: search wiki for terms like "conventions", "ADR", "testing", "guide" scoped to the project you are working in.
• Cross-project: omit project_key only when you genuinely need to search everywhere. Scoped search is almost always the right default.

If you run a search and get nothing useful, try one or two rephrasings before giving up — Specivo's search is keyword-based and phrasing matters.

Wiki pages

Reading

specivo_list_wiki_pages(project_key="FOO")
specivo_read_wiki(project_key="FOO", slug="testing-conventions")
specivo_read_wiki_section(project_key="FOO", slug="...", section="...")

Slugs are normalized automatically — Testing Conventions, testing_conventions, and testing-conventions all resolve to the same page. Users can paste whatever they have and it will work.

Creating and editing

specivo_create_wiki(
    project_key="FOO",
    title="Testing Conventions",
    body="Markdown body...",
    parent_slug="engineering",  # optional, for hierarchy
)

Rules that save pain later:

• Use spaces in titles, not underscores. "Testing Conventions", not "Testing_Conventions". The slug is auto-generated from the title — underscores produce ugly slugs and page headings.
• Do not add a redundant H1 at the top of the body. The page title is already rendered as the heading; adding # Testing Conventions inside the body duplicates it.
• Markdown only. Do not paste rendered HTML or other formats.
• Hierarchy via parent_slug. Use it instead of trying to encode hierarchy in titles.

For incremental changes:

specivo_edit_wiki(project_key="FOO", slug="...", body="...")        # full replace
specivo_append_wiki(project_key="FOO", slug="...", content="...")   # add at end
specivo_replace_wiki_section(project_key="FOO", slug="...",
                             section="Header", content="...")        # section surgery

Prefer section-level edits over full rewrites when you only need to change part of a page — it's safer and produces a cleaner history.

Sprints and versions

Versions group issues for a release; sprints group issues for a time-boxed iteration. Both are optional — not every project uses them.

specivo_list_versions(project_key="FOO")
specivo_create_version(project_key="FOO", name="1.4.0", due_date="YYYY-MM-DD")
specivo_list_sprints(project_key="FOO")
specivo_create_sprint(project_key="FOO", name="Sprint 12", start_date=..., end_date=...)

When creating an issue on a release branch, map it to the matching version (see Creating an issue above). When starting a sprint, use specivo_start_sprint; when finishing, specivo_complete_sprint.

Do not invent versions or sprints silently — ask the user which one a new issue belongs to if it isn't obvious from branch names or context.

Time logging

specivo_log_time(
    issue_ref="FOO-123",
    hours=1.5,
    activity_id=<from list_lookups>,
    comments="What you did",
    spent_on="YYYY-MM-DD",  # optional, defaults to today
)

Log time only when the user asks you to, or when there is an explicit project convention that you track time against issues. Don't fabricate durations.

When the task is unclear

Follow this order before guessing:

1. specivo_search(query="<keywords>", project_key="<key>") — issues and wiki combined.
2. specivo_list_issues(project_key="<key>", ...) with a narrow filter if step 1 didn't land on the right ticket.
3. specivo_read_wiki(project_key="<key>", slug="<slug>") for documented conventions.
4. Ask the user. Specivo is a source of truth for "what are we doing and why" — if it doesn't answer the question, neither should you.

Common anti-patterns to avoid

• Writing commit hashes, branch names, or PR URLs in issue descriptions. They belong in metadata. Descriptions are narrative.
• Writing other issue refs as plain text to imply a link. Use specivo_add_relation.
• Hard-coding status/tracker/priority IDs. They vary between instances. Always call specivo_list_lookups once per session and reference by name when talking to the user.
• Creating wiki pages with underscores in titles. Use spaces; let Specivo derive the slug.
• Duplicating the page title as an H1 inside the wiki body. The title is already the heading.
• Skipping specivo_setup_guide on first use. You will end up guessing tool names and parameters that the server already documents correctly for its current version.
• Searching broadly when you can scope by project_key. Scoped searches are faster, cheaper, and more relevant.
• Treating a stale session as a Specivo problem. If a tool call returns a session / auth error, the token or MCP connection is the issue — not Specivo's data.

Output style when reporting to the user

• Refer to issues by ref (FOO-123), not internal numeric IDs.
• Refer to statuses by name ("In Progress", "Resolved"), not by integer.
• When you've moved an issue, state the transition explicitly ("FOO-123: New → In Progress") so the user can confirm at a glance.
• When you've added metadata, say which key changed and the new value — metadata changes are easy to miss in a diff-less UI.