Evolve ai instructions

Evolve AI Instructions

Create a reversible, evidence-backed instruction change. Compare the current and candidate instructions against frozen inputs, preserve held-out cases, and separate structural validation from artifact verification and the project release decision.

Protocol version: 2.0.0.

Workflow

1. Identify one target instruction and its current semantic version. Do not combine unrelated behaviors in one proposal.

2. Collect raw evidence. A summary may locate evidence but does not qualify without a retained, redacted artifact and SHA-256 digest.

3. Read the evaluation protocol. State a falsifiable hypothesis, choose patch, minor, or major, and define criteria before running the candidate.

4. Start with the proposal template. A draft may be incomplete. Before changing it to candidate, freeze the diff, evaluator configuration, baseline and held-out inputs, criteria, rollback commit, and qualifying evidence.

5. Run the current and candidate instructions against the same case inputs. For every run retain the actual output, tool trace, criterion-level result, and rationale. Do not rewrite criteria after observing failures.

6. Use the resolved skill directory from the active skill source locator; never assume .agents/:

   python <resolved-skill-directory>/scripts/validate_proposal.py lint <proposal.json>
   python <resolved-skill-directory>/scripts/validate_proposal.py verify <proposal.json> \
     --repo-root <repository>
   python <resolved-skill-directory>/scripts/validate_proposal.py gate <proposal.json> \
     --repo-root <repository> --policy <release-policy.json>
   

7. Ask a human owner or independent reviewer to decide. An accepted proposal records a hashed attestation and policy. The supplied policy must match the recorded digest and trust that exact principal/provider and required role; the proposer cannot be the approver.

8. Promote only the exact verified candidate. Commit its proposal and evaluation artifacts. On a regression, revert through version control, retain regression and post-check artifacts, and mark the proposal rolled-back.

Validation Levels

• lint checks schema, semantic versions, lifecycle requirements, case separation, complete runs, criterion results, timestamps, and artifact metadata. It reads no referenced state.
• verify also resolves local artifacts, checks SHA-256 digests, confirms the target exists, and resolves the full immutable rollback commit in the supplied Git repository.
• gate also requires status=accepted and applies a supplied project approval policy.

These levels are cumulative. lint does not mean artifacts are genuine; verify does not authenticate a remote account; gate trusts the supplied policy and retained attestation. A provider-specific adapter must independently obtain or authenticate that attestation when required.

Non-Negotiable Gates

• Do not activate a target directly from chat memory or a generated summary.
• Require two qualifying sources with different independence keys, or one critical incident plus a reproducer. Different labels do not make copied evidence independent.
• Keep evidence cases separate from at least one held-out case.
• Store actual inputs, outputs, tool traces, evaluator configuration, and candidate diff with SHA-256.
• Do not expose secrets, personal chat content, or sensitive logs; retain redacted minimum evidence.
• Do not let this skill approve a change to itself. Evaluate self-changes with the last accepted protocol and require human approval.
• Keep project, stack, architecture, model, vendor, identity-provider, and approval-role details in an adapter. An adapter may strengthen but not weaken this protocol.

Outputs

Produce one proposal, candidate diff, evaluation inputs and runs, approval or rejection record, and immutable rollback commit. For accepted changes, retain the policy and approval attestation used by the release gate.

Follow the target repository's canonical evolution rule when one exists.