
dev-vitals
Core developer workflow skills: planning, execution, communication, and powerup discovery.
- version
- 0.6.3
- GitHub stars
- 9
Install
/plugin install dev-vitals@agent-powerupsRun it inside Claude Code after adding the marketplace with /plugin marketplace add yeaight7/agent-powerups.
Contents
Discovered from sourceSkills 16
Agent Harness Design
Use when designing or improving how an agent invokes tools, handles errors, and decides when to stop.
Tool Design Rules
- Names: explicit and stable (
read_file,run_tests); no generic names (do_action,execute) - Schemas: required fields only; enum values for modes; reject invalid input with a clear error
- Output: always include
status(success/warning/error),summary,next_actions,artifacts - Catch-all tools: avoid
run_bash/shell_execunless task is genuinely open-ended; add allowlist
Error Path Rules
| Case | Required response |
|---|---|
| Invalid input | Reject immediately with exact field name |
| Transient failure | Include retry_after hint and idempotency note |
| Non-recoverable | Set stop: true, describe manual resolution |
Retry and Stop Conditions
Define in harness, not inside tools:
- Max retries: 2
- Hard stops:
status: "error"withstop: true; same inputs called twice in a row
Granularity Guide
| Risk | Granularity |
|---|---|
| High (deploy, migrate, permissions) | Micro — one action, explicit confirmation |
| Medium (edit, read, search) | Standard composite |
| Low (format, list, report) | Macro batch acceptable |
Context Budget
- Keep system prompt fixed and minimal
- Load large guidance from skills on demand
- Compact at phase boundaries, not mid-task
Verification
- Every tool has an explicit, stable name and exactly one distinct operation
- Schemas use required fields and enums — no free-text mode strings, no behavior-changing optionals
- Every tool response carries
status,summary,next_actions, andartifacts - Every tool defines its invalid-input, transient-failure, and non-recoverable paths
- Retry ceiling and stop conditions are declared in the harness, not inside tools
- Any catch-all tool is documented with its risk and guarded by an allowlist or preflight check
Agent Runtime Patterns
When to use
- Optimizing a slow or over-spending agent loop (too many tool calls, high token use).
- Designing multi-agent orchestration topology for a new workflow.
- Managing MCP session lifecycle for experimental data-layer sessions.
- Reducing redundant search or file-read loops.
Core Patterns
| Pattern | Use when | Avoid when |
|---|---|---|
| Direct execution | Single agent, clear scope, no subagent benefits | Task genuinely requires parallel sub-agents or specialized routing |
| Routing | Input type determines which specialized agent to invoke | Agents share context and can't be isolated |
| Chaining | Output of A is strict input of B | Agents need to share partial context |
| Orchestrator-worker | Parallel independent subtasks with a coordinator | Tasks are tightly coupled or sequential |
| Agents-as-tools | Callable child agent inside a parent's tool loop | The child needs user interaction |
Knowledge Cards
A card is a compact, high-signal instruction block — typically 3–10 lines — for a specific operation. Cards are preferable to loading full documentation into context.
Good card: step sequence + key constraint + example invocation. Bad card: copied README sections, multiple unrelated topics in one block.
Pack cards for the current task only. Swap cards between phases rather than accumulating them.
Workflow
- Identify the bottleneck — measure before optimizing: count tool calls, token usage, and latency. Name the specific slow or expensive step.
- Choose the right pattern — use the table above. Default to direct execution; add orchestration only when simpler approaches are insufficient.
- Pack knowledge as cards — replace large prompt docs with targeted 5–10 line cards per operation.
- Bound search loops — cap retries (e.g., max 3 search attempts), normalize query construction, prefer a dedicated search subagent over inline ad-hoc loops.
- Model MCP sessions explicitly — for experimental sessions: track create/delete lifecycle, request
_metasession IDs, handle missing-session errors without silent retries. - Measure after — compare latency, tool-call count, token use, and task success rate before/after.
Safety Constraints
- Sandbox experimental runtime changes; do not deploy to production flows without verified before/after comparison.
- Do not add orchestration layers to compensate for unclear requirements — clarify the task first.
- Do not persist session state containing secrets without an explicit storage policy.
- Do not retry failed sessions silently; surface the error.
Validation / Done Criteria
- Measurable before/after evidence: fewer tool calls, lower latency, lower token use, or higher task success.
- Chosen orchestration pattern is named and justified.
- Session lifecycle and cleanup behavior are documented if MCP sessions were introduced.
References
references/runtime-patterns.md
Agent Session Forensics
When To Use
- Agent session ended mid-tool-call or cannot resume.
- Tool call appears in assistant turn but no corresponding result turn follows.
- Need to correlate tool calls, tool results, and timing metadata.
- Diagnosing slow LLM calls, duplicate user turns, or malformed results.
- Debugging experimental MCP data-layer sessions.
Requirements / Checks
- Locate session directory and history files before editing anything.
- Prefer read-only inspection first.
- Have
jqor equivalent JSON tooling available. - Ask before modifying, truncating, or deleting any session or history file.
Workflow
-
Inventory session files — find metadata, current history, rotated previous history, and related subagent histories.
-
Count and list last turns:
jq 'length' history.json # total messages jq '.[-10:] | .[] | {role, stop_reason}' history.json # last 10 turns jq '.[] | select(.role=="assistant") | .tool_calls[].id' history.json # tool call IDs jq '.[] | select(.role=="user") | .tool_results[]?.tool_call_id' history.json # results -
Correlate tool call IDs — every
tool_callin an assistant turn must have a matchingtool_resultin the immediately following user turn. Find the first gap. -
Check timing for slow calls:
jq '.[] | select(.timing) | {role, duration_ms: .timing.duration_ms}' history.json -
Identify failure pattern — see table below.
-
Repair (if approved) — write a backup first (
cp history.json history.json.bak), then make the smallest possible fix at the last valid correlation boundary.
Common Failure Patterns
| Symptom | Likely cause | Repair |
|---|---|---|
| Tool call with no result turn | Session interrupted mid-tool | Truncate after last matched pair |
| Two consecutive user turns | Duplicate message insertion | Remove the duplicate |
tool_result with no prior tool_call | Corrupted or manually edited history | Remove orphan result |
Empty content on assistant turn | Model returned no text + no tools | Usually safe to truncate |
| Session loops without progress | Missing result causes re-prompt | Inject minimal synthetic result |
Safety Constraints
- Do not edit session JSON without backing up the original first.
- Treat history files as sensitive: prompts, tool arguments, credentials, and file contents may appear.
- Do not infer user intent from stale history when current user instructions conflict.
- Do not repair by deleting broad ranges — find the last valid tool-call/result correlation boundary.
Validation / Done Criteria
- Report the names of every session file inspected.
- Every tool-call ID is accounted for (matched or flagged as unmatched).
- Any proposed repair names the backup path and truncation boundary.
- No session file is mutated without explicit user approval.
References
references/history-diagnostics.md
Brainstorming Ideas Into Designs
Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.
Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.Anti-Pattern: "This Is Too Simple To Need A Design"
Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.
Checklist
You MUST create a task for each of these items and complete them in order:
- Explore project context — check files, docs, recent commits
- Ask clarifying questions — one at a time, understand purpose/constraints/success criteria
- Propose 2-3 approaches — with trade-offs and your recommendation
- Present design — in sections scaled to their complexity, get user approval after each section
- Write design doc — save to
docs/specs/YYYY-MM-DD-<topic>-design.mdand commit - Spec self-review — quick inline check for placeholders, contradictions, ambiguity, scope
- User reviews written spec — ask user to review the spec file before proceeding
- Transition to implementation — invoke writing-plans skill to create implementation plan
Process Flow
graph TD
Explore["Explore project context"]
Ask["Ask clarifying questions"]
Propose["Propose 2-3 approaches"]
Present["Present design sections"]
ApproveDesign{"User approves design?"}
WriteDoc["Write design doc"]
SpecReview["Spec self-review<br/>(fix inline)"]
ReviewSpec{"User reviews spec?"}
InvokePlans((("Invoke writing-plans skill")))
Explore --> Ask
Ask --> Propose
Propose --> Present
Present --> ApproveDesign
ApproveDesign -->|"no, revise"| Present
ApproveDesign -->|"yes"| WriteDoc
WriteDoc --> SpecReview
SpecReview --> ReviewSpec
ReviewSpec -->|"changes requested"| WriteDoc
ReviewSpec -->|"approved"| InvokePlans
The terminal state is invoking writing-plans. Do NOT invoke any other implementation skill directly. The ONLY skill you invoke after brainstorming is writing-plans.
The Process
Understanding the idea:
- Check out the current project state first (files, docs, recent commits)
- Before asking detailed questions, assess scope: if the request describes multiple independent subsystems, flag this immediately
- If the project is too large for a single spec, help the user decompose into sub-projects
- For appropriately-scoped projects, ask questions one at a time to refine the idea
- Only one question per message — if a topic needs more exploration, break it into multiple questions
- Focus on understanding: purpose, constraints, success criteria
Exploring approaches:
- Propose 2-3 different approaches with trade-offs
- Lead with your recommended option and explain why
Presenting the design:
- Once you understand what you're building, present the design
- Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced
- Ask after each section whether it looks right so far
- Cover: architecture, components, data flow, error handling, testing
Design for isolation and clarity:
- Break the system into smaller units that each have one clear purpose
- For each unit: what does it do, how do you use it, what does it depend on?
- Smaller, well-bounded units are easier to test and change
After the Design
Documentation:
- Write the validated design to
docs/specs/YYYY-MM-DD-<topic>-design.md - Commit the design document to git
Spec Self-Review: After writing the spec document, look at it with fresh eyes:
- Placeholder scan: Any "TBD", "TODO", incomplete sections? Fix them.
- Internal consistency: Do any sections contradict each other?
- Scope check: Is this focused enough for a single implementation plan?
- Ambiguity check: Could any requirement be interpreted two different ways?
User Review Gate: After the spec review passes, ask the user to review the written spec before proceeding:
"Spec written and committed to
<path>. Please review it and let me know if you want to make any changes before we start writing out the implementation plan."
Wait for the user's response. Only proceed once the user approves.
Implementation:
- Invoke the writing-plans skill to create a detailed implementation plan
Key Principles
- One question at a time - Don't overwhelm with multiple questions
- Multiple choice preferred - Easier to answer than open-ended when possible
- YAGNI ruthlessly - Remove unnecessary features from all designs
- Explore alternatives - Always propose 2-3 approaches before settling
- Incremental validation - Present design, get approval before moving on
Context Compression
When to use
Use when context approaches limits or response quality degrades (repeated mistakes, forgotten constraints, lost-in-the-middle effects) — typically after many turns of debugging or complex planning.
Requirements / Checks
- Active session contains long stack traces, large file dumps, or multiple failed iterations.
Workflow
-
Diagnose bloat — identify: redundant outputs (same file read multiple times), contradictory instructions that accumulated over turns, constraint forgetting (earlier requirements no longer respected).
-
Draft summary — synthesize the current valid state of the code or plan in 3–5 sentences.
-
Extract anti-patterns — list what failed and why:
"Attempted X → failed because Y". These are critical to prevent the next session from looping on the same mistakes. -
Generate handoff artifact — write the following template to disk:
## Goal [One-sentence objective] ## Current state [What is working / what is in place right now] ## Blocker / next step [The exact next action to take] ## Anti-patterns (do not repeat) - Tried X → failed because Y - Tried A → blocked by B ## Key files - `path/to/file.ts` — [what it does / why it matters] ## Open risks - [Anything uncertain or requiring verification] ## Decisions made - [Key tradeoffs and why alternatives were rejected] -
Restart — tell the user to start a new chat session and attach the handoff file as the first message.
Quality Probes
Before finalizing, verify the handoff can answer:
- Recall: exact commands, errors, versions, decisions that still matter.
- Artifact: files created, modified, inspected, intentionally untouched.
- Continuation: next action, current blocker, validation state, open risks.
- Decision: why key tradeoffs were chosen and what alternatives were rejected.
Safety Constraints
- Do NOT silently drop critical architectural constraints or user preferences during compression.
- Write the handoff document to disk before asking the user to restart.
Validation / Done Criteria
- Handoff artifact exists on disk and is in the template format above.
- User is explicitly told to restart the session and attach the file.
- All four quality probes (recall, artifact, continuation, decision) can be answered from the artifact without re-reading the full transcript.
Anti-loss Checklist
- Goal is clearly stated.
- Current blocker / next step is identified.
- Failed approaches are documented to prevent looping.
- Relevant file paths are listed.
- Key decisions and their reasons are recorded.
References
references/compression-quality-probes.md
Purpose
Your context window is the most precious resource. Large contexts make you slow, expensive, and prone to hallucinations. Treat every token read or written as a cost, and apply a continuous discipline: read less, output less, keep the window lean.
When to Use
- Continuously during any long, multi-step task
- About to open a large file (hundreds or thousands of lines)
- A command is about to emit massive logs (installs, verbose builds)
- Responses are drifting into explanation and restatement
Inputs
- The current task and the files/commands it requires
- Awareness of which files are large enough to need targeted reads
Workflow
-
Before reading: search, do not slurp. Never read a 2,000-line file whole. Locate the relevant region first, then read only that range.
grep -n "functionName" src/module.ts # find the line numbersThen read only the surrounding window (e.g. lines 120-160), not the entire file.
-
While reading: parallelize, do not serialize. If you need to inspect 3 files, issue 3 reads/searches in a single turn rather than one per turn. Fewer turns means less context repetition.
-
When running commands: silence the noise. Suppress bulk output unless you need it to debug, and disable pagers so output is not re-printed.
npm install --silent # drop install chatter (-q on tools that use it) git --no-pager log -n 20 # no interactive pager some-build 2>/dev/null # discard stderr you do not need -
When outputting: stay terse. Do not explain what a tool does before calling it unless safety requires it. Do not repeat the user's instructions back verbatim. State the result, not the process.
-
After reading: close the file. Once you are done with a file, stop referring to it and do not re-read it. The harness already tracks what you have seen.
Output
- Targeted reads of only the needed line ranges
- Quiet, pager-free command invocations
- Concise responses with no restatement or pre-call narration
Verification
- No whole-file read of a large file without a line range
- Searched for line numbers before reading a large file
- Independent reads/searches batched into a single turn
- Noisy commands silenced and pagers disabled
- Responses contain no instruction restatement or tool pre-explanation
Failure Modes
- Slurping the whole file — reading an entire large file when a grep-located range would do; it floods context and buries the relevant lines.
- Serial reads — opening files one per turn instead of batching, multiplying context repetition across turns.
- Log flooding — running verbose installs or builds without silencing, drowning the transcript in output you never needed.
- Narrating everything — restating instructions and pre-explaining tool calls, spending output tokens on filler.
Context Retrieval Loop
Gather the right codebase context before making changes or spawning subagents.
When to Use
- Starting work in an unfamiliar area
- Spawning a subagent that needs targeted file context
- First search pass returned nothing useful
The 3-Cycle Loop
Cycle 1 — Broad Search
rg "<primary-keyword>" --type ts --type js -l
find . -name "*<keyword>*" -not -path "*/node_modules/*"
Stop here if 3+ directly relevant files found.
Cycle 2 — Exact Source and Tests
Read the most relevant files from Cycle 1. Then find:
rg "<filename-stem>" --glob "*.test.*" --glob "*.spec.*" -l
rg "import.*<module-name>" -l
Stop here if you can describe the change and its blast radius.
Cycle 3 — Docs and Setup
ls docs/ README.md AGENTS.md CLAUDE.md .claude/ 2>/dev/null
rg "<keyword>" .env.example *.config.* 2>/dev/null
Stopping Conditions
Stop when: 3+ high-relevance files understood, OR Cycle 3 complete, OR new cycles return only files already seen.
Output
Context gathered:
<file-path> — <one-line reason>
Missing context (if any):
<what is still unclear>
State gaps explicitly. Do not proceed with guesses when a known gap exists.
Integration with Subagents
Pass file paths to subagents, not file contents:
Relevant files: src/auth/tokens.ts, src/auth/session.ts, src/auth/tokens.test.ts
Verification
- The loop stopped at a stopping condition — never past 3 cycles
- Every gathered file is listed with a one-line relevance reason
- Missing context is stated explicitly — no proceeding on guesses when a gap is known
- Subagents received file paths, not inlined file contents
Dispatching Parallel Agents
Overview
You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.
When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.
Core principle: Dispatch one agent per independent problem domain. Let them work concurrently.
When to Use
graph TD
MultipleFailures{"Multiple failures?"}
AreIndependent{"Are they independent?"}
SingleAgent["Single agent investigates all"]
OneAgent["One agent per problem domain"]
CanParallel{"Can they work in parallel?"}
Sequential["Sequential agents"]
Parallel["Parallel dispatch"]
MultipleFailures -->|yes| AreIndependent
AreIndependent -->|"no - related"| SingleAgent
AreIndependent -->|yes| CanParallel
CanParallel -->|yes| Parallel
CanParallel -->|"no - shared state"| Sequential
Use when:
- 3+ test files failing with different root causes
- Multiple subsystems broken independently
- Each problem can be understood without context from others
- No shared state between investigations
Don't use when:
- Failures are related (fix one might fix others)
- Need to understand full system state
- Agents would interfere with each other
The Pattern
1. Identify Independent Domains
Group failures by what's broken:
- File A tests: Tool approval flow
- File B tests: Batch completion behavior
- File C tests: Abort functionality
Each domain is independent — fixing tool approval doesn't affect abort tests.
2. Create Focused Agent Tasks
Each agent gets:
- Specific scope: One test file or subsystem
- Clear goal: Make these tests pass
- Constraints: Don't change other code
- Expected output: Summary of what you found and fixed
3. Dispatch in Parallel
Send ALL agent calls in a single message. This is the only way they run concurrently. Making one Agent call, waiting, then another is sequential.
4. Review and Integrate
When agents return:
- Read each summary
- Verify fixes don't conflict
- Run full test suite
- Integrate all changes
Agent Prompt Structure
Good agent prompts are:
- Focused - One clear problem domain
- Self-contained - All context needed to understand the problem
- Specific about output - What should the agent return?
Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:
1. "should abort tool with partial output capture" - expects 'interrupted at' in message
2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
3. "should properly track pendingToolCount" - expects 3 results but gets 0
These are timing/race condition issues. Your task:
1. Read the test file and understand what each test verifies
2. Identify root cause - timing issues or actual bugs?
3. Fix by replacing arbitrary timeouts with event-based waiting
Do NOT just increase timeouts - find the real issue.
Return: Summary of what you found and what you fixed.
Common Mistakes
Too broad: "Fix all the tests" — agent gets lost Specific: "Fix agent-tool-abort.test.ts" — focused scope
No context: "Fix the race condition" — agent doesn't know where Context: Paste the error messages and test names
No constraints: Agent might refactor everything Constraints: "Do NOT change production code"
Vague output: "Fix it" — you don't know what changed Specific: "Return summary of root cause and changes"
When NOT to Use
- Related failures: Fixing one might fix others — investigate together first
- Need full context: Understanding requires seeing entire system
- Exploratory debugging: You don't know what's broken yet
- Shared state: Agents would interfere (editing same files, using same resources)
Verification
After agents return:
- Review each summary — Understand what changed
- Check for conflicts — Did agents edit same code?
- Run full suite — Verify all fixes work together
- Spot check — Agents can make systematic errors
Purpose
When ending a session, handing a task back to the user, or preparing to swap to a new context window, you must leave a clean paper trail — exactly what the next session or human engineer needs to resume work instantly.
When to Use
- A task ends (complete or not) and someone else picks it up next
- The context window is nearly full mid-task
- Work is blocked and must pause on an external dependency
Inputs
- The session's actual state: what ran, what passed, what is mid-flight
- The repo's working-tree status
Workflow
-
State the end condition. Explain exactly why you are stopping (e.g., "Task complete", "Blocked on PR", "Context window too large").
-
Leave a breadcrumb. If the task is incomplete, summarize the last successful step, the current failing step, and the exact next command to run. Record discovered constraints and dead ends so the next session doesn't retry them.
-
Commit or stash. Ensure the working directory is clean. Either commit the work, tell the user to commit, or stash it. Do not leave unverified messy state:
git status --short # what is uncommitted? git stash push -m "handoff: <task>" # if not committing -
Link the work. Provide file paths to the modified files or generated artifacts so the next agent/user doesn't have to search for them.
-
Write the handoff summary (a handoff markdown file, or the final message) using this exact structure:
### 1. Goal [1-2 sentences on what we were trying to do] ### 2. State - ✅ Completed: [What works] - 🚧 In Progress: [What is broken or partial] - 🛑 Blockers: [What stopped us] - ⚠️ Dead ends: [Approaches tried that failed, and why] ### 3. Next Steps 1. Run `npm test ...` 2. Fix the error in `src/foo.ts` around line X.
Output
- A handoff summary in the Goal / State / Next Steps format
- A clean, committed, or explicitly stashed working tree, with artifact paths linked
Verification
- End condition stated explicitly
- Next command is runnable verbatim by the next session — no "continue where I left off"
- Working tree clean, committed, or stashed — confirmed with git status, not assumed
- Every modified or generated file linked by path
- State section separates completed, in-progress, and blocked honestly
Failure Modes
- Vague resumption — "continue the refactor" instead of the exact failing step and next command.
- Dirty-tree handoff — uncommitted, unexplained changes the next session must reverse-engineer.
- Completed-only reporting — hiding the broken parts makes the handoff a trap.
- Unlinked artifacts — the next agent burns context searching for files you could have named.
Purpose
Reduce output tokens by ~75% by eliminating filler while preserving all technical content.
When to Use
- User requests brevity: "no fluff", "be concise", "use less tokens", "compress".
- Context budget is tight.
Stays active for all subsequent responses until explicitly turned off ("stop no fluff", "normal mode").
Inputs
Any communication task.
Workflow
Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). Abbreviate common terms (DB/auth/config/req/res/fn/impl). Strip conjunctions. Use arrows for causality (X → Y). One word when one word enough.
Technical terms stay exact. Code blocks unchanged. Errors quoted exact.
Pattern: [thing] [action] [reason]. [next step].
Not: "Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by..."
Yes: "Bug in auth middleware. Token expiry check use < not <=. Fix:"
Output
Compressed responses following the fragment pattern above.
Examples:
"Why React component re-render?" → Inline obj prop -> new ref -> re-render. useMemo.
"Explain database connection pooling." → Pool = reuse DB conn. Skip handshake -> fast under load.
Verification
- No filler words present
- No hedging language
- Technical content complete and accurate
- Mode persists across turns (no drift back to verbose)
Failure Modes
- Safety compression — Auto-clarity exception: use full sentences for security warnings, irreversible action confirmations, multi-step sequences where fragment order risks misread. Resume compression after.
- Drift — Once active, this mode persists. Do not revert after many turns or if unsure whether it is still active.
Purpose
Produce a structured overview of an unfamiliar codebase before making changes. Prevents wasted effort caused by misunderstanding project layout or entry points.
When to Use
- Starting work on an unfamiliar repository or module.
- Onboarding to a new project before the first edit.
- Locating where a feature lives before implementing or modifying it.
Do not edit code during this skill. Observation only.
Inputs
- Repository path or access to the codebase.
- Optional: specific area of interest (module, feature, data flow).
Workflow
- Identify project root, package manager, and language(s).
- Find main entry points (executables, API handlers, CLI commands).
- Read the smallest set of files needed to explain the architecture.
- Map major modules, their responsibilities, and how data flows between them.
- Flag risky or complex areas (high churn, missing tests, tangled dependencies).
Output
- Project purpose — What it does in one or two sentences.
- Entry points — Where execution starts.
- Main modules — What each major directory or package is responsible for.
- Data flow — How a typical request or operation moves through the system.
- Risky areas — Complex, undertested, or high-coupling zones to approach carefully.
Verification
- No code was edited during this skill
- All major modules identified
- Entry points documented
- Risky areas flagged
Failure Modes
- Premature editing — Do not make changes during mapping. Finish the map first.
- Monorepo confusion — Map each package or app separately if the repo contains multiple independent projects.
- Metaprogramming blind spots — Dynamic languages may have runtime-defined routes or classes. Note these as limitations in the output.
Purpose
Compact at logical boundaries to preserve high-value context while clearing noise. Arbitrary or mid-task compaction loses critical state -- file paths, variable names, partial reasoning -- that is expensive to reconstruct.
When to Use
- The context window is filling and you are at a phase boundary (research, planning, implementation, debugging)
- A failed approach left dead-end reasoning that pollutes the next attempt
- You are starting a conceptually distinct task in the same session
- A prior mid-task compaction dropped state you then had to rebuild
Inputs
- The current session state and which phase transition is approaching
- Knowledge of what is already saved durably (task list, files, git, memory) versus only in conversation
Workflow
-
Decide whether to compact by transition. Use the boundary table; default to NOT compacting mid-work.
Transition Compact? Reason Research -- Planning Yes Research context is bulky; the plan is the distilled output Planning -- Implementation Yes Plan is saved in tasks/files; context is free to reset Implementation -- Testing Maybe Keep if tests reference recent code; compact if switching focus area Debugging -- Next feature Yes Debug traces pollute unrelated work Mid-implementation No Losing file paths, variable names, partial state is costly After a failed approach Yes Clear dead-end reasoning before trying a new approach -
Save anything you cannot reconstruct cheaply before compacting.
- Write the plan to a task list or file before compacting after research
- Commit or stash work-in-progress code before compacting after debugging
- Note key file paths in the next prompt if they will be needed again
-
Know what survives versus what is lost. Anything in the Lost column must be persisted in step 2 first.
Survives Lost CLAUDE.md / AGENTS.md instructions Intermediate reasoning Task list (TodoWrite) File contents read in session Files on disk Tool call history Git state Verbally stated preferences Memory files Multi-step conversation context -
Compact with an intent-carrying summary prompt, then restore.
- Do not compact to "clean up" during active multi-file implementation
- Pass forward intent, e.g.
/compact -- now implementing auth middleware per plan - After compaction, re-read the task list or plan file to restore intent
Output
- A compaction decision (do it now / wait until the next boundary) with the reason
- A pre-compaction save of any non-reconstructible state (plan file, commit/stash, noted paths)
- A summary prompt that carries intent into the cleared context
Token Awareness
- Each loaded skill adds 1-5K tokens to context; load skills on demand, not at session start
- CLAUDE.md / AGENTS.md are always loaded -- keep them lean
- Duplicate instructions (root config plus plugin skill) are the most common waste
Verification
- The chosen action matches the transition table -- no compaction during active multi-file implementation
- Everything in the Lost column that is still needed was persisted (file, commit/stash, or next prompt) before compacting
- The compact prompt carries forward intent rather than clearing blindly
- After compaction, the task list or plan file was re-read to restore intent
Failure Modes
- Mid-task compaction — compacting during active multi-file work and losing paths, variable names, and partial state that must then be rebuilt.
- Compacting before saving — clearing context while the plan, WIP code, or key paths live only in conversation and not on disk or in tasks.
- Blind compaction — using
/compactwith no intent summary, so the cleared session has no direction and re-derives the goal. - Skipping the restore step — not re-reading the task list or plan after compaction, then drifting from the original intent.
Purpose
Never start implementing blindly. When you receive a new task, force clarification of boundaries and expected outcomes before touching files. A few minutes of intake prevents building the wrong thing.
When to Use
- At the beginning of any new task, before the first edit
- The request is ambiguous, broad, or missing files, logs, or environment details
- You cannot yet state how the result will be tested or what is out of scope
Inputs
- The user's task request
- Read access to the repo (to confirm files and the current state exist)
Workflow
-
Restate the goal. Summarize the user's request in your own words and ask them to confirm. A probing question here: "You want X to do Y instead of Z — is that right?"
-
Pin down scope. Identify explicitly what you are not going to do. If the user asked to fix a button, do not refactor the routing layer. Ask: "Should this change touch only the button handler, or is the surrounding component in scope too?"
-
Define how it will be tested. Decide the validation criteria up front — a unit test, a manual UI check, or a command. Ask: "How will we confirm this works — a passing test, or a manual check I should run?"
npm test # if the change is unit-testable curl -s localhost:3000/health # if it is an endpoint -
Surface missing context. If the request is too vague to act on, ask for the specific files, logs, or environment details you need. Confirm the targets exist before claiming you understand them.
git grep -n "handleSubmit" # confirm the symbol exists git ls-files "src/**/*.tsx" # confirm the area you'll edit -
State understanding, then pause if ambiguous. Do not say "I will now fix the bug" and immediately edit files. State your understanding of the problem first; if the instruction is ambiguous, explicitly pause and ask a clarifying question instead of guessing.
Output
- A one-paragraph restatement of the goal in your own words
- An explicit out-of-scope list
- A stated validation method (test, manual check, or command)
- Any clarifying questions, or confirmation that none remain
Verification
- The goal is restated in your own words and confirmed with the user
- What is out of scope is named explicitly
- The validation method (test, manual check, or command) is decided before editing
- Referenced files and symbols are confirmed to exist before claiming understanding
- Ambiguities are raised as clarifying questions, not resolved by guessing
Failure Modes
- The blind start — saying "I will now fix the bug" and editing files before confirming they exist or what success means.
- Silent scope creep — fixing the button but also refactoring unrelated layers because the boundary was never named.
- Untestable hand-off — finishing without ever deciding how the result would be validated.
- Guessing through ambiguity — inventing an interpretation of a vague request instead of pausing to ask.
Using Powerups
Purpose
Find and apply installed Agent Powerups before improvising. A powerup is useful only after you discover likely matches, inspect the actual asset, follow its instructions, and verify the user task with task-specific evidence.
When to Use
Use at the start of non-trivial work, and again when the task changes shape.
Use when the user asks for debugging, planning, review, setup, file intake, cleanup, PR triage, second opinions, MCP config, hooks, commands, or AGENTS.md templates.
Do not force a powerup when none fits. Say no matching powerup applies and proceed normally.
Inputs
- User task.
- Current repo or agent root.
- Installed
agent-powerupslocation, usuallyagent-powerups/under the agent root or the package repo. - Optional CLI access to
apxfor discovery and inventory. - Optional installed discovery index file; treat it as a derived snapshot, not the source of truth.
Workflow
- Discover or match available assets.
Use target-specific routing:
- Claude Code: start with native skill discovery when skills are already exposed by the host. Use
apx discoverwhen the task is uncertain, when no native skill clearly fits, or when the task may need non-skill assets. - Codex, Gemini, and generic agents: start with
apx discover. - All targets: use
apx inventoryfor MCP configs, hooks, AGENTS.md templates, plugin-contained assets, staged assets, and installed-only assets.
apx discover "<user task>" --target <codex|claude-code|gemini|generic>
apx inventory --target <codex|claude-code|gemini|generic> --json
apx list --json --verbose
apx plugins list
If apx is unavailable, inspect local folders: skills/, commands/, mcp/, agents-md/, hooks/, workflows/.
- Match the task to assets.
Prefer the narrowest high-ranked asset whose description matches the current task. Treat apx discover output as a shortlist, not as proof that a powerup has been used.
Examples:
| Task signal | Asset type to inspect |
|---|---|
| bug, failing test, regression | debugging skill |
| implementation spec | planning skill |
| file or URL intake | file-intake skill |
| pre-handoff validation | command |
| local MCP setup | MCP config |
| repo instruction baseline | AGENTS.md template |
- Read before using.
For a candidate asset:
apx info <name>
Then read the asset file. Do not rely only on the catalog summary.
Most powerups do not require step 4. Only use apx check when the asset declares external requirements or its own instructions say a dependency check is needed. Do not run apx check for every asset by default.
- Check requirements.
If apx check reports a missing command or package, stop and say exactly what is missing. Use apx check <asset> --install-missing --dry-run to preview supported installers. Ask before running --install-missing --yes. Do not pretend conversion, fetch, review, or CLI delegation happened when the tool was unavailable.
- Apply conservatively.
Follow the asset instructions. Keep scope local to the user task. For GitHub MCP, use apx mcp check github-local, apx mcp smoke github-local, then apx mcp install github-local --target <agent> --dry-run before any --yes install. For hooks, treat recipes as review-before-use; do not enable them automatically.
- Report use.
Final response should name:
- powerup used
- requirement check result, or
not needed - important fallback or skipped asset
- task-specific validation performed
Output
When a powerup applies:
Used: <asset-name>
Why: <task signal>
Requirements: <OK / missing / not needed>
Result: <how it changed the work>
Validation: <real task-specific checks, not apx check>
When none applies:
No matching Agent Powerup found. Proceeded with normal repo inspection.
Verification
Before claiming setup or use succeeded:
- Asset was read, not guessed from name.
- Requirements were checked only when the selected asset declared external dependencies.
- Missing tools were reported, not bypassed silently.
apx checkoutput was not presented as proof that the skill was used or the task succeeded.- No secrets were written.
- No global config, shell profile, hook, MCP server, or dependency install was changed without explicit user approval.
Failure Modes
- Catalog missing: inspect local asset folders directly, then report that
apxcatalog discovery failed. - Missing dependency: stop that asset path; ask before install; use a lower-capability fallback if safe.
- No matching asset: say so and continue normally.
- Unsafe asset request: print manual review steps instead of mutating config.
- Multiple possible assets: choose the narrowest one; mention skipped alternatives only when relevant.
Verification Before Completion
Overview
Claiming work is complete without verification is dishonesty, not efficiency.
Core principle: Evidence before claims, always.
Violating the letter of this rule is violating the spirit of this rule.
The Iron Law
NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
If you haven't run the verification command in this message, you cannot claim it passes.
The Gate Function
BEFORE claiming any status or expressing satisfaction:
1. IDENTIFY: What command proves this claim?
2. RUN: Execute the FULL command (fresh, complete)
3. READ: Full output, check exit code, count failures
4. VERIFY: Does output confirm the claim?
- If NO: State actual status with evidence
- If YES: State claim WITH evidence
5. ONLY THEN: Make the claim
Skip any step = lying, not verifying
Common Failures
| Claim | Requires | Not Sufficient |
|---|---|---|
| Tests pass | Test command output: 0 failures | Previous run, "should pass" |
| Linter clean | Linter output: 0 errors | Partial check, extrapolation |
| Build succeeds | Build command: exit 0 | Linter passing, logs look good |
| Bug fixed | Test original symptom: passes | Code changed, assumed fixed |
| Agent completed | VCS diff shows changes | Agent reports "success" |
| Requirements met | Line-by-line checklist | Tests passing |
Red Flags - STOP
- Using "should", "probably", "seems to"
- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!", etc.)
- About to commit/push/PR without verification
- Trusting agent success reports
- Relying on partial verification
- Thinking "just this once"
Rationalization Prevention
| Excuse | Reality |
|---|---|
| "Should work now" | RUN the verification |
| "I'm confident" | Confidence ≠ evidence |
| "Just this once" | No exceptions |
| "Linter passed" | Linter ≠ compiler |
| "Agent said success" | Verify independently |
| "Partial check is enough" | Partial proves nothing |
Key Patterns
Tests:
✅ [Run test command] [See: 34/34 pass] "All tests pass"
❌ "Should pass now" / "Looks correct"
Build:
✅ [Run build] [See: exit 0] "Build passes"
❌ "Linter passed" (linter doesn't check compilation)
Requirements:
✅ Re-read plan → Create checklist → Verify each → Report gaps or completion
❌ "Tests pass, phase complete"
Agent delegation:
✅ Agent reports success → Check VCS diff → Verify changes → Report actual state
❌ Trust agent report
When To Apply
ALWAYS before:
- ANY variation of success/completion claims
- ANY expression of satisfaction
- Committing, PR creation, task completion
- Moving to next task
- Delegating to agents
The Bottom Line
No shortcuts for verification.
Run the command. Read the output. THEN claim the result.
This is non-negotiable.
Purpose
Turn a spec into a detailed, executable multi-step implementation plan. Prevents implementation drift and gives any engineer — or agent — enough detail to build without guessing.
When to Use
- Before implementing any multi-subsystem or non-trivial feature.
- When a spec or requirements document exists and needs to become actionable tasks.
- When the implementation requires coordinating multiple files or components.
If the spec covers multiple independent subsystems, break it into separate plans — one per subsystem. Each plan should produce working, testable software on its own.
Inputs
- Spec or requirements document.
- Access to the codebase (for file paths and existing patterns).
Workflow
-
Scope check — Identify all affected subsystems. If multiple independent subsystems, suggest separate plans.
-
Design file structure — Before defining tasks, map which files will be created or modified and what each is responsible for. Units should have clear boundaries, focused responsibility, and well-defined interfaces.
-
Write the plan header:
# [Feature Name] Implementation Plan **Goal:** [One sentence describing what this builds] **Architecture:** [2-3 sentences about approach] **Tech Stack:** [Key technologies/libraries] --- -
Break work into bite-sized tasks — Each step should take 2–5 minutes:
- "Write the failing test" — step
- "Run it to verify it fails" — step
- "Implement the minimal code to pass the test" — step
- "Run tests and confirm pass" — step
- "Commit" — step
-
Write each task using this structure:
### Task N: [Component Name] **Files:** - Create: `exact/path/to/file.py` - Modify: `exact/path/to/existing.py` - Test: `tests/exact/path/to/test.py` - [ ] **Step 1:** [Action] ```code # Actual code here ``` - [ ] **Step 2:** Run: `<exact command>` Expected: `<exact output>` -
No placeholders — These are plan failures; never write them:
TBD / TODO / implement later / fill in details "Add appropriate error handling" / "handle edge cases" "Write tests for the above" (without actual test code) "Similar to Task N" (repeat the code — engineer may read tasks out of order) Steps that describe without showing how (code blocks required for code steps) -
Self-review before saving:
- Spec coverage: Can you point to a task for every requirement?
- Placeholder scan: No undefined, deferred, or vague steps?
- Type consistency: Do types and method names in later tasks match earlier definitions?
-
Save to
docs/plans/YYYY-MM-DD-<feature-name>.md.
Output
A Markdown plan file with:
- Header (goal, architecture, tech stack)
- Tasks with checkbox steps, exact file paths, actual code blocks, exact commands with expected output
- No placeholders of any kind
Verification
- All spec requirements covered (point to a task for each)
- No undefined, deferred, or vague steps present
- File paths are exact (not
path/to/file) - Tasks are 2–5 minutes each
- Code blocks contain actual code, not descriptions
- Commands include expected output
- Plan saved to
docs/plans/
Failure Modes
- Vague tasks — A reader who cannot execute a step without guessing means the task is incomplete.
- Missing spec coverage — Implementation diverges from requirements.
- Placeholder content — Implementation stalls when an engineer hits an undefined or deferred step.
- Stale type references — Function named
clearLayers()in Task 3 butclearFullLayers()in Task 7 is a bug in the plan.
Commands 4
implement
Use to turn a spec or user request into working, tested code.
Steps:
- Read the spec or request in full. If anything is ambiguous, ask before writing a single line.
- Identify the files to create or modify. Read them first.
- Write a failing test that captures the expected behavior. Confirm it fails.
- Implement the minimum code that makes the test pass. No extras.
- Run the full test suite:
npm test. All tests must pass. - If assets were added or changed, run
apx validate catalog. - Update any affected documentation or usage examples.
Do not add features beyond the spec. Do not commit unless asked.
plan
Use before starting any non-trivial task.
Steps:
- Re-read the user request in full. Identify the goal, constraints, and what "done" means.
- Map affected areas: run
git status --shortandapx listto see what exists. - List the files most likely to change. For each, read its current state with the Read tool.
- Write a numbered step list — small enough that each step is one logical change.
- Identify risks: external dependencies, breaking changes, missing context.
- Present the plan to the user and wait for approval before implementing.
Do not write code or modify files during planning.
ship-check
Use this before final handoff.
Steps:
- Read the active plan or user request.
- Inspect changes with
git status --shortandgit diff --check. - Run targeted tests for changed behavior. For this repo, CLI/catalog changes usually require
npm test. - If assets changed, run:
apx validate skillsapx validate catalog
- Final response must include changed files, commands run, validation results, and remaining risks.
Do not commit, push, install tools, or mutate global agent config unless explicitly requested.
using-powerups
Purpose: Find and apply installed Agent Powerups without guessing.
Use this prompt when starting non-trivial work in a repo where Agent Powerups may be installed.
Steps:
- Discover or match available assets:
- Claude Code: start with native skill discovery when skills are already exposed by the host.
- Codex, Gemini, and generic agents: start with
apx discover. - Use
apx discoverwhen uncertain or when the task may need non-skill assets. - Use
apx inventoryfor MCP configs, hooks, AGENTS.md templates, plugin-contained assets, staged assets, and installed-only assets. apx discover "<user task>" --target <codex|claude-code|gemini|generic>apx inventory --target <codex|claude-code|gemini|generic> --jsonapx list --json --verbose
- Pick the narrowest asset that matches the user task.
- Inspect it before using:
apx info <asset-name>- read the asset file when needed
- Run
apx check <asset-name>only when the asset declares external requirements or its instructions require a dependency check. - If a dependency is missing, stop that path and report the exact missing tool. Ask before installing anything.
- Apply the asset only within the user-requested scope.
- Report which powerup was used, whether a dependency check was needed, validation run, and any fallback.
Do not enable MCP servers, install packages, mutate shell profiles, activate hooks, or write secrets unless the user explicitly asks.
Agents 3
You are a developer workflow coach specializing in build systems, workspace architecture, and automation.
Core Directives
- Workflow Optimization: Eliminate friction in local development and continuous integration pipelines.
- Architecture Strategy: Provide guidance on workspace structuring (e.g., monorepos, multi-repo orchestration).
- Tooling Mastery: Leverage the best tools for task running, caching, and dependency management.
- Process Automation: Recommend scripts, git hooks, and CI workflows to automate repetitive tasks.
Process
- Evaluate the user's current development bottlenecks or architectural goals.
- Recommend specific tooling configurations or architectural shifts to address the pain points.
- Provide concrete implementation steps (e.g., configuration files, script updates).
- Focus on fast feedback loops and scalable development practices.
Always tailor your advice to the specific ecosystem (e.g., Node.js, Python, Rust) the user is operating in. Keep solutions pragmatic and maintainable.
Implementation Planner
You are an expert software architect. You do not write the final code; you write the plan for writing the code.
The Planning Process
- Understand Requirements: Review
$ARGUMENTScarefully. - Context Gathering: Map the files that will be affected by this change.
- Risk Analysis: Identify potential blast radius. Will this change break existing tests? Does it require database migrations?
- Step-by-Step Draft: Write a plan using actionable, sequential steps.
Plan Format
Output a PLAN.md file (or just markdown to the user) with:
- Objective: 1 sentence.
- Target Files: List of exact file paths to be modified.
- Execution Steps:
- Add test case to
test/foo.spec.ts. - Update
src/foo.tsto pass the test. - Export new type in
src/index.ts.
- Add test case to
- Validation: How to verify the whole feature works.
Stop and wait for the user to approve the plan before delegating to an implementation agent.
Repo Context Mapper
You are an expert at parachuting into unknown codebases and mapping their terrain fast. Your goal is to build an architectural understanding using minimal tokens.
Operational Rules
- Top-Down Search: Start with
list_directoryat the root. Look forpackage.json,Cargo.toml,pyproject.toml, orMakefileto understand the stack. - Entry Point Identification: Find the main entry points (
index.ts,main.py,App.tsx,cmd/main.go). - Structural Grep: Use broad
grep_searchcalls to find routes, controllers, or database models. E.g.,grep_search "class .*Controller". - Do Not Read Full Files: You are mapping, not reviewing. Use
grepand file listings to infer structure. - Output: Produce a concise Markdown tree or summary of the repository's core architecture, pointing out where business logic, state, and UI live.
If the user provided an $ARGUMENTS, focus your mapping specifically on that domain (e.g., "auth module" or "database layer").
Sponsors
Details
- Marketplace
- yeaight7/agent-powerups
- Source
- plugins/dev-vitals
- Category
- Developer Tools
- License
- Apache-2.0
- Keywords
- planning, execution, workflow, developer-tools, skills
More from yeaight7/agent-powerups
All 21- documentation-systemsv0.6.3
- github-opsv0.6.3
- machine-learning-opsv0.6.3
- mcp-developmentv0.6.3
- memory-optimizationv0.6.3
- quality-gatesv0.6.3
- security-guardrailsv0.6.3
- skill-authoringv0.6.3
- software-engineeringv0.6.3
- spec-driven-developmentv0.6.3
- spec-quality-gatesv0.6.3
- tool-integrationsv0.6.3
- agent-evaluation-labv0.6.3
- agentic-systemsv0.6.3
- codebase-intelligencev0.6.3
- codebase-maintenancev0.6.3
- connected-appsv0.6.3
- context-efficiencyv0.6.3
- data-engineeringv0.6.3
- debugging-diagnosticsv0.6.3