sagaz-ai 0.1.0

package/ai-orchestration-ecosystem/templates/product-spec.md

@@ -0,0 +1,20 @@
+# Product Spec
+
+## Objective
+
+## Context
+
+## Inputs
+
+## Decisions
+
+## Outputs
+
+## Evidence
+
+## Risks
+
+## Next Step
+
+## User Permission
+

package/ai-orchestration-ecosystem/templates/qa-report.md

@@ -0,0 +1,20 @@
+# Qa Report
+
+## Objective
+
+## Context
+
+## Inputs
+
+## Decisions
+
+## Outputs
+
+## Evidence
+
+## Risks
+
+## Next Step
+
+## User Permission
+

package/ai-orchestration-ecosystem/templates/run-state.md

@@ -0,0 +1,20 @@
+# Run State
+
+## Objective
+
+## Context
+
+## Inputs
+
+## Decisions
+
+## Outputs
+
+## Evidence
+
+## Risks
+
+## Next Step
+
+## User Permission
+

package/ai-orchestration-ecosystem/templates/squad-handoff.md

@@ -0,0 +1,20 @@
+# Squad Handoff
+
+## Objective
+
+## Context
+
+## Inputs
+
+## Decisions
+
+## Outputs
+
+## Evidence
+
+## Risks
+
+## Next Step
+
+## User Permission
+

package/ai-orchestration-ecosystem/templates/squad-runbook.md

@@ -0,0 +1,20 @@
+# Squad Runbook
+
+## Objective
+
+## Context
+
+## Inputs
+
+## Decisions
+
+## Outputs
+
+## Evidence
+
+## Risks
+
+## Next Step
+
+## User Permission
+

package/ai-orchestration-ecosystem/templates/stack-recommendation.md

@@ -0,0 +1,20 @@
+# Stack Recommendation
+
+## Objective
+
+## Context
+
+## Inputs
+
+## Decisions
+
+## Outputs
+
+## Evidence
+
+## Risks
+
+## Next Step
+
+## User Permission
+

package/ai-orchestration-ecosystem/templates/task-brief.md

@@ -0,0 +1,20 @@
+# Task Brief
+
+## Objective
+
+## Context
+
+## Inputs
+
+## Decisions
+
+## Outputs
+
+## Evidence
+
+## Risks
+
+## Next Step
+
+## User Permission
+

package/ai-orchestration-ecosystem/templates/technical-spec.md

@@ -0,0 +1,20 @@
+# Technical Spec
+
+## Objective
+
+## Context
+
+## Inputs
+
+## Decisions
+
+## Outputs
+
+## Evidence
+
+## Risks
+
+## Next Step
+
+## User Permission
+

package/ai-orchestration-ecosystem/workflows/brownfield-refactor-safe.md

@@ -0,0 +1,25 @@
+# Workflow: Brownfield Refactor Safe
+
+## Use
+
+Use this named workflow when the task matches Brownfield Refactor Safe delivery.
+
+## Sequence
+
+1. Intake: objective, constraints, definition of done, risks.
+2. Product: requirements, journeys, acceptance criteria.
+3. Technology: stack recommendation, architecture, deployment tradeoffs.
+4. Design: UX, UI, design system, accessibility, visual quality.
+5. Implementation: build in small verifiable increments.
+6. Verification: tests, QA, visual validation, security review.
+7. Production: readiness, environment variables, deployment, rollback.
+8. GitHub Ops: commit, push, PR, checks, release when approved.
+9. Delivery: final handoff with evidence and residual risks.
+
+## Gates
+
+- Use only necessary phases.
+- Ask permission before each major handoff.
+- Maintain run state for medium/large work.
+- Do not declare done without verification evidence.
+

package/ai-orchestration-ecosystem/workflows/bugfix-to-release.md

@@ -0,0 +1,25 @@
+# Workflow: Bugfix To Release
+
+## Use
+
+Use this named workflow when the task matches Bugfix To Release delivery.
+
+## Sequence
+
+1. Intake: objective, constraints, definition of done, risks.
+2. Product: requirements, journeys, acceptance criteria.
+3. Technology: stack recommendation, architecture, deployment tradeoffs.
+4. Design: UX, UI, design system, accessibility, visual quality.
+5. Implementation: build in small verifiable increments.
+6. Verification: tests, QA, visual validation, security review.
+7. Production: readiness, environment variables, deployment, rollback.
+8. GitHub Ops: commit, push, PR, checks, release when approved.
+9. Delivery: final handoff with evidence and residual risks.
+
+## Gates
+
+- Use only necessary phases.
+- Ask permission before each major handoff.
+- Maintain run state for medium/large work.
+- Do not declare done without verification evidence.
+

package/ai-orchestration-ecosystem/workflows/greenfield-web-app.md

@@ -0,0 +1,25 @@
+# Workflow: Greenfield Web App
+
+## Use
+
+Use this named workflow when the task matches Greenfield Web App delivery.
+
+## Sequence
+
+1. Intake: objective, constraints, definition of done, risks.
+2. Product: requirements, journeys, acceptance criteria.
+3. Technology: stack recommendation, architecture, deployment tradeoffs.
+4. Design: UX, UI, design system, accessibility, visual quality.
+5. Implementation: build in small verifiable increments.
+6. Verification: tests, QA, visual validation, security review.
+7. Production: readiness, environment variables, deployment, rollback.
+8. GitHub Ops: commit, push, PR, checks, release when approved.
+9. Delivery: final handoff with evidence and residual risks.
+
+## Gates
+
+- Use only necessary phases.
+- Ask permission before each major handoff.
+- Maintain run state for medium/large work.
+- Do not declare done without verification evidence.
+

package/ai-orchestration-ecosystem/workflows/mobile-app-production.md

@@ -0,0 +1,36 @@
+# Workflow: Mobile App Production
+
+## Use
+
+Use this named workflow when the task matches Mobile App Production delivery.
+
+## Sequence
+
+1. Intake: objective, constraints, definition of done, risks.
+2. Product: requirements, journeys, acceptance criteria.
+3. Technology: stack recommendation, architecture, deployment tradeoffs.
+4. Design: UX, UI, design system, accessibility, visual quality.
+5. Implementation: build in small verifiable increments.
+6. Verification: tests, QA, visual validation, security review.
+7. Production: readiness, environment variables, deployment, rollback.
+8. GitHub Ops: commit, push, PR, checks, release when approved.
+9. Delivery: final handoff with evidence and residual risks.
+
+## Advanced Protocols To Consider
+
+- SRE readiness for backends and critical services.
+- Secure SDLC.
+- Dependency governance.
+- Data privacy lifecycle.
+- Performance budgets for cold start, memory, and battery/network impact.
+- Accessibility compliance.
+- Release strategy for phased rollout.
+- AI application quality when AI features exist.
+
+## Gates
+
+- Use only necessary phases.
+- Ask permission before each major handoff.
+- Maintain run state for medium/large work.
+- Do not declare done without verification evidence.
+

package/ai-orchestration-ecosystem/workflows/web-production-release.md

@@ -0,0 +1,39 @@
+# Workflow: Web Production Release
+
+## Use
+
+Use this named workflow when the task matches Web Production Release delivery.
+
+## Sequence
+
+1. Intake: objective, constraints, definition of done, risks.
+2. Product: requirements, journeys, acceptance criteria.
+3. Technology: stack recommendation, architecture, deployment tradeoffs.
+4. Design: UX, UI, design system, accessibility, visual quality.
+5. Implementation: build in small verifiable increments.
+6. Verification: tests, QA, visual validation, security review.
+7. Production: readiness, environment variables, deployment, rollback.
+8. GitHub Ops: commit, push, PR, checks, release when approved.
+9. Delivery: final handoff with evidence and residual risks.
+
+## Advanced Protocols To Consider
+
+- SRE readiness.
+- Secure SDLC.
+- Dependency governance.
+- Data privacy lifecycle.
+- API contracts.
+- Performance budgets.
+- Accessibility compliance.
+- Database migrations.
+- Release strategy.
+- DORA metrics.
+- AI application quality when AI features exist.
+
+## Gates
+
+- Use only necessary phases.
+- Ask permission before each major handoff.
+- Maintain run state for medium/large work.
+- Do not declare done without verification evidence.
+

package/bin/sagaz.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageRoot = path.resolve(__dirname, "..");
+const skillSource = path.join(packageRoot, "codex-skill", "sagaz");
+const ecosystemSource = path.join(packageRoot, "ai-orchestration-ecosystem");
+const args = process.argv.slice(2);
+const command = args[0] ?? "help";
+
+function usage() {
+  console.log(`Sagaz CLI
+
+This CLI installs Sagaz into Codex Desktop. It is not a standalone runtime for using Sagaz in a terminal.
+
+Usage:
+  npx sagaz-ai install
+  npx sagaz-ai status
+  npx sagaz-ai doctor
+
+Options:
+  --codex-home <path>     Override Codex home. Default: ~/.codex
+  --ecosystem <path>      Also copy ai-orchestration-ecosystem to a target folder
+  --force                 Overwrite existing installed skill
+`);
+}
+
+function optionValue(name) {
+  const index = args.indexOf(name);
+  return index === -1 ? undefined : args[index + 1];
+}
+
+function hasFlag(name) {
+  return args.includes(name);
+}
+
+function codexHome() {
+  return path.resolve(optionValue("--codex-home") ?? path.join(os.homedir(), ".codex"));
+}
+
+function copyDirectory(source, target) {
+  if (!fs.existsSync(source)) throw new Error(`Source not found: ${source}`);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.cpSync(source, target, { recursive: true, force: true });
+}
+
+function install() {
+  const targetSkill = path.join(codexHome(), "skills", "sagaz");
+  if (fs.existsSync(targetSkill) && !hasFlag("--force")) {
+    console.log(`Sagaz is already installed at: ${targetSkill}`);
+    console.log("Run with --force to overwrite it.");
+  } else {
+    copyDirectory(skillSource, targetSkill);
+    console.log(`Sagaz skill installed at: ${targetSkill}`);
+  }
+
+  const ecosystemTarget = optionValue("--ecosystem");
+  if (ecosystemTarget) {
+    const resolvedTarget = path.resolve(ecosystemTarget);
+    copyDirectory(ecosystemSource, resolvedTarget);
+    console.log(`Sagaz ecosystem copied to: ${resolvedTarget}`);
+  }
+
+  console.log("");
+  console.log("Next step:");
+  console.log("Open a new Codex Desktop thread and run:");
+  console.log("");
+  console.log("  Sagaz: explain the available workflows.");
+}
+
+function status() {
+  const targetSkill = path.join(codexHome(), "skills", "sagaz");
+  const skillFile = path.join(targetSkill, "SKILL.md");
+  console.log(`Codex home: ${codexHome()}`);
+  console.log(`Sagaz skill: ${targetSkill}`);
+  console.log(`Installed: ${fs.existsSync(skillFile) ? "yes" : "no"}`);
+}
+
+function doctor() {
+  let ok = true;
+  const required = [
+    path.join(skillSource, "SKILL.md"),
+    path.join(ecosystemSource, "quickstart.md"),
+    path.join(ecosystemSource, "INDEX.md")
+  ];
+  for (const file of required) {
+    const exists = fs.existsSync(file);
+    console.log(`${exists ? "ok" : "missing"} ${file}`);
+    ok = ok && exists;
+  }
+  status();
+  if (!ok) process.exitCode = 1;
+}
+
+try {
+  if (command === "install") install();
+  else if (command === "status") status();
+  else if (command === "doctor") doctor();
+  else usage();
+} catch (error) {
+  console.error(`Sagaz error: ${error.message}`);
+  process.exitCode = 1;
+}

package/codex-skill/sagaz/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: sagaz
+description: Local orchestration of autonomous AI squads inside Codex. Use when the user invokes "Sagaz", "$sagaz", "activate Sagaz", "use Sagaz", or asks to create web/mobile products with AI teams, detailed specifications, low token usage, premium design, stack advisory, production-critical delivery, guided GitHub operations, CI/CD, rigorous testing, and team handoffs.
+---
+
+# Sagaz
+
+Activate Sagaz as a local AI orchestration operating system.
+
+## First Step
+
+Locate the Sagaz repository in the workspace and read this first:
+
+`ai-orchestration-ecosystem/quickstart.md`
+
+If navigation is needed, read:
+
+`ai-orchestration-ecosystem/INDEX.md`
+
+## Operating Rules
+
+1. Apply guided proactivity globally: detect required or recommended actions, explain reason/impact/risk, and ask permission before meaningful actions.
+2. Use the smallest sufficient workflow, squad, and file set.
+3. For medium/large work, use a named workflow, formal tasks, and persistent run state.
+4. For multi-phase work, use team handoffs and ask permission before moving forward.
+5. For software, apply senior engineering: simplicity, testability, security, observability, and maintainability.
+6. For stacks, recommend technologies by cost, speed, scale, maintainability, maturity, deployment, and future changes.
+7. For UI, apply design-excellence: UX, UI, design system, responsiveness, accessibility, and visual validation.
+8. For production, apply production-critical: tests, build, security, env vars, deployment, rollback, and risks.
+9. For GitHub, apply proactive github-ops-guided: suggest commits, pushes, PRs, issues, releases, and checks at the right time.
+10. For production-grade engineering, apply relevant advanced protocols: 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.
+11. Do not declare done without verification evidence proportional to risk.
+
+## Quick Selection
+
+- New web app: `workflows/greenfield-web-app.md`
+- Web for production: `workflows/web-production-release.md`
+- Android/iOS mobile: `workflows/mobile-app-production.md` and `squads/mobile-app-studio.md`
+- Safe refactoring: `workflows/brownfield-refactor-safe.md`
+- Bugfix to release: `workflows/bugfix-to-release.md`
+- Design/UI: `squads/design-studio.md` and `protocols/design-quality.md`
+- GitHub: `squads/github-ops.md` and `protocols/github-operations.md`
+
+## Required Handoff
+
+For medium/large tasks, at the end of each phase:
+
+```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?
+```
+
+## Persistent State
+
+For long-running work, create or update a file based on:
+
+`ai-orchestration-ecosystem/templates/run-state.md`
+
+## Source Of Truth
+
+The complete details are in:
+
+`ai-orchestration-ecosystem/`

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "sagaz-ai",
+  "version": "0.1.0",
+  "description": "Sagaz AI orchestration ecosystem installer for Codex Desktop.",
+  "type": "module",
+  "bin": {
+    "sagaz": "bin/sagaz.js"
+  },
+  "scripts": {
+    "doctor": "node ./bin/sagaz.js doctor",
+    "test": "node ./scripts/verify-package.js"
+  },
+  "files": [
+    "bin",
+    "scripts",
+    "codex-skill",
+    "ai-orchestration-ecosystem",
+    "README.md",
+    "INSTALL.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "codex",
+    "ai-agents",
+    "orchestration",
+    "skills",
+    "sagaz"
+  ],
+  "author": "Thiago Cabral",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tscabral1/sagaz.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tscabral1/sagaz/issues"
+  },
+  "homepage": "https://github.com/tscabral1/sagaz#readme"
+}

package/scripts/verify-package.js

@@ -0,0 +1,29 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const root = process.cwd();
+const required = [
+  "package.json",
+  "bin/sagaz.js",
+  "codex-skill/sagaz/SKILL.md",
+  "ai-orchestration-ecosystem/quickstart.md",
+  "ai-orchestration-ecosystem/INDEX.md",
+  "README.md",
+  "INSTALL.md",
+  "LICENSE"
+];
+
+let ok = true;
+for (const file of required) {
+  const exists = fs.existsSync(path.join(root, file));
+  console.log(`${exists ? "ok" : "missing"} ${file}`);
+  ok = ok && exists;
+}
+
+const skill = fs.readFileSync(path.join(root, "codex-skill/sagaz/SKILL.md"), "utf8").replace(/^\uFEFF/, "");
+if (!skill.startsWith("---") || !skill.includes("name: sagaz")) {
+  console.log("missing valid Sagaz skill frontmatter");
+  ok = false;
+}
+
+if (!ok) process.exitCode = 1;