init

name	init
description	Initialize Flowbit with intelligent project analysis and documentation generation
argument-hint	[--standards-from=PATH]

Initialize Flowbit

Initialize .flowbit/docs/ with intelligent project analysis and meaningful documentation generation based on actual codebase inspection.

NOTE: This skill invokes other skills and subagents at specific phases. Use the Task tool with docs-operator subagent (subagent_type: flowbit-docs-operator) for all docs-manager operations, and Task tool for project-analyzer. Use the Skill tool for standards-discover (Phase 8, last phase) and diagrams-mermaid (Phase 6 doc refinement). The Task tool returns control to this skill after completion; the Skill tool does not.

Phase Configuration

Phase	Subject	activeForm
1	Pre-flight checks	Running pre-flight checks
2	Analyze project codebase	Analyzing project codebase
3	Present findings & gather context	Gathering project context
4	Select standards to initialize	Selecting standards
5	Initialize documentation structure	Initializing documentation
6	Generate project documentation	Generating project documentation
7	Validate	Validating initialization
8	Discover coding standards	Discovering coding standards

Task Tracking: Before Phase 1, use TaskCreate for all phases (pending), then set sequential dependencies with TaskUpdate addBlockedBy. At each phase: TaskUpdate to in_progress → execute → TaskUpdate to completed. If skipped (e.g., user selects "Update existing"), mark skipped phases as completed with metadata: {skipped: true}.

---

PHASE 1: Pre-flight Checks

If --standards-from=PATH is provided:

1. Resolve the path (absolute or relative to current working directory)
2. Check if PATH/.flowbit/docs/standards/ exists. If not, inform the user and stop — the specified project doesn't have flowbit standards initialized.
3. Store the resolved standards source path for use in Phases 4 and 5.

Check if .flowbit/ directory already exists.

If exists, use ask_user:

• Options: "Backup and reinitialize", "Update existing documentation", "Cancel"
• If "Backup": Create .flowbit.backup-$(date +%Y%m%d-%H%M%S)/ using Bash tool
• If "Update": Skip to PHASE 6 (documentation generation only)
• If "Cancel": Stop execution

---

PHASE 2: Project Analysis

Invoke project-analyzer subagent via the Task tool.

Wait for completion. Store analysis results for use in Phases 3 and 6.

---

PHASE 3: Present Findings & Gather Context

Step 1: Present analysis results to the user (project type, primary language/framework, architecture, tech stack, conventions, strengths/opportunities).

Step 2: Use ask_user to confirm analysis accuracy. If corrections needed, collect them.

Step 3: Gather additional context via ask_user (adapt to project type):

1. Project name (if not obvious)
2. Project description (1-2 sentences)
3. Primary goals (adapt question to new/existing/legacy project)
4. Team context (optional)
5. Special requirements (optional)

Step 4: Ask which project documentation to generate using ask_user (sequential single-select):

• "Vision" — Project vision, goals, and purpose
• "Roadmap" — Development roadmap and planned features
• "Tech Stack" — Technology choices and rationale (ALWAYS selected, required)
• "Architecture" — System architecture and design patterns (ALWAYS selected, required)

Smart defaults based on projectArchitectureType:

• Standard/Frontend-only/Backend-only: All selected
• Monorepo/Umbrella: "Tech Stack" and "Architecture" selected

Store selections for Phase 6.

---

PHASE 4: Select Standards to Initialize

Before presenting options, explain to the user:

• What standards are: Coding standards are documented conventions and best practices (naming, error handling, testing patterns, etc.) that guide consistent development across the project.
• Starting point: If --standards-from was provided, standards come from the referenced project. Otherwise, the plugin includes generic built-in standards. Either way, they serve as a starting point and can be fully customized or extended later.

Determine available categories:

• If --standards-from was provided: Scan PATH/.flowbit/docs/standards/*/ to discover all available categories from the external project (may include custom categories beyond the baseline global/frontend/backend/testing).
• Otherwise: Use built-in baseline categories (global, frontend, backend, testing).

Calculate smart defaults based on analysis:

• Global: Always recommended (if available)
• Frontend: If frontend framework detected or projectArchitectureType includes frontend (if available)
• Backend: If backend framework detected or projectArchitectureType includes backend (if available)
• Testing: Always recommended (if available)

Also scan .flowbit/docs/standards/*/ for any existing custom categories to include.

Show smart defaults summary (noting the source: external project or built-in), then use ask_user:

• "Use smart defaults" → proceed with calculated defaults
• "Customize selection" → show sequential single-select with all discovered categories + "Add custom category" option

Custom categories: if user adds a new category, create the directory and include it in the selection.

Store selection for Phase 5.

---

PHASE 5: Initialize Documentation Structure

Invoke docs-operator subagent via Task tool (subagent_type: flowbit-docs-operator) with prompt:

"Initialize documentation structure. Standards selection: [array from Phase 4]. [If --standards-from was provided: Standards source path: [resolved path]/.flowbit/docs/standards/. Copy standards from this external path instead of built-in defaults.] Only copy selected standard categories. Do NOT copy project templates — only create the project/ directory. Project documentation will be generated in Phase 6 with real content from project analysis. Create placeholder sections in INDEX.md for skipped categories."

Wait for docs-operator to complete, then immediately proceed to Phase 6.

---

PHASE 6: Generate Project Documentation

IMPORTANT: Only generate docs selected in Phase 3.

For each selected doc type, read the corresponding reference template:

• Vision selected → Read references/vision-templates.md, select template by project type (new/existing/legacy)
• Roadmap selected → Read references/roadmap-templates.md, select template by project type
• Tech Stack (always) → Read references/tech-stack-template.md
• Architecture (always) → Read references/architecture-template.md

Fill templates using:

• Analysis report data (tech stack, age, structure)
• User-provided context from Phase 3 (goals, users, requirements)
• Auto-detected project characteristics

Write each file to .flowbit/docs/project/.

Diagram refinement (content-preserving, do NOT replace prose):

• If Architecture doc is selected and .flowbit/docs/project/architecture.md exists:

  1. Invoke Skill tool: flowbit-diagrams-mermaid
  2. Pass context from analysis + generated architecture content
  3. Add Mermaid sections that refine the document:
     • ## Visual Architecture Context (prefer C4Context or C4Container)
     • ## Component Communication Flow (prefer sequenceDiagram or flowchart)
  4. Keep existing architecture narrative intact; diagrams must supplement, not replace sections.

• If Tech Stack doc is selected and .flowbit/docs/project/tech-stack.md exists:

  1. Invoke Skill tool: flowbit-diagrams-mermaid
  2. Add one lightweight visual section (e.g., runtime/build dependency flow) only if context is sufficient
  3. If context is insufficient, keep text-only output and list missing details (no invented dependencies).

---

PHASE 7: Validate

Step 1: Invoke docs-operator subagent via Task tool (subagent_type: flowbit-docs-operator) with prompt:

"Regenerate INDEX.md to include all newly created project documentation. Then verify .github/copilot-instructions.md is properly integrated with .flowbit/docs/ documentation."

Wait for docs-operator to complete, then immediately continue with Step 2.

Step 2: Run validation checks:

• Verify INDEX.md exists
• Verify tech-stack.md exists (required)
• Verify architecture.md exists (required)
• Verify selected docs exist
• Verify selected standards directories exist
• Verify .github/copilot-instructions.md integration

Step 3: Display comprehensive summary:

• Project analysis results (type, language, framework, architecture)
• Structure created (tree with check marks for created items)
• Documentation status (which docs generated, which standards initialized)
• Key findings (strengths, opportunities)
• Next steps:
  1. Review generated documentation
  2. Customize for your team
  3. Start development with /flowbit-work
  4. Keep documentation current

---

PHASE 8: Discover Coding Standards

Invoke the standards-discover skill via Skill tool with --scope=full to automatically discover coding standards from the project's config files, source code patterns, documentation, and external sources.

"Run standards discovery with --scope=full. This is being invoked as part of project initialization."

The standards-discover skill handles its own user interaction (presenting findings by confidence tier, asking for approval). Let it run its full workflow — this is the last phase of init, so context handoff is fine here.

After completion, display a brief summary of how many standards were discovered and applied.

---

Error Handling Principles

• If .flowbit/docs/ creation fails: check permissions, suggest manual creation
• If project-analyzer fails: offer to proceed with manual input only
• If docs-manager fails: offer retry (max 2 attempts), then manual instructions
• Never auto-rollback — always ask user before destructive actions