From maister
Orchestrates development tasks that modify code—bug fixes, enhancements, new features—with adaptive phases for codebase analysis, specs, planning, implementation, and TDD testing.
npx claudepluginhub skillpanel/maister --plugin maisterThis skill uses the workspace's default tool permissions.
Unified workflow for all development tasks — bug fixes, enhancements, and new features. Phases activate based on context and analysis findings, not predetermined task types.
Orchestrates all code-modifying development tasks like bug fixes, enhancements, and new features using adaptive phases for analysis, specs, TDD, implementation, and verification.
Drives AI coding agents through gated Spec → Plan → Build → Test → Review → Ship workflow for non-trivial features, refactors, or multi-file projects.
Initiates tasks by interviewing user for requirements, setting up git-wt worktrees or branches, checking tools like direnv/dotenvx, and creating plans for review.
Share bugs, ideas, or general feedback.
Unified workflow for all development tasks — bug fixes, enhancements, and new features. Phases activate based on context and analysis findings, not predetermined task types.
BEFORE executing any phase, you MUST complete these steps:
Read the framework reference file NOW using the Read tool:
../orchestrator-framework/references/orchestrator-patterns.md - Delegation rules, interactive mode, state schema, initialization, context passing, issue resolutionIf argument is a research folder path (matches .maister/tasks/research/*):
research_context.research_questionresearch_reference in state automaticallyIf --research=<path> flag provided:
analysis/research-context/research_reference in stateTaskCreate for all phases (see Phase Configuration), then set dependencies with TaskUpdate addBlockedBy.maister/tasks/development/YYYY-MM-DD-task-name/orchestrator-state.yml with task info and research referenceOutput:
🚀 Development Orchestrator Started
Task: [description]
Directory: [task-path]
Starting Phase 1: Codebase Analysis...
Use for all development tasks: bug fixes, enhancements, new features, and any work that modifies code.
DO NOT use for: Performance optimization, security remediation, migrations, documentation-only, pure refactoring (use specialized orchestrators).
| Phase | content | activeForm | Activation |
|---|---|---|---|
| 1 | "Analyze codebase & clarify requirements" | "Analyzing codebase & clarifying" | Always |
| 2 | "Analyze gaps & clarify scope" | "Analyzing gaps & clarifying scope" | Always |
| 3 | "Write failing test (TDD Red)" | "Writing failing test" | When has_reproducible_defect |
| 4 | "Generate UI mockups" | "Generating UI mockups" | When ui_heavy |
| 5 | "Gather requirements & create specification" | "Gathering requirements & creating specification" | Always |
| 6 | "Audit specification" | "Auditing specification" | Always (conditional) |
| 7 | "Plan implementation" | "Planning implementation" | Always |
| 8 | "Execute implementation" | "Executing implementation" | Always |
| 9 | "Verify test passes (TDD Green)" | "Verifying test passes" | When Phase 3 was executed |
| 10 | "Prompt verification options" | "Prompting verification options" | Always |
| 11 | "Verify implementation & resolve issues" | "Verifying implementation" | Always |
| 12 | "Run E2E tests" | "Running E2E tests" | When e2e_enabled |
| 13 | "Generate user documentation" | "Generating user documentation" | When user_docs_enabled |
| 14 | "Finalize workflow" | "Finalizing workflow" | Always |
Purpose: Comprehensive codebase exploration followed by scope/requirements clarification Execute:
maister:codebase-analyzeranalysis/clarifications.md
Output: analysis/codebase-analysis.md, analysis/clarifications.md
State: Update task_context.risk_level, phase_summaries.codebase_analysis, task_context.clarifications_resolved→ AUTO-CONTINUE — Do NOT end turn, do NOT prompt user. Proceed immediately to Phase 2.
Purpose: Compare current vs desired state, detect task characteristics, then resolve scope/approach decisions Execute:
maister:gap-analyzer subagenttask_characteristics from gap-analyzer output — 5 fields: has_reproducible_defect, modifies_existing_code, creates_new_entities, involves_data_operations, ui_heavy
b. Write all 5 fields to orchestrator-state.yml at task_context.task_characteristics
c. Read risk_level from output and write to task_context.risk_level
d. Extract phase summary (1-2 sentences) and write to phase_summaries.gap_analysis
e. SELF-CHECK: "Did I read the 5 task_characteristics from the gap-analyzer output and write them to state? Let me re-read orchestrator-state.yml to verify the values match the gap-analyzer output."⛔ DECISION GATE (mandatory — do NOT skip):
decisions_needed from gap-analyzer outputdecisions_needed.critical OR decisions_needed.important is non-empty:
AskUserQuestion — one question per critical decision, batch important decisions into a single multi-select questionSELF-CHECK before continuing: "Did the gap-analyzer return decisions_needed items? If yes, did I invoke AskUserQuestion? If I skipped this, STOP and go back."
analysis/scope-clarifications.mdtask_characteristics.ui_heavy: true → set options.e2e_enabled: true, options.user_docs_enabled: truetask_characteristics.creates_new_entities: true → set options.user_docs_enabled: true--e2e, --no-e2e, --user-docs, --no-user-docs) override these defaultsOutput: analysis/gap-analysis.md, analysis/scope-clarifications.md (conditional)
State: Update task_context.task_characteristics, task_context.scope_expanded, options.e2e_enabled, options.user_docs_enabled, phase_summaries.gap_analysis
Context to pass: Risk level, codebase summary, key files, clarifications
→ Pause (when decisions exist), otherwise Conditional
ANTI-PATTERN — DO NOT DO THIS:
ui_heavy is true, Phase 4 runs. The gap-analyzer made this assessment, not you.ui_heavy is a signal from the gap-analyzer. Do NOT override it with your own complexity judgment.AskUserQuestion - Display executive summary before asking. Read analysis/gap-analysis.md and extract: task type detected, risk level, key characteristics enabled (TDD gates, UI mockups, E2E, user docs), scope decisions made (if any). Then read task_context.task_characteristics from orchestrator-state.yml and determine the next phase:
has_reproducible_defect is true → ask "Continue to Phase 3: TDD Red Gate?"ui_heavy is true → ask "Continue to Phase 4: UI Mockup Generation?"Phase gate: Requires
AskUserQuestionconfirmation from Phase 2 before executing.
Purpose: Write a failing test that reproduces the defect
Execute: Direct - write test, verify it FAILS
Output: implementation/tdd-red-gate.md, failing test file
State: Update tdd_red_passed: true
Skip if: task_characteristics.has_reproducible_defect is false (not set by gap-analyzer)
Critical: Test MUST fail before implementation (proves defect exists)
→ Pause
AskUserQuestion - "TDD red gate complete. Continue to Phase 4?"
Phase gate: Requires
AskUserQuestionconfirmation from the preceding phase before executing.
Purpose: Generate ASCII mockups showing UI integration
Execute: Task tool - maister:ui-mockup-generator subagent
Output: analysis/ui-mockups.md
State: Update phase_summaries.ui_mockups
Skip if: task_characteristics.ui_heavy is false
Context to pass: Gap analysis, scope decisions, component choices
→ Pause
AskUserQuestion - "UI mockups complete. Continue to Phase 5?"
Phase gate: Requires
AskUserQuestionconfirmation from the preceding phase before executing.
⛔ ROUTING GUARD: Read task_context.task_characteristics from orchestrator-state.yml. If has_reproducible_defect is true and Phase 3 is NOT in completed_phases → STOP, execute Phase 3 first. If ui_heavy is true and Phase 4 is NOT in completed_phases → STOP, execute Phase 4 first.
Purpose: Resolve technical decisions, gather specification requirements, then create comprehensive specification Execute:
Part A — Technical & Architecture Clarification (inline, conditional):
analysis/technical-clarifications.md (conditional)Skip technical clarification if: Simple task, risk_level = low, no multiple approaches detected
Part B — Requirements Gathering (inline): 3. Direct - use AskUserQuestion for specification requirements:
analysis/visuals/analysis/visuals/ (even if user says none)
analysis/requirements.md with: initial description, Q&A from all rounds, similar features identified, visual assets and insights, functional requirements summary, reusability opportunities, scope boundaries, technical considerationsPart C — Specification Creation (subagent):
ANTI-PATTERN — DO NOT DO THIS:
INVOKE NOW — Task tool call:
maister:specification-creator subagentContext to pass to subagent: task_path, task_description, task_characteristics, requirements_path (analysis/requirements.md), project_context_paths (INDEX.md, vision.md, roadmap.md, tech-stack.md), risk_level, phase_summaries (codebase_analysis, gap_analysis, clarifications, scope_clarifications, ui_mockups), research_context (if any)
SELF-CHECK: Did you just invoke the Task tool with maister:specification-creator? Or did you start writing spec.md yourself? If the latter, STOP immediately and invoke the Task tool instead.
Output: analysis/technical-clarifications.md (conditional), analysis/requirements.md, implementation/spec.md
State: Update task_context.tech_clarified, task_context.architecture_decision, phase_summaries.specification
→ Pause
AskUserQuestion - Display executive summary before asking. Read implementation/spec.md and extract: spec title, scope boundaries (what's included and excluded), number of key requirements, architecture approach chosen (if any), assumptions made. Format as brief overview then "Continue to specification audit?"
Phase gate: Requires
AskUserQuestionconfirmation from Phase 5 before executing.
Purpose: Independent review of specification before implementation
Execute: Task tool - maister:spec-auditor subagent
Output: verification/spec-audit.md
State: Update options.spec_audit_enabled
Recommended: Always. Present spec audit as the recommended default. User can skip if they choose.
AskUserQuestion - "Run specification audit? (Recommended)" with "Yes, run audit (Recommended)" as first option
→ Pause
AskUserQuestion - Display executive summary before asking. Read verification/spec-audit.md and extract: overall verdict (pass/pass-with-concerns/fail), issue counts by severity, top 1-2 critical findings if any. Format as brief overview then "Continue to implementation planning?"
Phase gate: Requires
AskUserQuestionconfirmation from Phase 6 before executing.
Purpose: Break specification into implementation steps
ANTI-PATTERN — DO NOT DO THIS:
INVOKE NOW — Task tool call:
Execute: Task tool - maister:implementation-planner subagent
Output: implementation/implementation-plan.md
State: Update task groups and dependencies
Context to pass to subagent: task_path, task_description, task_characteristics, phase_summaries (specification, gap_analysis, codebase_analysis), research_context (if any)
SELF-CHECK: Did you just invoke the Task tool with maister:implementation-planner? Or did you start writing implementation-plan.md yourself? If the latter, STOP immediately and invoke the Task tool instead.
→ Pause
AskUserQuestion - Display executive summary before asking. Read implementation/implementation-plan.md and extract: number of task groups, total implementation steps, key dependencies between groups, estimated complexity. Format as brief overview then "Continue to implementation?"
Phase gate: Requires
AskUserQuestionconfirmation from Phase 7 before executing.
Purpose: Execute the implementation plan
ANTI-PATTERN — DO NOT DO THIS:
INVOKE NOW — Skill tool call:
Execute: Skill tool - maister:implementation-plan-executor
Output: Implemented code, implementation/work-log.md
State: Update implementation progress, extract phase_summaries.implementation
SELF-CHECK: Did you just invoke the Skill tool with maister:implementation-plan-executor? Or did you start writing code yourself? If the latter, STOP immediately and invoke the Skill tool instead.
⚠️ POST-IMPLEMENTATION CONTINUATION — After the skill completes and returns control:
orchestrator-state.yml to confirm you are the orchestratorcompleted_phasestask_characteristics.has_reproducible_defect AND Phase 3 in completed_phases → Phase 9, else → Phase 10→ Pause
AskUserQuestion - Display executive summary before asking. Extract from phase_summaries.implementation and implementation/work-log.md: task groups completed, files changed, test results from incremental runs, any known issues or deferred items. Format as brief overview then "Continue to verification?"
Phase gate: Requires
AskUserQuestionconfirmation from Phase 8 before executing.
Purpose: Verify the failing test now passes
Execute: Direct - run the test written in Phase 3
Output: implementation/tdd-green-gate.md
State: Update tdd_green_passed: true
Skip if: Phase 3 was not executed
Critical: Test MUST pass (proves defect is fixed)
→ Pause
AskUserQuestion - "TDD gate passed. Continue to Phase 10?"
Phase gate: Requires
AskUserQuestionconfirmation from the preceding phase before executing.
Purpose: Determine which verification checks to run using tiered decision matrix
Execute: Direct - display plan, confirm/adjust via AskUserQuestion
Output: Updated state with all verification options
State: Set options.code_review_enabled, options.pragmatic_review_enabled, options.reality_check_enabled, options.production_check_enabled, options.e2e_enabled, options.user_docs_enabled
Auto-set: skip_test_suite: true (full test suite already passed during implementation phase; cleared before re-verification if fixes are applied)
Step 1: Display the verification plan:
Verification Plan:
Obligatory (always run):
✓ Completeness check
✓ Test suite (skipped — passed during implementation; re-enabled after fixes)
Recommended (adjustable):
✓ Code review — quality and security analysis
✓ Pragmatic review — detects over-engineering
✓ Reality check — validates work solves the problem
✓ Production readiness — deployment readiness checks
Conditional:
[✓/—] E2E browser testing — [reason]
[✓/—] User documentation — [reason]
Step 2 (3 questions):
Q1 (always): AskUserQuestion (multi-select) — "Which standard verifications to run?" Options: "Code review (Recommended)", "Pragmatic review (Recommended)", "Reality check (Recommended)", "Production readiness (Recommended)". All pre-selected.
Q2 (SKIP if options.e2e_enabled: false and no --e2e flag): AskUserQuestion — "Enable E2E browser verification?" Options: "Yes (Recommended)", "No, skip".
Q3 (SKIP if options.user_docs_enabled: false and no --user-docs flag): AskUserQuestion — "Generate user documentation?" Options: "Yes (Recommended)", "No, skip".
→ Pause
Phase gate: Requires
AskUserQuestionconfirmation from Phase 10 before executing.
Purpose: Comprehensive implementation verification with fix-then-reverify cycles
Output: verification/implementation-verification.md, optional code-review/pragmatic/reality reports, updated implementation/work-log.md
State: Update verification results, verification_context
Execute:
Step 1: Invoke Skill tool - maister:implementation-verifier
Step 2: Display detailed issue breakdown grouped by category and severity:
Verification Results:
Critical ([N]):
- [category]: [description] — [file:line] [fixable/manual]
...
Warning ([N]):
- [category]: [description] — [file:line] [fixable/manual]
...
Info ([N]):
- [description] (listed for awareness, not actionable)
Step 3: Gate on verification status:
status: passed → skip to Post-Verification Continuationstatus: passed_with_issues or failed → enter user-driven fix loop (Step 4)Step 4: User-driven fix loop (max 3 iterations):
verification_context.fixes_appliedskip_test_suite: false (code changed, tests must re-run)maister:implementation-verifier → return to Step 2verification_context.reverify_countExit conditions:
⚠️ POST-VERIFICATION CONTINUATION — After issue resolution completes:
orchestrator-state.yml to confirm you are the orchestratorcompleted_phases→ Pause
AskUserQuestion - Display executive summary: total issues found, issues fixed, issues remaining by severity. Then "Continue to Phase 12?"
Phase gate: Requires
AskUserQuestionconfirmation from Phase 11 before executing.
Purpose: Runtime browser verification with screenshots (via Playwright MCP tools, not test file generation)
Execute: Task tool - maister:e2e-test-verifier subagent
Prompt must include: task_path (absolute), spec_path, base_url. Report saves to {task_path}/verification/e2e-verification-report.md.
Output: verification/e2e-verification-report.md, screenshots
State: Update E2E results
Skip if: options.e2e_enabled = false
→ Pause
AskUserQuestion - "E2E complete. Continue to Phase 13?"
Phase gate: Requires
AskUserQuestionconfirmation from the preceding phase before executing.
Purpose: Generate user-facing documentation with screenshots
Execute: Task tool - maister:user-docs-generator subagent
Prompt must include: task_path (absolute), spec_path, base_url. Guide saves to {task_path}/documentation/user-guide.md.
Output: documentation/user-guide.md, screenshots
State: Update docs generation status
Skip if: options.user_docs_enabled = false
→ Pause
AskUserQuestion - "Documentation complete. Continue to Phase 14?"
Phase gate: Requires
AskUserQuestionconfirmation from the preceding phase before executing.
Purpose: Complete workflow and provide next steps
Execute: Direct - create summary, update state, guide commit
Output: Workflow summary
State: Set task.status: completed
Process:
→ End of workflow
Development-specific fields in orchestrator-state.yml:
orchestrator:
options:
spec_audit_enabled: true
skip_test_suite: true
e2e_enabled: null
user_docs_enabled: null
code_review_enabled: true
pragmatic_review_enabled: true
reality_check_enabled: true
production_check_enabled: true
task_context:
risk_level: null
clarifications_resolved: null
scope_expanded: null
architecture_decision: null
task_characteristics:
has_reproducible_defect: false
modifies_existing_code: false
creates_new_entities: false
involves_data_operations: false
ui_heavy: false
research_reference:
path: null
research_question: null
research_type: null
confidence_level: null
phase_summaries:
research: {summary: null, key_findings: [], recommended_approach: null}
codebase_analysis: {key_files: [], primary_language: null, summary: null}
clarifications: []
gap_analysis: {integration_points: [], summary: null}
scope_clarifications: {scope_expanded: null, summary: null}
ui_mockups: {components_designed: [], summary: null}
specification: {summary: null}
architecture_decision: {decision: null, summary: null}
.maister/tasks/development/YYYY-MM-DD-task-name/
├── orchestrator-state.yml
├── analysis/
│ ├── research-context/ # If --research provided
│ ├── codebase-analysis.md # Phase 1
│ ├── clarifications.md # Phase 1
│ ├── gap-analysis.md # Phase 2
│ ├── scope-clarifications.md # Phase 2 (conditional)
│ ├── technical-clarifications.md # Phase 5 (conditional)
│ └── ui-mockups.md # Phase 4 (conditional)
├── implementation/
│ ├── spec.md # Phase 5
│ ├── requirements.md # Phase 5
│ ├── implementation-plan.md # Phase 7
│ ├── work-log.md # Phase 8
│ ├── tdd-red-gate.md # Phase 3 (conditional)
│ └── tdd-green-gate.md # Phase 9 (conditional)
├── verification/
│ ├── spec-audit.md # Phase 6 (recommended)
│ ├── implementation-verification.md # Phase 11
│ └── e2e-verification-report.md # Phase 12 (optional)
└── documentation/
└── user-guide.md # Phase 13 (optional)
| Phase | Max Attempts | Strategy |
|---|---|---|
| 1 | 2 | Expand search, prompt user |
| 2 | 2 | Re-analyze, ask user |
| 3 | 2 | Rewrite test, skip TDD with doc |
| 5 | 2 | Regenerate spec |
| 7 | 2 | Regenerate plan |
| 8 | 5 | Fix syntax, imports, tests |
| 9 | 3 | Return to implementation |
| 11 | 3 | Fix tests, re-run |
| Flag | Effect |
|---|---|
--from=PHASE | Start from specific phase |
--research=PATH | Link to completed research task |
--audit / --no-audit | Force/skip specification audit |
--e2e / --no-e2e | Force/skip E2E testing |
--user-docs / --no-user-docs | Force/skip user documentation |
When starting development from a completed research task, the orchestrator loads research context to INFORM all phases.
Method 1: Research folder as sole argument (recommended)
/maister:development .maister/tasks/research/2026-01-12-oauth-research
The orchestrator auto-detects this is a research folder and:
research_context.research_questionresearch_reference in stateMethod 2: Explicit --research flag
/maister:development "Implement OAuth" --research=.maister/tasks/research/2026-01-12-oauth-research
When research context is detected, read these files from the research folder:
| Artifact | Path | Purpose |
|---|---|---|
| State | orchestrator-state.yml | research_type, confidence_level |
| Report | outputs/research-report.md | Main findings and conclusions |
| Solution Exploration | outputs/solution-exploration.md | Alternatives and trade-offs (input to Phase 5) |
| High-Level Design | outputs/high-level-design.md | C4 architecture (input to Phase 5) |
| Decision Log | outputs/decision-log.md | ADR decisions (input to Phase 5) |
Research INFORMS phases, never SKIPS them. Research context passes to ALL phases via task_context.phase_summaries.research. No phases are skipped.
| Phase | How Research Context is Used |
|---|---|
| Phase 1 | Codebase analyzer receives research findings as search guidance |
| Phase 2 | Gap analyzer uses research recommendations for comparison |
| Phase 5 | Specification creator uses high-level-design.md as INPUT (still creates full spec). Architecture decisions use research report AND decision-log.md (lighter when ADRs comprehensive) |
| Phase 7 | Implementation planner references research approach for task grouping |
Invoked via:
/maister:development [description] [--e2e] [--user-docs] [--research=PATH] (new)/maister:development [task-path] [--from=PHASE] [--reset-attempts] (resume)Phase 3 (Red Gate): Test MUST FAIL before implementation (activated when gap-analyzer detects reproducible defect) Phase 9 (Green Gate): Test MUST PASS after implementation (activated when Phase 3 was executed)