devex

devex

Developer Experience Tools - A unified CLI for common developer operations.

Installation

Add the following to your mise.toml file:

[tools]
"github:project-init/devex" = "latest"  # We suggest pinning a version here

This will install the pre-compiled binary from GitHub releases.

Then run:

mise install

Usage

The devex CLI provides a unified interface for all developer experience tools:

devex <subcommand> [options]

Run devex --help to see all available subcommands, or devex <subcommand> --help for detailed help on a specific command.

---

Subcommands

Localize

Manage gotext translations and generate platform localization bundles.

Usage:

devex localize audit
devex localize html
devex localize mobile
devex localize translate

The mobile command generates localization bundles for the platforms present in its configuration. The currently supported iOS generator distills registered strings from each out.gotext.json catalog into an l10n-<locale>.json bundle. It also validates registry coverage, placeholders, and Swift translation-key usage before replacing existing bundles.

The html command reads each locale's curated messages.gotext.json catalog and writes a single combined HTML report to localize.html.outputPath, with one column per locale and one row per message id, so English source strings and their translations can be reviewed side by side in a browser. The report includes the full set of ids found across all catalogs, including new English ids that do not yet exist in another locale; their missing translations appear as empty cells.

Configure repository paths under .localize/*.yaml:

localize:
  localesDir: internal/translations/locales
  html:
    outputPath: build/translations.html
  mobile:
    sourceLanguage: en-US
    registryPath: internal/translations/mobileregistry/registry.go
    ios:
      sourceDir: ios/ProjectInit
      outputDir: ios/ProjectInit/Resources/l10n

---

SRE

Site Reliability Engineering toolbox for common operational tasks.

Available Tools:

• keygen - Generate API keys based on configuration
• postgres - PostgreSQL operations and access management
• release - Git tag and release management
• analyze - Code analysis operations
• echo - Print and transform arguments

Usage:

devex sre <tool> [args]

Configuration:

Create a .sre directory in your project root to store configuration files. The tool looks for this directory by default, but you can override it with the --configDir flag.

Additional Dependencies:

Some SRE tools require AWS CLI:

[tools]
awscli = "latest"  # Required for some postgres operations

Examples:

# Generate an API key
devex sre keygen

# Access a postgres database
devex sre postgres access

# Create a new release
devex sre release

---

Discovery

Guide an idea through discovery, produce reviewable Markdown and YAML artifacts, and publish the resulting work breakdown to Jira or GitHub Issues after human review.

The discovery feature is separate from the existing workplan command.

Install devex in the repository where discovery work will happen using the installation instructions. The CLI and all generated configuration and artifacts are owned by that consuming project; you do not run discovery from a checkout of the devex source repository.

Run the top-level command from an interactive terminal for guided setup. It detects existing AI harness directories, offers to install the companion skill, creates .sre/discovery.yaml when requested, and finishes with a readiness report:

devex discovery

The same flow is available explicitly and can safely install missing files without prompts:

devex discovery setup
devex discovery setup --harness codex --yes

You can also install only the companion Agent Skill:

# Installs for Codex, Claude Code, and Cursor by default.
devex discovery install-skill

# Or install only one harness.
devex discovery install-skill --harness codex

The command installs run-discovery under .agents/skills/, .claude/skills/, or .cursor/skills/. Commit the installed skill so each harness can discover the workflow in that project. Installation is idempotent: identical files are reported as UNCHANGED and are not rewritten. Different files are protected; review them before using --force to install an updated bundled version.

Check prerequisites:

# Checks all supported harnesses by default.
devex discovery doctor

# Check only the harnesses used by this project.
devex discovery doctor --harness codex

doctor is read-only. It validates the project directory, Git metadata, installed skill contents, .sre/discovery.yaml, and customized target values. It also reports whether provider credential environment variables are available without printing their values. Results are grouped as passed, flagged, and failed, with failures rendered last and highlighted in interactive terminals.

At least one selected harness must have the skill installed. Once one is installed, missing additional harness integrations are flagged for awareness rather than treated as failures. Modified installed skills and missing, invalid, or placeholder configuration remain failures. Missing credentials are warnings because they are only required by publish apply. The command exits nonzero only when failures are present.

Create and validate a bundle:

devex discovery init docs/discoveries audit-logs
devex discovery validate docs/discoveries/audit-logs

The generated bundle contains:

docs/discoveries/audit-logs/
├── .gitignore
├── discovery.md
└── work-breakdown.yaml

discovery.md is the narrative document for GitHub-based peer review. work-breakdown.yaml is a provider-neutral graph with stable work-item IDs, hierarchy, dependencies, acceptance criteria, labels, and estimates. The generated YAML includes every supported work-item field, using empty lists where appropriate so teams can see what is configurable without consulting the Go schema.

Configure project defaults and publication targets:

Generate .sre/discovery.yaml in the consuming project and adjust its named targets:

devex discovery config init

The example is also available at cmd/devex/discovery/example_config.yaml for contributors to devex. Project configuration files contain no credentials. Use --config <path> on init or publish plan when a project needs a different location.

Set credentials only for the provider being applied:

# GitHub
export GITHUB_TOKEN=...

# Jira
export JIRA_EMAIL=...
export JIRA_API_KEY=...

The Jira base URL and project key live in the target configuration. GitHub targets identify an owner and repository. Set the top-level default_target to the name of the target normally used by the project:

default_target: github-project
default_labels:
  - discovery
  - team-platform

default_labels is optional. init copies each configured label onto every starter work item in the generated breakdown; the discovery skill preserves those labels as it replaces or adds work items. Labels added directly to an item remain supported alongside the defaults.

publish plan resolves its target in this order: an explicit --target, default_target, or the only configured target. If multiple targets remain and no default is configured, it exits with an error listing the available targets. This keeps scripted overrides explicit while allowing the common path to omit --target.

Plan and apply publication:

devex discovery publish plan docs/discoveries/audit-logs
# Override the configured default when needed:
devex discovery publish plan docs/discoveries/audit-logs --target jira-project
devex discovery publish apply docs/discoveries/audit-logs/.publish/github-project/plan.yaml

plan performs no remote mutations. It writes a frozen plan and displays every proposed operation and mapping warning. apply executes that plan and atomically updates .publish/<target>/receipt.yaml after each operation.

Planning is reproducible: an unchanged bundle and target produce the same operations and the same plan_digest on any machine. Only generated_at records the run, and it is excluded from the digest. apply never re-plans; it executes the frozen artifact and refuses to run against a bundle that changed after the plan was written.

The generated .gitignore excludes .publish/. Receipts are small local YAML files that allow a later CLI session to resume an interrupted publication. Jira issue properties and hidden GitHub issue-body markers provide a secondary idempotency check if a receipt is lost.

The tool deliberately does not prove or verify peer approval. Review and approval happen through the team's normal GitHub process; a human explicitly runs publish apply afterward.

GitHub initiatives are tracking issues, and hierarchy and dependencies are rendered as links in issue bodies. Jira kind and issue-type mappings are configured per target. Jira publishes every depends_on edge as a real issue link oriented so the dependency blocks the dependent item; set link_type on the target to use a link type other than Blocks.

Write the discovery document's title as a Markdown link to the issue that prompted the investigation, as the template does. Jira relates every published epic back to that issue, and GitHub links it from the tracking issue's body, so a reader who lands there can reach the request behind it. A title linking another tracker is reported as a Jira warning and skipped, because only an issue in the target instance can be linked.

Item descriptions and acceptance criteria are GitHub Flavored Markdown. GitHub renders them directly; Jira converts them to Atlassian Document Format, so headings, lists, tables, task lists, code, emphasis, strikethrough, and links survive rather than flattening into prose. Raw HTML has no ADF equivalent and is dropped, and an image becomes a link to its source because ADF images reference uploaded attachments.

Published issues footer the discovery document as a URL on the repository's default branch, resolved from the origin remote. The link works once the branch carrying the bundle merges. A bundle outside a GitHub checkout has no such URL, and the footer is omitted rather than naming a path no reader can open.

---

Workplan

Generate and publish workplan templates for investigating features or problems. Workplans help estimate the effort needed to complete a task and can be published directly to JIRA.

Usage:

devex workplan generate <directory> <title>
devex workplan publish <workplan_path>

Generate Example:

devex workplan generate docs/investigations/infrastructure/moveToProjectInitStack example_title

This will generate a workplan template in the specified directory:

<directory>
└── <yyyy>_<m>_<d>_example_title
    ├── workplan.yaml
    └── problem.md

Publishing to JIRA:

Set the following environment variables (consider adding them to your shell profile):

export JIRA_URL=https://yourdomain.atlassian.net
export JIRA_EMAIL=your_jira_email
export JIRA_API_KEY=your_api_key

Then publish:

devex workplan publish docs/investigations/infrastructure/moveToProjectInitStack/2026_5_3_example_title/workplan.yaml

Getting Your JIRA API Key:

1. Navigate to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click "Create API token"
3. Give it a name and click "Create"
4. Copy the token and set it in your environment variables

Why JIRA?

JIRA is the most common work tracking tool used by the project-init team. While we don't claim it's the best tool, it's what we have expertise with and have built integration for.

---

Contributions

A lightweight, opinionated contribution signal generator for GitHub-based engineering teams. Analyzes PR and review activity over configurable time windows (10 / 30 / 90 days) and produces structured output for evaluating contribution patterns.

What It Provides:

• PR authorship counts
• PR review counts
• PR-to-review ratios
• Total merge time
• Average time-to-merge
• Weighted contribution scoring
• Share breakdowns across contributors and repositories

Philosophy:

This is NOT a replacement for leadership judgment.
It IS a visibility tool.

For design intent and cultural philosophy, see PHILOSOPHY.md

Usage:

# Collect PR data
devex contributions collect <config_file>

# Generate signal output
devex contributions signal <config_file>

Example:

devex contributions collect contributions_config.yaml
devex contributions signal contributions_config.yaml

Output:

User signal output:

user,weighted_total,weighted_prs,weighted_reviews,weighted_pr_share,weighted_review_share,num_prs,num_reviews,TotalTimeToMerge,average_days_to_merge
user1,107.98,73.58,34.40,0.68,0.32,74,172,724538000000000,0.11
user2,49.21,39.61,9.60,0.80,0.20,42,48,4127456000000000,1.14

Repository signal output:

repo,weighted_total,weighted_prs,weighted_reviews,weighted_pr_share,weighted_review_share,num_prs,num_reviews,TotalTimeToMerge,average_days_to_merge
business-platform,72.69,45.09,27.60,0.62,0.38,48,138,5021492000000000,1.21
admin-platform,48.03,39.63,8.40,0.83,0.17,40,42,637432000000000,0.18

These CSV outputs are easily imported into spreadsheets or analyzed with AI tools.

Configuration:

See example_config.yaml for a sample configuration file.

---

Components

Generate component skeleton code from YAML configuration files. Currently focused on database components for PostgreSQL-based Go services.

Usage:

devex components <configuration_file_path>

Example:

devex components .components

Configuration Example:

outputDirectory: "gen"

db:
  schemaName: data_platform

See example_config.yaml for a complete example.

DB Components:

The DB component generator outputs:

• User setup scripts
• Schema definitions
• IAM permissions setup
• Default migrations
• Post-release scripts
• sqlc configuration for Go service integration

All setup is optimized for PostgreSQL clusters.

---

Additional Resources

• Code of Conduct
• Contribution Guide

Development

Run tests:

mise test

Build locally:

go build -o devex ./cmd/devex

Run linting:

mise lint