# How a New Case Is Initialized in reverse‑skill: Complete PowerShell Bootstrap Guide

> Discover how reverse-skill initializes a new case with case-init.ps1. Learn how this PowerShell script orchestrates master-route.ps1 to create a structured work directory, validate scope, and enforce authentication.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-08-10

---

**`case-init.ps1` creates a structured work directory with validated scope, timeline, and workitems files by orchestrating `master-route.ps1`, enforcing the repository's authentication gate before any security testing ACT can execute.**

The `reverse-skill` repository implements a disciplined, file-driven workflow for security research and penetration testing. Every engagement begins with formal case initialization—a mandatory step that provisions the `work/<CaseName>` directory structure and validates operational parameters according to [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md). This guide examines the initialization pipeline implemented in `skills/scripts/case-init.ps1` and its dependencies.

## How `case-init.ps1` Bootstraps a Fresh Analysis Case

The initialization script serves as the single entry point for provisioning new engagements. It performs six sequential operations that transform a user hint into a governed workspace.

### 1. Resolve and Create the Working Directory

`case-init.ps1` delegates path resolution to an internal helper, `WorkRoot.ps1`, which locates the repository-wide *work* folder and creates the case-specific subdirectory:

```

work\<CaseName>\

```

This directory becomes the canonical location for all case artefacts. Subsequent scripts—including `case-guard.ps1` and `append-evidence.ps1`—depend on this predictable structure.

### 2. Validate the Case Name

Before any filesystem operations, `case-init.ps1` applies strict validation rules to prevent path traversal and filesystem pollution. The script rejects:

- Wildcard characters (`*`, `?`)
- Trailing whitespace
- Control characters

Invalid names trigger immediate termination with an explanatory error.

### 3. Invoke `master-route.ps1` for Primary Skill Routing

The script passes the user-supplied `-Hint` (a one-sentence task description) to `skills/scripts/master-route.ps1`. This router analyzes the hint and produces [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) containing:

- A **primary-skill** recommendation
- A basic timeline skeleton

This file feeds directly into the case artefacts created in step 4.

### 4. Populate Core Case Artefacts

`case-init.ps1` atomically writes three mandatory markdown files using `[System.IO.File]::WriteAllText` with UTF-8 encoding:

| File | Purpose | Source Contract |
|------|---------|---------------|
| [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) | Operational contract defining auth status, in-scope targets, network profile | [`skills/ops/scope-contract.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/scope-contract.md) |
| [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) | Placeholder for engagement milestones | Derived from [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) |
| [`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/workitems.md) | Empty list for tracking actionable tasks | Repository template |

The script copies [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) into the case folder before populating these files, ensuring the primary skill recommendation persists.

### 5. Apply the Authentication and Networking Gate

`case-init.ps1` implements the security gate mandated by [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md): no ACT (action) may execute until `auth.status=granted` and a valid `network_profile` exist.

**With explicit parameters:**

```powershell
-AuthGranted -TargetUrl "https://target.example" -NetworkProfile authorized_target_only

```

The script pre-fills [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) with:
- `auth.status: granted`
- `in_scope: <TargetUrl>`

**Without parameters:**

The script leaves placeholder values and prints a mandatory reminder:

```

1. Edit `scope.md` — set auth.status=granted and in_scope (or re-run with -AuthGranted -TargetUrl)
NEXT: fill scope.md auth + in_scope; then open PRIMARY SKILL.md

```

This mirrors the enforcement logic in `case-guard.ps1`, which validates [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) before permitting any ACT execution.

### 6. Finalize with Diagnostics

The script concludes by:

- Echoing the absolute path to `work\<CaseName>`
- Listing all generated artefacts
- Aborting with detailed error context if any step fails

## Practical Code Examples

### Basic Initialization

```powershell
powershell -NoProfile -ExecutionPolicy Bypass `
          -File skills/scripts/case-init.ps1 `
          -Hint "web pentest of corporate portal" `
          -CaseName "corp-web-2024"

```

This creates:
- `work\corp-web-2024\scope.md`
- `work\corp-web-2024\timeline.md`
- `work\corp-web-2024\workitems.md`

### Automated Pipeline Initialization

```powershell
powershell -File skills/scripts/case-init.ps1 `
          -Hint "internal API audit" `
          -CaseName "api-audit-jan" `
          -AuthGranted `
          -TargetUrl "https://api.internal.company" `
          -NetworkProfile authorized_target_only

```

Post-execution verification checklist:

1. Open `work\api-audit-jan\scope.md`
2. Confirm `auth.status: granted`
3. Validate `in_scope` matches `https://api.internal.company`
4. Review `PRIMARY SKILL.md` for recommended tooling

## Key Source Files and Their Roles

Understanding the initialization flow requires familiarity with these repository components:

- **`skills/scripts/case-init.ps1`** — Core bootstrap script; orchestrates directory creation, routing, and artefact generation
- **`skills/scripts/master-route.ps1`** — Generates initial skill routing and timeline data consumed by `case-init.ps1`
- **[`skills/ops/scope-contract.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/scope-contract.md)** — Specification governing valid [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) structure, including required fields for authentication status and network profile
- **[`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md)** — Mandates `case-init` execution before any ACT; defines the security gate enforced by `case-init.ps1` and `case-guard.ps1`
- **`skills/scripts/case-guard.ps1`** — Validates that [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) exists and contains `auth.status=granted` before permitting ACT execution

## Summary

The reverse-skill initialization pipeline guarantees reproducible, governed engagement setup:

- **`case-init.ps1`** is the mandatory entry point for all new cases
- The script creates a **structured `work/<CaseName>` directory** with three core artefacts: [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md), [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md), and [`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/workitems.md)
- **`master-route.ps1`** provides skill routing recommendations based on the `-Hint` parameter
- **Authentication gating** is enforced at initialization; cases without `auth.status=granted` cannot proceed to ACT execution
- All file writes are **atomic and UTF-8 encoded**, preventing corruption during concurrent access
- The implementation follows the contract defined in **[`skills/ops/scope-contract.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/scope-contract.md)** and the rules in **[`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md)**

## Frequently Asked Questions

### What happens if I skip `case-init.ps1` and try to run an ACT directly?

`case-guard.ps1` will block execution. According to [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md), every ACT must be preceded by a valid [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) with `auth.status=granted`. The guard script checks for this file and its required fields before allowing any action to proceed.

### Can I rename a case after initialization?

The repository does not provide a native rename operation. You must manually move the `work/<CaseName>` directory and update any internal references. Future iterations of `case-init.ps1` may add `-Rename` functionality, but this is not currently implemented.

### How does `master-route.ps1` determine the primary skill?

The router parses your `-Hint` string against embedded heuristics and produces [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) with a recommended skill category and initial timeline. This recommendation is advisory; you may override it manually in [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) before opening `PRIMARY SKILL.md`.

### What network profiles are valid for `-NetworkProfile`?

Valid values are defined in [`skills/ops/scope-contract.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/scope-contract.md). Common profiles include `authorized_target_only`, `corporate_lan`, and `airgapped`. The profile affects which network behaviors are permitted during ACT execution and is validated by `case-guard.ps1`.