@lovehlmmm/primekit 1.0.0

package/skills/scenario/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: pk:scenario
+description: "Generate comprehensive edge cases and test scenarios by decomposing features across 12 dimensions. Use for pre-implementation risk discovery, QA planning, regression design, and iterative saturation when coverage must be exhaustive."
+user-invocable: true
+when_to_use: "Invoke to expand requirements into edge cases and QA scenarios."
+category: utilities
+keywords: [edge-cases, test-scenarios, dimensions, saturation, iterations]
+argument-hint: "<file path or feature description> [--iterations N] [--saturation]"
+metadata:
+  author: primekit
+  attribution: "Scenario exploration pattern adapted from autoresearch by Udit Goenka (MIT)"
+  license: MIT
+  version: "1.2.0"
+---
+
+# pk:scenario — Edge Case & Scenario Explorer
+
+Decompose any feature or code path across 12 dimensions to surface edge cases, risks, and test targets before implementation begins.
+
+Supports two modes:
+- **One-shot** (default): single pass, 3–5 scenarios per relevant dimension. Fast, backwards-compatible.
+- **Iterative** (`--iterations N` or `--saturation`): loop until bounded count or novelty exhausted.
+
+## When to Use
+
+- Before implementing complex or stateful features
+- Before writing tests (generates test targets)
+- Risk assessment during planning or code review
+- API design review — surface contract edge cases early
+- Deep pre-release coverage audit (`--saturation`)
+
+## When NOT to Use
+
+- Trivial single-line changes or cosmetic UI tweaks
+- Already well-tested, stable code with no recent modifications
+- Pure configuration changes with no logic paths
+
+---
+
+## Flags
+
+| Flag | Default | Purpose |
+|------|---------|---------|
+| `--iterations N` | — | Bounded loop: run exactly N iterations, then stop with summary |
+| `--saturation` | off | Saturation loop: keep iterating until 2 consecutive iterations produce no novel scenarios |
+| `--domain <type>` | auto | Domain hint: `software`, `product`, `business`, `security`, `marketing` |
+| `--focus <dim>` | auto | Prioritize dimension: `edge-cases`, `failures`, `security`, `scale` |
+| `--format <type>` | table | Output format: `table`, `use-cases`, `test-scenarios`, `threat-scenarios` |
+
+When neither `--iterations` nor `--saturation` is set: one-shot mode (original behavior, default).
+
+---
+
+## 12 Decomposition Dimensions
+
+Not all 12 apply to every feature. Identify relevant dimensions first, then generate scenarios only for those.
+
+| # | Dimension | What to Look For |
+|---|-----------|------------------|
+| 1 | **User Types** | admin, guest, banned, new user, power user, bot/scraper |
+| 2 | **Input Extremes** | empty, null, max length, unicode, special chars, SQL/script injection |
+| 3 | **Timing** | concurrent access, race conditions, timeout, slow network, retry storms |
+| 4 | **Scale** | 0 items, 1 item, 1M items, pagination boundary, cursor wrap |
+| 5 | **State Transitions** | first use, mid-flow abort, resume after crash, partial completion |
+| 6 | **Environment** | mobile/low-end CPU, no JS, screen reader, proxy/VPN, different timezone/locale |
+| 7 | **Error Cascades** | DB down, API timeout, disk full, OOM, network partition, partial write |
+| 8 | **Authorization** | expired token, wrong role, shared/public link, CORS, CSRF, privilege escalation |
+| 9 | **Data Integrity** | duplicate entries, orphan references, encoding mismatch, concurrent schema migration |
+| 10 | **Integration** | webhook replay, API version mismatch, third-party outage, contract drift |
+| 11 | **Compliance** | GDPR deletion request, audit logging gap, data retention, accidental PII exposure |
+| 12 | **Business Logic** | edge pricing (zero/negative), coupon stacking, refund after partial delivery, free tier limits |
+
+---
+
+## Workflow
+
+### One-Shot Mode (default)
+
+1. **Read** target file(s) or parse feature description from argument
+2. **Filter dimensions** — mark which of the 12 apply; skip irrelevant ones explicitly, naming the assumption behind each skip. A dimension skipped on an assumption that could break within the life of this feature is itself a scenario, not a skip
+3. **Generate 3–5 scenarios** per relevant dimension
+4. **Categorize severity** — Critical / High / Medium / Low
+5. **Output** as structured table (see format below)
+6. **Summarize** total scenario count by severity
+
+### Iterative Mode (`--iterations N` or `--saturation`)
+
+Iterative mode runs this saturation loop:
+
+1. **Read** target and build understanding (actors, components, preconditions)
+2. **Filter dimensions** — same as one-shot
+3. **Loop** — each iteration:
+   a. Pick highest-priority unexplored dimension or combination
+   b. Generate **one** concrete situation (specific trigger, flow, expected outcome)
+   c. **Classify** against all previously kept situations:
+      - **New**: different dimension AND different trigger/precondition → KEEP
+      - **Variant**: same dimension but different actor, data, or outcome → KEEP
+      - **Duplicate**: same dimension + same trigger + same outcome → DISCARD
+      - **Out of scope / Low value** → DISCARD, log reason
+   d. If kept: expand edge cases (what-if, boundary, interruption, ordering, missing data, stale data)
+   e. Log row to `scenario-results.tsv`
+   f. Every 5 iterations: print progress summary (see format below)
+4. **Halt**:
+   - `--iterations N`: stop after N iterations
+   - `--saturation`: stop when 2 consecutive iterations produce zero `New` classifications
+5. **Output** final summary with coverage matrix and composite score
+
+**Force dimension rotation** after 3 consecutive same-dimension iterations. Rotate through:
+Dimension walk → Combination → Negation → Amplification → Persona shift → Temporal shift
+
+### Severity Criteria
+
+| Level | Meaning |
+|-------|---------|
+| **Critical** | Data loss, security breach, auth bypass, silent corruption |
+| **High** | Feature broken for a subset of users, data inconsistency |
+| **Medium** | Degraded UX, recoverable error not surfaced to user |
+| **Low** | Minor visual glitch, non-blocking warning |
+
+---
+
+## Output Format
+
+### One-Shot
+
+```
+## Scenario Report: [target]
+
+Dimensions analyzed: [list]
+Dimensions skipped: [list + reason]
+
+| # | Dimension | Scenario | Severity | Expected Behavior |
+|---|-----------|----------|----------|-------------------|
+| 1 | Input Extremes | Empty string for required name field | High | Return 400 with field error |
+| 2 | Authorization | Expired JWT accessing protected route | Critical | Redirect to login, invalidate session |
+| 3 | Timing | Two users submit same form simultaneously | High | Idempotency key or conflict error |
+
+### Summary
+- Critical: N
+- High: N
+- Medium: N
+- Low: N
+- Total: N scenarios across X dimensions
+```
+
+### Iterative — Progress Summary (every 5 iterations)
+
+```
+=== Scenario Progress (iteration 15) ===
+Scenarios kept:    12  (8 new, 4 variants)
+Discarded:          3  (2 duplicates, 1 out-of-scope)
+Dimensions covered: 7/12 (58%)
+Edge cases found:  18
+Severity:          2 Critical, 4 High, 8 Medium, 4 Low
+Coverage gaps:     scale, temporal, recovery
+```
+
+### Iterative — TSV Log (`scenario-results.tsv`)
+
+```tsv
+iteration	dimension	classification	severity	title	description	parent
+1	happy_path	new	-	Successful checkout	User completes standard checkout	-
+2	error_path	new	HIGH	Payment declined	Card rejected during checkout	-
+3	edge_case	duplicate	-	Empty cart	Already covered by #1	#1
+```
+
+### Iterative — Final Summary
+
+```
+## Scenario Report: [target]  (iterations: N)
+
+[Full table of kept scenarios, grouped by dimension]
+
+### Coverage Matrix
+[dimension × severity grid]
+
+### Composite Score: NNN
+  scenarios_generated * 10  = X
+  edge_cases_found * 15     = X
+  dimensions_covered * 30   = X
+  unique_actors * 5         = X
+  high_severity * 3         = X
+
+### Saturation
+Halted: [after N iterations — bounded] | [saturation — 2 consecutive iterations with no novel cases]
+```
+
+---
+
+## Integration with Other Skills
+
+| Next Step | Skill | How |
+|-----------|-------|-----|
+| Generate test cases from scenarios | `pk:test` | Pass scenario table as input context |
+| Inform implementation plan risks | `pk:plan` | Paste Critical/High rows into risk assessment |
+| Deep persona debate on top risks | `pk:predict` | Feed Critical scenarios as the change proposal |
+
+---
+
+## Reference
+
+Saturation loop mechanics, novelty detection, and generation strategy are embedded in the iterative-mode instructions above.
+
+---
+
+## Example Invocations
+
+```
+# One-shot (default — backwards compatible)
+/pk:scenario src/api/payment.ts
+/pk:scenario "User registration with OAuth providers"
+
+# Bounded iterative — exactly 25 iterations
+/pk:scenario src/api/payment.ts --iterations 25
+
+# Saturation — stop when coverage exhausted
+/pk:scenario "Add multi-tenancy to the database layer" --saturation
+
+# Saturation with domain hint for priority dimension ordering
+/pk:scenario src/middleware/auth.ts --saturation --domain security
+```
+
+---
+
+## Lineage
+
+Faithful absorption (in scope) of upstream `/autoresearch:scenario` ([uditgoenka/autoresearch](https://github.com/uditgoenka/autoresearch), MIT). The local version supports both one-shot generation and the iterative saturation loop.
+
+See `/pk:autoresearch` for the full family map.

package/skills/scout/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: pk:scout
+description: "Fast codebase scouting using native search, optional Explore agents, and user-permitted OpenCode probes. Use for file discovery, task context gathering, and scoped searches across directories."
+user-invocable: true
+when_to_use: "Invoke for fast file discovery and codebase orientation."
+category: dev-tools
+keywords: [codebase, scouting, file-discovery, search]
+argument-hint: "[search-target] [ext] [--ultra]"
+metadata:
+  author: primekit
+  version: "1.1.0"
+---
+
+# Scout
+
+Fast, token-efficient codebase scouting using parallel agents to find files needed for tasks.
+
+## Arguments
+- Default: Scout using built-in Explore subagents in parallel when delegation is permitted (`./references/internal-scouting.md`)
+- `ext`: Scout using user-permitted OpenCode probes when native/local search is insufficient (`./references/external-scouting.md`)
+- `--ultra`: Run the scout as a best-of-5 verifier pass (see Ultra Verifier Mode)
+
+## When to Use
+
+- Beginning work on feature spanning multiple directories
+- User mentions needing to "find", "locate", or "search for" files
+- Starting debugging session requiring file relationships understanding
+- User asks about project structure or where functionality lives
+- Before changes that might affect multiple codebase parts
+
+## Quick Start
+
+1. Analyze user prompt to identify search targets
+2. Use a wide range of `search_files` patterns to find relevant files and estimate scale of the codebase
+3. Spawn parallel agents with divided directories only when the active runtime permits delegate_agent usage
+4. Collect results into concise report
+
+## Runtime Tooling
+
+Use portable capabilities first:
+- `search_files` for local discovery.
+- `read_file` for scoped file reads.
+- `run_shell` for local commands such as `rg`, `wc`, or `sed`.
+- The live task-management surface for progress tracking when useful.
+- `delegate_agent` for Explore subagents only when user request and runtime policy allow delegation.
+
+Do not spawn subagents only because this skill mentions Explore. Some runtimes,
+including Codex Desktop, require the actual user request to explicitly ask for
+subagents, delegation, or parallel agent work. If that explicit request is
+absent, scout in the main agent with `search_files` and `read_file`.
+
+Runtime mapping for `delegate_agent`:
+- Claude Code: use the native delegate call with `subagent_type: "Explore"`.
+- Codex Desktop: Explore is a deferred multi-agent role. If `multi_agent_v1`
+  is not visible, call `tool_search` for multi-agent spawn tools first, then use
+  `multi_agent_v1.spawn_agent` with `agent_type: "Explore"`. Do not set a model
+  override; the Explore role owns its runtime model configuration.
+
+## Workflow
+
+### 1. Analyze Task
+- Parse user prompt for search targets
+- Identify key directories, patterns, file types, lines of code
+- Determine optimal SCALE value of subagents to spawn
+
+### 2. Divide and Conquer
+- Split codebase into logical segments per agent
+- Assign each agent specific directories or patterns
+- Ensure no overlap, maximize coverage
+
+### 3. Register Scout Work
+- **Skip if:** Agent count ≤ 2 (overhead exceeds benefit)
+- Discover the live task-management surface and check for existing scout work
+- If available, register one scoped item per agent; otherwise update the active plan
+- Keep tracking concise: scope, assigned directories, current status, and timeout
+- Treat the active plan as the durable source of truth
+
+### 4. Spawn Parallel Agents
+Load appropriate reference based on decision tree:
+- **Internal (Default):** `references/internal-scouting.md` (Explore subagents)
+- **External:** `references/external-scouting.md` (OpenCode)
+
+**Notes:**
+- Record each scope as in progress before spawning its agent
+- Prompt detailed instructions for each subagent with exact directories or files it should read
+- Remember that each subagent has less than 200K tokens of context window
+- Amount of subagents to-be-spawned depends on the current system resources available and amount of files to be scanned
+- Each subagent must return a detailed summary report to a main agent
+- In Codex Desktop, first expose deferred multi-agent tools through `tool_search` if they are not already visible.
+- If runtime policy blocks subagents because the user did not explicitly request delegation, continue with main-agent scouting instead of forcing a spawn.
+
+### 5. Collect Results
+**IMPORTANT:** Invoke "the engineer project-organization skill" skill to organize the outputs.
+
+- Timeout: 3 minutes per agent (skip non-responders)
+- Record completed scopes and log timed-out agents in the report
+- Aggregate findings into single report
+- List unresolved questions at end
+
+## Report Format
+
+```markdown
+# Scout Report
+
+## Relevant Files
+- `path/to/file.ts` - Brief description
+- ...
+
+## Unresolved Questions
+- Any gaps in findings
+```
+
+## Ultra Verifier Mode (`--ultra`)
+
+When `--ultra` is present, run the scout as a best-of-5 verifier pass instead
+of a single pass. The controller builds one immutable evidence packet (the
+search targets, scope boundaries, and any prior findings) plus a rubric, then
+dispatches exactly five independent read-only candidate scout passes in one
+parallel wave; a single strongest-model verifier scores them.
+
+- **Candidate task:** each candidate produces a complete scout report — relevant
+  files with one-line roles, relationships, and unresolved questions — from the
+  same evidence packet.
+- **Rubric:** coverage of the stated targets, evidence quality (paths verified,
+  roles accurate), signal density, and honesty about gaps.
+- **Finalizer:** the verifier returns the
+  evidence-validated, deduplicated union of scouted findings across the five
+  passes — a relevant file may surface in only one candidate. It drops paths it
+  cannot validate; the controller emits the merged report.
+
+Scout's no-delegation degrade path does not apply under `--ultra`: if the
+runtime cannot dispatch five parallel read-only candidates,
+hard-stop and name the missing capability — never degrade to main-agent
+scouting for an ultra run. Full mechanics (evidence packet, anonymization, the
+five-usable-candidate gate, reject-all, fail-closed dispatch) are in
+`../primekit-brainstorm/references/ultra-verifier-mode.md`. It is a best-of-5
+verifier mode inspired by LLM-as-a-Verifier, not the full framework.
+
+## References
+
+- `references/internal-scouting.md` - Using Explore subagents
+- `references/external-scouting.md` - Using user-permitted OpenCode probes
+
+## Workflow Position
+
+**Typically precedes:** `/pk:fix` (fix after locating code)
+**Related:** `the engineer debug skill` (investigate after scouting), `/pk:brainstorm` (explore after scouting), `the installed code-review skill` (scout edge cases before review, engineer tier)

package/skills/scout/references/external-scouting.md

@@ -0,0 +1,85 @@
+# External Scouting with OpenCode
+
+Use external agentic tools only when the user permits that execution path and
+the runtime-native search capabilities are insufficient.
+
+## Routing
+
+```text
+Native/local search sufficient  -> use search_files, read_file, rg, wc, sed
+External probe permitted        -> use OpenCode for bounded read-only scopes
+Antigravity requested           -> route through primekit-orchestrate
+```
+
+Ordinary scouting must not invoke Antigravity directly. The `primekit-orchestrate`
+skill owns its version, authentication, safety, and first-class verification
+gates. Use that skill when the user explicitly requests Antigravity.
+
+## OpenCode CLI
+
+```bash
+opencode run "Find all payment-related files in lib/ and api/" --model opencode/grok-code
+```
+
+## Installation Check
+
+Verify OpenCode before using the external path:
+
+```bash
+command -v opencode
+```
+
+If OpenCode is not installed, continue with `search_files`, `read_file`, and
+scoped `run_shell` searches. Use internal Explore delegation only when the user
+explicitly requested or permitted subagents.
+
+## Parallel External Commands
+
+Prefer parallel runtime tool calls when available. If only shell execution is
+available, run independent one-shot searches with non-overlapping scopes:
+
+```bash
+opencode run "Read-only: search db/ and migrations/ for migration files" --model opencode/grok-code
+opencode run "Read-only: search lib/ and src/ for database schema files" --model opencode/grok-code
+opencode run "Read-only: search config/ for database configuration" --model opencode/grok-code
+```
+
+Do not dispatch multiple searches against the same directories. External tools
+must remain read-only for scouting prompts.
+
+## Prompt Guidelines
+
+- Name exact directories to search.
+- Request file paths with one-line relevance notes.
+- State that the task is read-only.
+- Set scope boundaries and exclusions.
+- Ask for relationships only when they affect the task.
+
+## Reading File Content
+
+Use local chunking for large files. Do not send whole private files to an
+external CLI just to bypass a context limit.
+
+### Step 1: Get Line Counts
+
+```bash
+wc -l path/to/file1.ts path/to/file2.ts path/to/file3.ts
+```
+
+### Step 2: Read Bounded Chunks
+
+- Files under 500 lines: read directly.
+- Files from 500 to 1500 lines: split into 2-3 chunks.
+- Files over 1500 lines: split into roughly 500-line chunks.
+
+```bash
+sed -n '1,500p' large-file.ts
+sed -n '501,1000p' large-file.ts
+```
+
+## Error Handling
+
+- Treat a non-zero exit code as failure.
+- Do not retry a failed external probe automatically.
+- After two external failures, continue with native/local scouting.
+- Note incomplete directory coverage in the report.

package/skills/scout/references/internal-scouting.md

@@ -0,0 +1,148 @@
+# Internal Scouting with Explore Subagents
+
+Use Explore subagents when SCALE >= 6 or external tools unavailable, and only
+when the active runtime permits the `delegate_agent` capability.
+
+## Delegation Gate
+
+Do not spawn Explore only because this reference says to use Explore. Spawn
+Explore only when:
+- The user explicitly asked for subagents, delegation, or parallel agent work.
+- The active runtime exposes a delegate_agent capability.
+- Each subagent has a distinct scope and useful work to do.
+
+If any condition is false, scout in the main agent with `search_files`,
+`read_file`, and `run_shell`.
+
+## How It Works
+
+Spawn multiple `Explore` subagents through the runtime's `delegate_agent`
+capability to search codebase segments in parallel.
+
+## Runtime Tool Mapping
+
+### Claude Code
+
+Use the native delegate call:
+
+```text
+delegate_agent capability(subagent_type="Explore", prompt="<prompt>", description="<short scope>")
+```
+
+### Codex Desktop
+
+Explore may be a deferred tool. If `multi_agent_v1` tools are not visible, first
+call `tool_search` for multi-agent spawn tools. Then call:
+
+```text
+multi_agent_v1.spawn_agent(
+  agent_type="Explore",
+  message="<prompt>"
+)
+```
+
+Do not set a model override. The Explore role owns its runtime model
+configuration. Close completed agents after collecting results so they do not
+consume concurrency slots.
+
+## Prompt Template
+
+```
+Quickly scout {DIRECTORY} for files related to: {USER_PROMPT}
+
+Instructions:
+- Search for relevant files matching the task
+- Use `search_files` capability for file discovery
+- List files with brief descriptions
+- Timeout: 3 minutes max
+- Skip if timeout reached
+
+Report format:
+## Found Files
+- `path/file.ext` - description
+
+## Patterns
+- Key patterns observed
+```
+
+## Spawning Strategy
+
+### Directory Division
+Split codebase logically:
+- `src/` - Source code
+- `lib/` - Libraries
+- `tests/` - Test files
+- `config/` - Configuration
+- `api/` - API routes
+
+### Parallel Execution
+- Spawn all agents in a single assistant turn when the runtime supports parallel tool calls
+- Each agent gets distinct directory scope
+- No overlap between agents
+
+## Example
+
+User prompt: "Find authentication-related files"
+
+```
+Agent 1: Scout src/auth/, src/middleware/ for auth files
+Agent 2: Scout src/api/, src/routes/ for auth endpoints
+Agent 3: Scout tests/ for auth tests
+Agent 4: Scout lib/, utils/ for auth utilities
+Agent 5: Scout config/ for auth configuration
+Agent 6: Scout types/, interfaces/ for auth types
+```
+
+## Timeout Handling
+
+- Set 3-minute timeout per agent
+- Skip non-responding agents
+- Don't restart timed-out agents
+- Aggregate available results
+
+## Reading File Content
+
+When needing to read file content, use chunking to stay within context limits (<150K tokens safe zone).
+
+### Step 1: Get Line Counts
+```bash
+wc -l path/to/file1.ts path/to/file2.ts path/to/file3.ts
+```
+
+### Step 2: Calculate Chunks
+- **Target:** ~500 lines per chunk (safe for most files)
+- **Max files per agent:** 3-5 small files OR 1 large file chunked
+
+**Chunking formula:**
+```
+chunks = ceil(total_lines / 500)
+lines_per_chunk = ceil(total_lines / chunks)
+```
+
+### Step 3: Read Chunks
+
+**Small files (<500 lines each):**
+Use `read_file` directly or `run_shell` with `sed`/`cat` for test-controlled
+paths.
+
+**Large file (>500 lines) - use sed for ranges:**
+Use `run_shell` with `sed -n` ranges in the main agent. Delegate chunk reading
+only when the user explicitly requested parallel delegation and the runtime has
+an appropriate worker role.
+
+### Chunking Decision Tree
+```
+File < 500 lines     → Read entire file
+File 500-1500 lines  → Split into 2-3 chunks
+File > 1500 lines    → Split into ceil(lines/500) chunks
+```
+
+Spawn all in a single assistant turn only when delegation is permitted.
+
+## Result Aggregation
+
+Combine results from all agents:
+1. Deduplicate file paths
+2. Merge descriptions
+3. Note any gaps/timeouts
+4. List unresolved questions