@garethdaine/agentops 0.9.0

package/templates/utilities/project-detection.md

@@ -0,0 +1,75 @@
+# Project Detection Utility
+
+When this utility is invoked, analyse the current project to detect the technology stack in use. Follow these steps exactly:
+
+## Detection Steps
+
+1. **Package Manager & Runtime**
+   - Check for `package.json` → Node.js project
+   - Check for `requirements.txt` / `pyproject.toml` / `setup.py` → Python project
+   - Check for `go.mod` → Go project
+   - Check for `Cargo.toml` → Rust project
+   - Check for `Gemfile` → Ruby project
+   - Check for `pom.xml` / `build.gradle` → Java/Kotlin project
+   - Check for `*.csproj` / `*.sln` → .NET project
+
+2. **Frontend Framework** (if Node.js)
+   - Read `package.json` dependencies for: next, remix, astro, nuxt, vite, create-react-app, angular, svelte, vue
+   - Check for `next.config.*`, `remix.config.*`, `astro.config.*`, `vite.config.*`, `angular.json`
+
+3. **Backend Framework** (if Node.js)
+   - Read `package.json` for: express, fastify, hono, nestjs, koa, @hapi/hapi
+   - Check for `nest-cli.json`
+
+4. **Database & ORM**
+   - Check for `prisma/schema.prisma` → Prisma
+   - Check for `drizzle.config.*` → Drizzle
+   - Read `package.json` for: typeorm, sequelize, knex, mongoose, pg, mysql2, better-sqlite3
+   - Check for `docker-compose.yml` and look for database services (postgres, mysql, redis, mongo)
+
+5. **Authentication**
+   - Read `package.json` for: next-auth, passport, jsonwebtoken, jose, @auth/core, clerk, supabase
+   - Check for auth-related directories: `src/auth/`, `lib/auth/`, `app/api/auth/`
+
+6. **Cloud & Infrastructure**
+   - Check for `serverless.yml` / `serverless.ts` → Serverless Framework
+   - Check for `terraform/` or `*.tf` → Terraform
+   - Check for `cdk.json` → AWS CDK
+   - Check for `Dockerfile`, `docker-compose.yml`
+   - Check for `.github/workflows/` → GitHub Actions CI/CD
+   - Check for `vercel.json`, `netlify.toml`, `fly.toml`
+
+7. **Testing**
+   - Read `package.json` for: jest, vitest, mocha, cypress, playwright, @testing-library/*
+   - Check for `jest.config.*`, `vitest.config.*`, `playwright.config.*`, `cypress.config.*`
+
+8. **Code Quality**
+   - Check for `.eslintrc*`, `eslint.config.*`, `.prettierrc*`, `biome.json`
+   - Check for `tsconfig.json` → TypeScript
+   - Check for `.editorconfig`
+
+## Output Format
+
+Present findings as a structured summary:
+
+```
+## Detected Stack
+
+| Layer | Technology | Confidence |
+|-------|-----------|------------|
+| Runtime | Node.js 20 | High |
+| Frontend | Next.js 14 (App Router) | High |
+| Backend | Next.js API Routes | High |
+| Database | PostgreSQL (via Prisma) | High |
+| Auth | NextAuth.js v5 | Medium |
+| Cloud | Vercel | High |
+| CI/CD | GitHub Actions | High |
+| Testing | Vitest + Playwright | High |
+| Language | TypeScript (strict) | High |
+
+### Key Observations
+- [Notable patterns, conventions, or architecture decisions detected]
+- [Any gaps or areas where the stack is unclear]
+```
+
+If no project is detected (empty directory), report: "No existing project detected. This is a greenfield project."

package/templates/utilities/requirements-collection.md

@@ -0,0 +1,68 @@
+# Requirements Collection Utility
+
+When this utility is invoked, use structured prompting to gather requirements from the user. Follow the framework below to ensure complete, unambiguous requirements.
+
+## Collection Framework
+
+### Step 1: Context Setting
+Before asking questions, summarise what you already know:
+- What the user has stated so far
+- What you've detected from the project (via project-detection utility)
+- What assumptions you're making
+
+### Step 2: Structured Questions
+Present questions in grouped sections. Use numbered multi-choice where possible to reduce friction.
+
+**Format for multi-choice questions:**
+```
+**[Category]: [Question]**
+1. Option A — brief description
+2. Option B — brief description
+3. Option C — brief description
+4. Other — specify
+
+Your choice:
+```
+
+**Format for open-ended questions:**
+```
+**[Category]: [Question]**
+Context: [Why this matters for the decision]
+Default: [Suggested default if the user doesn't have a preference]
+```
+
+### Step 3: Decision Tree Logic
+After each answer, determine if follow-up questions are needed:
+- If user picks a frontend framework → ask about routing strategy, state management
+- If user picks a database → ask about ORM preference, migration strategy
+- If user picks auth → ask about provider, session strategy, role model
+- If user picks cloud → ask about deployment model, scaling requirements
+
+### Step 4: Confirmation
+Before proceeding, present a complete summary of all collected requirements and ask for confirmation:
+
+```
+## Requirements Summary
+
+| Decision | Choice | Notes |
+|----------|--------|-------|
+| Project type | Full-stack web app | — |
+| Frontend | Next.js 14 | App Router |
+| Backend | Next.js API Routes + tRPC | Type-safe API |
+| Database | PostgreSQL | Managed (Supabase) |
+| ORM | Prisma | With migrations |
+| Auth | NextAuth.js v5 | Google + GitHub OAuth |
+| Cloud | Vercel | Edge runtime where possible |
+| Monorepo | No | Single package |
+
+Does this look correct? (yes / make changes)
+```
+
+## Guidelines
+
+- Never assume a technology choice — always ask
+- Offer sensible defaults based on detected stack and common patterns
+- Keep questions concise — respect the user's time
+- Group related decisions together (don't ask about database migrations before confirming database choice)
+- If the user says "you decide" or "whatever you recommend", state your recommendation with reasoning and ask for confirmation
+- Maximum 3 rounds of questions before presenting the summary

package/templates/utilities/template-rendering.md

@@ -0,0 +1,81 @@
+# Template Rendering Utility
+
+When generating files from templates, follow these variable substitution and conditional rendering rules.
+
+## Variable Substitution
+
+Templates use `{{variable_name}}` syntax for placeholder values. When rendering a template:
+
+1. Collect all required variables from the context (project detection, requirements collection, or user input)
+2. Replace every `{{variable_name}}` with the actual value
+3. Flag any unreplaced variables as errors — never leave `{{...}}` in generated output
+
+### Standard Variables
+
+| Variable | Source | Example |
+|----------|--------|---------|
+| `{{project_name}}` | User input or directory name | `acme-portal` |
+| `{{project_description}}` | User input | `Customer portal for Acme Corp` |
+| `{{framework}}` | Requirements collection | `nextjs` |
+| `{{framework_version}}` | Requirements or latest stable | `14` |
+| `{{database}}` | Requirements collection | `postgresql` |
+| `{{orm}}` | Requirements collection | `prisma` |
+| `{{auth_strategy}}` | Requirements collection | `nextauth` |
+| `{{cloud_provider}}` | Requirements collection | `vercel` |
+| `{{node_version}}` | Detected or default | `20` |
+| `{{package_manager}}` | Detected or default | `pnpm` |
+| `{{author_name}}` | Git config or user input | `Gareth Daine` |
+| `{{year}}` | Current year | `2026` |
+| `{{date}}` | Current date | `2026-03-17` |
+
+## Conditional Sections
+
+Templates use conditional blocks for stack-dependent content:
+
+```
+{{#if database}}
+## Database Setup
+... database-specific content ...
+{{/if}}
+
+{{#if auth_strategy}}
+## Authentication
+... auth-specific content ...
+{{/if}}
+
+{{#unless monorepo}}
+## Single Package Setup
+... single-package content ...
+{{/unless}}
+
+{{#eq framework "nextjs"}}
+## Next.js Configuration
+... Next.js-specific content ...
+{{/eq}}
+```
+
+### Rendering Rules
+
+1. `{{#if variable}}...{{/if}}` — Include block only if variable is truthy (non-empty, not "none", not "false")
+2. `{{#unless variable}}...{{/unless}}` — Include block only if variable is falsy
+3. `{{#eq variable "value"}}...{{/eq}}` — Include block only if variable equals the specified value
+4. `{{#neq variable "value"}}...{{/neq}}` — Include block only if variable does not equal value
+
+## Rendering Process
+
+1. **Resolve variables** — Build a complete variable map from all available sources
+2. **Process conditionals** — Evaluate all conditional blocks, removing blocks whose conditions are false
+3. **Substitute variables** — Replace all `{{variable}}` placeholders with values
+4. **Validate output** — Check for any remaining `{{...}}` markers; if found, report missing variables
+5. **Format output** — Ensure proper indentation and whitespace in the final rendered content
+
+## Usage in Commands
+
+Enterprise commands reference this utility by including rendered templates in their output. The rendering happens inline — Claude reads the template, collects the variables, and produces the final output in a single pass. There is no separate rendering engine; Claude IS the rendering engine.
+
+Example flow in a command:
+1. Run project detection (templates/utilities/project-detection.md)
+2. Run requirements collection (templates/utilities/requirements-collection.md)
+3. Read the relevant template file
+4. Apply variable substitution and conditional rendering per this spec
+5. Write the rendered output to the target location

package/templates/workflows/architecture-decision.md

@@ -0,0 +1,90 @@
+# Workflow Template: Architecture Decision
+
+## Context Gathering
+
+1. **Problem statement**
+   - What architectural question needs answering?
+   - What triggered this decision? (new feature, scaling issue, tech debt)
+   - What is the current architecture in the affected area?
+
+2. **Constraints**
+   - Timeline constraints
+   - Team skill constraints
+   - Budget/infrastructure constraints
+   - Compatibility requirements
+   - Compliance/regulatory requirements
+
+3. **Quality attributes**
+   - Which matter most? (performance, scalability, maintainability, security, developer experience)
+   - What are the measurable targets?
+
+## Analysis Steps
+
+### Step 1: Context Documentation
+- Document the current state
+- Identify the forces driving this decision
+- List all constraints and requirements
+
+### Step 2: Options Generation
+Generate minimum 3 distinct options:
+- **Option A:** The conservative approach (low risk, incremental)
+- **Option B:** The balanced approach (moderate risk, good ROI)
+- **Option C:** The ambitious approach (higher risk, higher reward)
+- Additional options as relevant
+
+### Step 3: Trade-off Analysis
+For each option, evaluate against:
+- Feasibility (1-5)
+- Risk (1-5)
+- Time to implement (1-5)
+- Long-term quality (1-5)
+- Team alignment (1-5)
+
+### Step 4: Recommendation
+- Select the recommended option with rationale
+- Address each major trade-off
+- Define implementation implications
+- Identify risks and mitigations
+
+## Output Format (ADR)
+
+```
+# ADR-[number]: [Title]
+
+## Status
+Proposed | Accepted | Deprecated | Superseded
+
+## Context
+[What is the issue motivating this decision?]
+
+## Decision
+[What is the change that we're proposing?]
+
+## Consequences
+
+### Positive
+- [benefit]
+
+### Negative
+- [drawback]
+
+### Neutral
+- [observation]
+
+## Alternatives Considered
+
+### [Alternative 1]
+- Rejected because: [reason]
+
+### [Alternative 2]
+- Rejected because: [reason]
+```
+
+## Quality Checks
+
+- [ ] Problem statement is clear and specific
+- [ ] At least 3 options were considered
+- [ ] Trade-offs are honestly assessed (no straw-man alternatives)
+- [ ] Recommendation has clear rationale
+- [ ] Consequences (positive AND negative) are documented
+- [ ] Implementation path is actionable

package/templates/workflows/bug-investigation.md

@@ -0,0 +1,83 @@
+# Workflow Template: Bug Investigation
+
+## Context Gathering
+
+1. **Symptom capture**
+   - What is the observed behaviour?
+   - What is the expected behaviour?
+   - When did this start happening?
+   - Is it reproducible? How often?
+   - What environment (dev/staging/prod)?
+
+2. **Reproduction steps**
+   - Exact steps to reproduce
+   - Required preconditions
+   - Input data that triggers the bug
+   - Error messages or logs
+
+3. **Impact assessment**
+   - How many users are affected?
+   - Is there a workaround?
+   - What is the business impact?
+   - Priority: Critical / High / Medium / Low
+
+## Analysis Steps
+
+### Step 1: Reproduce
+- Follow the reproduction steps exactly
+- Capture logs, errors, and stack traces
+- Identify the exact point of failure
+- Note any environmental factors
+
+### Step 2: Isolate
+- Narrow down to the specific file/function
+- Check recent changes (git log, git blame)
+- Identify if this is a regression or a latent bug
+- Determine the root cause (not just the symptom)
+
+### Step 3: Root Cause Analysis
+- What is the actual cause of the bug?
+- Why wasn't this caught earlier?
+- Are there similar patterns elsewhere that might have the same issue?
+- Is this a code bug, a data bug, or a configuration bug?
+
+### Step 4: Fix Proposal
+- Describe the fix approach
+- Assess risk of the fix (could it break other things?)
+- Identify what tests need to be added
+- Consider if a broader refactor is needed
+
+### Step 5: Implementation
+- Apply the fix
+- Add regression test that proves the fix works
+- Verify the fix doesn't break existing tests
+- Check for similar issues in related code
+
+## Output Format
+
+```
+## Bug Report
+
+### Symptom
+[What was observed]
+
+### Root Cause
+[What actually caused it]
+
+### Fix Applied
+[What was changed and why]
+
+### Regression Test
+[Test added to prevent recurrence]
+
+### Related Risks
+[Anything else that might be affected]
+```
+
+## Quality Checks
+
+- [ ] Root cause identified (not just symptom patched)
+- [ ] Regression test added
+- [ ] Existing tests still pass
+- [ ] Fix handles edge cases
+- [ ] No performance regression introduced

package/templates/workflows/feature-implementation.md

@@ -0,0 +1,80 @@
+# Workflow Template: Feature Implementation
+
+## Context Gathering
+
+Before starting implementation, collect and verify:
+
+1. **Existing codebase state**
+   - What framework/stack is in use? (run project detection)
+   - What patterns does the existing code follow?
+   - What testing framework is configured?
+   - What are the naming conventions?
+
+2. **Feature requirements**
+   - What exactly should this feature do?
+   - Who is the end user?
+   - What are the acceptance criteria?
+   - Are there performance requirements?
+   - Are there security considerations?
+
+3. **Integration context**
+   - What existing code will this feature interact with?
+   - Are there external APIs or services involved?
+   - What database tables/models are affected?
+   - Are there UI components to create or modify?
+
+## Analysis Steps
+
+### Step 1: Codebase Analysis
+- Identify all files relevant to this feature
+- Map the data flow for the feature
+- Identify shared utilities and patterns to reuse
+- Flag any technical debt that might affect implementation
+
+### Step 2: Architecture Proposal
+- Define the component boundaries
+- Choose appropriate patterns (repository, service, controller, etc.)
+- Plan the data model changes (if any)
+- Define the API contract (if applicable)
+
+### Step 3: Implementation Plan
+- Break down into ordered tasks with dependencies
+- Estimate complexity per task (S/M/L)
+- Identify risk points (security, performance, integration)
+- Define test strategy per component
+
+### Step 4: Implementation
+For each task in order:
+1. Announce the task before starting
+2. Write the implementation code
+3. Write the corresponding tests
+4. Verify the code compiles/passes linting
+5. Confirm integration with existing code
+
+### Step 5: Verification
+- Run all tests (new and existing)
+- Check for TypeScript errors
+- Verify lint compliance
+- Manual smoke test if applicable
+
+## Output Format
+
+### Implementation Summary
+```
+Feature: [name]
+Tasks completed: [N/N]
+Files created: [list]
+Files modified: [list]
+Tests added: [count]
+Test status: All passing / [failures]
+```
+
+## Quality Checks
+
+- [ ] All new functions have JSDoc/TSDoc comments
+- [ ] Error cases are handled (not just happy path)
+- [ ] Input validation at system boundaries
+- [ ] No hardcoded values (use env/config)
+- [ ] No console.log left in production code (use logger)
+- [ ] Tests cover both success and failure paths
+- [ ] Existing tests still pass

package/templates/workflows/refactoring.md

@@ -0,0 +1,83 @@
+# Workflow Template: Safe Refactoring
+
+## Context Gathering
+
+1. **Current state**
+   - What code needs refactoring?
+   - What is wrong with the current implementation?
+   - What patterns is it using vs what patterns should it use?
+
+2. **Target state**
+   - What should the code look like after refactoring?
+   - What patterns should be applied?
+   - What quality attributes should improve? (readability, performance, maintainability)
+
+3. **Constraints**
+   - What can't change? (public APIs, database schema, external contracts)
+   - What is the risk tolerance?
+   - Is there test coverage for the affected code?
+
+## Analysis Steps
+
+### Step 1: Assess Current State
+- Read all code to be refactored
+- Map dependencies (what depends on this code?)
+- Check test coverage (are there tests for this?)
+- Identify the public interface (what must not change?)
+
+### Step 2: Define Target State
+- Describe the desired end state
+- Identify which patterns to apply
+- Define what "done" looks like
+- Estimate the size of change
+
+### Step 3: Plan Incremental Steps
+Break the refactor into small, safe increments. Each increment must:
+- Be independently deployable
+- Not break existing tests
+- Have a clear rollback path
+
+### Step 4: Execute Incrementally
+For each step:
+1. Make the change
+2. Run tests — they must pass
+3. Verify no regressions
+4. Commit (if appropriate)
+
+### Step 5: Verify
+- All existing tests pass
+- New tests added for new patterns
+- Public API unchanged (or migration documented)
+- Performance not degraded
+
+## Output Format
+
+```
+## Refactoring Summary
+
+### Before
+[Description of the original state]
+
+### After
+[Description of the refactored state]
+
+### Changes Made
+| Step | Change | Tests |
+|------|--------|-------|
+| 1 | [change] | Passing |
+| 2 | [change] | Passing |
+
+### Quality Improvement
+- Readability: [improved/unchanged]
+- Maintainability: [improved/unchanged]
+- Performance: [improved/unchanged]
+- Test coverage: [from X% to Y%]
+```
+
+## Quality Checks
+
+- [ ] All existing tests pass after each step
+- [ ] No public API changes (or documented)
+- [ ] Code is simpler/clearer than before
+- [ ] No new dependencies introduced unnecessarily
+- [ ] Performance is equal or better

package/templates/workflows/spike-exploration.md

@@ -0,0 +1,82 @@
+# Workflow Template: Spike / Time-boxed Exploration
+
+## Context Gathering
+
+1. **Hypothesis**
+   - What are we trying to learn or prove?
+   - What question will this spike answer?
+   - What does success look like?
+
+2. **Time box**
+   - Maximum time allocated for this spike
+   - What happens if we don't find an answer in time?
+
+3. **Scope boundaries**
+   - What is in scope for exploration?
+   - What is explicitly out of scope?
+   - What deliverables are expected at the end?
+
+## Analysis Steps
+
+### Step 1: Define the Hypothesis
+State clearly:
+- "We believe [approach] will [outcome]"
+- "We will know this is true when [measurable result]"
+- "Time box: [duration]"
+
+### Step 2: Plan the Exploration
+- List specific things to try/investigate
+- Order by likelihood of providing answers
+- Identify dependencies or prerequisites
+- Set checkpoint times
+
+### Step 3: Execute
+- Try each approach in order
+- Document findings as you go (don't rely on memory)
+- If an approach fails, note WHY and move on
+- Stop when the time box expires, even if incomplete
+
+### Step 4: Capture Findings
+Document everything learned, including dead ends.
+
+## Output Format
+
+```
+## Spike Report
+
+### Hypothesis
+[What we set out to learn]
+
+### Time Box
+[Duration] | Started: [time] | Ended: [time]
+
+### Findings
+
+#### Approach 1: [Name]
+- **Result:** Success / Partial / Failed
+- **Evidence:** [What we observed]
+- **Notes:** [Key learnings]
+
+#### Approach 2: [Name]
+- **Result:** Success / Partial / Failed
+- **Evidence:** [What we observed]
+- **Notes:** [Key learnings]
+
+### Recommendation
+[Based on findings, what should we do next?]
+
+### Open Questions
+- [What we still don't know]
+
+### Artefacts
+- [Links to prototype code, diagrams, or docs produced]
+```
+
+## Quality Checks
+
+- [ ] Hypothesis was clearly stated before starting
+- [ ] Time box was respected
+- [ ] All approaches tried were documented (including failures)
+- [ ] Findings are specific and evidence-based
+- [ ] Recommendation is actionable
+- [ ] Open questions are captured for follow-up