About

AI coding agents are inconsistent. Without structure, they skip conventions, ignore shared state, and bypass quality gates.

workflow-state-engine-kit is an OpenCode plugin that replaces prose conventions with machine-readable enforcement. Install once — every project session gets agents, skills, MCPs, slash commands, and contract-based orchestration automatically.

Built with Node.js, OpenCode, lean-ctx, graphify, and GitNexus.

Getting Started

Prerequisites

• Node.js >= 18
• Git
• OpenCode installed and configured

node --version    # >= 18
git --version     # any recent version

Installation

Step 1 — Install globally (one-time)

npm install -g @ikieaneh/workflow-state-engine-kit

Step 2 — Add to your project

{
  "plugin": ["@ikieaneh/workflow-state-engine-kit"]
}

Add the snippet above to your project's opencode.json. Open your project in OpenCode — the plugin handles everything else.

Usage

After installation, verify everything loaded:

npx workflow-state-engine-kit doctor

Expected output:

✅ contract.json
✅ rules.json
✅ 18 agents provisioned
✅ 40 skills provisioned
✅ 7 rule files loaded
✅ All checks passed

Slash Commands (18)

| Category | Commands | |:---------|:---------| | Health & Status | doctor, status, preflight, verify | | Analytics & Scoring | analytics, score | | Contract | contract-lint, diff, lock | | Checkpoints | checkpoint, checkpoint-save | | Project Tools | audit, init, update, update-version, version | | ADRs | adr | | Logs | logs |

All commands are prefixed with /workflow-kit: — e.g., /workflow-kit:doctor.

What You Get

Agents (21)

| Agent | Purpose | |:------|:--------| | orchestrator | Delegates, validates, drives state machine | | planner | Analyzes requests, traces impact, produces plans | | task-manager | Breaks plans into tasks, implements each step | | code-reviewer | Read-only code review — quality, security, performance | | explorer | Fast codebase search across the entire project | | librarian | Authoritative source for library docs and API references | | architect | Strategic technical advisor for high-stakes decisions | | fixer | Fast implementation for well-defined bounded tasks | | learner | Post-execution learning — extracts lessons, persists knowledge | | observer | System state monitor — read-only | | database-specialist | Schema design, queries, migrations, optimization | | devops-agent | CI/CD, deployment, infrastructure, automation | | documentation-agent | Maintains README, API docs, inline documentation | | security-reviewer | Vulnerability assessment and security best practices | | testing-specialist | Unit tests, integration tests, test strategies | | council | Multi-LLM consensus engine for high-stakes decisions | | designer | UI/UX design, review, and implementation | | oracle | Strategic technical advisor for architecture and debugging | | definer | DEFINE phase — brainstorming, spec writing, ADR creation | | verifier | VERIFY phase — quality gates, test results, blast radius | | integrator | CROSS-CUTTING — merge conflicts, dependency resolution, state sync |

Skills (40)

| Category | Skills | |:---------|:-------| | DEFINE | brainstorming, writing-plans, adr-generator, codemap | | PLAN | orchestration-template, orchestration-workflow, dispatching-parallel-agents, using-git-worktrees | | EXECUTE | subagent-driven-development, executing-plans, test-driven-development, database-design, sql-optimization, deployment, system-analyst, infrastructure, firecrawl-* (7 skills) | | VERIFY | quality-checks, verification-before-completion, testing-strategies, systematic-debugging, ci-cd | | REVIEW | requesting-code-review, receiving-code-review, security-audit, simplify, qa-expert | | CROSS-CUTTING | humanizer, token-optimize, using-superpowers, learner, scoring-pipeline, gitnexus-exploring |

MCPs (5)

| MCP | Purpose | |:----|:--------| | lean-ctx | Token-compressed file/shell gateway (mandatory) | | gitnexus | Code intelligence and impact analysis | | context7 | Library documentation lookup | | firecrawl | Web search, scraping, and interaction | | github | GitHub API access |

Plus graphify (CLI tool, not MCP) for codebase graph intelligence.

.workflow-kit/ Storage

The plugin provisions agent templates, skills, rules, and contract files into .workflow-kit/ — all auto-managed, no manual setup needed.

Contract Enforcement

• 7-layer contract enforcement — Machine-readable workflow rules in contract.json that agents cannot bypass. Orchestrator forced to delegate (exploration→@explorer, implementation→@fixer), scoring thresholds (≥80 PASS), mandatory checkpoints + audit trail at every step.

Auto-Update & Version Staleness

The plugin self-updates on every session start. Before loading, autoUpdate checks the npm registry for the latest version and installs it automatically if a newer version is available.

To prevent stale cached versions from persisting across sessions, autoUpdate clears these cache paths:

| Cache Path | Purpose | Cleared? | |:-----------|:--------|:---------| | ~/.cache/opencode/packages/@ikieaneh/ | Extracted plugin cache | ✅ | | ~/.cache/opencode/pkgs/ | Transient npm fetch cache | ✅ | | ~/.cache/opencode/bun.lock | Bun lockfile | ✅ | | npm cache clean @ikieaneh/workflow-state-engine-kit | npm content-addressable cache | ✅ | | /opt/homebrew/.../node_modules/@ikieaneh/workflow-state-engine-kit | Brew-installed global module | ✅ | | npm root -g/@ikieaneh/workflow-state-engine-kit | npm global install (dynamic path) | ✅ |

Manual cleanup (nuclear option): If a project's .opencode/ directory is stale or corrupted, remove it and restart:

cd /path/to/stale-project
rm -rf .opencode/

The plugin re-provisions all files on the next session open.

Architecture

workflow-state-engine-kit is built on the Workflow Agent State Engine (WASE) — a phase-gated workflow platform with three pillars:

WAE (Workflow Agent Engine) — Phase-gated orchestration across 6 phases (DEFINE → PLAN → EXECUTE → VERIFY → REVIEW → COMPLETE), with 13 states including intermediate scoring transitions. Each agent is tagged by its primary phase and restricted to phase-appropriate skills.

WAC (Workflow Agent Contract) — contract.json serves as the API contract for the entire workflow. Written in wac-1.0 schema with dual persistence (memory + disk). Every agent reads/writes the contract. State transitions are validated against the transitions map. Scoring thresholds: ≥80 PASS, 50-79 RETRY, <50 BLOCKED (max 3 retries per phase).

WAS (Workflow Agent Summary) — 6-layer persistent memory: ctx_knowledge (facts), ctx_session (state), state.md (YAML checkpoint), project.md (narrative memory), graphify (knowledge graph on REVIEW_SCORED), gitnexus (reindex on EXECUTE_SCORED). State sync runs after every scored phase.

Inheritance Model

workflow-state-engine-kit uses class inheritance: projects extend the base, not replace it.

{
  "_meta": {
    "extends": "workflow-state-engine-kit",
    "overrides": ["requirements.goal"],
    "appends": ["scope.included"]
  },
  "requirements": {
    "goal": "Project-specific goal (overrides base)"
  }
}

| Layer | Extend Via | Example | |:------|:-----------|:--------| | Contract | _meta.overrides / _meta.appends | Override goal, append scope | | Agents | _meta.append_skills | Add project-specific skills | | Rules | _meta.appends: ["rules"] | Add custom rules | | Skills | Add to .opencode/skills/ | Create my-api-client/SKILL.md |

Merge rules:

• Scalars: project overrides base
• Arrays: concatenated + deduplicated
• Objects: deep merged (project wins)
• Excludes: _meta.excludes removes inherited items

See docs/inheritance-model.md for full architecture.

Roadmap

• [x] Auto-provision agents, skills, rules
• [x] Auto-config opencode.json
• [x] ADR reports and session summaries
• [x] Task complexity detection
• [x] Graphify integration
• [x] MCP availability checks
• [x] Inheritance model with overrides and appends
• [x] Scoring pipeline (PASS/RETRY/BLOCKED)
• [ ] Multi-language agent support
• [ ] Web-based dashboard
• [ ] VS Code extension

See ROADMAP.md for full details.

Contributing

See CONTRIBUTING.md for full guidelines.

Fork → Feature branch → Commit → PR. Follow the enforcement architecture. All rule enforcements must be tested.

License

Distributed under the MIT License. See LICENSE for more information.

Contact

RizkiRachman — GitHub

Project Link: https://github.com/RizkiRachman/workflow-state-engine-kit