Developer Guide · Claude Code & Plugins · TDIndustries Citizen Developer Program

01 — Overview

What this guide covers

The Citizen Developer Program website explains the lifecycle, roles, and review process. This page covers the hands-on development phase — how to use the tools to build the thing.

Claude Code is your AI pair programmer. The TD plugins are the instruction sets that tell Claude exactly how TD applications must be structured, styled, secured, and deployed.

When you use the plugins, Claude follows TD’s approved patterns automatically — the right folder structure, authentication wiring, code quality checks, and security scans all happen without you having to ask.

What you need before you start

Claude Code — available to all TD employees via the Claude Enterprise subscription. Contact the IT service desk if you do not have access.
The TD Industries plugins — see Section 02 for installation. TD Enterprise users have them automatically.
Node.js 24+ and Git — the build skill checks for these and walks you through installation if they are missing.

02 — Installing the Plugins

Setting up Claude Code for TD development

TD Industries publishes two plugins: software-development and td-governance. Enterprise users have them automatically.

TD Enterprise (automatic)

If you are on the TD Claude Enterprise subscription, the plugins are already available through the managed marketplace. No installation required. Open Claude Code and type /plugin to confirm software-development is listed.

Manual installation

If you need to install manually, run these two commands in any Claude Code session:

/plugin marketplace add TDICitizenDev/td-claude-plugins
/plugin install software-development@tdindustries

The td-governance plugin installs automatically alongside software-development.

What the governance plugin does

The td-governance plugin intercepts any request to build an application before Claude writes a single file. It redirects you to the standard skill. This is not optional — it exists so every citizen app starts from the same approved baseline.

⚠️

Apps built outside the standard plugin pattern will be rejected at AI App Review. The governance plugin is what makes review fast — not what slows you down.

Plugin structure

software-development

The primary plugin. Contains all citizen developer skills: build-fullstack-app, td-industries-style-guide, and pre-push-secret-scan.

td-governance

A mandatory guardrail plugin pinned org-wide. Triggers automatically when you ask Claude to build an app and redirects to the standard workflow. Users cannot opt out.

03 — The Skills

What each skill does

A skill is a set of instructions that Claude Code loads on demand to guide it through a specific task using TD’s approved patterns.

Skill	Plugin	How to Invoke	What It Does
build-fullstack-app	software-development	`/build-fullstack-app <name> <description>`	Creates one monorepo — a single `{app-name}/` folder with `ui/` and `api/` subfolders — with a React/Vite/MUI frontend and Express/TypeScript backend. Includes MSAL authentication, GitHub Actions CI/CD, validation tooling, git hooks, and auto-maintained release notes. The primary skill for all new applications.
td-industries-style-guide	software-development	`/td-industries-style-guide` or auto-invoked during UI work	TD visual standards — TDI Navy and Blue palette, Inter typography, MUI component patterns, button/input/alert patterns. Auto-invoked during any UI work by `build-fullstack-app`; invoke manually when reviewing or applying styling.
pre-push-secret-scan	software-development	Automatic — runs before every commit and push	Scans every file being committed for API keys, tokens, passwords, connection strings, and private keys. Blocks the operation and lists every finding until resolved. Cannot be skipped under any circumstances.

04 — Building

Creating a new application

Everything starts with one command. The skill handles the rest.

A

The governance redirect

When you ask Claude Code to build an app — in any phrasing — the td-governance plugin intercepts the request before Claude writes a single file and tells you:

"TD's standard scaffolding workflow is /build-fullstack-app from the
software-development plugin. It produces one monorepo (ui/ + api/) with all
TD conventions baked in: MUI styling, Entra auth, deploy workflows,
validation, release notes. I'll route you through that instead of
scaffolding manually — TD policy."

The only exceptions are one-off static HTML pages with no backend, modifications to an existing TD app already in the standard structure, or cases where you explicitly state you are building outside the standard (e.g., a throwaway prototype).

B

Running /build-fullstack-app

/build-fullstack-app my-app "A brief description of what this app does"

What the skill does, step by step

1
Prerequisite check
Verifies Node.js 24+, npm 11+, and Git. Installs missing tools with your permission before continuing.
2
Confirm app details
Confirms the app name, key data entities, and main pages. No files are created until you confirm.
3
Scaffold the frontend (my-app/ui/)
React + Vite + TypeScript + MUI + Tailwind, with TD’s visual style applied. Pre-wired to talk to the API.
4
Scaffold the backend (my-app/api/)
Express 5 + TypeScript with hardcoded mock data and MSAL authentication middleware.
5
Validation tooling & git hooks
ESLint, TypeScript checking, and a validate script added to both the ui/ and api/ folders. Git hooks run checks automatically on every commit.
6
Automated security review
Claude runs a security review and the secret scan against the generated code. Will not proceed if either finds a blocking issue.
7
CI/CD workflow files
GitHub Actions deploy files added to the repo. Used automatically when your app deploys — no action needed from you now.
8
Final checklist & summary
Claude verifies ~20 items and summarizes how to run the app locally.

C

Running locally

After scaffolding, Claude will ask whether you want to install dependencies and run both apps. Say yes. Claude will start the API on port 3000 and the UI on port 5173.

# In my-app/api/
npm install && npm run dev

# In my-app/ui/
npm install && npm run dev

Open http://localhost:5173 in your browser of choice. Authentication is automatically bypassed locally — you are signed in as “Dev User” without a Microsoft login. All your development and testing happens here before anything goes to Azure.

ℹ️

The scaffold uses hardcoded mock data. If your app needs to store data, you’ll request a database by checking “My app needs a Postgres database” when you deploy through Runway (see Section 08) — IT provisions it as part of approval.

05 — Guardrails

What the plugins enforce — and why

The plugins encode the same checks the AI App Review group performs. Building with them means your app arrives at review already meeting the bar.

🔍

Secret Scanning

The pre-push-secret-scan skill runs automatically before every git commit and git push. It cannot be skipped — even if you tell Claude to “just push it.”

What it scans for

Cloud keysAWS, Azure, GCP access keys and service account credentials

API tokensGitHub, Slack, Stripe, SendGrid, Twilio, generic bearer tokens, JWTs

Private keysRSA, DSA, EC, OpenSSH, PGP key blocks; .p12 and .pfx files

Connection stringsDatabase URLs with passwords, JDBC strings, MongoDB URIs, Redis passwords

.env filesAny .env file staged for commit (except .env.example)

High-entropy strings32+ character hex or 40+ character base64 assigned to secret-named variables

When a finding is detected Claude blocks the operation, lists every finding (with the secret redacted), explains the risk, and suggests how to fix it.

🚫

Never put credentials in source code. Use .env files locally and Azure Key Vault / GitHub Secrets in production. The scaffold creates .env.example files documenting required variables without containing real values.

🔐

Authentication & SSO

Every app built with the scaffold is pre-wired for Microsoft Entra ID (formerly Azure AD) single sign-on using MSAL. Locally, authentication is bypassed automatically. In production, every user must authenticate through TD’s identity provider.

The authFetch rule

All API calls from the UI must use the authFetch helper in src/api.ts, which automatically attaches the user’s Entra token to every request. The API middleware validates the token on every call.

🚫

Do not use raw fetch() for API calls. Use authFetch. The scaffold wires this correctly — do not change the auth pattern without IT involvement.

Entra configuration

Tenant and client IDs must be read from environment variables (VITE_AAD_TENANT_ID, VITE_AAD_CLIENT_ID) — never as literal strings in source code. The security review step checks for hardcoded Entra GUIDs.

🗄️

No localStorage or sessionStorage

Application data must not be stored in browser localStorage or sessionStorage. The scaffold’s final checklist verifies this. MSAL’s internal authentication cache is the only permitted exception.

Why this matters

Data is lost when the user clears their browser
IT cannot support or recover it
Creates data integrity and compliance gaps

🚫

Apps that store data in localStorage will be rejected at AI App Review. If your app needs persistence, contact IT to provision a database.

✅

Code Quality Enforcement

The scaffold installs tooling that enforces code quality on every commit:

TypeScript — both the ui/ and api/ folders are fully typed. The validate script runs tsc --noEmit and blocks commits on type errors.
ESLint — the pre-commit hook runs eslint --fix on staged files automatically, then validates. Commits are blocked if issues cannot be auto-fixed.
Matching types — src/types/index.ts must be identical between UI and API repos. Mismatches are a primary source of runtime bugs.
No any types — the final checklist verifies there are no TypeScript any types in the codebase.
ReleaseNotes.md — auto-updated by the post-commit hook on every commit. Reviewers use this to understand what changed.

Running validation manually

npm run check

Run this in both the ui/ and api/ folders before submitting for review. It runs typecheck, lint, and validate in sequence.

06 — Testing

What “done” looks like before review

Testing is your responsibility. Reviewers check safety, not functionality. Users finding bugs after deployment means you own the fix.

🖱️

Manual walkthrough

Walk through every user-facing screen and flow yourself — including the happy path, empty inputs, wrong inputs, the back button, and error conditions. If you can find it by clicking around, so can a user.

🧪

Unit tests

Ask Claude to write unit tests for the business logic it just wrote — calculations, validation, data transforms. These are cheap to generate and catch regressions when you make changes later.

👥

Second set of eyes

Have at least one other person who has never seen the app run it locally and try the main flows. They will click the wrong button and ask the questions a real user would ask — before review, not after.

💡

Write a test summary in your Pull Request description when you submit for review. If you cannot describe how you tested it, you have not tested it. Reviewers use the summary to scope their review.

Staying inside citizen dev scope

The program is designed for simple tools, automations, and lightweight applications. If your app grows to need complex database architecture, multi-system integrations, or broad organizational rollout, review it with the Product Team before continuing. A short conversation early saves weeks of misdirected development.

08 — Deploying & Maintaining

From local to live — and beyond

Your first deployment is self-service through Runway. After that, every change ships through a Pull Request — and you keep ownership the whole way.

Your first deployment: Runway

When your app runs locally and you’re ready to share it, deploy it yourself through Runway — TD’s self-service deployment portal. No terminal, no gh commands, and no waiting on IT to create repos for you.

1
Open Runway
Go to runway.tdindustries.com, sign in with your TD account, and click Ship a new app.
2
Enter the details
App name in kebab-case plus a one-line description. If your app needs to store data, check “My app needs a Postgres database.”
3
Drop your folder
Drag your whole my-app/ folder onto the upload area. Runway automatically excludes node_modules, dist, and .env, scans for secrets, and shows you exactly what will be submitted.
4
Submit for approval
Click Submit. An admin reviews your request — you don’t need to do anything else.
5
Runway does the rest
On approval, Runway creates the GitHub repo under TDICitizenDev, commits your code, registers your app’s sign-in, and deploys both ui/ and api/. You get an email when it’s live.

💡

Required: your app must run at http://localhost:5173 before you submit. If it doesn’t work locally, it won’t work hosted.

After it’s live: every change via a PR

Runway handles the first deployment. After that your code lives in a GitHub repo under TDICitizenDev and normal git takes over. Every change follows this path — no exceptions.

1
Develop locally
Branch, make changes, and test at http://localhost:5173.
2
Open a Pull Request
All changes go through a PR. Direct pushes to main are not permitted.
3
AI App Review
The review group approves the PR.
4
Change Management
A Change Management ticket is approved.
5
Merge & auto-deploy
The PR is merged to main and the pipeline redeploys both ui/ and api/ automatically.

🚫

Never push directly to main. main is protected — every change, including small bug fixes, goes through a Pull Request. This is a hard rule of the Citizen Developer Program.

Your responsibilities vs. IT’s

You own

Bug fixes and enhancements
Submitting all changes via PR
Notifying IT of data issues
Notifying IT and users before retiring

IT owns

PR security review
Infrastructure & hosting
Security incident response
Decommissioning & archiving

🔒

Security incidents are exclusively IT’s domain. If you discover or suspect a security issue, notify IT immediately through the service desk. Do not attempt to fix it or rotate credentials without IT’s involvement.

09 — Getting Help

Where to go when you hit a wall

Claude handles the technical work. IT handles the infrastructure. When you need a human, here’s who to contact.

What you need	Who to contact
Node.js, Git, or Claude Code setup	IT service desk
Database provisioning, SSO configuration, data source integration	Application Development / Platform Team via IT service desk
Code modularization (large app growing complex)	Application Development via IT service desk
Security incident or suspected vulnerability	IT service desk — mark as urgent
Plugin issues, skill questions, PR review questions	AI App Review group via Microsoft Teams
App scope grown beyond citizen dev — ready for Application Development	Product Team intake process (link on the program site) with manager approval

Questions about the program?

Contact the TDIndustries IT team through the standard IT service desk, or reach out directly to the AI App Review group via Microsoft Teams.