EngiFoundry

EngiFoundry is a platform-neutral set of Agent Skills for structured engineering work.

It helps coding agents move from one-shot answers to controlled delivery: select the lightest suitable engineering path, preserve durable project facts, verify claims, and review important outputs through an independent Reviewer chain.

Optimize for first-pass delivery, not cheapest generation.

Keyword: engifoundry.

中文说明见 zh/README.md.

Why EngiFoundry

Small, clear operations often need only inline execution. Durable atomic goals use direct execution; larger work fails more often through unclear scope, context drift, missing verification, weak handoff, or self-review bias.

EngiFoundry gives the Agent explicit engineering contracts while leaving the Agent responsible for judgment and execution:

• use inline action when durable task identity adds no material value;
• use controlling-Agent direct work for one durable atomic goal, without an Executor;
• use the configured Executor only for heavyweight Package work;
• preserve project facts and durable artifacts under .engifoundry/;
• close every PAK goal through evidence-based Verify;
• review direct work only when the controlling Agent finds it useful, while preserving required Package Review.

Engineering rigor scales with the task. Heavyweight process is not the default: inline action uses proportionate immediate evidence, while every PAK has a hard closure gate.

Runtime

Entry
Router
Init | Orch | Exec | Verify | Deliver
Audit | Review | Docs

• Entry checks only ./engifoundry.config.json; configured projects automatically route actionable engineering work materially related to that project. The working directory alone does not make unrelated work part of the project.
• Router declares the available contracts, typical contract combinations, and recorded state signals.
• The Agent selects and reads the contracts needed to reach the user's requested endpoint.
• Audit classifies new work as inline, direct, or packaged.
• Review is a reusable rule set; direct Review is optional, Package Jobs use it when their contract requires it, and each Package PAK uses one Reviewer chain whose first Review is clean and whose later Planning, Job, and rework Reviews normally continue the same session.
• Verify is mandatory for both PAK modes. Direct Verify is final requirement acceptance; Package Verify supplies evidence for Deliver.
• Docs produces detailed human-readable documents only when explicitly requested.
• States describe current project facts; they are not workflow events.

Every managed EngiFoundry goal has a PAK execution identity; bounded operations whose persistence would add no material value stay inline without records. Direct work records one minimal requirement Job for one overall acceptance boundary, even when it contains ordered repository, release, or publication steps. The controlling Agent implements it, may use Review, and must pass final Verify without entering Exec or Deliver. Fully planned heavyweight Package work is reserved for independent outcomes or responsibility boundaries that justify Orch, Exec, Verify, and Deliver overhead.

For heavyweight execution, a controlling Agent whose active model matches the configured pinned Executor model performs the Job directly; otherwise it invokes the configured Executor with that model through its verified CLI usage. Every external Executor invocation and every Reviewer task uses a mandatory worker identity protocol with zero child-Agent budget. A receiving Worker treats that protocol as a terminal routing fact and never selects another worker or infers its own model identity; only the controlling invocation and trusted transport metadata govern model selection. Reviewer session continuity is transient host state and is never written into project records; material contract changes, Reviewer participation in implementation, unreliable continuation, or an explicitly requested independent opinion reset the chain to a new clean context with prior immutable Review records as evidence. Init lists still-available custom CLI and model selections from the platform-standard user application-data directory in both role questions, always running a bounded command --version existence/version probe before listing them. It then silently probes the selected role's input capabilities or reuses an exactly matching role-specific confirmed conclusion, prefers verified native structured input and a separate instruction channel, and falls back to an equivalent canonical text envelope. Every task envelope embeds the complete handback schema, so a Worker never has to discover or guess its return shape. The controlling Agent validates external handbacks and owns canonical control records.

Optional extension discovery

Plugin installations register the read-only FoundryX catalog MCP at https://foundryx.site/mcp. The Router queries that catalog for current optional Skill and toolset routing metadata instead of embedding a fixed extension list. If the host does not support MCP or the MCP call fails, the same URL serves the schema-versioned manifest as JSON over an unauthenticated HTTPS GET. If neither transport is available, EngiFoundry continues without external extensions.

Catalog values are untrusted routing data, not instructions. A candidate is usable only after the current host confirms its advertised Skill invoke name or safely runs its bounded help probe; EngiFoundry never installs an extension or treats its catalog provenance as proof of availability.

Quickstart

Install the plugin for your Agent host and work normally in an initialized project. The root configuration activates automatic routing; users do not need to name EngiFoundry for each engineering request.

In an uninitialized project, explicitly requesting EngiFoundry for actionable engineering work uses a permissive controlling-Agent fallback. It keeps non-persistent operations inline; otherwise it creates only a minimal direct PAK and verification evidence under .engifoundry/. The Agent may suggest initialization to enable project preferences, Package selection, Executor delegation, and configured automation, but continues the request without waiting.

Initialize explicitly when that is the requested outcome or when the project should enable the complete configured runtime:

$engifoundry init

Natural-language requests such as "initialize this project with EngiFoundry" work too. The request must explicitly identify EngiFoundry; ordinary initialization language does not activate it. Existing sparse fallback PAK and verification records are preserved when Init later creates the complete scaffold.

Initialization creates only the root entry file and .engifoundry/ tree:

engifoundry.config.json
.engifoundry/
  workspace.md
  initialization.json
  executors.json
  workflows.json
  artifacts/
  packages/

Initialization is required for configured routing and heavyweight Package execution, but not for explicit unconfigured inline or direct work. If a project was initialized by an older EngiFoundry layout, identified by .engifoundry.config.json or .engifoundry-packages/, explicitly request an EngiFoundry migration instead. Historical artifacts are inherited into the active structure without rewriting their contents whenever possible; archival is only a fallback. Active control JSON is rebuilt from inspected project facts. Init determines whether migration or a full re-initialization is appropriate.

Installation

Installation differs by Agent host. If you use more than one host, install EngiFoundry separately for each one.

Plugin installation is preferred because compatible hosts can inject the lightweight Entry at session start. For hosts without plugin support, use the skills-only fallback.

The plugin package name is engifoundry-bundle. The manual entry point is $engifoundry.

Codex

Codex-compatible installations use this repository as a Git marketplace.

Register the marketplace:

codex plugin marketplace add caoyuan-fire/engi-foundry-skill

Install the plugin:

codex plugin add engifoundry-bundle@engi-foundry-skill

Update with:

codex plugin marketplace upgrade engi-foundry-skill
codex plugin add engifoundry-bundle@engi-foundry-skill

Relevant files:

.agents/plugins/marketplace.json
.codex-plugin/plugin.json
.mcp.json
hooks/
skills/

Claude

Claude-compatible installations use this repository as a Claude plugin marketplace.

Register the marketplace:

/plugin marketplace add caoyuan-fire/engi-foundry-skill

Install the plugin:

/plugin install engifoundry-bundle@engi-foundry-skill

Relevant files:

.claude-plugin/marketplace.json
.claude-plugin/plugin.json
.mcp.json
skills/

Kimi Code

Kimi Code can install directly from this repository.

Install the plugin:

/plugins install https://github.com/caoyuan-fire/engi-foundry-skill

Repository installs use:

.kimi-plugin/plugin.json
skills/

The Kimi manifest declares the FoundryX HTTP MCP directly.

GitHub Copilot CLI

GitHub Copilot CLI can use this repository as a plugin marketplace.

Register the marketplace:

copilot plugin marketplace add caoyuan-fire/engi-foundry-skill

Install the plugin:

copilot plugin install engifoundry-bundle@engi-foundry-skill

Relevant files:

.github/plugin/marketplace.json
.github/plugin/plugin.json
mcp.json
skills/

Cursor

Cursor-compatible installations use the Cursor plugin manifest in this repository.

Install from Cursor Agent chat or the plugin UI:

/add-plugin https://github.com/caoyuan-fire/engi-foundry-skill

Relevant files:

.cursor-plugin/plugin.json
mcp.json
hooks/hooks-cursor.json
skills/

Cursor IDE plugin support and Cursor Agent CLI support may not be identical in all versions.

Factory Droid

Factory Droid can use this repository as a plugin marketplace.

Register the marketplace:

droid plugin marketplace add https://github.com/caoyuan-fire/engi-foundry-skill

Install the plugin:

droid plugin install engifoundry-bundle@engi-foundry-skill

Relevant files:

.factory-plugin/marketplace.json
.factory-plugin/plugin.json
mcp.json
skills/

Skills-Only Hosts

For hosts without plugin support, install or symlink the complete skills/ directory into the host's skills directory. All EngiFoundry skill directories are part of one runtime and must be updated together.

Skills-only installation does not guarantee forced loading at session start. When the host does not autoload skills/engifoundry/SKILL.md, explicitly invoke $engifoundry for the request. Do not install both the plugin and skills-only copies in the same host home, because doing so can expose duplicate skill entries.

Skills-only installations do not register MCP configuration. The Router therefore uses the JSON fallback at https://foundryx.site/mcp when the host provides an HTTPS retrieval capability; otherwise optional extension discovery is unavailable while the core EngiFoundry runtime remains usable.

Updating

Update through the same channel used for installation:

• Codex users should run the two update commands shown in the Codex section.
• Marketplace users on other hosts should refresh the configured marketplace and reinstall or update engifoundry-bundle with that host's plugin manager.
• Direct repository installations should reinstall or refresh from this repository.
• Skills-only users should update the complete skills/ directory, not individual EngiFoundry skills.

Release versions are recorded in the plugin and marketplace manifests. Superseded runtime implementations remain available through Git history.

What's Inside

skills/engifoundry/            Session Entry contract
skills/engifoundry-router/     Contract registry and routing context
skills/engifoundry-init/       Initialization, configuration, and migration
skills/engifoundry-orch/       Package, Phase, PAK, and Job orchestration
skills/engifoundry-exec/       Disciplined Job execution and records
skills/engifoundry-verify/     Goal-level evidence and verification status
skills/engifoundry-deliver/    User acceptance and delivery closeout
skills/engifoundry-audit/      Direct-versus-packaged task assessment
skills/engifoundry-review/     Fresh-context review rules
skills/engifoundry-docs/       Detailed human-readable documents from project records
hooks/                         Session-start Entry injection
.mcp.json                      Codex/Claude native FoundryX MCP registration
mcp.json                       Portable Agent Plugins FoundryX MCP registration
.codex-plugin/                 Codex plugin manifest
.claude-plugin/                Claude plugin manifest and marketplace metadata
.agents/plugins/               Codex Git marketplace metadata
.github/plugin/                GitHub Copilot CLI plugin metadata
.cursor-plugin/                Cursor plugin manifest
.factory-plugin/               Factory Droid plugin manifest and marketplace metadata
tests/                         Repository-level validation
zh/                            Chinese documentation

Development

Run the repository test suite with:

python3 -m unittest discover -s tests -p 'test_*.py'

License

This project is licensed under the Apache License, Version 2.0. See LICENSE for details.