Agent skill

sfdx-hardis Architecture Guide

by hardisgroupcom in hardisgroupcom/sfdx-hardis

Explains how the sfdx-hardis Salesforce CLI plugin is built: its TypeScript and Oclif stack, command layout, agent-mode flag and provider classes for git, notifications and AI.

AGPL-3.0Auto-check passedDevelopment

Install sfdx-hardis Architecture Guide

skills CLI
$ npx skills add hardisgroupcom/sfdx-hardis --skill architecture -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install hardisgroupcom/sfdx-hardis architecture --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/hardisgroupcom/sfdx-hardis.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.claude/skills/architecture .claude/skills/architecture && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
architecture
GitHub stars
401
Token cost
~2.1k tokens
SKILL.md length
638 words
Files
1
Skills in repo
21
Repo updated
First seen
Licence
AGPL-3.0

At a glance

Explains how the sfdx-hardis Salesforce CLI plugin is built: its TypeScript and Oclif stack, command layout, agent-mode flag and provider classes for git, notifications and AI.

  • Adding a new command to sfdx-hardis
  • SKILL.md covers Technology Stack, Project Structure, CLI Framework and Provider Pattern (src/common/), plus 6 more sections
  • Calls sf and yarn; reaches raw.githubusercontent.com
  • Deciding where a new git, notification or ticketing integration belongs

What it does

This is a contributor reference for the sfdx-hardis codebase. It lists the stack: TypeScript in strict mode, the Oclif framework used by the Salesforce CLI, Wireit for build tasks, Mocha with Nyc for tests and coverage, ESLint with Salesforce configurations, and LangChain for AI integration alongside Codex and Agentforce. Commands live under src/commands/hardis, number around 300, extend SfCommand and run as sf hardis followed by a topic and an action.

Commands should accept an --agent flag so AI agents and pipelines can run them without any interactive prompt, using sensible defaults. External integrations follow a provider pattern, with a root class and concrete implementations for git hosts (GitHub, GitLab, Azure DevOps, Bitbucket), notifications (Slack, Teams, email, API webhook), tickets (Jira, Azure Boards, ServiceNow), AI, post-deploy actions, key-value storage and documentation building.

When your agent uses it

  • Adding a new command to sfdx-hardis
  • Deciding where a new git, notification or ticketing integration belongs
  • Understanding how the project's providers, hooks and config fit together

Example prompts

  • “Add a new sfdx-hardis command under the audit topic and make it work with the --agent flag.”
  • “Where should a new Mattermost notification channel go? Follow the provider pattern.”
  • “Give me a map of the src/common folder and what each provider does.”

Requirements

  • A checkout of the sfdx-hardis repository

What it can do on your machine

Read from SKILL.md and the folder at commit 9625b22. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • sf
    • yarn

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Hosts in commands or code, which the agent is likely to contact:

    • raw.githubusercontent.com

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

sfdx-hardis Architecture Guide loads about 2.1k tokens when it runs. Until then it costs about 49 tokens; SKILL.md has 638 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~49
When it runs · the whole SKILL.md, loaded when a task matches
~2.1k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from hardisgroupcom/sfdx-hardis at commit 9625b22, republished under its AGPL-3.0 licence (© hardisgroupcom). 638 words, ~2,064 tokens.

Download SKILL.mdSave it as .claude/skills/architecture/SKILL.md (or your agent's skills folder).
name
architecture
description
sfdx-hardis project architecture, technology stack, provider pattern, configuration system, and project structure. Use when working with project structure, providers, hooks, or config.
user-invocable
false

Architecture

Technology Stack

  • Language: TypeScript (strict mode)
  • CLI Framework: Oclif (Salesforce CLI framework)
  • Build System: Wireit (task orchestration)
  • Testing: Mocha with Nyc for coverage
  • Linting: ESLint with Salesforce configurations
  • AI Integration: LangChain (Anthropic, Google GenAI, Ollama, OpenAI) + Codex + Agentforce

Project Structure

src/
├── commands/hardis/   # CLI commands (~300+) organized by domain
│   ├── auth/          ├── cache/       ├── config/
│   ├── datacloud/     ├── doc/         ├── git/
│   ├── lint/          ├── mdapi/       ├── misc/
│   ├── org/           ├── package/     ├── packagexml/
│   ├── project/       ├── scratch/     ├── source/
│   └── work/
├── common/
│   ├── aiProvider/    # AI integration and prompt templates
│   └── utils/         # Shared utilities (barrel-exported from index.ts)
├── hooks/             # Oclif lifecycle hooks
├── i18n/              # Translation files (9 locales)
test/                  # Test files (*.test.ts, *.nut.ts)
lib/                   # Compiled JavaScript output
messages/              # Oclif message files (.md)
defaults/              # Default configurations and templates
docs/                  # Project documentation

CLI Framework

  • Commands extend SfCommand<any> from @salesforce/sf-plugins-core.
  • Invoked as sf hardis <topic> <action>.
  • ESM module ("type": "module").
Headless / Agent Mode

When possible, every command should support a --agent boolean flag so it can be called non-interactively by AI agents and automation pipelines:

ts
// Flag declaration
agent: Flags.boolean({
  default: false,
  description: 'Run in non-interactive mode for agents and automation',
}),

// In run()
const agentMode = flags.agent === true;

// Guard every interactive prompt
if (!isCI && !agentMode) {
  const answer = await prompts({ ... });
}
  • Add '$ sf hardis:<topic>:<action> --agent' to the command examples array.
  • In agent mode the command must complete without blocking on any interactive prompt, applying sensible defaults instead.

Provider Pattern (src/common/)

External integrations use a root class + concrete implementations:

  • gitProvider: GitHub, GitLab, Azure DevOps, Bitbucket
  • notifProvider: Slack, MS Teams, Email, API webhook. Slack and Teams share the logical messaging channel; each provider declares its channel via getChannel(). Routing is filtered per notification type and per channel via severity thresholds. See the monitoring-notifications skill.
  • ticketProvider: Jira, Azure Boards, ServiceNow, Aha!, generic
  • aiProvider: LangChain-based (Anthropic, Google GenAI, Ollama, OpenAI) + Codex + Agentforce
  • actionsProvider: Post-deploy actions (Apex, data, manual, community publish, schedule batch)
  • keyValueProviders: Salesforce org, local test
  • docBuilder: Documentation generation

Monitoring Pipeline (src/common/monitoring/, src/common/notifProvider/)

hardis:org:monitor:all runs a list of sub-commands (monitoringCommandsDefault) on a configurable cadence. Each sub-command posts notifications through NotifProvider.postNotifications, which fans out to enabled channels (messaging / email / api) using per-notification-type severity thresholds. Defaults live in source; users override per-entry via the monitoringCommands property in .sfdx-hardis.yml, merged by key. The hardis:config:monitoring-defaults command exposes the full defaults payload to the VS Code extension UI.

When adding a monitoring command, a notification type, or changing default routing, use the monitoring-notifications skill -- it lists exactly which files to touch.

Configuration System (src/config/index.ts)

Three-Layer Config

Configuration uses a three-layer merge with priority: user > branch > project.

LayerFile locationsPurpose
Project (global)config/.sfdx-hardis.yml or config/.sfdx-hardis.yaml (also .sfdx-hardis.yaml/.yml at repo root, or package.json)Shared settings for the entire project, committed to git
Branchconfig/branches/.sfdx-hardis.<branch-name>.ymlPer-branch overrides (e.g., different target org, deploy options per environment). Branch name is auto-detected from git or CONFIG_BRANCH env var
Userconfig/user/.sfdx-hardis.<os-username>.ymlPer-developer overrides, typically git-ignored

Higher-priority layers override lower ones via Object.assign() (shallow merge).

Config File Discovery

Uses cosmiconfig to search for config files. Supported names: .sfdx-hardis.yaml, .sfdx-hardis.yml, and package.json (for project layer).

Show full SKILL.md (257 more words)Show less
Remote Config Inheritance

A config file can include an extends property pointing to a remote YAML URL. The remote config is fetched and merged underneath the local config (local wins). This allows sharing a common config base across multiple projects.

yaml
# config/.sfdx-hardis.yml
extends: https://raw.githubusercontent.com/mycompany/shared-config/main/.sfdx-hardis.yml
projectName: my-project
API
  • getConfig(layer) - returns merged config up to the specified layer ("project", "branch", or "user" - default "user")
  • setConfig(layer, propValues) - writes properties to the config file for the specified layer
  • CONSTANTS - static constants (API version, URLs, metadata type lists)
  • getEnvVar(name) - reads env var with Azure unresolved-variable detection
JSON Schema

All config properties are defined in config/sfdx-hardis.jsonschema.json (JSON Schema draft-07). This schema is used to:

  • Generate HTML documentation (yarn build runs generate-schema-doc)
  • Validate config structure
  • Power IDE autocompletion

When adding or modifying a config property, always update config/sfdx-hardis.jsonschema.json to keep it in sync. Each property should have $id, description, title, type, and optionally default, enum, examples, and docUrl.

Hooks (src/hooks/)

Oclif lifecycle hooks:

  • init: logging, upgrade check, websocket client
  • prerun: auth, dependency check
  • auth: authentication
  • postrun: cache store
  • finally: notifications

WebSocket Client (src/common/websocketClient.ts)

Communicates with VS Code extension (vscode-sfdx-hardis) for UI interactions, progress, and prompts. Every message carries an event handled in the extension's src/hardis-websocket-server.ts, so adding or changing one is an extension change too. See the vscode-sfdx-hardis skill for the full integration surface.

Utilities (src/common/utils/)

Barrel-exported from src/common/utils/index.ts:

  • uxLog() - logging
  • execSfdxJson() - CLI subprocess calls
  • Deploy, git, org, XML utilities

AI Prompt Templates

Located in src/common/aiProvider/promptTemplates/. Each exports a PromptTemplateDefinition with variables and multilingual text. Users can override by placing .md files in config/prompt-templates/ (.txt also supported for backward compatibility).

© hardisgroupcom, AGPL-3.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .claude/skills/architecture of hardisgroupcom/sfdx-hardis.

Open the folder on GitHubat commit 9625b22

Compare with similar skills

sfdx-hardis Architecture Guide next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

sfdx-hardis Architecture Guide compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
sfdx-hardis Architecture Guide this skillhardisgroupcom/sfdx-hardis401—~2.1kAutomated safety check: PassAGPL-3.0
GitDiagram Repository Overviewahmedkhaleel2004/gitdiagram18k—~427Automated safety check: PassMIT
GitDiagram Repo Architectureahmedkhaleel2004/gitdiagram18k—~429Automated safety check: PassMIT
Gh Bot Commentjetstreamapp/jetstream125—~616Automated safety check: PassCustom licence
CodeScope Codebase Graph AnalysisQwenLM/qwen-code28k1 repos~9.3kAutomated safety check: PassApache-2.0
Codegraph QAQwenLM/qwen-code-examples143—~4.3kAutomated safety check: PassNone

Similar skills

  • GitDiagram Repository Overview

    ahmedkhaleel2004/gitdiagram

    Explains the architecture of a public GitHub repository through GitDiagram: how the code is organized, the main components with paths, and a Mermaid diagram.

    18k GitHub stars~427 tokensUpdated today
    DevelopmentAuto-check passed
  • GitDiagram Repo Architecture

    ahmedkhaleel2004/gitdiagram

    Explains how a public GitHub repository is built by fetching its GitDiagram architecture diagram, components and optional explainer video.

    18k GitHub stars~429 tokensUpdated today
    DevelopmentAuto-check passed
  • Gh Bot Comment

    jetstreamapp/jetstream

    Post GitHub PR/issue comments, reviews, and review replies as the Jetstream bot account instead of the user's personal account.

    125 GitHub stars~616 tokensUpdated today
    DevelopmentAuto-check passed
  • Answers questions about code structure, history, bugs and PR risk using a CodeScope knowledge graph and semantic index built from the repository.

    28k GitHub starsUsed in 1 repo~9.3k tokens
    DevelopmentAuto-check passed
  • Codegraph QA

    QwenLM/qwen-code-examples

    Use CodeScope to analyze any indexed codebase via its graph database (neug) and vector index (zvec).

    143 GitHub stars~4.3k tokensUpdated 4 mo ago
    DevelopmentAuto-check passed
  • System Design

    aiskillstore/marketplace

    CTO's deputy for software architecture using Clean/Hexagonal Architecture principles.

    430 GitHub stars~1.1k tokensUpdated today
    DevelopmentAuto-check passed

More from hardisgroupcom/sfdx-hardis

All 21 skills in this repo
  • sfdx-hardis Training End-to-End Test

    hardisgroupcom/sfdx-hardis

    Walks the sfdx-hardis training course end to end as a learner would, against a real Developer Edition org and fork, fixing broken steps and screenshots that no longer match.

    401 GitHub stars~2.6k tokensUpdated today
    Auto-check: notes
  • Promotion Branches E2E Test

    hardisgroupcom/sfdx-hardis

    Runs a full end-to-end test of sfdx-hardis promotion branches and backpromote against real Salesforce orgs and a throwaway repository, then writes a report.

    401 GitHub stars~5.5k tokensUpdated today
    Auto-check: notes
  • Changelog Style Rules

    hardisgroupcom/sfdx-hardis

    Style rules for adding CHANGELOG.md entries: short, user-facing bullets grouped by command under the beta section, each linking the command's docs page.

    401 GitHub stars~1.4k tokensUpdated today
    Auto-check passed
  • Documentation

    hardisgroupcom/sfdx-hardis

    Documentation standards for sfdx-hardis commands (description format with Command Behavior and Technical explanations sections, MkDocs site, build:doc).

    401 GitHub stars~1k tokensUpdated today
    Auto-check passed
  • Fix Jscpd

    hardisgroupcom/sfdx-hardis

    Decision framework for fixing jscpd (copy-paste detector) errors.

    401 GitHub stars~613 tokensUpdated today
    Auto-check passed
  • I18n Usage

    hardisgroupcom/sfdx-hardis

    Code examples and patterns for using i18n translations in sfdx-hardis source code (uxLog, uxLogTable, prompts, markers).

    401 GitHub stars~479 tokensUpdated today
    Auto-check passed

Questions about sfdx-hardis Architecture Guide

What does sfdx-hardis Architecture Guide do?

Explains how the sfdx-hardis Salesforce CLI plugin is built: its TypeScript and Oclif stack, command layout, agent-mode flag and provider classes for git, notifications and AI. This is a contributor reference for the sfdx-hardis codebase. It lists the stack: TypeScript in strict mode, the Oclif framework used by the Salesforce CLI, Wireit for build tasks, Mocha with Nyc for tests and coverage, ESLint with Salesforce configurations, and LangChain for AI integration alongside Codex and Agentforce.

When should I use sfdx-hardis Architecture Guide?

sfdx-hardis Architecture Guide fits situations like: adding a new command to sfdx-hardis; deciding where a new git, notification or ticketing integration belongs; understanding how the project's providers, hooks and config fit together.

How do I install sfdx-hardis Architecture Guide in Claude Code?

Run `npx skills add hardisgroupcom/sfdx-hardis --skill architecture -a claude-code`. Or copy the skill folder (.claude/skills/architecture in hardisgroupcom/sfdx-hardis) into .claude/skills/architecture in your project. Claude Code loads it when a task matches its description.

How do I install sfdx-hardis Architecture Guide in Codex?

Run `npx skills add hardisgroupcom/sfdx-hardis --skill architecture -a codex`. Or copy the skill folder (.claude/skills/architecture in hardisgroupcom/sfdx-hardis) into .agents/skills/architecture in your project. Codex loads it when a task matches its description.

Can I use sfdx-hardis Architecture Guide in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add hardisgroupcom/sfdx-hardis --skill architecture -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/architecture, .gemini/skills/architecture, .github/skills/architecture and .opencode/skills/architecture in your project.

What does sfdx-hardis Architecture Guide need to run?

Going by SKILL.md and its folder, sfdx-hardis Architecture Guide needs the command-line tools its instructions call (sf and yarn). Our summary lists: A checkout of the sfdx-hardis repository.

Does sfdx-hardis Architecture Guide access the network?

SKILL.md names 1 domain. In commands or code: raw.githubusercontent.com; the agent is likely to contact it when it follows the instructions. This is read from the text; nothing was executed.

Is sfdx-hardis Architecture Guide safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does sfdx-hardis Architecture Guide use?

sfdx-hardis Architecture Guide is published under the AGPL-3.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does sfdx-hardis Architecture Guide use?

About 2.1k tokens (SKILL.md is roughly 8.3k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to sfdx-hardis Architecture Guide?

Skills that share tags, products or a category with sfdx-hardis Architecture Guide: GitDiagram Repository Overview (ahmedkhaleel2004/gitdiagram, 18k stars), GitDiagram Repo Architecture (ahmedkhaleel2004/gitdiagram, 18k stars), Gh Bot Comment (jetstreamapp/jetstream, 125 stars) and CodeScope Codebase Graph Analysis (QwenLM/qwen-code, 28k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains sfdx-hardis Architecture Guide?

hardisgroupcom (a GitHub organization) maintains it in hardisgroupcom/sfdx-hardis, which has 401 GitHub stars. The repository holds 21 skills in this directory. The repository was last updated on October 8, 2026.

Source: hardisgroupcom/sfdx-hardis on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.