@williambeto/ai-workflow 1.19.1 → 2.2.0

package/dist-assets/agents/phoenix.md

@@ -0,0 +1,42 @@
+---
+name: phoenix
+description: Applies bounded, targeted remediation for concrete validation findings.
+mode: primary
+---
+
+# Phoenix
+
+## Role
+
+Phoenix fixes concrete findings supplied by validation. It does not redesign the solution or modify unrelated code.
+
+## Behavioral execution contract
+
+Remediation is bounded by execution mode and must show progress. Repeated or unchanged findings become `BLOCKED`.
+
+## Responsibilities
+
+- address only identified findings;
+- preserve working behavior;
+- keep the diff minimal;
+- run targeted checks after changes;
+- return the exact findings addressed and files changed.
+
+## Expected output
+
+Return the remediation diff summary, targeted validation results, unresolved findings, and whether independent revalidation is needed.
+
+## Quality failure examples
+
+- rewriting the feature to satisfy a report format;
+- changing copy or layout unrelated to the finding;
+- claiming a finding is fixed without running a relevant check;
+- exceeding the remediation attempt budget.
+
+## Boundaries
+
+Phoenix cannot approve its own remediation or convert failure into success.
+
+## Stop conditions
+
+Stop when the attempt budget is exhausted, no progress is observed, the fix requires broader scope approval, or a safe correction is unavailable.

package/dist-assets/agents/sage.md

@@ -0,0 +1,54 @@
+---
+name: sage
+description: Independently validates software behavior, regressions, and delivery evidence when review is proportionate to risk.
+mode: primary
+---
+
+# Sage
+
+## Role
+
+Sage validates independently from implementation when Atlas selects independent review, especially for full, risky, security-sensitive, or release work.
+
+## Behavioral execution contract
+
+Sage validates independently. It inspects the actual diff and runs relevant commands. It does not help manufacture the documents needed to pass a gate.
+
+## Responsibilities
+
+- review scope and changed files;
+- run relevant tests, build, typecheck, lint, and targeted checks;
+- identify concrete defects with evidence;
+- distinguish blocking defects from notes;
+- verify remediation against the changed workspace when requested.
+
+## Expected output
+
+Return:
+
+- commands and observed results;
+- findings with severity and file evidence;
+- blocking status;
+- limitations of the validation performed.
+
+## Quality failure examples
+
+- approving based only on a delivery report;
+- accepting screenshots as proof of all behavior;
+- repeating the implementer's claims without checking;
+- accepting claims about sources, integrations, data handling, or available capabilities that are not supported by the delivered code or clearly qualified as mocked or conceptual;
+- downgrading a failed required command to a note.
+
+## Boundaries
+
+Sage does not implement broad fixes, create fake evidence, or promote unresolved blocking findings.
+
+## Stop conditions
+
+Stop with a blocking result when required validation cannot run, the branch is unsafe, evidence contradicts the implementation, or remediation did not resolve a material finding.
+
+## Canonical policies
+
+- `03-QUALITY_GATE.md`
+- `06-FINAL_EVIDENCE_CONTRACT.md`
+- `PROCEDURE_UI_CHECKLIST.md`

package/dist-assets/commands/README.md

@@ -0,0 +1,14 @@
+# Commands
+
+Commands select a workflow action without changing the core safety rules.
+
+- `/atlas`: classify and route;
+- `/discover`: understand the project;
+- `/plan`: prepare a proportionate plan;
+- `/implement`: implement a scoped change;
+- `/validate`: run observed validation;
+- `/audit`: inspect and report findings;
+- `/release`: prepare release readiness without publishing automatically;
+- `/deploy`: prepare or execute deployment only with explicit approval.
+
+Every write command enforces protected-branch safety and cannot report success after failed required validation.

package/dist-assets/commands/atlas.md

@@ -0,0 +1,12 @@
+---
+description: Ask Atlas to classify, route, and coordinate a software request.
+agent: atlas
+---
+
+# Atlas
+
+Classify the request, choose a proportionate mode and domain profile, enforce branch safety, delegate only when useful, require observed validation, and return a concise delivery summary.
+
+Never write on a protected branch. Never promote failed or unavailable required validation to success.
+
+Policies: `01-BRANCH_GATE.md`, `03-QUALITY_GATE.md`, `05-AGENT_CONTRACT.md`, `06-FINAL_EVIDENCE_CONTRACT.md`.

package/dist-assets/commands/audit.md

@@ -0,0 +1,10 @@
+---
+name: audit
+description: Audit real project files and report prioritized findings.
+---
+
+# /audit
+
+Inspect the requested scope, cite file evidence, separate confirmed issues from hypotheses, and do not change files unless explicitly authorized. Validation claims must be observed, not inferred.
+
+Core rules: never write on protected branches, never skip relevant validation, never report false success.

package/dist-assets/commands/deploy.md

@@ -0,0 +1,12 @@
+---
+name: deploy
+description: Prepare or perform a deployment only with explicit approval.
+---
+
+# /deploy
+
+Verify branch, release readiness, validation, target, rollback path, and approval. Never deploy from failed validation or create release actions beyond the user request.
+
+Core rules: never write on protected branches, never skip relevant validation, never report false success.
+
+Policies: `01-BRANCH_GATE.md`, `06-FINAL_EVIDENCE_CONTRACT.md`, `07-RELEASE_GATE.md`.

package/dist-assets/commands/discover.md

@@ -0,0 +1,10 @@
+---
+name: discover
+description: Discover project context and clarify the safest next step.
+---
+
+# /discover
+
+Inspect only relevant files, identify architecture and constraints, record uncertainties, and avoid implementation. Return concise context and recommended next action.
+
+Core rules: never write on protected branches, never skip relevant validation, never report false success.

package/dist-assets/commands/implement.md

@@ -0,0 +1,28 @@
+---
+description: Implement a scoped change using a proportionate workflow and observed validation.
+agent: atlas
+---
+
+# Implement
+
+## Task
+
+Implement the requested scoped change.
+
+## Required behavior
+
+1. Verify branch and dirty state before editing.
+2. Never write on `main` or `master`; create a scoped branch when safe, otherwise stop `BLOCKED`.
+3. Select quick, standard, or full proportionately.
+4. Delegate only when specialization or independent review materially helps.
+5. Apply the minimum diff and preserve unrelated behavior.
+6. For new or changed executable behavior, add and run a proportional automated behavioral test; build/manual checks do not replace it.
+7. After the final implementation changes, run `npx ai-workflow collect-evidence --mode=<quick|standard> --task=<short-task-slug>`.
+8. Treat the finalizer exit code and public status as authoritative; never report success when it returns `BLOCKED` or fails.
+9. Use bounded remediation for recoverable findings.
+
+## Output
+
+Return status, branch, changes, validation commands/results, and known limitations. Do not create workflow artefacts solely to satisfy this command.
+
+Policies: `01-BRANCH_GATE.md`, `03-QUALITY_GATE.md`, `06-FINAL_EVIDENCE_CONTRACT.md`, `PROCEDURE_UI_CHECKLIST.md`.

package/dist-assets/commands/optimize-tokens.md

@@ -0,0 +1,10 @@
+---
+name: optimize-tokens
+description: Reduce workflow context without weakening safety.
+---
+
+# /optimize-tokens
+
+Remove duplicated prose and unnecessary artefacts. Preserve branch safety, required validation, bounded remediation, and truthful reporting.
+
+Core rules: never write on protected branches, never skip relevant validation, never report false success.

package/dist-assets/commands/plan.md

@@ -0,0 +1,10 @@
+---
+name: plan
+description: Create a proportionate implementation plan.
+---
+
+# /plan
+
+Define scope, risks, steps, validation, and stop conditions. Use a mini plan for small work and formal planning only when risk justifies it.
+
+Core rules: never write on protected branches, never skip relevant validation, never report false success.

package/dist-assets/commands/release.md

@@ -0,0 +1,12 @@
+---
+name: release
+description: Prepare release readiness without publishing automatically.
+---
+
+# /release
+
+Require clean branch state, successful required validation, safe package checks, changelog/version consistency, and explicit approval before tag, publish, or release.
+
+Core rules: never write on protected branches, never skip relevant validation, never report false success.
+
+Policies: `01-BRANCH_GATE.md`, `06-FINAL_EVIDENCE_CONTRACT.md`, `07-RELEASE_GATE.md`.

package/dist-assets/commands/run.md

@@ -0,0 +1,26 @@
+---
+description: Run the safest proportionate workflow for an approved task.
+agent: atlas
+---
+
+# Run
+
+## Task
+
+Route and execute the approved task using the lowest safe workflow mode.
+
+## Required behavior
+
+- enforce protected-branch safety before writes;
+- use project context and the closest domain profile;
+- delegate proportionately, not ceremonially;
+- run relevant validation from the project;
+- block false success when validation fails or is unavailable;
+- use bounded remediation and stop on no progress;
+- persist evidence only for full, release, audit, security, or explicitly requested work.
+
+## Output
+
+Return a concise delivery summary: status, branch, changed areas, observed validation, limitations, and next action when needed.
+
+Policies: `01-BRANCH_GATE.md`, `03-QUALITY_GATE.md`, `05-AGENT_CONTRACT.md`, `06-FINAL_EVIDENCE_CONTRACT.md`.

package/dist-assets/commands/spec-create.md

@@ -0,0 +1,10 @@
+---
+name: spec-create
+description: Create a specification proportionate to scope.
+---
+
+# /spec-create
+
+Capture objective, scope, constraints, acceptance criteria, risks, and validation. Avoid ceremony for small work.
+
+Core rules: never write on protected branches, never skip relevant validation, never report false success.

package/dist-assets/commands/spec-implement.md

@@ -0,0 +1,10 @@
+---
+name: spec-implement
+description: Implement an approved specification safely.
+---
+
+# /spec-implement
+
+Enforce branch safety, implement incrementally, run relevant validation, remediate bounded findings, and return concise evidence.
+
+Core rules: never write on protected branches, never skip relevant validation, never report false success.

package/dist-assets/commands/spec-review.md

@@ -0,0 +1,10 @@
+---
+name: spec-review
+description: Review specification readiness.
+---
+
+# /spec-review
+
+Find ambiguity, missing acceptance criteria, unsafe assumptions, scope creep, and validation gaps. Do not rewrite the spec unless requested.
+
+Core rules: never write on protected branches, never skip relevant validation, never report false success.

package/dist-assets/commands/update-memory.md

@@ -0,0 +1,10 @@
+---
+name: update-memory
+description: Persist durable project memory.
+---
+
+# /update-memory
+
+Store only stable decisions, constraints, current state, and next approved step. Do not store temporary logs or duplicate delivery reports.
+
+Core rules: never write on protected branches, never skip relevant validation, never report false success.

package/dist-assets/commands/validate.md

@@ -0,0 +1,12 @@
+---
+description: Validate the current scoped work using observed commands and objective findings.
+agent: sage
+---
+
+# Validate
+
+Inspect the actual diff and run relevant tests, build, typecheck, lint, and domain checks. Do not approve based only on reports or checklists. A failed required command is blocking until resolved or safely accepted by the user.
+
+Return commands/results, findings with evidence, limitations, and one status: `COMPLETED`, `COMPLETED_WITH_NOTES`, or `BLOCKED`.
+
+Policies: `03-QUALITY_GATE.md`, `06-FINAL_EVIDENCE_CONTRACT.md`, `PROCEDURE_UI_CHECKLIST.md`.

package/dist-assets/docs/INDEX.md

@@ -0,0 +1,21 @@
+# AI Workflow Kit v2 Documentation Index
+
+This directory is installed under `.ai-workflow/docs/` in consumer projects.
+
+## Start here
+
+- `../QUICKSTART.md` — generated consumer onboarding.
+- `compatibility/runtime-matrix.md` — runtime support levels.
+- `compatibility/provider-usage.md` — provider-specific usage and limitations.
+- `troubleshooting-guide.md` — operational troubleshooting.
+- `cli-reference.md` — CLI commands and flags.
+
+## Runtime contracts
+
+- `policies/01-BRANCH_GATE.md`
+- `policies/03-QUALITY_GATE.md`
+- `policies/06-FINAL_EVIDENCE_CONTRACT.md`
+- `policies/11-EXECUTABLE_DELEGATION_AND_TRUTHFULNESS.md`
+- `specs/runtime-operational-contract.md`
+
+These are packaged runtime documents. Repository maintainers edit their sources under `dist-assets/**`; consumers use the installed `.ai-workflow/**` paths.

package/dist-assets/docs/QUICKSTART.md

@@ -0,0 +1,23 @@
+# AI Workflow Kit quickstart
+
+Give Atlas a natural software request. Atlas chooses the lowest safe mode and the closest workflow profile.
+
+## Modes
+
+| Mode | Use | Required evidence |
+|---|---|---|
+| quick | small, reversible change | branch, changed files, targeted validation |
+| standard | normal scoped feature | branch, changed areas, relevant commands/results, limitations |
+| full | risky, broad, release, migration, security, or explicit audit | persisted machine-generated evidence and independent validation |
+
+## Safety
+
+Write-capable work never runs on `main` or `master`. Existing relevant tests/build/typecheck/lint scripts are executed. Failed or unavailable required validation results in `BLOCKED`.
+
+## Final states
+
+- `COMPLETED`
+- `COMPLETED_WITH_NOTES`
+- `BLOCKED`
+
+Workflow documents are optional unless they provide lasting value or full mode requires them.

package/dist-assets/docs/adr/ADR-0000.md

@@ -0,0 +1,19 @@
+# ADR-0000: Primary agent routing protocol
+
+## Status
+
+Accepted
+
+## Context
+
+The workspace uses six Primary Agents: Atlas, Nexus, Orion, Astra, Sage, and Phoenix. A clear routing and execution protocol prevents work from stopping at handoff messages and ensures delivery proceeds through documentation, tests, validation, and evidence.
+
+## Decision
+
+Adopt a professional runtime taxonomy and require execution requests to continue to the correct owner/command when the runtime can act.
+
+## Consequences
+
+- Routing is not completion.
+- Branch Gate uses Auto-Recovery when safe.
+- Implementation requires documentation, tests where feasible, validation, and evidence.

package/dist-assets/docs/adr/ADR-0001.md

@@ -0,0 +1,45 @@
+# ADR-0001: Isolated Branch Gate
+
+- **Status**: Accepted
+- **Date**: YYYY-MM-DD
+- **Author**: José Willams
+
+## Context
+
+Direct commits to `main` or `master` risk bypassing validation gates and introducing unvalidated changes. In a multi-agent workflow where agents (Astra, Phoenix) operate autonomously, there is no human reviewer at every step to catch a misdirected commit.
+
+The project needed a programmatic guard that prevents write operations on protected branches unless explicitly overridden with a justified reason.
+
+## Decision
+
+Implement an **Isolated Branch Gate** (`BranchGate` class) that:
+
+1. Reads the current branch via `git rev-parse --abbrev-ref HEAD`.
+2. Checks against a configurable list of protected branches (default: `["main", "master"]`).
+3. Blocks the operation with a clear reason if the branch is protected.
+4. Allows bypass only with `AI_OVERRIDE` environment variable containing a justification ≥20 characters.
+5. Logs all blocked attempts and authorized overrides to `GATE_ALERTS.log` in the memory directory.
+
+The gate is evaluated before any write operation in the `runMasterOrchestrator` pipeline. If blocked, the process exits with code 1 before any spec reading, implementation, or evidence collection occurs.
+
+## Consequences
+
+**Positive**:
+- Prevents accidental commits to main from automated agents.
+- Provides an audit trail of gate actions via `GATE_ALERTS.log`.
+- Override mechanism preserves flexibility for emergency fixes.
+- Early exit avoids wasting resources on a blocked pipeline.
+
+**Negative**:
+- Override justification requirement adds friction for legitimate main edits.
+- Git must be available in the execution environment.
+
+## Compliance
+
+- `src/core/gates/branch-gate.js` implements the gate logic.
+- `src/commands/run.js` calls `BranchGate.check()` as the first step in the master orchestrator.
+- All agent definitions reference the branch gate rule.
+
+## Notes
+
+The 20-character minimum for overrides was chosen to force meaningful justifications while remaining short enough to type inline. The gate file is stored in `.ai-workflow/` to keep it within the managed workspace boundary.

package/dist-assets/docs/adr/ADR-0002.md

@@ -0,0 +1,62 @@
+# ADR-0002: Three-Layer Validation Pipeline
+
+- **Status**: Accepted
+- **Date**: YYYY-MM-DD
+- **Author**: José Willams
+
+## Context
+
+The project needed a validation system that provides comprehensive quality assurance across multiple dimensions. A single validation script would not cover the diverse validation concerns: JSON schema conformance, cross-reference integrity, documentation consistency, artifact safety, policy compliance, and privacy gates.
+
+The `package.json` scripts section already defined individual validators, but there was no unified pipeline to run them all in sequence with a clear pass/fail summary.
+
+## Decision
+
+Adopt a **Three-Layer Validation Pipeline** enforced via `npm run validate`:
+
+### Layer 1: Lint
+Structural and formatting checks:
+- JSON validation (`validate:json`)
+- Repository structure validation (`validate:structure`)
+- Skill validation (`validate:skills`)
+
+### Layer 2: Type / Reference Integrity
+Cross-cutting consistency checks:
+- Cross-reference validation (`validate:refs`)
+- External link validation (`validate:links`)
+- Documentation consistency (`validate:docs-consistency`)
+- Canonical policy reference validation (`validate:policy-refs`)
+
+### Layer 3: Evidence
+Safety, privacy, and quality gates:
+- Artifact safety validation (`validate:artifact-safety`)
+- Workflow state validation (`validate:workflow`)
+- Schema validation (`validate:schemas`)
+- Privacy publication gate (`validate:privacy-gate`)
+- UI evidence gate (`validate:ui-evidence`)
+- Delegation validation (`validate:delegation`)
+
+The pipeline (`internal/validate/validate-all.mjs`) iterates through 14 checks sequentially. All checks must pass for the pipeline to succeed. The first failure does not abort — all checks run and a summary is printed at the end.
+
+## Consequences
+
+**Positive**:
+- Comprehensive coverage: 14 distinct validation checks.
+- Any single validator can be run independently via `npm run validate:<name>`.
+- Failures are collected and reported in aggregate, giving the full picture.
+- Markdown linting via `lint:md` provides an additional optional layer.
+
+**Negative**:
+- 14 sequential checks can take longer to complete.
+- New validators must be registered in both `package.json` and `validate-all.mjs`.
+
+## Compliance
+
+- `internal/validate/validate-all.mjs` orchestrates all 14 checks.
+- Each check maps to a `npm run validate:<name>` script.
+- The pipeline is invoked before every push and PR submission.
+- `EVIDENCE.json` records the results of these validation runs.
+
+## Notes
+
+Markdown linting (`lint:md`) is intentionally kept as a separate script rather than included in the validate pipeline, because some valid Markdown patterns may trigger linter rules. It should be run during development but not as a hard gate.

package/dist-assets/docs/adr/ADR-0003.md

@@ -0,0 +1,60 @@
+# ADR-0003: Spec-Driven Development (SDD)
+
+- **Status**: Accepted
+- **Date**: YYYY-MM-DD
+- **Author**: José Willams
+
+## Context
+
+Implementation without approved specifications leads to scope creep, misaligned outcomes, and rework. In a multi-agent system where Astra (developer) implements while Sage (auditor) validates, there must be a clear contract defining what constitutes correct implementation.
+
+The project needed a formal process ensuring that no code is written without an approved specification document.
+
+## Decision
+
+Adopt **Spec-Driven Development (SDD)** as the mandatory workflow:
+
+1. **Proposal**: Nexus uses the `openspec-propose` skill to create a change with artifacts: `proposal.md` (what and why), `design.md` (how), `tasks.md` (implementation steps).
+2. **Specification**: A spec file is created in `specs/` with a tiered classification:
+   - `[DEEP]` — Complex, multi-step features
+   - `[STANDARD]` — Moderate changes
+   - `[TINY]` — Simple, low-risk changes
+3. **Approval**: The spec must include a `## Metadata` section with `Status: APPROVED`.
+4. **Validation**: `SpecValidator` (`src/core/sdd/validator.js`) enforces:
+   - Presence of tier identifier `[DEEP|STANDARD|TINY]`
+   - `## Metadata` section
+   - `##  Acceptance Criteria` section
+   - `Status: APPROVED` in Metadata (not a template list)
+5. **Implementation**: `runMasterOrchestrator` requires `--spec-path` and validates the spec before proceeding.
+6. **No Spec, No Code**: The `AGENTS.md` hard constraint prohibits implementation without an approved spec.
+
+### OpenSpec Integration
+
+The `openspec-propose` skill automates artifact generation:
+1. `openspec new change "<name>"` creates the change scaffold
+2. Artifacts are built in dependency order (proposal → design → tasks)
+3. When all `applyRequires` artifacts are complete, implementation is ready
+
+## Consequences
+
+**Positive**:
+- Clear contract between specification and implementation.
+- Prevents unauthorized or misaligned code changes.
+- Audit trail: each implementation is traceable to an approved spec.
+- `SpecValidator` catches missing or unapproved specs early.
+
+**Negative**:
+- Adds overhead for tiny changes that could be implemented directly.
+- Requires discipline to keep specs in sync with code.
+- The spec approval process is manual (Status must be set to APPROVED).
+
+## Compliance
+
+- `src/core/sdd/validator.js` enforces the approval gate.
+- `src/commands/run.js` calls `SpecValidator.validate()` before any implementation.
+- `AGENTS.md` lists "No Spec, No Code" as a hard constraint.
+- Specs are stored in the `specs/` directory.
+
+## Notes
+
+The tier system (`DEEP/STANDARD/TINY`) was introduced to allow proportional spec rigor. A TINY spec requires the same structure but can be shorter. The acceptance criteria section ensures that Sage has measurable outcomes to validate against.

package/dist-assets/docs/adr/ADR-0004.md

@@ -0,0 +1,71 @@
+# ADR-0004: Self-Healing Loop Architecture
+
+- **Status**: Accepted
+- **Date**: YYYY-MM-DD
+- **Author**: José Willams
+
+## Context
+
+In an autonomous multi-agent workflow, validation failures can occur due to transient issues, configuration drift, incomplete implementation, or environmental differences. When Sage (the Auditor) detects a failure, the pipeline should not simply abort — it should attempt recovery autonomously before escalating.
+
+The project required a self-healing mechanism that:
+- Detects failures from evidence collection
+- Attempts repairs within safe limits
+- Escalates only after exhausting retry attempts
+- Maintains state across healing attempts
+
+## Decision
+
+Implement a **Self-Healing Loop Architecture** with a maximum of 3 retry attempts:
+
+### Components
+
+1. **HealerEngine** (`src/core/healing/healer-engine.js`):
+   - Reads `EVIDENCE.json` to detect failures
+   - Manages attempt count via `.ai-workflow/healing-state.json`
+   - Prepares high-signal failure context for Phoenix (the Healer agent)
+   - Resets state after successful healing
+
+2. **Phoenix Agent** (The Healer):
+   - Receives structured failure context from HealerEngine
+   - Performs autonomous repair (re-runs failed commands, fixes issues)
+   - Reports back for re-validation
+
+3. **Loop Controller** (`src/commands/run.js`, Phase 2):
+   - Runs up to `maxHealingAttempts` (default: 3) iterations
+   - Each iteration: Sage collects evidence → if PASS, break → if FAIL, Phoenix repairs → increment counter → repeat
+   - After 3 failed attempts: `[MASTER BLOCKED] Self-Healing failed to resolve the issue.`
+
+### Healing Flow
+
+```
+Sage collects evidence
+  ├─ PASS → proceed to Quality Shield
+  └─ FAIL → HealerEngine.getStatus()
+       ├─ shouldHeal=false AND maxAttempts reached → BLOCKED
+       └─ shouldHeal=true → preparePhoenixContext → Phoenix repairs → incrementAttempts → loop
+```
+
+## Consequences
+
+**Positive**:
+- Autonomous recovery for common transient failures.
+- Stateful: knows how many attempts have been made (persisted to disk).
+- Reset mechanism prevents infinite loops across sessions.
+- Clear escalation path after max attempts.
+
+**Negative**:
+- Complex failure patterns may not be recoverable by Phoenix.
+- Healing state persists on disk and may become stale.
+- Each attempt consumes resources (tool calls, tokens, time).
+
+## Compliance
+
+- `src/core/healing/healer-engine.js` implements the HealerEngine.
+- `src/commands/run.js` integrates the healing loop in Phase 2.
+- Healing state is stored in `.ai-workflow/healing-state.json`.
+- Max attempts is configurable via `HealerEngine` constructor (default: 3).
+
+## Notes
+
+The 3-attempt limit was chosen empirically: fewer attempts risk premature failure, while more attempts risk resource exhaustion without proportional benefit. The state file is stored in `.ai-workflow/` to keep it within the managed boundary and ensure cleanup on reset.

package/dist-assets/docs/adr/ADR-0005.md

@@ -0,0 +1,22 @@
+# ADR-0005: Optimize-Tokens Skill Selection
+
+## Status
+
+Accepted.
+
+## Context
+
+AI-assisted delivery workflows can waste tokens when agents load broad context or historical documents unnecessarily.
+
+## Decision
+
+Use the `optimize-tokens` skill for token discipline and context minimization.
+
+Agents and commands should prefer current runtime contracts, current policies, active specs, and directly relevant files over broad repository scans.
+
+## Consequences
+
+- Less historical noise reaches the model.
+- Agents should avoid loading obsolete planning material.
+- Context selection must preserve enough evidence to validate claims.
+- Token economy cannot override quality, safety, tests, documentation, or evidence requirements.