andersonmrodrigues/paved
Paved engineering commands for AI coding agents: repository context, governed workflows, explicit Tools, verification and evidence, executed by a pinned project-local Paved runtime.
Create or maintain a project-local skill and feature map for exercising user-visible behavior through the repository's existing verification tools. Use when setting up Paved in a repository with a runnable application, or when its verification guide is missing or stale.
Measure and improve latency, throughput or resource use in server-side request handling, background processing or data access. Use when profiling or a server-side budget identifies a backend bottleneck.
Reproduce a reported defect, find its cause, implement a fix and verify the behavior. Use when the user reports something that should work but does not and expects a fix; use root-cause-analysis when they only want the cause.
Carry a verified and reviewed change through its change request: open it, read automated checks and review comments, and merge only when the evidence still describes the head. Use when a completed Paved run's change is to be proposed, updated or merged through a pull or merge request; use change-review to review the code itself.
Review a completed code change for correctness, scope, architecture, tests, security, performance and evidence. Use when the user asks for a code review or a verified change reaches its review gate; use task-review for issue text and threat-modeling for a design not yet built.
Use when a user asks for repository orientation or onboarding: map an unfamiliar codebase's structure, entry points, key modules, tests or verification flow, even when no change is requested. Also use when starting discovery for a change or locating what an existing task may affect.
Relay a pending decision and collect the user's answer without deciding on their behalf. Use when Paved blocks on a decision or the user asks you to present or resume one.
Write end-to-end tests for important user-visible flows through the system's public interface. Use when a claim spans a complete flow that unit or integration tests cannot prove.
Paved command paved.execute. Take a request, or an approved plan, through to a verified and reviewed change, initializing or updating Paved when needed. Use when the user asks to execute a change or the user-approved plan is ready to implement.
Implement and verify a requested change to software behavior, including its tests and evidence. Use when the requirement is clear and the user asks to build or change behavior; use refactoring when behavior must stay the same and prototyping for throwaway experiments.
Design or critique a user-facing interface using the product, audience and project context. Use when creating or materially changing a page, component, layout, visual hierarchy, typography, color or motion; skip backend-only changes and fixes with no interface impact.
Improve perceived load time, interaction responsiveness, visual stability or client payload size. Use when profiling or a user-facing performance budget points to client loading, rendering or interaction.
Turn user corrections and repeated agent mistakes into an enforceable improvement to the engineering workflow. Use when a person corrects the agent with a project rule, the same correction recurs, a rule keeps being missed, or the user asks to improve Paved.
Run a bounded, evidence-based comparison of alternative agent harness configurations for a difficult or repeatedly failing task. Use when a task's quality or cost could plausibly improve through changes to prompts, guardrails, memory, tool guidance, subagents, skills, scripts, or plugins.
Paved command paved.init. Initialize Paved and prepare repository context and verification; offer a project-local app verification guide when a runnable user interface is present. Use when setting up Paved in a repository that is not initialized.
Test a component with its real collaborators or local stand-ins through the repository's integration setup. Use when behavior across a component boundary cannot be proven with isolated unit tests.
Paved command paved.intent. Start a repository change by classifying its type and recording the request before planning. Use when the user asks to begin a feature, bug fix, refactor or performance improvement, or asks a question about the code that needs a cited answer.
Paved command paved.plan. Draft and preview a plan for an open Intent, then record the user's explicit approval. Use when an Intent is ready for planning.
Paved command paved.preview. Open a local review of Markdown documents and collect comments on selected text. Use when the user wants to review or comment on documents before approving them.
Measure a performance baseline and locate its bottleneck before changing code. Use when investigating latency, throughput, memory, CPU, I/O or cost, or when a performance check or budget fails; use a specialized frontend or backend skill once the bottleneck is located.
Build a small disposable implementation to answer a feasibility or approach question. Use when the user asks for a spike, proof of concept or experiment; do not use for production code meant to ship.
Restructure, rename, split, merge or simplify code while preserving its behavior. Use when improving code structure or enforcing a boundary without changing what users observe; use feature-development when behavior changes.
Write a test that reproduces a defect, fails before its fix and passes after it at the lowest useful level. Use when fixing a bug or turning a confirmed incident or reproduction into a permanent regression guard.
Set up or repair Paved in a repository by preparing its project context, adapters and verification profile. Use when the user asks to initialize or onboard Paved, or Paved reports incomplete setup.
Identify and confirm the cause of a defect from errors, logs, failing checks or reproduction evidence without implementing a fix. Use when the user asks why a failure happens or the cause is still uncertain; use bug-investigation when a verified fix is expected.
Diagnose behavior that appears only while a system is running using logs, metrics, traces and health signals, starting with read-only inspection. Use when code inspection cannot explain a live defect or incident.
Review a change for risks to trust boundaries, input handling, access control, secrets, sensitive data or dependencies. Use when a change affects input, authorization, data exposure, security configuration or dependencies; use threat-modeling for a design before it is built.
Paved command paved.status. Inspect Paved setup, diagnostics and open runs, then offer safe repairs. Use when checking readiness or deciding whether a reported Paved problem needs repair.
Review an existing task, issue, ticket, story, bug report or epic for missing context, unsupported assumptions, unverifiable criteria and scope. Use when asked to assess or refine work-item text before implementation; use task-specification to write a new item and change-review to review code.
Turn a repository change request into a grounded, actionable task with a clear outcome and verifiable acceptance criteria. Use when asked to draft or complete a new or sparse issue, ticket, story, bug report or epic; use task-review to assess existing work-item text.
Identify assets, trust boundaries, likely threats and mitigations in a proposed design. Use when designing a new component, interface, data flow, integration or handling of sensitive data, or when the user asks for a threat model; use security-review for a completed code change.
Write fast, isolated tests for one unit of logic using the repository's test conventions. Use when new or changed logic can be proven without real external collaborators; use integration-testing when behavior depends on a boundary.
Paved command paved.update. Plan and apply a compatible local Paved Core, adapter or input update. Use when the user asks to update initialized Paved state.