catlog22/maestro-init

<bootstrap_mode> This skill initializes protected project state before a Session exists. It MUST NOT call maestro run create; bootstrap files remain owned by their protected stores. </bootstrap_mode>

<purpose> Initialize project: detect state, create .workflow/ with project.md, state.json, config.json. Entry point; downstream: step roadmap or step brainstorm. </purpose>

<deferred_reading>

• project.md — read when generating project description
• state.json — read when creating initial state
• config.json — read when creating workflow configuration

</deferred_reading>

<context> $ARGUMENTS — none for interactive mode, or -y with @file reference for auto mode.

Flags:

| Flag | Effect | Default | |------|--------|---------| | -y / --yes | Automatic mode. After config questions, runs research without further interaction. Expects idea document via @ reference. | false | | --from <source> | Load upstream context package (brainstorm:ID, @file, or path). Consumes context-package.json to pre-fill project vision, goals, constraints, and terminology. Skips interactive questioning. Alias: --from-brainstorm | — |

Load project state if exists: Check for .workflow/state.json -- loads context if project already initialized.

Output boundary: ALL file writes MUST target .workflow/ (project.md, state.json, config.json, specs/) only. NEVER modify source code or files outside .workflow/. </context>

<invariants>

1. Idempotent init — re-running init on an already-initialized project MUST detect existing .workflow/ and warn (E002); NEVER silently overwrite existing state
2. Scope guard — init MUST only make initialization decisions; NEVER prejudge roadmap structure, plan scope, or implementation details
3. All artifacts required — init MUST NOT report completion until project.md, state.json, and config.json all exist; missing artifacts MUST be created before exit
4. Template-driven — deferred templates (project.md, state.json, config.json) MUST be read from ~/.maestro/templates/ and customized; NEVER generate from scratch without template
5. Interview writes back — all interactive decisions MUST be written to project.md/config.json before proceeding to research or completion; NEVER leave decisions unrecorded

</invariants>

<interview_protocol> Follows @~/.maestro/workflows/interview-mechanics.md standard.

Interaction mode: convergent menu-driven Decision tree (strict order): project type (greenfield / existing codebase onboarding) → tech stack detection and confirmation → directory structure preferences → initial configuration (specs categories, wiki bootstrap) Scope guard: only init decisions; do not prejudge roadmap structure or plan scope Writeback target: project.md (project description) + config.json (settings) + state.json (initial state) Additional skip conditions: --from source (upstream context pre-fills decisions) Exit condition: all configuration questions settled → proceed to workflow execution </interview_protocol>

<execution>

Phase Gates (MANDATORY, BLOCKING)

GATE 1: Pre-flight → Interview

• REQUIRED: .workflow/ existence check completed.
• REQUIRED: --from source validated (if provided).
• BLOCKED if: E002 (greenfield conflict with existing .workflow/) unresolved.

GATE 2: Interview → Research

• REQUIRED: All interview decisions recorded in project.md and config.json.
• REQUIRED: .workflow/ directory created with initial structure.
• BLOCKED if: interview decisions not yet written to files.

GATE 3: Research → Completion

• REQUIRED: All 3 required artifacts exist (project.md, state.json, config.json).
• REQUIRED: .workflow/specs/ initialized.
• BLOCKED if: any artifact missing — write it before reporting completion.

Pre-flight

1. Check if .workflow/ already exists — if so, load state and warn (E002 for greenfield conflicts)
2. Validate --from source is accessible if provided

Follow '~/.maestro/workflows/init.md' completely.

Artifact Verification (before completion)

REQUIRED_ARTIFACTS = [
  ".workflow/project.md",    // Core Value, Requirements, Key Decisions
  ".workflow/state.json",    // artifacts[], initialized to idle state
  ".workflow/config.json"    // Workflow configuration
]

If any artifact is missing: DO NOT report completion. Write the missing file first. </execution>

<completion>

Standalone report

=== WORKFLOW INITIALIZED ===
Project: {project_name}
State:   .workflow/state.json (active)

Created:
  .workflow/project.md
  .workflow/state.json
  .workflow/config.json
  .workflow/specs/

Ralph-invoked completion

End the step through the v3 Run lifecycle (no text block output):

maestro run complete {run_id} --session {session_id} --participant {participant_id} --actor {actor_id} --request-id {request_id} --reason "<reason>" --expected-orchestration-revision {orchestration_revision} --expected-run-revision {run_revision} --verdict {VERDICT} [--summary "<summary>"] --advance --json

(run-id 由 birth packet 提供 — 自动解析当前 running 步)

Verdicts (v3 surface):

• done — Normal completion
• done_with_concerns — Completed with concerns; pass --summary and put concerns in report.md frontmatter
• needs-retry / blocked — handled by maestro run transition {run_id} failed|blocked ... or maestro run cancel {run_id} ...; the orchestrator retries via a later fenced run next

Next-step routing

| Condition | Suggestion | |-----------|-----------| | Roadmap needed (default light) | step roadmap — open a v3 Session and dispatch: maestro session open "<goal>" --id YYYYMMDD-roadmap-{topic} --chain roadmap --participant {p} --actor {a} --request-id {r} --reason "<reason>" --json → fenced maestro run next --session {session_id} ... --json (or route via /maestro-next) |

Note: roadmap step is responsible for creating state.json.sessions[] entries and setting the first active_session_id. | Full spec package | step blueprint — open a v3 Session (maestro session open "<goal>" --id YYYYMMDD-blueprint-{topic} --chain blueprint ... --json → fenced maestro run next), or route via /maestro-next | | Explore ideas first | step brainstorm — open a v3 Session (maestro session open "<goal>" --id YYYYMMDD-brainstorm-{topic} --chain brainstorm ... --json → fenced maestro run next), or route via /maestro-next | | Quick ad-hoc task | /maestro-companion "{goal}" | </completion>

<error_codes> | Code | Severity | Condition | Recovery | |------|----------|-----------|----------| | E001 | error | No arguments provided when -y requires @ reference | Check arguments format, re-run with correct input | | E002 | error | .workflow/ already exists (greenfield init) | Use --from to import existing state, or remove .workflow/ to start fresh | | E003 | error | Context source not found (--from / --from-brainstorm) | Check arguments format, re-run with correct input | | E004 | error | Template file missing in ~/.maestro/templates/ | Run maestro-update to restore templates | | E005 | warning | .workflow/ already exists (existing codebase onboarding) | Merge with existing state or overwrite; user chooses via request_user_input | | W001 | warning | Research agent failed, continuing with partial results | Retry research or proceed with partial results | </error_codes>

<success_criteria>

• ] .workflow/project.md created with Core Value, Requirements (Validated/Active/Out of Scope), Key Decisions
• ] .workflow/state.json created with artifacts] array and empty sessions] array, initialized to idle state
• ] .workflow/config.json created with workflow / execution / git / gates / codebase / guard / collab / specInjection / dashboard segments
• ] .workflow/specs/ initialized with convention files
• ] All interview decisions written to project.md / config.json before proceeding
• ] Research completed (if enabled) — parallel agents spawned with results merged
• ] Next-step routing displayed in completion report

</success_criteria>