sagaz-ai 0.3.2 → 0.4.1

package/ai-orchestration-ecosystem/onboarding/handoff-examples.md

@@ -0,0 +1,114 @@
+# Handoff Examples
+
+## Purpose
+
+Provide short examples of good Sagaz handoffs between product, design, engineering, QA, and release work.
+
+## Use When
+
+- A team member is learning what a Sagaz handoff should contain.
+- A project needs consistent phase transitions.
+- A reviewer wants to compare a handoff against the expected shape.
+
+## Invocation
+
+Ask Sagaz to produce a handoff for the next role:
+
+```text
+Sagaz: prepare a handoff from the current role to the next role. Include context, evidence, risks, assumptions, and permission needed before the next step.
+```
+
+## Handoff
+
+Use the examples below as calibration. A handoff should be short enough to scan and complete enough that the next role can continue without reconstructing the whole thread.
+
+## Product To Design
+
+```md
+Handoff: Product to Design
+Goal: Create scheduling flow for small service businesses.
+Users: Owner, staff member, customer.
+Scope: Booking, reschedule, cancellation, admin calendar.
+Non-goals: Payments in this release.
+Acceptance criteria:
+- Customer can book an available time.
+- Owner can see bookings by day.
+- Staff conflicts are prevented.
+Risks:
+- Calendar timezone behavior needs engineering review.
+Next squad: Design Studio
+Permission needed: approve UX exploration.
+```
+
+## Design To Engineering
+
+```md
+Handoff: Design to Engineering
+Screens covered: calendar, booking form, confirmation, empty state, error state.
+Components: date picker, time slot list, booking summary, status banner.
+Responsive notes: mobile single-column, desktop split calendar/detail view.
+Accessibility: keyboard focus states and form labels required.
+Assets: Figma link or local design references.
+Next squad: Product Factory or Implementation Engineer
+Permission needed: approve implementation.
+```
+
+## Engineering To QA
+
+```md
+Handoff: Engineering to QA
+Files changed:
+- src/features/scheduling/*
+- src/components/calendar/*
+Commands run:
+- npm test
+- npm run build
+Behavior verified:
+- booking creation
+- unavailable slot prevention
+Residual risk:
+- timezone edge cases need manual QA.
+Next squad: QA Verifier
+Permission needed: approve broader regression pass.
+```
+
+## QA To Release
+
+```md
+Handoff: QA to Release
+Verification:
+- unit tests passed
+- build passed
+- manual booking flow passed on desktop and mobile viewport
+Release blockers: none
+Risks accepted:
+- timezone behavior limited to configured business timezone.
+Rollback:
+- revert release commit
+- redeploy previous known-good build
+Next squad: GitHub Ops
+Permission needed: approve commit, tag, release, deploy, or publish.
+```
+
+## Release To Maintenance
+
+```md
+Handoff: Release to Maintenance
+Released version: vX.Y.Z
+Published artifacts:
+- GitHub release
+- deployment URL
+- package version, when applicable
+Monitoring:
+- check runtime logs
+- check user-reported booking failures
+Follow-up:
+- add timezone regression test
+- review operational memory preference for release cadence
+Next squad: Maintenance Ops
+Permission needed: approve follow-up issue creation.
+```
+
+## Verification
+
+A good handoff is complete when another role can continue without rereading the whole thread.

package/ai-orchestration-ecosystem/onboarding/product-pm.md

@@ -0,0 +1,97 @@
+# Product And PM Onboarding
+
+## Purpose
+
+Help product owners and PMs use Sagaz to turn goals into clear scope, requirements, risks, and implementation-ready handoffs.
+
+## Use When
+
+- Starting a new product, feature, or experiment.
+- Clarifying scope before design or engineering.
+- Comparing tradeoffs, cost, timeline, or risk.
+- Preparing a product handoff for implementation.
+
+## Invocation
+
+Start with the business outcome, users, constraints, and definition of done.
+
+```text
+Sagaz: act as the product team for this feature.
+
+Goal:
+- 
+
+Users:
+- 
+
+Constraints:
+- 
+
+Definition of done:
+- 
+
+Do not implement yet. Produce the product brief, risks, assumptions, and recommended next squad.
+```
+
+## Required Inputs
+
+- Product goal.
+- Target users.
+- Must-have and nice-to-have behavior.
+- Business constraints.
+- Deadline or milestone, when relevant.
+- Known risks or open questions.
+- Approval boundaries.
+
+## Expected Output
+
+- Product brief.
+- Scope boundaries.
+- Assumptions and questions.
+- Acceptance criteria.
+- Recommended workflow and squad.
+- Permission needed before design, architecture, or implementation.
+
+## Handoff
+
+Product handoff should include:
+
+- Problem statement.
+- User stories or jobs.
+- Acceptance criteria.
+- Non-goals.
+- Risks.
+- Open questions.
+- Recommended next role: design, technology, architecture, or implementation.
+
+## Good Prompts
+
+```text
+Sagaz: transform this idea into a product spec and tell me what is missing before design starts.
+```
+
+```text
+Sagaz: compare three implementation scopes for this feature: lean MVP, standard release, and premium version.
+```
+
+```text
+Sagaz: prepare a handoff for engineering, but first identify assumptions that still need approval.
+```
+
+## Common Mistakes
+
+- Asking for implementation before scope is stable.
+- Hiding non-goals.
+- Omitting target users.
+- Treating assumptions as requirements.
+- Skipping acceptance criteria.
+
+## Verification
+
+Before approving the next phase, confirm:
+
+- The scope is understandable.
+- Acceptance criteria are testable.
+- Non-goals are explicit.
+- Risks and tradeoffs are visible.
+- The next squad is appropriate.

package/ai-orchestration-ecosystem/onboarding/qa-release.md

@@ -0,0 +1,94 @@
+# QA And Release Onboarding
+
+## Purpose
+
+Help QA, release reviewers, and maintainers use Sagaz for verification, release readiness, GitHub operations, and rollback planning.
+
+## Use When
+
+- Reviewing a completed implementation.
+- Preparing a release.
+- Checking CI/CD readiness.
+- Creating release notes.
+- Auditing risk before deploy or publish.
+
+## Invocation
+
+Ask Sagaz to verify evidence and identify gaps.
+
+```text
+Sagaz: act as QA and release reviewer for this change.
+
+Review:
+- behavior
+- tests
+- build
+- accessibility or visual QA if relevant
+- deployment readiness
+- rollback plan
+
+Do not push, tag, release, deploy, or publish without asking approval.
+```
+
+## Required Inputs
+
+- Change summary.
+- Expected behavior.
+- Test commands.
+- Deployment target.
+- Release target.
+- Known risks.
+- Approval boundaries.
+
+## Expected Output
+
+- QA report.
+- Verification evidence.
+- Missing test or build gaps.
+- Release readiness decision.
+- Rollback plan.
+- GitHub or deployment operation proposal.
+
+## Handoff
+
+QA/release handoff should include:
+
+- What was verified.
+- Commands and results.
+- Manual checks.
+- Risks accepted or unresolved.
+- Release notes draft.
+- Rollback steps.
+- Approval needed before remote operations.
+
+## Good Prompts
+
+```text
+Sagaz: review this branch for release readiness and list blockers before any GitHub operation.
+```
+
+```text
+Sagaz: prepare release notes, rollback plan, and GitHub release proposal. Do not publish yet.
+```
+
+```text
+Sagaz: inspect CI failures and tell me the smallest safe fix path.
+```
+
+## Common Mistakes
+
+- Publishing before evidence is complete.
+- Forgetting rollback.
+- Skipping manual checks for UI changes.
+- Treating unreviewed CI failures as acceptable.
+- Mixing local success with production readiness.
+
+## Verification
+
+Before release approval, confirm:
+
+- Required checks passed.
+- Known risks are explicit.
+- Rollback plan is usable.
+- Changelog or release notes are ready.
+- GitHub/deploy/package operations have explicit approval.

package/ai-orchestration-ecosystem/prompts/README.md

@@ -0,0 +1,43 @@
+# Prompt Matrix
+
+## Purpose
+
+Provide copy-ready Sagaz prompts for common project, design, engineering, QA, release, and memory scenarios.
+
+Use these prompts when a user or team member knows the desired outcome but does not yet know which Sagaz workflow, squad, or protocol to invoke.
+
+## Use When
+
+- Starting a new project.
+- Auditing an existing repository.
+- Asking for Figma MCP or design work.
+- Implementing a feature.
+- Fixing a bug.
+- Preparing QA or release.
+- Creating operational memory.
+- Requesting review without file changes.
+
+## Prompt Rules
+
+- Start with `Sagaz:`.
+- Include goal, constraints, definition of done, and risk level when known.
+- State whether Sagaz may change files.
+- State whether external tools, MCPs, GitHub, deployment, or package publishing are allowed.
+- Ask Sagaz to identify workflow, squad, permission level, and first handoff.
+
+## Prompt Families
+
+- `project-start.md`: new projects and existing project audits.
+- `design-figma.md`: design, UX, UI, Figma MCP, and visual QA.
+- `implementation.md`: feature implementation, refactors, and bug fixes.
+- `qa-release.md`: verification, release readiness, GitHub, deploy, and publishing.
+- `memory.md`: project or team operational memory.
+
+## Verification
+
+Before using a prompt in production work, confirm:
+
+- It says whether file changes are allowed.
+- It names external operation limits.
+- It asks for evidence and risks.
+- It leaves room for Sagaz to inspect the current project before acting.

package/ai-orchestration-ecosystem/prompts/design-figma.md

@@ -0,0 +1,66 @@
+# Design And Figma Prompts
+
+## Purpose
+
+Provide prompts for UX, UI, design systems, visual QA, and Figma MCP workflows.
+
+## Use When
+
+- The team needs mockups, app flows, UI states, or design systems.
+- Designers want Sagaz to coordinate Figma MCP.
+- Engineering needs implementation-ready design handoff.
+
+## Prompt: UX Flow
+
+```text
+Sagaz: act as the design team and create a UX flow for this product.
+
+Users:
+-
+
+Core tasks:
+-
+
+Screens:
+-
+
+Do not use external connectors yet. Produce screen map, states, accessibility notes, and design handoff.
+```
+
+## Prompt: Figma MCP Mockup
+
+```text
+Sagaz: coordinate the design team using Figma MCP to create app-like mockups that can be inspected as real application flows.
+
+Include:
+- target users
+- main screens
+- empty/loading/error/success states
+- component states
+- interaction notes
+- responsive considerations
+- visual QA checklist
+
+Ask before using Figma MCP or writing to external design files.
+```
+
+## Prompt: Visual QA
+
+```text
+Sagaz: review this UI with the design and visual QA team.
+
+Check:
+- layout consistency
+- typography
+- spacing
+- accessibility
+- responsiveness
+- component states
+- visual regressions
+
+Do not change files until you list findings and ask for approval.
+```
+
+## Verification
+
+A good design response should include states, accessibility, responsive behavior, implementation constraints, and permission needed for Figma or file changes.

package/ai-orchestration-ecosystem/prompts/implementation.md

@@ -0,0 +1,69 @@
+# Implementation Prompts
+
+## Purpose
+
+Provide prompts for engineering implementation, refactors, and bug fixes.
+
+## Use When
+
+- Adding a feature.
+- Fixing a bug.
+- Refactoring code.
+- Implementing from a product or design handoff.
+
+## Prompt: Feature Implementation
+
+```text
+Sagaz: implement this feature using the existing project patterns.
+
+Feature:
+-
+
+Acceptance criteria:
+-
+
+Constraints:
+- keep the diff focused
+- avoid unrelated refactors
+- run proportional tests
+
+Inspect the project first, propose the plan, then proceed if the request already clearly authorizes implementation.
+```
+
+## Prompt: Bug Fix
+
+```text
+Sagaz: diagnose and fix this bug.
+
+Bug:
+-
+
+Expected behavior:
+-
+
+Observed behavior:
+-
+
+Find the likely root cause, make the smallest safe fix, run focused tests, and prepare a handoff with residual risk.
+```
+
+## Prompt: Safe Refactor
+
+```text
+Sagaz: refactor this area safely.
+
+Target:
+-
+
+Rules:
+- preserve behavior
+- keep public contracts stable
+- add or run tests proportional to risk
+- document rollback or recovery notes
+
+Do not broaden scope without asking.
+```
+
+## Verification
+
+A good implementation response should include files inspected, files changed, commands run, tests, behavior checked, and residual risk.

package/ai-orchestration-ecosystem/prompts/memory.md

@@ -0,0 +1,59 @@
+# Operational Memory Prompts
+
+## Purpose
+
+Provide prompts for creating, reviewing, applying, and updating Sagaz operational memory.
+
+## Use When
+
+- The team wants to preserve recurring preferences.
+- A project needs durable Sagaz context.
+- A preference should apply across future runs.
+- Existing memory needs review or cleanup.
+
+## Prompt: Propose Memory
+
+```text
+Sagaz: propose operational memory for this project.
+
+Include:
+- stable team preferences
+- stack preferences
+- design expectations
+- testing expectations
+- GitHub and release preferences
+- stop conditions
+
+Do not write files yet. Propose the memory content, scope, source, risk, review date, and ask for approval.
+```
+
+## Prompt: Apply Memory
+
+```text
+Sagaz: inspect existing operational memory and tell me which preferences are relevant to this task.
+
+Task:
+-
+
+Do not apply stale, risky, or conflicting preferences without asking.
+```
+
+## Prompt: Review Memory
+
+```text
+Sagaz: review this project's operational memory.
+
+Check:
+- stale preferences
+- unclear sources
+- missing review dates
+- risky assumptions
+- conflicts with the current repository
+- anything that should be deprecated
+
+Do not update the file until I approve.
+```
+
+## Verification
+
+A good memory response should include scope, source, confidence, permission impact, review date, and whether the preference is advisory or blocking.

package/ai-orchestration-ecosystem/prompts/project-start.md

@@ -0,0 +1,73 @@
+# Project Start Prompts
+
+## Purpose
+
+Provide prompts for starting new projects, auditing existing repositories, and selecting the right Sagaz workflow.
+
+## Use When
+
+- The user wants to begin a product or project.
+- The user opens Sagaz inside an existing codebase.
+- The team needs stack, workflow, risk, and next-step recommendations.
+
+## Prompt: New Product
+
+```text
+Sagaz: start a new project using the smallest sufficient workflow.
+
+Goal:
+-
+
+Users:
+-
+
+Constraints:
+-
+
+Definition of done:
+-
+
+Do not implement yet. Recommend workflow, squad, stack direction, risks, first artifacts, and permission needed for the next step.
+```
+
+## Prompt: Existing Project Audit
+
+```text
+Sagaz: audit this project and tell me what workflow, stack playbook, risks, tests, and next implementation step you recommend. Do not change files yet.
+```
+
+## Prompt: Stack Recommendation
+
+```text
+Sagaz: inspect the project goal and recommend a stack.
+
+Compare options by:
+- implementation speed
+- cost
+- maintainability
+- deployment
+- future changes
+- team skill fit
+- TypeScript strict compatibility
+- Supabase fit for auth, relational data, storage, realtime, RLS, migrations, and generated types
+
+Do not install dependencies or create files yet.
+```
+
+## Prompt: Resume A Project
+
+```text
+Sagaz: resume this project from existing repository context.
+
+First:
+- inspect current files
+- identify run state or handoff artifacts
+- summarize what appears complete
+- identify the safest next step
+
+Do not change files until I approve the plan.
+```
+
+## Verification
+
+A good project-start response should include selected workflow, squad, assumptions, risks, permission level, and next artifact.

package/ai-orchestration-ecosystem/prompts/qa-release.md

@@ -0,0 +1,65 @@
+# QA And Release Prompts
+
+## Purpose
+
+Provide prompts for QA, release readiness, GitHub operations, deployment, and package publishing.
+
+## Use When
+
+- Verifying a change.
+- Preparing a release.
+- Auditing CI/CD readiness.
+- Creating release notes or rollback plans.
+- Publishing to npm or another registry.
+
+## Prompt: QA Review
+
+```text
+Sagaz: review this change as QA.
+
+Check:
+- expected behavior
+- regressions
+- tests
+- build
+- accessibility or visual QA if relevant
+- residual risk
+
+Do not commit, push, deploy, tag, release, or publish.
+```
+
+## Prompt: Release Readiness
+
+```text
+Sagaz: prepare release readiness for this project.
+
+Include:
+- version recommendation
+- changelog or release notes
+- verification evidence
+- rollback plan
+- GitHub operations needed
+- deployment or publish operations needed
+
+Do not execute remote operations until I approve.
+```
+
+## Prompt: GitHub Release
+
+```text
+Sagaz: prepare a GitHub release proposal.
+
+Include:
+- commit summary
+- tag name
+- release title
+- release notes
+- checks required
+- rollback plan
+
+Ask before staging, committing, pushing, tagging, or creating the release.
+```
+
+## Verification
+
+A good QA/release response should clearly distinguish local verification from remote release, deployment, or package publishing.