Engi Elicit

Engi Elicit is an equality-centered elicitation skill for developing a project idea through sustained discussion between a user and an AI agent.

It replaces interview-style requirement extraction with mutual cognitive contribution. The user retains ownership of purpose, values, and authorization; the agent actively contributes analysis, connections, challenges, and read-only research without taking control of the agenda or implementing the target project.

The outcome is a validated, machine-readable ELICIT.md that can serve as durable input to product design, research, planning, or implementation.

Why it exists

Many elicitation workflows place the agent in the role of interviewer or examiner:

• the agent defines the questions;
• the user carries the burden of answering;
• the agent recommends answers inside its own frame;
• procedural agreement is mistaken for shared understanding.

Engi Elicit uses a different relationship. Both participants can offer, question, challenge, connect, reframe, investigate, and revise. The discussion remains anchored to one core proposition while progressively unpacking its motives, needs, principles, constraints, tensions, assumptions, unknowns, and consequences.

Core behavior

• Explicit entry is immediate. A direct $engi-elicit invocation does not require confirmation.
• Inferred entry requires consent. When an ordinary prompt clearly asks for sustained joint exploration, the agent asks once before changing modes and creating artifacts.
• The first expansion turn is chosen. After the original input is recorded, the user may continue speaking without analysis or invite the agent to offer its initial reflection.
• Cognitive initiative is automatic. The agent does not wait for “What do you think?” before contributing useful reasoning or research.
• Execution is forbidden while active. The agent may discuss, record, analyze, and investigate read-only sources, but it does not implement the target project.
• The core proposition remains traceable. Every round rereads the verbatim original input and the evolving shared understanding.
• Ending intent is sufficient. A clear request to end or crystallize the discussion finalizes the artifact without a redundant confirmation.

Workflow

explicit invocation ──────────────────────┐
                                         ├─> persist original input
inferred discussion intent -> consent ───┘
                                                 │
                                                 v
                                      choose first expansion turn
                                                 │
                                                 v
                                  mutual discussion + read-only research
                                                 │
                                      continuously update notes
                                                 │
                              user expresses clear ending intent
                                                 │
                                                 v
                              synthesize and validate ELICIT.md
                                                 │
                                                 v
                                    exit and hand off to engineering

Artifacts

Engi Elicit creates two files per subject under the subject project's ELICIT/ collection:

| Artifact | Role | | --- | --- | | ELICIT/<subjectId>/ELICIT.notes.md | Durable working notebook containing the verbatim input, attribution, research, proposition evolution, tensions, assumptions, and recovery state. | | ELICIT/<subjectId>/ELICIT.md | Final attribution-free synthesis containing only effective project information and its epistemic status. | | ELICIT/index.json | Compact discovery and lifecycle audit index containing each subject path, current status, status timestamp, and append-only transition history. |

ELICIT.notes.md explains how understanding developed. ELICIT.md expresses what that understanding became. Finalization never deletes the notes.

Different subjects coexist as independent, first-class units. Starting a subject does not archive, supersede, or invalidate any other subject. Legacy root artifacts can be migrated automatically into the same collection; the user does not need to rename or safeguard them manually.

Machine-readable document contract

The final document begins with stable YAML metadata:

---
schema: engifoundry.elicit/v1
kind: elicit
status: completed
title: "Project title"
subjectId: project-title
sourceNotes: ELICIT.notes.md
finalizedAt: 2026-08-10T12:00:00Z
corePropositionId: CP-001
readiness: conditional
recommendedNext: product-design
---

Its Markdown body uses canonical sections and typed IDs such as:

• CP-### — core proposition;
• NEED-### — deep need;
• PRI-### — principle;
• CON-### — constraint;
• TEN-### — tension;
• ASM-### — assumption;
• UNK-### — unknown;
• OOS-### — scope boundary;
• REQ-### — effective requirement.

Assumptions and unknowns retain explicit epistemic states. Finalization removes speaker attribution, but it never turns an unresolved idea into a fact.

See the complete document contract.

Installation

Node.js 18 or newer is required. Choose either npm or GitHub installation.

npm

Install the published package from the npm registry outside an engi-elicit source checkout:

npx --yes engi-elicit install

GitHub

Install directly from the public repository without waiting for an npm release:

npm exec --yes --package=github:caoyuan-fire/engi-elicit -- engi-elicit install

From a cloned source checkout, run:

npm run skill:install -- --host codex

Target hosts

Without target options, the installer presents detected hosts for selection. Use explicit targets in non-interactive environments:

npx --yes engi-elicit install --host codex
npx --yes engi-elicit install --host codex,claude
npx --yes engi-elicit install --host antigravity
npx --yes engi-elicit install --all
npx --yes engi-elicit install --target /custom/skills

Default locations:

Codex     ~/.codex/skills/engi-elicit
Claude    ~/.claude/skills/engi-elicit
Kimi Code ~/.kimi/skills/engi-elicit
Antigravity ~/.gemini/config/skills/engi-elicit

Manage an installation

npx --yes engi-elicit check --host codex
npx --yes engi-elicit update --host codex
npx --yes engi-elicit uninstall --host codex

Add --dry-run to preview a change. Replacing or removing an unmanaged installation requires --force.

The repository also includes a Codex plugin manifest at .codex-plugin/plugin.json.

Usage

Explicit invocation with a core proposition:

$engi-elicit

I want to build a topic-based community, with travel guides as a core product surface.

The skill can also recognize prompts that clearly request sustained discussion:

I have an early product idea. I do not want a plan yet; I want us to explore
the underlying needs together and gradually shape the complete project.

A one-shot request for an opinion or analysis does not automatically enter elicitation mode.

Bundled tools

Initialize a notebook without overwriting existing work:

node skills/engi-elicit/scripts/init-elicit.mjs \
  --project /path/to/project \
  --title "Project title" \
  --subject-id project-title \
  --input-file /path/to/original-input.txt

When legacy root artifacts exist, migrate them into their own subject directory while initializing a different subject:

node skills/engi-elicit/scripts/init-elicit.mjs \
  --project /path/to/project \
  --title "Next subject" \
  --input-file /path/to/original-input.txt \
  --migrate-legacy

Validate a finalized artifact:

node skills/engi-elicit/scripts/validate-elicit.mjs /path/to/project/ELICIT/subject-id/ELICIT.md
node skills/engi-elicit/scripts/validate-elicit.mjs /path/to/project/ELICIT/subject-id/ELICIT.md --format json

The validator checks exactly the artifact path supplied; it does not scan every indexed subject. It checks the deterministic document contract: metadata, canonical section order, typed IDs, epistemic statuses, source-notes linkage, placeholders, and process-attribution leakage. It cannot determine whether a discussion was genuinely equal or insightful; semantic fidelity remains an agent responsibility.

Update one subject's indexed lifecycle without touching other subjects. Every transition requires an audit reason:

node skills/engi-elicit/scripts/update-elicit-index.mjs \
  --project /path/to/project \
  --subject-id subject-id \
  --status elicited \
  --reason "ELICIT.md validated and discussion finalized."

The lifecycle statuses are eliciting, elicited, in-development, development-complete, and obsolete. obsolete explicitly means discarded: artifacts and audit history remain, but the subject is no longer valid downstream input.

Development

Requirements:

• Node.js 18 or newer;
• Python 3 only when running the external Skill or plugin validators.

Run the focused test suite:

npm test

The suite covers entry behavior, cognitive initiative, execution boundaries, finalization, notebook overwrite protection, valid final documents, and representative validation failures.

Project structure

.codex-plugin/plugin.json
bin/engi-elicit.mjs
skills/engi-elicit/
├── SKILL.md
├── agents/openai.yaml
├── assets/
│   ├── ELICIT.notes.template.md
│   └── ELICIT.template.md
├── references/
│   ├── document-contract.md
│   └── interaction-contract.md
└── scripts/
    ├── init-elicit.mjs
    └── validate-elicit.mjs
tests/
package.json

Status

Engi Elicit is currently an early 0.2.0 implementation. Its document structure, interaction boundaries, multi-subject lifecycle index, and multi-host npm installer are tested; implicit-intent recognition and multi-session behavior still need forward testing across agent hosts and models.

License

Apache-2.0