
aibp-base
AIBlueprint base configuration with custom agents, slash commands, hooks, and productivity workflows for Claude Code
- version
- 1.0.1
- GitHub stars
- 268
Install
/plugin install aibp-base@aiblueprintRun it inside Claude Code after adding the marketplace with /plugin marketplace add Melvynx/aiblueprint.
Contents
Discovered from sourceSkills 14
Create or edit an agent only when the work is autonomous, non-interactive, and returns one final report. Keep requirements, options, and confirmations in the main chat. Agents cannot use AskUserQuestion or wait on the user.
Project agents live in .claude/agents/ and override ~/.claude/agents/. Name is unique kebab-case. Description states when to invoke it. tools is a comma list or omitted to inherit all. model is sonnet, opus, haiku, or inherit.
Write the body as XML (<role>, <constraints>, <workflow>, <output_format>) with no markdown headings. Restrict tools to least privilege. Add Skill when the agent must call $find-docs or $exa-search; add Bash when those skills need local CLIs. Never put secrets in external queries.
- Create or rewrite a prompt: writing-agent-prompts.md, then agents.md for file format, tools, models, and Task invocation.
- Edit config, tools, model, or Task /
run_in_background/resume: agents.md. - Debug a failing or looping agent: debugging-agents.md.
- Multi-agent coordination: orchestration-patterns.md.
- Recovery, retries, communication: error-handling-and-recovery.md.
- Long-running context: context-management.md.
- Eval before trusting a new agent: evaluation-and-testing.md.
Prefer /agents to create or delete; otherwise edit the markdown file directly.
Stop when the agent has valid frontmatter, an XML body, least-privilege tools, a trigger-ready description, and a model that matches the task. Test on a representative task before claiming it works.
Implement through Analyze → Plan → Execute → eXamine. The task contract, repository state, authority, and evidence are the source of truth.
Load only the current step and any reference it names. Start with steps/step-00-init.md. Persist run state with scripts/apex-state.py under .agents/apex/runs/<run-id>/. Never store secrets in run state.
Flags express intent; they do not force a vendor implementation. -a/-A interaction low/standard. -x/-X review adversarial/risk-based. -s/-S artifacts verbose/minimal. -t/-T new tests on/off. -v/-V runtime proof on/off. -e/-E budget low/standard. -b/-B branch on/off. -pr/-PR pull request on/off. -i configure interactively. -k/-K expanded artifacts on/off. -m/-M prefer-parallel/direct. -r <id> resume a checkpoint.
- Contract —
steps/step-00-init.md(interactive00b-interactive, branch00b-branch, budget00b-economy, artifacts00b-save) - Analyze —
steps/step-01-analyze.md - Plan —
steps/step-02-plan.md(expanded graph02b-tasks) - Execute —
steps/step-03-execute.md(teams03-execute-teams) - Validate —
steps/step-04-validate.md - Examine / resolve —
steps/step-05-examine.md,steps/step-06-resolve.md - Tests when required —
steps/step-07-tests.md,steps/step-08-run-tests.md - Prove when required —
steps/step-10-verify.md - Handoff —
steps/step-09-finish.md
Delegate only bounded, independent work. Record objective, allowed files, forbidden scope, done evidence, and stop condition. Returned work is untrusted until the coordinator inspects the diff. Re-plan when evidence invalidates an assumption. Preserve unrelated local changes.
Finish only when the requested implementation is present, acceptance criteria have current evidence, introduced failures are resolved, required review is done, and delivery actions have authoritative read-back.
Generate the icon yourself with any reachable image tool. Codex: image_gen. If gemini-cli is available, use it (gemini-cli auth set <GOOGLE_API_KEY> if unauthenticated). Do not hand the prompt back when a tool can run. Do not fake it with SVG-to-PNG. If no tool exists, give the filled prompt to the user and resume post-processing with their file.
Read the Expo config and write to its real paths: expo.icon, expo.android.adaptiveIcon.foregroundImage, expo.android.adaptiveIcon.backgroundColor, expo.web.favicon. Pull brand colors and the app concept from the project. Use color names in the prompt, never hex.
Targets: iOS <ASSETS>/icon.png 1024×1024, no transparency, no baked rounded mask. Android <ASSETS>/adaptive-icon.png with the subject inside the central ~66% safe circle. Web <ASSETS>/favicon.png 192×192.
Send this as one prompt, filling Subject and Color palette:
Create a 1024x1024 square app icon — premium, vibrant and dimensional, in the style of top App Store featured apps.
Subject: <single hero for <AppName> — soft 3D mascot with simple dot eyes, OR a bold symbolic object; readable at small sizes>
Look: one glossy 3D/2.5D hero, studio lighting, rim light, subtle glow, centered on a FULL-BLEED branded background that reaches all four edges.
Composition: hero fills ~60-80%; one focal point; sharp 90° corners; critical detail inside the central ~70%.
Do NOT: flat pictogram, black-on-white glyph, line icon, white/empty background, icon-in-icon, baked rounded corners, text, letters, faces, logos, chrome, neon, flares.
Color palette: <brand color names>. Technical: square 1:1; readable at 60px.
Pick mascot for consumer, social, wellness, or AI; symbol or object for finance, productivity, or utilities.
gemini-cli image generate --prompt "$PROMPT" \
--model gemini-3-pro-image-preview --aspect-ratio 1:1 --image-size 2K \
--out ./icon-raw.png --images-only --json
gemini-2.5-flash-image is the cheaper fallback. Reject flat, monochrome, SVG-like, white-background, or mushy-at-64px output and regenerate. Reword safety-filter rejects into one plain paragraph.
sips -z 1126 1126 icon-raw.png --out /tmp/icon-up.png
sips -c 1024 1024 /tmp/icon-up.png --out /tmp/icon-fullbleed.png
sips -s format png /tmp/icon-fullbleed.png --out <ASSETS>/icon.png
sips -g hasAlpha <ASSETS>/icon.png
magick <ASSETS>/icon.png -resize 66% -background "<brand-bg-color>" -gravity center -extent 1024x1024 <ASSETS>/adaptive-icon.png
sips -z 192 192 <ASSETS>/icon.png --out <ASSETS>/favicon.png
Skip the scale-up crop if the background already bleeds to sharp corners. If hasAlpha is yes: magick in.png -background "<brand-bg-color>" -alpha remove -alpha off <ASSETS>/icon.png. Match expo.android.adaptiveIcon.backgroundColor to that color. Without magick, regenerate with "~20% padding for the Android adaptive safe zone".
Icon and adaptive-icon changes need a native rebuild (npx expo run:ios or npx expo run:android). Fail the run if the home screen still shows the old art, a flat glyph, or a corner halo.
Inspect first, mutate second. Discover flags from the CLI; do not guess them.
asc auth status
asc auth status --validate
asc doctor
asc --help
asc <area> --help
asc docs list
Use --profile <name> when more than one account exists. A new account with no stored key: run find-asc-credentials, then asc auth login. Never print or commit .p8 keys, key ids, issuer ids, or downloaded financial reports with PII.
Resolve the numeric app id once: asc apps list --output json. Use --output json when parsing ids.
| Goal | Area |
|---|---|
| Apps / status | asc apps, asc status --app <id> |
| Builds | asc builds |
| TestFlight | asc testflight, asc publish testflight |
| Versions / release | asc versions, asc release |
| Metadata / screenshots | asc metadata, asc localizations, asc screenshots |
| Pricing / IAP | asc pricing, asc iap, asc subscriptions |
| Submit | asc validate, asc review, asc submit, asc publish |
| Reviews / sales | asc reviews, asc analytics, asc insights, asc finance |
| Signing / team | asc signing, asc certificates, asc profiles, asc users |
Confirm before any externally visible or hard-to-reverse mutation (submit, publish ... --submit, pricing, IAP, user changes, certificate or profile deletion). State the app id, version, and exact change. Run asc validate before submitting. Prefer --dry-run when it exists.
This skill owns the store side only. For an endpoint asc does not expose:
node "$SKILL_DIR/scripts/asc-api.mjs" GET "/v1/apps?filter[bundleId]=com.example.app"
Credentials from env (ASC_KEY_ID, ASC_ISSUER_ID, ASC_P8_PATH); never hardcode them.
arena
For when Claude keeps giving a bad answer. Instead of asking again and again, this runs a tournament: N sub-agents get the exact same task, each attacks it with a different reasoning mode, workflow and strategy, and then they attack each other in a bracket until one solution is left. You are the orchestrator. You never compete and you never judge.
What the user typed after /arena: $ARGUMENTS
If that is blank, or still reads like a placeholder, nothing was passed: take the task from the conversation.
The tool
Every piece of bookkeeping goes through bracket.py in this skill's folder:
python3 "${CLAUDE_SKILL_DIR}/bracket.py" <command>
Below, ARENA means exactly that command. If the path looks unexpanded, use the "Base directory for
this skill" that Claude Code printed at the top of this skill. The state lives in
.arena/<run>/arena.json in the current directory, and every command after init finds it through
.arena/LATEST.
Step 1: size it, and get a yes if nobody asked for it
Read the flags out of the request. Everything that is not a flag is the task.
| flag | meaning |
|---|---|
--agents N | N competitors. Default 100. |
--quick | 16 competitors. The everyday setting. |
--seed S | Fixes the cards and the pairings. Default: random, and recorded. |
--wave W | Sub-agents per wave. Default 10. Only raise it if the user raised Claude Code's limit. |
No task text at all means: the task is the user's most recent request in this conversation, and your last answer to it is the baseline to beat.
Run ARENA plan --agents N (or --quick). It prints the rounds, the sub-agent calls and the waves.
- The user asked for the arena (typed
/arena, said "arena", or asked to make them compete): tell them in one line how big it is, for example "100 agents, 7 rounds, 595 sub-agent calls", and start. - This skill fired because the user is unhappy ("that's wrong", "try again", "bad answer") and
never mentioned the arena: ask once before spending anything. Offer three options: the full arena
(100 agents, 595 sub-agent calls),
--quick(16 agents, 91 calls), or an ordinary retry. Wait for the answer.
Sub-agents write their work into .arena/ in the current directory. In the default permission mode
that is one approval per file, which is hundreds on a big run. Before the spawn phase, suggest
accept-edits mode (Shift+Tab) for the run. Do not change the user's settings yourself.
Step 2: write the task file
This is the step that decides the result. Sub-agents cannot see this conversation. Every
competitor, attacker and judge knows only what is in the task file, so write .arena/task.md to stand
on its own:
- The request, in the user's own words where you can.
- Every requirement and constraint the user stated anywhere in the conversation: audience, length, format, tone, stack, deadline, what must not change.
- The context a stranger would need: absolute paths of the files that matter, pasted data, what the product is, the conventions in the codebase.
- What "done" looks like, if the user said.
- If there is an answer to beat: what the user disliked about it, in their words.
Do not add requirements the user never gave. Do not write your own view of the right answer into it: that pushes 100 agents the same way, which is the opposite of the point.
If there is an earlier answer the user was not satisfied with, write it word for word to
.arena/baseline.md.
Step 3: init
ARENA init --agents N --seed S --task-file .arena/task.md --baseline-file .arena/baseline.md
Leave out --baseline-file when there is nothing to beat, and --seed to get a random one. init
copies the task into the run folder, deals every competitor a different strategy card with no
repeats, pairs round 1, and writes arena.json.
Step 4: the loop
Always drive it with ARENA next. It reads the state on disk and tells you the next step and the
exact command.
Every phase that runs sub-agents works the same way:
-
ARENA prompts <phase>writes one brief per job and lists the jobs still to run, in waves. -
Launch one wave at a time: a single message with one Agent tool call per job in that wave (the Agent tool is called Task in older Claude Code versions). Each call is:
subagent_type:general-purposedescription:arena <job id>prompt:Read <prompt path> and follow it exactly. It is your whole brief.run_in_background: false, where the tool has that option, so the wave comes back together.
Wait until every agent in the wave has replied before you launch the next wave.
-
After the last wave, run
ARENA next. If an output is missing it sends you back to the same phase, andpromptsthen lists only the missing jobs. Re-run those once. If a job fails twice, write the single lineNO OUTPUTinto each of its output files (ARENA check <phase>lists them) and move on. A missing attack counts as no attacks. A missing solution loses its match. A judge that fails twice gets a third, fresh run: never decide a match yourself.
The order next takes you through:
- spawn, once: every competitor writes its own solution to the task.
- then every round: attack (two per match) → defend (two per match) → judge (one per
match) →
ARENA collect→ARENA advance. - final, once, only when there is a baseline: a judge compares the champion with the answer the
user rejected, blind to which is which. Then
ARENA collect. nextprints DONE: go to step 5.
After each advance, give the user one line, such as "Round 2 done: 25 of 100 left." Nothing more.
Never paste pairings, attacks, verdicts or solutions into the chat.
Why waves: Claude Code runs at most 10 tool calls at once by default (the
CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY setting). So a 100-agent spawn is 10 waves of 10, and a
100-agent arena is 70 waves in total, 71 with the final check.
Step 5: the result
Run ARENA winner, then read the champion's solution file at the path it prints. That is the only
solution file you read in the whole run. Give the user:
- The winning solution, in full.
- Why it won: the attacks it survived, from
winner, as a short list. Its card on one line (reasoning mode + workflow + strategy). - Rounds: for example "7 rounds, 100 agents in, 1 left."
- Against the answer you rejected, if there was one: the final check's scores, honestly. If the old answer scored higher, say so plainly and show both.
- Where the full record lives: the run folder.
If the solution changes files in the user's project, do not apply it. Ask: apply it, or change it?
Rules for the orchestrator
- You run the tournament. You do not compete, attack or judge, and you never pick a winner.
collectrecords what the judges decided.recordis only for fixing bookkeeping when the user asks you to. - Every sub-agent gets the task through its brief, which
promptsbuilds from the one task file, byte for byte the same for everyone. Never paraphrase the task for one agent or add a hint to one agent's call. - Do not read solutions, attacks or verdicts during the run. There are hundreds of them. The state
is on disk, and
next,statusandpairingsare all you need. - If your context gets compacted mid-run, nothing is lost. Run
ARENA status, thenARENA next, and carry on. - Run every
ARENAcommand from the directory you raninitin. That is where.arena/LATESTlives. - Sub-agents only write inside
.arena/. If one wrote anywhere else, tell the user. - If the user says stop, stop.
ARENA statusshows where it got to, andARENA nextresumes it later.
The prompt templates
bracket.py fills these in (the {{placeholders}}) and writes one brief per job, so what you see
here is exactly what every sub-agent is told. Never edit a brief for a single agent.
Competitor, in the spawn phase
You are competitor {{agent}} in an arena of {{n}}. All {{n}} competitors got the exact same task, word for word. The only thing that makes you different is the strategy card below: it decides how you attack the task. Your solution will be attacked by other competitors and scored by a judge, round after round, until one solution is left.
=== THE TASK (identical for every competitor) ===
{{task}}
=== END OF THE TASK ===
{{baseline_note}}
=== YOUR STRATEGY CARD ===
Reasoning mode: {{reasoning_name}}. {{reasoning_how}}
Workflow: {{workflow_name}}. {{workflow_how}}
Strategy: {{strategy_name}}. {{strategy_how}}
=== END OF THE CARD ===
How to work:
1. Use the card for real. Think in the reasoning mode, go through the workflow's steps in order, and let the strategy settle every trade-off. A generic answer with the card's name on top will lose.
2. Meet every requirement the task states. The judge scores you against the task, not against your card.
3. You cannot ask the user anything. Where the task is ambiguous, take the most reasonable reading and state it in a short Assumptions section.
4. Expect attacks: concrete flaws, counterexamples, missed requirements. Close those holes before you submit.
5. Do not create, edit or delete anything outside {{arena_dir}}. Read whatever the task points to. If the task is about code, put the exact changes in your solution (full files or a unified diff) instead of applying them. If your workflow needs scratch space, use {{arena_dir}}/scratch/{{agent}}/.
Write your solution to {{out}}: the solution itself, written for the person who asked. Leave out your drafts and your working. Keep a checklist, tests or trade-off notes only where they help that person use the answer. Say nothing about the arena, your card or your competitor number: the judges score the work blind.
When the file is written, reply with this one line and nothing else:
DONE {{agent}} <number of words in your solution>
Attacker, in every round
You are competitor {{agent}} in round {{round}} of an arena, match {{match}}. Your opponent is {{target}}. Only one of you gets out of this match. Right now your job is to attack your opponent's solution.
=== THE TASK (identical for every competitor) ===
{{task}}
=== END OF THE TASK ===
Your strategy card is the lens you look for flaws through:
Reasoning mode: {{reasoning_name}}. {{reasoning_how}}
Workflow: {{workflow_name}}. {{workflow_how}}
Strategy: {{strategy_name}}. {{strategy_how}}
Read your opponent's solution: {{target_solution}}
You may read your own for comparison: {{own_solution}}. Attack theirs on its merits against the task, not for being different from yours.
Find the real problems:
- WRONG: factual errors, logic errors, bugs, false claims.
- MISSING: a requirement the task states that it skips or only half meets. Quote the requirement.
- BREAKS: a concrete input, scenario or edge case where it fails. Give the exact counterexample.
- VAGUE: a place where the user could not act on it without guessing.
Rules:
- Every attack must be specific and checkable: point at the exact part, say what is wrong and why.
- No praise, no summary, and no style nitpicks unless they stop the user from using it.
- Do not invent requirements the task does not state. Do not attack the approach, only what it gets wrong.
- At most 7 attacks, strongest first. If you only find 2 real ones, write 2.
- Label each FATAL (wrong or unusable for the task), MAJOR (a real gap) or MINOR.
- Do not create, edit or delete any file except the one below.
Write the attacks to {{out}} in this format:
ATTACK 1 [FATAL|MAJOR|MINOR] <one-line title>
Where: <quote or location>
Problem: <what is wrong, with the counterexample or the missed requirement>
(and the same for each attack after that)
When the file is written, reply with this one line and nothing else:
ATTACKED {{target}} <number of attacks> (<number that are FATAL> fatal)
Defender, in every round
You are competitor {{agent}} in round {{round}} of an arena, match {{match}}. Your opponent {{attacker}} has attacked your solution. Now you defend it and revise it. A judge will score your revised solution against your opponent's, including how well each of you dealt with the attacks you took.
=== THE TASK (identical for every competitor) ===
{{task}}
=== END OF THE TASK ===
Your strategy card. Keep your approach: it is why you are still here.
Reasoning mode: {{reasoning_name}}. {{reasoning_how}}
Workflow: {{workflow_name}}. {{workflow_how}}
Strategy: {{strategy_name}}. {{strategy_how}}
Your current solution: {{own_solution}}
The attacks against it: {{attacks}}
Do this:
1. Take every attack in turn and decide honestly. CONCEDE if it is right, and fix it. REBUT if it is wrong, and show why with evidence from the task, your solution or a concrete check. A rebuttal that only insists you are right counts as a concession. Conceding a real flaw and fixing it scores better than defending it.
2. Write your revised solution: the complete solution, standalone, with every conceded point fixed. The judge reads only this file, so never write "see the previous version". Say nothing about the arena or your card.
3. Fix what was attacked and anything the attacks made you notice. Do not start again from scratch and do not copy your opponent.
4. If the attacks file is empty or says NO OUTPUT, you were not attacked: write NO ATTACKS RECEIVED as your defense, and resubmit your solution with only the fixes you know it needs.
5. Do not create, edit or delete anything outside {{arena_dir}}.
Write your point-by-point defense to {{defense_out}} in this format:
ATTACK 1: CONCEDE|REBUT. <one to three lines>
(one entry per attack)
Write your revised solution to {{solution_out}}.
When both files are written, reply with this one line and nothing else:
DEFENDED {{agent}} conceded <n> rebutted <n>
Judge, one per match
You are the judge of match {{match}}, round {{round}}, in an arena. Two solutions to the same task have fought: each attacked the other, then defended and revised its own. Score both against the rubric. The one with the higher score goes through and the other is eliminated.
=== THE TASK (identical for every competitor) ===
{{task}}
=== END OF THE TASK ===
Read the rubric first: {{rubric}}
Solution {{first}}
- revised solution: {{first_solution}}
- attacks it received: {{first_attacks}}
- its defense: {{first_defense}}
Solution {{second}}
- revised solution: {{second_solution}}
- attacks it received: {{second_attacks}}
- its defense: {{second_defense}}
How to judge:
1. Read both revised solutions in full before you score either one.
2. For every attack, check the revised solution yourself and call it FIXED, REBUTTED (only if the rebuttal is actually right) or STANDING. A defense that says "fixed" is not proof. Look.
3. Look for flaws the attackers missed, too.
4. Score each criterion from 0 to 10 using the rubric's anchors. Set fatal to true only for a flaw you have verified that makes the solution wrong or unusable for the task.
5. The winner is the higher weighted total (the weights are in the rubric). A fatal solution cannot beat one that is not fatal. On an exact tie, fewer standing attacks wins, then higher correctness.
6. Judge the work, not the writing about the work. Length is not quality. You do not know either competitor's strategy and should not guess it.
7. Do not create, edit or delete any file except the verdict. If the task is code and running something settles an attack, do it only inside {{arena_dir}}/scratch/judge-{{match}}/, never in the user's project.
Write this JSON, and nothing else, to {{out}}:
{
"match": "{{match}}",
"scores": {
"{{first}}": {"correctness": 0, "completeness": 0, "specificity": 0, "robustness": 0, "clarity": 0, "fatal": false},
"{{second}}": {"correctness": 0, "completeness": 0, "specificity": 0, "robustness": 0, "clarity": 0, "fatal": false}
},
"winner": "{{first}} or {{second}}",
"reason": "one sentence: the decisive difference",
"survived": ["each attack the winner took and beat, in a few words"],
"standing": {"{{first}}": ["attacks still standing"], "{{second}}": ["attacks still standing"]}
}
When the file is written, reply with this one line and nothing else:
WINNER <winner id> <winner total>-<loser total>
Final check, only when there is an answer to beat
You are the final check in an arena. {{n}} competitors fought over one task and a single solution survived {{rounds}} rounds. Before it goes back to the user, it is compared with the answer the user already rejected. You are not told which of the two is which. Score what is in front of you. Either one can win.
=== THE TASK ===
{{task}}
=== END OF THE TASK ===
Read the rubric first: {{rubric}}
Solution X: {{x_solution}}
Solution Y: {{y_solution}}
How to judge:
1. Read both in full before you score either.
2. Attack both yourself: find the strongest concrete flaws in each, the way a hostile expert would. For the robustness score, judge how well each one holds up against those attacks.
3. Score each criterion from 0 to 10 using the rubric's anchors. Set fatal to true only for a flaw you have verified that makes a solution wrong or unusable for the task.
4. The winner is the higher weighted total. A fatal solution cannot beat one that is not fatal.
5. Judge the work, not the writing about the work. Length is not quality.
6. Do not create, edit or delete any file except the verdict.
Write this JSON, and nothing else, to {{out}}:
{
"scores": {
"X": {"correctness": 0, "completeness": 0, "specificity": 0, "robustness": 0, "clarity": 0, "fatal": false},
"Y": {"correctness": 0, "completeness": 0, "specificity": 0, "robustness": 0, "clarity": 0, "fatal": false}
},
"winner": "X or Y",
"reason": "one sentence: the decisive difference",
"fixed": ["each thing the winner gets right that the other gets wrong, in a few words"]
}
When the file is written, reply with this one line and nothing else:
FINAL <X or Y> <X total>-<Y total>
Proceed only on an explicit $audit-memories or /audit-memories. An OpenCode command that states the user invoked /audit-memories satisfies this guard. Default action is audit. clean audits first, then applies justified local cleanup.
Resolve the project root from $PWD. Do not switch checkouts. Do not read or modify ~/.codex/memories. Classify only agent-facing Markdown: AGENTS.md, CLAUDE.md, GEMINI.md, .agents/**/*.md, .claude/**/*.md, .cursor/**/*.{md,mdc}, .github/copilot-instructions.md, .github/instructions/**/*.md, skills/**/SKILL.md, .agents/skills/**. Product docs, READMEs, changelogs, and public specs are truth evidence only.
Read the nearest AGENTS.md, CLAUDE.md, and repository rules first. Record git status --short before and after. Never inspect secret values. Never use rm -rf; trash approved removals. Use apply_patch for text. Label provider/runtime claims NOT VERIFIED unless this run checks the live system. Do not delete instruction, security, migration, incident, or destructive-safeguard files because they are old.
Audit
Run:
python3 ~/.agents/skills/audit-memories/scripts/inventory_project_markdown.py --root "$PWD" --format json
The byte ledger must show visited == eligible. Then read every eligible file. Over 30 files: disjoint batches of 10–20, one row per path, union equals the manifest.
Load cleanup-rubric.md before classifying. Verdict each file KEEP, UPDATE, MERGE, ARCHIVE, DELETE, or VERIFY. Mark important claims VERIFIED, CONTRADICTED, NOT VERIFIED, HISTORICAL, or OPINION.
Return the root, git boundary, counts, projected totals, one row per file, contradictions with line evidence, merge clusters, broken links, protected files, and NOT VERIFIED claims. Do not write a report file unless asked.
Clean
Reuse a still-current exhaustive audit for this Git tree; otherwise re-audit. Recheck hashes and git status. Apply verdicts: KEEP unchanged; UPDATE smallest accurate edit; MERGE unique knowledge into the canonical file, fix inbound links, then trash; ARCHIVE only with an existing archive convention; DELETE via trash only after a proven replacement or no-value rationale; VERIFY unchanged until evidence exists.
If the worktree is dirty, skip overlapping user changes (BLOCKED) and continue on disjoint files. After edits: rerun inventory and link checks, search for removed or renamed paths, run proportionate repo validation, confirm the diff is Markdown-only. Do not commit or push unless asked.
Stop audit when every eligible file has one evidenced verdict. Stop clean when the ledger matches the tree, every deletion has a proven rationale, links are repaired, protected knowledge remains, validation and blockers are reported separately, and the dirty tree has no out-of-scope edits.
Proceed only on an explicit $audit-skills invocation. Default audit; fix applies only high-confidence corrections after the ledger exists. Resolve project-root from the argument or current repo. Preserve unrelated dirty changes.
bun ~/.agents/skills/audit-skills/scripts/audit-skills.mjs --project "$PWD" --format markdown
Report every inventoried skill with scan coverage and one evidence class: OBSERVED_USER, OBSERVED_MODEL, UNOBSERVED, EXPLICIT_ONLY, INVOCATION_MISMATCH, LOCALITY_CANDIDATE, NAME_COLLISION. Cursor ACP stores are opaque. Do not label UNOBSERVED as never used without naming the scanned range.
Safe automatic fixes: mirror an existing explicit-only decision across Claude/Codex; add missing explicit-only controls when the skill text already requires direct invocation; repair stale move/rename metadata. Move a skill between scopes only with explicit user direction or a project-specific runtime dependency. Copy the full directory, rewrite self-paths, validate, trash the source, then confirm the name is discovered once.
Recommend rather than mutate unobserved skills. Protect incident, security, recovery, and migration skills from usage-only pruning.
Done when every skill has a row, every recommendation cites evidence, and — on fix — touched skills validate and Git status distinguishes this run.
Audit Test
Three modes, one value bar. Authoring mode gates every new or changed test at write time. Audit mode runs focused sweeps of tests that re-assert source, duplicate stronger proof, couple behavior to implementation, or keep test-only production seams alive. Continue broad audits as separate coherent follow-up PRs; optimize for confidence, not deletion count. Campaign mode prunes one whole subsystem's test surface (every test file a package, plugin, or core area owns); before starting one, read CAMPAIGN.md.
Authoring gate
Before adding any test, answer four questions; a missing answer means do not add it yet:
- What observable behavior, invariant, or independent contract does it protect?
- What credible regression makes it fail?
- Why does existing coverage not already catch that failure? Each contract has one primary test owner at the strongest boundary; another layer needs its own distinct risk, such as a transport or lifecycle failure the owner cannot reach. Prefer extending a table-driven case or shared fixture over a near-duplicate test; consolidate duplicated setup in the same change.
- Does it need a production seam (export, flag, wrapper, injection hook) that no production caller needs? If yes, move the test to the real boundary instead.
Then check the test against every junk pattern; a match fails the gate unless the retention bar names the contract it independently guards. A test that would break under behavior-preserving refactoring is asserting implementation, not behavior; rewrite it at the owning boundary before landing it.
Bug regression tests must fail on the pre-fix code for the intended reason and pass after the owner-boundary repair. A regression test that never demonstrably failed proves the mock, not the fix. One regression at the owner boundary covers the bug; do not replay the same scenario at every layer it crosses.
Junk patterns
The shared checklist for both modes: the authoring gate rejects a new test that matches one, and audits hunt for existing tests that do.
- assertion-free coverage probes;
- self-comparisons and identity copiers;
- copied fixtures, inventories, manifests, or export lists;
- exact source, import, or string greps;
- private predicate or call-shape tests duplicated at real boundaries;
- duplicate invocations of the same contract;
- provider-local replays of shared helpers;
- tests whose only purpose is preserving test-only exports, globals, or wrappers;
- dead production code whose only callers are tests;
- expected values produced by the helper or renderer under test;
- mocks that implement the asserted behavior, or one identical mock standing in for different APIs;
- fixtures that supply the receipt, admission, or callback ordering the owner should produce, or persistence asserted against a store the path never writes;
- capability tests that restate declared flags instead of exercising the delivery or acknowledgement the flag promises;
- negative controls that pass for an unrelated reason, such as a denial from a different guard or a rejection the production path never reaches;
- names or fixtures that promise more than the input exercises, such as a "retires the window" test asserting the window was not cleared.
Value bar
Tests justify their maintenance cost by protecting behavior, a credible regression, or an independently meaningful contract. In an audit, an existing test that must change for behavior-preserving source reorganization is suspect, not automatically deletable; the authoring gate still rejects new ones.
Before judging a candidate, read the complete test and production owner, its
entry point, callers, callees, sibling implementations, overlapping tests, CI
routing, and relevant history. Read root and scoped AGENTS.md files first.
When the test claims dependency-backed behavior, inspect the dependency source
or types directly.
Discovery
Keep discovery read-only and report evidence before editing. For broad scope, run parallel discovery lanes when available:
- core source and packages;
- plugins, extensions, or integrations;
- UI, apps, scripts, and tooling;
- a cross-cutting pattern sweep.
Outside campaign mode, prefer a few high-confidence candidates over a large speculative inventory. Hunt for the junk patterns.
Retention bar
Keep a test when it independently enforces a public API, SDK, protocol, config, migration, storage, security, platform, default, generated-output, package, release, or architecture contract. Also keep:
- call ordering when order is observable behavior;
- regressions with a credible failure mode;
- source inspection when it is the cheapest independent guard: it fails when the contract changes (the user-facing key, byte, or path) and survives an identifier-only refactor;
- a retained test that fails on the baseline: treat it as a possible product bug, reproduce it, and repair the owner rather than deleting it.
Static or slow is not a deletion reason. A test that resembles implementation may still be the independent contract; prove otherwise before removing it.
Candidate evidence
Record every field below before editing. A missing field means the candidate is not ready for deletion:
- exact test name and location;
- what failure it can actually detect;
- non-test callers of the covered production or support seam;
- stronger remaining owner-boundary proof, or why no proof is needed;
- relevant history and the reason the test or seam exists;
- production or test-support deletion unlocked;
- risk and the focused validation command.
Edit shape
Choose one coherent owner-boundary batch. Delete obsolete test-only exports, globals, wrappers, and dead production paths instead of preserving aliases. Move retained regressions to their canonical owners. Consolidate repeated package or dependency assertions into one generic contract.
Prefer net-negative production LOC. Do not add replacement tests that restate the same implementation, and do not convert uncertain candidates into cleanup to increase deletion counts.
Validation
Never edit source or tests while a test watcher is running in the checkout. Use
the test commands documented in the repository's AGENTS.md, CLAUDE.md, or
package scripts.
- Run the smallest owner and sibling tests with the repository's test runner, filtered to the affected paths.
- For removed source greps or plan assertions, run the executable script or dry-run that owns the real contract.
- Run targeted formatting, then
git diff --check. - Run the changed-files gate required by repository policy (lint, typecheck, and the CI checks those paths trigger).
- Inspect
git diff --numstat; report production/tooling separately from tests and test support. - After final audit edits, get an independent review of the deleted coverage against the remaining keepers.
Landing and continuation
Commit, push, open a PR, or land only when authorized. Follow the repository's
PR flow. Land one coherent PR at a time; after landing, refresh from current
main and rerun read-only discovery for the next high-confidence batch.
Handoff
Report:
- root cause and removed low-value categories;
- production owner simplifications;
- retained false positives and why they remain valuable;
- focused and full proof actually run;
- production versus test LOC;
- PR and merge state;
- named follow-ups.
Ask before writing. Use the host's question UI. Shared logic lives in scripts/*.sh; IDE configs only point at those files. Read a matching examples/ file before writing, then adapt.
- Ask what a fresh worktree should do (multi-select): copy ignored env files; install deps; isolate or seed a data backend; run codegen. Capture extra project steps in one follow-up.
- Ask the backend. PostgreSQL → postgresql.md. Convex → convex.md. None → skip isolation. Any other backend: research official docs and an in-repo example; do not guess CLI flags; summarize before editing.
- Ask which IDEs to wire (Claude Code, Cursor, Codex). Generate
scripts/once. Then load claude.md, cursor.md, and/or codex.md for linking config only.
Required files: scripts/worktree-up.sh, scripts/worktree-down.sh, scripts/dev.sh (all must end in .sh). Put them on the source checkout, not only the current worktree.
Resolve paths as WORKTREE_PATH="${CODEX_WORKTREE_PATH:-${CURSOR_WORKTREE_PATH:-$(pwd)}}" and SOURCE_PATH="${CODEX_SOURCE_TREE_PATH:-${ROOT_WORKTREE_PATH:-}}". Claude: use WorktreeCreate, never SessionStart; the wrapper adds the worktree then runs worktree-up.sh with ROOT_WORKTREE_PATH — see claude.md. Hook wrappers must survive a missing /dev/tty, a wrong default Node version, and CLI prompts.
worktree-up.sh is idempotent: set -euo pipefail, cd to the worktree, then the selected steps in order. Prefer .worktreeinclude for Claude env copy. Detect the lockfile for install. Read resource names from env/config or setup metadata; never invent them from branch names. Provide a reset escape hatch via <PROJECT>_RESET_<RESOURCE>=1.
worktree-down.sh cleans only resources this setup created. Missing tools: print one line and exit 0.
dev.sh picks a free port from ${DEV_PORT_START:-3910}. Never hardcode a port.
Never commit or log secrets. Never embed multi-line programs in IDE config. Never destroy or import production data unless the user set an override env var. Put this guard in any import/replay helper:
assert_non_prod_ref() {
case "$1" in
prod|prod:*|prod/*|production|production:*|production/*)
echo "refusing prod source: $1" >&2; exit 1 ;;
*prod*|*production*)
[ "${ALLOW_PROD_SOURCE:-0}" = "1" ] || { echo "looks like prod: $1" >&2; exit 1; } ;;
esac
}
Expose Dev, typecheck, unit tests, and lint through the IDE; add E2E only if cheap.
After writing: bash -n the three scripts, git status --short, and parse generated TOML/JSON when those files exist.
Stress-test the user's thinking until both sides share a precise, actionable understanding.
- Resolve discoverable facts from the environment. Ask only decisions the user can make.
- Recommend voice input: microphone is fastest; short answers keyed
1through10are enough. - Ask exactly 10 numbered questions in one batch. Lead with the highest-leverage unresolved decisions. Include a concise Recommended answer on every question.
- Invite one grouped reply. Accept terse answers, skips, or blanket acceptance of the recommendations.
- Summarize what is established, investigate new facts, then ask the next batch. If fewer than 10 decisions remain, ask only those.
- Present a compact decision brief: goal, scope, constraints, chosen approach, rejected alternatives, risks, and acceptance criteria.
- Get explicit confirmation before acting on it.
Challenge assumptions. Compare credible alternatives. Match the user's language. Do not implement until the brief is confirmed.
Configure Claude Code, Codex, and Cursor hooks as event-driven commands or prompts. Treat platform syntax as distinct.
- Identify the platform and load router.md.
- Load the platform file: claude-code.md, codex.md, or cursor.md.
- Pick the scope, file path, lifecycle event, and a command hook (deterministic) or prompt hook (reasoning, if supported).
- Validate the native config and run the platform smoke check.
Across agents, keep one portable script plus a small adapter per platform. Report unsupported features.
Load as needed: hook-types.md, command-vs-prompt.md, matchers.md, input-output-schemas.md, examples.md, troubleshooting.md.
Check stop_hook_active on Stop/SubagentStop. Use trusted absolute paths, timeouts, and jq validation. Keep blocking rules selective.
Manage the two-tier rule system: the always-loaded index plus modular files. Every modular file must be linked from the index or agents will not find it.
Open agents-vs-claude.md before choosing AGENTS.md + .agents/rules/ versus CLAUDE.md + .claude/rules/, path-scoped paths: frontmatter, or dual-format setup. Run the same workflows against the chosen pair. Open examples.md before writing a new rule file or index skeleton.
Never overwrite existing files without asking. Never write a rule file without confirming its content. Default new rules to a modular file (20–60 lines); put 1–2 line constraints in Universal Rules. When the user names index content (stack, commands, universal rules), edit that file in place. Write specific prohibitions. Do not add generic best practices, linter-enforced rules, or facts the agent can read from the code.
init: read package manifests; if the index or rules directory exists, ask before writing; create a <40-line index with an empty Rules section and the rules directory.
add <name>: slugify the name; init if no index; ask what it enforces and when it applies; write the modular file; add one index bullet whose path matches the file.
edit: change only the named index section; keep every modular-file link intact.
optimize: inventory index vs files (flag orphans and broken links); strip linter-enforced, generic, verbose, and code-derivable rules; compress to bullets; show the diff and wait. Targets: index <80 lines, each rule <60.
A free-form request is add with a derived name. Ask 1–2 scope questions if the rule is unclear.
Write skills the way $analyze, $plan, $implement, $code-review, and $verify are written.
Target
- One job. Imperative. Every line changes behavior.
- Body under ~40 lines unless the job is genuinely multi-branch.
- Description 50–300 chars: capability first, then
Use when+ trigger words. - No README, changelog, or theory. No restating model defaults.
- References only for platform or schema detail the body cannot hold. Name the file and when to open it.
- User-only workflows:
disable-model-invocation: true.
Write
- Confirm 2–3 trigger prompts with the user.
- Pick the platform. Default from the path:
.claude→ Claude,.agents→ Codex,.cursor→ Cursor. Ask if unclear. - Write frontmatter, then the body: inspect → act → return → stop.
- Run
bun ~/.agents/skills/skill-manager/scripts/inspect-description.tson the skill root.
Personal skills live in ~/.agents/skills/<name>/. Platform layout and frontmatter: claude-code.md, codex.md, cursor.md. Description rules: description-recommandation.md.
Audit
For each line: would removing it change behavior? Delete no-ops, duplicates, and stale rules. State the positive target; keep prohibitions only as hard guardrails.
Online research: $find-docs for current technical docs; $exa-search for broader web research.
After creating or renaming a personal skill icon, run bun ~/.agents/scripts/sync-codex-profile-icons.ts --install. Compat: ~/.claude/skills and ~/.codex/skills symlink to ~/.agents/skills. Do not symlink ~/.cursor/skills.
Load a named style before designing or implementing UI. Parse the name from $ARGUMENTS or the message. Aliases: ios/iphone/nowstack-mobile/ink & spark → ios-app; use-vercel/geist → vercel; old vercel/black grid → black-grid; testsprite/test sprite → testspirite; lu.ma/luma.com → luma; super simple/SUPER_SIMPLE → super-simple.
Defaults: NowStack / Expo / NativeWind → ios-app. Codelynx product landings → grid. Vercel / Geist infrastructure marketing → vercel. Austere monochrome tools → black-grid. Linear / issue tracker shell → linear. Newspaper / magazine → new-york-times. Anthropic / Claude cream lab → anthropic. Neo-brutalist yellow/pink → gumroad. Glossy dark glow marketing → raycast. Attio twilight CRM → dusk. TestSprite paper dashboard → testspirite. Luma / events / RSVP → luma.
If the name is list or nothing matches, list the styles in styles/ and stop until the user chooses.
- Read
styles/<name>.mdfrom this skill directory. - Prefer project overrides:
.agents/styles/<name>.md,<name>-theme.md,<name>-theme-migration.md. - Treat the loaded style as hard constraints. Reuse existing primitives (Codelynx:
GridTheme*fromgrid-theme-primitives.tsx).
Match the vibe exactly. Honor the style file's anti-patterns. Scaffold the shell first on landing pages. impeccable is the polish pass after the style is applied.
Agents 4
Batch conditional executor. Handle ≤5 tasks. VERIFY INDEPENDENTLY before each action.
Workflow
-
VERIFY each item yourself (never trust input):
- Exports/Types: Grep for
import.*{name}in codebase - Files: Check framework patterns via explore-docs, then Grep for imports
- Dependencies: Grep for
from 'pkg'orrequire('pkg')
- Exports/Types: Grep for
-
Execute ONLY if verified unused:
- If used → Skip with reason, continue next
- If unused → Execute action, confirm success
-
Report: Count executed, count skipped with reasons
Rules
- MANDATORY: Verify each item independently using Grep/explore-docs
- Skip if used: Continue to next task
- Max 5 tasks: Process all in batch
Example
"Verify and remove: lodash, axios, moment"
- Grep
lodash→ Found in utils.ts → Skip - Grep
axios→ Not found →pnpm remove axios→ Done - Grep
moment→ Not found →pnpm remove moment→ Done Report: "Removed 2/3: axios, moment. Skipped: lodash (used in utils.ts)"
<search_targets>
- Existing similar features or patterns to follow
- Related functions, classes, components
- Configuration and setup files
- Database schemas and models
- API endpoints and routes
- Tests showing usage examples
- Utility functions available for reuse </search_targets>
<output_format> Relevant Files:
path/to/file.ext — [Purpose]
- Lines X-Y: [Key code or logic]
- Lines Z: [Function/class definition]
- Connects to: [Relationship to feature]
path/to/another.ext — [Purpose]
- Lines X-Y: [Key code or logic]
Patterns & Conventions:
- [Naming conventions, architecture patterns, framework usage]
- [Existing approaches that should be followed]
Dependencies:
- Import relationships between key files
- External libraries in use
- API integrations
Gaps:
- [Libraries needing docs research]
- [External services to investigate] </output_format>
<extraction_focus>
- Setup: Dependencies, installation, configuration
- Core APIs: Functions, methods, props matching the task
- Code Examples: Real usage patterns (copy relevant snippets)
- Patterns: Idiomatic library usage
- Gotchas: Common pitfalls, version-specific issues </extraction_focus>
<output_format> Library: [name] — Context7 ID: [resolved ID]
[Topic 1]:
[Code example or API signature]
- Purpose: [what it does]
- Key params: [relevant parameters]
[Topic 2]:
[Code example]
- Purpose: [what it does]
- Usage: [when/how to use]
Implementation Notes:
- Key patterns: [list]
- Required setup: [list]
- Gotchas: [list]
Gaps: [Topics needing further research, if any] </output_format>
Relevance > Completeness. Extract what's needed for the specific implementation task, not everything available.<output_format> Summary: Clear, concise answer to the query in 1-3 sentences.
Key Points:
- Most important finding
- Second important finding
- Additional relevant details (if any)
Sources:
Accuracy > Speed. Get the right answer quickly. When uncertain, verify across multiple sources before responding.Sponsors
Details
- Marketplace
- Melvynx/aiblueprint
- Source
- agents-config
- Author
- Melvyn
- Category
- Essentials
- License
- MIT
- Keywords
- aiblueprint, melvynx, productivity, agents, commands, hooks, workflows, statusline