@williambeto/ai-workflow 1.19.1 → 2.2.0

package/dist-assets/docs/policies/02-SDD_METHODOLOGY.md

@@ -0,0 +1,95 @@
+# Spec-Driven Development
+
+## What it means in this repository
+
+Spec-Driven Development means implementation starts only after a clear, testable specification is drafted and reviewed.
+
+Standard flow:
+
+```txt
+Request
+→ Change proposal / lightweight spec
+→ Spec review
+→ Task breakdown
+→ Implementation
+→ Validation
+→ Evidence report
+```
+
+## When to use
+
+Use this flow for:
+
+- new features;
+- bug fixes that change behavior;
+- refactors with behavioral risk;
+- UI behavior changes;
+- architecture-impacting changes;
+- workflow/process changes.
+
+For tiny docs-only edits, use proportional workflow.
+
+## Assets to use
+
+- Lightweight change template: `templates/change-proposal.template.md`
+- Lightweight readiness checklist: `checklists/change-spec-readiness-checklist.md`
+- Request-to-spec command: `opencode/commands/spec-create.md`
+- Spec review command: `opencode/commands/spec-review.md`
+- Spec-to-implementation command: `opencode/commands/spec-implement.md`
+- Spec-first owner: `opencode/agents/spec-engineer.md`
+- Spec template: `templates/SPEC.template.md`
+- Readiness checklist: `checklists/spec-readiness-checklist.md`
+
+## Artifact location convention (consumer project)
+
+Store generated spec artifacts in the consumer repository using this default path:
+
+```txt
+docs/specs/[spec-type]/[yyyy-mm-dd]-[change-slug]/
+```
+
+Allowed `<spec-type>` values:
+
+- `feature`
+- `bugfix`
+- `refactor`
+- `ui-change`
+- `architecture`
+- `workflow`
+- `integration`
+- `test-strategy`
+
+Recommended files inside each folder:
+
+```txt
+00-proposal.md
+01-spec.md
+02-design.md
+03-tasks.md
+04-validation.md
+05-handoff.md
+```
+
+For `tiny` specs, allow a minimal set:
+
+```txt
+00-proposal.md
+03-tasks.md
+04-validation.md
+```
+
+## Connection to PR execution
+
+After spec review passes:
+
+1. split into small implementation tasks (or PRs when needed);
+2. implement one scoped task/PR only;
+3. run validation before claiming success;
+4. return evidence for commands, changed files, and acceptance-criteria coverage.
+
+## Required evidence after validation
+
+- commands executed + result;
+- files changed;
+- acceptance criteria status;
+- untested areas and residual risks.

package/dist-assets/docs/policies/03-QUALITY_GATE.md

@@ -0,0 +1,22 @@
+# Quality gate
+
+Quality gates validate observed delivery outcomes, not report formatting.
+
+## Blocking conditions
+
+- implementation changes on a protected branch;
+- a relevant required command fails;
+- implementation has no meaningful validation path;
+- a material finding remains after bounded remediation;
+- the reported result contradicts observed execution.
+
+## Non-blocking notes
+
+Missing screenshots, optional documentation, or minor review observations may produce `COMPLETED_WITH_NOTES` when required validation passed.
+
+## Prohibited shortcuts
+
+- no-op test scripts;
+- checklists used as substitutes for executable validation;
+- manually authored successful command results;
+- success inferred from the presence or name of a workflow file.

package/dist-assets/docs/policies/05-AGENT_CONTRACT.md

@@ -0,0 +1,7 @@
+# Agent contract
+
+Agents are responsibilities, not evidence artefacts.
+
+Atlas routes and coordinates. Astra implements substantial scoped work. Sage validates independently when proportional to risk. Phoenix remediates concrete findings within bounded attempts.
+
+Do not claim a handoff occurred unless it occurred. Do not force delegation merely to populate a report. The final user response focuses on the delivered result and observed validation.

package/dist-assets/docs/policies/06-FINAL_EVIDENCE_CONTRACT.md

@@ -0,0 +1,31 @@
+# Delivery evidence contract
+
+Evidence exists to help the user trust the delivery. It must not become the delivery itself.
+
+## Quick and standard work
+
+No fixed workflow filename, owner JSON, checklist, or `EVIDENCE.json` is required.
+
+The final handoff must state:
+
+- branch used;
+- files or areas changed;
+- validation commands actually executed;
+- observed results;
+- material limitations.
+
+A report written by an agent is not proof that a command ran. Command results must come from observed execution.
+
+## Full, release, audit, and security work
+
+Persisted evidence is appropriate when traceability has lasting value. The runtime may write a structured evidence file containing branch state, changed files, command exit codes, checks, limitations, and final status.
+
+The model must not manually author successful command results.
+
+## Completion states
+
+- `COMPLETED`
+- `COMPLETED_WITH_NOTES`
+- `BLOCKED`
+
+A failed required command, protected-branch violation, missing meaningful validation, or unresolved material finding cannot be promoted to success.

package/dist-assets/docs/policies/07-RELEASE_GATE.md

@@ -0,0 +1,47 @@
+# Release Gate Policy (Canonical)
+
+## Purpose
+
+Define non-negotiable checks required before release actions.
+
+## Required release prerequisites
+
+1. **Clean git state**
+   - Working tree must be clean.
+   - No unresolved merge or untracked release-critical artifacts.
+
+2. **Version identity**
+   - Target version is consistent across relevant package metadata.
+   - Release version must match intended release record.
+
+3. **Validation evidence**
+   - Required validation commands executed.
+   - Results attached with pass/fail status and notable warnings.
+
+4. **`npm pack` evidence**
+   - `npm pack --dry-run` output attached.
+   - Package name/version confirmed.
+   - Artifact contents reviewed for expected/forbidden files.
+
+## Approval gate (hard stop)
+
+Without explicit human approval:
+
+- Do not publish npm.
+- Do not deploy.
+- Do not create git tag.
+- Do not create GitHub release.
+- Do not merge release branches.
+- Do not push release changes.
+- Do not force-push.
+- Do not delete broadly.
+- Do not change package version.
+
+## Post-release verification expectations
+
+After approved release actions, verify and document:
+
+- Published version matches expected release version.
+- Install/smoke check succeeds in a clean consumer.
+- Release notes/tag metadata map to the shipped artifact.
+- Any non-blocking notes and follow-ups are recorded.

package/dist-assets/docs/policies/08-PRODUCT_TRUTHFULNESS_AND_PROJECT_DOCS.md

@@ -0,0 +1,18 @@
+# Product truthfulness and project documentation
+
+## Product truthfulness
+
+Do not present as verified fact anything that was not supplied by the user, implemented, or checked.
+
+For fictional or demonstrative products, make the fictional context clear at product level. Do not pollute every component with repetitive labels unless local clarification is genuinely necessary.
+
+Avoid unsupported claims about real customers, certifications, legal approval, guarantees, measured performance, availability, or integrations. Fictional prices, plans, and examples are allowed when the page clearly establishes that the product is fictional or demonstrative.
+Claims about data sources, provenance, live integrations, privacy or storage behavior, and available product capabilities must match the delivered code and configuration. When a capability is mocked, simulated, conceptual, or not yet available, qualify it clearly at the appropriate product or feature level.
+
+Truthfulness is primarily a semantic review responsibility. Keyword matching is not a substitute for judgement.
+
+## Documentation
+
+Update documentation when setup, usage, public behavior, architecture, or operational expectations changed. Do not create documentation solely to satisfy a gate.
+
+For small work, a concise final summary may be sufficient. Full, release, migration, and audit work may justify persisted documentation.

package/dist-assets/docs/policies/09-SPEC_VISIBILITY_AND_PUBLICATION.md

@@ -0,0 +1,28 @@
+# 09 — Spec Visibility and Publication Gate
+
+## Purpose
+
+Prevent private specification leakage to public package outputs.
+
+## Authority model
+
+1. `/specs` repository is the canonical private specification authority.
+2. `/core/packages/ai-workflow/docs/**` is public-safe output only.
+3. Public docs can summarize decisions but must not expose private rationale, internal audit details, or sensitive planning.
+
+## Visibility classes
+
+- `private`: full REQ/TECH, remediation details, internal trade-offs.
+- `restricted-summary`: redacted summary for package docs.
+- `public-safe`: safe to publish as-is.
+
+## Mandatory controls
+
+1. Every new spec must declare a `visibility` class.
+2. Any content copied to package docs must be rewritten as `restricted-summary` or `public-safe`.
+3. Release path must include privacy validation (`validate:privacy-gate`).
+
+## Failure policy
+
+- Any attempt to publish private spec paths is a release blocker.
+- Fix by removing private paths from package allowlist and sanitizing docs.

package/dist-assets/docs/policies/10-BEHAVIORAL_CONTRACT_HARDENING.md

@@ -0,0 +1,9 @@
+# Behavioral guardrail hardening
+
+The runtime hardens three outcomes, not report formatting:
+
+1. write-capable work does not proceed on protected branches;
+2. existing relevant validation is executed and observed;
+3. failed or unavailable required validation cannot become success.
+
+Prompt text, workflow filenames, owner labels, and checklists are not independent proof. Quick and standard workflows remain proportionate. Full workflows may persist structured runtime evidence.

package/dist-assets/docs/policies/11-EXECUTABLE_DELEGATION_AND_TRUTHFULNESS.md

@@ -0,0 +1,7 @@
+# Delegation and truthfulness
+
+Delegation is useful when specialization or independent review improves the result. It is not required merely to satisfy a report.
+
+Do not claim that Atlas, Astra, Sage, Phoenix, or a specialist acted unless the handoff occurred. For full or high-risk work, independent validation should be separated from implementation. For small and normal scoped work, use the smallest safe ownership model.
+
+Product truthfulness is semantic: do not present unverified claims as real. Fictional products should be clearly fictional at product level without repetitive labels dominating the interface.

package/dist-assets/docs/policies/ORCHESTRATION_PROTOCOL.md

@@ -0,0 +1,15 @@
+# Orchestration protocol
+
+## Quick
+
+Inspect → safe branch → edit → targeted validation → concise handoff.
+
+## Standard
+
+Understand → brief plan → safe branch → implement → relevant validation → bounded remediation when needed → concise handoff.
+
+## Full
+
+Discovery/specification → safe branch → specialist implementation → independent validation → bounded remediation → revalidation → persisted evidence → final decision.
+
+Protected-branch safety, required validation, and false-success prevention apply to every write-capable mode.

package/dist-assets/docs/policies/PROCEDURE_DELIVERY_ARTIFACTS.md

@@ -0,0 +1,21 @@
+# Delivery artefacts
+
+Artefacts are proportional to risk and future value.
+
+## Quick
+
+No mandatory persisted artefact. Provide a concise final summary with validation evidence.
+
+## Standard
+
+No mandatory filename or document set. Update project documentation only when behavior, setup, usage, or architecture changed.
+
+A delivery report is optional when it helps review or handoff.
+
+## Full
+
+Persist a concise evidence package appropriate to the task. It should record requirements or scope, implementation, validation, unresolved limitations, and final decision without duplicating the same information across several files.
+
+## Rule
+
+A file's presence, name, or prose never proves that the workflow happened. Observed branch state, diffs, commands, exit codes, and review findings are the evidence.

package/dist-assets/docs/policies/PROCEDURE_DOCUMENTATION_CHECKLIST.md

@@ -0,0 +1,24 @@
+# Documentation Procedure Checklist
+
+Use for docs, prompts, agents, commands, skills, policies, and runtime instructions.
+
+## Checks
+
+- Correct file path.
+- Accurate behavior.
+- No stale paths.
+- No invented commands.
+- No fake capabilities.
+- Examples included when useful.
+- Concise for simple changes.
+- Complete enough for complex workflows.
+- Branch Gate and Final Evidence preserved when relevant.
+- Primary Agents and Skill-backed Specialist Roles terminology used correctly.
+
+## Avoid
+
+- documenting behavior not implemented;
+- duplicating docs unnecessarily;
+- broad rewrites for small corrections;
+- legacy theatrical taxonomy;
+- calling skill-backed specialist roles standalone subagents.

package/dist-assets/docs/policies/PROCEDURE_UI_CHECKLIST.md

@@ -0,0 +1,54 @@
+# UI Procedure Checklist
+
+Use for user-facing UI work.
+
+## Minimum quality
+
+- Clear visual hierarchy.
+- Consistent spacing.
+- Readable typography.
+- Loading state when data is fetched.
+- Empty state when no data exists.
+- Error state when action/fetch can fail.
+- Basic keyboard/accessibility support.
+- Responsive sanity for common breakpoints.
+- No raw default controls when polished UI is expected.
+
+## Evidence
+
+Report:
+
+- files changed;
+- screenshots if available;
+- manual checks if screenshots are unavailable;
+- validation command/result;
+- known limitations.
+
+## Blocking issues
+
+- inaccessible primary flow;
+- broken layout on normal viewport;
+- missing error handling for critical action;
+- UI does not satisfy requested behavior.
+
+
+## Rendered UI evidence
+
+For user-facing UI work, validation should inspect the rendered interface when the runtime can run or open the app. Prefer a browser screenshot, Playwright check, viewport check, or equivalent rendered inspection.
+
+Build success does not prove visual quality. Unit tests do not prove visual quality.
+
+## Automatic FAIL_QUALITY_GATE cases
+
+Return `FAIL_QUALITY_GATE` when user-facing UI:
+
+- looks like default browser HTML;
+- uses raw unstyled controls as the final interface;
+- has broken or visibly incorrect copy;
+- lacks relevant empty, loading, error, or success states;
+- is not responsive for the requested context;
+- is visually cluttered, unreadable, or clearly placeholder-like.
+
+## Product UI minimum
+
+For request/consultation tools and dashboards, prefer a clear workspace, utility copy, styled form controls, summary cards, readable detailed sections, and one clear primary action.

package/dist-assets/docs/profiles/README.md

@@ -0,0 +1,19 @@
+# Workflow Profiles
+
+Workflow profiles guide domain quality without turning subjective preferences into universal runtime gates. Execution mode controls artifact depth; workflow profile controls domain guidance.
+
+The core remains deterministic: branch safety, scope, ownership, tests/build/typecheck, artifacts, evidence, truthfulness contradictions, bounded remediation, and final status.
+
+Profiles select skills and relevant checks. They must not impose a fixed visual template or add requirements that the user did not request.
+
+Available profiles:
+
+- `frontend-product`
+- `frontend-utility`
+- `backend-api`
+- `refactor`
+- `documentation`
+- `security-review`
+- `generic`
+
+A profile is independent from execution mode. Example: `standard + frontend-utility`.

package/dist-assets/docs/profiles/backend-api.md

@@ -0,0 +1,5 @@
+# Backend API Profile
+
+Use for endpoints, services, controllers, integrations, and authenticated APIs.
+
+Focus on contracts, boundary validation, authorization, failure paths, data consistency, idempotency where relevant, and automated tests. Do not add frontend deliverables unless requested.

package/dist-assets/docs/profiles/documentation.md

@@ -0,0 +1,3 @@
+# Documentation Profile
+
+Use for documentation-only work. Verify paths, commands, examples, links, and current behavior. Do not claim implementation or runtime behavior without repository evidence.

package/dist-assets/docs/profiles/frontend-product.md

@@ -0,0 +1,19 @@
+# Frontend Product Profile
+
+Use for landing pages, product pages, marketing surfaces, redesigns, and public product experiences.
+
+Required skills:
+
+- `frontend-development`
+- `ui-ux-design`
+
+Objective checks:
+
+- requested primary action works;
+- CSS is loaded and the rendered page is usable;
+- desktop and mobile layouts are not critically broken;
+- accessibility basics are present;
+- copy and data mode are truthful;
+- tests, typecheck, and build run when applicable.
+
+This profile does not require pricing, testimonials, a specific number of sections, a complex hero, or a SaaS template. Simplicity is not a failure. Broken rendering, unusable interaction, or unsupported claims are failures.

package/dist-assets/docs/profiles/frontend-utility.md

@@ -0,0 +1,19 @@
+# Frontend Utility Profile
+
+Use for search pages, validators, calculators, forms, dashboards, admin tools, and focused interactive utilities.
+
+Required skills:
+
+- `frontend-development`
+- `ui-ux-design`
+
+Objective checks:
+
+- the primary flow is complete;
+- applicable idle, loading, empty, error, and success states are handled;
+- deterministic logic is tested;
+- CSS is loaded and controls are usable;
+- desktop and mobile layouts are not critically broken;
+- tests, typecheck, and build run when applicable.
+
+Do not add pricing, testimonials, marketing sections, artificial loading, or commercial claims unless explicitly requested and truthful.

package/dist-assets/docs/profiles/refactor.md

@@ -0,0 +1,3 @@
+# Refactor Profile
+
+Use when observable behavior must be preserved while structure improves. Require focused diffs, characterization or regression tests, and explicit no-regression evidence. Do not combine unrelated cleanup.

package/dist-assets/docs/profiles/security-review.md

@@ -0,0 +1,3 @@
+# Security Review Profile
+
+Use for read-only or evidence-first security review. Classify findings by severity and runtime impact, distinguish production dependencies from development tooling, and identify the correct remediation owner. Never run force fixes without explicit approval.

package/dist-assets/docs/references/frontend-quality/landing-page-quality-checklist.md

@@ -0,0 +1,11 @@
+# Landing Page Quality Checklist
+
+- The page addresses the requested audience, promise, and primary action.
+- CSS is loaded and the primary action is usable.
+- Visual hierarchy, spacing, typography, and responsive rhythm are intentional enough for the requested context.
+- Copy and visual proof do not exceed implementation reality.
+- Interactive states are implemented only when they correspond to real behavior.
+- Desktop and mobile renders have no critical overflow, overlap, invisible content, or unreadable contrast.
+- Accessibility basics are present.
+
+Do not require a fixed section sequence, pricing, testimonials, a complex hero, or a particular visual fashion. A simple focused page may pass.

package/dist-assets/docs/references/frontend-quality/product-copy-truthfulness.md

@@ -0,0 +1,7 @@
+# Product Copy Truthfulness
+
+- Do not invent metrics, customers, testimonials, uptime, precision, certifications, official sources, or security claims.
+- Label mock and generated data visibly when users could mistake it for live data.
+- Match every CTA and benefit claim to implemented behavior.
+- Prefer concrete, supportable copy over inflated proof.
+- Treat unsupported claims as a quality failure, not harmless marketing polish.

package/dist-assets/docs/references/frontend-quality/quality-failure-examples.md

@@ -0,0 +1,20 @@
+# Frontend Quality Failure Examples
+
+Objective failures:
+
+- CSS is missing, not loaded, or leaves browser-default controls when styling was requested.
+- Primary interaction is unusable or required states are missing.
+- Desktop or mobile layout has severe overflow, overlap, invisible content, or unreadable contrast.
+- Mock data is presented as a live official integration.
+- Fictitious usage, speed, uptime, accuracy, security, or customer claims are presented as real.
+- Artificial loading is added to synchronous local logic.
+- Identifiers, money, dates, statuses, or API mappings are incorrect.
+- Visual evidence is claimed without a real browser check or evidence mode.
+
+Not failures by themselves:
+
+- a simple composition;
+- fewer sections than another landing page;
+- no pricing or testimonials;
+- a visual style that differs from a previous benchmark;
+- deliberate whitespace or a focused single-task layout.

package/dist-assets/docs/references/frontend-quality/visual-composition-patterns.md

@@ -0,0 +1,10 @@
+# Visual Composition Patterns
+
+Use these principles rather than copying a fixed template:
+
+- Establish one dominant visual idea per page.
+- Balance editorial storytelling with product interaction.
+- Use contrast, scale, spacing, and grouping before decoration.
+- Apply progressive disclosure to dense data.
+- Keep semantic colors consistent with status meaning.
+- Remove sections that repeat the same argument without new evidence.

package/dist-assets/docs/specs/runtime-operational-contract.md

@@ -0,0 +1,39 @@
+# Runtime operational contract
+
+## Objective
+
+Turn a natural software request into a safe, useful, validated delivery with proportionate process.
+
+## Invariants
+
+- no implementation on protected branches;
+- no skipped relevant validation;
+- no success after failed or unavailable required validation;
+- bounded remediation with `BLOCKED` on no progress;
+- no fabricated command, test, file, or agent claims.
+
+## Modes
+
+### Quick
+
+Inspect → safe branch → edit → targeted validation → concise handoff.
+
+### Standard
+
+Understand → brief plan → safe branch → implement → relevant validation → bounded remediation when needed → concise handoff.
+
+### Full
+
+Discovery/specification → safe branch → specialist implementation → independent validation → bounded remediation → revalidation → persisted evidence → final decision.
+
+## Evidence
+
+Quick and standard modes report branch, changed areas, observed commands/results, and limitations. No fixed workflow filenames or owner JSON are required.
+
+Full, release, audit, security, migration, and explicitly requested workflows may persist machine-generated evidence.
+
+## Public completion states
+
+- `COMPLETED`
+- `COMPLETED_WITH_NOTES`
+- `BLOCKED`

package/dist-assets/docs/troubleshooting-guide.md

@@ -0,0 +1,21 @@
+# Troubleshooting
+
+## Work is blocked on main or master
+
+Move to a scoped branch. If tracked dirty work makes recovery unsafe, preserve it and resolve the branch state before continuing.
+
+## Validation returns BLOCKED
+
+Inspect the command results. Fix failed tests/build/typecheck/lint, or add a meaningful validation path when none exists. Do not add no-op scripts or workflow documents as substitutes.
+
+## Standard work did not create EVIDENCE.json
+
+Expected. Quick and standard work use concise observed evidence. Persisted evidence is reserved for full, release, audit, security, migration, or explicitly requested work.
+
+## UI or product quality is weak
+
+Use the selected workflow profile and relevant skills. Automated gates do not fully evaluate visual hierarchy, copy, proportional architecture, or semantic truthfulness.
+
+## A direct model response ignored the workflow
+
+Direct natural-language execution remains instruction-driven unless the runtime invokes the CLI/gates. Treat unsupported claims about commands or agent handoffs as unverified.