Target Matcher

Target Matcher Skill

When a user runs /fractary-faber:plan <target> without a --work-id, this skill determines what type of entity the target represents and retrieves associated metadata.

Step 1: Execute Target Matching

Run the match-target.sh script:

plugins/faber/skills/target-matcher/scripts/match-target.sh \
  "$TARGET" \
  --config "$CONFIG_PATH" \
  --project-root "$PROJECT_ROOT"

Step 2: Parse Result

The script returns JSON with:

• status: "success", "no_match", or "error"
• match: The matched target definition with metadata
• all_matches: All matching definitions (for debugging)
• message: Human-readable result message

Step 3: Return Target Context

Return the match result for use by the planner.

Supported Patterns

The matcher supports glob patterns:

• * - Matches anything except /
• ** - Matches any number of path segments
• ? - Matches single character
• [abc] - Character class

Examples:

Specificity Rules

When multiple patterns match, specificity determines the winner:

Scoring Formula:

score = (literal_prefix_length * 100) - (wildcard_count * 10) - definition_index

Example:

• src/auth/** → prefix=9, wildcards=1, index=0 → score=890
• src/** → prefix=4, wildcards=1, index=1 → score=389
• Winner: src/auth/** (higher score)

Tie-Breaking: If two patterns have identical scores, the first defined pattern wins. A warning is logged about the ambiguity.

Success Match

{
  "status": "success",
  "input": "ipeds/admissions",
  "match": {
    "name": "ipeds-datasets",
    "pattern": "ipeds/*",
    "type": "dataset",
    "description": "IPEDS education datasets for ETL processing",
    "metadata": {
      "entity_type": "dataset",
      "processing_type": "etl",
      "expected_artifacts": ["processed_data", "validation_report"]
    },
    "workflow_override": null,
    "score": 490,
    "specificity": {
      "literal_prefix_length": 5,
      "wildcard_count": 1,
      "definition_index": 0
    }
  },
  "all_matches": [...],
  "message": "Matched 'ipeds/admissions' to 'ipeds-datasets'"
}

No Match (with default)

{
  "status": "no_match",
  "input": "unknown/path",
  "match": {
    "name": null,
    "pattern": null,
    "type": "file",
    "description": "Default target type (no pattern matched)",
    "metadata": {},
    "workflow_override": null
  },
  "all_matches": [],
  "message": "No pattern matched 'unknown/path', using default type 'file'"
}

Error (require_match=true)

{
  "status": "error",
  "input": "unknown/path",
  "match": null,
  "all_matches": [],
  "message": "No target definition matches 'unknown/path'. Configure targets in .fractary/plugins/faber/config.json"
}

Used By

• faber-planner agent - To resolve target context before creating plans

Configuration

Targets are configured in .fractary/plugins/faber/config.json:

{
  "targets": {
    "definitions": [
      {
        "name": "ipeds-datasets",
        "pattern": "ipeds/*",
        "type": "dataset",
        "description": "IPEDS education datasets",
        "metadata": {
          "entity_type": "dataset",
          "processing_type": "etl"
        }
      }
    ],
    "default_type": "file",
    "require_match": false
  }
}

See the config schema at plugins/faber/config/config.schema.json for full documentation.