Deployment & Usage

Two things to set up:

(1) the agents & skills on each developer’s machine

(2) the per-repo wiring & CI guardrails

Then drive it with prompts.

Scripts at a glance

Every script ships in two lockstep forms — bash (.sh, BSD/macOS + GNU/Linux) and PowerShell (.ps1, native Windows — no WSL/Git Bash needed). Pick your platform; both produce the same result (the deterministic gen-component-map is byte-identical across all three OSes). Human-run ones are opt-in and preview with DRY_RUN=1 (bash) / $env:DRY_RUN=1 (PowerShell); CI ones gate a PR. The table lists the .sh; the .ps1 sibling sits next to it — see the note below.

Script Why (what it’s for) How to run Where

deploy/scripts/install.sh

Sync skills + agents into ~/.claude/ and register the agents' MCP servers (user scope). Nothing auto-installs.

DRY_RUN=1 deploy/scripts/install.sh then without it (SKIP_MCP=1 to skip MCP)

local · per dev

deploy/scripts/wire-repo.sh <repo>

Wire a repo to the toolkit: standard pointer in CLAUDE.md + component map + CI workflows. Idempotent, never commits.

DRY_RUN=1 deploy/scripts/wire-repo.sh ../ftacs

local · per repo

deploy/scripts/gen-component-map.sh [repo]

(Re)generate the deterministic COMPONENT-MAP.md skeleton (the basis for the drift gate + onboarding).

deploy/scripts/gen-component-map.sh .

local + CI

deploy/ci/component-map-gate.sh [repo]

Fail CI if the committed map is stale or untracked (treat it like generated code).

in CI (or bash … . locally)

CI

deploy/ci/semantic-coverage.sh [repo]

Fail CI if a skeleton module has no ### <module> section in the semantic layer.

in CI

CI

deploy/ci/component-map.yml · ft-code-reindex.yml

GitHub Actions wrappers: run the two gates on PRs · reindex ft_code on merge.

drop into .github/workflows/

CI
Human flow is install.sh (once per machine) → wire-repo.sh (once per repo); the rest run in CI. Details for each below.

On Windows, run the .ps1 sibling of any script instead — same name, same flags, same behaviour:

macOS / Linux (bash) Windows (PowerShell)

deploy/scripts/install.sh

deploy\scripts\install.ps1 (-Doctor for verify-only)

deploy/scripts/wire-repo.sh <repo>

deploy\scripts\wire-repo.ps1 <repo>

deploy/scripts/gen-component-map.sh [repo]

deploy\scripts\gen-component-map.ps1 [repo]

deploy/ci/component-map-gate.sh [repo]

deploy\ci\component-map-gate.ps1 [repo]

deploy/ci/semantic-coverage.sh [repo]

deploy\ci\semantic-coverage.ps1 [repo]

The CI workflows (component-map.yml, ft-code-reindex.yml) run on Linux runners and call the .sh; the .ps1 gates are for running the same checks locally on a Windows dev box. wire-repo’s managed CLAUDE.md pointer block is the only place the two forms differ cosmetically (per-platform wording); the CI-gated `COMPONENT-MAP.md is byte-identical.

1 · Local — install agents & skills

Opt-in sync into ~/.claude (nothing auto-installs).

This installs the toolkit’s agents & skills — it does not install the Claude Code CLI itself. On Windows, install.ps1 assumes claude is already on your PATH; if it isn’t yet, start with Install Claude Code (Windows) first. 
# preview first
DRY_RUN=1 deploy/scripts/install.sh
# then apply
deploy/scripts/install.sh

On Windows run the native PowerShell counterpart instead — feature-identical, same env flags (DRY_RUN / SKIP_MCP / SKIP_JDTLS / ASSUME_YES), no WSL or Git Bash required:

# preview first
$env:DRY_RUN=1; .\deploy\scripts\install.ps1
# then apply
Remove-Item Env:\DRY_RUN; .\deploy\scripts\install.ps1

Both installers sync the same assets and register the same MCP set — the four remote servers plus the native sequential-thinking / memory stdio servers (via npx, no Docker) — and both install the Java LSP backend jdtls (skip it with SKIP_JDTLS=1). The only platform deltas: install.ps1 mirrors assets with robocopy (vs rsync) and installs jdtls via Scoop (scoop install jdtls), where install.sh uses Homebrew (brew install jdtls). They are kept behaviourally in lockstep — an edit to one must be applied to the other.

Installs Into

skills/* (incl. ft-java-standards, ft-angular-standards, ft-fix)

~/.claude/skills/

agents/*.md (incl. ft-architecture-audit, bugfix-agent, verifier)

~/.claude/agents/

rules/* (JIT reference files agents read at runtime, e.g. the bugfix capability manifest and checklists)

~/.claude/rules/

MCP servers (user scope)

your Claude config (via claude mcp add)

Verify in Claude Code with /skills, /agents, and claude mcp list (or /mcp).

Plugins (installed separately — once per developer)

Claude Code plugins are not files this script can copy — they install interactively through the plugin system. The FT workflow expects four:

Plugin Why

superpowers

process skills: brainstorming, systematic-debugging, verification-before-completion, …

claude-mem

cross-session memory + AST tools — both capability manifests list it (recommended tier)

obsidian

Obsidian vault access — the knowledge-persistence layer agents write decisions/debugging notes to when present

impeccable

frontend design QA — shape/audit/polish/critique skills the feature pipeline applies to UI work (pairs with the emil-design-eng skill)

 
/plugin install superpowers@claude-plugins-official
/plugin install claude-mem
/plugin install obsidian
/plugin install impeccable

`install.sh’s verification step detects missing plugins and prints exactly this copy-paste block; it never installs plugins itself.

Registry skills (npx — updatable upstream)

emil-design-eng (UI polish & animation canon, read JIT by the Angular coding agent) comes from the public skills registry rather than this repo, so it keeps receiving upstream updates. The invocation is fully non-interactive — --skill installs just this one skill (no multi-select picker), -g puts it in ~/.claude/skills (never a stray project-local .claude/), -a targets Claude Code, and the two -y flags clear npx’s own prompt and the CLI’s confirmation:

npx -y skills add emilkowalski/skill --skill emil-design-eng -g -a claude-code -y
# installs just this skill to ~/.claude — re-run the same command anytime to update

The install.sh / install.ps1 verification detects it and offers this command when it is missing.

Never add a skill named like a bundled one (code-review, security-review, verify, simplify, review, run) — ~/.claude/skills/<name> silently overrides the bundled skill.

MCP servers — the agents' live data

install.sh also registers, at user scope, the MCP servers the agents query (skip with SKIP_MCP=1). It is idempotent — each server is removed then re-added, so re-running is safe.

Server Transport Endpoint

qdrant-vector-db

SSE

http://ai.friendly-tech.com:8095/sse

jira-mcp

HTTP (streamable)

http://ai.friendly-tech.com:7010/mcp

tr069-emulator

SSE

http://ai.friendly-tech.com:7011/sse

context7

HTTP

https://mcp.context7.com/mcp
The three FT servers are internal — you need network/VPN access to ai.friendly-tech.com; context7 is public. jira-mcp already speaks streamable HTTP (/mcp); qdrant-vector-db and tr069-emulator still use SSE (deprecated in Claude Code v2.1+ — migrate each as its server exposes /mcp). What each server is for: Claude Toolkit § MCP servers.

The four above are remote (HTTP/SSE) and auto-registered. The agents also use local stdio servers — a local process, so no endpoint or VPN. Each needs a local prerequisite, so the verification pass offers them per item rather than adding them unattended:

Server What it gives How it’s set up

mcp-obsidian

Read/write the shared Obsidian Knowledge Vault — the agents' cross-session memory.

stdio via uvx mcp-obsidian; needs your own Obsidian Local REST API plugin key, so it is offered, never auto-registered. $FT_VAULT_PATH is set alongside it (the agent’s git commits need a working tree).

sequential-thinking · memory

Structured step-by-step reasoning · a local knowledge-graph the agents accumulate.

Both installers register them natively via npx -y @modelcontextprotocol/server-… (stdio, no Docker). A Docker MCP gateway (MCP_DOCKER) that already exposes them counts as an alternative provider.

codebase-memory-mcp

The local code graph — graph-first localization + blast-radius for the pipelines.

A local binary (its own installer); the verification pass offers to install/register it and enable auto-index.

Maximum-quality setup (checklist)

The quality pipelines degrade gracefully — every missing capability has a documented fallback — but degraded is degraded: each run’s report prints a degradations: line naming what was missing (e.g. "knowledge-graph absent → blast radius grep-only"). A complete install is not evangelism — it directly improves verification statistics: knowledge-graph gives the Architecture/Regression lenses an evidence source independent of the code, claude-mem feeds past misses back into triage.

The canonical per-item lists (purpose · benefit · tier · fallback) are the two capability manifests the pipelines read at preflight:

  • ~/.claude/rules/bugfix/dependencies.md — the ft-fix / bugfix pipeline

  • ~/.claude/rules/feature/dependencies.md — the ft-developer feature pipeline

Tiers: required — the pipeline escalates or runs with a prominent warning without it; recommended — a named degradation; optional — nice-to-have. Beyond install.sh defaults, the manifests cover: the superpowers plugin, claude-mem, a knowledge-graph server, sequentialthinking, codebase-memory-mcp (index your repos!), ide-diagnostics, and the jdtls Java LSP (symbol-accurate navigation/diagnostics for the Java agents). Both installers set these up automatically: the two stdio servers (sequential-thinking, memory) via npx — no Docker required — and jdtls via Scoop (install.ps1) or Homebrew (install.sh); skip the Java LSP with SKIP_JDTLS=1. A Docker MCP gateway (MCP_DOCKER) is an optional alternative for the reasoning servers.

Every install.sh run ends with a verification pass over the full working set — toolkit assets, MCP servers (incl. codebase-memory-mcp and the Docker MCP gateway), and the four workflow plugins (superpowers / claude-mem / obsidian / impeccable). Anything missing gets an offer: MCP servers register on a per-item y (or ASSUME_YES=1 for CI); plugins get the exact /plugin install copy-paste block.

The local code-graph server (codebase-memory-mcp) has its own official installer (macOS/Linux; Windows uses the install.ps1 from that upstream repo — not the toolkit’s — inspect third-party installers before running):

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash -s -- --ui

install.sh’s verification offers this installer when the binary is absent, Claude registration when it is unregistered, and auto-indexing on session start (`config set auto_index true, file limit auto_index_limit 50000) when it is off — new projects index on first connection; previously-indexed ones join the background git-change watcher.

Re-run the verification alone anytime:

deploy/scripts/install.sh --doctor   # verify only — ok/MISSING per item + fix offers

2 · On-project — plug into the FT portal & CI

Wire a repo in one command

wire-repo.sh is opt-in (like install.sh) and idempotent — it does not commit; it leaves changes for the repo owner to review. It detects the stack and:

  1. inserts a managed standard pointer block (between <!-- FT-AI-TOOLKIT:START/END --> markers) into the repo’s CLAUDE.md (or existing AGENTS.md, else creates CLAUDE.md) — naming the right standard (ft-java-standards / ft-angular-standards / both) plus a non-negotiables quick-ref;

  2. generates COMPONENT-MAP.md and seeds COMPONENT-MAP.semantic.md;

  3. installs the CI workflows (component-map.yml, ft-code-reindex.yml).

DRY_RUN=1 deploy/scripts/wire-repo.sh ../ftacs   # preview (diff + file list)
deploy/scripts/wire-repo.sh ../ftacs             # apply; then review & commit in that repo
Re-running replaces the managed block in place (markers) — safe to run after every standard change.

Plug in as a sub-portal

The FT Docs Portal (ft-docs-portal) is built and hosted on its own server (Cloudflare Pages). It clones each product under ./sources/<repo> and renders every Antora component — PlantUML via its own Kroki server — so there is nothing to build here. Register this repo like the other products in ft-docs-portal/antora-playbook.yml:

content:
  sources:
    # … existing product sources (ft-acs, ft-device-network-service, oneiot-ui, …) …
    - url: ./sources/ft-ai-toolkit
      branches: main
      start_path: docs          # this repo's Antora component root (docs/antora.yml)

The component name is ft-ai-toolkit (docs/antora.yml); link it from the portal nav with xref:ft-ai-toolkit::index.adoc[FT AI Toolkit].

The product repos mount at start_path: docs/src; this repo uses docs — both are supported, just match what’s in docs/antora.yml.

Component map: two layers

The map has a mechanical skeleton and a semantic layer — gated differently.

File Content CI gate

COMPONENT-MAP.md

Generated skeleton: modules, Spring beans, JPA entities, DB tables, legacy MDC keys (should be empty), Angular counts. Deterministic.

Content — fails on any drift (component-map-gate.sh).

COMPONENT-MAP.semantic.md

AI-authored: per-module responsibility, boundaries, key flows, standard deviations. Seed from deploy/templates/.

Coverage — every skeleton module needs a ### <module> section (semantic-coverage.sh). Prose is not content-gated (LLM output isn’t reproducible).

 
# locally, before commit:
deploy/scripts/gen-component-map.sh .   # (re)write the skeleton COMPONENT-MAP.md
# then have an agent (ft-architecture-audit / ft-doc-writer-agent) update the
# semantic layer when a module is added or its responsibility shifts.

Component-map drift gate (per repo)

Treat the skeleton like generated code — CI fails if it’s stale or uncommitted, then fails if the semantic layer is missing a module. Drop in deploy/ci/component-map.yml:

# .github/workflows/component-map.yml
- run: bash <toolkit>/deploy/ci/component-map-gate.sh .   # skeleton drift
- run: bash <toolkit>/deploy/ci/semantic-coverage.sh .    # semantic coverage
The generator skips vendored/build dirs (node_modules, target, build…), is portable across BSD (macOS) and GNU (Linux CI), and was validated on ft-bs-client, ftacs, ft-device-network-service, oneiot-ui, and angular-ui.

Keep onboarding fast

Channel Wire-up

Component map

the CI gate above (mechanical skeleton, always fresh)

Qdrant ft_code

re-index on merge to main via ft-code-reindex.yml (deep semantic search) — sketch; wire the real indexer

CLAUDE.md / AGENTS.md

the managed standard-pointer block from wire-repo.sh
All three are installed in one shot by wire-repo.sh (see "Wire a repo in one command" above).

3 · Drive it — example prompts

Full list in deploy/prompts/example-prompts.md. The essentials:

# feature, end to end
Use ft-developer. Add <feature> to <repo>; grade the task; follow the matching FT standard;
run ft-architecture-audit before reporting.

# bug
Use bugfix-agent for DEV-1234.

# standard audit (read-only)
Use ft-architecture-audit on the current branch diff. Report violations with file:line.

# final external review (user-only)
/autoreview
usage-loop
Back to Overview · Java / Angular standards · the Toolkit.