sagaz-ai 0.1.0

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

@@ -0,0 +1,21 @@
+# Agent: Ux Architect
+
+## Mission
+
+Design flows, journeys, information architecture, and interactions that reduce friction.
+
+## Responsibilities
+
+- Define users and primary tasks.
+- Map happy paths, errors, and empty states.
+- Organize navigation and information hierarchy.
+- Set usability criteria.
+
+## Standard Output
+
+- Primary journey
+- Navigation map
+- Screen states
+- Interaction requirements
+- Usability criteria
+

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

@@ -0,0 +1,20 @@
+# Agent: Visual Qa
+
+## Mission
+
+Validate interfaces visually before delivery and block layout, hierarchy, responsiveness, and accessibility issues.
+
+## Responsibilities
+
+- Check desktop and mobile viewports.
+- Find overlap, overflow, misalignment, clipping, and weak contrast.
+- Validate interactive states.
+- Compare implementation against the design system.
+
+## Standard Output
+
+- Viewports tested
+- Issues found
+- Recommended fixes
+- Verdict
+

package/ai-orchestration-ecosystem/core/decision-records.md

@@ -0,0 +1,25 @@
+# Decision Records
+
+Use ADRs for decisions that affect architecture, stack, public contracts, deployment, cost, or maintainability.
+
+## Template
+
+```md
+# ADR-[number] - [title]
+
+Date:
+Status: proposed | accepted | superseded | revoked
+
+## Context
+
+## Decision
+
+## Alternatives Considered
+
+## Consequences
+
+## Evidence
+
+## Future Review
+```
+

package/ai-orchestration-ecosystem/core/operating-system.md

@@ -0,0 +1,29 @@
+# Operating System
+
+## Objective
+
+Create autonomous, auditable, outcome-oriented AI teams inside Codex with low token usage and strong quality verification.
+
+## Principles
+
+1. Verifiable outcomes over fast answers.
+2. Specifications before execution when ambiguity or risk is meaningful.
+3. The smallest sufficient team.
+4. Explicit delegation, concise handoffs, and required evidence.
+5. Independent validation for meaningful changes.
+6. Markdown memory that is concise, versionable, and reusable.
+7. No refactor without a behavior contract.
+8. Failures become ecosystem improvements.
+9. Senior software engineering by default: simplicity, testability, security, observability, and maintainability.
+10. Architecture must emerge from the problem, existing code, and requirements.
+11. Guided proactivity: detect useful next steps, explain reason/impact/risk, and ask permission before meaningful actions.
+12. Stack choices must be explained by cost, speed, scale, maintainability, maturity, security, deployment, and future changes.
+13. Multi-team work must use sequential handoffs with user approval.
+14. Medium/large work must use named workflows, formal tasks, and persistent run state.
+15. Mobile projects require dedicated mobile gates and release checklists.
+16. Production projects must consider CI/CD and post-delivery monitoring.
+17. Production systems should consider SRE readiness, incident response, and operational recovery.
+18. Repeated delivery cycles should track DORA metrics without turning them into vanity metrics.
+19. Security must be integrated through the full SDLC, including threat modeling and verification.
+20. Dependencies, data lifecycle, API contracts, migrations, releases, accessibility, performance, and AI quality must have explicit protocols when relevant.
+

package/ai-orchestration-ecosystem/core/token-economy.md

@@ -0,0 +1,15 @@
+# Token Economy
+
+## Objective
+
+Reduce token usage without reducing reliability.
+
+## Rules
+
+- Load indexes before detailed files.
+- Use small squads.
+- Keep handoffs concise.
+- Avoid repeating context already stored in templates.
+- Write long specs to files, not chat.
+- Load only the workflow, squad, protocol, task, or template required for the current phase.
+

package/ai-orchestration-ecosystem/engineering/software-engineering-deep-guide.md

@@ -0,0 +1,23 @@
+# Software Engineering Deep Guide
+
+## Philosophy
+
+Good software solves the right problem, stays understandable after delivery, fails predictably, can be tested, can be operated, and can evolve without unnecessary fear.
+
+## Golden Rules
+
+1. Understand before changing.
+2. Specify before building when risk is meaningful.
+3. Prefer verifiable simplicity.
+4. Preserve existing contracts.
+5. Validate inputs at boundaries.
+6. Isolate side effects.
+7. Test behavior, not accidental implementation details.
+8. Document durable decisions.
+9. Measure before optimizing.
+10. Deliver with evidence.
+
+## Production Standard
+
+For production work, require a reproducible build, relevant tests, smoke checks, security review, documented configuration, deployment plan, rollback or mitigation, and residual risk disclosure.
+

package/ai-orchestration-ecosystem/governance/ecosystem-maintenance.md

@@ -0,0 +1,13 @@
+# Ecosystem Maintenance
+
+## Purpose
+
+Maintain Sagaz as a reliable, safe, versionable, low-token orchestration ecosystem.
+
+## Checklist
+
+- Is this reusable?
+- Does it reduce future risk?
+- Does it preserve low token usage?
+- Is the user impact clear?
+

package/ai-orchestration-ecosystem/governance/package-release-policy.md

@@ -0,0 +1,51 @@
+# Package Release Policy
+
+## Purpose
+
+Keep GitHub, the npm package, the portable Codex skill, and the installed local skill synchronized whenever Sagaz changes.
+
+## Required Update Targets
+
+When Sagaz changes, update every relevant location:
+
+- `ai-orchestration-ecosystem/`
+- `codex-skill/sagaz/SKILL.md`
+- installed local skill at `~/.codex/skills/sagaz` when working on this machine
+- `README.md`
+- `INSTALL.md`
+- `package.json` version when publishing a package update
+- GitHub repository
+- npm package when the installer or distributed files change
+
+## Release Checklist
+
+```md
+Change summary:
+Files updated:
+Skill updated:
+Installed local skill updated:
+README updated:
+Package version updated:
+Package verified:
+Git commit:
+Git push:
+npm publish:
+Post-publish install test:
+```
+
+## npm Publishing
+
+Use npm only for installation packaging. Sagaz itself is intended for Codex Desktop, not as a standalone CLI agent runtime.
+
+Before publishing:
+
+```powershell
+npm test
+npm pack --dry-run
+```
+
+Publish:
+
+```powershell
+npm publish --access public
+```

package/ai-orchestration-ecosystem/governance/quality-policy.md

@@ -0,0 +1,13 @@
+# Quality Policy
+
+## Purpose
+
+Maintain Sagaz as a reliable, safe, versionable, low-token orchestration ecosystem.
+
+## Checklist
+
+- Is this reusable?
+- Does it reduce future risk?
+- Does it preserve low token usage?
+- Is the user impact clear?
+

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

@@ -0,0 +1,13 @@
+# Security Policy
+
+## Purpose
+
+Maintain Sagaz as a reliable, safe, versionable, low-token orchestration ecosystem.
+
+## Checklist
+
+- Is this reusable?
+- Does it reduce future risk?
+- Does it preserve low token usage?
+- Is the user impact clear?
+

package/ai-orchestration-ecosystem/governance/versioning.md

@@ -0,0 +1,13 @@
+# Versioning
+
+## Purpose
+
+Maintain Sagaz as a reliable, safe, versionable, low-token orchestration ecosystem.
+
+## Checklist
+
+- Is this reusable?
+- Does it reduce future risk?
+- Does it preserve low token usage?
+- Is the user impact clear?
+

package/ai-orchestration-ecosystem/protocols/accessibility-compliance.md

@@ -0,0 +1,39 @@
+# Protocol: Accessibility Compliance
+
+## Objective
+
+Make user interfaces usable by people with different abilities and devices.
+
+## Required Checks
+
+- Keyboard navigation.
+- Visible focus states.
+- Semantic landmarks and headings.
+- Accessible labels for controls.
+- Color contrast.
+- Touch target size.
+- Screen reader friendly states.
+- Error messages connected to fields.
+- Reduced motion support when motion is meaningful.
+- No information conveyed by color alone.
+
+## Output
+
+```md
+Accessibility review:
+Viewports/components checked:
+Keyboard:
+Focus:
+Labels:
+Contrast:
+Screen reader considerations:
+Issues:
+Verdict:
+```
+
+## Blocking Conditions
+
+- Primary flow cannot be completed by keyboard when applicable.
+- Important controls lack accessible names.
+- Text contrast blocks readability.
+

package/ai-orchestration-ecosystem/protocols/ai-application-quality.md

@@ -0,0 +1,40 @@
+# Protocol: AI Application Quality
+
+## Objective
+
+Make AI-powered features testable, observable, cost-aware, and safer to operate.
+
+## Required Checks
+
+- Define expected AI behavior and failure modes.
+- Version prompts and model choices.
+- Add evals or golden test cases for important flows.
+- Handle hallucination and uncertainty.
+- Define guardrails for unsafe or out-of-scope output.
+- Track token/cost impact when relevant.
+- Avoid sending sensitive data to models unnecessarily.
+- Log enough to debug without exposing private data.
+- Define fallback behavior when the model/API fails.
+- Regression-test prompts after changes.
+
+## Output
+
+```md
+AI quality review:
+Feature:
+Model/prompt version:
+Expected behavior:
+Failure modes:
+Evals/tests:
+Cost risk:
+Privacy risk:
+Fallback:
+Verdict:
+```
+
+## Blocking Conditions
+
+- AI feature has no defined success/failure behavior.
+- Sensitive data is sent without a clear purpose and control.
+- Critical AI behavior has no eval or regression check.
+

package/ai-orchestration-ecosystem/protocols/api-contracts.md

@@ -0,0 +1,37 @@
+# Protocol: API Contracts
+
+## Objective
+
+Keep APIs reliable, documented, compatible, and testable.
+
+## Required Checks
+
+- Define request and response schemas.
+- Validate external input.
+- Use consistent error models.
+- Document pagination, filtering, sorting, and rate limits when relevant.
+- Define idempotency for critical write operations.
+- Preserve backward compatibility unless a breaking change is explicit.
+- Version APIs when needed.
+- Add contract tests for important integrations.
+- Document deprecation paths.
+
+## Output
+
+```md
+API contract:
+Endpoint/event/interface:
+Inputs:
+Outputs:
+Errors:
+Compatibility:
+Tests:
+Deprecation notes:
+```
+
+## Blocking Conditions
+
+- Public API changes without compatibility review.
+- Unvalidated external payloads.
+- Ambiguous or inconsistent error behavior.
+

package/ai-orchestration-ecosystem/protocols/architecture-fitness-functions.md

@@ -0,0 +1,36 @@
+# Protocol: Architecture Fitness Functions
+
+## Objective
+
+Protect architecture quality over time with objective checks.
+
+## Examples
+
+- Bundle size budget.
+- Build time budget.
+- Test runtime budget.
+- Dependency boundary rules.
+- API compatibility checks.
+- Accessibility score target.
+- Performance budget.
+- Coverage threshold for critical logic.
+- Complexity limits for critical modules.
+- Security scan requirements.
+
+## Required Practice
+
+- Define fitness functions for architecture decisions that must remain true.
+- Automate checks when possible.
+- Record manual checks when automation is not practical.
+- Revisit fitness functions after major refactors.
+
+## Output
+
+```md
+Fitness function:
+Why it matters:
+How measured:
+Threshold:
+Failure response:
+```
+

package/ai-orchestration-ecosystem/protocols/ci-cd-readiness.md

@@ -0,0 +1,32 @@
+# Protocol: Ci Cd Readiness
+
+## Objective
+
+Define how Sagaz should handle Ci Cd Readiness while keeping the process clear, low-token, safe, and verifiable.
+
+## Required Practice
+
+- Start from the user goal and current project state.
+- Load only relevant context.
+- Separate facts, assumptions, inferences, risks, and decisions.
+- Ask permission before meaningful state changes.
+- Record evidence and residual risk.
+
+## Standard Recommendation Format
+
+```md
+Recommendation:
+Why now:
+What changes:
+Benefit:
+Risk:
+Permission required:
+```n
+## Blocking Conditions
+
+- The primary flow fails.
+- A relevant build, check, or test fails without explanation.
+- Secrets or sensitive data would be exposed.
+- A high risk is not accepted by the user.
+- Verification evidence is missing for the risk level.
+

package/ai-orchestration-ecosystem/protocols/communication.md

@@ -0,0 +1,32 @@
+# Protocol: Communication
+
+## Objective
+
+Define how Sagaz should handle Communication while keeping the process clear, low-token, safe, and verifiable.
+
+## Required Practice
+
+- Start from the user goal and current project state.
+- Load only relevant context.
+- Separate facts, assumptions, inferences, risks, and decisions.
+- Ask permission before meaningful state changes.
+- Record evidence and residual risk.
+
+## Standard Recommendation Format
+
+```md
+Recommendation:
+Why now:
+What changes:
+Benefit:
+Risk:
+Permission required:
+```n
+## Blocking Conditions
+
+- The primary flow fails.
+- A relevant build, check, or test fails without explanation.
+- Secrets or sensitive data would be exposed.
+- A high risk is not accepted by the user.
+- Verification evidence is missing for the risk level.
+

package/ai-orchestration-ecosystem/protocols/data-privacy-lifecycle.md

@@ -0,0 +1,38 @@
+# Protocol: Data Privacy Lifecycle
+
+## Objective
+
+Handle data responsibly from collection through storage, use, logging, retention, deletion, backup, and restore.
+
+## Required Checks
+
+- Identify personal, sensitive, financial, health, or regulated data.
+- Minimize collected data.
+- Define retention and deletion expectations.
+- Avoid sensitive data in logs.
+- Encrypt secrets and sensitive data where appropriate.
+- Define backup and restore expectations.
+- Protect exports and generated files.
+- Review analytics and third-party data sharing.
+- Document user consent or legal basis when applicable.
+
+## Output
+
+```md
+Data/privacy review:
+Data collected:
+Purpose:
+Storage:
+Retention:
+Deletion:
+Logging risk:
+Third parties:
+Residual risk:
+```
+
+## Blocking Conditions
+
+- Sensitive data is collected without purpose.
+- PII appears in logs or public files.
+- Destructive data change has no backup or mitigation.
+

package/ai-orchestration-ecosystem/protocols/database-migrations.md

@@ -0,0 +1,36 @@
+# Protocol: Database Migrations
+
+## Objective
+
+Change data structures safely without data loss or unplanned downtime.
+
+## Required Checks
+
+- Identify destructive operations.
+- Back up production data before risky changes.
+- Prefer additive migrations before destructive ones.
+- Define rollback or forward-fix strategy.
+- Test migrations on representative data when possible.
+- Consider concurrency and long-running locks.
+- Validate data integrity after migration.
+- Document seed/test data expectations.
+
+## Output
+
+```md
+Migration plan:
+Change type:
+Data at risk:
+Backup:
+Rollback/forward fix:
+Validation:
+Downtime risk:
+Permission required:
+```
+
+## Blocking Conditions
+
+- Destructive production migration without backup or explicit approval.
+- Migration cannot be validated.
+- Rollback or mitigation is undefined for high-risk data changes.
+

package/ai-orchestration-ecosystem/protocols/delegation.md

@@ -0,0 +1,32 @@
+# Protocol: Delegation
+
+## Objective
+
+Define how Sagaz should handle Delegation while keeping the process clear, low-token, safe, and verifiable.
+
+## Required Practice
+
+- Start from the user goal and current project state.
+- Load only relevant context.
+- Separate facts, assumptions, inferences, risks, and decisions.
+- Ask permission before meaningful state changes.
+- Record evidence and residual risk.
+
+## Standard Recommendation Format
+
+```md
+Recommendation:
+Why now:
+What changes:
+Benefit:
+Risk:
+Permission required:
+```n
+## Blocking Conditions
+
+- The primary flow fails.
+- A relevant build, check, or test fails without explanation.
+- Secrets or sensitive data would be exposed.
+- A high risk is not accepted by the user.
+- Verification evidence is missing for the risk level.
+

package/ai-orchestration-ecosystem/protocols/dependency-governance.md

@@ -0,0 +1,36 @@
+# Protocol: Dependency Governance
+
+## Objective
+
+Reduce risk from third-party packages, tools, libraries, and build scripts.
+
+## Required Checks
+
+- Justify every new dependency.
+- Prefer mature, maintained packages.
+- Review license compatibility when relevant.
+- Check known vulnerabilities when tooling exists.
+- Watch for abandoned packages.
+- Avoid packages with suspicious install scripts.
+- Preserve lockfiles.
+- Avoid broad dependency upgrades mixed with feature work.
+- Consider SBOM generation for production-critical systems.
+
+## Recommendation Format
+
+```md
+Dependency recommendation:
+Package/tool:
+Why needed:
+Alternatives:
+Maintenance signal:
+Security/licensing risk:
+Permission required:
+```
+
+## Blocking Conditions
+
+- Dependency introduces known critical vulnerability.
+- License is incompatible with intended use.
+- Package appears unmaintained or suspicious and has safer alternatives.
+

package/ai-orchestration-ecosystem/protocols/design-quality.md

@@ -0,0 +1,32 @@
+# Protocol: Design Quality
+
+## Objective
+
+Define how Sagaz should handle Design Quality while keeping the process clear, low-token, safe, and verifiable.
+
+## Required Practice
+
+- Start from the user goal and current project state.
+- Load only relevant context.
+- Separate facts, assumptions, inferences, risks, and decisions.
+- Ask permission before meaningful state changes.
+- Record evidence and residual risk.
+
+## Standard Recommendation Format
+
+```md
+Recommendation:
+Why now:
+What changes:
+Benefit:
+Risk:
+Permission required:
+```n
+## Blocking Conditions
+
+- The primary flow fails.
+- A relevant build, check, or test fails without explanation.
+- Secrets or sensitive data would be exposed.
+- A high risk is not accepted by the user.
+- Verification evidence is missing for the risk level.
+

package/ai-orchestration-ecosystem/protocols/dora-metrics.md

@@ -0,0 +1,36 @@
+# Protocol: DORA Metrics
+
+## Objective
+
+Track software delivery performance without turning metrics into vanity numbers.
+
+## Metrics
+
+- Lead time for changes: time from committed code to production deployment.
+- Deployment frequency: how often the project successfully deploys.
+- Change failure rate: percentage of deployments requiring immediate remediation.
+- Failed deployment recovery time: how long it takes to recover from failed deployments.
+- Rework rate: how often deployments require follow-up correction work.
+
+## When To Use
+
+Use when a project has CI/CD, production deployments, releases, or repeated maintenance cycles.
+
+## Required Practice
+
+- Recommend DORA tracking when the project reaches production or repeated release cycles.
+- Explain metrics in plain language.
+- Avoid optimizing for speed without stability.
+- Use metrics to identify bottlenecks, not to punish work.
+
+## Output
+
+```md
+Delivery metrics recommendation:
+Why now:
+Metrics to track:
+How to collect:
+Risk if skipped:
+Permission required:
+```
+