scaffold

What this skill does

# Scaffold

One-shot project setup. Analyzes the codebase, builds the `.hyperflow/` cache, seeds the memory skeleton, and optionally installs detection shims for other AI tools. Does not start the spec → scope → dispatch chain — invoke `/hyperflow:spec` (or `/hyperflow:scope`) when you're ready for that.

## Step 1 — Analysis Cache

Check for `.hyperflow/` at project root.

**If absent — dispatch parallel searchers (single message, six Agent calls):**

| Label | File generated | Discovers |
|---|---|---|
| `Searcher — analyzing tech stack` | `profile.md` | Name, language, framework, build commands |
| `Searcher — mapping folder structure` | `architecture.md` | Dirs, patterns, routing, data flow |
| `Searcher — extracting conventions` | `conventions.md` | Naming, style, linting rules |
| `Searcher — scanning dependencies` | `dependencies.md` | UI lib, state, data fetching, DB, auth |
| `Searcher — auditing test setup` | `testing.md` | Runner, E2E, patterns, commands |
| `Searcher — reading git workflow` | `git-workflow.md` | Branches, commits, CI/CD, PR conventions |

See [project-analysis.md](references/project-analysis.md) for what each file captures.

**If present — staleness check:**
Compute SHA256 of tracked config files, compare against `.hyperflow/.checksums`. Refresh only stale files. Print `Refreshing — <comma-separated list of stale files>`.

**After analysis:**
- Write `.hyperflow/.checksums` (SHA256 of `package.json`, `tsconfig.json`, eslint/biome config, etc.)
- Append to `.gitignore` if `.hyperflow/` is not already excluded

## Step 2 — Memory Skeleton

Create `.hyperflow/memory/` if absent:

```
.hyperflow/memory/
├── doctrine.md          ← copied from skills/hyperflow/DOCTRINE.md
├── index.md
├── learnings.md         ← empty stub (populated by /hyperflow:dispatch wrap-up)
├── decisions.md
├── pitfalls.md
├── patterns.md
├── conventions.md
├── session-context.md   ← [populated by session-start hook, NOT by scaffold]
└── archive/.gitkeep
```

**session-context.md — populated by the session-start hook, not scaffold:**
Scaffold creates the empty `.hyperflow/memory/` directory; it does NOT write `session-context.md`. That file is generated at the start of each Claude Code session by `hooks/session-start`, which concatenates `.hyperflow/profile.md`, `architecture.md`, and `conventions.md` into a single bundled file. This enables Pattern L3 (session-cached context): lean workers read one bundled file instead of three separate source files.

**Limit:** mid-session changes to `profile.md`, `architecture.md`, or `conventions.md` won't propagate to `session-context.md` until the next session-start. Workers can still `Read` the source files directly if they suspect staleness.

**doctrine.md generation (idempotent):**
- Source: `skills/hyperflow/DOCTRINE.md` (canonical orchestration rules)
- If `.hyperflow/memory/doctrine.md` is absent — copy it.
- If it already exists — compare modification timestamps (or SHA256) against the source. If the source is newer, re-copy. If up-to-date, skip and print `doctrine.md — checksum match`.
- This enables Pattern P5 (lean worker prompts): workers `Read` doctrine on demand instead of receiving it inlined in every prompt.

**learnings.md (idempotent):**
- If absent — create as an empty stub with a single heading `# Learnings` and the line `<!-- populated by /hyperflow:dispatch wrap-up -->`.
- If it already exists with content — do NOT overwrite. Accumulated learnings from prior runs must be preserved across refreshes.

**Other stubs** — if any of `index.md`, `decisions.md`, `pitfalls.md`, `patterns.md`, `conventions.md` are absent, create them as an empty stub: one H1 matching the filename (title-cased) and the line `<!-- to be populated by future runs -->`.

**Lean prompt note:** scaffold has now populated the memory skeleton. Run `/hyperflow:dispatch` and workers will use `skills/hyperflow/worker-prompt-lean.md` by default; pass `--thorough` to fall back to the full inlined template.

**Migration:** If `~/.claude/hyperflow-memory.md` exists, migrate entries matching the current project path into the appropriate memory files. Tag migrated entries `[migrated]`.

## Step 3 — Detection Shims

Offer to run `scripts/setup-detection.sh --tools all` to generate AGENTS.md and CLAUDE.md.

Supported tools: `claude-code` (writes CLAUDE.md), `opencode` / `agents` (writes AGENTS.md), `all` (both).

Flags — `--tools <all|claude-code|opencode|agents>`, `--force`, `--dry-run`.

Default — `--tools all`. Ask once via `AskUserQuestion` if the user wants to skip any tool.

## Step 4 — Summary

Print what was created, skipped, and migrated (elegant style, no icons):

```
Hyperflow init complete
  Created   .hyperflow/{profile,architecture,conventions,dependencies,testing,git-workflow}.md
  Created   .hyperflow/.checksums
  Created   .hyperflow/memory/doctrine.md — copied from skills/hyperflow/DOCTRINE.md
  Created   .hyperflow/memory/{index,learnings,decisions,pitfalls,patterns,conventions}.md
  Created   .hyperflow/memory/session-context.md — populated by hooks/session-start (not scaffold)
  Skipped   .gitignore entry — already present
  Migrated  3 entries from ~/.claude/hyperflow-memory.md
  Shims     AGENTS.md, CLAUDE.md

Memory skeleton populated — workers will use lean prompts (skills/hyperflow/worker-prompt-lean.md) by default.
Pass --thorough to /hyperflow:dispatch to fall back to the full inlined template.
```

## Hand-off

This skill **does not** auto-chain. Init is project setup, not feature work. When the user wants to start a feature, they invoke `/hyperflow:spec` (for ambiguous scope) or `/hyperflow:scope` (for clear specs).

## Doctrine

Full rules in [DOCTRINE.md](references/DOCTRINE.md). Output style in [output-style.md](references/output-style.md).

## Overview

`/hyperflow:scaffold` is one-shot project setup. It analyzes the codebase via 6 parallel Sonnet searchers, builds the `.hyperflow/` cache (profile, architecture, conventions, dependencies, testing, git-workflow), seeds the memory skeleton, and optionally writes detection shims (CLAUDE.md for Claude Code, AGENTS.md for OpenCode). Does not start the spec → scope → dispatch chain — invoke `/hyperflow:spec` (ambiguous scope) or `/hyperflow:scope` (clear spec) when ready.

## Prerequisites

- Git repository (recommended for tag detection + git-workflow analysis; degrades gracefully if absent).
- Write access to the project root for `.hyperflow/` creation.
- For migration only: existing `~/.claude/hyperflow-memory.md` from a prior global install.

## Instructions

Numbered steps are in [Step 1 — Analysis Cache](#step-1--analysis-cache) through [Step 4 — Summary](#step-4--summary) above. Summary:

1. Check for `.hyperflow/` at project root; if absent, dispatch 6 parallel searchers (single message) to produce profile.md, architecture.md, conventions.md, dependencies.md, testing.md, git-workflow.md.
2. If present, recompute SHA256 checksums and refresh only stale files.
3. Create `.hyperflow/memory/` skeleton: copy `skills/hyperflow/DOCTRINE.md` → `doctrine.md` (idempotent — re-copy only if source is newer); create `learnings.md` empty stub (skip if content exists); create `index.md`, `decisions.md`, `pitfalls.md`, `patterns.md`, `conventions.md` stubs if absent.
4. Migrate matching entries from legacy `~/.claude/hyperflow-memory.md` if found.
5. Offer `scripts/setup-detection.sh --tools all` to write CLAUDE.md + AGENTS.md.
6. Print summary of created / skipped / migrated artifacts.

## Output

See the summary block under [Step 4 — Summary](#step-4--summary) above. Format: plain English, em-dash separator, sections for Created / Skipped / Migrated / Shims. No icons.

Step 2 generates the following files under `.hyperflow/memory/`:

| File | Source | Idempotence |
|---|---|---|
| `doctrine.md` | Copied from `skills/hyperflow/DOCTRINE.md` | Re-copied if source is newer; skipped if checksum matches |
| `learnings.md` | Empty stub (`# Learnings` heading) | Never overw