All document management is available as subcommands. Most accept --json for machine-readable output.

show Flags

provenance Subcommands

Cite the sources of truth that informed a document. Citations are free-form strings stored as a YAML list in frontmatter.

lazyspec provenance add RFC-001 "Workshop 2026-04-12"
lazyspec provenance add RFC-001 "Privacy Act 1988"
lazyspec provenance list RFC-001
# Workshop 2026-04-12
# Privacy Act 1988

lazyspec provenance remove RFC-001 "Privacy Act 1988"
lazyspec provenance list
# RFC-001	Workshop 2026-04-12

All three subcommands accept --json. Shapes:

• add / remove: { "doc": "...", "added"|"removed": "...", "provenance": [...] }
• list <id>: { "doc": "...", "provenance": [...] }
• list (no id): { "documents": [{ "id": "...", "path": "...", "provenance": [...] }, ...] }

add rejects empty citations. remove is exact-match and errors when the citation is absent.

Coordination

Claude Code Hooks

Lazyspec ships hook snippets that claim, heartbeat, and release a lease on $ASSIGNED_TASK across a Claude Code session. The orchestrator (daemon, manual export, etc.) sets the env var; hooks no-op silently when it is unset, so the snippet is safe to install unconditionally.

Drop into .claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "[ -n \"$ASSIGNED_TASK\" ] && lazyspec claim \"$ASSIGNED_TASK\" --agent-id \"$CLAUDE_SESSION_ID\" --json || true"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "[ -n \"$ASSIGNED_TASK\" ] && lazyspec heartbeat \"$ASSIGNED_TASK\" --agent-id \"$CLAUDE_SESSION_ID\" --min-interval 15m --json || true"
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "[ -n \"$ASSIGNED_TASK\" ] && lazyspec release \"$ASSIGNED_TASK\" --agent-id \"$CLAUDE_SESSION_ID\" --json || true"
          }
        ]
      }
    ]
  }
}

The standalone file lives at hooks/claude-code-settings.json.

$ASSIGNED_TASK contract. Orchestrator sets it to a doc id (e.g. ITERATION-170). If unset, the [ -n "$ASSIGNED_TASK" ] guard short-circuits and no lazyspec invocation happens.

Throttle. --min-interval 15m matches the default lease_duration / 4 (lease defaults to 60m). If you tune lease_duration in .lazyspec.toml, tune this to roughly a quarter of it.

Error tolerance. || true swallows non-zero exits from lazyspec (e.g. lease already released, network blip), so a session never fails to end because of a coordination error.

See RFC-035 for the design rationale.

Documents can embed references to source code using @ref directives. By default, lazyspec show renders them as-is. Pass -e to expand them inline.

@ref <path>                    # entire file
@ref <path>#<symbol>           # specific type or struct
@ref <path>#<symbol>@<sha>     # symbol at a specific git commit
@ref <path>#123                # line 123
@ref <path>#123@<sha>          # line 123 at a specific git commit

Expansion resolves content via git show (committed state, not working tree). Supported languages for symbol extraction are TypeScript (.ts/.tsx) and Rust (.rs).

Each expanded ref includes a caption line showing the file path, short git SHA, and symbol or line info. Expanded blocks are truncated to 25 lines by default; when truncated, a trailing comment shows how many lines were omitted. Use --max-ref-lines to adjust the limit.

Example

A document containing:

@ref src/engine/store.rs#Store

Renders as:

```rust
pub struct Store { ... }
```

Unresolvable refs render as:

> [unresolved: src/engine/store.rs#Store]

lazyspec init creates a .lazyspec.toml in your project root with four built-in document types:

[directories]
rfcs = "docs/rfcs"
adrs = "docs/adrs"
stories = "docs/stories"
iterations = "docs/iterations"

[templates]
dir = ".lazyspec/templates"

[naming]
pattern = "{type}-{n:03}-{title}.md"

Custom Types

Instead of [directories], you can define types explicitly with [[types]]. This lets you rename the defaults, add new types, or set custom prefixes and icons used in the TUI.

[[types]]
name = "rfc"
plural = "rfcs"
dir = "docs/rfcs"
prefix = "RFC"
icon = "●"

[[types]]
name = "spec"
plural = "specs"
dir = "docs/specs"
prefix = "SPEC"
icon = "◆"

Validation Rules

Validation rules define structural constraints between document types. Two shapes are supported:

• parent-child -- the child type must link to a parent type via a given relationship.
• relation-existence -- documents of a given type must have at least one relationship.

[[rules]]
shape = "parent-child"
name = "stories-need-rfcs"
child = "story"
parent = "rfc"
link = "implements"
severity = "warning"

[[rules]]
shape = "relation-existence"
name = "adrs-need-relations"
type = "adr"
require = "any-relation"
severity = "error"

Numbering

Document numbers are assigned automatically during create. Three strategies are available per type:

Reserved numbering uses git custom refs (refs/reservations/*) to coordinate across branches. It wraps either incremental or sqids formatting with an atomic push-based lock, so two people never get the same number.

[[types]]
name = "rfc"
prefix = "RFC"
numbering = "reserved"

[numbering.reserved]
remote = "origin"        # default
format = "incremental"   # or "sqids"
max_retries = 5          # push retry attempts before failing

If the remote is unreachable, create fails rather than silently falling back. Use lazyspec reservations prune to clean up refs for documents that have been created.

Templates

Place markdown templates in the templates directory (.lazyspec/templates/ by default). When creating a document, lazyspec uses the template matching the document type name (e.g. rfc.md, story.md).