Skip to content

Commit 6928b9e

Browse files
EvanAI0331EvanAI0331
committed
release specx codex plugin v0.1.0
0 parents  commit 6928b9e

26 files changed

Lines changed: 1340 additions & 0 deletions

‎.codex-plugin/plugin.json‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
{
2+
"name": "specx-codex-plugin",
3+
"version": "0.1.0",
4+
"description": "Universal spec-driven agent governance and execution contract runtime for Codex.",
5+
"license": "MIT",
6+
"author": {
7+
"name": "BTCNAI",
8+
"url": "https://github.com/BTCNAI"
9+
},
10+
"homepage": "https://github.com/BTCNAI/specx-codex-plugin",
11+
"repository": "https://github.com/BTCNAI/specx-codex-plugin",
12+
"keywords": [
13+
"spec-driven-execution",
14+
"agent-governance",
15+
"workflow-contracts",
16+
"verification",
17+
"codex-plugin"
18+
],
19+
"interface": {
20+
"displayName": "SpecX Universal Agent Governance Runtime",
21+
"shortDescription": "Spec-driven execution contracts and governance for Codex workflows.",
22+
"longDescription": "SpecX provides universal execution contracts, gates, evidence requirements, artifact expectations, failure semantics, and verification rules for governed Codex workflows.",
23+
"developerName": "SpecX contributors",
24+
"category": "Productivity",
25+
"capabilities": [
26+
"Read",
27+
"Write"
28+
],
29+
"websiteURL": "https://github.com/BTCNAI/specx-codex-plugin",
30+
"defaultPrompt": [
31+
"Use SpecX to compile this task into a governed execution contract.",
32+
"Use SpecX to verify whether this workflow has agents, tools, evidence, gates, artifacts, and failure semantics.",
33+
"Use SpecX to explain the execution contract before workflow execution."
34+
],
35+
"brandColor": "#2563EB"
36+
},
37+
"skills": "./skills/"
38+
}

‎.gitignore‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.pytest_cache/
2+
__pycache__/
3+
*.py[cod]
4+
.DS_Store
5+
.venv/
6+
dist/
7+
build/

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 SpecX contributors
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# SpecX Codex Plugin
2+
3+
SpecX turns vague agent tasks into governed execution contracts.
4+
It enforces required agents, tools, evidence, gates, artifacts, and failure semantics.
5+
It prevents fake success, silent fallback, and uncontrolled agent execution.
6+
7+
SpecX is a governance layer for Codex agents.
8+
9+
## Install
10+
11+
Install from the marketplace repository:
12+
13+
```bash
14+
codex plugin marketplace add BTCNAI/specx-codex-marketplace
15+
```
16+
17+
Or pin the stable release:
18+
19+
```bash
20+
codex plugin marketplace add https://github.com/BTCNAI/specx-codex-marketplace.git --ref v0.1.0
21+
```
22+
23+
## What It Provides
24+
25+
- Contract-first workflow definition.
26+
- Required LLM-backed agents with role, execution, and output specs.
27+
- Gate-bound and evidence-bound decisions.
28+
- Artifact contracts and explicit failure states.
29+
- Fail-closed verification for fake success and silent fallback.
30+
31+
## Current Release
32+
33+
Version `v0.1.0` is a skills + CLI release.
34+
35+
Included skills:
36+
37+
- `specx-contract-compiler`
38+
- `specx-runtime`
39+
- `specx-agent-governance`
40+
- `specx-verifier`
41+
42+
Included CLI:
43+
44+
```bash
45+
python3 scripts/specx_cli.py validate examples/demo_software_engineering_contract.json
46+
python3 scripts/specx_cli.py compile examples/demo_software_engineering_contract.json
47+
python3 scripts/specx_cli.py verify examples/demo_software_engineering_contract.json
48+
python3 scripts/specx_cli.py explain examples/demo_software_engineering_contract.json
49+
```
50+
51+
## Contract Shape
52+
53+
Every valid contract must define:
54+
55+
- `required_agents`
56+
- `required_tools`
57+
- `required_evidence`
58+
- `gates`
59+
- `expected_artifacts`
60+
- `failure_semantics`
61+
- `execution_constraints.no_fake_success`
62+
- `execution_constraints.no_silent_fallback`
63+
64+
If required evidence, tools, specs, gates, or artifacts are missing, the workflow must return `blocked`, `failed`, or `unsupported`. It must not claim success.
65+
66+
## Demos
67+
68+
Demo 1: Software engineering
69+
70+
- Before: "Refactor this backend."
71+
- After SpecX: required agents, gates, tests, failure semantics, and artifact contract.
72+
- File: `examples/demo_software_engineering_contract.json`
73+
74+
Demo 2: Research task
75+
76+
- Before: "Research this market."
77+
- After SpecX: evidence requirements, source gates, decision packet, and risk notes.
78+
- File: `examples/demo_research_task_contract.json`
79+
80+
Demo 3: Multi-agent system
81+
82+
- Before: agents freestyle.
83+
- After SpecX: contract-first runtime, verifier, and explicit failure state.
84+
- File: `examples/demo_multi_agent_system_contract.json`
85+
86+
## Docs
87+
88+
- `docs/quickstart.md`
89+
- `docs/contract-format.md`
90+
- `docs/use-cases.md`
91+
- `docs/comparison.md`
92+
93+
## Roadmap
94+
95+
P0:
96+
97+
- Real MCP server.
98+
- Contract schema v0.1.
99+
- `specx.validate`
100+
- `specx.compile`
101+
- `specx.verify`
102+
- `specx.explain`
103+
104+
P1:
105+
106+
- `specx init`
107+
- `specx verify`
108+
109+
The next release target is skills + CLI + MCP tools.
110+
111+
## Repository Structure
112+
113+
```text
114+
specx-codex-plugin/
115+
├── .codex-plugin/plugin.json
116+
├── docs/
117+
├── skills/
118+
├── scripts/
119+
├── schemas/
120+
├── examples/
121+
├── tests/
122+
├── README.md
123+
├── marketplace.json
124+
└── LICENSE
125+
```
126+
127+
## Failure Policy
128+
129+
SpecX must not replace agent decisions with hardcoded fallback logic. Scripts may validate, transform, launch, or verify; they must not impersonate agent reasoning.
130+
131+
No LLM-backed decision authority means no agent label.

‎docs/comparison.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Comparison
2+
3+
## Without SpecX
4+
5+
- The task starts from vague natural language.
6+
- Agents can act before evidence is available.
7+
- Missing outputs can be hidden behind generic summaries.
8+
- Failed gates can be described as partial success.
9+
- Scripts can be mislabeled as agents.
10+
11+
## With SpecX
12+
13+
- The task starts from a contract.
14+
- Required agents, tools, evidence, gates, artifacts, and failure semantics are explicit.
15+
- Decisions are gate-bound and evidence-bound.
16+
- Missing evidence blocks the workflow.
17+
- Failed verification remains failed.
18+
- Script-only components stay tools.
19+
20+
## Core Claim
21+
22+
Stop agents from pretending success.
23+
Make every task contract-bound, gate-bound, evidence-bound, and failure-explicit.

‎docs/contract-format.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Contract Format
2+
3+
A SpecX contract is the execution boundary for an agent workflow.
4+
5+
## Required Fields
6+
7+
- `contract_id`
8+
- `version`
9+
- `objective`
10+
- `domain`
11+
- `task_type`
12+
- `required_agents`
13+
- `required_tools`
14+
- `required_evidence`
15+
- `gates`
16+
- `expected_artifacts`
17+
- `failure_semantics`
18+
- `execution_constraints`
19+
20+
## Agent Specs
21+
22+
Each item in `required_agents` must define:
23+
24+
- `agent_id`
25+
- `role_spec`
26+
- `execution_spec`
27+
- `output_spec`
28+
29+
An item without LLM-backed decision authority must not be labeled as an agent. Script-only validators, launchers, and transformers are tools.
30+
31+
## Gates
32+
33+
Each gate must define:
34+
35+
- `gate_id`
36+
- `condition`
37+
- `on_failure`
38+
39+
Gate failure must return `blocked` or `failed`. It must not be converted into success.
40+
41+
## Failure Semantics
42+
43+
Use explicit states:
44+
45+
- `blocked`: required input, evidence, spec, approval, or gate is missing.
46+
- `failed`: execution or verification failed.
47+
- `unsupported`: requested capability is not implemented.
48+
49+
## Required Constraints
50+
51+
```json
52+
{
53+
"execution_constraints": {
54+
"no_fake_success": true,
55+
"no_silent_fallback": true,
56+
"no_hardcoded_fallback": true
57+
}
58+
}
59+
```
60+
61+
Missing constraints should fail verification.

‎docs/quickstart.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Quickstart
2+
3+
SpecX is a governance layer for Codex agents.
4+
5+
## Install
6+
7+
```bash
8+
codex plugin marketplace add BTCNAI/specx-codex-marketplace
9+
```
10+
11+
Pinned install:
12+
13+
```bash
14+
codex plugin marketplace add https://github.com/BTCNAI/specx-codex-marketplace.git --ref v0.1.0
15+
```
16+
17+
## Validate A Contract
18+
19+
```bash
20+
python3 scripts/specx_cli.py validate examples/demo_software_engineering_contract.json
21+
```
22+
23+
Expected success:
24+
25+
```json
26+
{
27+
"ok": true,
28+
"result": {
29+
"contract_id": "demo-software-engineering-001",
30+
"status": "valid"
31+
}
32+
}
33+
```
34+
35+
## Compile A Contract
36+
37+
```bash
38+
python3 scripts/specx_cli.py compile examples/demo_software_engineering_contract.json
39+
```
40+
41+
Compilation produces an execution plan with agents, tools, evidence requirements, gates, artifact plan, verification plan, failure semantics, and constraints.
42+
43+
## Verify A Contract
44+
45+
```bash
46+
python3 scripts/specx_cli.py verify examples/demo_software_engineering_contract.json
47+
```
48+
49+
Verification fails closed when gates, required agents, artifacts, failure semantics, or `no_fake_success` / `no_silent_fallback` constraints are missing.
50+
51+
## Current Boundary
52+
53+
`v0.1.0` is skills + CLI. MCP tools are planned next:
54+
55+
- `specx.validate`
56+
- `specx.compile`
57+
- `specx.verify`
58+
- `specx.explain`

‎docs/use-cases.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Use Cases
2+
3+
## Software Engineering
4+
5+
Before:
6+
7+
```text
8+
Refactor this backend.
9+
```
10+
11+
After SpecX:
12+
13+
- Planner and verification agents are explicit.
14+
- Public behavior inventory is required before edits.
15+
- Tests and diff evidence are required before success.
16+
- Missing verification becomes `blocked` or `failed`.
17+
18+
Demo: `examples/demo_software_engineering_contract.json`
19+
20+
## Research Tasks
21+
22+
Before:
23+
24+
```text
25+
Research this market.
26+
```
27+
28+
After SpecX:
29+
30+
- Source quality gates are required.
31+
- Claims require citations.
32+
- Decision packets include risk notes.
33+
- Unsupported claims stay unsupported.
34+
35+
Demo: `examples/demo_research_task_contract.json`
36+
37+
## Multi-Agent Systems
38+
39+
Before:
40+
41+
```text
42+
Agents freestyle.
43+
```
44+
45+
After SpecX:
46+
47+
- Runtime is contract-first.
48+
- Planner, executor, and verifier boundaries are explicit.
49+
- Every decision requires evidence and gate checks.
50+
- Failure state is explicit.
51+
52+
Demo: `examples/demo_multi_agent_system_contract.json`

0 commit comments

Comments
 (0)