maestro

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Maestro

Maestro is the orchestration skill. Use it first when the task needs more than a single framework answer: planning, implementing, reviewing, verifying, or publishing work across an application codebase.

text

INTAKE -> PLANNING -> BUILD -> VERIFY -> PUBLISH -> DONE

If the user is still planning, stop in PLANNING. If the user asks to implement, continue through VERIFY. If the user asks for commit, push, or PR, continue through DONE.

Maestro是一款编排技能。当任务需要跨应用代码库完成规划、实现、评审、验证或发布工作，而非单一框架的解决方案时，请首先使用它。

text

INTAKE -> PLANNING -> BUILD -> VERIFY -> PUBLISH -> DONE

如果用户仍处于规划阶段，则停留在PLANNING环节。如果用户要求实现，则推进至VERIFY环节。如果用户要求提交、推送或创建PR，则推进至DONE环节。

Role

角色

Maestro is not a replacement for framework/domain skills. It decides which skills are needed, when to load them, and which phase gate applies.

Use specialized skills for their owned areas:

Skill	Responsibility
`adonisjs`	AdonisJS backend: migrations, models, transformers, controllers, routes, redirects, auth, policies
`lucid`	Lucid ORM/database layer: migrations, schema generation, models, relationships, query builders, transactions, factories, seeders
`inertia-react`	React frontend layer in AdonisJS + Inertia projects
`inertia-vue`	Vue frontend layer in AdonisJS + Inertia projects
`japa`	Japa tests: API, browser, console, fakes, database setup
Project/domain skills	Business rules, repo-specific workflows, local conventions

When a repo provides project guides such as

CLAUDE.md

AGENTS.md

README.md

, or domain skills, read the relevant guide before editing code.

Maestro并非框架/领域技能的替代者。它负责决定需要哪些技能、何时加载这些技能，以及适用哪个阶段的管控规则。

请在对应领域使用专业技能：

Skill	职责
`adonisjs`	AdonisJS后端：迁移、模型、转换器、控制器、路由、重定向、认证、策略
`lucid`	Lucid ORM/数据库层：迁移、schema生成、模型、关联关系、查询构建器、事务、工厂、种子数据
`inertia-react`	AdonisJS + Inertia项目中的React前端层
`inertia-vue`	AdonisJS + Inertia项目中的Vue前端层
`japa`	Japa测试：API、浏览器、控制台、模拟、数据库设置
项目/领域技能	业务规则、仓库专属工作流、本地约定

当仓库提供

CLAUDE.md

、

AGENTS.md

、

README.md

等项目指南或领域技能文档时，请在编辑代码前阅读相关指南。

Runbooks

运行手册

Use these runbooks for complete feature flows that cross multiple skills:

Feature	File	Typical skill sequence
Auth — signup, login, email verification, rate limiting	`runbooks/auth.md`	`maestro` -> `lucid` -> `adonisjs` -> `japa`
Full CRUD resource	`runbooks/crud.md`	`maestro` -> `lucid` -> `adonisjs` -> `inertia-*` -> `japa`
File uploads with Drive	`runbooks/file-upload.md`	`maestro` -> `adonisjs` -> `lucid` -> `inertia-*` -> `japa`
Two-Factor Authentication (TOTP + recovery codes)	`runbooks/two-factor-auth.md`	`maestro` -> `lucid` -> `adonisjs` -> `japa`
Inertia resource with typed pages/forms	`runbooks/inertia-resource.md`	`maestro` -> `lucid` -> `adonisjs` -> `inertia-*` -> `japa`
JSON API endpoint	`runbooks/api-endpoint.md`	`maestro` -> `lucid` as needed -> `adonisjs` -> `japa`
Background job, event, or queued side effect	`runbooks/background-job.md`	`maestro` -> `adonisjs` -> `lucid` as needed -> `japa`
Transactional email flow	`runbooks/email-flow.md`	`maestro` -> `lucid` as needed -> `adonisjs` -> `japa`
Admin permissions and policy-backed UI	`runbooks/admin-permissions.md`	`maestro` -> `lucid` -> `adonisjs` -> `inertia-*` -> `japa`
Reporting dashboard or aggregate view	`runbooks/reporting-dashboard.md`	`maestro` -> `lucid` -> `adonisjs` -> `inertia-*` or API -> `japa`

Do not treat runbooks as a replacement for specialized skills. A runbook defines the orchestration path; each skill owns its technical details.

对于跨多个技能的完整功能流程，请使用以下运行手册：

功能	文件	典型技能执行顺序
认证 — 注册、登录、邮箱验证、速率限制	`runbooks/auth.md`	`maestro` -> `lucid` -> `adonisjs` -> `japa`
完整CRUD资源	`runbooks/crud.md`	`maestro` -> `lucid` -> `adonisjs` -> `inertia-*` -> `japa`
基于Drive的文件上传	`runbooks/file-upload.md`	`maestro` -> `adonisjs` -> `lucid` -> `inertia-*` -> `japa`
双因素认证（TOTP + 恢复码）	`runbooks/two-factor-auth.md`	`maestro` -> `lucid` -> `adonisjs` -> `japa`
带类型页面/表单的Inertia资源	`runbooks/inertia-resource.md`	`maestro` -> `lucid` -> `adonisjs` -> `inertia-*` -> `japa`
JSON API端点	`runbooks/api-endpoint.md`	`maestro` -> 按需使用 `lucid` -> `adonisjs` -> `japa`
后台任务、事件或排队副作用	`runbooks/background-job.md`	`maestro` -> `adonisjs` -> 按需使用 `lucid` -> `japa`
事务性邮件流	`runbooks/email-flow.md`	`maestro` -> 按需使用 `lucid` -> `adonisjs` -> `japa`
管理员权限与基于策略的UI	`runbooks/admin-permissions.md`	`maestro` -> `lucid` -> `adonisjs` -> `inertia-*` -> `japa`
报表仪表盘或聚合视图	`runbooks/reporting-dashboard.md`	`maestro` -> `lucid` -> `adonisjs` -> `inertia-*` 或API -> `japa`

请勿将运行手册视为专业技能的替代。运行手册定义编排路径，而每个技能负责其技术细节。

Phase 1: Intake

阶段1：任务接收

Classify the request:

Type	Meaning	Stop point
Planning only	Brainstorm, spec, issue text, task breakdown, plan review	PLANNING
Build	Implement feature or bugfix	VERIFY
Review	Inspect code, PR, or changes against a plan	DONE after findings
Publish	Commit, push, PR, release note	DONE

Start by understanding the worktree and project boundaries:

bash

git status --short --branch
rg --files -g 'CLAUDE.md' -g 'AGENTS.md' -g 'README.md' -g 'package.json'

Identify:

Which app/package is touched
Whether the user is asking for planning, implementation, review, or publish
Which framework/domain skills apply
Whether there are unrelated local changes to preserve

对请求进行分类：

类型	含义	终止节点
仅规划	头脑风暴、规格说明、问题文本、任务分解、规划评审	PLANNING
构建	实现功能或修复bug	VERIFY
评审	根据规划检查代码、PR或变更	发现问题后至DONE
发布	提交、推送、PR、发布说明	DONE

首先了解工作树和项目边界：

bash

git status --short --branch
rg --files -g 'CLAUDE.md' -g 'AGENTS.md' -g 'README.md' -g 'package.json'

确定：

涉及哪个应用/包
用户是否要求规划、实现、评审或发布
适用哪些框架/领域技能
是否存在需要保留的无关本地变更

Phase 2: Planning

阶段2：规划

Gate: a clear plan or task boundary must exist before BUILD.

text

IF a plan was provided:
  read it and execute against it

ELSE IF the task is ambiguous, recurring, risky, or broad:
  brainstorm first
  write a plan
  wait for approval if the user is still shaping the work

ELSE:
  state a short plan before editing

For recurring bugs, do not patch immediately. Re-open hypotheses, inspect prior attempts if available, and write the plan first.

Use durable plan files when the repo already has a planning convention, for example:

text

docs/superpowers/plans/YYYY-MM-DD-<feature>.md

管控要求：进入BUILD环节前，必须有清晰的规划或任务边界。

text

IF 已提供规划:
  阅读规划并按其执行

ELSE IF 任务模糊、重复、存在风险或范围宽泛:
  先进行头脑风暴
  编写规划
  如果用户仍在梳理工作，等待审批

ELSE:
  在编辑前说明简短规划

对于重复出现的bug，请勿立即打补丁。重新梳理假设，若有之前的尝试则进行检查，先编写规划。

当仓库已有规划约定时，使用持久化的规划文件，例如：

text

docs/superpowers/plans/YYYY-MM-DD-<feature>.md

Phase 3: Build

阶段3：构建

Load the specialized skills before editing the area they own. Keep changes inside the owning app/package unless the plan explicitly crosses boundaries.

For AdonisJS + Inertia work, respect the backend-to-frontend typing dependency:

text

lucid: migration -> schema generation -> model relationships
  -> adonisjs: transformer.toObject() -> controller: inertia.render('page', { data })
  -> generated Data.* types
    -> inertia-react/inertia-vue: typed props
      -> UI components and forms

Default build order:

Data contract: migration -> schema generation -> model -> relationships
Backend contract: transformer -> controller -> routes
Frontend contract: page props -> forms -> navigation -> UI components
Tests: focused unit/functional tests first, browser tests when UI behavior matters

Parallelize only when the user explicitly asks for subagents or parallel work, and only after dependencies are clear.

Do not:

Edit generated files unless the repo explicitly requires it
Use
```
git add .
```
or
```
git add -A
```
Broaden the task beyond the request
Implement while the user is still asking for planning
Revert unrelated worktree changes

在编辑专业技能负责的区域前，先加载该技能。除非规划明确要求跨边界，否则请将变更限制在所属应用/包内。

对于AdonisJS + Inertia的工作，需遵循后端到前端的类型依赖顺序：

text

lucid: 迁移 -> schema生成 -> 模型关联
  -> adonisjs: transformer.toObject() -> 控制器: inertia.render('page', { data })
  -> 生成的Data.*类型
    -> inertia-react/inertia-vue: 类型化props
      -> UI组件与表单

默认构建顺序：

数据契约：迁移 -> schema生成 -> 模型 -> 关联关系
后端契约：转换器 -> 控制器 -> 路由
前端契约：页面props -> 表单 -> 导航 -> UI组件
测试：优先编写聚焦的单元/功能测试，当UI行为重要时编写浏览器测试

仅当用户明确要求子代理或并行工作，且依赖关系清晰后，才可进行并行处理。

请勿：

编辑生成文件，除非仓库明确要求
使用
```
git add .
```
或
```
git add -A
```
超出请求范围扩展任务
用户仍在要求规划时就开始实现
回滚无关的工作树变更

Phase 4: Verify

阶段4：验证

Run the narrowest meaningful checks first, then broader checks when shared behavior changed.

Common examples:

bash

pnpm --filter <app> typecheck
pnpm --filter <app> test
pnpm --filter <app> build

For Inertia navigation, verify SPA behavior when relevant: requests should use Inertia navigation rather than full page reloads.

If broad commands fail because of unrelated pre-existing issues, run focused commands that prove the touched behavior and report the unrelated debt clearly.

先运行最窄范围的有效检查，当共享行为变更时再进行更宽泛的检查。

常见示例：

bash

pnpm --filter <app> typecheck
pnpm --filter <app> test
pnpm --filter <app> build

对于Inertia导航，相关时需验证SPA行为：请求应使用Inertia导航而非整页刷新。

如果宽泛的命令因无关的预存问题失败，请运行聚焦的命令以证明受影响的行为，并清晰报告无关问题。

Phase 5: Publish

阶段5：发布

Publish only when the user asks for commit, push, PR, or the original request includes that destination.

Before committing:

bash

git status --short
git diff --check -- <explicit-paths>
git log --oneline -5

Stage explicit paths only:

bash

git add <path-1> <path-2>
git commit -m "<type>(<scope>): <summary>"

For PRs:

Confirm the target branch from the user request or live PR context
Use the repository's established branch and PR conventions
Include summary plus exact validation commands run
Do not merge or delete branches unless explicitly asked

仅当用户要求提交、推送、PR，或原始请求包含该目标时，才进行发布。

提交前：

bash

git status --short
git diff --check -- <explicit-paths>
git log --oneline -5

仅暂存明确的路径：

bash

git add <path-1> <path-2>
git commit -m "<type>(<scope>): <summary>"

对于PR：

根据用户请求或现有PR上下文确认目标分支
使用仓库已确立的分支和PR约定
包含摘要以及实际运行的验证命令
除非明确要求，否则请勿合并或删除分支

Phase 6: Done

阶段6：完成

Before declaring completion:

Re-read the user request or plan and confirm the scope was met
Confirm the verification output from commands actually run
Report skipped or blocked checks explicitly
Keep the final status concise: changed files, validation, PR/issue link if created

在宣布完成前：

重新阅读用户请求或规划，确认已满足范围要求
确认实际运行的验证命令输出
明确报告跳过或受阻的检查
最终状态保持简洁：变更的文件、验证结果、创建的PR/问题链接（如有）

When Not To Use

禁用场景

Do not use Maestro for a narrow standalone question that clearly belongs to one skill only, such as "what is the correct Japa syntax for

loginAs

?" Use the specific skill directly.

请勿在仅涉及单一技能的狭义独立问题中使用Maestro，例如“

loginAs

的正确Japa语法是什么？”请直接使用对应的专业技能。