SKILL.md

name	k6-plan
description	Plan deterministic k6 performance tests from goals, SLA, protocol context, or exploratory application context. Use when users ask to plan a load test, set up a stress/spike/soak strategy, request a full k6 test blueprint, or need a suggested plan from estimated load goals and app flows. Route implementation output requests to k6-builder.
user-invocable	true
disable-model-invocation	false
license	MIT
metadata	version category protocols 0.1.0 performance-testing http grpc browser

• User says: "build a complete k6 test plan with SLA"

Tool Discovery Protocol

At the beginning of the workflow, detect and use interaction tools in this order:

1. If AskUserQuestion exists, use it for required inputs.
2. Else if mcp:sampling or create_message exists, use native IDE modal interaction.
3. Else if confirm_action exists, use it for critical confirmations.
4. Else emit the exact fallback and end the turn:

> [?] MISSING REQUIREMENT: Missing scenario or protocol detail for planning
missing: scenario type, protocol
why: planning cannot continue safely until the test objective shape and protocol are known or inferable
next_question: What scenario type and protocol should this test use?

Do not continue plan generation after fallback.

Interoperability Fallback Contract

When fallback is required, always use this portable payload shape:

> [?] MISSING REQUIREMENT: <short missing requirement summary>
missing: <comma-separated missing fields>
why: <why plan generation cannot continue deterministically>
next_question: <single, specific question that unblocks the next step>

Do not emit final plan content after this fallback.

Core Rules

1. **Adaptive Question System**: When critical parameters are missing, start with the baseline planning questions and continue in the same question flow with any additional required questions: - What is the target URL/endpoint? (if `target` missing) - What scenario type do you need? Options: load, stress, spike, soak, smoke (if `scenario` missing) - What are your SLA requirements? Example: p95<500ms,error<1% (if `sla` missing) - What protocol should this test use? Options: http, grpc, browser (if `protocol` missing)

Exploratory planning mode:

• Auto-detect exploratory mode when the user provides a concrete load objective, concurrency goal, duration, throughput target, or named business flow but omits target, sla, or both.
• Auto-detect exploratory mode when the active workspace appears to contain the application under test and the user has not provided concrete endpoints, routes, or user journeys.
• Exploratory mode is allowed only when scenario is explicit or can be determined directly from the user's wording. If scenario remains ambiguous, stop and ask for clarification.
• In exploratory mode, prefer generating a suggested plan with explicit assumptions over stopping at the first missing target or sla.

Application-context exploration:

• Before asking for endpoints, auth, or exact routes, inspect the available application context when the workspace likely contains the system under test.
• Look for likely performance-critical surfaces such as API routes, frontend journeys, HTTP clients, auth entry points, dashboards, search flows, write-heavy transactional flows, and polling or streaming paths.
• Produce a short prioritized candidate list with evidence-backed labels such as inferred target, inferred flow, and why this flow matters.
• If exploration yields viable candidates, use them to build a provisional plan directly and move unresolved details into pending_clarifications instead of blocking on questions.

Edge case hardening: When user input is ambiguous or conflicts with best practices:

• If SLA thresholds conflict (e.g., "p95<100ms" for a high-latency service), ask clarification.
• If scenario and SLA are mismatched (e.g., "smoke test with SLA p99<50ms"), flag and ask confirmation.
• For gRPC plans: Always ask about TLS, metadata, and failure handling explicitly.

Round contract:

• Round 1: one consolidated baseline question block with all minimum required questions.
• Round 2: one optional tie-break block only when a critical ambiguity remains after Round 1.
• If required inputs are still unresolved after Round 2, emit the interoperability fallback and end the turn.

Provisional plan policy:

• Default behavior remains strict certainty for finalized plans.
• If scenario and protocol are clear but target, sla, auth, or exact flow details are missing, exploratory mode may generate a provisional plan with explicit inferred or [assumption-based] markers.
• If critical data is missing outside exploratory mode, return unknown for unresolved fields and ask one unblocker question.
• Suggested SLA values in exploratory mode must come only from documented profile defaults or explicit user placeholders; do not invent new threshold heuristics.
• If scenario type is ambiguous, do not generate a provisional plan; ask clarification using the Clarification Output Contract.

Exploratory output contract:

• Provisional plans must include plan_mode: exploratory, ready_for_builder: false, assumption_basis, inferred_targets, inferred_flows, and pending_clarifications.
• pending_clarifications must list each unresolved field, why it matters, and whether it blocks runnable artifact generation.
• Exploratory plans may recommend one or more candidate SLAs, but each candidate must be labeled suggested_sla and tied to a named profile or user-provided placeholder.
• Exploratory plans must not present inferred routes, auth requirements, or SLA values as confirmed facts.

Clarification-mode hard stop:

• When clarification mode is triggered, emit only the canonical clarification block and stop.
• Do not append plan scaffolding, executor hints, thresholds, stage ideas, protocol tactics, or builder handoff details.
• Treat any plan-like token leakage as a contract violation.

Additional questions must be integrated into the same question system, not handled as a separate side flow:

• Add an HTTP method question when protocol=http and the method cannot be inferred safely.
• Add one or more authentication questions when auth is required or unknown and executable output depends on it.
• Add more questions only inside Round 1 or the single Round 2 tie-break block when other critical ambiguities or missing requirements are detected.
• Do not finalize a runnable builder handoff until all required questions from this same system are resolved or explicitly moved into exploratory handoff metadata.

2. Load Profile Defaults (when profile is not specified):

   • minimal: 5 VUs, 1m duration, smoke testing
   • standard: 25 VUs, 9m duration, realistic load
   • aggressive: 120 VUs, 14m duration, stress testing

3. Output Format: Primary output is a textual execution plan with:

   • plan_mode: finalized or exploratory
   • Recommended executor type
   • VU count and stages
   • Duration estimate
   • SLA-derived thresholds or suggested_sla candidates
   • Protocol-specific recommendations
   • Data integration suggestions (CSV/JSON)
   • Exploratory metadata when applicable: assumption_basis, inferred_targets, inferred_flows, pending_clarifications, ready_for_builder
   • Exactly one deterministic Next recommended step

4. Determinism: Same inputs produce identical outputs every time.

5. Compact-by-default responses:

   • Keep plan output concise and practical.
   • Avoid long explanatory prose unless user requests detail.
   • Prefer short verified bullets and direct next action.

Verified Evidence Policy

1. Report only values backed by user-provided inputs or direct runtime/tool evidence.
2. Do not present inferred values as final facts.
3. If unresolved, mark as unknown and ask one unblocker question unless exploratory mode is active.
4. In exploratory mode, inferred values must be isolated under explicit labels such as inferred, suggested_sla, or [assumption-based].
5. Keep exploratory assumptions out of finalized summaries and runnable handoff fields unless they remain explicitly marked as provisional.

Terminology Contract

• Scenario type means the test objective shape (load, stress, spike, soak, smoke).
• Profile means default intensity presets (minimal, standard, aggressive) used when explicit vus/duration are missing.
• Round means one consolidated question block in the adaptive question system; baseline questions are Round 1 and the optional tie-break is Round 2.
• Exploratory mode means the skill is generating a suggested plan from partial requirements or codebase evidence while keeping unresolved fields explicit.
• Scenario type selects the executor strategy; profile sets default intensity values.

Language Policy

1. If user language is explicit, answer in that language.
2. If language is not explicit, default to English.
3. Keep command names, k6 metric keys, and code identifiers in English.

Cloud Runtime Compatibility Gate

Cloud planning must be version-aware before emitting cloud commands, cloud options, or cloud validation guidance.

Required detection flow:

1. Resolve executable target.
2. Run k6 version.
3. Parse semantic version.
4. Classify runtime family deterministically:
   • V0_53_TO_V1_5 for >=0.53.0 and <1.6.0
   • V1_6_PLUS_V1_X for >=1.6.0 and <2.0.0
   • V2_0_PLUS for >=2.0.0

Gate behavior:

1. If exact version is unknown or parse fails, stop cloud planning and ask for exact k6 version.
2. Do not invent synthetic cloud-family labels.
3. Preserve k6_version and runtime_family in builder handoff metadata.

Cloud Planning Inputs

When cloud behavior is requested, ask these inputs in the same active question flow:

1. Execution mode: cloud-run, cloud-streaming-local-execution, or local-only.
2. Routing needs: stack routing, project routing, both, or none.
3. Whether zonal distribution is required.
4. If distribution is required, collect full { loadZone, percent } entries.

Cloud Authentication Readiness

When cloud execution or cloud-ready handoff is requested, plan for an explicit auth path:

1. Prefer K6_CLOUD_TOKEN for non-interactive execution.
2. If token-based auth is not available, require an interactive login path via k6 cloud login before execution.
3. Treat missing auth readiness as a blocker for cloud execution handoff, but not for non-executable planning discussion.
4. Keep auth and routing guidance in environment variables or explicit login steps; never assume a live cloud session exists.

Cloud Version-Gated Behavior

1. V0_53_TO_V1_5:
   • Allow only k6 cloud login, k6 cloud run, and k6 cloud run --local-execution.
   • Do not emit stack/project workflow assumptions unless user explicitly targets >= v1.6.0.
   • Do not emit v2-only cloud options.
2. V1_6_PLUS_V1_X:
   • Allow the restricted v1 path above plus stack routing via options.cloud.stackID and K6_CLOUD_STACK_ID.
   • Keep cloud options constrained to proven v1 evidence.
3. V2_0_PLUS:
   • Allow verified v2 cloud options and cloud context vars.
   • Require stack routing for cloud command guidance.

Cloud Distribution Validation

When options.cloud.distribution is present:

1. Every entry must include loadZone and percent.
2. Every percent must be an integer.
3. Sum of all percent values must be exactly 100.
4. If any rule fails, stop runnable handoff and emit clarification/validation failure. Do not normalize automatically.

Dashboard Policy

Apply deterministic recommendation:

1. CI/headless: K6_WEB_DASHBOARD=false
2. Local browser troubleshooting: K6_WEB_DASHBOARD=true
3. Local non-browser: default K6_WEB_DASHBOARD=false unless explicit opt-in
4. Otherwise default false

Dynamic Capacity Protocol

Run this protocol before finalizing any plan that could lead to executable current-host k6 output or validation handoff. For pure cloud-run, local host capacity is advisory only and must not block the remote cloud recommendation unless the user also asks for local execution.

Cross-skill required fields:

• execution_context
• machine_profile
• projected_load
• capacity_estimate
• risk_status
• safe_limit_recommendation
• scale_out_recommendation

High-risk gate rule (mandatory):

• Before generating or orchestrating any script that projects more than 500 VUs on the current host, run host audit silently with node skills/k6-plan/scripts/audit-host.js.
• If Node.js is unavailable, use the Python fallback: python3 skills/k6-plan/scripts/audit-host.py.
• Parse stdout JSON and use that as the primary machine_profile evidence for this request.

Contextual deterministic formulas:

• vus_max = (logical_cpu * cpu_factor) + (free_ram_gb * ram_factor)
• arrival_rate_max = floor(vus_max / max(projected_load.expected_iteration_duration_seconds, 1))

Default context factors:

• local: cpu_factor=50, ram_factor=10
• ci: cpu_factor=30, ram_factor=6
• container: cpu_factor=25, ram_factor=5
• cloud: cpu_factor=60, ram_factor=12
• distributed: compute per node, then aggregate

Evaluation order:

1. Build execution_context from the declared environment (local, ci, container, cloud, or distributed) plus user constraints.
2. Determine whether the active load generator is the current host or remote cloud-managed infrastructure.
3. Derive machine_profile from current evidence only for current-host execution paths: logical_cpu, free_ram_gb, fd_limit, ephemeral_port_budget, environment type, and declared user restrictions.
4. If projected load is expected to exceed 500 VUs on the current host, run host audit (node skills/k6-plan/scripts/audit-host.js, fallback python3 skills/k6-plan/scripts/audit-host.py) and overwrite missing or stale machine evidence with audit output.
5. Add optional telemetry when available: prior k6 saturation, observed memory per VU, prior stable arrival rate, or prior port exhaustion signals.
6. Derive projected_load from the requested or defaulted executor shape: target VUs, arrival rate, duration, stages, and expected_iteration_duration_seconds for arrival-rate executors.
   • projected_load.expected_iteration_duration_seconds must come from explicit user input, prior measured telemetry, or a conservative [assumption-based] estimate called out in the plan.
   • If that field is unavailable, do not present arrival_rate_max as fully deterministic.
7. Calculate capacity_estimate.vus_max and capacity_estimate.arrival_rate_max from the current machine_profile using the contextual deterministic formulas when the current host generates load. Never use a universal fixed VU ceiling.
8. Classify risk_status as SAFE, AT_RISK, or HIGH_RISK against the current estimate for current-host execution.
9. Derive safe_limit_recommendation and scale_out_recommendation, including additional_cpu_percent, additional_ram_gb, and additional_nodes.
10. If execution mode is pure cloud-run and remote worker capacity is not verified, report remote capacity as unknown and keep local capacity advisory-only for optional local validation.

Incomplete-data rules:

• If critical machine inputs are missing, ask one clarification question when that is the cheapest unblocker.
• If the scenario is otherwise clear, continue with a conservative [assumption-based] estimate instead of inventing a global default capacity.
• Mark every derived field that depends on missing telemetry as [assumption-based] and state the missing evidence explicitly.
• For pure cloud-run, missing local machine evidence must not block remote execution planning; report remote capacity as unknown unless cloud worker constraints are explicitly provided.

Plan-stage behavior:

• Include all required fields above in the final plan.
• If risk_status is AT_RISK or HIGH_RISK, append the canonical alert exactly as written below.
• Do not recommend runnable single-node execution above safe_limit_recommendation.
• When projected load exceeds current capacity, recommend either a reduced safe limit or distributed execution.
• If risk_status is HIGH_RISK, stop local runnable guidance and return only a reduced local limit or distributed recommendation.
• For pure cloud-run, local host risk may inform optional dry-run advice but must not block the remote cloud recommendation.

Canonical alert format:

LOAD GENERATOR CAPACITY ALERT
Risk Detected: The requested scenario ([X] VUs) exceeds the load generator operating limit ([Y] VUs).
Impact: Possible metric skew, TCP port exhaustion, or k6 process collapse.
Recommendation: Reduce the scenario to [Z] VUs or use distributed infrastructure with at least [N] additional nodes.

Determinism rules:

• Y must come from the current capacity_estimate.
• Z must come from the current safe_limit_recommendation.
• N must come from the current scale_out_recommendation.additional_nodes.
• The same request and machine evidence must produce the same capacity classification.

HTTP Method Question

Before producing a final HTTP plan, add the method question to the same active question system:

1. Confirm primary method (GET, POST, PUT, PATCH, DELETE) when endpoint behavior depends on method.
2. If method is missing and cannot be inferred, ask it as an additional required question before finalizing.
3. Reflect confirmed method in scenario steps, checks, and threshold rationale.

Auth Discovery Questions

Before finalizing plan output or builder handoff parameters, add auth questions to the same active question system:

1. Detect whether authentication is required (Bearer token, API key, basic auth, mTLS, session cookie, or none).
2. If auth is required or still unknown for executable output, ask for auth mechanism and required variable names as additional required questions.
3. Never hard-code credentials in examples or generated scripts.
4. Prefer environment variables (__ENV) for auth inputs and list required variables.

SLA-Scenario Coherence Validation

When both scenario and sla are available, run this coherence pass before finalizing output. This pass does not block plan generation; it produces explicit warnings and a confirmation prompt when needed.

1. load scenario:
   • If p95 target is higher than 500ms, emit INFO about potentially relaxed latency target.
   • If error bound is higher than 5%, emit WARNING about overly permissive failure rate for load tests.
2. stress scenario:
   • If latency target is ultra-strict (for example p99<100ms), emit WARNING about unrealistic stress constraints.
   • If error bound is stricter than 1%, emit WARNING because stress tests intentionally probe failure boundaries.
3. spike scenario:
   • If planned duration is greater than 10m, emit WARNING that spike tests should be short and abrupt.
4. soak scenario:
   • If SLA is stricter than load baseline defaults, emit WARNING that soak validates endurance, not peak latency.
5. smoke scenario:
   • If SLA includes strict percentile constraints (for example p99<50ms), emit WARNING that smoke does not validate sustained latency behavior.

After warning emission, ask one confirmation question: Do you want to keep these thresholds for this scenario type, or adjust them now?

If user confirms to proceed, continue with the plan and keep a compact assumptions entry tagged [provided override].

SLA Consistency Across Multi-Environment

When planning for multiple environments (dev/staging/prod):

• Threshold values MUST BE IDENTICAL across all environments.
• VU counts MAY VARY per environment.
• Duration MAY VARY per environment.
• Performance SLA targets (p95, p99, error bounds) MUST NOT VARY per environment.

Rationale: SLA is a commitment and must remain coherent across environments. Relaxing SLA by environment creates non-comparable results and hides production risk.

Canonical cross-skill warning (must match k6-builder exactly):

WARNING: SLA must be identical across environments to maintain testing coherence.

Canonical enforcement flow (planning stage):

1. Detect single declared SLA plus per-environment threshold divergence request.
2. Emit the canonical warning string above.
3. Ask one confirmation question:
   • Do you want to normalize all environment thresholds to the same SLA now?
4. If user confirms normalization:
   • Continue planning with identical thresholds across dev/staging/prod.
5. If user rejects normalization:
   • Keep the plan as non-runnable planning guidance only.
   • Add assumptions tag [provided override] and explicit note:
     • Builder-stage enforcement will reject runnable artifacts with per-environment SLA relaxation.
   • Do not present relaxed thresholds as compliant defaults.

Clarification Output Contract

When required inputs are missing and a clarification response is needed (not a provisional plan), use this exact format and nothing else:

missing: <comma-separated list of missing fields>
why: <one sentence explaining why these fields are required to proceed>
next_question: <single, specific question that unblocks the next step>

Rules:

• Use exactly these three fields — no additions, no removals.
• Do not mix plan fragments, partial executor recommendations, or scenario guesses into the clarification response. The clarification block must be self-contained.
• Keep why strictly unblocker-focused. Do not mention executor names, thresholds, VU counts, stages, protocol tactics, or builder handoff details.
• In clarification mode, avoid plan-like tokens in prose (executor, thresholds, stages, vus, ramping, constant-vus, arrival-rate).
• If multiple fields are missing, list them all in missing but ask only the single most-blocking question in next_question.
• Do not use clarification mode when exploratory mode is allowed and sufficient evidence exists to suggest a provisional plan.
• After emitting the clarification block, end the response. Do not add caveats or partial analysis below it.

Required k6 Invariants

Always enforce these validations before returning the plan:

1. Thresholds are required

   • Parse thresholds from SLA if provided.
   • If SLA is not provided in finalized mode, derive profile-based defaults and show them explicitly.
   • If SLA is not provided in exploratory mode, emit one or more suggested_sla candidates derived only from documented profile defaults and keep them marked as unconfirmed.

2. Load profile is required

   • Plan must include explicit VUs and duration (or explicit stage set with equivalent duration and target VUs).
   • If vus/duration are missing, derive from profile defaults and state assumptions.
   • When request is multi-environment (dev/staging/prod), VU counts must be explicit and distinct per environment.

3. Runnable URL hard-coding is forbidden

   • Do not generate runnable scripts with fixed live target URLs.
   • Require __ENV.BASE_URL (or equivalent) for executable output.
   • If target is missing in finalized mode, ask for it instead of using a default live URL.
   • If target is missing in exploratory mode, list inferred_targets or unknown and keep ready_for_builder: false.

4. Parameter coherence is required

   • Derived or explicit profile values must map to explicit vus and duration, or explicit staged equivalents.
   • If write methods are planned (POST/PUT/PATCH), payload assumptions and expected status must be explicit.

5. Secrets and runnable safety are required

   • Never hard-code credentials or tokens in runnable snippets.
   • Require environment variables (__ENV) for auth inputs.

6. Protocol-specific technical quality is required

   • gRPC plans must always include: grpc_req_duration metric, client.connect() in setup or default, and guaranteed client.close() on all execution paths (teardown or try/finally). Omitting any of these from a gRPC plan is a planning error.
   • HTTP plans must always include: http_req_duration threshold, explicit timeout guidance, and checks for response validation.
   • Browser plans must always include: page/context lifecycle management and at least one Web Vitals metric recommendation.
   • These are not stylistic preferences — they are required outputs for their respective plan types.

7. Journey/state fidelity is required

   • For multi-step user journeys, preserve the full requested sequence in order; do not merge, reorder, or drop steps.
   • Include a session/data-state handling strategy when the journey depends on auth/session, cart state, or correlated user data.
   • If the user provides an end-to-end KPI (for example checkout p95<5s), include it explicitly in Thresholds and map it to the relevant k6 metric.
   • Correlation map required for flows with 3+ steps that extract data: For every step that produces a value consumed by a later step, the plan must document it explicitly using this structure:

     correlation_map:
       - step: login → extracts: access_token → used_by: [createOrder, applyCoupon, pay, verify]
       - step: createOrder → extracts: orderId → used_by: [applyCoupon, pay, verify]
       - step: applyCoupon → extracts: discountApplied → used_by: [pay, verify]
     

   • For each extraction: name the variable, its source (JSON field or response header), and every downstream step that consumes it. Generic mention of "correlation" without this level of detail is insufficient — it is a planning error for flows with 3+ chained data dependencies.

8. Cloud compatibility invariants are required (when cloud mode is requested)

   • Exact k6 version must be detected and classified before cloud guidance.
   • Output must match runtime family cloud allowlist.
   • Distribution math must pass strict 100% validation.
   • Cloud auth and routing guidance must use environment variables (K6_CLOUD_TOKEN, K6_CLOUD_STACK_ID, K6_CLOUD_PROJECT_ID).

9. Exploratory handoff safety is required

   • Exploratory plans must include ready_for_builder: false until target, protocol, auth, and SLA blockers for runnable generation are confirmed or intentionally deferred.
   • Every inferred route, auth assumption, or business flow used in the plan must appear in assumption_basis or pending_clarifications.
   • Do not present exploratory plans as runnable or validation-complete artifacts.

Output Contract

Every response must include these sections in order:

1. Planning Inputs Summary
2. Executor Recommendation
3. Load Profile (explicit or derived)
4. Thresholds (SLA-derived or defaults)
5. Protocol-Specific Notes
6. Guardrail Validation
7. Next recommended step

Dynamic capacity reporting requirements:

• Planning Inputs Summary must include plan_mode and execution_context.
• Planning Inputs Summary must include assumption_basis when exploratory mode is active.
• Load Profile must include projected_load and machine_profile.
• Thresholds must switch from confirmed SLA to suggested_sla candidates when exploratory mode is active.
• Protocol-Specific Notes must include capacity_estimate, risk_status, safe_limit_recommendation, and scale_out_recommendation.
• Protocol-Specific Notes must include inferred_targets, inferred_flows, and ready_for_builder when exploratory mode is active.
• When risk_status is AT_RISK or HIGH_RISK, Protocol-Specific Notes must include the canonical capacity alert with current calculated values.

Guardrail Validation checklist (minimum):

• Final summary includes only verified facts or explicit unknown
• Missing critical data is surfaced with one unblocker question
• No assumption-based values are presented as confirmed
• Exploratory outputs keep ready_for_builder: false until runnable blockers are resolved

Scenario to Executor Mapping

- **load**: ramping-vus with gradual ramp-up/down - **stress**: ramping-vus with aggressive progression beyond capacity - **spike**: ramping-vus with rapid surge to peak - **soak**: constant-vus or ramping-vus sustained for extended duration - **smoke**: constant-vus with minimal load

SLA Parsing Rules

Parse SLA string to extract threshold conditions. Supported syntax:

Simple Conditions (single metric)

• p95<Xms → 95th percentile latency threshold
• p99<Xms → 99th percentile latency threshold
• error<X% or rate<X% → Error rate threshold

Comma-Separated Lists (implicit AND)

• p95<500ms,p99<900ms,error<1% → All conditions must be met
• Commas separate independent thresholds
• All listed thresholds are combined in final configuration

Explicit AND Conditions (multiple conditions on same metric)

• p95<500ms AND p95>100ms → p95 must be between 100ms and 500ms
• Multiple constraints on the same metric (range validation)
• Translates to multiple threshold entries for the same k6 metric

Note: OR logic is not supported in this skill behavior. All conditions are treated as mandatory (AND).

Parsing Examples

• Input: p95<400ms,error<1% → p95 AND error rate thresholds
• Input: p95<500ms AND p99<900ms → Both percentiles required
• Input: p99<200ms → p99 threshold must be emitted exactly (no conversion to p95-only)
• Input: p95<2s → Single threshold with p99 inferred (see sla-defaults.md)

Defaults per profile when SLA is not provided:

• minimal: p95<800ms, error<2%
• standard: p95<500ms, error<1%
• aggressive: p95<300ms, p99<700ms, error<0.5%, checks>99%

Protocol-Specific Generation

### HTTP - Use `http.get()`, `http.post()`, `http.batch()` for parallel requests - Metrics: `http_req_duration`, `http_req_failed` - Include explicit timeout guidance (baseline `timeout: '30s'`) for executable HTTP examples; missing timeout should be validated as `WARNING`. - Tag requests: `tags: { name: 'api-call' }`

gRPC

• Use grpc.Client(), client.load(), client.connect(), client.invoke()
• Metrics: grpc_req_duration, grpc_req_failed
• Always close connections on all execution paths (teardown or try/finally)
• Handle metadata for authentication
• Connection lifecycle guidance is mandatory:
  • Create/load client once, outside the hot iteration path.
  • Do not reconnect on every iteration unless explicitly justified.
  • Prefer teardown() for client.close() to avoid leaked connections.
• TLS guidance must be explicit:
  • Secure endpoints should use TLS-enabled connection options.
  • Non-TLS/plaintext mode must be marked as test-only assumption.
• Metadata guidance must include concrete key examples and env-var-driven token usage.
• Timeout guidance must include both connection timeout and request timeout recommendations.
• Flag anti-pattern: reconnect-per-iteration as a performance and reliability risk.

Browser

• Use browser.newContext(), context.newPage(), page.goto(), page.waitForSelector()
• Always close page/context at iteration end
• Prefer data-testid selectors
• Collect Web Vitals when relevant

Progressive Disclosure

Keep this file focused on core planning workflow. Place deep guidance in:

• skills/k6-plan/references/README.md

Workflow

When user invokes this skill:

1. Parse provided parameters (target, scenario, sla, profile, protocol, duration, vus, output).
2. Run Tool Discovery Protocol when scenario or protocol is missing and cannot be inferred safely.
3. Detect whether exploratory mode should activate from partial requirements or application-context evidence.
4. If the workspace likely contains the application under test and target is missing, inspect the available code and derive prioritized inferred_targets and inferred_flows before asking endpoint/auth questions.
5. Start the Adaptive Question System with baseline questions when target, scenario, sla, or protocol are missing.
   • If clarification mode is selected, emit only the canonical missing/why/next_question block and end the response immediately.
   • In clarification mode, reject any appended plan fragments, executor suggestions, threshold snippets, staged load drafts, or builder handoff notes.
6. Apply load profile defaults based on profile.
7. Add an HTTP method question to the same question system when protocol is HTTP and the method is still ambiguous.
8. Add auth questions to the same question system when auth is required, unknown, or otherwise blocks executable output.
9. Add more questions in the same system if other critical ambiguities or missing requirements are detected.
10. Select executor based on scenario type.
11. Parse SLA thresholds, apply deterministic defaults, or emit suggested_sla candidates for exploratory mode.
12. Run the Dynamic Capacity Protocol using current machine evidence and projected workload only when the selected execution path uses the current host as the load generator.
13. If cloud execution or cloud-ready handoff is requested, add explicit cloud auth readiness guidance (K6_CLOUD_TOKEN or k6 cloud login) before execution advice.
14. For journey-style plans, preserve the full requested sequence and add session/data-state handling strategy.
15. Validate explicit or derived VUs and duration.
16. Generate textual plan with recommendations and exploratory metadata when applicable.
17. Validate output structure using the Output Contract section order.
18. Add exactly one deterministic Next recommended step based on first unresolved dependency.
19. If output=script or user explicitly requests runnable code, route to k6-builder with accumulated plan parameters (target, scenario, sla, protocol, profile, method, auth, duration, vus) plus the current capacity assessment fields and exploratory metadata.
20. Return the plan and assumptions summary.

Local Evaluation Workspace Policy

For official skill evaluation runs in this repository:

• Store artifacts under skills/k6-plan/k6-plan-workspace/iteration-N/.
• Keep each run isolated inside its own iteration-N directory.
• Treat benchmark outputs, grading files, timing files, and generated responses as non-versioned execution artifacts.