oma-dev-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Dev Workflow - Monorepo Task Automation Specialist

开发工作流 - Monorepo任务自动化专家

When to use

适用场景

Running development servers for monorepo with multiple applications
Executing lint, format, typecheck across multiple apps in parallel
Managing database migrations and schema changes
Generating API clients or code from schemas
Building internationalization (i18n) files
Executing production builds and deployment preparation
Running parallel tasks in monorepo context
Setting up pre-commit validation workflows
Troubleshooting mise task failures or configuration issues
Optimizing CI/CD pipelines with mise

在包含多个应用的monorepo中运行开发服务器
并行执行多个应用的lint、格式化、类型检查
管理数据库迁移与架构变更
从Schema生成API客户端或代码
构建国际化（i18n）文件
执行生产构建与部署准备
在monorepo环境中运行并行任务
设置提交前验证工作流
排查mise任务失败或配置问题
使用mise优化CI/CD流水线

When NOT to use

不适用场景

Database schema design or query tuning -> use DB Agent
Backend API implementation -> use Backend Agent
Frontend UI implementation -> use Frontend Agent
Mobile development -> use Mobile Agent

数据库架构设计或查询调优 → 使用DB Agent
后端API实现 → 使用Backend Agent
前端UI实现 → 使用Frontend Agent
移动开发 → 使用Mobile Agent

Core Rules

核心规则

Always use
```
mise run
```
tasks instead of direct package manager commands
Run
```
mise install
```
after pulling changes that might update runtime versions
Use parallel tasks (
```
mise run lint
```
,
```
mise run test
```
) for independent operations
Run lint/test only on apps with changed files (
```
lint:changed
```
,
```
test:changed
```
)
Validate commit messages with commitlint before committing
Run pre-commit validation pipeline for staged files only
Configure CI to skip unchanged apps for faster builds
Check
```
mise tasks --all
```
to discover available tasks before running
Verify task output and exit codes for CI/CD integration
Document task dependencies in mise.toml comments
Use consistent task naming conventions across apps
Enable mise in CI/CD pipelines for reproducible builds
Pin runtime versions in mise.toml for consistency
Test tasks locally before committing CI/CD changes
Never use direct package manager commands when mise tasks exist
Never modify mise.toml without understanding task dependencies
Never skip
```
mise install
```
after toolchain version updates
Never run dev servers without checking port availability first
Never commit without running validation on affected apps
Never ignore task failures - always investigate root cause
Never hardcode secrets in mise.toml files
Never assume task availability - always verify with
```
mise tasks
```
Never run destructive tasks (clean, reset) without confirmation
Never skip reading task definitions before running unfamiliar tasks

始终使用
```
mise run
```
任务而非直接调用包管理器命令
在拉取可能更新运行时版本的代码后执行
```
mise install
```
对独立操作使用并行任务（
```
mise run lint
```
、
```
mise run test
```
）
仅对有文件变更的应用运行lint/test（
```
lint:changed
```
、
```
test:changed
```
）
提交前使用commitlint验证提交信息
仅对暂存文件运行提交前验证流水线
配置CI以跳过未变更的应用，提升构建速度
运行任务前先执行
```
mise tasks --all
```
查看可用任务
验证任务输出与退出码以适配CI/CD集成
在mise.toml注释中记录任务依赖
在所有应用中使用一致的任务命名规范
在CI/CD流水线中启用mise以实现可重复构建
在mise.toml中固定运行时版本以保证一致性
提交CI/CD变更前先在本地测试任务
当存在mise任务时，绝不直接使用包管理器命令
绝不修改mise.toml除非理解其任务依赖
工具链版本更新后绝不跳过
```
mise install
```
启动开发服务器前务必检查端口是否可用
绝不提交未对受影响应用进行验证的代码
绝不忽略任务失败 - 务必调查根本原因
绝不在mise.toml文件中硬编码密钥
绝不假设任务可用 - 务必通过
```
mise tasks
```
验证
绝不执行破坏性任务（clean、reset）而不确认
绝不运行不熟悉的任务而不先阅读任务定义

Technical Guidelines

技术指南

Prerequisites

前置条件

bash

undefined

bash

undefined

Install mise

curl https://mise.run | sh

Activate in shell

echo 'eval "$(~/.local/bin/mise activate)"' >> ~/.zshrc

Install all runtimes defined in mise.toml

mise install

Verify installation

mise list

undefined

mise list

undefined

Project Structure (Monorepo)

项目结构（Monorepo）

project-root/
├── mise.toml            # Root task definitions
├── apps/
│   ├── api/            # Backend application
│   │   └── mise.toml   # App-specific tasks
│   ├── web/            # Frontend application
│   │   └── mise.toml
│   └── mobile/         # Mobile application
│       └── mise.toml
├── packages/
│   ├── shared/         # Shared libraries
│   └── config/         # Shared configuration
└── scripts/            # Utility scripts

project-root/
├── mise.toml            # Root task definitions
├── apps/
│   ├── api/            # Backend application
│   │   └── mise.toml   # App-specific tasks
│   ├── web/            # Frontend application
│   │   └── mise.toml
│   └── mobile/         # Mobile application
│       └── mise.toml
├── packages/
│   ├── shared/         # Shared libraries
│   └── config/         # Shared configuration
└── scripts/            # Utility scripts

Task Syntax

任务语法

Root-level tasks:

bash

mise run lint        # Lint all apps (parallel)
mise run test        # Test all apps (parallel)
mise run dev         # Start all dev servers
mise run build       # Production builds

App-specific tasks:

bash

undefined

根级任务：

bash

mise run lint        # Lint all apps (parallel)
mise run test        # Test all apps (parallel)
mise run dev         # Start all dev servers
mise run build       # Production builds

应用专属任务：

bash

undefined

Syntax: mise run //{path}:{task}

mise run //apps/api:dev mise run //apps/api:test mise run //apps/web:build

undefined

mise run //apps/api:dev mise run //apps/api:test mise run //apps/web:build

undefined

Common Task Patterns

通用任务模式

Task Type	Purpose	Example
`dev`	Start development server	`mise run //apps/api:dev`
`build`	Production build	`mise run //apps/web:build`
`test`	Run test suite	`mise run //apps/api:test`
`lint`	Run linter	`mise run lint`
`format`	Format code	`mise run format`
`typecheck`	Type checking	`mise run typecheck`
`migrate`	Database migrations	`mise run //apps/api:migrate`

任务类型	用途	示例
`dev`	启动开发服务器	`mise run //apps/api:dev`
`build`	生产构建	`mise run //apps/web:build`
`test`	运行测试套件	`mise run //apps/api:test`
`lint`	运行代码检查	`mise run lint`
`format`	代码格式化	`mise run format`
`typecheck`	类型检查	`mise run typecheck`
`migrate`	数据库迁移	`mise run //apps/api:migrate`

Reference Guide

参考指南

Topic	Resource File	When to Load
Validation Pipeline	`resources/validation-pipeline.md`	Git hooks, CI/CD, change-based testing
Database & Infrastructure	`resources/database-patterns.md`	Migrations, local Docker infra
API Generation	`resources/api-workflows.md`	Generating API clients
i18n Patterns	`resources/i18n-patterns.md`	Internationalization
Release Coordination	`resources/release-coordination.md`	Versioning, changelog, releases
Troubleshooting	`resources/troubleshooting.md`	Debugging issues

主题	资源文件	加载时机
验证流水线	`resources/validation-pipeline.md`	Git钩子、CI/CD、基于变更的测试
数据库与基础设施	`resources/database-patterns.md`	迁移、本地Docker基础设施
API生成	`resources/api-workflows.md`	生成API客户端
国际化模式	`resources/i18n-patterns.md`	国际化处理
发布协调	`resources/release-coordination.md`	版本管理、变更日志、发布
问题排查	`resources/troubleshooting.md`	调试问题

Task Dependencies

任务依赖

Define dependencies in

mise.toml

toml

[tasks.build]
depends = ["lint", "test"]
run = "echo 'Building after lint and test pass'"

[tasks.dev]
depends = ["//apps/api:dev", "//apps/web:dev"]

在

mise.toml

中定义依赖：

toml

[tasks.build]
depends = ["lint", "test"]
run = "echo 'Building after lint and test pass'"

[tasks.dev]
depends = ["//apps/api:dev", "//apps/web:dev"]

Parallel vs Sequential Execution

并行与串行执行

Parallel (independent tasks):

bash

undefined

并行（独立任务）：

bash

undefined

Runs all lint tasks simultaneously

mise run lint


**Sequential (dependent tasks):**
```bash

mise run lint


**串行（依赖任务）：**
```bash

Runs in order: lint → test → build

mise run lint && mise run test && mise run build


**Mixed approach:**
```bash

mise run lint && mise run test && mise run build


**混合方式：**
```bash

Start dev servers in background

mise run //apps/api:dev & mise run //apps/web:dev & wait

undefined

mise run //apps/api:dev & mise run //apps/web:dev & wait

undefined

Environment Variables

环境变量

Common patterns for monorepo env vars:

bash

undefined

Monorepo环境变量通用模式：

bash

undefined

Database

DATABASE_URL=postgresql://user:pass@localhost:5432/db

Cache

REDIS_URL=redis://localhost:6379/0

API

API_URL=http://localhost:8000

Frontend

PUBLIC_API_URL=http://localhost:8000

undefined

PUBLIC_API_URL=http://localhost:8000

undefined

Output Templates

输出模板

When setting up development environment:

Runtime installation verification (
```
mise list
```
)
Dependency installation commands per app
Environment variable template (.env.example)
Development server startup commands
Common task quick reference

When running tasks:

Command executed with full path
Expected output summary
Duration and success/failure status
Next recommended actions

When troubleshooting:

Diagnostic commands (
```
mise config
```
,
```
mise doctor
```
)
Common issue solutions
Port/process conflict resolution
Cleanup commands if needed

搭建开发环境时：

运行时安装验证（
```
mise list
```
）
各应用的依赖安装命令
环境变量模板（.env.example）
开发服务器启动命令
常用任务速查

运行任务时：

包含完整路径的执行命令
预期输出摘要
执行时长与成功/失败状态
推荐后续操作

排查问题时：

诊断命令（
```
mise config
```
、
```
mise doctor
```
）
常见问题解决方案
端口/进程冲突解决
必要时的清理命令

Troubleshooting Guide

排查指南

Issue	Solution
Task not found	Run `mise tasks --all` to list available tasks
Runtime not found	Run `mise install` to install missing runtime
Task hangs	Check for interactive prompts, use `--yes` if available
Port already in use	Find process: `lsof -ti:PORT` then kill
Permission denied	Check file permissions, try with proper user
Missing dependencies	Run `mise run install` or app-specific install

问题	解决方案
任务未找到	执行 `mise tasks --all` 列出可用任务
运行时未找到	执行 `mise install` 安装缺失的运行时
任务挂起	检查是否有交互式提示，若可用则使用 `--yes` 参数
端口已被占用	查找进程： `lsof -ti:PORT` 然后终止进程
权限不足	检查文件权限，使用合适用户重试
依赖缺失	执行 `mise run install` 或应用专属的安装命令

How to Execute

执行步骤

Follow the core workflow step by step:

Analyze Task Requirements - Identify which apps are affected and task dependencies
Check mise Configuration - Verify mise.toml structure and available tasks
Determine Execution Strategy - Decide between parallel vs sequential task execution
Run Prerequisites - Install runtimes, dependencies if needed
Execute Tasks - Run mise tasks with proper error handling
Verify Results - Check output, logs, and generated artifacts
Report Status - Summarize success/failure with actionable next steps

按以下核心工作流逐步执行：

分析任务需求 - 确定受影响的应用及任务依赖
检查mise配置 - 验证mise.toml结构与可用任务
确定执行策略 - 选择并行或串行任务执行方式
运行前置操作 - 若需要则安装运行时、依赖
执行任务 - 运行mise任务并进行适当的错误处理
验证结果 - 检查输出、日志及生成的产物
报告状态 - 总结成功/失败情况并给出可执行的后续步骤

Execution Protocol (CLI Mode)

执行协议（CLI模式）

Vendor-specific execution protocols are injected automatically by

oh-my-ag agent:spawn

. Source files live under

../_shared/runtime/execution-protocols/{vendor}.md

供应商专属执行协议由

oh-my-ag agent:spawn

自动注入。源文件位于

../_shared/runtime/execution-protocols/{vendor}.md

。

References

参考资料

Clarification:

../_shared/core/clarification-protocol.md

Difficulty assessment:
```
../_shared/core/difficulty-guide.md
```

说明文档：

../_shared/core/clarification-protocol.md

难度评估：
```
../_shared/core/difficulty-guide.md
```

Knowledge Reference

知识参考

mise, task runner, monorepo, dev server, lint, format, test, typecheck, build, deployment, ci/cd, parallel execution, workflow, automation, tooling