@caoscompanybr/merlin 3.5.0

package/.merlin-core/development/workflows/brownfield-service.yaml

@@ -0,0 +1,52 @@
+workflow:
+  id: brownfield-service
+  name: Brownfield Service Enhancement
+  version: "1.0"
+  description: >-
+    Workflow for enhancing existing backend services.
+    Starts with codebase analysis, then follows SDD pipeline.
+
+  type: brownfield
+  constitution_articles: [III, IV]
+
+  sequence:
+    - step: analyze_codebase
+      phase: 1
+      agent: researcher
+      description: "Deep analysis of existing service codebase"
+      creates: thoughts/shared/research/codebase-analysis.md
+      duration_estimate: "20-40 min"
+
+    - step: create_spec
+      phase: 2
+      agent: architect
+      description: "Create spec for the enhancement, respecting existing patterns"
+      creates: thoughts/shared/plans/spec.md
+      duration_estimate: "30-60 min"
+
+    - step: implement
+      phase: 3
+      agent: dev
+      description: "Implement the enhancement following existing patterns"
+      creates: implementation_files
+      duration_estimate: "1-4 hours"
+
+    - step: review
+      phase: 4
+      agent: qa
+      description: "Review changes for quality and backward compatibility"
+      gate: true
+      duration_estimate: "20-40 min"
+
+  decision_guidance:
+    when_to_use:
+      - Adding features to existing backend
+      - API version upgrades
+      - Service refactoring
+    when_not_to_use:
+      - Full project assessment (use brownfield-discovery)
+      - New project (use greenfield workflows)
+
+  metadata:
+    created: "2026-02-14"
+    tags: [brownfield, service, workflow]

package/.merlin-core/development/workflows/development-cycle.yaml

@@ -0,0 +1,57 @@
+# ============================================
+# Development Cycle Workflow
+# ============================================
+# Merlin standard development cycle workflow.
+# Used for ongoing development within an established project.
+# ============================================
+
+workflow:
+  id: development-cycle
+  name: Standard Development Cycle
+  version: 3.0.0
+  description: >
+    The standard iterative development workflow for Merlin projects.
+    Follows the Constitution's spec-driven approach with quality gates.
+
+  phases:
+    - id: planning
+      name: Sprint Planning
+      agents: [pm, po, sm]
+      commands: [/plan]
+      output: thoughts/shared/plans/
+
+    - id: development
+      name: Development
+      agents: [dev, architect]
+      commands: [/implement, /oneshot]
+      quality_gates: [layer1]
+
+    - id: review
+      name: Code Review
+      agents: [qa, dev]
+      commands: [/review, /debug]
+      quality_gates: [layer1, layer2]
+
+    - id: release
+      name: Release
+      agents: [devops, qa]
+      commands: [/commit, /describe-pr]
+      quality_gates: [layer1, layer2, layer3]
+
+  transitions:
+    planning_to_development:
+      from: planning
+      to: development
+      condition: plan.approved
+    development_to_review:
+      from: development
+      to: review
+      condition: implementation.complete
+    review_to_release:
+      from: review
+      to: release
+      condition: review.verdict == "READY"
+    review_to_development:
+      from: review
+      to: development
+      condition: review.verdict == "NEEDS FIXES"

package/.merlin-core/development/workflows/epic-orchestration.yaml

@@ -0,0 +1,47 @@
+workflow:
+  id: epic-orchestration
+  name: Epic Orchestration - Multi-Story Coordination
+  version: "1.0"
+  description: >-
+    Orchestrates the execution of an epic containing multiple stories.
+    Manages story ordering, dependency resolution, and cross-story quality gates.
+
+  type: orchestration
+  constitution_articles: [II, III, V]
+
+  config:
+    maxParallelStories: 3
+    autoAdvance: true
+    qualityGatePerStory: true
+
+  sequence:
+    - step: epic_setup
+      phase: 1
+      agent: pm
+      description: "Parse epic, order stories by dependency, create execution plan"
+      creates: ".merlin/epic-state/{epicId}/plan.json"
+
+    - step: story_cycle
+      phase: 2
+      agent: system
+      description: "Execute each story through the development-cycle workflow"
+      repeats: for_each_story
+      sub_workflow: development-cycle
+      on_story_complete:
+        action: check_next
+
+    - step: epic_gate
+      phase: 3
+      agent: qa
+      description: "Final quality gate across all stories in the epic"
+      gate: true
+
+    - step: epic_retrospective
+      phase: 4
+      agent: po
+      description: "Document learnings, update velocity, archive epic"
+      optional: true
+
+  metadata:
+    created: "2026-02-14"
+    tags: [epic, orchestration, workflow]

package/.merlin-core/development/workflows/folloni-funnel.yaml

@@ -0,0 +1,177 @@
+# ============================================
+# Folloni Funnel Workflow
+# ============================================
+# The signature Merlin development workflow.
+# Three phases with context resets between them.
+# Each phase produces a document consumed by the next.
+#
+# Phase 1: Research -> prd.md -> [CONTEXT RESET]
+# Phase 2: Architecture -> spec.md -> [CONTEXT RESET]
+# Phase 3: Implementation -> Working Code -> Quality Check
+# ============================================
+
+workflow:
+  id: folloni-funnel
+  name: Folloni 3-Phase Development Funnel
+  version: 3.0.0
+  description: >
+    Research-first development methodology. Context is explicitly reset
+    between phases to ensure each phase starts FRESH, loading only the
+    output document from the previous phase. This prevents context
+    pollution and ensures clean architectural decisions.
+
+  # Step-file references for JIT loading (BMAD pattern).
+  # When StepLoader detects this key, it loads one step at a time
+  # instead of the full workflow. Inline phases below are kept
+  # for backward compatibility with executors that don't support step_files.
+  step_files:
+    - steps/folloni-01-research.yaml
+    - steps/folloni-02-architecture.yaml
+    - steps/folloni-03-implementation.yaml
+
+  constitution_references:
+    - "Article III: Spec-Driven Development"
+    - "Article IV: No Invention"
+    - "Article V: Quality First"
+
+  phases:
+    - id: research
+      name: "Phase 1: Research"
+      description: >
+        Deep research into requirements, codebase, and constraints.
+        Produces a PRD (Product Requirements Document) that captures
+        everything needed to make architecture decisions.
+      agents:
+        primary: researcher    # Sage - Deep Codebase Researcher
+        support:
+          - scout             # Scout - Fast File & Pattern Locator
+          - web-researcher    # Iris - External Research (if needed)
+          - analyst           # Atlas - Business Analysis
+      commands:
+        - /research
+      output:
+        document: thoughts/shared/research/prd.md
+        format: markdown
+        required_sections:
+          - Requirements
+          - Constraints
+          - Dependencies
+          - Risks
+          - Out of Scope
+      success_criteria:
+        automated: []
+        manual:
+          - "PRD covers all user requirements"
+          - "Risks and constraints are identified"
+          - "Dependencies are documented"
+      exit_action: context_reset
+      alkimia_bracket_on_exit: DEPLETED  # Marks context as DEPLETED, triggers reset
+
+    - id: architecture
+      name: "Phase 2: Architecture"
+      description: >
+        Design the technical architecture based on the PRD.
+        Produces a specification document with phases, file changes,
+        and success criteria for implementation.
+      context_on_entry:
+        load_from_previous: thoughts/shared/research/prd.md
+        alkimia_bracket: FRESH  # Starts with FRESH context
+      agents:
+        primary: architect     # Aria - Software Architect
+        support:
+          - data-engineer     # Dara - Schema design (if needed)
+      commands:
+        - /plan
+      output:
+        document: thoughts/shared/plans/spec.md
+        format: markdown
+        required_sections:
+          - Architecture Overview
+          - Phases (ordered, with file changes)
+          - Success Criteria (automated + manual)
+          - Risks
+          - Out of Scope
+      approval:
+        required: true
+        stake_level: MEDIUM
+        approvers: [user]
+      success_criteria:
+        automated: []
+        manual:
+          - "Spec traces to PRD requirements (Article IV)"
+          - "All phases have clear file changes"
+          - "Success criteria are testable"
+      exit_action: context_reset
+
+    - id: implementation
+      name: "Phase 3: Implementation"
+      description: >
+        Implement the spec phase by phase. Each phase is verified
+        before proceeding. Quality gates apply at the end.
+      context_on_entry:
+        load_from_previous: thoughts/shared/plans/spec.md
+        alkimia_bracket: FRESH
+      agents:
+        primary: dev           # Dex - Full Stack Developer
+        support:
+          - qa                # Quinn - Quality verification
+          - devops            # Gage - Git operations
+      commands:
+        - /implement
+        - /review
+        - /commit
+      output:
+        document: null  # Output is working code, not a document
+        artifacts:
+          - code changes
+          - test results
+          - quality report
+      quality_gates:
+        layer1:
+          - lint_passes: true
+          - tests_pass: true
+          - build_succeeds: true
+        layer2:
+          - pr_created: true
+          - ci_passes: true
+        layer3:
+          - human_review: optional
+      success_criteria:
+        automated:
+          - "npm run lint -- 0 errors"
+          - "npm run test -- all tests pass"
+          - "npm run build -- clean build"
+        manual:
+          - "Feature works as specified"
+          - "No unplanned changes (Article IV)"
+
+  transitions:
+    research_to_architecture:
+      from: research
+      to: architecture
+      condition: research.output.document exists
+      action: context_reset
+    architecture_to_implementation:
+      from: architecture
+      to: implementation
+      condition: architecture.approval.granted
+      action: context_reset
+
+  failure_handling:
+    phase_failure:
+      action: iterate
+      description: >
+        If a phase fails its success criteria, use /iterate-plan
+        to update the plan with new information and retry the phase.
+    implementation_failure:
+      action: debug
+      description: >
+        If implementation fails tests, use /debug to investigate
+        and fix before retrying the phase.
+
+  metadata:
+    source: "SDD Methodology + Merlin Enhancement"
+    context_reset_mechanism: >
+      Context reset is implemented via Alkimia engine: the current session
+      bracket is marked as DEPLETED, the handoff document is created, and
+      the next phase starts a new session loading ONLY the output document.

package/.merlin-core/development/workflows/greenfield-fullstack.yaml

@@ -0,0 +1,167 @@
+workflow:
+  id: greenfield-fullstack
+  name: Greenfield Full-Stack Application Development
+  version: "1.0"
+  description: >-
+    Agent workflow for building full-stack applications from concept to deployment.
+    Supports comprehensive planning for complex projects and rapid prototyping for simple ones.
+    Follows Constitution Article III: Spec-Driven Development.
+
+  type: greenfield
+  constitution_articles: [I, III, IV, V]
+
+  triggers:
+    - event: decision_tree
+      condition: "projectState === 'GREENFIELD' AND projectType === 'fullstack'"
+
+  phases:
+    - phase_0: Environment Bootstrap
+    - phase_1: Discovery & Planning
+    - phase_2: Document Sharding
+    - phase_3: Development Cycle
+
+  sequence:
+    # PHASE 0: ENVIRONMENT BOOTSTRAP
+    - step: environment_bootstrap
+      phase: 0
+      phase_name: "Environment Bootstrap"
+      agent: devops
+      description: "Setup development environment: CLIs, auth, git repo, project structure"
+      creates:
+        - .merlin-core/project-config.yaml
+        - .gitignore
+        - package.json
+      duration_estimate: "15-30 min"
+      optional: false
+
+    # PHASE 1: DISCOVERY & PLANNING
+    - step: project_brief
+      phase: 1
+      phase_name: "Create Project Brief"
+      agent: analyst
+      description: "Research and create comprehensive project brief"
+      creates: thoughts/shared/research/project-brief.md
+      requires: environment_bootstrap
+      duration_estimate: "30-60 min"
+
+    - step: create_prd
+      phase: 1
+      phase_name: "Create PRD"
+      agent: pm
+      description: "Create Product Requirements Document from project brief"
+      creates: thoughts/shared/plans/prd.md
+      requires: project-brief.md
+      duration_estimate: "30-60 min"
+
+    - step: create_frontend_spec
+      phase: 1
+      phase_name: "Create Frontend Spec"
+      agent: ux
+      description: "Create UI/UX specification from PRD"
+      creates: thoughts/shared/plans/frontend-spec.md
+      requires: prd.md
+      duration_estimate: "30-45 min"
+
+    - step: create_architecture
+      phase: 1
+      phase_name: "Create Architecture"
+      agent: architect
+      description: "Create comprehensive fullstack architecture"
+      creates: thoughts/shared/plans/architecture.md
+      requires:
+        - prd.md
+        - frontend-spec.md
+      duration_estimate: "30-60 min"
+
+    - step: validate_artifacts
+      phase: 1
+      phase_name: "Validate All Artifacts"
+      agent: po
+      description: "Validate all documents for consistency and completeness"
+      gate: true
+      on_verdict:
+        APPROVED:
+          next: shard_documents
+        NEEDS_WORK:
+          action: delegate_fixes
+          delegates_to: [analyst, pm, ux, architect]
+
+    # PHASE 2: DOCUMENT SHARDING
+    - step: shard_documents
+      phase: 2
+      phase_name: "Shard Documents"
+      agent: po
+      description: "Break down PRD and architecture into development-ready chunks"
+      creates:
+        - docs/source-tree.md
+        - docs/tech-stack.md
+        - docs/coding-standards.md
+      requires:
+        - prd.md
+        - frontend-spec.md
+        - architecture.md
+      duration_estimate: "15-30 min"
+
+    # PHASE 3: DEVELOPMENT CYCLE
+    - step: create_story
+      phase: 3
+      phase_name: "Create Story"
+      agent: sm
+      description: "Create next story from sharded docs"
+      creates: docs/stories/story-{id}.md
+      requires: sharded_docs
+      repeats: for_each_epic
+      duration_estimate: "15-30 min"
+
+    - step: implement_story
+      phase: 3
+      phase_name: "Implement Story"
+      agent: dev
+      description: "Implement the approved story"
+      creates: implementation_files
+      requires: story.md
+      duration_estimate: "1-4 hours"
+
+    - step: review_implementation
+      phase: 3
+      phase_name: "QA Review"
+      agent: qa
+      description: "Review implementation quality"
+      requires: implementation_files
+      gate: true
+      optional: true
+      on_verdict:
+        APPROVED:
+          next: create_story
+          condition: stories_remaining
+        NEEDS_REVISION:
+          next: implement_story
+      duration_estimate: "20-40 min"
+
+    - step: epic_retrospective
+      phase: 3
+      phase_name: "Epic Retrospective"
+      agent: po
+      description: "Validate epic completion and document learnings"
+      condition: epic_complete
+      optional: true
+
+  completion:
+    next_steps:
+      - "All stories implemented and reviewed"
+      - "Project development phase complete"
+
+  decision_guidance:
+    when_to_use:
+      - Building production-ready applications
+      - Complex feature requirements
+      - Need comprehensive documentation
+      - Enterprise or customer-facing applications
+    when_not_to_use:
+      - Enhancing existing application (use brownfield workflows)
+      - Simple single-concern project (use Folloni funnel)
+
+  metadata:
+    created: "2026-02-14"
+    author: "@architect (Aria)"
+    tags: [greenfield, fullstack, workflow]

package/.merlin-core/development/workflows/greenfield-service.yaml

@@ -0,0 +1,56 @@
+workflow:
+  id: greenfield-service
+  name: Greenfield Service/API Development
+  version: "1.0"
+  description: >-
+    Streamlined workflow for building backend services and APIs from scratch.
+    Lighter than full-stack workflow - focuses on data modeling, API design, and testing.
+
+  type: greenfield
+  constitution_articles: [III, V]
+
+  phases:
+    - phase_1: API Design
+    - phase_2: Implementation
+    - phase_3: Testing & Review
+
+  sequence:
+    - step: api_design
+      phase: 1
+      agent: architect
+      description: "Design API endpoints, data models, and service architecture"
+      creates: thoughts/shared/plans/api-spec.md
+      duration_estimate: "30-60 min"
+
+    - step: data_modeling
+      phase: 1
+      agent: data-engineer
+      description: "Design database schema and data access patterns"
+      creates: thoughts/shared/plans/data-model.md
+      duration_estimate: "20-40 min"
+
+    - step: implement_service
+      phase: 2
+      agent: dev
+      description: "Implement service endpoints and business logic"
+      creates: implementation_files
+      duration_estimate: "2-6 hours"
+
+    - step: qa_review
+      phase: 3
+      agent: qa
+      description: "Review implementation, run tests, validate API contracts"
+      gate: true
+      duration_estimate: "30-60 min"
+
+  decision_guidance:
+    when_to_use:
+      - API-only projects without frontend
+      - Microservices
+      - Backend services
+    when_not_to_use:
+      - Projects with UI (use greenfield-fullstack)
+
+  metadata:
+    created: "2026-02-14"
+    tags: [greenfield, service, api, workflow]

package/.merlin-core/development/workflows/qa-loop.yaml

@@ -0,0 +1,115 @@
+workflow:
+  id: qa-loop
+  name: QA Loop - Review Fix Re-review Cycle
+  version: "1.0"
+  description: >-
+    Automated QA loop that orchestrates the review → fix → re-review cycle.
+    Runs up to maxIterations (default 5), tracking each iteration's results.
+    Escalates to human when max iterations reached or manual stop requested.
+    Implements Constitution Article V: Quality First.
+
+  type: loop
+  constitution_articles: [V, VII]
+
+  triggers:
+    - event: command
+      command: "/review"
+      action: start_loop
+    - event: command
+      command: "/debug"
+      action: run_step
+      step: review
+
+  config:
+    maxIterations: 5
+    reviewTimeout: 1800000   # 30 minutes
+    fixTimeout: 3600000      # 60 minutes
+    maxRetries: 2
+
+  sequence:
+    - step: review
+      phase: 1
+      phase_name: "QA Review"
+      agent: qa
+      description: >-
+        Execute comprehensive QA review of the implementation.
+        Produces a verdict: APPROVE, REJECT, or BLOCKED.
+      outputs: [gate-file.yaml, verdict, issuesFound]
+      timeout: "{config.reviewTimeout}"
+      on_success:
+        next: check_verdict
+
+    - step: check_verdict
+      phase: 2
+      phase_name: "Verdict Check"
+      agent: system
+      description: >-
+        Evaluate the review verdict and determine next action.
+      condition_check:
+        - condition: verdict == "APPROVE"
+          action: complete
+        - condition: verdict == "BLOCKED"
+          action: escalate
+          reason: "QA review BLOCKED - requires human intervention"
+        - condition: verdict == "REJECT"
+          action: continue
+          next: create_fix_request
+
+    - step: create_fix_request
+      phase: 3
+      phase_name: "Create Fix Request"
+      agent: qa
+      description: >-
+        Generate structured fix request from review findings.
+        Prioritizes issues and provides actionable fix instructions.
+      outputs: [fix-request.md, prioritizedIssues]
+      on_success:
+        next: fix_issues
+
+    - step: fix_issues
+      phase: 4
+      phase_name: "Apply Fixes"
+      agent: dev
+      description: >-
+        Developer agent applies fixes based on the fix request.
+        Runs tests and validates changes.
+      outputs: [fixes-applied.json, issuesFixed]
+      timeout: "{config.fixTimeout}"
+      on_success:
+        next: increment_iteration
+
+    - step: increment_iteration
+      phase: 5
+      phase_name: "Check Iteration"
+      agent: system
+      description: >-
+        Increment iteration counter and check against max.
+        If max reached, escalate to human (Article VII).
+      condition_check:
+        - condition: currentIteration >= maxIterations
+          action: escalate
+          reason: "Max iterations ({maxIterations}) reached without APPROVE"
+        - condition: currentIteration < maxIterations
+          action: continue
+          next: review
+
+  escalation:
+    enabled: true
+    triggers: [max_iterations_reached, verdict_blocked, fix_failure]
+    approval_stake: MEDIUM
+
+  completion:
+    outputs: [loop-status.json, summary.md]
+
+  control:
+    stop:
+      action: "Save state and allow resume later"
+    resume:
+      action: "Load state and continue from last step"
+    reset:
+      action: "Delete state and start fresh"
+
+  metadata:
+    created: "2026-02-14"
+    author: "@architect (Aria)"
+    tags: [qa-loop, quality, workflow]