Customization Guide

How to customize devtronic for your project.

AGENTS.md / CLAUDE.md

AGENTS.md is the universal AI context file. Claude Code uses CLAUDE.md, which is a symlink to AGENTS.md.

Recommended Structure

# AI Agents Guide

## Quick Start
[Brief description and essential commands]

## Commands
[Common commands for development]

## Critical Rules
[Non-negotiable rules the AI must follow]

## Architecture
[Key patterns and decisions]

## Project-Specific
[Anything unique to your project]

What to Include

Do include:

Commands Claude can't deduce from code (special flags, env vars)
Non-obvious architectural decisions
Project-specific conventions not in linting
Known gotchas and how to avoid them
Sensitive operations that need human approval

Don't include:

Things obvious from the code (standard patterns)
Generic best practices Claude already knows
Duplicate information from docs
Overly verbose explanations

Self-Improvement Pattern

After any correction, tell Claude:

"Update CLAUDE.md so you don't make that mistake again."

Claude is good at writing rules for itself. Common additions:

"Don't use X pattern, use Y instead"
"Always check Z before modifying W"
"This file requires special handling because..."

Custom Rules

Rules are auto-applied guidelines. Format varies by IDE.

Claude Code Rules

Location: .claude/rules/*.md

---
alwaysApply: true
---

# My Rule

Instructions here...

Frontmatter options:

Field	Description
`alwaysApply`	Always apply this rule (default: false)
`paths`	Apply only to files matching these globs

Path-specific rule example:

---
paths:
  - "src/api/**/*.ts"
---

# API Layer Rules

When working in the API layer:
- Always validate input with Zod
- Return consistent error responses
- Log all errors

Cursor Rules

Location: .cursor/rules/*.mdc

---
description: What this rule does
alwaysApply: true
globs: "src/**/*.ts"
---

# My Rule

Instructions here...

MDC (Markdown Components) format - Cursor's extension of Markdown.

Google Antigravity Rules

Location: .agent/rules/*.md

# My Rule

Instructions here...

Antigravity uses plain Markdown without frontmatter in the .agent/rules/ directory.

Custom Skills

Skills are invocable workflows. Create yours in .claude/skills/.

Quick way: Use /create-skill for guided skill creation through conversation.

Manual way: Create the file directly following the structure below.

Basic Structure

---
name: my-skill
description: Brief description shown in help
disable-model-invocation: true
disallowed-tools: Edit, Write, NotebookEdit
---

# My Skill

## When to Use

[Describe when to invoke this skill]

## Process

[Step-by-step workflow]

## Output Format

[Expected output structure]

## Tips

[Usage tips]

Frontmatter Options

Field	Description
`name`	Display name. The command comes from the directory name
`description`	What the skill does and when to use it — Claude reads this to decide when to load it
`argument-hint`	Hint shown in autocomplete, e.g. `"[feature]"`
`allowed-tools`	Tools pre-approved for the turn that invokes the skill
`disallowed-tools`	Tools removed from Claude's pool while the skill is active
`disable-model-invocation`	`true` means only you can invoke it, never Claude
`context`	`fork` runs the skill in its own subagent context
`background`	With `context: fork`, `false` waits for the result in the same turn
`paths`	Globs that limit when the skill auto-activates

`allowed-tools` grants, it does not restrict

This is the field most often misread. allowed-tools pre-approves the listed tools so Claude can use them without a permission prompt during that turn. It does not limit what the skill can reach — every other tool stays callable and follows your normal permission settings.

So allowed-tools: Bash, Write, Edit does not mean "this skill may use Bash, Write and Edit". It means "let this skill run any shell command and write any file without asking you". Write narrow rules, or none at all:

# Nothing to pre-approve — reads never prompt inside the workspace anyway
# (no allowed-tools line)

# Writes confined to the artifacts directory
allowed-tools: Edit(thoughts/**)

# One exact command this skill always needs
allowed-tools: Bash(git worktree *)

Path rules are checked against Edit(...) and Read(...) only. Use Edit(docs/**), never Write(docs/**) — the latter is accepted but never consulted, and warns at startup.

To actually restrict a skill, use disallowed-tools:

# A read-only reviewer that must never modify code
disallowed-tools: Edit, Write, NotebookEdit

Example: Custom Deploy Skill

---
name: deploy
description: Deploy to staging or production environment
disable-model-invocation: true
allowed-tools: Bash(./scripts/deploy.sh *)
---

# Deploy

Deploy the application to staging or production.

## Usage

/deploy staging # Deploy to staging /deploy prod # Deploy to production (requires confirmation)


## Process

1. Verify clean git status
2. Run tests
3. Build application
4. Execute deployment command
5. Verify deployment health

## Commands

```bash
# Staging
npm run deploy:staging

# Production (requires DEPLOY_KEY)
npm run deploy:prod

Verification

After deployment, check:

Health endpoint returns 200
No errors in logs
Key features working


---

## Custom Agents

Agents are specialized subagents invoked via the Agent tool.

### Basic Structure

```markdown
---
name: my-agent
description: What this agent does
tools: Bash, Read, Grep, Glob
model: haiku
---

You are a [role] specialist for this project.

## When to Invoke

Claude should invoke you when:
- [condition 1]
- [condition 2]

## Process

1. [Step 1]
2. [Step 2]

## Output Format

[Define expected output]

Frontmatter Options

Field	Description
`name`	Unique id, lowercase and hyphens. Cannot contain `:` (reserved for plugin namespacing)
`description`	When Claude should delegate to this agent
`tools`	Allowlist. Inherits everything if omitted
`disallowedTools`	Denylist, applied first. Use it to make a read-only agent actually read-only
`model`	`haiku`, `sonnet`, `opus`, `fable`, a full model id, or `inherit`
`maxTurns`	Cap on agentic turns before the agent stops
`memory`	`user`, `project` or `local` — persistent memory across sessions
`effort`	`low` … `max`. Inherits from the session by default
`isolation`	`worktree` runs the agent in its own git worktree
`skills`	Skills preloaded into the agent's context at startup
`permissionMode`	`default`, `acceptEdits`, `auto`, `plan`, … (ignored for plugin agents)

devtronic's own agents use disallowedTools on every read-only analyst, maxTurns as a cost bound, and memory: project on the reviewers so they accumulate your project's conventions across sessions.

Model Selection

Model	Use For	Cost
haiku	Fast, simple tasks	Low
sonnet	Complex reasoning	Medium
opus	Deep analysis	High

Choose the cheapest model that can do the job.

Example: Custom Lint Agent

---
name: lint-runner
description: Run linting and report issues concisely
tools: Bash, Read
model: haiku
---

You are a code quality specialist.

## When to Invoke

Claude should invoke you after code modifications to catch style issues early.

## Process

1. Run the lint command
2. If no errors: Report success briefly
3. If errors: List issues with file:line and suggested fixes

## Commands

```bash
npm run lint
npm run lint:fix  # Auto-fix

Output Format

Success:

Lint passed - no issues

Issues:

LINT ISSUES:

1. [file:line]
   Rule: [rule name]
   Issue: [description]
   Fix: [suggestion or "auto-fixable"]

Focus on actionable information. Group by file when multiple issues.


---

## Directory Structure Customization

### thoughts/ Directory

Default structure:

thoughts/ ├── specs/ # PRDs from /spec ├── research/ # Research from /research ├── plans/ # Plans from /create-plan ├── checkpoints/ # Session checkpoints ├── notes/ # Project notes ├── debug/ # Debug analysis ├── audit/ # Audit reports from /audit └── archive/ # Archived items


**Customize by:**
- Adding subdirectories for your workflow
- Modifying skill templates to use different paths
- Creating project-specific note categories

### .claude/ Directory

.claude/ ├── skills/ # Workflow skills ├── agents/ # Specialized agents ├── rules/ # Auto-applied rules └── settings.local.json # Local settings (gitignored)


---

## IDE-Specific Customization

### GitHub Copilot

Single file: `.github/copilot-instructions.md`

```markdown
# Copilot Instructions

## Project Context
[Brief project description]

## Coding Standards
[Key conventions]

## Architecture
[Important patterns]

Zed

Zed uses AGENTS.md directly - no additional configuration needed.

Configuration Patterns

Environment-Specific Rules

---
paths:
  - ".env*"
  - "config/**"
---

# Environment Configuration

- Never commit secrets
- Use environment variables for all sensitive data
- Document all required env vars in .env.example

Component-Specific Rules

---
paths:
  - "src/components/**/*.tsx"
---

# Component Rules

- Use function components with hooks
- Props interface named `[ComponentName]Props`
- Export both named and default
- Co-locate styles and tests

Test-Specific Rules

---
paths:
  - "**/*.test.ts"
  - "**/*.spec.ts"
---

# Test Rules

- Use describe/it blocks
- One assertion concept per test
- Use factories for test data
- Mock external dependencies

Customizing Addons

devtronic ships three optional addon packs. You can select them during init or manage them at any time with the addon command.

Available Addons

Addon	Type	Skills	Description
`orchestration`	Plugin-mode	`briefing`, `handoff`	Pre-planning alignment and context rotation
`design-best-practices`	File-mode	`design-init`, `design-critique`, `design-refine`, `design-tokens`, `design-harden`	Frontend design quality: typography, color, layout, accessibility
`auto-devtronic`	File-mode	`auto-devtronic`	Autonomous engineering loop — spec → tests → plan → implement → PR

Enabling Addons

During init (Claude Code only):

The init wizard shows a multiselect after IDE selection:

◆ Enable optional addon packs? (space to toggle, enter to confirm)
  ○ Orchestration — briefing, handoff
  ○ Design Best Practices — design-init, design-critique, design-refine, design-tokens, design-harden
  ○ Auto-devtronic — auto-devtronic

After init, manage addons with:

npx devtronic addon list                          # See all addons + status
npx devtronic addon enable orchestration          # Install
npx devtronic addon enable design-best-practices
npx devtronic addon enable auto-devtronic
npx devtronic addon disable design-best-practices # Uninstall

How Addon Files Are Tracked

Plugin-mode addons (orchestration) are included in the devtronic marketplace plugin at r-bart/devtronic-plugin on GitHub. They are not stored locally — Claude Code fetches them from the remote plugin repository. Because plugin skills are remote, they are not directly editable. To customize behavior, create your own skills in .claude/skills/ instead.

File-mode addons (design-best-practices, auto-devtronic) install into your agent directories and are tracked in devtronic.json:

When you run devtronic addon add design-best-practices, the CLI:

Copies skill files to .claude/skills/design-init/, .claude/skills/design-critique/, etc.
Copies rule files to .claude/rules/design-quality.md
Copies reference docs to .claude/skills/design-harden/reference/
Records installed files and checksums in devtronic.json

Customizing Addon Skills

You can freely edit any installed addon file:

# Edit a design skill
vim .claude/skills/design-review/SKILL.md

The addon system tracks which files you've modified:

Unmodified files are updated automatically during addon sync
Modified files are preserved during sync (you'll see a warning)

Changing Agent Targets

By default, file-mode addon files are generated for Claude only. To target multiple agents:

// .claude/devtronic.json
{
  "agents": ["claude", "cursor", "gemini"],
  "installed": { ... }
}

After changing agents, run:

npx devtronic addon sync

This generates files for the new agents while keeping existing ones.

How `addon sync` Works

File State	Sync Behavior
Unmodified (matches original)	Updated to latest version
Modified by user	Preserved, conflict reported
Missing (new agent added)	Created from source

Removing Default Content

If you don't want certain default skills or agents:

# Remove specific skill
rm .claude/skills/backlog/

# Remove specific agent
rm .claude/agents/code-reviewer.md

The CLI won't re-add them on update if they don't exist (it only adds new files, doesn't restore deleted ones).

Sharing Customizations

Team Standards

Put shared customizations in the repo:

.claude/rules/ - Team coding standards
.claude/skills/ - Team workflows
AGENTS.md - Project context

Personal Preferences

Put personal customizations outside the repo:

CLAUDE.local.md - Personal overrides (gitignored)
.claude/settings.local.json - Personal settings

Navigation Menu

Customization Guide

AGENTS.md / CLAUDE.md

Recommended Structure

What to Include

Self-Improvement Pattern

Custom Rules

Claude Code Rules

Cursor Rules

Google Antigravity Rules

Custom Skills

Basic Structure

Frontmatter Options

`allowed-tools` grants, it does not restrict

Example: Custom Deploy Skill

Verification

Frontmatter Options

Model Selection

Example: Custom Lint Agent

Output Format

Zed

Configuration Patterns

Environment-Specific Rules

Component-Specific Rules

Test-Specific Rules

Customizing Addons

Available Addons

Enabling Addons

How Addon Files Are Tracked

Customizing Addon Skills

Changing Agent Targets

How `addon sync` Works

Removing Default Content

Sharing Customizations

Team Standards

Personal Preferences

Related Documentation

FilesExpand file tree

customization.md

Latest commit

History

customization.md

File metadata and controls

Customization Guide

AGENTS.md / CLAUDE.md

Recommended Structure

What to Include

Self-Improvement Pattern

Custom Rules

Claude Code Rules

Cursor Rules

Google Antigravity Rules

Custom Skills

Basic Structure

Frontmatter Options

allowed-tools grants, it does not restrict

Example: Custom Deploy Skill

Verification

Frontmatter Options

Model Selection

Example: Custom Lint Agent

Output Format

Zed

Configuration Patterns

Environment-Specific Rules

Component-Specific Rules

Test-Specific Rules

Customizing Addons

Available Addons

Enabling Addons

How Addon Files Are Tracked

Customizing Addon Skills

Changing Agent Targets

How addon sync Works

Removing Default Content

Sharing Customizations

Team Standards

Personal Preferences

Related Documentation

`allowed-tools` grants, it does not restrict

How `addon sync` Works