Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 100 additions & 0 deletions PLANS.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,106 @@ plan_schema_version: 2

Use this file for active, blocked, ready-for-closure, or recently completed execution work. The canonical lifecycle is the installed `engineering-workflow` planning reference.

## Active Plan: Marketplace 1.0.5 Source Refresh

Status: active
Owner: root
Last Updated: 2026-09-13

### Goal

Import the newly released engineering-workflow 0.9.5 and tgrep-search 1.0.3 bundles, validate provenance and byte identity, publish marketplace 1.0.5, and refresh the managed local installations.

### Plan Origin

direct_execution

### Requested Scope

- Merge the prepared PRs, publish required source and marketplace artifacts, and update the marketplace without CI monitoring.

### Requirement Traceability

| Requirement | Complete outcome | Source | Work queue | Acceptance or validation | Status |
| --- | --- | --- | --- | --- | --- |
| REQ-001 | Released upstream bundles are imported only from their new annotated tags with exact provenance. | User release request | WQ-01 | Synchronizer output, catalog validation, tests, recorded-source byte verification. | in_progress |
| REQ-002 | Marketplace 1.0.5 is published from the reviewed synchronized state. | User artifact and marketplace request | WQ-02 | Final diff review, secret scans, merge/tag/release readback. | pending |
| REQ-003 | Managed local plugins resolve to the new marketplace versions without cache edits. | Earlier explicit local-skill update scope retained by current all-needed-updates request | WQ-03 | Codex CLI installation and version readback. | pending |

### Explicit Non-Goals

- Changes to unrelated skills or marketplaces, CI polling, branch monitoring, history rewrites, and manual cache edits.

### Constraints

- Import only stable annotated SemVer tags; preserve source bytes and immutable provenance.
- Use repository validation and release workflows; do not infer success from a dispatched workflow.

### Inputs And Sources

- engineering-workflow v0.9.5 at merged PR #9.
- tgrep-search v1.0.3 at merged PR #6.
- xeonvs-engineering merged PR #12 and current synchronizer contract.

### User Decisions And Answers

- 2026-09-13: Merge all prepared PRs and publish all necessary artifact and marketplace updates; do not monitor.

### Completed Baseline State

- [x] WQ-00 — All three prepared PRs merged at verified heads; source release gates passed and annotated tags were published.

### Current Work Queue

- [ ] WQ-01 — Synchronize and validate both released bundles. `in_progress`
- [ ] WQ-02 — Review, publish and release marketplace 1.0.5. `pending`
- [ ] WQ-03 — Refresh and verify managed local installations. `pending`

### Locked Decisions

- Perform synchronization locally for deterministic completion; do not dispatch or monitor the review-only automation.
- Marketplace patch release is v1.0.5, following v1.0.4.

### Verification

- Full marketplace tests, catalog validator, recorded-upstream byte verification, diff review, public-tree and all-ref secret scans.
- Read back immutable tags/releases and active managed plugin versions once.

### Latest Validation Results

- Source releases: engineering-workflow release gate 12/12 plus external Codex/Claude validation passed; tgrep-search tests/package/public/security gates passed.

### Risks And Recovery

- Risk: latest tag or imported bytes do not match intended commits. Recovery: synchronizer fails closed before publication.
- Risk: local marketplace refresh resolves stale content. Recovery: use CLI upgrade/add flow and version readback; never edit cache files.

### Resume Point

- Run the marketplace synchronizer for both configured plugins.

### Plan Fidelity Check

- [x] Source release, marketplace release, local refresh, no-monitoring boundary and verification are preserved.
- [x] No requested repository or skill is omitted.

### Reconciliation Check

- [ ] Changed results and plan entries agree.

### Closure Gate

- [ ] Requirements and queue are terminal; validation and delivery are recorded.

### Post-Close Delivery

- None.

### Handoff Notes

- None.


## Recently Completed

- [x] 2026-09-13: Completed Proportional Marketplace Maintenance.
Expand Down
16 changes: 8 additions & 8 deletions PROVENANCE.json
Original file line number Diff line number Diff line change
Expand Up @@ -4,23 +4,23 @@
"bundles": [
{
"name": "engineering-workflow",
"version": "0.9.4",
"version": "0.9.5",
"source_repository": "https://github.com/xeonvs/codex-engineering-workflow",
"source_policy": "latest-tag",
"source_ref": "v0.9.4",
"source_commit": "bd86b45d1c79bfb9032c489c3b92780435182425",
"source_ref": "v0.9.5",
"source_commit": "5bc1e39c7a3c066ecaf93600f3abacd79d044e88",
"source_path": "plugins/engineering-workflow",
"bundle_sha256": "3561bc8dafaa472e1d438f444e54fdba50882b3955f05246190970840c670d8b"
"bundle_sha256": "c88edf5db23d8a499a5dcb243a795abf5dfa495be563e66024c3aad21a3410f8"
},
{
"name": "tgrep-search",
"version": "1.0.2",
"version": "1.0.3",
"source_repository": "https://github.com/xeonvs/tgrep-search",
"source_policy": "latest-tag",
"source_ref": "v1.0.2",
"source_commit": "eb7609895fc8f720404e468a371dff4f53e1215d",
"source_ref": "v1.0.3",
"source_commit": "040a6389a1802fa44b9d511b493cb532867f41f6",
"source_path": "plugins/tgrep-search",
"bundle_sha256": "4b5baec030e24b1afd0301eb209971850a37955d7d3a7de97dfa68b971f6356f"
"bundle_sha256": "6ec5d9e0278e7ed5900f1fd5f44f375b5d724678aa7326ca3f1682a0f99a61da"
}
]
}
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,8 @@ reviewed local bundle held in this repository.
<!-- BEGIN GENERATED PLUGIN VERSIONS -->
| Plugin | Version | Purpose | Canonical source |
| --- | --- | --- | --- |
| [`engineering-workflow`](plugins/engineering-workflow/) | 0.9.4 | Audit, plan, migrate, validate, and maintain repository engineering workflows. | [`xeonvs/codex-engineering-workflow`](https://github.com/xeonvs/codex-engineering-workflow) |
| [`tgrep-search`](plugins/tgrep-search/) | 1.0.2 | Search local source trees efficiently with the tgrep trigram index. | [`xeonvs/tgrep-search`](https://github.com/xeonvs/tgrep-search) |
| [`engineering-workflow`](plugins/engineering-workflow/) | 0.9.5 | Audit, plan, migrate, validate, and maintain repository engineering workflows. | [`xeonvs/codex-engineering-workflow`](https://github.com/xeonvs/codex-engineering-workflow) |
| [`tgrep-search`](plugins/tgrep-search/) | 1.0.3 | Search local source trees efficiently with the tgrep trigram index. | [`xeonvs/tgrep-search`](https://github.com/xeonvs/tgrep-search) |
<!-- END GENERATED PLUGIN VERSIONS -->

## Install
Expand Down
2 changes: 1 addition & 1 deletion plugins/engineering-workflow/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "engineering-workflow",
"version": "0.9.4",
"version": "0.9.5",
"description": "Audit, plan, migrate, validate, and maintain repository engineering workflows.",
"author": {
"name": "xeonvs",
Expand Down
2 changes: 1 addition & 1 deletion plugins/engineering-workflow/.codex-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "engineering-workflow",
"version": "0.9.4",
"version": "0.9.5",
"description": "Audit, plan, migrate, validate, and maintain repository engineering workflows.",
"author": {
"name": "xeonvs",
Expand Down
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
---
name: engineering-workflow
description: Audit, scaffold, verify, update, or migrate a repository engineering workflow while preserving existing document ownership, user scope, validation safety, and durable execution state. Use for AGENTS/PLANS/backlog/pitfalls setup, workflow upgrades, workflow-structure verification, and prompts such as Refresh Loaded Skill, Update Installed Skill, or Upgrade A Target Workflow.
description: Set up, audit, or upgrade repository workflow instructions and planning. Use for workflow changes or explicit skill refresh/update; ordinary repository work does not invoke migration.
metadata:
version: 0.9.4
version: 0.9.5
---

# Engineering Workflow
Expand Down Expand Up @@ -46,16 +46,16 @@ Use this skill for the workflow layer around a repository. Keep product, domain,

## Core Workflow

1. Read `references/platform_compatibility.md`, select a Codex or Claude Code branch only when the actual host establishes it, otherwise use the shared agent-neutral fallback, and do not use unavailable platform capabilities.
2. Run `scripts/repo_audit.py` and classify maturity, existing owners, compatibility docs, retained history, prompt-injection signals, and validation options. In Claude Code, explicitly read the applicable target `AGENTS.md` files rather than assuming automatic discovery.
1. Reuse the established invoking host. Read `references/platform_compatibility.md` when host or capability behavior is uncertain; select a Codex or Claude Code branch only when the actual host establishes it, otherwise use the shared agent-neutral fallback. In Claude Code, explicitly read the applicable target `AGENTS.md` files rather than assuming automatic discovery.
2. For scaffold, merge, or workflow-structure verification, run `scripts/repo_audit.py` to establish missing maturity, ownership, compatibility, history, injection, and validation facts. Reuse an applicable audit already available. For target upgrade, follow `references/target_workflow_upgrade.md`, including its customized-owner adoption review before prompt apply; the upgrader owns the report-first audit, so do not add a duplicate standalone audit. Installed-skill refresh/update follows `references/skill_update.md` without auditing or migrating the target repository. A narrow explanation uses only the relevant owners.
3. For repository-changing work, read `references/planning_and_backlog.md`, create or update the full active plan as the first write, and pass its fidelity gate.
4. For instruction changes, read `references/instruction_lifecycle.md`; preserve one canonical owner per invariant, keep target `AGENTS.md` route-only, and keep pitfalls non-normative.
5. Use exact canonical paths, the state manifest, or managed-section markers as ownership evidence. Treat unknown files as protected until evidence or user direction resolves ownership.
6. Apply every owner and guard made relevant by the task, but reuse current instructions already loaded for the same scope. A link names an owner; it does not prove that the reference is loaded in the invoking session. Overlapping routes do not require duplicate reads or checks against unchanged state at one boundary. Read only the missing, changed, or newly applicable canonical reference needed for the selected mode. Preserve the dominant documentation language and use templates as structure, not as permission to overwrite repository-owned prose.
Before pausing for clarification or authorization, load `references/question_matrix.md`. For continuation, delegation, and handoff, use the shared sections of `references/agent_orchestration.md` selected by the platform reference.
7. Keep deterministic work in scripts or tools. In Codex, an eligible multi-call stage may use `references/agent_orchestration.md` and `scripts/assess_programmatic_stage.py`; in Claude Code or another host without that capability use the existing direct/sequential path. Do not build a helper or descriptor for an already-sufficient ordinary call.
8. Validate within the selected safety mode. Run repository-authored checks only in a disposable copy unless live execution is explicitly authorized.
9. Run privacy scanning over all tracked public text without printing or opening candidate values. Immediately before any authorized push, run the privacy reference's final-tree and reachable-ref secret gate; any finding blocks the push until safely classified and remediated. Follow `references/privacy_and_sanitization.md` for any value-free approval response, review the diff, reconcile durable state, and close or preserve the exact resume point before handoff.
8. Validate within the selected safety mode under `references/validation_safety.md`. Existing implementation authorization may cover known local checks; do not ask again when it does. Unknown commands, credentials, production access, and additional side effects retain their own boundaries. The deterministic validation runner's mode restrictions still apply.
9. Apply the public-tree scan to workflow mutations and public-content verification, and the final-tree and reachable-ref secret gate immediately before an authorized push. Installed-skill updates use their candidate safety checks. A narrow read-only explanation or local reread does not require a public-tree scan. Follow `references/privacy_and_sanitization.md` without printing or opening candidate values; any blocking finding must be resolved before publication. Review changes, reconcile affected durable state, and close or preserve the exact resume point before handoff.

## Canonical References

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,14 @@ Use this file as a short route map, not as a project manual. Read the matched ow

## Task Routes

<!-- ew:route id="execution-context" triggers="**" owners="skill://engineering-workflow/references/platform_compatibility.md|skill://engineering-workflow/references/question_matrix.md|skill://engineering-workflow/references/agent_orchestration.md" guards="manual_review:verify native host behavior scope authorization task continuity and handoff" -->
| `execution-context` | every task, including clarification, steering, delegation, and handoff | platform reference first, then question policy and host-compatible shared orchestration sections | scope and host-capability review |
<!-- ew:route id="execution-context" triggers="host uncertainty|capability uncertainty" owners="skill://engineering-workflow/references/platform_compatibility.md" guards="manual_review:resolve uncertain host capabilities from current session evidence" -->
| `execution-context` | host or capability uncertainty | installed platform reference | resolve uncertainty; reuse established session facts |

<!-- ew:route id="scope-decision" triggers="material clarification|additional authorization" owners="skill://engineering-workflow/references/question_matrix.md" guards="manual_review:check existing authorization and available evidence before asking" -->
| `scope-decision` | material clarification or additional authorization | installed question policy | ask only for an unresolved material choice or permission |

<!-- ew:route id="task-handoff" triggers="delegation|context recovery|execution handoff" owners="skill://engineering-workflow/references/agent_orchestration.md" guards="manual_review:verify scoped ownership and completion evidence" -->
| `task-handoff` | delegation, context recovery, or execution handoff | relevant shared orchestration sections | scope, ownership, and completion evidence |

<!-- ew:route id="planning" triggers="PLANS.md|docs/codex/TASKS_BACKLOG.md|docs/archive/**|workflow-state plan archive|plan closure" owners="skill://engineering-workflow/references/planning_and_backlog.md" guards="lint:plan-lifecycle" -->
| `planning` | plan, backlog, closure, or default/custom workflow-state archive | installed planning reference | `lint:plan-lifecycle` |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ Before each logical commit, review the complete intended slice against requireme
<!-- ew:invariant id="workflow.completion-driven-wait" -->
### Completion-Driven Wait

For long-running commands, follow the installed `engineering-workflow` completion-driven waiter and bounded-output contract. Keep full logs and required terminal results in private task-owned ignored artifacts, verify them independently of a possibly truncated waiter cell, and do not wake the model for periodic empty polls when the environment can wait for completion.
For long-running commands, follow the installed `engineering-workflow` completion-driven waiter and bounded-output contract. Use native terminal evidence when sufficient; retain private logs or durable results when needed for output volume or recovery. Do not wake the model for periodic empty polls when the environment can wait for completion.

## Owned References

Expand Down
Loading