Handling Conflicting Pre-Flight Signals in Hallmark: Protocol and Implementation

Hallmark resolves conflicting pre-flight signals through a deterministic prioritization system that ranks explicit user commands above detected project artifacts and implicit defaults, automatically handling clear overrides while prompting users for ambiguous conflicts.

Hallmark, an open-source design automation toolkit from Nutlope/hallmark, begins every session with a comprehensive pre-flight scan of your project files. When this scan encounters conflicting signals—such as multiple CSS frameworks or contradictory configuration directives—it follows a strict protocol defined in skills/hallmark/SKILL.md to determine the correct path forward without making assumptions about developer intent.

Signal Prioritization Hierarchy

The pre-flight protocol organizes all detected signals into three distinct priority tiers. This hierarchy is defined in the pre-flight block specification within skills/hallmark/SKILL.md (lines 178‑191).

Explicit user commands receive the highest priority. These include direct instructions such as "ignore the existing project" or flags that force specific behaviors regardless of detected files.

Detected project artifacts occupy the middle tier. These encompass actual files discovered during the scan, such as tailwind.config.js, package.json configurations, or existing CSS frameworks.

Implicit defaults hold the lowest priority. These represent the absence of configuration or generic baseline assumptions that apply only when no higher-priority signals exist.

Automatic Resolution for Clear Conflicts

When a higher-priority signal unambiguously overrides a lower-priority one, Hallmark adopts the higher-priority setting and silently discards the conflicting signal. This automatic resolution requires no user intervention.

For example, if the user explicitly asks to "ignore the existing project," Hallmark skips the entire pre-flight scan regardless of any detected configs like Tailwind or Bootstrap files. This override behavior is documented in skills/hallmark/SKILL.md (lines 190‑191).

User Prompting for Ambiguous Conflicts

Equal-priority conflicts trigger an interactive resolution process. When the scan detects signals of the same tier that contradict each other—such as two different CSS frameworks or clashing design systems—Hallmark presents a prompt immediately after the pre-flight block.

The model always asks before proceeding with equal-priority conflicts, ensuring no assumptions are made about developer intent. This requirement is captured in skills/hallmark/SKILL.md (lines 211‑213) and implemented in site/js/main.js, which handles the runtime pre-flight UI.

Fallback Behavior and Caching

Neutral Fallback State

If the scan cannot resolve a conflict due to missing information for both options, Hallmark falls back to a neutral pre-flight message: "No pre‑flight signals — proceeding with full Hallmark stack." This default case is defined in skills/hallmark/SKILL.md (lines 187‑188) and demonstrated in test briefs such as site/_tests/01‑tide‑podcast/brief.md (line 9).

Cached Decision Reuse

Once a conflict is resolved, the chosen outcome is cached for subsequent runs. The system reuses this cached decision unless the user explicitly requests a "refresh pre-flight" or "scan again" command. The cache-reuse behavior is explained in skills/hallmark/SKILL.md (lines 181‑184), preventing redundant prompts for recurring project configurations.

Code Implementation

The conflict detection and resolution logic appears throughout the Hallmark codebase. The pre-flight questions that drive signal detection are defined in skills/hallmark/references/hero-enrichment.md.

Below are illustrative implementations showing framework conflict detection and resolution handling:

// src/preflight.js – Detect conflicting frameworks
function detectFrameworks(files) {
  const hasTailwind = files.some(f => /tailwind\.config\./.test(f));
  const hasBootstrap = files.some(f => /bootstrap\.css/.test(f));
  if (hasTailwind && hasBootstrap) {
    return { conflict: true, types: ['tailwind', 'bootstrap'] };
  }
  return { conflict: false, types: hasTailwind ? ['tailwind'] : [] };
}

// src/flow.js – Resolve conflict according to priority
async function handlePreflight(context) {
  const result = detectFrameworks(context.projectFiles);
  if (result.conflict) {
    // Ask the user which framework to keep
    const choice = await askUser(
      `We detected both Tailwind and Bootstrap. Which would you like to use?`,
      ['Tailwind', 'Bootstrap']
    );
    context.selectedFramework = choice.toLowerCase();
  } else {
    context.selectedFramework = result.types[0] || 'none';
  }
}

Summary

• Hallmark uses a three-tier prioritization system (explicit commands > detected artifacts > defaults) defined in SKILL.md to handle conflicting pre-flight signals.
• Clear hierarchical conflicts are resolved automatically without user input, with higher-priority signals overriding lower ones.
• Ambiguous equal-priority conflicts always trigger user prompts to prevent incorrect assumptions, as required by the protocol in SKILL.md lines 211‑213.
• A neutral fallback message appears when no signals are detectable, ensuring the system proceeds safely with the full Hallmark stack.
• Cached resolutions persist across sessions unless explicitly refreshed, optimizing the pre-flight workflow for repeated runs.

Frequently Asked Questions

What triggers a conflicting pre-flight signal in Hallmark?

A conflict occurs when the pre-flight scan detects contradictory indicators in your project files, such as two different CSS frameworks (Tailwind and Bootstrap), an existing Tailwind theme that clashes with a user-provided design system, or simultaneous "use existing project" and "start from scratch" directives.

How does Hallmark prioritize different signal sources?

According to the protocol in skills/hallmark/SKILL.md, Hallmark prioritizes signals in three tiers: explicit user commands have the highest priority, detected project artifacts like configuration files are secondary, and implicit defaults have the lowest priority. This hierarchy determines whether conflicts are resolved automatically or require user input.

Does Hallmark cache pre-flight conflict resolutions?

Yes, once you resolve a conflict, Hallmark caches that decision. Subsequent runs reuse the cached resolution unless you explicitly request a "refresh pre-flight" or "scan again" command, as documented in skills/hallmark/SKILL.md (lines 181‑184).

What happens when Hallmark cannot detect any pre-flight signals?

When the scan finds no discernible signals or cannot resolve a conflict due to missing information, Hallmark displays a neutral fallback message: "No pre-flight signals — proceeding with full Hallmark stack." This default behavior ensures the system continues safely without making unsupported assumptions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}