sagaz-ai 0.2.0 → 0.3.0

package/ai-orchestration-ecosystem/examples/web-saas-vercel.md

@@ -0,0 +1,114 @@
+# Example: Web SaaS On Vercel
+
+## User Prompt
+
+```text
+Sagaz: create a premium appointment scheduling SaaS for small clinics.
+
+Requirements:
+- user login
+- calendar
+- admin dashboard
+- payments later
+- premium responsive design
+- production-ready deployment on Vercel
+```
+
+## Selected Workflow
+
+`workflows/greenfield-web-app.md`
+
+## Required Squads
+
+- `squads/research-to-spec.md`
+- `squads/product-factory.md`
+- `squads/design-studio.md`
+- `squads/production-critical.md`
+- `squads/github-ops.md`
+
+## First Actions
+
+1. Confirm target users, appointment model, clinic roles, calendar rules, and payment timing.
+2. Create or update run state from `templates/run-state.md`.
+3. Use `tasks/intake-brief.md`.
+4. Use `tasks/product-requirements.md`.
+5. Use `tasks/stack-recommendation.md`.
+6. Ask permission before moving from planning into implementation.
+
+## Stack Recommendation
+
+Default recommendation:
+
+- Next.js.
+- TypeScript.
+- Vercel.
+- Supabase for auth, database, and storage.
+- shadcn/ui when the project uses React and wants a polished, composable UI baseline.
+- Playwright for end-to-end checks.
+- GitHub Actions for package and deployment checks.
+
+Decision points:
+
+- Use Stripe only when payments are in scope.
+- Use a dedicated calendar integration only when external calendar sync is required.
+- Use PostgreSQL migrations and RLS review before production.
+
+## Handoff Sequence
+
+| Phase | From | To | Evidence |
+| --- | --- | --- | --- |
+| Intake | research-to-spec | product-factory | user roles, constraints, success criteria |
+| Requirements | product-factory | design-studio | product spec, core flows, acceptance criteria |
+| Design | design-studio | production-critical | design system, responsive views, accessibility expectations |
+| Build | production-critical | production-critical | implementation plan, tests, env vars |
+| Release | production-critical | github-ops | QA report, production checklist, residual risks |
+
+## Expected Artifacts
+
+- `templates/product-spec.md`.
+- `templates/stack-recommendation.md`.
+- `templates/design-system-spec.md`.
+- `templates/implementation-plan.md`.
+- `templates/qa-report.md`.
+- `templates/future-change-guide.md`.
+- `templates/final-handoff.md`.
+
+## Verification Plan
+
+- Install/build check.
+- Unit or integration tests for scheduling logic.
+- Playwright smoke flow for signup, booking, admin review.
+- Accessibility pass on core views.
+- Responsive visual QA on mobile and desktop.
+- Security review for auth, roles, RLS, env vars, and secrets.
+- Production readiness check before Vercel release.
+
+## GitHub Actions To Suggest
+
+- Commit after implementation evidence exists.
+- Push after local checks pass.
+- Pull request if collaborating.
+- Release notes only after production readiness is complete.
+
+## Deployment Path
+
+1. Prepare Vercel project.
+2. Configure env vars.
+3. Configure Supabase project and migrations.
+4. Deploy preview.
+5. Run smoke tests against preview.
+6. Promote to production after approval.
+
+## Final Handoff Shape
+
+```md
+Current team:
+What was completed:
+Evidence/artifacts:
+Checks run:
+Deployment status:
+Risks or pending items:
+Next recommended action:
+Permission needed:
+```
+

package/ai-orchestration-ecosystem/governance/capabilities-matrix.md

@@ -0,0 +1,169 @@
+# Capabilities Matrix
+
+## Purpose
+
+Clarify what Sagaz does, what it does not try to do, and how it compares with external orchestration systems and agent frameworks.
+
+Use this matrix when deciding whether Sagaz needs a new capability, whether a project should use Sagaz alone, or whether Sagaz should coordinate with another framework.
+
+## Scope
+
+Sagaz is a Codex Desktop operating system for software delivery. It is not a standalone agent runtime, model gateway, hosted automation platform, or Python/TypeScript agent SDK.
+
+External systems in this matrix are grouped by practical role:
+
+- Agent frameworks: CrewAI, AutoGen, LangChain, LangGraph.
+- Enterprise orchestration platforms: AIOX, Synkra, and similar systems when the user provides internal context.
+- Adjacent infrastructure: MCP servers, GitHub, Vercel, Figma, Canva, Supabase, Firebase, and observability tools.
+
+## Source Notes
+
+- CrewAI publicly positions itself around collaborative AI agents, crews, flows, guardrails, memory, knowledge, observability, deployment, triggers, and enterprise controls.
+- AutoGen publicly positions itself as a framework for building AI agents and applications, including conversational single and multi-agent applications, event-driven multi-agent systems, extensions, MCP support, Docker code execution, distributed runtimes, and Studio.
+- LangChain publicly positions its platform around agent engineering, LangSmith observability/evaluation/prompt engineering/deployment, and LangGraph for low-level orchestration, memory, and human-in-the-loop support.
+- AIOX, Synkra, and similar systems should be compared from user-provided documentation or internal knowledge. Do not claim exact feature parity without a source.
+
+## High-Level Positioning
+
+| Capability Area | Sagaz | CrewAI | AutoGen | LangChain/LangGraph | AIOX/Synkra-Like Systems |
+| --- | --- | --- | --- | --- | --- |
+| Primary role | Codex Desktop delivery operating system | Agent/crew automation framework and platform | Multi-agent application framework | Agent engineering platform and graph runtime | Enterprise orchestration layer |
+| Runtime | Codex Desktop plus local Markdown rules | Python/package/platform runtime | Python/.NET ecosystem and Studio | Python/TypeScript plus hosted LangSmith/LangGraph options | Usually hosted, server, or enterprise runtime |
+| Best use | Software projects with planning, design, build, QA, GitHub, release | Building autonomous agents, crews, flows, automations | Building programmable multi-agent apps and experiments | Building agentic apps, graph workflows, observability, evaluation | Broad enterprise coordination, policy, governance, routing |
+| Requires coding framework | No, uses Codex and repo files | Yes for framework use | Yes for framework use | Yes for framework use | Usually yes or platform configuration |
+| Standalone agent runtime | No | Yes | Yes | Yes | Usually yes |
+| Codex Desktop integration | Native goal | Not primary | Not primary | Not primary | Not primary unless integrated |
+
+## Detailed Capability Matrix
+
+| Capability | Sagaz Status | Notes |
+| --- | --- | --- |
+| Named squads and agents | Strong | Markdown-defined squads and roles guide Codex behavior. |
+| Formal workflows | Strong | Workflow contracts, phases, gates, and handoffs are validated. |
+| Formal task contracts | Strong | Tasks define inputs, outputs, evidence, verification, and stop conditions. |
+| Durable run state | Strong | Markdown run state supports resume, skipped phases, blockers, and handoffs. |
+| Human approval gates | Strong | Built into handoffs, GitHub operations, release gates, and dangerous actions. |
+| GitHub release operations | Strong | Guided commit, push, tag, release, and npm flow with explicit permission. |
+| Package/release governance | Strong | Release/versioning gate, changelog, release notes, Actions, and npm packaging. |
+| Installed skill synchronization | Strong | `sync`, `doctor`, and protocol prevent installed skill drift. |
+| Design quality governance | Strong | UX/UI, Figma MCP guidance, responsive/accessibility/visual QA rules. |
+| Stack advisory | Strong | Stack presets and recommendation criteria guide web/mobile/backend choices. |
+| Evaluation suite | Medium-strong | Scenario contracts exist; automated agent-behavior execution is not yet implemented. |
+| Observability | Medium | Agent observability exists as a protocol; stronger structured traces remain future work. |
+| Tool and MCP policy | Medium | Tool registry exists; connector-specific policy remains future work. |
+| Multi-agent runtime execution | Limited | Sagaz does not spawn independent runtime agents; Codex executes under Sagaz rules. |
+| Distributed workers | Not a goal | Use AutoGen, LangGraph, CrewAI, or another runtime if needed. |
+| Model routing engine | Protocol-level only | Sagaz can guide model selection but does not provide live routing infrastructure. |
+| Hosted dashboard | Not a goal | Sagaz is local Markdown plus Codex Desktop. |
+| Visual workflow builder | Not a goal | Use external platforms if visual orchestration is required. |
+| Autonomous background jobs | Not a goal | Sagaz works in active Codex sessions unless paired with external automation. |
+| Enterprise RBAC | Not a goal | Use GitHub/org/platform controls or external enterprise orchestration. |
+| Provider gateway | Not a goal | Use LangSmith gateway, provider SDKs, or enterprise infra if needed. |
+| Vector/RAG runtime | Not a goal | Sagaz can recommend RAG architecture but does not host it. |
+
+## Sagaz vs CrewAI
+
+Use Sagaz when the goal is to guide Codex Desktop through software delivery with specs, implementation, QA, handoffs, GitHub, and release evidence.
+
+Use CrewAI when the goal is to build autonomous agent crews and flows as an application/runtime outside Codex Desktop.
+
+Complementary pattern:
+
+- Sagaz plans the product, architecture, tests, release, and governance.
+- CrewAI implements runtime automations when the product itself needs agent crews.
+
+Sagaz should not claim CrewAI-style runtime parity. CrewAI has a runtime and platform orientation; Sagaz has a Codex Desktop operating-system orientation.
+
+## Sagaz vs AutoGen
+
+Use Sagaz when the goal is delivery orchestration for a repository.
+
+Use AutoGen when the goal is to program multi-agent applications, conversational agents, distributed runtimes, MCP-backed agents, Docker code execution, or Studio-based agent prototyping.
+
+Complementary pattern:
+
+- Sagaz specifies and validates the software project.
+- AutoGen becomes an implementation dependency if the product needs programmable multi-agent behavior.
+
+Sagaz should not claim AutoGen-style distributed or event-driven agent runtime parity.
+
+## Sagaz vs LangChain And LangGraph
+
+Use Sagaz when the goal is to coordinate Codex work across planning, build, verification, and release.
+
+Use LangChain or LangGraph when the product needs an agentic application framework, graph-based execution, memory, human-in-the-loop runtime flows, tracing, evaluation, deployment, or LangSmith operations.
+
+Complementary pattern:
+
+- Sagaz decides whether an app needs LangChain/LangGraph.
+- LangChain/LangGraph implement runtime application behavior.
+- LangSmith can provide production tracing/evaluation that Sagaz records as release evidence.
+
+Sagaz should not claim LangGraph-style graph runtime or LangSmith-style hosted observability parity.
+
+## Sagaz vs AIOX, Synkra, And Similar Systems
+
+Use this comparison only when the user provides reliable details about those systems.
+
+Typical external orchestration platforms may include:
+
+- Runtime execution.
+- Agent registries.
+- Model routing.
+- Dashboards.
+- Enterprise permissions.
+- Background jobs.
+- Cross-framework orchestration.
+- Monitoring.
+- Hosted workflow state.
+
+Sagaz currently covers the delivery governance side strongly but does not aim to replace hosted enterprise orchestration runtimes.
+
+Sagaz can become more similar in selected areas by adding:
+
+- Stronger execution observability.
+- Connector/MCP policy.
+- Permission contracts.
+- Stack playbooks.
+- More complete examples.
+- Optional external automation hooks.
+
+## Decision Guide
+
+| Need | Recommended Path |
+| --- | --- |
+| Build a web/mobile product in Codex Desktop | Sagaz |
+| Refactor or fix a codebase safely in Codex Desktop | Sagaz |
+| Add governance, gates, release discipline, handoffs | Sagaz |
+| Build runtime multi-agent app behavior | CrewAI, AutoGen, LangGraph, or similar |
+| Build graph-based long-running agent workflows | LangGraph |
+| Build conversational multi-agent applications | AutoGen |
+| Build crew/flow business automations | CrewAI |
+| Need hosted tracing/evaluation/deployment for agents | LangSmith/LangGraph Platform or similar |
+| Need enterprise RBAC, dashboards, background jobs | External orchestration platform |
+| Need Figma app-like mockups and design handoff | Sagaz plus Figma MCP |
+
+## Gaps To Consider
+
+Sagaz does not need a standalone CLI runtime if it remains Codex Desktop-focused.
+
+The next useful additions are:
+
+- Permission contract.
+- Stack playbooks.
+- Stronger execution observability.
+- MCP and connector policy.
+
+## Output
+
+```md
+Capability question:
+Sagaz fit:
+External system fit:
+Recommended path:
+Reason:
+Missing capability:
+Next action:
+Permission needed:
+```
+

package/ai-orchestration-ecosystem/governance/operations-runbook.md

@@ -0,0 +1,236 @@
+# Sagaz Operations Runbook
+
+## Purpose
+
+Provide the day-to-day operating procedure for using Sagaz inside Codex Desktop.
+
+Use this runbook when starting work, resuming work, approving handoffs, verifying delivery, syncing the installed skill, preparing releases, publishing packages, or recovering from common errors.
+
+Apply `protocols/permission-contract.md` before actions that change local state, remote state, accounts, deployments, packages, credentials, or GitHub history.
+
+Apply `protocols/mcp-connector-policy.md` before using MCPs or external connectors such as Figma, GitHub, Canva, Browser, Vercel, Supabase, Firebase, npm, or observability tools.
+
+## Daily Start
+
+1. Confirm the workspace is the intended project or the Sagaz repository.
+2. If using Sagaz itself, read `ai-orchestration-ecosystem/quickstart.md`.
+3. If navigation is needed, read `ai-orchestration-ecosystem/INDEX.md`.
+4. Choose the smallest sufficient workflow, squad, task, or protocol.
+5. For medium or large work, create or update `templates/run-state.md`.
+6. For multi-phase, production, release, deployment, package, or high-risk work, create or update `templates/execution-trace.md`.
+7. State the current objective, current squad, next action, and permission needed.
+
+## Start A New Project
+
+Use this sequence:
+
+1. Intake: clarify goal, platform, audience, constraints, budget, timeline, and risk.
+2. Workflow selection: choose the named workflow that matches the project.
+3. Task selection: map the first phase to a formal task.
+4. Stack recommendation: use stack presets only as starting points.
+5. Planning: produce product, technical, design, testing, and release expectations.
+6. Handoff: ask permission before moving into implementation.
+
+Standard start prompt:
+
+```text
+Sagaz: use the appropriate workflow for this project. Maintain run state, handoffs, and verification evidence.
+```
+
+## Resume Work
+
+When resuming after a pause, context compaction, or a new Codex Desktop thread:
+
+1. Read the newest user request.
+2. Read `templates/run-state.md` if it exists.
+3. Check `git status --short --branch`.
+4. Identify the current workflow, phase, squad, task, blockers, and next action.
+5. Continue from the newest approved point instead of restarting the whole run.
+6. Update run state if the work is medium, large, production, or multi-phase.
+
+Resume output:
+
+```md
+Current workflow:
+Current phase:
+Current squad:
+Current task:
+Completed:
+Evidence:
+Blockers:
+Next action:
+Permission needed:
+```
+
+## Handoff Procedure
+
+Use handoffs whenever work moves between squads or phases.
+
+Required handoff:
+
+```md
+Current team:
+What was completed:
+Evidence/artifacts:
+Risks or pending items:
+Next team:
+What it will do:
+Why now:
+May I perform the handoff?
+```
+
+Do not proceed to a new phase when the handoff requires user approval and approval has not been given.
+
+## Verification Procedure
+
+Verification must match risk.
+
+Minimum Sagaz repository checks:
+
+```powershell
+npm test
+npm run doctor
+npm pack --dry-run
+```
+
+For product work, choose checks from the active project:
+
+- Build.
+- Lint.
+- Unit tests.
+- Integration tests.
+- End-to-end tests.
+- Accessibility checks.
+- Visual QA.
+- Security checks.
+- Deployment preview.
+- Manual smoke test.
+
+Never declare done without saying which checks were run and what risk remains.
+
+## Sync Installed Skill
+
+When Sagaz rules, activation, release behavior, or `codex-skill/sagaz/SKILL.md` change, sync the installed Codex Desktop skill.
+
+Windows PowerShell and macOS Terminal:
+
+```bash
+npx sagaz-ai sync
+npx sagaz-ai doctor
+```
+
+Then open a new Codex Desktop thread so the updated skill can be discovered.
+
+If `doctor` reports a stale installed skill, run:
+
+```bash
+npx sagaz-ai install --force
+```
+
+## Release Procedure
+
+Before version bumps, tags, GitHub releases, or npm publishes:
+
+1. Apply `protocols/release-versioning-gate.md`.
+2. Decide patch, minor, or major.
+3. Update `CHANGELOG.md` and `RELEASE_NOTES.md`.
+4. Run `npm test`.
+5. Run `npm run doctor`.
+6. Run `npm pack --dry-run`.
+7. Confirm `git status --short --branch`.
+8. Ask for approval before commit, tag, push, GitHub release, or npm publish.
+
+Release output:
+
+```md
+Version:
+Release type:
+Checks:
+Git status:
+Tag:
+GitHub release:
+npm publish:
+Residual risk:
+```
+
+## GitHub Procedure
+
+Before GitHub operations:
+
+1. Inspect `git status --short --branch`.
+2. Avoid including unrelated user changes.
+3. Run required checks.
+4. Apply `protocols/permission-contract.md`.
+5. Ask approval before commit, push, tag, release, issue, or pull request.
+6. Report commit hash, branch, push status, and release URL when created.
+
+## Common Errors
+
+### npm E401 Unauthorized
+
+Meaning: npm is not authenticated or the token is invalid.
+
+Action:
+
+```powershell
+npm logout
+npm login
+npm whoami
+```
+
+### npm ENOENT package.json
+
+Meaning: the command was run outside the package folder.
+
+Action:
+
+```powershell
+cd C:\Users\tscab\Documents\Projects\Sagaz
+dir package.json
+```
+
+### npm Cannot Publish Over Previous Version
+
+Meaning: that version is already published.
+
+Action:
+
+```powershell
+npm view sagaz-ai version
+```
+
+If the published version is correct, stop. If another release is needed, bump the version first.
+
+### Stale Installed Skill
+
+Meaning: the installed Codex Desktop skill differs from the repository skill.
+
+Action:
+
+```bash
+npx sagaz-ai sync
+npx sagaz-ai doctor
+```
+
+## Stop Conditions
+
+Stop and ask the user when:
+
+- A destructive action is needed.
+- Remote publication is needed.
+- Credentials or account permissions are missing.
+- Git status contains unrelated changes.
+- Required checks fail.
+- The next action changes cost, account state, deployment, package publication, or release state.
+
+## Output
+
+```md
+Runbook step:
+Current state:
+Action taken:
+Evidence:
+Risk:
+Next action:
+Permission needed:
+```

package/ai-orchestration-ecosystem/manifest.json

@@ -80,6 +80,8 @@
       "protocols/installed-skill-sync.md",
       "protocols/memory.md",
       "protocols/model-routing.md",
+      "protocols/mcp-connector-policy.md",
+      "protocols/permission-contract.md",
       "protocols/performance-budgets.md",
       "protocols/post-delivery-monitoring.md",
       "protocols/production-readiness.md",
@@ -103,6 +105,14 @@
       "stack-presets/static-site.md",
       "stack-presets/supabase.md"
     ],
+    "stack_playbooks": [
+      "stack-playbooks/README.md",
+      "stack-playbooks/expo-eas.md",
+      "stack-playbooks/firebase.md",
+      "stack-playbooks/nextjs-vercel-supabase.md",
+      "stack-playbooks/node-api.md",
+      "stack-playbooks/react-vite-static.md"
+    ],
     "templates": [
       "templates/changelog.md",
       "templates/design-system-spec.md",
@@ -110,6 +120,7 @@
       "templates/future-change-guide.md",
       "templates/github-actions-checklist.md",
       "templates/implementation-plan.md",
+      "templates/execution-trace.md",
       "templates/mobile-release-checklist.md",
       "templates/product-spec.md",
       "templates/qa-report.md",
@@ -134,7 +145,9 @@
       "engineering/software-engineering-deep-guide.md"
     ],
     "governance": [
+      "governance/capabilities-matrix.md",
       "governance/ecosystem-maintenance.md",
+      "governance/operations-runbook.md",
       "governance/package-release-policy.md",
       "governance/quality-policy.md",
       "governance/security-policy.md",
@@ -144,7 +157,11 @@
       "evals/sagaz-evaluation-suite.md"
     ],
     "examples": [
-      "examples/README.md"
+      "examples/README.md",
+      "examples/brownfield-refactor.md",
+      "examples/bugfix-production-release.md",
+      "examples/mobile-habit-tracker.md",
+      "examples/web-saas-vercel.md"
     ],
     "docs": [
       "ACTIVATE.md",