deploy

Orchestrates the full deployment pipeline for a full-stack application. Builds artefacts, runs pre-deployment checks, pushes to the target environment, and reports the outcome.

Usage

"Deploy the current branch to staging"
"Deploy version 2.4.1 to production with a canary rollout"
"Deploy only the backend service to staging"

Deployment targets

The skill reads target definitions from deploy.config.json at the project root:

{
  "targets": {
    "staging": {
      "provider": "aws",
      "region": "eu-west-1",
      "cluster": "staging-ecs",
      "services": ["api", "worker", "frontend"]
    },
    "production": {
      "provider": "aws",
      "region": "eu-west-1",
      "cluster": "prod-ecs",
      "services": ["api", "worker", "frontend"],
      "strategy": "canary",
      "canaryWeight": 10
    }
  }
}

Deployment steps

1. Run npm run build (or the configured build command)
2. Execute the test suite and abort on failure
3. Build and push Docker images tagged with the commit SHA
4. Update the target service definition
5. Wait for the health check to pass
6. Print the deployment URL and service versions

Rollback

If the health check fails after deployment, the skill automatically rolls back to the previous task definition and reports the failure:

Deployment failed — health check timeout after 120s
Rolled back api service to revision 47

Supported providers

• AWS ECS / Fargate
• Google Cloud Run
• Heroku
• Fly.io
• Custom (via deploy script hook)

scaffold

Generates project structure, boilerplate files, and configuration for new features or entire new services following the team's conventions.

Usage

"Scaffold a new REST endpoint for user notifications"
"Create a new React feature module for the checkout flow"
"Scaffold a new microservice for email delivery"
"Add a new database entity for subscription plans"

What can be scaffolded

Backend (Node.js / TypeScript)

• REST endpoint: controller, service, repository, DTO, tests
• GraphQL resolver with schema type, resolver, and data source
• Background job / queue consumer
• New microservice with Dockerfile, CI config, and health endpoint

Frontend (React / Vue)

• Feature module: component, hook, context, styles, and test
• Page with route registration
• Form with validation schema
• Data-fetching hook with error boundary

Shared

• Database migration file with up/down functions
• OpenAPI schema entry
• Environment variable declarations in .env.example

Conventions applied

• File and folder naming follows the project's existing pattern (detected automatically)
• Imports use the project's configured path aliases
• Test files are placed alongside source files or in the __tests__ directory, whichever the project uses
• Generated code passes the project's linter and formatter without modification

Example output

Scaffolding REST endpoint: GET /api/notifications

Created:
  src/api/notifications/notifications.controller.ts
  src/api/notifications/notifications.service.ts
  src/api/notifications/notifications.repository.ts
  src/api/notifications/dto/notification.dto.ts
  src/api/notifications/__tests__/notifications.controller.spec.ts
  db/migrations/20240315_create_notifications_table.ts

/build

Triggers the full build pipeline for the project, including compilation, asset bundling, and Docker image creation. Reports build output and any errors.

Usage

/build
/build staging
/build production --no-cache

Arguments

Build steps

1. Install or verify dependencies (npm ci)
2. Run TypeScript compilation (tsc --noEmit for type checking)
3. Bundle frontend assets (npm run build:client)
4. Compile backend (npm run build:server)
5. Build Docker images for each service
6. Run smoke tests against built artefacts

Output

[build] Installing dependencies... done (2.1s)
[build] Type checking... done (4.3s)
[build] Bundling frontend... done (12.7s)
[build] Compiling backend... done (3.1s)
[build] Building Docker images...
  api:abc1234 done
  worker:abc1234 done
[build] Build successful in 24.8s

Failure handling

On failure, the command prints the error output from the failing step and exits. The --verbose flag streams all output in real time rather than buffering it.

/test

Runs the project test suite with coverage reporting. Supports filtering by file pattern, test name, or suite type.

Usage

/test
/test unit
/test integration
/test src/api/users/
/test --watch

Arguments

Test suites

Output

[test] Running unit tests...
  ✓ UserService > creates a user (12ms)
  ✓ UserService > rejects duplicate email (8ms)
  ✓ NotificationService > sends welcome email (5ms)
  ...
  47 passed, 0 failed (1.4s)

[test] Coverage: 84.2% statements, 79.6% branches
[test] Coverage report written to coverage/

Notes

• Integration tests require Docker to be running (Testcontainers spins up databases automatically)
• E2E tests require the application to be running; start it first with /build and npm start

architect-agent

An autonomous agent that helps design system architecture, review technical decisions, and evaluate trade-offs for full-stack applications. Acts as a technical sounding board grounded in the existing codebase.

Capabilities

• Analyses the existing codebase to understand current architecture and constraints
• Proposes system designs for new features with component diagrams in Mermaid
• Reviews architectural decisions for scalability, maintainability, and security implications
• Identifies coupling, circular dependencies, and layering violations
• Recommends patterns (CQRS, event sourcing, saga, BFF, etc.) when appropriate
• Evaluates database schema designs and query access patterns
• Reviews API contract designs (REST, GraphQL, gRPC) for consistency and evolvability

Usage

"Design the architecture for a real-time notification system"
"Review the current service boundaries — are they well-defined?"
"We need to add multi-tenancy. What are the options and trade-offs?"
"Is our current database schema going to scale to 10M users?"
"Should we split the monolith? What would the service boundaries be?"

Output style

The agent communicates as a senior engineer: it asks clarifying questions when requirements are ambiguous, presents options with explicit trade-offs, and recommends a path while explaining why. It avoids over-engineering and explicitly calls out when a simpler approach is sufficient.

Example response structure:

## Notification system — architecture options

### Option A: in-process event bus
Pros: simple, no new infrastructure
Cons: does not survive process restarts, no fan-out

### Option B: message queue (Redis Streams / SQS)
Pros: durable, scalable fan-out, retry support
Cons: operational overhead, eventual consistency

### Recommendation
Given your current scale (<100k users) and team size (5 engineers),
Option B with Redis Streams is the right call. It avoids the fragility
of Option A without the complexity of a full message broker.

Context used

The agent reads the repository structure, existing service definitions, database migrations, and API contracts before responding to ensure recommendations are grounded in the real codebase rather than generic advice.

pre-push hook

Runs a final quality gate before commits are pushed to the remote repository. Ensures that nothing broken is shared with the rest of the team.

Checks performed

1. Full test suite — runs unit and integration tests (not E2E, which are too slow for a push hook)
2. Build verification — confirms the project compiles without errors
3. Security scan — quick scan for hardcoded secrets in the commits being pushed
4. Branch policy — prevents direct pushes to main or master; requires a pull request

Behaviour

The hook receives the list of commits being pushed. It only runs checks relevant to the diff (e.g., if no source files changed, the build step is skipped). This keeps the hook fast for documentation-only pushes.

[pre-push] Checking 3 commits for push to origin/feature/checkout-flow
[pre-push] Running tests... 47 passed (1.4s)
[pre-push] Build verification... ok (3.1s)
[pre-push] Secret scan... clean
[pre-push] All checks passed. Pushing.

Branch protection

pre-push:
  protected-branches:
    - main
    - master
    - release/*
  allow-force-push: false

Attempting to push directly to a protected branch produces:

[pre-push] Direct push to 'main' is not allowed.
[pre-push] Open a pull request instead: https://github.com/org/repo/compare/your-branch

Configuration

pre-push:
  tests: unit              # "unit" | "all" | false
  build: true
  secret-scan: true
  protected-branches: [main, master]
  skip-for-tags: true      # tags bypass this hook

Bypassing

git push --no-verify

Force-push attempts to protected branches are blocked even with --no-verify if the remote has branch protection rules enabled.

post-deploy hook

Runs automatically after a successful deployment. Performs smoke testing, cache warming, and notifications so the team knows the deployment succeeded and the service is healthy.

Actions performed

1. Smoke tests — sends a set of HTTP requests to key endpoints and verifies expected responses
2. Cache warming — pre-fetches high-traffic pages or primes application-level caches
3. Database migration check — verifies that pending migrations were applied successfully
4. Notification — posts a deployment summary to the configured Slack channel or webhook
5. Monitoring alert suspension — pauses deployment noise alerts in PagerDuty / Grafana for 5 minutes

Smoke test configuration

Define smoke tests in deploy/smoke-tests.json:

[
  { "path": "/health", "expect": { "status": 200, "body": { "status": "ok" } } },
  { "path": "/api/version", "expect": { "status": 200 } },
  { "path": "/api/products", "expect": { "status": 200, "maxMs": 500 } }
]

Notification format

Deployed api@abc1234 to production
  3/3 smoke tests passed
  Response time p95: 142ms
  Deployed by: mathieu.durand
  Duration: 3m 12s

Configuration

post-deploy:
  smoke-tests: deploy/smoke-tests.json
  warm-cache: true
  notify:
    slack:
      webhook: ${SLACK_DEPLOY_WEBHOOK}
      channel: "#deployments"
  monitoring:
    suppress-alerts: 5m
    provider: grafana

Failure handling

If smoke tests fail, the hook:

1. Triggers automatic rollback via the deploy skill
2. Posts a failure notification with the failing test details
3. Re-enables monitoring alerts immediately

Notes

• The hook runs in the context of the deployment pipeline, not on the developer's machine
• Environment-specific configuration is selected based on the DEPLOY_ENV variable set by the deploy skill

git-mcp

MCP server that exposes Git repository data to Claude. Provides access to commit history, diffs, branches, tags, and blame information without requiring shell command execution.

Capabilities

Usage examples

"Show me the last 10 commits that touched src/api/users/"
"What changed between v2.3.0 and v2.4.0?"
"Who last modified the payment service and when?"
"What commits are on this branch that aren't on main yet?"
"Show me the full diff for commit abc1234"

Configuration

The server operates on the current workspace root by default. For monorepos with multiple Git repositories, specify the target:

{
  "git-mcp": {
    "workspaceRoot": "${workspaceFolder}",
    "maxLogEntries": 500,
    "diffContextLines": 5
  }
}

Notes

• Read-only: no write operations (commit, push, reset) are exposed
• Binary file diffs are summarised as "binary file changed" rather than shown inline
• Commit messages and diffs are truncated at 50KB per entry to avoid context overflow

eslint-lsp

LSP server that surfaces ESLint diagnostics and auto-fix actions for JavaScript and TypeScript files within the full-stack-toolkit workflow.

Installation prerequisite

ESLint must be available either locally in the project or globally:

npm install --save-dev eslint
# or globally:
npm install -g eslint

Capabilities provided

Integration with the toolkit

Within full-stack-toolkit, eslint-lsp is complementary to typescript-language-server (from the lsp-tools plugin if installed). ESLint handles style and quality rules; TypeScript handles type correctness. Both diagnostic streams are merged and presented together.

The /build command respects ESLint: the build step runs eslint src/ --max-warnings 0 and fails if any warnings are present in production build mode.

Configuration

The server reads the project's ESLint configuration automatically. A recommended baseline for full-stack TypeScript projects:

// eslint.config.js
import js from "@eslint/js";
import tseslint from "typescript-eslint";

export default tseslint.config(
  js.configs.recommended,
  ...tseslint.configs.recommended,
  {
    rules: {
      "@typescript-eslint/no-floating-promises": "error",
      "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
      "no-console": "warn"
    }
  }
);

Plugin settings

{
  "eslint-lsp": {
    "run": "onSave",
    "fixOnSave": false,
    "validate": ["javascript", "javascriptreact", "typescript", "typescriptreact"]
  }
}

Notes

• run: "onType" provides the fastest feedback but increases CPU usage on large files
• Type-aware lint rules require parserOptions.project pointing to your tsconfig.json