Scaffold

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 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):

See 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.)
• Write .hyperflow/.version (the current plugin version from skills/hyperflow/VERSION) so the cache is stamped current. The session-start migrator (scripts/migrate-cache.py) 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).
• 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 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.

Supported tools: claude-code (CLAUDE.md), opencode / agents / codex / cursor (AGENTS.md), antigravity (AGENTS.md + .agent/workflows/), grok (AGENTS.md + .grok/rules/hyperflow.md), all (every tool).

Flags — --tools <all|claude-code|opencode|agents|codex|cursor|antigravity|grok>, --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:plan.

Doctrine

Full rules in DOCTRINE.md. Output style in output-style.md.