Claude Toolkit

Four pillars, one standard underneath them all. The quickest way to tell them apart:

Pillar What it is Think of it as FT example

agents

A delegated worker that runs a sub-task in its own context window and hands back a result.

a specialist you give a self-contained brief — they go away, do the job, return the answer.

ft-java-coding-agent

skills

A procedure + knowledge loaded on demand into the running agent — no separate context.

a playbook on the shelf the agent opens only when the task matches its description.

ft-java-standards

MCP servers

A live connection to external tools & data an agent can query mid-task.

a wall socket the agent plugs into for real-time data (tickets, code search, docs).

Qdrant · JIRA · Context7

automation

Scripts + CI that install, wire, and guard all of the above — runs with no human in the loop.

the plumbing and guardrails behind the walls: nobody sees it, everything depends on it.

install.sh · component-map CI
One sentence: an agent does the work, skills tell it the rules, MCP feeds it live data, automation wires it all up and keeps it honest.

Toolkit at a glance

toolkit-map

Who runs whom

fleet

Which agent do I use?

Start from the situation, not the agent. In almost every case the entry point is ft-developer — it grades the task and delegates to the coding agents, the documentation agent, and audit, so you rarely call those directly.

I want to… Agent Invoke with

Build a feature / idea end-to-end (code + tests + docs)

ft-developer (or /ft-dev)

Use ft-developer. <task>; … — or the /ft-dev <task> skill shim, a thin entry point that launches the same orchestrator.

Refactor / clean up code (behavior unchanged)

refactor-agent (or /ft-refactor)

Use refactor-agent on <class/package/area>. — or the /ft-refactor <target> skill shim. Safety-net-first, behavior-preserving, FT-standard-driven.

Fix a bug from a JIRA ticket

bugfix-agent

Use bugfix-agent for DEV-1234.

Fix a MAJOR/CRITICAL bug with independent multi-verifier gating

/ft-fix (skill)

/ft-fix DEV-1234 — orchestrates bugfix-agent + parallel adversarial verification of the plan and the diff.

Just check conformance — no changes

ft-architecture-audit

Use ft-architecture-audit on the current branch diff. Report file:line.

Write/update docs only

ft-doc-writer-agent

Use ft-doc-writer-agent to document <feature>.

A protocol envelope / spec question

cwmp-xml / oma-lwm2m-expert (skills)

Use cwmp-xml to build a GetParameterValues for Device.WiFi.* …
ft-java-coding-agent, ft-angular-coding-agent, and ft-coding-agent are delegated to by ft-developer — you normally don’t invoke them by hand. ft-doc-writer-agent is the only Friendly AI agent that writes documentation, including protocol flows and PlantUML. The legacy tr-doc-writer definition redirects callers to ft-doc-writer-agent. bugfix-agent is the shortcut when the work is a ticket-scoped fix rather than a planned feature. Full prompt set: Deployment / deploy/prompts/example-prompts.md.

Agents

Agent Model Role

ft-developer

Opus

Quality-gated feature orchestrator. Capability preflight → grades the task (architecture-led / TDD-led / simple-addition) → elicits every blocking requirement → SDD → adversarial design verification (verifier lenses, checkpoint D) → the user’s explicit approval gate → delegates implementation → mandatory test-adequacy adversary (ft-test-adversary) → baseline gate + adversarial diff verification (checkpoint F). Never writes code itself.

ft-java-coding-agent

Opus

Implements backend code and tests in one pass (Java/Spring). TDD mode for TDD-led tasks. Enforces ft-java-standards (records, package placement, greppable logging, real *IT, DB contract).

ft-angular-coding-agent

Opus

Implements frontend code and tests in one pass (Angular/TS). Enforces ft-angular-standards (feature folders + barrels, OnPush/NgRx, logging, kept style).

ft-coding-agent

Opus

New. The stack-neutral coding leaf — every stack with no dedicated agent (Python, Go, Rust, Node/TS, tooling). Code and tests in one pass, same report contract as the specialized leaves. Deliberately preloads no standard: a specialized agent exists exactly where an authoritative standard exists, so here the repo is the standard (nearest analogue → CLAUDE.md/AGENTS.md → linter/type-checker config → .claude/bugfix-profile.md), it must never harden repo norms as a feature side effect, and every report carries the degradation line no FT standard exists for this stack. Returns BLOCKED if handed Java/Angular work — unless the brief’s capabilities map declares the specialized agent missing (the capability manifest’s degraded-fallback path, reported as such).

ft-doc-writer-agent

Sonnet

The single Friendly AI documentation writer. Audits existing docs first (EXTEND / REVISE / NEW / NO-OP). Writes all AsciiDoc, protocol flows, and PlantUML. Enforces the support/QA language contract, separates For developers content, and runs vale docs/src. Shared doc leaf of both pipelines: ft-developer (Stage 8, unless the user writes docs manually) and the bugfix pipeline (conditionally, only on a behavior-visible fix — most fixes make the code match existing docs → NO-OP).

ft-architecture-audit

Sonnet

New. Read-only conformance auditor. Reports boundary / naming / DI / DTO / logging / DB / protocol violations with file:line. Complements the bundled /code-review.

bugfix-agent

Opus

Flagship bug fixer (any FT repo, stack auto-detected). Reproduce-first (failing repro test before any production edit), N-cycle self-verification on fresh evidence, explicit outcome classification (incl. CANNOT_REPRODUCE/EXTERNAL_GAP), siblings sweep + a red-green-proven guard against the bug class. Reference-parity mode only when the repo declares a reference implementation. A diagnosed bug that is really a feature-sized change escalates to ft-developer with the diagnosis dossier (SCOPE_IS_FEATURE), rather than forcing a feature through the bugfix gates.

refactor-agent

Opus

New. Behavior-preserving refactoring (any FT repo, stack auto-detected). Safety-net-first (a green characterization net that is shown to catch a behavior change before the first edit), small verified steps (Fowler catalog), the design-principles thresholds + ft-*-standards as the objective smell basis, a consistency sweep + a baseline-preserving gate. Three modes: targeted / audit-driven / standard-violation. Behavior changes route to ft-developer, bugs to bugfix-agent. Standalone; does not touch the verifier canon.

tr-doc-writer

Sonnet

Legacy compatibility redirect. It does not write documentation and directs callers to ft-doc-writer-agent.

ft-test-adversary

Opus

New — shared canon of BOTH pipelines. Adversarial test-adequacy reviewer — read-only on production code (it never writes the fix). Spawned by ft-developer (feature checkpoint F) and by ft-fix / standalone bugfix-agent (bugfix Gate B) after the fix author reports green, to PROVE the delivered tests are insufficient: honest-RED, negative/observability assertions, regression-guard, seam composition, challenged design assumptions, emulator-leniency, and that the tests actually ran (skip-gate). Returns ranked missing-test briefs that are re-delegated until it finds nothing new. Complements /code-review (reviews the diff, not test adequacy) and the verifier Test-plan-adequacy lens (plan-coverage mapping only — no overlap).

verifier

Opus

Adversarial verifier shared by ft-fix (checkpoints 1/2) and ft-developer (checkpoints D/F). One lens per launch; attacks a fix plan, an SDD, or a diff from fresh evidence; verdicts SOUND / REFUTED / NEEDS_EVIDENCE / NEEDS_HUMAN; only the single executor role runs tests, in its own worktree.
Model tiering is conservative, and it follows the reasoning the agent must do — not whether it writes files. Opus for code, orchestration, bugfix, and the adversarial roles (verifier, ft-test-adversary): refuting a plan and finding the tests that were never written are generative judgement, read-only or not. Sonnet for docs and the rule-checklist audit (ft-architecture-audit), where the verdict follows from an explicit standard. Use Haiku as a habit for read-only exploration sub-agents.

Skills

Skill Kind Use

ft-java-standards

⭐ authoritative

The backend standard (Java doc). Read by ft-java-coding-agent / audit; overrides any other Java coding-standard skill on conflict.

ft-angular-standards

⭐ authoritative

The frontend standard (Angular doc). Read by ft-angular-coding-agent / audit; overrides any other Angular coding-standard skill on conflict.

cwmp-xml

protocol

Write/parse/validate CWMP (TR-069 SOAP) envelopes.

oma-lwm2m-expert

protocol

OMA LwM2M spec expert (v1.0–v2.0), CoAP/DTLS, FOTA, bootstrap. (extras stripped; trigger narrowed)

tr69hostif-issue-triage

domain

Triage tr69hostif/RDK device issues from logs.

iot-fleet-engineer

domain

Fleet provisioning, X.509 identity, staged OTA, telemetry budget.

emil-design-eng

design

UI polish & animation canon (easing/duration, transform-origin, reduced-motion, perf). Read JIT by ft-angular-coding-agent on any visual work; pairs with the impeccable plugin’s design-QA skills. Registry-managed: npx -y skills add emilkowalski/skill --skill emil-design-eng -g -a claude-code -y installs AND updates it, non-interactively (not vendored in this repo).

agent-browser

verification

Browser automation CLI (Chrome/Chromium over CDP, accessibility-tree @eN refs) — the single channel for every agent-driven browser check: UI verification, UI-bug observation, rendered before/after on refactors, checkpoint-F executor evidence. Canon: rules/agents/common.md. External: npm i -g agent-browser && agent-browser install; its skill file is a discovery stub — agents load the reference with agent-browser skills get core. Playwright keeps committed *.spec.ts e2e suites and the fallback role.

clickhouse-io

db

ClickHouse engines, ORDER BY indexes, batch inserts.

performance-engineer

perf

Observability, profiling, load testing, caching.

springboot-tdd

tests

TDD loop (JUnit5/Mockito/Testcontainers). FT-override banner applied.

springboot-verification

tests

Pre-PR build → static analysis → coverage → security scan. FT-override banner.

ft-fix

orchestration

Quality-gated bug fixing: drives bugfix-agent + parallel adversarial verification of the plan and the diff at two checkpoints. User-invoked only (/ft-fix, disable-model-invocation).

autoreview

review

External-engine final review. User-invoked only (/autoreview, disable-model-invocation).

receiving-code-review

review

How to act on incoming review feedback (verify, don’t blindly agree).

friendly-branded-docs

documents

The official Friendly Technologies branding skill (organization-library skill, extended in the toolkit). Builds Word documents from the approved Doc and Letter templates and PowerPoint decks from the PPT template, with the company icon library and Roboto fonts. Input is a JSON spec or Markdown (technical documents with images, code blocks, tables with any number of columns, numbered lists, inline formatting). Uses the Python 3 standard library only. Checks the structure (check_office.py) and renders the pages through real Word or PowerPoint (Windows, or macOS via AppleScript) or LibreOffice.
Skills we deliberately did NOT install (and why)

  • code-reviewer, requesting-code-review — redundant with the bundled /code-review; risk double-firing with autoreview.

  • security-review (library) — name-collides with the bundled /security-review (would silently disable it) and is wrong-stack (Next.js/Supabase/Solana).

  • brainstorming — its hard "no code until approved spec" gate fights plan-mode and the autonomous ft-developer flow.

  • java-coding-standards, springboot-patterns — superseded by ft-java-standards; no competing standards.

  • Skipped: java-pro (broken), performance-investigation (Svelte), coding-agent (needs openclaw), coding-standards (JS/TS only).

We also rely on Claude Code’s bundled skills: /code-review, /security-review, /verify, /simplify, /review.

MCP servers — the live data the agents reach

Skills are procedures; MCP servers are data sources. Agents query them at runtime for grounding.

Server What it gives Key tools Who · when

qdrant-vector-db ⭐

The FT vector knowledge base — docs, code, protocol params/specs, bugs, UI map (full breakdown in Knowledge Base).

semantic_search, list_sources, count_points, get_collection_info

all agents · ground before writing, validate a protocol path, find an analogue

jira-mcp

Implementation-ready ticket context — brief, logs, and an emulator seed from a Jira issue.

get_issue_brief (always first), get_issue_logs, get_issue_emulator

bugfix-agent, ft-developer · a ticket-driven task (e.g. DEV-1234)

context7

Up-to-date external library/framework docs (Spring, Angular, NgRx, Netty, Paho…).

resolve-library-id → query-docs

coding agents, ft-developer · an unfamiliar/external library API

tr069-emulator

Drives an emulated TR-069 device — reproduce device state and run CWMP sessions.

mcptr069-emulator* (seed the device tree via jira-mcp get_issue_emulator)

bugfix-agent, ft-doc-writer-agent, coding agents · reproduce / verify a device-level flow

mcp-obsidian

Read/write access to the team’s shared Obsidian Knowledge Vault — the agents' cross-session memory (full breakdown in Knowledge Vault).

obsidian_simple_search, note read/write

all pipelines (ft-fix, ft-developer, bugfix-agent) · search prior knowledge at task start, persist the root cause / decision at task end
Two more MCP servers are installed as native stdio processes (no Docker) — sequential-thinking (structured reasoning) and memory (a local knowledge graph). See Deployment § MCP servers.

  • Qdrant vs context7: Qdrant holds FT-specific knowledge (our docs/code/specs/bugs); context7 holds external library docs. Don’t confuse them.

  • jira-mcp: always call get_issue_brief first; pull logs / emulator only if the brief says they’re available and you need them.
Connecting them: install.sh registers all four at user scope (claude mcp add). Endpoints, transports, and the network prerequisite are in Deployment & Usage § MCP servers.

The user-visible gate (rules/ux/)

The costliest interface defects are not authored in *.tsx files. They are authored in a handler that returns a reason no frontend reads, in a catch block that forwards an internal phrase to a screen, in a panel that reports "failed" for work that never started. A trigger keyed to the file extension misses every one of them, so the toolkit keys its gate to the outcome instead:

File What it owns

rules/ux/user-visible-dod.md

The trigger ("a human will read, see, or decide from this — whatever the layer") and the Definition of Done that closes it. Its cross-layer core — consumer contract at file:line, the failure text written out, state truthfulness, recovery — is the class a green unit suite, a clean lint and a component-level review miss at once. Four items demand an artifact (a file:line, a quoted string, a computed contrast ratio, a screenshot path), because an item answered from memory is an item nobody ran. It is an inline self-check: minutes, not an agent run.

rules/ux/design-skill-routing.md

Property-to-owner routing against the installed inventory (never a remembered name list), the 0-4 escalation ladder with the preconditions that keep agent spend honest, and precedence when two design canons disagree.

Every consumer points at these instead of carrying a copy: rules/agents/common.md ("User-visible work"), the three coding agents' step 3b, the verifier Visual/UX lens (the DoD is its minimum attack list, and its cross-layer core needs no running app), ft-developer Stages 1/6/7/9, and bugfix-agent Gate B.

The ladder is the part that controls cost: rung 0 is the inline DoD, rung 2 one agent-browser drive, rung 4 a verifier agent — and rung 3 or 4 never runs on a slice that is still moving, parallel lenses must be disjoint, and a lens brief carries the diff, the exact route, the states and the DoD items already answered. A lens that has to re-derive its context is where "the agent was slow and no better" comes from.

deploy/templates/hooks/user-visible-gate.py makes the trigger deterministic outside the pipelines: a PostToolUse hook that fires after an edit to a UI file, an i18n catalog, a 4xx/5xx response, or any code that authors a sentence a person will read — at most three times per session, once per file. Its detection principle is the same as the canon’s: user-facing text looks like a sentence. Enumerating framework call sites (toastr., ResponseEntity.status() keys the rule on incidental syntax and goes silent on the next framework, so it looks for a quoted run of real words outside a logger call instead.

install.sh / install.ps1 copy it into ~/.claude/hooks/ and offer to wire it, appending to hooks.PostToolUse and never replacing what is there; the verify pass parses settings.json rather than matching text, so a wrongly-nested (and therefore dead) entry reports dead, not green. Wiring stays opt-in.

Finishing the class, not the instance (rules/code-quality/convergent-change.md)

Two domains in one service were asked the same question — what does it mean that a name is absent from a cache another service owns? — and answered it differently: one warned and imported, one blocked with Invalid parameters present: 4. Neither site is wrong when read on its own. The divergence is the defect, and nothing finds it by reading files: a text search for duplication returns nothing, because the two implementations look nothing alike.

The sweep that does find it asks by consumer, and the code graph answers it in one call:

search_graph(name_pattern=".*<TheSymbol>.*")     # the cache / client / validator / config key
trace_path(function_name="<theMethod>", mode="calls", direction="inbound", depth=2)

Run against the real repository, that returns both importers — and omits the third domain, which validates its own data and never consults that source. One query, the exact answer set, no grep. query_graph (Cypher) and search_graph(semantic_query=[…​]) cover the case with no shared symbol; trace_path(mode="cross_service") follows the question across an HTTP boundary.

Two rules make the result binding:

  • Divergence converges at TWO. Duplication tolerates two occurrences (Rule of Three); contradiction does not, because one of the two sites is lying to its callers right now. Converge onto the site that already reasoned it through — the one with the decision, the OpenAPI sentence describing it, and the tests — not onto the one you happen to be editing.

  • Refactors are proposed unprompted, with a contract: WHAT · WHY NOW (with file:line) · BUYS · BASED ON (a named principle and threshold, or an existing repo precedent) · COST · RISK · VERDICT. not-worth-it is a valid verdict worth stating, so the next run does not re-derive it. A refactor rides in the same diff only when it is the change — the shared-root fix is the smaller diff — because a diff mixing behavior with restructuring cannot be reviewed.

The related correctness rule lives next door in rules/code-quality/design-principles.md: a verdict computed from data another service owns has three states — confirmed, refuted, and not checked. Collapsing "the source was empty or unreachable" into "your input is invalid" produces a verdict that is false exactly when the other system is down.

Wired into: rules/agents/common.md, all three coding agents (step 3c, plus Convergence: and Refactor proposals: report fields), ft-developer Stages 7 and 9, bugfix-agent Phase 5 step 2a, refactor-agent Phase 5, the verifier checkpoint-2 and checkpoint-F rubrics, and ft-architecture-audit.

How skills fire (and how to keep them quiet)

Fact Consequence

Model-invoked by description

Keep descriptions narrow & action-first (< ~150 chars). Broad ones over-fire.

No tie-break; not concurrency-safe

Avoid overlapping triggers across skills.

~/.claude/skills/<name> overrides a bundled skill of the same name — silently

❌ Never name a skill code-review, security-review, verify, simplify, run, review…

disable-model-invocation: true

Makes a side-effect skill user-only (e.g. autoreview).

Hooks register only via plugin.json / frontmatter hooks:

Strip stray .claude/ from downloaded skills (done for oma-lwm2m-expert).
Next → Knowledge Base (the Qdrant collections in depth) · Deployment & Usage to install these and see example prompts.