sagaz-ai 0.3.2 → 0.4.1

package/ai-orchestration-ecosystem/protocols/generated-code-linting.md

@@ -0,0 +1,103 @@
+# Protocol: Generated Code Linting
+
+## Objective
+
+Ensure code generated or modified by Sagaz is checked with the project's existing linting, formatting, and static-analysis tools whenever those tools are available and relevant.
+
+Sagaz must not invent a new lint stack by default. It should discover and use the project's existing commands first.
+
+## Required Practice
+
+1. Inspect the project for existing lint, format, typecheck, and static-analysis commands before or during implementation.
+2. Prefer package scripts and repository documentation over ad hoc commands.
+3. Run the narrowest relevant lint command after code changes when available.
+4. Run typecheck or build when lint alone cannot validate generated code risk.
+5. Do not install ESLint, Biome, Prettier, Ruff, Stylelint, or similar tools without explicit user approval.
+6. If no lint command exists, record that absence and recommend adding one only when it would help the project.
+7. If lint fails, treat the failure as a blocker unless the user explicitly accepts the residual risk.
+8. Avoid unrelated formatting churn; format only touched files unless the project command intentionally formats the full repository.
+9. Include lint command, result, and residual risk in the implementation or QA handoff.
+
+## Tool Discovery
+
+Check common sources in this order:
+
+- Repository docs such as `README.md`, `CONTRIBUTING.md`, or task runner docs.
+- `package.json` scripts such as `lint`, `format`, `typecheck`, `check`, `biome`, or `eslint`.
+- Monorepo task runners such as Turborepo, Nx, pnpm workspaces, npm workspaces, or yarn workspaces.
+- Language-specific tooling such as Ruff, Black, mypy, gofmt, golangci-lint, cargo fmt, cargo clippy, dotnet format, ktlint, swiftlint, or Android lint.
+- CI configuration when local commands are unclear.
+
+## Required Commands
+
+When available and relevant, Sagaz should prefer:
+
+```text
+npm run lint
+npm run typecheck
+npm run build
+pnpm lint
+yarn lint
+bun run lint
+```
+
+Use the package manager already used by the project.
+
+For non-JavaScript projects, use the equivalent project-native command.
+
+## Permission Rules
+
+Linting existing project code is usually a local verification action.
+
+Ask explicit approval before:
+
+- Installing or upgrading linting tools.
+- Rewriting the whole repository with a formatter.
+- Running commands that modify large unrelated areas.
+- Running networked package-manager commands.
+- Changing lint rules, formatter config, CI config, or pre-commit hooks.
+
+Follow `protocols/permission-contract.md`.
+
+## Handoff Evidence
+
+Generated code handoff should include:
+
+```md
+Lint discovery:
+Lint command:
+Typecheck command:
+Format command:
+Commands run:
+Result:
+Failures:
+Fixes applied:
+Residual risk:
+```
+
+If lint was not run:
+
+```md
+Lint not run:
+Reason:
+Recommended next step:
+Risk:
+```
+
+## Blocking Conditions
+
+- A relevant lint command exists and fails.
+- Generated code introduces lint violations.
+- Typecheck fails after generated code changes.
+- The only available lint command would rewrite unrelated files and the user has not approved it.
+- The project lacks linting and the change is high risk without an alternative verification method.
+
+## Output
+
+When Sagaz changes code, the final response or handoff should state whether lint was:
+
+- run and passed,
+- run and failed,
+- unavailable,
+- skipped with reason,
+- deferred pending user approval.

package/ai-orchestration-ecosystem/protocols/stack-selection.md

@@ -1,32 +1,104 @@
-# Protocol: Stack Selection
+# Protocol: Stack Selection
 
 ## Objective
 
-Define how Sagaz should handle Stack Selection while keeping the process clear, low-token, safe, and verifiable.
+Define how Sagaz selects and explains a project stack, including when to recommend TypeScript strict mode and Supabase.
+
+Sagaz should prefer boring, maintainable, production-friendly choices that fit the user's goal, existing repository, team skill, cost, deployment target, and future-change needs.
 
 ## Required Practice
 
-- Start from the user goal and current project state.
-- Load only relevant context.
-- Separate facts, assumptions, inferences, risks, and decisions.
-- Ask permission before meaningful state changes.
-- Record evidence and residual risk.
+1. Start from the user goal, project maturity, current repository state, and definition of done.
+2. Reuse the existing stack when it is healthy and fits the goal.
+3. Compare meaningful alternatives when the stack is not already fixed.
+4. Explain tradeoffs by cost, speed, maintainability, scale, deployment, security, and future changes.
+5. Recommend TypeScript strict mode for TypeScript-based new projects unless there is a clear migration or legacy constraint.
+6. Consider Supabase when the app needs relational data, managed auth, storage, realtime, or fast backend setup.
+7. Record assumptions, risks, and permission boundaries before installing dependencies or provisioning external services.
+8. Reference relevant stack presets and playbooks.
+9. Include verification commands and release implications in the recommendation.
+
+## TypeScript Strict Policy
+
+For new TypeScript projects, Sagaz should default to:
+
+- `typescript`
+- `strict: true`
+- `noImplicitAny: true` through strict mode
+- typecheck script such as `npm run typecheck` when supported by the stack
+- linting via the project's selected lint tool
+
+For existing TypeScript projects:
+
+- Inspect `tsconfig.json` before recommending changes.
+- Preserve existing constraints unless the user approves a migration.
+- If `strict` is disabled, recommend a staged strict migration when risk is meaningful.
+- Do not flip strict mode on a large existing codebase without a migration plan and user approval.
+
+If TypeScript is not appropriate, explain why and name the verification alternative.
+
+## Supabase Policy
+
+Consider Supabase when the project needs:
+
+- relational data with managed Postgres,
+- authentication,
+- row-level security,
+- user-uploaded files,
+- realtime features,
+- generated types from database schema,
+- fast full-stack delivery without operating database infrastructure directly.
 
-## Standard Recommendation Format
+Do not recommend Supabase automatically when:
+
+- the app is static and has no backend data,
+- the user already has a committed backend platform,
+- compliance or data residency constraints are unresolved,
+- the project needs a database architecture Supabase does not fit,
+- vendor coupling is unacceptable.
+
+When recommending Supabase, Sagaz must include:
+
+- data model strategy,
+- RLS policy plan,
+- migration plan,
+- backup and restore plan,
+- environment variable plan,
+- local or preview environment strategy,
+- permission needed before creating or changing Supabase resources.
+
+Use `stack-presets/supabase.md`, `stack-playbooks/nextjs-vercel-supabase.md`, and `protocols/mcp-connector-policy.md` when relevant.
+
+## Recommendation Format
 
 ```md
-Recommendation:
-Why now:
-What changes:
-Benefit:
-Risk:
+Recommended stack:
+Why this fits:
+Alternatives considered:
+TypeScript strict decision:
+Supabase decision:
+Deployment target:
+Cost and operational impact:
+Security and data impact:
+Verification commands:
+Migration or setup steps:
 Permission required:
+Residual risk:
 ```
+
 ## Blocking Conditions
 
-- The primary flow fails.
-- A relevant build, check, or test fails without explanation.
-- Secrets or sensitive data would be exposed.
-- A high risk is not accepted by the user.
+- The project already has a stack and Sagaz has not inspected it.
+- The recommendation changes database, auth, hosting, or language without user approval.
+- TypeScript strict migration would cause broad breakage and no migration plan exists.
+- Supabase would introduce unresolved compliance, data residency, backup, RLS, or vendor-coupling risk.
+- Required secrets or external account access would be needed without approval.
 - Verification evidence is missing for the risk level.
-
+
+## Output
+
+Sagaz stack recommendations should be concise, but must explicitly state:
+
+- whether TypeScript strict is recommended, already enabled, deferred, or not applicable,
+- whether Supabase is recommended, deferred, rejected, or already present,
+- what must be verified before implementation begins.

package/ai-orchestration-ecosystem/stack-playbooks/nextjs-vercel-supabase.md

@@ -14,9 +14,10 @@ Operate a Next.js application deployed on Vercel with Supabase for auth, databas
 
 1. Inspect `package.json` scripts and package manager.
 2. Confirm Node.js version and lockfile.
-3. Confirm whether Supabase is already configured.
-4. Identify required env vars for local, preview, and production.
-5. Apply `protocols/permission-contract.md` before touching Vercel or Supabase accounts.
+3. Inspect `tsconfig.json` and confirm TypeScript strict status.
+4. Confirm whether Supabase is already configured.
+5. Identify required env vars for local, preview, and production.
+6. Apply `protocols/permission-contract.md` before touching Vercel or Supabase accounts.
 
 Common commands:
 
@@ -33,10 +34,12 @@ Use the project's actual package manager if it is not npm.
 
 - Typecheck or build.
 - Lint if configured.
+- TypeScript strict compatibility or migration notes.
 - Unit/integration tests for business logic.
 - Playwright smoke test for critical flows.
 - Accessibility and responsive checks for core pages.
 - Supabase RLS review when user data exists.
+- Generated Supabase TypeScript types when schema is available.
 - Env var audit for secrets and public variables.
 
 ## Deployment
@@ -61,4 +64,3 @@ Preview URL:
 Risks:
 Permission needed:
 ```
-

package/ai-orchestration-ecosystem/stack-presets/admin-dashboard.md

@@ -7,7 +7,7 @@ Operational dashboards, internal tools, CRM-like interfaces, analytics panels, a
 ## Default Stack
 
 - React or Next.js
-- TypeScript
+- TypeScript with `strict: true` for new projects
 - shadcn/ui, another component library, or a strict internal design system
 - Tables, filters, forms, role permissions, and audit logs
 - Playwright for critical workflows
@@ -52,4 +52,5 @@ Operational dashboards, internal tools, CRM-like interfaces, analytics panels, a
 - error states
 - destructive-action confirmations
 - audit trail needs
+- TypeScript strict compatibility
 - responsive behavior

package/ai-orchestration-ecosystem/stack-presets/nextjs-vercel.md

@@ -7,10 +7,11 @@ Production web apps, SaaS products, dashboards, marketing sites with dynamic fea
 ## Default Stack
 
 - Next.js
-- TypeScript
+- TypeScript with `strict: true` for new projects
 - Tailwind CSS or an existing design system
 - shadcn/ui when the project needs customizable React components and no established component system exists
 - Vercel
+- Supabase when auth, relational data, storage, or realtime features are needed
 - Playwright
 - GitHub Actions
 
@@ -27,6 +28,7 @@ Production web apps, SaaS products, dashboards, marketing sites with dynamic fea
 - Good performance defaults.
 - Works well for full-stack web applications.
 - Easy to evolve from prototype to production.
+- Strong fit with Supabase when managed auth, Postgres, storage, realtime, RLS, and generated TypeScript types are useful.
 
 ## Tradeoffs
 
@@ -39,6 +41,7 @@ Production web apps, SaaS products, dashboards, marketing sites with dynamic fea
 - The user wants a serious browser-based app.
 - SEO or performance matters.
 - Deployment simplicity matters.
+- The app needs TypeScript strict, managed backend services, or Supabase-friendly auth/data flows.
 
 ## Avoid When
 

package/ai-orchestration-ecosystem/stack-presets/node-api.md

@@ -7,7 +7,7 @@ Backend APIs, integrations, webhooks, automation services, and full-stack apps n
 ## Default Stack
 
 - Node.js
-- TypeScript
+- TypeScript with `strict: true` for new projects
 - Fastify or Express based on project needs
 - Zod or similar runtime validation
 - Postgres or managed database
@@ -37,4 +37,5 @@ Backend APIs, integrations, webhooks, automation services, and full-stack apps n
 - logging and observability
 - rate limiting
 - integration tests
+- typecheck and lint
 - deployment and rollback

package/ai-orchestration-ecosystem/stack-presets/react-vite.md

@@ -7,7 +7,7 @@ Client-heavy apps, dashboards, internal tools, prototypes, and static sites that
 ## Default Stack
 
 - React
-- TypeScript
+- TypeScript with `strict: true` for new projects
 - Vite
 - Tailwind CSS or existing CSS architecture
 - shadcn/ui when using Tailwind CSS and the app needs reusable, accessible UI components
@@ -36,3 +36,4 @@ Client-heavy apps, dashboards, internal tools, prototypes, and static sites that
 - The app is mostly client-side.
 - The project needs simplicity and speed.
 - The backend already exists.
+- TypeScript strict and lint/typecheck feedback are useful for maintainability.

package/ai-orchestration-ecosystem/stack-presets/supabase.md

@@ -11,6 +11,7 @@ Apps needing managed Postgres, authentication, storage, edge functions, and fast
 - Supabase Storage when user-uploaded files are needed
 - Supabase Edge Functions when lightweight backend functions are needed
 - Local Supabase CLI or preview environment strategy for schema and policy testing
+- Generated TypeScript types from the Supabase schema when the app uses TypeScript
 
 ## Strengths
 
@@ -24,6 +25,7 @@ Apps needing managed Postgres, authentication, storage, edge functions, and fast
 - Row-level security must be designed and tested carefully.
 - Vendor-specific features create some coupling.
 - Production backup and migration strategy must be explicit.
+- TypeScript projects should use generated Supabase types and strict mode where practical.
 
 ## Use When
 
@@ -40,3 +42,5 @@ Apps needing managed Postgres, authentication, storage, edge functions, and fast
 - auth flows
 - environment variables
 - local or preview environment strategy
+- generated TypeScript types
+- TypeScript strict compatibility

package/ai-orchestration-ecosystem/tasks/implementation-build.md

@@ -38,7 +38,8 @@ Active workflow owner squad.
 - Changes are scoped to the active task.
 - Implementation maps to acceptance criteria.
 - Risky changes are isolated, reversible, or explicitly justified.
-- Tests, build checks, or manual verification steps are identified.
+- Existing lint, format, typecheck, tests, build checks, or manual verification steps are identified.
+- Generated or modified code follows `protocols/generated-code-linting.md`.
 
 ## Handoff
 
@@ -53,7 +54,7 @@ Active owner squad -> verification or audit squad based on the active workflow.
 
 ## Verification
 
-Check against the implementation plan, active workflow contract, and relevant engineering protocols.
+Check against the implementation plan, active workflow contract, `protocols/generated-code-linting.md`, and relevant engineering protocols.
 
 ## Stop Condition
 

package/ai-orchestration-ecosystem/tasks/verification-qa.md

@@ -30,6 +30,7 @@ Active workflow owner squad or code-audit squad when independent review is neede
 
 - `template:qa-report`.
 - Test, build, lint, typecheck, visual, accessibility, security, or manual verification evidence.
+- Generated code linting evidence from `protocols/generated-code-linting.md` when code changed.
 - Defects found and recommended fixes.
 - Go/no-go verdict with residual risks.
 

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

@@ -0,0 +1,61 @@
+# Sagaz Training Track
+
+## Purpose
+
+Provide a guided practice path for teams learning Sagaz through short exercises.
+
+Use this track after reading `ADOPTION.md`, `onboarding/README.md`, and `prompts/README.md`.
+
+## Use When
+
+- A team is adopting Sagaz for the first time.
+- A new team member needs hands-on practice.
+- A project lead wants to verify that PMs, designers, engineers, QA, and release reviewers understand Sagaz handoffs.
+- The team wants to practice permission gates before using Sagaz on production work.
+
+## Training Sequence
+
+1. `day-1-first-project-audit.md`: inspect a project without changing files.
+2. `day-2-product-to-design.md`: turn product intent into design-ready context.
+3. `day-3-design-to-implementation.md`: move from design handoff to implementation plan.
+4. `day-4-qa-release.md`: verify work and prepare release readiness.
+5. `day-5-operational-memory.md`: propose durable project/team preferences safely.
+
+## Prerequisites
+
+- Codex Desktop installed.
+- Sagaz installed and verified with `npx sagaz-ai doctor`.
+- A low-risk repository for practice.
+- Git available if the exercise includes repository status.
+- Agreement that Sagaz should not push, deploy, publish, or perform destructive operations during training.
+
+## Invocation
+
+Start every exercise with `Sagaz:` and explicitly state whether file changes are allowed.
+
+For the safest training mode, use:
+
+```text
+Sagaz: follow this training exercise. Do not change files, install dependencies, use external connectors, commit, push, deploy, or publish unless I explicitly approve.
+```
+
+## Handoff
+
+Each exercise should end with:
+
+- What Sagaz inspected.
+- What Sagaz recommended.
+- What evidence was produced.
+- What risks or assumptions remain.
+- What permission would be needed for the next step.
+- Which training exercise should come next.
+
+## Verification
+
+Training is successful when:
+
+- The team can invoke Sagaz without custom coaching.
+- Sagaz identifies workflow, squad, risk, permission level, and handoff.
+- The user understands when Sagaz may act and when it must ask.
+- No remote operation happens during training unless explicitly approved.
+- The final handoff is understandable to the next role.

package/ai-orchestration-ecosystem/training/day-1-first-project-audit.md

@@ -0,0 +1,62 @@
+# Day 1: First Project Audit
+
+## Purpose
+
+Practice using Sagaz to inspect an existing project safely before making changes.
+
+## Use When
+
+- A team member is opening Sagaz in a project for the first time.
+- The project structure, stack, risks, or test commands are not yet clear.
+- The team wants to practice inspection-only behavior.
+
+## Estimated Time
+
+20 to 30 minutes.
+
+## Prerequisites
+
+- Open a low-risk repository in Codex Desktop.
+- Confirm Sagaz is installed with `npx sagaz-ai doctor`.
+- Do not approve file changes during this exercise.
+
+## Invocation
+
+```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.
+```
+
+## What To Observe
+
+- Sagaz should inspect project structure before recommending action.
+- Sagaz should identify likely stack and tooling.
+- Sagaz should explain which workflow or squad fits.
+- Sagaz should list unknowns and risks.
+- Sagaz should ask before changing files or running high-impact commands.
+
+## Handoff
+
+Expected handoff:
+
+- Project summary.
+- Stack observations.
+- Recommended workflow.
+- Suggested next squad.
+- Risks and unknowns.
+- Permission needed for the first implementation or planning step.
+
+## Verification
+
+Success criteria:
+
+- No files were changed.
+- No dependency was installed.
+- No GitHub, deploy, or publish operation was attempted.
+- The next step is clear enough for a PM, designer, or engineer to approve.
+
+## Common Mistakes
+
+- Asking Sagaz to implement immediately.
+- Approving broad file changes before the stack is understood.
+- Treating guesses as project facts.
+- Skipping test discovery.

package/ai-orchestration-ecosystem/training/day-2-product-to-design.md

@@ -0,0 +1,76 @@
+# Day 2: Product To Design
+
+## Purpose
+
+Practice turning a product idea into a design-ready handoff.
+
+## Use When
+
+- Product intent exists but UX flow, screens, or states are unclear.
+- PMs and designers need a shared brief.
+- The team wants to practice handoff quality before Figma or implementation work.
+
+## Estimated Time
+
+30 to 45 minutes.
+
+## Prerequisites
+
+- A product idea or feature request.
+- Day 1 completed or project context already understood.
+- No approval for Figma MCP or external design writes yet.
+
+## Invocation
+
+```text
+Sagaz: act as the product team and prepare a design-ready handoff.
+
+Goal:
+-
+
+Users:
+-
+
+Constraints:
+-
+
+Definition of done:
+-
+
+Do not use Figma MCP or change files. Produce scope, acceptance criteria, risks, and the design handoff.
+```
+
+## What To Observe
+
+- Sagaz should separate goals, non-goals, assumptions, and risks.
+- Sagaz should produce testable acceptance criteria.
+- Sagaz should identify screens, states, and design questions.
+- Sagaz should recommend whether Design Studio should work next.
+
+## Handoff
+
+Expected handoff:
+
+- Problem statement.
+- Users and jobs.
+- Scope and non-goals.
+- Acceptance criteria.
+- Screen/state inventory.
+- Open questions for design.
+- Permission needed before Figma MCP or design-file changes.
+
+## Verification
+
+Success criteria:
+
+- A designer can continue without rereading the whole thread.
+- Acceptance criteria are testable.
+- Design unknowns are explicit.
+- External connector usage still requires approval.
+
+## Common Mistakes
+
+- Skipping non-goals.
+- Asking for visual output before user flows are clear.
+- Omitting empty, loading, error, and success states.
+- Treating design assumptions as approved requirements.

package/ai-orchestration-ecosystem/training/day-3-design-to-implementation.md

@@ -0,0 +1,73 @@
+# Day 3: Design To Implementation
+
+## Purpose
+
+Practice converting a design handoff into an implementation plan.
+
+## Use When
+
+- A UX flow, UI mockup, or design brief exists.
+- Engineering needs a safe implementation path.
+- The team wants to confirm scope, files, tests, and risks before code changes.
+
+## Estimated Time
+
+30 to 45 minutes.
+
+## Prerequisites
+
+- Day 2 completed or an equivalent design handoff.
+- A repository open in Codex Desktop.
+- Agreement on whether file changes are allowed.
+
+## Invocation
+
+```text
+Sagaz: convert this design/product handoff into an implementation plan.
+
+Handoff:
+-
+
+Rules:
+- inspect the project first
+- use existing patterns
+- keep the diff focused
+- identify tests before coding
+
+Do not change files until you propose the plan and ask for approval.
+```
+
+## What To Observe
+
+- Sagaz should inspect existing code patterns.
+- Sagaz should identify likely files or modules.
+- Sagaz should call out accessibility, responsive, and state requirements.
+- Sagaz should produce a focused plan instead of broad refactors.
+- Sagaz should name the permission level for implementation.
+
+## Handoff
+
+Expected handoff:
+
+- Implementation plan.
+- Files or areas likely involved.
+- Test plan.
+- Risks and assumptions.
+- Permission required to edit files.
+- Recommended next engineering action.
+
+## Verification
+
+Success criteria:
+
+- Plan is scoped.
+- Tests are proportional to risk.
+- Existing patterns are respected.
+- The team knows exactly what approval would allow Sagaz to do next.
+
+## Common Mistakes
+
+- Implementing without inspecting the codebase.
+- Changing design scope during engineering.
+- Refactoring unrelated areas.
+- Forgetting responsive or accessibility constraints.