# Upgrade Environment

> Audits an existing Claude Code environment against current best practices, interviews the user about pain points, and implements approved improvements -- including shape conversions (single <-> multi-area hub <-> undeclared siblings). Recommendations are tiered quick wins / medium / large so the user picks what to implement. Use when user says "upgrade environment", "improve my environment", "opt…

- **Type:** Skill
- **Install:** `agentstack add skill-popschlock-claude-harness-generator-upgrade-environment`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Popschlock](https://agentstack.voostack.com/s/popschlock)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Popschlock](https://github.com/Popschlock)
- **Source:** https://github.com/Popschlock/Claude-Harness-Generator/tree/main/.claude/skills/upgrade-environment

## Install

```sh
agentstack add skill-popschlock-claude-harness-generator-upgrade-environment
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

## Critical

This skill is a TRIGGER. It inventories the target environment and writes UPGRADE_CONTEXT.md, then returns control to the orchestrator. It does NOT run the analysis, interview, or implementation -- the orchestrator coordinates those steps.

## What this skill does

1. Get target path (offer current directory if it has `.claude/`)
2. Verify environment exists (must have `.claude/` + `CLAUDE.md`)
3. Quick inventory: count rules, agents, skills, check for Docs/ structure
4. Check for GENESIS.md and ARCHITECTURE.md (richer context if present)
5. Write `/Docs/Environment/UPGRADE_CONTEXT.md` with inventory + platform info
6. Return to orchestrator

## Steps

### Step 1: Get the target directory

Ask the user for the path to the environment to upgrade. If the current directory contains a `.claude/` directory and `CLAUDE.md`, offer to use it.

### Step 2: Verify environment exists

The target MUST have both:
- `.claude/` directory
- `CLAUDE.md` file

If either is missing, report "No complete Claude Code environment found at this path" and stop. An environment must exist before it can be upgraded.

### Step 3: Quick inventory

Count and list:
- Rule files: glob `.claude/rules/*.md` -- count and list names
- Agent files: glob `.claude/agents/*.md` -- count and list names
- Skill directories: glob `.claude/skills/*/SKILL.md` -- count and list names
- Docs structure: check for `Docs/index.md`, `Docs/GETTING_STARTED.md`, `Docs/_working/`
- Settings: check for `.claude/settings.json`, `.claude/settings.local.json`
- Hooks: check for `.claude/hooks.json` or hook entries in settings.json
- VCS ignore: check for `.gitignore`, `.p4ignore`

### Step 4: Check for GENESIS.md and ARCHITECTURE.md

Look for `/Docs/Environment/GENESIS.md` and `/Docs/Environment/ARCHITECTURE.md`. These provide richer context for the upgrade analysis but are not required (the environment may not have been created by the Harness Generator).

Also check for `/Docs/Environment/VALIDATION_REPORT.md` -- a recent validation gives the analyzer a head start.

### Step 4a: Detect hub shape

Apply these tests in order. First match wins.

**Test 1 -- declared hub**:
If `/Docs/Environment/HUB_GENESIS.md` exists, record `Shape: HUB`.
Read its work-area registry and for each listed area-slug record whether
`//Docs/Environment/GENESIS.md` and `ARCHITECTURE.md` exist
(registry-vs-disk drift).

**Test 2 -- single environment**:
If `/.claude/` AND `/CLAUDE.md` both exist, record `Shape: SINGLE`.
Do NOT look deeper. A single environment may have unrelated subfolders that
contain their own unrelated Claude setups (e.g., a vendored library with its
own CLAUDE.md), and those should not be treated as work areas.

**Test 3 -- undeclared hub**:
ALL of the following must hold:
- `/.claude/` does NOT exist at the root
- `/CLAUDE.md` does NOT exist at the root
- `/Docs/Environment/HUB_GENESIS.md` does NOT exist
- Two or more immediate subdirectories of `` each contain their own
  `.claude/` directory AND a `CLAUDE.md` file
- Those subdirectory environments are sibling peers (common parent is ``,
  not grandparent-and-below)

If all hold, record `Shape: HUB_LIKE_UNDECLARED` and list the qualifying
subfolders. Offer `Declare hub structure` in the upgrade recommendations.

**Test 4 -- empty target**:
If none of the above matches, report "No Claude Code environment found at this
path" and stop. Do not attempt to upgrade an empty directory.

### Why the tests are ordered this way

- Declared hubs (Test 1) are unambiguous -- HUB_GENESIS.md is the declaration.
- Single environments (Test 2) must be detected BEFORE undeclared-hub because a
  single env with noise in subfolders should stay single. Only match
  HUB_LIKE_UNDECLARED when there is NO env at the root.
- Two sibling envs is the minimum for "hub-like" -- one sibling is just a
  single env with an odd parent.
- Deeper nesting (e.g., `/a/b/c/.claude/`) is ignored; hubs are
  parent + immediate children only.

### Step 5: Create environment directory

Create `/Docs/Environment/` if it does not exist.

### Step 6: Write UPGRADE_CONTEXT.md

Write to `/Docs/Environment/UPGRADE_CONTEXT.md`:

```markdown
# Upgrade Context

Created: 

## Target
- Path: 
- Platform: 

## Inventory
- Rules:  ()
- Agents:  ()
- Skills:  ()
- Docs structure:  (index.md: yes|no, GETTING_STARTED: yes|no, _working: yes|no)
- Settings: settings.json , settings.local.json 
- Hooks:  ()
- VCS ignore: 

## Available Context
- GENESIS.md: 
- ARCHITECTURE.md: 
- HUB_GENESIS.md: 
- HUB_ARCHITECTURE.md: 
- VALIDATION_REPORT.md:  ()

## Shape
- Shape: 
- Work areas (hub only): 

## CLAUDE.md Stats
- Line count:  (hub: parent CLAUDE.md line count; per-area counts listed separately)
- Has first-run greeting: 
- Has routing reference: 

## Pipeline Status
- Stage: TRIGGER_COMPLETE
- Next: USER_INTERVIEW
```

### Step 7: Output summary

Report to the user:
- Environment found at target path
- Quick inventory summary (N rules, N agents, N skills)
- Whether GENESIS.md/ARCHITECTURE.md were found (richer analysis if present)
- "The upgrade analysis pipeline will now begin."

The orchestrator reads UPGRADE_CONTEXT.md and coordinates: user interview -> structural pre-check -> deep analysis -> recommendations -> implementation -> validation.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Popschlock](https://github.com/Popschlock)
- **Source:** [Popschlock/Claude-Harness-Generator](https://github.com/Popschlock/Claude-Harness-Generator)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-popschlock-claude-harness-generator-upgrade-environment
- Seller: https://agentstack.voostack.com/s/popschlock
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.