Frame

Frame Skill

You are invoked by the workflow-manager agent and receive full workflow context. You execute Frame phase operations by reading workflow steps from workflow/basic.md and using deterministic scripts.

1. Complete Execution

   • ALWAYS execute all workflow steps completely
   • ALWAYS fetch work item before proceeding
   • ALWAYS classify work type accurately
   • NEVER skip environment setup steps

2. State Management

   • ALWAYS update session state after major operations
   • ALWAYS record Frame results in session
   • ALWAYS post status notifications
   • NEVER lose work item information

3. Work Item Integration

   • ALWAYS use work-manager agent for work item operations
   • ALWAYS validate work item exists before proceeding
   • ALWAYS extract complete work item details
   • NEVER proceed with invalid work items

4. Environment Setup

   • ALWAYS prepare domain-specific environment
   • ALWAYS create branch for work (if applicable)
   • ALWAYS validate environment readiness
   • NEVER leave environment in incomplete state

5. Error Handling

   • ALWAYS catch and report errors clearly
   • ALWAYS update session with error state
   • ALWAYS post failure notifications
   • NEVER continue after unrecoverable errors

Required Parameters:

• operation: "execute_frame"
• work_id (string): FABER work identifier
• source_type (string): Issue tracker (github, jira, linear, manual)
• source_id (string): External issue ID
• work_domain (string): Domain (engineering, design, writing, data)

Context Provided:

{
  "work_id": "abc12345",
  "source_type": "github",
  "source_id": "123",
  "work_domain": "engineering",
  "autonomy": "guarded"
}

Frame is the first phase, so no previous phase context is available.

Step 1: Output Start Message

🎯 STARTING: Frame Skill
Work ID: {work_id}
Source: {source_type}/{source_id}
Domain: {work_domain}
───────────────────────────────────────

Step 2: Load Workflow Implementation

Read the workflow implementation from workflow/basic.md:

WORKFLOW_FILE="$SKILL_DIR/workflow/basic.md"

if [ ! -f "$WORKFLOW_FILE" ]; then
    echo "Error: Workflow file not found: $WORKFLOW_FILE"
    exit 1
fi

# The workflow file contains the implementation steps
# Read and execute according to workflow/basic.md

Step 3: Execute Workflow Steps

Execute all steps defined in workflow/basic.md:

1. Fetch Work Item - Use work-manager agent to retrieve work item
2. Classify Work Type - Determine work type (/bug, /feature, /chore, /patch)
3. Post Frame Start - Notify work tracking system
4. Setup Environment - Prepare domain-specific workspace
5. Update Session - Record Frame results
6. Post Frame Complete - Notify completion

See workflow/basic.md for detailed implementation.

Step 4: Validate Results

Ensure all Frame operations completed successfully:

# Verify work item was fetched
if [ -z "$WORK_ITEM_TITLE" ]; then
    echo "Error: Failed to fetch work item"
    exit 1
fi

# Verify work type was classified
if [ -z "$WORK_TYPE" ]; then
    echo "Error: Failed to classify work type"
    exit 1
fi

# Verify environment was prepared
if [ -z "$BRANCH_NAME" ]; then
    echo "Warning: No branch created (may be intentional for some domains)"
fi

Step 5: Output Completion Message

✅ COMPLETED: Frame Skill
Work Type: {work_type}
Branch: {branch_name}
Environment: Ready
───────────────────────────────────────
Next: Architect phase will generate specification

See: plugins/faber/docs/RESPONSE-FORMAT.md for complete specification.

Success Response:

{
  "status": "success",
  "message": "Frame phase completed - work item fetched and environment prepared",
  "details": {
    "phase": "frame",
    "work_type": "/feature",
    "work_item": {
      "title": "Add export feature",
      "description": "Users should be able to export data...",
      "labels": ["feature", "enhancement"]
    },
    "environment": {
      "branch_name": "feat/123-add-export",
      "worktree_path": "/path/to/worktree",
      "ready": true
    }
  }
}

Warning Response (environment setup had minor issues):

{
  "status": "warning",
  "message": "Frame phase completed with warnings",
  "details": {
    "phase": "frame",
    "work_type": "/feature",
    "work_item": {...}
  },
  "warnings": [
    "Branch already exists, using existing branch",
    "Optional dependency 'foo' not installed"
  ],
  "warning_analysis": "The work can proceed but some optional features may not be available",
  "suggested_fixes": [
    "Run 'npm install foo' to enable optional features"
  ]
}

Failure Response:

{
  "status": "failure",
  "message": "Frame phase failed - could not fetch work item",
  "details": {
    "phase": "frame"
  },
  "errors": [
    "Work item #123 not found in GitHub Issues",
    "HTTP 404: Resource not found"
  ],
  "error_analysis": "The specified issue ID does not exist or you may not have permission to access it",
  "suggested_fixes": [
    "Verify the issue ID is correct",
    "Check that you have access to the repository",
    "Ensure GitHub token has 'issues:read' scope"
  ]
}

• workflow/basic.md - Default Frame implementation (batteries-included)

Domain plugins can override by providing:

• workflow/{domain}.md - Domain-specific Frame workflow

The workflow is selected based on configuration or defaults to basic.md.

1. State Updates - Frame results stored in .fractary/plugins/faber/state.json
2. Status Notifications - Start/complete posted to work tracking system
3. Console Output - Detailed execution log
4. Environment Artifacts - Branch, worktree, allocated resources

All documentation is created during execution - no separate step required.

Work Item Not Found (Exit Code 1)

Cause: Invalid source_id or work tracking system unavailable Action: Update session with error, post notification, exit

Classification Failed (Exit Code 1)

Cause: No labels or unclear work item description Action: Default to /feature, post warning, continue

Environment Setup Failed (Exit Code 1)

Cause: Missing dependencies or resource constraints Action: Update session with error, post notification, exit

Session Update Failed (Exit Code 1)

Cause: Invalid session file or permission issues Action: Log error, attempt retry, exit if persistent

Integration

Invoked By:

• workflow-manager agent (during Frame phase execution)

Invokes:

• work-manager agent (fetch and classify work items)
• repo-manager agent (create branch, if applicable)
• core-skill scripts (session management, status cards)

Workflow Files:

• workflow/basic.md - Default implementation

Scripts:

• scripts/ - Deterministic operations (if needed)

Configuration Support

Frame skill respects configuration:

[workflow.skills]
frame = "fractary-faber:frame"  # Use built-in

# Or domain override:
# frame = "fractary-faber-app:frame"  # Use domain-specific

State Fields Updated

Frame skill updates these session fields:

{
  "stages": {
    "frame": {
      "status": "completed",
      "data": {
        "work_type": "/feature",
        "title": "Add export feature",
        "description": "...",
        "labels": ["feature"],
        "branch_name": "feat/123-add-export",
        "worktree_path": "/path/to/worktree"
      }
    }
  }
}

Best Practices

1. Always fetch work item first - Don't rely on cached data
2. Classify accurately - Proper classification ensures correct workflow
3. Prepare environment completely - All resources ready before Architect
4. Update session frequently - Save progress at each step
5. Post clear notifications - Keep stakeholders informed
6. Handle errors gracefully - Clean up and report failures

Domain-Specific Behavior

Engineering Domain

• Creates git branch
• Allocates ports (if needed)
• Installs dependencies
• Prepares database

Design Domain (Future)

• Creates design workspace
• Loads design templates
• Prepares asset directories

Writing Domain (Future)

• Creates document workspace
• Loads style guides
• Prepares references

Data Domain (Future)

• Creates data workspace
• Loads data sources
• Prepares analysis environment

This Frame skill provides the first phase of FABER workflows, ensuring consistent work item intake and environment preparation across all domains.