create-genia-os 2.4.0 → 3.0.0

package/template/.aiox-core/development/checklists/agent-quality-gate.md

@@ -0,0 +1,559 @@
+# Agent Quality Gate Checklist
+
+```yaml
+checklist:
+  id: agent-quality-gate
+  version: 4.0.0
+  created: 2026-01-30
+  updated: 2026-02-04
+  purpose: "Validate agent definitions meet Hybrid Loader quality standard + operational completeness"
+  mode: blocking  # Prevents publication if critical items fail
+  architecture: "hybrid-loader"
+  new_in_v4: "SC_AGT_004 — Operational Completeness (task files, templates, checklists, maturity scoring)"
+  reference: "aprendizado/32-ANATOMIA-AGENTE-100-PORCENTO-REPLICAVEL.md"
+```
+
+---
+
+## Pre-Validation: File Basics
+
+```yaml
+file_basics:
+  - id: min-lines
+    check: "Agent file has 800+ lines"
+    type: blocking
+    validation: "wc -l {file} >= 800"
+
+  - id: yaml-valid
+    check: "YAML syntax is valid"
+    type: blocking
+    validation: "yamllint passes"
+
+  - id: no-placeholders
+    check: "No unfilled {{placeholders}} remain"
+    type: blocking
+    validation: "grep '{{' returns empty"
+```
+
+---
+
+## Level 0: Loader Configuration (All Required - NEW)
+
+```yaml
+loader_checks:
+  - id: activation-notice
+    check: "ACTIVATION-NOTICE is present"
+    type: blocking
+    section: "top of file"
+
+  - id: ide-file-resolution
+    check: "IDE-FILE-RESOLUTION has valid base_path"
+    type: blocking
+    section: "Level 0"
+    required_fields:
+      - base_path
+      - resolution_pattern
+
+  - id: request-resolution
+    check: "REQUEST-RESOLUTION has mapping examples"
+    type: blocking
+    section: "Level 0"
+
+  - id: command-loader-exists
+    check: "command_loader section exists"
+    type: blocking
+    section: "Level 0"
+
+  - id: command-loader-complete
+    check: "Every command with loader != null has entry in command_loader"
+    type: blocking
+    validation: |
+      For each command in commands:
+        if command.loader != null:
+          assert command.name in command_loader
+
+  - id: command-loader-requires
+    check: "Each command_loader entry has 'requires' array"
+    type: blocking
+    validation: "command_loader[*].requires is array"
+
+  - id: critical-loader-rule
+    check: "CRITICAL_LOADER_RULE is present"
+    type: blocking
+    must_contain:
+      - "LOOKUP"
+      - "STOP"
+      - "LOAD"
+      - "VERIFY"
+      - "EXECUTE"
+      - "FAILURE TO LOAD = FAILURE TO EXECUTE"
+
+  - id: dependencies-complete
+    check: "dependencies lists all files in command_loader.requires"
+    type: blocking
+    validation: |
+      all_required_files = flatten(command_loader[*].requires)
+      all_dependency_files = flatten(dependencies[*])
+      assert all_required_files is subset of all_dependency_files
+
+  - id: files-exist
+    check: "All files in dependencies actually exist"
+    type: recommended
+    validation: "ls {base_path}/{file} succeeds for each"
+```
+
+---
+
+## Level 1: Identity (All Required)
+
+```yaml
+identity_checks:
+  - id: agent-name
+    check: "agent.name is defined"
+    type: blocking
+    section: "agent"
+
+  - id: agent-id
+    check: "agent.id is kebab-case"
+    type: blocking
+    section: "agent"
+    pattern: "^[a-z]+(-[a-z]+)*$"
+
+  - id: agent-tier
+    check: "agent.tier is 1, 2, or 3"
+    type: blocking
+    section: "agent"
+
+  - id: when-to-use
+    check: "agent.whenToUse is descriptive (20+ chars)"
+    type: blocking
+    section: "agent"
+
+  - id: persona-complete
+    check: "persona has role, style, identity, focus"
+    type: blocking
+    section: "persona"
+
+  - id: persona-background
+    check: "persona.background has 3+ paragraphs"
+    type: recommended
+    section: "persona"
+```
+
+---
+
+## Level 2: Operational (All Required)
+
+```yaml
+operational_checks:
+  - id: core-principles
+    check: "core_principles has 5-9 items"
+    type: blocking
+    min: 5
+    max: 9
+
+  - id: framework-exists
+    check: "operational_frameworks has at least 1 framework"
+    type: blocking
+    min: 1
+
+  - id: framework-complete
+    check: "Each framework has: name, philosophy, steps, examples"
+    type: blocking
+    required_fields:
+      - name
+      - philosophy
+      - steps
+      - examples
+
+  - id: framework-steps
+    check: "Each framework has 3+ steps with descriptions"
+    type: blocking
+    min_steps: 3
+
+  - id: commands-defined
+    check: "commands has 5+ items including *help and *exit"
+    type: blocking
+    min: 5
+    required:
+      - "*help"
+      - "*exit"
+```
+
+---
+
+## Level 3: Voice DNA (All Required)
+
+```yaml
+voice_checks:
+  - id: sentence-starters
+    check: "voice_dna.sentence_starters has 5+ patterns"
+    type: recommended
+    min: 5
+
+  - id: metaphors
+    check: "voice_dna.metaphors has 3+ metaphors"
+    type: recommended
+    min: 3
+
+  - id: vocabulary-always
+    check: "voice_dna.vocabulary.always_use has 5+ terms"
+    type: blocking
+    min: 5
+
+  - id: vocabulary-never
+    check: "voice_dna.vocabulary.never_use has 3+ terms"
+    type: blocking
+    min: 3
+
+  - id: behavioral-states
+    check: "voice_dna.behavioral_states has 2+ states"
+    type: recommended
+    min: 2
+
+  - id: signature-phrases
+    check: "signature_phrases has 5+ phrases"
+    type: recommended
+    min: 5
+```
+
+---
+
+## Level 4: Quality Assurance (All Required)
+
+```yaml
+quality_checks:
+  - id: output-examples
+    check: "output_examples has 3+ complete examples"
+    type: blocking
+    min: 3
+    required_fields:
+      - task
+      - input
+      - output
+
+  - id: anti-patterns-never
+    check: "anti_patterns.never_do has 5+ items"
+    type: blocking
+    min: 5
+
+  - id: anti-patterns-flags
+    check: "anti_patterns.red_flags_in_input has 2+ items"
+    type: recommended
+    min: 2
+
+  - id: completion-criteria
+    check: "completion_criteria.task_done_when is defined"
+    type: blocking
+
+  - id: handoff-defined
+    check: "completion_criteria.handoff_to has 1+ handoffs"
+    type: blocking
+    min: 1
+
+  - id: validation-checklist
+    check: "completion_criteria.validation_checklist has 3+ items"
+    type: recommended
+    min: 3
+
+  - id: objection-algorithms
+    check: "objection_algorithms has 3+ objections with responses"
+    type: recommended
+    min: 3
+```
+
+---
+
+## Level 5: Credibility (Domain-Specific)
+
+```yaml
+credibility_checks:
+  applies_to:
+    - copy
+    - legal
+    - storytelling
+    - data
+
+  checks:
+    - id: achievements
+      check: "authority_proof_arsenal.career_achievements has 3+ items"
+      type: recommended
+      min: 3
+
+    - id: publications
+      check: "authority_proof_arsenal.publications is defined"
+      type: recommended
+
+    - id: testimonials
+      check: "authority_proof_arsenal.testimonials has 1+ items"
+      type: recommended
+      min: 1
+```
+
+---
+
+## Operational Completeness (SC_AGT_004 - NEW)
+
+> **Reference:** `aprendizado/32-ANATOMIA-AGENTE-100-PORCENTO-REPLICAVEL.md`
+> **Principle:** An agent without operational infrastructure is a persona without process.
+
+```yaml
+operational_completeness_checks:
+  # ═══════════════════════════════════════════════════════════════
+  # TASK FILES — Every operational command must have a task file
+  # ═══════════════════════════════════════════════════════════════
+
+  - id: task-files-exist
+    check: "Each operational command has a corresponding task file"
+    type: blocking
+    validation: |
+      For each command in commands where loader != null:
+        assert file_exists(command_loader[command].requires[0])
+    veto_if_fail: "Command without task file = LLM will improvise every execution"
+
+  - id: task-files-have-steps
+    check: "Each task file has 3+ steps with actions"
+    type: blocking
+    validation: "count(steps) >= 3 for each task file"
+    veto_if_fail: "Task without steps is decoration, not process"
+
+  - id: task-files-have-veto
+    check: "Each task file has at least 1 veto condition"
+    type: blocking
+    validation: "count(veto_conditions) >= 1 for each task file"
+    veto_if_fail: "Task without veto allows incomplete work to pass (PV004)"
+
+  # ═══════════════════════════════════════════════════════════════
+  # TEMPLATES — Structured outputs need templates
+  # ═══════════════════════════════════════════════════════════════
+
+  - id: templates-exist
+    check: "Commands that produce structured output have template"
+    type: recommended
+    validation: |
+      For commands that generate reports/analysis/documents:
+        assert template file exists or inline format defined
+
+  - id: templates-have-sections
+    check: "Templates define required sections"
+    type: recommended
+    validation: "Each template lists mandatory sections"
+
+  # ═══════════════════════════════════════════════════════════════
+  # CHECKLISTS — At least 1 with veto conditions
+  # ═══════════════════════════════════════════════════════════════
+
+  - id: checklist-exists
+    check: "Agent has at least 1 operational checklist"
+    type: blocking
+    validation: "count(checklists in dependencies) >= 1"
+    veto_if_fail: "Without checklist, no systematic validation of outputs"
+
+  - id: checklist-has-blocking
+    check: "Checklist has blocking items with veto conditions"
+    type: recommended
+    validation: "Checklist has items with type: blocking"
+
+  # ═══════════════════════════════════════════════════════════════
+  # DEPENDENCIES INTEGRITY — Everything referenced exists
+  # ═══════════════════════════════════════════════════════════════
+
+  - id: dependencies-files-exist
+    check: "ALL files listed in dependencies actually exist on disk"
+    type: blocking
+    validation: |
+      For each file in dependencies.tasks + dependencies.templates + dependencies.checklists:
+        assert file_exists("{base_path}/{file}")
+    veto_if_fail: "Referencing non-existent files = broken command execution"
+
+  - id: dependencies-match-loader
+    check: "All command_loader.requires files are in dependencies"
+    type: blocking
+    validation: |
+      required_files = flatten(command_loader[*].requires)
+      dependency_files = flatten(dependencies[*])
+      assert required_files is subset of dependency_files
+
+  # ═══════════════════════════════════════════════════════════════
+  # MATURITY SCORE
+  # ═══════════════════════════════════════════════════════════════
+
+  - id: maturity-score
+    check: "Agent maturity score >= 7.0 (Nivel 3)"
+    type: blocking
+    formula: |
+      Score = (identity × 1.0) + (thinking_dna × 1.5) + (voice_dna × 1.5)
+            + (output_examples >= 3 × 1.0) + (command_loader × 1.5)
+            + (tasks_coverage × 1.5) + (templates × 1.0)
+            + (checklists × 0.5) + (data_files × 0.5)
+      Max = 10.0
+    threshold: 7.0
+    levels:
+      '0.0-3.9': 'Nivel 1 — Persona only (FAIL)'
+      '4.0-6.9': 'Nivel 2 — Frameworks only (CONDITIONAL)'
+      '7.0-8.9': 'Nivel 3 — Complete (PASS)'
+      '9.0-10.0': 'Nivel 3+ — Integrated (EXCELLENT)'
+```
+
+---
+
+## Level 6: Integration (All Required)
+
+```yaml
+integration_checks:
+  - id: tier-position
+    check: "integration.tier_position is defined"
+    type: blocking
+
+  - id: workflow-position
+    check: "integration.workflow_integration.position_in_flow is defined"
+    type: blocking
+
+  - id: handoff-from
+    check: "integration.workflow_integration.handoff_from has 1+ items"
+    type: recommended
+    min: 1
+
+  - id: handoff-to
+    check: "integration.workflow_integration.handoff_to has 1+ items"
+    type: blocking
+    min: 1
+
+  - id: activation-greeting
+    check: "activation.greeting is defined and 50+ chars"
+    type: blocking
+    min_chars: 50
+```
+
+---
+
+## Validation Execution
+
+### Quick Validation (CLI)
+
+```bash
+# Run quality gate on agent file
+*validate-agent squads/{pack}/agents/{agent}.md
+```
+
+### Manual Validation Checklist
+
+Copy this checklist and fill in:
+
+```markdown
+## Agent Quality Gate: {agent_name}
+
+### Blocking Requirements (Must Pass)
+
+**Level 1: Identity**
+- [ ] agent.name defined
+- [ ] agent.id is kebab-case
+- [ ] agent.tier is 1-3
+- [ ] agent.whenToUse is descriptive
+- [ ] persona complete (role, style, identity, focus)
+
+**Level 2: Operational**
+- [ ] core_principles has 5-9 items
+- [ ] operational_frameworks has 1+ framework
+- [ ] Each framework has name, philosophy, steps, examples
+- [ ] commands has 5+ items including *help, *exit
+
+**Level 3: Voice DNA**
+- [ ] vocabulary.always_use has 5+ terms
+- [ ] vocabulary.never_use has 3+ terms
+
+**Level 4: Quality**
+- [ ] output_examples has 3+ complete examples
+- [ ] anti_patterns.never_do has 5+ items
+- [ ] completion_criteria.task_done_when defined
+- [ ] completion_criteria.handoff_to has 1+ items
+
+**Level 6: Integration**
+- [ ] integration.tier_position defined
+- [ ] workflow_integration.position_in_flow defined
+- [ ] handoff_to has 1+ items
+- [ ] activation.greeting defined (50+ chars)
+
+**Operational Completeness (SC_AGT_004)**
+- [ ] Task file exists for each operational command
+- [ ] Each task file has 3+ steps
+- [ ] Each task file has 1+ veto conditions
+- [ ] At least 1 checklist with blocking items
+- [ ] ALL dependency files exist on disk
+- [ ] command_loader.requires matches dependencies
+- [ ] Maturity score >= 7.0
+
+### Recommended Requirements (Should Pass)
+
+- [ ] persona.background has 3+ paragraphs
+- [ ] sentence_starters has 5+ patterns
+- [ ] metaphors has 3+ metaphors
+- [ ] behavioral_states has 2+ states
+- [ ] signature_phrases has 5+ phrases
+- [ ] red_flags_in_input has 2+ items
+- [ ] validation_checklist has 3+ items
+- [ ] objection_algorithms has 3+ objections
+- [ ] Agent file has 800+ lines
+- [ ] Templates exist for structured output types
+- [ ] Checklists have blocking items with veto conditions
+
+### Domain-Specific (If Applicable)
+
+For Copy/Legal/Storytelling/Data:
+- [ ] authority_proof_arsenal.achievements has 3+ items
+- [ ] publications defined
+- [ ] testimonials has 1+ items
+
+### Result
+
+**Blocking:** ___/24 passed
+**Recommended:** ___/11 passed
+**Maturity Score:** ___/10
+**Maturity Level:** Nivel ___
+**Total Score:** ___%
+
+**Decision:** [ ] PASS - Ready for publication (Nivel 3+)
+              [ ] CONDITIONAL - Pass with documented gaps (Nivel 2)
+              [ ] FAIL - Must fix blocking items (Nivel 1)
+```
+
+---
+
+## Scoring
+
+| Score | Result | Action |
+|-------|--------|--------|
+| 100% Blocking + 80%+ Recommended | EXCELLENT | Publish |
+| 100% Blocking + 50-79% Recommended | GOOD | Publish with note |
+| 100% Blocking + <50% Recommended | CONDITIONAL | Document gaps, publish |
+| <100% Blocking | FAIL | Fix before publish |
+
+---
+
+## Integration with Workflow
+
+This checklist is automatically invoked at:
+
+```
+research-then-create-agent workflow
+    ↓
+[Phase 6: Framework Extraction]
+    ↓
+[Phase 7: Agent Definition]
+    ↓
+[Phase 8: QUALITY GATE] ← THIS CHECKLIST
+    ↓
+    ├── PASS → Continue to task creation
+    └── FAIL → Loop back to fix issues
+```
+
+---
+
+**Version:** 4.0.0
+**Created:** 2026-01-30
+**Updated:** 2026-02-04
+**Standard:** AIOX Agent Quality Level + Operational Completeness
+**Changelog:**
+- v4.0: Added SC_AGT_004 (Operational Completeness), maturity scoring, task/template/checklist validation
+- v3.0: Added Level 0 loader checks
+- v2.0: Initial hybrid loader architecture

package/template/.aiox-core/development/checklists/brownfield-compatibility-checklist.md

@@ -0,0 +1,114 @@
+# Brownfield Compatibility Checklist
+
+> Story AIOX-DIFF-4.3.2: Checklist formal de compatibilidade retroativa
+
+## Pre-Migration Compatibility Check
+
+### 1. Source Control Status
+- [ ] All changes committed to version control
+- [ ] Working branch created from main/master
+- [ ] Remote backup verified (push before migration)
+
+### 2. Existing Configuration Preservation
+- [ ] `.env` files backed up (never overwritten by AIOX)
+- [ ] `package.json` scripts preserved
+- [ ] Existing linting config (.eslintrc, .prettierrc) detected
+- [ ] CI/CD workflows (.github/workflows) inventoried
+
+### 3. Dependency Compatibility
+- [ ] Node.js version compatible (>=18)
+- [ ] No conflicting global dependencies
+- [ ] Lock file (package-lock.json/yarn.lock) preserved
+
+### 4. Directory Structure Analysis
+- [ ] `docs/` directory status checked (empty/existing)
+- [ ] `.aiox-core/` not present (fresh install)
+- [ ] No naming conflicts with AIOX directories
+
+## During Migration Checks
+
+### 5. Non-Destructive Operations
+- [ ] AIOX creates new files, never overwrites existing
+- [ ] Merge conflicts surfaced for user decision
+- [ ] Original files preserved with `.backup` if conflict
+
+### 6. Configuration Merge Strategy
+- [ ] Existing `.gitignore` entries preserved + AIOX entries added
+- [ ] TypeScript config extended (not replaced) if existing
+- [ ] ESLint rules merged (not overwritten)
+
+### 7. Rollback Points
+- [ ] Pre-migration commit hash recorded
+- [ ] AIOX files clearly identified (can be removed cleanly)
+- [ ] No modifications to existing source code during install
+
+## Post-Migration Validation
+
+### 8. Existing Functionality
+- [ ] `npm test` passes (if tests existed before)
+- [ ] `npm run build` succeeds (if build existed)
+- [ ] Application starts normally
+
+### 9. AIOX Integration
+- [ ] `npx aiox-core doctor` reports healthy
+- [ ] Agent activation works (@dev, @architect, etc.)
+- [ ] Existing docs not duplicated
+
+### 10. Rollback Verification
+- [ ] `git diff HEAD~1` shows only AIOX additions
+- [ ] `git checkout HEAD~1 -- .` would restore pre-AIOX state
+- [ ] No orphaned AIOX processes or files
+
+---
+
+## Compatibility Matrix
+
+| Existing Config | AIOX Behavior | User Action Required |
+|-----------------|---------------|---------------------|
+| `.eslintrc.*` | Detect + preserve | None |
+| `.prettierrc.*` | Detect + preserve | None |
+| `tsconfig.json` | Extend (not replace) | Review extends |
+| `jest.config.*` | Detect + preserve | None |
+| `docs/*.md` | Skip (don't overwrite) | Manual merge if needed |
+| `.github/workflows/*` | Inventory only | User decides integration |
+| `package.json` scripts | Preserve all | None |
+
+## Rollback Procedure
+
+If migration fails or is unwanted:
+
+```bash
+# Option 1: Full rollback to pre-migration state
+git checkout HEAD~1 -- .
+
+# Option 2: Remove only AIOX files
+rm -rf .aiox-core/
+rm -rf docs/architecture/ docs/prd/ docs/stories/
+# Review and revert .gitignore AIOX entries
+
+# Option 3: Soft rollback (keep docs, remove runtime)
+rm -rf .aiox-core/
+```
+
+---
+
+## Checklist Usage
+
+**Pre-Migration:**
+```bash
+# Run compatibility check
+npx aiox-core doctor --pre-migration
+```
+
+**Post-Migration:**
+```bash
+# Validate migration
+npx aiox-core doctor
+npm test  # if tests exist
+npm run build  # if build exists
+```
+
+---
+
+*AIOX Brownfield Compatibility Checklist v1.0*
+*Story AIOX-DIFF-4.3.2*

package/template/.aiox-core/development/checklists/issue-triage-checklist.md

@@ -0,0 +1,35 @@
+# Issue Triage Checklist
+
+## Per-Issue Checklist
+
+For each issue being triaged, verify:
+
+### Classification
+- [ ] Issue has been read and understood
+- [ ] ONE `type:` label applied (bug/feature/enhancement/docs/test/chore)
+- [ ] ONE `priority:` label applied (P1/P2/P3/P4)
+- [ ] At least ONE `area:` label applied
+- [ ] `status: needs-triage` removed
+
+### Status Resolution
+- [ ] Status set to `status: confirmed` OR `status: needs-info`
+- [ ] If `status: needs-info` — comment posted asking for specific details
+- [ ] If duplicate — labeled `duplicate`, closed with reference to original issue
+
+### Community
+- [ ] Assessed for `community: good first issue` (clear scope, isolated, well-documented)
+- [ ] Assessed for `community: help wanted` (valid but team lacks bandwidth)
+
+### Quality
+- [ ] Issue has sufficient information to act on (or `status: needs-info` applied)
+- [ ] Related issues cross-referenced if applicable
+- [ ] No sensitive information in issue (API keys, credentials)
+
+## Session Checklist
+
+After completing a triage session:
+
+- [ ] All `status: needs-triage` issues reviewed
+- [ ] Triage report generated
+- [ ] Story GHIM-001 updated with triage count
+- [ ] High-priority issues (P1/P2) flagged for immediate attention