Skip to content

Reduce workflow instruction and execution overhead #9

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
xeonvs merged 1 commit into from
Sep 13, 2026
Merged

Reduce workflow instruction and execution overhead #9

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
17 changes: 11 additions & 6 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,13 +20,16 @@ Reference paths beginning with `references/` below resolve under `skill/engineer

| Trigger or changed area | Read before editing | Required gate |
| --- | --- | --- |
| Every task, including scope questions, steering, delegation, or handoff | `skill/engineering-workflow/references/platform_compatibility.md` first; then `references/question_matrix.md` and the host-compatible shared sections of `references/agent_orchestration.md` | Review native host behavior, established authorization, task continuity, and evidence |
| Host or capability uncertainty | `references/platform_compatibility.md` | Resolve only the uncertain host behavior; reuse established session facts |
| Material clarification or additional authorization | `references/question_matrix.md` | Check existing authorization and available evidence before asking |
| Delegation, context recovery, or execution handoff | Relevant shared sections of `references/agent_orchestration.md` | Scope, ownership, and completion evidence |
| Runtime routing or public skill behavior | `skill/engineering-workflow/SKILL.md` and the directly linked canonical reference | Structural validator and affected behavioral tests |
| Plan, backlog, closure, archive, or index behavior | `references/planning_and_backlog.md`, plan/index templates, lifecycle scripts and tests | Plan lifecycle tests plus target validation |
| AGENTS, principles, pitfalls, provider/UI/operations ownership | `references/instruction_lifecycle.md`, related templates, instruction validator and tests | Instruction graph check plus migration tests |
| Installed-skill refresh or update | `references/skill_update.md`, updater and updater tests | Candidate-tree and rollback matrix |
| Target workflow upgrade | `references/target_workflow_upgrade.md`, audit/common/upgrader code and tests | Report/apply/prompt migration matrix |
| Validation, command execution, or privacy | `references/validation_safety.md`, `references/privacy_and_sanitization.md`, related scripts and tests | Safety matrix and public-tree scan |
| Validation policy or command-classifier changes | `references/validation_safety.md`, related scripts and tests | Affected safety matrix |
| Public-content sanitization or push | `references/privacy_and_sanitization.md`, related scanner | Required public-tree and pre-push scans |
| Agent orchestration or model mapping | `references/agent_orchestration.md`, `references/model_profiles.md`, agent templates and tests | Ownership/model-profile validation |
| Long-running execution or execution-efficiency rules | `references/agent_orchestration.md`, then `references/validation_safety.md` | Completion/result-integrity and affected behavioral tests |
| Version or release contract | `SKILL.md`, root `README.md`, upgrader defaults, state template, CI and version tests | Full gate and active-version search |
Expand All @@ -44,17 +47,19 @@ Reference paths beginning with `references/` below resolve under `skill/engineer

## Local Validation

Install the pinned root-only tooling once, run the narrowest affected layer while iterating, then run the complete gate:
Use one environment with the pinned root-only tooling. Select the narrowest affected profile while iterating; the examples below are alternatives, not a required sequence. Run `full` on the completed implementation. A read-only answer does not require implementation checks.

```bash
python3 -m pip install --requirement requirements-dev.txt
python3 scripts/dev_check.py focused --test-pattern test_plan_lifecycle.py
python3 scripts/dev_check.py contracts
python3 scripts/dev_check.py full
python3 scripts/dev_check.py focused --test-pattern test_plan_lifecycle.py # one affected suite
python3 scripts/dev_check.py contracts # affected cross-contract changes
python3 scripts/dev_check.py full # final implementation gate; includes the suites above
```

The harness forces `PYTHONDONTWRITEBYTECODE=1`, writes complete child output only to a private task-owned temporary directory, and prints a bounded status summary. It stops on the first failure by default. Raw failure tails require explicit `--show-failure-tail`; do not request them when output may contain private values. `format --fix` is the only mutating profile. The root harness and its Ruff configuration are repository-maintenance tools: never copy them into `skill/engineering-workflow`, target templates, generated marketplace skill bytes, or target migrations.

The local unit tests use disposable fixtures and no production services. A request to implement a change authorizes these checks and affected reruns without separate approval. External integrations and publication retain their own authorization boundaries.

Immediately before every authorized push, run `python3 scripts/dev_check.py security` against the final staged/public state. This pre-push gate includes the public-tree privacy scan plus fully redacted Gitleaks scans of the current tree and all reachable refs. A failure blocks the push: classify it without exposing the value, revoke or replace a real credential first, remove the source occurrence, and rescan. Rewrite published history only for a confirmed historical secret and only with explicit authorization, recovery refs, object-ID-pinned `force-with-lease`, and post-rewrite scans. The `release` profile composes `full` and `security`; external plugin validators remain separate because they depend on maintainer tooling.

Do not weaken a failing gate or leave cache, scanner, generated, backup, or temporary artifacts in the repository.
Expand Down
2 changes: 1 addition & 1 deletion PLANS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ Use this file for active, blocked, ready-for-closure, or recently completed exec

## Recently Completed

- [x] 2026-09-13: Completed Astra Workflow Instruction Efficiency; [full archived plan](docs/archive/plans/2026-09-13-astra-workflow-instruction-efficiency.md).
- [x] 2026-09-12: Completed Engineering Workflow 0.9.4 Plugin Brand Icon; [full archived plan](docs/archive/plans/2026-09-12-engineering-workflow-0-9-4-plugin-brand-icon.md).
- [x] 2026-09-12: Completed Engineering Workflow 0.9.3 Preserve Customized Plan Sections On Closure; [full archived plan](docs/archive/plans/2026-09-12-engineering-workflow-0-9-3-preserve-customized-plan-sections-on-closure.md).
- [x] 2026-09-12: Completed Engineering Workflow 0.9.2 Current-State Efficiency And Agent-Neutral Continuation; [full archived plan](docs/archive/plans/2026-09-12-engineering-workflow-0-9-2-current-state-efficiency-and-agent-neutral-continuati.md).
Expand All @@ -15,4 +16,3 @@ Use this file for active, blocked, ready-for-closure, or recently completed exec
- [x] 2026-08-28: Completed Engineering Workflow 0.8.2 Empty Compatibility Archive Index Fix; [full archived plan](docs/archive/plans/2026-08-28-engineering-workflow-0-8-2-empty-compatibility-archive-index-fix.md).
- [x] 2026-08-21: Completed Engineering Workflow 0.8.1 Privacy Review Token; [full archived plan](docs/archive/plans/2026-08-21-engineering-workflow-0-8-1-privacy-review-token.md).
- [x] 2026-08-20: Completed Engineering Workflow 0.8.0 Execution Discipline And Dual Marketplace; [full archived plan](docs/archive/plans/2026-08-20-engineering-workflow-0-8-0-execution-discipline-and-dual-marketplace.md).
- [x] 2026-08-16: Completed PTC Partial-Evidence Closure Correction 0.7.0.
24 changes: 13 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

`engineering-workflow` is a public skill for auditing, setting up, validating, updating, and safely migrating the engineering-workflow layer of a repository. It works with Codex and Claude Code.

Current skill version: `0.9.4`.
Current skill version: `0.9.5`.

The skill uses `AGENTS.md` as a short map, `PLANS.md` as durable execution state, and leaves product, architecture, operations, security, and other repository-owned documentation with its existing owners. Any repository change starts with a full plan; read-only inspection is the only exception.

Expand Down Expand Up @@ -73,7 +73,7 @@ Use $engineering-workflow to audit this mature repository and add only the missi
```

```text
Use $engineering-workflow to Upgrade A Target Workflow in this repository to version 0.9.4.
Use $engineering-workflow to Upgrade A Target Workflow in this repository to version 0.9.5.
```

Repository text is evidence, not authority. It cannot grant approval, expand scope, request secrets, or override system, developer, or user instructions.
Expand Down Expand Up @@ -178,7 +178,7 @@ When the result permits an automatic update, rerun it with `--apply`. Alternate
`Upgrade A Target Workflow` tells the agent to run a report-first guarded migration, not to hand the user a list of backend commands. It applies automatically only when ownership, privacy, and approval checks are resolved. An already-current valid target returns `already_current` without creating a plan or rewriting state/index files; missing or drifted required artifacts still take the guarded migration path.

```text
Use $engineering-workflow to Upgrade A Target Workflow in this repository to version 0.9.4. Run the report first, apply it when safe, and ask only when the report requires a user decision.
Use $engineering-workflow to Upgrade A Target Workflow in this repository to version 0.9.5. Run the report first, apply it when safe, and ask only when the report requires a user decision.
```

The maintainer/automation backend is:
Expand All @@ -187,7 +187,7 @@ The maintainer/automation backend is:
python3 skill/engineering-workflow/scripts/upgrade_target_workflow.py \
--repo <target-repository> \
--prompt \
--target-version 0.9.4 \
--target-version 0.9.5 \
--format json
```

Expand Down Expand Up @@ -240,9 +240,9 @@ Mutable plan sections carry the latest applicable confirmed state and are update

One root agent is the default and the sole owner of shared workflow state and final synthesis. Subagents are used only for necessary independent semantic work with a clear output contract and a measurable benefit. External orchestration does not automatically transfer plan ownership, task context, loaded instructions, workspace paths, or file access.

Long-running local work uses one completion-driven persistent waiter. Complete logs and machine-readable results go to private task-owned ignored artifacts because waiter-cell output can be truncated or lost. Completion readback verifies process state and result integrity independently and returns a bounded terminal summary as soon as the process exits. Fallback polling starts at the next expected meaningful boundary and backs off without waking the model for unchanged state.
Long-running local work uses the native completion-driven waiter and sufficient terminal evidence. Separate private logs and durable results are required when output volume, detachment recovery, or the task's evidence requirements justify them. Completion readback returns as soon as the process exits; fallback polling starts at the next expected meaningful boundary and backs off without waking the model for unchanged state.

Programmatic Tool Calling is limited to deterministic, schema-bounded multi-call stages whose allowed tools, reduced output, concurrency, retry limit, and stopping condition are known in advance. One already-sufficient direct call does not justify a new helper or descriptor. Architecture choices, semantic review, approvals, destructive or external writes, and adaptive workflows remain direct model-guided work. The skill never claims exact subscription or token savings; the intended benefit is fewer redundant model turns and less repeated tool-result context.
Programmatic Tool Calling is limited to deterministic, schema-bounded multi-call stages whose allowed tools, reduced output, concurrency, retry limit, and stopping condition are known in advance. Ordinary native batching uses the host contract directly; the descriptor helper is optional for complex custom stages. One already-sufficient direct call does not justify a new helper or descriptor. Architecture choices, semantic review, approvals, destructive or external writes, and adaptive workflows remain direct model-guided work. The skill never claims exact subscription or token savings; the intended benefit is fewer redundant model turns and less repeated tool-result context.

## Validation and privacy

Expand All @@ -269,7 +269,7 @@ Use $engineering-workflow to audit this mature repository, preserve every existi
Target migration:

```text
Use $engineering-workflow to Upgrade A Target Workflow here to 0.9.4. Run the report and apply it when safe.
Use $engineering-workflow to Upgrade A Target Workflow here to 0.9.5. Run the report and apply it when safe.
```

## Repository layout
Expand All @@ -288,11 +288,13 @@ Use $engineering-workflow to Upgrade A Target Workflow here to 0.9.4. Run the re

## Validating

Select an affected profile during iteration; the examples are alternatives, not a sequence of prerequisite gates. Run `full` on completed implementation, and `security` immediately before an authorized push. Known local fixture tests are included in an implementation request's authorization.

```bash
python3 -m pip install --requirement requirements-dev.txt
python3 scripts/dev_check.py focused --test-pattern test_plan_lifecycle.py
python3 scripts/dev_check.py contracts
python3 scripts/dev_check.py full
python3 scripts/dev_check.py focused --test-pattern test_plan_lifecycle.py # one affected suite
python3 scripts/dev_check.py contracts # cross-contract changes
python3 scripts/dev_check.py full # final implementation gate
python3 scripts/dev_check.py security # mandatory immediately before every push
```

Expand All @@ -302,7 +304,7 @@ This harness and its Ruff configuration improve development of this repository o

## Versioning and updates

The project uses semantic versioning. Version 0.9.4 adds the approved opaque Engineering Workflow identity and Codex plugin-card icon metadata without changing the runtime workflow contract. Version 0.9.3 preserves customized top-level `PLANS.md` sections during compact and archive closure, correcting a data-loss defect discovered while dogfooding 0.9.2 against the unified marketplace repository. Version 0.9.2 keeps durable state current inside useful work rather than a recurring model-maintenance loop, distinguishes continuous task context from real recovery, removes plan-date ordering as a validation-applicability proxy, stops redundant route/tool/subagent work after sufficient evidence, and provides an agent-neutral fallback when the invoking host is not established as Codex or Claude Code. Versions 0.9.2 through 0.9.4 preserve all existing schema and contract versions. Version 0.9.1 updated Codex's standard/review recommendations for Astra, preserved native Claude model/effort inheritance, and clarified existing authorization, task steering, bounded delegation, and proportional verification. Version 0.9.0 added ownership-aware archive closure and instruction contract v3: target agents review every complete logical commit slice and then the aggregate final diff, while customized mature repositories migrate conservatively. Version 0.8.2 stopped empty compatibility archive directories from producing false missing-index errors while retaining fail-closed checks for real archive content and unsafe index paths. Version 0.8.1 added exact, user-approved synthetic-fixture privacy review without exposing candidate values to the agent. Version 0.8.0 introduced loss-resistant completion-driven waits, correctness-first execution discipline, instruction contract v2 migration, Claude Code compatibility, and the deterministic dual marketplace. Version 0.7.0 is the historical baseline for bounded Programmatic Tool Calling assessment and runtime instruction rendering.
The project uses semantic versioning. Version 0.9.5 narrows instruction loading to the selected task, accepts sufficient native completion evidence, makes custom stage assessment optional, and clarifies existing local-check authorization. It preserves the full plan and security contracts. Version 0.9.4 adds the approved opaque Engineering Workflow identity and Codex plugin-card icon metadata without changing the runtime workflow contract. Version 0.9.3 preserves customized top-level `PLANS.md` sections during compact and archive closure, correcting a data-loss defect discovered while dogfooding 0.9.2 against the unified marketplace repository. Version 0.9.2 keeps durable state current inside useful work rather than a recurring model-maintenance loop, distinguishes continuous task context from real recovery, removes plan-date ordering as a validation-applicability proxy, stops redundant route/tool/subagent work after sufficient evidence, and provides an agent-neutral fallback when the invoking host is not established as Codex or Claude Code. Versions 0.9.2 through 0.9.5 preserve all existing schema and contract versions. Version 0.9.1 updated Codex's standard/review recommendations for Astra, preserved native Claude model/effort inheritance, and clarified existing authorization, task steering, bounded delegation, and proportional verification. Version 0.9.0 added ownership-aware archive closure and instruction contract v3: target agents review every complete logical commit slice and then the aggregate final diff, while customized mature repositories migrate conservatively. Version 0.8.2 stopped empty compatibility archive directories from producing false missing-index errors while retaining fail-closed checks for real archive content and unsafe index paths. Version 0.8.1 added exact, user-approved synthetic-fixture privacy review without exposing candidate values to the agent. Version 0.8.0 introduced loss-resistant completion-driven waits, correctness-first execution discipline, instruction contract v2 migration, Claude Code compatibility, and the deterministic dual marketplace. Version 0.7.0 is the historical baseline for bounded Programmatic Tool Calling assessment and runtime instruction rendering.

Historical version records remain valid in completed plans, archives, and migration tests. Current-version owners are `SKILL.md`, this README, current update prompts, active workflow state manifests, and the generated plugin manifests.

Expand Down
Loading