blueprint-research

Blueprint Research

Handles the research phase of the blueprint workflow: Toolbox resolution, lessons discovery, local/external research decision, and spec review.

Input

feature_description: string
tech_stack: string | string[]  # From config-reader
discovery_result:
  user_familiarity: high | medium | low  # Do they know the codebase?
  user_intent: speed | thoroughness      # What matters more?
  topic_risk: high | medium | low        # Security, payments, external APIs?
  uncertainty_level: high | medium | low # Is the approach clear?

1. Resolve Toolbox + Discover Lessons

Read config (parallel):

config_read("tech_stack", "generic")
config_read("lessons_path", ".agents/lessons/")

Spawn agents (parallel):

Task(majestic-engineer:workflow:toolbox-resolver):
  prompt: "Stage: blueprint | Tech Stack: {tech_stack}"

Task(majestic-engineer:workflow:lessons-discoverer):
  prompt: "workflow_phase: planning | tech_stack: {tech_stack} | task: {feature_description}"

Store outputs:

• research_hooks → for Step 4 (external research)
• coding_styles → for Step 5 (skill injection)
• lessons_context → for architect agent

Non-blocking errors:

• No toolbox found → Continue with core agents
• Lessons directory missing → Continue
• Discovery returns 0 lessons → Log, continue
• Discovery fails → Log warning, continue

2. Local Research (Always Runs)

Fast, local research to understand codebase patterns before deciding on external research.

Task(majestic-engineer:research:git-researcher, prompt="{feature}")
Task(majestic-engineer:research:repo-analyst, prompt="{feature}")

Store: local_findings - patterns, conventions, similar implementations

3. Research Decision

Based on discovery signals + local findings, decide if external research adds value.

Decision matrix:

Condition	External Research
topic_risk: high (security, payments, external APIs)	Always - cost of missing something too high
local_findings has strong patterns + user_familiarity: high	Skip - codebase is authoritative
uncertainty_level: high OR user_familiarity: low	Research - external perspective valuable
user_intent: speed + adequate local patterns	Skip - optimize for velocity
Default (no strong signal)	Research - err on side of thoroughness

research_decision = evaluate(discovery_result, local_findings)
  → SKIP_EXTERNAL | RUN_EXTERNAL

If research_decision == SKIP_EXTERNAL:
  Announce: "Codebase has solid patterns for this. Proceeding without external research."
Else:
  Announce: "Running external research for {reason}."

4. External Research (Conditional)

Only runs if research_decision == RUN_EXTERNAL

Task(majestic-engineer:research:docs-researcher, prompt="{feature}")
Task(majestic-engineer:research:best-practices-researcher, prompt="{feature}")

Stack-specific agents (from toolbox):

For each hook in research_hooks:
  If hook.triggers.any_substring matches feature_description:
    Task(subagent_type=hook.agent, prompt="{feature} | Context: {hook.context}")

Cap: Maximum 4 external agents to avoid noise.

Wait: Collect all results before proceeding.

5. Spec Review + Skill Injection

Run in parallel:

Apply spec-reviewer skill:
  context: "Feature: {feature} | Research: {combined_research}"

For each skill in coding_styles:
  Skill(skill: skill)

Outputs:

• spec_findings → gaps, edge cases, questions
• skill_content → loaded coding style content

Output

research_result:
  toolbox:
    research_hooks: array
    coding_styles: array
  lessons_context: string | null
  research_decision: SKIP_EXTERNAL | RUN_EXTERNAL
  research_decision_reason: string
  research_findings:
    local:
      git: string
      repo: string
    external:              # null if research_decision == SKIP_EXTERNAL
      docs: string | null
      best_practices: string | null
      stack_specific: array | null
  spec_findings:
    gaps: array
    edge_cases: array
    questions: array
  skill_content: string
  ready_for_architecture: boolean