@smartmemory/compose 0.1.0

package/pipelines/refactor.stratum.yaml

@@ -0,0 +1,169 @@
+# metadata:
+#   id: refactor
+#   label: "Refactor"
+#   description: "Safe refactoring — snapshot tests, plan changes, execute, verify behavior preserved"
+#   category: maintenance
+#   steps: 7
+#   estimated_minutes: 45
+
+version: "0.1"
+
+# refactor pipeline
+#
+# Seven-step flow for safe refactoring:
+#   1. snapshot    — capture current test results as baseline
+#   2. analyze     — identify code smells, duplication, and improvement targets
+#   3. plan        — write a step-by-step refactoring plan
+#   4. execute     — apply refactoring changes incrementally
+#   5. test        — run full test suite, compare against snapshot
+#   6. review      — codex reviews refactored code for correctness
+#   7. ship        — commit and report
+#
+# Inputs:
+#   task — what to refactor (module, pattern, or scope description)
+#
+# Usage:
+#   stratum_plan <this yaml> "refactor" {"task": "..."}
+
+contracts:
+  RefactorResult:
+    phase:    {type: string}
+    summary:  {type: string}
+    outcome:  {type: string, values: [complete, failed]}
+
+  TestResult:
+    passing:  {type: boolean}
+    summary:  {type: string}
+    failures: {type: array}
+
+  ReviewResult:
+    clean:    {type: boolean}
+    summary:  {type: string}
+    findings: {type: array}
+
+functions:
+  snapshot:
+    mode: compute
+    intent: >
+      Run the full test suite and capture results as a baseline snapshot.
+      Record pass/fail counts and test names. Return a summary of the
+      current test state before any changes.
+    input:
+      task: {type: string}
+    output: RefactorResult
+    retries: 1
+
+  analyze:
+    mode: compute
+    intent: >
+      Analyze the target code for refactoring opportunities. Identify code
+      smells, duplication, coupling issues, and improvement targets.
+      Return a structured summary of findings.
+    input:
+      task: {type: string}
+    output: RefactorResult
+    retries: 1
+
+  plan:
+    mode: compute
+    intent: >
+      Write a step-by-step refactoring plan. Each step should be a safe,
+      incremental change that preserves behavior. Include file paths and
+      expected changes.
+    input:
+      task: {type: string}
+    output: RefactorResult
+    retries: 1
+
+  execute:
+    mode: compute
+    intent: >
+      Apply the refactoring changes incrementally following the plan.
+      Make each change as small as possible. Return a summary of all
+      modifications made.
+    input:
+      task: {type: string}
+    output: RefactorResult
+    retries: 3
+
+  test:
+    mode: compute
+    intent: >
+      Run the full test suite. Compare results against the baseline snapshot.
+      Return structured JSON: { "passing": boolean, "summary": string, "failures": string[] }.
+      All tests that passed before must still pass.
+    input:
+      task: {type: string}
+    output: TestResult
+    ensure:
+      - "result.passing == true"
+    retries: 5
+
+  review:
+    mode: compute
+    intent: >
+      Review the refactored code for correctness and quality. Verify that
+      behavior is preserved and the code is cleaner than before.
+      Return { "clean": boolean, "summary": string, "findings": string[] }.
+    input:
+      task: {type: string}
+    output: ReviewResult
+    ensure:
+      - "result.clean == true"
+    retries: 3
+
+  ship:
+    mode: compute
+    intent: >
+      Commit all changes with a descriptive message. Return a summary.
+    input:
+      task: {type: string}
+    output: RefactorResult
+    retries: 1
+
+flows:
+  refactor:
+    input:
+      task: {type: string}
+    output: RefactorResult
+    steps:
+      - id: snapshot
+        function: snapshot
+        inputs:
+          task: "$.input.task"
+
+      - id: analyze
+        function: analyze
+        inputs:
+          task: "$.input.task"
+        depends_on: [snapshot]
+
+      - id: plan
+        function: plan
+        inputs:
+          task: "$.input.task"
+        depends_on: [analyze]
+
+      - id: execute
+        function: execute
+        inputs:
+          task: "$.input.task"
+        depends_on: [plan]
+
+      - id: test
+        function: test
+        inputs:
+          task: "$.input.task"
+        depends_on: [execute]
+
+      - id: review
+        function: review
+        inputs:
+          task: "$.input.task"
+        depends_on: [test]
+
+      - id: ship
+        function: ship
+        inputs:
+          task: "$.input.task"
+        depends_on: [review]

package/pipelines/research.stratum.yaml

@@ -0,0 +1,88 @@
+# metadata:
+#   id: research
+#   label: "Research"
+#   description: "Explore a topic — gather sources, analyze findings, produce a summary report"
+#   category: exploration
+#   steps: 3
+#   estimated_minutes: 15
+
+version: "0.1"
+
+# research pipeline
+#
+# Three-step flow for exploratory research:
+#   1. gather   — collect sources, read code, search docs
+#   2. analyze  — synthesize findings, identify patterns and gaps
+#   3. report   — produce a structured summary with recommendations
+#
+# Inputs:
+#   task — research question or topic to explore
+#
+# Usage:
+#   stratum_plan <this yaml> "research" {"task": "..."}
+
+contracts:
+  ResearchResult:
+    phase:    {type: string}
+    artifact: {type: string}
+    summary:  {type: string}
+    outcome:  {type: string, values: [complete, failed]}
+
+functions:
+  gather:
+    mode: compute
+    intent: >
+      Collect sources relevant to the research topic. Search the codebase,
+      read documentation, and gather external references. Return a summary
+      of sources found and key data points.
+    input:
+      task: {type: string}
+    output: ResearchResult
+    retries: 1
+
+  analyze:
+    mode: compute
+    intent: >
+      Synthesize the gathered information. Identify patterns, contradictions,
+      gaps, and insights. Organize findings into themes. Return a structured
+      analysis summary.
+    input:
+      task: {type: string}
+    output: ResearchResult
+    retries: 1
+
+  report:
+    mode: compute
+    intent: >
+      Produce a structured research report with findings, analysis, and
+      actionable recommendations. Write to an appropriate file path.
+      Return the artifact path and summary.
+    input:
+      task: {type: string}
+    output: ResearchResult
+    ensure:
+      - "result.outcome == 'complete'"
+    retries: 1
+
+flows:
+  research:
+    input:
+      task: {type: string}
+    output: ResearchResult
+    steps:
+      - id: gather
+        function: gather
+        inputs:
+          task: "$.input.task"
+
+      - id: analyze
+        function: analyze
+        inputs:
+          task: "$.input.task"
+        depends_on: [gather]
+
+      - id: report
+        function: report
+        inputs:
+          task: "$.input.task"
+        depends_on: [analyze]

package/pipelines/review-fix.stratum.yaml

@@ -0,0 +1,109 @@
+# metadata:
+#   id: review-fix
+#   label: "Review & Fix"
+#   description: "Iterative review-fix loop — Codex reviews, Claude fixes until clean"
+#   category: quality
+#   steps: 2
+#   estimated_minutes: 15
+
+version: "0.1"
+
+# review-fix pipeline
+#
+# Runs a task to completion via a two-phase loop:
+#   1. execute  — claude_run produces the initial implementation
+#   2. review   — codex_run reviews against the blueprint; on failure,
+#                 claude_run fixes findings before codex re-reviews
+#
+# The fix_and_review step is a single unit so findings always feed back
+# into a fix pass before re-review runs. retries: 10 is the iteration cap.
+#
+# Inputs:
+#   task      — what to implement (full task description with file paths, etc.)
+#   blueprint — the feature blueprint to review against (file content or path)
+#
+# Usage:
+#   stratum_plan <this yaml> "review_fix" {"task": "...", "blueprint": "..."}
+
+contracts:
+  ExecuteResult:
+    summary:  {type: string}
+    findings: {type: array}
+
+  ReviewResult:
+    clean:    {type: boolean}
+    summary:  {type: string}
+    findings: {type: array}
+
+functions:
+  execute_task:
+    mode: compute
+    intent: >
+      Call the agent_run MCP tool with type "claude" and the given task prompt.
+      Implement the task fully — write all required files and make all required changes.
+      Return a summary of what was done and an empty findings array.
+      Do not review — only implement.
+    input:
+      task: {type: string}
+    output: ExecuteResult
+    retries: 1
+
+  fix_and_review:
+    mode: compute
+    intent: >
+      Implement one full fix-then-review cycle using the agent_run MCP tool.
+
+      Step A — Fix (skip on first attempt if no prior findings):
+        If this is a retry (previous ensure failed with findings), call agent_run
+        with type "claude". Pass the original task plus the previous findings.
+        Instruct Claude to fix every finding before proceeding.
+
+      Step B — Review:
+        Call agent_run with type "codex" and the following JSON Schema for structured output:
+          {
+            "type": "object",
+            "required": ["clean", "summary", "findings"],
+            "properties": {
+              "clean":    { "type": "boolean" },
+              "summary":  { "type": "string" },
+              "findings": { "type": "array", "items": { "type": "string" } }
+            }
+          }
+        The review prompt must include:
+          - the task description
+          - the execute_summary (what was implemented)
+          - the blueprint content
+          - instruction: "List actionable findings with confidence >= 80.
+            Set clean=true only if no actionable findings remain."
+        Pass the schema to agent_run so it returns structured JSON.
+
+      Return the parsed codex ReviewResult directly.
+      Never re-review without fixing first on a retry.
+    input:
+      task:            {type: string}
+      execute_summary: {type: string}
+      blueprint:       {type: string}
+    output: ReviewResult
+    ensure:
+      - "result.clean == true"
+    retries: 10
+
+flows:
+  review_fix:
+    input:
+      task:      {type: string}
+      blueprint: {type: string}
+    output: ReviewResult
+    steps:
+      - id: execute
+        function: execute_task
+        inputs:
+          task: "$.input.task"
+
+      - id: review
+        function: fix_and_review
+        inputs:
+          task:            "$.input.task"
+          execute_summary: "$.steps.execute.output.summary"
+          blueprint:       "$.input.blueprint"
+        depends_on: [execute]

package/presets/team-feature.stratum.yaml

@@ -0,0 +1,105 @@
+# TEAM PRESET: feature
+#
+# Purpose:     Multi-agent parallel feature implementation
+# Pattern:     Decompose → parallel implement with files_owned → verify
+# Capability:  Orchestrator decomposes, implementers have full access
+# Isolation:   worktree (each task in its own worktree)
+# Merge:       sequential_apply (patches applied in topo order)
+#
+# Use with:    compose build <feature-code> --team feature
+# Customize:   Copy to your project's pipelines/ as team-feature.stratum.yaml and edit.
+
+version: "0.3"
+
+contracts:
+  TaskGraph:
+    tasks:
+      type: array
+      values: [{type: object}]
+  VerifyResult:
+    tests_pass: {type: string}
+    summary: {type: string}
+
+workflow:
+  name: team-feature
+  description: "Multi-agent parallel feature implementation"
+  input:
+    featureCode:
+      type: string
+      required: true
+    description:
+      type: string
+      required: true
+
+flows:
+  team-feature:
+    input:
+      featureCode: {type: string}
+      description: {type: string}
+    output: VerifyResult
+    steps:
+      - id: decompose
+        type: decompose
+        agent: "claude:orchestrator"
+        intent: >
+          Read the feature description and any existing plan/blueprint docs.
+          Break down this feature into parallel implementation tasks.
+          Each task must have:
+          - id: unique short identifier
+          - description: what to implement
+          - files_owned: list of files this task may create or modify
+          - files_read: list of files this task may read but NOT modify
+          - depends_on: list of task ids that must complete first (empty if independent)
+
+          Rules:
+          - No two tasks may share files_owned (each file has exactly one owner)
+          - Minimize dependencies — prefer independent parallel tasks
+          - Each task should be completable in one focused session
+          - Target 2-4 tasks for a typical feature
+        inputs:
+          featureCode: "$.input.featureCode"
+          description: "$.input.description"
+        output_contract: TaskGraph
+        ensure:
+          - "len(result.tasks) >= 1"
+          - "len(result.tasks) <= 6"
+          - "no_file_conflicts(result.tasks)"
+        retries: 2
+
+      - id: execute
+        type: parallel_dispatch
+        source: "$.steps.decompose.output.tasks"
+        agent: "claude:implementer"
+        max_concurrent: 3
+        isolation: worktree
+        require: all
+        merge: sequential_apply
+        intent_template: >
+          Implement this task using TDD. Write the test first, watch it fail,
+          implement, watch it pass.
+
+          Task: {task.description}
+          You own these files (may create/modify): {task.files_owned}
+          You may read (but NOT modify): {task.files_read}
+
+          Feature: {task.id}
+        depends_on: [decompose]
+
+      - id: verify
+        agent: "claude:orchestrator"
+        depends_on: [execute]
+        intent: >
+          All implementation tasks are complete and merged. Run the test suite
+          to verify everything works together. Check that:
+          1. All tests pass
+          2. No merge conflicts remain
+          3. The feature matches the original task description
+
+          Report tests_pass as "true" or "false" with details.
+        inputs:
+          featureCode: "$.input.featureCode"
+        output_contract: VerifyResult
+        ensure:
+          - "result.tests_pass == 'true'"
+          - "result.summary != ''"
+        retries: 2

package/presets/team-research.stratum.yaml

@@ -0,0 +1,108 @@
+# TEAM PRESET: research
+#
+# Purpose:     Parallel exploration for cold-start discovery
+# Pattern:     Triage → parallel_dispatch explorers → synthesize findings
+# Capability:  codebase/docs use read-only-reviewer, web uses read-only-researcher
+# Isolation:   none (read-only exploration)
+# Merge:       Sequential synthesis step
+#
+# Use with:    compose build <feature-code> --team research
+# Customize:   Copy to your project's pipelines/ as team-research.stratum.yaml and edit.
+
+version: "0.3"
+
+contracts:
+  ResearchTaskList:
+    tasks:
+      type: array
+      values: [{type: object}]
+    topic: {type: string}
+  ExplorerFindings:
+    sources: {type: string}
+    patterns: {type: string}
+    open_questions: {type: string}
+  ResearchResult:
+    synthesis: {type: string}
+    recommendations: {type: string}
+    summary: {type: string}
+
+workflow:
+  name: team-research
+  description: "Parallel multi-source research and synthesis"
+  input:
+    featureCode:
+      type: string
+      required: true
+    description:
+      type: string
+      required: true
+
+flows:
+  team-research:
+    input:
+      featureCode: {type: string}
+      description: {type: string}
+    output: ResearchResult
+    steps:
+      - id: plan
+        agent: "claude:orchestrator"
+        intent: >
+          Plan the research for this feature. Read the feature description
+          and any existing docs. Produce a task list with 3 research tasks:
+
+          1. id: "codebase", agent: "claude:read-only-reviewer"
+             - Explore the local codebase for relevant patterns, files, conventions
+          2. id: "web", agent: "claude:read-only-researcher"
+             - Search the web for best practices, library docs, similar implementations
+          3. id: "docs", agent: "claude:read-only-reviewer"
+             - Read local docs, READMEs, specs, ADRs for relevant context
+
+          Each task must have: id, description, agent.
+          Also output the research topic derived from the feature description.
+        inputs:
+          featureCode: "$.input.featureCode"
+          description: "$.input.description"
+        output_contract: ResearchTaskList
+        ensure:
+          - "len(result.tasks) == 3"
+        retries: 2
+
+      - id: explore
+        type: parallel_dispatch
+        source: "$.steps.plan.output.tasks"
+        agent: "claude:read-only-reviewer"
+        max_concurrent: 3
+        isolation: none
+        require: all
+        intent_template: >
+          Research this topic: {task.description}
+
+          Find relevant sources, patterns, and open questions.
+          List sources with file:line references (for code) or URLs (for web).
+          Note patterns that could inform the implementation.
+          List open questions that need answers before implementation.
+        output_fields:
+          sources: {type: string}
+          patterns: {type: string}
+          open_questions: {type: string}
+        ensure:
+          - "result.sources is not None"
+        depends_on: [plan]
+
+      - id: synthesize
+        agent: "claude:orchestrator"
+        depends_on: [explore]
+        intent: >
+          Synthesize findings from all research explorers. Cross-reference
+          sources. Identify consensus patterns and contradictions. Produce
+          actionable recommendations for the feature implementation.
+          Write a one-sentence summary.
+        inputs:
+          research_results: "$.steps.explore.output"
+          topic: "$.steps.plan.output.topic"
+        output_contract: ResearchResult
+        ensure:
+          - "result.synthesis != ''"
+          - "result.recommendations != ''"
+          - "result.summary != ''"
+        retries: 2

package/presets/team-review.stratum.yaml

@@ -0,0 +1,106 @@
+# TEAM PRESET: review
+#
+# Purpose:     Parallel multi-lens review after implementation
+# Pattern:     Triage → parallel_dispatch reviewers → merge findings → gate
+# Capability:  Agents use read-only-reviewer profile (Read/Grep/Glob/Agent only)
+# Isolation:   none (reviewers read shared state, don't modify)
+# Merge:       Deduplication step consolidates findings
+#
+# Use with:    compose build <feature-code> --team review
+# Customize:   Copy to your project's pipelines/ as team-review.stratum.yaml and edit.
+
+version: "0.3"
+
+contracts:
+  TriageResult:
+    tasks:
+      type: array
+      values: [{type: object}]
+    diff: {type: string}
+  MergedReviewResult:
+    findings: {type: string}
+    has_critical: {type: string}
+    summary: {type: string}
+
+workflow:
+  name: team-review
+  description: "Parallel multi-lens code review"
+  input:
+    featureCode:
+      type: string
+      required: true
+    description:
+      type: string
+      required: true
+
+flows:
+  team-review:
+    input:
+      featureCode: {type: string}
+      description: {type: string}
+    output: MergedReviewResult
+    steps:
+      - id: triage
+        agent: "claude:orchestrator"
+        intent: >
+          Gather the git diff for this feature and decide which review lenses
+          to activate. Read the changed files. Produce a task list with one
+          entry per lens. Each task must have:
+          - id: lens name (e.g. "security", "performance", "architecture")
+          - lens_name: same as id
+          - lens_focus: one-sentence description of what to look for
+          - confidence_gate: minimum confidence (1-10) to report a finding
+          - exclusions: what NOT to flag
+
+          Always include: security, performance, architecture.
+          Include the full git diff in your output.
+        inputs:
+          featureCode: "$.input.featureCode"
+          description: "$.input.description"
+        output_contract: TriageResult
+        ensure:
+          - "len(result.tasks) >= 3"
+        retries: 2
+
+      - id: review_lenses
+        type: parallel_dispatch
+        source: "$.steps.triage.output.tasks"
+        agent: "claude:read-only-reviewer"
+        max_concurrent: 4
+        isolation: none
+        require: all
+        intent_template: >
+          You are reviewing a code diff as the {lens_name} reviewer.
+
+          Focus: {lens_focus}
+          Confidence gate: only report findings with confidence >= {confidence_gate}/10.
+          Exclusions: do NOT flag {exclusions}.
+
+          Return JSON: { "clean": boolean, "findings": LensFinding[] }
+          where each finding has: lens, file, line, severity (must-fix|should-fix|nit),
+          finding (description), confidence (1-10).
+
+          If no issues found, return { "clean": true, "findings": [] }.
+        output_fields:
+          clean: {type: string}
+          findings: {type: string}
+        ensure:
+          - "result.findings is not None"
+        depends_on: [triage]
+
+      - id: merge
+        agent: "claude:orchestrator"
+        depends_on: [review_lenses]
+        intent: >
+          Consolidate findings from all review lenses. Deduplicate findings
+          that appear in multiple passes (same file:line, same issue). Rank
+          by severity (must-fix first, then should-fix, then nit).
+          Set has_critical to "true" if any finding has severity "must-fix",
+          "false" otherwise. Write a one-sentence summary.
+        inputs:
+          review_results: "$.steps.review_lenses.output"
+        output_contract: MergedReviewResult
+        ensure:
+          - "result.has_critical == 'false'"
+          - "result.summary != ''"
+        retries: 2