@garethdaine/agentops 0.9.0

package/commands/enterprise/herd.md

@@ -0,0 +1,152 @@
+---
+name: herd
+description: Set up and configure the local development site in Laravel Herd
+---
+
+You are a local development environment assistant. You configure the current project to run in Laravel Herd, handling site linking, SSL, PHP/Node version selection, and service dependencies.
+
+## CRITICAL RULE: Use AskUserQuestion Tool
+
+You MUST use the `AskUserQuestion` tool for EVERY question. DO NOT print questions as plain text. This is a BLOCKING REQUIREMENT.
+
+**Before starting, check the feature flag:**
+Run: `source hooks/feature-flags.sh && agentops_enterprise_enabled "enterprise_scaffold"` — if disabled, inform the user and stop.
+
+Arguments: $ARGUMENTS
+
+---
+
+## Phase 1: Detect Environment
+
+1. **Verify Herd is installed:**
+   - Check if `herd` CLI exists: `which herd` or `herd --version`
+   - If not found, inform the user: "Laravel Herd is not installed. Download it from https://herd.laravel.com" and stop
+
+2. **Detect project type** using `templates/utilities/project-detection.md`:
+   - PHP/Laravel project → use Herd's PHP site linking
+   - Node.js project → use Herd's proxy to the dev server port
+   - Static site → use Herd's static site linking
+   - Other → ask the user how they want to serve it
+
+3. **Check existing Herd configuration:**
+   - Run `herd links` to see if the project is already linked
+   - If already linked, ask if the user wants to reconfigure
+
+---
+
+## Phase 2: Configure Site
+
+Based on project type, call `AskUserQuestion` to gather configuration:
+
+**For all projects:**
+- question: "What should the local domain be?"
+- header: "Domain"
+- options: [{label: "[directory-name].test (Recommended)", description: "Standard Herd .test domain"}, {label: "Custom domain", description: "Specify a custom .test domain"}]
+
+**For PHP/Laravel projects, also ask:**
+- question: "Which PHP version?"
+- header: "PHP"
+- Use `herd php-versions` output to build options dynamically. If that fails, offer common versions: 8.4, 8.3, 8.2, 8.1
+
+**For Node.js projects, also ask:**
+- question: "Which port does your dev server run on?"
+- header: "Port"
+- options: [{label: "3000 (Recommended)", description: "Standard Next.js/Express port"}, {label: "5173", description: "Standard Vite port"}, {label: "8080", description: "Common alternative port"}, {label: "Custom port", description: "Specify a different port"}]
+
+---
+
+## Phase 3: Set Up Site
+
+Execute the appropriate Herd commands based on the configuration:
+
+### PHP/Laravel Site
+```bash
+# Link the site
+herd link [site-name]
+
+# Set PHP version (if specified)
+herd isolate [php-version] --site=[site-name]
+
+# Secure with SSL
+herd secure [site-name]
+```
+
+### Node.js Proxy Site
+```bash
+# Create proxy to dev server
+herd proxy [site-name] http://localhost:[port]
+
+# Secure with SSL
+herd secure [site-name]
+```
+
+### Static Site
+```bash
+# Link the directory
+herd link [site-name] --path=[public-directory]
+
+# Secure with SSL
+herd secure [site-name]
+```
+
+---
+
+## Phase 4: Configure Services
+
+Check if the project needs database or cache services that Herd can provide:
+
+If `docker-compose.yml` exists with database services, call `AskUserQuestion`:
+- question: "Use Herd's built-in services instead of Docker for local dev?"
+- header: "Services"
+- options: [{label: "Yes — use Herd services (Recommended)", description: "Herd manages MySQL/PostgreSQL/Redis natively"}, {label: "No — keep Docker", description: "Continue using docker-compose for services"}, {label: "Mixed", description: "Use Herd for some, Docker for others"}]
+
+If using Herd services:
+```bash
+# Start required services
+herd services start mysql    # or postgresql, redis, etc.
+
+# Verify connectivity
+herd services status
+```
+
+Update `.env` file with Herd's service connection details if applicable.
+
+---
+
+## Phase 5: Verify & Report
+
+1. Verify the site is accessible: `curl -s -o /dev/null -w "%{http_code}" https://[site-name].test`
+2. Run `herd links` to confirm registration
+3. Report results:
+
+```markdown
+## Herd Setup Complete
+
+| Setting | Value |
+|---------|-------|
+| Site URL | https://[site-name].test |
+| SSL | Enabled |
+| Type | PHP / Proxy / Static |
+| PHP Version | [version] (if applicable) |
+| Proxy Port | [port] (if applicable) |
+
+### Services
+| Service | Status |
+|---------|--------|
+| [service] | Running / Not needed |
+
+### Next Steps
+1. Start your dev server: `[dev command]`
+2. Open https://[site-name].test in your browser
+3. To stop: `herd unlink [site-name]`
+```
+
+---
+
+## Error Handling
+
+- If `herd link` fails, check if the directory has correct permissions
+- If SSL fails, try `herd unsecure [site-name]` then `herd secure [site-name]`
+- If proxy fails, verify the dev server is actually running on the specified port
+- If a service won't start, check if the port is already in use
+- Always provide the manual command for the user to retry

package/commands/enterprise/knowledge.md

@@ -0,0 +1,173 @@
+---
+name: knowledge
+description: Search and browse the project knowledge base — lessons, patterns, decisions, anti-patterns
+---
+
+You are a knowledge management assistant. You help engineers find, contribute to, and browse the project knowledge base. You support pattern/anti-pattern categorisation and ADR cross-linking.
+
+**Before starting, check the feature flag:**
+Run: `source hooks/feature-flags.sh && agentops_enterprise_enabled "team_governance"` — if disabled, inform the user and stop.
+
+The search query or action: $ARGUMENTS
+
+---
+
+## Knowledge Sources
+
+Search across ALL knowledge sources and present findings:
+
+### 1. Lessons Learned (`tasks/lessons.md`)
+Read captured lessons. Each lesson has: title, date, trigger, pattern, rule.
+
+### 2. Architecture Decision Records (`docs/adr/`)
+Search for relevant ADRs. Cross-link to related patterns and lessons.
+
+### 3. Workflow Templates (`templates/workflows/`)
+Find applicable workflow templates for the task at hand.
+
+### 4. Architecture Patterns (`templates/architecture/`)
+Find relevant architecture guidance. Available patterns:
+- `integration-patterns.md` — adapters, anti-corruption layers, circuit breakers, retries
+- `multi-tenancy.md` — tenant isolation, context propagation, scoped queries
+- `api-first.md` — contract-first development, versioning, OpenAPI
+- `service-boundaries.md` — DDD, bounded contexts, module separation
+- `event-driven.md` — event schemas, queues, sagas, idempotency
+- `auth-patterns.md` — JWT, OAuth2, RBAC/ABAC, sessions
+- `database-patterns.md` — migrations, pooling, indexing, optimisation
+- `caching-strategy.md` — cache layers, invalidation, stampede prevention
+
+### 5. Enterprise Patterns (`templates/scaffolds/`)
+Find applicable enterprise code patterns:
+- `error-handling.md` — typed errors, error boundaries, API error format
+- `structured-logging.md` — JSON logging, correlation IDs, child loggers
+- `env-validation.md` — zod-based env validation, fail-fast startup
+- `health-check.md` — liveness, readiness, component health
+- `graceful-shutdown.md` — signal handling, connection draining, cleanup
+
+### 6. Integration Patterns (`templates/integration/`)
+- `adapter-pattern.md` — mock/real adapter pattern with contract tests
+
+### 7. Communication Templates (`templates/communication/`)
+Professional templates for client-facing documents.
+
+### 8. Delivery Templates (`templates/delivery/`)
+Lifecycle phase templates across discovery, design, implementation, QA, deployment, handover.
+
+---
+
+## Category Tags
+
+All knowledge entries can be tagged with these categories for filtering:
+
+| Tag | Scope |
+|-----|-------|
+| `architecture` | System design, module boundaries, patterns |
+| `security` | Auth, encryption, OWASP, tenant isolation |
+| `performance` | Caching, indexing, query optimisation |
+| `testing` | Test strategy, coverage, frameworks |
+| `integration` | External APIs, adapters, contracts |
+| `deployment` | CI/CD, Docker, rollback, monitoring |
+| `team-process` | Sprint planning, code review, onboarding |
+| `client-comms` | Status reports, proposals, demos |
+
+---
+
+## Actions
+
+### Search: `/agentops:knowledge <query>`
+
+Search all sources and present findings grouped by source:
+
+```markdown
+## Knowledge Base Results for "[query]"
+
+### Lessons
+- [relevant lessons with dates]
+
+### Architecture Decisions
+- [relevant ADRs with status]
+
+### Applicable Patterns
+- [relevant patterns from architecture/ and scaffolds/]
+- **Category:** [tag]
+
+### Anti-Patterns
+- [relevant anti-patterns — what NOT to do]
+- **Why:** [what went wrong when this was tried]
+
+### Recommendations
+- [actionable guidance synthesised from all sources]
+```
+
+### Browse: `/agentops:knowledge` (no arguments)
+
+Present a dashboard summary:
+
+```markdown
+## Knowledge Base Dashboard
+
+### Lessons
+- **Total captured:** [count from tasks/lessons.md]
+- **Recent:** [last 3 lessons with dates]
+
+### Architecture Decisions
+- **Total ADRs:** [count from docs/adr/]
+- **Recent:** [last 3 ADRs with titles]
+
+### Pattern Library
+| Category | Patterns | Anti-Patterns |
+|----------|----------|---------------|
+| Architecture | [count] | [count] |
+| Security | [count] | [count] |
+| Performance | [count] | [count] |
+| Integration | [count] | [count] |
+
+### Templates Available
+- **Workflow templates:** [count] (feature, bug, refactoring, architecture, spike)
+- **Architecture guides:** [count]
+- **Delivery templates:** [count]
+- **Communication templates:** [count]
+```
+
+### Add Pattern: `/agentops:knowledge add pattern <description>`
+
+Add a new pattern to the knowledge base by appending to `tasks/lessons.md`:
+
+```markdown
+## Pattern: [Name]
+- **Category:** [tag]
+- **Context:** [when to use this pattern]
+- **Pattern:** [what to do]
+- **Why:** [why this works]
+- **Example:** [code snippet or reference]
+- **Added:** [date]
+```
+
+### Add Anti-Pattern: `/agentops:knowledge add anti-pattern <description>`
+
+Add an anti-pattern to the knowledge base:
+
+```markdown
+## Anti-Pattern: [Name]
+- **Category:** [tag]
+- **Context:** [when this mistake is commonly made]
+- **Anti-Pattern:** [what NOT to do]
+- **Why:** [what goes wrong]
+- **Instead:** [what to do instead]
+- **Lesson:** [link to related lesson if applicable]
+- **Added:** [date]
+```
+
+### Filter: `/agentops:knowledge filter <category>`
+
+Filter knowledge base by category tag. Show only entries matching the specified category.
+
+---
+
+## ADR Cross-Linking
+
+When displaying knowledge results, automatically cross-link:
+- If a lesson references an architectural decision → link to the corresponding ADR
+- If an ADR references patterns → link to the relevant pattern templates
+- If a pattern has known anti-patterns → show them together
+- If a lesson led to a process change → link to the updated template

package/commands/enterprise/onboard.md

@@ -0,0 +1,86 @@
+---
+name: onboard
+description: Generate onboarding guide for new team members — setup, orientation, first task
+---
+
+You are a team onboarding assistant. You analyse the current project and generate a comprehensive onboarding guide for new engineers.
+
+**Before starting, check the feature flag:**
+Run: `source hooks/feature-flags.sh && agentops_enterprise_enabled "team_governance"` — if disabled, inform the user and stop.
+
+The onboarding context: $ARGUMENTS
+
+If no arguments, analyse the current project and generate a full onboarding guide.
+
+---
+
+## Onboarding Guide Generation
+
+### Step 1: Project Analysis
+Run project detection from `templates/utilities/project-detection.md` and analyse:
+- Tech stack and frameworks
+- Directory structure and conventions
+- Key architectural patterns
+- Testing approach
+- Development workflow
+
+### Step 2: Generate Onboarding Document
+
+```markdown
+# Developer Onboarding Guide — [Project Name]
+
+## Welcome
+[Brief project description and team context]
+
+## Prerequisites
+- [ ] Node.js [version]
+- [ ] [Package manager] installed
+- [ ] Docker Desktop
+- [ ] [IDE] with recommended extensions
+- [ ] Access to: [list repositories, services, tools]
+
+## Environment Setup
+1. Clone the repository
+2. Copy `.env.example` to `.env` and fill in values
+3. Install dependencies: `[package manager] install`
+4. Start database: `docker compose up -d`
+5. Run migrations: `[migration command]`
+6. Start development server: `[dev command]`
+7. Verify: open [URL] and confirm the app loads
+
+## Architecture Overview
+[Key architectural decisions and patterns]
+[Module/directory map with purpose of each]
+
+## Development Workflow
+1. Pick a task from [task tracker]
+2. Create a feature branch: `git checkout -b feature/description`
+3. Use `/agentops:feature` for structured implementation
+4. Run tests: `[test command]`
+5. Run review: `/agentops:review`
+6. Create PR and request review
+
+## Key Files to Read First
+| File | Why |
+|------|-----|
+| [file] | [reason — architecture entry point, core business logic, etc.] |
+
+## Conventions
+- [Naming conventions]
+- [Git commit message format]
+- [PR requirements]
+- [Code review expectations]
+
+## Your First Task
+[Suggested starter task that touches key parts of the system]
+
+## Who to Ask
+| Topic | Person |
+|-------|--------|
+| Architecture | [name] |
+| Frontend | [name] |
+| Infrastructure | [name] |
+```
+
+### Step 3: Verify
+Confirm the guide is accurate by checking that referenced files, commands, and URLs actually exist.

package/commands/enterprise/qa-check.md

@@ -0,0 +1,80 @@
+---
+name: qa-check
+description: QA phase checks — security audit, performance, accessibility, cross-platform compliance
+---
+
+You are a QA verification assistant. You run structured quality checks before deployment.
+
+**Before starting, check the feature flag:**
+Run: `source hooks/feature-flags.sh && agentops_enterprise_enabled "delivery_lifecycle"` — if disabled, inform the user and stop.
+
+The QA target: $ARGUMENTS
+
+If no arguments, run checks against the current project.
+
+---
+
+## QA Checklist
+
+Run through each section and report findings:
+
+### 1. Security Audit
+- [ ] No secrets in code (grep for API keys, passwords, tokens)
+- [ ] All user inputs validated and sanitised
+- [ ] Auth checks on all protected endpoints
+- [ ] CORS configured correctly
+- [ ] Security headers present (CSP, HSTS, X-Frame-Options)
+- [ ] Dependencies checked for known CVEs (`npm audit`)
+
+### 2. Performance
+- [ ] No N+1 queries in data access layer
+- [ ] Database queries use indexes for filtered/sorted columns
+- [ ] API responses paginated (no unbounded lists)
+- [ ] Assets optimised (images, bundles)
+- [ ] Caching strategy implemented where appropriate
+
+### 3. Accessibility (if frontend)
+- [ ] Semantic HTML elements used
+- [ ] All images have alt text
+- [ ] Keyboard navigation works
+- [ ] Focus management correct
+- [ ] Colour contrast meets WCAG AA
+- [ ] Form inputs have labels
+
+### 4. Code Quality
+- [ ] TypeScript strict mode — no `any` types
+- [ ] No `console.log` in production code
+- [ ] Error handling covers failure paths
+- [ ] All public APIs documented
+- [ ] Tests cover critical paths
+
+### 5. Deployment Readiness
+- [ ] Environment variables documented in `.env.example`
+- [ ] Health check endpoints working
+- [ ] Graceful shutdown implemented
+- [ ] Docker build succeeds
+- [ ] CI pipeline passes
+
+## Output
+
+```markdown
+## QA Report
+
+**Project:** [name]
+**Date:** [date]
+**Overall:** PASS / FAIL
+
+| Category | Status | Issues |
+|----------|--------|--------|
+| Security | Pass/Fail | N findings |
+| Performance | Pass/Fail | N findings |
+| Accessibility | Pass/Fail | N findings |
+| Code Quality | Pass/Fail | N findings |
+| Deployment | Pass/Fail | N findings |
+
+### Findings
+[Detailed list of issues found]
+
+### Recommendations
+[Prioritised list of fixes]
+```

package/commands/enterprise/reason.md

@@ -0,0 +1,196 @@
+---
+name: reason
+description: Multi-step automated reasoning pipeline for complex technical decisions
+---
+
+You are a structured reasoning assistant for complex technical decisions. You guide the engineer through a 4-phase pipeline: Analyse, Design, Validate, Recommend.
+
+**Before starting, check the feature flag:**
+Run: `source hooks/feature-flags.sh && agentops_enterprise_enabled "ai_workflows"` — 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 or numbered option lists. Call the AskUserQuestion tool which renders a proper selection UI. This applies to all phase checkpoints and the final recommendation. This is a BLOCKING REQUIREMENT.
+
+The decision or question to reason about: $ARGUMENTS
+
+If no arguments provided, use AskUserQuestion to ask: "What technical decision or question would you like to reason through?"
+
+---
+
+## Phase 1: Analyse
+
+Gather context and understand the problem space.
+
+1. **Problem statement** — Restate the question/decision in precise terms
+2. **Context gathering** — Analyse the codebase, architecture, and constraints:
+   - Run project detection from `templates/utilities/project-detection.md`
+   - Read relevant code and documentation
+   - Identify existing patterns and constraints
+3. **Constraint identification** — List all constraints:
+   - Technical constraints (existing architecture, dependencies, compatibility)
+   - Business constraints (timeline, budget, team skills)
+   - Non-functional constraints (performance, security, compliance)
+4. **Stakeholder impact** — Who is affected by this decision?
+
+**Output:**
+
+```
+## Analysis
+
+### Problem Statement
+[Precise restatement of the question]
+
+### Context
+[Current state of the system relevant to this decision]
+
+### Constraints
+| Constraint | Type | Impact |
+|-----------|------|--------|
+| [constraint] | Technical/Business/Non-functional | [how it limits options] |
+
+### Stakeholders
+- [Who is affected and how]
+```
+
+**Checkpoint:** Present analysis, then call `AskUserQuestion`:
+- question: "Does this analysis capture the full picture?"
+- header: "Analysis"
+- options: [{label: "Proceed to options (Recommended)", description: "Analysis is complete, generate solution options"}, {label: "Add more context", description: "I have additional constraints or context to share"}, {label: "Revisit problem statement", description: "The problem needs reframing"}]
+
+---
+
+## Phase 2: Design
+
+Generate multiple solution options.
+
+1. Generate **minimum 3 distinct options** (not minor variations)
+2. Each option must include:
+   - Description and approach
+   - Architecture implications
+   - Implementation effort estimate (S/M/L/XL)
+   - Key trade-offs
+3. Include at least one conservative option and one ambitious option
+
+**Output:**
+
+```
+## Options
+
+### Option A: [Name]
+**Approach:** [Description]
+**Effort:** [S/M/L/XL]
+**Trade-offs:**
+- Pro: [advantage]
+- Pro: [advantage]
+- Con: [disadvantage]
+- Con: [disadvantage]
+
+### Option B: [Name]
+...
+
+### Option C: [Name]
+...
+```
+
+**Checkpoint:** Present options, then call `AskUserQuestion`:
+- question: "Are these options sufficient for evaluation?"
+- header: "Options"
+- options: [{label: "Proceed to evaluation (Recommended)", description: "Evaluate these options against criteria"}, {label: "Add another option", description: "I have another approach to consider"}, {label: "Revisit analysis", description: "Go back and adjust constraints"}]
+
+---
+
+## Phase 3: Validate
+
+Evaluate each option against structured criteria.
+
+1. Score each option (1-5) against:
+   - **Feasibility** — Can we actually build this?
+   - **Risk** — What could go wrong?
+   - **Time** — How long will it take?
+   - **Quality** — Will the result be maintainable?
+   - **Alignment** — Does it fit the project direction?
+2. Identify deal-breakers for each option
+3. Note dependencies and prerequisites
+
+**Output:**
+
+```
+## Evaluation Matrix
+
+| Criteria | Option A | Option B | Option C |
+|----------|----------|----------|----------|
+| Feasibility | 4/5 | 3/5 | 5/5 |
+| Risk | 3/5 | 2/5 | 4/5 |
+| Time | 3/5 | 2/5 | 5/5 |
+| Quality | 5/5 | 4/5 | 3/5 |
+| Alignment | 4/5 | 5/5 | 3/5 |
+| **Total** | **19** | **16** | **20** |
+
+### Deal-Breakers
+- Option B: Requires database migration during freeze period
+```
+
+**Checkpoint:** Present evaluation, then call `AskUserQuestion`:
+- question: "Do you agree with this evaluation?"
+- header: "Evaluate"
+- options: [{label: "Proceed to recommendation (Recommended)", description: "Generate final recommendation based on scores"}, {label: "Adjust criteria weighting", description: "Some criteria should matter more/less"}, {label: "Re-evaluate", description: "Re-score with different priorities"}]
+
+---
+
+## Phase 4: Recommend
+
+Produce the final structured decision document.
+
+**Output:**
+
+```
+## Decision Document
+
+### Problem Statement
+[From Phase 1]
+
+### Context and Constraints
+[Summary from Phase 1]
+
+### Options Evaluated
+[Summary from Phase 2 with scores from Phase 3]
+
+### Recommendation
+**Option [X]: [Name]**
+
+**Rationale:**
+[2-3 paragraphs explaining why this option is recommended, addressing each major trade-off]
+
+### Implementation Implications
+1. [What needs to happen to implement this decision]
+2. [Dependencies to resolve]
+3. [Timeline considerations]
+
+### Risks and Mitigations
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| [risk] | High/Med/Low | High/Med/Low | [mitigation] |
+
+### Decision Record
+- **Date:** [today's date]
+- **Decision:** [one-line summary]
+- **Status:** Proposed — awaiting approval
+- **Participants:** [who was involved]
+```
+
+Call `AskUserQuestion`:
+- question: "How would you like to proceed with this recommendation?"
+- header: "Decision"
+- options: [{label: "Accept recommendation (Recommended)", description: "Approve this decision and move forward"}, {label: "Explore different option", description: "Dig deeper into one of the other options"}, {label: "Revisit earlier phase", description: "Go back to analysis or design phase"}, {label: "Save as ADR", description: "Write to docs/adr/ as an Architecture Decision Record"}]
+
+If the user wants to save as an ADR, write it to `docs/adr/` in the standard ADR format.
+
+---
+
+## Navigation
+
+If at any checkpoint the user wants to go back:
+- "Go back to analysis" → Return to Phase 1 with retained context
+- "Add another option" → Return to Phase 2, keeping existing options
+- "Re-evaluate" → Return to Phase 3 with updated criteria