sagaz-ai 0.1.0

package/INSTALL.md

@@ -0,0 +1,78 @@
+# Sagaz Installation
+
+## Requirements
+
+- Codex Desktop.
+- Node.js 18+ if installing with `npx`.
+- Git installed.
+- GitHub CLI (`gh`) installed and authenticated if you want GitHub Ops.
+- Access to the local Codex skills folder.
+
+## Recommended: Install With npx
+
+```powershell
+npx sagaz-ai install
+```
+
+Then open a new Codex Desktop thread and test:
+
+```text
+Sagaz: explain the available workflows.
+```
+
+## Optional Commands
+
+```powershell
+npx sagaz-ai status
+npx sagaz-ai doctor
+npx sagaz-ai install --force
+```
+
+To also copy the ecosystem to a chosen folder:
+
+```powershell
+npx sagaz-ai install --ecosystem C:\Users\YOUR_USER\Documents\Sagaz\ai-orchestration-ecosystem
+```
+
+## Manual Install
+
+Copy:
+
+```text
+codex-skill\sagaz
+```
+
+into:
+
+```text
+C:\Users\YOUR_USER\.codex\skills\sagaz
+```
+
+Then open a new Codex Desktop thread and test:
+
+```text
+Sagaz: explain the available workflows.
+```
+
+## Use In A Project
+
+Keep this repository available to Codex. Then, inside the project you want to work on, ask:
+
+```text
+Sagaz: use the appropriate workflow for this project. Maintain run state, handoffs, and verification evidence.
+```
+
+## GitHub Ops
+
+Authenticate GitHub CLI:
+
+```powershell
+gh auth login -h github.com
+```
+
+Verify:
+
+```powershell
+gh auth status
+git --version
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thiago Cabral
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,185 @@
+# Sagaz
+
+Sagaz is a local AI orchestration ecosystem designed for Codex Desktop. It turns a product request into a structured delivery process with specialized AI teams, explicit handoffs, detailed specifications, implementation, testing, high-standard UX/UI, guided GitHub operations, CI/CD readiness, and production-quality gates.
+
+It is inspired by ideas from AIOX, CrewAI, AutoGen, LangChain, and enterprise governance platforms, but it is designed for one practical goal: make Codex Desktop easy to use for serious web and mobile software projects while keeping token usage low and technical quality high.
+
+## Designed For Codex Desktop
+
+Sagaz is intended to be used inside Codex Desktop the way this repository was created: as a local Codex skill plus a Markdown orchestration ecosystem. The npm package only installs the skill and ecosystem files. It is not a standalone terminal agent runtime and it is not a replacement for Codex CLI.
+
+## What Sagaz Does
+
+Sagaz organizes work into focused teams:
+
+- Product strategy and requirements.
+- Stack recommendation.
+- Software architecture.
+- UX, UI, and design systems.
+- Implementation.
+- QA and testing.
+- Security and production readiness.
+- GitHub commits, pull requests, issues, releases, and checks.
+- Android/iOS mobile delivery.
+- CI/CD and post-delivery monitoring.
+
+Sagaz also guides the user through the process. At the end of each phase, it explains what was completed, which team should work next, why the next step matters, and asks permission before moving forward.
+
+## Why Use Sagaz
+
+- **Simple invocation:** start with `Sagaz:` and describe the goal.
+- **Low token usage:** load only the workflow, squad, task, or protocol needed for the current phase.
+- **Guided process:** team handoffs require user approval.
+- **Production quality:** gates for tests, security, builds, deployment, rollback, and residual risk.
+- **Premium design:** UX/UI, design systems, responsiveness, accessibility, and visual QA.
+- **Stack advisory:** technology choices explained by cost, speed, scale, maintainability, deployment, and future changes.
+- **GitHub without guesswork:** Sagaz recommends commits, pushes, pull requests, issues, and releases at the right time.
+- **Web and mobile:** workflows for browser apps, websites, dashboards, Android, and iOS.
+- **Persistent state:** Markdown run state records decisions, approvals, handoffs, risks, and test evidence.
+
+## How It Works
+
+Sagaz uses Markdown files as the source of truth. The main structure is:
+
+```text
+ai-orchestration-ecosystem/
+```
+
+Key areas:
+
+- `workflows/`: ready-made workflows for web, mobile, production, bug fixes, and refactoring.
+- `squads/`: specialized teams.
+- `agents/`: individual roles.
+- `tasks/`: formal tasks with inputs, outputs, acceptance criteria, verification, and stop conditions.
+- `protocols/`: rules for quality, handoffs, GitHub, production, design, CI/CD, and monitoring.
+- `templates/`: reusable artifacts for specs, QA, handoffs, run state, and releases.
+- `engineering/`: deep software engineering standards.
+- `governance/`: security, quality, versioning, and ecosystem maintenance.
+
+## Included Workflows
+
+- `greenfield-web-app`: create a website or web app from scratch.
+- `web-production-release`: prepare a web app for production.
+- `mobile-app-production`: create or prepare an Android/iOS app.
+- `brownfield-refactor-safe`: refactor an existing project safely.
+- `bugfix-to-release`: fix a bug through verification and release.
+
+## Installation In Codex Desktop
+
+### Recommended: Install With npx
+
+```powershell
+npx sagaz-ai install
+```
+
+Then open a new Codex Desktop thread and run:
+
+```text
+Sagaz: explain the available workflows.
+```
+
+Optional: also copy the ecosystem to a known local folder:
+
+```powershell
+npx sagaz-ai install --ecosystem C:\Users\YOUR_USER\Documents\Sagaz\ai-orchestration-ecosystem
+```
+
+Check installation:
+
+```powershell
+npx sagaz-ai status
+npx sagaz-ai doctor
+```
+
+### Manual Installation
+
+#### 1. Clone Or Download The Repository
+
+```powershell
+git clone https://github.com/tscabral1/sagaz.git
+```
+
+Or download the ZIP from GitHub.
+
+#### 2. Copy The Skill Into Codex
+
+On Windows, the local Codex skills folder is usually:
+
+```text
+C:\Users\YOUR_USER\.codex\skills
+```
+
+Copy this folder:
+
+```text
+codex-skill\sagaz
+```
+
+into:
+
+```text
+C:\Users\YOUR_USER\.codex\skills\sagaz
+```
+
+#### 3. Keep The Ecosystem Available
+
+Keep `ai-orchestration-ecosystem/` accessible in the Codex workspace or in a known local folder.
+
+#### 4. open a new Codex Desktop thread
+
+After copying the skill, open a new Codex Desktop thread so Codex can discover the updated skill.
+
+## How To Use
+
+Use a simple prompt:
+
+```text
+Sagaz: create a complete website for my company, from planning to deployment.
+```
+
+Or:
+
+```text
+Sagaz: create an Android/iOS app for personal finance tracking, with premium design, tests, and production readiness.
+```
+
+Sagaz should choose the appropriate workflow, create or update persistent run state, recommend a stack, plan requirements, create UX/UI and a design system, implement, test, prepare production and CI/CD, suggest GitHub operations, and deliver a final handoff with evidence and risks.
+
+For production-grade work, Sagaz can also apply 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 protocols.
+
+## Web Example
+
+```text
+Sagaz: I want to create a web SaaS for appointment scheduling.
+
+Requirements:
+- user login
+- calendar
+- admin dashboard
+- premium design
+- production-ready
+- deployment on Vercel
+```
+
+## Mobile Example
+
+```text
+Sagaz: I want to create an Android/iOS app for daily habit tracking.
+
+Recommend the stack, explain costs, create mobile UX, implement it, test it, and prepare the release checklist.
+```
+
+## Important Rules
+
+Sagaz must ask permission before moving between major teams/phases, installing dependencies, creating or editing files when implementation has not been clearly authorized, deploying, creating a repository, committing, pushing, opening a PR, creating an issue/tag/release, accepting high risk, or running destructive actions.
+
+Sagaz may directly run low-risk diagnostics such as reading files, inspecting structure, searching text, checking status, and proposing plans.
+
+## Who It Is For
+
+Sagaz is for users who want to build serious software with Codex without needing to personally manage every detail of engineering, design, GitHub, deployment, and production operations.
+
+## Status
+
+Sagaz is an evolving local orchestration ecosystem. The source of truth is the Markdown in this repository.
+

package/ai-orchestration-ecosystem/ACTIVATE.md

@@ -0,0 +1,45 @@
+# Activate Sagaz Ecosystem
+
+## Short Invocation
+
+```text
+Sagaz: [your task]
+```
+
+## Full Invocation
+
+```text
+Activate the Sagaz AI Orchestration Ecosystem.
+Read only ai-orchestration-ecosystem/quickstart.md first.
+Choose the smallest sufficient mode, workflow, and squad.
+Use detailed specifications when risk justifies it.
+Validate with quality gates and the testing matrix.
+Use low token context and save important artifacts in Markdown.
+```
+
+## Common Uses
+
+### New Product
+
+```text
+Sagaz: use the product-factory squad to create this product from planning through delivery.
+```
+
+### High-Standard Design
+
+```text
+Sagaz: use design-studio to create a premium UX/UI with a complete design system, responsiveness, accessibility, and visual QA.
+```
+
+### Guided GitHub
+
+```text
+Sagaz: proactively handle Git and GitHub for this project. Explain why each action matters and ask permission before running it.
+```
+
+### Pipeline With Handoffs
+
+```text
+Sagaz: follow a sequential pipeline with team handoffs. At the end of each phase, explain what was done, what the next team will do, and ask permission before moving forward.
+```
+

package/ai-orchestration-ecosystem/INDEX.md

@@ -0,0 +1,73 @@
+# Index
+
+## Quick Entry
+
+- `ACTIVATE.md`: ready-to-use activation prompts.
+- `quickstart.md`: minimum operating rules.
+- `README.md`: ecosystem overview.
+
+## Core
+
+- `core/operating-system.md`
+- `core/token-economy.md`
+- `core/decision-records.md`
+
+## Engineering
+
+- `engineering/software-engineering-deep-guide.md`
+
+## Workflows
+
+- `workflows/greenfield-web-app.md`
+- `workflows/web-production-release.md`
+- `workflows/mobile-app-production.md`
+- `workflows/brownfield-refactor-safe.md`
+- `workflows/bugfix-to-release.md`
+
+## Squads
+
+- `squads/product-factory.md`
+- `squads/design-studio.md`
+- `squads/mobile-app-studio.md`
+- `squads/production-critical.md`
+- `squads/github-ops.md`
+- `squads/code-audit.md`
+- `squads/refactor-lab.md`
+- `squads/research-to-spec.md`
+- `squads/maintenance-ops.md`
+
+## Agents
+
+See `agents/` for Orchestrator, Product Strategist, Technology Strategist, Software Architect, Implementation Engineer, QA Verifier, Security Governance, Design Director, UX Architect, UI Systems Designer, Visual QA, Specification Writer, and Refactor Steward.
+
+## Protocols
+
+See `protocols/` for quality gates, testing matrix, stack selection, design quality, guided proactivity, squad handoffs, production readiness, GitHub operations, CI/CD readiness, post-delivery monitoring, delegation, communication, memory, and model routing.
+
+## Advanced Engineering Protocols
+
+- `protocols/sre-readiness.md`
+- `protocols/dora-metrics.md`
+- `protocols/secure-sdlc.md`
+- `protocols/dependency-governance.md`
+- `protocols/data-privacy-lifecycle.md`
+- `protocols/architecture-fitness-functions.md`
+- `protocols/api-contracts.md`
+- `protocols/performance-budgets.md`
+- `protocols/accessibility-compliance.md`
+- `protocols/database-migrations.md`
+- `protocols/release-strategy.md`
+- `protocols/ai-application-quality.md`
+
+## Templates
+
+See `templates/` for task briefs, product specs, technical specs, design systems, stack recommendations, run state, squad handoffs, QA reports, release checklists, and final handoffs.
+
+## Governance
+
+- `governance/quality-policy.md`
+- `governance/security-policy.md`
+- `governance/versioning.md`
+- `governance/ecosystem-maintenance.md`
+- `governance/package-release-policy.md`
+

package/ai-orchestration-ecosystem/README.md

@@ -0,0 +1,31 @@
+# Sagaz AI Orchestration Ecosystem
+
+A local AI orchestration ecosystem for Codex, focused on autonomous teams, consistent outcomes, low token usage, high-quality software engineering, premium UX/UI, and production-ready delivery.
+
+## 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.
+
+## Structure
+
+- `workflows/`: named end-to-end flows.
+- `squads/`: specialized teams.
+- `agents/`: role definitions.
+- `tasks/`: formal task contracts.
+- `protocols/`: operating rules and quality gates.
+- `templates/`: reusable Markdown artifacts.
+- `engineering/`: software engineering standards.
+- `governance/`: quality, security, and maintenance policies.
+
+## Golden Rule
+
+No delivery is complete without verification evidence proportional to the risk.
+
+## 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/agents/design-director.md

@@ -0,0 +1,20 @@
+# Agent: Design Director
+
+## Mission
+
+Set visual direction and ensure the interface reaches a high market-standard quality bar.
+
+## Responsibilities
+
+- Interpret domain, audience, and positioning.
+- Define visual personality.
+- Enforce hierarchy, composition, rhythm, and polish.
+- Block generic or visually weak interfaces.
+
+## Standard Output
+
+- Visual direction
+- Interface principles
+- Design risks
+- Visual acceptance criteria
+

package/ai-orchestration-ecosystem/agents/implementation-engineer.md

@@ -0,0 +1,21 @@
+# Agent: Implementation Engineer
+
+## Mission
+
+Implement scoped changes while respecting existing patterns and keeping verification practical.
+
+## Responsibilities
+
+- Inspect the repository before editing.
+- Follow local conventions.
+- Make small verifiable changes.
+- Avoid unrelated refactors.
+- Document changed files and reasons.
+
+## Standard Output
+
+- Implementation summary
+- Changed files
+- How to run
+- Notes for future work
+

package/ai-orchestration-ecosystem/agents/orchestrator.md

@@ -0,0 +1,22 @@
+# Agent: Orchestrator
+
+## Mission
+
+Turn user goals into an executable plan, select the smallest sufficient team, manage handoffs, and enforce quality gates.
+
+## Responsibilities
+
+- Clarify objective, constraints, definition of done, and risks.
+- Select workflow, squad, and autonomy level.
+- Break work into verifiable phases.
+- Ask permission before meaningful handoffs or state-changing actions.
+- Require evidence before declaring work complete.
+
+## Standard Output
+
+- Plan
+- Delegations
+- Handoff requests
+- Quality gate summary
+- Final report
+

package/ai-orchestration-ecosystem/agents/product-strategist.md

@@ -0,0 +1,22 @@
+# Agent: Product Strategist
+
+## Mission
+
+Translate broad intent into product scope, user journeys, requirements, and acceptance criteria.
+
+## Responsibilities
+
+- Define target users and primary jobs to be done.
+- Separate essential scope from optional scope.
+- Write functional and non-functional requirements.
+- Identify success metrics and product risks.
+
+## Standard Output
+
+- Product goal
+- Users
+- Use cases
+- Requirements
+- Acceptance criteria
+- Product risks
+

package/ai-orchestration-ecosystem/agents/qa-verifier.md

@@ -0,0 +1,23 @@
+# Agent: Qa Verifier
+
+## Mission
+
+Prove that the delivery works, expose regressions, and document residual risks.
+
+## Responsibilities
+
+- Create a test matrix proportional to risk.
+- Run relevant automated checks.
+- Perform smoke tests for primary flows.
+- Test edge cases, empty states, and error states.
+- Block fragile deliveries.
+
+## Standard Output
+
+- Tests run
+- Manual checks
+- Failures
+- Fixes
+- Residual risks
+- Verdict
+

package/ai-orchestration-ecosystem/agents/refactor-steward.md

@@ -0,0 +1,20 @@
+# Agent: Refactor Steward
+
+## Mission
+
+Guide refactors while preserving behavior and public contracts.
+
+## Responsibilities
+
+- Map current behavior before changes.
+- Identify invariants and public contracts.
+- Plan incremental changes.
+- Require before/after verification.
+
+## Standard Output
+
+- Preserved behavior
+- Internal changes
+- Regression tests
+- Residual risks
+

package/ai-orchestration-ecosystem/agents/security-governance.md

@@ -0,0 +1,21 @@
+# Agent: Security Governance
+
+## Mission
+
+Protect secrets, data, permissions, dependencies, and production safety.
+
+## Responsibilities
+
+- Identify sensitive data and secrets.
+- Review permissions and external integrations.
+- Check logs, generated files, and configuration.
+- Require mitigations for high risk.
+
+## Standard Output
+
+- Sensitive assets
+- Threats
+- Controls
+- Gaps
+- Recommendations
+

package/ai-orchestration-ecosystem/agents/software-architect.md

@@ -0,0 +1,21 @@
+# Agent: Software Architect
+
+## Mission
+
+Design simple, evolvable, testable architecture aligned with the existing codebase and product goals.
+
+## Responsibilities
+
+- Read existing patterns before proposing changes.
+- Define modules, contracts, dependencies, and data flow.
+- Prefer proportional architecture over fashionable complexity.
+- Create ADRs for durable decisions.
+
+## Standard Output
+
+- Architecture overview
+- Module contracts
+- Tradeoffs
+- Risks
+- ADR recommendation
+

package/ai-orchestration-ecosystem/agents/specification-writer.md

@@ -0,0 +1,21 @@
+# Agent: Specification Writer
+
+## Mission
+
+Write detailed specifications that preserve consistency and reduce ambiguity.
+
+## Responsibilities
+
+- Write product and technical requirements.
+- Define expected behavior and acceptance criteria.
+- Document constraints, states, and non-goals.
+- Keep language operational and testable.
+
+## Standard Output
+
+- PRD or technical spec
+- Contracts
+- Use cases
+- Acceptance criteria
+- Validation checklist
+

package/ai-orchestration-ecosystem/agents/technology-strategist.md

@@ -0,0 +1,21 @@
+# Agent: Technology Strategist
+
+## Mission
+
+Recommend stacks, frameworks, databases, hosting, tools, and deployment architecture.
+
+## Responsibilities
+
+- Evaluate cost, speed, scalability, maintainability, maturity, security, deployment, and future changes.
+- Compare alternatives when decisions have meaningful impact.
+- Explain tradeoffs in plain American English.
+- Ask confirmation before installing dependencies or adopting costly or locked-in choices.
+
+## Standard Output
+
+- Recommended stack
+- Alternatives
+- Tradeoff matrix
+- Final recommendation
+- Confirmation question
+

package/ai-orchestration-ecosystem/agents/ui-systems-designer.md

@@ -0,0 +1,20 @@
+# Agent: Ui Systems Designer
+
+## Mission
+
+Create design systems, tokens, components, and consistent visual rules.
+
+## Responsibilities
+
+- Define colors, typography, spacing, radii, borders, elevation, icons, and motion.
+- Create base components and variants.
+- Standardize forms, feedback, cards, tables, navigation, and modals.
+
+## Standard Output
+
+- Design tokens
+- Component inventory
+- Responsive rules
+- Component states
+- Consistency checklist
+