Metadata-Version: 2.4
Name: intentos-engineering
Version: 1.1.0
Summary: Engineering intent into reliable AI execution.
Author: Milad Seify
License-Expression: MIT
Project-URL: Repository, https://github.com/milad-seify/IntentOS
Project-URL: Issues, https://github.com/milad-seify/IntentOS/issues
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: mcp
Requires-Dist: mcp<3,>=2; extra == "mcp"
Dynamic: license-file

# IntentOS

**Reliable AI Delegation**

[![CI](https://github.com/milad-seify/IntentOS/actions/workflows/ci.yml/badge.svg)](https://github.com/milad-seify/IntentOS/actions/workflows/ci.yml)

**IntentOS makes AI delegation controlled, portable, and verifiable.**

IntentOS is an open-source, vendor-neutral control and trust layer between **human intent** and **AI execution**. It turns rough goals into reviewable delegation contracts: what should be done, relevant context, constraints, risk, approval boundaries, an appropriate execution target/process, and evidence needed to establish completion. The chosen AI tool or agent performs the work.

Software engineering and DevOps are the initial product wedge and current domain-policy support. The [long-term vision](docs/VISION.md) serves professionals across domains without requiring expertise in prompt engineering, model routing, MCP, or agent internals. Wider domain support requires evidence and separately scoped work.

```text
Intent
  → Normalize / clarify
  → Task + risk
  → Relevant project context
  → Engineering / DevOps policy
  → AI / model route
  → Optimized execution prompt / portable Skill
  → Verification contract
  → Evaluation + versioned run record
  → Learning
```

## Why IntentOS?

A delegation needs a clear goal, relevant context, constraints, risk awareness, and a way to verify the result.

For software engineering and DevOps, that includes engineering expectations, capability/effort guidance, and evidence from actual outcomes. IntentOS makes these concerns explicit in the existing Prepare → Review → Copy workflow and portable preparation artifacts.

Trust comes from explicit interpretation, traceable context, visible assumptions, constraints, consequential human approval, verification criteria, and outcome evidence. IntentOS does not guarantee AI correctness; its preparation guidance does not enforce an agent's permissions or certify completed work.

### What makes it different

- **Intent contracts** — preserve and clarify the goal, scope, constraints, and success criteria in a reviewable execution prompt or portable Skill.
- **Context-aware engineering** — KISS/YAGNI by default; SOLID, DRY, Clean Code, security, and DevOps guidance only when the task actually benefits from them.
- **Risk-aware delegation** — production, security, schema, destructive, and persistent changes get stronger approval boundaries.
- **Minimal project context** — rank, deduplicate, and budget repository context instead of dumping the whole repo into the agent.
- **Portable agent context** — compile reusable `SKILL.md` artifacts instead of repeating the same instructions in every conversation.
- **Agent workspace hygiene** — detect missing, stale, duplicate, or bloated agent-facing files and propose safe updates.
- **Future-proof model routing** — route by capability, effort, availability, surface compatibility, and relative cost without hardcoding today's model names into the core.
- **Evidence over intuition** — regression assertions, A/B ranking, token/latency/retry metrics, versioned privacy-minimal run records, and repeated-failure learning proposals.
- **Ease of use by design** — common workflows should not require prompt-engineering, model-routing, MCP, or internal architecture knowledge.
- **Vendor-neutral core** — provider-specific behavior lives behind profiles/adapters.

## How people should use IntentOS

IntentOS is designed as **one shared core with multiple access surfaces** so different users can work in the environment that fits them.

```text
                         IntentOS Core
                              │
          ┌───────────────────┼───────────────────┐
          │                   │                   │
       Simple UI          VS Code UX          CLI / API
          │                   │                   │
          └───────────────────┼───────────────────┘
                              │
                             MCP
                              │
                  Compatible AI agents/tools
```

Current surfaces:

- **CLI** — portable use from the terminal and scripts.
- **Python API** — programmatic access for integrations and automation.
- **MCP adapter** — optional local stdio connection exposing one bounded `prepare_task` tool.
- **VS Code extension** — the published `0.1.1` release provides Prepare → Review → Copy. The unreleased `0.2.0` candidate adds an Activity Bar workbench for the existing project, governance, delegation, recovery and outcome workflows.
- **Agent Skills** — portable, reusable `SKILL.md` guidance.

Accepted, not-yet-published Core `1.1.0` surface:

- **Local Simple UI (Core `1.1.0` release candidate)** — `intentos ui` opens an outcome-first local browser interface for Prepare → Review → Copy and guided access to the existing F01–F10 operations. See [the UI guide](docs/SIMPLE_UI.md).

The owner-approved graphical scope was integrated by [PR #66](https://github.com/milad-seify/IntentOS/pull/66), accepted at `862c5be0b15125c9f7e3f0ff24de2580fad39a51` with [post-merge CI 7/7](https://github.com/milad-seify/IntentOS/actions/runs/42633513115). Neither Core 1.1.0 nor extension 0.2.0 is published; neither interface silently runs an agent. Neither interface silently runs an agent.

Advanced controls should use **progressive disclosure**: everyday users see simple outcome-first actions, while experts can inspect and control context, risk, policy, routing, cost, approvals, and verification.

See [`docs/UX.md`](docs/UX.md) for the product usage and UX contract.

## Quick start

Requires Python 3.11+.

### Stable release installation

IntentOS 1.0.1 is the current stable release. Install it without cloning the repository:

```bash
python -m pip install intentos-engineering
intentos --help
intentos optimize "Refactor the parser" --target codex
```

The Python distribution is named `intentos-engineering`; its import package and CLI remain `intentos`. A clean public installation of version 1.0.1 was verified.

### Core 1.1.0 source candidate (not yet on PyPI)

After installing from the accepted checkout, launch the local graphical UI with `intentos ui`, or use `intentos ui --no-browser` for a one-time local link. Do not expose the link or loopback server through a proxy. The extension `0.2.0` candidate requires the Core `1.1.0` CLI; public versions remain Core `1.0.1` and extension `0.1.1` until independently published.

### Development checkout

```bash
git clone https://github.com/milad-seify/IntentOS.git
cd IntentOS
python -m pip install -e .
```

Optimize a request for Codex:

```bash
intentos optimize "Refactor the auth module without changing behavior" \
  --target codex \
  --constraint "No new dependencies" \
  --success "Relevant tests pass"
```

If the target is named in the request, the CLI can detect it:

```bash
intentos optimize "Codex: refactor the parser without changing behavior"
```

Use project context:

```bash
intentos optimize "Refactor the parser" \
  --target codex \
  --context-file AGENTS.md \
  --context-file docs/ARCHITECTURE.md
```

Compile the same engineering contract into a portable Agent Skill without writing files:

```bash
intentos skill "Refactor the parser" \
  --target codex \
  --name parser-refactor
```

Machine-readable output:

```bash
intentos optimize "Review this architecture" --target claude --json
```

JSON mode returns the versioned machine contract documented in [`docs/PUBLIC_CONTRACT.md`](docs/PUBLIC_CONTRACT.md). Schema versioning is independent from the Python package version. The v1 contract is frozen; package version `1.0.1` is the current stable release.

Plan agent workspace maintenance without writing files:

```bash
intentos workspace \
  --phase "Phase 7B — minimum VS Code UX" \
  --document AGENTS.md \
  --document docs/STATUS.md
```

`workspace` and `skill` are **proposal-first**: they emit reviewable artifacts; they do not silently mutate or install anything in your repository.

On the unreleased development branch, review project state and scope from files you choose:

```bash
intentos compass --authoritative-document docs/PLAN.md \
  --document docs/STATUS.md --task "Review API"
```

`compass` reports each extracted claim with its file and line, including `D-xxx` decision headings, and labels missing, stale, or unresolved facts. An exact in-scope match needs a file you explicitly designated authoritative; the result does not approve execution or verify the underlying claims. Use `--json` for the review data. This command is not in the published Core 1.0.1 package.

The same unreleased development branch can propose a bounded update to a simple `docs/STATUS.md`:

```bash
intentos state status --root . --current-phase "Milestone 2" \
  --evidence "owner-reviewed PR #12"
```

Review the displayed diff and record its approval digest. Only after explicit owner approval, rerun with the same arguments plus `--approve-digest DIGEST`. `intentos state decision` similarly proposes an append-only decision. These commands write only the two named documents, reject changed source revisions, and do not verify that an evidence reference is truthful. Complex status sections require manual review. They are not in Core 1.0.1.

For projects with a simple `docs/SCOPE.md`, the unreleased `intentos state scope` command previews an owner-approved scope amendment. It requires an amendment ID, exact task, reason, and approval reference. The preview shows the diff and approval digest; apply requires rerunning with `--approve-digest DIGEST`. An out-of-scope item moves to the in-scope list only after approval, with an append-only audit entry in the same file. Ambiguous or stale scope requires manual review.

For a development milestone/launch review, place accepted requirements, milestone states and external check references in a local JSON file, then run `intentos gates --file project-gates.json --json`. The file uses `schema_version: 1` and three arrays: `requirements` (`key`, `outcome`, `checks`, `accepted_by_owner`, `approval_ref`), `milestones` (`key`, `requirement_keys`, `state`, `approval_ref`), and `evidence` (`requirement_key`, `check`, `passed`, `source_ref`, `source_revision`, `independently_reviewed`). States are `proposed`, `done`, `verified` and `approved`; unknown checks remain `null`. The command reports missing, failed and unreviewed gates and never grants launch approval. It is not in Core 1.0.1.

The unreleased `intentos route "Refactor the parser" --target codex --models-file models.json --json` command reviews a recommendation from caller-supplied model metadata. The catalog has `schema_version: 1` and a `models` array with each model's `name`, `provider`, `surfaces`, `capability` (`fast`/`balanced`/`strong`), `cost` (`low`/`medium`/`high`), `available`, and `verified`. Availability and verification default to false when omitted. The report explains eligible and excluded candidates, required capability/effort, relative cost and the catalog SHA-256. No live provider availability or price is claimed; missing or conflicting verified metadata produces a fallback for human review.

For an interrupted development task, `intentos checkpoint create --root PROJECT --context-file docs/STATUS.md --spec checkpoint-spec.json --output checkpoint.json --json` saves a versioned checkpoint without overwriting an existing file. The spec supplies `task_id`, `next_step_id`, `approved_plan` (step IDs and actions), `plan_approval_ref`, `state_summary`, `state_evidence_ref`, and optional `completed` steps (step ID, evidence reference, `accepted_by_owner`), `operation_ids`, `required_approval_ids`, and `estimated_remaining_tokens`. IntentOS reads the actual Git HEAD and fingerprints only the explicitly named context files; it stores the fingerprint, not their contents. After interruption, run `intentos checkpoint review` with the same `--root` and `--context-file` arguments, `--checkpoint checkpoint.json`, and externally checked `--ledger-reviewed`, repeated `--executed-operation` and `--accepted-approval` values as applicable. A changed revision/context, possible replay, or missing approval blocks resume. A passing review means **ready for owner review**, never permission to execute; references and ledger checks are caller assertions, not independently verified facts. This development command is not in Core 1.0.1.

The development `intentos handoff prepare "TASK" --root PROJECT --target codex --task-id TASK-1 --context-file docs/STATUS.md --output handoff.json --json` creates a reviewable packet using the same core preparation as `optimize`. The packet includes the target-specific prepared task, goal, policy and verification fields, named context sources, source revision and context fingerprint. `intentos handoff dispatch --root PROJECT --file handoff.json --json` previews an exact approval digest and permission boundary without starting an agent. Only a second invocation with the matching `--approve-digest` runs the supported Codex CLI adapter; `--sandbox read-only` is the default, and `--sandbox workspace-write` additionally requires a clean Git tree and is unavailable for high-risk tasks. [Codex's noninteractive mode](https://learn.chatgpt.com/docs/non-interactive-mode) provides the underlying `codex exec` sandbox and JSONL event contract. IntentOS reports an agent turn as `completed_unverified` until independent task checks run. Other target profiles produce portable packets for manual copy and an explicit unavailable dispatch status. Local CLI credentials and any agent actions remain governed by the executing environment; do not include secrets in the task or selected context. These development commands are not in Core 1.0.1.

The development `intentos outcome record --file observed.json --output record.json --json` captures one externally verified outcome without raw prompts. The input names the task and `raw`, `prepared`, or `single` variant; the executor/model/effort/base/context/permissions/environment conditions; 1–64 named acceptance checks with `passed` (`true`, `false`, or `null`) and evidence references; `execution_success`; optional measured `quality_score`, `input_tokens`, `output_tokens`, `latency_ms`, `retries`; a source reference; and optional friction, rework, gap and lesson fields. `intentos outcome compare --raw raw.json --prepared prepared.json --json` requires the same task, conditions and acceptance checks, then uses the existing correctness-first paired comparator. Unknown checks or changed conditions are inconclusive, and missing measures stay null. `intentos outcome learn --record RECORD ... --json` proposes a lesson only after failures on two distinct tasks; rerunning with the exact proposal digest, external `--approval-ref`, and new `--output` saves an approved proposal record without changing runtime policy. All evidence and approvals are caller supplied, not independently collected by IntentOS. These development commands are not in Core 1.0.1 and do not start Phase 8 user validation.

For an explicit model choice, run `intentos route` with a caller-verified catalog, then pass its selected name as `--model` to both the handoff dispatch preview and approved dispatch. The model name is part of the approval digest; IntentOS does not claim live model availability. `intentos checkpoint review --remaining-budget-tokens N` compares a caller-supplied remaining budget with the checkpoint's caller-supplied estimate, blocks an estimated overrun, and reports unknown when either figure is absent. Neither estimate guarantees actual token use.

You can also run the CLI as a module:

```bash
python -m intentos optimize "Fix the failing parser test" --target codex
```

## MCP adapter

MCP support is optional so the standard-library core remains lightweight.

Install the MCP extra without cloning:

```bash
python -m pip install "intentos-engineering[mcp]"
```

For development, contributors can install the extra from a repository checkout with `python -m pip install -e ".[mcp]"`.

A compatible local MCP host can launch:

```bash
intentos-mcp
```

The server uses stdio and exposes exactly one tool: `prepare_task`.

`prepare_task` accepts the user request, optional target tool, constraints, success criteria, output format/audience, and bounded caller-supplied project context. Project context entries contain only `path` labels and `content`; IntentOS does **not** read those paths from the filesystem. The first slice accepts at most 32 context documents and 6000 characters total.

The MCP result uses the same versioned machine contract as the CLI: ready/clarification status, prepared prompt, task/risk decision, engineering and approval boundaries, routing, context diagnostics, and verification criteria.

MCP preparation does not execute the task, authorize a risky action, mutate the repository, expose workspace/Skill/run-record operations, or turn IntentOS into a general MCP runtime.

## VS Code extension

Install the [IntentOS extension from the Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=milad-seyfi.intentos-vscode). First install the local CLI:

```bash
python -m pip install intentos-engineering
```

Then install the extension from the Marketplace and use this flow:

```text
Request
→ IntentOS preparation
→ Review
→ Copy Prepared Task
→ hand off to Codex / ChatGPT / Claude / Gemini / Cursor / another AI tool
```

The extension uses the editable package installation only for local development. IntentOS 1.0.1 is also available as the stable public package.

The editor extension lives in `integrations/vscode` and intentionally has no npm runtime dependencies or build pipeline. The development candidate adds an Activity Bar entry and a native-themed workbench while preserving the published Prepare → Review → Copy path.

Basic flow:

1. make sure the `intentos` CLI is available to the VS Code extension host
2. select request text in an editor, or leave nothing selected
3. run `IntentOS: Prepare Task` from the Command Palette
4. if needed, type the request into the small input box
5. review interpretation, risk/approval boundaries, context summary, verification, and the prepared prompt
6. use **Copy Prepared Task** when ready

Advanced routing/context details stay collapsed by default. The extension invokes `intentos optimize ... --json`; it does not duplicate IntentOS classification, policy, context, or routing logic in JavaScript.

`intentos.executable` defaults to `intentos` and can be changed when VS Code needs a specific virtual-environment executable path.

For the development workbench, open **IntentOS** in the Activity Bar, then choose Start, Project, Govern, Delegate, Recover or Outcomes. The workbench uses the installed Core `1.1.0` candidate CLI for advanced actions; the published Core `1.0.1` package does not contain those commands. Explicit source selection and approval previews preserve the existing CLI boundaries. There is no automatic project-file discovery, telemetry or background service. See [`integrations/vscode/README.md`](integrations/vscode/README.md).

## Python API

```python
from intentos import (
    IntentRequest,
    RunMetrics,
    build_run_record,
    build_skill_artifact,
    optimize_prompt,
)

result = optimize_prompt(
    IntentRequest.from_values(
        "Refactor the auth module without changing behavior",
        target_tool="codex",
        constraints=["No new dependencies"],
        success_criteria=["Relevant tests pass"],
    )
)

if result.needs_clarification:
    print(result.questions)
else:
    print(result.policy.task_type, result.policy.risk_level)
    print(result.routing.required_capability, result.routing.effort)
    print(result.prompt)

    skill = build_skill_artifact(result.intent, result.policy)
    record = build_run_record(
        result,
        metrics=RunMetrics(success=True, quality_score=0.9),
    )
    print(skill.content)
    print(record.to_json())
```

For project-aware prompting, use `optimize_project_prompt()`. For model selection, pass replaceable `ModelMetadata` entries. IntentOS intentionally does not hardcode volatile model names in the core.

Run records intentionally avoid storing raw prompts by default. They use fingerprints and compact metadata so future telemetry/dataset adapters can be added without making raw private agent traces a core requirement.

The deterministic task/risk classifier is an **advisory preparation mechanism**, not a security authorization boundary.

## Engineering philosophy

IntentOS prefers:

- minimal sufficient context
- small coherent changes
- KISS and YAGNI before abstraction
- contextual SOLID / DRY / Clean Code
- explicit scope and approval boundaries
- secure defaults and least privilege
- reproducible and recoverable DevOps changes
- evidence-backed completion
- the lowest-overhead model that still meets the quality bar
- simple defaults with expert controls available when needed

It should **not** force Clean Architecture, microservices, extra abstractions, heavyweight process, or expert-only UX onto small tasks.

## Architecture

The conceptual pipeline is:

```text
User Intent
   ↓
Intent Normalizer
   ↓
Task + Risk Classifier
   ↓
Context Selector
   ↓
Policy Engine
   ↓
AI / Model Router
   ↓
Prompt / Skill Compiler
   ↓
Verification Contract
   ↓
Evaluation + Run Record
```

See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md), [`docs/UX.md`](docs/UX.md), [`docs/DECISIONS.md`](docs/DECISIONS.md), [`docs/EVALUATION.md`](docs/EVALUATION.md), and [`docs/HUGGINGFACE_RESEARCH.md`](docs/HUGGINGFACE_RESEARCH.md).

## What IntentOS is not

IntentOS is not:

- an IDE
- an LLM or coding-agent replacement
- a general autonomous-agent framework
- a general MCP runtime
- a telemetry backend
- a CI/CD platform
- a project-management suite
- a framework that forces one software architecture
- a giant prompt-template collection

## Development

The core and local Simple UI have no third-party runtime dependencies. MCP support is an optional extra rather than a core dependency. The VS Code extension uses plain JavaScript and built-in VS Code/Node APIs.

```bash
PYTHONPATH=src python -m unittest discover -s tests -v
```

GitHub Actions runs the full core suite on Ubuntu with Python 3.11, 3.12, and 3.13, focused Windows/Python 3.13 regression coverage, CLI smoke checks, MCP protocol/stdio parity checks, and a dependency-free VS Code extension syntax check.

## Project status

The initial Phase 0–6 roadmap and independent-audit stabilization gate are complete. **Phase 7 is complete:** MCP parity was proven, VS Code is publicly distributed with a visible status-bar launcher, and the accepted workflow remains Prepare → Review → Copy. The evidence gate did not justify additional adapters or execution capabilities.

The current UI candidate runs **258 Python unit tests (one skipped)** locally, plus CLI/MCP smoke, VS Code contract/syntax/real-host checks, a real browser acceptance flow across all six areas and package validation. CI builds and inspects wheel/sdist artifacts, then installs and smoke-tests them from clean environments without publishing. Use exact-head CI for a final gate rather than treating this local count as release acceptance.

Core `1.0.1` is published on PyPI and GitHub, packaging the review-only classification/policy correction. See the [1.0.1 release notes](docs/RELEASE_NOTES_1.0.1.md) and [GitHub Release](https://github.com/milad-seify/IntentOS/releases/tag/v1.0.1).

The v1 public compatibility contract is frozen in `docs/PUBLIC_CONTRACT.md`. IntentOS `1.0.1` is the current stable published core release; VS Code extension `0.1.1` is published. Phase 7 is formally complete. The F01–F10 source scope was accepted at PR #65, and the owner subsequently authorized the bounded pre-release graphical access candidate in [D-033](docs/DECISIONS.md). Neither the new UI nor Core source `1.1.0` is published, and the revised integrated freeze awaits exact-SHA verification and owner acceptance. [Phase 8 — Adoption & Outcome Validation](docs/PHASE_8_VALIDATION.md) has an approved protocol, but operational validation and owner-led dogfooding have not started. See [status](docs/STATUS.md), [release notes](docs/RELEASE_NOTES_1.0.1.md) and [release procedure](docs/RELEASING.md).

See [`docs/STATUS.md`](docs/STATUS.md) for the concise handoff, [`docs/DOGFOODING.md`](docs/DOGFOODING.md) for real-world findings, [`docs/MCP_DOGFOODING.md`](docs/MCP_DOGFOODING.md) for MCP parity evidence, [`docs/HUGGINGFACE_RESEARCH.md`](docs/HUGGINGFACE_RESEARCH.md) for the ecosystem research pass, [`docs/UX.md`](docs/UX.md) for usage/access principles, [`docs/INDEPENDENT_AUDIT.md`](docs/INDEPENDENT_AUDIT.md) for the review contract, and [`docs/ROADMAP.md`](docs/ROADMAP.md) for the roadmap.

## Contributing

Contributions are welcome, especially:

- real-world failure/regression fixtures
- target-tool profiles where generic behavior is demonstrably insufficient
- provider/model metadata adapters
- context-selection improvements backed by tests
- evaluation and workflow improvements with measurable evidence
- portable Agent Skills and integration adapters that preserve the vendor-neutral core
- usability improvements that reduce friction without duplicating core behavior

Please read [`CONTRIBUTING.md`](CONTRIBUTING.md) before opening a PR.

## License

MIT
