sagaz-ai 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,122 @@
 # Changelog
 
+## [0.3.1] - 2026-06-11
+
+### Release Type
+
+Patch
+
+### Added
+
+- Sagaz adoption guide for first use in another project, team onboarding, invocation prompts, cross-platform notes, permission model, and evidence expectations.
+
+### Changed
+
+- README, ecosystem README, INDEX, manifest, and package verifier now register the adoption guide as an official ecosystem document.
+
+### Fixed
+
+- None.
+
+### Removed
+
+- None.
+
+### Security
+
+- No security changes.
+
+### Compatibility
+
+- Windows: supported through Codex Desktop.
+- macOS: supported through Codex Desktop.
+- Node.js: package baseline remains `>=22.14`; Node.js 24 is preferred for new installs and CI.
+- Codex Desktop: Sagaz remains a Codex Desktop orchestration skill, not a standalone terminal agent runtime.
+
+### Migration Notes
+
+- Existing users should run `npx sagaz-ai@0.3.1 sync` or `npx sagaz-ai sync` to refresh the installed Codex Desktop skill.
+- Open a new Codex Desktop thread after syncing so the updated skill can be discovered.
+
+### Verification
+
+- npm test: passed locally on Windows.
+- npm run doctor: passed locally on Windows with `Synchronized with source: yes`.
+- npm pack --dry-run: passed locally on Windows after allowing npm cache access outside the sandbox.
+- Windows: prepared from a Windows Codex Desktop workspace.
+- macOS: package checks remain covered by GitHub Actions.
+- Codex Desktop: skill sync remains required after install or upgrade.
+
+### Release Evidence
+
+- Commit: pending.
+- Tag: pending.
+- GitHub release: pending.
+- npm package: pending.
+
+## [0.3.0] - 2026-06-11
+
+### Release Type
+
+Minor
+
+### Added
+
+- Operations runbook for daily starts, project starts, resumes, handoffs, verification, releases, GitHub operations, and stop conditions.
+- Complete examples library covering web SaaS on Vercel, mobile habit tracking, production bugfix releases, and brownfield refactors.
+- Capabilities matrix comparing Sagaz with common orchestration systems and identifying what Sagaz now covers or intentionally defers.
+- Formal permission contract with approval levels for local edits, installs, network access, GitHub operations, releases, secrets, and destructive actions.
+- Stack playbooks for Next.js/Vercel/Supabase, React/Vite/static hosting, Expo/EAS, Node APIs, and Firebase.
+- Execution trace template and stronger observability contract for commands, decisions, failures, handoffs, and release evidence.
+- MCP connector policy for Figma, GitHub, browser automation, deployment providers, databases, Canva, npm registries, observability, and AI providers.
+
+### Changed
+
+- `npm test` now validates stack playbooks, permission policy, execution trace requirements, observability rules, and MCP connector policy coverage.
+- README, INDEX, manifest, tool registry, run-state template, and Sagaz skill instructions now expose the new governance and connector contracts.
+- Release governance now requires stronger evidence around permissions, connector usage, workflow traceability, and stack-specific verification.
+
+### Fixed
+
+- Filled remaining non-CLI governance gaps identified after the 0.2.0 release.
+- Reduced ambiguity around cross-platform execution on Windows and macOS inside Codex Desktop.
+
+### Removed
+
+- None.
+
+### Security
+
+- Added explicit permission levels for secrets, destructive actions, external publishing, GitHub operations, package registries, and MCP connectors.
+
+### Compatibility
+
+- Windows: supported through Codex Desktop and locally verified on Windows.
+- macOS: supported through Codex Desktop and covered by GitHub Actions package checks.
+- Node.js: package baseline remains `>=22.14`; Node.js 24 is preferred for new installs and CI.
+- Codex Desktop: Sagaz remains a Codex Desktop orchestration skill, not a standalone terminal agent runtime.
+
+### Migration Notes
+
+- Existing users should run `npx sagaz-ai@0.3.0 sync` or `npx sagaz-ai sync` to refresh the installed Codex Desktop skill.
+- Open a new Codex Desktop thread after syncing so the updated skill can be discovered.
+
+### Verification
+
+- npm test: passed locally on Windows.
+- npm run doctor: passed locally on Windows with `Synchronized with source: yes`.
+- npm pack --dry-run: passed locally on Windows after allowing npm cache access outside the sandbox.
+- Windows: prepared and verified from a Windows Codex Desktop workspace.
+- macOS: package checks remain covered by GitHub Actions.
+- Codex Desktop: skill sync remains required after install or upgrade.
+
+### Release Evidence
+
+- Commit: pending.
+- Tag: pending.
+- GitHub release: pending.
+- npm package: pending.
+
 ## [0.2.0] - 2026-06-08
 
 ### Release Type
@@ -64,4 +181,3 @@ Minor
 - Tag: pending.
 - GitHub release: pending.
 - npm package: pending.
-

package/README.md

@@ -168,6 +168,14 @@ Then open a new Codex Desktop thread and run:
 Sagaz: explain the available workflows.
 ```
 
+For the first real use in another project, start with:
+
+```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.
+```
+
+The detailed adoption guide lives at `ai-orchestration-ecosystem/ADOPTION.md`.
+
 ### Manual Installation
 
 #### 1. Clone Or Download The Repository

package/RELEASE_NOTES.md

@@ -2,9 +2,9 @@
 
 ## Release
 
-Version: 0.2.0
-Date: 2026-06-08
-Release type: Minor
+Version: 0.3.1
+Date: 2026-06-11
+Release type: Patch
 GitHub commit: pending
 Git tag: pending
 GitHub release: pending
@@ -12,38 +12,32 @@ npm package: pending
 
 ## Summary
 
-Sagaz 0.2.0 strengthens the orchestration ecosystem around formal workflows, handoffs, task contracts, registry validation, release gates, GitHub Actions enforcement, evaluation coverage, and installed skill synchronization.
+Sagaz 0.3.1 adds the official adoption guide for using Sagaz in another project after installation. It documents the first-use flow, team operating model, invocation prompts, Windows/macOS notes, permission expectations, and evidence artifacts.
 
 ## Audience Impact
 
-- New users: clearer README, requirements, installation guidance, and sync instructions.
-- Existing users: should refresh the installed skill with `npx sagaz-ai sync`.
-- Maintainers: stronger `npm test` coverage catches manifest, dependency graph, release, workflow, task, and evaluation drift.
-- Design team: Figma MCP and app-like mockup guidance are now part of Sagaz operating rules.
-- Engineering team: workflows now behave more like formal contracts with gates, state, handoffs, and evidence.
+- New users: clearer first real step after installing Sagaz.
+- Existing users: can sync the installed skill and follow the adoption guide from a fresh Codex Desktop thread.
+- Teams: get a practical onboarding path before applying Sagaz to production work.
+- Maintainers: package validation now tracks the adoption guide in the ecosystem manifest.
 
 ## What Changed
 
-- Added `manifest.json` as an internal component registry.
-- Added dependency graph validation.
-- Added component governance.
-- Added release/versioning gate.
-- Added GitHub Actions package checks across Linux, Windows, and macOS.
-- Added formal changelog and release notes templates.
-- Added installed skill sync protocol and CLI command.
-- Strengthened workflow, task, run-state, and evaluation contracts.
+- Added `ai-orchestration-ecosystem/ADOPTION.md`.
+- Linked the adoption guide from the root README, ecosystem README, and ecosystem INDEX.
+- Registered the adoption guide in `manifest.json`.
+- Updated package verification so the docs group validates the new guide.
 
 ## Why It Matters
 
-Sagaz is now harder to accidentally drift, release, or publish in an inconsistent state. The system can validate its own structure, release gates, installed skill sync, and GitHub automation before maintainers ship changes.
+After `0.3.0`, Sagaz had strong governance but needed a direct bridge between installation and first use in a real project. This patch gives teams a safe starting prompt, explains what Sagaz should inspect first, and reinforces permission gates before risky actions.
 
 ## Compatibility
 
-- Windows: supported and locally verified.
-- macOS: supported through Codex Desktop and GitHub Actions runner validation.
+- Windows: supported through Codex Desktop.
+- macOS: supported through Codex Desktop.
 - Node.js: `>=22.14` remains the package minimum; Node.js 24 is preferred for new installs and CI.
 - Codex Desktop: required.
-- GitHub Actions: package checks run on Ubuntu, Windows, and macOS.
 - npm package: still an installer/distribution package, not a standalone Sagaz runtime.
 
 ## Migration Notes
@@ -51,7 +45,7 @@ Sagaz is now harder to accidentally drift, release, or publish in an inconsisten
 Run:
 
 ```bash
-npx sagaz-ai sync
+npx sagaz-ai@0.3.1 sync
 npx sagaz-ai doctor
 ```
 
@@ -59,16 +53,15 @@ Then open a new Codex Desktop thread so Sagaz is rediscovered.
 
 ## Verification
 
-- `npm test`: passed locally.
-- `npm run doctor`: passed locally with installed skill synchronization confirmed.
-- `npm pack --dry-run`: passed locally after npm cache access was allowed outside the sandbox.
-- Evaluation scenarios: enforced by the strengthened Sagaz evaluation suite.
-- Manual checks: Git status reviewed before release preparation.
+- `npm test`: passed locally on Windows.
+- `npm run doctor`: passed locally on Windows with installed skill synchronization confirmed.
+- `npm pack --dry-run`: passed locally on Windows after npm cache access was allowed outside the sandbox.
+- Manual checks: adoption guide linked from README, INDEX, and manifest.
 
 ## Known Limitations
 
-- GitHub release and npm publishing remain manual approval steps.
-- The package still installs Sagaz for Codex Desktop; it is not a standalone terminal orchestration runtime.
+- Sagaz still intentionally skips a standalone CLI runtime; Codex Desktop remains the execution surface.
+- Connector behavior depends on each external MCP/app authorization and platform availability.
 
 ## Rollback Plan
 
@@ -79,6 +72,5 @@ Then open a new Codex Desktop thread so Sagaz is rediscovered.
 ## Release Decision
 
 Approved by: Thiago Cabral
-Approval date: 2026-06-08
+Approval date: 2026-06-11
 Residual risk: GitHub Actions and npm publishing still need remote execution after push.
-

package/ai-orchestration-ecosystem/ADOPTION.md

@@ -0,0 +1,178 @@
+# Sagaz Adoption Guide
+
+Use this guide when starting Sagaz in another project or onboarding a team to Sagaz inside Codex Desktop.
+
+## Purpose
+
+This guide gives a practical first-use path for teams that want Sagaz to orchestrate product, design, implementation, verification, GitHub operations, and release readiness in an existing or new project.
+
+It assumes Sagaz is already installed with `npx sagaz-ai install` or `npx sagaz-ai sync`.
+
+## Requirements
+
+- Codex Desktop on Windows or macOS.
+- Node.js `22.14+`; Node.js 24 LTS is preferred.
+- npm available in the terminal.
+- Git installed when the project is version controlled.
+- GitHub CLI (`gh`) when Sagaz should create branches, pull requests, issues, releases, or inspect checks.
+- Project-specific tools already installed or approved for installation, such as `pnpm`, `yarn`, `bun`, Expo/EAS, Android Studio, Xcode, Supabase CLI, Firebase CLI, Vercel CLI, or test browsers.
+
+Before starting a real project, run:
+
+```bash
+npx sagaz-ai doctor
+```
+
+If the installed skill is out of sync, run:
+
+```bash
+npx sagaz-ai sync
+```
+
+Then open a new Codex Desktop thread so the refreshed skill is discovered.
+
+## First Use In Another Project
+
+1. Open the target project folder in Codex Desktop.
+2. Start a new thread after installing or syncing Sagaz.
+3. Invoke Sagaz with a direct goal and any known constraints.
+4. Let Sagaz inspect the project before making changes.
+5. Approve each major handoff, external operation, dependency install, GitHub operation, deployment, package publish, or destructive action.
+6. Keep the final handoff and run-state artifacts inside the project when the work is meaningful or long-lived.
+
+## Invocation Pattern
+
+Use `Sagaz:` at the beginning of the message.
+
+For a new product:
+
+```text
+Sagaz: create a production-ready web SaaS for appointment scheduling.
+
+Requirements:
+- user login
+- calendar scheduling
+- admin dashboard
+- premium but practical UI
+- deployment on Vercel
+- GitHub release flow
+```
+
+For an existing project:
+
+```text
+Sagaz: inspect this project and prepare a safe implementation plan before changing code.
+
+Goal:
+- add subscription billing
+- preserve the current UX
+- use the existing stack when reasonable
+- include tests and deployment notes
+```
+
+For a bug:
+
+```text
+Sagaz: diagnose and fix the production checkout failure.
+
+Rules:
+- identify likely root cause first
+- make the smallest safe fix
+- run focused tests
+- prepare a release handoff
+```
+
+For design work with Figma MCP:
+
+```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
+- component states
+- interaction notes
+- visual QA checklist
+```
+
+## Recommended First Response From Sagaz
+
+Sagaz should respond with:
+
+- The selected workflow.
+- The selected squad or agents.
+- The assumptions it is making.
+- The files, commands, or connectors it needs to inspect.
+- The permission level required for the next step.
+- The expected first handoff artifact.
+
+Sagaz should avoid starting large implementation work before it understands the project structure, stack, risks, and definition of done.
+
+## Team Operating Model
+
+Use this rhythm for team adoption:
+
+1. Product confirms objective, users, constraints, and definition of done.
+2. Technology confirms stack, architecture, dependencies, and operating costs.
+3. Design confirms UX, UI system, accessibility, responsiveness, and visual QA expectations.
+4. Engineering implements in small verifiable steps.
+5. QA verifies behavior, regressions, accessibility, build, and deployment readiness.
+6. GitHub Ops prepares commit, branch, pull request, checks, release notes, tag, and release when approved.
+7. The final handoff records evidence, residual risk, rollback plan, and next recommended work.
+
+## Cross-Platform Notes
+
+Sagaz should treat Windows and macOS as first-class Codex Desktop environments.
+
+- Prefer commands that work in the user's current shell.
+- Use PowerShell syntax on Windows and POSIX shell syntax on macOS.
+- Record when a command or dependency is platform-specific.
+- Verify path examples before presenting them.
+- Do not assume Linux-only tooling unless the project or CI requires it.
+
+## Permission Model
+
+Sagaz follows `protocols/permission-contract.md`.
+
+Low-risk inspection can usually proceed directly. These actions require explicit approval:
+
+- Installing dependencies.
+- Writing or deleting files when implementation has not been clearly authorized.
+- Running commands that access networked registries or external services.
+- Creating, pushing, tagging, or releasing in GitHub.
+- Deploying to hosting providers.
+- Publishing packages.
+- Handling secrets, credentials, production data, billing, or destructive operations.
+
+## Evidence To Keep
+
+For serious work, Sagaz should maintain or produce:
+
+- `templates/run-state.md`
+- `templates/execution-trace.md`
+- `templates/implementation-plan.md`
+- `templates/qa-report.md`
+- `templates/final-handoff.md`
+- `templates/future-change-guide.md`
+- `templates/release-notes.md` when release work is involved.
+
+## Good First Team Exercise
+
+Use a low-risk existing repository and ask:
+
+```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.
+```
+
+This verifies that the team understands Sagaz handoffs, permission gates, stack reasoning, and evidence before using it on production work.
+
+## Success Criteria
+
+Sagaz adoption is working when:
+
+- The team can invoke Sagaz consistently in new and existing projects.
+- Sagaz chooses workflows and stack playbooks without bloating context.
+- The team sees clear permission prompts before risky actions.
+- Handoffs explain what changed, what was verified, and what remains risky.
+- GitHub, design, deployment, and package operations happen only after approval.
+- Windows and macOS users can follow the same operating model with platform-appropriate commands.

package/ai-orchestration-ecosystem/INDEX.md

@@ -3,6 +3,7 @@
 ## Quick Entry
 
 - `ACTIVATE.md`: ready-to-use activation prompts.
+- `ADOPTION.md`: first-use guide for adopting Sagaz in another project or team.
 - `quickstart.md`: minimum operating rules.
 - `README.md`: ecosystem overview.
 - `manifest.json`: internal component registry for validation and navigation.
@@ -71,6 +72,8 @@ See `protocols/` for quality gates, testing matrix, stack selection, design qual
 - `protocols/installed-skill-sync.md`
 - `protocols/memory.md`
 - `protocols/model-routing.md`
+- `protocols/mcp-connector-policy.md`
+- `protocols/permission-contract.md`
 - `protocols/post-delivery-monitoring.md`
 
 ## Tools
@@ -89,6 +92,15 @@ See `protocols/` for quality gates, testing matrix, stack selection, design qual
 - `stack-presets/static-site.md`
 - `stack-presets/admin-dashboard.md`
 
+## Stack Playbooks
+
+- `stack-playbooks/README.md`
+- `stack-playbooks/nextjs-vercel-supabase.md`
+- `stack-playbooks/react-vite-static.md`
+- `stack-playbooks/expo-eas.md`
+- `stack-playbooks/node-api.md`
+- `stack-playbooks/firebase.md`
+
 ## Evaluations
 
 - `evals/sagaz-evaluation-suite.md`
@@ -96,16 +108,28 @@ See `protocols/` for quality gates, testing matrix, stack selection, design qual
 ## Examples
 
 - `examples/README.md`
+- `examples/web-saas-vercel.md`
+- `examples/mobile-habit-tracker.md`
+- `examples/bugfix-production-release.md`
+- `examples/brownfield-refactor.md`
 
 ## Templates
 
 See `templates/` for task briefs, product specs, technical specs, design systems, future-change guides, refactor safety contracts, stack recommendations, run state, squad handoffs, QA reports, release checklists, changelogs, release notes, and final handoffs.
 
+- `templates/execution-trace.md`
+
 ## Governance
 
+- `governance/capabilities-matrix.md`
+- `governance/operations-runbook.md`
 - `governance/quality-policy.md`
 - `governance/security-policy.md`
 - `governance/versioning.md`
 - `governance/ecosystem-maintenance.md`
 - `governance/package-release-policy.md`
+
+## Adoption
+
+- `ADOPTION.md`
 

package/ai-orchestration-ecosystem/README.md

@@ -4,21 +4,26 @@ A local AI orchestration ecosystem for Codex, focused on autonomous teams, consi
 
 ## How To Use
 
-1. Read `quickstart.md`.
-2. Choose the smallest sufficient workflow or squad.
-3. Use formal tasks, handoffs, and quality gates.
-4. Create or update run state for medium/large work.
-5. Verify before declaring done.
+1. Read `governance/operations-runbook.md` for the daily operating procedure.
+2. Read `ADOPTION.md` when starting Sagaz in another project or onboarding a team.
+3. Read `quickstart.md`.
+4. Choose the smallest sufficient workflow or squad.
+5. Use formal tasks, handoffs, and quality gates.
+6. Create or update run state for medium/large work.
+7. Verify before declaring done.
 
 ## Structure
 
 - `manifest.json`: internal component registry used to validate and navigate the ecosystem.
+- `ADOPTION.md`: first-use guide for adopting Sagaz in another project or team.
 - `workflows/`: named end-to-end flows.
 - `squads/`: specialized teams.
 - `agents/`: role definitions.
 - `tasks/`: formal task contracts.
 - `protocols/`: operating rules and quality gates.
+- `stack-playbooks/`: operational guides for common stack implementation, verification, and deployment.
 - `templates/`: reusable Markdown artifacts.
+- `examples/`: complete web, mobile, bugfix, and refactor flow examples.
 - `engineering/`: software engineering standards.
 - `governance/`: quality, security, and maintenance policies.
 
@@ -34,6 +39,14 @@ Use `protocols/release-versioning-gate.md` before version bumps, Git tags, GitHu
 
 Use `protocols/installed-skill-sync.md` after changing the Sagaz skill or release rules so the installed Codex Desktop skill does not drift from the repository copy.
 
+Use `governance/capabilities-matrix.md` when comparing Sagaz with CrewAI, AutoGen, LangChain, LangGraph, AIOX, Synkra, or similar orchestration systems.
+
+Use `protocols/permission-contract.md` before actions that change local state, remote state, accounts, deployments, packages, credentials, or GitHub history.
+
+Use `protocols/agent-observability.md` and `templates/execution-trace.md` for multi-phase, production, release, deployment, package, or high-risk work.
+
+Use `protocols/mcp-connector-policy.md` before using MCPs or external connectors such as Figma, GitHub, Canva, Browser, Vercel, Supabase, Firebase, npm, or observability tools.
+
 ## Advanced Engineering Coverage
 
 Sagaz includes protocols for SRE readiness, DORA metrics, secure SDLC, dependency governance, data privacy lifecycle, architecture fitness functions, API contracts, performance budgets, accessibility compliance, database migrations, release strategy, and AI application quality.

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

@@ -2,69 +2,47 @@
 
 ## Purpose
 
-Provide reusable, low-token examples for common Sagaz projects. Examples are not templates to copy blindly. They show the expected flow, artifacts, handoffs, and verification depth.
+Provide reusable, low-token examples for common Sagaz projects.
 
-## Example Categories
+Examples are not templates to copy blindly. They show the expected prompt shape, workflow, squads, artifacts, handoffs, verification depth, GitHub actions, deployment path, and final delivery evidence.
 
-- complete marketing website
-- SaaS web app
-- admin dashboard
-- mobile app
-- bugfix to release
-- safe refactor
-- production deploy
-- GitHub release
+## Complete Examples
 
-## Example Structure
-
-Each example should include:
-
-- user prompt
-- selected workflow
-- required squads
-- first questions, if any
-- stack recommendation summary
-- handoff sequence
-- expected artifacts
-- verification plan
-- GitHub actions to suggest
-- deployment path
-- final handoff shape
-
-## Minimal Web App Example
-
-```md
-User prompt:
-Sagaz: create a premium appointment scheduling SaaS for small clinics.
-
-Workflow:
-workflows/greenfield-web-app.md
-
-Squads:
-Product Factory -> Design Studio -> Production Critical -> GitHub Ops
+- `web-saas-vercel.md`: appointment scheduling SaaS using a web production path.
+- `mobile-habit-tracker.md`: Android/iOS habit tracker with mobile release planning.
+- `bugfix-production-release.md`: production bugfix through verification and GitHub release.
+- `brownfield-refactor.md`: safe refactor of an existing project without behavior changes.
 
-Stack recommendation:
-Next.js on Vercel, TypeScript, Supabase, Playwright, GitHub Actions.
-
-Reason:
-Fast delivery, clear deployment path, managed auth/database, strong web ecosystem, good future maintainability.
-
-Required handoffs:
-Intake -> stack -> spec -> design -> architecture -> implementation -> QA -> production readiness -> GitHub/deploy.
-```
-
-## Mobile App Example
-
-```md
-User prompt:
-Sagaz: create an Android/iOS habit tracker with premium UX and store-ready release planning.
-
-Workflow:
-workflows/mobile-app-production.md
+## Example Structure
 
-Likely stack:
-Expo, React Native, TypeScript, SQLite or Supabase depending on sync needs, EAS for builds.
+Each complete example includes:
+
+- User prompt.
+- Selected workflow.
+- Required squads.
+- First actions.
+- Stack recommendation.
+- Handoff sequence.
+- Expected artifacts.
+- Verification plan.
+- GitHub actions to suggest.
+- Deployment or release path.
+- Final handoff shape.
+
+## How To Use
+
+1. Pick the example closest to the user's request.
+2. Load only that example and the named workflow/task/protocol files needed for the current phase.
+3. Adapt constraints to the actual project.
+4. Keep run state for medium, large, production, mobile, or multi-phase work.
+5. Ask permission before moving across major phases or doing remote actions.
+
+## Selection Map
+
+| User Request | Example | Workflow |
+| --- | --- | --- |
+| New SaaS, dashboard, or premium web app | `web-saas-vercel.md` | `workflows/greenfield-web-app.md` |
+| Android/iOS app | `mobile-habit-tracker.md` | `workflows/mobile-app-production.md` |
+| Production bug | `bugfix-production-release.md` | `workflows/bugfix-to-release.md` |
+| Safe refactor | `brownfield-refactor.md` | `workflows/brownfield-refactor-safe.md` |
 
-Required evidence:
-Device-size review, offline behavior decision, accessibility checks, app icon/splash plan, release checklist.
-```