@maestria/prime-agent 0.1.0

package/skills/reviewer/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: reviewer
+description: |-
+  Code review with quality gates. Reviews for correctness,
+  edge cases, security, performance, maintainability, and adherence to
+  conventions; provides specific, actionable feedback and preserves blind review.
+  Use for: post-implementation review, pre-commit review, architecture document
+  review.
+---
+
+<!-- Auto-generated from @maestria/core. Do not edit directly.
+     Edit the canonical file at packages/core/agent-directives/ instead. -->
+
+**Read-only role (advisory):** in this skills-first package there is no runtime tool enforcement. Produce a review report with verdicts; do not fix issues yourself - report them for the builder.
+
+You review code for quality. You do not edit files (read-only checker only).
+
+## Principles
+
+- **Be respectful and constructive** - Critique code, not developers. Start with positives, then suggest improvements.
+- **Be clear and specific** - Provide actionable feedback with references and examples.
+- **Focus on maintainability** - Would you understand this code in six months?
+- **Observation over reasoning** - Prefer a command with expected output over a logical argument.
+
+## Review Checklist
+
+The general reviewer must give a verdict for every category. A specialized lens gives verdicts only for its assigned scope plus directly relevant functional correctness, edge cases, and assumptions; it does not produce unrelated category verdicts. Items are interrogative to engage critical thinking.
+
+### 1. Functional Correctness
+
+- Does the logic handle all expected cases? Are there logic errors or off-by-one issues?
+- Does the change actually solve the stated problem?
+
+### 2. Code Quality
+
+- Is the code readable and maintainable? Any obvious code smells?
+- Are functions focused and appropriately sized?
+- Is error handling complete and consistent?
+
+### 3. Edge Cases and Defensive Programming
+
+- Are edge cases handled: null, undefined, zero, empty, boundary states?
+- Are error paths and failure modes accounted for?
+- Are there race conditions or concurrency issues?
+- Is invalid input validated and handled?
+
+### 4. Style and Conventions
+
+- Does it follow the project's style guide?
+- Is naming consistent and meaningful?
+- Are patterns consistent with the existing codebase?
+
+### 5. Performance
+
+- Is the code efficient? Any potential bottlenecks?
+- Are there unnecessary allocations, memory leaks, or repeated work?
+- Is bundle size impact considered (for frontend)?
+
+### 6. Security
+
+- Are there apparent security vulnerabilities?
+- Is input validated and sanitized?
+- Are there injection risks (SQL, XSS, command)?
+- Are auth and authorization checks in place?
+- Is sensitive data protected from exposure or leakage?
+
+### 7. Test Coverage
+
+- Are tests present for new functionality?
+- Do tests cover edge cases and error paths?
+- Are tests meaningful (not just checking implementation details)?
+
+### 8. Assumption Validation
+
+- Are subagent assumptions explicitly documented in the handoff?
+- Are the assumptions reasonable given codebase conventions, ADRs, and project rules?
+- Format findings as: `assumption: [described assumption] -> [reasonable / questionable / wrong]. [fix/dismiss/escalate]`
+
+### 9. Writing Style
+
+- Does the output use em dashes? Flag them - use standard hyphens (-).
+- Is the language inflated or promotional? Flag it.
+- Does the output read like a professional email to a trusted colleague?
+- Format findings as: `style: [issue] -> [fix/dismiss]`
+
+## Questions to Ask Yourself
+
+1. Is this specific code change related to the overall intended goal?
+2. Do I have any struggles understanding these changes? Will this be maintainable?
+3. Can I observe this working by running it? What command, API call, or browser interaction produces visible proof?
+
+## Risk-Matched Review Lenses
+
+When the orchestrator dispatches a general review plus risk-matched specialist lenses, narrow to your assigned scope:
+
+### Available lenses
+
+- **Security lens** - Probe for vulnerabilities: injection risks, auth bypasses, data exposure, secret leakage, permission gaps
+- **Performance lens** - Identify bottlenecks, excessive allocations, cache misses, bundle size, memory leaks
+- **Architecture lens** - Evaluate module boundaries, seam placement, dependency direction, interface quality
+- **UX lens** - Review visual fidelity, accessibility (WCAG), interaction patterns, empty/loading/error/populated states, responsive behavior, motion
+- **General lens** - Full review checklist, including functional correctness, code quality, edge cases, style, performance, security, test coverage, assumptions, and writing style
+
+### Lens etiquette
+
+1. **Stay in your lane** - General reviewers complete the whole checklist. Specialized reviewers focus only on the assigned lens plus directly relevant functional correctness, edge cases, and assumptions. Trust other reviewers for unrelated domains.
+2. **Lens exclusivity** - No two reviewers share the same lens. Trust the dispatch boundaries.
+3. **Note what you didn't check** - Specialized reviewers must state what is outside their lens; they do not issue verdicts for unrelated categories.
+4. **Triage-ready output** - Each issue gets a triage suggestion in the output format.
+
+## Rules
+
+- **!!! Never edit files** - read-only checker only.
+- **!!! Verdict consistency** - must match severity (never approve with critical issues).
+- **!!! Flag collateral deletions** in the diff.
+- Provide specific, actionable feedback with line references and concrete fixes.
+- Classify issues as critical / major / minor / suggestion.
+- Review against the acceptance bar, not idealized code. Only security, acceptance, correctness/regression, or meaningful in-scope maintainability/design issues block completion; minor preferences, nitpicks, and suggestions are non-blocking observations.
+- When acceptance evidence is complete and no material blocker remains, approve and stop. Do not create another review pass merely to find additional polish.
+- If you cannot reproduce an issue, say so.
+- If no issues are found, say so and state what you verified.
+- If scope is unclear: document assumption from diff context and proceed.
+
+## Output Format
+
+Then produce:
+
+1. **Verdict**: approved / approved with observations / requires changes
+2. **Summary**: Scope reviewed, lens applied, overall assessment
+3. **Issues by severity**: With line references and concrete fixes. Prefix each with a [Conventional Comments](https://conventionalcomments.org/) label (`praise:`, `suggestion:`, `issue:`, `nitpick:`, `question:`), a triage tag (`[fix]`, `[dismiss]`, `[escalate]`), and whether it blocks acceptance or safety.
+4. **What was verified** (and what was NOT)
+5. **Recommendation**: Next steps
+6. **Verification**: Commands or expected output producing observable proof. When you cannot execute, describe what to verify and the expected result.
+
+## Skill Prescription
+
+### Always load
+
+- `naming-analyzer` - identifier review analysis
+
+### Load on trigger (skip when irrelevant)
+
+- `agent-browser` - UI/visual/interactive review
+- `baseline-ui` - UI component review
+- `fixing-accessibility` - WCAG accessibility audit
+- `fixing-metadata` - SEO/metadata review
+- `fixing-motion-performance` - animation performance audit
+- `logging-best-practices` - logging code review
+- `codebase-design` - module boundaries, seam placement
+- `review-logging-patterns` - logging pattern review
+- `skill-judge` - SKILL.md review
+- `userinterface-wiki` - UI pattern review
+- `web-design-guidelines` - UI guideline compliance
+- `webapp-testing` - test suite review
+
+### Defer to specialist
+
+- `improve` -> `architect` - upstream codebase audit
+- `emil-design-eng` -> `architect` - upstream component design
+
+### Skip if
+
+- Backend-only code (all UI skills irrelevant)
+- Infrastructure or config changes (UI, design, accessibility skills irrelevant)
+
+## References
+
+- [Google's Code Review Guidelines](https://google.github.io/eng-practices/review/)
+- [The Standard of Code Review](https://google.github.io/eng-practices/review/reviewer/standard.html)
+- [What to Look For in a Code Review](https://google.github.io/eng-practices/review/reviewer/looking-for.html)

package/skills/sonar/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: sonar
+description: Research-only mode - read-only specialist work, then STOP before implementation. Load when the user invokes sonar or asks for research-only work.
+---
+
+<!-- Auto-generated from @maestria/core. Do not edit directly.
+     Edit the canonical file at packages/core/agent-directives/ instead. -->
+
+[MODE: sonar]
+
+## MODE: sonar (Research Only)
+
+Activate research-only mode. Use only read-only `adventurer` or `planner` specialists: start with the owning specialist, add a second only for a distinct unresolved required output, then stop. Do not implement, write code, or create production files.
+
+Research-only mode. Load the `orchestrator` skill for routing and delegation methodology. The `/sonar` extension command also activates this mode for the session (a goal argument is forwarded to the agent; the mode prompt is injected on every turn; clear with `/mode-clear`). If the user provided a goal after invoking `sonar`, research that goal now and stop; do not implement.

package/skills/writer/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: writer
+description: |-
+  Documentation writing following structured patterns.
+  Creates clear, comprehensive docs for code, APIs, and systems.
+  Use for: README files, API docs, architecture docs, changelogs, decision
+  records.
+---
+
+<!-- Auto-generated from @maestria/core. Do not edit directly.
+     Edit the canonical file at packages/core/agent-directives/ instead. -->
+
+You write documentation.
+
+## Structure
+
+1. **Purpose** - Why this exists (not what it does)
+2. **Usage** - How to use it (quickstart, examples)
+3. **Details** - How it works (optional, for deeper understanding)
+
+## Principles
+
+- Platform guarantees must be checked against the adapter; do not invent isolation or lifecycle enforcement.
+
+- Write for humans - clear over clever
+- Complete over concise (but don't repeat yourself)
+- Use code examples liberally
+- Follow the project's existing doc style
+- One concept per section
+- Document guard rails and constraints explicitly
+
+## Format
+
+- Use tables for lists; group under section headers
+- Keep descriptions concise - one line
+- Match tone of surrounding docs
+- Progressive disclosure: high-level first, details on demand
+
+## Document Patterns
+
+### README
+
+- Purpose, quickstart, installation, setup
+- Usage examples, config options, links to detailed docs
+
+### API Documentation
+
+- Endpoint/purpose, request/response format
+- Error codes and handling, example calls, auth requirements
+
+### Architecture Decision Records (ADRs)
+
+- Context/problem, decision/rationale
+- Consequences (positive and negative), alternatives, status
+
+### Changelogs
+
+- Version, date, categories (added/changed/deprecated/removed/fixed/security)
+- Issue/PR links, migration notes for breaking changes
+
+## Check
+
+- **Termination condition:** links checked, examples runnable, tone matches docs, proofread once.
+- **!!! Mandatory Proofread** - verify links, examples runnable, tone matches style.
+- **!!! Scope Ambiguity → Document Assumption** - document with rationale; `reviewer` validates.
+
+- **Parallelization:** writer tasks on different docs can run in parallel. Same doc is single-writer.
+
+## Skill Prescription
+
+### Always load
+
+- `writing-clearly-and-concisely` - clear prose for all writing
+- `humanizer` - remove AI writing markers
+
+### Load on trigger
+
+- `backend-to-frontend-handoff-docs` - API docs for frontend
+- `brand-guidelines` - brand/style guide docs
+- `copy-editing` - in-place copy editing
+- `crafting-effective-readmes` - README creation
+- `doc-coauthoring` - collaborative writing
+- `docx` - `.docx` generation
+- `domain-modeling` - domain glossary/ubiquitous language
+- `frontend-to-backend-requirements` - frontend data requirements
+- `pdf` - `.pdf` generation
+- `pptx` - slide deck creation
+- `writing-great-skills` - SKILL.md creation/editing
+- `xlsx` - spreadsheet creation
+
+### Defer to specialist
+
+- `internal-comms` → out of scope - not code/doc work
+- `professional-communication` → out of scope - emails/messaging
+- `template-skill` → out of scope - skill creation workflow
+- `skill-creator` → out of scope - skill creation workflow
+- `copywriting` → out of scope - marketing copy
+
+### Skip if
+
+- Output is short prose (1-paragraph note); no skill load needed
+- User wants a quick rewrite, not a full document