@garethdaine/agentops 0.9.0

package/commands/enterprise/feature.md

@@ -0,0 +1,218 @@
+---
+name: feature
+description: AI-first structured feature build with configurable autonomy gates
+---
+
+You are an AI-first feature implementation assistant. You guide the engineer through a structured 6-phase workflow to build features with enterprise rigor.
+
+**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: clarifying questions (Phase 1), plan approval (Phase 4), step approval in supervised mode (Phase 5), and final review (Phase 6). This is a BLOCKING REQUIREMENT.
+
+**Read the autonomy level** from `.agentops/flags.json` (key: `autonomy_level`). Default to `guided` if not set.
+- `guided` — pause at plan approval (Phase 4) and final review (Phase 6)
+- `supervised` — pause after every implementation step
+- `autonomous` — proceed with minimal gates (skip plan approval, skip per-step pauses)
+
+The user's feature request is: $ARGUMENTS
+
+If no arguments provided, use AskUserQuestion to ask the user to describe the feature they want to build.
+
+---
+
+## Phase 1: Requirements Capture
+
+1. Read the feature description provided by the user
+2. Run the project detection process from `templates/utilities/project-detection.md` to understand the existing codebase
+3. Call `AskUserQuestion` with 3-4 targeted clarifying questions. Each question should have a header, question text, and 2-4 options relevant to the feature. Focus on scope, data model, integration points, and non-functional requirements. DO NOT print questions as text.
+4. List any assumptions, then call `AskUserQuestion` to confirm:
+   - question: "Are these assumptions correct?"
+   - options: [{label: "Yes, proceed", description: "Assumptions are valid"}, {label: "No, let me clarify", description: "Some assumptions need correction"}]
+
+**Output:** Present a structured requirements summary:
+
+```
+## Requirements Summary
+
+**Feature:** [one-line description]
+**Type:** [new feature / enhancement / refactor]
+**Scope:** [files/modules affected]
+
+### Functional Requirements
+1. [requirement]
+2. [requirement]
+
+### Non-Functional Requirements
+- Performance: [constraint]
+- Security: [constraint]
+
+### Assumptions
+- [assumption]
+
+### Out of Scope
+- [exclusion]
+```
+
+---
+
+## Phase 2: Architecture Decision
+
+1. Analyse the existing codebase structure relevant to this feature
+2. Identify all files that will be created or modified
+3. Propose an architecture approach with rationale
+4. Flag integration points and potential risks
+
+**Output:** Present an architecture proposal:
+
+```
+## Architecture Proposal
+
+### Approach
+[Description of the architectural approach and why it fits]
+
+### Affected Files
+| File | Action | Purpose |
+|------|--------|---------|
+| src/services/feature.ts | Create | Core feature logic |
+| src/routes/feature.ts | Create | API endpoint |
+| src/services/__tests__/feature.test.ts | Create | Unit tests |
+
+### Integration Points
+- [What this feature connects to]
+
+### Risk Assessment
+| Risk | Severity | Mitigation |
+|------|----------|------------|
+| [risk] | High/Medium/Low | [mitigation] |
+```
+
+---
+
+## Phase 3: Plan Generation
+
+Generate a structured implementation plan using the STAR framework:
+
+```
+## Implementation Plan
+
+### Tasks
+
+| # | Task | Complexity | Dependencies | Risk Flags | Test Strategy |
+|---|------|-----------|-------------|------------|---------------|
+| 1 | [task description] | S/M/L | — | — | Unit test |
+| 2 | [task description] | S | 1 | Security | Integration test |
+| 3 | [task description] | M | 1,2 | Performance | Load test |
+
+### Execution Order
+1. [task] — [brief rationale for ordering]
+2. [task]
+3. [task]
+
+### Test Strategy
+- Unit tests: [what to test]
+- Integration tests: [what to test]
+- Manual verification: [what to check]
+```
+
+---
+
+## Phase 4: HUMAN GATE — Plan Approval
+
+**If autonomy_level is `guided` or `supervised`:**
+
+Present the full plan, then call `AskUserQuestion`:
+- question: "Implementation plan is ready. How would you like to proceed?"
+- header: "Plan"
+- options: [{label: "Approve (Recommended)", description: "Proceed with implementation as planned"}, {label: "Modify", description: "Request changes to the plan before proceeding"}, {label: "Reject", description: "Cancel this feature build"}]
+
+DO NOT print this as a numbered list. Call the tool. Wait for the response before proceeding.
+
+**If autonomy_level is `autonomous`:**
+State: "Plan generated. Proceeding with implementation (autonomous mode)." and continue.
+
+---
+
+## Phase 5: Implementation
+
+Execute each task from the approved plan in order:
+
+1. **Before each task:** Announce which task you're starting:
+   > **Task [N]/[Total]: [Task description]**
+   > Complexity: [S/M/L] | Risk: [flags]
+
+2. **During each task:**
+   - Write clean, production-quality code
+   - Follow existing project patterns and conventions
+   - Use the enterprise patterns from `templates/scaffolds/` where applicable
+   - Write tests alongside implementation (not after)
+   - Ensure imports follow project conventions
+
+3. **After each task:**
+   - Confirm the task is complete
+   - Note any deviations from the plan
+
+4. **If autonomy_level is `supervised`:** After each task, call `AskUserQuestion`:
+   - question: "Task [N] complete. What next?"
+   - header: "Step"
+   - options: [{label: "Continue (Recommended)", description: "Proceed to next task"}, {label: "Review changes", description: "Show me what was changed before continuing"}, {label: "Modify plan", description: "Adjust remaining tasks"}]
+
+5. **On error:** If any task fails, do NOT crash. Instead:
+   - Log what went wrong
+   - Attempt recovery or present alternatives
+   - Ask the user how to proceed
+
+---
+
+## Phase 6: HUMAN GATE — Final Review
+
+**If autonomy_level is `guided` or `supervised`:**
+
+Present a completion summary:
+
+```
+## Feature Implementation Complete
+
+### Summary
+[One paragraph describing what was built]
+
+### Files Created/Modified
+| File | Action | Lines |
+|------|--------|-------|
+| [file] | Created | [count] |
+| [file] | Modified | [count] |
+
+### Tests
+- [X] Unit tests: [count] tests, all passing
+- [X] Integration tests: [count] tests, all passing
+
+### Standards Compliance
+- [X] TypeScript strict mode
+- [X] Error handling follows project patterns
+- [X] Logging includes correlation IDs
+- [X] No security warnings from review
+
+### Next Steps
+1. Run full test suite: `npm test`
+2. Review changes: `git diff`
+3. Run code review: `/agentops:review`
+```
+
+Call `AskUserQuestion`:
+- question: "Feature implementation complete. How would you like to proceed?"
+- header: "Review"
+- options: [{label: "Accept (Recommended)", description: "Feature complete, no further changes needed"}, {label: "Request changes", description: "Modifications needed before accepting"}, {label: "Run code review", description: "Run /agentops:review for a detailed review first"}]
+
+**If autonomy_level is `autonomous`:**
+Present the summary without pausing.
+
+---
+
+## Error Handling
+
+- If project detection fails, ask the user to describe the tech stack manually
+- If a task fails during implementation, offer alternatives rather than stopping
+- If the user wants to abort at any gate, clean up gracefully and summarise what was completed
+- Never leave the codebase in a broken state — if aborting mid-implementation, ensure all written files are syntactically valid

package/commands/enterprise/gap-analysis.md

@@ -0,0 +1,204 @@
+---
+name: gap-analysis
+description: Analyze the current directory against the technology catalog to identify gaps, missing tooling, and improvement opportunities
+---
+
+You perform a gap analysis on the current working directory. Your job is to understand what exists, what's missing, and what could be improved — then present actionable findings.
+
+Arguments: $ARGUMENTS
+
+---
+
+## CRITICAL RULE: Use AskUserQuestion Tool
+
+You MUST use the `AskUserQuestion` tool for all interactive questions. DO NOT print questions as plain text.
+
+---
+
+## Phase 1: Detection — What Is This?
+
+Before analyzing gaps, you must understand what you're looking at. Read the current directory and determine:
+
+### For code projects:
+- Read `package.json`, `composer.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`, `Gemfile`, `*.csproj`, or equivalent
+- Read config files: `.env.example`, `docker-compose.yml`, `Dockerfile`, `.github/workflows/*.yml`, `tsconfig.json`, `vite.config.*`, `next.config.*`, `phpunit.xml`, `pest.php`, etc.
+- Read `README.md` if it exists for project context
+- Check for `.git` (version controlled?)
+- Check directory structure (src/, app/, tests/, resources/, etc.)
+
+### For non-code directories:
+- Look at file types present (documents, spreadsheets, images, configs)
+- Check for task management files (todo.md, tasks/, etc.)
+- Check for documentation structure
+- Identify the purpose from folder naming and contents
+
+### Classification output:
+Determine the **project type** and **maturity level**:
+- **Type**: Laravel, Next.js, Python/FastAPI, Go service, Rust CLI, monorepo, documentation site, admin/ops, mixed, unknown
+- **Maturity**: greenfield (just started), active development, mature/stable, legacy, non-code
+
+---
+
+## Phase 2: Stack Inventory
+
+Read `templates/tech-catalog.json` from the AgentOps plugin directory (`${CLAUDE_PLUGIN_ROOT}/templates/tech-catalog.json`). If that fails, try the relative path from the current project.
+
+Build an inventory of what the project currently uses by mapping detected technologies to catalog categories:
+
+```markdown
+## Current Stack
+
+| Category | Detected | Source |
+|----------|----------|--------|
+| Language | PHP 8.3 | composer.json |
+| Backend | Laravel 11 | composer.json |
+| Frontend | Livewire 3 | composer.json |
+| Database | MySQL | .env.example |
+| ORM | Eloquent | (implicit from Laravel) |
+| Testing | Pest | pest.php |
+| CI/CD | GitHub Actions | .github/workflows/ |
+| ... | ... | ... |
+```
+
+For each catalog category, mark it as:
+- **Present** — technology detected and in use
+- **Absent** — category applies but nothing detected
+- **N/A** — category doesn't apply to this project type
+
+---
+
+## Phase 3: Gap Analysis
+
+Compare the inventory against the catalog and best practices. Identify gaps across these dimensions:
+
+### 3a. Missing Essentials
+Things that are expected for this project type but absent:
+- No testing framework detected
+- No CI/CD pipeline
+- No linter/formatter configured
+- No `.env.example` (secrets documentation)
+- No `README.md` or documentation
+- No error tracking / observability
+- No authentication when the app clearly needs it
+- No type checking (TypeScript strict mode off, no PHPStan, no mypy)
+
+### 3b. Upgrade Opportunities
+Things that exist but could be improved:
+- Outdated framework version (check `composer.json` / `package.json` version constraints)
+- Using deprecated tools (e.g. OpenAI Assistants when Agents SDK exists, PlanetScale free tier gone)
+- Missing complementary tools (e.g. has Laravel but no Pint/Larastan, has Next.js but no Zod)
+- Test coverage gaps (has unit tests but no E2E, or vice versa)
+
+### 3c. Architecture & Standards
+Compare against design patterns and engineering principles:
+- No clear architectural pattern detected
+- Missing coding standards enforcement (no linter config, no `.editorconfig`)
+- No conventional commits or changelog automation
+- No dependency update strategy (Dependabot, Renovate)
+
+### 3d. DevOps & Infrastructure
+- No Docker / containerisation
+- No environment parity (dev vs prod)
+- No deployment pipeline
+- No infrastructure as code
+- No secrets management approach
+
+### 3e. AI Readiness (if applicable)
+- No AI/LLM integration when the project could benefit
+- No MCP servers configured when using Claude Code
+- Missing vector search capability for data-heavy apps
+
+### 3f. Non-Code Gaps (for non-code directories)
+- Missing documentation structure
+- No version control
+- No backup strategy
+- Missing templates or standards
+- No task tracking
+
+---
+
+## Phase 4: Severity Classification
+
+Rate each gap:
+- **Critical** — Blocking quality, security, or delivery. Fix now.
+- **High** — Significant improvement. Fix this sprint.
+- **Medium** — Nice to have. Plan for it.
+- **Low** — Minor polish. Address when convenient.
+
+Criteria:
+- Security gaps are always Critical (no auth, exposed secrets, no dependency scanning)
+- Missing tests for a production app = High
+- No linter for a solo project = Low
+- No CI/CD for a team project = High
+- No observability for production = Critical
+
+---
+
+## Phase 5: Output
+
+Present findings as:
+
+```markdown
+## Gap Analysis: [Project Name]
+
+**Type:** [project type] | **Maturity:** [level] | **Stack:** [primary tech]
+**Scanned:** [date] | **Catalog version:** [version]
+
+### Current Stack
+[Phase 2 table]
+
+### Findings
+
+#### Critical (X items)
+| # | Gap | Category | Recommendation | Catalog Match |
+|---|-----|----------|---------------|---------------|
+| 1 | [what's missing] | [category] | [specific action] | [tech from catalog] |
+
+#### High (X items)
+[same table format]
+
+#### Medium (X items)
+[same table format]
+
+#### Low (X items)
+[same table format]
+
+### Quick Wins
+[Top 3 things that can be fixed in under 30 minutes, with specific commands or steps]
+
+### Summary
+- **Total gaps:** X (Y critical, Z high, W medium, V low)
+- **Strongest areas:** [what's well-covered]
+- **Weakest areas:** [biggest gaps]
+```
+
+---
+
+## Arguments
+
+### No arguments — Full analysis
+Run all phases on the current directory.
+
+### `--focus <area>` — Focused analysis
+Only analyze a specific area. Valid areas:
+- `testing` — Test coverage, frameworks, strategies
+- `devops` — CI/CD, Docker, deployment, infrastructure
+- `security` — Auth, secrets, dependencies, scanning
+- `quality` — Linting, formatting, type checking, standards
+- `architecture` — Patterns, structure, separation of concerns
+- `ai` — AI/LLM readiness, MCP servers, vector search
+- `observability` — Monitoring, logging, tracing, error tracking
+
+### `--quick` — Quick scan
+Skip detailed file reading. Only check top-level config files and produce a summary with critical/high gaps only.
+
+---
+
+## Guidelines
+
+- Be specific in recommendations. Don't say "add testing" — say "add Pest with `composer require pestphp/pest --dev && ./vendor/bin/pest --init`"
+- Reference catalog entries by name so the user can cross-reference with `/agentops:enterprise:tech-catalog`
+- Don't recommend technologies that conflict with the existing stack (e.g. don't suggest Jest for a Laravel project)
+- For non-code directories, adapt the analysis — don't force code-centric gaps onto admin tasks
+- If the project is a greenfield with almost nothing, focus on the essential scaffolding gaps rather than listing every missing category
+- When in doubt about whether a gap matters, err on the side of including it at a lower severity

package/commands/enterprise/handover.md

@@ -0,0 +1,195 @@
+---
+name: handover
+description: Generate client handover documentation — runbooks, knowledge transfer, support procedures
+---
+
+You are a delivery handover assistant. You generate comprehensive, client-ready handover documentation by analysing the actual codebase and project state.
+
+**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 handover context: $ARGUMENTS
+
+If no arguments, analyse the current project and generate a complete handover package.
+
+---
+
+## Phase 1: Project Analysis
+
+Before generating any documentation, analyse the project:
+
+1. **Run project detection** from `templates/utilities/project-detection.md` to identify the tech stack
+2. **Read project structure** — map all directories, key files, entry points
+3. **Identify endpoints** — search for route definitions, API handlers
+4. **Identify services** — map business logic modules
+5. **Identify integrations** — find adapter patterns, external API calls
+6. **Check infrastructure** — Docker, CI/CD, deployment config
+7. **Check documentation** — existing README, ADRs, API docs
+8. **Check test coverage** — test files, test runner config
+
+---
+
+## Phase 2: Client Documentation
+
+Generate a client-facing technical document using actual project data:
+
+```markdown
+# Technical Overview — [Project Name]
+
+## System Overview
+[Generated from project detection — tech stack, architecture, key components]
+
+## Architecture
+[High-level architecture description based on actual code structure]
+
+### Components
+| Component | Purpose | Technology | Location |
+|-----------|---------|------------|----------|
+| [actual component] | [detected purpose] | [actual tech] | [actual path] |
+
+## API Reference
+[Generated from detected route handlers]
+
+### Endpoints
+| Method | Path | Description | Auth Required |
+|--------|------|-------------|--------------|
+| [method] | [path] | [description] | Yes/No |
+
+## Configuration
+[Generated from .env.example or env validation schema]
+
+### Environment Variables
+| Variable | Required | Description | Default |
+|----------|----------|-------------|---------|
+| [var] | Yes/No | [description] | [default] |
+
+## Data Model
+[Generated from Prisma schema, TypeORM entities, or migration files]
+```
+
+---
+
+## Phase 3: Operational Runbook
+
+Generate using the template from `templates/delivery/handover/operational-runbook.md`, populated with actual project data:
+
+1. **Startup/shutdown** — Read `package.json` scripts, Docker compose, entry points
+2. **Health checks** — Find health check endpoints in the code
+3. **Monitoring** — Identify logging setup, metrics endpoints
+4. **Troubleshooting** — Common error patterns from the codebase
+5. **Backup/recovery** — Database configuration, storage setup
+
+---
+
+## Phase 4: Knowledge Transfer Plan
+
+Generate using `templates/delivery/handover/knowledge-transfer-checklist.md`:
+
+### Session Planning
+
+Based on the project complexity, recommend session structure:
+
+```markdown
+### Recommended Knowledge Transfer Sessions
+
+| # | Session | Duration | Audience | Content |
+|---|---------|----------|----------|---------|
+| 1 | Architecture Overview | 1.5 hours | All engineers | System architecture, key decisions (ADRs), module boundaries |
+| 2 | Codebase Deep-Dive | 2 hours | Backend engineers | Services, adapters, data layer, testing |
+| 3 | Frontend Walkthrough | 1.5 hours | Frontend engineers | Components, state management, routing |
+| 4 | Operations & Deployment | 1 hour | DevOps / on-call | CI/CD, monitoring, runbook walkthrough |
+| 5 | Security & Auth | 45 min | All engineers | Auth flow, RBAC, tenant isolation, data handling |
+```
+
+### Key Files to Review
+
+Identify and list the most important files for understanding the system:
+
+```markdown
+### Critical Files (read these first)
+| File | Why It Matters |
+|------|---------------|
+| [actual file path] | [Main entry point / Core business logic / etc.] |
+```
+
+### Architecture Decisions
+
+Link to any ADRs in `docs/adr/`:
+
+```markdown
+### Architecture Decision Records
+| ADR | Title | Status |
+|-----|-------|--------|
+| [number] | [title] | Accepted/Proposed |
+```
+
+---
+
+## Phase 5: Support Escalation
+
+Generate using `templates/delivery/handover/support-escalation-matrix.md`:
+
+Customise severity levels and response times based on the client's requirements:
+
+```markdown
+### Support Tiers
+
+| Tier | Handles | Response | Resolution |
+|------|---------|----------|------------|
+| L1 — Client Team | FAQ, config, password resets | Same day | Same day |
+| L2 — Dev Team | Bugs, performance, data issues | 4 hours | 2 business days |
+| L3 — Architecture | Design issues, infrastructure, security | 1 hour (P1) | Case-by-case |
+| Emergency | Security breach, data loss, total outage | 15 minutes | ASAP |
+```
+
+---
+
+## Phase 6: Handover Checklist
+
+Present the final checklist and confirm with the user:
+
+```markdown
+## Handover Readiness
+
+### Documentation
+- [ ] Technical overview document generated
+- [ ] Operational runbook generated (with actual endpoints, services, config)
+- [ ] API reference generated
+- [ ] Architecture decisions documented (ADRs)
+
+### Knowledge Transfer
+- [ ] Sessions scheduled with receiving team
+- [ ] Key files identified and annotated
+- [ ] Demo environment prepared for walkthrough
+- [ ] Q&A sessions planned
+
+### Access Transfer
+- [ ] Repository access granted
+- [ ] CI/CD pipeline access granted
+- [ ] Cloud console access granted
+- [ ] Monitoring dashboard access granted
+- [ ] Secret management access granted
+- [ ] Third-party service credentials handed over
+
+### Operational Readiness
+- [ ] On-call rotation established
+- [ ] Escalation procedures documented and agreed
+- [ ] SLA terms agreed
+- [ ] Incident response playbook delivered
+- [ ] First week support plan in place
+
+### Sign-off
+- [ ] Client technical lead confirms documentation received
+- [ ] Client confirms access to all systems
+- [ ] Client confirms support procedures understood
+- [ ] Warranty/support period agreed
+```
+
+---
+
+## Error Handling
+
+- If no routes/endpoints are found, note this in the API section and explain it's a library/CLI/non-API project
+- If no database schema is found, skip the data model section
+- If no Docker/CI config exists, note it as a gap in the operational readiness section and recommend adding it
+- If existing documentation is sparse, generate what's needed and flag documentation debt to the client