sagaz-ai 0.3.2 → 0.4.1

package/ai-orchestration-ecosystem/golden-outputs/memory-proposal-output.md

@@ -0,0 +1,63 @@
+# Golden Output: Memory Proposal
+
+## Purpose
+
+Show a reference operational memory proposal before writing durable memory.
+
+## Use When
+
+- A team wants project or team preferences retained.
+- Sagaz should propose memory but not write it yet.
+- Reviewers need to check memory safety.
+
+## Input Prompt
+
+```text
+Sagaz: propose operational memory for this project. Do not write files yet.
+```
+
+## Expected Response
+
+```md
+Memory update proposed:
+Scope: M2 project
+Preference:
+- Use existing stack patterns before introducing new dependencies.
+- Ask before GitHub, deploy, package, or external connector operations.
+- Preserve Windows and macOS command differences in handoffs.
+
+Source:
+- User request and current Sagaz operating rules.
+
+Why it helps:
+- Reduces repeated setup discussion in future Sagaz runs.
+
+Risk:
+- Preferences can become stale after stack or team changes.
+
+Expiry or review date:
+- Review in 90 days or after major architecture changes.
+
+Approval needed:
+- May I create or update `.sagaz/operational-memory.md` with these entries?
+```
+
+## Quality Criteria
+
+- It asks before writing memory.
+- It excludes secrets and sensitive data.
+- It names scope, source, confidence, risk, and review date.
+- It treats memory as advisory.
+- It references permission impact.
+
+## Bad Output Signals
+
+- Writes memory without approval.
+- Stores secrets, tokens, or private data.
+- Stores guesses as confirmed preferences.
+- Omits review date.
+- Lets memory override current user instructions.
+
+## Verification
+
+Only approve memory writing when each entry is scoped, sourced, reviewable, and safe.

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,70 @@
+# 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
+- TypeScript strict status when TypeScript is present
+- Supabase configuration when backend data, auth, storage, or realtime is present
+- 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

@@ -77,6 +77,7 @@
       "protocols/future-change-safety.md",
       "protocols/github-operations.md",
       "protocols/guided-proactivity.md",
+      "protocols/generated-code-linting.md",
       "protocols/installed-skill-sync.md",
       "protocols/memory.md",
       "protocols/model-routing.md",
@@ -155,6 +156,7 @@
       "governance/versioning.md"
     ],
     "evals": [
+      "evals/golden-output-evaluation.md",
       "evals/sagaz-evaluation-suite.md"
     ],
     "examples": [
@@ -164,6 +166,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.