How the `case-init` Scripts Manage Work Directory Structure and `scope.md` in Reverse-Skill

The case-init scripts automatically create a standardized work directory under work/<case>/ with evidence, notes, and report subfolders, then generate a YAML-style scope.md contract that records authentication status, network profile, in-scope assets, and a ready_for_act flag for downstream enforcement.

The case-init utilities—skills/scripts/case-init.sh for Linux/macOS/Kali and skills/scripts/case-init.ps1 for Windows—are the entry point for every reverse engineering engagement in the zhaoxuya520/reverse-skill framework. These scripts enforce consistent directory structure and scope documentation before any skill module executes.

Resolving Repository Roots and Project Context

The scripts first establish three critical path variables to anchor all subsequent operations:

• SKILLS_ROOT – the directory containing the scripts themselves
• PACKAGE_ROOT – resolved as SKILLS_ROOT/.. (two levels above the script location)
• PROJECT_ROOT – defaults to the current working directory, overridable via --project-root or --package-root

These calculations appear in case-init.sh at lines 47-58, ensuring the framework can locate skill modules and write case data to the correct location regardless of where the user invokes the script.

Determining and Validating the Case Name

If the user omits --case-name, the script constructs a slug from the --hint value, truncates it to prevent filesystem issues, and prefixes it with an ISO-style timestamp (lines 99-103). The validation logic (lines 104-114) enforces strict rules:

• 1-80 characters maximum
• Alphanumeric characters only
• No special characters, spaces, or control characters

This prevents path traversal vulnerabilities and ensures cross-platform compatibility.

Processing Presets and Building the Asset Inventory

The case-init scripts support preset profiles that configure multiple parameters simultaneously (lines 69-97):

Preset	Use Case	Auth Status	Network Profile
offline-sample	Local malware/samples	granted	offline
ctf-public	Public CTF challenges	granted	authorized_target_only
own-system	User-owned hardware	granted	air_gap or isolated_vlan

Assets are collected into an ASSETS array from three sources (lines 47-55):

• --target-url for remote hosts
• --sample for local files
• --in-scope-asset for explicit additions

If no assets are provided but the hint contains a URL, the host is extracted and added automatically (lines 56-58).

Deriving Network Constraints

The final network_mode is determined through a priority cascade (lines 60-79):

1. Explicit --network-profile if provided
2. Preset-derived profile based on authentication status
3. Default safe mode if assets exist but auth is pending

This ensures network isolation requirements are never accidentally relaxed.

Creating the Work Directory Structure

Upon successful validation, the script creates the canonical directory layout at <PROJECT_ROOT>/work/<CASE_NAME>/ (line 26):

work/<timestamp>-<case-name>/
├─ evidence/          # Malware samples, memory dumps, disk images

├─ notes/             # Analysis notebooks and scratch files

├─ report/            # Final deliverables and findings

├─ scope.md           # Authorization contract and constraints

├─ timeline.md        # Audit trail starting with initialization

├─ workitems.md       # Task tracking table

└─ README.md          # Human-readable case status and next steps

Generating the scope.md Contract

The scope.md file is the centerpiece of the case-init scripts' output. Built between lines 30-94 of case-init.sh, it contains a YAML-style header with these sections:

• meta – case name, timestamp, primary skill, analyst identification
• auth – status (granted, pending, denied), basis (legal document reference), and evidence_of_auth (file paths or ticket IDs)
• in_scope_assets – enumerated list of URLs, file hashes, IP ranges
• out_of_scope_assets – explicitly excluded systems
• network_profile – operational network constraints
• deliverables – expected output formats and deadlines
• constraints – time windows, no-fly zones, special handling requirements
• checklist – verification that auth, assets, and network profile are satisfied
• ready_for_act – boolean flag computed by validating checklist completion

The ready_for_act flag (lines 8-15, 17-22) implements critical safety logic: it returns false if authentication status is not granted or if the network profile conflicts with the asset types present.

Creating Ancillary Documentation Files

Three additional files support case workflow:

timeline.md

Records the initialization event with ready status and links back to scope.md (lines 96-108). This forms the audit trail required for incident response and legal proceedings.

workitems.md

Provides a starter Markdown table for tracking analysis tasks (lines 110-128):

| ID | Task | Skill | Status | Owner | Due |
|----|------|-------|--------|-------|-----|
| 1  | Static analysis of sample | reverse-apk | todo | | |

README.md

Conditionally generated based on ready_for_act (lines 31-43):

• If false: Instructions to complete scope.md and obtain proper authorization
• If true: Confirmation that downstream skills can be invoked

Example: Initializing an Offline Sample Case

bash skills/scripts/case-init.sh \
  --hint "apk reverse" \
  --case-name demo \
  --preset offline-sample \
  --sample ./app.apk

This creates work/20231120-123456-apk-reverse-demo/ with:

• auth.status: granted (preset)
• network_profile: offline
• assets containing the APK file path
• ready_for_act: true

Example: Initializing a CTF Public Challenge

bash skills/scripts/case-init.sh \
  --hint "ctf web" \
  --preset ctf-public \
  --target-url https://challenge.example

Resulting scope.md contains:

• auth.status: granted (CTF challenges are pre-authorized)
• network_profile: authorized_target_only
• Target URL in the assets list with host extraction

Integration with Downstream Enforcement

The scope.md contract is not merely documentation—it is machine-readable. According to the reverse-skill source code, case-guard.sh validates this file before any skill execution, checking that:

• The ready_for_act flag is true
• The current network mode matches the declared profile
• Assets referenced in skill commands appear in the in-scope list

Similarly, master-route.sh (invoked during initialization) reads scope.md to determine the appropriate primary skill based on asset types and network constraints.

Summary

• Root resolution: case-init.sh calculates PACKAGE_ROOT and PROJECT_ROOT to anchor all file operations
• Safe naming: Timestamps and slugified hints produce valid, unique directory names
• Preset system: Common engagement types pre-configure auth status and network isolation
• Asset collection: URLs, samples, and explicit assets merge into a validated inventory
• Directory layout: work/<case>/ with evidence/, notes/, report/ subfolders
• Contract generation: scope.md encodes authorization, constraints, and ready_for_act status
• Safety gates: Downstream scripts like case-guard.sh enforce scope compliance before skill execution

Frequently Asked Questions

What happens if I don't provide a --case-name?

The script generates one automatically by combining a timestamp with a slugified version of your --hint value, truncated to 80 characters (lines 99-103). For example, --hint "analyze banking trojan" might produce 20231120-143022-analyze-banking-tro.

Can I override the default project root directory?

Yes. Use --project-root /path/to/cases or --package-root to bind PROJECT_ROOT to the package installation directory. This is useful when running case-init.sh from arbitrary locations while keeping case data organized (lines 47-58).

Why does scope.md use YAML-style frontmatter?

The format allows both human readability and automated parsing by downstream scripts. case-guard.sh and skill modules extract specific fields like auth.status and network_profile without requiring a full Markdown parser, while analysts can edit the file in any text editor.

What prevents me from running skills against assets I haven't authorized?

The ready_for_act flag must be true, which requires auth.status: granted and compatible asset/network combinations. case-guard.sh validates this before skill execution. Additionally, the checklist in scope.md documents which authorization elements have been satisfied, creating an audit trail for compliance review.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}