Documentation

Authoring artifacts

Create artifacts in the right place, move them through their lifecycle, and make accountability explicit.

Start with the graph

Call workspace_summary to orient yourself, then search for the idea before creating anything. Read the intended parent's chain so the new artifact inherits the right strategic context.

Call artifact_types for the type you plan to create. Its allowedParentTypes, allowedStates, and fields are the live contract; do not infer a type or field from an older example.

• A project belongs under a goal.
• A ticket belongs under a project.
• A problem belongs under a persona, goal, or project.

Create and link

Prefer parent_id on artifacts_create when the canonical parent is already known. The service validates the parent type and creates the artifact and parent edge together.

Use artifacts_set_parent to replace an artifact's canonical parent. Use links_add for additional references, dependencies, or supersession relationships; adding a second parent edge is not a re-parent operation.

Create a ticket under a project

artifacts_create({
  type: "ticket",
  title: "Keep the artifact list filter in the URL",
  description: "Preserve the selected owner filter across reloads and shared links.",
  parent_id: "<project-uuid>",
  owner_id: "<workspace-member-uuid>",
  priority: "medium",
  state: "todo",
  content: { ticket_type: "feature" },
  spec_clauses: [
    "Selecting an owner MUST write that owner's UUID to the page URL.",
    "Opening the copied URL MUST restore the same owner filter.",
    "Clearing the filter MUST remove the owner parameter without changing other parameters.",
    "This change MUST NOT alter the workspace-wide saved-view model."
  ]
})

Use lifecycle states and closure reasons deliberately

Mission, vision, strategy, goal, domain_model, persona, and problem use draft, active, or closed. Execution types also support backlog, todo, in_progress, and in_review. The artifact_types response is authoritative for each type.

Closing answers where the work is in its lifecycle; closure_reason answers why it closed. Pass both explicitly when the reason matters. Use completed for delivered work, abandoned for intentionally stopped work, obsolete when the premise no longer applies, migrated when another system now owns it, and duplicate when another artifact is canonical.

Archiving is separate from closure. Archive an artifact to shelve it from normal lists, not to claim that its work was completed.

Close delivered work

artifacts_update({
  id: "<ticket-uuid>",
  state: "closed",
  closure_reason: "completed"
})

Make ownership explicit

Ownership identifies the workspace member accountable for the artifact. Call members_list to get a valid member UUID, then pass owner_id during creation or update it later with artifacts_update.

Assign ownership before moving execution work into in_progress. Clear owner_id only when accountability has genuinely returned to the team; do not use an unassigned artifact as a substitute for an unclear handoff.

Reassign an artifact

artifacts_update({
  id: "<artifact-uuid>",
  owner_id: "<workspace-member-uuid>"
})

Link a pull request to its artifact

The linked check reads the pull request description for a marker. A link is a URL that contains /artifact/<uuid>. Put it anywhere in the pull request description.

A bare UUID does not link. The /artifact/ segment is what the check matches. The host does not matter. Production, preview, and relative links all match.

Link an execution-tier artifact: a project or ticket. Orient, directional, and structural artifacts can stay in the description as context, but they do not satisfy the check on their own.

• Put the marker in the pull request description, not in a commit message or a comment.
• Edit the description and the check runs again on the same commit.
• Several markers link several artifacts; each one has to carry the /artifact/ segment.

Link a pull request to a ticket

Implements [Ticket: Fix signup redirect](https://hf.dev/artifact/00000000-0000-4000-8000-000000000000)

Verify the result

Read the artifact's chain after writing. Confirm the parent, type-specific content, state, owner, and any additional links match the intended work. Treat detector findings returned with a write as follow-up work, not as decoration.