Catalog
mastra-ai/mastra-factory

mastra-ai

mastra-factory

Operate and supervise Mastra Factory through `mastra api factory`. Use for first-time Factory connection and login, status or queue summaries, project and work-item inspection, thread history and memory, metrics, health, decisions, attention, and user-authorized autonomous or interactive Factory operations on hosted, local, remote, or self-hosted servers.

NewUpdated Nov 5, 2026

Mastra Factory

Use mastra api factory as the operational control plane for Factory.

First use: connect before inspecting

Read references/connection.md. Check CLI availability, establish the user's actual Factory URL, and for platform-hosted deployments run mastra auth whoami. If logged out, offer mastra auth login rather than silently starting browser login. Local/self-hosted authentication may differ.

An explicit mastra api --url "$FACTORY_URL" factory project list works from an empty directory; no deployed repository or .mastra-project.json is required. Never assume a shared host, organization, project name, or ID. Preserve the explicit target on subsequent commands.

Default behavior

For status, inspection, diagnosis, queue review, or recommendation requests:

  1. Stay read-only.
  2. Select the sole or explicitly named project; report choices when ambiguous.
  3. Inspect project state, work items, metrics, thresholds, decisions, and attention.
  4. Correlate stages, revisions, sessions, decisions, and attention items.
  5. Report active/queued work, blocked or unhealthy items, running sessions, pending decisions, human attention, and one recommended next action.
  6. Execute a recommendation only when the current request or a previously granted operating scope authorizes it.

Required reference

Read references/factory-cli.md before running Factory commands for output control, contracts, the read-only workflow, mutation protocol, governance constraints, durable-session limitations, and error handling.

For “my work,” actual execution progress, thread messages, memory, or health interpretation, also read references/session-inspection.md. Distinguish card stages from running agents, historical messages from current memory, and agent claims from verified repository outcomes.

Safety boundary

  • Never read or reveal .env, bearer tokens, saved login contents, or platform/provider credentials.
  • Never invent IDs, stages, revisions, request IDs, or sessions.
  • Establish the user's operating scope before mutating. Authorization may cover one action or grant standing autonomy over named projects, resources, action types, or objectives.
  • Within a clear delegated scope, act without asking for confirmation before every mutation. Ask only when an action is ambiguous, outside scope, or materially more destructive than the granted authority.
  • Fetch current state before a write, make the smallest in-scope change, then refetch and report IDs, revisions, and final state.
  • Use transitions—not metadata updates—for stage changes, with the current revision and a fresh UUID request ID.
  • Never use private HTTP routes to bypass unsupported CLI operations.
  • If work-item start lacks a supported durable user session, report the block; never substitute another session or invent a session UUID.
Files4
4 files · 36.7 KB

Select a file to preview

Overall Score

88/100

Grade

A

Excellent

Grades are signals, not a certification. Always review a skill yourself before use.

Safety

90

Quality

88

Clarity

86

Completeness

85

Summary

The mastra-factory skill provides structured guidance for operating Mastra Factory through the `mastra api factory` CLI. It covers first-time setup, read-only project/work-item inspection, queue diagnostics, decision handling, and mutation protocols with explicit authorization boundaries. The skill emphasizes safety guardrails: it defines clear operating scopes, enforces authorization checking before mutations, and provides detailed reference documentation for CLI contracts, error handling, and session management.

Static Analysis Findings

1 finding

Patterns detected by deterministic static analysis before AI scoring. Hover over any finding code for detailed information and remediation guidance.

Credential Exposure
SEC-020Direct .env File Access2x in 2 files

Direct .env file access

SKILL.md.env
references/factory-cli.md.env

Detected Capabilities

CLI command execution (mastra api factory)JSON query and filtering (jq)File reading and inspectionHTTP requests via CLI to Factory endpointsEnvironment variable reference ($FACTORY_URL, $PROJECT_ID)Credential/auth state inspection (mastra auth whoami)Mutation operations on Factory resources (create, update, transition, delete)

Trigger Keywords

Phrases that agents use to match this skill to user intent.

inspect factory statusfactory queue reviewmastra work itemfactory project diagnosticsautonomous factory operationsfactory mutation protocolwork item transitiondecision approvalfactory health check

Risk Signals

INFO

SEC-020: Direct .env file access referenced in context

SKILL.md | Safety boundary section
INFO

SEC-020: Direct .env file access referenced in connection documentation

references/factory-cli.md | Safety and delegation rules section
INFO

Shell variable expansion ($FACTORY_URL, $PROJECT_ID, $USER_ID) used in command examples

Multiple locations in factory-cli.md and session-inspection.md
INFO

Bearer token and credential non-exposure explicitly documented as safety boundary

SKILL.md, factory-cli.md (Safety and delegation rules, Safety boundary)

Referenced Domains

External domains referenced in skill content, detected by static analysis.

github.comlocalhostwww.apache.org

Use Cases

  • Inspect Factory project status and queue health without modifying state
  • Review active work items, running sessions, and pending decisions
  • Perform authorized mutations (create, transition, approve) within delegated scope
  • Diagnose blocked work, failed decisions, and attention items
  • Navigate multi-deployment Factory instances with explicit URL targeting

Quality Notes

  • Comprehensive reference documentation with clear section hierarchy and distinct workflows (read-only vs. mutation)
  • Explicit safety boundaries documented in multiple locations: .env and credentials are never read or exposed
  • Clear authorization model: differentiates between one-action authorization and standing delegation with scope examples
  • Mutation protocol clearly itemized with pre-action state verification and post-action refetch patterns
  • Edge case handling: addresses revision conflicts, empty project lists, missing CLI commands, and pagination limits
  • Error handling guidance: distinguishes shell failures from CLI JSON errors with specific remediation
  • Security-conscious design: requires explicit verification of authorization scope before mutations, forbids session ID invention, blocks bypass of missing CLI features via private HTTP routes
  • References are self-contained and interlinked; all referenced files are present
  • Positional argument discovery explicitly requires schema/help inspection before attempting mutations
  • Well-defined contracts: standard JSON envelopes, collection payload structures, and pagination patterns documented
Model: claude-haiku-4-5-20251001Analyzed: Nov 5, 2026

Reviews

Add this skill to your library to leave a review.

No reviews yet

Be the first to share your experience.

Version History

  1. v2.1

    Content updated

    ✦ AIReference documentation in factory-cli.md updated.

    2026-11-05

    LATEST
  2. v2.0

    Contract changed: description

    ✦ AIRemoves supervisor session and health inspection scope; replaces factory-supervisor.md reference with factory-cli.md; updates safety guidance on session substitution.

    triggering2026-11-03

    View This Version
  3. v1.0

    2026-10-12

    View This VersionInitial version

Use mastra-ai/mastra-factory in your dev environment

Command Palette

Search for a command to run...