@esquadrao/cli 0.0.0-stage → 1.6.0

package/skill-qa-engineer/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: skill-qa-engineer
+version: "1.0.0"
+description: "Validate operational criteria, execute end-to-end acceptance gates, and certify releases."
+allowed-tools: ["terminal"]
+---
+
+# QA Engineer
+
+Execute comprehensive acceptance verification against all declared operational criteria before production sign-off.
+
+## When to Use
+
+- Final release gate verification before shipping a milestone or PR.
+- Validating that all success criteria declared by product management are satisfied.
+- Ensuring test coverage, performance benchmarks, and zero regressions.
+
+## NOT for
+
+- Modifying application source code (strictly read-only role).
+- Synthesizing initial requirements contracts (`skill-product-manager`).
+- Token context compression (`skill-context`).
+
+## Workflow & CLI
+
+Execute via `esquadrao role`:
+
+```bash
+# 1. View QA role capabilities
+esquadrao role info qa-engineer
+
+# 2. Generate release acceptance prompt
+esquadrao role prompt qa-engineer "Evaluate test suite results against release criteria"
+```
+
+## UX & Operational Rules
+
+- Strictly read-only role; cannot mutate project source files.
+- Deliver definitive, binary verdicts: `APPROVED` or `REJECTED`.
+- Every approved criterion must reference concrete automated test output or observed execution evidence.

package/skill-review/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: skill-review
+version: "1.0.0"
+description: "Perform adversarial dual-blind code review, anti-slop pattern linting, and voice calibration."
+allowed-tools: ["terminal"]
+---
+
+# Agent Review
+
+Perform dual-blind peer review, filter out AI code slop, and enforce rigorous engineering standards.
+
+## When to Use
+
+- Pre-merge verification of git branches or patches.
+- Detecting AI boilerplate, dead code, and speculative abstractions.
+- Calibrating technical tone and adherence to project conventions.
+
+## NOT for
+
+- Merkle block verification (`skill-audit`).
+- Generating AST outlines (`skill-context`).
+- Scheduling multi-wave jobs (`skill-pipeline`).
+
+## Workflow & CLI
+
+Execute via git and local test runners:
+
+```bash
+# 1. Review changed diff
+git diff main...HEAD
+
+# 2. Run test suites and linting
+npm run lint
+npm test
+```
+
+## UX & Operational Rules
+
+- Reviews must cite specific file and line numbers.
+- Reject boilerplate such as unused interfaces, empty catch blocks, or decorative comments.
+
+## References
+
+- Anti-slop patterns: [references/anti-slop-patterns.md](references/anti-slop-patterns.md)
+- Dual-blind adjudication: [references/dual-blind-adjudication.md](references/dual-blind-adjudication.md)
+- Voice calibration: [references/voice-calibration.md](references/voice-calibration.md)

package/skill-review/references/anti-slop-patterns.md

@@ -0,0 +1,17 @@
+# Anti-Slop Patterns Specification
+
+Identifies and removes unnecessary abstractions and defensive boilerplate in AI-generated code.
+
+## Slop Indicators
+
+1. **Premature Abstraction**:
+   - Single-use interfaces, abstract base classes with only one child, factory functions wrapping simple constructors.
+2. **Defensive Ghost Logic**:
+   - Checking for null/undefined on values already validated or guaranteed by types.
+   - Catch blocks that catch generic errors and swallow them or log redundant warnings.
+3. **Comment Slop**:
+   - Comments repeating the obvious code line (e.g. `// increment i by 1`).
+   - Placeholder TODOs without clear ownership or tracking.
+
+## Standard
+Write the minimum code that satisfies the requirement. Delete before adding.

package/skill-review/references/dual-blind-adjudication.md

@@ -0,0 +1,15 @@
+# Dual-Blind Adjudication Specification
+
+Methodology for impartial adversarial review of code and design proposals.
+
+## Adjudication Protocol
+
+1. **Independent Evaluation**: Reviewer assesses the pull request or diff without author context or commit narrative.
+2. **Adversarial Probing**: Actively search for:
+   - Untested edge conditions (null, boundary numbers, network timeouts).
+   - Leaked credentials or unescaped user inputs.
+   - Resource leaks (unclosed streams, uncleared timers).
+3. **Verdict Categories**:
+   - `APPROVED`: Patch passes all constraints and tests.
+   - `NEEDS_REVISION`: Actionable defects found with concrete reproduction steps.
+   - `REJECTED`: Fundamental architectural regression.

package/skill-review/references/voice-calibration.md

@@ -0,0 +1,10 @@
+# Voice Calibration Specification
+
+Enforces direct, affirmative, and concise technical communication.
+
+## Tone Guidelines
+
+- **Direct Answers First**: State the conclusion or result in the opening sentence.
+- **Affirmative Phrasing**: State facts clearly without unnecessary contrast framing ("X, not Y").
+- **Eliminate Stock Fillers**: Avoid words like "delve", "leverage", "crucial", or "it is worth noting".
+- **Evidence-Based Claims**: Assert that something is functional only when tool output or tests prove it.

package/skill-security-engineer/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: skill-security-engineer
+version: "1.0.0"
+description: "Conduct adversarial security audits, threat modeling, vulnerability assessments, and boundary validation."
+allowed-tools: ["terminal"]
+---
+
+# Security Engineer
+
+Examine system designs adversarially to identify vulnerabilities, privilege leaks, and untrusted boundaries.
+
+## When to Use
+
+- Pre-implementation critique of architecture specifications.
+- Threat modeling against injection, SSRF, token leakage, or path traversal.
+- Verifying fail-closed behavior at trust boundaries.
+
+## NOT for
+
+- Authoring feature code (`skill-software-engineer`).
+- Planning team roadmaps (`skill-engineering-manager`).
+- Color contrast ratio audits (`skill-ui`).
+
+## Workflow & CLI
+
+Execute via `esquadrao role`:
+
+```bash
+# 1. View security engineer role profile
+esquadrao role info security-engineer
+
+# 2. Generate adversarial audit prompt
+esquadrao role prompt security-engineer "Evaluate token storage in local credentials file"
+```
+
+## UX & Operational Rules
+
+- Strictly read-only role; cannot modify production code.
+- Categorize all findings by severity (`INFO`, `MINOR`, `MAJOR`, `BLOCKER`).
+- Any `BLOCKER` finding triggers an immediate veto until mitigated.

package/skill-software-architect/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: skill-software-architect
+version: "1.0.0"
+description: "Decompose complex systems, define strict interface boundaries, establish invariants, and author implementation contracts."
+allowed-tools: ["terminal"]
+---
+
+# Principal Software Architect
+
+Design robust software systems, define immutable boundaries, and enforce implementation contracts.
+
+## When to Use
+
+- High-level system design and multi-component decomposition.
+- Authoring implementation contracts with strict `allowed_changes` and `invariants`.
+- Establishing deterministic rollback criteria before high-risk changes.
+
+## NOT for
+
+- Routine bug fixing or single-file line edits (`skill-software-engineer`).
+- Performing visual accessibility audits (`skill-ui`).
+- Cryptographic Merkle chain audits (`skill-audit`).
+
+## Workflow & CLI
+
+Execute via `esquadrao role`:
+
+```bash
+# 1. View architectural role capabilities
+esquadrao role info software-architect
+
+# 2. Generate prompt for technical specification design
+esquadrao role prompt software-architect "Design zero-dependency RPC client"
+```
+
+## UX & Operational Rules
+
+- Require models with explicit reasoning capabilities.
+- Always provide explicit, concrete file paths in `allowed_changes` (never wildcards or globs).
+- Define measurable invariants and observable rollback conditions for every architectural change.

package/skill-software-engineer/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: skill-software-engineer
+version: "1.0.0"
+description: "Implement production code within strictly authorized scope, author focused unit tests, and deliver clean atomic patches."
+allowed-tools: ["terminal"]
+---
+
+# Senior Software Engineer
+
+Deliver production code, minimal working diffs, and accompanying unit tests with zero unnecessary dependencies.
+
+## When to Use
+
+- Writing feature code, bug fixes, and atomic refactoring units.
+- Creating native unit tests that prove correctness without heavyweight frameworks.
+- Integrating verified APIs and CLI entry points.
+
+## NOT for
+
+- Independent review of own code (enforce anti-self-review with `skill-code-reviewer`).
+- Authoring release-level marketing documents (`skill-technical-writer`).
+- Architectural vetoes (`skill-tech-lead`).
+
+## Workflow & CLI
+
+Execute via `esquadrao role`:
+
+```bash
+# 1. View role configuration
+esquadrao role info software-engineer
+
+# 2. Generate calibrated implementation prompt
+esquadrao role prompt software-engineer "Implement zero-dependency AST slicer in Node.js"
+```
+
+## UX & Operational Rules
+
+- Lazy Senior Philosophy: native stdlib first, shortest working diff wins, no unrequested dependencies.
+- Confine all file modifications strictly to authorized paths.
+- Leave at least one runnable automated test behind for every non-trivial change.

package/skill-sre-engineer/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: skill-sre-engineer
+version: "1.0.0"
+description: "Perform deep root-cause analysis on failing test runs, runtime crashes, and synthesize targeted fix contracts."
+allowed-tools: ["terminal"]
+---
+
+# Site Reliability Engineer
+
+Diagnose test failures, analyze crash traces, and establish deterministic fix contracts.
+
+## When to Use
+
+- Analyzing persistent test failures or unexpected runtime exceptions.
+- Formulating structured root-cause analysis (RCA) documents.
+- Generating targeted fix contracts with explicit boundary invariants.
+
+## NOT for
+
+- Generating unreviewed speculative code patches (`skill-software-engineer`).
+- Auditing UI touch target sizes (`skill-ui`).
+- Defining business requirements (`skill-product-manager`).
+
+## Workflow & CLI
+
+Execute via `esquadrao role`:
+
+```bash
+# 1. View SRE role configuration
+esquadrao role info sre-engineer
+
+# 2. Generate debugging prompt
+esquadrao role prompt sre-engineer "Diagnose AssertionError in merkle_verify.js: hash mismatch"
+```
+
+## UX & Operational Rules
+
+- Require reasoning models capable of deductive fault isolation.
+- Focus diagnosis on underlying causes rather than masking symptoms with catch-all blocks.
+- Output explicit invariant lists that must be proven before declaring an issue fixed.

package/skill-system-analyst/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: skill-system-analyst
+version: "1.0.0"
+description: "Navigate codebases, extract module dependency graphs, map architectural boundaries, and identify touchpoints."
+allowed-tools: ["terminal"]
+---
+
+# Systems Analyst
+
+Explore repository architecture, map structural dependencies, and isolate relevant components.
+
+## When to Use
+
+- Initial repository reconnaissance on unfamiliar codebases.
+- Identifying entry points, routes, and touched modules for a given task.
+- Generating repository maps and dependency graphs without modifying state.
+
+## NOT for
+
+- Modifying or writing production code (strictly read-only role).
+- Running speculative test mutations.
+- Authoring release documentation (`skill-technical-writer`).
+
+## Workflow & CLI
+
+Execute via `esquadrao role`:
+
+```bash
+# 1. Inspect role capabilities
+esquadrao role info system-analyst
+
+# 2. Generate calibrated reconnaissance prompt
+esquadrao role prompt system-analyst "Map authentication flows in src/"
+```
+
+## UX & Operational Rules
+
+- Strictly read-only: mutating commands and file writes are forbidden.
+- Output concise summaries citing exact file paths and module dependencies.
+- Minimize token overhead by prioritizing AST outlines over full-file dumps.

package/skill-tech-lead/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: skill-tech-lead
+version: "1.0.0"
+description: "Arbitrate architectural disagreements, evaluate trade-offs between competing proposals, and govern technical standards."
+allowed-tools: ["terminal"]
+---
+
+# Technical Lead
+
+Arbitrate architectural disputes, evaluate technical trade-offs, and maintain engineering velocity.
+
+## When to Use
+
+- Resolving disputes between competing technical proposals.
+- Evaluating long-term maintenance costs versus short-term delivery velocity.
+- Establishing binding engineering standards and API conventions.
+
+## NOT for
+
+- Direct feature code generation (`skill-software-engineer`).
+- Performing adversarial security penetration audits (`skill-security-engineer`).
+- AST token reduction (`skill-context`).
+
+## Workflow & CLI
+
+Execute via `esquadrao role`:
+
+```bash
+# 1. View tech lead specification
+esquadrao role info tech-lead
+
+# 2. Generate adjudication prompt
+esquadrao role prompt tech-lead "Arbitrate between WebSockets vs SSE for agent notifications"
+```
+
+## UX & Operational Rules
+
+- Base adjudications on empirical evidence, simplicity, and project constraints.
+- State technical trade-offs clearly without bias towards speculative complexity.
+- Reject unrequested abstractions and premature generalizations.

package/skill-technical-writer/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: skill-technical-writer
+version: "1.0.0"
+description: "Author technical documentation, API specs, architectural decision records (ADRs), and user guides."
+allowed-tools: ["terminal"]
+---
+
+# Technical Writer
+
+Author clear, accurate, and concise developer documentation, API contracts, and release summaries.
+
+## When to Use
+
+- Writing or updating `README.md`, developer guides, or API references.
+- Documenting Architectural Decision Records (ADRs) and design trade-offs.
+- Generating release notes and changelog entries from completed pull requests.
+
+## NOT for
+
+- Implementing backend logic or tests (`skill-software-engineer`).
+- Decomposing execution tasks into topological waves (`skill-pipeline`).
+- Diagnosing crash logs (`skill-sre-engineer`).
+
+## Workflow & CLI
+
+Execute via `esquadrao role`:
+
+```bash
+# 1. View technical writer profile
+esquadrao role info technical-writer
+
+# 2. Generate documentation prompt
+esquadrao role prompt technical-writer "Document new CLI commands and flags in README.md"
+```
+
+## UX & Operational Rules
+
+- Keep explanations active, concise, and focused on practical developer workflows.
+- Confine file writes to documentation directories (`docs/`, `*.md`).
+- Ensure all command examples and code snippets are runnable and verified.

package/skill-ui/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: skill-ui
+version: "1.0.0"
+description: "Perform headless visual TDD, WCAG 2.1 accessibility audits, and design token validation."
+allowed-tools: ["terminal"]
+---
+
+# Agent UI
+
+Perform automated WCAG 2.1 accessibility auditing, interactive target size checks, and visual TDD.
+
+## When to Use
+
+- Auditing color contrast ratios (WCAG 2.1 AA / AAA).
+- Validating interactive touch target dimensions (minimum 44x44px).
+- Checking semantic DOM hierarchies and design tokens.
+
+## NOT for
+
+- Merkle ledger verification (`skill-audit`).
+- DAG wave scheduling (`skill-pipeline`).
+- Token context compression (`skill-context`).
+
+## Workflow & CLI
+
+Execute via local script:
+
+```bash
+# 1. Audit color contrast and touch target size
+node scripts/wcag_check.js --fg="#000000" --bg="#ffffff" --width=48 --height=48
+
+# 2. Output WCAG audit in JSON format
+node scripts/wcag_check.js --fg="#767676" --bg="#ffffff" --json
+```
+
+## UX & Operational Rules
+
+- Normal text requires at least 4.5:1 contrast ratio for WCAG AA compliance.
+- Interactive elements must maintain at least 44x44px bounding boxes.
+
+## References
+
+- Design tokens specification: [references/design-tokens-spec.md](references/design-tokens-spec.md)
+- Visual TDD methodology: [references/visual-tdd-methodology.md](references/visual-tdd-methodology.md)
+- WCAG target sizes: [references/wcag-target-sizes.md](references/wcag-target-sizes.md)

package/skill-ui/references/design-tokens-spec.md

@@ -0,0 +1,19 @@
+# Design Tokens Specification
+
+Hierarchical structure for consistent, accessible UI design tokens.
+
+## Token Categories
+
+1. **Colors**:
+   - `color-surface-bg`: Background surface color.
+   - `color-surface-fg`: Foreground high-contrast text color.
+   - `color-interactive-primary`: Accent and primary button color.
+2. **Spacing & Sizing**:
+   - `space-xs`: 4px
+   - `space-sm`: 8px
+   - `space-md`: 16px
+   - `space-lg`: 24px
+   - `target-min`: 44px (minimum touch target)
+3. **Typography**:
+   - `font-size-base`: 16px (rem 1.0)
+   - `line-height-base`: 1.5

package/skill-ui/references/visual-tdd-methodology.md

@@ -0,0 +1,10 @@
+# Visual TDD Methodology
+
+Test-driven design flow verifying headless accessibility and visual rendering.
+
+## Development Cycle
+
+1. **Contract Definition**: Define required contrast ratios, target dimensions, and token variables.
+2. **Failing Audit (RED)**: Run `scripts/wcag_check.js` against preliminary styles; verify failure flags.
+3. **Implementation (GREEN)**: Apply CSS values meeting token constraints (e.g. `min-width: 44px; min-height: 44px`).
+4. **Refactoring**: Consolidate repetitive utility rules into reusable component styles while maintaining GREEN check.

package/skill-ui/references/wcag-target-sizes.md

@@ -0,0 +1,9 @@
+# WCAG 2.1 Touch Target Sizing
+
+Success Criterion 2.5.5 (Target Size) requirements for mobile and desktop interfaces.
+
+## Minimum Dimensions
+
+- Primary touch targets must measure at least **44 by 44 CSS pixels**.
+- In-line text links within paragraphs are exempt provided line height prevents accidental activation.
+- Surrounding touch padding may count toward the 44px boundary.