Using Claude Code on LCO-DMA¶

A practical guide for a developer who is new to driving Claude Code (the CLI) on this repository. It explains how the model gets its context here, what the building blocks are (skills, agents, rules, MCP servers), and the canonical workflows the team uses.

If you only read one other file, read CONTEXT_MAP.md — the audience-tagged inventory of every context surface in the repo.

TL;DR for your first session¶

Don't paste big context. The model already auto-loads CLAUDE.md, every file under .claude/rules/, the .agent-context/ brief, and persistent memory at session start.
Work flows through tickets. TDD (/kickoff-jira-ticket → /tackle-ticket) is the day-to-day default; deep-feature is the heavy-analysis path for complex features; the built-in /feature lifecycle covers mid-size Jira work. (See Building features.)
Every stage has a gate — scope → commit → push → merge → release — and the same gate runs no matter who or which workflow produced the diff. (See Gates at every stage.)
Invoke a skill before doing raw work — /design-system for UI, /api-endpoint to scaffold an endpoint, /analyze-feature to size a feature first.
Ask the LCO MCPs about data & domain — cosmos-mcp for live project data, lco-domain-mcp (lco_summary, then lco_impact) for how the system fits together.
Let agents do the bulk implementation. The main session orchestrates; lco-* agents write the code.
Branch off dev, run /testing-protocol before committing, use gh (not a GitHub MCP).

How context loads¶

Every Claude Code session on this repo starts with a curated context bundle loaded automatically. You do not need to paste it, and you should not — re-pasting wastes the context window and risks drift from the canonical source.

flowchart TD
    A[Session starts] --> B[CLAUDE.md auto-loads]
    B --> C[.claude/rules/*.md auto-included via CLAUDE.md hierarchy]
    B --> D[.agent-context/ brief — product/tech/structure/conventions/practices]
    B --> E[Persistent memory: compass-memory KG + user auto-memory]
    C --> F[Model now knows stack, conventions, codegen guardrails]
    D --> F
    E --> F
    F --> G[You give a task]

What loads, and where it lives:

Surface	What it carries	Source of truth
`CLAUDE.md` (repo root)	Quick context, tech stack, `just` recipes, key patterns, critical files, skills reference	Hand-maintained; reviewed on infra/skill/rule changes
`.claude/rules/*.md`	Hard codegen guardrails — schemas, routers, repositories, services, styling, hooks, components, stores, api-services, EM template columns	Hand-maintained per convention shift
`.agent-context/` (5 files)	`product.md`, `tech.md`, `structure.md`, `conventions.md`, `practices.md` — the durable repo brief	Maintained by URM (see below)
compass-memory knowledge-graph	Prior facts, decisions, learnings about this codebase, captured across sessions	Auto-captured via hooks; queried on demand

Why this matters: the rules and .agent-context/conventions.md encode things a generic model would get wrong here — text-lco-* typography instead of text-sm, require_auth on every endpoint, parameterized Cosmos SQL, the 3-store Zustand limit, branch-off-dev. Trust those files over your own assumptions about "the usual way."

The building blocks¶

Four distinct concepts. Knowing which is which is most of the skill of driving Claude Code here.

Block	What it is	How you invoke it	Example
Skill	A bundled, named workflow (a "slash command"). Self-contained instructions the model loads on demand.	`/skill-name`	`/design-system`, `/api-endpoint`, `/feature LCO-241`
Agent	A sub-persona with its own scoped toolset and prompt. Does focused work and reports back.	Main session delegates via the Agent tool (`subagent_type`)	`lco-backend-implementer`, `lco-code-reviewer`
Rule	An auto-loaded codegen guardrail. Always in context; no invocation needed.	(automatic)	`.claude/rules/backend-routers.md`
MCP server	An external tool surface — live data, memory, code-nav, tickets, parallel jobs.	Tool calls (often behind a skill)	`cosmos-mcp`, `serena`, `ticket-driven-dev`

Mental model: rules are the always-on guardrails, skills are the recipes you call, agents are the workers you hand a recipe to, and MCP servers are the model's hands reaching outside the codebase.

Project agents (`.claude/agents/`)¶

The lco-* personas do the bulk implementation and review so the main session can stay an orchestrator:

lco-fullstack-implementer, lco-frontend-implementer, lco-backend-implementer — write code
lco-api-scaffolder — scaffold a full vertical endpoint
lco-code-reviewer, lco-security-reviewer, lco-performance-analyzer — read-only review
lco-design-system-migrator — migrate a file to design tokens
lco-pr-pre-review, lco-veracity-checker — pre-PR / acceptance checks

Skills¶

The full enumeration of project + plugin skills lives in the sibling docs/SKILLS_MATRIX.md — that is the canonical list. The handful you'll reach for daily are in the lifecycle section below. The skills themselves live under .claude/skills/ and are also summarized in the "Skills Reference" table in CLAUDE.md.

MCP servers available¶

MCP (Model Context Protocol) servers give the model tool surfaces beyond reading and editing files. The two you'll use most are project-specific — they live in tools/mcps/ and were built for LCO-DMA: cosmos-mcp (live data) and lco-domain-mcp (the domain model + code knowledge graph, built by Richard). Start there; the rest are general-purpose plugins.

The two LCO MCPs (project-specific — use these first)¶

cosmos-mcp — talk to live project data. Read/query the real estimates, budgets, schedules, crews, and materials in dev Cosmos. It speaks in business terms ("your estimate", "the piping items") and deliberately hides container names, partition keys, and UUIDs. Use it to answer "what's actually in the data?", sanity-check a migration, or confirm a container's contents before writing code against it.

How to use: just ask in business language — "how many piping items are in the latest estimate revision for project X?". Internally it lists containers, resolves the project + active service, then queries. It connects to dev Cosmos (not an emulator), so it's the reliable way to verify data locally when integration tests can't run.

lco-domain-mcp — reason about the system (Richard's domain layer). The conceptual layer: why the system works the way it does. Two layers behind one server — a hand-curated cache (12 YAML entity types: container, module, page, flow, behavior, migration, glossary, state-machine, import-pipeline, intent, infrastructure, seed-state) and a code knowledge graph auto-extracted from backend/app + frontend/src. ~20 tools.

How to use: always start with lco_summary to orient. Then lco_impact(target_id) for blast-radius before a change, lco_field(container, field) for field-level QA impact, lco_search/lco_get/lco_module to look things up, and the lco_kg_* tools to verify a cache claim against the actual code. Rule of thumb: cache first, KG to fill gaps or ground-truth a claim. It's registered in tools/mcps/lco-domain-mcp (uv run lco-domain-mcp).

General-purpose MCP servers (from the compass plugins)¶

Server	What it gives you	When to use
knowledge-graph (compass-memory)	Persistent cross-session memory — prior facts, decisions, learnings about this codebase.	Recall a past decision before re-deriving it; record durable knowledge after significant work.
serena	Symbol-level code navigation / LSP — find symbol, find references, rename, diagnostics.	Trace a function's callers, do a safe rename, navigate by symbol rather than text grep.
ticket-driven-dev	The `.tdd/` backlog data layer — ticket CRUD, registry, board state.	Create/track/transition local TDD tickets; drive the tackle workflow.
tmux-orchestrator	Spawn and supervise parallel workers in tmux windows; wait on sentinels; live dashboard at `http://127.0.0.1:7777/`.	Fan out TDD tackle workers or deep-feature analysts in parallel.
skill-manager	Author / validate / score local skills and agents (no network).	Turn a repeated workflow into a reusable skill.
chrome-devtools	Drive a real Chrome — navigate, screenshot, Lighthouse, console.	UI behavioral testing, perf audits of the running app.
lco-storybook	HTTP MCP into the running Storybook (`localhost:6006`).	Inspect component stories during UI work.

cosmos-mcp, chrome-devtools, and lco-storybook are wired in the repo's .mcp.json; lco-domain-mcp runs from tools/mcps/; the rest come from your Claude Code plugin install.

Building features: pick a workflow¶

There are three ways to take work from idea to PR on this repo. They share the same gates (next section) and the same lco-* implementer/reviewer agents — they differ in how much up-front structure they impose. Pick by size and risk.

flowchart LR
    J[Jira LCO-NNN] --> Q{Size / risk?}
    Q -->|"small / medium<br/>(day-to-day)"| TDD[TDD<br/>ticket-driven dev]
    Q -->|"complex / cross-cutting<br/>(deep analysis pays off)"| DF[deep-feature<br/>Richard's workflow]
    Q -->|"mid-size Jira feature"| FL["/feature lifecycle"]
    TDD --> G[Gates]
    DF --> G
    FL --> G
    G --> PR[PR -> dev]

1. TDD — ticket-driven development (the day-to-day default)¶

The primary workflow here. The .tdd/ directory is a local backlog (backlog / in_progress / completed / registry.json), managed by the ticket-driven-dev plugin and its ticket-engine MCP.

/kickoff-jira-ticket LCO-NNN — bootstrap a Jira ticket into a ready-to-work setup: a git worktree off dev, a synced jira/<KEY>/ folder anchored by spec.md, and an initial .tdd/ backlog of subtask tickets derived from the Jira description.
/tackle-ticket — implement a backlog ticket via the explore → plan → implement → review subagent workflow. Drain the backlog ticket by ticket.
/ticket-manager, /refine-ticket, /tdd-doctor — tactical grooming, refinement, and drift repair of the board.
Parallelize by fanning out tackle workers via the tmux-orchestrator MCP (watch them on the dashboard at http://127.0.0.1:7777/).

Run /tdd for the state-aware board dashboard and "what should I work on next".

2. deep-feature — exhaustive analysis for complex features (Richard's workflow)¶

Deep Feature Development (the deep-feature compass plugin) is the heavy-duty option for features big or risky enough that getting the analysis wrong is expensive. It exists to solve context evaporation — it captures every insight as structured, on-disk artifacts so implementers never re-discover context and sessions resume losslessly.

Six phases, idea → shipped PR:

flowchart LR
    A[1. Intake<br/>problem + scope] --> B[2. Analysis<br/>BE / FE / Risk specialists<br/>in parallel via tmux]
    B --> C[3. Interview<br/>asks only what<br/>code can't answer]
    C --> D[4. Plan<br/>vertical slices +<br/>fat tickets]
    D --> E[5. Implement<br/>fat tickets in parallel]
    E --> F[6. Review<br/>5-pass reviewer] --> G[PR]

State lives in a gitignored .features/<slug>/. Commands: /feature-implement (execute a fat ticket), /feature-review (5-pass reviewer), /feature-status, /feature-resume (pick up where you left off), /feature-tickets, /feature-branch, /feature-fix. Reach for it when "fat tickets so detailed implementers never need to re-discover context" is worth the up-front cost; use TDD for everyday work.

3. `/feature` — the built-in lifecycle (mid-size Jira features)¶

The lighter-weight built-in path for a self-contained Jira feature:

Step	Skill	What it does
1. Assess	`/analyze-feature LCO-NNN`	Complexity, risk, impact, alternatives — before any code.
2. Build	`/feature LCO-NNN`	Requirements → plan → implement → verify. For L/XL it forms an agent team (`agent-teams`) — `lco-*` implementers write code, reviewers gate it.
3–6. Ship	`/testing-protocol` → `/create-pr` → `/pr-bot-review` → `/branch-review`	Gate, open the PR (structured title + mandatory test plan + Jira link via `gh`), resolve bot comments, review.

Keeping context fresh: URM (not a build workflow)¶

Running alongside all three: the Ultimate Repo Manager keeps the model's understanding fresh (the build workflows manage the work). It maintains the five .agent-context/ files that auto-load each session — /urm-init (bootstrap/rebuild), /urm-doctor (drift check vs recent code), /urm-distill (fold session learnings into practices.md), /urm-decide (record a new convention). Plans → .agent-context/plans/, decisions → .agent-context/decisions/; never write plan.md/notes.md to the repo root.

Gates at every stage¶

The team's operating principle: every stage of every workflow passes through a gate — a skill that verifies the work before it advances. Whether a human, a TDD tackle worker, or a deep-feature implementer produced the diff, the same gate runs. Gate skills are read-only verifiers — they report and block, they don't implement — which is exactly why they're trustworthy across workflows.

flowchart LR
    S[Scope] -->|gate| C[Commit] -->|gate| P[Push] -->|gate| M[Merge] -->|gate| R[Release]

Stage	Gate skill(s)	What it verifies
Pre-ticket / scoping	`/analyze-feature`, `/refine-ticket`, `/expand-jira-ticket`	Size, risk, impact, and acceptance criteria are defined before code.
Pre-commit	`/testing-protocol` (or `/quality-checks`, `just check`)	Build + lint + types pass; mandatory before every commit.
Pre-push	`/pre-push`, `/pre-push-review`	Local mirror of the GHA bot review (`just quality-*` + reviewer) before you push.
Pre-merge	`/pre-merge LCO-NNN`	The SDD exit gate — four sub-gates: quality, `/check-acceptance` (every AC in `spec.md` has evidence), behaviors, `/veracity-check` (diff actually delivers the ticket, no scope drift) → one GO/HOLD verdict.
Post-merge / release	`/weekly-release-pr`	Bundles the periodic `dev → main` release PR with a structured summary.

This gate-per-stage discipline is the backbone — it's why a feature can be built three different ways yet still meet one consistent bar. See docs/SKILLS_MATRIX.md for every skill, including the smaller ones (/git-commit-pull, /db-migration, /import-pipeline, /azure-cosmosdb-cli, …).

Git & branching norms¶

flowchart LR
    main["main<br/><i>production</i>"]
    dev["dev<br/><i>integration</i>"]
    feat["feature/lco-NNN_slug<br/><i>your work</i>"]

    dev -->|"1 · branch off dev"| feat
    feat -->|"2 · feature PR → dev"| dev
    dev -->|"3 · weekly release PR → main"| main

    classDef prod fill:#1f6feb,stroke:#1f6feb,color:#fff;
    classDef integ fill:#2da44e,stroke:#2da44e,color:#fff;
    classDef work fill:#8957e5,stroke:#8957e5,color:#fff;
    class main prod;
    class dev integ;
    class feat work;

main = production, dev = integration. This is what .agent-context/conventions.md and practices.md state at the branch-model level.
Worktrees branch off dev. Always diff against dev, not main.
Feature/fix PRs target dev. dev → main is a periodic (weekly) release merge — see the weekly-release-pr skill. (The conventions file phrases the model as "PR into main via dev rebase"; in day-to-day practice your feature PR goes into dev, and dev → main is the separate release PR. When in doubt, diff and target dev.)
Use just worktree <branch> [base] to spin up an isolated checkout (or the /create-worktree skill).
Use the gh CLI for all GitHub operations — not a GitHub MCP server. This is an explicit team preference.
Branches: feature/lco-NNN_short_slug, fix/short-slug, chore/short-slug.
Commits: conventional-ish (feat(scope): …), one logical change each, no AI attribution, never --amend after a failed pre-commit hook (make a new commit), never --no-verify unless asked.

Day-one Claude Code habits¶

Do

Invoke the right skill before raw work — /design-system for any UI, /api-endpoint to scaffold an endpoint, /feature for a real feature, /analyze-feature to size it first.
Run /testing-protocol (or just check / just ci) before committing.
Let agents do the bulk implementation. Keep the main session as orchestrator — plan, curate context, review. Delegate the typing.
Trust .claude/rules/ and .agent-context/conventions.md over guessing the convention.
Ask cosmos-mcp about live data instead of assuming what's in a container.
Query the knowledge-graph before re-deriving a decision someone already made.
Use just <recipe> for everything (just --list is the source of truth) and uv run for Python — never bare pip / python.

Don't

Don't paste CLAUDE.md, the rules, or the agent-context back into the chat — they're already loaded.
Don't use raw Tailwind (text-sm, bg-white, text-neutral-*) — semantic text-lco-* / bg-card / text-foreground only. Run /design-system if unsure.
Don't add a 4th Zustand store without justification — default to a custom hook.
Don't string-interpolate values into Cosmos SQL — always parameterize.
Don't mock the database in integration tests — hit real Cosmos.
Don't write scratch plan.md / notes.md to the repo root — use .agent-context/plans/.
Don't approve a terraform apply without grepping the plan for will be destroyed / must be replaced on data-bearing resources.

Where to go next¶

You want to…	Read
Find where any context surface lives	`CONTEXT_MAP.md`
See every skill and what it's for	`docs/SKILLS_MATRIX.md`
Understand the stack & conventions	`.agent-context/tech.md`, `.agent-context/conventions.md`
Know where code goes	`.agent-context/structure.md`
The codegen guardrails the model follows	`.claude/rules/*.md`
Project docs index	`docs/KNOWLEDGE_BASE.md`, `docs/index.md`