LGTM Specifications

LGTM Specifications is a versioned knowledge graph of engineering standards (Rules) and an agent workforce (Modes/Roles) that tools can run to plan, build, and audit changes with high assurance.

Quick Links

• Rules: rules/README.md
• Agents: agents/README.md
• Integration protocol: integrate/README.md
• Docs: docs/README.md
• Contributing: docs/CONTRIBUTING.md

Knowledge

We turn industry best practices and internal standards into atomic, enforceable rules:

1. Source material lives in docs/meta/**.
2. Atomic rules live in rules/** and cite their sources.
3. Runtimes inject only the relevant rules for a given task (tag/domain based) instead of loading the entire graph.

Start here:

• Rules Index
• Docs Index

Workflows

LGTM runs as operating modes that orchestrate a specialist team (Lead, Explorer, Counsel, Planner, Builder, Reviewers).

Modes:

• @Build: production changes (rules + plan + proof + specialist review).
• @Hack: fast iteration (lighter gates).
• @Review: read-only audit.

Core roles:

• 🧠 Lead: orchestrates and arbitrates.
• 🗺️ Explorer: maps the target repo.
• ⚖️ Counsel: selects minimal relevant rule paths.
• 📐 Planner: produces an execution/audit plan.
• 🏗️ Builder: implements and produces proof.
• 🔬 Reviewers: audit from specialized perspectives.

Start here:

• Agent Architecture
• Agents Index

Consume

Tools consume this repo as a read-only spec database.

Install via npm (recommended):

npm install --save-dev lgtm-specs

# or:
bun add -d lgtm-specs

The specs live at node_modules/lgtm-specs/.

Versioning:

• VERSION matches integrate/README.md **Spec Version**:
• See integrate/versioning.md for consumption options (tags, submodules, npm)

Integrating

Start here:

• Integration Protocol

You are implementing integration for the LGTM specs repo (yyforyongyu/lgtm-specs).

Goal: wire this repo into a coding tool so it can run the LGTM agent workflows.

Read and follow `integrate/README.md` exactly, including:
- Parsing `agents/**/*.md` and honoring placeholders like `{{injected_rules}}`.
- Running Counsel and enforcing its JSON output schema.
- Hydrating rule paths into rule content and injecting role-appropriate subsets per reviewer.
- Resolving models using `models/registry.yaml` in list order (preference order) with deterministic availability checks.

Output:
1) a concise implementation checklist,
2) the minimal data structures you will use (schemas),
3) pseudocode for: index loading -> counsel -> rule hydration -> per-agent injection -> execution.

Contributing

Contributions should preserve atomicity, indexing, and link integrity.

Start here:

• Contribution SOPs
• Definition of Done Checklist
• Local checks: bun run check (runs spec validation + prettier --check).

You are contributing to the LGTM specs repo (yyforyongyu/lgtm-specs).

Read `docs/contribute/README.md` and `docs/contribute/checklist.md` and follow them strictly.
Run `bun run check` before finalizing your changes.

Constraints:
- One rule per file; follow the rule template used in this repo.
- Add new files to the parent directory index README(s).
- Use repo-relative links only and ensure every link target exists.

Task:
1) identify the smallest set of atomic rule/doc changes needed for the request,
2) propose exact file edits,
3) run `python3 scripts/validate_specs.py` and report any failures.