Specs and the AI

The AI in the chat panel reads and changes specs through the spec_* and reverse_spec_* tools of the Tracemoor MCP server. Reading works in every session mode. Tools that write need Brave mode. See Session modes.

What the AI does with specs

Tracemoor gives the AI these working rules with every session:

Before changing a symbol, look up the specs anchored to it. A spec is a constraint: if a change contradicts it, say so instead of overriding it.
When answering a question about a symbol, name the specs that cover it.
Create drafts only with reverse_spec_create_draft. A spec file written by hand has no database entry and does not appear in the Specs view.

The rules are instructions to the AI, not checks. Review what the AI changed in the Specs view.

The AI finds specs by meaning as well: projectdocs_semantic_search with source: spec searches spec texts, also across languages. See Project context.

Anchors during refactoring

Before the AI renames, moves or deletes a symbol, it looks up the anchors with spec_anchors_for_symbol. In the same step as the code change it moves each anchor to the new symbol with spec_reanchor. If the new symbol is not clear, it leaves the anchor as it is and reports it. The anchor then shows missing or suspect in the Specs view.

Approval by the AI

In profiles with signatures, spec_set_status accepts a transition to approved or rejected only with the signing passphrase. Do not type the passphrase into the chat. The AI asks for approval with spec_request_batch_approval instead. The request appears as a banner in the Specs view: "AI requests approved of N artifacts" with the reason. Review & Sign opens the signature dialog for the whole batch, Dismiss discards the request.

Links in chat answers

The AI links specs with ce://spec?id=<ID>, for example ce://spec?id=FS-66EP13. Clicking one opens the spec in the Specs view.

Tools

Read

Tool	Purpose
`spec_list`	All artifacts, filtered by type or status.
`spec_read`	One artifact with frontmatter and body.
`spec_search`	Full-text search over the spec texts.
`spec_profile_active`	Active profile: types, link types, statuses, trace chain.
`spec_template`	Template sections of a type, for structured drafts.
`spec_anchors_for_symbol`	Specs anchored to a symbol.
`spec_symbols_for_artifact`	Symbols anchored by a spec, with their state.
`spec_suspect_anchors`	All suspect anchors.
`spec_coverage_summary`, `spec_coverage_for_symbol`, `spec_coverage_for_file`, `spec_coverage_for_cluster`, `spec_coverage_gaps`, `spec_coverage_overlay`	Coverage. See Coverage.
`spec_traceability_matrix`, `spec_export_matrix_markdown`	Traceability matrix.
`spec_decompose_strategies`, `spec_decompose_candidates`	Groups of symbols for drafts.
`reverse_spec_list_drafts`, `reverse_spec_run_status`	Drafts and runs.
`spec_list_approval_requests`, `spec_signing_status`, `spec_verify_signature`, `spec_verify_audit_chain`	Approval requests, signatures, audit trail.
`spec_reindex`, `spec_resolve_all_anchors`	Read the spec files again, resolve all anchors again.

Write (Brave mode)

Tool	Purpose
`spec_create`	Create an artifact.
`spec_update_body`, `spec_set_field`	Change the body or a field.
`spec_set_status`, `spec_batch_set_status`	Change the status. Signed transitions need the passphrase.
`spec_request_batch_approval`	Ask for approval of several artifacts.
`spec_add_anchor`, `spec_add_anchors_batch`, `spec_remove_anchor`	Maintain anchors. With `ref=<reference>` for a symbol of a reference project.
`spec_reanchor`	Move an anchor to another symbol.
`spec_resolve_suspect`	Confirm a suspect anchor with a reason.
`spec_add_link`, `spec_remove_link`	Maintain links. The inverse link is written as well.
`reverse_spec_create_draft`	Create a draft.
`reverse_spec_accept_draft`, `reverse_spec_discard_draft`	Accept or discard a draft.
`reverse_spec_run_start`	Start a reverse-spec run in the background (`claude -p`). Not meant for use from the chat.
`spec_set_signer_profile`, `spec_register_signer`	Signer identity. See Signatures.