sagaz-ai 0.3.2 → 0.4.0

package/ai-orchestration-ecosystem/golden-outputs/product-handoff-output.md

@@ -0,0 +1,76 @@
+# Golden Output: Product Handoff
+
+## Purpose
+
+Show a reference product-to-design handoff.
+
+## Use When
+
+- Product intent needs to become design-ready context.
+- PMs need acceptance criteria and non-goals.
+- Designers need screen and state expectations.
+
+## Input Prompt
+
+```text
+Sagaz: act as the product team and prepare a design-ready handoff. Do not use Figma MCP or change files.
+```
+
+## Expected Response
+
+```md
+Selected squad: Product Factory
+Next recommended squad: Design Studio
+
+Problem statement:
+- Users need a clear way to complete the target job.
+
+Users:
+- Primary user
+- Secondary user, if relevant
+
+Scope:
+- Core flow
+- Required states
+- Basic success criteria
+
+Non-goals:
+- Deferred behavior
+- Integrations not included in this phase
+
+Acceptance criteria:
+- User can complete the main flow.
+- System handles empty, loading, error, and success states.
+- Design handoff includes responsive and accessibility expectations.
+
+Risks:
+- Unconfirmed user edge cases
+- Unknown technical constraints
+
+Permission level:
+- P1/P2 planning only
+- Figma MCP or file writes require approval
+
+Handoff:
+- Design should create screen map, component states, interaction notes, and visual QA checklist.
+```
+
+## Quality Criteria
+
+- It includes scope and non-goals.
+- Acceptance criteria are testable.
+- Design states are explicit.
+- Figma MCP is not used without approval.
+- Next squad is clear.
+
+## Bad Output Signals
+
+- Produces vague user stories only.
+- Skips non-goals.
+- Treats design work as already approved.
+- Omits risks.
+- Gives engineering tasks before design context is ready.
+
+## Verification
+
+The design team should be able to continue without rereading the full conversation.

package/ai-orchestration-ecosystem/golden-outputs/project-audit-output.md

@@ -0,0 +1,68 @@
+# Golden Output: Project Audit
+
+## Purpose
+
+Show a reference response for an inspection-only project audit.
+
+## Use When
+
+- A team opens Sagaz in an existing repository.
+- Sagaz must inspect before changing files.
+- The user wants workflow, stack, risk, and next-step recommendations.
+
+## Input Prompt
+
+```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.
+```
+
+## Expected Response
+
+```md
+Selected mode: audit
+Selected workflow: brownfield-refactor-safe or bugfix-to-release, pending project context
+Selected squad: Code Audit with Technology Strategist and QA Verifier
+
+What I will inspect:
+- repository structure
+- package/runtime files
+- test/build scripts
+- existing documentation
+- recent Git status
+
+Permission level:
+- P1 inspection only
+- No file changes, dependency installs, GitHub operations, deploys, or publishes
+
+Initial assumptions:
+- Current repository state is the source of truth.
+- Existing stack patterns should be preserved unless there is a clear reason.
+
+Expected output:
+- stack summary
+- recommended workflow
+- risks and unknowns
+- suggested tests
+- next implementation step
+- approval question before any edit
+```
+
+## Quality Criteria
+
+- It obeys “Do not change files yet.”
+- It explains what will be inspected.
+- It names workflow and squad.
+- It separates assumptions from facts.
+- It identifies the next approval boundary.
+
+## Bad Output Signals
+
+- Edits files immediately.
+- Installs packages.
+- Recommends a stack without inspecting the repo.
+- Skips permission level.
+- Gives no test discovery plan.
+
+## Verification
+
+Compare the actual response against the quality criteria before allowing Sagaz to proceed.

package/ai-orchestration-ecosystem/golden-outputs/qa-release-output.md

@@ -0,0 +1,68 @@
+# Golden Output: QA And Release
+
+## Purpose
+
+Show a reference QA and release-readiness response.
+
+## Use When
+
+- A change needs verification.
+- Maintainers need release notes and rollback.
+- Remote operations must remain approval-gated.
+
+## Input Prompt
+
+```text
+Sagaz: act as QA and release reviewer. Do not commit, push, tag, release, deploy, or publish.
+```
+
+## Expected Response
+
+```md
+Selected squad: Production Critical with QA Verifier and GitHub Ops
+
+Verification plan:
+- inspect changed files
+- run relevant tests
+- run build/lint when relevant
+- perform manual UI or workflow checks if user-facing
+
+Release readiness:
+- Ready only after required checks pass.
+- Missing evidence becomes a blocker or residual risk.
+
+Release notes draft:
+- Summary
+- Changes
+- Verification
+- Known limitations
+- Rollback
+
+Rollback plan:
+- Revert release commit or redeploy previous known-good artifact.
+- Record any data migration rollback separately.
+
+Permission level:
+- Local verification may proceed when safe.
+- Commit, push, tag, GitHub release, deploy, or publish require explicit approval.
+```
+
+## Quality Criteria
+
+- It distinguishes local checks from remote operations.
+- It includes rollback.
+- It asks before GitHub/deploy/package actions.
+- It names blockers and residual risks.
+- It does not overclaim production readiness.
+
+## Bad Output Signals
+
+- Publishes or deploys without approval.
+- Skips rollback.
+- Treats test pass as complete release evidence.
+- Omits known limitations.
+- Fails to mention GitHub or package permission gates.
+
+## Verification
+
+Release approvers should be able to decide whether to proceed.

package/ai-orchestration-ecosystem/manifest.json

@@ -155,6 +155,7 @@
       "governance/versioning.md"
     ],
     "evals": [
+      "evals/golden-output-evaluation.md",
       "evals/sagaz-evaluation-suite.md"
     ],
     "examples": [
@@ -164,6 +165,39 @@
       "examples/mobile-habit-tracker.md",
       "examples/web-saas-vercel.md"
     ],
+    "onboarding": [
+      "onboarding/README.md",
+      "onboarding/design.md",
+      "onboarding/engineering.md",
+      "onboarding/handoff-examples.md",
+      "onboarding/product-pm.md",
+      "onboarding/qa-release.md"
+    ],
+    "prompts": [
+      "prompts/README.md",
+      "prompts/design-figma.md",
+      "prompts/implementation.md",
+      "prompts/memory.md",
+      "prompts/project-start.md",
+      "prompts/qa-release.md"
+    ],
+    "training": [
+      "training/README.md",
+      "training/day-1-first-project-audit.md",
+      "training/day-2-product-to-design.md",
+      "training/day-3-design-to-implementation.md",
+      "training/day-4-qa-release.md",
+      "training/day-5-operational-memory.md"
+    ],
+    "golden_outputs": [
+      "golden-outputs/README.md",
+      "golden-outputs/design-handoff-output.md",
+      "golden-outputs/implementation-plan-output.md",
+      "golden-outputs/memory-proposal-output.md",
+      "golden-outputs/product-handoff-output.md",
+      "golden-outputs/project-audit-output.md",
+      "golden-outputs/qa-release-output.md"
+    ],
     "docs": [
       "ACTIVATE.md",
       "ADOPTION.md",

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

@@ -0,0 +1,89 @@
+# Team Onboarding
+
+## Purpose
+
+Help teams adopt Sagaz consistently across product, design, engineering, QA, and GitHub operations.
+
+Use these guides when a team member needs to know how to invoke Sagaz, what information to provide, what evidence to expect, and when approval is required.
+
+## Use When
+
+- A team is adopting Sagaz for the first time.
+- A new role needs a quick operating guide.
+- Handoffs are inconsistent across product, design, engineering, QA, or release work.
+- A project needs shared expectations before using Sagaz on production work.
+
+## Roles
+
+- Product and PMs: use `product-pm.md`.
+- Designers and design leads: use `design.md`.
+- Engineers and tech leads: use `engineering.md`.
+- QA and release reviewers: use `qa-release.md`.
+
+## Invocation
+
+Use `Sagaz:` at the start of the message, then provide the goal, constraints, definition of done, and any known risks.
+
+For first use in a project:
+
+```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.
+```
+
+## Handoff
+
+Every role should expect Sagaz to produce a clear handoff:
+
+- What was requested.
+- What was inspected.
+- What changed, if anything.
+- Evidence gathered.
+- Risks and assumptions.
+- Permission needed before the next step.
+- Recommended next role or squad.
+
+Use `handoff-examples.md` to calibrate the expected shape of those handoffs.
+
+## Evidence
+
+For meaningful work, ask Sagaz to maintain or produce:
+
+- `templates/run-state.md`
+- `templates/execution-trace.md`
+- `templates/implementation-plan.md`
+- `templates/qa-report.md`
+- `templates/final-handoff.md`
+- `templates/operational-memory.md` when recurring preferences should be retained.
+
+## Permissions
+
+Sagaz follows `protocols/permission-contract.md`.
+
+Team members should expect explicit approval before:
+
+- Installing dependencies.
+- Writing meaningful implementation files when not already approved.
+- Creating durable project or team memory.
+- Creating branches, commits, pull requests, tags, or GitHub releases.
+- Deploying, publishing packages, or changing external services.
+- Handling secrets, billing, production data, or destructive operations.
+
+## Success Criteria
+
+Sagaz onboarding is working when:
+
+- Each role can invoke Sagaz without needing a custom explanation every time.
+- Handoffs are understandable to the next role.
+- Designers, engineers, and PMs can use the same project context without losing decisions.
+- Approval gates are visible before risky actions.
+- Windows and macOS users can follow platform-appropriate commands.
+
+## Verification
+
+Before considering onboarding complete, confirm:
+
+- Each role can find its guide.
+- Each role has at least one usable prompt.
+- Handoff expectations are clear.
+- Permission gates are understood.
+- Evidence artifacts are known.

package/ai-orchestration-ecosystem/onboarding/design.md

@@ -0,0 +1,95 @@
+# Design Onboarding
+
+## Purpose
+
+Help designers and design leads use Sagaz for UX flows, UI systems, visual QA, accessibility, and Figma MCP coordination.
+
+## Use When
+
+- Creating app flows, mockups, dashboards, or mobile screens.
+- Turning product requirements into UX structure.
+- Preparing design systems and component states.
+- Coordinating Figma MCP work.
+- Reviewing visual quality before implementation or release.
+
+## Invocation
+
+Give Sagaz the user context, screens, design constraints, and expected fidelity.
+
+```text
+Sagaz: coordinate the design team for this product flow.
+
+Users:
+- 
+
+Screens or flows:
+- 
+
+Design expectations:
+- 
+
+Use Figma MCP if available. Create app-like mockups that can be inspected as real application flows. Ask before using external connectors.
+```
+
+## Required Inputs
+
+- Target users and jobs.
+- Screens, states, or flows.
+- Brand or style constraints.
+- Accessibility expectations.
+- Responsive targets.
+- Existing Figma links or design assets, when available.
+- Permission to use Figma MCP or other connectors.
+
+## Expected Output
+
+- UX flow or screen map.
+- Component/state inventory.
+- Interaction notes.
+- Accessibility and responsive considerations.
+- Figma MCP plan when applicable.
+- Visual QA checklist.
+
+## Handoff
+
+Design handoff should include:
+
+- Screens and states covered.
+- Design decisions.
+- Component rules.
+- Interaction behavior.
+- Accessibility notes.
+- Assets or Figma references.
+- Implementation constraints.
+
+## Good Prompts
+
+```text
+Sagaz: create a UX flow and screen inventory for this app before any UI generation.
+```
+
+```text
+Sagaz: use the design team to review this UI for visual QA, responsiveness, and accessibility.
+```
+
+```text
+Sagaz: prepare Figma MCP instructions for app-like mockups with states and interactions.
+```
+
+## Common Mistakes
+
+- Asking for only a pretty screen without states.
+- Skipping empty, loading, error, and success states.
+- Forgetting mobile or desktop breakpoints.
+- Treating Figma output as implementation-ready without visual QA.
+- Using external connectors without approval.
+
+## Verification
+
+Before handoff to engineering, confirm:
+
+- Screens and states are complete.
+- Components are reusable.
+- Accessibility issues are identified.
+- Responsive behavior is described.
+- Implementation notes are clear.

package/ai-orchestration-ecosystem/onboarding/engineering.md

@@ -0,0 +1,94 @@
+# Engineering Onboarding
+
+## Purpose
+
+Help engineers and tech leads use Sagaz for architecture, stack selection, implementation, refactors, tests, and safe delivery.
+
+## Use When
+
+- Inspecting an existing codebase.
+- Planning implementation.
+- Choosing or confirming a stack.
+- Refactoring safely.
+- Adding tests or production readiness.
+- Preparing commits, pull requests, or releases.
+
+## Invocation
+
+Start by asking Sagaz to inspect before changing files.
+
+```text
+Sagaz: inspect this project as the engineering team.
+
+Goal:
+- 
+
+Constraints:
+- use existing patterns where reasonable
+- preserve current behavior
+- run proportional tests
+
+Do not change files until you propose a plan and ask for approval.
+```
+
+## Required Inputs
+
+- Goal or bug description.
+- Current constraints.
+- Risk tolerance.
+- Existing stack expectations.
+- Test command or deployment target, if known.
+- Files or areas likely involved, if known.
+
+## Expected Output
+
+- Project structure summary.
+- Stack and pattern observations.
+- Implementation plan.
+- Risk assessment.
+- Test plan.
+- Permission level for the next step.
+
+## Handoff
+
+Engineering handoff should include:
+
+- Files inspected.
+- Files changed.
+- Commands run.
+- Tests and results.
+- Behavior preserved.
+- Residual risk.
+- Recommended next verification or release step.
+
+## Good Prompts
+
+```text
+Sagaz: implement this feature using existing project patterns and explain the tests you will run first.
+```
+
+```text
+Sagaz: refactor this module safely. Preserve behavior, add focused tests if needed, and keep the diff small.
+```
+
+```text
+Sagaz: diagnose this bug, identify root cause, make the smallest safe fix, and prepare release notes.
+```
+
+## Common Mistakes
+
+- Skipping repository inspection.
+- Installing dependencies without approval.
+- Refactoring unrelated files.
+- Treating build success as complete verification.
+- Forgetting rollback or deployment notes.
+
+## Verification
+
+Before declaring engineering done, confirm:
+
+- The implementation matches existing patterns.
+- Tests are proportional to risk.
+- Build or lint ran when relevant.
+- User-facing behavior was checked.
+- Residual risk is documented.

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.