reqvire: Instructions file for Claude Code

Reqvire Development Guide

System Overview

Reqvire is an AI-driven framework for system modeling and requirements management that integrates with Git workflows. It processes semi-structured Markdown documents containing system requirements, manages relationships between elements, validates model consistency, and generates documentation and visualizations.

Workspace Management Decisions

Persistent project decisions, updated with the user on 2026-11-03:

• The native target is one tracked reqvire-workspace.toml at the effective workspace root, including a subdirectory root. Required repositories_dir configures the checkout parent; never hardcode repositories. Each declaration identifies URL/path, a configured tracking ref and an exact commit pin. The owning repository/branch is the source of truth; it may contain all, some or none of the model.
• Native runtime uses the reqvire-workspace crate and reqvire-workspace.toml. Repo XML is read only for explicit migration and older change-impact baselines; it is not a live workspace fallback. WorkspacesPlan.md and system-model/Workspaces/ describe the contracts. Do not refer to the removed ModelStructure/RepoWorkspaces.md.
• One dedicated reqvire-workspace crate owns discovery, state, identity, synchronization, locks, pins, baseline access, branch/checkpoint and publication coordination. CLI, MCP and model processing consume its API. It does not depend on CLI or the model engine; model-aware consumers validate/admit candidates through an explicit boundary.
• No manifest selects the normal single-repository API. An invalid native manifest fails. Discovery does not cross a Git repository boundary to adopt a parent composition. The root does not pin itself.
• CLI scope is workspace status/add/remove/sync/freeze/migrate only. Keep existing MCP branch, commit, push and linked-PR tools. Add typed MCP workspace add/remove/sync/freeze/migrate, retaining reqvire.workspace_status. Initial model-less bootstrap uses CLI; normal validated MCP startup is unchanged.
• Default sync materializes exact pins; sync --latest follows configured refs and advances commit. Freeze records committed component HEADs and preserves ref. Ref is independent of feature working branches and PR targets. Removal unregisters a declaration and preserves the checkout/history.
• Repo migration reads selected XML, writes native TOML into the effective root and invokes ordinary shared sync. Preserve matching checkouts and Git links/metadata; add no backing-store conversion, automatic .repo deletion, extra checkout engine, manifest authoring branch/PR or self-association file.
• The user's example uses the server/client monorepo as owner, with shared model and separate declared website/docs repositories. A manifest-only owner works identically; do not introduce a third manifest participant.
• Commit changed components first, then exact pins and accepted root changes in one root checkpoint. Branch creation alone does not advance pins. Public MCP management uses branches; worktrees stay internal. No repository-mode argument is needed.
• Publish components before root only when requested. One coordinated MCP PR-create call creates/reuses linked changed-component PRs and the root PR. Comments do not fan out implicitly.
• Review uses the actual PR baseline and one explicit Git-baseline override. Do not assume origin/main, add another manifest-commit flag or rename change impact analysis.
• Explicit branch.open admits a clean prepared changed composition; rejected admission preserves accepted reads. No reload/adopt mode is approved. Guarded branch.refresh remains artifact-only. Explicit workspace freeze is a separate validated candidate operation, with no pending accepted edits or unresolved recovery bypass.
• Keep the Git executable backend and reuse shared git_commands/GitReader plus bounded execution. A Git-library rewrite needs a separate measured reason.
• Resolve physical existing paths through reqvire_workspace::paths::canonicalize_existing, including roots returned by Git. Create temporary directories/fixtures through paths::temporary_directory so their paths use the physical OS-selected temporary parent. Rust selects the OS filesystem implementation; do not strip platform prefixes manually. Logical model paths and nonexistent destinations remain lexical; keep declared-path comparisons that reject component/source symlinks. Path tests run on Linux, macOS and Windows.
• Before implementation, update requirements/verifications and capture failing Bash/Git/jq tests. Keep provider/consumer subgraphs independent and use Contract References for documentation/adapters. Preserve existing regression assertions during fixture conversion. Website/shipped skills must be updated with verified runtime behavior; model edits alone do not update them.