usage-monitor-workflow
Skill19 starsChanged 50 days agoMITView on GitHub
Run the usage-monitor delivery workflow end to end — issue with a short plan, plan in docs/planos, worktree, strict TDD (red before green, recorded), local tests, PR with auto-merge, CI incident count, cleanup and a test-case comment on the issue. Implementation is delegated to subagents (backend-dev, frontend-dev, prototype-dev) that run red to green in their worktree, while the session plans, validates and commits. Use for EVERY request that changes the repository, even when the user does not mention the workflow.
- Commits and pushes
In this repository13 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- orchestrateSkill
- usage-monitor-commit-pushSkill
- usage-monitor-designSkill
- usage-monitor-nsis-installerSkill
- usage-monitor-release-betaSkill
- usage-monitor-releaseSkill
- usage-monitor-release-videoSkill
- usage-monitor-social-videoSkill
- usage-monitor-test-reportSkill
- usage-monitor-token-cleanupSkill
- usage-monitor-visual-optionsSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
18 rules. About 0 are common, 7 are distinctive, and 11 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
11
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 14
No step waits for approval: the CLAUDE.md rule is the authorization for commit, push, PR and merge.
- Very specific: line 18
If the Agents: block above says PENDENTE, the project has no agents configured yet.
- Very specific: line 23
Ask which option they want, with AskUserQuestion:
- Very specific: line 29
After installing, read each generated agent and fix what the manifests could not tell: conventions, forbidden paths, the real test command …
- Very specific: line 32
If the new agents are not available to delegate to, tell the user to restart the session (or reload with /agents) and run the same request …
- Distinctive: line 98
No delivery is accepted on the agent's own report.
- Very specific: line 101
Run the emit.mjs commands from the main checkout, each with --sessao ${CLAUDE_SESSION_ID}.
- Very specific: line 111
Only delivery defects reject: a BLOQUEADA return and a usage-limit interruption do not count.
- Distinctive: line 135
Stop and ask the user to choose.
- Very specific: line 144
Before planning any visual task, delegate to explorer with the standard prompt format.
- Very specific: line 147
Write the return to a briefing file (prototipos/design-system.md): pointers plus the few values that decide the work.
- Distinctive: line 149
Every visual task points to that briefing and names the design-system files the agent must read.
- Very specific: line 153
If the explorer finds nothing usable in docs/design-system/, stop and tell the user.
- Distinctive: line 157
Use the issue the user gave.
- Very specific: line 182
Never commit on main (the ruleset rejects the push anyway).
- Distinctive: line 196
Red: Write the test for the behavior first: the contract (route, body, published state, text, decision), as the neighboring tests do.
- Distinctive: line 199
Green: Write the least production code that makes it pass.
- Very specific: line 291
If the removal still fails and git worktree list no longer shows the worktree, run git worktree prune, list what is left in the folder, and …
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Usage Monitor Workflow
Agents:
!node .claude/skills/orchestrate/setup/agentes.mjs verificar || true
The "Fluxo de trabalho" section of CLAUDE.md is the rule; this skill is how to execute it. It applies to every request
that changes a versioned file. A question that only asks for an explanation is answered in chat, outside the flow.
No step waits for approval: the CLAUDE.md rule is the authorization for commit, push, PR and merge.
0. First run: configure the agents for this project
If the Agents: block above says PENDENTE, the project has no agents configured yet. Do this before planning. If it
says CONFIGURADO, skip to section 1.
- Show the user the detected stack and commands from the block (they come from manifests only; commands marked
convençãoare the ecosystem default, not verified in this project). - Ask which option they want, with
AskUserQuestion:- Install for this project (recommended):
node .claude/skills/orchestrate/setup/agentes.mjs instalarwrites the five agents to.claude/agents/from the templates in.claude/skills/orchestrate/agents/, each with aProject contextsection (stack, commands, rule files). It never overwrites an existing agent. - Use the generic agents:
node .claude/skills/orchestrate/setup/agentes.mjs dispensarrecords the choice and stops asking.
- Install for this project (recommended):
- After installing, read each generated agent and fix what the manifests could not tell: conventions, forbidden
paths, the real test command if the detected one is a
convenção. Take the rules from the project'sCLAUDE.mdorAGENTS.mdif present; do not invent any. - If the new agents are not available to delegate to, tell the user to restart the session (or reload with
/agents) and run the same request again.
Who does what (#513)
The session is the Neferpitou orchestrator. Models, effort and tools live only in .claude/agents/; this list names the
agent, never the model. Rules against context leakage: CLAUDE.md, "Orquestração e agentes".
- Neferpitou (main session): issue, both plans, briefings, worktree, validation, commits, push, PR, merge, cleanup and the issue comment. Never writes production code or tests.
- Implementing agent (
backend-dev,frontend-dev,prototype-dev): red → green, and the fix of a red CI, in the worktree named in the prompt. test-runner: step 5 (local tests, test report, diff coverage) and step 7 (watch the CI run,--log-failed,ci-incidents.mjs).explorer: broad search in any step, read-only.
The roles are mandatory, not advice (#515): it is the user's explicit request to use these subagents. Never run the
step 5 or step 7 commands in the main session; call the test-runner agent with them.
Route: work by agent
Subagents run the model and effort set in their frontmatter in .claude/agents/: implementers and test-runner on
haiku with high effort (test-runner since #532), explorer without effort (#513). Delegate without model or
effort, except the
escalation in "Validate and send back".
| Work | Agent |
| Sweeps, locating code, gathering facts | explorer |
| Tests, typecheck, build, smoke, CI | test-runner |
| Back-end code | backend-dev |
| Front-end code | frontend-dev |
| Prototype, tooling, video, audio | prototype-dev |
| Planning, judging, integrating, shared contracts, dependencies, commits | Neferpitou (main session) |
Sonnet enters only by escalation. Never pass model in advance, nor because a task looks hard. Haiku costs 5x more above
100K prompt tokens: a large task becomes several small tasks, not one long agent.
Edit directly only a pinpoint tweak to one known file. A long command that needs no judgement (a render, for example) runs in the background in the main session: it costs no agent tokens.
Delegate without inflating context
Split only when it pays off: evaluate the demand before opening agents. A small or sequential task goes to one agent. Parallelism needs several truly independent tasks, never a target number of agents: every return costs one orchestrator turn with the whole context.
A delegation prompt has at most 12 lines, in this format:
Task <ID>. Briefing: <path>, section <n>.
Edit only: <paths>.
Acceptance: <command that exits 0, or verifiable criteria>.
Return: the agent's standard format.The directory of the prompt is the worktree path. Forbidden in the prompt: conversation summary, another agent's return, file contents the agent can read, the reason behind the request. Point to a path, do not paste text. Never the conversation, never a fork. A red verdict comes back as the failing assertion lines; Neferpitou decides the fix.
- At most 4 simultaneous agents. Agents always in the background when there is other work to do.
- Parallel code tasks go in
isolation: "worktree". Exception: artefacts in exclusive folders with no shared test suite may use the same checkout, because no agent runs or reads another's work.
Validate and send back
No delivery is accepted on the agent's own report. Check every criterion with your own evidence: diff, execution, screenshot or a frame extracted from the video.
Run the emit.mjs commands from the main checkout, each with --sessao ${CLAUDE_SESSION_ID}. The log of rejections and
limits is located from the repo root through raizRepo(), so run it from the main checkout and keep the counts in one
place. Register the task on its first call, then give the verdict:
node .claude/skills/orchestrate/portal/emit.mjs tarefa --sessao ${CLAUDE_SESSION_ID} --id <ID> --titulo "<title>" --dono <agent> --estado andamento
node .claude/skills/orchestrate/portal/emit.mjs veredito --sessao ${CLAUDE_SESSION_ID} --tarefa <ID> --resultado aprovada --texto "Criteria checked."Rejected: --resultado devolvida. The command prints the count and the action; follow the printed action, never memory.
Only delivery defects reject: a BLOQUEADA return and a usage-limit interruption do not count. Never fix it in the
agent's place. Returns (devolvida) and CI incidents are separate counts.
devolver ao mesmo agente(return to the same agent):SendMessageto the same agent, which keeps its context. The first line is<ID> devolvida: <defect>. The message carries only the failed criterion, the evidence and the expected result. Never resend the briefing. Verdict andSendMessagego out in the same turn: each orchestrator turn resends the whole session context.escalar para sonnet high(3rd rejection on haiku): runemit.mjs escaladaand open a new agent of the same type withmodel: "sonnet"andeffort: "high", becauseSendMessagecannot change the model. Noisolation: the work continues in the path where haiku stopped, which the prompt points to with the open defect. Never paste haiku's history.parar e reportar ao dono do produto(3rd rejection on sonnet): stop and report to the user what failed.
node .claude/skills/orchestrate/portal/emit.mjs escalada --sessao ${CLAUDE_SESSION_ID} --tarefa <ID>emit.mjs escalada refuses a task below the limit. Limits live in LIMITE_REPROVACOES in
.claude/skills/orchestrate/portal/emit.mjs (haiku 3, sonnet 3).
Prototype gate (visual work)
- Generate the prototypes in
prototipos/<entrega>/, one agent per prototype, with genuinely different directions. - Open each
prototipos/<entrega>/index.htmlin a real browser and validate it there. Give the user those paths. - Stop and ask the user to choose. No final version before the choice.
Visual options follow the usage-monitor-visual-options skill; the design system is the source for tokens and components.
Design system
The design system is docs/design-system/. Never read it yourself: explorer does it, to keep the whole system out of the
main context.
- Before planning any visual task, delegate to
explorerwith the standard prompt format. Task: locate, indocs/design-system/, the tokens (colors, type, spacing), the components with their props and usage rules, and any written guidelines. Returnfile:linepointers, at most 20 lines.exploreris read-only and cannot write files. - Write the return to a briefing file (
prototipos/design-system.md): pointers plus the few values that decide the work. Shared specification goes in a briefing, never in the prompt. - Every visual task points to that briefing and names the design-system files the agent must read. Prototypes use the existing tokens and components only.
- A new token, component or rule: list what is missing and ask permission first.
If the explorer finds nothing usable in docs/design-system/, stop and tell the user; do not invent a design system.
1. Issue (always)
Use the issue the user gave. Without one, create it — the first line is mandatory (CLAUDE.md, "Convenções"):
gh issue create --title "<what>" --body-file <scratchpad>/issue.mdBody: 🤖 Escrito por Claude Code, a pedido de @edilsonvilarinho, then the plan in at most 15 lines: O quê,
Atividades (A01, A02… one line each), Onde, Validação, Fora (what is deliberately left out).
In chat, the plan for the user is at most one paragraph. Every chat report stays within 15 lines.
2. Plan in docs/planos/ (activity A01)
docs/planos/<subject>-<issue>-execucao.md, modeled on fluxo-automatizado-496-execucao.md: provenance (model,
tool, date, branch, commit identity), Objetivo, Fatos confirmados (each with the command that measured it),
Decisões, Atividades, Ponto de situação (one row per activity, written in that activity's commit, with the
command and its result — never the intention), Problemas em aberto e riscos. A01 commits the plan alone.
3. Worktree and branch
git fetch origin
git worktree add .claude/worktrees/<slug> -b <type>/issue-<n>-<slug> origin/mainNever commit on main (the ruleset rejects the push anyway). Commit identity, passed per command and never written
to the config — the same thing the usage-monitor-commit-push script does since #498:
git -c user.name=claude -c user.email=claude@anthropic.com commit -F <message>Conventional Commits in English, trailers from the conversation's attribution reminder. One activity, one commit: test, code, docs and the plan row together.
4. TDD — every activity that changes behavior
The implementing agent does this and returns the literal lines; Neferpitou rejects a delivery without them.
- Red. Write the test for the behavior first: the contract (route, body, published state, text, decision), as the neighboring tests do. Run the narrowest command and confirm it fails on the assertion, for the expected reason. A compile error is not red: add the minimal stub so the test compiles and fails on what it asserts.
- Green. Write the least production code that makes it pass. Run the same command.
- Refactor with the test green; run it again.
- Record in the activity's plan row: the agent returns the red command and the failure line (
expected …, actual …), then the green command and its count. Neferpitou copies both into the row. A delivery without them is returned: a row without the red run is an activity that did not follow TDD.
A bug fix starts with a test that reproduces the bug (red), never with the fix. A test that only executes code without
asserting behavior does not count (cobertura-95-execucao.md, "Decisões").
Without a test harness (Actions YAML, docs/, design system, skill text), the row says so and names what validated
it (parse, a real run, real data). That is the only exception.
5. Local tests before the PR
test-runner runs these commands. Run the slice of what changed, mirroring the changes job of ci.yml:
| Changed | Command |
src/**, Gradle files | gradlew.bat allTests (narrow with desktopTest --tests … while iterating) |
server/** | cd server && npm test (npm run test:coverage for coverage) |
tools/ci/** | node --test "tools/ci/test/*.test.mjs" |
| any test change | report of the usage-monitor-test-report skill |
Diff coverage before opening the PR (advisory in CI, floor 90%):
gradlew.bat allTests koverXmlReport -Pcoverage
node tools/ci/diff-coverage.mjs --base origin/main --kover build/reports/kover/report.xml
node tools/ci/diff-coverage.mjs --base origin/main --lcov server/coverage/lcov.infoBelow 90%: write the missing tests (TDD) or justify each uncovered line in the plan row.
6. PR with auto-merge
git push -u origin <branch>
gh pr create --title "<conventional title> (#<n>)" --body-file <scratchpad>/pr.md
gh pr merge --auto --merge <pr>Body: Closes #<n>, what changed, platforms tested (CLAUDE.md, "CI e testes"; window host changes say the
#342 risk), test plan with the commands run, footer from the attribution reminder. The main ruleset requires
ci-ok; GitHub merges by itself when it passes and deletes the remote branch. Never --admin.
7. CI and the incident stop
Watch the CI run of the head commit, not gh pr checks --watch: right after a push the CI run sits queued behind
the concurrency cancel with no check registered yet, and gh pr checks --watch returns as soon as the checks it
sees (the skipped Dependabot auto-merge job) are done — measured on PR #497.
gh run list --branch <branch> --workflow ci.yml --limit 1 --json databaseId,headSha
gh run watch <run-id> --exit-status
gh run view <run-id> --log-failed # on red
node tools/ci/ci-incidents.mjs # count after every red run
node tools/ci/ci-incidents.mjs --local "<what failed>" # local test failure after the PR is openThe red goes back to the implementing agent: it reproduces the failure with a test, then fixes it (TDD), and Neferpitou
commits and pushes. Exit code 3 from ci-incidents.mjs is the 4th incident: run
gh pr merge --disable-auto <pr>, stop touching the branch, and hand back to the user the diagnosis of each failure,
what was tried and the branch state.
8. After the merge
First take every session's working directory out of the worktree, each in its own tool: the PowerShell tool keeps
its directory between calls, and a process whose current directory is inside the folder makes the removal exit 255 with
Permission denied, after dropping the registration and the content, leaving the empty folder (#500, measured: PR #499
cleanup, and reproduced with Start-Process pwsh -WorkingDirectory <wt>). A cd inside the same Bash command does
not release the PowerShell session.
Set-Location <repo root> # PowerShell tool, in its own callcd <repo root> # Bash tool, in its own call
gh pr view <pr> --json state,mergedAt,mergeCommit
git -c core.longpaths=true worktree remove .claude/worktrees/<slug>
git branch -D <branch>
git fetch --prune
git pull --ff-only # local main, always (#509)The local main is always brought up to the merge: without the pull it stays behind origin/main (11 commits after
PR #508, measured). --ff-only never creates a local merge; if it fails, report why instead of forcing.
core.longpaths is mandatory on Windows: server/node_modules (after npm ci) passes 260 characters, and without it
git worktree remove exits 255 with Filename too long, drops the registration and leaves the folder half deleted
(#498, measured). It goes per command, never into the user's config.
If the removal still fails and git worktree list no longer shows the worktree, run git worktree prune, list what is
left in the folder, and delete it only if it is empty or holds nothing but this branch's ignored files
(node_modules, build): Remove-Item -LiteralPath '\\?\<absolute path>' -Recurse -Force. Another process holding the
folder (editor, file explorer) gives the same Permission denied; close it first.
Then comment on the issue with the test cases created — at most 20 lines, first line
🤖 Escrito por Claude Code, a pedido de @edilsonvilarinho:
gh issue comment <n> --body-file <scratchpad>/tests.mdContent: one line per test file or group — what behavior each case asserts (not the method name alone), the red →
green evidence of the key cases, totals (tests added, suite count), diff coverage result, and what stayed without a
test and why. Close the issue if Closes #<n> did not.
Finally tell the user, within 15 lines: PR, merge commit, CI run, incidents, and the issue comment link.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

