Use when starting hyperflow in a new project, refreshing the .hyperflow/ cache, or installing auto-detection shims (AGENTS.md, CLAUDE.md). One-shot project setup; does not start the spec → scope → dispatch chain.
Trigger with /hyperflow:scaffold, "init hyperflow", "set up hyperflow", "refresh hyperflow", "install hyperflow shims".
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Use when starting hyperflow in a new project, refreshing the .hyperflow/ cache, or installing auto-detection shims (AGENTS.md, CLAUDE.md). One-shot project setup; does not start the spec → scope → dispatch chain.
Trigger with /hyperflow:scaffold, "init hyperflow", "set up hyperflow", "refresh hyperflow", "install hyperflow shims".
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 plan → dispatch chain — invoke /hyperflow:plan 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):
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.)
Write .hyperflow/.version (the current plugin version from skills/hyperflow/VERSION) so the cache is stamped current. The session-start migrator () reads this marker on later sessions and brings an older cache forward when the plugin version moves — a missing/older marker triggers an idempotent, additive migration (new memory files, refreshed doctrine copy).
scripts/migrate-cache.py
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.
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 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 -->.
Do not stub index.md. It is derived — scripts/memory-index.py writes it from the category files at every session start. A hand-written stub is overwritten on the next run.
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, CLAUDE.md, and provider-specific shims.
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:plan.
/hyperflow:scaffold is one-shot project setup. It analyzes the codebase via 6 parallel searchers, builds the .hyperflow/ cache (profile, architecture, conventions, dependencies, testing, git-workflow), seeds the memory skeleton, and optionally writes detection shims (CLAUDE.md, AGENTS.md, Grok rules, Antigravity workflows). Does not start the plan → dispatch chain — invoke /hyperflow:plan 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.
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.
If present, recompute SHA256 checksums and refresh only stale files.
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 decisions.md, pitfalls.md, patterns.md, conventions.md stubs if absent. index.md and .checksums are derived — leave them to scripts/memory-index.py.
Migrate matching entries from legacy ~/.claude/hyperflow-memory.md if found.
Offer scripts/setup-detection.sh --tools all to write CLAUDE.md, AGENTS.md, and Grok/Antigravity shims when those tools are selected.
Print summary of created / skipped / migrated artifacts.
Output
See the summary block under 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 overwritten if content exists — preserves accumulated learnings
Scaffold does not create these; the session-start hook rebuilds them from the category files on every run.
session-context.md
Populated by hooks/session-start (NOT scaffold)
Scaffold does not create this file; the session-start hook generates it at session open by concatenating profile.md, architecture.md, and conventions.md. Lean workers reference this bundle (Pattern L3).
Error Handling
Failure
Behavior
Not a git repo
Skip git-workflow.md searcher; print (skipped — no git) in summary.
Some searchers fail
Mark the failing files with (partial) in profile.md; continue. Other 5 sources still produce valid output.
.hyperflow/ exists but .checksums missing
Treat all tracked configs as stale; refresh everything.
~/.claude/hyperflow-memory.md malformed
Skip migration; print Migration skipped — legacy file parse failed at line N. Original file untouched.
setup-detection.sh missing or non-executable
Print Detection shims skipped — scripts/setup-detection.sh not runnable. Initialization still succeeds.
.gitignore write blocked
Print warning and the suggested line to add manually; continue.
Examples
Fresh project
/hyperflow:scaffold
Searcher — analyzing tech stack
Searcher — mapping folder structure
Searcher — extracting conventions
Searcher — scanning dependencies
Searcher — auditing test setup
Searcher — reading git workflow
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
Note .hyperflow/memory/session-context.md — will be populated by hooks/session-start on next session
Created .gitignore entry — .hyperflow/
Shims CLAUDE.md, AGENTS.md
Memory skeleton populated — workers will use lean prompts by default.
