skillpanel/maister/init

Initialize Maister Framework

Initialize .maister/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: maister:docs-operator) for all docs-manager operations, and Task tool for project-analyzer. Use the Skill tool only for standards-discover (Phase 8, last phase). The Task tool returns control to this skill after completion; the Skill tool does not.

Phase Configuration

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/.maister/docs/standards/ exists. If not, inform the user and stop — the specified project doesn't have maister standards initialized.
3. Store the resolved standards source path for use in Phases 4 and 5.

Check if .maister/ directory already exists.

If exists, use AskUserQuestion:

• Options: "Backup and reinitialize", "Update existing documentation", "Cancel"
• If "Backup": Create .maister.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 AskUserQuestion to confirm analysis accuracy. If corrections needed, collect them.

Step 3: Gather additional context via AskUserQuestion (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 AskUserQuestion (multi-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 (optional)

Smart defaults based on projectArchitectureType:

• Standard/Frontend-only/Backend-only: All selected
• Monorepo/Umbrella: Only "Tech Stack" 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/.maister/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 .maister/docs/standards/*/ for any existing custom categories to include.

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

• "Use smart defaults" → proceed with calculated defaults
• "Customize selection" → show multi-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: maister:docs-operator) with prompt:

"Initialize documentation structure. Standards selection: [array from Phase 4]. [If --standards-from was provided: Standards source path: [resolved path]/.maister/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.

Step 2 — Scaffold project config (Write tool, directly — not via docs-operator): if .maister/config.yml does not already exist, create it with the documented default so users have a discoverable place to toggle output. Do not overwrite an existing config.

# Maister project configuration.
# html_output — generate the operator dashboard (dashboard.html + dashboard-data.js,
# auto-opened in your browser) and the HTML companion reports (.html twins of spec,
# implementation plan, verification, and research/design outputs). Set to false for
# markdown-only runs. Markdown artifacts, their TL;DR summary blocks, and
# orchestrator-state.yml are produced regardless. Default: true.
html_output: true
 
# mockup_format — how UI mockups are rendered when a workflow generates them
# (development Phase 4, product-design Phase 7, or /maister:mockup-studio).
#   html  (default): rendered HTML/CSS via the visual companion (browser preview, saved as .html).
#   ascii          : terminal ASCII mockups via the ascii-mockup-generator agent (no Node/browser needed).
# Auto-falls back to ascii when Node.js is unavailable. Default: html.
mockup_format: html

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 selected → 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 .maister/docs/project/.

PHASE 7: Validate

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

"Regenerate INDEX.md to include all newly created project documentation. Then verify CLAUDE.md is properly integrated with .maister/docs/ documentation."

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

Step 2: Display comprehensive summary. Include any failure docs-operator reported.

• 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 /maister: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 .maister/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