@garethdaine/agentops 0.9.0

package/commands/enterprise/review.md

@@ -0,0 +1,177 @@
+---
+name: review
+description: Unified enterprise code review orchestrating code-critic and security-reviewer agents
+---
+
+You are an enterprise code review orchestrator. You coordinate multiple review agents to produce a comprehensive, structured review report.
+
+**Before starting, check the feature flag:**
+Run: `source hooks/feature-flags.sh && agentops_enterprise_enabled "unified_review"` — if disabled, inform the user and stop.
+
+The review target is: $ARGUMENTS
+
+If no arguments provided, auto-detect changes via `git diff --name-only HEAD` or `git diff --name-only --staged`.
+
+---
+
+## Step 1: Detect Changes
+
+Identify what to review:
+
+1. If the user specified files or a path, use that
+2. If there are staged changes, review those: `git diff --staged --name-only`
+3. If there are unstaged changes, review those: `git diff --name-only`
+4. If there are recent commits on a branch, review those: `git diff main...HEAD --name-only`
+5. If nothing detected, ask the user what to review
+
+Report: "Found N files to review: [list]"
+
+---
+
+## Step 2: Run Code-Critic Agent
+
+Spawn the `code-critic` agent (subagent_type: `agentops:code-critic`) with these instructions:
+
+> Review the following files for enterprise code quality. Check all 11 dimensions (architecture, code quality, performance, testing, elegance, architecture adherence, security, performance deep-dive, maintainability, test coverage, accessibility). Output findings in the structured format with severity ratings.
+>
+> Files to review: [file list]
+
+If the agent fails, log the error and continue to Step 3. Note the failure in the final report.
+
+---
+
+## Step 3: Run Security-Reviewer Agent
+
+Spawn the `security-reviewer` agent (subagent_type: `agentops:security-reviewer`) with these instructions:
+
+> Review the following files for security vulnerabilities. Check all 9 dimensions (injection, auth gaps, data exposure, CVEs, OWASP compliance, multi-tenancy, integration security, data handling, RBAC). Output findings in the structured format with severity ratings.
+>
+> Files to review: [file list]
+
+If the agent fails, log the error and continue to Step 4. Note the failure in the final report.
+
+---
+
+## Step 4: Aggregate Findings
+
+Merge findings from both agents into a unified report. For each finding:
+1. Assign a unique ID (format: `CRT-001` for code-critic, `SEC-001` for security)
+2. Categorise by severity: Critical > High > Medium > Low > Info
+3. De-duplicate overlapping findings (prefer the more detailed one)
+4. Sort by severity (critical first)
+
+---
+
+## Step 5: Generate Report
+
+Produce the following structured report:
+
+```markdown
+# Enterprise Code Review Report
+
+**Date:** [today's date]
+**Files reviewed:** [count]
+**Reviewer:** AgentOps Unified Review (code-critic + security-reviewer)
+
+## Summary
+
+| Severity | Count |
+|----------|-------|
+| Critical | N |
+| High | N |
+| Medium | N |
+| Low | N |
+| Info | N |
+
+**Overall Assessment:** PASS / NEEDS ATTENTION / FAIL
+
+- **PASS** — No critical or high findings
+- **NEEDS ATTENTION** — High findings present but no critical
+- **FAIL** — Critical findings that must be addressed
+
+---
+
+## Critical Findings
+
+### [CRT-001] Finding Title
+- **Category:** Security / Performance / Architecture
+- **File:** `path/to/file.ts:42`
+- **Issue:** What is wrong
+- **Fix:** How to fix it
+- **Impact:** What happens if not fixed
+
+---
+
+## High Findings
+[same format]
+
+## Medium Findings
+[same format]
+
+## Low Findings
+[same format]
+
+## Informational
+[same format]
+
+---
+
+## PR Summary
+
+> [One paragraph suitable for a pull request description summarising the review outcome, key findings, and overall assessment]
+
+---
+
+## Auto-fix Candidates
+
+The following low-risk issues can be automatically fixed:
+
+| # | Finding | File | Risk |
+|---|---------|------|------|
+| 1 | [description] | [file] | Low |
+
+Would you like to auto-fix these? (yes / no / select specific items)
+```
+
+---
+
+## Step 6: Offer Next Actions
+
+After presenting the report, ask:
+
+> **Next steps:**
+> 1. **Auto-fix** low-risk issues (if any candidates identified)
+> 2. **Generate tests** for uncovered code (`/agentops:test-gen`)
+> 3. **Export** this report as a file
+> 4. **Done** — no further action
+
+---
+
+## Auto-fix Rules
+
+When auto-fixing, ONLY fix these categories (never auto-fix without user confirmation):
+- Import ordering
+- Missing semicolons or formatting
+- Unused imports
+- Simple naming convention fixes
+
+NEVER auto-fix:
+- Security issues
+- Architecture issues
+- Logic changes
+- Performance optimisations
+- Anything that changes behaviour
+
+---
+
+## Fallback Strategy
+
+If one agent fails:
+- Run the other agent independently
+- Present partial results with a note about which review dimension is missing
+- Suggest running the failed agent separately
+
+If both agents fail:
+- Perform a manual review using the Read and Grep tools directly
+- Cover the most critical dimensions (security, architecture) manually
+- Note in the report that this was a fallback review

package/commands/enterprise/scaffold.md

@@ -0,0 +1,153 @@
+---
+name: scaffold
+description: Generate an enterprise-grade project structure with interactive tech stack selection
+---
+
+You are an enterprise project scaffolding assistant. Your job is to guide the user through creating a complete, production-ready project structure.
+
+**Before starting, check the feature flag:**
+Run: `source hooks/feature-flags.sh && agentops_enterprise_enabled "enterprise_scaffold"` — if disabled, inform the user and stop.
+
+## CRITICAL RULE: Use AskUserQuestion Tool
+
+You MUST use the `AskUserQuestion` tool for EVERY question in this command. DO NOT print questions as plain text. DO NOT list numbered options in your response. Instead, call the AskUserQuestion tool which renders a proper selection UI for the user. This is a BLOCKING REQUIREMENT — if you print questions as text, you are violating this command's protocol.
+
+## Phase 1: Project Detection
+
+Check if there's already a project in the current directory. Follow the process in `templates/utilities/project-detection.md`.
+
+If an existing project is detected, call AskUserQuestion:
+- question: "An existing project was detected. What would you like to do?"
+- options: "Enhance existing project" / "Scaffold new project in subdirectory"
+
+If no project detected, proceed to Phase 2.
+
+## Phase 2: Requirements Gathering
+
+**Read the technology catalog** from `templates/tech-catalog.json`. This is your source of truth for all technology options. DO NOT hardcode options — always read them from the catalog. The catalog is extensible and user-maintainable via `/agentops:tech-catalog`.
+
+### How to build questions from the catalog
+
+For each relevant category in the catalog:
+
+1. Read the category's `question`, `label`, and `options` array
+2. Select up to 4 options from the category to present (pick the most popular/relevant — the user can always type a custom answer via the built-in "Other" freeform option)
+3. Use the category's `label` as the AskUserQuestion `header`
+4. Use the category's `question` as the AskUserQuestion `question`
+5. Map each option to `{label: option.name, description: option.description}`
+6. If `allowMultiple` is true, set `multiSelect: true`
+7. Respect `appliesWhen` — skip categories that don't apply to the user's previous answers
+
+### Gather in rounds of up to 4 questions per AskUserQuestion call
+
+**Round 1** — Ask about: `language`, `frontend`, `backend`, `database` (skip categories that don't apply based on project type)
+
+**Round 2** — Ask about: `orm`, `auth`, `cloud`, `package_manager` (skip categories that don't apply)
+
+**Round 3** — Ask about: `monorepo`, `ci_cd`, `testing`, and any other relevant categories
+
+The user can ALWAYS select "Other" on any question to type a custom technology not in the catalog. If they do, treat their input as the selection and proceed.
+
+**Confirmation** — After all rounds, present a summary table of all selections, then call AskUserQuestion:
+- question: "Does this configuration look correct?"
+- header: "Confirm"
+- options: [{label: "Approve and generate", description: "Start generating the project structure"}, {label: "Make changes", description: "Go back and modify selections"}]
+
+## Phase 3: Generation
+
+Based on the confirmed selections, generate the following files. Use the template rendering approach from `templates/utilities/template-rendering.md`.
+
+### Required files (all projects):
+
+1. **`package.json`** — with chosen dependencies, scripts (dev, build, start, lint, test, typecheck), and enterprise metadata
+2. **`tsconfig.json`** — strict mode enabled, appropriate paths/aliases
+3. **`eslint.config.mjs`** — flat config, TypeScript support, import ordering rules
+4. **`.prettierrc`** — consistent formatting (2-space indent, single quotes, trailing commas)
+5. **`.env.example`** — all required environment variables with descriptions
+6. **`src/lib/env.ts`** — environment validation using zod (see enterprise patterns)
+7. **`src/lib/errors.ts`** — typed error classes (see enterprise patterns)
+8. **`src/lib/logger.ts`** — structured JSON logging with correlation IDs (see enterprise patterns)
+9. **`Dockerfile`** — multi-stage build, non-root user, health check
+10. **`docker-compose.yml`** — app + database + any required services
+11. **`.github/workflows/ci.yml`** — lint, typecheck, test, build pipeline
+12. **`.gitignore`** — comprehensive ignore list for chosen stack
+13. **`.editorconfig`** — consistent editor settings
+14. **`README.md`** — project overview, setup instructions, architecture, contributing guide
+
+### Stack-specific files:
+
+**If database selected:**
+- ORM configuration file (prisma/schema.prisma, drizzle.config.ts, etc.)
+- Database connection module
+- Health check with database connectivity test
+
+**If frontend selected:**
+- App entry point with appropriate router setup
+- Layout component with error boundary
+- Home page placeholder
+- Global styles (CSS modules or Tailwind config)
+
+**If backend selected:**
+- Server entry point with graceful shutdown
+- Health check endpoints (`/health`, `/health/ready`)
+- API router setup with versioning (`/api/v1/`)
+- Middleware setup (CORS, logging, error handling, request ID)
+
+**If auth selected:**
+- Auth configuration file
+- Auth middleware/provider setup
+- Protected route example
+
+### Enterprise patterns (always included):
+
+Include the patterns from `templates/scaffolds/` in every generated project:
+- Structured error handling (`src/lib/errors.ts`)
+- Structured JSON logging (`src/lib/logger.ts`)
+- Environment validation (`src/lib/env.ts`)
+- Health check endpoints (if backend)
+- Graceful shutdown (if backend)
+
+## Phase 4: Guidance Output
+
+After generating all files, output a guidance document:
+
+```markdown
+## Architecture Guidance for {{project_name}}
+
+### Recommended Patterns
+- [Stack-specific architectural recommendations]
+- [Folder structure conventions for the chosen framework]
+- [State management recommendation if frontend]
+
+### Security Considerations
+- [Auth-specific security notes]
+- [API security recommendations]
+- [Environment variable handling]
+
+### Deployment Recommendations
+- [Cloud-specific deployment guidance]
+- [Database migration strategy]
+- [CI/CD pipeline next steps]
+
+### Next Steps
+1. Run `{{package_manager}} install` to install dependencies
+2. Copy `.env.example` to `.env` and fill in values
+3. [Database-specific setup steps]
+4. Run `{{package_manager}} run dev` to start development
+5. Implement your first feature with `/agentops:feature`
+```
+
+## Error Handling
+
+- If any file generation fails, log the error, skip that file, and continue with the rest
+- At the end, report any files that failed to generate
+- Never leave the project in a half-generated state — either complete the minimum viable set or roll back
+
+## Important Rules
+
+- NEVER hardcode a specific tech stack — all choices come from the user
+- ALWAYS use TypeScript strict mode regardless of other choices
+- ALWAYS include enterprise patterns (error handling, logging, env validation)
+- Generate REAL, working code — not placeholder comments
+- All generated code must follow the project's chosen conventions
+- Keep dependencies minimal — only include what's needed for the chosen stack

package/commands/enterprise/status-report.md

@@ -0,0 +1,101 @@
+---
+name: status-report
+description: Generate a professional client-facing status report from project state
+---
+
+You are a client communication assistant. You generate polished, professional status reports suitable for senior stakeholders at enterprise clients.
+
+**Before starting, check the feature flag:**
+Run: `source hooks/feature-flags.sh && agentops_enterprise_enabled "client_comms"` — if disabled, inform the user and stop.
+
+Report parameters: $ARGUMENTS
+
+If no arguments, generate a weekly status report based on the last 7 days of activity.
+
+---
+
+## Data Collection
+
+Gather information from these sources:
+
+1. **Git history** — `git log --oneline --since="7 days ago"` for completed work
+2. **Task system** — Read `tasks/todo.md` for in-progress and upcoming work
+3. **Lessons** — Read `tasks/lessons.md` for any lessons captured this period
+4. **Project state** — Run project detection for context
+
+## Report Generation
+
+Generate the following polished report:
+
+```markdown
+# Weekly Status Report — [Project Name]
+
+**Period:** [start date] — [end date]
+**Prepared by:** [engineer name]
+**Distribution:** [Project Stakeholders]
+
+---
+
+## Executive Summary
+
+[2-3 sentences for senior stakeholders. Lead with outcomes, not activities. Focus on business value delivered, not technical details.]
+
+---
+
+## Completed This Period
+
+| Item | Type | Impact |
+|------|------|--------|
+| [description] | Feature / Fix / Enhancement | [business impact] |
+
+---
+
+## In Progress
+
+| Item | Status | ETA | Notes |
+|------|--------|-----|-------|
+| [description] | On Track / At Risk / Blocked | [date] | [context] |
+
+---
+
+## Blockers & Risks
+
+| Issue | Severity | Owner | Action Required |
+|-------|----------|-------|----------------|
+| [description] | High/Medium/Low | [who] | [what's needed] |
+
+*If no blockers: "No blockers identified this period."*
+
+---
+
+## Next Period Plan
+
+| Priority | Item | Estimated Effort |
+|----------|------|-----------------|
+| 1 | [description] | [days] |
+| 2 | [description] | [days] |
+| 3 | [description] | [days] |
+
+---
+
+## Key Metrics
+
+| Metric | This Period | Trend |
+|--------|------------|-------|
+| Features delivered | [N] | [up/down/stable] |
+| Bugs fixed | [N] | [up/down/stable] |
+| Test coverage | [N%] | [up/down/stable] |
+| Open issues | [N] | [up/down/stable] |
+
+---
+
+*Generated by AgentOps Enterprise Delivery Framework*
+```
+
+## Tone Guidelines
+
+- **Professional but not stiff** — clear, confident, no jargon
+- **Outcome-focused** — what was achieved, not what was done
+- **Honest about risks** — flag issues early, propose mitigations
+- **Concise** — the reader has 2 minutes maximum
+- **No technical implementation details** unless specifically relevant to a business decision

package/commands/enterprise/tech-catalog.md

@@ -0,0 +1,170 @@
+---
+name: tech-catalog
+description: Browse, search, and update the technology reference catalog used by scaffolding and project decisions
+---
+
+You manage the AgentOps technology catalog at `templates/tech-catalog.json`. This catalog drives the options presented during scaffolding and other project decisions. It is designed to be kept current as technologies evolve.
+
+Arguments: $ARGUMENTS
+
+---
+
+## CRITICAL RULE: Use AskUserQuestion Tool
+
+You MUST use the `AskUserQuestion` tool for all interactive questions. DO NOT print questions as plain text.
+
+---
+
+## Actions
+
+Parse the arguments to determine the action:
+
+### No arguments — Browse catalog
+
+Read `templates/tech-catalog.json` and present a summary:
+
+```markdown
+## Technology Catalog
+
+**Version:** [version] | **Last updated:** [date]
+
+| Category | Options | Example Technologies |
+|----------|---------|---------------------|
+| [category label] | [count] | [top 3-4 names] |
+...
+
+Commands:
+- `/agentops:tech-catalog browse <category>` — view all options in a category with docs links
+- `/agentops:tech-catalog add <category> <name>` — add a new technology
+- `/agentops:tech-catalog remove <category> <name>` — remove a technology
+- `/agentops:tech-catalog update` — interactive update session
+- `/agentops:tech-catalog auto-update` — AI-driven catalog refresh (researches and proposes changes automatically)
+- `/agentops:tech-catalog search <query>` — search across all categories
+```
+
+### `browse <category>` — View category details
+
+Read the specified category from the catalog and present all options with descriptions and doc links:
+
+```markdown
+## [Category Label]
+
+| Technology | Description | Docs |
+|-----------|-------------|------|
+| [name] | [description] | [link] |
+...
+```
+
+### `add <category> <name>` — Add new technology
+
+Use `AskUserQuestion` to gather:
+1. question: "Brief description of [name]?" (with freeform "Other" option for typing)
+2. question: "Documentation URL for [name]?" (freeform)
+
+Then add the entry to the catalog JSON and confirm.
+
+If the category doesn't exist, ask if a new category should be created — gather: category key, label, question text, and whether multiple selections are allowed.
+
+### `remove <category> <name>` — Remove technology
+
+Read the catalog, find the entry, confirm removal with AskUserQuestion, then remove and save.
+
+### `update` — Interactive update session
+
+Walk through the catalog category by category. For each, use `AskUserQuestion`:
+- question: "Review [category]. Any changes needed?"
+- options: "Looks good — skip", "Add a technology", "Remove a technology", "Update an entry"
+
+After all categories, update the `_meta.lastUpdated` field and save.
+
+### `auto-update` — AI-driven catalog refresh
+
+Automatically research and update the entire catalog without manual intervention. This is the hands-off alternative to `update`.
+
+**Process:**
+
+1. Read the current catalog from `templates/tech-catalog.json`.
+2. Use `WebSearch` to research each category for:
+   - **New entrants:** Technologies that have gained significant adoption since the catalog was last updated (check `_meta.lastUpdated`). Look for new frameworks, tools, or services that have reached production-readiness and meaningful community adoption.
+   - **Deprecated/dead:** Technologies that have been deprecated, abandoned, or superseded. Look for official deprecation notices, archived repositories, or successor announcements.
+   - **Description drift:** Existing entries whose descriptions are now inaccurate (e.g. a tool that has expanded scope, changed ownership, or shifted focus).
+   - **Broken docs links:** Verify that documentation URLs still resolve. If a docs site has moved, update the URL.
+   - **Missing categories:** Consider whether any new category of tooling has emerged that warrants its own section (e.g. AI/LLM frameworks, edge runtimes, observability).
+3. For each category, launch parallel `Agent` searches where possible to speed up research.
+4. Compile all proposed changes into a summary table:
+
+```markdown
+## Auto-Update Proposals
+
+| Action | Category | Technology | Reason |
+|--------|----------|-----------|--------|
+| ADD | [category] | [name] | [why — adoption signal, release date] |
+| REMOVE | [category] | [name] | [why — deprecated, archived, superseded by X] |
+| UPDATE | [category] | [name] | [what changed — description, docs URL] |
+| NEW CAT | [key] | — | [why this category is needed] |
+```
+
+5. Present the summary to the user and use `AskUserQuestion`:
+   - question: "Apply these catalog updates?"
+   - options: "Apply all", "Let me review individually", "Cancel"
+6. If "Let me review individually": walk through each proposed change with `AskUserQuestion` asking "Apply this change?" with options "Yes", "No", "Edit before applying".
+7. Apply approved changes to the catalog JSON, update `_meta.lastUpdated`, bump `_meta.version` patch number, and save.
+8. Present a final diff summary of what was changed.
+
+**Research guidelines:**
+- Prefer technologies with 1,000+ GitHub stars or equivalent adoption signal.
+- Don't add niche or experimental tools — the catalog should reflect production-ready, broadly applicable options.
+- Keep each category to a reasonable size (8–18 options). If a category is getting too large, consider whether some entries should be removed or a subcategory created.
+- When in doubt about whether to add something, err on the side of not adding — the user can always add manually.
+- Search queries should target "[category] framework/tool 2025 2026" to find recent entrants.
+
+### `search <query>` — Search catalog
+
+Search all categories for technologies matching the query (case-insensitive, partial match on name and description). Present matching results with category, description, and docs link.
+
+---
+
+## How to Update the Catalog
+
+When updating `templates/tech-catalog.json`:
+
+1. Read the current file
+2. Parse as JSON
+3. Apply the change (add/remove/update entry)
+4. Update `_meta.lastUpdated` to today's date
+5. Write back with proper JSON formatting (2-space indent)
+6. Confirm the change to the user
+
+### Entry Format
+
+Each technology entry follows this structure:
+```json
+{
+  "name": "Technology Name",
+  "description": "One-line description of what it is and when to use it",
+  "docs": "https://link-to-official-docs"
+}
+```
+
+### Category Format
+
+Each category follows this structure:
+```json
+{
+  "label": "Human-readable category name",
+  "question": "Question to ask the user during scaffolding",
+  "allowMultiple": false,
+  "appliesWhen": "Optional condition for when this category is relevant",
+  "options": [...]
+}
+```
+
+---
+
+## Integration with Scaffold
+
+The `/agentops:scaffold` command reads `templates/tech-catalog.json` to dynamically build its questions. When you add a category here, scaffold will automatically pick it up. When you add a technology, it becomes available as a selection option.
+
+Categories with `allowMultiple: true` will use multiSelect in AskUserQuestion (e.g., databases, testing frameworks).
+
+The "Other" option is always available via AskUserQuestion's built-in freeform input — users can type any technology not in the catalog.