Risk-proportionate engineering workflows for Codex, Claude and OpenCode. One shared plugin combines selected Spec Kit, OpenSpec and Superpowers practices with durable project state, cohesive implementation slices and architecture verification. Small edits stay small; complex changes receive the evidence they need.
Every skill follows a shared proportionality rule: local checks first, reuse unaffected evidence, focused review of fixes, and an effort brake before testing or delegation grows beyond the task. Subscription limits and model-effort permissions remain binding across quota resets.
Version 0.3.2 adds a runner for unscripted routing evaluations and fixes host runs that timed out without output. See the release notes. Earlier scopes: 0.3.1 added a test that holds every skill to the published skill authoring limits, 0.3.0 separated writing into its own plugin and bundled shared support from a pinned Method Core, 0.2.1 refined local PDF export, 0.2.0 added documentation and playbook work, and 0.1.1 added native OpenCode integration. The historical 0.1.0 baseline has independently accepted complete original gate coverage, with documented evidence reuse and corrections. Read the acceptance limits before relying on it for unattended work. The approved design records the intended scope.
The earlier v0.1.0-rc.1 pre-release remains available with its original, reduced
acceptance scope.
The historical release 0.2.1 retained the 0.2.0 scale-aware documentation, Humanizer drafting, playbook and read-only state-check work while refining the local Quarto/Typst PDF export. Its verification covers 319 local tests, five documentation routing cases on each of Codex and Claude, and two bounded native OpenCode probes; the playbook record adds no native routing evaluation.
Version 0.3.2 is the current stable release; 0.2.1 was the last release that bundled the writing skills.
Version 0.3.0 separates writing into Writing Method. Method Core owns the bundled host adapters, state/continuity tools, verification/review/isolation support and generic playbooks. Each repository keeps its own Issues and pull requests; the common topic is agent-methods.
Engineering owns Spec Kit, OpenSpec, architecture, debugging and TDD. Writing owns documentation planning, authoring, review, didactic guidance and PDF delivery. Each plugin runs independently. Both expose byte-identical shared support under their own namespaces; invoke the current method's copy, for example engineering-method:playbook-authoring, once. Core is bundled source, not a third plugin installation. Gemini adapter work remains deferred.
Shared changes originate in Core. From this checkout run python3 /absolute/path/to/method-core/scripts/sync-core --source-root /absolute/path/to/method-core --target-root ., then python3 scripts/sync-core --check and the verification commands below. Commit copies and method-core.lock.json together. Sync refuses local drift and unowned conflicts; write failures attempt restoration of the previous files/modes/lock. After a process abort or incomplete rollback, fix the reported disk/permission error and run python3 scripts/sync-core --recover before retrying; original backups remain until recovery succeeds. To roll back, synchronize the previous full Core revision with --revision. Existing engineering_method imports, CLI wrapper names, project .engineering-method/ state and work IDs remain unchanged. Reinstall copied host plugins and restart the session after updating.
Requires Python 3.11+, Git, and Codex CLI, Claude Code or OpenCode.
OpenCode uses the separate source-linked installation described below.
GitHub task synchronization additionally requires authenticated gh and repository
permissions. No upstream Spec Kit, OpenSpec or Superpowers installation is needed.
Version 0.3.0's local package installation and coexistence were checked with Codex CLI 0.169.0 and
Claude Code 2.1.323;
other host versions and operating systems are not covered by that evidence.
Install from phense/engineering-method:
# Codex
codex plugin marketplace add phense/engineering-method
codex plugin add engineering-method@engineering-method
# Claude Code
claude plugin marketplace add phense/engineering-method
claude plugin install engineering-method@engineering-methodStart a new host session in your target project, then describe the change you
want. These commands follow the repository's default branch. For the fixed
release, local packages, updates, disabling and removal, see
Installation and maintenance. Disable overlapping
lifecycle plugins, including Superpowers, before using Engineering Method.
Claude also supports session-only loading with claude --plugin-dir and an
absolute plugin directory; see the installation guide.
OpenCode can load the same shared skills through a source-linked native adapter; its recorded discovery evidence covers the 17 skills of version 0.1.1. See OpenCode installation for setup, verification and the bounded OpenCode 1.18.30 / DeepSeek acceptance scope. This addition is separate from the historical v0.1.0 dual-host release evidence.
Describe the engineering outcome. The host selects skills from exclusive descriptions, existing artifacts and explicit handoffs; there is no central router and no methodology-selection question. Quality skills support one primary lifecycle rather than start competing plans.
| Work and current artifacts | Selected workflow |
|---|---|
| Small reversible docs/configuration or mechanical edit without behavior-contract impact | Focused edit and targeted verification; no spec, plan or UML cycle |
| Reproducible failure or unexplained regression | Systematic debugging, meaningful regression test, fix and verification |
| Bounded intentional change to existing behavior | OpenSpec propose → apply → archive |
| New subsystem, multi-component feature, architecture change or risky migration | Spec Kit specify → plan → architecture gate → tasks → orchestrated implementation → converge |
| Existing Spec Kit or OpenSpec artifacts | Continue the recorded phase; preserve completed work |
Review, TDD, worktrees and parallel dispatch activate only when their own conditions apply. If a bounded change reveals architectural scope, its formal escalation artifact preserves the original work and transfers ownership.
The playbook policy distinguishes procedures needed to carry out development from procedures delivered with the system. Specification identifies system-playbook requirements; planning assesses critical development operations. Tasks make a development playbook ready before its operation and a system playbook ready before delivery. Small reversible work does not acquire a playbook by default.
playbook-authoring creates scenario-bound decisions, actions, verification,
interruption recovery and rollback paths. playbook-review checks the procedure
without relying on the author's background knowledge. They support the existing
engineering owner, including direct playbook requests, and do not execute the
procedure. Drafted, reviewed and rehearsed are separate facts; generation never
sets the validation date. Missing or stale required evidence blocks the dependent
operation, convergence or archival.
Default target-project paths are docs/playbooks/development/ and
docs/playbooks/system/, with separate review/rehearsal records. Existing
project conventions take precedence. These skills are new in release 0.2.0; see
the bounded verification record.
Writing workflows and their local PDF template live in the optional Writing Method companion. Install it when documentation planning, drafting, didactic support or PDF delivery is needed. Engineering Method keeps engineering artifacts and its own work IDs.
Large features and architecture changes use relevant Mermaid sources under
docs/uml. Each diagram answers a named question and identifies its requirements,
source evidence and verification date. Small changes do not acquire an
architecture gate merely because diagrams exist.
Design findings become ordinary tasks before implementation. After cohesive slices complete, a system architect reconciles the as-built diagrams with code and derives cross-component success and relevant failure, rollback or recovery tests. Convergence requires current reconciliation, integration results, resolved review findings and fresh verification. Remaining findings return to the same executor as new slices, preserving completed work.
Independent reviews cover risky or integration-bearing slices. Mechanical work can use coordinator review. Failed fixes require new evidence or a changed approach; repeated ineffective attempts escalate perspective rather than repeat the same prompt. Parallel writes require disjoint ownership and safe isolation.
These are agent instructions supported by contract tests and executable fixtures, not a mechanism that makes arbitrary host/model behavior infallible. Mermaid sources can be semantically checked without a renderer; rendered validation is reported separately when available.
BACKLOG.md is the canonical local task register. Stable IDs never change when
priorities change. Unblocking work comes first; status is open, in progress,
complete or blocked. FEATURES.md records working capabilities, not another
task list. Large local backlogs archive eligible completed groups while retaining
active dependencies.
backlog state-check only reports state; it never migrates or writes local or
remote data. Migration requires explicit authorization and the separate
backlog-to-issues migrate command.
With a reachable authorized GitHub repository and suitable CLI permissions, migration preserves IDs and completed history in Issues. Hierarchy becomes sub-issues and dependency edges become native dependencies. All agent-authored GitHub titles, bodies, labels and comments are English. User communication can remain in the user's language.
After migration, Issues are canonical and BACKLOG.md is a marked cache.
An offline outage queues changes for reconciliation rather than creating a
second source of truth. Migration and refresh use embedded identity markers to
avoid duplicate issues. Current project restrictions on remote mutations still
apply. Publishing this repository does not migrate its backlog. Its task register remains
local until a separate migration is explicitly authorized.
Stateful workflows persist checkpoints, concise recovery notes, artifact pointers
and events in .engineering-method/runs/<work-id>/. The coordinator owns run
state; agents own their assigned reports. Dispatch, review, fixes, verification
and phase transitions form recovery boundaries.
After /compact or a new session, skills validate saved work against Git,
artifacts, canonical task state and host-observed agents before continuing.
Completed work is retained; stale memory cannot override repository evidence.
This is explicit workflow checkpoint/recovery behavior, not a universal host
hook that intercepts every possible compaction.
The plugin works without agentic-rag. A separate downstream integration may index events and recall a work ID plus artifact pointers; it never becomes the canonical state writer. Project instructions and explicit user constraints remain authoritative.
The common core uses strong, standard and fast roles. Concrete model IDs,
effort levels and tool names live in the host adapters. The coordinator owns
architecture, cross-slice interfaces, integration and final acceptance.
Adapters inspect actual host capabilities, record unavailable preferred tiers, and fall back without asking the user to choose a methodology. If delegation or safe worktree isolation is unavailable, work proceeds sequentially when possible. The plugin never claims to change the current main model when the host cannot do so. Escalating model effort respects the adapter's explicit approval boundary.
Run the inexpensive local checks from the checkout root:
python3 -m unittest discover -s tests -t . -v
python3 scripts/validate-plugin
claude plugin validate --strict .Contributing covers provenance, committed-source reproducible packaging and isolated clean installation. Full release evaluations require separate budget authorization and are not implied by these local checks.
- Usage examples: a small edit, bug repair, a bounded existing-system change, a large feature, one document, a documentation set, reader-oriented replies, and recovery after compact or a new session.
- Contributing: local checks, provenance, packaging and review.
- Verification history: bounded candidate acceptance and the subsequent complete gate coverage.
Skill descriptions and artifact handoffs guide host selection; they cannot force every model to route correctly or follow every instruction. Delegation and isolation depend on tools actually exposed by the host. Continuity requires explicit checkpoints; there is no universal compact hook. agentic-rag is optional. GitHub task operations have fake-boundary coverage, not live mutation acceptance. Mermaid validation covers semantic sources, not rendered diagrams.
The accepted baseline covers 308 local tests, 24 native routing cases and the architecture fixture on both hosts. Acceptance reused unchanged evidence and included a Claude checkpoint instruction supplement and one verified report metadata correction. No single successful full release-check invocation is claimed. Native Codex recovery in the unborn fixture repository remains outside that live proof; continuity has script-test coverage. See the acceptance record for exact limits.
Copyright (c) 2026 Peter Hense. Distributed under the MIT License. The third-party notices and source lock contain pinned revisions, file mappings, hashes and complete MIT notices.
- GitHub Spec Kit: adapted specification, planning, task and convergence practices/templates.
- OpenSpec: adapted bounded-change proposals, application and archival practices/templates.
- Superpowers: adapted debugging, TDD, verification, reviews, worktree and delegation practices.
- SRE Runbook Agent Skills: adapted playbook authoring, review and templates.
- Han: selected need, origin and validation rules adapted into the playbook policy.
- Humanizer: adapted AI-writing patterns as drafting-time constraints for documentation.
Project-state implementation, architecture modeling, host adapters and validation fixtures are original work. Orchestration combines original policy with the specifically mapped adapted mechanics; it is not a wholesale upstream copy. Upstream names identify sources and do not imply affiliation with or endorsement by their maintainers.