andersonmrodrigues/paved

Improves the performance of server-side code paths: latency percentiles, throughput, data access patterns, remote calls, caching, concurrency and resource use. Use when a profile points at request handling, background processing or data access, or when a server-side budget fails.

Takes a bug report from symptom to verified fix: clarifies the expected behavior, reproduces the defect, isolates it, finds the root cause, writes a regression test, fixes it and verifies. Use when something that used to work, or should work, does not, and a fix is expected.

Reviews a finished change before completion across correctness, scope, architecture, consistency, maintainability, tests, security, performance and evidence. Use when a change reaches the review phase of a workflow, or when a human asks for a review.

Builds an understanding of a repository, or of the part a task touches, before anything is modified: structure, build and runtime, dependencies, tests, CI, configuration, documentation, entry points and architecture clues, plus the Project Context, rules and existing patterns relevant to the task. Use when starting a task, when working in an unfamiliar repository, or when unsure what a change affects.

Use when Paved surfaces a decision, blocks a command on user input, or an agent is asked to answer, relay, or raise a decision.

Writes or updates end-to-end tests that drive the system the way a user or client does, through its public interface, for the few flows that matter most. Use when a claim is about a complete user-visible flow that lower-level tests cannot prove.

Paved command paved.execute. Implement the approved plan, then test, verify, record evidence, review in the preview and complete the run.

Implements new behavior or a change to existing behavior: understands the requirement, finds the code it affects, plans the change and its proof, implements it in the repository's existing style, adds tests and verifies. Use when a task adds or changes what the software does and the requirement is clear enough to state as claims.

Plans, builds and critiques user-facing frontend interfaces with visual choices grounded in the product, audience and project. Use when creating or materially changing a page, component, layout, visual hierarchy, typography, color or motion; skip for backend-only work and fixes that do not alter the interface.

Improves the performance users perceive in a client application: time until content is visible and usable, responsiveness to input, visual stability, and the amount of data and code sent to the client. Use when a profile points at client-side loading, rendering or interaction, or when a user-facing performance budget fails.

Turns recurring agent mistakes and human corrections into structural improvements of the paved path, choosing the strongest enforcement layer available (architecture, static analysis, CI, rule, skill, documentation). Use when the same correction happens twice, when a rule keeps being violated, or when asked to improve Paved.

Paved command paved.init. Bootstrap the pinned project-local Paved runtime and initialize this repository.

Writes or updates tests that exercise a component together with its real collaborators (storage, messaging, other services or their local stand-ins) through the repository's existing integration test setup. Use when a claim depends on how components interact across a boundary, which unit tests with doubles cannot prove.

Paved command paved.intent. Start any repository change: classify the request into the feature, bug or refactor workflow, write the Intent, and run context and discovery.

Paved command paved.plan. Write the plan for the open run, review it in the preview, and record the user's approval given in the conversation.

Paved command paved.preview. Open a local review of a Markdown file or folder where a person comments on selected text across its documents.

Measures where time and resources go: defines the metric and workload, records a baseline, profiles to locate the bottleneck, changes one thing at a time and measures again under the same conditions. Use when a task concerns latency, throughput, memory, CPU, I/O or cost, or when a performance check or budget fails.

Builds a small, deliberately temporary implementation to answer a question (is this feasible, which approach works, what does a dependency really return) and reports the answer. Use when a human asks for a spike, proof of concept or experiment, not for code meant to ship.

Changes the structure of code without changing its behavior, in small steps that each keep the tests passing. Use when code must be reorganized, renamed, split, merged or simplified, or moved to respect a boundary, and no behavior should change.

Writes an automated test that reproduces a defect, fails before the fix and passes after it, at the lowest level that still captures the bug. Use for every bug fix and when turning an incident or reproduction into a permanent guard.

Sets up Paved in a repository that has no .paved/ directory, or repairs an incomplete one: discovers the repository, detects its technologies, proposes adapters, drafts Project Context, discovers verification commands and validates the result for human review. Use when asked to initialize, install or onboard Paved, or when paved doctor reports missing structure.

Finds the actual cause of a defect from observed evidence (errors, logs, failing tests, reproduction steps) and confirms it before any fix is attempted. Use when the cause of a bug, failing test, incident or unexpected behavior is not yet proven.

Observes a running system to explain its behavior: logs, metrics, traces, health endpoints and configuration, read-only first and never destructive in shared or production environments. Use when a defect or incident shows up only in a running environment, or when code reading alone cannot explain what the system does.

Reviews a change for security impact: trust boundaries crossed, untrusted input handling, authentication and authorization, secrets, sensitive data exposure and new dependencies. Use before completing any change that touches input handling, access control, data exposure, configuration or dependencies.

Paved command paved.status. Inspect Paved lifecycle, lock, adapters, context, verification profile and open runs, diagnose inconsistent state, and offer repairs.

Reviews an existing task, issue, ticket, story, bug or epic against the project's issue template and against the repository: missing sections, unverifiable criteria, premises the code contradicts, omitted impact and scope too large for one item. Returns validated findings, a verdict and a corrected version. Use when someone asks to review, refine, groom, improve or check a task or issue before it is implemented, including by pasting a link to it.

Writes new tracker items, or fills in an existing sparse issue or ticket, grounded in the repository: type, description, expected result, verifiable acceptance criteria, technical context and, for bugs, steps to reproduce, in the repository's own issue template when it has one. Splits requests too large for one item. Use when someone asks to write, create, fill in, complete, specify, detail or break down a task, issue, ticket, story, bug or epic for this repository, including by pasting a link to one.

Identifies what can go wrong, security-wise, in a design before or while it is built: what is being protected, where the trust boundaries are, which threats apply at each and what mitigates them. Use when a change adds a component, interface, data flow, integration or new kind of sensitive data, or when asked for a threat model.

Writes or updates fast, isolated tests for one unit of logic, following the repository's existing test conventions: location, naming, structure, test doubles and assertions. Use when code with its own logic is added or changed, or when a claim can be proven without real external collaborators.

Paved command paved.update. Plan and apply a safe local Core, adapter, or input update.