Setup Skill

Purpose

Bootstrap the gener8v pipeline in a project. This skill creates the .gener8v/ directory structure, installs the shared conventions, generates the initial pipeline state file, and patches the project's CLAUDE.md with a short set of pipeline directives. After setup, the pipeline's state is in front of every session — mechanically, through the plugin's SessionStart hook when the plugin is installed, or through /orchestrate when it is not — and code changes flow through Delivery on tickets.

When to Use

Use this skill when:

• Starting a new project that will use the gener8v pipeline
• Onboarding an existing project to the pipeline for the first time
• The project has no .gener8v/prd.md and no ## gener8v Pipeline section in CLAUDE.md
• The user says "set up gener8v" or "initialize the pipeline"

Do not use this skill when:

• .gener8v/prd.md already exists and the question is what to do next — use the Orchestrate skill. Re-running Setup there after a plugin upgrade is still right: it refreshes only CONVENTIONS.md, the CLAUDE.md section and missing directories. (A .gener8v/ directory holding only sweeps/ or flows/ is not an onboarded project; Setup is the right call and keeps those standalone artifacts.)
• The user wants to start building immediately — run Planning (greenfield) or Brownfield (existing code) directly; each creates what it needs.

Input

Source: The project root directory Read from:

• CLAUDE.md in the project root (if it exists)
• .gener8v/ (to see what already exists)
• ${CLAUDE_SKILL_DIR}/references/conventions.md — resolves under both the plugin and a copied install
• The plugin's scripts/gener8v-state.py (plugin install only)

Expects: A project directory. May or may not have existing code, documentation, or a CLAUDE.md.

Output

Produces:

1. .gener8v/ directory structure (9 subdirectories, including changes/ — the home of every change set)
2. .gener8v/CONVENTIONS.md — the shared rules every skill reads (copied unchanged from this skill's references/conventions.md)
3. .gener8v/pipeline-state.yaml — generated by scripts/gener8v-state.py, or written by hand in the fallback format below when the script is unavailable
4. CLAUDE.md with a ## gener8v Pipeline section (created, appended, or replaced in place)

Not produced by Setup: .gener8v/runs.jsonl. The plugin's hooks append one line to it at each session start, artifact write and state regeneration; the model never writes it, and scripts/gener8v-state.py metrics reads it for session counts. Setup does not create it — under a copied install there are no hooks, so the file never appears.

Process

1. Check Existing State: Look for .gener8v/prd.md and for a ## gener8v Pipeline section in CLAUDE.md. If prd.md exists the project is already on the pipeline: refresh only what Setup owns — steps 2, 3 and 5 (missing directories, CONVENTIONS.md, the CLAUDE.md section) — leave every artifact alone, then recommend /orchestrate. Note any standalone artifacts already present (sweeps/, flows/, reviews/*-assessment.md) — they are kept, never moved. A legacy layout (top-level ticket, delivery and per-ticket review directories) is likewise left where it is; Orchestrate recommends the one-time move to changes/initial/, and Setup never scaffolds those legacy directories.
2. Create Directory Structure: Create any of these that do not exist (existing directories and files are left untouched):

   .gener8v/
     specifications/   # living: one per capability area, amended in place
     constraints/
     dependencies/
     technical-design/
     changes/          # one change set per initiative: changes/<change-slug>/{change.md,tickets,delivery,reviews}
     reviews/          # system-level assessments only (OWASP, OWASP LLM, architecture)
     audits/
     flows/            # Flow Mapping
     sweeps/           # Defect Sweep

   changes/ is created empty. Planning creates each changes/<change-slug>/ when it opens a change, and the per-change tickets, delivery records and reviews live inside it — there is no top-level home for them.
3. Install Conventions: Copy ${CLAUDE_SKILL_DIR}/references/conventions.md to .gener8v/CONVENTIONS.md. If the file already exists, replace it — it is owned by Setup and versioned with the plugin.
4. Generate Pipeline State: Run the deterministic generator when it is available:

   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/gener8v-state.py state

   Under a copied install the script is not present and the command fails with No such file; write the fallback file instead:

   # gener8v pipeline state — GENERATED; do not edit by hand.
   # Regenerate with scripts/gener8v-state.py (plugin) or /orchestrate.
   generated: "[ISO 8601 timestamp]"
   schema_version: 4
   stage: not_started
   prd_title: null
   system_context: false
   has_source: [true or false — whether the root holds source code]
   active_changes: []
   approvals_pending: 0
   capability_areas: {}
   changes: {}
   cross_cutting: {}
   next_steps:
     - skill: planning
       target: user prompt
       reason: "No PRD yet — or run brownfield for an existing codebase"
   warnings: []
   totals: {}

5. Patch CLAUDE.md: If CLAUDE.md does not exist, create it containing only the directives below. If it exists and has no ## gener8v Pipeline heading, append the directives. If it already has that heading, replace everything from the heading up to the next ## heading (or end of file) with the current directives — never duplicate the section, never ask. Leave every other line of the file exactly as it was.
6. Present Summary: Say what was created, replaced, and left alone, then recommend the entry point:
   • Greenfield (no source code yet): /planning
   • Brownfield (existing code): /brownfield
   • Mention the invocation form that applies: /planning under a copied install, /gener8v:planning under the plugin.

CLAUDE.md Directives

Write this section (verbatim, apart from nothing) into the project's CLAUDE.md:

## gener8v Pipeline

This project uses the [gener8v pipeline](https://github.com/gener8v/gener8v.claude-skills). Skills are `/<skill>` under a copied install or `/gener8v:<skill>` under the plugin; this file uses the short form. The rules every skill follows are in `.gener8v/CONVENTIONS.md`.

- **Where things stand.** `.gener8v/pipeline-state.yaml` is generated from the artifacts — never hand-edit it. With the plugin installed a SessionStart hook puts the current state and next steps in front of every session; without it, run `/orchestrate` at session start and after any pipeline skill.
- **Who writes code.** Delivery writes source, on a ticket, after an approved plan. Brownfield adds `@spec` annotations only. Reviews change code only during interactive resolution, with approval, and record it in the delivery record. Anything else in source is a trivial fix (typo, formatting, config) or it becomes a ticket.
- **Traceability.** Every function, class or handler that implements a requirement carries `@spec <PREFIX>-REQ-XXX` on the line above it. Preserve and update annotations when code moves. `grep -rn "@spec"` audits coverage.
- **Artifacts and IDs.** Everything the pipeline produces lives in `.gener8v/` at the root you work from — a single repository or a workspace holding several, with every code path root-relative — and is written by the skill that owns it. Requirement, constraint, decision and ticket IDs are append-only — never renumber; mark removed items Withdrawn.
- **Changes.** Work is organised in changes under `.gener8v/changes/<slug>/`; living specifications are amended, never regenerated.
- **Scale.** 1–2 capability areas: Planning → Specification → Ticket Breakdown → Delivery → Reviews. 3–5: add Constraints, Dependencies, Technical Design. 6+: parallel specification passes and sub-pipelines. Depth follows correctness risk (data integrity, tenant isolation, security), not just area count.

Principles

Non-Destructive

Never change CLAUDE.md content outside the ## gener8v Pipeline section, never delete existing .gener8v/ files. The one thing Setup owns and may overwrite is that section and CONVENTIONS.md.

Deterministic Idempotence

Running Setup twice yields the same files. The section is replaced in place rather than appended, the state file is regenerated rather than re-initialised, directories are created only if missing. There is nothing to ask the user.

Prose Is Not Enforcement

The directives tell the model what the pipeline expects. What is actually enforced comes from the plugin's hooks (hooks/hooks.json): state injected at session start, pipeline-state.yaml protected from hand edits, the state regenerated after every artifact write, a reminder when source is edited with no delivery in progress, and runs.jsonl appended at each session start, artifact write and state regeneration. Setup names both so a reader knows which is which.

Immediate Value

After setup, the user knows exactly what to run next, in the invocation form that applies to their install.

Example

Input

A project with an existing CLAUDE.md containing coding conventions and a stale ## gener8v Pipeline section from an earlier version.

Output

Setup complete:

  Created:
  - .gener8v/changes/, .gener8v/flows/, .gener8v/sweeps/ (6 other directories already existed)
  - .gener8v/CONVENTIONS.md
  - .gener8v/pipeline-state.yaml (generated: stage not_started)

  Replaced:
  - CLAUDE.md ## gener8v Pipeline section (everything else untouched)

  Next:
  - This project has source code and no .gener8v/prd.md. Run /gener8v:brownfield to map it into the pipeline.

Troubleshooting

• The state command fails with No such file. A copied install — the skill was invoked as /setup, not /gener8v:setup. ${CLAUDE_PLUGIN_ROOT} is substituted only for plugin skills, so the path collapses to /scripts/gener8v-state.py. Write the fallback file from step 4; from then on Orchestrate keeps the state file by hand.
• The state command fails with python3: command not found under the plugin. Install Python 3.8 or later and re-run step 4. The plugin's SessionStart and PostToolUse hooks call python3 as well and exit silently without it, so nothing regenerates the state until it is installed.
• Setup refreshed only the conventions and recommended Orchestrate. .gener8v/prd.md exists: the project is already on the pipeline, so step 1 limits the run to what Setup owns. That is the intended outcome — it is how a plugin upgrade reaches CONVENTIONS.md — not an error.
• Local edits to the ## gener8v Pipeline section are gone after a re-run. Step 5 replaces the section wholesale, by design. Recover the lines from git and keep them under a heading of their own, outside the section.
• Both /setup and /gener8v:setup are listed. A copied install lingers beside the plugin; the copy shadows the plugin's skills and never updates. scripts/check-install.sh in the plugin lists each lingering directory — move them aside (README: Upgrading from a copied install).

Integration with Other Skills

Upstream:

• None — this is the first skill to run in any project

Downstream:

• Planning / Brownfield: the entry points Setup recommends
• Orchestrate: reads the state file Setup generates
• Every skill: reads .gener8v/CONVENTIONS.md

Revisions

• Re-run Setup after upgrading the plugin: it refreshes CONVENTIONS.md, the CLAUDE.md section and any newly scaffolded directories without touching artifacts
• If the directives are customised locally, keep the customisation outside the ## gener8v Pipeline section — Setup replaces that section wholesale

Notes

• .gener8v/ should be committed so pipeline artifacts are shared across the team. pipeline-state.yaml is derived; committing it is optional — the hook regenerates it on every session start
• runs.jsonl is derived too. The hooks append it (session start, artifact writes, state regeneration); no skill and no person writes it, and scripts/gener8v-state.py metrics reads it for session counts. Committing it is optional; without the plugin's hooks it never exists
• Under the plugin install, ${CLAUDE_PLUGIN_ROOT} resolves to the plugin directory and scripts/gener8v-state.py is available; under a copied install only skills/ exist and Orchestrate maintains the state file by hand
• scripts/check-install.sh (plugin) reports drift between the repository and a copied ~/.claude/skills/ install