Core developer workflow skills: planning, execution, communication, and powerup discovery.

version
0.6.3
GitHub stars
9

Install

/plugin install dev-vitals@agent-powerups

Run it inside Claude Code after adding the marketplace with /plugin marketplace add yeaight7/agent-powerups.

Contents

Discovered from source

Skills 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_exec unless task is genuinely open-ended; add allowlist

Error Path Rules

CaseRequired response
Invalid inputReject immediately with exact field name
Transient failureInclude retry_after hint and idempotency note
Non-recoverableSet stop: true, describe manual resolution

Retry and Stop Conditions

Define in harness, not inside tools:

  • Max retries: 2
  • Hard stops: status: "error" with stop: true; same inputs called twice in a row

Granularity Guide

RiskGranularity
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, and artifacts
  • 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

PatternUse whenAvoid when
Direct executionSingle agent, clear scope, no subagent benefitsTask genuinely requires parallel sub-agents or specialized routing
RoutingInput type determines which specialized agent to invokeAgents share context and can't be isolated
ChainingOutput of A is strict input of BAgents need to share partial context
Orchestrator-workerParallel independent subtasks with a coordinatorTasks are tightly coupled or sequential
Agents-as-toolsCallable child agent inside a parent's tool loopThe 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

  1. Identify the bottleneck — measure before optimizing: count tool calls, token usage, and latency. Name the specific slow or expensive step.
  2. Choose the right pattern — use the table above. Default to direct execution; add orchestration only when simpler approaches are insufficient.
  3. Pack knowledge as cards — replace large prompt docs with targeted 5–10 line cards per operation.
  4. Bound search loops — cap retries (e.g., max 3 search attempts), normalize query construction, prefer a dedicated search subagent over inline ad-hoc loops.
  5. Model MCP sessions explicitly — for experimental sessions: track create/delete lifecycle, request _meta session IDs, handle missing-session errors without silent retries.
  6. 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 jq or equivalent JSON tooling available.
  • Ask before modifying, truncating, or deleting any session or history file.

Workflow

  1. Inventory session files — find metadata, current history, rotated previous history, and related subagent histories.

  2. 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
    
  3. Correlate tool call IDs — every tool_call in an assistant turn must have a matching tool_result in the immediately following user turn. Find the first gap.

  4. Check timing for slow calls:

    jq '.[] | select(.timing) | {role, duration_ms: .timing.duration_ms}' history.json
    
  5. Identify failure pattern — see table below.

  6. 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

SymptomLikely causeRepair
Tool call with no result turnSession interrupted mid-toolTruncate after last matched pair
Two consecutive user turnsDuplicate message insertionRemove the duplicate
tool_result with no prior tool_callCorrupted or manually edited historyRemove orphan result
Empty content on assistant turnModel returned no text + no toolsUsually safe to truncate
Session loops without progressMissing result causes re-promptInject 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:

  1. Explore project context — check files, docs, recent commits
  2. Ask clarifying questions — one at a time, understand purpose/constraints/success criteria
  3. Propose 2-3 approaches — with trade-offs and your recommendation
  4. Present design — in sections scaled to their complexity, get user approval after each section
  5. Write design doc — save to docs/specs/YYYY-MM-DD-<topic>-design.md and commit
  6. Spec self-review — quick inline check for placeholders, contradictions, ambiguity, scope
  7. User reviews written spec — ask user to review the spec file before proceeding
  8. 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:

  1. Placeholder scan: Any "TBD", "TODO", incomplete sections? Fix them.
  2. Internal consistency: Do any sections contradict each other?
  3. Scope check: Is this focused enough for a single implementation plan?
  4. 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

  1. Diagnose bloat — identify: redundant outputs (same file read multiple times), contradictory instructions that accumulated over turns, constraint forgetting (earlier requirements no longer respected).

  2. Draft summary — synthesize the current valid state of the code or plan in 3–5 sentences.

  3. 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.

  4. 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]
    
  5. 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

  1. 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 numbers
    

    Then read only the surrounding window (e.g. lines 120-160), not the entire file.

  2. 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.

  3. 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
    
  4. 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.

  5. 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:

  1. Focused - One clear problem domain
  2. Self-contained - All context needed to understand the problem
  3. 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:

  1. Review each summary — Understand what changed
  2. Check for conflicts — Did agents edit same code?
  3. Run full suite — Verify all fixes work together
  4. 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

  1. State the end condition. Explain exactly why you are stopping (e.g., "Task complete", "Blocked on PR", "Context window too large").

  2. 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.

  3. 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
    
  4. 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.

  5. 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

  1. Identify project root, package manager, and language(s).
  2. Find main entry points (executables, API handlers, CLI commands).
  3. Read the smallest set of files needed to explain the architecture.
  4. Map major modules, their responsibilities, and how data flows between them.
  5. 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

  1. Decide whether to compact by transition. Use the boundary table; default to NOT compacting mid-work.

    TransitionCompact?Reason
    Research -- PlanningYesResearch context is bulky; the plan is the distilled output
    Planning -- ImplementationYesPlan is saved in tasks/files; context is free to reset
    Implementation -- TestingMaybeKeep if tests reference recent code; compact if switching focus area
    Debugging -- Next featureYesDebug traces pollute unrelated work
    Mid-implementationNoLosing file paths, variable names, partial state is costly
    After a failed approachYesClear dead-end reasoning before trying a new approach
  2. 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
  3. Know what survives versus what is lost. Anything in the Lost column must be persisted in step 2 first.

    SurvivesLost
    CLAUDE.md / AGENTS.md instructionsIntermediate reasoning
    Task list (TodoWrite)File contents read in session
    Files on diskTool call history
    Git stateVerbally stated preferences
    Memory filesMulti-step conversation context
  4. 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 /compact with 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

  1. 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?"

  2. 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?"

  3. 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
    
  4. 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
    
  5. 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-powerups location, usually agent-powerups/ under the agent root or the package repo.
  • Optional CLI access to apx for discovery and inventory.
  • Optional installed discovery index file; treat it as a derived snapshot, not the source of truth.

Workflow

  1. 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 discover when 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 inventory for 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/.

  1. 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 signalAsset type to inspect
bug, failing test, regressiondebugging skill
implementation specplanning skill
file or URL intakefile-intake skill
pre-handoff validationcommand
local MCP setupMCP config
repo instruction baselineAGENTS.md template
  1. 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.

  1. 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.

  1. 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.

  1. 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 check output 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 apx catalog 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

ClaimRequiresNot Sufficient
Tests passTest command output: 0 failuresPrevious run, "should pass"
Linter cleanLinter output: 0 errorsPartial check, extrapolation
Build succeedsBuild command: exit 0Linter passing, logs look good
Bug fixedTest original symptom: passesCode changed, assumed fixed
Agent completedVCS diff shows changesAgent reports "success"
Requirements metLine-by-line checklistTests 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

ExcuseReality
"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

  1. Scope check — Identify all affected subsystems. If multiple independent subsystems, suggest separate plans.

  2. 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.

  3. 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]
    
    ---
    
  4. 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
  5. 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>`
    
  6. 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)
    
  7. 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?
  8. 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 but clearFullLayers() 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:

  1. Read the spec or request in full. If anything is ambiguous, ask before writing a single line.
  2. Identify the files to create or modify. Read them first.
  3. Write a failing test that captures the expected behavior. Confirm it fails.
  4. Implement the minimum code that makes the test pass. No extras.
  5. Run the full test suite: npm test. All tests must pass.
  6. If assets were added or changed, run apx validate catalog.
  7. 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:

  1. Re-read the user request in full. Identify the goal, constraints, and what "done" means.
  2. Map affected areas: run git status --short and apx list to see what exists.
  3. List the files most likely to change. For each, read its current state with the Read tool.
  4. Write a numbered step list — small enough that each step is one logical change.
  5. Identify risks: external dependencies, breaking changes, missing context.
  6. 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:

  1. Read the active plan or user request.
  2. Inspect changes with git status --short and git diff --check.
  3. Run targeted tests for changed behavior. For this repo, CLI/catalog changes usually require npm test.
  4. If assets changed, run:
    • apx validate skills
    • apx validate catalog
  5. 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:

  1. 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 discover when uncertain or when the task may need non-skill assets.
    • Use apx inventory for 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
  2. Pick the narrowest asset that matches the user task.
  3. Inspect it before using:
    • apx info <asset-name>
    • read the asset file when needed
  4. Run apx check <asset-name> only when the asset declares external requirements or its instructions require a dependency check.
  5. If a dependency is missing, stop that path and report the exact missing tool. Ask before installing anything.
  6. Apply the asset only within the user-requested scope.
  7. 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

  1. Evaluate the user's current development bottlenecks or architectural goals.
  2. Recommend specific tooling configurations or architectural shifts to address the pain points.
  3. Provide concrete implementation steps (e.g., configuration files, script updates).
  4. 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

  1. Understand Requirements: Review $ARGUMENTS carefully.
  2. Context Gathering: Map the files that will be affected by this change.
  3. Risk Analysis: Identify potential blast radius. Will this change break existing tests? Does it require database migrations?
  4. 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:
    1. Add test case to test/foo.spec.ts.
    2. Update src/foo.ts to pass the test.
    3. Export new type in src/index.ts.
  • 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

  1. Top-Down Search: Start with list_directory at the root. Look for package.json, Cargo.toml, pyproject.toml, or Makefile to understand the stack.
  2. Entry Point Identification: Find the main entry points (index.ts, main.py, App.tsx, cmd/main.go).
  3. Structural Grep: Use broad grep_search calls to find routes, controllers, or database models. E.g., grep_search "class .*Controller".
  4. Do Not Read Full Files: You are mapping, not reviewing. Use grep and file listings to infer structure.
  5. 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