trae-coding-engine

Install the Trae AI-Coding best-practice guardrails — AGENTS.md, Skill Router, docs/adr templates & guidance, 204 template files, and SKILL.md skill definitions — into any repo with a single command.

What you get

A complete set of AI-coding best practices extracted from a production enterprise agent platform, sanitized and generalized for any team to adopt.

Quick start

# One-shot (no install needed)
npx trae-coding-engine setup

# Or install globally
npm install -g trae-coding-engine
coding-engine setup

This installs the following into your project:

| Destination | Content | |---|---| | AGENTS.md (repo root) | Cross-tool source of truth — instructions for every AI coding agent (Trae, Cursor, Copilot, Claude Code, Codex, Gemini, etc.) | | Makefile.coding-engine (repo root) | AI-coding check targets only — installed as a separate file, does NOT overwrite your existing Makefile. Use make -f Makefile.coding-engine help or include Makefile.coding-engine from your Makefile. | | REGISTRY.md (repo root) | Skill registry / router index | | MR-Template-Default.md (repo root) | Merge-request template | | docs/ | Architecture doc templates & guidance — scaffold files for architecture overview, project layout, component design, data model, and conventions. Write your own project-specific docs using these templates. | | docs/adr/ | ADR templates & conventions — ADR writing guide, record template (0000-template.md), and an empty index to get you started. Your team writes the actual decision records. | | docs/runbooks/ | Runbook templates & oncall playbook guidance | | scripts/ (103 files) | Engineering check scripts (.sh + .py) — ADR, MR hygiene, skill sync, docs audit, self-maintenance, etc. | | .agents/skills/ | Skill definitions: architecture, code-review, cve-remediation, db-schema, deploy-config, docs-audit, http-api, issue-autodev, merge-request, observability, refactor-insight, release-merge, runtime-adapter, testing | | .ci-templates/ | Issue templates (ai-task, bug, skill-evolution) and CI pipeline configs | | .gitlab/merge_request_templates/ | MR templates | | .cursor/rules/ | Cursor skill-router rules | | .claude/agents/ | Claude Code agent definitions (code reviewers) | | .codex/agents/ | Codex agent definitions | | .coco/agents/ | Coco agent definitions | | .semgrep/ | Semgrep rules for refactor insights | | Root config files | .golangci.yml, .pre-commit-config.yaml, .yamllint.yml, .dockerignore, .gitignore, etc. |

Commands

coding-engine setup   [options]   # Install everything
coding-engine update  [options]   # Alias of `setup --force`
coding-engine list                # Show every file this package would install
coding-engine doctor  [options]   # Diagnose an existing install (missing / drifted files)
coding-engine --help
coding-engine --version

Options

| Flag | Description | |---|---| | --target <dir> | Target repo root. Default: current working directory. | | --scripts-dir <dir> | Where to place shell / py scripts. Default: <target>/scripts | | --skills-dir <dir> | Where to place the SKILL.md tree. Default: <target>/.agents/skills | | --force | Overwrite existing files (a .bak copy is kept for anything modified) | | --dry-run | Print the plan without touching disk | | --no-chmod | Skip chmod +x on installed shell / py scripts | | --only <group> | Comma-separated groups to install (see below) | | --yes / -y | Skip the confirmation prompt |

Install groups

Use --only to install specific groups:

| Group | Content | |---|---| | agents-md | AGENTS.md — cross-tool agent instructions | | makefile | Makefile.coding-engine — AI-coding check targets (does NOT overwrite your Makefile) | | registry | REGISTRY.md — skill registry | | mr-template | MR-Template-Default.md | | docs | Architecture doc templates & guidance | | adr | ADR templates & conventions | | scripts | Engineering check scripts | | skills | .agents/skills/ — SKILL.md definitions | | ci-templates | .ci-templates/ — issue templates, pipelines | | gitlab | .gitlab/ — MR templates | | cursor-rules | .cursor/rules/ — Cursor skill router | | claude-agents | .claude/agents/ — Claude Code reviewers | | codex-agents | .codex/agents/ — Codex reviewers | | coco-agents | .coco/agents/ — Coco reviewers | | semgrep | .semgrep/ — Semgrep rules | | root-config | Root config files (lint, pre-commit, etc.) |

Examples

# Install everything
coding-engine setup

# Install only docs and ADR
coding-engine setup --only docs,adr

# Install only AGENTS.md and scripts
coding-engine setup --only agents-md,scripts

# Preview without writing
coding-engine setup --dry-run

# Force-update everything (existing files get .bak backups)
coding-engine update

# Check what's missing or drifted
coding-engine doctor --target /path/to/repo

Why docs/ and adr/?

The docs/ directory is a first-class citizen of this best-practice package. Before starting any significant feature work, you should have:

1. Architecture overview (docs/00-architecture-overview.md) — so every contributor and AI agent understands the system structure
2. Project layout (docs/01-project-layout.md) — directory structure and module boundaries
3. Component docs (docs/02-*.md through docs/NN-*.md) — one doc per major component
4. Data model doc (docs/07-data-model.md) — the canonical schema reference
5. ADR records (docs/adr/) — architecture decision records that capture why technical decisions were made, not just what was decided

This package provides templates and guidance for all of these — not pre-filled content. The templates include section headers, placeholders, and writing tips. Your team fills in the project-specific details. This is intentional: every project's architecture is different, and copying another project's design decisions would lead to cargo-cult architecture.

Each doc carries implementation status markers ([Implemented] / [Partial] / [Planned]) to distinguish shipped behavior from design intent — see docs/CONVENTIONS.md for the full spec.

How it works

1. The npm package ships a templates/ directory containing all 204 source files.
2. setup walks templates/ and copies each file to the corresponding destination in your repo.
3. Root files go to the repo root; directory trees preserve their structure.
4. .sh and .py files are chmod +x by default (skip with --no-chmod).
5. If a file already exists with different content, it is skipped by default. Use --force to overwrite.
6. Re-running setup is idempotent.

Requirements

• Node.js >= 16
• No external dependencies (zero-dependency CLI, uses only Node.js stdlib)

License

Apache-2.0