@garethdaine/agentops 0.9.0

package/templates/architecture/service-boundaries.md

@@ -0,0 +1,200 @@
+# Architecture Pattern: Service Boundaries
+
+## When to Use
+
+- Codebase has grown beyond a single team's cognitive capacity
+- Multiple teams need to ship independently without merge conflicts
+- You need clear dependency rules to prevent spaghetti imports
+- Deciding between a monolith with strong module boundaries and microservices
+
+## Pattern Description
+
+Service boundaries define how a system is decomposed into modules or services, what each module owns, and the rules governing communication between them. Done well, boundaries enable independent development, testing, and deployment. Done poorly, they create distributed monoliths or circular dependency nightmares.
+
+## Bounded Contexts (DDD)
+
+Each bounded context owns a slice of the domain with its own ubiquitous language. The same real-world concept may have different representations in different contexts.
+
+```typescript
+// --- Billing context: a "User" is a billing account
+// src/billing/types.ts
+export interface BillingAccount {
+  accountId: string;
+  plan: 'free' | 'pro' | 'enterprise';
+  paymentMethodId: string | null;
+  invoiceEmail: string;
+}
+
+// --- Identity context: a "User" is an authentication principal
+// src/identity/types.ts
+export interface UserIdentity {
+  userId: string;
+  email: string;
+  roles: string[];
+  mfaEnabled: boolean;
+  lastLoginAt: Date;
+}
+
+// These are NOT the same type. Each context defines
+// only the fields it needs, using its own language.
+```
+
+## Module Structure: Package by Feature
+
+Organise code around business capabilities, not technical layers:
+
+```
+src/
+  projects/
+    projects.controller.ts    # HTTP layer
+    projects.service.ts       # Business logic
+    projects.repository.ts    # Data access
+    projects.types.ts         # Types scoped to this module
+    projects.test.ts          # Tests for this module
+    index.ts                  # Barrel export (public API)
+  billing/
+    billing.controller.ts
+    billing.service.ts
+    billing.repository.ts
+    billing.types.ts
+    billing.test.ts
+    index.ts
+  shared/
+    errors.ts
+    logger.ts
+    middleware/
+```
+
+**Contrast with package-by-layer (avoid):**
+
+```
+src/
+  controllers/     # Mixes all domains together
+    projects.ts
+    billing.ts
+  services/
+    projects.ts
+    billing.ts
+  repositories/
+    projects.ts
+    billing.ts
+```
+
+Package-by-layer scatters related code across directories and makes it impossible to reason about a single feature in isolation.
+
+## Public API Surface (Barrel Exports)
+
+Each module exposes a deliberate public API through its `index.ts`. Internal implementation details stay private.
+
+```typescript
+// src/projects/index.ts — the public API of the projects module
+export { ProjectService } from './projects.service';
+export type { Project, CreateProjectInput } from './projects.types';
+
+// NOT exported: repository, internal helpers, database schemas
+// Other modules may only import from this barrel file
+```
+
+## Dependency Rules
+
+Define and enforce what can import what:
+
+```typescript
+/**
+ * Dependency rules (enforce via eslint-plugin-import or eslint-plugin-boundaries):
+ *
+ * 1. Modules may import from `shared/` — shared utilities have no domain logic
+ * 2. Modules must NOT import directly from another module's internals
+ *    WRONG: import { projectRepo } from '../projects/projects.repository'
+ *    RIGHT: import { ProjectService } from '../projects'
+ * 3. Circular dependencies between modules are forbidden
+ * 4. If module A needs data from module B, it calls B's public service API
+ * 5. shared/ must NOT import from any domain module
+ */
+
+// ESLint boundaries configuration example
+// .eslintrc.js
+const boundaryRules = {
+  'boundaries/element-types': [
+    'error',
+    {
+      default: 'disallow',
+      rules: [
+        { from: 'projects', allow: ['shared'] },
+        { from: 'billing', allow: ['shared'] },
+        { from: 'shared', allow: ['shared'] },
+        // projects and billing cannot import from each other
+      ],
+    },
+  ],
+};
+```
+
+## Cross-Module Communication
+
+When modules need to collaborate, use explicit integration points:
+
+```typescript
+// Option 1: Direct service call (simpler, synchronous)
+// src/billing/billing.service.ts
+import { ProjectService } from '../projects';
+
+export class BillingService {
+  constructor(private projectService: ProjectService) {}
+
+  async calculateUsage(accountId: string): Promise<UsageReport> {
+    const projects = await this.projectService.listByAccount(accountId);
+    return this.computeUsage(projects);
+  }
+}
+
+// Option 2: Domain events (decoupled, asynchronous)
+// src/projects/projects.service.ts
+export class ProjectService {
+  constructor(private eventBus: EventBus) {}
+
+  async deleteProject(projectId: string): Promise<void> {
+    await this.repository.delete(projectId);
+    await this.eventBus.publish({
+      type: 'project.deleted',
+      data: { projectId },
+    });
+    // Billing module listens and cleans up independently
+  }
+}
+```
+
+## When to Split vs Keep Together
+
+```typescript
+/**
+ * SPLIT into separate modules when:
+ * - Different teams own different parts
+ * - Different deployment cadences are needed
+ * - Data ownership is clearly separable
+ * - The bounded contexts have distinct ubiquitous languages
+ *
+ * KEEP TOGETHER when:
+ * - Changes to A almost always require changes to B
+ * - They share the same database tables
+ * - Splitting would require distributed transactions
+ * - The team is small enough to own the whole thing
+ * - You are unsure — premature splitting is harder to undo than late splitting
+ */
+```
+
+## Trade-offs
+
+- **Upfront design cost:** Defining boundaries requires deep domain understanding early on.
+- **Cross-cutting changes:** Features that span boundaries require coordination across modules.
+- **Indirection overhead:** Service calls between modules add complexity versus direct function calls.
+- **Duplication is sometimes correct:** Each context should own its types even if they look similar. Sharing types across boundaries creates coupling.
+
+## Common Pitfalls
+
+1. **Shared database tables across modules** — If two modules read/write the same table, they are not truly separated. One module should own the table and expose an API.
+2. **God modules** — A `shared/` or `common/` directory that grows unbounded. Keep shared code limited to genuinely cross-cutting concerns (logging, errors, HTTP utilities).
+3. **Barrel export everything** — Only export what other modules actually need. Internal helpers should remain private.
+4. **Splitting too early** — Extracting a microservice before you understand the domain leads to wrong boundaries that are expensive to move.
+5. **Circular dependencies** — If module A imports from B and B imports from A, extract the shared concept into a third module or use events to break the cycle.
+6. **Ignoring runtime coupling** — Two services that must be deployed together and fail together are a distributed monolith, not microservices.

package/templates/build/brief-template.md

@@ -0,0 +1,86 @@
+# Build Brief: {Project Name}
+
+**Slug:** {project-slug}
+**Created:** {ISO date}
+**Status:** Draft / Approved
+
+---
+
+## Vision
+
+> {One paragraph verbatim from the user describing what they want to build}
+
+---
+
+## Core Problem
+
+What specific problem does this solve, and for whom?
+
+- **Problem:** {Describe the pain point in concrete terms}
+- **Who experiences it:** {Target user / persona}
+- **Current solution / workaround:** {How this is solved today, if at all}
+- **Why that's insufficient:** {What's wrong with the current approach}
+
+---
+
+## Proposed Direction
+
+**Chosen framing:** {A — Minimal Core / B — Balanced / C — Ambitious Platform / Custom}
+
+### Description
+
+{2-3 paragraphs describing what will be built, in the chosen framing}
+
+### What this is
+
+- {Concrete capability 1}
+- {Concrete capability 2}
+- {Concrete capability 3}
+
+### What this is NOT (explicit exclusions)
+
+- {Explicitly out of scope item 1}
+- {Explicitly out of scope item 2}
+
+---
+
+## Key Trade-offs
+
+| Decision | Option A | Option B | Chosen | Rationale |
+|----------|----------|----------|--------|-----------|
+| {e.g. Architecture} | Monolith | Microservices | Monolith | Team size, delivery speed |
+| {e.g. Auth} | Custom auth | Auth provider | Auth provider | Security, speed |
+
+---
+
+## Constraints
+
+| Constraint | Description | Source |
+|-----------|-------------|--------|
+| Timeline | {Deadline or time budget if known} | User |
+| Team | {Solo / pair / team size} | User |
+| Existing stack | {Languages / frameworks already committed} | Codebase |
+| Compliance | {Any regulatory requirements: GDPR, HIPAA, SOC2, etc.} | User |
+| Budget | {Infrastructure / tooling constraints if known} | User |
+
+---
+
+## Open Questions
+
+Questions that must be answered before or during planning. These will drive the interrogation phase.
+
+- [ ] {Open question 1}
+- [ ] {Open question 2}
+- [ ] {Open question 3}
+
+---
+
+## Approval
+
+- [ ] Brief approved by user
+- **Approved direction:** {Framing chosen}
+- **Approval date:** {date}
+
+---
+
+*Generated by `/agentops:build` Phase 1 — BRAINSTORM*

package/templates/build/summary-template.md

@@ -0,0 +1,100 @@
+# Build Summary: {Project Name}
+
+**Slug:** {project-slug}
+**Build duration:** {start date} → {end date} ({N hours/days})
+**PR:** {PR URL or "No PR created"}
+**Status:** Complete
+
+---
+
+## Metrics
+
+| Metric | Value |
+|--------|-------|
+| Total duration | {e.g. 4h 32m} |
+| Phases completed | {N} / 8 |
+| Tasks completed | {N} |
+| Tasks fixed (fix wave) | {N} |
+| Waves | {N} ({wave names}) |
+| Commits | {N} |
+| Tests added | {N} |
+| Test pass rate | {N}% |
+| Critical findings fixed | {N} |
+| High findings fixed | {N} |
+| Lessons captured | {N} |
+| Estimated tokens used | ~{N}K |
+
+---
+
+## What Was Built
+
+{2-4 paragraphs in plain language describing what was built. Written for a non-technical stakeholder who needs to understand what they're getting. Avoid jargon. Describe the user-facing outcome.}
+
+---
+
+## Architecture Decisions
+
+The following key decisions were made during this build. Each decision is recorded with its rationale so future contributors understand why things are the way they are.
+
+### ADR-001: {Decision title}
+
+- **Context:** {Why this decision needed to be made}
+- **Decision:** {What was chosen}
+- **Rationale:** {Why this was the right choice for this project}
+- **Consequences:** {Trade-offs accepted; what this makes harder}
+
+### ADR-002: {Decision title}
+[Same format]
+
+---
+
+## Known Limitations
+
+These are medium-severity findings or deferred scope items from Phase 6 review. They are tracked and known — not surprises.
+
+| # | Limitation | Severity | Deferred to |
+|---|-----------|----------|-------------|
+| 1 | {Description} | Medium | {v2 / next sprint / backlog} |
+| 2 | {Description} | Medium | {when} |
+
+---
+
+## Lessons Learned
+
+These lessons were captured from failures and unexpected complexity during Phase 5 execution. They are written to prevent the same issues in future builds.
+
+### Lesson 1: {Title}
+
+- **What happened:** {Brief description of the failure or friction}
+- **Why it happened:** {Root cause}
+- **How it was resolved:** {What worked}
+- **Apply next time:** {Specific rule or change to apply in the next build}
+
+### Lesson 2: {Title}
+[Same format]
+
+---
+
+## Files Created / Modified
+
+| File | Action | Purpose |
+|------|--------|---------|
+| `{path/to/file}` | Created | {Purpose} |
+| `{path/to/file}` | Modified | {What changed} |
+
+**Total:** {N} files created, {N} files modified.
+
+---
+
+## Next Steps
+
+Recommended actions after this build:
+
+1. {e.g. Run load testing against the new API endpoints}
+2. {e.g. Set up monitoring and alerting for the new service}
+3. {e.g. Schedule v2 planning for deferred features: [list]}
+4. {e.g. Run /agentops:review after the first week of production use}
+
+---
+
+*Generated by `/agentops:build` Phase 8 — APPROVAL*

package/templates/build/task-plan-template.md

@@ -0,0 +1,133 @@
+# Task Plan: {Task ID} — {Task Title}
+
+**Wave:** {wave number}
+**Complexity:** {S / M / L}
+**Build:** {project-slug}
+
+---
+
+## Context
+
+### Files to read first
+
+Before writing a single line of code, read these files to understand what already exists:
+
+| File | Why |
+|------|-----|
+| {path/to/file} | {What to understand from it} |
+
+### Dependencies satisfied
+
+These tasks have already completed and their outputs are available:
+
+| Task ID | What it produced |
+|---------|-----------------|
+| {T001} | {e.g. UserRepository interface at src/users/user.repository.ts} |
+
+### Integration points
+
+This task connects to:
+- {Component or module this task integrates with}
+- {API contract or interface this task must respect}
+
+---
+
+## TDD Specification
+
+### RED Phase — Write the failing test first
+
+**Test file:** `{path/to/test-file}` *(use the project's test file naming convention — e.g., `.test.ts`, `_test.go`, `test_*.py`, `*_spec.rb`)*
+
+**Test to write:**
+
+```
+{Write the test using the project's testing framework and language.
+ Follow Arrange-Act-Assert structure.
+ Test description format: "should {expected behaviour} when {condition}".
+ Example patterns by language:
+
+ TypeScript/Jest:  describe('...', () => { it('should ...', () => { expect(...).toBe(...); }); });
+ Python/pytest:    def test_should_do_x_when_y(): ... assert result == expected
+ Go:              func TestShouldDoXWhenY(t *testing.T) { ... if got != want { t.Errorf(...) } }
+ Rust:            #[test] fn should_do_x_when_y() { assert_eq!(...); }
+}
+```
+
+**Expected failure message:** `{The exact error you expect to see when running this test before implementation — e.g., "ModuleNotFoundError", "undefined: FunctionName", "cannot find module"}`
+
+**Run command:** `{project's test runner — e.g., npm test, pytest, go test, cargo test} {with filter for this specific test}`
+
+**Confirm RED:** The test must fail with the expected error before any implementation begins. If it passes, the test is wrong.
+
+---
+
+### GREEN Phase — Minimal implementation
+
+**File(s) to create or modify:**
+
+| File | Action | Description |
+|------|--------|-------------|
+| `{path/to/file.ts}` | Create | {What this file contains} |
+
+**Implementation approach:**
+
+{2-3 sentences describing the minimal, correct implementation to make the test pass. No extra features. No premature abstraction. Just enough to go green.}
+
+**Key decisions:**
+- {Decision 1: e.g., "Use constructor injection for the repository dependency"}
+- {Decision 2: e.g., "Return null (not throw) when the entity is not found — let callers decide"}
+
+**After implementing:** Run the test. It must pass. If it doesn't, fix the implementation — do NOT modify the test to make it pass.
+
+---
+
+### REFACTOR Phase — Improve without changing behaviour
+
+After the test is green, apply these improvements. Re-run tests after each change to confirm they still pass.
+
+| Refactor | Rationale |
+|----------|-----------|
+| {e.g. Extract the validation logic into a private/internal function} | {SRP — keeps the main function at one abstraction level} |
+| {e.g. Add doc comment to the public function} | {Aids future contributors} |
+| {e.g. Replace magic number 3 with named constant MAX_RETRY_ATTEMPTS} | {Avoid magic numbers} |
+
+**Standards to verify during refactor (from standards-checklist.md):**
+- [ ] Function is ≤30 lines
+- [ ] No concrete dependency instantiation in business logic
+- [ ] Function is named as a verb phrase
+- [ ] Boolean parameters removed (if any crept in)
+- [ ] Command-query separation respected
+
+---
+
+## Verification
+
+**Command:** `{full command to run — e.g., npm test -- --grep "UserService" && npm run typecheck}`
+
+**Expected output:**
+```
+{The exact output expected — e.g., "Tests: 3 passed, 3 total"}
+```
+
+**Additional checks:**
+- [ ] `git diff` shows only the expected files changed
+- [ ] No TypeScript errors: `{typecheck command}`
+- [ ] {Any domain-specific check}
+
+---
+
+## Commit
+
+**Message:** `{type(scope): description — e.g., feat(users): implement user registration with email validation}`
+
+**Files to stage:** `{list of specific files to add — do NOT use git add -A}`
+
+**Commit command:**
+```
+git add {file1} {file2}
+git commit -m "{commit message}"
+```
+
+---
+
+*Generated by `/agentops:build` Phase 4 — TASK_BREAKDOWN*

package/templates/communication/effort-estimate.md

@@ -0,0 +1,54 @@
+# Communication Template: Effort Estimate
+
+```markdown
+# Effort Estimate: [Feature/Project Name]
+
+**Prepared by:** [name]
+**Date:** [date]
+**Confidence level:** High / Medium / Low
+
+## Feature Breakdown
+
+| # | Feature | Complexity | Effort (days) | Dependencies | Risk |
+|---|---------|-----------|--------------|-------------|------|
+| 1 | [feature] | S/M/L/XL | [days] | [deps] | [risk] |
+| 2 | [feature] | S/M/L/XL | [days] | [deps] | [risk] |
+
+## Complexity Guide
+
+| Size | Description | Typical Effort |
+|------|-------------|---------------|
+| S | Well-understood, similar to existing code | 0.5-1 day |
+| M | Some unknowns, moderate scope | 2-3 days |
+| L | Significant scope, multiple components | 5-8 days |
+| XL | High complexity, cross-cutting concerns | 10+ days |
+
+## Summary
+
+| Category | Effort |
+|----------|--------|
+| Development | [days] |
+| Testing | [days] |
+| Code review | [days] |
+| Documentation | [days] |
+| **Total** | **[days]** |
+
+## Assumptions
+
+1. [assumption that affects estimate]
+2. [assumption that affects estimate]
+
+## Caveats
+
+- Estimates assume [condition]
+- Not included: [out of scope items]
+- Confidence is [level] because [reason]
+
+## Range Estimate
+
+| Scenario | Effort | Conditions |
+|----------|--------|-----------|
+| Best case | [days] | No surprises, all assumptions hold |
+| Expected | [days] | Moderate unknowns |
+| Worst case | [days] | Major unknowns materialise |
+```

package/templates/communication/incident-response.md

@@ -0,0 +1,59 @@
+# Communication Template: Incident Response
+
+## Incident Report Template
+
+```markdown
+# Incident Report: [Title]
+
+**Severity:** P1 (Critical) / P2 (High) / P3 (Medium) / P4 (Low)
+**Status:** Investigating / Identified / Monitoring / Resolved
+**Start time:** [timestamp]
+**Resolution time:** [timestamp]
+**Duration:** [hours/minutes]
+**Affected systems:** [list]
+**Impact:** [user-facing description of impact]
+
+## Timeline
+
+| Time | Event |
+|------|-------|
+| [HH:MM] | [what happened] |
+| [HH:MM] | [action taken] |
+| [HH:MM] | [resolution] |
+
+## Root Cause
+
+[What caused the incident — be specific and honest]
+
+## Resolution
+
+[What was done to fix it]
+
+## Impact
+
+- **Users affected:** [count/percentage]
+- **Duration:** [time]
+- **Data impact:** [any data loss or corruption]
+- **Financial impact:** [if applicable]
+
+## Action Items
+
+| Action | Owner | Due Date | Status |
+|--------|-------|----------|--------|
+| [preventive action] | [name] | [date] | Open |
+
+## Lessons Learned
+
+1. [What went well]
+2. [What could be improved]
+3. [What we'll do differently]
+```
+
+## Post-Mortem Framework
+
+1. **What happened?** (factual timeline)
+2. **Why did it happen?** (5 Whys root cause analysis)
+3. **How was it detected?** (monitoring, user report, automated alert)
+4. **How was it resolved?** (steps taken)
+5. **How do we prevent recurrence?** (action items)
+6. **Blameless culture:** Focus on systems and processes, not individuals