Engineering OS

AI-agnostic, workflow-driven /feature delivery for any AI coding assistant.

Engineering OS turns a Jira ticket, Figma design, or plain task description into a tested, verified feature through one coherent, conversational workflow — the same active run from intake to delivery, with human decisions and approvals happening in the chat, never in a separate CLI ceremony.

It is repository-aware, workflow-driven (not prompt-driven), and tool-independent. Thin adapters map the same core to each AI tool (Cursor, Claude Code, GitHub Copilot, Cline, Roo Code, Windsurf, and others).

Why Engineering OS?

Most AI coding setups are a pile of prompts. Engineering OS replaces that with:

One declared /feature workflow that orchestrates every phase automatically
Required artifacts (contract, plan, verification evidence) before code
Human approval gates and clarifications resolved in the same conversation
Capability detection so agents never assume missing systems (backend, E2E, …)
A fail-closed mutation guard so application code cannot change before it is authorized

Core principles

Discover before implementing
Reuse before creating
Repository-first, AI-second
Never assume missing systems (especially backend and E2E)
Never modify architecture without approval
Generate evidence, not assumptions
Verification is mandatory before delivery

See docs/principles.md.

The `/feature` workflow

Engineering OS ships a single, authoritative workflow: feature-development, driven end-to-end through eos feature. Its phases run in one active run:

Intake            Jira / Figma / task description (no application code is touched)
  → Discovery     Ingest and normalize the requirement source
  → Clarification Ask every unresolved question in chat; re-analyze after each
                  answer and ask any newly discovered question before proceeding
  → Testing       Decide unit / integration / E2E / manual QA. E2E is never
    strategy      auto-installed; if it is appropriate but unavailable the user
                  must explicitly decide to proceed without it
  → Test cases    Generate copy-pasteable test cases before any code is written
  → Confirmation  Explicit user confirmation of the testing approach and cases
  → Approval      Contract / plan (and, if flagged, architecture) gates
  → Implement     Only now can application code be mutated
  → Test          Validate that the claimed test files actually exist and run
    execution     them; report real results
  → Regression    Analyze blast radius, generate REG scenarios, require
                  current-run evidence (automated and/or user-confirmed manual)
  → Verify        AC → implementation + test + execution evidence chain
  → Review        →  Deliver  →  Completion report

The whole flow stays in the same conversation. The agent runs the eos commands on your behalf; you never have to run a CLI command to resume the workflow. Temporary run artifacts are cleaned automatically on successful completion, while the durable delivery record and permanent project metadata are preserved.

Add Engineering OS to your project (5 steps)

Step 1 — Install the eos CLI once (from this repo):

git clone https://github.com/AlpeshB08/engineering-os
cd engineering-os && npm install && npm link   # exposes `eos` globally

Step 2 — Initialize it inside your project:

cd /path/to/your-app
eos init      # creates .engineering-os/ and updates .gitignore
eos detect    # detects your stack and writes the Repository Profile

Step 3 — Connect your AI assistant. Copy the adapter for your tool into your project (see Adapters), e.g. for Claude Code copy adapters/claude-code/CLAUDE.md. This tells the assistant to follow the active /feature workflow and drive the eos commands for you.

Step 4 — Start a feature. In your AI chat, paste a Jira key, a Figma link, or a plain description and ask it to run the /feature workflow. Under the hood it runs:

eos feature --jira PROJ-123 --figma <url> --context "what you want built"

Step 5 — Answer in the chat and let it drive. The workflow stays in one conversation: the assistant asks questions, you answer, it re-analyzes and asks the next one, then confirms the test strategy and test cases with you before writing any code, implements, runs tests, does regression, and finishes with a delivery report.

You never run these yourself — the assistant does — but under the hood each of your answers/approvals is one eos feature continue call in the same run:

eos feature continue --answer "..."               # answer a clarification
eos feature continue --confirm testing-strategy   # confirm the strategy
eos feature continue --confirm test-cases         # confirm cases → implement
eos feature continue --implemented --summary "..." --tests-created "path/to/test"
eos feature continue --confirm regression
eos feature continue --confirm review
eos feature continue --confirm delivery

Tip: run eos status any time to see the current phase, pending questions, and blockers. (Optional: export ENGINEERING_OS_HOME=/path/to/engineering-os if the CLI can't locate the framework; for Cursor, install .cursor/hooks.json for hard mutation guards — see docs/installing-into-a-repo.md.)

Should this be published to npm?

Not yet — npm link (or install-from-Git) is enough for now. The /feature workflow is still stabilizing, and both methods above already give you the global eos command without publishing anything public.

Publish to npm later, once the workflow is stable and you want frictionless installs across a team (npm i -g engineering-os, or npx engineering-os). When that time comes it is a small step — there is no build, the CLI ships as source:

# one-time, when ready to release publicly
npm version patch
npm publish --access public
# if the name "engineering-os" is taken, publish under a scope, e.g. @alpeshb08/engineering-os

Until then, teammates install exactly as in Step 1 above.

CLI (`eos`)

Command	Purpose
`eos init`	Scaffold `.engineering-os/` in the current repo
`eos detect`	Detect capabilities and refresh the Repository Profile
`eos feature [--jira …] [--figma …] [--context …]`	Start the `/feature` workflow with structured intake
`eos feature continue …`	Advance the active run in the same conversation (answers, confirmations, implementation evidence)
`eos status`	Show phase, gates, pending decisions, blockers
`eos next`	Print AI-readable instructions for the current phase
`eos decision list \| answer <id> --option <id>`	Inspect / answer a workflow decision
`eos gate <id> --approve \| --reject`	Low-level approval primitive (the conversation drives these for you)
`eos guard implementation [--path <file>]`	Check whether application mutation is authorized
`eos verify run \| report`	Execute capability-gated checks / final readiness report
`eos cleanup [--dry-run] [--run <id>]`	Safely remove finalized run-owned temporary artifacts
`eos validate [--framework]`	Validate workflow, state, and schemas

Repository layout

engineering-os/
├── docs/               # Framework documentation
├── engine/             # CLI, schemas, and tests
├── workflows/          # The feature-development workflow definition
├── phases/             # Shared phase instructions
├── templates/          # Artifact templates
├── standards/          # Enforceable engineering standards
├── checklists/         # QA and regression checklists
├── knowledge-base/     # Patterns, anti-patterns, ADRs, playbooks
└── adapters/           # Cursor, Claude Code, Copilot, Generic

Adapters

Tool	Path
Cursor	adapters/cursor
Claude Code	adapters/claude-code
GitHub Copilot	adapters/copilot
Generic (Cline, Roo, Windsurf, …)	adapters/generic
AGENTS.md (Codex CLI, Gemini CLI, Amp, Jules, …)	adapters/agents-md
Agent Skill (`SKILL.md` for Cursor / Claude / Copilot)	adapters/skill

Adapters never embed workflow logic. They instruct agents to run eos status / eos next, present questions and approvals in chat, fill templates, and stop at gates.

MCP server (recommended for reliability)

Instead of relying on the agent to choose to type eos commands, expose the workflow as typed MCP tools. The agent then drives /feature through a tool contract, so steps cannot be silently skipped:

npm install @modelcontextprotocol/sdk   # optional dependency
eos-mcp                                  # stdio MCP server

Register it with your client (example):

{ "mcpServers": { "engineering-os": { "command": "eos-mcp" } } }

Tools: feature_start, feature_continue, feature_status, guard_check. The core eos CLI does not depend on the SDK — if it is not installed, only eos-mcp is unavailable.

Documentation

Consumer state

After eos init, the target repo contains:

.engineering-os/
├── state.json
├── repository-profile.md
├── artifacts/<run-id>/     # cleaned automatically after successful delivery
└── knowledge-base/          # optional overlay

License

MIT — see LICENSE.

Navigation Menu

Repository files navigation

Engineering OS

Why Engineering OS?

Core principles

The `/feature` workflow

Add Engineering OS to your project (5 steps)

Should this be published to npm?

CLI (`eos`)

Repository layout

Adapters

MCP server (recommended for reliability)

Documentation

Consumer state

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
adapters		adapters
checklists		checklists
docs		docs
engine		engine
knowledge-base		knowledge-base
phases		phases
standards		standards
templates		templates
workflows		workflows
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

Latest commit

History

Folders and files

Repository files navigation

Engineering OS

Why Engineering OS?

Core principles

The /feature workflow

Add Engineering OS to your project (5 steps)

Should this be published to npm?

CLI (eos)

Repository layout

Adapters

MCP server (recommended for reliability)

Documentation

Consumer state

License

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

The `/feature` workflow

CLI (`eos`)