sagaz-ai 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # 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

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.3.0
+Version: 0.3.1
 Date: 2026-06-11
-Release type: Minor
+Release type: Patch
 GitHub commit: pending
 Git tag: pending
 GitHub release: pending
@@ -12,38 +12,32 @@ npm package: pending
 
 ## Summary
 
-Sagaz 0.3.0 completes the main non-CLI governance layer for Codex Desktop orchestration. It adds operational runbooks, complete scenario examples, a capabilities matrix, formal permission policy, stack playbooks, execution trace evidence, and MCP connector governance.
+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 operating model, examples, stack guidance, and permission expectations before using Sagaz.
-- Existing users: should refresh the installed skill with `npx sagaz-ai sync`.
-- Maintainers: stronger package checks now catch stack playbook, observability, permission, and connector-policy drift.
-- Design team: Figma MCP usage is governed as a formal connector workflow for app-like mockups and design artifacts.
-- Engineering team: workflow evidence now includes traceable commands, decisions, failures, permissions, and handoffs.
+- 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 an operations runbook for everyday Sagaz use.
-- Added complete examples for common delivery scenarios.
-- Added a capabilities matrix against other orchestration ecosystems.
-- Added a formal permission contract for Windows and macOS Codex Desktop usage.
-- Added stack-specific playbooks.
-- Added an execution trace template and stronger observability protocol.
-- Added MCP connector policy across design, deploy, package, data, browser, and AI providers.
-- Expanded package verification to enforce the new governance files.
+- 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 now has clearer rules for how agents should choose tools, request permission, preserve workflow state, hand off work, verify stack-specific outcomes, and operate MCP connectors without drifting into ad hoc behavior.
+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 from a Codex Desktop workspace.
-- 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 now has clearer rules for how agents should choose tools, request permissi
 Run:
 
 ```bash
-npx sagaz-ai@0.3.0 sync
+npx sagaz-ai@0.3.1 sync
 npx sagaz-ai doctor
 ```
 
@@ -62,12 +56,11 @@ Then open a new Codex Desktop thread so Sagaz is rediscovered.
 - `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: Git status reviewed before release preparation.
+- Manual checks: adoption guide linked from README, INDEX, and manifest.
 
 ## Known Limitations
 
 - Sagaz still intentionally skips a standalone CLI runtime; Codex Desktop remains the execution surface.
-- GitHub release and npm publishing remain explicit approval steps.
 - Connector behavior depends on each external MCP/app authorization and platform availability.
 
 ## Rollback Plan

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.
@@ -127,4 +128,8 @@ See `templates/` for task briefs, product specs, technical specs, design systems
 - `governance/versioning.md`
 - `governance/ecosystem-maintenance.md`
 - `governance/package-release-policy.md`
+
+## Adoption
+
+- `ADOPTION.md`
 

package/ai-orchestration-ecosystem/README.md

@@ -5,15 +5,17 @@ A local AI orchestration ecosystem for Codex, focused on autonomous teams, consi
 ## How To Use
 
 1. Read `governance/operations-runbook.md` for the daily operating procedure.
-2. Read `quickstart.md`.
-3. Choose the smallest sufficient workflow or squad.
-4. Use formal tasks, handoffs, and quality gates.
-5. Create or update run state for medium/large work.
-6. Verify before declaring done.
+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.

package/ai-orchestration-ecosystem/manifest.json

@@ -165,6 +165,7 @@
     ],
     "docs": [
       "ACTIVATE.md",
+      "ADOPTION.md",
       "INDEX.md",
       "README.md",
       "quickstart.md"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sagaz-ai",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Sagaz AI orchestration ecosystem installer for Codex Desktop.",
   "type": "module",
   "bin": {

package/scripts/verify-package.js

@@ -203,7 +203,7 @@ function validateManifest() {
 
     const baseDirectory = path.join(ecosystemRoot, directory);
     const actual = directory === "."
-      ? ["ACTIVATE.md", "INDEX.md", "README.md", "quickstart.md"]
+      ? ["ACTIVATE.md", "ADOPTION.md", "INDEX.md", "README.md", "quickstart.md"]
       : walkMarkdown(baseDirectory).map((markdownFile) => path.relative(ecosystemRoot, markdownFile).split(path.sep).join("/"));
     const expected = new Set(actual);
     const declared = new Set(entries);