fit-guide

name: fit-guide description: > Get career guidance and output review grounded in your organization's engineering standard. Use when a promotion conversation ended without specifics and you need evidence of what to improve, when reviewing agent output and you want a second opinion against the standard, or when asking about skills, levels, and career expectations. Also covers setting up the Guide service stack and ingesting knowledge content.

Guide Product

AI agent that understands your organization's agent-aligned engineering standard — skills, levels, behaviours, and expectations — and reasons about them in context. Guide helps engineers onboard, find growth areas, and interpret engineering artifacts against skill markers.

Guide runs on the Claude Agent SDK and exposes its knowledge through MCP, making it accessible from three surfaces: fit-guide CLI, Claude Code, and Claude Chat.

When to Use

Find growth areas:

• Getting career guidance grounded in your organization's standard — npx fit-guide "What should I focus on to reach the next level?"
• Asking about skills, levels, behaviours, and expectations — npx fit-guide "What does practitioner-level delivery look like?"
• Checking whether recent work shows progress — npx fit-guide "Does my recent PR show growth in code quality?"

Verify agent work:

• Interpreting engineering artifacts against skill markers — npx fit-guide "Review this diff against senior delivery expectations"
• Getting a second opinion before approving a deliverable — npx fit-guide "Does this design doc meet the standard for system design?"

Setup and operations:

• Bootstrap a new project — npx fit-guide --init (safe to re-run; no-op on existing projects)
• Authenticate — npx fit-guide login
• Start the service stack — npx fit-rc start
• Check system readiness — npx fit-guide status
• Process knowledge content — npx fit-process-resources, npx fit-process-graphs, npx fit-process-vectors

How It Works

Agent Orchestration

The CLI sends user queries to the Claude Agent SDK, which orchestrates the conversation using a single-agent guide-default prompt. The agent follows a structured workflow: orient (explore the ontology), query (retrieve data via tools), and synthesize (compose a grounded answer). The SDK handles context compaction and session persistence automatically.

Tool Execution

Guide exposes 10 tools via an MCP endpoint, each backed by a gRPC service:

Knowledge Pipeline

Content flows through three stages: HTML files in data/knowledge/ are processed into typed resources (data/resources/), then indexed as RDF triples in the graph store (data/graphs/) for structured queries, and as vector embeddings (data/vectors/) for similarity search. This dual index lets the agent combine precise graph lookups with fuzzy semantic retrieval.

Three Surfaces

• fit-guide CLI — Reference implementation on the Claude Agent SDK. Fetches the guide-default prompt from MCP and streams the response.
• Claude Code — Register the MCP endpoint as an MCP server. Guide's tools appear in the tool picker; Claude Code provides the harness.
• Claude Chat — Configure a Claude Connector backed by the MCP endpoint. Same tools, same knowledge, same answers.

Initialization

Run npx fit-guide --init in a fresh project directory. It produces .env (token and port assignments) and config/config.json (service composition). Re-runs are byte-stable no-ops — generated SERVICE_SECRET and MCP_TOKEN are preserved across invocations, so running init again to pick up a starter update never rotates credentials. Then authenticate and set up the stack:

npx fit-guide --init        # Bootstrap .env + config/config.json (idempotent)
npx fit-codegen --all       # Generate gRPC stubs and field metadata
npx fit-guide --login       # OAuth PKCE login (or set ANTHROPIC_API_KEY in .env)
npx fit-process-resources   # Process starter knowledge HTML
npx fit-process-graphs      # Build the RDF index
npx fit-process-vectors     # Build the vector index (skip if no embeddings backend)
npx fit-rc start            # Launch the service stack
npx fit-guide "What skills does a senior engineer need?"

CLI Reference

See references/cli.md for full command listings.

Service Stack

Guide requires the service stack to be running. Services are supervised by fit-rc and defined in config/config.json.

MCP Endpoint Configuration

For Claude Code, register the MCP endpoint in your MCP server config:

{
  "guide": {
    "url": "http://localhost:3005",
    "headers": { "Authorization": "Bearer <MCP_TOKEN>" }
  }
}

Authentication

Data Pipeline

See references/data.md for processing steps and directory layout.

Verification

npx fit-guide status                    # All services should show "ok"
echo "hello" | npx fit-guide            # Should return an agent response

Documentation

• Guide Overview — Product overview, audience model, and key concepts
• Getting Started: Guide for Engineers — Set up the AI agent that understands your engineering standard
• See What's Expected at Your Level — Stop guessing what your level requires
• Understand Autonomy and Scope — What each level implies for decision-making and ownership
• Get Career Guidance Grounded in the Standard — Identify gaps and track progress toward the next level
• Ask a Growth Question — Get context-specific guidance grounded in your standard
• Check Progress Toward Next Level — See where you stand against level expectations
• Get Output Review Grounded in the Standard — Know what to expect from agent output
• Get a Second Opinion on a Deliverable — Have the Guide review work against quality criteria